Skip to content

Prepare the exchange and queues

The adapter creates no durable topology. For each AtLeastOnce subscription, an operator creates a quorum queue; the adapter checks it at Subscribe.

For each at-least-once subscription

  1. The exchange, once: a durable topic exchange named by Settings.Exchange.
  2. A dead-letter exchange and a queue bound to it, for exhausted messages. The adapter requires that the dead-letter exchange is set; it does not check that it exists or that anything is bound to it.
  3. The queue, named by the subscription's DurableName (or by your own Topology), with these arguments or an equivalent policy:
Argument Value
x-queue-type quorum
x-dead-letter-exchange your dead-letter exchange
x-dead-letter-strategy at-least-once
x-overflow reject-publish
x-delivery-limit at least MaxDeliver - 1 (or a policy or default that gives that)
  1. The binding from the exchange to the queue, with the routing key that the subscription's Pattern translates to. A trailing .> becomes .#, a lone > becomes #, and * and everything else are unchanged. orders.> is bound as orders.#.

The tutorial's step 2 does all of this through the management API. The same arguments can be a policy: the adapter reads the queue's argument first, then its effective policy.

Size the delivery limit

The broker counts failed deliveries and the adapter counts attempts. MaxDeliver attempts is a broker limit of MaxDeliver - 1; a lower limit would dead-letter the message before its last attempt, so Subscribe refuses it. A negative limit (unlimited) is accepted. The limit is read from the management API's delivery_limit field, which the API reports only after its statistics interval; the adapter polls for up to 15 seconds and then refuses with a message saying no limit was reported.

On a RabbitMQ 4.3.5 quorum queue with no x-delivery-limit, that field was 20 when this page was written, so a MaxDeliver of 21 or less passes without setting one. Check it on your broker rather than relying on the number.

Size the consumer timeout

RabbitMQ cancels a consumer that holds a delivery past the queue's consumer timeout. If the queue sets one (x-consumer-timeout as an argument, or consumer-timeout in its effective policy) and the subscription's MaxProcessingTime is within a minute of it, Subscribe refuses. Leave at least a minute of headroom: the broker evaluates the timeout once a minute.

When the management API reports no timeout for the queue, nothing is refused, because the node's own setting is not in the queue document. The check does not run when MaxProcessingTime is zero, which is the case under Redeliver.

Read a refusal

Each refusal names the queue and what was found. They are returned from Subscribe. When it is the subscription's first attempt, bus.Start fails with messaging: subscription "name" could not start wrapping the refusal.

You see Fix
ErrNoQueue create the queue, or correct DurableName or your Topology
queue "q" is "classic"; an at-least-once identity must be a quorum queue declare it with x-queue-type: quorum; a queue's type cannot be changed
effective delivery-limit is N, below MaxDeliver M less one raise the limit or lower MaxDeliver
has no dead-letter exchange set x-dead-letter-exchange or a policy
dead-letter-strategy is X, want at-least-once set x-dead-letter-strategy: at-least-once
overflow is X, want reject-publish set x-overflow: reject-publish
MaxProcessingTime ... is within 1m0s of queue "q"'s consumer timeout shorten MaxProcessingTime or raise the timeout
Pattern "p": queue "q" is not bound to "e" with it bind the queue with the translated pattern; a different pattern is a different identity

The full list is in Topology it expects.

Create queues from your own tool

Set Settings.Topology to resolve, and if you like create, the queue for a subscription:

type Topology interface {
    Queue(ctx context.Context, spec messaging.SourceSpec) (string, error)
}

It is called once per AtLeastOnce subscribe with the subscription's SourceSpec, and returns the queue name. The adapter verifies whatever it returns. The default, ByName{}, returns spec.DurableName. The module's own integration fixture is a Topology that declares the queue and its dead-letter pair on first use.

AtMostOnce needs none of this

An AtMostOnce subscription declares its own transient queue and binds it to the exchange with the pattern. See Topology it expects.