Skip to content

Bulk Operations & Reliability

See the Bulk Operations guide for the contract and safety invariants.

Bulk publishing

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}")

BulkPublishItem dataclass

Outcome of ONE input envelope.

Keyed by index (position in the caller's input), never solely by message_id — input IDs may legitimately repeat. attempt_id is a fresh UUID per submission so an UNKNOWN item can be reconciled against a downstream inbox even when the same message_id was published twice.

Source code in src/rabbitkit/core/bulk.py
@dataclass(frozen=True, slots=True)
class BulkPublishItem:
    """Outcome of ONE input envelope.

    Keyed by ``index`` (position in the caller's input), never solely by
    ``message_id`` — input IDs may legitimately repeat. ``attempt_id`` is a
    fresh UUID per submission so an UNKNOWN item can be reconciled against a
    downstream inbox even when the same ``message_id`` was published twice.
    """

    index: int
    status: BulkPublishStatus
    reason: str
    message_id: str = ""
    attempt_id: str = ""
    exchange: str = ""
    routing_key: str = ""
    body_bytes: int = 0
    error: BaseException | None = None
    submitted_at: float | None = None
    settled_at: float | None = None

    def __post_init__(self) -> None:
        if self.reason not in ALL_REASONS:
            raise ValueError(f"BulkPublishItem.reason must be a bounded reason code, got {self.reason!r}")

    @property
    def ok(self) -> bool:
        """True only for ``CONFIRMED``. UNKNOWN is never ok."""
        return self.status is BulkPublishStatus.CONFIRMED

    @property
    def duration(self) -> float | None:
        """Seconds from submission to settlement, when both are known."""
        if self.submitted_at is None or self.settled_at is None:
            return None
        return max(0.0, self.settled_at - self.submitted_at)

    @property
    def safe_to_resubmit(self) -> bool:
        """True when resubmitting cannot duplicate a broker-held message
        (``NOT_SENT`` / ``INVALID`` after fixing the input). UNKNOWN is
        deliberately False — it needs stable IDs plus deduplication."""
        return self.status in (BulkPublishStatus.NOT_SENT, BulkPublishStatus.INVALID)

Attributes

ok: bool property

True only for CONFIRMED. UNKNOWN is never ok.

duration: float | None property

Seconds from submission to settlement, when both are known.

safe_to_resubmit: bool property

True when resubmitting cannot duplicate a broker-held message (NOT_SENT / INVALID after fixing the input). UNKNOWN is deliberately False — it needs stable IDs plus deduplication.

BulkPublishResult dataclass

Input-ordered per-item outcomes for one publish_many call.

Source code in src/rabbitkit/core/bulk.py
@dataclass(frozen=True, slots=True)
class BulkPublishResult:
    """Input-ordered per-item outcomes for one ``publish_many`` call."""

    items: tuple[BulkPublishItem, ...]
    started_at: datetime = field(default_factory=lambda: datetime.now(UTC))
    finished_at: datetime = field(default_factory=lambda: datetime.now(UTC))

    def __post_init__(self) -> None:
        indices = [it.index for it in self.items]
        if indices != sorted(indices) or len(set(indices)) != len(indices):
            raise ValueError("BulkPublishResult.items must be input-ordered with unique indices")

    def __len__(self) -> int:
        return len(self.items)

    @property
    def counts(self) -> dict[BulkPublishStatus, int]:
        return dict(Counter(it.status for it in self.items))

    def by_status(self, status: BulkPublishStatus) -> tuple[BulkPublishItem, ...]:
        return tuple(it for it in self.items if it.status is status)

    @property
    def confirmed(self) -> tuple[BulkPublishItem, ...]:
        return self.by_status(BulkPublishStatus.CONFIRMED)

    @property
    def unknown(self) -> tuple[BulkPublishItem, ...]:
        return self.by_status(BulkPublishStatus.UNKNOWN)

    @property
    def resubmittable(self) -> tuple[BulkPublishItem, ...]:
        """Items that were definitively never sent (safe to resubmit)."""
        return tuple(it for it in self.items if it.safe_to_resubmit)

    @property
    def failed(self) -> tuple[BulkPublishItem, ...]:
        """Everything that is not CONFIRMED — including UNKNOWN."""
        return tuple(it for it in self.items if not it.ok)

    @property
    def all_confirmed(self) -> bool:
        return all(it.ok for it in self.items)

    def raise_for_status(self) -> BulkPublishResult:
        """Raise :class:`BulkPublishError` unless every item is CONFIRMED."""
        if not self.all_confirmed:
            raise BulkPublishError(self)
        return self

Attributes

resubmittable: tuple[BulkPublishItem, ...] property

Items that were definitively never sent (safe to resubmit).

failed: tuple[BulkPublishItem, ...] property

Everything that is not CONFIRMED — including UNKNOWN.

Methods:

raise_for_status() -> BulkPublishResult

Raise :class:BulkPublishError unless every item is CONFIRMED.

Source code in src/rabbitkit/core/bulk.py
def raise_for_status(self) -> BulkPublishResult:
    """Raise :class:`BulkPublishError` unless every item is CONFIRMED."""
    if not self.all_confirmed:
        raise BulkPublishError(self)
    return self

BulkPublishError

Bases: Exception

Raised by :meth:BulkPublishResult.raise_for_status when not every item is CONFIRMED. Carries the full result for reconciliation.

Source code in src/rabbitkit/core/bulk.py
class BulkPublishError(Exception):
    """Raised by :meth:`BulkPublishResult.raise_for_status` when not every
    item is CONFIRMED. Carries the full result for reconciliation."""

    def __init__(self, result: BulkPublishResult) -> None:
        self.result = result
        counts = ", ".join(f"{s.value}={n}" for s, n in sorted(result.counts.items(), key=lambda kv: kv[0].value))
        super().__init__(f"bulk publish incomplete: {counts}")

BulkPublishStatus

Bases: str, Enum

Actionable per-item state of a bulk publish (broker.publish_many).

Stricter than :class:PublishStatus and deliberately preserves uncertainty: SENT, a confirm timeout, and a mid-publish exception all become UNKNOWN (the publish may have reached the broker) rather than a success or a definite failure. See :mod:rabbitkit.core.bulk.

Source code in src/rabbitkit/core/types.py
class BulkPublishStatus(str, Enum):
    """Actionable per-item state of a bulk publish (``broker.publish_many``).

    Stricter than :class:`PublishStatus` and deliberately preserves
    uncertainty: ``SENT``, a confirm timeout, and a mid-publish exception all
    become ``UNKNOWN`` (the publish may have reached the broker) rather than
    a success or a definite failure. See :mod:`rabbitkit.core.bulk`.
    """

    CONFIRMED = "confirmed"
    UNROUTABLE = "unroutable"
    NACKED = "nacked"
    INVALID = "invalid"
    NOT_SENT = "not_sent"
    UNKNOWN = "unknown"

PublishPreparer

Transport-independent preparation for one envelope.

input → envelope validation → frozen copy → final byte/header checks. Middleware/serialization run later, inside the broker's publish chain, exactly once per attempt. Everything here happens BEFORE admission so a bad item never consumes an in-flight slot.

The prepared envelope is a copy whose headers dict is snapshotted — a caller mutating its original dict after publish_many returns (or while it is still running) cannot alter what is on the wire.

Source code in src/rabbitkit/core/bulk.py
class PublishPreparer:
    """Transport-independent preparation for one envelope.

    ``input → envelope validation → frozen copy → final byte/header checks``.
    Middleware/serialization run later, inside the broker's publish chain,
    exactly once per attempt. Everything here happens BEFORE admission so a
    bad item never consumes an in-flight slot.

    The prepared envelope is a *copy* whose ``headers`` dict is snapshotted —
    a caller mutating its original dict after ``publish_many`` returns (or
    while it is still running) cannot alter what is on the wire.
    """

    def __init__(
        self,
        *,
        max_message_bytes: int,
        max_buffer_bytes: int,
    ) -> None:
        self._max_message_bytes = max_message_bytes
        self._max_buffer_bytes = max_buffer_bytes

    def prepare(self, index: int, raw: Any) -> tuple[MessageEnvelope | None, BulkPublishItem | None]:
        """Return ``(envelope, None)`` when admissible, else ``(None, INVALID item)``."""
        if not isinstance(raw, MessageEnvelope):
            return None, BulkPublishItem(
                index=index,
                status=BulkPublishStatus.INVALID,
                reason=REASON_INVALID_TYPE,
                error=TypeError(f"publish_many items must be MessageEnvelope, got {type(raw).__name__}"),
            )
        body_len = len(raw.body)
        if self._max_message_bytes and body_len > self._max_message_bytes:
            return None, BulkPublishItem(
                index=index,
                status=BulkPublishStatus.INVALID,
                reason=REASON_BODY_TOO_LARGE,
                message_id=raw.message_id,
                exchange=raw.exchange,
                routing_key=raw.routing_key,
                body_bytes=body_len,
                error=MessageTooLargeError(
                    f"Message body ({body_len} bytes) exceeds PublisherConfig.max_message_bytes "
                    f"({self._max_message_bytes})."
                ),
            )
        if body_len > self._max_buffer_bytes:
            return None, BulkPublishItem(
                index=index,
                status=BulkPublishStatus.INVALID,
                reason=REASON_EXCEEDS_BUFFER,
                message_id=raw.message_id,
                exchange=raw.exchange,
                routing_key=raw.routing_key,
                body_bytes=body_len,
                error=ValueError(
                    f"Message body ({body_len} bytes) exceeds BulkPublishOptions.max_buffer_bytes "
                    f"({self._max_buffer_bytes}); it can never be admitted."
                ),
            )
        if raw.headers and not all(isinstance(k, str) and _validate_header_value(v) for k, v in raw.headers.items()):
            return None, BulkPublishItem(
                index=index,
                status=BulkPublishStatus.INVALID,
                reason=REASON_INVALID_HEADERS,
                message_id=raw.message_id,
                exchange=raw.exchange,
                routing_key=raw.routing_key,
                body_bytes=body_len,
                error=TypeError("headers must be str-keyed AMQP field-table values"),
            )
        # Snapshot: the caller cannot mutate the queued envelope's headers.
        frozen = dataclasses.replace(raw, headers=dict(raw.headers)) if raw.headers else raw
        return frozen, None

Methods:

prepare(index: int, raw: Any) -> tuple[MessageEnvelope | None, BulkPublishItem | None]

Return (envelope, None) when admissible, else (None, INVALID item).

Source code in src/rabbitkit/core/bulk.py
def prepare(self, index: int, raw: Any) -> tuple[MessageEnvelope | None, BulkPublishItem | None]:
    """Return ``(envelope, None)`` when admissible, else ``(None, INVALID item)``."""
    if not isinstance(raw, MessageEnvelope):
        return None, BulkPublishItem(
            index=index,
            status=BulkPublishStatus.INVALID,
            reason=REASON_INVALID_TYPE,
            error=TypeError(f"publish_many items must be MessageEnvelope, got {type(raw).__name__}"),
        )
    body_len = len(raw.body)
    if self._max_message_bytes and body_len > self._max_message_bytes:
        return None, BulkPublishItem(
            index=index,
            status=BulkPublishStatus.INVALID,
            reason=REASON_BODY_TOO_LARGE,
            message_id=raw.message_id,
            exchange=raw.exchange,
            routing_key=raw.routing_key,
            body_bytes=body_len,
            error=MessageTooLargeError(
                f"Message body ({body_len} bytes) exceeds PublisherConfig.max_message_bytes "
                f"({self._max_message_bytes})."
            ),
        )
    if body_len > self._max_buffer_bytes:
        return None, BulkPublishItem(
            index=index,
            status=BulkPublishStatus.INVALID,
            reason=REASON_EXCEEDS_BUFFER,
            message_id=raw.message_id,
            exchange=raw.exchange,
            routing_key=raw.routing_key,
            body_bytes=body_len,
            error=ValueError(
                f"Message body ({body_len} bytes) exceeds BulkPublishOptions.max_buffer_bytes "
                f"({self._max_buffer_bytes}); it can never be admitted."
            ),
        )
    if raw.headers and not all(isinstance(k, str) and _validate_header_value(v) for k, v in raw.headers.items()):
        return None, BulkPublishItem(
            index=index,
            status=BulkPublishStatus.INVALID,
            reason=REASON_INVALID_HEADERS,
            message_id=raw.message_id,
            exchange=raw.exchange,
            routing_key=raw.routing_key,
            body_bytes=body_len,
            error=TypeError("headers must be str-keyed AMQP field-table values"),
        )
    # Snapshot: the caller cannot mutate the queued envelope's headers.
    frozen = dataclasses.replace(raw, headers=dict(raw.headers)) if raw.headers else raw
    return frozen, None

classify_publish_outcome(outcome: PublishOutcome | None) -> tuple[BulkPublishStatus, str]

Map a transport PublishOutcome onto the bulk vocabulary.

Precedence rules (safety invariant 2):

  • RETURNED wins over everything — an unroutable message is not a successful routed publication even though the broker also confirms it.
  • SENT (confirms disabled) is UNKNOWN, not confirmed.
  • TIMEOUT and UNKNOWN are UNKNOWN — the frame may have reached the broker.
  • NOT_SENT is NOT_SENT — the transport proved nothing left.
  • ERROR with reason exchange_not_found is UNROUTABLE (the broker refused to route it); any other ERROR is UNKNOWN unless the error proves nothing was submitted (backpressure drop, broker not started) or that the input itself was invalid (oversized body / ValueError/TypeError from validation).
  • None (a duck-typed publish fn returned nothing) is UNKNOWN.

The transport's own reason code is kept when it has one.

Source code in src/rabbitkit/core/bulk.py
def classify_publish_outcome(outcome: PublishOutcome | None) -> tuple[BulkPublishStatus, str]:
    """Map a transport ``PublishOutcome`` onto the bulk vocabulary.

    Precedence rules (safety invariant 2):

    * ``RETURNED`` wins over everything — an unroutable message is not a
      successful routed publication even though the broker also confirms it.
    * ``SENT`` (confirms disabled) is ``UNKNOWN``, not confirmed.
    * ``TIMEOUT`` and ``UNKNOWN`` are ``UNKNOWN`` — the frame may have
      reached the broker.
    * ``NOT_SENT`` is ``NOT_SENT`` — the transport proved nothing left.
    * ``ERROR`` with reason ``exchange_not_found`` is ``UNROUTABLE`` (the
      broker refused to route it); any other ``ERROR`` is ``UNKNOWN`` unless
      the error proves nothing was submitted (backpressure drop, broker not
      started) or that the input itself was invalid (oversized body /
      ``ValueError``/``TypeError`` from validation).
    * ``None`` (a duck-typed publish fn returned nothing) is ``UNKNOWN``.

    The transport's own ``reason`` code is kept when it has one.
    """
    if outcome is None:
        return BulkPublishStatus.UNKNOWN, REASON_NO_OUTCOME
    status = outcome.status
    reason = outcome.reason if outcome.reason in PublishReason.ALL else None
    if status is PublishStatus.RETURNED:
        return BulkPublishStatus.UNROUTABLE, REASON_RETURNED
    if status is PublishStatus.CONFIRMED:
        return BulkPublishStatus.CONFIRMED, REASON_CONFIRMED
    if status is PublishStatus.SENT:
        return BulkPublishStatus.UNKNOWN, REASON_SENT_UNCONFIRMED
    if status is PublishStatus.NACKED:
        return BulkPublishStatus.NACKED, REASON_NACKED
    if status is PublishStatus.TIMEOUT:
        return BulkPublishStatus.UNKNOWN, reason or REASON_CONFIRM_TIMEOUT
    if status is PublishStatus.UNKNOWN:
        return BulkPublishStatus.UNKNOWN, reason or REASON_PUBLISH_ERROR
    if status is PublishStatus.NOT_SENT:
        if reason is None and isinstance(outcome.error, BackpressureError):
            reason = REASON_BACKPRESSURE
        return BulkPublishStatus.NOT_SENT, reason or REASON_NOT_SENT
    # ERROR
    if reason == REASON_EXCHANGE_NOT_FOUND:
        return BulkPublishStatus.UNROUTABLE, REASON_EXCHANGE_NOT_FOUND
    err = outcome.error
    if isinstance(err, BackpressureError):
        return BulkPublishStatus.NOT_SENT, REASON_BACKPRESSURE
    if isinstance(err, BrokerNotStartedError):
        return BulkPublishStatus.NOT_SENT, REASON_NOT_STARTED
    if isinstance(err, MessageTooLargeError):
        return BulkPublishStatus.INVALID, REASON_BODY_TOO_LARGE
    if isinstance(err, (ValueError, TypeError)):
        return BulkPublishStatus.INVALID, REASON_INVALID_ENVELOPE
    return BulkPublishStatus.UNKNOWN, reason or REASON_PUBLISH_ERROR

Selected settlement

SettlementReport dataclass

Input-ordered per-item report for one ack_many/nack_many call.

Source code in src/rabbitkit/core/settlement.py
@dataclass(frozen=True, slots=True)
class SettlementReport:
    """Input-ordered per-item report for one ``ack_many``/``nack_many`` call."""

    action: SettlementAction
    items: tuple[SettlementItem, ...]
    requeue: bool | None = None
    finished_at: datetime = field(default_factory=lambda: datetime.now(UTC))

    def __len__(self) -> int:
        return len(self.items)

    @property
    def counts(self) -> dict[SettlementItemStatus, int]:
        return dict(Counter(it.status for it in self.items))

    def by_status(self, status: SettlementItemStatus) -> tuple[SettlementItem, ...]:
        return tuple(it for it in self.items if it.status is status)

    @property
    def dispatched(self) -> tuple[SettlementItem, ...]:
        return self.by_status(SettlementItemStatus.DISPATCHED)

    @property
    def problems(self) -> tuple[SettlementItem, ...]:
        """Everything except DISPATCHED and ALREADY_SETTLED."""
        return tuple(
            it
            for it in self.items
            if it.status not in (SettlementItemStatus.DISPATCHED, SettlementItemStatus.ALREADY_SETTLED)
        )

    @property
    def all_dispatched(self) -> bool:
        return not self.problems

    def raise_for_status(self) -> SettlementReport:
        if not self.all_dispatched:
            raise SettlementReportError(self)
        return self

Attributes

problems: tuple[SettlementItem, ...] property

Everything except DISPATCHED and ALREADY_SETTLED.

SettlementItem dataclass

Source code in src/rabbitkit/core/settlement.py
@dataclass(frozen=True, slots=True)
class SettlementItem:
    index: int
    status: SettlementItemStatus
    reason: str
    delivery_tag: int | None = None
    message_id: str | None = None
    error: BaseException | None = None

    def __post_init__(self) -> None:
        if self.reason not in _SETTLE_REASONS:
            raise ValueError(f"SettlementItem.reason must be a bounded reason code, got {self.reason!r}")

    @property
    def ok(self) -> bool:
        return self.status is SettlementItemStatus.DISPATCHED

SettlementReportError

Bases: Exception

Raised by :meth:SettlementReport.raise_for_status when any item was not dispatched (already-settled items are tolerated — they are no-ops).

Source code in src/rabbitkit/core/settlement.py
class SettlementReportError(Exception):
    """Raised by :meth:`SettlementReport.raise_for_status` when any item was
    not dispatched (already-settled items are tolerated — they are no-ops)."""

    def __init__(self, report: SettlementReport) -> None:
        self.report = report
        counts = ", ".join(f"{s.value}={n}" for s, n in sorted(report.counts.items(), key=lambda kv: kv[0].value))
        super().__init__(f"{report.action.value}_many incomplete: {counts}")

SettlementItemStatus

Bases: str, Enum

Per-item outcome of ack_many / nack_many.

DISPATCHED = handed to the transport (a local wire-write boundary). RabbitMQ never acknowledges a consumer ack, so no member here can mean "broker confirmed".

Source code in src/rabbitkit/core/types.py
class SettlementItemStatus(str, Enum):
    """Per-item outcome of ``ack_many`` / ``nack_many``.

    ``DISPATCHED`` = handed to the transport (a local wire-write boundary).
    RabbitMQ never acknowledges a consumer ack, so no member here can mean
    "broker confirmed".
    """

    DISPATCHED = "dispatched"
    ALREADY_SETTLED = "already_settled"
    DUPLICATE = "duplicate"
    INVALID = "invalid"
    STALE = "stale"
    NOT_ATTEMPTED = "not_attempted"
    FAILED = "failed"

SettlementAction

Bases: str, Enum

Which consumer settlement a bulk call / coordinator command performs.

Source code in src/rabbitkit/core/types.py
class SettlementAction(str, Enum):
    """Which consumer settlement a bulk call / coordinator command performs."""

    ACK = "ack"
    NACK = "nack"
    REJECT = "reject"

plan_selected_settlement(messages: Iterable[Any], *, runtime: str, fail_fast: bool = True) -> SettlementPlan

Validate a selected-settlement input before any I/O.

Parameters:

Name Type Description Default
messages Iterable[Any]

Caller-supplied deliveries (must be RabbitMessage).

required
runtime str

"sync" or "async" — which settlement functions the broker will call. A message wired only for the other runtime is INVALID (wrong_runtime).

required
fail_fast bool

When True and ANY item is invalid/stale/duplicate, nothing is approved: every otherwise-valid item is reported NOT_ATTEMPTED (validation_failed_fail_fast). Already-settled items are not problems (idempotent no-ops). When False, valid items are approved and problems are reported alongside.

True
Source code in src/rabbitkit/core/settlement.py
def plan_selected_settlement(
    messages: Iterable[Any],
    *,
    runtime: str,
    fail_fast: bool = True,
) -> SettlementPlan:
    """Validate a selected-settlement input before any I/O.

    Args:
        messages: Caller-supplied deliveries (must be ``RabbitMessage``).
        runtime: ``"sync"`` or ``"async"`` — which settlement functions the
            broker will call. A message wired only for the other runtime is
            ``INVALID`` (``wrong_runtime``).
        fail_fast: When True and ANY item is invalid/stale/duplicate, nothing
            is approved: every otherwise-valid item is reported
            ``NOT_ATTEMPTED`` (``validation_failed_fail_fast``). Already-settled
            items are not problems (idempotent no-ops). When False, valid
            items are approved and problems are reported alongside.
    """
    if runtime not in ("sync", "async"):
        raise ValueError(f"runtime must be 'sync' or 'async', got {runtime!r}")
    approved: list[tuple[int, RabbitMessage]] = []
    rejected: list[SettlementItem] = []
    seen: set[int] = set()

    for index, raw in enumerate(messages):
        if not isinstance(raw, RabbitMessage):
            rejected.append(
                SettlementItem(
                    index=index,
                    status=SettlementItemStatus.INVALID,
                    reason=SETTLE_REASON_NOT_MESSAGE,
                    error=TypeError(f"expected RabbitMessage, got {type(raw).__name__}"),
                )
            )
            continue
        tag = raw.delivery_tag
        if id(raw) in seen:
            rejected.append(
                SettlementItem(
                    index=index,
                    status=SettlementItemStatus.DUPLICATE,
                    reason=SETTLE_REASON_DUPLICATE,
                    delivery_tag=tag,
                    message_id=raw.message_id,
                )
            )
            continue
        seen.add(id(raw))
        if raw.is_settled:
            rejected.append(
                SettlementItem(
                    index=index,
                    status=SettlementItemStatus.ALREADY_SETTLED,
                    reason=SETTLE_REASON_ALREADY,
                    delivery_tag=tag,
                    message_id=raw.message_id,
                )
            )
            continue
        has_sync = raw._ack_fn is not None
        has_async = raw._ack_async_fn is not None
        if not has_sync and not has_async:
            rejected.append(
                SettlementItem(
                    index=index,
                    status=SettlementItemStatus.INVALID,
                    reason=SETTLE_REASON_NO_SETTLEMENT_FN,
                    delivery_tag=tag,
                    message_id=raw.message_id,
                )
            )
            continue
        # Sync runtime needs a sync fn; async runtime accepts either
        # (RabbitMessage.ack_async falls back to the sync fn).
        if runtime == "sync" and not has_sync:
            rejected.append(
                SettlementItem(
                    index=index,
                    status=SettlementItemStatus.INVALID,
                    reason=SETTLE_REASON_WRONG_RUNTIME,
                    delivery_tag=tag,
                    message_id=raw.message_id,
                )
            )
            continue
        alive = raw._channel_alive
        if alive is not None:
            try:
                is_alive = bool(alive())
            except Exception:
                is_alive = False
            if not is_alive:
                rejected.append(
                    SettlementItem(
                        index=index,
                        status=SettlementItemStatus.STALE,
                        reason=SETTLE_REASON_STALE_CHANNEL,
                        delivery_tag=tag,
                        message_id=raw.message_id,
                    )
                )
                continue
        approved.append((index, raw))

    plan = SettlementPlan(approved=tuple(approved), rejected=tuple(rejected))
    if fail_fast and plan.has_problems and approved:
        aborted = tuple(
            SettlementItem(
                index=i,
                status=SettlementItemStatus.NOT_ATTEMPTED,
                reason=SETTLE_REASON_VALIDATION_ABORT,
                delivery_tag=m.delivery_tag,
                message_id=m.message_id,
            )
            for i, m in approved
        )
        return SettlementPlan(approved=(), rejected=tuple(sorted((*rejected, *aborted), key=lambda it: it.index)))
    return plan

Safe coalescing

SettlementCoordinator

Channel-wide delivery ledger with provably safe ack coalescing.

One coordinator per channel generation. EVERY delivery on that channel must be :meth:register-ed before its handler runs; if that ownership cannot be guaranteed (another consumer shares the channel and does not register), coalescing is unsafe — construct with coalesce=False.

Decision rule for a cumulative ack: let P be the longest prefix of the ledger (ascending tag order) in which every entry is SUCCESS. If |P| >= 2 emit ack(max(P), multiple=True); |P| == 1 is a plain individual ack. max(P) must also lie below the generation's first gap -- the lowest delivery tag that was never registered (refused by max_pending, consumed by someone else on the channel, or skipped by the caller). The broker settles EVERY unacked tag up to max(P), so a gap below it would be acknowledged without ever being processed. Tags above a gap are acked individually; :meth:invalidate (a new channel, where tags restart at 1) clears the gap. Tags below the first registered one count as a gap too: the coordinator must own the channel from delivery tag 1. Any SUCCESS entry AFTER the first non-success entry is acked individually (never buffered past max_hold). NACK / REJECT intents are always individual and are emitted in tag order interleaved with acks, so a later prefix decision can never leap over an unsettled reject.

Thread-safe: every method takes the internal lock. Command emission is the adapter's job and must happen on the transport owner (sync I/O thread / event loop).

Source code in src/rabbitkit/core/settlement.py
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 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
class SettlementCoordinator:
    """Channel-wide delivery ledger with provably safe ack coalescing.

    One coordinator per channel generation. EVERY delivery on that channel
    must be :meth:`register`-ed before its handler runs; if that ownership
    cannot be guaranteed (another consumer shares the channel and does not
    register), coalescing is unsafe — construct with ``coalesce=False``.

    Decision rule for a cumulative ack: let ``P`` be the longest prefix of
    the ledger (ascending tag order) in which every entry is ``SUCCESS``.
    If ``|P| >= 2`` emit ``ack(max(P), multiple=True)``; ``|P| == 1`` is a
    plain individual ack. ``max(P)`` must also lie below the generation's
    first *gap* -- the lowest delivery tag that was never registered (refused
    by ``max_pending``, consumed by someone else on the channel, or skipped
    by the caller). The broker settles EVERY unacked tag up to ``max(P)``, so
    a gap below it would be acknowledged without ever being processed. Tags
    above a gap are acked individually; :meth:`invalidate` (a new channel,
    where tags restart at 1) clears the gap. Tags below the first registered
    one count as a gap too: the coordinator must own the channel from
    delivery tag 1. Any ``SUCCESS`` entry AFTER the first non-success
    entry is acked individually (never buffered past ``max_hold``). NACK /
    REJECT intents are always individual and are emitted in tag order
    interleaved with acks, so a later prefix decision can never leap over
    an unsettled reject.

    Thread-safe: every method takes the internal lock. Command *emission*
    is the adapter's job and must happen on the transport owner (sync I/O
    thread / event loop).
    """

    #: Which state transitions are legal. Repeating the SAME state is an
    #: idempotent no-op (handled before this table); anything not listed is a
    #: contradiction. SUCCESS is reachable ONLY from OUTSTANDING/RETRY_PENDING
    #: — a delivery that FAILED or was CANCELLED can never be acked (I3).
    _TRANSITIONS: ClassVar[dict[DeliveryState, frozenset[DeliveryState]]] = {
        DeliveryState.OUTSTANDING: frozenset(
            {
                DeliveryState.SUCCESS,
                DeliveryState.NACK,
                DeliveryState.REJECT,
                DeliveryState.RETRY_PENDING,
                DeliveryState.FAILED,
                DeliveryState.CANCELLED,
            }
        ),
        DeliveryState.RETRY_PENDING: frozenset(
            {
                DeliveryState.SUCCESS,
                DeliveryState.NACK,
                DeliveryState.REJECT,
                DeliveryState.FAILED,
                DeliveryState.CANCELLED,
            }
        ),
        DeliveryState.FAILED: frozenset({DeliveryState.NACK, DeliveryState.REJECT}),
        DeliveryState.CANCELLED: frozenset({DeliveryState.NACK, DeliveryState.REJECT}),
        DeliveryState.SUCCESS: frozenset(),
        DeliveryState.NACK: frozenset(),
        DeliveryState.REJECT: frozenset(),
    }

    def __init__(
        self,
        *,
        generation: int = 0,
        coalesce: bool = True,
        max_hold: int = 0,
        max_pending: int = 0,
        clock: Callable[[], float] = time.monotonic,
    ) -> None:
        self._generation = generation
        self._coalesce = coalesce
        # max_hold: how many planning rounds a SUCCESS entry stranded behind
        # a blocking tag may wait for a cumulative ack before being acked
        # individually. 0 = never hold (always individual fallback).
        self._max_hold = max(0, max_hold)
        # max_pending: hard ceiling on ledger size. 0 = unbounded (default).
        # Exceeding it raises LedgerFullError from register() so the caller
        # applies backpressure — it NEVER relaxes the ack rules (I7).
        self._max_pending = max(0, max_pending)
        self._clock = clock
        self._lock = threading.Lock()
        self._ledger: dict[int, DeliveryState] = {}  # insertion == ascending tag order
        self._hold: dict[int, int] = {}
        self._requeue: dict[int, bool] = {}
        self._registered_at: dict[int, float] = {}
        self._last_registered = 0
        # Lowest delivery tag of this generation that was never registered
        # (0 = none). A cumulative ack may never reach it (see class doc).
        self._gap_floor = 0
        self._unregistered_gaps = 0
        self._prev_high_water = 0  # highest tag of any dropped generation
        self._registered_count = 0
        self._settled_count = 0
        self._coalesced_count = 0
        self._frames_sent = 0
        self._invalidations = 0
        self._dropped_on_invalidate = 0
        # plan/emit/commit protocol: tags reserved by an in-flight batch.
        # They are NOT settled yet, so they stay in the ledger, but a second
        # prepare() must not re-plan them AND nothing above them may be
        # cumulatively acked while their wire outcome is unknown.
        self._reserved: dict[int, int] = {}  # tag -> batch_id
        self._next_batch_id = 1
        self._unresolved_count = 0
        self._frames_failed = 0
        self._frames_not_attempted = 0

    # ── inspection ────────────────────────────────────────────────────────

    @property
    def generation(self) -> int:
        return self._generation

    @property
    def coalesce_enabled(self) -> bool:
        return self._coalesce

    @property
    def max_pending(self) -> int:
        return self._max_pending

    @property
    def outstanding(self) -> int:
        with self._lock:
            return sum(1 for s in self._ledger.values() if s is DeliveryState.OUTSTANDING)

    @property
    def pending(self) -> int:
        """Registered but not yet emitted (any state)."""
        with self._lock:
            return len(self._ledger)

    @property
    def ack_ready(self) -> int:
        """Deliveries approved for an ack but not yet emitted."""
        with self._lock:
            return sum(1 for s in self._ledger.values() if s.is_ack_safe)

    @property
    def frontier(self) -> int:
        """Highest tag a cumulative ack could cover right now (0 = none).

        This is the end of the leading all-SUCCESS run, NOT the highest
        completed tag — that difference is the whole point of the
        coordinator (invariant I1).
        """
        with self._lock:
            return self._frontier_locked()

    def _frontier_locked(self) -> int:
        frontier = 0
        for tag in sorted(self._ledger):
            if self._gap_floor and tag > self._gap_floor:
                break
            if self._ledger[tag].is_ack_safe:
                frontier = tag
            else:
                break
        return frontier

    @property
    def gap_count(self) -> int:
        """Blocking deliveries sitting below an ack-ready one — i.e. how many
        stragglers are stranding otherwise-settleable work."""
        with self._lock:
            tags = sorted(self._ledger)
            highest_ready = max((t for t in tags if self._ledger[t].is_ack_safe), default=0)
            return sum(1 for t in tags if t < highest_ready and self._ledger[t].blocks_frontier)

    @property
    def oldest_pending_age(self) -> float:
        """Seconds since the oldest still-unsettled delivery was registered
        (0.0 when the ledger is empty). The signal for a stuck handler
        holding the frontier back."""
        with self._lock:
            if not self._registered_at:
                return 0.0
            return max(0.0, self._clock() - min(self._registered_at.values()))

    @property
    def stats(self) -> dict[str, float]:
        """Snapshot for metrics/debugging. ``coalescing_ratio`` is
        deliveries settled per AMQP frame sent — 1.0 means no coalescing."""
        with self._lock:
            return {
                "registered": self._registered_count,
                "pending": len(self._ledger),
                "outstanding": sum(1 for s in self._ledger.values() if s is DeliveryState.OUTSTANDING),
                "ack_ready": sum(1 for s in self._ledger.values() if s.is_ack_safe),
                "frontier": self._frontier_locked(),
                "settled": self._settled_count,
                "coalesced": self._coalesced_count,
                "frames_sent": self._frames_sent,
                "coalescing_ratio": (self._settled_count / self._frames_sent) if self._frames_sent else 0.0,
                "invalidations": self._invalidations,
                "dropped_on_invalidate": self._dropped_on_invalidate,
                "reserved": len(self._reserved),
                "unresolved": self._unresolved_count,
                "frames_failed": self._frames_failed,
                "frames_not_attempted": self._frames_not_attempted,
                "gap_floor": self._gap_floor,
                "unregistered_gaps": self._unregistered_gaps,
                "oldest_pending_age": (
                    max(0.0, self._clock() - min(self._registered_at.values())) if self._registered_at else 0.0
                ),
            }

    @property
    def gap_floor(self) -> int:
        """Lowest delivery tag of this generation that was never registered
        (0 = none). No cumulative ack will reach it or anything above it."""
        with self._lock:
            return self._gap_floor

    def state_of(self, delivery_tag: int) -> DeliveryState | None:
        with self._lock:
            return self._ledger.get(delivery_tag)

    # ── registration & intents ───────────────────────────────────────────

    def register(self, delivery_tag: int) -> None:
        """Register a delivery BEFORE its handler runs. Tags must be strictly
        increasing within a generation (AMQP guarantees this per channel), so
        a redelivered message — which always arrives with a NEW, higher tag —
        registers cleanly while the old tag can never be re-registered.

        Raises :class:`LedgerFullError` when ``max_pending`` is reached. The
        refused tag is not recorded, so the next registration sees it as a
        gap and cumulative acks stop short of it for this generation.

        A tag that skips ahead (``delivery_tag > last + 1``) records a gap at
        ``last + 1`` for the same reason: the skipped deliveries are unacked
        at the broker and unknown to the ledger.
        """
        with self._lock:
            if delivery_tag <= 0:
                raise CoordinatorError(f"delivery_tag must be positive, got {delivery_tag}")
            if delivery_tag <= self._last_registered:
                raise CoordinatorError(
                    f"delivery_tag {delivery_tag} is not greater than last registered "
                    f"{self._last_registered} (stale or duplicate delivery on generation "
                    f"{self._generation})"
                )
            if self._max_pending and len(self._ledger) >= self._max_pending:
                raise LedgerFullError(
                    f"ledger holds {len(self._ledger)} unsettled deliveries (max_pending="
                    f"{self._max_pending}) on generation {self._generation}; apply backpressure "
                    "(stop consuming / lower prefetch) — the delivery stays unacked and the "
                    "broker will redeliver it."
                )
            if delivery_tag > self._last_registered + 1:
                self._unregistered_gaps += 1
                if not self._gap_floor:
                    self._gap_floor = self._last_registered + 1
            self._ledger[delivery_tag] = DeliveryState.OUTSTANDING
            self._registered_at[delivery_tag] = self._clock()
            self._last_registered = delivery_tag
            self._registered_count += 1

    def _missing(self, delivery_tag: int) -> CoordinatorError:
        """Classify a tag that is not in the ledger (best effort — all three
        are CoordinatorError and none of them ever emits a frame)."""
        if delivery_tag <= self._last_registered:
            return ContradictorySettlementError(
                f"delivery_tag {delivery_tag} was already settled or released on generation {self._generation}"
            )
        if delivery_tag <= self._prev_high_water:
            return StaleGenerationError(
                f"delivery_tag {delivery_tag} belongs to a previous generation (current is "
                f"{self._generation}); that channel is gone and the broker will redeliver "
                "the message with a new tag"
            )
        return UnknownDeliveryError(
            f"delivery_tag {delivery_tag} was never registered on generation {self._generation}"
        )

    def _set_intent(self, delivery_tag: int, state: DeliveryState, requeue: bool | None = None) -> None:
        current = self._ledger.get(delivery_tag)
        if current is None:
            raise self._missing(delivery_tag)
        if current is state:
            # Idempotent repeat — but a nack/reject that flips requeue is a
            # different decision, not a repeat.
            if requeue is not None and self._requeue.get(delivery_tag) != requeue:
                raise ContradictorySettlementError(
                    f"delivery_tag {delivery_tag} is already {state.value} with "
                    f"requeue={self._requeue.get(delivery_tag)}; cannot change it to requeue={requeue}"
                )
            return
        if state not in self._TRANSITIONS[current]:
            raise ContradictorySettlementError(
                f"delivery_tag {delivery_tag} is {current.value}; refusing to change it to "
                f"{state.value} (legal next states: "
                f"{sorted(x.value for x in self._TRANSITIONS[current]) or 'none — terminal'})"
            )
        self._ledger[delivery_tag] = state
        if requeue is not None:
            self._requeue[delivery_tag] = requeue

    def mark_success(self, delivery_tag: int) -> None:
        """Handler succeeded: the delivery is ack-safe. Idempotent."""
        with self._lock:
            self._set_intent(delivery_tag, DeliveryState.SUCCESS)

    def mark_retry_pending(self, delivery_tag: int) -> None:
        """Handler failed and the retry/terminal path now owns this delivery.
        It is NOT settleable through the coordinator; it blocks any
        cumulative ack above it until :meth:`release` (settled elsewhere)."""
        with self._lock:
            self._set_intent(delivery_tag, DeliveryState.RETRY_PENDING)

    def mark_failed(self, delivery_tag: int) -> None:
        """Handler failed with no settlement decision: block the frontier and
        never emit anything. The delivery stays unacked, so the broker
        redelivers it when the channel closes. It can still be settled
        explicitly with :meth:`mark_nack` / :meth:`mark_reject`, but never
        acked."""
        with self._lock:
            self._set_intent(delivery_tag, DeliveryState.FAILED)

    def mark_cancelled(self, delivery_tag: int) -> None:
        """Handler was cancelled (shutdown, timeout): same treatment as
        :meth:`mark_failed` — blocks the frontier, never acked."""
        with self._lock:
            self._set_intent(delivery_tag, DeliveryState.CANCELLED)

    def mark_nack(self, delivery_tag: int, *, requeue: bool = True) -> None:
        with self._lock:
            self._set_intent(delivery_tag, DeliveryState.NACK, requeue=requeue)

    def mark_reject(self, delivery_tag: int, *, requeue: bool = False) -> None:
        with self._lock:
            self._set_intent(delivery_tag, DeliveryState.REJECT, requeue=requeue)

    def release(self, delivery_tag: int) -> None:
        """Remove a delivery that was settled OUTSIDE the coordinator (e.g. by
        the retry middleware's own ack after a confirmed handoff, or a
        MANUAL handler). Unknown tags are ignored (idempotent)."""
        with self._lock:
            self._ledger.pop(delivery_tag, None)
            self._hold.pop(delivery_tag, None)
            self._requeue.pop(delivery_tag, None)
            self._registered_at.pop(delivery_tag, None)

    # ── planning ─────────────────────────────────────────────────────────

    def _plan_locked(self, *, force_individual: bool) -> tuple[list[SettlementCommand], set[int]]:
        """The planning walk. Caller must hold ``self._lock``.

        Returns the commands and the set of tags they cover. Nothing is
        removed from the ledger here — consuming is the caller's decision,
        which is what makes the plan/emit/commit protocol possible.

        Walks the ledger in ascending tag order and coalesces each contiguous
        run of ack-safe deliveries. A nack/reject in the middle is emitted
        individually and, because it settles that tag on the wire first, the
        run AFTER it can form a new cumulative range::

            101 SUCCESS  102 SUCCESS  103 NACK  104 SUCCESS  105 SUCCESS
            -> ack(102, multiple=True), nack(103), ack(105, multiple=True)

        The moment a BLOCKING delivery is reached (still outstanding, retry-
        pending, failed, cancelled, or RESERVED by an in-flight batch) no
        cumulative ack may reach past it again in this plan: everything above
        is acked individually, optionally after a bounded hold.

        Commands come back in ascending tag order and MUST be emitted in that
        order. A cumulative ack is only correct because the frames below it
        went out first -- see :func:`emit_batch`, which is the only supported
        way to put a plan on the wire.
        """
        commands: list[SettlementCommand] = []
        covered: set[int] = set()
        run: list[int] = []  # current contiguous ack-safe run
        blocked = False  # a blocking delivery has been passed

        gap_floor = self._gap_floor

        def flush_run() -> None:
            if not run:
                return
            # A cumulative ack settles EVERY unacked tag up to its own, so it
            # may only cover tags below the first gap (a tag the ledger never
            # saw is still unacked at the broker). The rest go individually.
            if gap_floor:
                safe = [t for t in run if t < gap_floor]
                rest = run[len(safe) :]
            else:
                safe, rest = run, []
            if self._coalesce and not force_individual and len(safe) >= 2:
                commands.append(
                    SettlementCommand(
                        kind=SettlementAction.ACK,
                        delivery_tag=safe[-1],
                        multiple=True,
                        covers=tuple(safe),
                        generation=self._generation,
                    )
                )
            else:
                rest = run
            commands.extend(
                SettlementCommand(
                    kind=SettlementAction.ACK,
                    delivery_tag=t,
                    multiple=False,
                    covers=(t,),
                    generation=self._generation,
                )
                for t in rest
            )
            covered.update(run)
            run.clear()

        for tag in sorted(self._ledger):
            # A reserved tag is on the wire with an UNKNOWN outcome. It may
            # still be unacknowledged at the broker, so no cumulative ack may
            # sweep past it and it must not be planned twice.
            if tag in self._reserved:
                flush_run()
                blocked = True
                continue
            state = self._ledger[tag]
            if state.is_ack_safe:
                if not blocked:
                    run.append(tag)
                    continue
                # Stranded behind a blocker: hold briefly hoping the blocker
                # resolves, then fall back to an individual ack so one slow
                # handler cannot pin its siblings forever.
                if self._coalesce and not force_individual and self._hold.get(tag, 0) < self._max_hold:
                    self._hold[tag] = self._hold.get(tag, 0) + 1
                    continue
                commands.append(
                    SettlementCommand(
                        kind=SettlementAction.ACK,
                        delivery_tag=tag,
                        multiple=False,
                        covers=(tag,),
                        generation=self._generation,
                    )
                )
                covered.add(tag)
            elif state is DeliveryState.NACK or state is DeliveryState.REJECT:
                # Settles this tag on the wire before anything above it, so it
                # does NOT block a later cumulative range -- PROVIDED it
                # actually reaches the broker. emit_batch enforces that.
                flush_run()
                commands.append(
                    SettlementCommand(
                        kind=SettlementAction.NACK if state is DeliveryState.NACK else SettlementAction.REJECT,
                        delivery_tag=tag,
                        requeue=self._requeue.get(tag, state is DeliveryState.NACK),
                        covers=(tag,),
                        generation=self._generation,
                    )
                )
                covered.add(tag)
            else:  # OUTSTANDING / RETRY_PENDING / FAILED / CANCELLED
                flush_run()
                blocked = True
        flush_run()
        commands.sort(key=lambda c: c.delivery_tag)
        return commands, covered

    def _settle_tags_locked(self, tags: Iterable[int]) -> None:
        """Drop tags from the ledger for good. Caller holds ``self._lock``."""
        for tag in tags:
            self._ledger.pop(tag, None)
            self._hold.pop(tag, None)
            self._requeue.pop(tag, None)
            self._registered_at.pop(tag, None)
            self._reserved.pop(tag, None)

    def prepare(self, *, force_individual: bool = False) -> SettlementBatch:
        """Plan the commands that are safe to emit now, WITHOUT settling them.

        The covered tags are *reserved*: they stay in the ledger, a second
        ``prepare()`` will not re-plan them, and nothing above them may be
        cumulatively acked while their wire outcome is unknown. Resolve the
        batch with :func:`emit_batch`, or by hand via
        :meth:`commit_command` / :meth:`fail_command` / :meth:`release_commands`.

        Every command MUST be emitted in the order given, and a command must
        never be emitted after an earlier one failed.
        """
        with self._lock:
            if not self._ledger:
                return SettlementBatch(commands=(), generation=self._generation, batch_id=0)
            commands, covered = self._plan_locked(force_individual=force_individual)
            batch_id = self._next_batch_id
            self._next_batch_id += 1
            for tag in covered:
                self._reserved[tag] = batch_id
            return SettlementBatch(
                commands=tuple(commands),
                generation=self._generation,
                batch_id=batch_id,
            )

    def commit_command(self, batch: SettlementBatch, command: SettlementCommand) -> None:
        """The frame reached the broker: settle its tags for good.

        A no-op when the generation moved on under us (the channel was rebuilt
        mid-batch), because those tags are already gone and the broker will
        redeliver them.
        """
        with self._lock:
            if batch.generation != self._generation:
                return
            self._settle_tags_locked(command.covers)
            self._settled_count += len(command.covers)
            self._frames_sent += 1
            if command.multiple and len(command.covers) > 1:
                self._coalesced_count += len(command.covers)

    def fail_command(self, batch: SettlementBatch, command: SettlementCommand, error: BaseException) -> bool:
        """The frame did NOT reach the broker, or we cannot tell.

        The covered tags become UNRESOLVED: they leave the ledger and are
        never re-emitted, because re-sending a settlement whose first attempt
        may have landed is how you turn an ambiguity into a protocol error.
        Leaving them unacknowledged is always safe -- the broker redelivers
        them when the channel goes away.

        Returns True when the generation was invalidated, which the caller
        must treat as "this channel can no longer be used for coalescing".
        That happens for a failed NACK or REJECT: the tag may still be
        unacknowledged at the broker, so ANY later cumulative ack above it
        would silently acknowledge the very delivery we meant to requeue.
        An ACK that fails is not dangerous in the same way -- a later
        cumulative ack sweeping it up produces exactly the intended outcome.
        """
        with self._lock:
            if batch.generation != self._generation:
                return False
            self._settle_tags_locked(command.covers)
            self._unresolved_count += len(command.covers)
            self._frames_failed += 1
            must_invalidate = command.kind in (SettlementAction.NACK, SettlementAction.REJECT)
        if must_invalidate:
            self.invalidate()
            return True
        return False

    def release_commands(self, batch: SettlementBatch, commands: Sequence[SettlementCommand]) -> None:
        """These commands were never attempted: un-reserve their tags.

        They go back to being ordinary ledger entries and will be planned
        again on the next :meth:`prepare`. Nothing reached the wire, so this
        is always safe.
        """
        with self._lock:
            if batch.generation != self._generation:
                return
            for command in commands:
                for tag in command.covers:
                    if self._reserved.get(tag) == batch.batch_id:
                        del self._reserved[tag]
                self._frames_not_attempted += 1

    def plan(self, *, force_individual: bool = False) -> list[SettlementCommand]:
        """Plan AND immediately settle every command in the ledger.

        This is the pure-planning primitive. It assumes the caller emits every
        returned command, in order, and that they all succeed -- so it is only
        appropriate for tests, for ``TestBroker``, and for callers that supply
        their own ordering and failure guarantees.

        For anything that touches a real channel use :meth:`prepare` plus
        :func:`emit_batch`, which stops on the first failure instead of
        letting a cumulative ack follow a nack that never landed.
        """
        with self._lock:
            if not self._ledger:
                return []
            commands, covered = self._plan_locked(force_individual=force_individual)
            self._settle_tags_locked(covered)
            self._settled_count += len(covered)
            self._frames_sent += len(commands)
            self._coalesced_count += sum(len(c.covers) for c in commands if c.multiple and len(c.covers) > 1)
            return commands

    # ── lifecycle ────────────────────────────────────────────────────────

    def invalidate(self) -> tuple[int, ...]:
        """Reconnect / channel rebuild: drop the WHOLE ledger and bump the
        generation. Returns the dropped tags for logging. Old tags must never
        be replayed onto the replacement channel — the broker will redeliver
        every unacked message on it anyway (invariants I2, I5)."""
        with self._lock:
            dropped = tuple(sorted(self._ledger))
            self._prev_high_water = max(self._prev_high_water, self._last_registered)
            self._ledger.clear()
            self._hold.clear()
            self._requeue.clear()
            self._registered_at.clear()
            # Any in-flight batch is void: its generation no longer matches,
            # so commit/fail/release for it become no-ops.
            self._reserved.clear()
            self._last_registered = 0
            self._gap_floor = 0
            self._generation += 1
            self._invalidations += 1
            self._dropped_on_invalidate += len(dropped)
            return dropped

    def drain_plan(self) -> list[SettlementCommand]:
        """Shutdown: plan AND settle everything already approved.

        Individual frames only — at shutdown there is no reason to wait for a
        prefix. Every blocking delivery is left UNACKED for redelivery; this
        never acks merely to empty the ledger (invariant I6). Same caveat as
        :meth:`plan`: use :meth:`prepare_drain` for a real channel.
        """
        return self.plan(force_individual=True)

    def prepare_drain(self) -> SettlementBatch:
        """Shutdown equivalent of :meth:`prepare`: individual frames only."""
        return self.prepare(force_individual=True)

Attributes

pending: int property

Registered but not yet emitted (any state).

ack_ready: int property

Deliveries approved for an ack but not yet emitted.

frontier: int property

Highest tag a cumulative ack could cover right now (0 = none).

This is the end of the leading all-SUCCESS run, NOT the highest completed tag — that difference is the whole point of the coordinator (invariant I1).

gap_count: int property

Blocking deliveries sitting below an ack-ready one — i.e. how many stragglers are stranding otherwise-settleable work.

oldest_pending_age: float property

Seconds since the oldest still-unsettled delivery was registered (0.0 when the ledger is empty). The signal for a stuck handler holding the frontier back.

stats: dict[str, float] property

Snapshot for metrics/debugging. coalescing_ratio is deliveries settled per AMQP frame sent — 1.0 means no coalescing.

gap_floor: int property

Lowest delivery tag of this generation that was never registered (0 = none). No cumulative ack will reach it or anything above it.

Methods:

register(delivery_tag: int) -> None

Register a delivery BEFORE its handler runs. Tags must be strictly increasing within a generation (AMQP guarantees this per channel), so a redelivered message — which always arrives with a NEW, higher tag — registers cleanly while the old tag can never be re-registered.

Raises :class:LedgerFullError when max_pending is reached. The refused tag is not recorded, so the next registration sees it as a gap and cumulative acks stop short of it for this generation.

A tag that skips ahead (delivery_tag > last + 1) records a gap at last + 1 for the same reason: the skipped deliveries are unacked at the broker and unknown to the ledger.

Source code in src/rabbitkit/core/settlement.py
def register(self, delivery_tag: int) -> None:
    """Register a delivery BEFORE its handler runs. Tags must be strictly
    increasing within a generation (AMQP guarantees this per channel), so
    a redelivered message — which always arrives with a NEW, higher tag —
    registers cleanly while the old tag can never be re-registered.

    Raises :class:`LedgerFullError` when ``max_pending`` is reached. The
    refused tag is not recorded, so the next registration sees it as a
    gap and cumulative acks stop short of it for this generation.

    A tag that skips ahead (``delivery_tag > last + 1``) records a gap at
    ``last + 1`` for the same reason: the skipped deliveries are unacked
    at the broker and unknown to the ledger.
    """
    with self._lock:
        if delivery_tag <= 0:
            raise CoordinatorError(f"delivery_tag must be positive, got {delivery_tag}")
        if delivery_tag <= self._last_registered:
            raise CoordinatorError(
                f"delivery_tag {delivery_tag} is not greater than last registered "
                f"{self._last_registered} (stale or duplicate delivery on generation "
                f"{self._generation})"
            )
        if self._max_pending and len(self._ledger) >= self._max_pending:
            raise LedgerFullError(
                f"ledger holds {len(self._ledger)} unsettled deliveries (max_pending="
                f"{self._max_pending}) on generation {self._generation}; apply backpressure "
                "(stop consuming / lower prefetch) — the delivery stays unacked and the "
                "broker will redeliver it."
            )
        if delivery_tag > self._last_registered + 1:
            self._unregistered_gaps += 1
            if not self._gap_floor:
                self._gap_floor = self._last_registered + 1
        self._ledger[delivery_tag] = DeliveryState.OUTSTANDING
        self._registered_at[delivery_tag] = self._clock()
        self._last_registered = delivery_tag
        self._registered_count += 1

mark_success(delivery_tag: int) -> None

Handler succeeded: the delivery is ack-safe. Idempotent.

Source code in src/rabbitkit/core/settlement.py
def mark_success(self, delivery_tag: int) -> None:
    """Handler succeeded: the delivery is ack-safe. Idempotent."""
    with self._lock:
        self._set_intent(delivery_tag, DeliveryState.SUCCESS)

mark_retry_pending(delivery_tag: int) -> None

Handler failed and the retry/terminal path now owns this delivery. It is NOT settleable through the coordinator; it blocks any cumulative ack above it until :meth:release (settled elsewhere).

Source code in src/rabbitkit/core/settlement.py
def mark_retry_pending(self, delivery_tag: int) -> None:
    """Handler failed and the retry/terminal path now owns this delivery.
    It is NOT settleable through the coordinator; it blocks any
    cumulative ack above it until :meth:`release` (settled elsewhere)."""
    with self._lock:
        self._set_intent(delivery_tag, DeliveryState.RETRY_PENDING)

mark_failed(delivery_tag: int) -> None

Handler failed with no settlement decision: block the frontier and never emit anything. The delivery stays unacked, so the broker redelivers it when the channel closes. It can still be settled explicitly with :meth:mark_nack / :meth:mark_reject, but never acked.

Source code in src/rabbitkit/core/settlement.py
def mark_failed(self, delivery_tag: int) -> None:
    """Handler failed with no settlement decision: block the frontier and
    never emit anything. The delivery stays unacked, so the broker
    redelivers it when the channel closes. It can still be settled
    explicitly with :meth:`mark_nack` / :meth:`mark_reject`, but never
    acked."""
    with self._lock:
        self._set_intent(delivery_tag, DeliveryState.FAILED)

mark_cancelled(delivery_tag: int) -> None

Handler was cancelled (shutdown, timeout): same treatment as :meth:mark_failed — blocks the frontier, never acked.

Source code in src/rabbitkit/core/settlement.py
def mark_cancelled(self, delivery_tag: int) -> None:
    """Handler was cancelled (shutdown, timeout): same treatment as
    :meth:`mark_failed` — blocks the frontier, never acked."""
    with self._lock:
        self._set_intent(delivery_tag, DeliveryState.CANCELLED)

release(delivery_tag: int) -> None

Remove a delivery that was settled OUTSIDE the coordinator (e.g. by the retry middleware's own ack after a confirmed handoff, or a MANUAL handler). Unknown tags are ignored (idempotent).

Source code in src/rabbitkit/core/settlement.py
def release(self, delivery_tag: int) -> None:
    """Remove a delivery that was settled OUTSIDE the coordinator (e.g. by
    the retry middleware's own ack after a confirmed handoff, or a
    MANUAL handler). Unknown tags are ignored (idempotent)."""
    with self._lock:
        self._ledger.pop(delivery_tag, None)
        self._hold.pop(delivery_tag, None)
        self._requeue.pop(delivery_tag, None)
        self._registered_at.pop(delivery_tag, None)

prepare(*, force_individual: bool = False) -> SettlementBatch

Plan the commands that are safe to emit now, WITHOUT settling them.

The covered tags are reserved: they stay in the ledger, a second prepare() will not re-plan them, and nothing above them may be cumulatively acked while their wire outcome is unknown. Resolve the batch with :func:emit_batch, or by hand via :meth:commit_command / :meth:fail_command / :meth:release_commands.

Every command MUST be emitted in the order given, and a command must never be emitted after an earlier one failed.

Source code in src/rabbitkit/core/settlement.py
def prepare(self, *, force_individual: bool = False) -> SettlementBatch:
    """Plan the commands that are safe to emit now, WITHOUT settling them.

    The covered tags are *reserved*: they stay in the ledger, a second
    ``prepare()`` will not re-plan them, and nothing above them may be
    cumulatively acked while their wire outcome is unknown. Resolve the
    batch with :func:`emit_batch`, or by hand via
    :meth:`commit_command` / :meth:`fail_command` / :meth:`release_commands`.

    Every command MUST be emitted in the order given, and a command must
    never be emitted after an earlier one failed.
    """
    with self._lock:
        if not self._ledger:
            return SettlementBatch(commands=(), generation=self._generation, batch_id=0)
        commands, covered = self._plan_locked(force_individual=force_individual)
        batch_id = self._next_batch_id
        self._next_batch_id += 1
        for tag in covered:
            self._reserved[tag] = batch_id
        return SettlementBatch(
            commands=tuple(commands),
            generation=self._generation,
            batch_id=batch_id,
        )

commit_command(batch: SettlementBatch, command: SettlementCommand) -> None

The frame reached the broker: settle its tags for good.

A no-op when the generation moved on under us (the channel was rebuilt mid-batch), because those tags are already gone and the broker will redeliver them.

Source code in src/rabbitkit/core/settlement.py
def commit_command(self, batch: SettlementBatch, command: SettlementCommand) -> None:
    """The frame reached the broker: settle its tags for good.

    A no-op when the generation moved on under us (the channel was rebuilt
    mid-batch), because those tags are already gone and the broker will
    redeliver them.
    """
    with self._lock:
        if batch.generation != self._generation:
            return
        self._settle_tags_locked(command.covers)
        self._settled_count += len(command.covers)
        self._frames_sent += 1
        if command.multiple and len(command.covers) > 1:
            self._coalesced_count += len(command.covers)

fail_command(batch: SettlementBatch, command: SettlementCommand, error: BaseException) -> bool

The frame did NOT reach the broker, or we cannot tell.

The covered tags become UNRESOLVED: they leave the ledger and are never re-emitted, because re-sending a settlement whose first attempt may have landed is how you turn an ambiguity into a protocol error. Leaving them unacknowledged is always safe -- the broker redelivers them when the channel goes away.

Returns True when the generation was invalidated, which the caller must treat as "this channel can no longer be used for coalescing". That happens for a failed NACK or REJECT: the tag may still be unacknowledged at the broker, so ANY later cumulative ack above it would silently acknowledge the very delivery we meant to requeue. An ACK that fails is not dangerous in the same way -- a later cumulative ack sweeping it up produces exactly the intended outcome.

Source code in src/rabbitkit/core/settlement.py
def fail_command(self, batch: SettlementBatch, command: SettlementCommand, error: BaseException) -> bool:
    """The frame did NOT reach the broker, or we cannot tell.

    The covered tags become UNRESOLVED: they leave the ledger and are
    never re-emitted, because re-sending a settlement whose first attempt
    may have landed is how you turn an ambiguity into a protocol error.
    Leaving them unacknowledged is always safe -- the broker redelivers
    them when the channel goes away.

    Returns True when the generation was invalidated, which the caller
    must treat as "this channel can no longer be used for coalescing".
    That happens for a failed NACK or REJECT: the tag may still be
    unacknowledged at the broker, so ANY later cumulative ack above it
    would silently acknowledge the very delivery we meant to requeue.
    An ACK that fails is not dangerous in the same way -- a later
    cumulative ack sweeping it up produces exactly the intended outcome.
    """
    with self._lock:
        if batch.generation != self._generation:
            return False
        self._settle_tags_locked(command.covers)
        self._unresolved_count += len(command.covers)
        self._frames_failed += 1
        must_invalidate = command.kind in (SettlementAction.NACK, SettlementAction.REJECT)
    if must_invalidate:
        self.invalidate()
        return True
    return False

release_commands(batch: SettlementBatch, commands: Sequence[SettlementCommand]) -> None

These commands were never attempted: un-reserve their tags.

They go back to being ordinary ledger entries and will be planned again on the next :meth:prepare. Nothing reached the wire, so this is always safe.

Source code in src/rabbitkit/core/settlement.py
def release_commands(self, batch: SettlementBatch, commands: Sequence[SettlementCommand]) -> None:
    """These commands were never attempted: un-reserve their tags.

    They go back to being ordinary ledger entries and will be planned
    again on the next :meth:`prepare`. Nothing reached the wire, so this
    is always safe.
    """
    with self._lock:
        if batch.generation != self._generation:
            return
        for command in commands:
            for tag in command.covers:
                if self._reserved.get(tag) == batch.batch_id:
                    del self._reserved[tag]
            self._frames_not_attempted += 1

plan(*, force_individual: bool = False) -> list[SettlementCommand]

Plan AND immediately settle every command in the ledger.

This is the pure-planning primitive. It assumes the caller emits every returned command, in order, and that they all succeed -- so it is only appropriate for tests, for TestBroker, and for callers that supply their own ordering and failure guarantees.

For anything that touches a real channel use :meth:prepare plus :func:emit_batch, which stops on the first failure instead of letting a cumulative ack follow a nack that never landed.

Source code in src/rabbitkit/core/settlement.py
def plan(self, *, force_individual: bool = False) -> list[SettlementCommand]:
    """Plan AND immediately settle every command in the ledger.

    This is the pure-planning primitive. It assumes the caller emits every
    returned command, in order, and that they all succeed -- so it is only
    appropriate for tests, for ``TestBroker``, and for callers that supply
    their own ordering and failure guarantees.

    For anything that touches a real channel use :meth:`prepare` plus
    :func:`emit_batch`, which stops on the first failure instead of
    letting a cumulative ack follow a nack that never landed.
    """
    with self._lock:
        if not self._ledger:
            return []
        commands, covered = self._plan_locked(force_individual=force_individual)
        self._settle_tags_locked(covered)
        self._settled_count += len(covered)
        self._frames_sent += len(commands)
        self._coalesced_count += sum(len(c.covers) for c in commands if c.multiple and len(c.covers) > 1)
        return commands

invalidate() -> tuple[int, ...]

Reconnect / channel rebuild: drop the WHOLE ledger and bump the generation. Returns the dropped tags for logging. Old tags must never be replayed onto the replacement channel — the broker will redeliver every unacked message on it anyway (invariants I2, I5).

Source code in src/rabbitkit/core/settlement.py
def invalidate(self) -> tuple[int, ...]:
    """Reconnect / channel rebuild: drop the WHOLE ledger and bump the
    generation. Returns the dropped tags for logging. Old tags must never
    be replayed onto the replacement channel — the broker will redeliver
    every unacked message on it anyway (invariants I2, I5)."""
    with self._lock:
        dropped = tuple(sorted(self._ledger))
        self._prev_high_water = max(self._prev_high_water, self._last_registered)
        self._ledger.clear()
        self._hold.clear()
        self._requeue.clear()
        self._registered_at.clear()
        # Any in-flight batch is void: its generation no longer matches,
        # so commit/fail/release for it become no-ops.
        self._reserved.clear()
        self._last_registered = 0
        self._gap_floor = 0
        self._generation += 1
        self._invalidations += 1
        self._dropped_on_invalidate += len(dropped)
        return dropped

drain_plan() -> list[SettlementCommand]

Shutdown: plan AND settle everything already approved.

Individual frames only — at shutdown there is no reason to wait for a prefix. Every blocking delivery is left UNACKED for redelivery; this never acks merely to empty the ledger (invariant I6). Same caveat as :meth:plan: use :meth:prepare_drain for a real channel.

Source code in src/rabbitkit/core/settlement.py
def drain_plan(self) -> list[SettlementCommand]:
    """Shutdown: plan AND settle everything already approved.

    Individual frames only — at shutdown there is no reason to wait for a
    prefix. Every blocking delivery is left UNACKED for redelivery; this
    never acks merely to empty the ledger (invariant I6). Same caveat as
    :meth:`plan`: use :meth:`prepare_drain` for a real channel.
    """
    return self.plan(force_individual=True)

prepare_drain() -> SettlementBatch

Shutdown equivalent of :meth:prepare: individual frames only.

Source code in src/rabbitkit/core/settlement.py
def prepare_drain(self) -> SettlementBatch:
    """Shutdown equivalent of :meth:`prepare`: individual frames only."""
    return self.prepare(force_individual=True)

SettlementCommand dataclass

One wire command the transport adapter must issue, in order.

covers lists every delivery tag this command settles (for a cumulative ack that is the whole approved prefix) so adapters and tests can account for each tag exactly once.

Source code in src/rabbitkit/core/settlement.py
@dataclass(frozen=True, slots=True)
class SettlementCommand:
    """One wire command the transport adapter must issue, in order.

    ``covers`` lists every delivery tag this command settles (for a
    cumulative ack that is the whole approved prefix) so adapters and tests
    can account for each tag exactly once.
    """

    kind: SettlementAction
    delivery_tag: int
    multiple: bool = False
    requeue: bool = False
    covers: tuple[int, ...] = ()
    generation: int = 0

DeliveryState

Bases: str, Enum

Ledger state of one delivery inside a SettlementCoordinator.

A delivery being finished is not the same as being safe to ack. Only SUCCESS may advance the cumulative-ack frontier; only SUCCESS / NACK / REJECT are emitted at all::

OUTSTANDING ──┬─> SUCCESS        ack-safe, advances the frontier
              ├─> NACK           emitted individually, then settled
              ├─> REJECT         emitted individually, then settled
              ├─> RETRY_PENDING ─┐ owned elsewhere, blocks the frontier
              ├─> FAILED         │ blocks the frontier, never emitted
              └─> CANCELLED      │ blocks the frontier, never emitted
                                 └─> SUCCESS / NACK / REJECT

SUCCESS is reachable only from OUTSTANDING or RETRY_PENDING: a delivery whose handler failed or was cancelled can never be acked (invariant I3). FAILED and CANCELLED deliveries are left unacked so the broker redelivers them; release() drops them from the ledger when something else settled them.

Source code in src/rabbitkit/core/types.py
class DeliveryState(str, Enum):
    """Ledger state of one delivery inside a ``SettlementCoordinator``.

    A delivery being *finished* is not the same as being *safe to ack*. Only
    ``SUCCESS`` may advance the cumulative-ack frontier; only ``SUCCESS`` /
    ``NACK`` / ``REJECT`` are emitted at all::

        OUTSTANDING ──┬─> SUCCESS        ack-safe, advances the frontier
                      ├─> NACK           emitted individually, then settled
                      ├─> REJECT         emitted individually, then settled
                      ├─> RETRY_PENDING ─┐ owned elsewhere, blocks the frontier
                      ├─> FAILED         │ blocks the frontier, never emitted
                      └─> CANCELLED      │ blocks the frontier, never emitted
                                         └─> SUCCESS / NACK / REJECT

    ``SUCCESS`` is reachable only from ``OUTSTANDING`` or ``RETRY_PENDING``:
    a delivery whose handler failed or was cancelled can never be acked
    (invariant I3). ``FAILED`` and ``CANCELLED`` deliveries are left unacked
    so the broker redelivers them; ``release()`` drops them from the ledger
    when something else settled them.
    """

    #: Registered, handler still running. Blocks the frontier.
    OUTSTANDING = "outstanding"
    #: Handler succeeded — ack-safe (the plan's ACK_READY).
    SUCCESS = "success"
    #: Handed to the retry/terminal path; it owns settlement. Blocks.
    RETRY_PENDING = "retry_pending"
    #: Handler failed with no settlement decision. Blocks; never emitted.
    FAILED = "failed"
    #: Handler was cancelled (shutdown, timeout). Blocks; never emitted.
    CANCELLED = "cancelled"
    #: Approved for an individual nack.
    NACK = "nack"
    #: Approved for an individual reject.
    REJECT = "reject"

    @property
    def is_ack_safe(self) -> bool:
        """Only this state may advance the cumulative-ack frontier."""
        return self is DeliveryState.SUCCESS

    @property
    def is_emittable(self) -> bool:
        """True when the coordinator may put a frame on the wire for it."""
        return self in (DeliveryState.SUCCESS, DeliveryState.NACK, DeliveryState.REJECT)

    @property
    def blocks_frontier(self) -> bool:
        """True when a cumulative ack may not reach past this delivery."""
        return not self.is_emittable

Attributes

is_ack_safe: bool property

Only this state may advance the cumulative-ack frontier.

is_emittable: bool property

True when the coordinator may put a frame on the wire for it.

blocks_frontier: bool property

True when a cumulative ack may not reach past this delivery.

CoordinatorError

Bases: RuntimeError

Invalid use of :class:SettlementCoordinator. Base class for the specific errors below; catching it catches all of them.

Source code in src/rabbitkit/core/settlement.py
class CoordinatorError(RuntimeError):
    """Invalid use of :class:`SettlementCoordinator`. Base class for the
    specific errors below; catching it catches all of them."""

UnknownDeliveryError

Bases: CoordinatorError

A delivery tag that was never registered on this generation.

Silently ignoring it would let a caller bug corrupt the frontier, so it is always loud. A tag from an OLDER generation (the channel was rebuilt under you) raises :class:StaleGenerationError instead.

Source code in src/rabbitkit/core/settlement.py
class UnknownDeliveryError(CoordinatorError):
    """A delivery tag that was never registered on this generation.

    Silently ignoring it would let a caller bug corrupt the frontier, so it
    is always loud. A tag from an OLDER generation (the channel was rebuilt
    under you) raises :class:`StaleGenerationError` instead.
    """

StaleGenerationError

Bases: CoordinatorError

A delivery tag from a previous channel generation.

The channel it arrived on is gone; the broker will redeliver the message on the new one with a NEW tag. Emitting anything for the old tag would settle an unrelated message (invariants I2, I5).

Source code in src/rabbitkit/core/settlement.py
class StaleGenerationError(CoordinatorError):
    """A delivery tag from a previous channel generation.

    The channel it arrived on is gone; the broker will redeliver the message
    on the new one with a NEW tag. Emitting anything for the old tag would
    settle an unrelated message (invariants I2, I5).
    """

ContradictorySettlementError

Bases: CoordinatorError

A settlement decision that contradicts one already recorded.

Repeating the SAME decision is an idempotent no-op; changing it (ack → nack, nack → ack, acking something that FAILED) is never silently accepted (invariant I4).

Source code in src/rabbitkit/core/settlement.py
class ContradictorySettlementError(CoordinatorError):
    """A settlement decision that contradicts one already recorded.

    Repeating the SAME decision is an idempotent no-op; changing it (ack →
    nack, nack → ack, acking something that FAILED) is never silently
    accepted (invariant I4).
    """

LedgerFullError

Bases: CoordinatorError

max_pending reached — the ledger refuses to grow further.

Raised by :meth:SettlementCoordinator.register, so the caller applies backpressure (stop consuming / lower prefetch). The delivery stays unacked and the broker redelivers it when the channel closes. Bounds NEVER cause an unsafe ack (invariant I7): the refused tag becomes a gap, and no cumulative ack on this generation will ever reach past it (deliveries above it are acked individually).

Source code in src/rabbitkit/core/settlement.py
class LedgerFullError(CoordinatorError):
    """``max_pending`` reached — the ledger refuses to grow further.

    Raised by :meth:`SettlementCoordinator.register`, so the caller applies
    backpressure (stop consuming / lower prefetch). The delivery stays
    unacked and the broker redelivers it when the channel closes. Bounds
    NEVER cause an unsafe ack (invariant I7): the refused tag becomes a
    *gap*, and no cumulative ack on this generation will ever reach past it
    (deliveries above it are acked individually).
    """

CoalescingAcker

Safe cumulative acking for ONE channel generation (plan §8.3).

Every delivery on the channel must be :meth:register-ed before its handler runs, then reported via :meth:complete / :meth:fail / :meth:retry_pending / :meth:release. flush() asks the :class:~rabbitkit.core.settlement.SettlementCoordinator for the commands that are provably safe and emits them through the three callables — ack_fn(tag, multiple), nack_fn(tag, requeue), reject_fn(tag, requeue) — which must marshal onto the transport owner (see :class:BatchAcker's notes on pika thread safety).

One acker per channel. The emit callables are bound to one channel and delivery tags are a per-channel counter, so feeding two channels' tags into one acker would ack the wrong messages. Pass channel_key (the channel object itself is the natural key — all pika/aio-pika channels are identity-hashable) and that convention becomes an enforced invariant: a delivery from any other channel raises :class:ChannelMismatchError at :meth:register time, before it can corrupt the ledger. An unbound acker binds to the first channel_key it is given. :class:CoalescingAckerGroup does this for you.

on_reconnect() invalidates the ledger; old tags are never replayed.

Pass marshal whenever flush_interval_ms > 0. The interval timer is a threading.Timer, so without it the emit callables run on a background thread instead of the transport owner. That is not merely unsupported, it fails SILENTLY: loop.create_task() from a foreign thread only raises under asyncio debug mode, so in production the task is queued without waking the loop — a busy loop happens to pick it up, an idle one never does. At prefetch=1 the loop goes idle waiting for the next delivery that the un-emitted ack would have unlocked, and the consumer deadlocks.

marshal takes a zero-argument callable and runs it on the transport owner; both standard entry points match that signature directly, so it is one argument, not a wrapper around each callable::

# asyncio / aio-pika
acker = CoalescingAcker(..., marshal=loop.call_soon_threadsafe)

# pika
acker = CoalescingAcker(..., marshal=connection.add_callback_threadsafe)

With marshal set, the whole interval flush — planning and emission — runs on the owner, so ordinary channel.basic_ack(...) / loop.create_task(...) callables are safe. Size-triggered and manual flushes already run on the caller's thread and are unaffected.

flush_interval_ms=0 disables the timer entirely; then no marshalling is needed because every flush is one you drive yourself.

Source code in src/rabbitkit/highload/batch.py
 874
 875
 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
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
class CoalescingAcker:
    """Safe cumulative acking for ONE channel generation (plan §8.3).

    Every delivery on the channel must be :meth:`register`-ed before its
    handler runs, then reported via :meth:`complete` / :meth:`fail` /
    :meth:`retry_pending` / :meth:`release`. ``flush()`` asks the
    :class:`~rabbitkit.core.settlement.SettlementCoordinator` for the
    commands that are provably safe and emits them through the three
    callables — ``ack_fn(tag, multiple)``, ``nack_fn(tag, requeue)``,
    ``reject_fn(tag, requeue)`` — which must marshal onto the transport
    owner (see :class:`BatchAcker`'s notes on pika thread safety).

    **One acker per channel.** The emit callables are bound to one channel
    and delivery tags are a per-channel counter, so feeding two channels'
    tags into one acker would ack the wrong messages. Pass ``channel_key``
    (the channel object itself is the natural key — all pika/aio-pika
    channels are identity-hashable) and that convention becomes an enforced
    invariant: a delivery from any other channel raises
    :class:`ChannelMismatchError` at :meth:`register` time, before it can
    corrupt the ledger. An unbound acker binds to the first ``channel_key``
    it is given. :class:`CoalescingAckerGroup` does this for you.

    ``on_reconnect()`` invalidates the ledger; old tags are never replayed.

    **Pass ``marshal`` whenever ``flush_interval_ms > 0``.** The interval
    timer is a ``threading.Timer``, so without it the emit callables run on
    a background thread instead of the transport owner. That is not merely
    unsupported, it fails SILENTLY: ``loop.create_task()`` from a foreign
    thread only raises under asyncio debug mode, so in production the task
    is queued without waking the loop — a busy loop happens to pick it up, an
    idle one never does. At ``prefetch=1`` the loop goes idle waiting for the
    next delivery that the un-emitted ack would have unlocked, and the
    consumer deadlocks.

    ``marshal`` takes a zero-argument callable and runs it on the transport
    owner; both standard entry points match that signature directly, so it is
    one argument, not a wrapper around each callable::

        # asyncio / aio-pika
        acker = CoalescingAcker(..., marshal=loop.call_soon_threadsafe)

        # pika
        acker = CoalescingAcker(..., marshal=connection.add_callback_threadsafe)

    With ``marshal`` set, the whole interval flush — planning and emission —
    runs on the owner, so ordinary ``channel.basic_ack(...)`` /
    ``loop.create_task(...)`` callables are safe. Size-triggered and manual
    flushes already run on the caller's thread and are unaffected.

    ``flush_interval_ms=0`` disables the timer entirely; then no marshalling
    is needed because every flush is one you drive yourself.
    """

    def __init__(
        self,
        *,
        ack_fn: Callable[[int, bool], Any],
        nack_fn: Callable[[int, bool], Any],
        reject_fn: Callable[[int, bool], Any],
        config: BatchAckConfig | None = None,
        max_hold: int = 2,
        coalesce: bool = True,
        channel_key: Any = None,
        max_pending: int = 0,
        marshal: Callable[[Callable[[], None]], None] | None = None,
        collector: Any = None,
        metrics_config: Any = None,
        on_flush: Callable[[CoalescingFlushReport], None] | None = None,
    ) -> None:
        self._config = config or BatchAckConfig()
        self._channel_key = channel_key
        self._ack_fn = ack_fn
        self._nack_fn = nack_fn
        self._reject_fn = reject_fn
        self._on_flush = on_flush
        self._marshal = marshal
        self._collector = collector
        self._metrics_config = metrics_config
        self._coordinator = SettlementCoordinator(coalesce=coalesce, max_hold=max_hold, max_pending=max_pending)
        self._lock = threading.Lock()
        self._flush_lock = threading.Lock()
        self._timer: threading.Timer | None = None
        self._closed = False
        self._approved_since_flush = 0
        self._warned_unmarshalled = False
        self.last_error: BaseException | None = None
        self.settled_total = 0
        self.coalesced_total = 0

    @property
    def coordinator(self) -> SettlementCoordinator:
        return self._coordinator

    @property
    def channel_key(self) -> Any:
        """The channel this acker is bound to, or ``None`` while unbound."""
        return self._channel_key

    @property
    def metrics(self) -> dict[str, float]:
        """Coordinator instrumentation for this channel: ``registered``,
        ``pending``, ``outstanding``, ``ack_ready``, ``frontier``,
        ``settled``, ``coalesced``, ``frames_sent``, ``coalescing_ratio``,
        ``gap_count``, ``oldest_pending_age``, ``invalidations``,
        ``dropped_on_invalidate``."""
        stats = self._coordinator.stats
        stats["gap_count"] = self._coordinator.gap_count
        return stats

    def _emit_metrics(self) -> None:
        """Push :attr:`metrics` into a ``MetricsCollector`` when one was
        supplied. Labels are bounded (none) — this is per-channel state, so
        wire one collector per process, not per delivery."""
        if self._collector is None or self._metrics_config is None:
            return
        cfg, stats = self._metrics_config, self.metrics
        set_gauge = getattr(self._collector, "set_gauge", None)
        if set_gauge is None:
            return
        for name, key in (
            (cfg.settlement_pending, "pending"),
            (cfg.settlement_ack_ready, "ack_ready"),
            (cfg.settlement_frontier, "frontier"),
            (cfg.settlement_gap_count, "gap_count"),
            (cfg.settlement_oldest_pending_age_seconds, "oldest_pending_age"),
            (cfg.settlement_coalescing_ratio, "coalescing_ratio"),
        ):
            set_gauge(name, {}, float(stats[key]))

    @property
    def pending(self) -> int:
        return self._coordinator.pending

    @property
    def generation(self) -> int:
        """The current channel generation.

        It advances on :meth:`on_reconnect`, and also when a failed
        nack/reject forces the acker to abandon coalescing on this channel.
        """
        return self._coordinator.generation

    @property
    def closed(self) -> bool:
        return self._closed

    # ── ledger API ───────────────────────────────────────────────────────

    def register(self, delivery_tag: int, *, channel_key: Any = None) -> None:
        """Register a delivery BEFORE its handler runs.

        Pass ``channel_key`` (normally the channel object the delivery
        arrived on) to have the one-acker-per-channel rule enforced: an
        unbound acker binds to it, a bound acker raises
        :class:`ChannelMismatchError` on anything else. Omitting it keeps the
        legacy, unchecked behavior.
        """
        with self._lock:
            if self._closed:
                raise BatchClosedError("CoalescingAcker is closed; register() rejected")
            if channel_key is not None:
                bound = self._channel_key
                if bound is None:
                    self._channel_key = channel_key  # first registration binds
                elif bound is not channel_key and bound != channel_key:
                    raise ChannelMismatchError(
                        f"delivery_tag {delivery_tag} arrived on {channel_key!r} but this "
                        f"CoalescingAcker is bound to {bound!r}. Delivery tags are a "
                        "per-channel counter — use one acker per channel "
                        "(CoalescingAckerGroup does this for you)."
                    )
        self._coordinator.register(delivery_tag)
        self._arm_timer()

    def complete(self, delivery_tag: int) -> None:
        self._coordinator.mark_success(delivery_tag)
        self._after_intent()

    def fail(self, delivery_tag: int, *, requeue: bool = True, reject: bool = False) -> None:
        if reject:
            self._coordinator.mark_reject(delivery_tag, requeue=requeue)
        else:
            self._coordinator.mark_nack(delivery_tag, requeue=requeue)
        self._after_intent()

    def retry_pending(self, delivery_tag: int) -> None:
        """The retry middleware owns this delivery now; it blocks coalescing
        above it until :meth:`release`."""
        self._coordinator.mark_retry_pending(delivery_tag)

    def abandon(self, delivery_tag: int) -> None:
        """The handler failed with no settlement decision (``FAILED``).

        Blocks the frontier and is NEVER acked — the delivery stays unacked
        so the broker redelivers it when the channel closes. Use this instead
        of leaving the tag ``OUTSTANDING`` so the ledger records that nobody
        is still working on it.
        """
        self._coordinator.mark_failed(delivery_tag)

    def cancel(self, delivery_tag: int) -> None:
        """The handler was cancelled (shutdown, timeout) — ``CANCELLED``.

        Same treatment as :meth:`abandon`: blocks the frontier, never acked.
        """
        self._coordinator.mark_cancelled(delivery_tag)

    def release(self, delivery_tag: int) -> None:
        self._coordinator.release(delivery_tag)

    def _after_intent(self) -> None:
        with self._lock:
            self._approved_since_flush += 1
            should_flush = self._approved_since_flush >= self._config.batch_size
        if should_flush:
            self.flush(FlushReason.SIZE)

    # ── timer ────────────────────────────────────────────────────────────

    def _warn_unmarshalled_timer(self) -> None:
        """One warning per acker: an interval timer without ``marshal`` runs
        the emit callables off the transport owner, which fails silently."""
        if self._warned_unmarshalled:
            return
        self._warned_unmarshalled = True
        warnings.warn(
            "CoalescingAcker has flush_interval_ms > 0 but no marshal=. The interval "
            "timer fires on a threading.Timer thread, so the emit callables will run "
            "off the transport owner — asyncio only raises for that in debug mode, so "
            "acks can be queued without ever reaching the broker (a consumer at "
            "prefetch=1 then deadlocks). Pass marshal=loop.call_soon_threadsafe "
            "(asyncio) or marshal=connection.add_callback_threadsafe (pika), or set "
            "flush_interval_ms=0 and flush yourself.",
            RuntimeWarning,
            stacklevel=3,
        )

    def _arm_timer(self) -> None:
        if self._config.flush_interval_ms > 0 and self._marshal is None:
            self._warn_unmarshalled_timer()
        with self._lock:
            if self._timer is None and self._config.flush_interval_ms > 0 and not self._closed:
                self._timer = threading.Timer(self._config.flush_interval_ms / 1000.0, self._timer_callback)
                self._timer.daemon = True
                self._timer.start()

    def _interval_flush(self) -> None:
        """The interval flush body. Runs on the transport owner when
        ``marshal`` was supplied, otherwise on the timer thread."""
        try:
            self.flush(FlushReason.INTERVAL)
        except BaseException as exc:
            self.last_error = exc
            logger.error("CoalescingAcker interval flush failed: %s", exc, exc_info=True)

    def _timer_callback(self) -> None:
        with self._lock:
            self._timer = None
        if self._marshal is None:
            self._interval_flush()
        else:
            # Hand the WHOLE flush — planning and emission — to the transport
            # owner, so the emit callables never run on this timer thread.
            try:
                self._marshal(self._interval_flush)
            except BaseException as exc:
                self.last_error = exc
                logger.error("CoalescingAcker could not marshal its interval flush: %s", exc, exc_info=True)
        if self._coordinator.pending:
            self._arm_timer()

    # ── flush / lifecycle ────────────────────────────────────────────────

    def flush(self, reason: FlushReason = FlushReason.MANUAL) -> CoalescingFlushReport:
        with self._flush_lock:
            with self._lock:
                self._approved_since_flush = 0
            batch = (
                self._coordinator.prepare_drain() if reason is FlushReason.CLOSE else self._coordinator.prepare()
            )
            # plan -> emit -> commit. The ledger only advances for frames the
            # transport actually accepted, and emission stops at the first
            # failure so a cumulative ack can never follow a nack that never
            # left the process.
            emission = emit_batch(
                batch, self._coordinator, ack=self._ack_fn, nack=self._nack_fn, reject=self._reject_fn
            )
            errors = ((emission.failed, emission.error),) if emission.failed is not None and emission.error else ()
            report = CoalescingFlushReport(
                reason=reason,
                commands=batch.commands,
                errors=errors,
                emitted=emission.emitted,
                not_attempted=emission.not_attempted,
                invalidated=emission.invalidated,
            )
            self.settled_total += report.settled_tags
            self.coalesced_total += report.coalesced_tags
            if errors:
                self.last_error = errors[0][1]
                # Previously these were recorded on last_error and nothing
                # else — a failing ack_fn was invisible in the logs.
                for command, exc in errors:
                    logger.error(
                        "CoalescingAcker failed to emit %s(delivery_tag=%d, multiple=%s) "
                        "covering %d tag(s) on generation %d: %s",
                        command.kind.value,
                        command.delivery_tag,
                        command.multiple,
                        len(command.covers),
                        command.generation,
                        exc,
                        exc_info=exc,
                    )
                if report.not_attempted:
                    logger.warning(
                        "CoalescingAcker withheld %d command(s) covering %d tag(s) after that failure: "
                        "emitting them could settle deliveries the failed command was meant to handle. "
                        "The broker will redeliver anything left unacknowledged.",
                        len(report.not_attempted),
                        sum(len(c.covers) for c in report.not_attempted),
                    )
                if report.invalidated:
                    logger.warning(
                        "CoalescingAcker invalidated generation %d: a failed nack/reject may still be "
                        "unacknowledged at the broker, so no later cumulative ack on this channel is safe.",
                        batch.generation,
                    )
            if self._collector is not None:
                inc = getattr(self._collector, "inc_counter", None)
                if inc is not None and self._metrics_config is not None and report.coalesced_tags:
                    inc(self._metrics_config.settlement_coalesced_total, {}, float(report.coalesced_tags))
                self._emit_metrics()
            if self._on_flush is not None:
                try:
                    self._on_flush(report)
                except Exception:
                    logger.exception("CoalescingAcker on_flush callback raised")
            return report

    def on_reconnect(self) -> tuple[int, ...]:
        """Channel rebuilt: drop every pending tag (never replay them)."""
        dropped = self._coordinator.invalidate()
        if dropped:
            logger.warning("CoalescingAcker dropped %d pending tags on reconnect (broker will redeliver)", len(dropped))
        with self._lock:
            self._approved_since_flush = 0
        return dropped

    def close(self) -> CoalescingFlushReport:
        with self._lock:
            self._closed = True
            timer, self._timer = self._timer, None
        if timer is not None:
            timer.cancel()
        return self.flush(FlushReason.CLOSE)

Attributes

channel_key: Any property

The channel this acker is bound to, or None while unbound.

metrics: dict[str, float] property

Coordinator instrumentation for this channel: registered, pending, outstanding, ack_ready, frontier, settled, coalesced, frames_sent, coalescing_ratio, gap_count, oldest_pending_age, invalidations, dropped_on_invalidate.

generation: int property

The current channel generation.

It advances on :meth:on_reconnect, and also when a failed nack/reject forces the acker to abandon coalescing on this channel.

Methods:

register(delivery_tag: int, *, channel_key: Any = None) -> None

Register a delivery BEFORE its handler runs.

Pass channel_key (normally the channel object the delivery arrived on) to have the one-acker-per-channel rule enforced: an unbound acker binds to it, a bound acker raises :class:ChannelMismatchError on anything else. Omitting it keeps the legacy, unchecked behavior.

Source code in src/rabbitkit/highload/batch.py
def register(self, delivery_tag: int, *, channel_key: Any = None) -> None:
    """Register a delivery BEFORE its handler runs.

    Pass ``channel_key`` (normally the channel object the delivery
    arrived on) to have the one-acker-per-channel rule enforced: an
    unbound acker binds to it, a bound acker raises
    :class:`ChannelMismatchError` on anything else. Omitting it keeps the
    legacy, unchecked behavior.
    """
    with self._lock:
        if self._closed:
            raise BatchClosedError("CoalescingAcker is closed; register() rejected")
        if channel_key is not None:
            bound = self._channel_key
            if bound is None:
                self._channel_key = channel_key  # first registration binds
            elif bound is not channel_key and bound != channel_key:
                raise ChannelMismatchError(
                    f"delivery_tag {delivery_tag} arrived on {channel_key!r} but this "
                    f"CoalescingAcker is bound to {bound!r}. Delivery tags are a "
                    "per-channel counter — use one acker per channel "
                    "(CoalescingAckerGroup does this for you)."
                )
    self._coordinator.register(delivery_tag)
    self._arm_timer()

retry_pending(delivery_tag: int) -> None

The retry middleware owns this delivery now; it blocks coalescing above it until :meth:release.

Source code in src/rabbitkit/highload/batch.py
def retry_pending(self, delivery_tag: int) -> None:
    """The retry middleware owns this delivery now; it blocks coalescing
    above it until :meth:`release`."""
    self._coordinator.mark_retry_pending(delivery_tag)

abandon(delivery_tag: int) -> None

The handler failed with no settlement decision (FAILED).

Blocks the frontier and is NEVER acked — the delivery stays unacked so the broker redelivers it when the channel closes. Use this instead of leaving the tag OUTSTANDING so the ledger records that nobody is still working on it.

Source code in src/rabbitkit/highload/batch.py
def abandon(self, delivery_tag: int) -> None:
    """The handler failed with no settlement decision (``FAILED``).

    Blocks the frontier and is NEVER acked — the delivery stays unacked
    so the broker redelivers it when the channel closes. Use this instead
    of leaving the tag ``OUTSTANDING`` so the ledger records that nobody
    is still working on it.
    """
    self._coordinator.mark_failed(delivery_tag)

cancel(delivery_tag: int) -> None

The handler was cancelled (shutdown, timeout) — CANCELLED.

Same treatment as :meth:abandon: blocks the frontier, never acked.

Source code in src/rabbitkit/highload/batch.py
def cancel(self, delivery_tag: int) -> None:
    """The handler was cancelled (shutdown, timeout) — ``CANCELLED``.

    Same treatment as :meth:`abandon`: blocks the frontier, never acked.
    """
    self._coordinator.mark_cancelled(delivery_tag)

on_reconnect() -> tuple[int, ...]

Channel rebuilt: drop every pending tag (never replay them).

Source code in src/rabbitkit/highload/batch.py
def on_reconnect(self) -> tuple[int, ...]:
    """Channel rebuilt: drop every pending tag (never replay them)."""
    dropped = self._coordinator.invalidate()
    if dropped:
        logger.warning("CoalescingAcker dropped %d pending tags on reconnect (broker will redeliver)", len(dropped))
    with self._lock:
        self._approved_since_flush = 0
    return dropped

CoalescingFlushReport dataclass

What a flush PLANNED versus what actually reached the broker.

commands is the plan. emitted is the subset whose frames the transport accepted; only those tags are settled. not_attempted were deliberately withheld after a failure, because a cumulative ack must never follow a settlement that did not land.

Source code in src/rabbitkit/highload/batch.py
@dataclass(frozen=True, slots=True)
class CoalescingFlushReport:
    """What a flush PLANNED versus what actually reached the broker.

    ``commands`` is the plan. ``emitted`` is the subset whose frames the
    transport accepted; only those tags are settled. ``not_attempted`` were
    deliberately withheld after a failure, because a cumulative ack must
    never follow a settlement that did not land.
    """

    reason: FlushReason
    commands: tuple[SettlementCommand, ...] = ()
    errors: tuple[tuple[SettlementCommand, BaseException], ...] = field(default_factory=tuple)
    emitted: tuple[SettlementCommand, ...] | None = None
    not_attempted: tuple[SettlementCommand, ...] = ()
    invalidated: bool = False

    @property
    def settled_tags(self) -> int:
        return sum(len(c.covers) for c, _ in self.ok_commands)

    @property
    def coalesced_tags(self) -> int:
        return sum(len(c.covers) for c, _ in self.ok_commands if c.multiple)

    @property
    def ok_commands(self) -> tuple[tuple[SettlementCommand, None], ...]:
        """Commands that reached the broker.

        When ``emitted`` is set (every flush through :func:`emit_batch`) it is
        authoritative. The fallback covers reports built by hand and treats
        anything not in ``errors`` as sent.
        """
        if self.emitted is not None:
            return tuple((c, None) for c in self.emitted)
        failed = {id(c) for c, _ in self.errors}
        return tuple((c, None) for c in self.commands if id(c) not in failed)

Attributes

ok_commands: tuple[tuple[SettlementCommand, None], ...] property

Commands that reached the broker.

When emitted is set (every flush through :func:emit_batch) it is authoritative. The fallback covers reports built by hand and treats anything not in errors as sent.

CoalescingAckerGroup

One :class:CoalescingAcker per channel, created on demand.

rabbitkit gives every subscriber queue its own channel, and delivery tags are a PER-CHANNEL counter — so a consumer with several queues needs several ledgers::

Channel A → CoalescingAcker A → SettlementCoordinator A
Channel B → CoalescingAcker B → SettlementCoordinator B

This group keeps that isolation for you: factory(channel) builds a fully wired acker (its ack_fn/nack_fn/reject_fn bound to THAT channel — only you know how to reach your transport), the group caches it per channel, and every per-delivery call carries the channel so a cross-channel mistake raises :class:ChannelMismatchError instead of acking the wrong messages.

Channels are used as dict keys (all pika/aio-pika channel objects are identity-hashable). The group holds a strong reference to each channel it settles on, so call :meth:on_reconnect when one is rebuilt (or :meth:reset when the whole connection is) to drop it.

Correctness does NOT depend on you making that call: a rebuilt channel is a different object, so the next :meth:for_channel builds a fresh acker with an empty ledger and the stale one is never consulted again. Calling it releases the retired acker (and its channel reference) promptly and keeps the metrics honest.

Wiring :meth:reset to the transport's on_reconnect hook is safe. The hook fires once per rebuilt connection (publisher and consumer, on both brokers, also for a broker-closed connection), after aio-pika has restored the consumers, so restored channels may already be delivering when it runs. :meth:reset therefore drops only the ledgers of channels that are closed and leaves live ones alone. Dropping a live ledger would leave its deliveries unacked on a channel the broker still considers healthy, so they would never be redelivered.

Usage::

def build(channel: Any) -> CoalescingAcker:
    return CoalescingAcker(
        ack_fn=lambda t, m: loop.create_task(channel.basic_ack(t, multiple=m)),
        nack_fn=lambda t, r: loop.create_task(channel.basic_nack(t, requeue=r)),
        reject_fn=lambda t, r: loop.create_task(channel.basic_reject(t, requeue=r)),
        config=BatchAckConfig(batch_size=50, flush_interval_ms=200),
        channel_key=channel,
        marshal=loop.call_soon_threadsafe,   # required with an interval timer
    )

group = CoalescingAckerGroup(factory=build)

@broker.subscriber(queue="orders", ack_policy=AckPolicy.MANUAL)
async def handle(body: bytes, msg: RabbitMessage) -> None:
    channel = msg.raw_message.channel
    group.register(channel, msg.delivery_tag)
    ...
    group.complete(channel, msg.delivery_tag)
Source code in src/rabbitkit/highload/batch.py
class CoalescingAckerGroup:
    """One :class:`CoalescingAcker` per channel, created on demand.

    rabbitkit gives every subscriber queue its own channel, and delivery tags
    are a PER-CHANNEL counter — so a consumer with several queues needs
    several ledgers::

        Channel A → CoalescingAcker A → SettlementCoordinator A
        Channel B → CoalescingAcker B → SettlementCoordinator B

    This group keeps that isolation for you: ``factory(channel)`` builds a
    fully wired acker (its ``ack_fn``/``nack_fn``/``reject_fn`` bound to THAT
    channel — only you know how to reach your transport), the group caches it
    per channel, and every per-delivery call carries the channel so a
    cross-channel mistake raises :class:`ChannelMismatchError` instead of
    acking the wrong messages.

    Channels are used as dict keys (all pika/aio-pika channel objects are
    identity-hashable). The group holds a strong reference to each channel it
    settles on, so call :meth:`on_reconnect` when one is rebuilt (or
    :meth:`reset` when the whole connection is) to drop it.

    Correctness does NOT depend on you making that call: a rebuilt channel is
    a different object, so the next :meth:`for_channel` builds a fresh acker
    with an empty ledger and the stale one is never consulted again. Calling
    it releases the retired acker (and its channel reference) promptly and
    keeps the metrics honest.

    Wiring :meth:`reset` to the transport's ``on_reconnect`` hook is safe.
    The hook fires once per rebuilt connection (publisher and consumer, on
    both brokers, also for a broker-closed connection), after aio-pika has
    restored the consumers, so restored channels may already be delivering
    when it runs. :meth:`reset` therefore drops only the ledgers of channels
    that are closed and leaves live ones alone. Dropping a live ledger would
    leave its deliveries unacked on a channel the broker still considers
    healthy, so they would never be redelivered.

    Usage::

        def build(channel: Any) -> CoalescingAcker:
            return CoalescingAcker(
                ack_fn=lambda t, m: loop.create_task(channel.basic_ack(t, multiple=m)),
                nack_fn=lambda t, r: loop.create_task(channel.basic_nack(t, requeue=r)),
                reject_fn=lambda t, r: loop.create_task(channel.basic_reject(t, requeue=r)),
                config=BatchAckConfig(batch_size=50, flush_interval_ms=200),
                channel_key=channel,
                marshal=loop.call_soon_threadsafe,   # required with an interval timer
            )

        group = CoalescingAckerGroup(factory=build)

        @broker.subscriber(queue="orders", ack_policy=AckPolicy.MANUAL)
        async def handle(body: bytes, msg: RabbitMessage) -> None:
            channel = msg.raw_message.channel
            group.register(channel, msg.delivery_tag)
            ...
            group.complete(channel, msg.delivery_tag)
    """

    def __init__(self, factory: Callable[[Any], CoalescingAcker]) -> None:
        self._factory = factory
        self._ackers: dict[Any, CoalescingAcker] = {}
        self._lock = threading.Lock()
        self._closed = False
        # Totals survive a channel being retired on reconnect/close, so a
        # reconnect does not silently reset the metrics.
        self._retired_settled = 0
        self._retired_coalesced = 0

    # ── inspection ───────────────────────────────────────────────────────

    @property
    def channels(self) -> int:
        """Number of channels with a live acker."""
        with self._lock:
            return len(self._ackers)

    @property
    def closed(self) -> bool:
        return self._closed

    @property
    def pending(self) -> int:
        """Registered-but-unsettled deliveries across every channel."""
        return sum(a.pending for a in self._snapshot())

    @property
    def settled_total(self) -> int:
        return self._retired_settled + sum(a.settled_total for a in self._snapshot())

    @property
    def coalesced_total(self) -> int:
        return self._retired_coalesced + sum(a.coalesced_total for a in self._snapshot())

    @property
    def last_error(self) -> BaseException | None:
        for acker in self._snapshot():
            if acker.last_error is not None:
                return acker.last_error
        return None

    @property
    def metrics(self) -> dict[str, float]:
        """Per-channel metrics summed across the group (``coalescing_ratio``
        is recomputed from the totals, not averaged)."""
        total: dict[str, float] = {}
        for acker in self._snapshot():
            for key, value in acker.metrics.items():
                if key == "coalescing_ratio":
                    continue
                total[key] = total.get(key, 0.0) + value
        total["channels"] = float(self.channels)
        total["settled"] = float(self.settled_total)
        total["coalesced"] = float(self.coalesced_total)
        frames = total.get("frames_sent", 0.0)
        total["coalescing_ratio"] = (total["settled"] / frames) if frames else 0.0
        return total

    def _snapshot(self) -> tuple[CoalescingAcker, ...]:
        with self._lock:
            return tuple(self._ackers.values())

    def _retire(self, acker: CoalescingAcker) -> None:
        self._retired_settled += acker.settled_total
        self._retired_coalesced += acker.coalesced_total

    # ── per-channel access ───────────────────────────────────────────────

    def for_channel(self, channel: Any) -> CoalescingAcker:
        """Return (creating on first use) the acker that owns *channel*."""
        with self._lock:
            if self._closed:
                raise BatchClosedError("CoalescingAckerGroup is closed; for_channel() rejected")
            acker = self._ackers.get(channel)
            if acker is not None:
                return acker
        # Build outside the lock: the factory touches the transport and must
        # not serialize every other channel behind it.
        acker = self._factory(channel)
        with self._lock:
            existing = self._ackers.get(channel)
            if existing is not None:  # another thread won the race
                return existing
            self._ackers[channel] = acker
            return acker

    # ── per-delivery API (channel-checked) ───────────────────────────────

    def register(self, channel: Any, delivery_tag: int) -> None:
        """Register a delivery BEFORE its handler runs, on *channel*'s ledger."""
        self.for_channel(channel).register(delivery_tag, channel_key=channel)

    def complete(self, channel: Any, delivery_tag: int) -> None:
        self.for_channel(channel).complete(delivery_tag)

    def fail(self, channel: Any, delivery_tag: int, *, requeue: bool = True, reject: bool = False) -> None:
        self.for_channel(channel).fail(delivery_tag, requeue=requeue, reject=reject)

    def retry_pending(self, channel: Any, delivery_tag: int) -> None:
        self.for_channel(channel).retry_pending(delivery_tag)

    def abandon(self, channel: Any, delivery_tag: int) -> None:
        """Handler failed with no settlement decision — never acked."""
        self.for_channel(channel).abandon(delivery_tag)

    def cancel(self, channel: Any, delivery_tag: int) -> None:
        """Handler was cancelled — never acked."""
        self.for_channel(channel).cancel(delivery_tag)

    def release(self, channel: Any, delivery_tag: int) -> None:
        self.for_channel(channel).release(delivery_tag)

    # ── lifecycle ────────────────────────────────────────────────────────

    def flush(self, reason: FlushReason = FlushReason.MANUAL) -> GroupFlushReport:
        """Flush every channel's acker; never let one channel's failure skip
        the others (each acker records its own errors in its report)."""
        return GroupFlushReport(reason=reason, reports=tuple(a.flush(reason) for a in self._snapshot()))

    def on_reconnect(self, channel: Any) -> tuple[int, ...]:
        """One channel was rebuilt: drop its ledger and retire its acker.

        Returns the dropped delivery tags (the broker redelivers them). The
        replacement channel is a different object, so the next
        :meth:`for_channel` builds a fresh acker for it. Unknown channels are
        a no-op, so this is safe to call from a reconnect hook that does not
        track which channels were in use.
        """
        with self._lock:
            acker = self._ackers.pop(channel, None)
        if acker is None:
            return ()
        dropped = acker.on_reconnect()
        self._retire(acker)
        return dropped

    def reset(self) -> int:
        """The connection was rebuilt: drop the ledger of every channel that
        is CLOSED. Returns the total number of dropped tags.

        A channel that is still open keeps its ledger. The reconnect hook
        fires after aio-pika has already restored the consumers, and once
        per connection (publisher and consumer), so by the time it runs a
        restored channel may already be delivering. Dropping that live
        ledger stranded its deliveries: their ``complete()`` found no
        ledger, nothing was ever acked, and the broker never redelivered
        them because the channel stayed open. A live channel's ledger is
        valid, so keeping it is always correct; a closed channel's tags are
        redelivered by the broker. A key that reports no liveness at all
        (not a pika/aio-pika channel) is dropped, as before.
        """
        with self._lock:
            ackers = []
            for channel, acker in list(self._ackers.items()):
                if _channel_open(channel):
                    continue
                del self._ackers[channel]
                ackers.append(acker)
        dropped = 0
        for acker in ackers:
            dropped += len(acker.on_reconnect())
            self._retire(acker)
        return dropped

    def close(self) -> GroupFlushReport:
        """Close every acker (draining what is approved) and clear the group."""
        with self._lock:
            self._closed = True
            ackers = tuple(self._ackers.values())
            self._ackers.clear()
        reports = []
        for acker in ackers:
            reports.append(acker.close())
            self._retire(acker)
        return GroupFlushReport(reason=FlushReason.CLOSE, reports=tuple(reports))

Attributes

channels: int property

Number of channels with a live acker.

pending: int property

Registered-but-unsettled deliveries across every channel.

metrics: dict[str, float] property

Per-channel metrics summed across the group (coalescing_ratio is recomputed from the totals, not averaged).

Methods:

for_channel(channel: Any) -> CoalescingAcker

Return (creating on first use) the acker that owns channel.

Source code in src/rabbitkit/highload/batch.py
def for_channel(self, channel: Any) -> CoalescingAcker:
    """Return (creating on first use) the acker that owns *channel*."""
    with self._lock:
        if self._closed:
            raise BatchClosedError("CoalescingAckerGroup is closed; for_channel() rejected")
        acker = self._ackers.get(channel)
        if acker is not None:
            return acker
    # Build outside the lock: the factory touches the transport and must
    # not serialize every other channel behind it.
    acker = self._factory(channel)
    with self._lock:
        existing = self._ackers.get(channel)
        if existing is not None:  # another thread won the race
            return existing
        self._ackers[channel] = acker
        return acker

register(channel: Any, delivery_tag: int) -> None

Register a delivery BEFORE its handler runs, on channel's ledger.

Source code in src/rabbitkit/highload/batch.py
def register(self, channel: Any, delivery_tag: int) -> None:
    """Register a delivery BEFORE its handler runs, on *channel*'s ledger."""
    self.for_channel(channel).register(delivery_tag, channel_key=channel)

abandon(channel: Any, delivery_tag: int) -> None

Handler failed with no settlement decision — never acked.

Source code in src/rabbitkit/highload/batch.py
def abandon(self, channel: Any, delivery_tag: int) -> None:
    """Handler failed with no settlement decision — never acked."""
    self.for_channel(channel).abandon(delivery_tag)

cancel(channel: Any, delivery_tag: int) -> None

Handler was cancelled — never acked.

Source code in src/rabbitkit/highload/batch.py
def cancel(self, channel: Any, delivery_tag: int) -> None:
    """Handler was cancelled — never acked."""
    self.for_channel(channel).cancel(delivery_tag)

flush(reason: FlushReason = FlushReason.MANUAL) -> GroupFlushReport

Flush every channel's acker; never let one channel's failure skip the others (each acker records its own errors in its report).

Source code in src/rabbitkit/highload/batch.py
def flush(self, reason: FlushReason = FlushReason.MANUAL) -> GroupFlushReport:
    """Flush every channel's acker; never let one channel's failure skip
    the others (each acker records its own errors in its report)."""
    return GroupFlushReport(reason=reason, reports=tuple(a.flush(reason) for a in self._snapshot()))

on_reconnect(channel: Any) -> tuple[int, ...]

One channel was rebuilt: drop its ledger and retire its acker.

Returns the dropped delivery tags (the broker redelivers them). The replacement channel is a different object, so the next :meth:for_channel builds a fresh acker for it. Unknown channels are a no-op, so this is safe to call from a reconnect hook that does not track which channels were in use.

Source code in src/rabbitkit/highload/batch.py
def on_reconnect(self, channel: Any) -> tuple[int, ...]:
    """One channel was rebuilt: drop its ledger and retire its acker.

    Returns the dropped delivery tags (the broker redelivers them). The
    replacement channel is a different object, so the next
    :meth:`for_channel` builds a fresh acker for it. Unknown channels are
    a no-op, so this is safe to call from a reconnect hook that does not
    track which channels were in use.
    """
    with self._lock:
        acker = self._ackers.pop(channel, None)
    if acker is None:
        return ()
    dropped = acker.on_reconnect()
    self._retire(acker)
    return dropped

reset() -> int

The connection was rebuilt: drop the ledger of every channel that is CLOSED. Returns the total number of dropped tags.

A channel that is still open keeps its ledger. The reconnect hook fires after aio-pika has already restored the consumers, and once per connection (publisher and consumer), so by the time it runs a restored channel may already be delivering. Dropping that live ledger stranded its deliveries: their complete() found no ledger, nothing was ever acked, and the broker never redelivered them because the channel stayed open. A live channel's ledger is valid, so keeping it is always correct; a closed channel's tags are redelivered by the broker. A key that reports no liveness at all (not a pika/aio-pika channel) is dropped, as before.

Source code in src/rabbitkit/highload/batch.py
def reset(self) -> int:
    """The connection was rebuilt: drop the ledger of every channel that
    is CLOSED. Returns the total number of dropped tags.

    A channel that is still open keeps its ledger. The reconnect hook
    fires after aio-pika has already restored the consumers, and once
    per connection (publisher and consumer), so by the time it runs a
    restored channel may already be delivering. Dropping that live
    ledger stranded its deliveries: their ``complete()`` found no
    ledger, nothing was ever acked, and the broker never redelivered
    them because the channel stayed open. A live channel's ledger is
    valid, so keeping it is always correct; a closed channel's tags are
    redelivered by the broker. A key that reports no liveness at all
    (not a pika/aio-pika channel) is dropped, as before.
    """
    with self._lock:
        ackers = []
        for channel, acker in list(self._ackers.items()):
            if _channel_open(channel):
                continue
            del self._ackers[channel]
            ackers.append(acker)
    dropped = 0
    for acker in ackers:
        dropped += len(acker.on_reconnect())
        self._retire(acker)
    return dropped

close() -> GroupFlushReport

Close every acker (draining what is approved) and clear the group.

Source code in src/rabbitkit/highload/batch.py
def close(self) -> GroupFlushReport:
    """Close every acker (draining what is approved) and clear the group."""
    with self._lock:
        self._closed = True
        ackers = tuple(self._ackers.values())
        self._ackers.clear()
    reports = []
    for acker in ackers:
        reports.append(acker.close())
        self._retire(acker)
    return GroupFlushReport(reason=FlushReason.CLOSE, reports=tuple(reports))

GroupFlushReport dataclass

Aggregate of one :meth:CoalescingAckerGroup.flush across channels.

Source code in src/rabbitkit/highload/batch.py
@dataclass(frozen=True, slots=True)
class GroupFlushReport:
    """Aggregate of one :meth:`CoalescingAckerGroup.flush` across channels."""

    reason: FlushReason
    reports: tuple[CoalescingFlushReport, ...] = ()

    @property
    def channels(self) -> int:
        return len(self.reports)

    @property
    def settled_tags(self) -> int:
        return sum(r.settled_tags for r in self.reports)

    @property
    def coalesced_tags(self) -> int:
        return sum(r.coalesced_tags for r in self.reports)

    @property
    def errors(self) -> tuple[tuple[SettlementCommand, BaseException], ...]:
        return tuple(err for r in self.reports for err in r.errors)

ChannelMismatchError

Bases: RuntimeError

A delivery from a different channel was handed to a bound :class:CoalescingAcker.

Delivery tags are a PER-CHANNEL counter: tag 7 on channel A and tag 7 on channel B are different messages. Mixing two channels in one ledger makes a cumulative ack computed from channel A's prefix settle channel B's messages — silent, wrong, and unrecoverable. Bind the acker (constructor channel_key= or the first register(..., channel_key=...)) and this is caught at registration instead.

Source code in src/rabbitkit/highload/batch.py
class ChannelMismatchError(RuntimeError):
    """A delivery from a different channel was handed to a bound
    :class:`CoalescingAcker`.

    Delivery tags are a PER-CHANNEL counter: tag 7 on channel A and tag 7 on
    channel B are different messages. Mixing two channels in one ledger makes
    a cumulative ack computed from channel A's prefix settle channel B's
    messages — silent, wrong, and unrecoverable. Bind the acker (constructor
    ``channel_key=`` or the first ``register(..., channel_key=...)``) and this
    is caught at registration instead.
    """

Reliability profiles & preflight

ReliabilityProfile

Bases: str, Enum

Opt-in reliability profiles (see :mod:rabbitkit.core.profiles).

Source code in src/rabbitkit/core/types.py
class ReliabilityProfile(str, Enum):
    """Opt-in reliability profiles (see :mod:`rabbitkit.core.profiles`)."""

    STANDARD = "standard"
    CRITICAL = "critical"

apply_profile(config: RabbitConfig, profile: ReliabilityProfile | str) -> RabbitConfig

Return a copy of config satisfying profile's config-level requirements.

Raises :class:ConfigValidationError if the caller pinned a contradictory value (e.g. confirm_delivery=False under CRITICAL) — a profile never silently overrides an explicit choice — and, under CRITICAL, when consumer.processing_timeout is not set (it has no safe default).

CRITICAL fills in: confirms, persistence, mandatory, body limit (<= 256 KiB), max_in_flight_bytes (:data:CRITICAL_MAX_IN_FLIGHT_BYTES unless set), strip_reserved_headers, a RetryConfig when there is none (keeping your ladder when there is) with quorum delay queues dead-lettering at-least-once, a quorum DLQ, terminal_action=dead_letter and trust_retry_header=False, and safety.dead_letter_with_metadata. It requires a heartbeat (heartbeat=0 raises) and leaves the reconnect budget and TLS to you. Per-route requirements (quorum source queues declared at-least-once, no ACK_FIRST, retry not disabled) are the routes' to meet: check them with :func:validate_profile / :func:preflight after registering the subscribers.

STANDARD fills in confirms, persistence and mandatory only.

Source code in src/rabbitkit/core/profiles.py
def apply_profile(config: RabbitConfig, profile: ReliabilityProfile | str) -> RabbitConfig:
    """Return a copy of *config* satisfying *profile*'s config-level requirements.

    Raises :class:`ConfigValidationError` if the caller pinned a
    contradictory value (e.g. ``confirm_delivery=False`` under CRITICAL) —
    a profile never silently overrides an explicit choice — and, under
    CRITICAL, when ``consumer.processing_timeout`` is not set (it has no
    safe default).

    CRITICAL fills in: confirms, persistence, mandatory, body limit
    (<= 256 KiB), ``max_in_flight_bytes`` (:data:`CRITICAL_MAX_IN_FLIGHT_BYTES`
    unless set), ``strip_reserved_headers``, a ``RetryConfig`` when there is
    none (keeping your ladder when there is) with quorum delay queues
    dead-lettering at-least-once, a quorum DLQ, ``terminal_action=dead_letter``
    and ``trust_retry_header=False``, and ``safety.dead_letter_with_metadata``. It requires a heartbeat (``heartbeat=0``
    raises) and leaves the reconnect budget and TLS to you. Per-route requirements (quorum source
    queues declared at-least-once, no ``ACK_FIRST``, retry not disabled) are
    the routes' to meet: check them with :func:`validate_profile` /
    :func:`preflight` after registering the subscribers.

    STANDARD fills in confirms, persistence and mandatory only.
    """
    prof = ReliabilityProfile(profile)
    defaults = RabbitConfig()

    def _pinned(section: Any, section_defaults: Any, name: str) -> bool:
        return bool(getattr(section, name) != getattr(section_defaults, name))

    pub = config.publisher
    contradictions: list[str] = []
    if _pinned(pub, defaults.publisher, "confirm_delivery") and not pub.confirm_delivery:
        contradictions.append("publisher.confirm_delivery=False")
    if _pinned(pub, defaults.publisher, "persistent") and not pub.persistent:
        contradictions.append("publisher.persistent=False")
    if config.safety.reject_without_dlx == "discard":
        contradictions.append("safety.reject_without_dlx='discard'")
    if config.retry is not None and config.retry.error_detail == "raw":
        contradictions.append("retry.error_detail='raw'")
    if prof is ReliabilityProfile.CRITICAL:
        contradictions.extend(_critical_contradictions(config, defaults))
    if contradictions:
        raise ConfigValidationError(
            f"Cannot apply reliability profile {prof.value!r}: contradictory explicit settings: "
            + ", ".join(contradictions)
        )
    if prof is ReliabilityProfile.CRITICAL and config.consumer.processing_timeout is None:
        raise ConfigValidationError(f"Cannot apply reliability profile 'critical': {_PROCESSING_TIMEOUT_REQUIRED}.")

    if prof is ReliabilityProfile.CRITICAL:
        new_pub = dataclasses.replace(
            pub,
            confirm_delivery=True,
            persistent=True,
            mandatory=True,
            max_message_bytes=min(pub.max_message_bytes, CRITICAL_MAX_MESSAGE_BYTES),
            max_in_flight_bytes=(
                pub.max_in_flight_bytes if pub.max_in_flight_bytes is not None else CRITICAL_MAX_IN_FLIGHT_BYTES
            ),
            strip_reserved_headers=True,
        )
        base_retry = config.retry if config.retry is not None else RetryConfig()
        # A critical DLQ stores failed events indefinitely: always quorum
        # ("inherit" would silently become classic for a classic source).
        # Delay queues dead-letter back to the source at-least-once, so an
        # expiring retry copy is never dropped when the source is full.
        new_retry: RetryConfig | None = dataclasses.replace(
            base_retry,
            delay_queue_type="quorum",
            dlq_queue_type="quorum",
            delay_queue_dead_letter_strategy=DeadLetterStrategy.AT_LEAST_ONCE.value,
            terminal_action=TerminalAction.DEAD_LETTER,
            trust_retry_header=False,
        )
        new_safety = dataclasses.replace(config.safety, dead_letter_with_metadata=True)
        return dataclasses.replace(config, publisher=new_pub, retry=new_retry, safety=new_safety)

    new_pub = dataclasses.replace(pub, confirm_delivery=True, persistent=True, mandatory=True)
    return dataclasses.replace(config, publisher=new_pub)

validate_profile(config: RabbitConfig, profile: ReliabilityProfile | str, *, routes: Sequence[Any] = ()) -> list[ProfileViolation]

Return every requirement of profile that config (and routes) violate.

Empty list == compliant. Local checks only — see :func:preflight for broker-side verification.

Source code in src/rabbitkit/core/profiles.py
def validate_profile(
    config: RabbitConfig,
    profile: ReliabilityProfile | str,
    *,
    routes: Sequence[Any] = (),
) -> list[ProfileViolation]:
    """Return every requirement of *profile* that *config* (and *routes*) violate.

    Empty list == compliant. Local checks only — see :func:`preflight` for
    broker-side verification.
    """
    prof = ReliabilityProfile(profile)
    out: list[ProfileViolation] = []
    pub: PublisherConfig = config.publisher
    safety: SafetyConfig = config.safety
    retry: RetryConfig | None = config.retry

    # Shared (standard + critical): the guardrails both profiles turn on.
    if not pub.confirm_delivery:
        out.append(ProfileViolation("publisher.confirm_delivery", "True", "False"))
    if not pub.persistent:
        out.append(ProfileViolation("publisher.persistent", "True", "False"))
    if not pub.mandatory:
        out.append(
            ProfileViolation(
                "publisher.mandatory",
                "True",
                "False",
                severity="error" if prof is ReliabilityProfile.CRITICAL else "warning",
            )
        )
    if pub.max_message_bytes == 0:
        out.append(ProfileViolation("publisher.max_message_bytes", "> 0 (bounded)", "0 (unbounded)"))
    if safety.reject_without_dlx == "discard":
        out.append(ProfileViolation("safety.reject_without_dlx", "'auto_provision' or 'error'", "'discard'"))
    if retry is not None and retry.error_detail == "raw" and prof is ReliabilityProfile.STANDARD:
        out.append(ProfileViolation("retry.error_detail", "'sanitized' or 'omit'", "'raw'"))

    if prof is ReliabilityProfile.CRITICAL:
        out.extend(_critical_config_violations(config))
        out.extend(_critical_route_violations(config, routes))
    return out

critical_config(base: RabbitConfig | None = None) -> RabbitConfig

Shorthand for apply_profile(base or RabbitConfig(), CRITICAL).

base must set consumer.processing_timeout (see :func:apply_profile).

Source code in src/rabbitkit/core/profiles.py
def critical_config(base: RabbitConfig | None = None) -> RabbitConfig:
    """Shorthand for ``apply_profile(base or RabbitConfig(), CRITICAL)``.

    *base* must set ``consumer.processing_timeout`` (see :func:`apply_profile`).
    """
    return apply_profile(base or RabbitConfig(), ReliabilityProfile.CRITICAL)

standard_config(base: RabbitConfig | None = None) -> RabbitConfig

Shorthand for apply_profile(base or RabbitConfig(), STANDARD).

Source code in src/rabbitkit/core/profiles.py
def standard_config(base: RabbitConfig | None = None) -> RabbitConfig:
    """Shorthand for ``apply_profile(base or RabbitConfig(), STANDARD)``."""
    return apply_profile(base or RabbitConfig(), ReliabilityProfile.STANDARD)

ProfileViolation dataclass

One profile requirement the configuration does not meet.

Source code in src/rabbitkit/core/profiles.py
@dataclass(frozen=True, slots=True)
class ProfileViolation:
    """One profile requirement the configuration does not meet."""

    setting: str
    expected: str
    actual: str
    severity: str = "error"  # "error" | "warning"

    def __str__(self) -> str:
        return f"{self.setting}: expected {self.expected}, got {self.actual} ({self.severity})"

preflight(config: RabbitConfig, profile: ReliabilityProfile | str, *, routes: Sequence[Any] = (), management_client: Any | None = None, vhost: str = '/') -> PreflightReport

Verify profile prerequisites locally and, when a read-only management client is provided, on the broker. Broker-side checks are reported UNVERIFIED (with the reason) when no client is given or a lookup fails — never silently VERIFIED.

management_client needs only get_queue(name, vhost) returning the management API's queue JSON (RabbitManagementClient fits).

Source code in src/rabbitkit/core/profiles.py
def preflight(
    config: RabbitConfig,
    profile: ReliabilityProfile | str,
    *,
    routes: Sequence[Any] = (),
    management_client: Any | None = None,
    vhost: str = "/",
) -> PreflightReport:
    """Verify profile prerequisites locally and, when a read-only management
    client is provided, on the broker. Broker-side checks are reported
    ``UNVERIFIED`` (with the reason) when no client is given or a lookup
    fails — never silently VERIFIED.

    *management_client* needs only ``get_queue(name, vhost)`` returning the
    management API's queue JSON (``RabbitManagementClient`` fits).
    """
    prof = ReliabilityProfile(profile)
    checks: list[PreflightCheck] = []

    violations = validate_profile(config, prof, routes=routes)
    if management_client is not None:
        # The broker-side dead-letter-strategy check below is authoritative
        # (it sees policies too); drop the local "not declared" warning.
        violations = [
            v
            for v in violations
            if not (v.setting.startswith("queue[") and v.setting.endswith(".dead_letter_strategy"))
        ]
    if violations:
        for v in violations:
            checks.append(
                PreflightCheck(
                    name=f"config:{v.setting}",
                    status=PreflightStatus.FAILED if v.severity == "error" else PreflightStatus.UNVERIFIED,
                    detail=str(v),
                )
            )
    else:
        checks.append(PreflightCheck(name="config", status=PreflightStatus.VERIFIED, detail="profile requirements met"))

    queues = _route_queues(routes)
    if prof is ReliabilityProfile.CRITICAL and queues:
        for q in queues:
            name = str(getattr(q, "name", ""))
            if management_client is None:
                checks.append(
                    PreflightCheck(
                        name=f"broker:{name}",
                        status=PreflightStatus.UNVERIFIED,
                        detail="no management client supplied; broker policy not checked",
                    )
                )
                continue
            try:
                info = management_client.get_queue(name, vhost)
            except Exception as exc:  # 404 (not declared yet), auth, network
                checks.append(
                    PreflightCheck(
                        name=f"broker:{name}",
                        status=PreflightStatus.UNVERIFIED,
                        detail=f"management lookup failed: {type(exc).__name__}",
                    )
                )
                continue
            if not isinstance(info, dict):
                checks.append(
                    PreflightCheck(
                        name=f"broker:{name}", status=PreflightStatus.UNVERIFIED, detail="unexpected management payload"
                    )
                )
                continue
            qtype = str(info.get("type") or _queue_policy_definition(info).get("x-queue-type") or "classic")
            checks.append(
                PreflightCheck(
                    name=f"broker:{name}:type",
                    status=PreflightStatus.VERIFIED if qtype == "quorum" else PreflightStatus.FAILED,
                    detail=f"type={qtype}",
                )
            )
            pol = _queue_policy_definition(info)
            dls = pol.get("dead-letter-strategy") or pol.get("x-dead-letter-strategy")
            checks.append(
                PreflightCheck(
                    name=f"broker:{name}:dead-letter-strategy",
                    status=PreflightStatus.VERIFIED if dls == "at-least-once" else PreflightStatus.FAILED,
                    detail=f"dead-letter-strategy={dls!r}",
                )
            )
            overflow = pol.get("overflow") or pol.get("x-overflow")
            checks.append(
                PreflightCheck(
                    name=f"broker:{name}:overflow",
                    status=PreflightStatus.VERIFIED if overflow == "reject-publish" else PreflightStatus.FAILED,
                    detail=f"overflow={overflow!r}",
                )
            )
            limit = pol.get("delivery-limit") or pol.get("x-delivery-limit")
            checks.append(
                PreflightCheck(
                    name=f"broker:{name}:delivery-limit",
                    status=PreflightStatus.VERIFIED if isinstance(limit, int) and limit > 0 else PreflightStatus.FAILED,
                    detail=f"delivery-limit={limit!r}",
                )
            )
    return PreflightReport(profile=prof, checks=tuple(checks))

PreflightReport dataclass

Source code in src/rabbitkit/core/profiles.py
@dataclass(frozen=True, slots=True)
class PreflightReport:
    profile: ReliabilityProfile
    checks: tuple[PreflightCheck, ...] = field(default_factory=tuple)

    def by_status(self, status: PreflightStatus) -> tuple[PreflightCheck, ...]:
        return tuple(c for c in self.checks if c.status is status)

    @property
    def failed(self) -> tuple[PreflightCheck, ...]:
        return self.by_status(PreflightStatus.FAILED)

    @property
    def unverified(self) -> tuple[PreflightCheck, ...]:
        return self.by_status(PreflightStatus.UNVERIFIED)

    @property
    def ok(self) -> bool:
        """No FAILED checks. UNVERIFIED checks do NOT make this False — they
        are listed separately and must be reported, not hidden."""
        return not self.failed

    @property
    def fully_verified(self) -> bool:
        return self.ok and not self.unverified

    def as_dict(self) -> dict[str, Any]:
        return {
            "profile": self.profile.value,
            "ok": self.ok,
            "fully_verified": self.fully_verified,
            "checks": [{"name": c.name, "status": c.status.value, "detail": c.detail} for c in self.checks],
        }

Attributes

ok: bool property

No FAILED checks. UNVERIFIED checks do NOT make this False — they are listed separately and must be reported, not hidden.

PreflightCheck dataclass

Source code in src/rabbitkit/core/profiles.py
@dataclass(frozen=True, slots=True)
class PreflightCheck:
    name: str
    status: PreflightStatus
    detail: str = ""

PreflightStatus

Bases: str, Enum

Outcome of one preflight check. UNVERIFIED is reported, never hidden.

Source code in src/rabbitkit/core/types.py
class PreflightStatus(str, Enum):
    """Outcome of one preflight check. ``UNVERIFIED`` is reported, never hidden."""

    VERIFIED = "verified"
    UNVERIFIED = "unverified"
    FAILED = "failed"

policy_templates(queue_names: Sequence[str], *, retry: RetryConfig | None = None, profile: ReliabilityProfile | str = ReliabilityProfile.CRITICAL, delivery_limit: int | None = None, max_length: int | None = None, vhost: str = '/') -> list[PolicyTemplate]

Render reviewed policy definitions for queue_names and their retry chain.

For the CRITICAL profile every source queue and DLQ gets dead-letter-strategy: at-least-once (which RabbitMQ requires to be paired with overflow: reject-publish) and a delivery-limit backstop (defaults to retry.max_retries + 1 when retry is given, else 5). Delay queues get only overflow: reject-publish — TTL expiry is their whole job and they must never drop on overflow. STANDARD renders just the overflow guard. Nothing here is applied automatically.

Source code in src/rabbitkit/core/profiles.py
def policy_templates(
    queue_names: Sequence[str],
    *,
    retry: RetryConfig | None = None,
    profile: ReliabilityProfile | str = ReliabilityProfile.CRITICAL,
    delivery_limit: int | None = None,
    max_length: int | None = None,
    vhost: str = "/",
) -> list[PolicyTemplate]:
    """Render reviewed policy definitions for *queue_names* and their retry chain.

    For the CRITICAL profile every source queue and DLQ gets
    ``dead-letter-strategy: at-least-once`` (which RabbitMQ requires to be
    paired with ``overflow: reject-publish``) and a ``delivery-limit``
    backstop (defaults to ``retry.max_retries + 1`` when *retry* is given,
    else 5). Delay queues get only ``overflow: reject-publish`` — TTL expiry
    is their whole job and they must never drop on overflow. STANDARD
    renders just the overflow guard. Nothing here is applied automatically.
    """
    prof = ReliabilityProfile(profile)
    limit = delivery_limit if delivery_limit is not None else ((retry.max_retries + 1) if retry is not None else 5)
    out: list[PolicyTemplate] = []
    for q in queue_names:
        src_def: dict[str, Any] = {"overflow": "reject-publish"}
        if prof is ReliabilityProfile.CRITICAL:
            src_def["dead-letter-strategy"] = "at-least-once"
            src_def["delivery-limit"] = limit
        if max_length is not None:
            src_def["max-length"] = max_length
        out.append(
            PolicyTemplate(
                name=f"rabbitkit-{q}-source",
                pattern=f"^{_regex_escape(q)}$",
                definition=src_def,
                apply_to="quorum_queues" if prof is ReliabilityProfile.CRITICAL else "queues",
                vhost=vhost,
            )
        )
        if retry is not None:
            out.append(
                PolicyTemplate(
                    name=f"rabbitkit-{q}-retry",
                    pattern=f"^{_regex_escape(q)}\\.retry\\.[0-9]+(\\.s[0-9]+)?$",
                    definition={"overflow": "reject-publish"},
                    apply_to="queues",
                    vhost=vhost,
                )
            )
            dlq_def: dict[str, Any] = {"overflow": "reject-publish"}
            if max_length is not None:
                dlq_def["max-length"] = max_length
            out.append(
                PolicyTemplate(
                    name=f"rabbitkit-{q}-dlq",
                    pattern=f"^{_regex_escape(q)}\\.dlq$",
                    definition=dlq_def,
                    apply_to="quorum_queues" if prof is ReliabilityProfile.CRITICAL else "queues",
                    vhost=vhost,
                )
            )
    return out

PolicyTemplate dataclass

One RabbitMQ policy in management-API shape (PUT /api/policies/{vhost}/{name}).

Source code in src/rabbitkit/core/profiles.py
@dataclass(frozen=True, slots=True)
class PolicyTemplate:
    """One RabbitMQ policy in management-API shape (``PUT /api/policies/{vhost}/{name}``)."""

    name: str
    pattern: str
    definition: dict[str, Any]
    apply_to: str = "quorum_queues"
    priority: int = 10
    vhost: str = "/"

    def as_api_body(self) -> dict[str, Any]:
        return {
            "pattern": self.pattern,
            "definition": dict(self.definition),
            "apply-to": self.apply_to,
            "priority": self.priority,
        }

    def as_rabbitmqctl(self) -> str:
        import json

        return (
            f"rabbitmqctl set_policy -p {self.vhost} --priority {self.priority} --apply-to {self.apply_to} "
            f"{self.name} '{self.pattern}' '{json.dumps(self.definition, separators=(',', ':'))}'"
        )

Retry hardening

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}"
            )

RetryHandoffTracker

Thread-safe consecutive-failure tracker for one route.

record_failure() returns the backoff (seconds) the caller should apply before letting the next redelivery through. record_success() resets the streak. The tracker never sleeps itself.

Source code in src/rabbitkit/core/retry_handoff.py
class RetryHandoffTracker:
    """Thread-safe consecutive-failure tracker for one route.

    ``record_failure()`` returns the backoff (seconds) the caller should
    apply before letting the next redelivery through. ``record_success()``
    resets the streak. The tracker never sleeps itself.
    """

    def __init__(
        self,
        config: RetryHandoffConfig | None = None,
        *,
        clock: Callable[[], float] = time.monotonic,
        rng: Callable[[], float] = random.random,
    ) -> None:
        self._config = config or RetryHandoffConfig()
        self._clock = clock
        self._rng = rng
        self._lock = threading.Lock()
        self._consecutive = 0
        self._total = 0
        self._first_failure_at: float | None = None
        self._last_failure_at: float | None = None
        self._last_backoff = 0.0

    # ── inspection ────────────────────────────────────────────────────────

    @property
    def config(self) -> RetryHandoffConfig:
        return self._config

    @property
    def consecutive_failures(self) -> int:
        with self._lock:
            return self._consecutive

    @property
    def total_failures(self) -> int:
        with self._lock:
            return self._total

    @property
    def last_backoff(self) -> float:
        with self._lock:
            return self._last_backoff

    @property
    def first_failure_at(self) -> float | None:
        with self._lock:
            return self._first_failure_at

    @property
    def state(self) -> HandoffState:
        with self._lock:
            return self._state_locked()

    def _state_locked(self) -> HandoffState:
        if self._consecutive == 0:
            return HandoffState.HEALTHY
        if self._consecutive >= self._config.max_consecutive_failures:
            return HandoffState.EXHAUSTED
        if self._first_failure_at is not None and (
            self._clock() - self._first_failure_at >= self._config.recovery_deadline
        ):
            return HandoffState.EXHAUSTED
        return HandoffState.DEGRADED

    @property
    def is_exhausted(self) -> bool:
        return self.state is HandoffState.EXHAUSTED

    @property
    def is_paused(self) -> bool:
        """True while degraded or exhausted (drives the ``retry_handoff_paused`` gauge)."""
        return self.state is not HandoffState.HEALTHY

    # ── transitions ───────────────────────────────────────────────────────

    def record_failure(self) -> float:
        """Register one handoff failure; return the backoff to apply (seconds)."""
        with self._lock:
            now = self._clock()
            self._consecutive += 1
            self._total += 1
            if self._first_failure_at is None:
                self._first_failure_at = now
            self._last_failure_at = now
            cfg = self._config
            base = _capped_exponential(cfg.backoff_initial, cfg.backoff_max, self._consecutive)
            if cfg.jitter > 0:
                spread = base * cfg.jitter
                base = base - spread + (2 * spread * self._rng())
            self._last_backoff = max(0.0, min(cfg.backoff_max, base))
            return self._last_backoff

    def record_success(self) -> None:
        """A handoff succeeded: the streak ends; the deadline clock resets."""
        with self._lock:
            self._consecutive = 0
            self._first_failure_at = None
            self._last_failure_at = None
            self._last_backoff = 0.0

    def reset(self) -> None:
        """Forget everything (e.g. after a deliberate consumer restart)."""
        with self._lock:
            self._consecutive = 0
            self._total = 0
            self._first_failure_at = None
            self._last_failure_at = None
            self._last_backoff = 0.0

Attributes

is_paused: bool property

True while degraded or exhausted (drives the retry_handoff_paused gauge).

Methods:

record_failure() -> float

Register one handoff failure; return the backoff to apply (seconds).

Source code in src/rabbitkit/core/retry_handoff.py
def record_failure(self) -> float:
    """Register one handoff failure; return the backoff to apply (seconds)."""
    with self._lock:
        now = self._clock()
        self._consecutive += 1
        self._total += 1
        if self._first_failure_at is None:
            self._first_failure_at = now
        self._last_failure_at = now
        cfg = self._config
        base = _capped_exponential(cfg.backoff_initial, cfg.backoff_max, self._consecutive)
        if cfg.jitter > 0:
            spread = base * cfg.jitter
            base = base - spread + (2 * spread * self._rng())
        self._last_backoff = max(0.0, min(cfg.backoff_max, base))
        return self._last_backoff

record_success() -> None

A handoff succeeded: the streak ends; the deadline clock resets.

Source code in src/rabbitkit/core/retry_handoff.py
def record_success(self) -> None:
    """A handoff succeeded: the streak ends; the deadline clock resets."""
    with self._lock:
        self._consecutive = 0
        self._first_failure_at = None
        self._last_failure_at = None
        self._last_backoff = 0.0

reset() -> None

Forget everything (e.g. after a deliberate consumer restart).

Source code in src/rabbitkit/core/retry_handoff.py
def reset(self) -> None:
    """Forget everything (e.g. after a deliberate consumer restart)."""
    with self._lock:
        self._consecutive = 0
        self._total = 0
        self._first_failure_at = None
        self._last_failure_at = None
        self._last_backoff = 0.0

HandoffState

Bases: str, Enum

Retry-handoff tracker state (see :mod:rabbitkit.core.retry_handoff).

Source code in src/rabbitkit/core/types.py
class HandoffState(str, Enum):
    """Retry-handoff tracker state (see :mod:`rabbitkit.core.retry_handoff`)."""

    HEALTHY = "healthy"
    DEGRADED = "degraded"
    EXHAUSTED = "exhausted"

ErrorSanitizer

Turn an exception into a :class:SanitizedError.

Parameters:

Name Type Description Default
policy str

One of :data:ERROR_DETAIL_POLICIES.

'sanitized'
max_summary_len int

Hard cap on the summary (after redaction).

256
max_code_len int

Hard cap on the code.

64
patterns Sequence[Pattern[str]] | None

Regexes whose matches are replaced by *** in the summary. Defaults cover URL credentials, bearer/basic auth, password=/token=-style pairs, AWS key ids, and long opaque tokens.

None
allowed_codes frozenset[str] | None

Optional allowlist of exception class names. A code outside it is reported as "ApplicationError" — for teams that consider exception class names themselves sensitive.

None
Source code in src/rabbitkit/core/sanitizer.py
class ErrorSanitizer:
    """Turn an exception into a :class:`SanitizedError`.

    Args:
        policy: One of :data:`ERROR_DETAIL_POLICIES`.
        max_summary_len: Hard cap on the summary (after redaction).
        max_code_len: Hard cap on the code.
        patterns: Regexes whose matches are replaced by ``***`` in the
            summary. Defaults cover URL credentials, bearer/basic auth,
            ``password=``/``token=``-style pairs, AWS key ids, and long
            opaque tokens.
        allowed_codes: Optional allowlist of exception class names. A code
            outside it is reported as ``"ApplicationError"`` — for teams
            that consider exception class names themselves sensitive.
    """

    def __init__(
        self,
        *,
        policy: str = "sanitized",
        max_summary_len: int = 256,
        max_code_len: int = 64,
        patterns: Sequence[re.Pattern[str]] | None = None,
        allowed_codes: frozenset[str] | None = None,
    ) -> None:
        if policy not in ERROR_DETAIL_POLICIES:
            raise ValueError(f"policy must be one of {ERROR_DETAIL_POLICIES}, got {policy!r}")
        if max_summary_len < 0 or max_code_len < 1:
            raise ValueError("max_summary_len must be >= 0 and max_code_len >= 1")
        self._policy = policy
        self._max_summary = max_summary_len
        self._max_code = max_code_len
        self._patterns = tuple(patterns) if patterns is not None else _DEFAULT_PATTERNS
        self._allowed_codes = allowed_codes

    @property
    def policy(self) -> str:
        return self._policy

    # ── public API ────────────────────────────────────────────────────────

    def code_for(self, exc: BaseException) -> str:
        name = type(exc).__name__
        if self._allowed_codes is not None and name not in self._allowed_codes:
            name = "ApplicationError"
        return _CODE_SAFE.sub("", name)[: self._max_code] or "Error"

    def redact(self, text: str) -> str:
        """Apply every redaction pattern to *text*."""
        out = text
        for pat in self._patterns:
            out = pat.sub(self._replacement_for(pat), out)
        return out

    def summary_for(self, exc: BaseException) -> str:
        if self._policy == "omit" or self._max_summary == 0:
            return ""
        try:
            text = str(exc)
        except Exception:
            text = "<unprintable exception>"
        if self._policy == "raw":
            return text[: self._max_summary]
        # Collapse whitespace/newlines: a header is one line; a stack-trace-
        # shaped message must not smuggle formatting into log pipelines.
        text = " ".join(text.split())
        # Bound the input BEFORE redacting. redact() runs six regexes over
        # whatever it is given, and `str(exc)` is attacker-influenced whenever
        # a handler echoes the body (json.JSONDecodeError, pydantic's
        # ValidationError, ValueError(f"bad: {body}")). Redacting a 16 MiB
        # message to keep 256 characters is pure waste, and on the async path
        # it blocks the event loop, which costs heartbeats and wedges the
        # consumer into a redelivery loop.
        #
        # The window is a MULTIPLE of the kept length, not the kept length:
        # truncating to exactly _max_summary could slice a secret that starts
        # just inside the kept region, leaving its prefix unredacted. With 8x
        # slack, any secret beginning within the kept 256 characters is still
        # seen whole by the patterns.
        return self.redact(text[: self._max_summary * _REDACT_WINDOW_FACTOR])[: self._max_summary]

    def sanitize(self, exc: BaseException, severity: ErrorSeverity | None = None) -> SanitizedError:
        category = severity.value if severity is not None else "unknown"
        return SanitizedError(category=category, code=self.code_for(exc), summary=self.summary_for(exc))

    # ── internals ────────────────────────────────────────────────────────

    @staticmethod
    def _replacement_for(pat: re.Pattern[str]) -> Any:
        groups = pat.groups
        if groups == 3 and "://" in pat.pattern:
            return rf"\1{_REDACTED}:{_REDACTED}@"
        if groups == 3:
            return rf"\1\2{_REDACTED}"
        if groups == 1:
            return rf"\1 {_REDACTED}"
        return _REDACTED

Methods:

redact(text: str) -> str

Apply every redaction pattern to text.

Source code in src/rabbitkit/core/sanitizer.py
def redact(self, text: str) -> str:
    """Apply every redaction pattern to *text*."""
    out = text
    for pat in self._patterns:
        out = pat.sub(self._replacement_for(pat), out)
    return out

SanitizedError dataclass

Allowlisted, bounded description of a failure.

Attributes:

Name Type Description
category str

"transient" / "permanent" / "unknown".

code str

Exception class name, restricted to [A-Za-z0-9_.] and capped in length — stable enough to alert on, never user text.

summary str

Redacted, length-capped message text (empty under omit).

Source code in src/rabbitkit/core/sanitizer.py
@dataclass(frozen=True, slots=True)
class SanitizedError:
    """Allowlisted, bounded description of a failure.

    Attributes:
        category: ``"transient"`` / ``"permanent"`` / ``"unknown"``.
        code: Exception class name, restricted to ``[A-Za-z0-9_.]`` and
            capped in length — stable enough to alert on, never user text.
        summary: Redacted, length-capped message text (empty under ``omit``).
    """

    category: str
    code: str
    summary: str = ""

    def as_headers(self, prefix: str = "x-rabbitkit-error") -> dict[str, str]:
        headers = {f"{prefix}-category": self.category, f"{prefix}-type": self.code}
        if self.summary:
            headers[f"{prefix}-message"] = self.summary
        return headers