nats-server(the NATS server) through a regular TCP/IP socket using a small set of protocol operations that are terminated by a new line.
0x0D0A) to terminate protocol messages. This newline sequence is also used to mark the end of the message payload in a
FOO.BAR.BAZare all valid subject names
foo..barare not valid subject names
*) matches a single token at any level of the subject.
>), also known as the full wildcard, matches one or more tokens at the tail of a subject, and must be the last token. The wildcarded subject
foo.bar.baz.1, but not
foo.>are syntactically valid;
foo.bar.quux, but only the latter matches
foo.bar.baz. With the full wildcard, it is also possible to express interest in every subject that may exist in NATS:
sub > 1, limited of course by authorization settings.
SUB foo 1and
sub foo 1are equivalent.
INFOmessages can be sent anytime by the server. This means clients with that protocol level need to be able to asynchronously handle
server_id: The unique identifier of the NATS server
version: The version of the NATS server
go: The version of golang the NATS server was built with
host: The IP address used to start the NATS server, by default this will be
0.0.0.0and can be configured with
port: The port number the NATS server is configured to listen on
max_payload: Maximum payload size, in bytes, that the server will accept from the client.
proto: An integer indicating the protocol version of the server. The server version 1.2.0 sets this to
1to indicate that it supports the "Echo" feature.
client_id: An optional unsigned integer (64 bits) representing the internal client identifier in the server. This can be used to filter client connections in monitoring, correlate with error logs, etc...
auth_required: If this is set, then the client should try to authenticate upon connect.
tls_required: If this is set, then the client must perform the TLS/1.2 handshake. Note, this used to be
ssl_requiredand has been updated along with the protocol from SSL to TLS.
tls_verify: If this is set, the client must provide a valid certificate during the TLS handshake.
connect_urls: An optional list of server urls that a client can connect to.
ldm: If the server supports Lame Duck Mode notifications, and the current server has transitioned to lame duck,
ldmwill be set to
connect_urlsfield is a list of urls the server may send when a client first connects, and when there are changes to server cluster topology. This field is considered optional, and may be omitted based on server configuration and client protocol level.
INFOmessage is sent to the client with an updated
connect_urlslist. This cloud-friendly feature asynchronously notifies a client of known servers, allowing it to connect to servers not originally configured.
connect_urlswill contain a list of strings with an IP and port, looking like this:
CONNECTmessage is the client version of the
INFOmessage. Once the client has established a TCP/IP socket connection with the NATS server, and an
INFOmessage has been received from the server, the client may send a
CONNECTmessage to the NATS server to provide more information about the current connection as well as security information.
pedantic: Turns on additional strict format checking, e.g. for properly formed subjects
tls_required: Indicates whether the client requires an SSL connection.
auth_token: Client authorization token (if
user: Connection username (if
pass: Connection password (if
name: Optional client name
lang: The implementation language of the client.
version: The version of the client.
protocol: optional int. Sending
0(or absent) indicates client supports original protocol. Sending
1indicates that the client supports dynamic reconfiguration of cluster topology changes by asynchronously receiving
INFOmessages with known servers it can reconnect to.
echo: Optional boolean. If set to
true, the server (version 1.2.0+) will not send originating messages from this connection to its own subscriptions. Clients should set this to
trueonly for server supporting this feature, which is when
INFOprotocol is set to at least
sig: In case the server has responded with a
INFO, then a NATS client must use this field to reply with the signed
jwt: The JWT that identifies a user permissions and acccount.
PUBmessage publishes the message payload to the given subject name, optionally supplying a reply subject. If a reply subject is supplied, it will be delivered to eligible subscribers along with the supplied payload. Note that the payload itself is optional. To omit the payload, set the payload size to 0, but the second CRLF is still required.
PUB <subject> [reply-to] <#bytes>\r\n[payload]
subject: The destination subject to publish to
reply-to: The optional reply inbox subject that subscribers can use to send a response back to the publisher/requestor
#bytes: The payload size in bytes
payload: The message payload data
PUB FOO 11\r\nHello NATS!
PUB FRONT.DOOR INBOX.22 11\r\nKnock Knock
PUB NOTIFY 0\r\n
SUBinitiates a subscription to a subject, optionally joining a distributed queue group.
SUB <subject> [queue group] <sid>
subject: The subject name to subscribe to
queue group: If specified, the subscriber will join this queue group
sid: A unique alphanumeric subscription ID, generated by the client
FOOwith the connection-unique subscription identifier (sid)
SUB FOO 1
BARas part of distribution queue group
SUB BAR G1 44
UNSUBunsubscribes the connection from the specified subject, or auto-unsubscribes after the specified number of messages has been received.
UNSUB <sid> [max_msgs]
sid: The unique alphanumeric subscription ID of the subject to unsubscribe from
max_msgs: An optional number of messages to wait for before automatically unsubscribing
FOOwhich has been assigned sid
1. To unsubscribe from
FOOafter 5 messages have been received:
UNSUB 1 5
MSGprotocol message is used to deliver an application message to the client.
MSG <subject> <sid> [reply-to] <#bytes>\r\n[payload]
subject: Subject name this message was received on
sid: The unique alphanumeric subscription ID of the subject
reply-to: The inbox subject on which the publisher is listening for responses
#bytes: Size of the payload in bytes
payload: The message payload data
MSG FOO.BAR 9 11\r\nHello World
MSG FOO.BAR 9 INBOX.34 11\r\nHello World
PONGimplement a simple keep-alive mechanism between client and server. Once a client establishes a connection to the NATS server, the server will continuously send
PINGmessages to the client at a configurable interval. If the client fails to respond with a
PONGmessage within the configured response interval, the server will terminate its connection. If your connection stays idle for too long, it is cut off.
verboseconnection option is set to
true(the default value), the server acknowledges each well-formed protocol message from the client with a
+OKmessage. Most NATS clients set the
-ERRmessage is used by the server indicate a protocol, authorization, or other runtime connection error to the client. Most of these errors result in the server closing the connection.
-ERR <error message>
-ERR 'Unknown Protocol Operation': Unknown protocol error
-ERR 'Attempted To Connect To Route Port': Client attempted to connect to a route port instead of the client port
-ERR 'Authorization Timeout': Client took too long to authenticate to the server after establishing a connection (default 1 second)
-ERR 'Maximum Control Line Exceeded': Message destination subject and reply subject length exceeded the maximum control line value specified by the
max_control_lineserver option. The default is 1024 bytes.
-ERR 'Parser Error': Cannot parse the protocol message sent by the client
-ERR 'Secure Connection - TLS Required': The server requires TLS and the client does not have TLS enabled.
-ERR 'Stale Connection': The server hasn't received a message from the client, including a
PONGin too long.
-ERR 'Maximum Connections Exceeded': This error is sent by the server when creating a new connection and the server has exceeded the maximum number of connections specified by the
max_connectionsserver option. The default is 64k.
-ERR 'Slow Consumer': The server pending data size for the connection has reached the maximum size (default 10MB).
-ERR 'Maximum Payload Violation': Client attempted to publish a message with a payload size that exceeds the
max_payloadsize configured on the server. This value is supplied to the client upon connection in the initial
INFOmessage. The client is expected to do proper accounting of byte size to be sent to the server in order to handle this error synchronously.
-ERR 'Invalid Subject': Client sent a malformed subject (e.g.
sub foo. 90)