NATS

Use Nimbus with NATS for ultra-fast, cloud-native messaging with optional JetStream persistence

The Nimbus NATS transport connects to a NATS server, delivering ultra-high-performance messaging with minimal overhead. It supports two operating modes: standard mode using core NATS pub/sub, and JetStream mode for persistent, durable messaging with delivery guarantees. Standard mode prioritises raw throughput; JetStream mode adds persistence, replay, and acknowledgements.

Installation

dotnet add package Nimbus.Transports.Nats

Quick Start

Run NATS

docker run -d \
  --name nats \
  -p 4222:4222 \
  -p 8222:8222 \
  nats:latest

The NATS monitoring dashboard is available at http://localhost:8222.

Configure Nimbus

using Nimbus;
using Nimbus.Configuration;
using Nimbus.Transports.Nats;

var bus = new BusBuilder()
    .Configure()
    .WithNames("OrderService", Environment.MachineName)
    .WithTransport(new NatsTransportConfiguration()
        .WithUrl("nats://localhost:4222"))
    .WithTypesFrom(typeProvider)
    .WithAutofacDefaults(container)
    .Build();

await bus.Start();

Or use the convenience extension method:

var bus = new BusBuilder()
    .Configure()
    .WithNames("OrderService", Environment.MachineName)
    .WithNatsTransport("nats://localhost:4222")
    .WithTypesFrom(typeProvider)
    .WithAutofacDefaults(container)
    .Build();

await bus.Start();

JetStream Mode

JetStream gives NATS durable persistence, acknowledgements, and message replay. Enable it by passing -js to the NATS server and calling .WithJetStream() in your configuration:

# Run NATS with JetStream enabled
docker run -d \
  --name nats \
  -p 4222:4222 \
  -p 8222:8222 \
  nats:latest \
  -js

var bus = new BusBuilder()
    .Configure()
    .WithNames("OrderService", Environment.MachineName)
    .WithTransport(new NatsTransportConfiguration()
        .WithUrl("nats://localhost:4222")
        .WithJetStream())
    .WithTypesFrom(typeProvider)
    .WithAutofacDefaults(container)
    .Build();

await bus.Start();

Use JetStream mode for production workloads where message durability and guaranteed delivery are required. Standard mode suits fire-and-forget scenarios where raw throughput takes priority over persistence.

Idle Subscription Cleanup

In JetStream mode every multicast event subscriber gets a durable consumer and a retry stream of its own, so each restart of an instance leaves both behind. Nimbus sets InactiveThreshold on these consumers to your AutoDeleteOnIdle window, so the server removes a consumer once nothing has pulled from it for that long. A running instance keeps pulling, so only stopped instances are affected.

Topic streams discard messages older than the same window, so an abandoned stream can’t grow without bound. Streams have no idle expiry of their own, so each bus also runs a periodic sweep that deletes a subscription’s retry stream once it has had no consumers for two consecutive sweeps.

var bus = new BusBuilder()
    .Configure()
    .WithNames("OrderService", Environment.MachineName)
    .WithTransport(new NatsTransportConfiguration().WithJetStream())
    .WithAutoDeleteOnIdle(TimeSpan.FromDays(1)) // Optional, defaults to 4 days, minimum 5 minutes
    .WithTypesFrom(typeProvider)
    .WithAutofacDefaults(container)
    .Build();

If an instance is stopped for longer than the idle window, its consumer is deleted and events published in the meantime are not delivered to it when it returns. Raise WithAutoDeleteOnIdle if instances routinely stay down for long periods.

Core NATS mode needs no cleanup because its subscriptions only exist while a connection does.

Authentication

NATS supports several authentication methods. Choose the one that matches your server configuration:

Username and Password

new NatsTransportConfiguration()
    .WithUrl("nats://localhost:4222")
    .WithCredentials("username", "password")

Token Authentication

new NatsTransportConfiguration()
    .WithUrl("nats://localhost:4222")
    .WithToken("my-secret-token")

NKey Authentication

new NatsTransportConfiguration()
    .WithUrl("nats://localhost:4222")
    .WithNKey("SUANQDPB...")  // NKey seed

Credentials File

new NatsTransportConfiguration()
    .WithUrl("nats://localhost:4222")
    .WithCredentialsFile("/path/to/credentials.creds")

Scheduled Delivery

Both standard and JetStream modes support scheduled message delivery:

// Deliver after a delay
await bus.SendAfter(new MyCommand(), TimeSpan.FromMinutes(5));

// Deliver at a specific time
await bus.SendAt(new MyCommand(), DateTimeOffset.UtcNow.AddHours(1));

Limitations

Large message support is not available. Keep message payloads under 1 MB — the NATS server’s default maximum payload size.

Compatibility

✅ NATS Server 2.x+ (required)
✅ JetStream (requires NATS Server 2.2+)
✅ .NET 9.0+