resumable: introduce new append-granularity limit

[danielresnick]

See discussion on #3193

[gstrauss]

@danielresnick There should be an exception for the size of the final chunk at the end of the file.

Requiring upload-complete be set for the final chunk would take away the ability of a robust client to send chunks, and then separately without any additional body content, to send Upload-Complete. The ability to send a separate message separates the uploading from marking the upload as complete.

The authors of resumable uploads have made many premature optimizations and I hope that they do not downplay or ignore the robustness of separation of concerns when evaluating this append-granularity feature.

---

Personally, I would prefer that the granularity be a hint, and not a hard error, especially since according to the resumable uploads draft, a server may accept part of an upload even if the upload gets disconnected. If there was a part of the granularity chunk committed and the offset is no longer a multiple of the granularity, then a client might wish to send a smaller chunk (smaller than the granularity) even in the middle of an upload in order to re-align with the granularity for further chunks.

[danielresnick]

Thanks for the feedback @gstrauss. Just to make sure I'm understanding, you're suggesting that the proposed carve out for final chunks ("Requests completing the upload by including the Upload-Complete: ?1 header field are exempt from this limit.") be generalised to not necessarily require Upload-Complete: ?1, but rather be applicable to any append request which would result in the reaching of the declared Upload-Length (if there is one), is that right? If so I'm open to this idea, though am interested in others' thoughts also. It's definitely more difficult to express concisely, but I can see how it might improve separation of concepts.

Re: hint vs hard error, as I mentioned on #3193 I'm open to expressing this as SHOULD rather than MUST, but I do think it's important to be clear that a client intending to be widely interoperable with a variety of servers needs to be aware/respectful of potential granularity requirements.

Re: "a server may accept part of an upload even if the upload gets disconnected", I think the onus should be on the server which is advertising an append-granularity to avoid committing partial state that isn't aligned with that granularity. In fact the whole motivation for append-granularity's existence is server-side limitations that make it technically difficult to commit on non-aligned boundaries. Or to put it another way: clients shouldn't need to worry about re-aligning granularity. Open to suggestions on how I might make this clearer in the PR! Thanks again for the detailed feedback!

[Acconut]

How should a client act when receiving this response? The document currently recommends client to stop the upload once they receive a 400.

[danielresnick]

Technically the spec says "4xx (Client Error) status code, the client SHOULD NOT attempt to retry or resume the upload, unless the semantics of the response allow or recommend the client to retry the request."

I agree that's quite subtle though -- expecting a client dev to read this, and then trawl through all possible response_code+problem_type combinations to decide on resume vs abort behaviour. Particularly because even parsing out the problem type requires doing some json parsing. I'll have a think about the best path forward here.. the most obvious options in my mind are (in no particular order):

1. Switch to a 5xx response code. As discussed on the corresponding issue this is likely to improve client interop, but is a hacky / less pure solution since this isn't actually a server error.

2. Use a different / more specific 4xx response code and improve the wording to call this code out specifically. The problem is I don't see a super obvious pre-existing code in the 4xx space. Maybe 422 Unprocessable Content, but that feels slightly odd vs the suggestion that a server should partially process the provided response.

3. Keep using 400 (Bad Request) and try to improving the wording in the client section to be clearer (e.g. with some combination of improving cross-referencing with problem-types, marking problem-types more explicitly as retryable vs not, rephrasing the 4xx status code handling piece quoted above to lead with a discussion on what's retryable vs not).

[Acconut]

I think 409 would be an option. If #3319 lands, clients should resume the upload when they get a 409, which I think it desired in that case.

3. Keep using 400 (Bad Request) and try to improving the wording in the client section to be clearer (e.g. with some combination of improving cross-referencing with problem-types, marking problem-types more explicitly as retryable vs not, rephrasing the 4xx status code handling piece quoted above to lead with a discussion on what's retryable vs not).

I wouldn't want to mandate clients to parse the response body. It would be great if we can keep using status codes as the definitive signal for clients.

[danielresnick]

Yeah that's a good point. I'd sort of dismissed that option as I was finding it hard to justify granularity mismatch as a state conflict (though I agree that if that PR lands it would solve the problem from a pure behaviour standpoint), but thinking some more I guess an argument could be made that partial acceptance of a chunk (e.g., accepting 256 KiB of a 300 KiB request) creates a direct mismatch between the client's perceived state and the server's actual state. And yes agreed leveraging status codes only is much more robust & likely to get adoption in practice

[Acconut]

Thank you for this proposal! We'll bring up the general topic of handling granularities during the IETF 124 httpbis meeting next Wednesday.

[danielresnick]

Noting before I forget: assuming I understood @gstrauss 's feedback correctly I think min-append-size also has this discrepancy as-is, so we should aim to be consistent for both. That is either only exempt requests with Upload-Complete:?1 from the limit, or exempt any request which contains the final bytes of the representation data as indicated by Upload-Length (in the current or a previous request).