NN_WS(7)

📦
version 1.2.2 · 5 versions
, in fedora 44

✨ NN_WS(7) ✨ — the WebSocket transport, bestie edition 🦋

okay so first things first: this is the manual for nn_ws, the WebSocket transport mechanism from nanomsg 1.2.2, and I'm gonna walk you through it like we're texting at 2am 💅 no gatekeeping, only facts.

🌸 SYNOPSIS 🌸

#include <nanomsg/nn.h>

#include <nanomsg/ws.h>

that's it. two includes. go off, queen 👑

💖 DESCRIPTION 💖

so the WebSocket transport ships your messages using the framing protocol from RFC 6455 ✨ The initial handshake happens with HTTP headers, and the Sec-Websocket-Protocol header gets set to the SP protocol that the server is using. Like, for example? A REQ client will send rep.sp.nanomsg.org. slay.

Every single SP message travels inside one WebSocket frame, with no extra data or headers piled on top. By default this library sends binary frames and expects to receive binary frames. lowkey simple, highkey powerful 🫶

When you call nn_bind() or nn_connect(), if you omit the port it defaults to the RFC 6455 default port 80 for HTTP. So:

ws://127.0.0.1 is equivalent to ws://127.0.0.1:80

💀 not me having to be the one to say it: WebSocket over TLS is not supported by this library, at this time. periodt.

🎀 URI limitations 🎀

When you're calling nn_connect(), the URI can optionally also include the path to a resource and/or query parameters. cute right?

Example 1. Path and query parameters

s1 = nn_socket (AF_SP, NN_PAIR);
nn_connect (s1, "ws://example.com/path?query=value");

This implementation includes the full path and any query parameters in the HTTP handshake when establishing connections with nn_connect(). However, that info is not available via the nanomsg API afterwards. it's giving "you can send it but you can't read it back" 🙈

Likewise, this implementation does not examine or use either any path or query parameters that may be supplied to nn_bind(), because it only binds to the TCP port. Basically it's acting as a limited HTTP server that offers SP over WebSocket at all URIs for the given TCP address.

Applications, though, should not depend on this behavior — intervening infrastructure may proxy, filter or route based on URI, and other implementations of the SP over WebSocket protocol may offer other HTTP services at the same TCP port, using the path, the query parameters, or both to figure out which service is being requested. so like, don't get comfy 😭

👑 Socket Options 👑

  • NN_WS_MSG_TYPE — you can set this option to NN_WS_MSG_TYPE_TEXT or NN_WS_MSG_TYPE_BINARY. Its value decides whether data messages get sent as WebSocket text frames or binary frames, per RFC 6455. Text frames should only contain valid UTF-8 text in their payload, or they will be rejected. Binary frames may contain any data. Not all WebSocket implementations support binary frames. The default is to send binary frames. 🦋

This option may also be specified as control data when when sending a message with nn_sendmsg().

🧚 TODO: NN_TCP_NODELAY 🧚

  • NN_TCP_NODELAY — when set to 1, this disables Nagle's algorithm. It also disables delaying of TCP acknowledgments. Using this option improves latency at the expense of throughput. Type of this option is int. Default value is 0.

⭐ EXAMPLE ⭐

nn_bind (s1, "ws://*:5555");
nn_connect (s2, "ws://myserver:5555");

look at you, binding and connecting like a main character 💅

🌈 SEE ALSO 🌈

💜 AUTHORS 💜

  • Martin Sustrik <sustrik@250bpm.com>
  • Jack R. Dunaway <jack@wirebirdlabs.com>
  • Garrett D'Amore <garrett@damore.org>

and that's the whole page bestie!! 🎀 this one's from nanomsg 1.2.2, dated 2026-01-16 — shoutout to the authors for real, they ate and left no crumbs 👑✨ k bye, go build something iconic 💖

📦 where this page comes from