| Basic HTTP Push Relay Protocol |
| |
| Rev. 2.23 |
| |
| 1. Introduction |
| |
| 1.1. Purpose |
| |
| 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. |
| |
| 1.2. Requirements |
| |
| 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." |
| |
| 1.3. Terminology |
| |
| This specification uses a number of terms to refer to the roles played |
| by participants in, and objects of, this protocol: |
| |
| server |
| The HTTP server implementing this protocol. |
| |
| client |
| A program that initiates TCP/IP connections with the HTTP server |
| for the purpose of sending HTTP requests. |
| |
| message |
| Application specific data, usually enclosed in a request or |
| response body. |
| |
| channel |
| A resource representing an isolated pathway for message |
| transmission. Each channel has a single unique message queue. |
| |
| subscriber |
| A client that sends HTTP requests to the server for the purposes |
| of receiving messages via some channel. |
| |
| publisher |
| A client that sends HTTP requests to the server in order to |
| transmit messages to subscribers via a channel. |
| |
| channel id |
| A unique identifier for a channel. |
| |
| location |
| A url (or set of urls) on the server. |
| |
| 2. Requirements |
| |
| 2.1. Server Requirements |
| |
| 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. |
| |
| 2.2. Client Requirements |
| |
| 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). |
| |
| 2.3. The Channel ID |
| |
| It is not the responsibility of the server to generate IDs. |
| |
| 3. Server Operation |
| |
| 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. |
| |
| 3.1. The Subscriber |
| |
| 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: |
| |
| Long-Polling |
| Requests for existing messages will be responded to immediately; |
| responses to requests for messages not yet available MUST be |
| delayed until the message becomes available. Delayed responses |
| MUST satisfy all of the following conditions: |
| |
| + A 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. |
| + If the channel the subscriber is waiting on is deleted or for |
| some reason becomes unavailable, the server MUST immediately |
| send a 410 Gone response. |
| + If another subscriber has conflicted with this request, the |
| server MUST immediately send a 409 Conflict response. |
| |
| Interval-Polling |
| All requests will be responded to immediately. Requests for |
| messages not yet available MUST produce a 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: |
| |
| Broadcast |
| No additional actions are performed |
| |
| Last-in, first-out |
| All but the most recent long-held subscriber request on the |
| channel are sent a 409 Conflict response. |
| |
| First-in, last-out |
| All but the oldest request will be sent a 409 Conflict |
| |
| The server SHOULD make this selection configurable, and MUST default to |
| broadcast behavior. |
| |
| 3.2. The Publisher |
| |
| 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: |
| * GET requests receive a 200 OK response for existing channels and a |
| 404 Not Found otherwise. |
| * PUT requests receive a 200 OK response. The request creates a |
| channel if no channel with the given channel id exists. |
| * DELETE requests receive a 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. |