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¶
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-attemptsmust be at least the highestMaxDeliverof 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-addressmust 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 checksDurableas well and refuses a volatile one.AtMostOncecompeting 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.