aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md30
1 files changed, 25 insertions, 5 deletions
diff --git a/README.md b/README.md
index 3c8df33..b1decc9 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,23 @@ It is written in C and supports pluggable modules for bridge peer selection modu
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 compatibility between traditional network transports and WebSockets.
+## Table of contents
+
+* [Motivation](#motivation)
+* [Dynamic proxying](#dynamic-proxying)
+ * [Peer discovery backends](#peer-discovery-backends)
+ * [Peer stream framing](#peer-stream-framing)
+* [Configuration / Usage](#configuration--usage)
+ * [Command line arguments](#command-line-arguments)
+ * [Configuration file](#configuration-file)
+ * [Default backend](#default-backend)
+* [Building](#building)
+* [Development](#development)
+ * [Peer discovery backend API](#peer-discovery-backend-api)
+ * [Peer stream framing API](#peer-stream-framing-api)
+
+## Motivation
+
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.
### Framing
@@ -37,7 +54,7 @@ being the primary discriminator between services.
To allow `websocksy` to connect any protocol to a WebSocket endpoint despite these differences, there are two avenues of extensibility.
-### Peer discovery backend
+### Peer discovery backends
Peer discovery backends map the metadata from a WebSocket connection, such as HTTP headers (e.g. Cookies), the connection endpoint and any indicated
subprotocols to a peer address naming a 'normal' socket.
@@ -67,8 +84,11 @@ framing functions (both built in and loaded from plugins).
* `auto`: Send all data immediately, with the `text` type if the content was detected as valid UTF-8 string, otherwise use a `binary` frame
* `binary`: Send all data immediately as a `binary` 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 can be specified hexadecimally 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 valid UTF-8 (data frame otherwise). The configuration string may be one of `crlf`, `lfcr`, `lf`, `cr` specifying the sequence to look for.
+* `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 specified
+ hexadecimally 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 valid
+ UTF-8 (binary frame otherwise). The configuration string may be one of `crlf`, `lfcr`, `lf`, `cr` specifying the sequence to look for.
# Configuration / Usage
@@ -111,8 +131,8 @@ 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, which fails clients indicating
- an explicitly supported subprotocol. The special value `*` matches the first available protocol.
+* `protocol`: The subprotocol to negotiate with the WebSocket peer. If not set, only the empty protocol set is accepted, which
+ fails clients indicating an explicitly supported subprotocol. The special value `*` matches the first available protocol.
* `framing-config`: Arguments to the framing function
# Building