Skip to main content

NATS JetStream

NATS JetStream is supported as an Agent transport only — the Master database must still use a SQL provider. Use it for ultra-low latency, high fan-out, or ephemeral workloads.

Install​

dotnet add package JobMaster.NatsJetStream

Configuration​

builder.Services.AddJobMasterCluster(config =>
{
    config.ClusterId("My-Cluster")
          .UsePostgresForMaster("Host=...;Database=...;Username=...;Password=...");

    config.AddAgentConnectionConfig("Nats-1")
          .UseNatsJetStream("nats://localhost:4222");
});
warning

When using NATS as the Agent transport, TransientThreshold is capped at 5 minutes. JobMaster validates this at startup and refuses to start a NATS-backed cluster configured above the cap.

TransientThreshold and NATS capacity​

Jobs onboarded ahead of their execution time sit in the NATS stream as unacknowledged messages until they're due. As you increase TransientThreshold, JobMaster increases MaxAckPending on the consumer to match — more jobs can be held ahead of time, but each one occupies broker capacity for the whole wait, not just while it's running. That trade-off is why the setting is capped for this transport.

**Not sure what to set?** `TransientThreshold(TimeSpan.FromMinutes(2))` is a good starting point for NATS — enough look-ahead to keep Master DB scan frequency reasonable, without parking too many jobs in the stream at once. If your workload needs a longer look-ahead than 5 minutes, use a SQL-backed Agent transport for it instead — see Database vs. Message Broker Isolation.

Authentication & TLS​

Pass auth and TLS settings directly on UseNatsJetStream, or via ConfigFromJson's per-connection connectionOptions dictionary:

config.AddAgentConnectionConfig("Nats-1")
      .UseNatsJetStream("nats-1:4222", userName: "svc", password: "secret");

// Multi-server cluster connection, one set of credentials per server
config.AddAgentConnectionConfig("Nats-1")
      .UseNatsJetStream(new[]
      {
          ("nats-1:4222", "svc", "secret"),
          ("nats-2:4222", "svc", "secret"),
      });

Supported connectionOptions keys when configuring via JSON:

  • Auth: username, password, token, credentialsFile, nkey, jwt
  • TLS: tlsCertBundleFile, tlsCertBundleFilePassword, tlsCaFile, tlsInsecureSkipVerify, tlsMode

An unrecognized key, or an invalid tlsMode value, throws at startup.