Addressing

The terminus address is the single most client-load-bearing fact about the KubeMQ AMQP 1.0 connector: it tells the connector which KubeMQ pattern and channel a link talks to. This guide is the practical playbook for the <pattern>/<channel> grammar — always use explicit prefixes — plus channel validation, longest-prefix matching, dynamic and anonymous addresses, and the absence of vhosts.

For the address validation rules in table form, see Address mapping.

Where the address goes

AMQP 1.0 has no exchanges or routing keys. You choose the destination by setting a terminus address on the link — and where it goes depends on the link role:

The grammar — always use explicit prefixes

address := [ "/" ] pattern "/" channel    # leading "/" is optional: queues/x ≡ /queues/x
        |  bare                            # no recognized prefix → JMS hint, else DefaultPattern
        |  "/responses/" RequestID         # RPC reply token (reply path only; server-receiver only)
        |  <dynamic>                       # source.dynamic / target.dynamic → _amqp10.tmp.<connID>.<uuid>
pattern := "queues" | "events" | "events-store" | "commands" | "queries"

The leading slash is optional and stripped: queues/orders ≡ /queues/orders. The prefix is stripped, never prepended — the resolved channel (orders) is what the broker sees, so it always passes the underlying channel validation.

Longest-prefix matching

The connector matches prefixes longest-first: events-store/ is tested before events/. So events-store/audit resolves to the events-store pattern with channel audit — it is never mis-read as the events pattern with channel store/audit. You never need to escape or disambiguate; just write the full prefix. The full matching order is events-store → queues → events → commands → queries → responses.

Bare addressing — a Qpid-JMS migration convenience only

A bare address (no recognized prefix and no /) is resolved non-deterministically:

1. If the terminus carries a JMS node-capability hint, it selects the pattern: queue → queues, topic → events.
2. Otherwise the connector's configured DefaultPattern applies (default queues).

This exists so a migrating Qpid-JMS / ActiveMQ app can point at KubeMQ by changing only the connection string and the destination name — a JMS Queue("orders") carries the queue capability and lands on queues/orders without an explicit prefix.

Channel validation — stricter than the native layer

After the prefix is stripped, the connector validates the channel more strictly than the underlying KubeMQ array layer. A channel that works on the gRPC/native side can be rejected over AMQP. A violation closes the link with DETACH(amqp:not-found):

Dynamic and anonymous addresses

These are special address forms the connector mints or routes specially.

Dynamic nodes (source.dynamic / target.dynamic)

Attach a receiver with DynamicAddress: true (a dynamic source) and the connector creates a fresh node and echoes its address in the reply ATTACH: _amqp10.tmp.<connID>.<uuid>. This is the mechanism for an RPC reply node — a requester opens a dynamic receiver, reads back its echoed address, and stamps it as reply-to. See Commands.

Anonymous terminus (null target sender)

A sender opened with a null target (NewSender("", nil)) is an anonymous sender: it has no fixed destination, and each message selects its destination via properties.to (which itself uses the <pattern>/<channel> grammar). Because there is no fixed channel at attach, authorization is deferred to a per-message Write check on each message's to (see Authentication). A bad to → amqp:precondition-failed; a missing to → a Send error.

/responses/ reply tokens

/responses/<RequestID> is a synthetic RPC reply address. It is valid only as a server-receiver attach (the reply path); a receiver attach on /responses/ → DETACH(amqp:not-allowed). You do not construct these yourself in normal use — the RPC layer manages them, and they are connection-scoped (not authorized via Casbin).

No vhost

AMQP 1.0 has no vhost. The OPEN hostname field (which a client carrying over a 0-9-1 mental model might set) is logged then ignored. There is no vhost option to expose and no namespace scoping by hostname.

Reaching AMQP 0-9-1 data

The AMQP 1.0 and AMQP 0-9-1 connectors do not share a namespace. AMQP 0-9-1 queues live on KubeMQ channels named amqp.<vhost>.<queue>. To reach the same data from an AMQP 1.0 client, use the explicit queues prefix over that channel name:

/queues/amqp.<vhost>.<queue>

Cross-protocol equivalence holds the other way too: an AMQP 1.0 queues/<ch> maps to the bare KubeMQ channel <ch>, so a gRPC/native client producing to <ch> interoperates with an AMQP 1.0 consumer of queues/<ch>.

Quick reference

Related