Skip to content

xtr_amqp_messenger

A RabbitMQ transport for xtr-messenger, built on its taskiq bridge.

Installed beside xtr-messenger — or as xtr-messenger[amqp] — an amqp:// or amqps:// DSN is served by :class:AmqpTransportFactory, found by its scheme with no wiring: a connection and its queues, a retry ladder, delays through the delayed-message exchange, and real dead-lettering.

AmqpTransportFactory

AmqpTransportFactory(serializer: SerializerInterface, options: AmqpOptions | None = None)

Bases: TransportFactoryInterface, WorkerProvidingInterface, PublisherClosingInterface

Builds amqp:// transports, sharing one broker per DSN.

Apply these to everything it builds.

serializer is what both halves of every transport it builds write and read messages with. Producer and consumer are separate processes, so build both from the same configuration: the guarantee that matters is that what one side writes, the other reads back exactly.

supports

supports(dsn: Dsn) -> bool

Recognise the AMQP schemes.

create

create(group: Mapping[str, TransportConfig]) -> Mapping[str, SenderInterface]

Build one broker for the group, and a sender per named queue.

close_publishers async

close_publishers() -> None

Close every connection this factory's senders opened on first publish.

A worker's broker is closed by its own run loop and was never recorded, so this releases the producer side only.

worker

worker(group: Mapping[str, TransportConfig], bus: MessageBusInterface, *, event_dispatcher: EventDispatcherInterface | None = None, resetter: AsyncResetter | None = None) -> WorkerInterface

Build a runnable worker consuming only group.

Every declared message is registered on the broker as a task that dispatches into bus, so the result needs no further wiring — await worker.run() and it consumes, with bus deciding which handlers run. It listens on exactly these queues, so a worker serving a different transport is unaffected.

Import the modules that declare your messages and handlers before calling this; a message that has not been declared cannot be bound. It handles at most max_async_tasks messages at once.

event_dispatcher hears the worker events, each message reported as received from the transport whose queue it arrived on.

resetter has reset() awaited after each message, settled either way, so long-lived services are cleared between units of work.

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.

Raises:

  • MixedDsnError –

    If the transports do not share one connection.

DeadLetterMiddleware

DeadLetterMiddleware(queue_name: str, max_attempts: int)

Bases: TaskiqMiddleware

Republishes a message to the dead-letter queue once retries run out.

Dead-letter to queue_name after max_attempts deliveries.

on_error async

on_error(message: TaskiqMessage, result: TaskiqResult[object], exception: BaseException) -> None

Dead-letter the message if this was its last attempt.

Reliability dataclass

Reliability(max_attempts: int = 3, base_delay_seconds: float = 1.0, dead_letter_queue: str | None = DEFAULT_DEAD_LETTER_QUEUE)

How hard to try, and where a message goes when trying stops.

Attributes:

  • max_attempts (int) –

    Total deliveries including the first, not retries on top of it.

  • base_delay_seconds (float) –

    Delay before the first retry; later retries back off from it.

  • dead_letter_queue (str | None) –

    Where a message is republished once attempts run out. Set to None to drop exhausted messages instead.

from_settings classmethod

from_settings(settings: Mapping[str, str], defaults: Reliability | None = None) -> Reliability

Read reliability out of a transport's settings.

Anything the settings do not mention keeps its value from defaults, so a factory constructed with a policy in code can still have one setting overridden per transport.

Raises:

  • InvalidTransportOptionError –

    If a value is present but not a number.

create_amqp_broker

create_amqp_broker(url: str, options: AmqpOptions | None = None, queues: Sequence[str] = (), clock: ClockInterface | None = None) -> AioPikaBroker

Build a RabbitMQ broker.

Construction opens no connection, so this is safe to call at import time — which is what a module-level broker in a worker entrypoint needs.

Pass queues to publish to more than one queue; a :class:~xtr_messenger.bridge.taskiq.taskiq_sender.TaskiqSender then selects one by name, which is how a routing table maps message types onto queues.

A delayed message is held back as options.delay says — natively on RabbitMQ 4.4 and later, in a delay queue of its own on an older one, by default; clock reads the time a native delay ends at. With auto_setup off nothing is declared but delay queues, the dead-letter queue and the plugin's delayed exchange included: the topology must already exist, or startup fails naming what is missing.

declared_queues

declared_queues(broker: AioPikaBroker) -> tuple[str, ...]

Return the queues broker declares, which are the ones it consumes.

Useful at worker startup to log the workload a process has taken on, and to confirm a deployment scoped its workers the way it intended.