nats

A client for NATS: publish, subscribe (plain and queue groups), headers, request/reply, flush and drain, keepalive, and automatic reconnection with resubscription. It covers core NATS, not JetStream.

import "nats";

let r = nats.connect("nats://127.0.0.1:4222", deadline);
guard let nc = r else let e = err_of(r) { panic(e); }

let sr = nats.subscribe(nc, "orders.*");                  // or queue_subscribe(nc, subj, "workers")
guard let sub = sr else let e = err_of(sr) { panic(e); }
nats.publish(nc, "orders.new", b"{\"id\":1}");
let m = nats.next_msg(sub, deadline);                     // result[opt[Msg], str]: none at the deadline

let h: map[str][str] = {};
h["Trace-Id"] = ["abc"];
nats.publish_headers(nc, "audit", h, body);

let reply = nats.request(nc, "pricing.quote", b"BTC", deadline);   // result[Msg, str]
nats.respond(nc, request_msg, b"42");
nats.drain(nc, deadline);                                 // unsubscribe, let in-flight arrive, close

URLs are nats://host:port or tls://host:port, optionally with user:pass@ or token@. options(url) gives an Options to adjust before connect_with:

• Servers and identity: servers (tried in turn), name.
• Authentication: user/pass, token, nkey_seed, or a user JWT and seed via with_creds(o, creds_file_text). NKeys sign the server's nonce with Ed25519.
• TLS: tls, ca_path, and tls_first for servers with handshake_first. By default INFO arrives in clear and the client upgrades before sending CONNECT, so credentials travel only over TLS.
• Delivery and keepalive: pending (see below), ping_interval, max_pings_out.
• Reconnection: reconnect, max_reconnects, reconnect_wait, reconnect_buffer.

One connection, one reader. A reader task parses what the server sends and hands each message to its subscription's channel, so next_msg parks rather than polls. A subscriber that falls more than pending (default 1,024) messages behind loses the newest ones and counts them in sub.dropped, rather than stalling every other subscription. This is the NATS "slow consumer" rule.

Deadlines. Each connection has one timer task that is parked while nothing waits on a deadline; deadlines resolve to within 10 ms.

Writes coalesce. Publishes append to one buffer, and a flusher task writes it out after a short wait (20 µs, or 200 µs while a publisher is streaming). A publisher that fills 32 KB first writes it itself.

Reconnection. When the connection breaks, or the server stops answering pings, the reader redials the servers in turn with jittered backoff, sends CONNECT and every live SUB again, then replays what was published in the meantime, up to reconnect_buffer (8 MiB). Delivery is at most once, as in core NATS: a message written into a connection just as it broke is lost. reconnects(nc), is_connected(nc) and last_error(nc) report the state.

request uses one shared inbox subscription for every request on the connection. If no subscriber is listening, the server's "no responders" status makes it fail at once rather than at its deadline. A -ERR 'Permissions Violation' leaves the connection up; any other -ERR or a malformed frame drops and redials it. Subjects are validated (no whitespace, no empty tokens, no wildcards in a publish), and header names and values are refused if they would inject protocol lines.

API#