Ubuntu Manpage: nng - nanomsg next generation

NAME

       nng - nanomsg next generation

SYNOPSIS

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

DESCRIPTION

NNG 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.

NNG is designed to permit easy creation of new transports and, to a lesser extent, new
protocols.

NNG is wire compatible with the SP protocols described in the nanomsg project; projects
using libnanomsg <https://github.com/nanomsg/nanomsg> can inter-operate with nng as well
as other conforming implementations. (One such implementation is mangos
<https://github.com/go-mangos/mangos>.) Applications using NNG which wish to communicate
with other libraries must ensure that they only use protocols or transports offered by the
other library.

NNG 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.

NNG is implemented in pure C; if you need bindings for other languages please check the
website <http://nanomsg.org/>.

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_socket(7)
BSD socket 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 protocol.

Each socket can be used to send and receive messages (if the protocol) supports it, and
implements the appropriate protocol semantics. For example, sub 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 req 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 accept 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 operating system 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.

Raw Mode
Most applications will use sockets in normal, or cooked, mode. This mode provides the full
semantics of the protocol. For example, req sockets will automatically match a reply to a
request, and resend requests periodically if no reply was received.

There are situations, such as with proxies, where it is desirable to bypass these
semantics and simply pass messages to and from the socket with no extra semantic handling.
This is possible using raw mode sockets.

Raw mode sockets are generally constructed with a different function, such as
nng_req0_open_raw(). Using these sockets, the application can simply send and receive
messages, and is responsible for supplying any additional socket semantics. Typically this
means that the application will need to inspect message headers on incoming messages, and
supply them on outgoing messages.

Tip
The nng_device() function only works with raw mode sockets, but as it only forwards
the messages, no additional application processing is needed.

URLs
NNG uses universal resource locators (URLs) following the format specified in RFC 3986
<https://tools.ietf.org/html/rfc3986>, 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 <https://tools.ietf.org/html/rfc3986#section-6.2.2>:

1. The URL is parsed into scheme, userinfo, host, port, path, query and fragment
components. (Not all of these members are necessarily present.)

2. The scheme, hostname, and port if present, are converted to lower case.

3. Percent-encoded values for unreserved characters
<https://tools.ietf.org/html/rfc3986#section-2.3> converted to their unencoded forms.

4. Additionally URL percent-encoded values for characters in the path and with numeric
values larger than 127 (i.e. not ASCII) are decoded.

5. 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.

6. Path segments consisting of . and .. are resolved as per RFC 3986 6.2.2.3
<https://tools.ietf.org/html/rfc3986#section-6.2.2.3>.

7. 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 applications, without violating RFC 3986
itself.

Tip
Port numbers may be service names in some instances, but it is recommended that
numeric port numbers be used when known. If service names are used, it is recommended
that they follow the naming conventions for C identifiers, and not be longer than 32
characters in length. This will maximize compatibility across systems and minimize
opportunities for confusion when they are parsed on different systems.

API
The library API is documented at libnng(3).

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO