NATS uses cookies to ensure you get the best experience on our website. Continuing to use this site assumes compliance with our Privacy Policy.
Edit on GitHub

Connection Options

The NATS client libraries offer a range of options for controlling how connections operate. Some of these are language dependent while some are library/version dependent. Please see the documentation for the client library your application uses for a full list of options. This page presents some options commonly used and options related to NATS internals that are important to understand.

Setting the Connection Name

Connections can be assigned a name which will appear in some of the server monitoring data. This name is not required but can help in debugging and testing.

// Set a connection name
nc, err := nats.Connect("demo.nats.io", nats.Name("my-connection"))
if err != nil {
	log.Fatal(err)
}
defer nc.Close()

// Do something with the connection

Options options = new Options.Builder().
                            server("nats://demo.nats.io:4222").
                            connectionName("my-connection"). // Set a connection name
                            build();
Connection nc = Nats.connect(options);

// Do something with the connection

nc.close();
let nc = NATS.connect({
    url: "nats://demo.nats.io:4222",
    name: "my-connection"
});

nc = NATS()

await nc.connect(servers=["nats://demo.nats.io:4222"], name="my-connection")

# Do something with the connection.

require 'nats/client'

NATS.start(servers:["nats://demo.nats.io:4222"], name: "my-connection") do |nc|
   nc.on_reconnect do
    puts "Got reconnected to #{nc.connected_server}"
  end

  nc.on_disconnect do |reason|
    puts "Got disconnected! #{reason}"
  end

  nc.close
end
// will throw an exception if connection fails
let nc = await connect({
    url: "nats://demo.nats.io:4222",
    name: "my-connection"
});

nc.close();

Ping/Pong

The client and server use a simple PING/PONG protocol to check that they are both still connected. The client will ping the server on a regular, configured interval so that the server usually doesn’t have to initiate the PING/PONG interaction.

digraph g { rankdir=LR client [shape=box, style="rounded", label="NATS Client"]; gnatsd [shape=circle, label="gnatsd"]; client -> gnatsd [label="PING"]; gnatsd -> client [label="PONG"]; }

Set the Ping Interval

If you have a connection that is going to be open a long time with few messages traveling on it, setting this PING interval can control how quickly the client will be notified of a problem. However on connections with a lot of traffic, the client will often figure out there is a problem between PINGS, and as a result the default PING interval is often on the order of minutes. To set the interval to 20s:

// Set Ping Interval to 20 seconds
nc, err := nats.Connect("demo.nats.io", nats.PingInterval(20*time.Second))
if err != nil {
	log.Fatal(err)
}
defer nc.Close()

// Do something with the connection

Options options = new Options.Builder().
                            server("nats://demo.nats.io:4222").
                            pingInterval(Duration.ofSeconds(20)). // Set Ping Interval
                            build();
Connection nc = Nats.connect(options);

// Do something with the connection

nc.close();
let nc = NATS.connect({
    pingInterval: 20*2000, //20s
    url: "nats://demo.nats.io:4222"
});
nc = NATS()

await nc.connect(
   servers=["nats://demo.nats.io:4222"],
   # Set Ping Interval to 20 seconds
   ping_interval=20,
   )

# Do something with the connection.

require 'nats/client'

NATS.start(ping_interval: 20) do |nc|
   nc.on_reconnect do
    puts "Got reconnected to #{nc.connected_server}"
  end

  nc.on_disconnect do |reason|
    puts "Got disconnected! #{reason}"
  end

  # Do something with the connection
end
// will throw an exception if connection fails
let nc = await connect({
    pingInterval: 20*2000, //20s
    url: "nats://demo.nats.io:4222"
});
nc.close();

Limit Outgoing Pings

The PING/PONG interaction is also used by most of the clients as a way to flush the connection to the server. Clients that cache outgoing messages provide a flush call that will run a PING/PONG. The flush will wait for the PONG to return, telling it that all cached messages have been processed, including the PING. The number of cached PING requests can be limited in most clients to insure that traffic problems are identified early. This configuration for max outgoing pings or similar will usually default to a small number and should only be increased if you are worried about fast flush traffic, perhaps in multiple threads.

For example, to set the maximum number of outgoing pings to 5:

opts := nats.GetDefaultOptions()
opts.Url = "demo.nats.io"
// Set maximum number of PINGs out without getting a PONG back
// before the connection will be disconnected as a stale connection.
opts.MaxPingsOut = 5

nc, err := opts.Connect()
if err != nil {
	log.Fatal(err)
}
defer nc.Close()

// Do something with the connection

Options options = new Options.Builder().
                            server("nats://demo.nats.io:4222").
                            maxPingsOut(5). // Set max pings in flight
                            build();
Connection nc = Nats.connect(options);

// Do something with the connection

nc.close();
let nc = NATS.connect({
    maxPingOut: 5,
    url: "nats://demo.nats.io:4222"
});
nc = NATS()

await nc.connect(
   servers=["nats://demo.nats.io:4222"],
   # Set maximum number of PINGs out without getting a PONG back
   # before the connection will be disconnected as a stale connection.
   max_outstanding_pings=5,
   ping_interval=1,
   )

# Do something with the connection.

require 'nats/client'

NATS.start(max_outstanding_pings: 5) do |nc|
   nc.on_reconnect do
    puts "Got reconnected to #{nc.connected_server}"
  end

  nc.on_disconnect do |reason|
    puts "Got disconnected! #{reason}"
  end

  # Do something with the connection
end
// will throw an exception if connection fails
let nc = await connect({
    maxPingOut: 5,
    url: "nats://demo.nats.io:4222"
});
nc.close();

Controlling the Client/Server Protocol

The protocol between the client and the server is fairly simple and relies on a control line and sometimes a body. The control line contains the operations being sent, like PING or PONG, followed by a carriage return and line feed, CRLF or “\r\n”. The server has a setting that can limit the maximum size of a control line. For PING and PONG this doesn’t come into play, but for messages that contain subject names, the control line length can be important. The server is also configured with a maximum payload size, which limits the size of a message body. The server sends the maximum payload size to the client at connect time but doesn’t currently tell the client the maximum control line size.

Set the Maximum Control Line Size

Some clients will try to limit the control line size on themselves to prevent an error from the server. These clients may or may not allow you to set the size being used, but if they do, the size should be set to match the server configuration.

For example, to set the maximum control line size to 2k:

// This does not apply to the NATS Go Client
Options options = new Options.Builder().
                            server("nats://demo.nats.io:4222").
                            maxControlLine(2 * 1024). // Set the max control line to 2k
                            build();
Connection nc = Nats.connect(options);

// Do something with the connection

nc.close();
// set this option before creating a connection
NATS.MAX_CONTROL_LINE_SIZE = 1024*2;
let nc = NATS.connect({
    url: "nats://demo.nats.io:4222"
});

# Asyncio NATS client does not allow custom control lines
# There is no need to customize this in the Ruby NATS client.
// control line size is not configurable on ts-nats

Get the Maximum Payload Size

While the client can’t control the maximum payload size, clients may provide a way for applications to get the size after the connection is made. This will allow the application to chunk or limit data as needed to pass through the server.

nc, err := nats.Connect("demo.nats.io")
if err != nil {
	log.Fatal(err)
}
defer nc.Close()

mp := nc.MaxPayload()
log.Printf("Maximum payload is %v bytes", mp)

// Do something with the max payload

Connection nc = Nats.connect("nats://demo.nats.io:4222");

long max = nc.getMaxPayload();
// Do something with the max payload

nc.close();
let nc = NATS.connect("nats://demo.nats.io:4222");

// on node you *must* register an error listener. If not registered
// the library emits an 'error' event, the node process will exit.
nc.on('error', (err) => {
    t.log('client got an error:', err);
});
nc.on('connect', () => {
   t.log(nc.info.max_payload);
});
nc = NATS()

await nc.connect(servers=["nats://demo.nats.io:4222"])

print("Maximum payload is %d bytes" % nc.max_payload)

# Do something with the max payload.

require 'nats/client'

NATS.start(max_outstanding_pings: 5) do |nc|
   nc.on_reconnect do
    puts "Got reconnected to #{nc.connected_server}"
  end

  nc.on_disconnect do |reason|
    puts "Got disconnected! #{reason}"
  end

  # Do something with the max_payload
  puts "Maximum Payload is #{nc.server_info[:max_payload]} bytes"
end
// connect will happen once - the first connect
nc.on('connect', (nc: Client, url: string, options: ServerInfo) => {
    // nc is the connection that connected
    t.log('client connected to', url);
    t.log('max_payload', options.max_payload);
});

Turning Off Echo’d Messages

By default the server will echo messages. This means that if a publisher on a connection sends a message to a subject any subscribers on that same connection may receive the message. Turning off echo is a fairly new feature for the NATS server, but some of the clients already support it.

digraph { rankdir=LR; subgraph cluster_1 { shape=box; style="rounded"; label = "Connection #1"; publisher [shape=box, style="rounded", label="Publisher"]; subscriber_1 [shape=box, style="rounded", label="Subscriber"]; } subgraph cluster_2 { shape=box; style="rounded"; label = "Connection #2"; subscriber_2 [shape=box, style="rounded", label="Subscriber"]; } subject [shape=circle, label="Subject"]; publisher -> subject [label="msg"]; subject -> subscriber_1 [label="echo'd msg", style="dashed"]; subject -> subscriber_2 [label="msg"]; }

Keep in mind that each connection will have to turn off echo, and that it is per connection, not per application. Also, turning echo on and off can result in a major change to your applications communications protocol since messages will flow or stop flowing based on this setting and the subscribing code won’t have any indication as to why.

// Turn off echo
nc, err := nats.Connect("demo.nats.io", nats.NoEcho())
if err != nil {
	log.Fatal(err)
}
defer nc.Close()

// Do something with the connection

Options options = new Options.Builder().
                            server("nats://demo.nats.io:4222").
                            noEcho(). // Turn off echo
                            build();
Connection nc = Nats.connect(options);

// Do something with the connection

nc.close();
// no_echo is not supported.
ncA = NATS()
ncB = NATS()

await ncA.connect(no_echo=True)
await ncB.connect()

async def handler(msg):
   # Messages sent by `ncA' will not be received.
   print("[Received] ", msg)

await ncA.subscribe("greetings", cb=handler)
await ncA.flush()
await ncA.publish("greetings", b'Hello World!')
await ncB.publish("greetings", b'Hello World!')

# Do something with the connection

await asyncio.sleep(1)
await ncA.drain()
await ncB.drain()

NATS.start("nats://demo.nats.io:4222", no_echo: true) do |nc|
  # ...
end
let nc = await connect({
    url: "nats://demo.nats.io:4222", noEcho: true});

Turn On Pedantic Mode

The NATS server provides a pedantic mode that does extra checks on the protocol. By default, this setting is off but you can turn it on:

opts := nats.GetDefaultOptions()
opts.Url = "demo.nats.io"
// Turn on Pedantic
opts.Pedantic = true
nc, err := opts.Connect()
if err != nil {
	log.Fatal(err)
}
defer nc.Close()

// Do something with the connection

Options options = new Options.Builder().
                            server("nats://demo.nats.io:4222").
                            pedantic(). // Turn on pedantic
                            build();
Connection nc = Nats.connect(options);

// Do something with the connection

nc.close();
let nc = NATS.connect({
    url: "nats://demo.nats.io:4222",
    pedantic: true
});

nc = NATS()

await nc.connect(servers=["nats://demo.nats.io:4222"], pedantic=True)

# Do something with the connection.

require 'nats/client'

NATS.start(pedantic: true) do |nc|
   nc.on_reconnect do
    puts "Got reconnected to #{nc.connected_server}"
  end

  nc.on_disconnect do |reason|
    puts "Got disconnected! #{reason}"
  end

  nc.close
end
// will throw an exception if connection fails
let nc = await connect({
    url: "nats://demo.nats.io:4222",
    pedantic: true
});

nc.close();

Turn On/Off Verbose Mode

The NATS server also provide a verbose mode. By default, verbose mode is enabled and the server will reply to every message from the client with either a +OK or a -ERR. Most clients turn off verbose mode, which disables all of the +OK traffic. Errors are rarely subject to verbose mode and client libraries handle them as documented. To turn on verbose mode, likely for testing:

opts := nats.GetDefaultOptions()
opts.Url = "demo.nats.io"
// Turn on Verbose
opts.Verbose = true
nc, err := opts.Connect()
if err != nil {
	log.Fatal(err)
}
defer nc.Close()

// Do something with the connection

Options options = new Options.Builder().
                            server("nats://demo.nats.io:4222").
                            verbose(). // Turn on verbose
                            build();
Connection nc = Nats.connect(options);

// Do something with the connection

nc.close();
let nc = NATS.connect({
    url: "nats://demo.nats.io:4222",
    verbose: true
});

nc = NATS()

await nc.connect(servers=["nats://demo.nats.io:4222"], verbose=True)

# Do something with the connection.

require 'nats/client'

NATS.start(verbose: true) do |nc|
   nc.on_reconnect do
    puts "Got reconnected to #{nc.connected_server}"
  end

  nc.on_disconnect do |reason|
    puts "Got disconnected! #{reason}"
  end

  nc.close
end
// will throw an exception if connection fails
let nc = await connect({
    url: "nats://demo.nats.io:4222",
    verbose: true
});

nc.close();