caliban(8)              FreeBSD System Manager's Manual             caliban(8)

NAME
     caliban - Pipelining extension for HTTP/1.1

DESCRIPTION
     Caliban is a simple extension to HTTP/1.1 that enables clients to request
     more than 1 resource in a single HEAD or GET request and receive the
     responses pipelined.  Such requests are called compound requests.

   CLIENTS
     Clients must not send compound requests to servers that do not advertise
     support for the Caliban extension with an "X-Caliban: 1" header line in
     responses.

     To create a compound request, clients must list the desired resource
     names separated by semicolons (ASCII 59) in the resource field of a
     request line.  Resource names must be expressed in the UTF-8 encoding.
     Clients must not insert whitespace on either side of the semicolons:

     GET image0.jpg;image1.jpg;image3.jpg HTTP/1.1

     Clients must not create compound requests with the request method set to
     any method other than HEAD or GET.  Clients must not create compound
     requests with the protocol field set to HTTP/1.0.  Clients must not
     create request lines longer than 8192 bytes.  Clients must not request
     more than 256 resources in a compound request.

     Clients must percent-encode semicolons, percent signs, and whitespace
     characters in resource names by replacing the characters to be encoded
     with a percent sign (ASCII 37) followed by two ASCII characters
     representing the 8-bit character code of the character being encoded, in
     hexadecimal notation.  Percents signs must be encoded this way and not by
     being doubled.

     If clients include an "If-Modified-Since" or "If-Unmodified-Since" header
     line in a request, clients must list the dates for each requested
     resource separated by semicolons in the value of the header line.
     Clients must not insert whitespace on either side of the semicolons.
     Clients must list the dates in the order that the corresponding resources
     appear in the request line:

     If-Modified-Since: Mon, 08 Feb 2016 11:02:12 UMT;Mon, 08 Feb 2016 01:34:50 UMT;Sun, 07 Feb 2016 10:49:17 UMT

     If clients lack cached dates for requested resources, clients must insert
     separating semicolons to create empty fields.  Clients must include at
     least 1 date or omit the entire header line.  Clients must not create
     "If-Modified-Since" and "If-Unmodified-Since" header lines longer than
     8192 bytes.  There is enough room in 8192 bytes to hold a header line
     with 256 dates.

     Other content negotiation header lines in a compound request apply to all
     requested resources.  For example, if a client sends an "Accept" header
     line specifying only image types with a request for image and non-image
     resources, the server must send a "406 Not Acceptable" response to each
     non-image request.  Clients should request as many resources as possible
     in single compound requests.  Clients should set the "Accept" header line
     value to list all acceptable types.

     All cookies in a compound request apply to all requested resources.

     Clients must submit a compound request to a server and then attempt to
     read a response for every resource listed in the request.  Clients must
     expect responses to be sent in the order that the corresponding resources
     were listed in the request.  Clients must read and parse responses one at
     a time, detecting the presence of a "Connection:  close" header line in
     each response header.  When clients detect a "Connection:  close" header
     line in one of the responses, clients must close the connection after
     receiving that response.

     If the first response is an error response and the "Connection: close"
     header line is present, the response is for the compound request as a
     whole.  If the "Connection: close" header line is not present, the
     response is to the first resource listed in the request line.

     A response subsequent to the first response is always a response to a
     resource requested in the compound request and not to the compound
     request as a whole.  If a response of any kind, subsequent to the first
     response, contains a "Connection:  close" header line, and the response
     is the last expected response, the server is closing the connection after
     successful delivery of all the responses to the compound request.  If the
     response is not the last expected response, the server is behaving
     erratically.  The client must close the connection.

   SERVERS
     Servers that support the caliban extension must include the "X-Caliban:
     1" header line in their responses.

     Servers must not process request lines as compound requests when the
     request method is any method other than HEAD or GET.  Servers must not
     process request lines as compound requests when requests initiate a
     WebSocket handshake.  Servers must not process request lines as compound
     requests when the protocol field is set to HTTP/1.0.

     Servers must be able to process request header lines with lengths up to
     8192 bytes.  Servers must decode percent-encoded bytes in resource names.
     Servers must support compound requests that contain up to 256 requests
     but no more.

     Servers must interpret the resource fields of compound requests as
     semicolon-delimited lists of requested resources with UTF-8 encoded
     names.  Servers must deliver responses to those requests in the order
     that the resources are listed.  Servers must deliver all responses before
     accepting further client requests.

     Servers must interpret the values of "If-Modified-Since" and "If-
     Unmodified-Since" header lines as semicolon-delimited lists of
     modification dates.  Servers must use the date at the same ordinal
     position as the ordinal position of the resource in the request line to
     process that resource.

     Servers must consider all other content negotiation header lines when
     processing all resources in a compound request.

     Servers must make all cookies in a compound request available to all the
     requested resources that can consume cookies.

     If servers need to deliver an error response to compound requests as a
     whole, servers must include a "Connection: close" header line in a single
     response header and close connections.  This applies to the following 3
     paragraphs.

     Servers must respond with a "429 Too Many Requests" response to compound
     requests that list more than 256 resources in resource fields.

     Servers must respond with a "400 Bad Request" response to compound
     requests with empty resource names in the resource fields.  Specifically,
     servers must reject requests with resource lists that begin or end with a
     semicolon or that have two adjacent semicolons.

     Servers must respond with a "400 Bad Request" response to compound
     requests that do not have the same quantity of resources listed in the
     request lines as they have date fields (empty or otherwise) in the values
     of "If-Modified-Since" or "If-Unmodified-Since" header lines.

     If servers wish to notify clients to close connections after receipt of
     all the responses to a compound request, servers must include a
     "Connection: close" header line in the last delivered response only.

     If servers encounter unrecoverable errors while processing a pipeline
     such that the servers cannot deliver a response to each request in a
     compound request, servers must close connections without explanation.

AUTHORS
     James Bailie <jimmy@mammothcheese.ca>
     http://www.mammothcheese.ca

                               December 2, 2016