NATS .NET v2.5.7

We're happy to announce a new NATS .NET release version 2.5.7. This release includes various minor fixes and features. There is also a breaking change in the dependency injection package; please make sure to check the details below.

What's Changed

• Add CreateOrUpdateStoreAsync by @Ivandemidov00 in #707
• Implement Lame Duck Mode Event Handler by @pzajaczkowski in #716
• Add callback to NatsAuthOpts that allows refreshing a Token by @garrett-sutton in #712
• Add NatsClient to DI by @mtmk in #689
• Fix telemetry header readonly error by @mtmk in #719

Breaking Change to NATS.Extensions.Microsoft.DependencyInjection Default Serialization

Since the introduction of INatsClient interface we have made developers and newcomers life easier by providing a sensible default serialization setting that would avoid surprises, and allow ad hoc JSON serialization of custom objects out of the box. With the change Add NatsClient to DI #689 we are now introducing these defaults into the NATS.Extensions.Microsoft.DependencyInjection package. If you are using this package and want to stay with the old defaults you must change the following options:

• BoundedChannelFullMode option is applied to the subscription channels and the connection default is to DropNewest. The default applied to the NatsClient instances and in turn to the NATS.Extensions.Microsoft.DependencyInjection package is now to wait when the channel is full. You can set it back to the connection default or if you are happy to go with the new default please make sure to test your application.
• DefaultSerializerRegistry of NATS.Extensions.Microsoft.DependencyInjection package is the main change with this release, allowing applications to automatically serialize ad hoc objects to JSON, while serializing primitives like byte arrays, numbers, dates, and strings to their raw values using the same serializer registry as NatsClient. We are also deprecating AddJsonSerialization methods to avaoid confusion. They are only marked as Obsolete for now, so there is no need to change that with this release.

services.AddNatsClient(nats =>
{
    // DropNewest was the default, now it's set to Wait. To keep
    // the behavior before this PR add the following line:
    nats.WithSubPendingChannelFullMode(BoundedChannelFullMode.DropNewest);

    // If you were not using custom serializer which doesn't derialize ad hoc JSON
    // objects make sure to add the following to keep to original serializer settings:
    nats.WithSerializerRegistry(NatsDefaultSerializerRegistry.Default);
});

For more information, please check the PR Add NatsClient to DI #689. Overall, we don't expect many application would be affected by this change; nevertheless, feel free to ask for clarification in the #dotnet channel on http://slack.nats.io if needed.

New Contributors

• @garrett-sutton made their first contribution in #712

Full Changelog: v2.5.6...v2.5.7

NuGet Downloads

https://www.nuget.org/packages/NATS.Net/2.5.7

NATS .NET v2.5.6

This is a bug fix release of NATS .NET v2.5.6. It fixes a serialization issue that was happening when interacting with JetStream APIs. Impact should be minimal since JetStream API calls would be retried in most cases however you might see warnings in your logs regarding malformed JSON buffers. The bug was introduced in v2.5.5 and you are strongly encourage to upgrade from v2.5.5. See #709 for more information.

What's Changed

• Fix JS API deserializer by @mtmk in #709

Full Changelog: v2.5.5...v2.5.6

Download and Install from NuGet

https://www.nuget.org/packages/NATS.Net

NATS .NET v2.5.5

Happy to announce a new release of NATS .NET v2.5.5. With this release we're introducing exception-free methods especially in operations where logic might've been driven by exceptions like the KV get method which might return a not-found. See #688 for more details.

What's Changed

• Add flags to NatsMsg and JetStream Request by @mtmk in #652
• Add (force) reconnect method by @pzajaczkowski in #684
• Update README.md by @mtmk in #683
• Jetstream CreateOrUpdateStream by @Ivandemidov00 in #692
• Add KV try get by @mtmk in #688
• Add password support for PFX files by @mtmk in #694
• Release 2.5.5 by @mtmk in #695

New Contributors

• @pzajaczkowski made their first contribution in #684

Full Changelog: v2.5.4...v2.5.5

https://www.nuget.org/packages/NATS.Net

NATS .NET v2.5.3

This is a minor release of a missing feature.

What's Changed

• Add support for auth in URL by @Mrxx99 in #670

New Contributors

• @Mrxx99 made their first contribution in #670

Full Changelog: v2.5.2...v2.5.3

NuGet

https://www.nuget.org/packages/NATS.Net/2.5.3

NATS .NET v2.5.2

Bugfix release.

What's Changed

• Add DateTimeOffset converter to handle UTC serialization by @mtmk in #661

Full Changelog: v2.5.1...v2.5.2

NATS .NET v2.5.1

Patch fix release.

What's Changed

• Update docs using the simple client by @mtmk in #655
  Added NatsOpts to NatsClient constructor. (Note that documentation update is for the repo GitHub pages docs site.)

Full Changelog: v2.5.0...v2.5.1

NATS .NET v2.5.0

We're happy to announce a new release of NATS .NET version 2.5.0 with new NatsClient extensions. With this release we are completing the features required for a simplified client initialization for ease of use especially for newcomers.

New Features

• Add JetStream NATS Client Extensions by @mtmk in #598
• Add other client extensions by @mtmk in #637

New extensions to INatsClient enables context creation easily.

using NATS.Net;

await using var nc = new NatsClient();

// Serializer does the expected thing with all types
await nc.PublishAsync("x.int", 100);
await nc.PublishAsync("x.string", "Hello, World!");
await nc.PublishAsync("x.bytes", new byte[] { 65, 66, 67 });
await nc.PublishAsync("x.json", new MyData(30, "bar"));

// ...and now you can create the contexts from the client
var js = nc.CreateJetStreamContext();
var kv = nc.CreateKeyValueStoreContext();
var obj = nc.CreateObjectStoreContext();
var svc = nc.CreateServicesContext();

Contexts are also refactored to accept interfaces rather than implementations (see breaking changes below)

• Added Domain support for stream mirroring and sourcing and KV full support for the same. by @darkwatchuk in #631

With this addition you can now setup your KV stores with mirroring support. We still have a bit more work to do with #642 to add domains.

Fixes

• Run core tests on Windows and test run stability by @mtmk in #464
• Adds type-forwarders NET 5.0+ by @VaticanUK in #641
• Add placement configuration to key-value and object store by @mtmk in #650

Security

• Bump System.Text.Json from 8.0.4 to 8.0.5 in /src/NATS.Client.Core by @dependabot in #649

Breaking Changes

Contexts now take interfaces instead of implementations. This helps us with creating various extensions as well as making it easier to unit test application code:

- public NatsJSContext(NatsConnection connection)
+ public NatsJSContext(INatsConnection connection)

- public NatsKVContext(NatsJSContext context)
+ public NatsKVContext(INatsJSContext context)

- public NatsObjContext(NatsJSContext context)
+ public NatsObjContext(INatsJSContext context)

- public NatsSvcContext(NatsConnection nats)
+ public NatsSvcContext(INatsConnection nats)

Code should compile without any issues but we're probably braking binary compatibility and you might want to refactor your code if you were working around the fact these constructors were not using interfaces.

New Contributors

• @VaticanUK made their first contribution in #641

Thank You

A big thank you to our contributors.

Happy coding ❤️

Full Changelog: v2.4.0...v2.5.0

NATS .NET v2.4.0

We are excited to announce the release of NATS .NET v2.4.0! This version brings a host of new features, enhancements, and bug fixes to improve your experience with the NATS .NET client.

New Features

New Simplified NatsClient API (Experimental)

• Add NATS client implementation by @mtmk in #589
• Simplified NATS client by @mtmk in #607

We've introduced a new, simplified NATS client implementation that makes initialization easier with common defaults, like JSON serialization for ad hoc types—great for newcomers!

Note that this new API is experimental at this stage and we will be implementing JetStream, KV, ObjectStore and Services extensions in the next minor release 2.5.x.

// Simpler initialization
await using var client = new NatsClient("nats://localhost:4222");

// Already setup with most common serialization scenarios
await client.PublishAsync("x.int", 100);
await client.PublishAsync("x.string", "Hello, World!");
await client.PublishAsync("x.bytes", new byte[] { 65, 66, 67 });
await client.PublishAsync("x.json", new MyData(30, "bar"));

Please note that this new interface is added alongside the existing INatsConnection interface, and existing applications are not affected by it.

WebSocket Improvements

• NatsOpts.ConfigureWebSocketOpts callback handler by @wolfman42 in #605
• Nats web socket opts improvements by @Ivandemidov00 in #623

This change allows setting an authorization header and a callback for more connection setup options for WebSocket connections. Unfortunately because of browser restrictions not all the options (e.g. setting headers) won't work for WebAssembly projects. Thank you @wolfman42 for the idea, @Ivandemidov00 for options enhancement and also thanks to @caleblloyd for his help in shaping the API.

Nuid Public Type

• Make NuidWriter public by @Madgvox in #618

The Nuid class generates unique identifiers that can be used to ensure uniqueness in distributed systems. With this change we opened up this internal API for applications to use in their scenarios as well. Thank you @Madgvox for the idea and the implementation and thanks to @jasper-d for verifying the implementation and the API making sure it makes sense for the .NET ecosystem.

var id = Nuid.NewNuid();

Dependency Injection Improvements

• ServiceProvider callback for NATS DI configuration; by @william-liebert in #619

This change adds IServiceProvider overloads to configuration methods, to enable resolution-time configuration. Thank you @william-liebert for the implementation.

services.AddNatsClient(builder => builder.ConfigureOptions((provider, opts) => {
    var configurator = provider.GetRequiredService<MyOptsConfigurator>();
    return configurator.Configure(opts);
}));

Fixes

• Extensive logging for reconnect debugging by @mtmk in #593
• Add default timeout to initial commands by @mtmk in #594
• Fix various disposable issues by @Bykiev in #625
• Fixed consume pending message calculation by @mtmk in #626

Documentation

• Add clear next step navigation to API index doc by @johnweldon in #592
• Update docs by @mtmk in #595

Breaking Changes

There are breaking changes that might affect your applications, but most should be caught by the compiler as you build, if any. We don't expect many applications to be affected. However, there maybe some behavioral changes you might want to keep an eye on and test especially around the JetStream consume method. Again, we do not expect many applications affected by these changes.

Changes to INatsConnection interface and the New INatsClient Interface

INatsConnection now extends the new INatsClient interface, with commonly used methods moved into the new interface. With this change, you should not normally see any effects in your code, as the INatsConnection interface still implements the exact same members so it is not actually a breaking change. However, it's something to be aware of. The idea is that if you start implementing your application using INatsClient you should be able to swap it out with INatsConnection if you see the need to use more specialized members.

public interface INatsConnection : INatsClient { /* ...on top of INatsClient also implements more specialized members */ }
public interface INatsClient : IAsyncDisposable { /* implements most common members e.g. Publish and Subscribe... */ }

Changes to Log Messages

If you are monitoring log messages there are a few minimal changes that might affect your monitoring configuration.

- Trace "Connection {Name} is closed. Will cleanup and reconnect"
+ Debug "Connection {Name} is closed. Will cleanup and reconnect [{ReconnectCount}]"

- Information "Try to invoke OnConnectingAsync before connect to NATS"
+ Information "Try to invoke OnConnectingAsync before connect to NATS [{ReconnectCount}]"

- Information "Tried to connect NATS {Url}"
+ Information "Tried to connect NATS {Url} [{ReconnectCount}]"

- Information "Connection succeeded {Name}, NATS {Url}"
+ Information "Connection succeeded {Name}, NATS {Url} [{ReconnectCount}]"

- Error "Retry loop stopped and connection state is invalid"
+ Error "Retry loop stopped and connection state is invalid [{ReconnectCount}]"

JetStream Changes to Consume Pending Message Calculation

We had a back pressure handling issue with ConsumeAsync() method in JetStream consumers. If you are using that method and relying on how many messages are consumed and how fast or tweaked options for max-messages, bytes or thresholds please test you applications to make sure you are happy with the behaviour. We don't expect any issues but there maybe some cases that needs attention. Let us know if you have any questions about this.

For more details please check PR 626 and relevant discussions.

Thank You

A huge thank you to our amazing community and all the contributors for their invaluable support. We hope these updates enhance your experience with NATS .NET and make your development process smoother. Happy coding ❤️

New Contributors

• @johnweldon made their first contribution in #592
• @wolfman42 made their first contribution in #605
• @Madgvox made their first contribution in #618
• @Bykiev made their first contribution in #625
• @william-liebert made their first contribution in #619

Full Changelog: v2.3.3...v2.4.0

NATS .NET v2.3.3

This is a minor bug fix and improvements of NATS .NET release v2.3.3. Please check the notes below about minor breaking changes.

What's Changed

• Use string.Create when building a new inbox string by @jasper-d in #551
• Add logging enhancements and improve error handling by @mtmk in #570
• KV never set duplicate window by @scottf in #577
• Obj store empty list fixed by @Ivandemidov00 in #578
• Fetch idle timeout default fix by @mtmk in #582

Breaking Changes

• Base64 Encoding simplification + optimization by @to11mtm in #549:
  JetStream model NATS.Client.JetStream.Models.StoredMessage class' Data property type changed from string to ReadOnlyMemory<byte>. This is a Base64 encoded field which now is taken case of by System.Text.Json library to be serialized as binary data. KV and Object store implementations are updated to use this more efficient version of the property so if you're only using these high level APIs you won't need to do any changes. Otherwise you will have to update your code to use the new type and in most cases compiler should catch the code that needs updating.

• Resolved issue of ObjStore GetInfo MTime returning 0 by @darkwatchuk in #567:
  Another change to the same NATS.Client.JetStream.Models.StoredMessage class. Time property is changed from string to DataTimeOffset making it easier to deal with. Again, if you're not using the model directly you should not need any changes otherwise you'd need to update your code where compiler should catch the required change for you.

• Handle various protocol errors and socket exceptions by @mtmk in #584:
  This is a log level change, so you might want to update your monitoring setup if you're watching this particular log entry for NATS.Client.Core.Commands.CommandWriter logger. We demoted socket errors (which are expected during reconnect) to a warning and changed the message slightly. Please see #584 for the exact details.

New Contributors

• @ronnieoverby made their first contribution in #576

Full Changelog: v2.3.2...v2.3.3

Nuget Package

dotnet add package NATS.Net --version 2.3.3

NATS .NET v2.3.3-preview.1

Bug fix and improvements release.

Breaking

There is one breaking change to StoredMessage.Data type in #549

What's Changed

• Use string.Create when building a new inbox string by @jasper-d in #551
• Base64 Encoding simplification + optimization by @to11mtm in #549
• Add logging enhancements and improve error handling by @mtmk in #570 (this also fixes a service API bug around error reporting)

Full Changelog: v2.3.2...v2.3.3-preview.1

Nuget Package

dotnet add package NATS.Net --version 2.3.3-preview.1