NATS

NATS is a lightweight publish and subscribe messaging system. It can serve as the coordinator of a cluster in two situations: when coordination traffic should run on a dedicated messaging service, and when NATS is already operated. NATS support is included in the official binaries. Stalwart uses only core NATS publish and subscribe, so JetStream, the persistence layer of NATS, is not required.

Choosing NATS for coordination does not remove the need for Redis. A cluster coordinated through NATS still requires a Redis-based in-memory store, which must be configured before the coordinator, as described in Coordination mechanism.

Configuration

NATS coordination is selected with the Nats variant of the Coordinator object (found in the WebUI under Settings › Cluster › Coordinator).

hosts lists the NATS servers as host:port pairs. Listing several servers of a NATS cluster allows the client to fail over between them. useTls enables TLS, and allowInvalidCerts accepts an invalid server certificate.

NATS servers accept two kinds of credential, and either can be configured. The first is a user name and password, in authUsername and authSecret. The second is a JWT credentials string, in credentials, which can be read from a NATS credentials file. Each secret can be given as a value, read from an environment variable or read from a file, and None disables it.

The remaining fields control the connection, and they rarely need to change:

• connectTimeout and requestTimeout limit connection establishment and requests.
• pingInterval sets how often the client checks the connection, and maxReconnects limits the reconnection attempts after the connection is lost. When it is unset, the client keeps reconnecting.
• noEcho stops a node from receiving the notifications it published itself.
• clientCapacity, subscriptionCapacity and readBufferCapacity size the client’s internal buffers. A subscription whose buffer fills is treated by NATS as a slow consumer, and messages are dropped.

The following coordinator connects to a two-server NATS cluster, with a password read from an environment variable:

{
  "@type": "Nats",
  "hosts": {"nats1.example.com:4222": true, "nats2.example.com:4222": true},
  "authUsername": "stalwart",
  "authSecret": {"@type": "EnvironmentVariable", "variableName": "NATS_PASSWORD"},
  "credentials": {"@type": "None"}
}