Skip to content

Prepare Artemis for at-least-once

An AtLeastOnce subscription attaches to what you have made and refuses what is wrong. This is the checklist, with the error you get for each miss. The reference for the checks is Topology it expects; the broker settings below are from the module's test fixture, test/integration/testdata/broker.xml, which is the one configuration the suite has run.

1. Turn on what survival needs

In broker.xml, inside <core>:

<persistence-enabled>true</persistence-enabled>
<persist-delivery-count-before-delivery>true</persist-delivery-count-before-delivery>
<journal-sync-non-transactional>true</journal-sync-non-transactional>

The adapter declares SurvivesRestart only when all three are on. With the image's stock configuration it declares false, and the core then refuses an AtLeastOnce subscription unless it sets AllowVolatile. See Capabilities.

With persist-delivery-count-before-delivery on, one attempt can still be lost to an orderly restart, and the adapter declares RestartLosesLastFailure for it. MaxDeliver still bounds the message.

2. Make a dead-letter address with a queue

<addresses>
   <address name="DLQ">
      <anycast>
         <queue name="DLQ" />
      </anycast>
   </address>
</addresses>

This is the fixture's own. Without a queue behind the dead-letter address, a rejected message is dropped, and the adapter refuses: dead-letter address "DLQ" of "<address>" has no queue; a message sent to it is dropped.

3. Give the subjects' addresses a budget and a dead-letter address

<address-setting match="orders.#">
   <dead-letter-address>DLQ</dead-letter-address>
   <max-delivery-attempts>10</max-delivery-attempts>
   <auto-create-queues>false</auto-create-queues>
</address-setting>
  • max-delivery-attempts must be at least the highest MaxDeliver of any subscription on the address. Below it, the broker would dead-letter before the last attempt, and the adapter refuses. A negative value is not checked.
  • dead-letter-address must be set. The adapter reads the address's settings from the broker as they resolve, so a catch-all's value counts, but a dead-letter address you did not mean to inherit is the usual way to get this wrong.
  • Auto-create of queues should be off on these addresses. A subscription naming a queue that does not exist then fails with ErrNoQueue, naming it, rather than being given a volatile queue of that name. The adapter checks Durable as well and refuses a volatile one. AtMostOnce competing groups need auto-create on for the address they use, because the broker makes the group's queue.

4. Create the durable multicast queue, on the pattern's address

The queue is on the address the pattern translates to (orders.> becomes orders.#), is durable, and is multicast. The name is the subscription's DurableName, unless your Topology says otherwise.

The adapter will not create it. Make it declaratively in broker.xml, or through Artemis's management as the fixture does:

err := amqp.Artemis{}.Create(ctx, sess, amqp.QueueSpec{
    Name:        "billing",      // the subscription's DurableName
    Address:     "orders.#",     // the pattern, translated
    RoutingType: "MULTICAST",
    Durable:     true,
})

Create is ignore-if-exists, so running it again is safe. Do it from a deploy step or a Topology you write for the job. Use the Topology to create queues only where you want the adapter's process to own them.

One queue per DurableName. Under Competing, the core requires DurableName to equal Group, so a group is one shared queue. For fan-out across replicas of a service, give each replica its own name.

5. Let the adapter's user manage

The adapter reads queues, addresses and settings through activemq.management. The user needs permission on it. The fixture grants its amq role manage along with send, consume and browse.

Check it

Subscribe. A subscription that attaches has passed every check. One that does not names the first check it failed, in the order the reference lists.