Skip to content

NATS Transporter

NATS is the best-matched broker for this layer: it has native request/reply with server-side correlation, so this transport keeps no correlation map at all, and it reports "no responders" immediately instead of making a caller wait out a timeout to discover that nobody is listening. What it does not have is character-level wildcards — NATS subjects are dot-separated tokens and its wildcards work on whole tokens — and that gap is the one thing to understand before you use it.

See Microservices Overview for patterns, handlers and the envelope.

Delivery guarantees

Core NATS is at-most-once. A subscriber that is down misses messages, exactly as with Redis pub/sub. A Publish is asynchronous and buffered, so a nil error means the message was queued to the connection, not that a subscriber received it. Call Ping — which flushes — when a publish must be known to have reached the server.

NATS JetStream adds persistence and acknowledgement and is the right answer when a message must survive a consumer restart. This transport speaks core NATS.

Request/reply is where NATS is genuinely better than the alternatives. It is native: the client library allocates a per-connection inbox, tags the request with a unique reply subject and matches the response, so there is no correlation map to leak and no extra identifier to keep consistent. And an unroutable request comes back immediately as microservice.ErrNoHandler rather than as a timeout:

var user User
err := client.Send(ctx, "user_find", FindDto{ID: 23}, &user)

switch {
case errors.Is(err, microservice.ErrNoHandler):
    // Nobody is subscribed. Reported at once, not after 10 seconds.
case errors.Is(err, microservice.ErrTimeout):
    // Somebody is subscribed but did not answer in time.
}

That distinction is worth a lot during an incident: "the service is not deployed" and "the service is slow" stop looking the same.

Minimal working setup

A server:

package main

import (
    "github.com/gin-gonic/gin"

    "github.com/nika-framework/nika"
    "github.com/nika-framework/nika/common/microservice"
    "github.com/nika-framework/nika/common/microservice/transport/natsmq"

    "myapp/src"
)

func main() {
    app := nika.NewApp()

    microservice.Setup(app, microservice.Config{
        Transport: natsmq.MustNew(natsmq.Options{
            URL:  "nats://localhost:4222",
            Name: "users", // identifies the connection, and seeds QueueGroup
        }),
        Middleware: []gin.HandlerFunc{nika.RecoveryMiddleware()},
    })

    app.LoadModule(src.NewAppModule())
    app.Listen(":3001")
}

Handlers declare transport:"nats":

type UserController struct {
    Create  func(*gin.Context) `transport:"nats" pattern:"user_created"`
    FindOne func(*gin.Context) `transport:"nats" pattern:"user_find"`
}

A client, handling the error:

transport, err := natsmq.New(natsmq.Options{
    URL:       "nats://localhost:4222",
    Name:      "orders",
    CredsFile: "/etc/nats/orders.creds",
})
if err != nil {
    return fmt.Errorf("nats transport: %w", err)
}

client, err := microservice.SetupClient(app, transport)
if err != nil {
    return err
}

New connects eagerly, because NATS reports authentication failures, TLS problems and unreachable servers on connect and those are startup problems rather than per-message problems. Set LazyConnect when the process must be able to start before the broker is reachable.

Options

Field Default Purpose
URL nats.DefaultURL Server URL, or a comma-separated list for a cluster.
Conn nil Reuse an existing *nats.Conn. Close neither drains nor closes a connection it did not create.
Prefix "nika" (DefaultPrefix) Namespaces every subject as prefix + "." + pattern.
QueueGroup Name, else empty Load-balance across replicas. See below — this is the consequential setting.
Concurrency 64 Caps messages dispatched at once by this transport.
ReplyTimeout microservice.DefaultRequestTimeout (10s) Request/reply deadline when the caller passes none.
Name "" Names the connection in nats server report connections. Also seeds QueueGroup.
Token "" Bearer-token authentication.
User, Password "" Credential authentication.
NKeySeed "" Raw nkey seed (SU…). The ed25519 private key never leaves the process; the server is convinced by a signature over a per-connection nonce.
CredsFile "" Path to a NATS JWT credentials file — the usual choice with a managed or multi-tenant deployment.
TLSConfig nil For mTLS or a private CA. A tls:// URL alone does not pin anything.
ReconnectWait 2s Pause between reconnect attempts. Reconnect attempts are unlimited.
DrainTimeout 30s Bounds a graceful shutdown.
LazyConnect false Defer dialing to the first Listen, Publish or Request instead of connecting in New.
Logger slog.Default() Receives connection lifecycle and decode events.

Setting both URL and Conn is an error, as is a negative Concurrency or a prefix containing a character NATS reserves.

Reconnection is configured for an incident rather than for a demo: reconnect attempts are unlimited, because the library default gives up after a handful of attempts and then closes the connection permanently, turning a broker restart into a service that stays broken until someone redeploys it. Disconnects, reconnects and slow-consumer errors are all logged, because a silent reconnect loop is indistinguishable from a healthy connection.

QueueGroup decides how your service scales

This is the setting to get right, because both behaviours are silent:

QueueGroup Behaviour
set Replicas join a queue group and NATS delivers each message to exactly one of them. This is a load-balanced service; scaling out adds throughput.
empty Every replica receives every message. This is a broadcast; scaling out multiplies the work, and a non-idempotent handler now runs once per replica.

Because the broadcast failure mode is silent and expensive — duplicate writes, duplicate emails, duplicate charges, all proportional to your replica count — the default leans toward safety: when QueueGroup is empty and Name is set, Name is adopted as the queue group. A named service with several replicas almost always wants load balancing.

To force broadcast anyway, ask for it explicitly:

natsmq.MustNew(natsmq.Options{
    URL:        "nats://localhost:4222",
    Name:       "cache",
    QueueGroup: natsmq.NoQueueGroup, // every replica handles every message
})

Transport.QueueGroup() returns the effective value after this defaulting, so you can log it and be sure.

Wildcard patterns force a catch-all subscription

NATS wildcards are token based: * matches exactly one dot-separated token and > matches all remaining tokens. Nika pattern wildcards are character based — user_* matches user_23 and user_created.

So user_* is not a NATS wildcard at all. user_created is one single NATS token, and a subscription to prefix.user_* matches only the literal subject with that one-token suffix. There is no NATS subject that expresses "any suffix within one token".

The resolution:

  • Literal patterns map one-to-one onto exact subjects, and the broker filters. This is the efficient path.
  • Any wildcard pattern makes the process subscribe once to prefix.> and let the core Router do the character-level matching locally.
  • When the catch-all is used, the literal subjects are deliberately not also subscribed. > already covers them, and NATS delivers a message once per matching subscription, so binding both would run every literal message's handler twice.

The cost of the catch-all is real: the process then receives every message published under the prefix, including subjects owned by other services sharing it, and discards most of them — after they have crossed this process's socket, JSON decoder and CPU. The Router answers the unowned ones with a 404 / PATTERN_NOT_FOUND envelope. A warning is logged when the catch-all is used, so this is not something you have to discover from a flame graph.

The practical advice is to prefer literal patterns on this transport. If you need a wildcard, give the service its own Prefix so the catch-all only sees its own traffic.

Patterns must fit in one subject token

A pattern is rejected at Listen time if it contains a character NATS reserves:

Character Why
. The token separator — the pattern would silently become two tokens and change what the broker matches.
> The NATS multi-token wildcard; a literal one would turn an exact subscription into a firehose.
space, tab These terminate a subject in the NATS protocol's line format.

Failing at Listen is the point. The alternative is a subscription the server happily accepts and that never matches anything, which presents as "my handler is never called" with nothing in any log. Use _ where you would reach for ..

Publishing to a wildcard pattern is rejected too — a published subject must be literal.

Shutdown drains rather than drops

Close waits for in-flight handlers so their replies are still publishable, then drains a connection it owns rather than hard-closing it: drain unsubscribes, lets already-delivered messages finish, flushes anything still buffered, and only then closes. A plain close would discard in-flight work, which on a request/reply subject means every caller currently waiting gets a timeout instead of an answer. DrainTimeout bounds the whole thing so a broker that will not let go cannot hold shutdown hostage. A borrowed connection (Options.Conn) is left alone.

Subscriptions are drained on the way down too, so a shutdown does not throw away messages the broker already considers delivered.

A saturated consumer loses messages

Concurrency bounds concurrent dispatch. Reaching the cap stops draining the subscription, and NATS enforces its own pending limits on an unread subscription: a consumer that stays saturated is reported as a slow consumer and its messages are dropped, not queued. The per-subscription pending limits are raised explicitly so the limit is a deliberate choice rather than an accident, and slow-consumer errors are logged at error level because they mean data loss.

Testing

Handlers need no broker. nikatest.NewMicroservice(t) runs the whole message stack over the in-memory transport:

ms := nikatest.NewMicroservice(t)
ms.LoadModule(src.NewAppModule())

ms.Send("user_created", CreateUserDto{Name: "Ada"}).
    ExpectStatus(201).
    ExpectJSONPath("data.name", "Ada")

See Testing.

The transport's own integration suite needs a real server and is behind a build tag:

NATSMQ_TEST_URL=nats://localhost:4222 \
  go test -tags nats_integration -race ./common/microservice/transport/natsmq/

The tests use a random prefix per run, because the NATS subject space is flat and account-wide and the prefix is the only isolation available.

When to use it, and when not to

Use NATS for low-latency request/reply between services and for events where a missed message is acceptable. It has the best RPC story of the brokers here — native correlation, immediate "no responders", a flat and cheap subject space — plus queue groups, which give you load-balanced replicas with one option instead of a topology. nkey and JWT credentials make it comfortable in a multi-tenant deployment.

Do not use it when a message must survive the consumer being down: core NATS is at-most-once, and this transport does not speak JetStream. Reach for RabbitMQ when you want a durable work queue with per-message acknowledgement, or Kafka when you want a replayable log. Prefer another transport if your patterns are heavily wildcarded, since every wildcard here costs a catch-all subscription — or gRPC if the calls are strictly synchronous and you would rather have mTLS and no broker at all.