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:

The HTTP server implementing this protocol.
A program that initiates TCP/IP connections with the HTTP server for the purpose of sending HTTP requests.
Application specific data, usually enclosed in a request or response body.
A resource representing an isolated pathway for message transmission. Each channel has a single unique message queue.
A client that sends HTTP requests to the server for the purposes of receiving messages via some channel.
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.
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:

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:
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:

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:

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.