Skip to content

Add Message Annotations section #2193

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 13, 2025
Merged

Add Message Annotations section #2193

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion docs/amqp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ For example, to connect to a virtual host called `tenant-1`, the client sets the

An AMQP 1.0 [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.
What internal object an AMQP address refers to and how an AMQP address is resolved is not defined by the AMQP 1.0 specification.
Different AMQP 1.0 brokers can choose to interprete the provided address differently.
Different AMQP 1.0 brokers can choose to interpret the provided address differently.

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).
Therefore, AMQP clients talking to RabbitMQ send messages to exchanges and consume messages from queues.
Expand Down Expand Up @@ -219,6 +219,23 @@ As explained previously, RabbitMQ 4.0 allows AMQP clients to create RabbitMQ top
Hence, there is no need for RabbitMQ itself to auto declare a specific queue for a given queue source address format.
In v2, clients should first declare their own queues and bindings, and then attach with source address `/queues/:queue` which causes the client to consume from that queue.

## Message Annotations

When a message is delivered to a consumer, RabbitMQ sets at least the following two [message annotations](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-message-annotations):
* `x-exchange` set to the [exchange](/tutorials/amqp-concepts#exchanges) this message was originally published to.
* `x-routing-key` set to the routing key this message was originally published with.

These message annotations are derived in different ways depending on how the message was originally sent to RabbitMQ. For example, they could be derived from:
* The `address` field of the [target](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-target) an AMQP 1.0 publisher attached to.
* The `to` field of the AMQP 1.0 message [properties](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-properties) section.
* The `exchange` and `routing_key` fields of the AMQP 0.9.1 `basic.publish` frame, if the message was originally published with AMQP 0.9.1.
* The [topic name](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901107) of an MQTT PUBLISH packet, if the message was originally published with MQTT.
* The name of the [stream](./streams), if the message was originally published with the [RabbitMQ stream protocol](https://github.com/rabbitmq/rabbitmq-server/blob/main/deps/rabbitmq_stream/docs/PROTOCOL.adoc).

However, AMQP 1.0 clients should not publish messages with message annotations `x-exchange` or `x-routing-key` to RabbitMQ.
RabbitMQ will not interpret them.
Instead, if an AMQP 1.0 client wants to re-publish a message to the original exchange with the original routing key, the [address](#addresses) should be set accordingly.

## Outcomes

An [outcome](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#section-delivery-state) indicates the result of delivery (message)
Expand Down
19 changes: 18 additions & 1 deletion versioned_docs/version-4.0/amqp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ For example, to connect to a virtual host called `tenant-1`, the client sets the

An AMQP 1.0 [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.
What internal object an AMQP address refers to and how an AMQP address is resolved is not defined by the AMQP 1.0 specification.
Different AMQP 1.0 brokers can choose to interprete the provided address differently.
Different AMQP 1.0 brokers can choose to interpret the provided address differently.

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).
Therefore, AMQP clients talking to RabbitMQ send messages to exchanges and consume messages from queues.
Expand Down Expand Up @@ -219,6 +219,23 @@ As explained previously, RabbitMQ 4.0 allows AMQP clients to create RabbitMQ top
Hence, there is no need for RabbitMQ itself to auto declare a specific queue for a given queue source address format.
In v2, clients should first declare their own queues and bindings, and then attach with source address `/queues/:queue` which causes the client to consume from that queue.

## Message Annotations

When a message is delivered to a consumer, RabbitMQ sets at least the following two [message annotations](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-message-annotations):
* `x-exchange` set to the [exchange](/tutorials/amqp-concepts#exchanges) this message was originally published to.
* `x-routing-key` set to the routing key this message was originally published with.

These message annotations are derived in different ways depending on how the message was originally sent to RabbitMQ. For example, they could be derived from:
* The `address` field of the [target](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-target) an AMQP 1.0 publisher attached to.
* The `to` field of the AMQP 1.0 message [properties](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-properties) section.
* The `exchange` and `routing_key` fields of the AMQP 0.9.1 `basic.publish` frame, if the message was originally published with AMQP 0.9.1.
* The [topic name](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901107) of an MQTT PUBLISH packet, if the message was originally published with MQTT.
* The name of the [stream](./streams), if the message was originally published with the [RabbitMQ stream protocol](https://github.com/rabbitmq/rabbitmq-server/blob/main/deps/rabbitmq_stream/docs/PROTOCOL.adoc).

However, AMQP 1.0 clients should not publish messages with message annotations `x-exchange` or `x-routing-key` to RabbitMQ.
RabbitMQ will not interpret them.
Instead, if an AMQP 1.0 client wants to re-publish a message to the original exchange with the original routing key, the [address](#addresses) should be set accordingly.

## Outcomes

An [outcome](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#section-delivery-state) indicates the result of delivery (message)
Expand Down