The primary purpose of this protocol is to enable a method of long-polling, transparent to the web client, where client connections idle only on the HTTP server and need not be forwarded.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119. An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements.
An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant."
This specification uses a number of terms to refer to the roles played by participants in, and objects of, this protocol:
The HTTP server MUST have a mechanism of specifying a url, or a set of urls as publisher and subscriber locations. All requests to the publisher location MUST be treated as publisher requests, all to the subscriber location as subscriber requests.
The server MUST implement a mechanism for identifying channels with unique ids. This MAY, for example, be a url parameter (/foo/?id=123) or a cookie. Methods of channel identification other than those using the url MAY be used, but are strongly discouraged.
The server MUST accept requests on publisher locations and respond to them immediately. It MUST also accept requests on subscriber locations, but need not respond immediately.
All clients must prodice valid HTTP requests.
Subscriber clients must have a caching
mechanism that appropriately reacts to Last-Modified and Etag
response headers (web browsers, for example).
It is not the responsibility of the server to generate IDs.
A publisher request functions as notification to the server of a message to send to some subscribers over some channel. A subscriber request notifies the server of the subscriber's intent to receive a message.
The server MUST accept all valid HTTP GET requests to the
subscriber location.
All other request methods SHOULD be responded to with a 405 Method Not Allowed status code.
Subscriber requests are considered notifications of intent to receive some message. Subscribers may request existing messages,
messages that are not yet available, and messages that are no longer available. The requested message is identified using the
If-Modified-Since and If-None-Match request headers. A request with no If-Modified-Since header
MUST be assumed to be requesting the oldest available message in a channel. Each 200 OK response containing a message MUST
have its Last-Modified and Etag headers set so that a request using those headers will be interpreted as
a request for the next available message. Additionally, said 200 OK MUST contain the Content-Type header of
the message publisher request, unless no Content-Type header had been provided or it is
explicitly overridden by server configuration.
There are several common mechanisms for performing an HTTP server push. The rest of the behavior of the server in response to a subscriber request SHOULD be configurable and MUST be selected from the following list of mechanisms:
200 OK response containing the message (and its Content-Type) MUST be sent immediately
after the message becomes available. The entire response must be indistinguishable from a response to a request for
an existing message.
410 Gone response.
409 Conflict response.
304 Not Modified response code.
In addition, when the server receives more than one concurrent subscriber request on the same channel, it MUST do one of the following:
409 Conflict response.
409 Conflict
The server SHOULD make this selection configurable, and MUST default to broadcast behavior.
The server MUST accept all valid HTTP requests to the publisher location. The server, when sent a publisher request, MUST satisfy all of the following conditions:
200 OK response for existing channels and a
404 Not Found otherwise.
200 OK response. The request creates a channel if
no channel with the given channel id exists.
200 OK if the channel identified by the
channel id exists and has been completely deleted. All subscribers MUST
have been sent a 410 Gone response. Requests for nonexistent channels MUST
be responded to with a 404 Not Found.
POST requests are used to send messages. The request MAY contain a body in any encoding representing a message to be sent over the channel. The message MUST be immediately delivered to all currently long-held subscriber requests. Additionally, the message MAY be stored for future retrieval and the oldest message stored for the channel MAY be deleted.
A POST request MUST be replied to with a 201 Created if there were any
long-held subscribers that have been sent this message, and with a
202 Accepted otherwise.
The Content-Type header of the request MUST be forwarded with the message.
Message storage limits SHOULD be configurable. publisher locations SHOULD be configurable to allow foregoing message storage on POST requests. All 200-level responses MUST, in the response body, contain information about the applicable channel. This information MAY contain the number of stored messages and the number of subscribers' requests being long-held prior to this request. The server MAY implement a content-negotiation scheme for this information.