Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Tune HTTP examples #421

Merged
merged 1 commit into from Dec 13, 2017
Merged

Tune HTTP examples #421

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
121 changes: 69 additions & 52 deletions draft-ietf-httpbis-rand-access-live.xml
View file
Open in desktop
Expand Up @@ -19,7 +19,8 @@
<rfc
category="exp"
ipr="trust200902"
docName="draft-ietf-httpbis-rand-access-live-latest" >
docName="draft-ietf-httpbis-rand-access-live-latest"
xmlns:x='http://purl.org/net/xml2rfc/ext'>

<!-- Processing Instructions- PIs (for a complete list and description,
see file http://xml.resource.org/authoring/README.html and below... -->
Expand Down Expand Up @@ -238,16 +239,18 @@
representation length) may respond with a 206 status code (Partial Content) with a Content-Range
header indicating the currently satisfiable byte range. For example:
</t>
<figure><artwork type="example">
HEAD /resource HTTP/1.1
Range: bytes=0-
<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with=" ">
HEAD /resource HTTP/1.1
Host: example.com
Range: bytes=0-

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think the blank lines at the end of the examples are really necessary? (Presume the intent is to show the terminating \n\n?)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do it in the base specs as well...

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good enough reason for me. Consistency is good....

</artwork></figure>
<t>
returns a response of the form:
</t>
<figure><artwork type="example">
HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1234567/*
<figure><artwork type="message/http; msgtype=&#34;response&#34;" x:indent-with=" ">
HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1234567/*
</artwork></figure>
<t>
from the server indicating that (1) the complete representation length is unknown (via the "*" in place of the complete-length field) and (2) that only bytes 0-1234567 were accessable at the time the request was processed by the server. The client can infer from this response that bytes 0-1234567 of the representation can be requested and returned in a timely fashion (the bytes are immediately available).
Expand Down Expand Up @@ -279,9 +282,11 @@
<t>
A client can indicate support for handling indeterminate-length byte-range responses by providing a Very Large Value for the last-byte-pos in the byte-range request. For example, a client can perform a byte-range GET request of the form:
</t>
<figure><artwork type="example">
GET /resource HTTP/1.1
Range: bytes=1230000-999999999999
<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with=" ">
GET /resource HTTP/1.1
Host: example.com
Range: bytes=1230000-999999999999

</artwork></figure>
<t>
where the last-byte-pos in the Request is much larger than the last-byte-pos returned in response to an open-ended byte-range HEAD request, as described above.
Expand All @@ -292,16 +297,18 @@
<t>
For example:
</t>
<figure><artwork type="example">
GET /resource HTTP/1.1
Range: bytes=1230000-999999999999
<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with=" ">
GET /resource HTTP/1.1
Host: example.com
Range: bytes=1230000-999999999999

</artwork></figure>
<t>
returns
</t>
<figure><artwork type="example">
HTTP/1.1 206 Partial Content
Content-Range: bytes 1230000-999999999999/*
<figure><artwork type="message/http; msgtype=&#34;response&#34;" x:indent-with=" ">
HTTP/1.1 206 Partial Content
Content-Range: bytes 1230000-999999999999/*
</artwork></figure>
<t>
from the server to indicate that the response will start at byte 1230000 and continues indefinitely to include all aggregated content, as it becomes available.
Expand All @@ -312,16 +319,18 @@
<t>
For example:
</t>
<figure><artwork type="example">
GET /resource HTTP/1.1
Range: bytes=1230000-999999999999
<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with=" ">
GET /resource HTTP/1.1
Host: example.com
Range: bytes=1230000-999999999999

</artwork></figure>
<t>
will return
</t>
<figure><artwork type="example">
HTTP/1.1 206 Partial Content
Content-Range: bytes 1230000-1234567/*
<figure><artwork type="message/http; msgtype=&#34;response&#34;" x:indent-with=" ">
HTTP/1.1 206 Partial Content
Content-Range: bytes 1230000-1234567/*
</artwork></figure>
<t>
from the server to indicate that the response will start at byte 1230000 and end at byte 1234567 and will not include any aggregated content. This is the response expected from a typical HTTP server - one that doesn't support byte-range requests on aggregating content.
Expand All @@ -342,32 +351,36 @@
learn what range the server has currently available and initiate an
indeterminate-length transfer. For example:
</t>
<figure><artwork type="example">
HEAD /resource HTTP/1.1
Range: bytes=0-
<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with=" ">
HEAD /resource HTTP/1.1
Host: example.com
Range: bytes=0-

</artwork></figure>
<t>
With the Content-Range response header indicating the (or ranges) available. For example:
</t>
<figure><artwork type="example">
206 Partial Content
Content-Range: bytes 0-1234567/*
<figure><artwork type="message/http; msgtype=&#34;response&#34;" x:indent-with=" ">
206 Partial Content
Content-Range: bytes 0-1234567/*
</artwork></figure>
<t>
The client can then issue a request for a range starting at the end
value (using a very large value for the end of a range) and receive
only new content.
</t>
<figure><artwork type="example">
GET /resource HTTP/1.1
Range: bytes=1234567-999999999999
<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with=" ">
GET /resource HTTP/1.1
Host: example.com
Range: bytes=1234567-999999999999

</artwork></figure>
<t>
with a server returning a Content-Range response indicating that an indeterminate-length response body will be provided
</t>
<figure><artwork type="example">
206 Partial Content
Content-Range: bytes 1234567-999999999999/*
<figure><artwork type="message/http; msgtype=&#34;response&#34;" x:indent-with=" ">
206 Partial Content
Content-Range: bytes 1234567-999999999999/*
</artwork></figure>
</section>
<section anchor="shift-buffers" title="Shift Buffer Representations">
Expand All @@ -377,45 +390,49 @@
<t>
For example a Range request containing:
</t>
<figure><artwork type="example">
HEAD /resource HTTP/1.1
Range: bytes=0-
<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with=" ">
HEAD /resource HTTP/1.1
Host: example.com
Range: bytes=0-

</artwork></figure>
<t>
returns
</t>
<figure><artwork type="example">
206 Partial Content
Content-Range: bytes 1000000-1234567/*
<figure><artwork type="message/http; msgtype=&#34;response&#34;" x:indent-with=" ">
206 Partial Content
Content-Range: bytes 1000000-1234567/*
</artwork></figure>
<t>
indicating that the first 1000000 bytes were not accessible at the time the HEAD request was processed. Subsequent HEAD requests could return:
</t>
<figure><artwork type="example">
Content-Range: bytes 1000000-1234567/*
<figure><artwork type="example" x:indent-with=" ">
Content-Range: bytes 1000000-1234567/*
</artwork></figure>
<figure><artwork type="example">
Content-Range: bytes 1010000-1244567/*
<figure><artwork type="example" x:indent-with=" ">
Content-Range: bytes 1010000-1244567/*
</artwork></figure>
<figure><artwork type="example">
Content-Range: bytes 1020000-1254567/*
<figure><artwork type="example" x:indent-with=" ">
Content-Range: bytes 1020000-1254567/*
</artwork></figure>
<t>
Note though that the difference between the first-byte-pos and last-byte-pos need not be constant.
</t>
<t>
The client could then follow-up with a GET Range request containing
</t>
<figure><artwork type="example">
GET /resource HTTP/1.1
Range: bytes=1020000-999999999999
<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with=" ">
GET /resource HTTP/1.1
Host: example.com
Range: bytes=1020000-999999999999

</artwork></figure>
<t>
with the server returning
</t>
<figure><artwork type="example">
206 Partial Content
Content-Range: bytes 1020000-999999999999/*
<figure><artwork type="message/http; msgtype=&#34;response&#34;" x:indent-with=" ">
206 Partial Content
Content-Range: bytes 1020000-999999999999/*
</artwork></figure>
<t>
with the response body returning bytes 1020000-1254567 immediately and aggregated ("live") data being returned as the content is aggregated.
Expand Down