nats-io/nats.net v2.8.0 on GitHub

Happy to announce the NATS .NET 2.8.0 stable release of the 2.8 line. It picks up the NATS Server v2.14 client surface (consumer reset, $JS.FC.* flow-control replies, Consumer field on stream source/mirror, AllowBatchPublish on stream config), ships two breaking changes that landed in the preview cycle, and fixes in-flight message loss on consumer/connection dispose behind an opt-in drain.

A big thank you to all NATS contributors and community members who helped make this release possible. <3

NATS Server v2.14 Features

ResetConsumerAsync on INatsJSContext and INatsJSConsumer (ADR-60), to reset a pinned consumer's state (#1126).
$JS.FC.* flow-control replies are parsed by the JS metadata layer, for streams that publish with the js_ack_fc_v2 flag (#1127).
Consumer field on StreamSource and stream mirror config, for pre-created mirror/source consumers (#1128).
AllowBatchPublish on StreamConfig (JSON allow_batched), required by streams that opt into fast-ingest batch publishing per ADR-50 (#1120). The fast-ingest publisher itself lives in orbit.net alongside the existing atomic batch publisher.

Breaking Changes

Subject Validation On By Default (#1093)

Subjects containing whitespace (space, tab, CR, LF) now throw NatsException. This closes a class of CRLF injection issues from malformed subjects.

Opt out if you rely on legacy subjects that contain whitespace:

var opts = NatsOpts.Default with { SkipSubjectValidation = true };

NKeyPair Removed From NATS.Client.Core (#1101)

NATS.Client.Core.NKeys and NKeyPair are removed. Signing now goes through the NATS.NKeys package, which lets the nkey/Ed25519 code be versioned independently of the client.

For typical users this is transparent: keep using NatsAuthOpts.NKeyFile, CredsFile, Jwt + Seed, or AuthCredCallback and the client wires up the new signer automatically.

Only direct callers of NATS.Client.Core.NKeyPair need to switch:

// Before
using NATS.Client.Core;
var kp = NKeyPair.FromSeed(seed);
var sig = kp.Sign(nonce);

// After
using NATS.NKeys;
var kp = KeyPair.FromSeed(seed);
var sig = kp.Sign(nonce);

Other Notable Changes

Server error event (#745): a new event on NatsConnection surfaces server-side errors to client code.

Message loss on consumer dispose (#1085): opt-in drain keeps in-flight messages from being dropped when a consumer or connection is disposed. Enable with:

var opts = NatsOpts.Default with
{
    DrainSubscriptionsOnDispose = true,
    ConsumerDrainOnDisposeTimeout = TimeSpan.FromSeconds(10),
};

Auth signs the server nonce regardless of auth_required advertisement (#1109), so NKey/credential clients respond to the challenge even when the server doesn't advertise auth_required.
Connection state resets cleanly on credential loading failure (#1107).
Duplicate status headers no longer leak an incorrect Pin ID (#1116); other Pin ID handling improvements (#1099).
KV watcher cancellation behavior fix (#1084).
Protocol size checks: 64MB incoming payload cap, matching nats.js (#1095).
Range attribute fix on MaxBytes (#1096).
ArrayPool buffers are cleared before return to pool (#1097).

What's Changed

Since 2.8.0-preview.3:

Add server error event (#745)
Add Client and Orbit section to README (#1133)
Add Example Docs (#1119)
Migrate solution to slnx format (#1131)

2.8.0-preview.3:

Fix message loss on consumer dispose (#1085)
Add consumer reset API (#1126) [server 2.14]
Add consumer field on stream source/mirror (#1128) [server 2.14]
Add $JS.FC support to JS metadata parser (#1127) [server 2.14]

2.8.0-preview.2:

Add AllowBatchPublish stream config field (#1120) [server 2.14]
Bump OpenTelemetry and OpenTelemetry.Exporter.OpenTelemetryProtocol (#1121)
Fix setting wrong pin id from status header (#1116) (thanks @colprog)
Fix slow-consumer test first-ping RTT flap (#1115)
Fix net481 TLS test flakes (#1111)
Rewrite README intro (#1114)

2.8.0-preview.1:

auth: sign nonce regardless of auth_required (#1109) (thanks @Lionel-Zieminski)
auth: use NATS.NKeys package for nkey signing (#1101) [breaking]
conn: reset state on credential loading failure (#1107) (thanks @Prochy)
Improve package metadata and README (#1103)
tests: fix TlsPreferTest flap on net481 (#1108)
Fix release workflow (#1106)
Fix test flaps (#1083)
ci: add contents and actions read permissions to Claude workflow (#1102)
tls: document Prefer mode plaintext behavior (#1094)
tests: increase NuidTests thread join timeouts (#1100)
Improve Pin ID handling (#1099) (thanks @colprog)
Fix KV watcher cancellation behavior (#1084)
Clear ArrayPool buffers before returning to pool (#1097)
Enable subject validation by default (#1093) [breaking]
Add protocol size checks (#1095)
Fix Range attribute for MaxBytes property (#1096) (thanks @partnerRuiSilva)
Add CC reviews (#1092)

Full Changelog: v2.7.3...v2.8.0

Download from NuGet at https://www.nuget.org/packages/NATS.Net/2.8.0

nats-io/nats.net v2.8.0 NATS .NET v2.8.0 on GitHub