GDP

# 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)