From 76d0674d7b02c42fcd110ce87fa19600191a4eb9 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Wed, 27 Dec 2017 18:13:22 -0800 Subject: fixes #169 document websocket transport --- docs/nng_ws.adoc | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/nng_ws.adoc (limited to 'docs') diff --git a/docs/nng_ws.adoc b/docs/nng_ws.adoc new file mode 100644 index 00000000..8073e158 --- /dev/null +++ b/docs/nng_ws.adoc @@ -0,0 +1,161 @@ +nng_ws(7) +========= +:doctype: manpage +:manmanual: nng +:mansource: nng +:icons: font +:source-highlighter: pygments +:copyright: Copyright 2017 Garrett D'Amore \ + Copyright 2017 Staysail Systems, Inc. \ + Copyright 2017 Capitar IT Group BV \ + This software is supplied under the terms of the MIT License, a \ + copy of which should be located in the distribution where this \ + file was obtained (LICENSE.txt). A copy of the license may also \ + be found online at https://opensource.org/licenses/MIT. + +NAME +---- +nng_ws - WebSocket transport for nng + +SYNOPSIS +-------- + +[source,c] +---------- +#include + +int nng_ws_register(void); +---------- + +DESCRIPTION +----------- + +The _nng_ws_ transport provides communication support between +_nng_ sockets across a TCP/IP network using +https://tools.ietf.org/html/rfc6455[WebSockets]. Both IPv4 and IPv6 +are supported when the underlying platform also supports it. + +The protocol details are documented in +http://nanomsg.org/rfcs/sp-websocket-v1.html[WebSocket Mapping for Scalability Protocols]. + +Registration +~~~~~~~~~~~~ + +Depending upon how the library was built, it may be necessary to +register the transport by calling `nng_ws_register`. This function +returns zero on success, or an nng error value if the transport +cannot be initialized for any reason. + +URI Format +~~~~~~~~~~ + +This transport uses URIs using the scheme `ws://`, followed by +an IP address or hostname, optionally followed by a colon and an +TCP port number, optionally followed by a path. (If no port number +is specified then port 80 is assumed. If no path is specified then +a path of `/` is assumed.) +For example, the URI `ws://localhost/app/pubsub` would use +port 80 on localhost, with the path `/app/pubsub`. + +When specifying IPv6 addresses, the address must be enclosed in +square brackets (`[]`) to avoid confusion with the final colon +separating the port. + +For example, the same path and port on the IPv6 loopback address (`::1`) +would be specified as `ws://[::1]/app/pubsub`. + +NOTE: When using symbolic names, the name is resolved when the +name is first used. _nng_ won't become aware of changes in the +name resolution until restart, +usually.footnote:[This is a bug and will likely be fixed in the future.] + +NOTE: The value specified as the host, if any, will also be used +in the `Host:` HTTP header during HTTP negotiation. + +The special value of 0 (`INADDR_ANY`) can be used for a listener +to indicate that it should listen on all interfaces on the host. +A short-hand for this form is to either omit the address, or specify +the asterisk (`*`) character. For example, the following three +URIs are all equivalent, and could be used to listen to port 9999 +on the host: + + 1. `ws://0.0.0.0:9999` + 2. `ws://*:9999` + 3. `ws://:9999` + +Socket Address +~~~~~~~~~~~~~~ + +When using an `nng_sockaddr` structure, the actual structure is either +of type `nng_sockaddr_in` (for IPv4) or `nng_sockaddr_in6` (for IPv6). +These are `struct` types with the following definitions: + +[source,c] +-------- +#define NNG_AF_INET 3 <1> +#define NNG_AF_INET6 4 +#define NNG_MAXADDRLEN 128 + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_INET + uint16_t sa_port; // TCP port number + uint32_t sa_addr; + // ... +} nng_sockaddr_in; + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_INET6 + uint16_t sa_port; // TCP port number + uint8_t sa_addr[16]; + // ... +} nng_sockaddr_in6; +-------- +<1> The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically. +<2> Other members may be present, but only those listed here +are suitable for application use. + +The `sa_family` member will have the value `NNG_AF_INET` or `NNG_AF_INET6`. +The `sa_port` and `sa_addr` are the TCP port number and address, both in +network byte order (most significant byte is first). + +Transport Options +~~~~~~~~~~~~~~~~~ + +The following transport options are available. Note that +setting these must be done before the transport is started. + +`NNG_OPT_WS_REQUEST_HEADERS`:: + +This value is a string, consisting of multiple lines terminated +by CRLF sequences, that can be used to add further headers to the +HTTP request sent when connecting. This option can be set on dialers, +and retrieved from pipes. + +`NNG_OPT_WS_RESPONSE_HEADERS`:: + +This value is a string, consisting of multiple lines terminated +by CRLF sequences, that can be used to add furthe headers to the +HTTP response sent when connecting. This option can be set on listeners, +and retrieved from pipes. + +// We should also look at a hook mechanism for listeners. Probably this could +// look like NNG_OPT_WS_LISTEN_HOOK_FUNC which would take a function pointer +// along the lines of int hook(void *, char *req_headers, char **res_headers), +// and NNG_OPT_LISTEN_HOOK_ARG that passes the void * passed in as first arg. +// Alternatively we can uplevel the HTTP API and pass the actual HTTP objects. + +SEE ALSO +-------- +<> + +COPYRIGHT +--------- + +Copyright 2017 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/LICENSE.txt[MIT License]. -- cgit v1.2.3-70-g09d2