Skip to content

Configuration

All configuration is composed from frozen, immutable dataclasses.

RabbitConfig (top-level)

RabbitConfig dataclass

Top-level config — composes focused config objects.

Frozen + slots (per project convention). Brokers that need to apply per-route overrides (e.g. prefetch) hold a private dataclasses.replace copy rather than mutating the caller's object.

Only connection/broker defaults. Throughput/batching configs are accepted by their respective components directly.

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class RabbitConfig:
    """Top-level config — composes focused config objects.

    Frozen + slots (per project convention). Brokers that need to apply
    per-route overrides (e.g. prefetch) hold a private ``dataclasses.replace``
    copy rather than mutating the caller's object.

    Only connection/broker defaults. Throughput/batching configs
    are accepted by their respective components directly.
    """

    connection: ConnectionConfig = field(default_factory=ConnectionConfig)
    socket: SocketConfig = field(default_factory=SocketConfig)
    security: SecurityConfig = field(default_factory=SecurityConfig)
    publisher: PublisherConfig = field(default_factory=PublisherConfig)
    consumer: ConsumerConfig = field(default_factory=ConsumerConfig)
    pool: PoolConfig = field(default_factory=PoolConfig)
    topology_mode: TopologyMode = TopologyMode.AUTO_DECLARE
    safety: SafetyConfig = field(default_factory=SafetyConfig)
    retry: RetryConfig | None = None
    compression: CompressionConfig | None = None
    logging: LoggingConfig | None = None

ConnectionConfig

ConnectionConfig dataclass

Core connection parameters.

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class ConnectionConfig:
    """Core connection parameters."""

    host: str = "localhost"
    port: int = 5672
    username: str = "guest"
    password: str = "guest"
    vhost: str = "/"
    heartbeat: int = 30
    socket_timeout: float = 10.0
    # k8s-friendly default: fail fast on a blocked connection rather than
    # appearing healthy for 5 minutes while publishing stalls.
    blocked_connection_timeout: float = 60.0
    connection_name: str | None = None
    reconnect_backoff_base: float = 1.0
    reconnect_backoff_max: float = 30.0
    # Bound on the SYNC transport's reconnect loop only (H-SRE4: never retry
    # forever). Previously hardcoded (30 attempts) and unreachable from
    # config -- the transport constructor accepted no override and
    # RabbitConfig had no path to it at all. Async's *ongoing* reconnect
    # (after the first successful connect) is NOT bounded by this field: it
    # retries with exponential backoff and full jitter (reconnect_backoff_base
    # doubling up to reconnect_backoff_max), unlimited by default, and is
    # bounded only by reconnect_budget_attempts / reconnect_budget_seconds
    # below. Unlimited is the right default for a long-running consumer (let
    # Kubernetes/the supervisor decide whether to kill a wedged pod). See
    # docs/concurrency-model.md for the full reasoning.
    reconnect_max_attempts: int = 30
    # M13: credential rotation. When set, called at each (re)connect to fetch
    # fresh (username, password) — e.g. from Vault/short-lived secrets — so a
    # rotated credential is picked up on the next reconnect WITHOUT a redeploy
    # (the frozen username/password fields are the static fallback). Excluded
    # from the AMQP URL/repr paths; only the connection builders call it. On
    # async this includes every in-place reconnect attempt of a live
    # connection, not only rabbitkit-built connections.
    credentials_provider: Callable[[], tuple[str, str]] | None = None
    # M9: additional cluster nodes for failover, each "host" or "host:port".
    # The primary (host/port above) is tried first, then each node in order.
    # All share the same credentials/vhost/TLS/heartbeat. Sync (pika) tries
    # them natively via a ConnectionParameters list; async cycles endpoints on
    # the initial connect AND on every reconnect attempt after a drop,
    # moving to the next node after each failure.
    nodes: tuple[str, ...] = ()
    # Item 8: escape-hatch for extra AMQP client_properties, shown in the
    # management UI's Connections tab alongside connection_name -- e.g.
    # service_name/environment/pod_name for fleet-wide "which pod owns this
    # connection" triage. rabbitkit ALWAYS adds its own library/
    # library_version identification regardless of this field; these are
    # purely additive on top (see sync/connection.py, async_/connection.py).
    #
    # SECURITY: every key/value here is visible in PLAINTEXT to anyone with
    # RabbitMQ management-UI/API read access -- there is no additional authn
    # on top of that. Never put secrets, credentials, or tenant-identifying
    # PII here; service_name/environment/pod_name/region are fine, customer
    # IDs or API keys are not.
    client_properties: dict[str, str] = field(default_factory=dict)
    # bounds on the ASYNC transport's reconnects after the first
    # successful connect (an outage). Both default to None = unlimited, the
    # availability-first behaviour rabbitkit always had. When either runs
    # out, the connection gives up for good: ReconnectBudgetExhaustedError
    # reaches on_connection_failed hooks, readiness and liveness go false and
    # AsyncBroker.run() raises it. Attempts count consecutive failed
    # reconnects within one outage; seconds count from the moment the
    # connection was lost. The counters reset when a reconnect succeeds.
    # The SYNC transport ignores both; its loop stays bounded by
    # reconnect_max_attempts above (unchanged).
    reconnect_budget_attempts: int | None = None
    reconnect_budget_seconds: float | None = None

    def resolve_credentials(self) -> tuple[str, str]:
        """Return ``(username, password)`` — from ``credentials_provider`` if
        set (M13: called at each (re)connect so rotated secrets are picked up
        without a redeploy), else the static ``username``/``password`` fields."""
        if self.credentials_provider is not None:
            return self.credentials_provider()
        return self.username, self.password

    def cluster_endpoints(self) -> list[tuple[str, int]]:
        """Primary host:port plus any failover nodes, in connect-attempt order."""
        endpoints = [(self.host, self.port)]
        for node in self.nodes:
            if ":" in node:
                host, _, port = node.partition(":")
                endpoints.append((host, int(port)))
            else:
                endpoints.append((node, self.port))
        return endpoints

    def __repr__(self) -> str:
        return _masked_repr(self)

    @property
    def url(self) -> str:
        """Build AMQP URL from config fields.

        Username, password and vhost are URL-encoded so credentials containing
        reserved characters (``@:/#`` etc.) cannot corrupt the host/port parse
        (mirrors the encoding done in ``async_/connection.py``).

        SECURITY (L2): this embeds the plaintext password (``user:pass@host``)
        — never log or repr it. Use :attr:`safe_url` for logging/display.
        """
        if self.vhost == "/":
            vhost = "%2F"
        else:
            vhost = quote(self.vhost, safe="")
        user = quote(self.username, safe="")
        pwd = quote(self.password, safe="")
        return f"amqp://{user}:{pwd}@{self.host}:{self.port}/{vhost}"

    @property
    def safe_url(self) -> str:
        """Like :attr:`url` but with the password masked (L2) — safe to log."""
        if self.vhost == "/":
            vhost = "%2F"
        else:
            vhost = quote(self.vhost, safe="")
        user = quote(self.username, safe="")
        return f"amqp://{user}:***@{self.host}:{self.port}/{vhost}"

    def __post_init__(self) -> None:
        # Surface the insecure default-credentials-against-non-local-host mistake
        # once at construction (not per-connection). The default is kept for dev
        # convenience; this only warns.
        if self.username == "guest" and self.host not in {"localhost", "127.0.0.1", "::1"}:
            warnings.warn(
                "ConnectionConfig uses default 'guest' credentials against non-local "
                f"host {self.host!r}; set explicit username/password for production.",
                UserWarning,
                stacklevel=2,
            )
        # M9: fail fast on a malformed node entry rather than at connect time.
        for node in self.nodes:
            _, sep, port = node.partition(":")
            if sep and not port.isdigit():
                raise ConfigValidationError(
                    f"ConnectionConfig.nodes entry {node!r} has a non-numeric port; use 'host' or 'host:port'."
                )
        if self.reconnect_max_attempts < 1:
            raise ConfigValidationError(
                f"ConnectionConfig.reconnect_max_attempts must be >= 1, got "
                f"{self.reconnect_max_attempts} (this bounds the sync transport's "
                "reconnect loop only -- see the field docstring)."
            )
        self._validate_timing()
        # Item 8: basic validation for the client_properties escape hatch --
        # strings only (AMQP field-table values could otherwise smuggle
        # arbitrary types through to the broker), length-capped so a runaway
        # value can't bloat every connection's handshake frame.
        for key, cp_value in self.client_properties.items():
            if key in _RESERVED_CLIENT_PROPERTIES:
                raise ConfigValidationError(
                    f"ConnectionConfig.client_properties may not set {key!r}: it would replace the "
                    "client's capability table, and the broker would stop sending connection.blocked "
                    "(so is_blocked, FlowController and blocked_connection_timeout go silent)."
                )
            if not isinstance(key, str) or not isinstance(cp_value, str):
                raise ConfigValidationError(
                    f"ConnectionConfig.client_properties keys and values must be strings, got {key!r}={cp_value!r}."
                )
            if len(cp_value) > _CLIENT_PROPERTY_VALUE_MAX_LEN:
                raise ConfigValidationError(
                    f"ConnectionConfig.client_properties[{key!r}] is "
                    f"{len(cp_value)} chars, exceeding the "
                    f"{_CLIENT_PROPERTY_VALUE_MAX_LEN}-char limit."
                )

    def _validate_timing(self) -> None:
        """reject timing values that silently break reconnects.

        ``reconnect_backoff_base=0`` made every retry immediate (a hot
        reconnect loop) and ``reconnect_backoff_max < base`` capped the
        backoff below its own starting point. ``socket_timeout <= 0`` is not
        a usable connect timeout. ``heartbeat=0`` is legal (it disables
        heartbeats) but means a silently dead TCP peer is never detected, so
        it warns.
        """
        if not self.reconnect_backoff_base > 0:
            raise ConfigValidationError(
                f"ConnectionConfig.reconnect_backoff_base must be > 0, got {self.reconnect_backoff_base}."
            )
        if not self.reconnect_backoff_max >= self.reconnect_backoff_base:
            raise ConfigValidationError(
                f"ConnectionConfig.reconnect_backoff_max ({self.reconnect_backoff_max}) must be >= "
                f"reconnect_backoff_base ({self.reconnect_backoff_base})."
            )
        if not self.socket_timeout > 0:
            raise ConfigValidationError(f"ConnectionConfig.socket_timeout must be > 0, got {self.socket_timeout}.")
        if self.heartbeat < 0:
            raise ConfigValidationError(
                f"ConnectionConfig.heartbeat must be >= 0 (0 disables heartbeats), got {self.heartbeat}."
            )
        if self.heartbeat == 0:
            warnings.warn(
                "ConnectionConfig(heartbeat=0) disables AMQP heartbeats: a broker or network "
                "that dies without closing the TCP connection is not detected, and the client "
                "waits on a dead socket. Keep a heartbeat (the default is 30 s) in production.",
                UserWarning,
                stacklevel=3,
            )
        if self.reconnect_budget_attempts is not None and self.reconnect_budget_attempts < 1:
            raise ConfigValidationError(
                "ConnectionConfig.reconnect_budget_attempts must be >= 1 or None (unlimited), "
                f"got {self.reconnect_budget_attempts}."
            )
        if self.reconnect_budget_seconds is not None and not self.reconnect_budget_seconds > 0:
            raise ConfigValidationError(
                "ConnectionConfig.reconnect_budget_seconds must be > 0 or None (unlimited), "
                f"got {self.reconnect_budget_seconds}."
            )

    @classmethod
    def from_url(cls, url: str) -> ConnectionConfig:
        """Parse an AMQP URL into a ConnectionConfig.

        Supports: amqp://user:pass@host:port/vhost?heartbeat=30&connection_timeout=10
        """
        parsed = urlparse(url)
        query = parse_qs(parsed.query)

        vhost = parsed.path.lstrip("/") if parsed.path and parsed.path != "/" else "/"
        if vhost == "%2F" or vhost == "":
            vhost = "/"

        # M3: an amqps:// URL implies TLS, but rabbitkit enables TLS via
        # SecurityConfig(ssl=SSLConfig(enabled=True)), NOT the URL scheme —
        # ConnectionConfig carries no TLS state. Silently ignoring the scheme
        # would let an operator ship PLAINTEXT while believing TLS is on. We
        # default the port to the AMQPS port (5671) and warn loudly, so a
        # not-actually-encrypted connection fails fast against a TLS-only port
        # instead of leaking plaintext to a plaintext listener.
        is_amqps = parsed.scheme == "amqps"
        default_port = 5671 if is_amqps else 5672
        if is_amqps:
            import warnings

            warnings.warn(
                "amqps:// URL parsed, but rabbitkit does not enable TLS from the URL "
                "scheme — you must pass SecurityConfig(ssl=SSLConfig(enabled=True)) to "
                "RabbitConfig. Port defaulted to 5671; without TLS enabled this "
                "connection will fail against a TLS-only listener (not silently send "
                "plaintext).",
                RuntimeWarning,
                stacklevel=2,
            )

        kwargs: dict[str, str | int | float | None] = {
            "host": parsed.hostname or "localhost",
            "port": parsed.port or default_port,
            # Percent-decode credentials so an encoded AMQP URL round-trips
            # without double-encoding (e.g. user%40 -> user@).
            "username": unquote(parsed.username) if parsed.username else "guest",
            "password": unquote(parsed.password) if parsed.password else "guest",
            "vhost": vhost,
        }

        if "heartbeat" in query:
            kwargs["heartbeat"] = int(query["heartbeat"][0])
        if "connection_timeout" in query:
            kwargs["socket_timeout"] = float(query["connection_timeout"][0])
        if "blocked_connection_timeout" in query:
            kwargs["blocked_connection_timeout"] = float(query["blocked_connection_timeout"][0])

        return cls(**kwargs)  # type: ignore[arg-type]

Attributes

url: str property

Build AMQP URL from config fields.

Username, password and vhost are URL-encoded so credentials containing reserved characters (@:/# etc.) cannot corrupt the host/port parse (mirrors the encoding done in async_/connection.py).

SECURITY (L2): this embeds the plaintext password (user:pass@host) — never log or repr it. Use :attr:safe_url for logging/display.

safe_url: str property

Like :attr:url but with the password masked (L2) — safe to log.

Methods:

resolve_credentials() -> tuple[str, str]

Return (username, password) — from credentials_provider if set (M13: called at each (re)connect so rotated secrets are picked up without a redeploy), else the static username/password fields.

Source code in src/rabbitkit/core/config.py
def resolve_credentials(self) -> tuple[str, str]:
    """Return ``(username, password)`` — from ``credentials_provider`` if
    set (M13: called at each (re)connect so rotated secrets are picked up
    without a redeploy), else the static ``username``/``password`` fields."""
    if self.credentials_provider is not None:
        return self.credentials_provider()
    return self.username, self.password

cluster_endpoints() -> list[tuple[str, int]]

Primary host:port plus any failover nodes, in connect-attempt order.

Source code in src/rabbitkit/core/config.py
def cluster_endpoints(self) -> list[tuple[str, int]]:
    """Primary host:port plus any failover nodes, in connect-attempt order."""
    endpoints = [(self.host, self.port)]
    for node in self.nodes:
        if ":" in node:
            host, _, port = node.partition(":")
            endpoints.append((host, int(port)))
        else:
            endpoints.append((node, self.port))
    return endpoints

from_url(url: str) -> ConnectionConfig classmethod

Parse an AMQP URL into a ConnectionConfig.

Supports: amqp://user:pass@host:port/vhost?heartbeat=30&connection_timeout=10

Source code in src/rabbitkit/core/config.py
@classmethod
def from_url(cls, url: str) -> ConnectionConfig:
    """Parse an AMQP URL into a ConnectionConfig.

    Supports: amqp://user:pass@host:port/vhost?heartbeat=30&connection_timeout=10
    """
    parsed = urlparse(url)
    query = parse_qs(parsed.query)

    vhost = parsed.path.lstrip("/") if parsed.path and parsed.path != "/" else "/"
    if vhost == "%2F" or vhost == "":
        vhost = "/"

    # M3: an amqps:// URL implies TLS, but rabbitkit enables TLS via
    # SecurityConfig(ssl=SSLConfig(enabled=True)), NOT the URL scheme —
    # ConnectionConfig carries no TLS state. Silently ignoring the scheme
    # would let an operator ship PLAINTEXT while believing TLS is on. We
    # default the port to the AMQPS port (5671) and warn loudly, so a
    # not-actually-encrypted connection fails fast against a TLS-only port
    # instead of leaking plaintext to a plaintext listener.
    is_amqps = parsed.scheme == "amqps"
    default_port = 5671 if is_amqps else 5672
    if is_amqps:
        import warnings

        warnings.warn(
            "amqps:// URL parsed, but rabbitkit does not enable TLS from the URL "
            "scheme — you must pass SecurityConfig(ssl=SSLConfig(enabled=True)) to "
            "RabbitConfig. Port defaulted to 5671; without TLS enabled this "
            "connection will fail against a TLS-only listener (not silently send "
            "plaintext).",
            RuntimeWarning,
            stacklevel=2,
        )

    kwargs: dict[str, str | int | float | None] = {
        "host": parsed.hostname or "localhost",
        "port": parsed.port or default_port,
        # Percent-decode credentials so an encoded AMQP URL round-trips
        # without double-encoding (e.g. user%40 -> user@).
        "username": unquote(parsed.username) if parsed.username else "guest",
        "password": unquote(parsed.password) if parsed.password else "guest",
        "vhost": vhost,
    }

    if "heartbeat" in query:
        kwargs["heartbeat"] = int(query["heartbeat"][0])
    if "connection_timeout" in query:
        kwargs["socket_timeout"] = float(query["connection_timeout"][0])
    if "blocked_connection_timeout" in query:
        kwargs["blocked_connection_timeout"] = float(query["blocked_connection_timeout"][0])

    return cls(**kwargs)  # type: ignore[arg-type]

ConsumerConfig

ConsumerConfig dataclass

Consumer behavior tuning.

Attributes:

Name Type Description
prefetch_count int

AMQP QoS per consumer channel. On the async broker this is also the handler concurrency per queue unless a WorkerConfig(worker_count >= 2) pool is used.

graceful_timeout float

shutdown drain budget in seconds (stop()).

reject_transient_on_redelivery bool

bound the transient-failure loop on routes without retry (default True). A transient error (TimeoutError, OSError, HandlerTimeoutError, ...) on a first delivery is nack-requeued once; the same error on a message the broker has already redelivered (redelivered=True) is dead-lettered instead of requeued again. This is a 2-strike cap on the broker's redelivered flag, the only per-message redelivery signal classic queues carry. It also counts a redelivery caused by a crash or a lost connection, so one transient failure after a reconnect goes to the DLQ. For more attempts or delays use RetryConfig (delay queues). False restores the previous behaviour: transient errors requeue immediately with no cap, which hot-loops a poison message (thousands of handler runs per second).

manual_settle_on_error bool

under AckPolicy.MANUAL, a handler that raises WITHOUT settling its message gets the same failure settlement as AUTO (transient: requeue, bounded as above; permanent: dead-letter), logged with the action taken (default True). Without it the delivery stayed unacked until the channel closed, holding a prefetch slot; prefetch such failures stalled the consumer. Set False only if the handler settles through something other than RabbitMessage (a raw channel or a coalescing acker) and then re-raises: the pipeline cannot see that settlement and would settle the delivery a second time.

processing_timeout float | None

per-delivery handler deadline in seconds (None = off, the default). On expiry HandlerTimeoutError (outcome_unknown=True, transient) goes through the normal failure settlement. Async: the handler task is cancelled. Sync: the I/O thread settles the delivery at the deadline, but Python cannot interrupt a thread, so the handler keeps running (and keeps its worker) until it returns; its late result is discarded. With it set, sync handlers always run off the I/O thread: on the worker pool, or with worker_count=1 on one dedicated handler thread (see docs/concurrency-model.md).

max_body_bytes int | None

raw-body cap for deliveries, in bytes (None = no cap, the default). A delivery whose body as received (before decompression or any on_receive hook) is larger is INVALID_MESSAGE: rejected without requeue, so the source queue's dead-letter exchange moves it to the DLQ, without running any middleware or the handler. By default the broker dead-letters it, so the DLQ entry carries x-death but not rabbitkit's failure headers; with SafetyConfig.dead_letter_with_metadata (async broker; set by the CRITICAL profile) it is a confirmed copy with them (x-rabbitkit-error-category: invalid_message). CompressionMiddleware caps the decompressed size separately.

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class ConsumerConfig:
    """Consumer behavior tuning.

    Attributes:
        prefetch_count: AMQP QoS per consumer channel. On the async broker
            this is also the handler concurrency per queue unless a
            ``WorkerConfig(worker_count >= 2)`` pool is used.
        graceful_timeout: shutdown drain budget in seconds (``stop()``).
        reject_transient_on_redelivery: bound the transient-failure loop on
            routes without retry (default True). A transient error
            (``TimeoutError``, ``OSError``, ``HandlerTimeoutError``, ...) on
            a first delivery is nack-requeued once; the same error on a
            message the broker has already redelivered
            (``redelivered=True``) is dead-lettered instead of requeued
            again. This is a 2-strike cap on the broker's ``redelivered``
            flag, the only per-message redelivery signal classic queues
            carry. It also counts a redelivery caused by a crash or a lost
            connection, so one transient failure after a reconnect goes to
            the DLQ. For more attempts or delays use ``RetryConfig`` (delay
            queues). ``False`` restores the previous behaviour: transient
            errors requeue immediately with no cap, which hot-loops a
            poison message (thousands of handler runs per second).
        manual_settle_on_error: under ``AckPolicy.MANUAL``, a handler that
            raises WITHOUT settling its message gets the same failure
            settlement as ``AUTO`` (transient: requeue, bounded as above;
            permanent: dead-letter), logged with the action taken (default
            True). Without it the delivery stayed unacked until the channel
            closed, holding a prefetch slot; ``prefetch`` such failures
            stalled the consumer. Set False only if the handler settles
            through something other than ``RabbitMessage`` (a raw channel or
            a coalescing acker) and then re-raises: the pipeline cannot see
            that settlement and would settle the delivery a second time.
        processing_timeout: per-delivery handler deadline in seconds
            (``None`` = off, the default). On expiry ``HandlerTimeoutError``
            (``outcome_unknown=True``, transient) goes through the normal
            failure settlement. Async: the handler task is cancelled. Sync:
            the I/O thread settles the delivery at the deadline, but Python
            cannot interrupt a thread, so the handler keeps running (and
            keeps its worker) until it returns; its late result is
            discarded. With it set, sync handlers always run off the I/O
            thread: on the worker pool, or with ``worker_count=1`` on one
            dedicated handler thread (see ``docs/concurrency-model.md``).
        max_body_bytes: raw-body cap for deliveries, in bytes (``None`` =
            no cap, the default). A delivery whose body as received (before
            decompression or any ``on_receive`` hook) is larger is
            ``INVALID_MESSAGE``: rejected without requeue, so the source
            queue's dead-letter exchange moves it to the DLQ, without running
            any middleware or the handler. By default the broker dead-letters
            it, so the DLQ entry carries ``x-death`` but not rabbitkit's
            failure headers; with ``SafetyConfig.dead_letter_with_metadata``
            (async broker; set by the CRITICAL profile) it is a confirmed copy
            with them (``x-rabbitkit-error-category: invalid_message``).
            ``CompressionMiddleware`` caps the decompressed size separately.
    """

    prefetch_count: int = 10
    graceful_timeout: float = 30.0
    reject_transient_on_redelivery: bool = True
    manual_settle_on_error: bool = True
    processing_timeout: float | None = None
    max_body_bytes: int | None = None

    def __post_init__(self) -> None:
        # Architect review M1: prefetch_count=0 means AMQP "unlimited" — a
        # deep queue then buffers its whole backlog in process memory
        # (OOMKill → mass redelivery → crash loop). Nobody sets 0 on purpose
        # to mean that; reject it. graceful_timeout=0 is also nonsensical.
        if self.prefetch_count < 1:
            raise ConfigValidationError(
                f"ConsumerConfig.prefetch_count must be >= 1, got {self.prefetch_count} "
                "(0 would mean UNLIMITED prefetch in AMQP — the whole queue backlog "
                "buffered in process memory)."
            )
        if self.graceful_timeout <= 0:
            raise ConfigValidationError(f"ConsumerConfig.graceful_timeout must be > 0, got {self.graceful_timeout}")
        if self.processing_timeout is not None and self.processing_timeout <= 0:
            raise ConfigValidationError(
                f"ConsumerConfig.processing_timeout must be > 0 or None, got {self.processing_timeout}"
            )
        if self.max_body_bytes is not None and self.max_body_bytes < 1:
            raise ConfigValidationError(
                f"ConsumerConfig.max_body_bytes must be >= 1 or None, got {self.max_body_bytes}"
            )

PublisherConfig

PublisherConfig dataclass

Publisher behavior tuning.

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class PublisherConfig:
    """Publisher behavior tuning."""

    exchange: str = ""
    confirm_delivery: bool = True
    confirm_timeout: float = 5.0
    mandatory: bool = False
    persistent: bool = True
    # M10: reject oversized message bodies at publish time (bytes),
    # enforced by broker.publish() → MessageTooLargeError (a ValueError
    # subclass). Default mirrors RabbitMQ's
    # own server-side `max_message_size` default (16 MiB): the server would
    # reject a larger message anyway — but with a channel exception that
    # kills the (possibly pooled) publisher channel, corrupting sibling
    # in-flight publishes. Neither AMQP connection negotiation nor the
    # management API exposes the server's actual limit, so it cannot be
    # discovered at connect time — if you raised `max_message_size` in
    # rabbitmq.conf, raise this to match; 0 disables the client-side guard
    # entirely. Large messages are a RabbitMQ anti-pattern (memory pressure,
    # head-of-line blocking, slow recovery) — consider a tighter cap
    # (e.g. 1_048_576 for 1 MiB) and storing payloads externally.
    max_message_bytes: int = 16_777_216
    # Both brokers: cap on the sum of body bytes of publishes between
    # admission and their terminal outcome (async: single ``publish()`` and
    # the batch publisher share it; sync: every transport publish, including
    # worker-thread publishes waiting for the I/O thread). A body larger
    # than the budget is NOT_SENT(reason="exceeds_max_in_flight_bytes"); any
    # other publish waits FIFO (bounded by PoolConfig.channel_acquire_timeout
    # or, async only, its per-call ``timeout``) for room and then returns
    # NOT_SENT(reason="admission_timeout"). None (the
    # default) = no byte bound, the previous behaviour. Must be >= 1 and,
    # when ``max_message_bytes`` is set, >= ``max_message_bytes`` so every
    # admissible message fits.
    max_in_flight_bytes: int | None = None
    # remove rabbitkit's retry/DLQ/replay bookkeeping headers
    # (``x-rabbitkit-retry-count``, ``x-rabbitkit-first-failed-at``,
    # ``x-rabbitkit-original-queue`` ...) and the broker's ``x-death`` from
    # APPLICATION publishes (``broker.publish()`` and the bulk APIs built on
    # it), so a forged or copied header cannot make a new message skip its
    # retries. Also strips a custom ``RetryConfig.retry_header``. rabbitkit's
    # own retry / DLQ / replay republishes do not go through
    # ``broker.publish()`` and keep them. Default False (headers pass
    # through unchanged, the previous behaviour); the CRITICAL reliability
    # profile turns it on. See ``rabbitkit.core.reserved_headers``.
    strip_reserved_headers: bool = False

    def __post_init__(self) -> None:
        if self.max_in_flight_bytes is None:
            return
        if self.max_in_flight_bytes < 1:
            raise ConfigValidationError(
                f"PublisherConfig.max_in_flight_bytes must be >= 1 or None, got {self.max_in_flight_bytes}"
            )
        if self.max_message_bytes and self.max_in_flight_bytes < self.max_message_bytes:
            raise ConfigValidationError(
                f"PublisherConfig.max_in_flight_bytes ({self.max_in_flight_bytes}) must be >= "
                f"max_message_bytes ({self.max_message_bytes}), otherwise a message within the "
                "size limit could never be admitted. Lower max_message_bytes or raise the budget."
            )

PoolConfig

PoolConfig dataclass

Connection and channel pool sizing.

channel_pool_size (publisher channel pool) and channel_acquire_timeout are active. publisher_connections / consumer_connections are reserved and ignored (setting them changes nothing): the transport currently uses one connection per role, because multiple connections sharing a single event loop showed no throughput benefit in benchmarks (the loop is the bound). Scale throughput by running more processes/pods, not more connections per process.

Attributes:

Name Type Description
channel_pool_size int

Maximum publisher channels per pool (>= 1). On the async broker every confirmed publish holds one channel until its confirm arrives, so this is also the in-flight confirmed-publish cap.

channel_acquire_timeout float

Admission bound in seconds (> 0). A publish that cannot get a channel (pool exhausted) within it returns NOT_SENT with reason admission_timeout; exhaustion never rebuilds the connection. Also bounds opening one channel, and (both brokers) the wait for room in PublisherConfig.max_in_flight_bytes.

prewarm_channels bool

Pre-create all pool channels on connect().

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class PoolConfig:
    """Connection and channel pool sizing.

    ``channel_pool_size`` (publisher channel pool) and ``channel_acquire_timeout``
    are active. ``publisher_connections`` / ``consumer_connections`` are
    **reserved and ignored** (setting them changes nothing): the transport
    currently uses one connection per role, because multiple connections
    sharing a single event loop showed no throughput benefit in benchmarks
    (the loop is the bound). Scale throughput by running more processes/pods,
    not more connections per process.

    Attributes:
        channel_pool_size: Maximum publisher channels per pool (>= 1). On the
            async broker every confirmed publish holds one channel until its
            confirm arrives, so this is also the in-flight confirmed-publish
            cap.
        channel_acquire_timeout: Admission bound in seconds (> 0). A publish
            that cannot get a channel (pool exhausted) within it returns
            ``NOT_SENT`` with reason ``admission_timeout``; exhaustion never
            rebuilds the connection. Also bounds opening one channel, and
            (both brokers) the wait for room in
            ``PublisherConfig.max_in_flight_bytes``.
        prewarm_channels: Pre-create all pool channels on ``connect()``.
    """

    channel_pool_size: int = 10
    publisher_connections: int = 1  # reserved — see class docstring
    consumer_connections: int = 1  # reserved — see class docstring
    channel_acquire_timeout: float = 10.0  # seconds to wait for a pooled channel
    prewarm_channels: bool = False  # pre-create all pool channels on connect() to eliminate warmup jitter

    def __post_init__(self) -> None:
        if self.channel_pool_size < 1:
            raise ConfigValidationError(f"PoolConfig.channel_pool_size must be >= 1, got {self.channel_pool_size}")
        if not self.channel_acquire_timeout > 0:
            raise ConfigValidationError(
                f"PoolConfig.channel_acquire_timeout must be > 0, got {self.channel_acquire_timeout}"
            )

RetryConfig

RetryConfig dataclass

Retry with delay queues configuration.

Accepted by RetryMiddleware. Can be set as broker default (RabbitConfig.retry) or per-route override (route.retry_override).

delays must have at least max_retries entries. Extra retries beyond the length of delays would silently reuse the last delay, which is almost always a misconfiguration.

Durability knobs (plan §5.1) — all default to the legacy topology so an upgrade never re-declares an existing queue with different arguments:

  • delay_queue_type: "classic" (legacy default), "quorum", or "inherit" (match the source queue). Quorum delay queues make the retry chain replicated end-to-end for critical work; note that a quorum SOURCE does not by itself secure a classic delay queue.
  • dlq_queue_type: "inherit" (legacy default — quorum when the source is quorum), "classic", or "quorum".
  • error_detail: what goes into x-rabbitkit-error-message — "sanitized" (default: redacted + capped), "omit", or "raw" (legacy). See :mod:rabbitkit.core.sanitizer.
  • handoff: bounded behavior when the retry publish itself fails.

Retry policy:

  • max_retries / delays — the ladder (delays in whole seconds, one fixed-TTL delay queue per tier). :meth:exponential builds delays from initial_delay / multiplier / max_delay.
  • max_retry_age (seconds, None = unbounded) — a transient failure more than this long after the message's FIRST failure (x-rabbitkit-first-failed-at) is terminal (category retry-age-exceeded) even with retries left.
  • terminal_action — :class:~rabbitkit.core.types.TerminalAction: "dead_letter" (default) publishes a confirmed, metadata-stamped copy to <queue>.dlq before acking; "reject" is the legacy broker dead-letter path.
  • Jitter: jitter_factor only takes effect with jitter_mode="sharded". Per-message TTL jitter is deliberately not offered: a classic queue expires messages only at its head, so a message with a long TTL blocks every shorter one behind it.

Trust model: the retry count, first-failure timestamp and original-* headers travel on the message and are client-controlled. rabbitkit never lowers them on its own republish, takes the larger of the header count and the broker's x-death history for this queue's delay tiers, and clamps to max_retries; a producer that strips every header restarts the budget — max_retry_age and a quorum source's x-delivery-limit bound that case. A producer that sets the header HIGH skips retries; trust_retry_header=False closes that by counting only the x-death entries the broker adds when a copy expires out of a <queue>.retry.<n> delay queue (the header is then informational). Leave it True for TestBroker suites that simulate later attempts by setting the header, since the in-memory broker writes no x-death.

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class RetryConfig:
    """Retry with delay queues configuration.

    Accepted by RetryMiddleware. Can be set as broker default
    (RabbitConfig.retry) or per-route override (route.retry_override).

    ``delays`` must have at least ``max_retries`` entries.  Extra retries
    beyond the length of ``delays`` would silently reuse the last delay,
    which is almost always a misconfiguration.

    Durability knobs (plan §5.1) — all default to the legacy topology so an
    upgrade never re-declares an existing queue with different arguments:

    * ``delay_queue_type``: ``"classic"`` (legacy default), ``"quorum"``, or
      ``"inherit"`` (match the source queue). Quorum delay queues make the
      retry chain replicated end-to-end for critical work; note that a
      quorum SOURCE does not by itself secure a classic delay queue.
    * ``dlq_queue_type``: ``"inherit"`` (legacy default — quorum when the
      source is quorum), ``"classic"``, or ``"quorum"``.
    * ``error_detail``: what goes into ``x-rabbitkit-error-message`` —
      ``"sanitized"`` (default: redacted + capped), ``"omit"``, or ``"raw"``
      (legacy). See :mod:`rabbitkit.core.sanitizer`.
    * ``handoff``: bounded behavior when the retry publish itself fails.

    Retry policy:

    * ``max_retries`` / ``delays`` — the ladder (delays in whole seconds,
      one fixed-TTL delay queue per tier). :meth:`exponential` builds
      ``delays`` from ``initial_delay`` / ``multiplier`` / ``max_delay``.
    * ``max_retry_age`` (seconds, ``None`` = unbounded) — a transient
      failure more than this long after the message's FIRST failure
      (``x-rabbitkit-first-failed-at``) is terminal (category
      ``retry-age-exceeded``) even with retries left.
    * ``terminal_action`` — :class:`~rabbitkit.core.types.TerminalAction`:
      ``"dead_letter"`` (default) publishes a confirmed, metadata-stamped
      copy to ``<queue>.dlq`` before acking; ``"reject"`` is the legacy
      broker dead-letter path.
    * Jitter: ``jitter_factor`` only takes effect with
      ``jitter_mode="sharded"``. Per-message TTL jitter is deliberately not
      offered: a classic queue expires messages only at its head, so a
      message with a long TTL blocks every shorter one behind it.

    Trust model: the retry count, first-failure timestamp and original-*
    headers travel on the message and are client-controlled. rabbitkit
    never lowers them on its own republish, takes the larger of the header
    count and the broker's ``x-death`` history for this queue's delay
    tiers, and clamps to ``max_retries``; a producer that strips every
    header restarts the budget — ``max_retry_age`` and a quorum source's
    ``x-delivery-limit`` bound that case. A producer that sets the header
    HIGH skips retries; ``trust_retry_header=False`` closes that by counting
    only the ``x-death`` entries the broker adds when a copy expires out of
    a ``<queue>.retry.<n>`` delay queue (the header is then informational).
    Leave it ``True`` for ``TestBroker`` suites that simulate later attempts
    by setting the header, since the in-memory broker writes no ``x-death``.
    """

    max_retries: int = 4
    delays: tuple[int, ...] = (5, 30, 120, 600)
    retry_header: str = "x-rabbitkit-retry-count"
    # Only used with jitter_mode="sharded" (TTL spread across shard queues).
    # With jitter_mode="off" it has no effect: per-message TTL jitter would
    # reintroduce head-of-line blocking on classic delay queues.
    jitter_factor: float = 0.1
    # F4: "off" (default — single delay queue per tier, exact legacy topology)
    # or "sharded" — each tier becomes jitter_shards sub-queues with uniform
    # TTLs staggered across ±jitter_factor; a message picks its shard by a
    # STABLE hash of its message_id, decorrelating retry waves across the
    # fleet WITHOUT per-message TTL (which would reintroduce classic-queue
    # head-of-line blocking). Shard 0 keeps the legacy queue name/TTL, so
    # enabling this on an existing topology is additive (no 406s).
    jitter_mode: str = "off"
    jitter_shards: int = 3
    # DEPRECATED, never used: the DLQ is always "<queue>.dlq" reached via the
    # default exchange. A non-empty value warns.
    dead_letter_exchange: str = ""
    per_queue: bool = True
    unknown_policy: ErrorSeverity = ErrorSeverity.PERMANENT
    strict_delays: bool = True
    delay_queue_type: str = "classic"
    dlq_queue_type: str = "inherit"
    error_detail: str = "sanitized"
    handoff: RetryHandoffConfig = field(default_factory=RetryHandoffConfig)
    max_retry_age: float | None = None
    terminal_action: TerminalAction = TerminalAction.DEAD_LETTER
    # Quorum options for the retry chain (applied only to the delay queues /
    # DLQ that resolve to quorum). None = broker defaults = legacy topology.
    quorum_initial_group_size: int | None = None
    # x-dead-letter-strategy for QUORUM delay queues: "at-least-once" keeps an
    # expired message on the delay queue until the source queue confirms it
    # (also sets x-overflow=reject-publish on them, which RabbitMQ requires).
    delay_queue_dead_letter_strategy: str | None = None
    # True (legacy) = the attempt count is the larger of the
    # retry_header value and the broker's x-death history. False = only the
    # x-death history counts: a producer cannot skip (or restart) retries by
    # setting the header. The header is still written for observability.
    trust_retry_header: bool = True

    def __post_init__(self) -> None:
        if self.max_retries < 0:
            raise ConfigValidationError(f"RetryConfig.max_retries must be >= 0, got {self.max_retries}")
        try:
            object.__setattr__(self, "terminal_action", TerminalAction(self.terminal_action))
        except ValueError:
            raise ConfigValidationError(
                f"RetryConfig.terminal_action must be one of {[a.value for a in TerminalAction]}, "
                f"got {self.terminal_action!r}"
            ) from None
        if self.quorum_initial_group_size is not None and self.quorum_initial_group_size < 1:
            raise ConfigValidationError(
                f"RetryConfig.quorum_initial_group_size must be >= 1, got {self.quorum_initial_group_size}"
            )
        if self.delay_queue_dead_letter_strategy not in (None, "at-most-once", "at-least-once"):
            raise ConfigValidationError(
                "RetryConfig.delay_queue_dead_letter_strategy must be None, 'at-most-once' or "
                f"'at-least-once', got {self.delay_queue_dead_letter_strategy!r}"
            )
        if self.delay_queue_dead_letter_strategy is not None and self.delay_queue_type == "classic":
            raise ConfigValidationError(
                "RetryConfig.delay_queue_dead_letter_strategy needs quorum delay queues "
                "(delay_queue_type='quorum' or 'inherit'); classic queues have no dead-letter strategy"
            )
        if self.max_retry_age is not None and self.max_retry_age <= 0:
            raise ConfigValidationError(f"RetryConfig.max_retry_age must be > 0 seconds, got {self.max_retry_age}")
        if any(d < 0 for d in self.delays):
            raise ConfigValidationError(f"RetryConfig.delays must be >= 0 seconds, got {self.delays}")
        if self.dead_letter_exchange:
            warnings.warn(
                "RetryConfig.dead_letter_exchange is deprecated and has never been used: retry "
                "dead-letters to '<queue>.dlq' through the default exchange. Remove the argument; "
                "for an infrastructure-managed dead-letter exchange use terminal_action='reject' "
                "with TopologyMode.PASSIVE_ONLY.",
                DeprecationWarning,
                stacklevel=3,
            )
        if self.delay_queue_type not in RETRY_QUEUE_TYPES:
            raise ConfigValidationError(
                f"RetryConfig.delay_queue_type must be one of {RETRY_QUEUE_TYPES}, got {self.delay_queue_type!r}"
            )
        if self.dlq_queue_type not in RETRY_QUEUE_TYPES:
            raise ConfigValidationError(
                f"RetryConfig.dlq_queue_type must be one of {RETRY_QUEUE_TYPES}, got {self.dlq_queue_type!r}"
            )
        if self.error_detail not in ("sanitized", "omit", "raw"):
            raise ConfigValidationError(
                f"RetryConfig.error_detail must be 'sanitized', 'omit' or 'raw', got {self.error_detail!r}"
            )
        if self.jitter_mode not in ("off", "sharded"):
            raise ConfigValidationError(f"RetryConfig.jitter_mode must be 'off' or 'sharded', got {self.jitter_mode!r}")
        if self.jitter_mode == "sharded":
            if self.jitter_shards < 2:
                raise ConfigValidationError(
                    f"RetryConfig.jitter_shards must be >= 2 with jitter_mode='sharded', got {self.jitter_shards}"
                )
            if not (0 < self.jitter_factor < 1):
                raise ConfigValidationError(
                    "RetryConfig.jitter_factor must be in (0, 1) with jitter_mode='sharded' "
                    f"(it sets the TTL spread), got {self.jitter_factor}"
                )
        if not self.per_queue:
            # H3: shared delay queues (rabbitkit.retry.N) bake a single
            # x-dead-letter-routing-key into each queue at declare time. That
            # key can only point at ONE source queue, so with >1 subscriber
            # they either 406 at startup (conflicting args) or silently
            # dead-letter every queue's failures back to whichever queue
            # declared first — cross-queue misdelivery (orders' failures
            # reappearing on payments). A shared delay queue physically
            # cannot route each message back to its own varying source with
            # static broker config, so there is no safe shared topology.
            raise ConfigValidationError(
                "RetryConfig(per_queue=False) is unsafe and unsupported: shared "
                "delay queues misroute failed messages across source queues (or "
                "406 at startup). Use per_queue=True (the default), which gives "
                "each queue isolated '<queue>.retry.N'/'<queue>.dlq' topology."
            )
        if len(self.delays) < self.max_retries:
            msg = (
                f"RetryConfig.delays has {len(self.delays)} entries but max_retries={self.max_retries}. "
                "Retries beyond the last delay entry will reuse the last delay value, "
                "which is almost always a misconfiguration. Provide at least max_retries "
                "delay values, or set strict_delays=False to allow the flat-tail behavior."
            )
            if self.strict_delays:
                raise ConfigValidationError(msg)
            warnings.warn(msg, UserWarning, stacklevel=2)

    @classmethod
    def exponential(
        cls,
        *,
        max_retries: int = 4,
        initial_delay: float = 5.0,
        multiplier: float = 2.0,
        max_delay: float = 600.0,
        **kwargs: Any,
    ) -> RetryConfig:
        """Build a ``RetryConfig`` whose ``delays`` follow a capped exponential.

        ``delays[i] = min(max_delay, initial_delay * multiplier ** i)``,
        rounded to whole seconds (minimum 1) because each tier is a delay
        queue with a fixed ``x-message-ttl``. Every other field is passed
        through ``kwargs``.
        """
        if initial_delay <= 0:
            raise ConfigValidationError(f"initial_delay must be > 0, got {initial_delay}")
        if multiplier < 1:
            raise ConfigValidationError(f"multiplier must be >= 1, got {multiplier}")
        if max_delay < initial_delay:
            raise ConfigValidationError(f"max_delay ({max_delay}) must be >= initial_delay ({initial_delay})")
        delays: list[int] = []
        current = float(initial_delay)
        for _ in range(max_retries):
            delays.append(max(1, round(min(max_delay, current))))
            current = min(max_delay, current * multiplier)
        return cls(max_retries=max_retries, delays=tuple(delays), **kwargs)

Methods:

exponential(*, max_retries: int = 4, initial_delay: float = 5.0, multiplier: float = 2.0, max_delay: float = 600.0, **kwargs: Any) -> RetryConfig classmethod

Build a RetryConfig whose delays follow a capped exponential.

delays[i] = min(max_delay, initial_delay * multiplier ** i), rounded to whole seconds (minimum 1) because each tier is a delay queue with a fixed x-message-ttl. Every other field is passed through kwargs.

Source code in src/rabbitkit/core/config.py
@classmethod
def exponential(
    cls,
    *,
    max_retries: int = 4,
    initial_delay: float = 5.0,
    multiplier: float = 2.0,
    max_delay: float = 600.0,
    **kwargs: Any,
) -> RetryConfig:
    """Build a ``RetryConfig`` whose ``delays`` follow a capped exponential.

    ``delays[i] = min(max_delay, initial_delay * multiplier ** i)``,
    rounded to whole seconds (minimum 1) because each tier is a delay
    queue with a fixed ``x-message-ttl``. Every other field is passed
    through ``kwargs``.
    """
    if initial_delay <= 0:
        raise ConfigValidationError(f"initial_delay must be > 0, got {initial_delay}")
    if multiplier < 1:
        raise ConfigValidationError(f"multiplier must be >= 1, got {multiplier}")
    if max_delay < initial_delay:
        raise ConfigValidationError(f"max_delay ({max_delay}) must be >= initial_delay ({initial_delay})")
    delays: list[int] = []
    current = float(initial_delay)
    for _ in range(max_retries):
        delays.append(max(1, round(min(max_delay, current))))
        current = min(max_delay, current * multiplier)
    return cls(max_retries=max_retries, delays=tuple(delays), **kwargs)

RetryHandoffConfig

RetryHandoffConfig dataclass

Bounded behavior when the RETRY PUBLISH itself fails (plan §5.2).

A handler failure and a failure to hand the message to its delay queue are different events. When the delay-queue publish is returned, nacked, times out, or the connection drops, RetryMiddleware never acks the source (it nack-requeues it) — but without a brake that is a hot redelivery loop against a broken destination. This config bounds that loop:

  • backoff_initial / backoff_max / jitter shape a capped exponential delay applied per consecutive handoff failure (async handlers await asyncio.sleep; the sync path never sleeps on the I/O thread — it reports the backoff through the on_handoff_failure hook so the broker/worker can pause admission instead).
  • max_consecutive_failures and recovery_deadline define when the tracker reports exhausted so an owner can stop the consumer and let the broker redeliver instead of spinning.
Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class RetryHandoffConfig:
    """Bounded behavior when the RETRY PUBLISH itself fails (plan §5.2).

    A handler failure and a failure to hand the message to its delay queue
    are different events. When the delay-queue publish is returned,
    nacked, times out, or the connection drops, ``RetryMiddleware`` never
    acks the source (it nack-requeues it) — but without a brake that is a
    hot redelivery loop against a broken destination. This config bounds
    that loop:

    * ``backoff_initial`` / ``backoff_max`` / ``jitter`` shape a capped
      exponential delay applied per consecutive handoff failure (async
      handlers ``await asyncio.sleep``; the sync path never sleeps on the
      I/O thread — it reports the backoff through the ``on_handoff_failure``
      hook so the broker/worker can pause admission instead).
    * ``max_consecutive_failures`` and ``recovery_deadline`` define when the
      tracker reports ``exhausted`` so an owner can stop the consumer and
      let the broker redeliver instead of spinning.
    """

    backoff_initial: float = 0.5
    backoff_max: float = 30.0
    jitter: float = 0.2
    max_consecutive_failures: int = 20
    recovery_deadline: float = 300.0

    def __post_init__(self) -> None:
        if self.backoff_initial <= 0:
            raise ConfigValidationError(f"RetryHandoffConfig.backoff_initial must be > 0, got {self.backoff_initial}")
        if self.backoff_max < self.backoff_initial:
            raise ConfigValidationError(
                f"RetryHandoffConfig.backoff_max ({self.backoff_max}) must be >= backoff_initial "
                f"({self.backoff_initial})"
            )
        if not (0 <= self.jitter < 1):
            raise ConfigValidationError(f"RetryHandoffConfig.jitter must be in [0, 1), got {self.jitter}")
        if self.max_consecutive_failures < 1:
            raise ConfigValidationError(
                f"RetryHandoffConfig.max_consecutive_failures must be >= 1, got {self.max_consecutive_failures}"
            )
        if self.recovery_deadline <= 0:
            raise ConfigValidationError(
                f"RetryHandoffConfig.recovery_deadline must be > 0, got {self.recovery_deadline}"
            )

BulkPublishOptions

BulkPublishOptions dataclass

Bounds for one publish_many / iter_publish operation.

Every bound is explicit; none is a tuning recommendation. The defaults are conservative starting points — measure before changing them.

Attributes:

Name Type Description
max_in_flight int

Maximum envelopes submitted to the transport but not yet settled (async broker). Without an AsyncBatchPublisher each in-flight publish holds one pooled channel, so the broker caps the effective value at PoolConfig.channel_pool_size (default 10) — raise the pool or configure batching for more concurrency. The sync broker publishes one at a time; the value is validated but has no effect there.

max_buffer_bytes int

Maximum sum of in-flight body bytes. An envelope larger than this can never be admitted and is reported INVALID (exceeds_max_buffer_bytes) without being sent.

admission_timeout float

Seconds to wait for an in-flight/byte slot before reporting an item NOT_SENT (admission_timeout).

confirm_timeout float | None

Per-item confirm wait override (async broker). A timeout reports UNKNOWN (confirm_timeout) — the publish may have reached the broker. None uses the transport's configured PublisherConfig.confirm_timeout.

overall_timeout float | None

Whole-operation deadline. On expiry admission stops; never-submitted items are NOT_SENT (overall_timeout), in-flight items are given drain_grace seconds to settle and then reported UNKNOWN (overall_timeout). None = no operation deadline (each item still bounded individually).

drain_grace float

Seconds to wait for in-flight items after the overall deadline before classifying them UNKNOWN.

max_items int

Upper bound on publish_many input length. Exceeding it raises ValueError BEFORE anything is published — a bulk call is a bounded finite collection; use iter_publish for streams.

Source code in src/rabbitkit/core/bulk.py
@dataclass(frozen=True, slots=True)
class BulkPublishOptions:
    """Bounds for one ``publish_many`` / ``iter_publish`` operation.

    Every bound is explicit; none is a tuning recommendation. The defaults are
    conservative starting points — measure before changing them.

    Attributes:
        max_in_flight: Maximum envelopes submitted to the transport but not
            yet settled (async broker). Without an ``AsyncBatchPublisher``
            each in-flight publish holds one pooled channel, so the broker
            caps the effective value at ``PoolConfig.channel_pool_size``
            (default 10) — raise the pool or configure batching for more
            concurrency. The sync broker publishes one at a time; the value
            is validated but has no effect there.
        max_buffer_bytes: Maximum sum of in-flight body bytes. An envelope
            larger than this can never be admitted and is reported
            ``INVALID`` (``exceeds_max_buffer_bytes``) without being sent.
        admission_timeout: Seconds to wait for an in-flight/byte slot before
            reporting an item ``NOT_SENT`` (``admission_timeout``).
        confirm_timeout: Per-item confirm wait override (async broker). A
            timeout reports ``UNKNOWN`` (``confirm_timeout``) — the publish
            may have reached the broker. ``None`` uses the transport's
            configured ``PublisherConfig.confirm_timeout``.
        overall_timeout: Whole-operation deadline. On expiry admission stops;
            never-submitted items are ``NOT_SENT`` (``overall_timeout``),
            in-flight items are given ``drain_grace`` seconds to settle and
            then reported ``UNKNOWN`` (``overall_timeout``). ``None`` = no
            operation deadline (each item still bounded individually).
        drain_grace: Seconds to wait for in-flight items after the overall
            deadline before classifying them ``UNKNOWN``.
        max_items: Upper bound on ``publish_many`` input length. Exceeding it
            raises ``ValueError`` BEFORE anything is published — a bulk call
            is a bounded finite collection; use ``iter_publish`` for streams.
    """

    max_in_flight: int = 256
    max_buffer_bytes: int = 8 * 1024 * 1024
    admission_timeout: float = 5.0
    confirm_timeout: float | None = None
    overall_timeout: float | None = 30.0
    drain_grace: float = 2.0
    max_items: int = 100_000

    def __post_init__(self) -> None:
        if self.max_in_flight < 1:
            raise ConfigValidationError(f"BulkPublishOptions.max_in_flight must be >= 1, got {self.max_in_flight}")
        if self.max_buffer_bytes < 1:
            raise ConfigValidationError(
                f"BulkPublishOptions.max_buffer_bytes must be >= 1, got {self.max_buffer_bytes}"
            )
        if self.admission_timeout <= 0:
            raise ConfigValidationError(
                f"BulkPublishOptions.admission_timeout must be > 0, got {self.admission_timeout}"
            )
        if self.confirm_timeout is not None and self.confirm_timeout <= 0:
            raise ConfigValidationError(
                f"BulkPublishOptions.confirm_timeout must be > 0 when set, got {self.confirm_timeout}"
            )
        if self.overall_timeout is not None and self.overall_timeout <= 0:
            raise ConfigValidationError(
                f"BulkPublishOptions.overall_timeout must be > 0 when set, got {self.overall_timeout}"
            )
        if self.drain_grace < 0:
            raise ConfigValidationError(f"BulkPublishOptions.drain_grace must be >= 0, got {self.drain_grace}")
        if self.max_items < 1:
            raise ConfigValidationError(f"BulkPublishOptions.max_items must be >= 1, got {self.max_items}")

CompressionConfig

CompressionConfig dataclass

Compression configuration.

Accepted by CompressionMiddleware.

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class CompressionConfig:
    """Compression configuration.

    Accepted by CompressionMiddleware.
    """

    algorithm: str = "gzip"
    threshold: int = 1024
    level: int = 6

SocketConfig

SocketConfig dataclass

Low-level TCP tuning.

Applied best-effort — not all options are universally guaranteed depending on OS and backend internals.

Sync-only. SyncBroker applies these via pika's tcp_options; AsyncBroker emits a RuntimeWarning and ignores a non-default value — aio-pika/aiormq exposes no socket-tuning hooks, and per-socket tuning would be silently lost on every automatic reconnect. Tune the async side via ConnectionConfig (heartbeat, timeouts) or at the OS level.

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class SocketConfig:
    """Low-level TCP tuning.

    Applied best-effort — not all options are universally guaranteed
    depending on OS and backend internals.

    **Sync-only.** ``SyncBroker`` applies these via pika's ``tcp_options``;
    ``AsyncBroker`` emits a ``RuntimeWarning`` and ignores a non-default
    value — aio-pika/aiormq exposes no socket-tuning hooks, and per-socket
    tuning would be silently lost on every automatic reconnect. Tune the
    async side via ``ConnectionConfig`` (heartbeat, timeouts) or at the
    OS level.
    """

    tcp_nodelay: bool = True
    tcp_keepidle: int = 10
    tcp_keepintvl: int = 5
    tcp_keepcnt: int = 3
    tcp_sndbuf: int = 196608  # 192KB
    tcp_rcvbuf: int = 196608  # 192KB

SSLConfig

SSLConfig dataclass

TLS/SSL configuration.

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class SSLConfig:
    """TLS/SSL configuration."""

    enabled: bool = False
    certfile: str | None = None
    keyfile: str | None = None
    ca_certs: str | None = None
    cert_reqs: str = "CERT_REQUIRED"
    server_hostname: str | None = None

SecurityConfig

SecurityConfig dataclass

SASL + authentication configuration.

Only mechanism="PLAIN" is implemented (username/password). EXTERNAL (x509 client-cert auth) is not wired into either transport, so accepting it silently would be "config that lies" — it is rejected at construction (M2). mTLS is still supported for transport encryption via SSLConfig(certfile=..., keyfile=...); it just isn't an auth mechanism.

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class SecurityConfig:
    """SASL + authentication configuration.

    Only ``mechanism="PLAIN"`` is implemented (username/password). ``EXTERNAL``
    (x509 client-cert auth) is not wired into either transport, so accepting
    it silently would be "config that lies" — it is rejected at construction
    (M2). mTLS is still supported for transport *encryption* via
    ``SSLConfig(certfile=..., keyfile=...)``; it just isn't an auth mechanism.
    """

    mechanism: str = "PLAIN"
    ssl: SSLConfig = field(default_factory=SSLConfig)

    def __post_init__(self) -> None:
        if self.mechanism != "PLAIN":
            raise ConfigValidationError(
                f"SecurityConfig.mechanism={self.mechanism!r} is not supported — only "
                "'PLAIN' (username/password) is implemented. SASL EXTERNAL/x509-auth is "
                "not wired into the transports. For TLS client certs (encryption, not "
                "auth), use SSLConfig(certfile=..., keyfile=...)."
            )

WorkerConfig

WorkerConfig dataclass

Consumer concurrency configuration.

Accepted by broker.start(), NOT part of RabbitConfig. Added in 0.2.0.

Concurrency semantics, per queue:

  • worker_count >= 2: a worker pool of that size runs the handlers; prefetch is worker_count * prefetch_per_worker when prefetch_per_worker is set.
  • worker_count == 1 (the default) creates NO pool, and prefetch_per_worker is ignored. On the async broker every delivery then runs as its own task, so up to prefetch_count handlers of one queue run concurrently -- worker_count=1 does not serialize async handlers. Use prefetch_count=1 (or a lock in the handler) for one-at-a-time processing. On the sync broker handlers run inline on the I/O thread, one at a time (with ConsumerConfig.processing_timeout set: one at a time on one dedicated handler thread, so the I/O thread can enforce the deadline).

stop_timeout (H12): a FALLBACK drain deadline for the worker pool's stop() — consulted only when no explicit timeout is passed. On the standard shutdown path (broker.stop()) the pool drain budget is ConsumerConfig.graceful_timeout, NOT this field — tune THAT (and keep terminationGracePeriodSeconds a few seconds above it) for Kubernetes; setting only stop_timeout there has no effect (architect review M2 — the old text here said the opposite). stop_timeout matters when you drive a worker pool directly. A handler still running past this deadline is abandoned, not killed: the sync pool's daemon thread keeps running in the background (it is never forcibly stopped — Python cannot interrupt an arbitrary thread), and the async pool cancels the task (which does not guarantee the handler reaches its own ack/nack — CancelledError is a BaseException and is not caught by the pipeline's exception handling). Either way the abandoned delivery is logged by delivery tag/message id, and — for the async pool — nacked for redelivery immediately rather than relying on the implicit requeue that happens when the connection eventually closes. Because the original handler may still complete its side effects after abandonment, handlers must be idempotent under at-least-once delivery regardless of stop_timeout.

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class WorkerConfig:
    """Consumer concurrency configuration.

    Accepted by broker.start(), NOT part of RabbitConfig. Added in 0.2.0.

    Concurrency semantics, per queue:

    * ``worker_count >= 2``: a worker pool of that size runs the handlers;
      prefetch is ``worker_count * prefetch_per_worker`` when
      ``prefetch_per_worker`` is set.
    * ``worker_count == 1`` (the default) creates NO pool, and
      ``prefetch_per_worker`` is ignored. On the **async** broker every
      delivery then runs as its own task, so up to ``prefetch_count``
      handlers of one queue run concurrently -- ``worker_count=1`` does
      **not** serialize async handlers. Use ``prefetch_count=1`` (or a
      lock in the handler) for one-at-a-time processing. On the **sync**
      broker handlers run inline on the I/O thread, one at a time (with
      ``ConsumerConfig.processing_timeout`` set: one at a time on one
      dedicated handler thread, so the I/O thread can enforce the deadline).

    ``stop_timeout`` (H12): a FALLBACK drain deadline for the worker pool's
    ``stop()`` — consulted only when no explicit timeout is passed. On the
    standard shutdown path (``broker.stop()``) the pool drain budget is
    **``ConsumerConfig.graceful_timeout``**, NOT this field — tune THAT (and
    keep ``terminationGracePeriodSeconds`` a few seconds above it) for
    Kubernetes; setting only ``stop_timeout`` there has no effect
    (architect review M2 — the old text here said the opposite).
    ``stop_timeout`` matters when you drive a worker pool directly. A
    handler still running past this deadline is **abandoned, not killed**:
    the sync pool's daemon thread keeps running in the background (it is
    never forcibly stopped — Python cannot interrupt an arbitrary thread),
    and the async pool cancels the task (which does not guarantee the
    handler reaches its own ack/nack — ``CancelledError`` is a
    ``BaseException`` and is not caught by the pipeline's exception
    handling). Either way the abandoned delivery is logged by delivery
    tag/message id, and — for the async pool — nacked for redelivery
    immediately rather than relying on the implicit requeue that happens
    when the connection eventually closes. Because the original handler may
    still complete its side effects after abandonment, **handlers must be
    idempotent under at-least-once delivery** regardless of ``stop_timeout``.
    """

    worker_count: int = 1
    prefetch_per_worker: int | None = None
    stop_timeout: float = 30.0
    # M11: bound the sync worker pool's internal work queue. 0 = unbounded
    # (default, unchanged). In practice the broker's prefetch already caps
    # in-flight messages (effective prefetch = worker_count x
    # prefetch_per_worker), so this is a defensive ceiling — set it >= your
    # effective prefetch so it only trips if prefetch isn't being honored.
    # When the queue is full, submit() blocks (backpressure); keep it above
    # prefetch so that never happens on the I/O thread.
    max_queue_size: int = 0

    def __post_init__(self) -> None:
        if self.worker_count < 1:
            raise ConfigValidationError(f"WorkerConfig.worker_count must be >= 1, got {self.worker_count}")
        if self.max_queue_size < 0:
            raise ConfigValidationError(f"WorkerConfig.max_queue_size must be >= 0, got {self.max_queue_size}")
        # Architect review M1: prefetch_per_worker=0 made the effective
        # prefetch worker_count * 0 = 0 = AMQP "unlimited" — see
        # ConsumerConfig.prefetch_count for why that is never intended.
        if self.prefetch_per_worker is not None and self.prefetch_per_worker < 1:
            raise ConfigValidationError(
                f"WorkerConfig.prefetch_per_worker must be >= 1 when set, got "
                f"{self.prefetch_per_worker} (0 would make the effective prefetch "
                "UNLIMITED, not disabled)."
            )

BackpressureConfig

BackpressureConfig dataclass

Backpressure configuration. Active.

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class BackpressureConfig:
    """Backpressure configuration. Active."""

    max_in_flight: int = 1000
    rate_limit: int | None = None
    blocked_timeout: float = 60.0
    on_blocked: str = "wait"
    poll_interval_ms: int = 10

BatchPublishConfig

BatchPublishConfig dataclass

Batch publish configuration. Active.

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class BatchPublishConfig:
    """Batch publish configuration. Active."""

    batch_size: int = 100
    flush_interval_ms: int = 50
    max_in_flight: int = 1000
    flush_workers: int = 0  # 0 = auto (min(16, max_in_flight // batch_size)); >0 = explicit count

    def __post_init__(self) -> None:
        if self.batch_size <= 0:
            raise ConfigValidationError(f"BatchPublishConfig.batch_size must be > 0, got {self.batch_size}")
        if self.flush_interval_ms < 0:
            raise ConfigValidationError(
                f"BatchPublishConfig.flush_interval_ms must be >= 0, got {self.flush_interval_ms}"
            )
        if self.max_in_flight <= 0:
            raise ConfigValidationError(f"BatchPublishConfig.max_in_flight must be > 0, got {self.max_in_flight}")
        if self.flush_workers < 0:
            raise ConfigValidationError(f"BatchPublishConfig.flush_workers must be >= 0, got {self.flush_workers}")

BatchAckConfig

BatchAckConfig dataclass

Batch ack configuration. Active.

mode (plan §4.1):

  • "individual" (default, SAFE) — every buffered tag is acked with its own multiple=False frame. Out-of-order completion can never settle a delivery that was not submitted.
  • "cumulative" — legacy ack(max_tag, multiple=True). RabbitMQ settles EVERY outstanding tag up to max_tag on the channel, so a still-running sibling delivery gets acked early unless this helper is the only thing that ever acks on that channel AND completions are submitted in tag order. Requires ordered_exclusive_owner=True as an explicit attestation; otherwise construction fails. For safe coalescing with arbitrary completion order use :class:rabbitkit.highload.batch.CoalescingAcker instead.
Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class BatchAckConfig:
    """Batch ack configuration. Active.

    ``mode`` (plan §4.1):

    * ``"individual"`` (default, SAFE) — every buffered tag is acked with
      its own ``multiple=False`` frame. Out-of-order completion can never
      settle a delivery that was not submitted.
    * ``"cumulative"`` — legacy ``ack(max_tag, multiple=True)``. RabbitMQ
      settles EVERY outstanding tag up to ``max_tag`` on the channel, so a
      still-running sibling delivery gets acked early unless this helper is
      the only thing that ever acks on that channel AND completions are
      submitted in tag order. Requires ``ordered_exclusive_owner=True`` as
      an explicit attestation; otherwise construction fails. For safe
      coalescing with arbitrary completion order use
      :class:`rabbitkit.highload.batch.CoalescingAcker` instead.
    """

    batch_size: int = 100
    flush_interval_ms: int = 200
    mode: str = "individual"
    ordered_exclusive_owner: bool = False

    def __post_init__(self) -> None:
        if self.batch_size <= 0:
            raise ConfigValidationError(f"BatchAckConfig.batch_size must be > 0, got {self.batch_size}")
        if self.flush_interval_ms < 0:
            raise ConfigValidationError(f"BatchAckConfig.flush_interval_ms must be >= 0, got {self.flush_interval_ms}")
        if self.mode not in BATCH_ACK_MODES:
            raise ConfigValidationError(f"BatchAckConfig.mode must be one of {BATCH_ACK_MODES}, got {self.mode!r}")
        if self.mode == "cumulative" and not self.ordered_exclusive_owner:
            raise ConfigValidationError(
                "BatchAckConfig(mode='cumulative') issues ack(max_tag, multiple=True), which settles EVERY "
                "outstanding delivery on the channel up to max_tag — including ones still being processed. "
                "It is only safe when this acker is the channel's sole settler and completions arrive in "
                "tag order. Set ordered_exclusive_owner=True to attest to that, or keep mode='individual' "
                "(the default), or use CoalescingAcker for safe out-of-order coalescing."
            )

DeduplicationConfig

DeduplicationConfig dataclass

Deduplication configuration. Active.

mark_policy accepts a :class:~rabbitkit.core.types.DeduplicationMarkPolicy member or its string value:

  • "on_success" (default) — crash-safe; concurrent duplicates may both run.
  • "on_start" — blocks concurrent duplicates but a crash mid-handler LOSES the message. Advanced/dangerous.
  • "claim" — in-flight claim (processing_timeout) before the handler, "completed" (ttl) after success. Blocks concurrent duplicates and survives crashes; processing_timeout must comfortably exceed the worst-case handler duration or a duplicate can start while the original is still running.
Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class DeduplicationConfig:
    """Deduplication configuration. Active.

    ``mark_policy`` accepts a :class:`~rabbitkit.core.types.DeduplicationMarkPolicy`
    member or its string value:

    - ``"on_success"`` (default) — crash-safe; concurrent duplicates may both run.
    - ``"on_start"`` — blocks concurrent duplicates but a crash mid-handler
      LOSES the message. Advanced/dangerous.
    - ``"claim"`` — in-flight claim (``processing_timeout``) before the
      handler, "completed" (``ttl``) after success. Blocks concurrent
      duplicates and survives crashes; ``processing_timeout`` must
      comfortably exceed the worst-case handler duration or a duplicate can
      start while the original is still running.
    """

    key_prefix: str = "rabbitkit:dedup"
    ttl: int = 86400
    fallback_on_redis_error: bool = True
    key_source: str = "message_id"
    mark_policy: str = "on_success"
    local_cache_size: int = 0  # 0 = disabled; >0 = in-process LRU capacity (short-circuits Redis for known duplicates)
    processing_timeout: int = 300  # claim only: in-flight claim TTL (seconds)
    # F5 (idempotent receiver): with mark_policy="claim", store the handler's
    # JSON-serializable result alongside the completed mark; a duplicate
    # delivery then REPLAYS the stored result (the pipeline re-publishes it to
    # the route's result publisher / reply_to, byte-identical) instead of just
    # skipping. Results that aren't JSON-serializable or exceed
    # max_result_bytes degrade gracefully to plain skip-without-replay.
    # This is the idempotent-receiver EFFECT — wire-level exactly-once does
    # not exist on RabbitMQ and this does not claim otherwise.
    store_results: bool = False
    max_result_bytes: int = 65536
    on_in_flight: str = "nack_requeue"  # claim only: "nack_requeue" (retry-safe) | "ack_skip"
    #: Seconds to wait before nack-requeueing a duplicate of an IN-FLIGHT
    #: message. Without it the requeue is immediate, the broker redelivers at
    #: once, and the message spins until the claim resolves — measured at
    #: ~3,160 redeliveries/second from ONE duplicate, for up to
    #: ``processing_timeout`` (default 300s). That burns a prefetch slot and
    #: broker bandwidth, and an attacker who can publish a colliding id plus a
    #: slow payload gets the amplification for free. 0 restores the old
    #: behaviour.
    in_flight_requeue_delay: float = 0.5
    #: Include the CONSUMING QUEUE in the dedup key. Default True since 0.18.
    #:
    #: Without it the key is just ``{key_prefix}:{id}``, so one middleware
    #: instance shared across routes — which the project's own examples do —
    #: gives every queue a single shared keyspace. Two different queues each
    #: handling a message with id ``order-1001`` then deduplicate against each
    #: other and one is silently dropped. That is wrong regardless of who is
    #: publishing.
    #:
    #: The queue name comes from ``x-rabbitkit-original-queue``, which both
    #: brokers overwrite at consume time, so a publisher cannot steer it.
    #:
    #: MIGRATION: enabling this changes every key, so on deploy there is one
    #: ``ttl`` window (24h by default) in which previously-seen messages are
    #: not recognised as duplicates. Harmless for most workloads; if a
    #: duplicate is unacceptable, set False, deploy, then flip it during a
    #: quiet period.
    namespace_by_queue: bool = True

    def __post_init__(self) -> None:
        if self.store_results and self.mark_policy != "claim":
            raise ConfigValidationError(
                "DeduplicationConfig.store_results=True requires mark_policy='claim' "
                f"(got {self.mark_policy!r}) — result replay is only crash-safe on the "
                "claim state machine."
            )
        if self.max_result_bytes < 1:
            raise ConfigValidationError(
                f"DeduplicationConfig.max_result_bytes must be >= 1, got {self.max_result_bytes}"
            )
        if self.mark_policy not in ("on_success", "on_start", "claim"):
            raise ConfigValidationError(
                f"DeduplicationConfig.mark_policy must be one of "
                f"'on_success', 'on_start', 'claim'; got {self.mark_policy!r}"
            )
        if self.on_in_flight not in ("nack_requeue", "ack_skip"):
            raise ConfigValidationError(
                f"DeduplicationConfig.on_in_flight must be 'nack_requeue' or 'ack_skip'; got {self.on_in_flight!r}"
            )
        if self.processing_timeout <= 0:
            raise ConfigValidationError(
                f"DeduplicationConfig.processing_timeout must be > 0, got {self.processing_timeout}"
            )

HealthCheckConfig

HealthCheckConfig dataclass

Thresholds for broker_health_check().

Source code in src/rabbitkit/core/config.py
@dataclass(frozen=True, slots=True)
class HealthCheckConfig:
    """Thresholds for broker_health_check()."""

    pending_threshold: int = 100

MetricsConfig

MetricsConfig dataclass

Metrics naming configuration.

namespace sets the metric name prefix (default "rabbitkit"). Individual name fields override the derived default when non-empty.

Source code in src/rabbitkit/core/config.py
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
@dataclass(frozen=True, slots=True)
class MetricsConfig:
    """Metrics naming configuration.

    ``namespace`` sets the metric name prefix (default "rabbitkit").
    Individual name fields override the derived default when non-empty.
    """

    namespace: str = "rabbitkit"
    consumed_counter: str = ""
    processing_histogram: str = ""
    published_counter: str = ""
    publish_histogram: str = ""

    @property
    def consumed_total(self) -> str:
        return self.consumed_counter or f"{self.namespace}_messages_consumed_total"

    @property
    def processing_seconds(self) -> str:
        return self.processing_histogram or f"{self.namespace}_message_processing_seconds"

    @property
    def messages_acked_total(self) -> str:
        return f"{self.namespace}_messages_acked_total"

    @property
    def messages_nacked_total(self) -> str:
        return f"{self.namespace}_messages_nacked_total"

    @property
    def messages_rejected_total(self) -> str:
        return f"{self.namespace}_messages_rejected_total"

    @property
    def messages_retried_total(self) -> str:
        return f"{self.namespace}_messages_retried_total"

    @property
    def messages_dead_lettered_total(self) -> str:
        return f"{self.namespace}_messages_dead_lettered_total"

    @property
    def settlement_outcome_unknown_total(self) -> str:
        """Incremented (labeled by ``queue``) when a handler succeeded but its
        ack raised: the ack may or may not have reached the broker, so the
        message may be redelivered and processed again."""
        return f"{self.namespace}_settlement_outcome_unknown_total"

    @property
    def dedup_fallback_total(self) -> str:
        """M9: incremented every time DeduplicationMiddleware falls back to
        processing a message despite a Redis error (idempotency is not
        enforced for that message) — see
        ``DeduplicationConfig.fallback_on_redis_error``."""
        return f"{self.namespace}_dedup_fallback_total"

    @property
    def rate_limit_dropped_total(self) -> str:
        """L5: incremented every time RateLimitMiddleware settles a message
        without calling the handler — nack/drop policy, or the "wait" policy's
        deadline elapsing with no token acquired. Labeled by ``reason``
        (``nack``/``drop``/``wait_deadline_exceeded``)."""
        return f"{self.namespace}_rate_limit_dropped_total"

    @property
    def messages_redelivered_total(self) -> str:
        """Incremented (labeled by ``queue``) for every consumed message the
        broker flagged ``redelivered=True`` — the broker-redelivery-rate
        signal. A sustained rise means handlers are dying/timing out before
        acking (crash loops, heartbeat kills, connection churn), which the
        success/error consume counters alone can't distinguish from ordinary
        traffic."""
        return f"{self.namespace}_messages_redelivered_total"

    @property
    def reconnects_total(self) -> str:
        """Incremented on every transport re-connection after the first
        successful connect — the connection-churn signal. Reconnects were
        previously logged but never counted, so a flapping broker/network
        was invisible to metrics-based alerting."""
        return f"{self.namespace}_reconnects_total"

    @property
    def channels_opened_total(self) -> str:
        """Incremented every time either transport actually creates a new
        low-level channel — the publisher/topology channel, a per-queue
        consumer channel, an async channel-pool slot, or a dedicated
        fast/mandatory/reply-to channel. A steady climb with no matching
        traffic growth signals a channel leak (a "cache" of channels that
        never shrinks) — previously invisible, since only the connection
        churn (``reconnects_total``) was counted."""
        return f"{self.namespace}_channels_opened_total"

    @property
    def channel_rebuilds_total(self) -> str:
        """Incremented when a channel is created to REPLACE one that died —
        a reconnect-driven per-queue consumer channel recreate (sync), a
        406-drift publisher channel reopen (sync), or a mandatory/fast
        channel recycle after a timeout or closed-channel discovery (async).
        Unlike ``channels_opened_total`` (every creation, including ordinary
        pool growth and first-ever opens), this isolates the subset that
        indicates something upstream actually failed."""
        return f"{self.namespace}_channel_rebuilds_total"

    @property
    def published_total(self) -> str:
        return self.published_counter or f"{self.namespace}_messages_published_total"

    @property
    def publish_confirm_latency_seconds(self) -> str:
        return f"{self.namespace}_publish_confirm_latency_seconds"

    @property
    def publish_seconds(self) -> str:
        return self.publish_histogram or f"{self.namespace}_message_publish_seconds"

    @property
    def in_flight_messages(self) -> str:
        return f"{self.namespace}_in_flight_messages"

    @property
    def worker_pool_pending(self) -> str:
        return f"{self.namespace}_worker_pool_pending"

    @property
    def broker_connected(self) -> str:
        return f"{self.namespace}_broker_connected"

    @property
    def consumer_active(self) -> str:
        return f"{self.namespace}_consumer_active"

    # ── Bulk operations & settlement (plan §11) ──

    @property
    def bulk_publish_items_total(self) -> str:
        """Incremented per ``publish_many``/``iter_publish`` item, labeled by
        ``status`` (confirmed/unroutable/nacked/invalid/not_sent/unknown)
        and ``reason`` (bounded reason code). A sustained ``unknown`` rate is
        the "reconcile me" signal."""
        return f"{self.namespace}_bulk_publish_items_total"

    @property
    def bulk_publish_batch_size(self) -> str:
        """Histogram of ``publish_many`` input sizes (items)."""
        return f"{self.namespace}_bulk_publish_batch_size"

    @property
    def bulk_publish_admission_wait_seconds(self) -> str:
        """Histogram of time an item waited for an in-flight/byte slot."""
        return f"{self.namespace}_bulk_publish_admission_wait_seconds"

    @property
    def settlement_items_total(self) -> str:
        """Incremented per ``ack_many``/``nack_many`` item, labeled by
        ``action`` and ``status`` (dispatched/already_settled/duplicate/
        invalid/stale/not_attempted/failed)."""
        return f"{self.namespace}_settlement_items_total"

    @property
    def settlement_pending(self) -> str:
        """Gauge: deliveries registered with a ``SettlementCoordinator`` but
        not yet settled. Unbounded growth means a stuck handler is holding
        the ack frontier back."""
        return f"{self.namespace}_settlement_pending"

    @property
    def settlement_ack_ready(self) -> str:
        """Gauge: deliveries approved for an ack but not yet emitted."""
        return f"{self.namespace}_settlement_ack_ready"

    @property
    def settlement_frontier(self) -> str:
        """Gauge: highest delivery tag a cumulative ack could currently cover.
        Flat while ``settlement_ack_ready`` climbs = a straggler is blocking."""
        return f"{self.namespace}_settlement_frontier"

    @property
    def settlement_gap_count(self) -> str:
        """Gauge: blocking deliveries sitting below an ack-ready one — the
        stragglers stranding otherwise-settleable work."""
        return f"{self.namespace}_settlement_gap_count"

    @property
    def settlement_oldest_pending_age_seconds(self) -> str:
        """Gauge: age of the oldest unsettled delivery. The clearest
        "a handler is stuck" signal; alert on it."""
        return f"{self.namespace}_settlement_oldest_pending_age_seconds"

    @property
    def settlement_coalescing_ratio(self) -> str:
        """Gauge: deliveries settled per AMQP frame sent. 1.0 = no coalescing
        happening (often because the frontier is blocked)."""
        return f"{self.namespace}_settlement_coalescing_ratio"

    @property
    def settlement_coalesced_total(self) -> str:
        """Tags settled through a cumulative (multiple=True) ack by a
        ``CoalescingAcker`` — the coalescing-ratio numerator."""
        return f"{self.namespace}_settlement_coalesced_total"

    @property
    def retry_handoff_failures_total(self) -> str:
        """Incremented when the RETRY PUBLISH (delay-queue handoff) fails —
        returned, nacked, timed out, or errored — labeled by ``queue``.
        Distinct from ``messages_retried_total`` (handler attempts)."""
        return f"{self.namespace}_retry_handoff_failures_total"

    @property
    def retry_handoff_paused(self) -> str:
        """Gauge: 1 while a route's retry-handoff tracker is in backoff/
        exhausted state, labeled by ``queue``."""
        return f"{self.namespace}_retry_handoff_paused"

    # ── Broker-side gauges (H5: polled from the management API) ──
    # Bridged by QueueMetricsPoller — the #1 RabbitMQ incident signal
    # (queue growth / consumer lag) that the consume/publish counters cannot
    # see. All labeled by {queue}.

    @property
    def queue_messages_ready(self) -> str:
        """Messages ready for delivery (backlog depth)."""
        return f"{self.namespace}_queue_messages_ready"

    @property
    def queue_messages_unacked(self) -> str:
        """Messages delivered but not yet acked (in-flight at consumers)."""
        return f"{self.namespace}_queue_messages_unacked"

    @property
    def queue_messages_total(self) -> str:
        """Total messages in the queue (ready + unacked)."""
        return f"{self.namespace}_queue_messages_total"

    @property
    def queue_consumers(self) -> str:
        """Number of consumers attached to the queue (0 = nothing draining)."""
        return f"{self.namespace}_queue_consumers"

    @property
    def queue_quorum_members(self) -> str:
        """Quorum queues only: Raft members the queue is configured with."""
        return f"{self.namespace}_queue_quorum_members"

    @property
    def queue_quorum_online(self) -> str:
        """Quorum queues only: members currently online. The queue is
        available while more than half of its members are online."""
        return f"{self.namespace}_queue_quorum_online"

    # ── Broker/transport metrics. Emitted by the broker itself
    # whenever any MetricsMiddleware with a collector is configured (publish
    # middlewares or any route), so publish-only brokers get them too. ──

    @property
    def messages_failed_total(self) -> str:
        """Handler failures labeled by ``queue`` and ``category`` (one of the
        six ``ErrorCategory`` values)."""
        return f"{self.namespace}_messages_failed_total"

    @property
    def publish_in_flight(self) -> str:
        """Gauge: async publishes between admission and their outcome (sampled)."""
        return f"{self.namespace}_publish_in_flight"

    @property
    def publish_in_flight_bytes(self) -> str:
        """Gauge: body bytes held by the ``max_in_flight_bytes`` budget (sampled;
        only emitted when that budget is configured)."""
        return f"{self.namespace}_publish_in_flight_bytes"

    @property
    def publish_channels_in_use(self) -> str:
        """Gauge: publisher channels checked out of the async pools (sampled)."""
        return f"{self.namespace}_publish_channels_in_use"

    @property
    def publish_routing_failures_total(self) -> str:
        """Publishes the broker could not route, labeled by ``exchange`` and
        ``reason`` (``returned`` / ``exchange_not_found``). Counts every
        transport publish, including retry and dead-letter copies."""
        return f"{self.namespace}_publish_routing_failures_total"

    @property
    def connection_up(self) -> str:
        """Gauge: 1 while the connection of ``role`` is up, else 0."""
        return f"{self.namespace}_connection_up"

    @property
    def connections_active(self) -> str:
        """Gauge: connections currently up."""
        return f"{self.namespace}_connections_active"

    @property
    def channels_active(self) -> str:
        """Gauge: channels the transport currently holds open (sampled)."""
        return f"{self.namespace}_channels_active"

    @property
    def connection_failures_total(self) -> str:
        """Connection failures labeled by ``role`` and a bounded ``reason``:
        a live connection lost, a failed reconnect attempt, or a terminal
        give-up (its ``TerminalConnectionError.reason``)."""
        return f"{self.namespace}_connection_failures_total"

    @property
    def reconnect_attempts_total(self) -> str:
        """FAILED reconnect attempts labeled by ``role``. A successful
        reconnect increments ``reconnects_total`` instead."""
        return f"{self.namespace}_reconnect_attempts_total"

    @property
    def connection_blocked(self) -> str:
        """Gauge: 1 while RabbitMQ has the connection blocked
        (``connection.blocked``: a memory or disk alarm), else 0."""
        return f"{self.namespace}_connection_blocked"

    @property
    def connection_blocked_reason(self) -> str:
        """Gauge per bounded ``reason`` (``disk`` / ``memory`` / ``other``): 1
        while the connection is blocked and the broker's ``connection.blocked``
        reason names that alarm, else 0. The client-side form of the broker's
        disk and memory alarms; needs no broker plugin."""
        return f"{self.namespace}_connection_blocked_reason"

    @property
    def consumer_cancelled_total(self) -> str:
        """Consumers the BROKER cancelled (``basic.cancel``), labeled by ``queue``."""
        return f"{self.namespace}_consumer_cancelled_total"

    @property
    def route_consuming(self) -> str:
        """Gauge per ``queue``: 1 while the route's consumer is subscribed, 0
        while it is not (stopped, or cancelled by the broker)."""
        return f"{self.namespace}_route_consuming"

Attributes

settlement_outcome_unknown_total: str property

Incremented (labeled by queue) when a handler succeeded but its ack raised: the ack may or may not have reached the broker, so the message may be redelivered and processed again.

dedup_fallback_total: str property

M9: incremented every time DeduplicationMiddleware falls back to processing a message despite a Redis error (idempotency is not enforced for that message) — see DeduplicationConfig.fallback_on_redis_error.

rate_limit_dropped_total: str property

L5: incremented every time RateLimitMiddleware settles a message without calling the handler — nack/drop policy, or the "wait" policy's deadline elapsing with no token acquired. Labeled by reason (nack/drop/wait_deadline_exceeded).

messages_redelivered_total: str property

Incremented (labeled by queue) for every consumed message the broker flagged redelivered=True — the broker-redelivery-rate signal. A sustained rise means handlers are dying/timing out before acking (crash loops, heartbeat kills, connection churn), which the success/error consume counters alone can't distinguish from ordinary traffic.

reconnects_total: str property

Incremented on every transport re-connection after the first successful connect — the connection-churn signal. Reconnects were previously logged but never counted, so a flapping broker/network was invisible to metrics-based alerting.

channels_opened_total: str property

Incremented every time either transport actually creates a new low-level channel — the publisher/topology channel, a per-queue consumer channel, an async channel-pool slot, or a dedicated fast/mandatory/reply-to channel. A steady climb with no matching traffic growth signals a channel leak (a "cache" of channels that never shrinks) — previously invisible, since only the connection churn (reconnects_total) was counted.

channel_rebuilds_total: str property

Incremented when a channel is created to REPLACE one that died — a reconnect-driven per-queue consumer channel recreate (sync), a 406-drift publisher channel reopen (sync), or a mandatory/fast channel recycle after a timeout or closed-channel discovery (async). Unlike channels_opened_total (every creation, including ordinary pool growth and first-ever opens), this isolates the subset that indicates something upstream actually failed.

bulk_publish_items_total: str property

Incremented per publish_many/iter_publish item, labeled by status (confirmed/unroutable/nacked/invalid/not_sent/unknown) and reason (bounded reason code). A sustained unknown rate is the "reconcile me" signal.

bulk_publish_batch_size: str property

Histogram of publish_many input sizes (items).

bulk_publish_admission_wait_seconds: str property

Histogram of time an item waited for an in-flight/byte slot.

settlement_items_total: str property

Incremented per ack_many/nack_many item, labeled by action and status (dispatched/already_settled/duplicate/ invalid/stale/not_attempted/failed).

settlement_pending: str property

Gauge: deliveries registered with a SettlementCoordinator but not yet settled. Unbounded growth means a stuck handler is holding the ack frontier back.

settlement_ack_ready: str property

Gauge: deliveries approved for an ack but not yet emitted.

settlement_frontier: str property

Gauge: highest delivery tag a cumulative ack could currently cover. Flat while settlement_ack_ready climbs = a straggler is blocking.

settlement_gap_count: str property

Gauge: blocking deliveries sitting below an ack-ready one — the stragglers stranding otherwise-settleable work.

settlement_oldest_pending_age_seconds: str property

Gauge: age of the oldest unsettled delivery. The clearest "a handler is stuck" signal; alert on it.

settlement_coalescing_ratio: str property

Gauge: deliveries settled per AMQP frame sent. 1.0 = no coalescing happening (often because the frontier is blocked).

settlement_coalesced_total: str property

Tags settled through a cumulative (multiple=True) ack by a CoalescingAcker — the coalescing-ratio numerator.

retry_handoff_failures_total: str property

Incremented when the RETRY PUBLISH (delay-queue handoff) fails — returned, nacked, timed out, or errored — labeled by queue. Distinct from messages_retried_total (handler attempts).

retry_handoff_paused: str property

Gauge: 1 while a route's retry-handoff tracker is in backoff/ exhausted state, labeled by queue.

queue_messages_ready: str property

Messages ready for delivery (backlog depth).

queue_messages_unacked: str property

Messages delivered but not yet acked (in-flight at consumers).

queue_messages_total: str property

Total messages in the queue (ready + unacked).

queue_consumers: str property

Number of consumers attached to the queue (0 = nothing draining).

queue_quorum_members: str property

Quorum queues only: Raft members the queue is configured with.

queue_quorum_online: str property

Quorum queues only: members currently online. The queue is available while more than half of its members are online.

messages_failed_total: str property

Handler failures labeled by queue and category (one of the six ErrorCategory values).

publish_in_flight: str property

Gauge: async publishes between admission and their outcome (sampled).

publish_in_flight_bytes: str property

Gauge: body bytes held by the max_in_flight_bytes budget (sampled; only emitted when that budget is configured).

publish_channels_in_use: str property

Gauge: publisher channels checked out of the async pools (sampled).

publish_routing_failures_total: str property

Publishes the broker could not route, labeled by exchange and reason (returned / exchange_not_found). Counts every transport publish, including retry and dead-letter copies.

connection_up: str property

Gauge: 1 while the connection of role is up, else 0.

connections_active: str property

Gauge: connections currently up.

channels_active: str property

Gauge: channels the transport currently holds open (sampled).

connection_failures_total: str property

Connection failures labeled by role and a bounded reason: a live connection lost, a failed reconnect attempt, or a terminal give-up (its TerminalConnectionError.reason).

reconnect_attempts_total: str property

FAILED reconnect attempts labeled by role. A successful reconnect increments reconnects_total instead.

connection_blocked: str property

Gauge: 1 while RabbitMQ has the connection blocked (connection.blocked: a memory or disk alarm), else 0.

connection_blocked_reason: str property

Gauge per bounded reason (disk / memory / other): 1 while the connection is blocked and the broker's connection.blocked reason names that alarm, else 0. The client-side form of the broker's disk and memory alarms; needs no broker plugin.

consumer_cancelled_total: str property

Consumers the BROKER cancelled (basic.cancel), labeled by queue.

route_consuming: str property

Gauge per queue: 1 while the route's consumer is subscribed, 0 while it is not (stopped, or cancelled by the broker).

RetryDisabled / RETRY_DISABLED

RetryDisabled

Typed singleton — explicitly disables retry on a route.

Distinct from RetryConfig(max_retries=0) which means 'retry-owned terminal semantics with zero retry attempts (immediate DLQ on any classified error).'

Source code in src/rabbitkit/core/config.py
class RetryDisabled:
    """Typed singleton — explicitly disables retry on a route.

    Distinct from RetryConfig(max_retries=0) which means 'retry-owned
    terminal semantics with zero retry attempts (immediate DLQ on any
    classified error).'
    """

    _instance: RetryDisabled | None = None

    def __new__(cls) -> RetryDisabled:
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

    def __repr__(self) -> str:
        return "RETRY_DISABLED"

    def __bool__(self) -> bool:
        return False