babelqueue 1.24.0__tar.gz → 1.25.0__tar.gz

{babelqueue-1.24.0 → babelqueue-1.25.0}/.github/workflows/ci.yml

@@ -177,7 +177,7 @@ jobs:
           --health-retries 10
     env:
       # The pinned conformance release (ADR-0032). Bump together with tests/conformance/.
-      BQ_CONFORMANCE_VERSION: 1.8.0
+      BQ_CONFORMANCE_VERSION: 1.9.0
       # sha256 of that release's fetch.sh: the script runs on the runner, so it is pinned rather
       # than trusted from a mutable tag. Bump together with BQ_CONFORMANCE_VERSION.
       BQ_FETCH_SH_SHA256: 8bb6ba567b288fb0ac71a70fd17041b2503df119e01998d76fdad372570bf849

{babelqueue-1.24.0 → babelqueue-1.25.0}/.github/workflows/release.yml

@@ -28,7 +28,7 @@ jobs:
           --health-retries 10
     env:
       # The pinned conformance release (ADR-0032). Keep identical to ci.yml.
-      BQ_CONFORMANCE_VERSION: 1.8.0
+      BQ_CONFORMANCE_VERSION: 1.9.0
       BQ_FETCH_SH_SHA256: 8bb6ba567b288fb0ac71a70fd17041b2503df119e01998d76fdad372570bf849
     permissions:
       id-token: write   # PyPI Trusted Publishing (OIDC) — no API token needed

{babelqueue-1.24.0 → babelqueue-1.25.0}/CHANGELOG.md

@@ -9,6 +9,93 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [1.25.0] - 2026-11-01
+
+### Changed (dashboard-breaking) — `babelqueue.otel` follows the OpenTelemetry messaging semantic conventions v1.44.0 (ADR-0038)
+- **Span names change with no overlap:** `publish <urn>` becomes `send <queue>` and
+  `process <urn>` becomes `process <queue>` (the bare `send` / `process` when there is no queue).
+  The URN is never in the span name now (it is unbounded); it is the `babelqueue.urn` attribute.
+  The producer's `messaging.destination.name` is the queue the message is published to (it was the
+  URN), so a producer span and its consumer span share one destination. **Saved queries and
+  dashboards that filter on the old span names or on the producer destination must be updated.**
+- **`messaging.system` is now the broker when you pass it.** `wrap_handler(..., system="kafka")` and
+  `publish(..., system="kafka")` (`redis`, `rabbitmq`, `aws_sqs`, `servicebus`, `pulsar`, `kafka`,
+  `activemq`; any other value is written as given). **Omitting `system` keeps `babelqueue`, which is
+  deprecated** (a one-time warning is logged); what an absent `system` means after the deprecation
+  window is not decided yet, so pass it now.
+- New span attributes: `messaging.operation.type` / `messaging.operation.name` (`send` or
+  `process`), `babelqueue.urn`, `babelqueue.schema_version`, `babelqueue.attempts` and, on a failure,
+  `error.type` (`module.QualName` of the exception, the bare name for builtins) with an explicit
+  `ERROR` status whose description is the exception message. `consumer_group="..."` on
+  `wrap_handler` writes `messaging.consumer.group.name`.
+- **Dual-emit for this MINOR only:** the deprecated `messaging.operation` (`publish` / `process`) and
+  `messaging.babelqueue.attempts` are still written next to their replacements. **The next MINOR
+  removes both.**
+- `babelqueue.otel.SEMCONV_VERSION` (`1.44.0`) and `SEMCONV_SCHEMA_URL` (`https://opentelemetry.io/schemas/1.44.0`)
+  are public; create the tracer and meter with the schema URL
+  (`trace.get_tracer("orders", schema_url=otel.SEMCONV_SCHEMA_URL)`).
+- A `trace_id` that is not a UUID is still preserved byte for byte and hashed for the OTel TraceID
+  (`trace_id_of` is unchanged); `wrap_handler` now logs a warning once per distinct value
+  (message-envelope.md 5.1, ADR-0038 section 7). Nothing is rejected or regenerated.
+
+### Added
+- **Standard metrics (ADR-0039), opt-in.** Pass `meter=` to `wrap_handler` and `publish` to record
+  `messaging.process.duration` (histogram, `s`, semconv bucket advice where the API supports it),
+  `messaging.client.consumed.messages`, `messaging.client.sent.messages` and `babelqueue.retries`
+  (counters, `{message}`; `retries` counts a delivery with `attempts > 0`). The attributes are
+  `messaging.system`, `messaging.operation.name`, `messaging.destination.name` (when known) and
+  `error.type` (on failure); never the URN, an id, the attempt count or a dead-letter reason. With no
+  `meter` nothing is recorded.
+- **`babelqueue.dlq.messages` and the dead-letter observer seam (ADR-0039 section 5).**
+  `BabelQueue(..., dead_letter_observer=callback)` calls `callback(DeadLetterEvent(queue,
+  dead_letter_queue, reason))` once per dead-letter the runtime carried out, after the DLQ write is
+  confirmed (`BabelQueue._write_dead_letter`, the one chokepoint for exhausted retries, an unknown
+  URN, a poison body and a version-gated raw body) or after an SDK-initiated native dead-letter. A
+  failed write, a native no-op (SQS) and a broker-side dead-letter are not reported; an exception
+  raised by the observer is logged and never changes how the message is settled.
+  `otel.dead_letter_observer(meter, system=...)` is the observer that counts the metric.
+  New exports: `DeadLetterEvent`, `DeadLetterObserver`, and the `NativeDeadLetterSettler` protocol.
+- **`NativeDeadLetterSettler`**: the optional native-settle variant
+  `settle_native_dead_letter(message, reason, description) -> bool` next to `NativeSettler`
+  (unchanged). When a transport implements it the runtime prefers it and reports a dead-letter only
+  on `True`; `AsbTransport` implements it, the SQS no-op does not.
+- **`BabelQueue.publish_envelope(urn, data, *, queue=None, trace_id=None, headers=None)`** returns a
+  `PublishResult(envelope, error)` pair instead of raising. After a transport failure it still
+  carries the envelope that was handed to the transport (so `otel.publish` can put `meta.id` and
+  `trace_id` on a failed span); after a `make` or `encode` failure `envelope` is `None`. `publish`
+  and `publish_with_headers` delegate to it and behave exactly as before (an empty `queue` still
+  resolves to the default queue). `otel.publish` falls back to a duck-typed `app.publish(...)` for
+  objects that do not have it.
+- Conformance **1.9.0** is vendored; the `span-shape`, `trace-id` and `metrics` sections (and the six
+  new `traceparent` cases) run and pass.
+- **W3C `traceparent` / `tracestate` on the Kafka, Pulsar, Artemis and Azure Service Bus
+  transports (ADR-0028; broker-bindings 4.3, 5.2, 6.3, 7.2).** Each transport now implements the
+  `HeaderPublisher` capability: `publish_with_headers(queue, body, headers)` carries the headers
+  out of band beside the `bq-*` / `bq_*` projection (Kafka record headers, Pulsar message
+  properties, Artemis AMQP 1.0 application-properties, Azure Service Bus application properties).
+  The projection wins a key collision, and the body is byte-identical to a plain `publish`.
+  `pop` surfaces every non-projection header on `ReceivedMessage.headers` (so
+  `babelqueue.otel.wrap_handler` links the consumer span to the producer's across these brokers);
+  the projection keys themselves are never leaked, and `bq-replay-bypass` (ADR-0027) passes
+  through. A Kafka retry parks the consumed record's `traceparent` / `tracestate` on the tier topic
+  (the re-inject consumer already keeps every header except `bq-delay` / `bq-original-topic`), so
+  a retried message stays in the original trace. Retry tier names, `retry_tiers_ms` and the
+  poison / DLQ shapes are unchanged. `babelqueue.headers.out_of_band_headers` is the shared helper.
+- **`RedrivePublisher` capability and `redrive(bypass=True)` on the header-capable transports.**
+  Kafka, Pulsar, Artemis and Azure Service Bus becoming `HeaderPublisher`s means
+  `redrive(..., bypass=True)` now really stamps the `bq-replay-bypass` marker on them
+  (`RedriveItem.bypassed` is `True`; it was `False` before, because the transports could not carry
+  headers), and the write goes through the transport's header-carrying path. So that this path
+  loses nothing the ordinary redrive write keeps, `Kafka` and `Pulsar` implement the new optional
+  `publish_redriven(queue, body, headers, route_urn, key)`: Kafka's is the broker-confirmed settle
+  write (a delivery failure raises `KafkaDeliveryError`, the DLQ record is restored and not
+  committed past) and carries the DLQ record key unchanged; Pulsar's pins `bq-job` to the
+  dead-lettered delivery's routing property. `redrive` uses it when the transport has it.
+- **`AsbTransport.settle_native_dead_letter(message, reason, description) -> bool`** (ADR-0039
+  section 5.1): the optional native-settle variant that reports what it did. It performs the same
+  settle as `settle_native` (which is unchanged) and returns `True` when the receiver's
+  `dead_letter_message` ran, `False` when it only abandoned the lock or had no handle.
+
 ## [1.24.0] - 2026-10-26
 
 Implements conformance **1.8.0** (vendored from the `v1.8.0` release asset, verified with

{babelqueue-1.24.0 → babelqueue-1.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: babelqueue
-Version: 1.24.0
+Version: 1.25.0
 Summary: Polyglot Queues, Simplified — the Python core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers.
 Project-URL: Homepage, https://babelqueue.com
 Project-URL: Source, https://github.com/BabelQueue/babelqueue-python

{babelqueue-1.24.0 → babelqueue-1.25.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.24.0"
+version = "1.25.0"
 description = "Polyglot Queues, Simplified — the Python core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers."
 readme = "README.md"
 requires-python = ">=3.9"

{babelqueue-1.24.0 → babelqueue-1.25.0}/src/babelqueue/__init__.py

@@ -15,6 +15,7 @@ from . import dead_letter, gdpr, headers, idempotency, outbox, redrive, replay
 from .app import BabelQueue
 from .codec import SCHEMA_VERSION, SOURCE_LANG, EnvelopeCodec
 from .contracts import HasTraceId, PolyglotMessage
+from .dead_letter import DeadLetterEvent, DeadLetterObserver, NativeDeadLetterSettler
 from .gdpr import Cipher, protect, unprotect
 from .headers import headers_from_context
 from .idempotency import IdempotencyStore, InMemoryStore
@@ -39,13 +40,14 @@ from .transport import (
     NativeSettler,
     ReceivedMessage,
     Redeliverer,
+    RedrivePublisher,
     Rewinder,
     RoutedPublisher,
     SettlePublisher,
     Transport,
 )
 
-__version__ = "1.24.0"
+__version__ = "1.25.0"
 
 __all__ = [
     "BabelQueue",
@@ -64,7 +66,11 @@ __all__ = [
     "DeadLetterWriter",
     "HeaderPublisher",
     "NativeSettler",
+    "NativeDeadLetterSettler",
+    "DeadLetterEvent",
+    "DeadLetterObserver",
     "Redeliverer",
+    "RedrivePublisher",
     "Rewinder",
     "RoutedPublisher",
     "SettlePublisher",

{babelqueue-1.24.0 → babelqueue-1.25.0}/src/babelqueue/app.py

@@ -32,10 +32,11 @@ import random
 import signal
 import threading
 from types import FrameType
-from typing import Any, Callable, Dict, Mapping, Optional
+from typing import Any, Callable, Dict, Mapping, NamedTuple, Optional
 
 from . import dead_letter
 from .codec import EnvelopeCodec, has_forbidden_keys, parse_envelope
+from .dead_letter import DeadLetterEvent, DeadLetterObserver, NativeDeadLetterSettler
 from ._poison_record import build_poison_record
 from .exceptions import BabelQueueError, UnknownUrnError
 from .headers import _headers_scope
@@ -101,6 +102,19 @@ class _ShutdownDeadline(BaseException):
     A ``BaseException`` so the dispatch-level ``except Exception`` does not swallow it."""
 
 
+class PublishResult(NamedTuple):
+    """The outcome of :meth:`BabelQueue.publish_envelope`: ``(envelope, error)``.
+
+    ``envelope`` is the envelope that was handed to the transport (``None`` when building or
+    encoding it failed, so nothing was ever handed over); ``error`` is the exception that stopped
+    the publish (``None`` on success). A failed transport publish therefore still yields the
+    envelope that was attempted, which is what an observability wrapper needs.
+    """
+
+    envelope: Optional[Dict[str, Any]]
+    error: Optional[Exception]
+
+
 class BabelQueue:
     def __init__(
         self,
@@ -119,6 +133,7 @@ class BabelQueue:
         retry_jitter: str = "none",
         unknown_urn_release_delay: float = 0.0,
         shutdown_timeout: float = 30.0,
+        dead_letter_observer: Optional[DeadLetterObserver] = None,
     ) -> None:
         """
         ``retry_backoff`` / ``unknown_urn_release_delay`` are the seconds a released message
@@ -139,6 +154,12 @@ class BabelQueue:
         before releasing its message. Keep it above your longest handler run: a released
         message is redelivered and its handler runs again, and on brokers that count
         deliveries (SQS ``ApproximateReceiveCount``) the release also consumes an attempt.
+
+        ``dead_letter_observer`` (ADR-0039 section 5.1) is an optional callback
+        :data:`~babelqueue.dead_letter.DeadLetterObserver` the runtime calls once per dead-letter it
+        carried out itself, after the DLQ write (or the native dead-letter) is confirmed. A failed
+        write, a native no-op and a broker-side dead-letter are not reported. An exception it
+        raises is logged and never changes how the message is settled.
         """
         self.transport = transport if transport is not None else make_transport(broker_url)
         self.queue = queue
@@ -157,6 +178,7 @@ class BabelQueue:
         self.retry_jitter = retry_jitter
         self.unknown_urn_release_delay = float(unknown_urn_release_delay)
         self.shutdown_timeout = float(shutdown_timeout)
+        self.dead_letter_observer = dead_letter_observer
         self._handlers: Dict[str, Handler] = {}
         self._stop = threading.Event()
         self._rewind_pause = 1.0  # seconds to wait before a rewound gated message is re-polled
@@ -178,10 +200,7 @@ class BabelQueue:
         trace_id: Optional[str] = None,
     ) -> str:
         """Publish a message; returns its id (``meta.id``)."""
-        target = queue or self.queue
-        envelope = EnvelopeCodec.make(urn, data, queue=target, trace_id=trace_id)
-        self.transport.publish(target, EnvelopeCodec.encode(envelope))
-        return envelope["meta"]["id"]
+        return self._published_id(self.publish_envelope(urn, data, queue=queue, trace_id=trace_id))
 
     def publish_with_headers(
         self,
@@ -205,14 +224,60 @@ class BabelQueue:
         exactly as :func:`~babelqueue.redrive.redrive` degrades. Passing empty headers is
         equivalent to :meth:`publish`, so callers need not branch on transport capability.
         """
+        return self._published_id(
+            self.publish_envelope(urn, data, queue=queue, trace_id=trace_id, headers=headers)
+        )
+
+    def publish_envelope(
+        self,
+        urn: str,
+        data: Mapping[str, Any],
+        *,
+        queue: Optional[str] = None,
+        trace_id: Optional[str] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> PublishResult:
+        """Publish like :meth:`publish` / :meth:`publish_with_headers`, but **return** the outcome
+        instead of raising: a :class:`PublishResult` ``(envelope, error)`` pair.
+
+        It is the one place that builds and sends the envelope. The two plain publish methods
+        delegate to it and re-raise ``error``, so their behaviour is unchanged (an empty ``queue``
+        resolves to :attr:`queue`, exactly as there). The difference is what a failure leaves
+        behind:
+
+        * ``make`` or ``encode`` failed (e.g. a blank URN, or ``data`` that is not JSON
+          serializable): ``envelope`` is ``None``, because nothing was ever handed to the
+          transport; ``error`` is the exception.
+        * the transport failed: ``envelope`` is the envelope that was handed to it (``meta.id``,
+          ``trace_id`` and ``meta.queue`` are readable), and ``error`` is the exception.
+        * success: ``(envelope, None)``.
+
+        ``headers`` are the out-of-band transport headers of :meth:`publish_with_headers`
+        (empty or ``None`` means a plain publish). The observability wrapper
+        :func:`babelqueue.otel.publish` uses it to read the produced identity on the failure path.
+        Only ``Exception`` is captured; ``KeyboardInterrupt`` and friends propagate.
+        """
         target = queue or self.queue
-        envelope = EnvelopeCodec.make(urn, data, queue=target, trace_id=trace_id)
-        body = EnvelopeCodec.encode(envelope)
-        if headers and isinstance(self.transport, HeaderPublisher):
-            self.transport.publish_with_headers(target, body, dict(headers))
-        else:
-            self.transport.publish(target, body)
-        return envelope["meta"]["id"]
+        try:
+            envelope = EnvelopeCodec.make(urn, data, queue=target, trace_id=trace_id)
+            body = EnvelopeCodec.encode(envelope)
+        except Exception as exc:  # noqa: BLE001 - returned to the caller, which re-raises it
+            return PublishResult(None, exc)
+        try:
+            if headers and isinstance(self.transport, HeaderPublisher):
+                self.transport.publish_with_headers(target, body, dict(headers))
+            else:
+                self.transport.publish(target, body)
+        except Exception as exc:  # noqa: BLE001 - returned to the caller, which re-raises it
+            return PublishResult(envelope, exc)
+        return PublishResult(envelope, None)
+
+    @staticmethod
+    def _published_id(result: PublishResult) -> str:
+        if result.error is not None:
+            raise result.error
+        assert result.envelope is not None  # no error means the envelope was built and sent
+        return result.envelope["meta"]["id"]
 
     # -- Register handlers --------------------------------------------------
 
@@ -504,16 +569,46 @@ class BabelQueue:
         mismatch does not flip to the body URN on the next attempt or in the DLQ."""
         publish_keeping_route(self.transport, queue, body, received.route_urn, received.key)
 
-    def _write_dead_letter(self, received: ReceivedMessage, queue: str, body: str) -> None:
+    def _write_dead_letter(
+        self,
+        received: ReceivedMessage,
+        queue: str,
+        body: str,
+        *,
+        source_queue: Optional[str] = None,
+        reason: str = "",
+    ) -> None:
         """Write the dead-letter record ``body`` to ``queue`` and settle ``received``.
 
         A :class:`~babelqueue.transport.DeadLetterWriter` transport does both as one guarded step
-        (a failed write propagates, never acks); otherwise publish, then acknowledge."""
+        (a failed write propagates, never acks); otherwise publish, then acknowledge.
+
+        The single chokepoint of every BabelQueue DLQ write (ADR-0039 section 5.2): once the write
+        is confirmed the dead-letter observer is told (``source_queue`` defaults to the queue
+        ``received`` came from, ``reason`` is empty for a raw body). A failed write raises before
+        that, so the observer is never called for it."""
         if isinstance(self.transport, DeadLetterWriter):
             self.transport.dead_letter(received, queue, body)
+        else:
+            self._publish_for(received, queue, body)
+            self._ack_settled(received)
+        self._notify_dead_letter(source_queue or received.queue, queue, reason)
+
+    def _notify_dead_letter(self, queue: str, dead_letter_queue: str, reason: str) -> None:
+        """Tell :attr:`dead_letter_observer` about a confirmed dead-letter. A raising observer is
+        logged and swallowed: it must never change the settle outcome (ADR-0039 section 5.1)."""
+        observer = self.dead_letter_observer
+        if observer is None:
             return
-        self._publish_for(received, queue, body)
-        self._ack_settled(received)
+        try:
+            observer(DeadLetterEvent(queue=queue, dead_letter_queue=dead_letter_queue, reason=reason))
+        except Exception:  # noqa: BLE001 - an observer must never affect settlement
+            logger.error(
+                "The dead-letter observer failed for a message from queue %r; the dead-letter "
+                "itself was already settled and is unaffected.",
+                queue,
+                exc_info=True,
+            )
 
     def _ack_settled(self, received: ReceivedMessage) -> None:
         """Acknowledge a message whose outcome is already final (handled, dead-lettered,
@@ -540,8 +635,13 @@ class BabelQueue:
         """Hand ``received`` to the transport's :class:`~babelqueue.transport.NativeSettler`
         capability and report whether it did: ``False`` means the transport has none and the caller
         keeps its previous settle. The event is logged and never retried by the SDK; a failing call
-        is logged too and leaves the message unacknowledged (the broker redelivers it)."""
-        if not isinstance(self.transport, NativeSettler):
+        is logged too and leaves the message unacknowledged (the broker redelivers it).
+
+        A transport that also implements :class:`~babelqueue.dead_letter.NativeDeadLetterSettler`
+        is settled through that variant instead, and the dead-letter observer is told only when it
+        returns ``True`` (a native dead-letter the SDK carried out, ADR-0039 section 5.1)."""
+        transport = self.transport
+        if not isinstance(transport, (NativeDeadLetterSettler, NativeSettler)):
             return False
         logger.warning(
             "Left to the broker's native mechanism (not acknowledged, not retried): queue %r, "
@@ -549,7 +649,14 @@ class BabelQueue:
             received.queue, received.route_urn, reason,
         )
         try:
-            self.transport.settle_native(received, reason, description)
+            if isinstance(transport, NativeDeadLetterSettler):
+                # The optional variant (ADR-0039 section 5.1) says whether the broker really
+                # dead-lettered the message: only a literal ``True`` is a dead-letter the SDK
+                # carried out (an abandon, or the SQS-style no-op, is not).
+                if transport.settle_native_dead_letter(received, reason, description) is True:
+                    self._notify_dead_letter(received.queue, "", "")
+            else:
+                transport.settle_native(received, reason, description)
         except Exception:  # noqa: BLE001 - reported, never kills the loop
             logger.error(
                 "Native settle of a message on queue %r failed; it stays unacknowledged and will "
@@ -735,7 +842,7 @@ class BabelQueue:
             self._ack_settled(received)
             return
         if self.dead_letter_enabled or self.on_unknown_urn == UnknownUrnStrategy.DEAD_LETTER:
-            self._settle_version_gated(received, always=True)
+            self._settle_version_gated(received, always=True, reason="poison")
             return
         if self._retry_tiers_unavailable():
             # broker-bindings §6.5 / ADR-0036 decision 5: no retry tier, no dead-lettering and not
@@ -836,7 +943,10 @@ class BabelQueue:
             exception=BabelQueueError.__name__,
         )["dead_letter"]
         self._write_dead_letter(
-            received, self._dead_letter_target(received), build_poison_record(received.body, block)
+            received,
+            self._dead_letter_target(received),
+            build_poison_record(received.body, block),
+            reason="poison",
         )
 
     def _dead_letter_target(self, received: ReceivedMessage) -> str:
@@ -850,11 +960,16 @@ class BabelQueue:
             return self.transport.dead_letter_queue_name(received.queue, self.dead_letter_suffix)
         return received.queue + (".dlq" if self.dead_letter_suffix is None else self.dead_letter_suffix)
 
-    def _settle_version_gated(self, received: ReceivedMessage, always: bool = False) -> None:
+    def _settle_version_gated(
+        self, received: ReceivedMessage, always: bool = False, reason: str = ""
+    ) -> None:
         """Dead-letter a version-gated delivery directly (no retry). With no DLQ set it is left to the
         transport's native mechanism when the transport has the :class:`~babelqueue.transport.NativeSettler`
         capability (SQS, Azure Service Bus; ADR-0037 decision 1 rule 3) and dropped otherwise.
 
+        ``reason`` is what the dead-letter observer is told (``""`` for a raw version-gated body;
+        ``"poison"`` for a Kafka poison record, whose DLQ record the transport wraps with that reason).
+
         ``always`` writes the DLQ record in every configuration, ignoring ``dead_letter_enabled``.
         A Kafka poison record reaches it with the DLQ already on (:meth:`_route_poison`). The Redis
         poison reservation does not come through here: it has its own ADR-0035 record
@@ -866,7 +981,9 @@ class BabelQueue:
         (see :meth:`dispatch`), never retried.
         """
         if always or self.dead_letter_enabled or self.on_unknown_urn == UnknownUrnStrategy.DEAD_LETTER:
-            self._write_dead_letter(received, self._dead_letter_target(received), received.body)
+            self._write_dead_letter(
+                received, self._dead_letter_target(received), received.body, reason=reason
+            )
             return
         # No DLQ to hold it (broker-bindings §5.7 rule 3). A transport with a native mechanism (SQS,
         # Azure Service Bus) leaves it to that mechanism instead of dropping it (ADR-0037 decision 1).
@@ -927,7 +1044,11 @@ class BabelQueue:
             exception=(type(exc).__name__ if exc is not None else None),
         )
         self._write_dead_letter(
-            received, self._dead_letter_target(received), EnvelopeCodec.encode(annotated)
+            received,
+            self._dead_letter_target(received),
+            EnvelopeCodec.encode(annotated),
+            source_queue=original_queue,
+            reason=reason,
         )
 
 

{babelqueue-1.24.0 → babelqueue-1.25.0}/src/babelqueue/artemis_transport.py

@@ -21,6 +21,13 @@ deliveries. (The Java JMS binding reads ``JMSXDeliveryCount`` which is 1-based a
 arriving at the same 0-based ``attempts``.) A message left un-accepted is redelivered
 (at-least-once).
 
+Out-of-band transport headers (a W3C ``traceparent`` for cross-hop span linkage, ADR-0028) ride as
+extra AMQP 1.0 application-properties (string-valued, hyphen-free names) beside the ``bq_*`` projection:
+:meth:`ArtemisTransport.publish_with_headers` writes them (the projection wins a collision) and
+:meth:`~ArtemisTransport.pop` surfaces every non-projection application-property on
+:attr:`~babelqueue.transport.ReceivedMessage.headers`; the ``bq_*`` projection keys are not leaked. The
+body is untouched (GR-1).
+
 This implements §7 of the broker-bindings contract. The envelope is unchanged
 (``schema_version`` stays 1); Apache ActiveMQ Artemis is purely additive.
 
@@ -38,6 +45,7 @@ from typing import Any, Dict, Optional
 from urllib.parse import quote
 
 from .codec import ASCII_WHITESPACE, SCHEMA_VERSION, EnvelopeCodec, parse_envelope
+from .headers import out_of_band_headers
 from .transport import ReceivedMessage, Transport, truncate_declared_version
 
 _logger = logging.getLogger("babelqueue.artemis")
@@ -157,12 +165,14 @@ class ArtemisTransport(Transport):
         except (TypeError, ValueError):  # pragma: no cover - defensive
             return None
 
-    def _message(self, body: str) -> Any:
-        """Build the proton Message projecting the §7 JMS-readable metadata."""
+    def _message(self, body: str, headers: Optional[Dict[str, str]] = None) -> Any:
+        """Build the proton Message projecting the §7 JMS-readable metadata. ``headers`` are
+        out-of-band application-properties (ADR-0028) merged *under* the ``bq_*`` projection."""
         from proton import Message, symbol
 
         message: Any = Message(body=body)
-        props = self._projection(body)
+        props = out_of_band_headers(headers)
+        props.update(self._projection(body))
         if props:
             message.properties = props
         correlation_id = self._correlation_id(body)
@@ -242,6 +252,13 @@ class ArtemisTransport(Transport):
     def publish(self, queue: str, body: str) -> None:
         self._sender(queue).send(self._message(body))
 
+    def publish_with_headers(self, queue: str, body: str, headers: Dict[str, str]) -> None:
+        """:meth:`publish` with out-of-band ``headers`` (a W3C ``traceparent``, the replay-bypass
+        marker ...) carried as extra AMQP 1.0 application-properties beside the ``bq_*`` projection
+        (:class:`~babelqueue.transport.HeaderPublisher`, ADR-0028, broker-bindings 7.2). The
+        projection wins a key collision and the body is byte-identical to :meth:`publish`."""
+        self._sender(queue).send(self._message(body, headers))
+
     def pop(self, queue: str, timeout: float = 1.0) -> Optional[ReceivedMessage]:
         wait = self._receive_timeout_millis / 1000.0
         if timeout and timeout > 0:
@@ -276,7 +293,12 @@ class ArtemisTransport(Transport):
                 route_urn=UNSUPPORTED_SCHEMA_ROUTE_PREFIX + quote(unsupported, safe=""),
             )
         body = self._reconcile(self._payload(message), self._delivery_count(message))
-        return ReceivedMessage(body=body, queue=queue, handle=receiver)
+        return ReceivedMessage(
+            body=body,
+            queue=queue,
+            handle=receiver,
+            headers=out_of_band_headers(getattr(message, "properties", None)),
+        )
 
     def ack(self, message: ReceivedMessage) -> None:
         if message.handle is None:

{babelqueue-1.24.0 → babelqueue-1.25.0}/src/babelqueue/asb_transport.py

@@ -16,6 +16,13 @@ A version-gated message (``bq-schema-version`` the consumer does not support) or
 dead-lettering off, not completed: :meth:`AsbTransport.settle_native` dead-letters it natively into
 ``$DeadLetterQueue`` (ADR-0037).
 
+Out-of-band transport headers (a W3C ``traceparent`` for cross-hop span linkage, ADR-0028) ride as
+extra application properties (string-valued) beside the ``bq-*`` projection:
+:meth:`AsbTransport.publish_with_headers` writes them (the projection wins a collision) and
+:meth:`~AsbTransport.pop` surfaces every non-projection application property on
+:attr:`~babelqueue.transport.ReceivedMessage.headers`; the ``bq-*`` projection keys are not leaked.
+The body is untouched (GR-1).
+
 This implements §4 of the broker-bindings contract. The envelope is unchanged
 (``schema_version`` stays 1); Azure Service Bus is purely additive.
 
@@ -33,6 +40,7 @@ from typing import Any, Dict, Optional
 from urllib.parse import quote, urlsplit
 
 from .codec import ASCII_WHITESPACE, SCHEMA_VERSION, EnvelopeCodec, parse_envelope
+from .headers import out_of_band_headers
 from .transport import ReceivedMessage, Transport, truncate_declared_version
 
 _logger = logging.getLogger("babelqueue.asb")
@@ -228,11 +236,23 @@ class AsbTransport(Transport):
     # -- Transport ----------------------------------------------------------
 
     def publish(self, queue: str, body: str) -> None:
+        self._send(queue, body, None)
+
+    def publish_with_headers(self, queue: str, body: str, headers: Dict[str, str]) -> None:
+        """:meth:`publish` with out-of-band ``headers`` (a W3C ``traceparent``, the replay-bypass
+        marker ...) carried as extra string-valued application properties beside the ``bq-*``
+        projection (:class:`~babelqueue.transport.HeaderPublisher`, ADR-0028, broker-bindings 4.3).
+        The projection wins a key collision and the body is byte-identical to :meth:`publish`."""
+        self._send(queue, body, headers)
+
+    def _send(self, queue: str, body: str, headers: Optional[Dict[str, str]]) -> None:
         from azure.servicebus import ServiceBusMessage
 
         kwargs = self._projection(body)
-        if kwargs.get("application_properties"):
-            kwargs["application_properties"] = _amqp_typed(kwargs["application_properties"])
+        properties: Dict[str, Any] = dict(out_of_band_headers(headers))
+        properties.update(kwargs.get("application_properties") or {})
+        if properties:
+            kwargs["application_properties"] = _amqp_typed(properties)
         message = ServiceBusMessage(body, **kwargs)
         self._sender(queue).send_messages(message)
 
@@ -266,7 +286,12 @@ class AsbTransport(Transport):
                 route_urn=UNSUPPORTED_SCHEMA_ROUTE_PREFIX + quote(unsupported, safe=""),
             )
         body = self._reconcile(str(message), getattr(message, "delivery_count", None))
-        return ReceivedMessage(body=body, queue=queue, handle=message)
+        return ReceivedMessage(
+            body=body,
+            queue=queue,
+            handle=message,
+            headers=out_of_band_headers(getattr(message, "application_properties", None)),
+        )
 
     def ack(self, message: ReceivedMessage) -> None:
         if message.handle is None:
@@ -297,14 +322,26 @@ class AsbTransport(Transport):
         ``$DeadLetterQueue``. Nothing is completed, re-published or retried, and the body is
         unchanged. A receiver without ``dead_letter_message`` abandons the lock instead (also a
         conformant native settle: ``MaxDeliveryCount`` takes over)."""
+        self.settle_native_dead_letter(message, reason, description)
+
+    def settle_native_dead_letter(
+        self, message: ReceivedMessage, reason: str, description: str
+    ) -> bool:
+        """:meth:`settle_native` that also reports what it did (the optional native-settle variant
+        of ADR-0039 section 5.1): ``True`` when the receiver's ``dead_letter_message`` was called,
+        so the message really went to ``$DeadLetterQueue``, and ``False`` when it only abandoned
+        the lock (a receiver without ``dead_letter_message``) or had no handle to settle. The
+        runtime prefers it over :meth:`settle_native` and counts a dead-letter only on ``True``.
+        The settle itself is identical to :meth:`settle_native`, which stays as it was."""
         if message.handle is None:
-            return
+            return False
         receiver = self._receiver(message.queue)
         dead_letter = getattr(receiver, "dead_letter_message", None)
         if dead_letter is not None:
             dead_letter(message.handle, reason=reason, error_description=description)
-            return
+            return True
         self.abandon(message)
+        return False
 
     def close(self) -> None:  # pragma: no cover - resource cleanup
         for resource in (*self._senders.values(), *self._receivers.values(), self._client):