websocksy.h

#ifndef WEBSOCKSY_HEADER_INCLUDED
#define WEBSOCKSY_HEADER_INCLUDED
#include <stdint.h>
#include <stdlib.h>
#include <nettle/sha1.h>
#include <nettle/base64.h>

/* Version defines */
#define WEBSOCKSY_API_VERSION 1
#define WEBSOCKSY_VERSION "0.1"

/* HTTP/WS read buffer size & limit */
#define WS_MAX_LINE 16384
/* Peer read buffer size / proxy packet limit */
#define PEER_BUFFER_SIZE 16384
/* Maximum number of HTTP headers to accept */
#define WS_HEADER_LIMIT 10

/*
 * State machine for WebSocket connections
 */
typedef enum {
	ws_new = 0, /* Initial state */
	ws_http, /* HTTP Headers */
	ws_open, /* Upgrade performed, forwarding */
	ws_closed /* Close frame sent */
} ws_state;

/*
 * WebSocket frame opcodes
 * RFC Section 5.2
 */
typedef enum {
	ws_frame_continuation = 0,
	ws_frame_text = 1,
	ws_frame_binary = 2,
	ws_frame_close = 8,
	ws_frame_ping = 9,
	ws_frame_pong = 10,
	ws_frame_discard /* Special opcode to discard bytes from the peer buffer */
} ws_operation;

/*
 * WebSocket close reasons / response codes
 * RFC Section 7.4.1
 */
typedef enum {
	ws_close_http = 100,
	ws_close_normal = 1000,
	ws_close_shutdown = 1001,
	ws_close_proto = 1002,
	ws_close_data = 1003,
	ws_close_format = 1007,
	ws_close_policy = 1008,
	ws_close_limit = 1009,
	ws_close_unexpected = 1011
} ws_close_reason;

/*
 * HTTP header split into tag and value
 */
typedef struct /*_ws_http_header*/ {
	char* tag;
	char* value;
} ws_http_header;

/*
 * Peer stream framing function
 *
 * Since the WebSocket protocol transfers its payload using discrete frames, unlike the peer's
 * underlying TCP/Unix sockets (UDP is a different matter and may be framed directly), we need
 * a method to indicate whether a complete frame to be forwarded has been received from the peer
 * and with what WebSocket frame type to forward it (binary/text). Since this is largely
 * protocol-dependent, this functionality needs to be user-extendable.
 *
 * We do however provide some default framing functions:
 * 	* auto: Based on the content, forward every read result as binary/text
 * 	* binary: Always forward all reads as binary frames
 * 	* separator: Separate binary frames on a sequence of bytes
 * 	* newline: Forward text frames separated by newlines (\r\n)
 *
 * The separator function is called once for every successful read from the peer socket and called
 * again when it indicates a frame boundary but there is still data in the buffer.
 * The `framing_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
 * NULL `data` pointer as an indication that any allocation within `framing_data` is to be freed.
 * The return value is the number of bytes to be sent to the peer.
 */
typedef int64_t (*ws_framing)(uint8_t* data, size_t length, size_t last_read, ws_operation* opcode, void** framing_data, const char* config);

/* Peer connection modes */
typedef enum {
	peer_transport_detect,
	peer_tcp_client,
	peer_udp_client,
	peer_fifo_tx,
	peer_fifo_rx,
	peer_unix_stream,
	peer_unix_dgram
} peer_transport;

/* Peer address model */
typedef struct /*_ws_peer_info*/ {
	/* Peer protocol data */
	peer_transport transport;
	char* host;
	char* port;

	/* Framing function for this peer */
	ws_framing framing;
	char* framing_config;

	/* WebSocket subprotocol indication index*/
	size_t protocol;
} ws_peer_info;

/* Core connection model */
typedef struct /*_web_socket*/ {
	/* WebSocket state & data */
	int ws_fd;
	uint8_t read_buffer[WS_MAX_LINE];
	size_t read_buffer_offset;
	ws_state state;
	time_t last_event;

	/* HTTP request headers */
	size_t headers;
	ws_http_header header[WS_HEADER_LIMIT];

	/* WebSocket parameters */
	char* request_path;
	unsigned websocket_version;
	char* socket_key;
	unsigned want_upgrade;

	/* WebSocket indicated subprotocols*/
	size_t protocols;
	char** protocol;

	/* Peer data */
	ws_peer_info peer;
	int peer_fd;
	uint8_t peer_buffer[PEER_BUFFER_SIZE];
	size_t peer_buffer_offset;
	void* peer_framing_data;
} websocket;

/*
 * Peer discovery backend API
 *
 * Peer discovery backends are used to dynamically select the peer based on parameters supplied by
 * the WebSocket connection. The backend maps WebSocket characteristics (such as the endpoint used,
 * the supported protocols and HTTP client headers) to a TCP/UDP/Unix socket peer endpoint using
 * some form of possibly user-configurable provider (such as databases, files, crystal balls or
 * sheer guesses).
 *
 * Backends are supplied as shared objects exporting the following symbols:
 * 	* `init`: Required, initialize any storage or connections required
 * 	* `configure`: Optional, configure the backend
 * 	* `query`: Required, find a peer for the given parameters
 * 	* `cleanup`: Optional, Release any acquired resources prior to shutdown
 */

/*
 * Called once for the initialization of backend resources. Exported as the `init` symbol from
 * the backend shared object.
 * Returns the WEBSOCKSY_API_VERSION used to compile the backend.
 */
typedef uint64_t (*ws_backend_init)();
/*
 * Called once for every backend configuration variable if the backend shared object exports it as
 * the `configure` symbol.
 * Returns 0 on success, anything else fails configuration.
 */
typedef uint64_t (*ws_backend_configure)(char* key, char* value);
/*
 * Called when a WebSocket successfully negotiates a connection upgrade and is to be connected with
 * a peer. Exported as the `query` symbol from the backend shared object.
 * The return value is a structure containing the destination address and transport to be connected to
 * the Web Socket, as well as the indicated subprotocol to use (or none, if set to the provided maximum
 * number of protocols).
 * The fields within the structure should be allocated with `calloc` and will be free'd by websocky
 * after use.
 */
typedef ws_peer_info (*ws_backend_query)(char* endpoint, size_t protocols, char** protocol, size_t headers, ws_http_header* header, websocket* ws);
/*
 * Called once for the release of all backend-internal resources if exported as the `cleanup` symbol.
 */
typedef void (*ws_backend_cleanup)();

/*
 * Composite backend model structure
 */
typedef struct /*_ws_backend*/ {
	ws_backend_init init;
	ws_backend_configure config;
	ws_backend_query query;
	ws_backend_cleanup cleanup;
} ws_backend;

/* Core API */
ws_framing core_framing(char* name);
int core_register_framing(char* name, ws_framing func);

/* Internal helper functions */
char* xstr_lower(char* in);
int client_register(websocket* ws);
int client_connect(websocket* ws);
#endif