babelqueue 1.14.0__tar.gz → 1.16.0__tar.gz

{babelqueue-1.14.0 → babelqueue-1.16.0}/.github/workflows/ci.yml

@@ -17,10 +17,10 @@ jobs:
       matrix:
         python: ['3.9', '3.10', '3.11', '3.12', '3.13']
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python }}
 
@@ -36,9 +36,9 @@ jobs:
     name: Static analysis (ruff + mypy)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: '3.12'
       - name: Install (dev + all adapters for type context)
@@ -79,10 +79,10 @@ jobs:
         ports:
           - 9324:9324
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: '3.12'
 
@@ -115,10 +115,10 @@ jobs:
     name: Conformance suite in sync
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
       - name: Verify vendored conformance matches the canonical suite
         run: |
-          git clone --depth 1 --branch v1.0.0 https://github.com/BabelQueue/conformance.git "$RUNNER_TEMP/conformance"
+          git clone --depth 1 --branch v1.1.0 https://github.com/BabelQueue/conformance.git "$RUNNER_TEMP/conformance"
           diff -u "$RUNNER_TEMP/conformance/CONFORMANCE_VERSION" "tests/conformance/CONFORMANCE_VERSION"
           diff -ru "$RUNNER_TEMP/conformance/manifest.json" "tests/conformance/manifest.json"
           diff -ru "$RUNNER_TEMP/conformance/fixtures"      "tests/conformance/fixtures"

{babelqueue-1.14.0 → babelqueue-1.16.0}/.github/workflows/release.yml

@@ -18,10 +18,10 @@ jobs:
       id-token: write   # PyPI Trusted Publishing (OIDC) — no API token needed
       contents: write   # create the GitHub release
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: '3.12'
 
@@ -41,6 +41,6 @@ jobs:
         #     password: ${{ secrets.PYPI_API_TOKEN }}
 
       - name: Create GitHub release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           generate_release_notes: true

{babelqueue-1.14.0 → babelqueue-1.16.0}/CHANGELOG.md

@@ -9,6 +9,99 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [1.16.0] - 2026-10-10
+
+### Added
+- New optional `Rewinder` protocol (`rewind(message)`), implemented by `KafkaTransport` and
+  exported from `babelqueue` (public API, MINOR). The runtime calls it after a failed
+  version-gate dead-letter write and then pauses briefly (1 s) before the next poll.
+
+### Fixed
+- **`bq-schema-version` pre-decode gate on the SQS, Azure Service Bus, Kafka and Artemis
+  transports** (`pop`). The broker's schema-version property is read **before** the body is
+  decoded (broker-bindings §3.7 / §4.7 / §6.7 / §7.7), mirroring the existing Pulsar gate:
+  a missing or blank value (empty or only ASCII whitespace) takes the normal path; anything
+  else is compared untrimmed to `"1"` and a mismatch is returned with the raw body and the
+  reserved route `babelqueue:unsupported-schema-version:<v>` (version percent-escaped) without
+  decoding it. SQS/ASB/Kafka read `bq-schema-version`, Artemis `bq_schema_version`
+  (ADR-0017); ASB and Artemis also accept an integer `1` (a `bool` is not `1`). The conformance suite now reads each binding's
+  `schema_version_gate` table (including Pulsar's). No wire change.
+- **A version-gated delivery is dead-lettered directly, never retried.** `BabelQueue` now
+  sends a message under the reserved gate route straight to the DLQ (reason `unknown_urn`,
+  body untouched) when `dead_letter` is enabled and drops it otherwise, regardless of
+  `max_attempts` / `on_unknown_urn`. A retry would re-publish through paths that rebuild the
+  version header from the (valid) body (ASB/Kafka/Artemis) or never advance the attempt
+  counter (SQS), letting the gate be bypassed or the message loop. Applies to Pulsar too
+  (previously it retried up to `max_attempts` first).
+  If the dead-letter write itself fails, the message is still never retried: it is left
+  unacknowledged (an error is logged) so the broker redelivers it and the gate rejects it again
+  (SQS at the visibility timeout, Azure Service Bus at lock expiry, Artemis when the link or
+  connection closes). Kafka commits offsets cumulatively, so merely not acknowledging the
+  record would lose it once a later record is committed: `KafkaTransport` now `seek`s the
+  partition back to the failed record's offset so it is polled again and the dead-letter write
+  is retried (no commit moves past it).
+- The rejected `bq-schema-version` value is capped at 64 characters plus `...` in the log and
+  the route.
+
+## [1.15.0] - 2026-10-10
+
+### Added
+- **`ReceivedMessage.route_urn` routing seam** (MINOR). An optional field a transport can set
+  when its broker carries the URN out of band. When non-empty `BabelQueue.dispatch()` looks the
+  handler up by it instead of the decoded body's URN; empty (the default for every existing
+  transport) keeps routing on the body. The body is never rewritten, so the handler, the retry
+  re-publish and the dead-letter record carry the producer's original body (including a `urn`
+  alias). No wire change.
+- **`RoutedPublisher` optional transport capability** (MINOR). `publish_routed(queue, body,
+  route_urn)`. When a delivery has a `route_urn` and the transport implements it, the retry, release and dead-letter
+  writes, and `redrive`, use it so the broker's routing property keeps the original
+  value across attempts (no flip to the body URN on the second delivery). `PulsarTransport`
+  implements it (`bq-job` pinned; blank derives from the body). Others keep plain `publish`.
+  No wire change.
+
+### Changed
+- `BabelQueue.dispatch()` applies `route_urn` only to a body that decodes; an undecodable body
+  stays on the poison / unknown-URN path instead of being routed to a handler.
+
+### Fixed
+- **`on_unknown_urn=RELEASE` no longer loops a version-gated or poison message forever.**
+  `BabelQueue.dispatch()` re-published such a message unchanged on every delivery (`attempts` never
+  grew, so it never reached the DLQ). A delivery a transport version-gated (reserved
+  `unsupported-schema-version` `route_urn`, e.g. Pulsar `bq-schema-version`), an undecodable body
+  and a body naming no URN now take the bounded `FAIL` path under `RELEASE` (retry up to
+  `max_attempts`, then dead-letter or drop), matching the Go core (GR-5). A genuinely unknown URN
+  still releases verbatim. No public API or wire change. Note: as on the existing `FAIL` path, a
+  body that is not valid JSON is not carried verbatim through the retry / dead-letter re-publish
+  (the runtime re-encodes the envelope it could build, so the producer's original bytes are lost);
+  previously `RELEASE` re-published those bytes unchanged.
+- **Pulsar consumer version-gates on `bq-schema-version` (broker-bindings §5.7 step 3).**
+  `PulsarTransport.pop()` now reads the `bq-schema-version` message property before decoding the
+  body. A missing or blank value changes nothing; "Blank" is the same set in every SDK: the empty string or only ASCII whitespace (space, `\t`, `\n`, `\v`, `\f`, `\r`); anything else (NBSP, U+001C-U+001F, U+0085, U+FEFF, U+3000, ...) is not blank and is rejected unless it is exactly the supported version. (`str.strip()` is not used: it also strips U+001C-U+001F, U+0085, NBSP, ...) a value other than the supported
+  `SCHEMA_VERSION` (`"2"`, `"x"`, `"01"`, ...) is not decoded: the delivery carries the reserved
+  `route_urn` `babelqueue:unsupported-schema-version:<value>`, which no handler owns, so the
+  runtime quarantines it through the existing unknown-URN retry / dead-letter path (the error
+  names the rejected version). The body is passed through untouched. No wire change. The route
+  is an in-process marker only: it also carries the delivery's original `bq-job`, and the retry /
+  dead-letter re-publish (`publish_routed`) writes that original `bq-job` (or, when the delivery
+  had none, the body's job) and the original raw `bq-schema-version` back, never the sentinel, so
+  a redrive meets the same gate. The gate also logs a `babelqueue.pulsar` warning naming the
+  rejected version and queue, including for a body that is not valid JSON (which the runtime
+  quarantines as a poison message whose error names the reserved route).
+- **Pulsar consumer now follows broker-bindings §5.2 / §5.7.** `PulsarTransport.pop()` routes on
+  the `bq-job` message property (set on `ReceivedMessage.route_urn`; the body's URN is used only
+  when the property is absent or blank) and takes `attempts` from the authoritative
+  `bq-attempts` property (the body's value is used only when the property is absent or not a
+  plain ASCII-decimal integer that fits a 32-bit int), then applies `max(.., redelivery_count)`.
+  Previously only the body was read. The body's `job` / `urn` is **not** rewritten, so a
+  property/body mismatch no longer leaks into retries or the DLQ; `attempts` is written into the
+  body only when the body already holds an integer `attempts` and the value changes (a missing
+  or non-integer `attempts` is still rejected by `EnvelopeCodec.accepts`). When the property and
+  the body name different URNs the property wins and the new optional
+  `on_routing_mismatch(property_urn, body_urn, envelope)` constructor hook is called for an
+  accepted envelope, after attempts are reconciled (its exceptions are swallowed; it is separate
+  from error handling). A body without a URN is still rejected. No wire change
+  (`schema_version: 1`).
+
 ## [1.14.0] - 2026-10-03
 
 ### Added

{babelqueue-1.14.0 → babelqueue-1.16.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: babelqueue
-Version: 1.14.0
+Version: 1.16.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
 Project-URL: Issues, https://github.com/BabelQueue/babelqueue-python/issues
 Project-URL: Changelog, https://github.com/BabelQueue/babelqueue-python/blob/main/CHANGELOG.md
-Author-email: Muhammet Şafak <info@muhammetsafak.com.tr>
+Author-email: Muhammet Şafak <info@muhammetsafak.com>
 License-Expression: MIT
 License-File: LICENSE
 Keywords: envelope,json,messaging,microservices,polyglot,queue
@@ -178,6 +178,43 @@ app.run()                               # consume forever (Ctrl-C to stop)
   the message unchanged once `shutdown_timeout` expires. Delivery is
   **at-least-once** — keep handlers idempotent (see the idempotency helper).
 
+### Unsupported `schema_version` (SQS, Azure Service Bus, Kafka, Artemis, Pulsar)
+
+These transports read the binding's schema-version property (`bq-schema-version`; Artemis
+`bq_schema_version`) **before** decoding the body. A missing or blank value (empty or only
+ASCII whitespace) follows the normal path; any other value must be exactly `"1"` (compared
+untrimmed; Azure Service Bus and Artemis also accept the integer `1`). A message carrying
+anything else is not decoded: it reaches the runtime on the reserved route
+`babelqueue:unsupported-schema-version:<v>` (the version percent-escaped) and is **never
+retried** — it goes straight to the dead-letter queue (reason `unknown_urn`, the body kept
+verbatim) when `dead_letter` is enabled, and is dropped otherwise, whatever `max_attempts` is.
+It does not depend on a broker `RedrivePolicy`. If the dead-letter write fails the message is
+left unacknowledged (an error is logged), is never retried and never reaches a handler; the
+dead-letter write is attempted again when the broker brings it back, which depends on the
+broker:
+
+- **SQS** — redelivered when the visibility timeout expires.
+- **Azure Service Bus** — redelivered when the message lock expires.
+- **Artemis** — an unsettled AMQP 1.0 delivery is returned only when the link or connection
+  closes, so it stays unsettled until then.
+- **Kafka** — offsets are committed cumulatively per partition, so merely skipping the commit
+  would lose the record once a later one is committed. The transport therefore implements
+  the optional `Rewinder` protocol: it `seek`s the partition back to the failed record's
+  offset and pauses `_rewind_pause` (1 s by default, so an unavailable DLQ is not hammered)
+  before the record is polled again; the gate rejects it again and the dead-letter write
+  is retried. While the dead-letter write keeps failing (for example the `.dlq` topic is not
+  writable) the partition **stalls on that record** (head-of-line blocking, consumer lag
+  grows) and the worker waits the pause on every attempt, which also delays its other
+  partitions and queues. The commit does not move past the record as long as the seek
+  succeeds; if the seek itself fails, an error naming the topic, partition and offset is
+  logged and a later commit on that partition may skip the record, so recover it by hand from
+  that offset. If the partition was lost to a rebalance, the new owner resumes from the last
+  committed offset and the record is not lost.
+- **Pulsar** — acknowledgement is per message; the unacknowledged message is redelivered by
+  the broker.
+
+A warning naming the version (cut at 64 characters plus `...`) and queue is logged.
+
 ### SQS release and poison messages
 
 On a handler failure, unknown-URN `release` or shutdown release, the SQS

{babelqueue-1.14.0 → babelqueue-1.16.0}/README.md

@@ -124,6 +124,43 @@ app.run()                               # consume forever (Ctrl-C to stop)
   the message unchanged once `shutdown_timeout` expires. Delivery is
   **at-least-once** — keep handlers idempotent (see the idempotency helper).
 
+### Unsupported `schema_version` (SQS, Azure Service Bus, Kafka, Artemis, Pulsar)
+
+These transports read the binding's schema-version property (`bq-schema-version`; Artemis
+`bq_schema_version`) **before** decoding the body. A missing or blank value (empty or only
+ASCII whitespace) follows the normal path; any other value must be exactly `"1"` (compared
+untrimmed; Azure Service Bus and Artemis also accept the integer `1`). A message carrying
+anything else is not decoded: it reaches the runtime on the reserved route
+`babelqueue:unsupported-schema-version:<v>` (the version percent-escaped) and is **never
+retried** — it goes straight to the dead-letter queue (reason `unknown_urn`, the body kept
+verbatim) when `dead_letter` is enabled, and is dropped otherwise, whatever `max_attempts` is.
+It does not depend on a broker `RedrivePolicy`. If the dead-letter write fails the message is
+left unacknowledged (an error is logged), is never retried and never reaches a handler; the
+dead-letter write is attempted again when the broker brings it back, which depends on the
+broker:
+
+- **SQS** — redelivered when the visibility timeout expires.
+- **Azure Service Bus** — redelivered when the message lock expires.
+- **Artemis** — an unsettled AMQP 1.0 delivery is returned only when the link or connection
+  closes, so it stays unsettled until then.
+- **Kafka** — offsets are committed cumulatively per partition, so merely skipping the commit
+  would lose the record once a later one is committed. The transport therefore implements
+  the optional `Rewinder` protocol: it `seek`s the partition back to the failed record's
+  offset and pauses `_rewind_pause` (1 s by default, so an unavailable DLQ is not hammered)
+  before the record is polled again; the gate rejects it again and the dead-letter write
+  is retried. While the dead-letter write keeps failing (for example the `.dlq` topic is not
+  writable) the partition **stalls on that record** (head-of-line blocking, consumer lag
+  grows) and the worker waits the pause on every attempt, which also delays its other
+  partitions and queues. The commit does not move past the record as long as the seek
+  succeeds; if the seek itself fails, an error naming the topic, partition and offset is
+  logged and a later commit on that partition may skip the record, so recover it by hand from
+  that offset. If the partition was lost to a rebalance, the new owner resumes from the last
+  committed offset and the record is not lost.
+- **Pulsar** — acknowledgement is per message; the unacknowledged message is redelivered by
+  the broker.
+
+A warning naming the version (cut at 64 characters plus `...`) and queue is logged.
+
 ### SQS release and poison messages
 
 On a handler failure, unknown-URN `release` or shutdown release, the SQS

{babelqueue-1.14.0 → babelqueue-1.16.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.14.0"
+version = "1.16.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"
 license = "MIT"
 license-files = ["LICENSE"]
-authors = [{ name = "Muhammet Şafak", email = "info@muhammetsafak.com.tr" }]
+authors = [{ name = "Muhammet Şafak", email = "info@muhammetsafak.com" }]
 keywords = ["queue", "polyglot", "microservices", "json", "envelope", "messaging"]
 classifiers = [
     "Development Status :: 4 - Beta",

{babelqueue-1.14.0 → babelqueue-1.16.0}/src/babelqueue/__init__.py

@@ -29,9 +29,17 @@ from .outbox import (
 from .exceptions import BabelQueueError, DecryptError, UnknownUrnError
 from .replay import HEADER_REPLAY_BYPASS, bypass_external_effects, is_replay
 from .routing import UnknownUrnStrategy
-from .transport import HeaderPublisher, InMemoryTransport, ReceivedMessage, Redeliverer, Transport
+from .transport import (
+    HeaderPublisher,
+    InMemoryTransport,
+    ReceivedMessage,
+    Redeliverer,
+    Rewinder,
+    RoutedPublisher,
+    Transport,
+)
 
-__version__ = "1.14.0"
+__version__ = "1.16.0"
 
 __all__ = [
     "BabelQueue",
@@ -46,6 +54,8 @@ __all__ = [
     "ReceivedMessage",
     "HeaderPublisher",
     "Redeliverer",
+    "Rewinder",
+    "RoutedPublisher",
     "BabelQueueError",
     "UnknownUrnError",
     "DecryptError",

{babelqueue-1.14.0 → babelqueue-1.16.0}/src/babelqueue/app.py

@@ -43,8 +43,10 @@ from .transport import (
     HeaderPublisher,
     ReceivedMessage,
     Redeliverer,
+    Rewinder,
     Transport,
     make_transport,
+    publish_keeping_route,
 )
 
 Handler = Callable[..., None]
@@ -110,6 +112,7 @@ class BabelQueue:
         self.shutdown_timeout = float(shutdown_timeout)
         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
         self._phase = _IDLE
         self._last_phase = _IDLE
         self._signalled = False
@@ -278,6 +281,10 @@ class BabelQueue:
         ):
             envelope = EnvelopeCodec.decode(received.body)
             urn = str(envelope.get("job") or envelope.get("urn") or "")
+            if received.route_urn and envelope:
+                # Transport-supplied routing override; body untouched. Only for a body that
+                # decodes: an undecodable one (decode() yields {}) stays on the poison path.
+                urn = received.route_urn
             handler = self._handlers.get(urn) if urn else None
 
             try:
@@ -290,6 +297,20 @@ class BabelQueue:
                 self._phase = _SETTLING
             except Exception as exc:  # noqa: BLE001 - one bad message must not kill the loop
                 self._phase = _SETTLING
+                if received.route_urn.startswith(_UNSUPPORTED_SCHEMA_ROUTE_PREFIX):
+                    # A version-gated delivery never takes the generic retry path, even when its
+                    # dead-letter write fails: a retry re-publish may rebuild the version header
+                    # from the (valid) body and walk the message past the gate into a handler.
+                    # It is left unacked; the broker (or a rewind, for cumulative-offset brokers
+                    # such as Kafka) brings it back and the gate rejects it again.
+                    logger.error(
+                        "Dead-lettering a version-gated message on queue %r failed; it was NOT "
+                        "retried or acknowledged; it will come back and the dead-letter write will be retried.",
+                        received.queue,
+                        exc_info=exc,
+                    )
+                    self._rewind_unsettled(received)
+                    return
                 self._retry_or_dead_letter(received, envelope, exc)
             else:
                 # Outside the handler's try: a failed ack is not a handler failure, so it must
@@ -381,9 +402,16 @@ class BabelQueue:
         if isinstance(self.transport, Redeliverer):
             self.transport.redeliver(received, body, delay)
             return
-        self.transport.publish(received.queue, _without_forbidden_keys(body))
+        self._publish_for(received, received.queue, _without_forbidden_keys(body))
         self._ack_settled(received)
 
+    def _publish_for(self, received: ReceivedMessage, queue: str, body: str) -> None:
+        """Publish ``body`` to ``queue`` on behalf of ``received`` (a retry / release re-publish
+        or its dead-letter record). Keeps the routing URN the broker property carried on this
+        delivery when the transport can pin it (:class:`RoutedPublisher`), so a property/body
+        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)
+
     def _ack_settled(self, received: ReceivedMessage) -> None:
         """Acknowledge a message whose outcome is already final (handled, dead-lettered,
         re-published, dropped or deleted by the unknown-URN strategy).
@@ -405,6 +433,23 @@ class BabelQueue:
                 exc_info=True,
             )
 
+    def _rewind_unsettled(self, received: ReceivedMessage) -> None:
+        """Make a deliberately unsettled message come back (cumulative-offset brokers such as Kafka
+        would otherwise lose it when a later record on the partition is committed), after a short
+        pause so an unavailable DLQ is not hammered in a hot loop."""
+        if not isinstance(self.transport, Rewinder):
+            return
+        try:
+            self.transport.rewind(received)
+        except Exception:  # noqa: BLE001 - reported, never kills the loop
+            logger.error(
+                "Failed to rewind an unsettled version-gated message on queue %r.",
+                received.queue,
+                exc_info=True,
+            )
+            return
+        self._stop.wait(self._rewind_pause)
+
     def _release_unprocessed(self, received: ReceivedMessage) -> None:
         """Release a message whose handler never completed (shutdown): unchanged body, no
         backoff, and the runtime adds no ``attempts`` increment. A broker that counts
@@ -428,16 +473,35 @@ class BabelQueue:
         if strategy == UnknownUrnStrategy.DELETE:
             self._ack_settled(received)
             return
-        if strategy == UnknownUrnStrategy.RELEASE:
+        # A transport's version-gated delivery (unsupported ``bq-schema-version``) can never gain
+        # a handler and must not be retried: a retry re-publishes through paths that may rebuild
+        # the version header from the (valid) body, or never advance the attempt counter, so the
+        # gate would be bypassed or the message would loop. It goes straight to the DLQ (or is
+        # dropped when no DLQ is configured).
+        if received.route_urn.startswith(_UNSUPPORTED_SCHEMA_ROUTE_PREFIX):
+            self._settle_version_gated(received, envelope)
+            return
+        # An undecodable body or a body naming no URN can never gain a handler either, so
+        # releasing it unchanged would redeliver it forever. It takes the bounded FAIL path
+        # instead (retry up to max_attempts, then dead-letter or drop); only a genuinely unknown
+        # URN keeps the verbatim release.
+        if strategy == UnknownUrnStrategy.RELEASE and urn:
             self._release(received, received.body, self.unknown_urn_release_delay)
             return
         if strategy == UnknownUrnStrategy.DEAD_LETTER:
             self._dead_letter(received, dict(envelope), "unknown_urn", None)
             return
-        # FAIL — surfaced through the retry/dead-letter path (never kills the loop).
-        raise UnknownUrnError(
-            f"No handler mapped for URN [{urn or '(empty)'}]."
-        )
+        # FAIL (and RELEASE of a poison message) — surfaced through the retry/dead-letter path
+        # (never kills the loop).
+        raise UnknownUrnError(f"No handler mapped for URN [{urn or '(empty)'}].")
+
+    def _settle_version_gated(self, received: ReceivedMessage, envelope: Mapping[str, Any]) -> None:
+        """Dead-letter a version-gated delivery directly (no retry); drop it when no DLQ is set."""
+        if self.dead_letter_enabled or self.on_unknown_urn == UnknownUrnStrategy.DEAD_LETTER:
+            error = UnknownUrnError(f"No handler mapped for URN [{received.route_urn}].")
+            self._dead_letter(received, dict(envelope), "unknown_urn", error)
+            return
+        self._ack_settled(received)
 
     def _retry_or_dead_letter(
         self, received: ReceivedMessage, envelope: Dict[str, Any], exc: BaseException
@@ -474,10 +538,18 @@ class BabelQueue:
             exception=(type(exc).__name__ if exc is not None else None),
         )
         target = self.dead_letter_queue or (received.queue + self.dead_letter_suffix)
-        self.transport.publish(target, EnvelopeCodec.encode(annotated))
+        self._publish_for(received, target, EnvelopeCodec.encode(annotated))
         self._ack_settled(received)
 
 
+#: Reserved ``ReceivedMessage.route_urn`` prefix a transport uses to hand over a delivery it
+#: version-gated (broker-bindings §5.7 step 3, e.g. the pulsar transport's ``bq-schema-version``
+#: check). Not a ``urn:babel:`` URN, so no handler owns it. Must equal
+#: ``UNSUPPORTED_SCHEMA_ROUTE_PREFIX`` of the pulsar, sqs, asb, kafka and artemis transports (locked
+#: by a test); never reaches the wire. A delivery under it is dead-lettered directly, never retried.
+_UNSUPPORTED_SCHEMA_ROUTE_PREFIX = "babelqueue:unsupported-schema-version:"
+
+
 def _without_forbidden_keys(body: str) -> str:
     """``body`` unchanged, unless it carries a forbidden envelope key (message-envelope.md §10,
     e.g. from a legacy producer) — then it is re-encoded without it (warned by the codec), so a

{babelqueue-1.14.0 → babelqueue-1.16.0}/src/babelqueue/artemis_transport.py

@@ -32,10 +32,24 @@ transport directly and pass it via ``BabelQueue(transport=...)`` or
 
 from __future__ import annotations
 
+import logging
+import re
 from typing import Any, Dict, Optional
+from urllib.parse import quote
 
-from .codec import EnvelopeCodec, parse_envelope
-from .transport import ReceivedMessage, Transport
+from .codec import SCHEMA_VERSION, EnvelopeCodec, parse_envelope
+from .transport import ReceivedMessage, Transport, truncate_declared_version
+
+_logger = logging.getLogger("babelqueue.artemis")
+
+#: A blank ``bq_schema_version``: empty or only ASCII whitespace (space, \t, \n, \v, \f, \r) — the
+#: same set in every SDK (GR-5). Deliberately not ``str.strip()``, which also strips U+001C-U+001F,
+#: U+0085, U+00A0, U+2028, U+3000 ...
+_BLANK_ASCII_PATTERN = re.compile(r"[ \t\n\x0b\x0c\r]*")
+#: Prefix of the reserved ``route_urn`` a version-gated message is delivered under. It is not a
+#: ``urn:babel:`` URN, so no handler can legitimately own it; the runtime reports it as an
+#: unknown URN, which names the rejected ``bq_schema_version``.
+UNSUPPORTED_SCHEMA_ROUTE_PREFIX = "babelqueue:unsupported-schema-version:"
 
 JMS_TYPE_ANNOTATION = "x-opt-jms-type"
 APP_ID = "babelqueue"
@@ -187,6 +201,33 @@ class ArtemisTransport(Transport):
         except (TypeError, ValueError):  # pragma: no cover - defensive
             return 0
 
+    @staticmethod
+    def _unsupported_schema_version(properties: Any) -> Optional[str]:
+        """The §7.7 step-3 gate on the ``bq_schema_version`` application property (underscores —
+        ADR-0017): the offending raw value, or ``None``.
+
+        A missing property, a null value or a blank value (the empty string or only ASCII
+        whitespace — the same set in every SDK, GR-5, not ``str.strip()``) is not gated: the usual
+        decode path runs. A ``bytes`` value is decoded as UTF-8. A present value is accepted only
+        when it is exactly the core's supported ``SCHEMA_VERSION``: the string ``"1"`` or the
+        integer ``1`` (a ``bool`` is not an integer here, though it is one in Python); ``"2"``,
+        ``"x"``, ``"01"``, ``" 1"``, ``0``, ``2``, ``1.5``, ``True`` and any other type are
+        rejected."""
+        if not isinstance(properties, dict):
+            return None
+        raw = properties.get("bq_schema_version")
+        if raw is None:
+            return None
+        if isinstance(raw, (bytes, bytearray)):
+            raw = bytes(raw).decode("utf-8", "replace")
+        if isinstance(raw, str):
+            if _BLANK_ASCII_PATTERN.fullmatch(raw) is not None or raw == str(SCHEMA_VERSION):
+                return None
+            return raw
+        if isinstance(raw, int) and not isinstance(raw, bool) and raw == SCHEMA_VERSION:
+            return None
+        return str(raw)
+
     @staticmethod
     def _payload(message: Any) -> str:
         body = getattr(message, "body", None)
@@ -212,6 +253,26 @@ class ArtemisTransport(Transport):
             raise
         if message is None:  # pragma: no cover - defensive (real client raises instead)
             return None
+        # §7.7 step 3: gate on the ``bq_schema_version`` property BEFORE any body decode (the
+        # attempts reconcile below decodes the body). A rejected message keeps its raw body and the
+        # reserved route; the runtime then dead-letters it directly (no retry).
+        unsupported = truncate_declared_version(
+            self._unsupported_schema_version(getattr(message, "properties", None))
+        )
+        if unsupported is not None:
+            _logger.warning(
+                "Artemis message on %r carries unsupported bq_schema_version %r (supported: %s); "
+                "not decoding it.",
+                queue,
+                unsupported,
+                SCHEMA_VERSION,
+            )
+            return ReceivedMessage(
+                body=self._payload(message),
+                queue=queue,
+                handle=receiver,
+                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)
 

{babelqueue-1.14.0 → babelqueue-1.16.0}/src/babelqueue/asb_transport.py

@@ -23,11 +23,24 @@ transport directly and pass it via ``BabelQueue(transport=...)`` or
 
 from __future__ import annotations
 
+import logging
+import re
 from typing import Any, Dict, Optional
-from urllib.parse import urlsplit
+from urllib.parse import quote, urlsplit
 
-from .codec import EnvelopeCodec, parse_envelope
-from .transport import ReceivedMessage, Transport
+from .codec import SCHEMA_VERSION, EnvelopeCodec, parse_envelope
+from .transport import ReceivedMessage, Transport, truncate_declared_version
+
+_logger = logging.getLogger("babelqueue.asb")
+
+#: A blank ``bq-schema-version``: empty or only ASCII whitespace (space, \t, \n, \v, \f, \r) — the
+#: same set in every SDK (GR-5). Deliberately not ``str.strip()``, which also strips U+001C-U+001F,
+#: U+0085, U+00A0, U+2028, U+3000 ...
+_BLANK_ASCII_PATTERN = re.compile(r"[ \t\n\x0b\x0c\r]*")
+#: Prefix of the reserved ``route_urn`` a version-gated message is delivered under. It is not a
+#: ``urn:babel:`` URN, so no handler can legitimately own it; the runtime reports it as an
+#: unknown URN, which names the rejected ``bq-schema-version``.
+UNSUPPORTED_SCHEMA_ROUTE_PREFIX = "babelqueue:unsupported-schema-version:"
 
 
 class AsbTransport(Transport):
@@ -141,6 +154,42 @@ class AsbTransport(Transport):
         env["attempts"] = native
         return EnvelopeCodec.encode(env)
 
+    @staticmethod
+    def _unsupported_schema_version(properties: Any) -> Optional[str]:
+        """The §4.7 step-3 gate on the ``bq-schema-version`` application property: the offending
+        raw value as text, or ``None``.
+
+        The AMQP client may hand keys and values over as ``bytes``; both are decoded as UTF-8. A
+        missing property, or a blank string (the empty string or only ASCII whitespace — the same
+        set in every SDK, GR-5, not ``str.strip()``) is not gated: the usual decode path runs. A
+        present value is accepted only when it is exactly the core's supported ``SCHEMA_VERSION``:
+        the string ``"1"`` or the integer ``1`` (a ``bool`` is not an integer here, though it is
+        one in Python). ``"2"``, ``"x"``, ``"01"``, ``" 1"``, ``0``, ``2``, ``1.5``, ``True`` and
+        any other type are rejected."""
+        if not properties:
+            return None
+        raw: Any = None
+        try:
+            items = list(properties.items())
+        except (AttributeError, TypeError):
+            return None
+        for key, value in items:
+            name = key.decode("utf-8", "replace") if isinstance(key, (bytes, bytearray)) else key
+            if name == "bq-schema-version":
+                raw = value
+                break
+        if raw is None:
+            return None
+        if isinstance(raw, (bytes, bytearray)):
+            raw = bytes(raw).decode("utf-8", "replace")
+        if isinstance(raw, str):
+            if _BLANK_ASCII_PATTERN.fullmatch(raw) is not None or raw == str(SCHEMA_VERSION):
+                return None
+            return raw
+        if isinstance(raw, int) and not isinstance(raw, bool) and raw == SCHEMA_VERSION:
+            return None
+        return str(raw)
+
     # -- Transport ----------------------------------------------------------
 
     def publish(self, queue: str, body: str) -> None:
@@ -157,6 +206,27 @@ class AsbTransport(Transport):
         if not messages:
             return None
         message = messages[0]
+        # §4.7 step 3: gate on ``bq-schema-version`` BEFORE any body decode (the attempts reconcile
+        # below decodes the body). A rejected message keeps its raw body and the reserved route.
+        unsupported = truncate_declared_version(
+            self._unsupported_schema_version(
+            getattr(message, "application_properties", None)
+        )
+        )
+        if unsupported is not None:
+            _logger.warning(
+                "Azure Service Bus message on %r carries unsupported bq-schema-version %r "
+                "(supported: %s); not decoding it.",
+                queue,
+                unsupported,
+                SCHEMA_VERSION,
+            )
+            return ReceivedMessage(
+                body=str(message),
+                queue=queue,
+                handle=message,
+                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)