Add support for HEAD endpoints; add example accepting Range: header

[jgallagher]

Several examples of running curl against the example with -i to show the headers the server returns are below.

Normal request; fetch all data:

$ curl -i http://127.0.0.1:41597/lorem-ipsum
HTTP/1.1 200 OK
accept-ranges: bytes
content-type: text/plain
content-length: 445
x-request-id: 31a1df27-3a35-42cf-8db2-6e69d02a4147
date: Wed, 06 Sep 2023 15:57:29 GMT

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Ask for just 20 bytes starting at offset 20:

$ curl -r 20-39 -i http://127.0.0.1:41597/lorem-ipsum
HTTP/1.1 206 Partial Content
accept-ranges: bytes
content-type: text/plain
content-length: 20
content-range: bytes 20-39/445
x-request-id: a9140c5d-3f6e-4437-92a8-4fa29ccc2059
date: Wed, 06 Sep 2023 15:57:50 GMT

t amet, consectetur

Ask for all bytes starting from offset 100 (this matches the way curl resumes downloads via -C -, which also works with this example but I'm not showing explicitly here):

$ curl -r 100- -i http://127.0.0.1:41597/lorem-ipsum
HTTP/1.1 206 Partial Content
accept-ranges: bytes
content-type: text/plain
content-length: 345
content-range: bytes 100-444/445
x-request-id: 5a6f6599-9d37-4db4-ab81-dee4bcdecaab
date: Wed, 06 Sep 2023 15:58:00 GMT

et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Ask for the last 100 bytes:

$ curl -r -100 -i http://127.0.0.1:41597/lorem-ipsum
HTTP/1.1 206 Partial Content
accept-ranges: bytes
content-type: text/plain
content-length: 100
content-range: bytes 345-444/445
x-request-id: aecb26b4-d375-441b-864b-194d0ae3718e
date: Wed, 06 Sep 2023 15:58:04 GMT

sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

---

We can repeat any of the above requests with -I to send an HTTP HEAD; we should get back identical headers but no body content; e.g., asking for all bytes starting from offset 100:

$ curl -I -r 100- http://127.0.0.1:41597/lorem-ipsum
HTTP/1.1 206 Partial Content
accept-ranges: bytes
content-type: text/plain
content-length: 345
content-range: bytes 100-444/445
x-request-id: bd5e6771-0320-48e0-987a-f0c91a2b712b
date: Wed, 06 Sep 2023 16:04:24 GMT

---

Asking for too many bytes (e.g., "the last 500 bytes") fails:

$ curl -r -500 -i http://127.0.0.1:41597/lorem-ipsum
HTTP/1.1 416 Range Not Satisfiable
accept-ranges: bytes
content-range: bytes */445
x-request-id: 912c5b82-69ea-4f06-b678-5e7f49c6ec8e
content-length: 70
date: Wed, 06 Sep 2023 16:01:36 GMT

RangeUnsatisfiable: File suffix out of bounds (larger than file bytes)

as does asking for multiple ranges (which is legal but I think very unusual?):

$ curl -r 0-19,40-99 -i http://127.0.0.1:41597/lorem-ipsum
HTTP/1.1 416 Range Not Satisfiable
accept-ranges: bytes
content-range: bytes */445
x-request-id: 7884a1b6-a437-4b47-b781-cd329c7c61bc
content-length: 35
date: Wed, 06 Sep 2023 16:02:55 GMT

server only supports a single range

---

Interestingly, asking for an explicit range that goes past the end of the file succeeds:

$ curl -i -r 0-500 http://127.0.0.1:41597/lorem-ipsum
HTTP/1.1 206 Partial Content
accept-ranges: bytes
content-type: text/plain
content-length: 445
content-range: bytes 0-444/445
x-request-id: c78cbd57-b0e6-448f-948b-d57fbde6269a
date: Wed, 06 Sep 2023 16:05:02 GMT

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

This is because http-range-header clamps the end position. I'm having a hard time finding anything in RFC 7233 to confirm that's the correct behavior, but I imagine it is?

[davepacheco]

Sorry this one fell off my radar. It looks like HEAD support came in with #755. We could still add the Range: example if that seems worthwhile. Up to you!