Repository files navigation

websocksy is a highly configurableWebSocket (RFC6455) to 'normal' networking transport (TCP/UDP/Unix sockets) bridge.It is written in C and supports pluggable modules for bridge peer selection modules (for dynamic bridging) and stream framing.

It can be used to connect a wide variety of existing applications directly to a website, or to implement new functionality in a way that maintains compatibilitybetween traditional network transports and WebSockets.

• Motivation
• Dynamic proxying
  • Peer discovery backends
  • Peer stream framing
• Configuration / Usage
  • Command line arguments
  • Configuration file
  • Default backend
  • Plugins
• Building
• Development
  • Peer discovery backend API
  • Peer stream framing API

Connecting WebSockets to 'real' sockets may seem like an easy task at first, but the WebSocket protocol has some fundamental differences to TCP and UDP.

Data sent over WebSockets is explicitly framed - you get told how much data to expect for any one package. This is similar to UDP, which operates on Datagrams,which are always received as one full message and carry an integrated length field.

In contrast to that, TCP operates on a 'stream' basis, where any message boundaries need to be established by an upper layer protocol, and any messages sentmay be fragmented into multiple receive operations.

Bridging datafrom the WebSocketto the network peer is thus not the problem - one can simply write out any complete message frame received.For TCP, the other direction needs some kind of indication when to send the currently buffered data from the stream as one message to the WebSocket client.

WebSocket frames contain anopcode, which indicates the type of data the frame contains, for examplebinary,text, orping frames.

Normal sockets only transfer bytes of data as payload, without any indication or information on what they signify - that is dependent on the upper layer protocolsthat use these transport protocols.

WebSockets carry in their connection establishment additional metadata, such as HTTP headers, an endpoint address and a list of supported subprotocols,from which the server may select one it supports.

Normal sockets only differentiate connections by a tuple consisting of source and destination addresses and ports, with the destination port numberbeing the primary discriminator between services.

To allowwebsocksy to connect any protocol to a WebSocket endpoint despite these differences, there are two avenues of extensibility.

Peer discovery backends map the metadata from a WebSocket connection, such as HTTP headers (e.g. Cookies), the connection endpoint and any indicatedsubprotocols to a peer address naming a 'normal' socket.

Backends can be loaded from shared libraries and may use any facilities available to them in order to find a peer - for example they may query a databaseorscan a file based on the supplied metadata. This allows the creation of dynamically configured bridge connections.

Currently, the following peer address schemes are supported:

• tcp://<host>[:<port>] - TCP client
• udp://<host>[:<port>] - UDP client
• unix://<file> - Unix socket, stream mode
• unix-dgram://<file> - Unix socket, datagram mode

The default backend integrated intowebsocksy returns the same (configurable) peer for any connection.

To solve the problem of framing the data stream from TCP peers and selecting the correct WebSocket frame type,websocksy uses "framing functions",which can be loaded as plugins from shared objects. These are called when data was received from the network peer to decide if and how many bytes areto be framed and sent to the WebSocket, and with what frame type.

The framing function to be used for a connection is returned dynamically by the peer discovery backend. The backend may select from a library of differentframing functions (both built in and loaded from plugins).

websocksy comes with the following framing functions built in:

• auto: Send all data immediately, with thetext type if the content was detected as valid UTF-8 string, otherwise use abinary frame
• binary: Send all data immediately as abinary frame
• separator: Waits until a variable-length separator is found in the stream and sends data up to and including that position as binary frame.Takes as parameter the separator string. The escape sequences\r,\t,\n,\0,\f and\\ are recognized, arbitrary bytes may be specifiedhexadecimally using\x<hex>
• newline: Waits until a newline sequence is found in the stream and sends data up to and including that position as text frame if all data is validUTF-8 (binary frame otherwise). The configuration string may be one ofcrlf,lfcr,lf,cr specifying the sequence to look for.

websocksy may either be configured by passing command line arguments or by specifying a configuration file to be read.

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 backendand load the requested one, losing all configuration. Options will be applied in the order specified to the backend loadedat the time.

• -p <port>: Set the listen port for incoming WebSocket connections (Default:8001)
• -l <host>: Set the host for listening for incoming WebSocket connections (Default:::)
• -k <seconds>: Set the inactivity timeout for sending WebSocket keep-alive pings (Default:30)
• -b <backend>: Select external backend
• -c <option>=<value>: Pass configuration option to backend

If only one option is passed towebsocksy, it is interpreted as the path to a configuration file to be read.A configuration file should consist of one[core] section, configuring central options and an optional[backend]section, configuring the current backend. Options are set as lines of<option> = <value> pairs.

In the[core] section, the following options are recognized:

• port: Listen port for incoming WebSocket connections
• listen: Host for incoming WebSocket connections
• ping: Inactivity timeout for WebSocket keep-alive pings in seconds
• backend: External backend selection

In the[backend] section, all options are passed directly to the backend and thus are dependent on the specificimplementation. Backends should provide their own documentation files.

Anexample configuration file using thefile backend is available in the repository.

The integrated default backend takes the following configuration arguments:

• host: The peer address to connect to
• port: An explicit port specification for the peer (may be inferred from the host if not specified or ignored if not required)
• framing: The name of a framing function to be used (auto is used when none is specified)
• protocol: The subprotocol to negotiate with the WebSocket peer. If not set, only the empty protocol set is accepted, whichfails clients indicating an explicitly supported subprotocol. The special value* matches the first available protocol.
• framing-config: Configuration data for the framing function

This repository comes with some plugins already included, in addition to the built-in backend and framing functions.Documentation for these resides in theplugins/ directory.

• backend_file - Read connection peers from dynamic file paths
• framing_fixedlength - Frame the peer stream using fixed length segments
• framing_dynamic32 - Frame the peer stream using 32bit length fields from the stream itself
• framing_json - Segment the peer stream into JSON entities

To buildwebsocksy, you need the following things

• A working C compiler
• make
• gnutls andlibnettle development packages (nettle-dev andlibgnutls28-dev for Debian, respectively)

Runmake in the project directory to build the core binary as well as the default plugins.

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 inwebsocksy.h, along with their in-depth documentation.

The current API version is1. It is available via the compile-time defineWEBSOCKSY_API_VERSION.

When requested to load a backend,websocksy tries to loadbackend_<name>.so from the plugin path, which is acompile time variable (overridable by providing the environment variablePLUGINPATH tomake), which by defaultpoints to theplugins/ 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 theWEBSOCKSY_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 peerto be bridged. The fields in the returned structure should be allocated usingcalloc ormalloc andwill befree'd by the core.
• cleanup (void cleanup()): Release all allocated memory. Called in preparation to core shutdown.

Backends should take precautions and offer configuration for WebSocket requests that do not indicate a subprotocol(theprotocols argument to the backendquery function will be0).Backends should also provide a method for indicating that any subprotocol indicated is acceptable (and thus the firstone indicated, if any, will be selected). Idiomatically, this is done by accepting* as special value for the protocolfield.

Thefile backend is provided as a reference backend implementation.

At startup,websocksy tries to load all shared objects in the plugin path (plugins/ by default) that have a filename ending in.so and not starting withbackend_ (which is reserved for backend plugins, of which only one may beloaded at run time).

Plugins should declare their own initializer functions to be called at load time using e.g. the compiler's__attribute__((constructor)) syntax or the equivalent linker flag.

To register a framing function with the framing function library, the initializer function must use thecore_register_framing(char* name, ws_framing func) API exported by the core.

The framing function is called once for every successful read from the peer it is used on, and again when it indicatesa frame boundary which leaves data in the buffer. It must return the number of bytes to be framed and sent to theWebSocket client (Returning0 indicates that the message is not complete and additional data is required from thepeer). To select the frame type, set theopcode argument. The default frame type isbinary (ws_frame_binary).

Theframing_data pointer can be used to store data on a per-connection basis.If the pointer is nonzero when the connection is terminated, the function will be called with a NULLdata pointeras an indication that any allocation withinframing_data is to be freed.

An example plugin providing thefixedlength framing function is provided in the repository.Additions to thewebsocksy plugin library are welcome!