npm @nats-io/jetstream 3.5.0
v3.5.0

52 minutes ago

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 import and require to 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: mixing import and require loads 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-node now declares an exports map, 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 removed index.js no longer resolve; import from the package root instead. (#484 by @aricart)
  • FIX: the packages' types pointed at lib/mod.d.js, which doesn't exist; it now points at lib/mod.d.ts. @nats-io/*/internal now resolves for TypeScript's node10 module resolution. (#484 by @aricart)
  • CHANGE: depends on @nats-io/nkeys 2.1.0 and @nats-io/nuid 3.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://h or ws://h entry gossiped over a wss connection (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)
  • 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 localhost default. 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)

Changes by module

@nats-io/nats-core

  • FEAT: Msg instances now have respondRequest(), that publishes a request to the reply subject. This API was added to simplify ackAck() 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 new timeout option fails the request with a TimeoutError if no response arrives in time. (#472 by @aricart)

  • FEAT: ConnectionOptions#waitOnFirstConnect accepts 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. See FirstConnectFn. (#459 by @aricart)

  • FEAT: ConnectionOptions#debug now 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 with debug: true, the function can be set on a live connection. See DebugFn. (#465 by @aricart)

  • FEAT: async authenticators (experimental) — an authenticator can now return a Promise. It also receives an AbortSignal that 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#wssOnly provides symmetry to ConnectionOptions#tls for WebSocket connections. true requires every server to be wss (a bare host:port is dialed with wss, and a ws:// URL is an error), as tls requires TLS; null requires ws, as tls: null refuses 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 a wsFactory, so nothing is sent on a connection that doesn't match. Whether a connection is encrypted now comes from the socket's URL, so a wsFactory no longer returns encrypted (factories that still return it compile). wsconnect() rejects a tls option, which W3C WebSocket connections can't configure. (#515 by @aricart)

  • CHANGE: NatsConnection#requestMany() maxWait is now a hard limit: the total time the request listens for responses, as ADR-47 specifies. Previously, with the stall strategy, the stall timer replaced maxWait after the first response, so the request stayed open until responses stopped for the stall interval, even past maxWait. (#472 by @aricart)

  • CHANGE: the MsgHdrsImpl export is deprecated; it was exposed by mistake. Use headers() and MsgHdrs. (#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.
  • FIX: tls: null with a server that requires TLS now fails, as intended. Previously, when the server offered TLS, tls: null connected 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: null error above), rather than the last "connection refused". The other addresses' errors are attached as errors. (#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 timeout closes 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 the TimeoutError, closed resolves 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 with ConnectionOptions#noAsyncTraces. (#471 by @aricart)

  • FIX: message tracing can be used from every publish path. The trace options (traceDestination, traceOnly) were previously dropped by respond(), requests with noMux and replies sent as requests. (#471 by @aricart)

  • FIX: clients that explicitly set traceOnly: false no longer have their messages made trace-only. The client tested the option's type rather than its value, so false set Nats-Trace-Only and 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 same host:port (e.g. wss://h:1234 for ws://h:1234) replaces it, and its reconnect history starts over; a bare host:port keeps the existing URL. Previously a server was matched by host:port alone, 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 the servers option. (#511 by @aricart)

  • FIX: WebSocket URLs are always dialed on the configured port, even when it is the other scheme's default (e.g. wss on port 80). (#513 by @aricart)

  • FIX: ConnectionOptions#timeout, the time in milliseconds allowed for each connection attempt's handshake, is validated: unset or 0 means the default (20000), and a negative or non-numeric value is rejected by connect(). 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. localhost on ::1 and 127.0.0.1), the most meaningful error is reported, with the others chained in errors. (#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. Concurrent close() 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 timeout before 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's CreateOrUpdateConsumer. (#412 by @styler)
  • FEAT: timeout option 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 a TimeoutError. 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 core Msg.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 of JetStreamStatusError with code 503 (no JetStream, no stream, or direct get not enabled). Code that checks err instanceof JetStreamStatusError && err.code === 503 should catch NoRespondersError instead. (#473 by @aricart)
  • CHANGE: push consumers fail with a PermissionViolationError when 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 either filter_subject or filter_subjects is 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 a JetStreamApiError with the server's code and description. (#467 by @aricart)
  • FIX: direct batch get (getBatch(), getLastMessagesFor()). (#473 by @aricart)
    • The new timeout option (default: the JetStream client's timeout) applies to every reply, so a batch that stalls fails with a TimeoutError; 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 DirectConsumer waits 2.5s after a pull that failed or returned nothing before pulling again.

@nats-io/kv

  • FEAT: KV entries' json() accepts an optional reviver, like core Msg.json(), to transform values while parsing. (#421 by @aricart)
  • CHANGE: watch(), history() and keys() 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 a PermissionViolationError instead of stalling. (#451 by @aricart)
  • CHANGE: history() and keys() 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 as ttl (it is the message TTL, not a marker TTL); calls are unchanged. (#422 by @aricart)

@nats-io/obj

  • CHANGE: get(), getBlob() and watch() 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 a PermissionViolationError instead of stalling. (#451 by @aricart)
  • CHANGE: list() fails with "list incomplete", and get() with "object read incomplete" when chunks are missing, instead of returning partial results or hanging. (#466, #477 by @aricart)
  • CHANGE: ObjectResult.error resolves to the error as documented, instead of rejecting. (#466 by @aricart)
  • CHANGE: mtime and revision are 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-sha256 elsewhere. 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 a TypeError), 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's prefix option 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_error is always present ("" until an error is counted, and again after reset()), and respondError now counts as an error, so application errors show in last_error. reset() no longer changes started. 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) replies 500 internal error; details go to last_error and the console, no longer to the Nats-Service-Error header. (#480 by @aricart)
  • CHANGE: $SRV (or the service's configured prefix) is reserved for the service's own handlers, and is now enforced: addEndpoint refuses 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-Error header. (#445 by @aricart)
  • CHANGE: a user-provided statsHandler that throws fails the stats request: stats() rejects and a $SRV STATS 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

Full Changelog: v3.4.0...v3.5.0

Don't miss a new jetstream release

NewReleases is sending notifications on new releases.