nats.h File Reference

The NATS client protocol (PROTOCORE_ENABLE_NATS): the client-to-server operations a device writes, and the server-to-client operations it reads. More...

#include "protocore_config.h"

Go to the source code of this file.

Detailed Description

The NATS client protocol (PROTOCORE_ENABLE_NATS): the client-to-server operations a device writes, and the server-to-client operations it reads.

NATS is not an IETF protocol and no RFC governs it. The specification followed here is the NATS project's client protocol reference, "NATS Protocol" (docs.nats.io, Reference > Protocols > Client), whose Overview and one section per operation - INFO, CONNECT, PUB, HPUB, SUB, UNSUB, MSG, HMSG, PING/PONG, +OK/ERR - carry the syntax written below. The wire conventions come from that document's "Protocol conventions" section, kept in the nats-io/nats.docs repository at docs/nats_protocol/nats-protocol.html.

Protocol conventions: a space or a tab delimits the fields of a protocol message and repeated whitespace counts as one delimiter; CR LF terminates every protocol message and ends a PUB or MSG payload; subject names, reply subject (INBOX) names included, are case-sensitive, non-empty alphanumeric strings with no embedded whitespace, optionally token-delimited by the dot.

The operations, as the reference writes them:

CONNECT {"option_name":option_value,...}<CRLF>
PUB   <subject> [reply-to] <#bytes><CRLF>[payload]<CRLF>
HPUB  <subject> [reply-to] <#header bytes> <#total bytes><CRLF>[headers]<CRLF><CRLF>[payload]<CRLF>
SUB   <subject> [queue group] <sid><CRLF>
UNSUB <sid> [max_msgs]<CRLF>
PING<CRLF>
PONG<CRLF>
INFO  {"option_name":option_value,...}<CRLF>
MSG   <subject> <sid> [reply-to] <#bytes><CRLF>[payload]<CRLF>
HMSG  <subject> <sid> [reply-to] <#header bytes> <#total bytes><CRLF>[headers]<CRLF><CRLF>[payload]<CRLF>
+OK<CRLF>
-ERR <error message><CRLF>

#header bytes counts the header section including its terminating CR LF CR LF, and #total bytes counts that section plus the payload, so an HPUB takes the whole section as one span.

The Overview states operation names are case insensitive. The parser here matches them in the upper case a server writes.

A builder writes one operation into the caller's buffer and reports its length; the parser decodes the operation at the head of the caller's inbound buffer and reports the octets it occupies. Pure: no state, no allocation, no I/O.

The module exports one symbol, Nats. Everything in nats.c has internal linkage.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file nats.h.