Skip to content

Topology it expects, and what it refuses

Source: naming.go, session.go (Publish, sender, durableReceiver, verify, volatileReceiver). Messages quoted are what the code returns, run against Artemis 2.57.0.

Pattern to address

A subscription's Pattern is translated to the broker's wildcard address grammar. A subject you publish to is its own address.

Pattern Address
> #
a.b.> (a trailing .>) a.b.#
anything else, * included unchanged

Artemis's wildcards: . delimits words, * matches one word, # matches zero or more. The core's > matches one or more tokens (see Subjects and patterns), so a.b.# on the broker also matches the address a.b itself. See Limits and gaps.

Publish

Before the first publish to an address in a session, the adapter asks the Management whether anything receives from it: a queue on the address itself, or a queue on a wildcard address that matches it. If nothing does, Publish returns ErrUnrouted, because a publish nothing receives is accepted by the broker and kept by nobody.

The check is once per address per session. A subscriber that appears afterwards is the next session's news; one that disappears is not noticed.

The sender link is opened on first publish and kept. Its target carries the capability topic.

Subscribe, AtLeastOnce

The subscription attaches by fully qualified name, address::queue, to a queue the operator made. The queue name comes from the Topology, which by default returns the subscription's DurableName. The adapter reads the queue and its address's settings through the Management and refuses unless all of these hold, checked in this order.

Requirement Refusal
The queue exists. ErrNoQueue, wrapped as queue "<queue>" on "<address>".
It is durable. messaging-amqp: queue "<queue>" on "<address>" is not durable; an at-least-once identity must be (auto-create on the address makes a volatile queue of a name that did not exist — turn it off for at-least-once addresses)
Its routing type is MULTICAST. messaging-amqp: queue "<queue>" is <type>; an at-least-once identity is a multicast queue
It is on the pattern's address. messaging-amqp: Pattern "<pattern>": queue "<queue>" is on address "<actual>", not "<expected>"; a subscription's Pattern is its queue's address, and a different one is a different identity (0008 D10)
The address's max-delivery-attempts is not below MaxDeliver. A negative value is not checked. messaging-amqp: MaxDeliver <n> but address "<address>"'s max-delivery-attempts is <m>; the broker would dead-letter before the last attempt
The address has a dead-letter-address. messaging-amqp: address "<address>" has no dead-letter-address; an exhausted message would be dropped silently
That dead-letter address has at least one queue. messaging-amqp: dead-letter address "<dla>" of "<address>" has no queue; a message sent to it is dropped

The receiver is then attached with the queue name as the link name, unsettled-state durability and a never-expiring expiry policy.

Nothing here creates a durable queue, an address, or a dead-letter address. A changed Pattern on a reopened DurableName is refused by the address check above. A changed MaxDeliver is accepted while it stays within the address's budget; the budget is shared by every queue on the address.

On a broker whose address has no dead-letter-address of its own, Artemis may apply a catch-all's. The adapter reports what the broker reports for that address, so the dead-letter case an operator can get wrong is a dead-letter address with no queue. The module's test fixture holds an address, c.#, dead-lettering to a name with no queue to prove that refusal.

Subscribe, AtMostOnce

The protocol gives this mode its own topology, so there is nothing to verify.

Shape Attaches to The queue
Fanout the address, with a source terminus that has no durability the broker backs the link with a queue of its own
Competing address::group the group's shared queue

The group's queue is made by the broker, so auto-create must be on for these addresses. The module's test fixture records that such a queue outlives its last member until the broker's auto-delete scan, about sixty seconds.

What the operator needs on the broker

For Artemis, the user the adapter connects as needs permission on activemq.management, which it uses for every check above. The test fixture's broker.xml grants its role manage along with send, consume, browse and queue and address creation. See Prepare Artemis for at-least-once.