diff options
Diffstat (limited to 'docs/nng_ws.adoc')
| -rw-r--r-- | docs/nng_ws.adoc | 209 |
1 files changed, 0 insertions, 209 deletions
diff --git a/docs/nng_ws.adoc b/docs/nng_ws.adoc deleted file mode 100644 index c41ccc1c..00000000 --- a/docs/nng_ws.adoc +++ /dev/null @@ -1,209 +0,0 @@ -= nng_ws(7) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document 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 <nng/transport/websocket/ws.h> - -int nng_ws_register(void); -int nng_wss_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. - -If TLS support is enabled in the library, secure WebSockets (over TLS v1.2) -can be used as well, but the secure transport may have to be registered using -the `nng_wss_register` function. (Note that this function will not be -present if TLS support was not enabled in the library.) - -=== 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`. - -Secure WebSockets (if enabled) use the scheme `wss://`, and the default -TCP port number of 443. Otherwise the format is the same as for regular -WebSockets. - -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. - -To listen to all ports on the system, the host name may be elided from -the URL on the listener. This will wind up listening to all interfaces -on the system, with possible caveats for IPv4 and IPv6 depending on what -the underlying system supports. (On most modern systems it will map to the -special IPv6 address `::`, and both IPv4 and IPv6 connections will be -permitted, with IPv4 addresses mapped to IPv6 addresses.) - -=== 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). - -=== Server Instances - -This transport makes use of shared HTTP server instances, permitting multiple -sockets or listeners to be configured with the same hostname and port. When -creating a new listener, it is registered with an existing HTTP server instance -if one can be found. Note that the matching algorithm is somewhat simple, -using only a string based hostname or IP address and port to match. Therefore -it is recommended to use only IP addresses or the empty string as the hostname -in listener URLs. - -Likewise, when sharing a server instance, it may not be possible to alter -TLS configuration if the server is already running, as there is only a single -TLS configuration context for the entire server instance. - -All sharing of server instances is only typically possible within the same -process. - -The server may also be used by other things (for example to serve static -content), in the same process. - -=== Transport Options - -The following transport options are available. Note that -setting these must be done before the transport is started. - -NOTE: The TLS specific options (beginning with `NNG_OPT_TLS_`) are -only available for `wss://` endpoints. - -`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. - -`NNG_OPT_TLS_CONFIG`:: - -This option is used on an endpoint to access the underlying TLS -configuration object. The value is of type `nng_tls_config *`. - -TIP: Use this option when advanced TLS configuration is required. - -`NNG_OPT_TLS_CA_FILE`:: - -This is a write-only option used to load certificates associated -associated private key from a file. -See <<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>> for more -information. - -`NNG_OPT_TLS_CERT_KEY_FILE`:: - -This is a write-only option used to load the local certificate and -associated private key from a file. The private key used must be -unencrypted. (Use the `NNG_OPT_TLS_CONFIG` option to access the underlying -TLS configuration if more advanced configuration is needed.) -See <<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>> for more -information. - -`NNG_OPT_TLS_AUTH_MODE`:: - -This is a write-only option used to configure the authentication mode -used. It can take an integer with value `NNG_TLS_AUTH_MODE_NONE`, -`NNG_TLS_AUTH_MODE_REQUIRED`, or `NNG_TLS_AUTH_MODE_OPTIONAL`. See -<<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>> for more details. - -`NNG_OPT_TLS_VERIFIED`:: - -This is a read-only option which returns a boolean value (integer 0 or 1). -It will true (1) if the remote peer has been properly verified using TLS -authentication, or false (0) otherwise. This option may return incorrect -results if peer authentication is disabled with `NNG_TLS_AUTH_MODE_NONE`. - -// 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 - -<<nng#,nng(7)>>, -<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>> |