What's Changed
This release greatly improves the robustness of the client across many areas.
Connections are more robust: the TLS handshake and cluster discovery are hardened against malformed or malicious peers, and connecting and closing behave predictably even when they race each other, where they could previously hang.
Reading from JetStream is more dependable: ordered consumers are more resilient and reliable. Reads that could hang due to some unexpected condition, or that returned partial results, now finish or fail with an error that says why.
Services follow ADR-32, the services specification shared by all NATS clients, more closely: stats count errors returned to clients (previously only internal errors) and latency the same way other clients do, the $SRV subjects are reserved for discovery, queue groups behave as documented, and the discovery prefix can be configured.
There are new capabilities too, such as Msg.respondRequest(), predicates for requestMany() and a waitOnFirstConnect function. Errors thrown by user-provided callbacks are contained consistently, so they can't stall or crash the client, and more.
The npm packages now ship both ES modules and CommonJS, so bundlers can tree-shake the client, and they require Node 22 or later.
In summary, most of this release is about making the client more reliable and predictable.
Packaging
- FEAT: the npm packages ship both ES modules and CommonJS. Each package routes
importandrequireto its own build, each with its own types, and is marked free of side effects, so bundlers (esbuild, webpack, Vite, Metro) can tree-shake it: an unused import drops out entirely. Use one or the other within an application: mixingimportandrequireloads two copies of the client. (#484 by @aricart) - CHANGE: Node 22 or later is required (
engines: node >= 22, the supported versions). (#484 by @aricart) - CHANGE:
@nats-io/transport-nodenow declares anexportsmap, as the other packages already did, so only@nats-io/transport-node(and@nats-io/transport-node/package.json) can be imported. Imports of internal paths, such as@nats-io/transport-node/lib/node_transport, and of the removedindex.jsno longer resolve; import from the package root instead. (#484 by @aricart) - FIX: the packages'
typespointed atlib/mod.d.js, which doesn't exist; it now points atlib/mod.d.ts.@nats-io/*/internalnow resolves for TypeScript'snode10module resolution. (#484 by @aricart) - CHANGE: depends on
@nats-io/nkeys2.1.0 and@nats-io/nuid3.1.0, which ship the same dual build. (#521 by @aricart)
Security
- Hardened the TLS upgrade.
- Fixed an issue where a client presented with a crafted or malicious INFO could be steered into connecting without TLS. The client now verifies that the connection's security policy is acceptable before sending its CONNECT. (#503 by @aricart)
- Safeguarded the client on connections that upgrade to TLS. Any data received in addition to the initial INFO is discarded. This prevents a malicious server from injecting protocol data into the client buffer before the TLS upgrade is completed. (#504 by @aricart)
- An INFO that cannot be parsed fails the connection with a
ProtocolError. The client then redials as per its reconnect strategy. (#491, #492, #507 by @aricart)
- Hardened cluster discovery.
- On connections that upgrade to TLS, cluster gossip (
connect_urls) in the plaintext INFO is ignored. Cluster updates are only processed when received under TLS. (#507 by @aricart) - For WebSocket connections, servers learned from a cluster update were dialed with the protocol in the gossiped entry, rather than the protocol of the connection that reported them. A
nats://horws://hentry gossiped over awssconnection (maliciously crafted, or from an incorrectly configured server) was dialed in plaintext. The gossiped protocol is now ignored, and gossiped hosts are dialed with the protocol of the current connection. (#514, #518 by @aricart) - TLS name: servers gossiped by IP adopt the TLS name of the server that reported them (or the name that server inherited). The name is fixed when the entry is added. (#508 by @aricart)
- On connections that upgrade to TLS, cluster gossip (
- Certificate hostnames are verified against the right name.
- transport-node: when the server is dialed by IP, the TLS upgrade verifies the certificate against that IP (or the name it inherited). Previously no name was passed, so Node checked the certificate against its
localhostdefault. Servers dialed by hostname were always verified against their hostname. (#505, #509 by @aricart) - transport-deno: TLS-first connections verify the certificate against the inherited TLS name. Previously the client used
Deno.connectTls(), which uses the dialed address both to dial and to verify, so a server gossiped by IP was verified against its IP and refused unless the certificate listed it. (#517 by @aricart)
- transport-node: when the server is dialed by IP, the TLS upgrade verifies the certificate against that IP (or the name it inherited). Previously no name was passed, so Node checked the certificate against its
Changes by module
@nats-io/nats-core
-
FEAT:
Msginstances now haverespondRequest(), that publishes a request to the reply subject. This API was added to simplifyackAck()in JetStream, and deemed useful for custom protocols where an exchange takes more than one round trip, such as confirmations or follow-up input. (#470 by @aricart) -
FEAT:
NatsConnection#requestMany()strategies can be functions (predicates) that end the request on a custom condition, and a newtimeoutoption fails the request with aTimeoutErrorif no response arrives in time. (#472 by @aricart) -
FEAT:
ConnectionOptions#waitOnFirstConnectaccepts a function. The function can decide to stop the initial connection process by examining the attempted server, the error, and the number of attempts. This enables the connection promise to be rejected by user code instead of trying forever. SeeFirstConnectFn. (#459 by @aricart) -
FEAT:
ConnectionOptions#debugnow accepts a function. When set, the client doesn't print the protocol frames; it passes each one to the function, which does its own logging, so user code can filter or redact what is logged. Note that a frame can hold several protocol messages, or part of one. As withdebug: true, the function can be set on a live connection. SeeDebugFn. (#465 by @aricart) -
FEAT: async authenticators (experimental) — an authenticator can now return a
Promise. It also receives anAbortSignalthat is aborted if the connection attempt is abandoned (closed, timed out or moved to another server), so pending work such as a token fetch can be cancelled. (#468, #479 by @aricart) -
FEAT:
WsConnectionOptions#wssOnlyprovides symmetry toConnectionOptions#tlsfor WebSocket connections.truerequires every server to bewss(a barehost:portis dialed withwss, and aws://URL is an error), astlsrequires TLS;nullrequiresws, astls: nullrefuses TLS; unset uses each URL's scheme. The socket URL is checked to match this policy as soon as the socket is created, including one from awsFactory, so nothing is sent on a connection that doesn't match. Whether a connection is encrypted now comes from the socket's URL, so awsFactoryno longer returnsencrypted(factories that still return it compile).wsconnect()rejects atlsoption, which W3C WebSocket connections can't configure. (#515 by @aricart) -
CHANGE:
NatsConnection#requestMany()maxWaitis now a hard limit: the total time the request listens for responses, as ADR-47 specifies. Previously, with the stall strategy, the stall timer replacedmaxWaitafter the first response, so the request stayed open until responses stopped for the stall interval, even pastmaxWait. (#472 by @aricart) -
CHANGE: the
MsgHdrsImplexport is deprecated; it was exposed by mistake. Useheaders()andMsgHdrs. (#464 by @aricart) -
FIX: the TLS handshake, cluster discovery and certificate verification are hardened; see Security above. (#503, #504, #505, #507, #508, #509, #514, #517, #518 by @aricart)
-
FIX: errors thrown by user code are contained consistently. Previously such an error could stop a consumer unexpectedly or crash the client. (#480 by @aricart)
- Data callbacks (subscriptions, consumers, direct get, service handlers): the error is printed to the console as an
UnhandledCallbackError, as the runtime would print an uncaught error, but the client and the process keep running. Consumers no longer stop; the unacked message is redelivered. - Callbacks that return values the client must act on (
authenticator,reconnectToServer,reconnectDelayHandler,waitOnFirstConnect): the connection closes with the error; on the first connect,connect()rejects with it.
- Data callbacks (subscriptions, consumers, direct get, service handlers): the error is printed to the console as an
-
FIX:
tls: nullwith a server that requires TLS now fails, as intended. Previously, when the server offered TLS,tls: nullconnected in plaintext as requested; but when the server required TLS, the connection was upgraded anyway. Now the connection is failed before anything is sent, with the error "client disabled tls ('tls: null'), but server requires tls". Node and Deno transports. (#516 by @aricart) -
FIX: when a server name resolves to several addresses and only some refuse the connection, the error reported is the reason from an address that was reached (such as the
tls: nullerror above), rather than the last "connection refused". The other addresses' errors are attached aserrors. (#516 by @aricart) -
FIX: when the TLS upgrade fails and the server had responded with an
-ERR(e.g.-ERR 'maximum connections exceeded'), the error message is preserved and quoted in the connection error, as it may be the reason for the handshake failure. The line is shown as untrusted text, escaped and truncated, and never processed. Node and Deno transports. (#506 by @aricart) -
FIX: a subscription
timeoutcloses a subscription that doesn't receive a message within the specified deadline. This was handled properly for iterators, but not for callbacks: the timer wasn't cancelled by the first message, and on expiry the subscription was left open on the server. Callback subscriptions now behave like iterators: the callback gets theTimeoutError,closedresolves with it, and the subscription unsubscribes. Draining subscriptions no longer time out. (#481 by @aricart) -
FIX: request errors no longer modify shared error objects. Previously
requestMany()appended the caller's stack to whatever error it received, and since on close every pending request receives the same error, each request appended its stack to it. Now no-responders errors are created where the request was made, so they carry the caller's stack, and other errors are passed through unchanged. Performance-sensitive clients can opt out of capturing the caller's stack withConnectionOptions#noAsyncTraces. (#471 by @aricart) -
FIX: message tracing can be used from every publish path. The trace options (
traceDestination,traceOnly) were previously dropped byrespond(), requests withnoMuxand replies sent as requests. (#471 by @aricart) -
FIX: clients that explicitly set
traceOnly: falseno longer have their messages made trace-only. The client tested the option's type rather than its value, sofalsesetNats-Trace-Onlyand the message was traced but never delivered. (#471 by @aricart) -
FIX:
NatsConnection#setServers()triggers a reconnect when the current server is not included. Previously the client stayed connected to the current server even when the new list omitted it, which doesn't match the intent of replacing the server list. Now the client reconnects to a server on the new list. (#494 by @aricart) -
FIX: for WebSocket connections,
NatsConnection#setServers()now compares servers by their URL. A URL whose scheme differs from the entry with the samehost:port(e.g.wss://h:1234forws://h:1234) replaces it, and its reconnect history starts over; a barehost:portkeeps the existing URL. Previously a server was matched byhost:portalone, so the new scheme was ignored and the old URL kept. (#512 by @aricart) -
FIX: for WebSocket connections, servers learned from cluster updates (INFO) are tracked by
host:port. Previously each INFO dropped and re-added them, resetting their reconnect counts, and added duplicates of servers the client already knew, including the current server and those in theserversoption. (#511 by @aricart) -
FIX: WebSocket URLs are always dialed on the configured port, even when it is the other scheme's default (e.g.
wsson port 80). (#513 by @aricart) -
FIX:
ConnectionOptions#timeout, the time in milliseconds allowed for each connection attempt's handshake, is validated: unset or0means the default (20000), and a negative or non-numeric value is rejected byconnect(). Previously such a value made every connection attempt time out immediately. (#490 by @aricart) -
FIX: the DNS lookup counts against the connect timeout, so a lookup that never answers is retried like a failed connect, and
NatsConnection#close()during it stops the connect. (#490 by @aricart) -
FIX: disconnect and reconnect events are reported once per real disconnect. Previously the socket close of every failed or replaced connection attempt was treated as a disconnect, producing duplicate (and sometimes out-of-order) disconnect/reconnect events. (#448 by @aricart)
-
FIX: connect errors name the real reason. When a host has several addresses (e.g.
localhoston::1and127.0.0.1), the most meaningful error is reported, with the others chained inerrors. (#516 by @aricart) -
FIX: fixed a connection race between the end of the handshake and the client marking itself connected. If the socket closed in that window, the client reported itself connected on a closed socket; now the attempt fails and is retried. (#453 by @ajaykr0905)
-
FIX:
NatsConnection#close()no longer hangs on a connection that won't drain: it still flushes pending data, but gives up after 2 seconds and closes the connection. A disconnect (stale, forced reconnect, errors) closes immediately, without a flush. All transports. (#458 by @aricart) -
FIX:
NatsConnection#close()during a connect stops it: the connect rejects, and no other servers or addresses are tried. Concurrentclose()calls wait for the first. A failed connect reports the connection's actual close reason, and data from a replaced connection is dropped. (#457 by @aricart) -
FIX: a protocol error is cleared once the client reconnects, so it isn't reported again for a later disconnect. (#492 by @aricart)
-
FIX: the transport, DNS resolver and URL parser (in the case of WebSocket connections) are bound per connection, so a later
wsconnect()/connect()in the same process doesn't affect existing connections. (#493 by @aricart) -
FIX: the first reconnect after connecting dials the next server in the pool. Previously it dialed the server that was just lost, and if that server had gone silent, the client waited out the full connect
timeoutbefore trying another one. (#520 by @aricart) -
FIX: a request no longer builds an error that nothing sees. Every request created a
RequestError("cancelled"), with its stack trace, after it had already settled. (#499 by @aricart)
@nats-io/transport-node
- FIX: servers configured with a fully-qualified hostname ending in a dot (
name.:4222) can now connect over TLS. The dot is dropped from the name sent to the server (SNI) and used to verify its certificate; previously the server refused the handshake. (#510 by @aricart) - FIX: fixed a leak where the socket of an abandoned dial (one that timed out, plain, TLS-first or STARTTLS) was left open. It is now destroyed. (#450 by @aricart)
- FIX: if the socket errors or closes while the TLS certificate files (
certFile,keyFile,caFile) are being read, the connect attempt fails and is retried like any other failed connect. (#495 by @aricart)
@nats-io/transport-deno
- FIX: TLS-first connections verify against the inherited TLS name; see Security above. (#517 by @aricart)
- FIX: connection errors keep their original text, so a quoted server error reads exactly as the server sent it. (#506 by @aricart)
- FIX:
NatsConnection#close()flushes the whole write queue; previously it waited for only one pending write, so any other buffered data could be lost. (#458 by @aricart)
@nats-io/jetstream
- FEAT:
ConsumerAPI#addOrUpdate()(jsm.consumers.addOrUpdate()) creates a consumer if it doesn't exist, or updates it if it does, so setup code can run repeatedly without first checking whether the consumer is there. It matches Go'sCreateOrUpdateConsumer. (#412 by @styler) - FEAT:
timeoutoption for direct batch get (getBatch(),getLastMessagesFor()). It sets how long to wait for each reply: the first, and every one after it. A batch that keeps flowing is never cut short, and one that stalls fails with aTimeoutError. It defaults to the JetStream client's timeout, and isn't sent to the server. (#473 by @aricart) - FEAT:
JsMsg.json()accepts an optional reviver, like coreMsg.json(), to transform values while parsing. (#421 by @aricart) - CHANGE: direct get reports a 503 as
NoRespondersError, like every other no-responders case in the client, instead ofJetStreamStatusErrorwith code 503 (no JetStream, no stream, or direct get not enabled). Code that checkserr instanceof JetStreamStatusError && err.code === 503should catchNoRespondersErrorinstead. (#473 by @aricart) - CHANGE: push consumers fail with a
PermissionViolationErrorwhen the client isn't allowed to publish the flow-control reply. The server waits for each flow-control request to be answered before it sends more messages; when the client's permissions denied the reply, the server only reported it as an asynchronous error, and heartbeats kept the consumer looking alive, so the consumer stalled forever. The consumer now stops with the error, which names the denied subject. This only affects reads large enough for the server to request flow control. (#451 by @aricart) - FIX: ordered pull consumers deliver each message once across a reconnect during a reset, recover when the last messages of a delivery are lost (the idle heartbeat's sequence reveals the gap), and a concurrent
fetch()/next()while a fetch is recreating the consumer is rejected, as documented. (#496 by @MauriceVanVeen, @aricart) - FIX: ordered consumers keep
inactive_threshold(default 5m) across resets. (#446 by @aricart) - FIX: consumer
update()replaces the filter when eitherfilter_subjectorfilter_subjectsis set, so only the desired filter needs to be specified. (#449 by @aricart) - FIX:
Batch.commit()reports why the server rejected a batch (e.g. wrong last sequence, incomplete batch) as aJetStreamApiErrorwith the server's code and description. (#467 by @aricart) - FIX: direct batch get (
getBatch(),getLastMessagesFor()). (#473 by @aricart)- The new
timeoutoption (default: the JetStream client's timeout) applies to every reply, so a batch that stalls fails with aTimeoutError; a batch that keeps flowing is never cut short. - A connection that closes mid-batch fails the batch.
- A batch with a single result always delivers it.
- A batch with no results ends cleanly.
- Stopping the batch from its callback is final: nothing more is delivered.
- The options passed to
getBatch()are left unchanged. - Experimental
DirectConsumerwaits 2.5s after a pull that failed or returned nothing before pulling again.
- The new
@nats-io/kv
- FEAT: KV entries'
json()accepts an optional reviver, like coreMsg.json(), to transform values while parsing. (#421 by @aricart) - CHANGE:
watch(),history()andkeys()are built on JetStream push consumers, so they get the push consumer flow-control change (see jetstream): without permission to publish the flow-control reply they now fail with aPermissionViolationErrorinstead of stalling. (#451 by @aricart) - CHANGE:
history()andkeys()fail with an "incomplete" error instead of returning partial results when the read can't finish. (#452 by @aricart) - CHANGE: buckets use their own
timeout, or inherit the JetStream client's (5s by default) instead of a hidden 2s default. (#469 by @Grivn, @aricart) - FIX:
create()documents its per-key TTL parameter asttl(it is the message TTL, not a marker TTL); calls are unchanged. (#422 by @aricart)
@nats-io/obj
- CHANGE:
get(),getBlob()andwatch()are built on JetStream push consumers, so they get the push consumer flow-control change (see jetstream): without permission to publish the flow-control reply they now fail with aPermissionViolationErrorinstead of stalling. (#451 by @aricart) - CHANGE:
list()fails with "list incomplete", andget()with "object read incomplete" when chunks are missing, instead of returning partial results or hanging. (#466, #477 by @aricart) - CHANGE:
ObjectResult.errorresolves to the error as documented, instead of rejecting. (#466 by @aricart) - CHANGE:
mtimeandrevisionare no longer stored in metadata; both come from the server's message, per ADR-20. Watch entries report their message's revision. (#460 by @Grivn; #482 by @aricart) - CHANGE: native SHA-256 is used where the runtime has it (Node, Deno, Bun), which is much faster;
js-sha256elsewhere.setSha256Backend()still forces either. (#485 by @aricart) - FIX:
ObjectStore#put()now releases its lock on the caller's input stream when it settles. Previously the stream stayed locked, so after a failed upload the caller couldn't cancel it (cancel()rejected with aTypeError), leaving sources such as a file or an HTTP response open. (#475 by @Grivn, @aricart) - FIX: apps bundling Object Store for React Native or the browser build without errors, and don't need to stub
crypto.subtle. (#485 by @aricart)
@nats-io/services
- FEAT: the discovery prefix (
$SRV) can now be configured, so services can be discovered under their own namespace. A service'sprefixoption sets the subject prefix its PING, INFO and STATS handlers listen on. The services client could already query a custom prefix; now services can be created with one too. (#444 by @aricart) - CHANGE: stats and metadata follow ADR-32.
last_erroris always present (""until an error is counted, and again afterreset()), andrespondErrornow counts as an error, so application errors show inlast_error.reset()no longer changesstarted. Service and endpoint metadata are frozen copies of the caller's map: later changes to the map don't affect the service, and the metadata can't be modified. (#440 by @aricart) - CHANGE: a handler failing with a runtime error (not a
ServiceError) replies500 internal error; details go tolast_errorand the console, no longer to theNats-Service-Errorheader. (#480 by @aricart) - CHANGE:
$SRV(or the service's configuredprefix) is reserved for the service's own handlers, and is now enforced:addEndpointrefuses a subject equal to the prefix or starting with it (including a group named after it). Previously such an endpoint subscribed next to the internal handlers, and every ping got a second reply. (#443 by @aricart) - CHANGE: async endpoint handlers (ones that return a promise) are counted when the promise settles: their latency includes the async work, and a rejection is counted as an error and answered with an error response. A request gets at most one error response, and error descriptions are sent on a single line in the
Nats-Service-Errorheader. (#445 by @aricart) - CHANGE: a user-provided
statsHandlerthat throws fails the stats request:stats()rejects and a$SRVSTATS request gets a 500. (#480 by @aricart) - FIX: an empty queue (
"") on a group or endpoint means no queue, as documented. Previously the endpoint joined the parent's (default) queue instead. Queue names on groups and endpoints are now validated like the service's. (#441 by @aricart)
Documentation
- docs.nats.io examples live in the repo and are type-checked in CI (#425 by @Jarema); README section on clients and Orbit (#414 by @Jarema).
- The API documentation covers the changes since 3.4, and the core README's connection options table is current. (#501 by @aricart)
New Contributors
- @styler made their first contribution in #412
- @ajaykr0905 made their first contribution in #453
- @Grivn made their first contribution in #460
- @MauriceVanVeen made their first contribution, co-authoring #496
Full Changelog: v3.4.0...v3.5.0