GDP Websocket gateway

A gateway for subscribing to a GDP log via websockets.

Requirements and setup

Requires following to be installed:

• GDP C library (libgdp)
• GDP python bindings
• Python 2.7
• twisted, Event-based framework for internet applications (package python-twisted on Ubuntu)
• autobahn, WebSocket/WAMP implementation for Python/Twisted (package python-autobahn on Ubuntu)

Once the required dependencies are met, running a gateway is as simple as

python gdp-ws.py --port XXXX

This opens a websocket server on the specified port. If needed, a secure websocket interface can also be instantiated. See python gdp-ws.py -h for invocation details. Note that setting up secure websockets requires you to have appropriate certificate/private keys.

Client interaction

Clients issue subscription requests by sending a JSON encoded text message, which should at least specify the logname (and optionally the range of records as well). An example client=>server message looks like the following:

{"logname": "a-human-readable-logname", "startrec": 0, "numrec": 20}

The startrec and numrec represent the range of records and are optional parameters. The behavior is the same as for gdp_gcl_subscribe API call in the C library. The default values are startrec = 0 and numrec = 1, which implies a request for only the next available record. For the subscription to run forever, use numrec = 0 (see documentation doc/gdp-programmatic-api.html)

The websocket gateway subscribes to the specified log on behalf of the client and sends the events it receives from a log-server to the client. An example response looks as follows:

{"logname": "a-human-readable-logname", "ep_stat": [200, "OK [200 = 0xc8]"],
"datum": {"recno": 24, "data": "hello", "ts": {"tv_sec": 1498143987,
"tv_accuracy": 0.0, "tv_nsec": 662371000}}, "type": 1}

A quick summary of the various fields is:

• logname: the name of the log, of course. Useful in case a client has multiple subscriptions active
• ep_stat: a status code returned by the C library (EP_STAT)
• type : the type of event. Valid types are defined by the C-library, see gdp/gdp.h.
• datum : the datum returned as a result of subscription. Only valid if the event type is GDP_EVENT_DATA (1).

A client can send multiple subscription requests over the same websocket. Each such request is treated as an independent request, thus a client will receive multiple copies of any new data if it has duplicate active subscriptions on the same log. However, such subscriptions are lost in case the websocket connection goes away; it is the responsibility of a client to re-send the subscription request if the connection fails for any reason.

Note that any exceptions encountered by the gateway are sent back to the client as unformatted text (see Limitations). Thus, a client should be ready to handle the incoming data that is not a well formatted JSON.

Limitations

• Only textual mode is supported for the moment. Binary data (in the logs, logname, etc) does not work.
• In particular, using JSON as the transport format rules out supporting records with binary payload.
• Any exceptions that the gateway encountered while processing a request are sent back to the client as it is. In some cases, it makes sense (such as a non-existent logname causing Error 600), but in many cases it does not (the gateway server losing connection to the GDP infrastucture)