Warning: Reason support is experimental. We are looking for beta-tester and contributors.

Comet

Available from Ocsigen server version 1.90

This extension provides an easy way for the server to send messages to the connected clients. It can be used as such or wrapped in a high-level module. Such a wrapping is provided in Eliom. The whole implementation is in the extensions/comet.ml file, the corresponding interface is in the associated mli file.

User interface

The user interface for the extension is quite simple. It is divided into two distinct modules, namely Channels and Security. The former allow channel creation and tampering while the latter gives a few functions to interrupt normal execution flow. The interfaces of both modules are pretty straight forward. Documentation is provided for each function in the mli file.

The Channels module important functions are: create for channel creation, write to actually send a message and get_id to get a channel identifier. Detailed description is available in the mli file.

The Security module is accessible from Ocsigen's command pipe. The different commands aredeactivate, activate and set_timeout, the meaning of each of them along with their arguments are given in the mli file.

Specifications and client implementation

If not used with the Eliom high-level wrap, it is up to the developer to create a compatible client code. This task requires one to know the protocol used by the extension.

It is the client's responsibility to open a connection indicating the channels it want to be registered to. This is acheived by making an Xml Http Request (XHR) with the following characteristics: the content-type header field must read application/x-ocsigen-comet, the registration POST parameter must be included with a list of channel as value. The said list should be made of channel identifiers separated by newline (\n) character and encoded according to the escape Javascript primitive. Following is an example of list for registration:

randomstringblahblahtotofoocoucoubardfhkqjsdkjdfgqf
nicely%20encoded%20channel%20identifier
foooobaarfoofoo

When the server receives an XHR with a comet specific content-type it decodes the registration list, and waits for one of them to be written upon. Then it either times out sending an empty answer or answers with a list of values written on channels. The said list is newline separated and contains channel identifier-value tuples. The reserved value "ENDED_CHANNEL" marks channels that no longer exists on the server (their identifier is no longer relevant). An example of answer the server can make to the example client XHR is:

randomstringblahblahtotofoocoucoubardfhkqjsdkjdfgqf:ENDED_CHANNEL
nicely%20encoded%20channel%20identifier:42%2043%2044

In this example, the first channel identifier is no longer associated to any channel on the server, the second channel receives the encoded string value "42 43 44" and the third channel hasn't been written upon.