Backend API documentation

1 files changed, 31 insertions, 0 deletions

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 <port>`: 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_<name>.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