xtr-amqp-messenger
A RabbitMQ transport for xtr-messenger: queues on an AMQP broker, a retry ladder, delays and real dead-lettering, through taskiq.
Why?
A message bus moves work to another process; RabbitMQ is the broker most deployments already run. This package is xtr-messenger's transport for it, built on the bus's broker-agnostic taskiq bridge, and it adds only what is genuinely RabbitMQ:
- 🐇
amqp://andamqps://— found by the bus from the DSN's scheme, with no wiring. - 🔁 A retry ladder — a failed message is tried again, each time later,
max_attemptstimes. - ⏰ Delays — a
DelayStamprides RabbitMQ's delayed-message exchange. - ☠️ Real dead-lettering — a message out of attempts, or one that can never be handled, is republished to a dead-letter queue in its original wire format, never acknowledged and lost.
- 🎯 One process per workload — a worker consumes only the queues it is asked to serve.
Install
uv add xtr-amqp-messenger
uv add "xtr-messenger[amqp]" # the same, from the message bus's side
It brings xtr-messenger, taskiq, taskiq-aio-pika and aio-pika. It ships no
bundle: the bus finds its factory by the DSN scheme, and the factory needs only the envelope
serializer, which discovery hands over.
Quick start
from xtr_messenger import MessageBusConfig, MessageBusFactory, TransportConfig, WorkerFactory
from xtr_messenger import JsonSerializer, TransportFactory
from xtr_serializer import JsonEncoder, PydanticNormalizer, Serializer
config = MessageBusConfig(
transports={"jobs": TransportConfig("amqp://guest:guest@rabbit:5672/", queue="jobs")},
routing={IngestDocument: "jobs"},
)
wire = JsonSerializer(Serializer([PydanticNormalizer()], [JsonEncoder()]))
factories = [TransportFactory(serializer=wire)]
await MessageBusFactory(config, factories).bus().dispatch(IngestDocument(document_id=1))
await WorkerFactory(config, factories).worker(["jobs"]).run()
Import the modules declaring your messages before building a worker: it registers one task per
message declared with @as_message, and a message nothing declared cannot be bound.
Settings
Every setting may go in the DSN's query string or in TransportConfig.options; options wins.
TransportConfig(
"amqp://user:pass@rabbit:5672/?queue=jobs&max_attempts=10",
options={"prefetch_count": "50", "dead_letter_queue": "jobs.dlq"},
)
| Group | Settings |
|---|---|
| Retries | max_attempts, base_delay_seconds, dead_letter_queue |
| Exchange | exchange, exchange_type, exchange_durable, exchange_auto_delete |
| Queue | queue, queue_type, queue_durable, queue_auto_delete, queue_exclusive, queue_max_priority, routing_key |
| Connection | heartbeat, connect_timeout, connection_name, frame_max, channel_max |
| TLS | cacert, cert, key, verify |
| Consumption | prefetch_count, max_async_tasks, auto_setup, delayed_message_exchange_plugin |
max_async_tasks is how many messages a worker handles at once: ten per CPU, capped at 100,
unless set. A message is acked once handled, so prefetch_count (10 by default) caps it too —
a worker handles the smaller of the two at once. Raise both together to go wider.
Delays — a DelayStamp, and the retry ladder's backoff — ride RabbitMQ's delayed-message
exchange, which needs the rabbitmq_delayed_message_exchange plugin enabled on the broker
(rabbitmq-plugins enable rabbitmq_delayed_message_exchange). That is what
delayed_message_exchange_plugin (on by default) declares. On a broker without the plugin set
it to false: a delayed send is then refused with UnsupportedStampError rather than
published without its delay — and pair it with max_attempts=1, because the retry ladder's
backoff has nowhere to ride either.
The TLS settings belong to amqps:// and are refused on plain amqp://, where the driver
would silently ignore them. verify=false is warned about once per factory — a notice, not a
per-broker drumbeat. connect_timeout is passed to the driver's connect call, where it is
read; heartbeat takes whole seconds and refuses values below one, which the driver would
read as "no heartbeat at all".
An unrecognised setting is refused with UnknownTransportOptionError, naming what the scheme
does accept, and a value it cannot use — prefetch_count=lots — with
InvalidTransportOptionError. Credentials stay in the DSN, percent-encoded.
Retries and dead-lettering
The bus's own worker makes one attempt per message; here taskiq's worker runs the message, and
the transport decides what a failure means. A failed message is retried, each attempt later
than the last, until max_attempts; then it is republished to taskiq.dlq — or the
dead_letter_queue you name — in its original wire format, so it can be inspected and
replayed. A handler asking for the envelope reads which attempt it is on in its
RedeliveryStamp.
With a dead-letter queue configured, a delivery that can never be handled — unparsable, naming a task nobody registered, or whose body does not decode into its message — is quarantined there at once rather than retried.
Transports sharing a DSN but naming different queues share one connection, and a worker
consumes exactly the queues of the transports it is asked for, so one deployment can run a
process per workload. One worker serving two servers is refused with MixedDsnError.
Warnings — verify=false, a poison delivery dead-lettered — go to the standard library's
logging.getLogger("messenger"), beside the rest of the bus's output; a poison delivery's
reason is logged, never its body.
Building it yourself
A factory given a collaborator discovery cannot supply is passed to the bus directly:
from xtr_amqp_messenger import AmqpTransportFactory
from xtr_amqp_messenger.transport.amqp_options import AmqpOptions
MessageBusFactory(config, [AmqpTransportFactory(wire, options=AmqpOptions(...))]).bus()
create_amqp_broker builds a configured AioPikaBroker — retry ladder, delayed-message
exchange and dead-lettering wired — and declared_queues(broker) names the queues it consumes.
xtr_messenger.bridge.amqp and its modules, where this transport used to live, still import as
the very objects defined here through this major version; they go in the next one.
Use in an application
Everything adding this package to an application takes — and, read backwards, what removing it undoes. It ships no bundle: the message bus finds its factory by the DSN scheme.
- Install —
uv add xtr-amqp-messenger, oruv add "xtr-messenger[amqp]", beside xtr-messenger set up as its Use in an application says. - Recipe —
uv run xtr-recipes recipes:syncwrites nothing: there is no bundle to list, no configuration file, environment variable or ignore line. The messenger's own recipe writesMESSENGER_DSN, a RabbitMQ one. It prints the step enabling the delayed-message plugin, which a recipe cannot make for you. - Configure — name
amqp://transports in<app>/config/packages/messenger.pyand route messages to them; enable therabbitmq_delayed_message_exchangeplugin on the broker, or adddelayed_message_exchange_plugin=falseto the DSN. - Run — a worker is
<script> messenger:consume <transport>. - Remove — drop the
amqp://transports and the routing to them, thenuv remove xtr-amqp-messenger. - Check —
debug:config messengerlists theamqp://transports.
Errors
Everything raised derives from xtr-messenger's MessageBusError:
| Error | Raised when |
|---|---|
UnknownTransportOptionError, InvalidTransportOptionError |
A setting is not accepted, or its value is not usable |
UnsupportedStampError |
A delayed message is sent with delayed_message_exchange_plugin=false |
MixedDsnError |
One worker is asked to serve transports on two servers |
MissingSerializerError |
The factory is discovered with no envelope serializer to build it with |
Development
Developed in the python-xtr monorepo, under
packages/xtr-amqp-messenger; run the commands below from there. The python-xtr-amqp-messenger
repository is a read-only copy, so send issues and pull requests to the monorepo.
uv sync
uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest
No broker is needed: every test runs on brokers that open no connection.
License
MIT — see LICENSE.
Metadata
Release files for xtr-amqp-messenger 6.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xtr_amqp_messenger-6.1.0.tar.gz | 22.7 kB | With provenance | Details for xtr_amqp_messenger-6.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xtr_amqp_messenger-6.1.0-py3-none-any.whl | Python 3 | none | any | Details for xtr_amqp_messenger-6.1.0-py3-none-any.whl |
Total release size: 52.4 kB
Release files / xtr_amqp_messenger-6.1.0.tar.gz
| Download URL | xtr_amqp_messenger-6.1.0.tar.gz |
|---|---|
| Size | 22.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
91ca616a0e89e9fe25b4af91298861abf492bd5beb60fbd3eaeec6401fce5fad
|
|
BLAKE2b-256 checksum How to use checksums |
0a3cf183ec594c4bef80a98146d77582ffe5847e56a5d6e921f1ad0cdb36bb10
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logRelease files / xtr_amqp_messenger-6.1.0-py3-none-any.whl
| Download URL | xtr_amqp_messenger-6.1.0-py3-none-any.whl |
|---|---|
| Size | 29.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a1a33a6c5197fed1496d30f5e838d5f1e2f3d254b92dad3a35bb50895a952168
|
|
BLAKE2b-256 checksum How to use checksums |
47e516b42ec200d3a5203f0f2cb6be06d854d92366f609b69cb0151dacf58534
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logSecurity for xtr-amqp-messenger 6.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for xtr_amqp_messenger-6.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.