nng(7)

SYNOPSIS

cc ['flags'] 'files' -lnng ['libraries']

DESCRIPTION

The nng library provides a common messaging framework intended to +solve common communication problems in distributed applications. +It offers a number of protocols, and also a number of transports.

The protocols implement the semantics associated with particular +communications scenarios, such as RPC style services, service discovery, +publish/subscribe, and so forth.

The transports provide support for underlying transport methods, such +as TCP, IPC, websockets, and so forth.

The nng library is designed to permit easy creation of new transports and, +to a lesser extent, new protocols.

The nng library is wire compatible with the SP protocols described in +the nanomsg project; projects using +libnanomsg can inter-operate with +nng as well as other conforming implementations. (One such implementation +is mangos.) Applications using nng +which wish to communicate with older libraries must ensure that they only +use protocols or transports offered by the earlier library.

The nng library also offers a compatible API, permitting legacy code to +be recompiled or relinked against nng. When doing this, support for +certain enhancements or features will likely be absent, requiring the +application developer to use the new-style API.

The nng library is implemented in pure C; if you need bindings for +other languages please check the website.

Protocols

+
nng_bus(7) - Bus protocol
+
+
nng_pair(7) - Pair protocol
+
+
nng_pub(7) - Publisher side of publish/subscribe protocol
+
+
nng_pull(7) - Pull side of pipeline protocol
+
+
nng_push(7) - Push side of pipeline protocol
+
+
nng_sub(7) - Subscriber side of publish/subscribe protocol
+
+
nng_rep(7) - Reply side of request/reply protocol
+
+
nng_req(7) - Request side of request/reply protocol
+
+
nng_respondent(7) - Respondent side of survey protocol
+
+
nng_surveyor(7) - Surveyor side of survey protocol
+

Transports

+
nng_inproc(7) - Intra-process transport
+
+
nng_ipc(7) - Inter-process transport
+
+
nng_tls(7) - TLSv1.2 over TCP transport
+
+
nng_tcp(7) - TCP (and TCPv6) transport
+
+
nng_ws(7) - WebSocket transport
+
+
nng_zerotier(7) - ZeroTier transport
+

Conceptual Overview

nng presents a socket view of networking. The sockets are constructed +using protocol-specific functions, as a given socket implements precisely +one nng protocol.

Each socket can be used to send and receive messages (if the protocol) +supports it, and implements the appropriate protocol semantics. For +example, nng_sub(7) sockets automatically filter incoming +messages to discard those for topics that have not been subscribed.

nng sockets are message oriented, so that messages are either delivered +wholly, or not at all. Partial delivery is not possible. Furthermore, +nng does not provide any other delivery or ordering guarantees; +messages may be dropped or reordered. (Some protocols, such as +nng_req(7) may offer stronger guarantees by +performing their own retry and validation schemes.)

Each socket can have zero, one, or many "endpoints", which are either +listeners or dialers. (A given socket may freely choose whether it uses +listeners, dialers, or both.) These "endpoints" provide access to +underlying transports, such as TCP, etc.

Each endpoint is associated with a URL, which is a service address. For +dialers, this will be the service address that will be contacted, whereas +for listeners this is where the listener will bind and watch for new +connections.

Endpoints do not themselves transport data. They are instead responsible +for the creation of pipes, which can be thought of as message-oriented, +connected, streams. Pipes frequently correspond to a single underlying +byte stream — for example both IPC and TCP transports implement their +pipes using a 1:1 relationship with a connected socket.

Endpoints create pipes as needed. Listeners will create them when a new +client connection request arrives, and dialers will generally create one, +then wait for it to disconnect before reconnecting.

Most applications should not have to worry about endpoints or pipes at +all; the socket abstraction should provide all the functionality needed +other than in a few specific circumstances.

URLs

+The nng library uses universal resource locators (URLs) +following the format specified in +RFC 3986, +including some schemes that are unique +to SP. + +The URLs used in nng are canonicalized as follows, mostly in +accordance with +RFC 3986 6.2.2:

+
The URL is parsed into scheme, userinfo, host, port, path, query and +fragment components. (Not all of these members are necessarily present.)
+
+
The scheme, hostname, and port if present, are converted to lower case.
+
+
Percent-encoded values for +unreserved characters +converted to their unencoded forms.
+
+
Additionally URL percent-encoded values for characters in the path +and with numeric values larger than 127 (i.e. not ASCII) are decoded.
+
+
The resulting path is checked for invalid UTF-8 sequences, consisting +of surrogate pairs, illegal byte sequences, or overlong encodings. +If this check fails, then the entire URL is considered invalid.
+
+
Path segments consisting of . and .. are resolved as per +RFC 3986 6.2.2.3.
+
+
Further, empty path segments are removed, meaning that duplicate +slash (/) separators are removed from the path.
+

Note that steps 4, 5, and 7 are not specified by RFC 3986, but performing +them is believed to improve both the usability and security of nng +applications, without violating RFC 3986 itself.

API

The library API is documented at libnng(3).

nng(7) Manual Page

NAME