Skip to content

Subscribe durably

An AtLeastOnce subscription on the JetStream backend is a durable pull consumer. The core's rules for the fields are in Settle a delivery; this page is what the adapter does with them.

messaging.SubscriptionSpec{
    Name:        "orders",
    Pattern:     "orders.created",
    Shape:       messaging.Fanout,
    Mode:        messaging.AtLeastOnce,
    DurableName: "orders",
    MaxDeliver:  5,
    AckWait:     time.Minute,
    StartAt:     messaging.AllAvailable,
    Handler:     handle,
}

The adapter creates a consumer with:

Consumer field Set from
Durable and Name DurableName
FilterSubject Pattern
DeliverPolicy NewMessages is DeliverNew; AllAvailable is DeliverAll
AckPolicy always explicit
AckWait AckWait; zero takes the server's default, 30 seconds
MaxDeliver MaxDeliver

StartAt applies when the identity is created and never again.

Share work across replicas

A durable name is one consumer on the server, and every process using it competes for its messages, whatever Shape it declared. For a competing group, give Group and DurableName the same value; the core requires it.

For fan-out across replicas, where every replica must see every message, give each replica its own DurableName.

Reopen a durable identity

Starting a bus again with the same DurableName resumes the consumer. The configuration must match: the adapter creates the consumer, and when it already exists with a different configuration it refuses, naming the first field that differs:

messaging-nats: durable "orders" exists with a different MaxDeliver; a durable identity is immutable
once created (0005 D10), so reopen it as it was or use a new name

The fields are Pattern, StartAt, MaxDeliver, Mode and AckWait, checked in that order. Reopen the identity as it was, or use a new name.

Keep a slow handler's message

Under the default SlowHandler: ExtendLease, the adapter calls InProgress every AckWait divided by three until the handler settles or MaxProcessingTime passes. Under Redeliver it does not, and AckWait must exceed your slowest handler. See How JetStream settles and redelivers.

Make a decline wait

The backend declares DelaysRedelivery, so Backoff and Delivery.NackAfter work. See Settle a delivery and the limit on delayed messages.

Subscribe without being durable

An AtMostOnce subscription on the JetStream backend is a core NATS subscription: no consumer, no cursor, no replay. It is subject to core NATS's overflow policy, ShedNewest.