                         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.
