Skip to content

Commit 876868d

Browse files
ansdansd
committed
Add AMQP address v2
This is the documentation for rabbitmq/rabbitmq-server#10873
1 parent 411cb23 commit 876868d

File tree

1 file changed

+166
-0
lines changed

1 file changed

+166
-0
lines changed

‎docs/amqp.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
title: AMQP 1.0
3+
---
4+
<!--
5+
Copyright (c) 2005-2024 Broadcom. All Rights Reserved. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.
6+
7+
All rights reserved. This program and the accompanying materials
8+
are made available under the terms of the under the Apache License,
9+
Version 2.0 (the "License”); you may not use this file except in compliance
10+
with the License. You may obtain a copy of the License at
11+
12+
https://www.apache.org/licenses/LICENSE-2.0
13+
14+
Unless required by applicable law or agreed to in writing, software
15+
distributed under the License is distributed on an "AS IS" BASIS,
16+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17+
See the License for the specific language governing permissions and
18+
limitations under the License.
19+
-->
20+
21+
# AMQP 1.0
22+
23+
## Address
24+
25+
An AMQP [address](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-address-string) determines where a message is sent to or consumed from.
26+
What internal object an AQMP address refers to and how an AMQP address is resolved is not defined by the AMQP specification because different AMQP brokers have different models to receive, store, and send messages.
27+
28+
RabbitMQ implements the powerful and flexible [AMQ 0.9.1 model](/tutorials/amqp-concepts) comprising [exchanges](/tutorials/amqp-concepts#exchanges), [queues](/tutorials/amqp-concepts#queues), and [bindings](/tutorials/amqp-concepts#bindings).
29+
Therefore, AMQP clients talking to RabbitMQ send messages to exchanges and consume messages from queues.
30+
Hence, the AMQP addresses that RabbitMQ understands and resolves contain exchange names, queue names, and routing keys.
31+
32+
RabbitMQ 4.0 introduces a new RabbitMQ specific AMQP address format, v2.
33+
The old RabbitMQ 3.x address format is referrered to as v1.
34+
35+
AMQP clients should use address format v2.
36+
Address format v1 is deprecated in RabbitMQ 4.0 and will be unsupported in a future RabbitMQ version.
37+
Whether format v1 is still supported is determined by the [deprecated feature flag](https://github.com/rabbitmq/rabbitmq-server/pull/7390) `amqp_address_v1` whose deprecation phase is `permitted_by_default` in RabbitMQ 4.0.
38+
39+
### Address v2
40+
41+
This section defines the new v2 address formats.
42+
Pull Request [#10873](https://github.com/rabbitmq/rabbitmq-server/pull/10873) explains why v2 was introduced.
43+
44+
#### Target Address v2
45+
46+
The possible v2 [target address](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-target) formats are:
47+
```
48+
1) /exchange/:exchange/key/:routing-key
49+
2) /exchange/:exchange
50+
3) /queue/:queue
51+
4) <null>
52+
```
53+
54+
The first three formats are [strings](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-string).
55+
56+
The 1st format `/exchange/:exchange/key/:routing-key` causes all messages on the given [link](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-transport-v1.0-os.html#section-links) to be sent to exchange `:exchange` with routing key `:routing-key`.
57+
58+
The 2nd format `/exchange/:exchange` causes all messages on the given link to be sent to exchange `:exchange` with the empty routing key `""`.
59+
This is useful for exchange types that ignore the routing key, such as the [fanout](/tutorials/amqp-concepts#exchange-fanout) exchange or the [headers](/tutorials/amqp-concepts#exchange-headers) exchange.
60+
61+
Setting the default exchange `""` in either of the first two formats is disallowed. Instead, use the 3rd format.
62+
63+
The 3rd format `/queue/:queue` causes all messages on the given link to be sent to queue `:queue`.\
64+
If the deprecated feature `amqp_address_v1` is denied, the queue must exist.\
65+
If the deprecated feature `amqp_address_v1` is permitted and the queue does not exist, the queue will be auto-created.\
66+
Internally, this queue target still uses the default exchange. Hence, the user needs write permissions to exchange `amq.default`.
67+
68+
The first 3 formats require the target address to be the same for all messages on the given link.
69+
If different exchanges, routing keys, or queues need to be set for different messages on the same link, use the 4th format.
70+
71+
The 4th format is the AMQP [null](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-null) value.
72+
As explained in the AMQP extension [Using the AMQP Anonymous Terminus for Message Routing](https://docs.oasis-open.org/amqp/anonterm/v1.0/cs01/anonterm-v1.0-cs01.html),
73+
each message's `to` field of the [properties](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-properties) section must be set.
74+
The allowed `to` address strings must have the same format, i.e. one of
75+
```
76+
1) /exchange/:exchange/key/:routing-key
77+
2) /exchange/:exchange
78+
3) /queue/:queue
79+
```
80+
where the exchange must exist.
81+
If a message cannot be routed because no queue is bound to the exchange, RabbitMQ settles the message with the [released outcome](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-released).
82+
83+
If your publishing application needs to send to a
84+
* single destination: prefer one of the first three string formats over the 4th (null) format as the first three formats provide slightly better performance
85+
* small number of different destinations: prefer opening one link per destination with one of the first three formats
86+
* large number of different destinations: prefer the 4th (null) format defining each destination in the `to` field.
87+
88+
#### Source Address v2
89+
90+
The only valid v2 [source address](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-source) string format is
91+
```
92+
1) /queue/:queue
93+
```
94+
where clients consume messages from queue `:queue`.
95+
96+
If the deprecated feature `amqp_address_v1` is denied, the queue must exist.\
97+
If the deprecated feature `amqp_address_v1` is permitted and the queue does not exist, the queue will be auto-created.
98+
99+
### Address v1
100+
101+
This section lists the **deprecated** v1 address string formats.
102+
103+
#### Target Address v1
104+
105+
```
106+
1) /exchange/:exchange/:routing-key
107+
2) /exchange/:exchange
108+
3) /topic/:routing-key
109+
4) /amq/queue/:queue
110+
5) /queue/:queue
111+
6) :queue
112+
7) /queue
113+
```
114+
115+
The 1st format `/exchange/:exchange/:routing-key` causes all messages on the given link to be sent to exchange `:exchange` with routing key `:routing-key`.
116+
The equivalent v2 format is `/exchange/:exchange/key/:routing-key`.
117+
118+
The 2nd format `/exchange/:exchange` causes all messages on the given link to be sent to exchange `:exchange` while the routing key can optionally be provided in the
119+
message `subject` field of the [properties](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-properties) section.
120+
In v2, defining different routing keys per message requires setting the target address to the AMQP null value and the message `to` field to `/exchange/:exchange/key/:routing-key`.
121+
122+
The 3rd format `/topic/:routing-key` causes all messages on the given link to be sent to RabbitMQ's default topic exchange called `amq.topic` with topic `routing-key`.
123+
In v2, use `/exchange/amq.topic/key/:routing-key`.
124+
125+
The 4th format `/amq/queue/:queue` causes all messages on the given link to be sent to queue `:queue` (to be more precise, internally, to the default exchange with routing key `:queue`).
126+
Queue `:queue` must exist.
127+
In v2, use `/queue/:queue`.
128+
129+
The 5th format `/queue/:queue` has similar semantics to the 4th format.
130+
However, RabbitMQ will auto declare queue `:queue`, i.e. create such a queue if it doesn't exist.
131+
The queue is never auto deleted by RabbitMQ.
132+
In v2, use `/queue/:queue`.
133+
RabbitMQ 4.0 allows AMQP clients to create RabbitMQ topologies including queues with client defined queue types, properties, and arguments.
134+
Hence, there is no need for RabbitMQ itself to auto declare a specific queue for a given queue target address format.
135+
136+
The 6th format `:queue` is redundant to the 5th format.
137+
138+
The 7th format causes the message to be sent to the queue provided in the message `subject` field.
139+
In v2, to send messages to different queues, set the target address to the AMQP null value and the message `to` field to `/queue/:queue`.
140+
141+
#### Source Address v1
142+
143+
```
144+
1) /exchange/:exchange/:binding-key
145+
2) /topic/:binding-key
146+
3) /amq/queue/:queue
147+
4) /queue/:queue
148+
5) :queue
149+
```
150+
151+
The 1st format `/exchange/:exchange/:binding-key` causes RabbitMQ to declare a queue and bind that queue to exchange `:exchange` with binding key `:binding-key`.
152+
Messages are then consumed from that queue.
153+
154+
The 2nd format `/topic/:binding-key` causes RabbitMQ to declare a queue and bind that queue to the default topic exchange `amq.topic` with topic filter `:binding-key`.
155+
Messages are then consumed from that queue.
156+
157+
The 3rd format `/amq/queue/:queue` causes RabbitMQ to consume from queue `:queue`.
158+
Queue `:queue` must exist.
159+
160+
The 4th format `/queue/:queue` causes RabbitMQ to declare a queue `:queue` and consume from that queue.
161+
162+
The 5th format `:queue` is redundant to the 4th format.
163+
164+
As explained previously, RabbitMQ 4.0 allows AMQP clients to create RabbitMQ topologies including queues with client defined queue types, properties, and arguments.
165+
Hence, there is no need for RabbitMQ itself to auto declare a specific queue for a given queue source address format.
166+
In v2, clients should first declare their own queues and bindings, and then attach with source address `/queue/:queue` which causes the client to consume from that queue.

0 commit comments

Comments
 (0)