1. Concepts

The Pushlet protocol facilitates publishing and streaming of data on top of the standard HTTP protocol This section introduces the main Pushlet protocol concepts.

1.1. Example

As a start, below is an example of Pushlet protocol exchange between a client and a server (various details omitted).

1: (client to server: start session) 2: GET /pushlet/pushlet.srv?p_event=join&p_format=xml HTTP/1.1 3: 4: (server to client: ack session create) 5: HTTP/1.1 200 OK 6: 7: <event p_id="faruhofoja" p_event="join-ack" p_format="xml" /> 8: 9: 10: (client to server: open data stream) 11: GET /pushlet/pushlet.srv?p_event=listen&p_id=faruhofoja&p_mode=stream&p_subject=/temperature HTTP/1.1 12: 13: (server to client: send data stream) 14: HTTP/1.1 200 OK 15: 16: <event p_sid="dujut" p_id="faruhofoja" p_mode="stream" p_event="listen-ack" p_format="xml" /> 17: 18: <event p_sid="dujut" p_subject="/temperature" p_event="data" city="twente" value="8" /> 19: 20: <event p_sid="dujut" p_subject="/temperature" p_event="data" city="amsterdam" value="8" /> 21: 22: <event p_sid="dujut" p_subject="/temperature" p_event="data" city="leeuwarden" value="6" /> 23: 24: <event p_sid="dujut" p_subject="/temperature" p_event="data" city="limburg" value="12" /> 25:

The above example shows a client starting a session through a join request. This request is acknowledged with an XML event join-ack. Subsequently a data stream is opened using the listen request. The listen-ack is returned followed by the data events over the data channel.

1.2. Streaming

Concepts used in the Pushlet protocol are somewhat similar to those used in the Real-Time Streaming Protocol (RTSP).

Like RTSP the Pushlet protocol provides both a control channel and a data channel. The client uses the control channel to start/stop sessions (join/leave), subscribe/unsubscribe to/from subjects, publish data etc. The actual streaming of data is transmitted out of band over a separate (HTTP) connection.

Since the HTTP protocol is request/response oriented, data streaming is achieved similar to audio/video streaming over HTTP, i.e. as a very long response. Since not all clients may support long-lived HTTP responses, data streaming may also be conducted in the so called pull and poll modes as controlled by the client or enforced by the server. In these latter modes the server will end the HTTP response document after one or more events are returned and instruct the client to wait and renew (refresh) the data streaming request.

1.3. Events

Protocol control and data messages exchanged between client and server are called events. Pushlet events are currently defined as a flat set of name/value pairs. The Pushlet protocol reserves names starting with p_ to discern protocol-specific names from user-supplied names.

Note: future versions of the protocol will introduce a more versatile event structure in which applications may use arbitrary payload data.

1.4. Event Encoding

To encode events (control responses and data) sent to the client, the Pushlet protocol supports several encoding formats. Browser clients supporting DHTML receive events encoded as JavaScript calls. This technique is similar to what Apple describes as Remote Scripting. Other clients, such as Java clients can receive events as XML elements as a stream (format="xml" or as a complete document (format="xml-strict"). The preferred encoding format is specified by the client.

Control events to the server can be specified as HTTP query parameters when using GET or as XML in a POST body.

1.5. Session Management

The Pushlet protocol provides a simple form of session management. A client starts with creating a Pushlet session using a join request. This request is acknowledged by the server through a join-ack response. Within the response a session id ( p_id) is returned that the client should supply in all other requests in this session. Note that Pushlet session management is independent from the standard HTTP session management (often with cookies) as to be independent of specific server implementations or (browser) client settings.

Since not all applications may require session management, the join-listen service is supplied that allows clients to join, subscribe and listen in one request. This allows for very simple clients (like even Unix telnet) to receive data without the need to keep state.

1.6. Topic Subscription

After a client has created a Pushlet session or even while streaming data, it can subscribe to and unsubscribe from topics, historically called subjects.

1.7. Event Publication

After a client has created a Pushlet session or even while streaming data, it use the publish service to send data events to the server. The server will route the event to those clients with a matching subscription (multicast). The event may also be directed to one specific client by supplying that client's session id.