Messages & Settlement¶
RabbitMessage¶
RabbitMessage
¶
Rich incoming message with transport-aware settlement.
The message object wraps raw AMQP delivery data and provides: - Typed access to headers, properties, routing info - Sync and async ack/nack/reject methods - Idempotent settlement (double-ack is a no-op) - Topic wildcard path extraction
Source code in src/rabbitkit/core/message.py
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 | |
Attributes¶
wire_body: bytes
property
¶
The body exactly as the broker delivered it.
body may have been rewritten by an on_receive hook
(CompressionMiddleware decompresses it in place); this is the
original, still matching :attr:wire_content_encoding.
wire_content_encoding: str | None
property
¶
content_encoding exactly as the broker delivered it.
stream_offset: int | None
property
¶
This delivery's offset in a stream queue, else None.
RabbitMQ stamps every delivery from a stream with an
x-stream-offset header (overwriting any value a publisher set).
On a classic or quorum queue the header is whatever the publisher
sent, so only read this for deliveries from a stream.
is_settled: bool
property
¶
True if the message has been acked, nacked, or rejected.
disposition: str
property
¶
Final settlement state: "pending", "acked", "nacked", or "rejected" (M2).
settlement_outcome_unknown: bool
property
¶
True if an async settlement was claimed but its send raised or was cancelled.
The ack/nack/reject frame may or may not have reached the broker.
disposition keeps the claimed value and no other settlement is
sent for this delivery; if the frame was lost, the broker redelivers
the message when its channel closes (at-least-once).
channel_alive: bool | None
property
¶
Whether the channel this delivery arrived on is still open.
None when the transport did not wire a probe (in-memory
TestBroker, hand-constructed messages). False means the
delivery tag is STALE — the broker has already (or will) redeliver
this message on a new channel and settling it here would be a
protocol error or, worse, settle a different message.
Methods:¶
ack() -> None
¶
Synchronous ack. Raises SettlementError on async-only transport.
Sets disposition only after the transport call succeeds, so a failed ack (channel closed, frame error) leaves the message unsettled and the exception propagates to the recovery loop instead of being swallowed.
Source code in src/rabbitkit/core/message.py
nack(requeue: bool = True) -> None
¶
Synchronous nack. Raises SettlementError on async-only transport.
Source code in src/rabbitkit/core/message.py
reject(requeue: bool = False) -> None
¶
Synchronous reject. Raises SettlementError on async-only transport.
Source code in src/rabbitkit/core/message.py
ack_async() -> None
async
¶
Async ack. Falls back to sync if async fn not set.
The settlement is claimed before the transport call (see
settlement_outcome_unknown): a concurrent or later
ack_async/nack_async/reject_async is a no-op.
Source code in src/rabbitkit/core/message.py
nack_async(requeue: bool = True) -> None
async
¶
Async nack. Falls back to sync if async fn not set. Claims first (see ack_async).
reject_async(requeue: bool = False) -> None
async
¶
Async reject. Falls back to sync if async fn not set. Claims first (see ack_async).
Source code in src/rabbitkit/core/message.py
MessageEnvelope¶
MessageEnvelope
dataclass
¶
Outgoing message envelope.
NOTE: AMQP header values are limited to: str, int, float, bool, bytes, datetime, Decimal, list/dict of these, or None. Arbitrary Python objects (sets, custom classes) will raise at publish time. Transport validates header values before sending.
Source code in src/rabbitkit/core/types.py
InboundMessageTooLargeError
¶
Bases: InvalidMessageError
A delivery's raw body exceeds ConsumerConfig.max_body_bytes.
INVALID_MESSAGE: the delivery is dead-lettered without running any
middleware or the handler.
Source code in src/rabbitkit/core/errors.py
Reserved headers¶
strip_reserved_headers(headers: Mapping[str, Any], extra: Iterable[str] = ()) -> dict[str, Any] | None
¶
headers without the reserved ones (and any in extra), or None
when nothing had to be removed (the caller keeps its object, no copy).
Source code in src/rabbitkit/core/reserved_headers.py
AckPolicy¶
AckPolicy
¶
Bases: str, Enum
Message acknowledgement policies.
See Contract 1 in the plan for exact semantics: - AUTO: success→ack, exception→classify→nack/reject - MANUAL: handler owns ack/nack/reject entirely - NACK_ON_ERROR: success→ack, exception→nack(requeue=False) - ACK_FIRST: ack BEFORE handler runs (at-most-once)
Source code in src/rabbitkit/core/types.py
AckStrategy¶
AckStrategy
¶
Bases: Protocol
Settlement strategy for an AckPolicy.
Each strategy owns the success-path ack and the error-path settlement.
Handler-raised AckMessage / NackMessage / RejectMessage are
NOT policy-driven and stay in the pipeline.
See Contract 1 in the plan for per-policy semantics.
Source code in src/rabbitkit/core/types.py
PublishOutcome / PublishStatus¶
PublishOutcome
dataclass
¶
Result of a publish operation.
reason is a bounded code from :class:PublishReason saying why a
non-success status happened (None when the transport did not
classify it). reply_code / reply_text carry the broker's
basic.return fields for a RETURNED publish (e.g. 312 /
"NO_ROUTE") and the channel-close fields for a refused one.
Source code in src/rabbitkit/core/types.py
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 | |
Attributes¶
is_unknown: bool
property
¶
True when the broker may or may not have the message: UNKNOWN
or TIMEOUT (a confirm timeout is one kind of unknown outcome).
Republish only with the same message_id so consumers can
deduplicate.
ok: bool
property
¶
True if the publish did not fail -- CONFIRMED (broker acknowledged it) or SENT (fire-and-forget, confirm_delivery=False -- written to the socket but never broker-confirmed).
M4: if you specifically need to know the broker actually confirmed
the message (e.g. before treating a republish as durable enough to
settle/discard the original), check status ==
PublishStatus.CONFIRMED directly -- .ok alone can't
distinguish "confirmed" from "sent, unconfirmed."
classification: ClassifiedError | None
property
¶
Best-effort severity/reason for self.error, via the existing
classify_error() (production-hardening item 5).
Deliberately NOT a new PublishStatus enum member: growing that
small, closed "what happened" set (CONFIRMED/SENT/NACKED/TIMEOUT/
RETURNED/ERROR) risks breaking exhaustive match/if-chains callers
may have written against it, for a "why" signal better served by
reusing the classification machinery already wired into the
consume/retry path (core/errors.py) rather than duplicating it.
A lazy import avoids a module-level cycle (core/errors.py
already imports from this module) — same pattern as
:meth:raise_for_status.
None when there's nothing to classify: a non-ERROR status, or
an ERROR outcome that (unusually) captured no exception.
Methods:¶
raise_for_status() -> PublishOutcome
¶
Raise PublishError if the publish failed; else return self (M1).
broker.publish() never raises — it returns this outcome so a
failed publish (NACKED / TIMEOUT / RETURNED / ERROR / NOT_SENT /
UNKNOWN) can't be lost by
code that simply ignores the return value. Callers who prefer
exceptions opt in::
broker.publish(envelope).raise_for_status()
Chains so outcome = broker.publish(...).raise_for_status() works.
Source code in src/rabbitkit/core/types.py
PublishStatus
¶
Bases: str, Enum
Result status of a publish operation.
Source code in src/rabbitkit/core/types.py
PublishReason
¶
Bounded PublishOutcome.reason codes (snake_case, safe as a metric label).
Plain string constants rather than an Enum so outcome.reason is an
ordinary str ("admission_timeout"), whatever produced it.