From 3ba33c4b256577be7962dd41b0c8221a0447aef0 Mon Sep 17 00:00:00 2001 From: cbdev Date: Sat, 8 Jun 2019 12:03:18 +0200 Subject: Backend API documentation --- README.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/README.md b/README.md index 11cbfc1..246ac99 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,10 @@ framing functions (both built in and loaded from plugins). The listen port may either be exposed to incoming WebSocket clients directly or via a proxying webserver such as nginx. +Exactly one backend can be active at run time. Specifying the backend parameter a second time will unload the first backend +and load the requested one, losing all configuration. Options will be applied in the order specified to the backend loaded +at the time. + ### Command line arguments * `-p `: Set the listen port for incoming WebSocket connections (Default: `8001`) @@ -119,4 +123,31 @@ Run `make` in the project directory to build the core binary as well as the defa # Development +`websocksy` provides two major extension interfaces, which can be attached to by providing custom shared objects. +The core is written in C and designed to use as few external dependencies as possible. + +All types and structures are defined in [`websocksy.h`](websocksy.h), along with their in-depth documentation. + +The current API version is `1`. It is available via the compile-time define `WEBSOCKSY_API_VERSION`. + +## Peer discovery backend API + +When requested to load a backend, `websocksy` tries to load `backend_.so` from the plugin path, which is a +compile time variable (overridable by providing the environment variable `PLUGINPATH` to `make`), which by default +points to the `plugins/` directory. + +From the backend shared object, `websocksy` tries to resolve the following symbols: + +* `init` (`uint64t init()`): Initialize the backend for operation. Called directly after loading the shared object. + Must return the `WEBSOCKSY_API_VERSION` the module was built with. +* `configure` (`uint64_t configure(char* key, char* value)`): Set backend-specific configuration options. + Backends should ship their own documentation on which configuration options they provide. +* `query` (`ws_peer_info query(char* endpoint, size_t protocols, char** protocol, size_t headers, ws_http_header* header, websocket* ws)`): + The core function of a backend. Called once for each incoming WebSocket connection to provide a remote peer + to be bridged. The fields in the returned structure should be allocated using `calloc` or `malloc` and + will be `free`'d by the core. +* `cleanup` (`void cleanup()`): Release all allocated memory. Called in preparation to core shutdown. + +## Peer stream framing API + TBD -- cgit v1.2.3