Range Header Clarifications for Resumable Uploads and Partial Downloads

[amouat]

When doing a PATCH upload, the spec says the returned Range header should return 0-<offset>. So I assume if you were to do two PATCH uploads, both of 64 bytes, the first header would be 0-63 and the second would be 0-127 (or perhaps that's off by one?).

But the PUT request to complete an upload says it returns Content-Range not Range and that it should be <start of range>-<end of range, inclusive>. So if I upload another 20 bytes in the PUT, it should return 128-148?

Can I just confirm the following is correct:

• Range changes to Content-Range
• The final PUT returns a range starting at the last byte uploaded, unlike PATCH whose range is always from 0? (Perhaps a better way of phrasing this is Range headers always start from 0 and Content-Range from last-byte?).

At the moment, I assume the previous is correct and is to do with interoperability with other specs and tooling (e.g. the HTTP spec and s3 buckets)? This could be made a bit clearer with some examples and more tests in the conformance suite. Giving the reasons for a spec being a certain way also helps implementers, even though it may seem irrelevant.

Also, there is a section for partial downloads, which doesn't seem to be symmetrical. The client request is described as including the header Range: bytes=<start>-<end>, but the bytes= is dropped from other places in the spec. And the returned header has the form Content-Range: bytes <start>-<end>/<size> which is different again (no = and the addition of /<size>). Finally there is also a brief mention of Accept-Range as a way of testing support for partial downloads, I think this would benefit from being called out more.

My questions here are:

• Is bytes= and bytes a mistake?
• I think this is the only place the Accept-Range header is mentioned - should it also be added to a separate HEAD request detail?

[jdolitsky]

Related to https://github.com/opencontainers/distribution-spec/pull/203

@amouat - could you PR into spec some language that would make this clearer? From what I can tell, the bytes/bytes= prefix is actually not used in practice (on existing registries)

[amouat]

Yes, I can have a go. But I'm not 100% sure what the actual behaviour is around some of my questions. I'll take a look at the Docker client and Docker distribution code.