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