Support publishing AMQP 1.0 to Event Exchange #12714
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ansd
force-pushed
the
amqp-event-exchange
branch
3 times, most recently
from
987446a
to
4ff9c8f
Compare
ansd
added a commit
to rabbitmq/rabbitmq-website
that referenced
this pull request
Nov 14, 2024
This is the docs PR for rabbitmq/rabbitmq-server#12714 and applies to RabbitMQ >= 4.1 Note that the internal event types were documented previously at three different places: 1. https://github.com/rabbitmq/rabbitmq-server/blob/main/deps/rabbitmq_event_exchange/README.md 2. https://www.rabbitmq.com/docs/event-exchange 3. https://www.rabbitmq.com/docs/logging#internal-events All of them listed different and/or outdated event types. From now on, we use the 3rd place as only place and single source of truth for documenting internal events.
ansd
added a commit
that referenced
this pull request
Nov 14, 2024
## What? Prior to this commit, the `rabbitmq_event_exchange` internally published always AMQP 0.9.1 messages to the `amq.rabbitmq.event` topic exchange. This commit allows users to configure the plugin to publish AMQP 1.0 messages instead. ## Why? Prior to this commit, when an AMQP 1.0 client consumed events, event properties that are lists were omitted, for example property `client_properties` of event `connection.created` or property `arguments` of event `queue.created` because of the following sequence: 1. The event exchange plugins listens for all kind of internal events. 2. The event exchange plugin re-publishes all events as AMQP 0.9.1 message to the event exchange. 3. Later, when an AMQP 1.0 client consumes this message, the broker must translate the message from AMQP 0.9.1 to AMQP 1.0. 4. This translation follows the rules outlined in https://www.rabbitmq.com/docs/conversions#amqpl-amqp 5. Specifically, in this table the row before the last one describes the rule we're hitting here. It says that if the AMQP 0.9.1 header value is not an `x-` prefixed header and its value is an array or table, then this header is not converted. That's because AMQP 1.0 application-properties must be simple types as mandated in https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-application-properties ## How? The user can configure the plugin as follows to have the plugin internally publish AMQP 1.0 messages: ``` event_exchange.protocol = amqp_1_0 ``` To support complex types such as lists, the plugin sets all event properties as message-annotations. The plugin prefixes all message annotation keys with `x-opt-` to comply with the AMQP 1.0 spec. ## Alternative Design An alternative design would have been to format all event properties e.g. as JSON within the message body. However, this breaks routing on specific event property values via a headers exchange. ## Documentation #12714
ansd
force-pushed
the
amqp-event-exchange
branch
2 times, most recently
from
2e57eb7
to
68c0735
Compare
## What? Prior to this commit, the `rabbitmq_event_exchange` internally published always AMQP 0.9.1 messages to the `amq.rabbitmq.event` topic exchange. This commit allows users to configure the plugin to publish AMQP 1.0 messages instead. ## Why? Prior to this commit, when an AMQP 1.0 client consumed events, event properties that are lists were omitted. For example property `client_properties` of event `connection.created` or property `arguments` of event `queue.created` were omitted because of the following sequence: 1. The event exchange plugins listens for all kind of internal events. 2. The event exchange plugin re-publishes all events as AMQP 0.9.1 message to the event exchange. 3. Later, when an AMQP 1.0 client consumes this message, the broker must translate the message from AMQP 0.9.1 to AMQP 1.0. 4. This translation follows the rules outlined in https://www.rabbitmq.com/docs/conversions#amqpl-amqp 5. Specifically, in this table the row before the last one describes the rule we're hitting here. It says that if the AMQP 0.9.1 header value is not an `x-` prefixed header and its value is an array or table, then this header is not converted. That's because AMQP 1.0 application-properties must be simple types as mandated in https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-application-properties ## How? The user can configure the plugin as follows to have the plugin internally publish AMQP 1.0 messages: ``` event_exchange.protocol = amqp_1_0 ``` To support complex types such as lists, the plugin sets all event properties as AMQP 1.0 message-annotations. The plugin prefixes all message annotation keys with `x-opt-` to comply with the AMQP 1.0 spec. ## Alternative Design An alternative design would have been to format all event properties e.g. as JSON within the message body. However, this breaks routing on specific event property values via a headers exchange. ## Documentation rabbitmq/rabbitmq-website#2129
ansd
force-pushed
the
amqp-event-exchange
branch
from
68c0735
to
de804d1
Compare
MirahImage
approved these changes
Nov 14, 2024
michaelklishin
approved these changes
Nov 14, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What?
Prior to this commit, the
rabbitmq_event_exchangeinternally publishedalways AMQP 0.9.1 messages to the
amq.rabbitmq.eventtopic exchange.This commit allows users to configure the plugin to publish AMQP 1.0
messages instead.
Why?
Prior to this commit, when an AMQP 1.0 client consumed events,
event properties that are lists were omitted. For example property
client_propertiesof eventconnection.createdor propertyargumentsof eventqueue.createdwere omitted because of the following sequence:header value is not an
x-prefixed header and its value is an array or table, then this header is not converted.That's because AMQP 1.0 application-properties must be simple types as mandated in https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-application-properties
How?
The user can configure the plugin as follows to have the plugin
internally publish AMQP 1.0 messages:
To support complex types such as lists, the plugin sets all event
properties as AMQP 1.0 message-annotations. The plugin prefixes all message
annotation keys with
x-opt-to comply with the AMQP 1.0 spec.Alternative Design
An alternative design would have been to format all event properties
e.g. as JSON within the message body. However, this breaks routing on
specific event property values via a headers exchange.
Documentation
rabbitmq/rabbitmq-website#2129