babelqueue 1.14.0__tar.gz → 1.15.0__tar.gz

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

@@ -9,6 +9,65 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [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.15.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: babelqueue
-Version: 1.14.0
+Version: 1.15.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

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

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.14.0"
+version = "1.15.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.15.0}/src/babelqueue/__init__.py

@@ -29,9 +29,16 @@ 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,
+    RoutedPublisher,
+    Transport,
+)
 
-__version__ = "1.14.0"
+__version__ = "1.15.0"
 
 __all__ = [
     "BabelQueue",
@@ -46,6 +53,7 @@ __all__ = [
     "ReceivedMessage",
     "HeaderPublisher",
     "Redeliverer",
+    "RoutedPublisher",
     "BabelQueueError",
     "UnknownUrnError",
     "DecryptError",

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

@@ -45,6 +45,7 @@ from .transport import (
     Redeliverer,
     Transport,
     make_transport,
+    publish_keeping_route,
 )
 
 Handler = Callable[..., None]
@@ -278,6 +279,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:
@@ -381,9 +386,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).
@@ -428,15 +440,22 @@ class BabelQueue:
         if strategy == UnknownUrnStrategy.DELETE:
             self._ack_settled(received)
             return
-        if strategy == UnknownUrnStrategy.RELEASE:
+        # A transport's version-gated delivery, an undecodable body or a body naming no URN can
+        # never gain a handler, 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.
+        gated = received.route_urn.startswith(_UNSUPPORTED_SCHEMA_ROUTE_PREFIX)
+        poison = gated or not urn
+        if strategy == UnknownUrnStrategy.RELEASE and not poison:
             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).
+        # FAIL (and RELEASE of a poison message) — surfaced through the retry/dead-letter path
+        # (never kills the loop). A gated delivery names its reserved route (the rejected version).
         raise UnknownUrnError(
-            f"No handler mapped for URN [{urn or '(empty)'}]."
+            f"No handler mapped for URN [{urn or (received.route_urn if gated else '') or '(empty)'}]."
         )
 
     def _retry_or_dead_letter(
@@ -474,10 +493,17 @@ 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
+#: ``pulsar_transport.UNSUPPORTED_SCHEMA_ROUTE_PREFIX`` (locked by a test); never reaches the wire.
+_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.15.0/src/babelqueue/pulsar_transport.py

@@ -0,0 +1,383 @@
+"""Apache Pulsar transport. Requires the ``pulsar`` extra:
+
+    pip install "babelqueue[pulsar]"
+
+Producing sends the canonical envelope as the message payload and projects the contract
+envelope fields onto native Pulsar message properties (string->string): ``bq-job`` = URN,
+``bq-trace-id`` = trace_id, ``bq-message-id`` = meta.id, plus ``bq-schema-version`` /
+``bq-source-lang`` / ``bq-attempts`` — so a Java/.NET/... peer can route on ``bq-job``
+without parsing the body. Consuming receives one message at a time
+(``receive`` -> process -> ``acknowledge``). Per §5.2 / §5.7 the ``bq-job`` property is the
+routing key (the body's URN is used only when ``bq-job`` is absent or blank) and the
+``bq-attempts`` property is the authoritative attempt count (the body's ``attempts`` is used
+only when the property is absent or not a plain non-negative ASCII-decimal integer that fits
+a 32-bit int). The result is then raised to the broker's native ``redelivery_count``
+(0-based): ``attempts = max(bq-attempts, redelivery_count)`` — no -1, because Pulsar's
+redelivery count is 0-based (0 on first delivery). The routing URN is handed to the app through
+``ReceivedMessage.route_urn`` — the body's ``job`` / ``urn`` is never rewritten, so retries and
+the DLQ keep the producer's original body. When ``bq-job`` and the body name different URNs
+the property wins and the optional ``on_routing_mismatch(property_urn, body_urn, envelope)``
+hook is called (for an accepted envelope, after attempts are reconciled). A message left un-acked is redelivered (at-least-once).
+
+Before any of that, a ``bq-schema-version`` property that is present but not the core's supported
+``SCHEMA_VERSION`` (``"2"``, ``"x"``, ``"01"``, ...) is version-gated (§5.7 step 3): the body is
+**not decoded** and the message is handed to the runtime under a reserved ``route_urn`` no
+handler owns, so it is quarantined through the existing unknown-URN retry / dead-letter path (the
+error names the rejected version, and a ``babelqueue.pulsar`` warning is logged with the version
+and queue, also for a body that is not valid JSON). A missing or blank property (empty or only
+ASCII whitespace: space, tab, LF, VT, FF, CR - nothing else counts as blank) decodes as usual.
+The reserved route is an in-process marker only: it carries the delivery's original ``bq-job``,
+and a retry / dead-letter re-publish writes that ``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.
+
+This implements §5 of the broker-bindings contract. The envelope is unchanged
+(``schema_version`` stays 1); Apache Pulsar is purely additive.
+
+URL form: ``pulsar://host:6650`` (or ``pulsar+ssl://``). The default subscription name is
+``babelqueue`` over a ``Shared`` subscription. For a custom client/subscription, build the
+transport directly and pass it via ``BabelQueue(transport=...)`` or
+``PulsarTransport(client=...)``.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from urllib.parse import quote, unquote
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from .codec import SCHEMA_VERSION, EnvelopeCodec, parse_envelope
+from .transport import ReceivedMessage, Transport
+
+#: ``bq-attempts`` is valid only as a run of ASCII digits (no sign, no whitespace) ...
+_ATTEMPTS_PATTERN = re.compile(r"[0-9]+")
+#: 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]*")
+#: ... that fits a signed 32-bit int, matching the Java and .NET consumers (GR-5).
+_MAX_ATTEMPTS = 2**31 - 1
+#: 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:"
+#: Separates the rejected version from the delivery's original ``bq-job`` in a gate route.
+_GATE_JOB_PARAM = "?bq-job="
+
+_logger = logging.getLogger("babelqueue.pulsar")
+
+
+def _gate_route(version: str, properties: Dict[str, Any]) -> str:
+    """The reserved route of a version-gated delivery: the prefix, the rejected version and, when
+    the delivery carried one, its original ``bq-job`` (both percent-escaped). The runtime hands
+    it back through :meth:`PulsarTransport.publish_routed` on every retry / dead-letter write."""
+    route = UNSUPPORTED_SCHEMA_ROUTE_PREFIX + quote(version, safe="")
+    job = properties.get("bq-job")
+    if job is not None:
+        route += _GATE_JOB_PARAM + quote(str(job), safe="")
+    return route
+
+
+def _parse_gate_route(route: str) -> Optional[Tuple[str, Optional[str]]]:
+    """Inverse of :func:`_gate_route`: ``(version, bq_job_or_None)``, or ``None`` for any other
+    route."""
+    if not route.startswith(UNSUPPORTED_SCHEMA_ROUTE_PREFIX):
+        return None
+    rest = route[len(UNSUPPORTED_SCHEMA_ROUTE_PREFIX):]
+    raw_version, sep, raw_job = rest.partition(_GATE_JOB_PARAM)
+    return unquote(raw_version), (unquote(raw_job) if sep else None)
+
+
+class PulsarTransport(Transport):
+    def __init__(
+        self,
+        url: str = "pulsar://localhost:6650",
+        *,
+        client: Any = None,
+        subscription: str = "babelqueue",
+        consumer_type: Any = None,
+        topic_prefix: str = "",
+        receive_timeout_millis: int = 1000,
+        on_routing_mismatch: Optional[Callable[[str, str, Dict[str, Any]], None]] = None,
+        **subscribe_options: Any,
+    ) -> None:
+        self._url = url or "pulsar://localhost:6650"
+        self._subscription = subscription
+        self._consumer_type = consumer_type
+        self._topic_prefix = topic_prefix
+        self._receive_timeout_millis = receive_timeout_millis
+        self._subscribe_options = subscribe_options
+        self._on_routing_mismatch = on_routing_mismatch
+        self._producers: Dict[str, Any] = {}
+        self._consumers: Dict[str, Any] = {}
+
+        if client is not None:
+            self._client = client
+            return
+        self._client = self._build_client()  # pragma: no cover - needs Pulsar / network
+
+    def _build_client(self) -> Any:  # pragma: no cover - needs Pulsar / network
+        try:
+            import pulsar
+        except ImportError as exc:
+            raise ImportError(
+                "PulsarTransport requires the 'pulsar-client' package. Install with "
+                'pip install "babelqueue[pulsar]".'
+            ) from exc
+        return pulsar.Client(self._url)
+
+    # -- helpers ------------------------------------------------------------
+
+    def _topic(self, queue: str) -> str:
+        return f"{self._topic_prefix}{queue}" if self._topic_prefix else queue
+
+    def _producer(self, queue: str) -> Any:
+        producer = self._producers.get(queue)
+        if producer is None:
+            producer = self._client.create_producer(self._topic(queue))
+            self._producers[queue] = producer
+        return producer
+
+    def _consumer(self, queue: str) -> Any:
+        consumer = self._consumers.get(queue)
+        if consumer is None:
+            consumer = self._client.subscribe(
+                self._topic(queue), self._subscription, **self._subscribe_kwargs()
+            )
+            self._consumers[queue] = consumer
+        return consumer
+
+    def _subscribe_kwargs(self) -> Dict[str, Any]:
+        kwargs = dict(self._subscribe_options)
+        consumer_type = self._consumer_type
+        if consumer_type is None:
+            consumer_type = self._default_shared_type()
+        if consumer_type is not None:
+            kwargs.setdefault("consumer_type", consumer_type)
+        return kwargs
+
+    @staticmethod
+    def _default_shared_type() -> Any:
+        try:
+            import pulsar
+        except ImportError:  # pragma: no cover - exercised only with pulsar absent
+            return None
+        return pulsar.ConsumerType.Shared  # pragma: no cover - needs Pulsar
+
+    @staticmethod
+    def _projection(body: str, route_urn: str = "") -> Dict[str, str]:
+        """Native Pulsar message properties (string->string) — a redundant, routable view of
+        the body: bq-job/bq-trace-id/bq-message-id + bq-schema-version/lang/attempts. §5.2.
+
+        A non-empty ``route_urn`` pins ``bq-job`` (a retry / release re-publish keeps the original
+        delivery's routing URN); blank derives it from the body.
+
+        A ``route_urn`` that is a version-gate route is never written: the original delivery's
+        ``bq-job`` (if it had one) and raw ``bq-schema-version`` are restored instead, so the
+        republished message is gated the same way when it is consumed again."""
+        gate = _parse_gate_route(route_urn)
+        env = parse_envelope(body)
+        if gate is not None:
+            props = PulsarTransport._projection(body) if env else {}
+            props["bq-schema-version"] = gate[0]
+            if gate[1] is not None:
+                props["bq-job"] = gate[1]
+            return props
+        if not env:
+            return {}
+        meta = env.get("meta") or {}
+
+        props: Dict[str, str] = {}
+        if env.get("job"):
+            props["bq-job"] = str(env["job"])
+        if env.get("trace_id"):
+            props["bq-trace-id"] = str(env["trace_id"])
+        if meta.get("id"):
+            props["bq-message-id"] = str(meta["id"])
+        if meta.get("schema_version") is not None:
+            props["bq-schema-version"] = str(meta["schema_version"])
+        if meta.get("lang"):
+            props["bq-source-lang"] = str(meta["lang"])
+        props["bq-attempts"] = str(int(env.get("attempts", 0) or 0))
+        if route_urn:
+            props["bq-job"] = route_urn
+        return props
+
+    @staticmethod
+    def _unsupported_schema_version(properties: Dict[str, Any]) -> Optional[str]:
+        """The §5.7 step-3 gate on ``bq-schema-version``: the offending raw value, or ``None``.
+
+        A missing or blank property is not gated (the usual decode path runs); blank means the
+        empty string or only ASCII whitespace (space, ``\\t``, ``\\n``, ``\\v``, ``\\f``, ``\\r``) — the
+        same set in every SDK (GR-5), not ``str.strip()``, which also strips U+001C-U+001F,
+        U+0085, U+00A0, U+2028, U+3000 ... A present property is accepted only when it is exactly
+        the core's supported ``SCHEMA_VERSION`` as a plain decimal string, so ``"2"``, ``"x"``,
+        ``"01"`` and ``" 1"`` are all rejected."""
+        raw = properties.get("bq-schema-version")
+        if raw is None or (isinstance(raw, str) and _BLANK_ASCII_PATTERN.fullmatch(raw) is not None):
+            return None
+        if isinstance(raw, str) and raw == str(SCHEMA_VERSION):
+            return None
+        return str(raw)
+
+    @staticmethod
+    def _parse_attempts(raw: Any) -> Optional[int]:
+        """The ``bq-attempts`` value as an int, or ``None`` when absent or invalid (§5.5)."""
+        if not isinstance(raw, str) or _ATTEMPTS_PATTERN.fullmatch(raw) is None:
+            return None
+        value = int(raw)
+        return value if value <= _MAX_ATTEMPTS else None
+
+    @staticmethod
+    def _reconcile(
+        body: str,
+        redelivery_count: Any,
+        properties: Optional[Dict[str, str]] = None,
+        on_routing_mismatch: Optional[Callable[[str, str, Dict[str, Any]], None]] = None,
+    ) -> Tuple[str, str]:
+        """Apply §5.2 / §5.7 to a received body; returns ``(body, route_urn)``.
+
+        * Routing: a non-blank ``bq-job`` property is the URN the app routes on. It is returned
+          as ``route_urn`` (set on :attr:`ReceivedMessage.route_urn`); the body's ``job`` /
+          ``urn`` is never rewritten, so the handler, retries and the dead-letter record keep the
+          producer's original body. A body with no URN gets no ``route_urn`` — it stays
+          non-conformant and is rejected whatever ``bq-job`` says.
+        * Attempts: a valid ``bq-attempts`` property replaces the body's value (the body's is
+          kept when it is absent or invalid), then the result is raised to
+          ``redelivery_count``. Pulsar's count is 0-based (0 on first delivery), so it maps
+          directly with no -1; the max never lowers a runtime-incremented counter (the runtime
+          retries by republishing with attempts+1, which resets the redelivery count to 0). The
+          value is written into the body only when the body already holds an integer
+          ``attempts`` and the value really changes, so a missing / non-integer ``attempts`` is
+          still rejected by ``EnvelopeCodec.accepts``.
+        * ``on_routing_mismatch(property_urn, body_urn, envelope)`` is called when the property
+          and the body name different URNs — only for an envelope the consumer accepts and after
+          attempts are reconciled (as in the Java and .NET consumers), so it sees what the
+          handler will get. The hook is optional, separate from any error handling, and any
+          exception it raises is swallowed — it never affects the message flow.
+        """
+        properties = properties or {}
+        env = parse_envelope(body)
+        if not env:
+            return body, ""
+
+        routed = str(properties.get("bq-job") or "").strip()
+        body_urn = EnvelopeCodec.urn(env)
+        route_urn = routed if routed and body_urn else ""
+
+        current = env.get("attempts")
+        has_int_attempts = isinstance(current, int) and not isinstance(current, bool)
+        attempts = current if has_int_attempts else 0
+        from_property = PulsarTransport._parse_attempts(properties.get("bq-attempts"))
+        if from_property is not None:
+            attempts = from_property
+        try:
+            rc = int(redelivery_count)
+        except (TypeError, ValueError):
+            rc = 0
+        if rc > attempts:
+            attempts = rc
+
+        out = body
+        if has_int_attempts and current != attempts:
+            env["attempts"] = attempts
+            out = EnvelopeCodec.encode(env)
+
+        if route_urn and route_urn != body_urn and on_routing_mismatch is not None:
+            if EnvelopeCodec.accepts(env):
+                try:
+                    on_routing_mismatch(route_urn, body_urn, dict(env))
+                except Exception:  # noqa: BLE001 - a diagnostic hook must never break consumption
+                    pass
+        return out, route_urn
+
+    @staticmethod
+    def _redelivery_count(message: Any) -> int:
+        getter = getattr(message, "redelivery_count", None)
+        value = getter() if callable(getter) else getter
+        if value is None:
+            return 0
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return 0
+
+    @staticmethod
+    def _properties(message: Any) -> Dict[str, str]:
+        getter = getattr(message, "properties", None)
+        value = getter() if callable(getter) else getter
+        return dict(value) if isinstance(value, dict) else {}
+
+    @staticmethod
+    def _payload(message: Any) -> str:
+        getter = getattr(message, "data", None)
+        data = getter() if callable(getter) else getter
+        if isinstance(data, bytes):
+            return data.decode("utf-8")
+        return str(data) if data is not None else ""
+
+    # -- Transport ----------------------------------------------------------
+
+    def publish(self, queue: str, body: str) -> None:
+        self.publish_routed(queue, body, "")
+
+    def publish_routed(self, queue: str, body: str, route_urn: str) -> None:
+        """:meth:`publish` with ``bq-job`` pinned to ``route_urn`` (:class:`RoutedPublisher`);
+        a blank ``route_urn`` derives it from the body."""
+        self._producer(queue).send(
+            body.encode("utf-8"), properties=self._projection(body, route_urn)
+        )
+
+    def pop(self, queue: str, timeout: float = 1.0) -> Optional[ReceivedMessage]:
+        wait = self._receive_timeout_millis
+        if timeout and timeout > 0:
+            wait = int(timeout * 1000)
+        consumer = self._consumer(queue)
+        try:
+            message = consumer.receive(timeout_millis=wait)
+        except Exception as exc:  # noqa: BLE001 - Pulsar raises pulsar.Timeout on no message
+            if type(exc).__name__ == "Timeout":
+                return None
+            raise
+        if message is None:  # pragma: no cover - defensive (real client raises instead)
+            return None
+        properties = self._properties(message)
+        rejected = self._unsupported_schema_version(properties)
+        if rejected is not None:
+            # Version gate (§5.7 step 3): quarantine before decoding. The body is handed over
+            # untouched; the reserved route keeps the runtime from dispatching it to a handler.
+            _logger.warning(
+                "Pulsar message on %r rejected by the bq-schema-version gate: unsupported "
+                "version %r (supported: %s); quarantined without decoding the body",
+                queue, rejected, SCHEMA_VERSION,
+            )
+            return ReceivedMessage(
+                body=self._payload(message),
+                queue=queue,
+                handle=message,
+                route_urn=_gate_route(rejected, properties),
+            )
+        body, route_urn = self._reconcile(
+            self._payload(message),
+            self._redelivery_count(message),
+            properties,
+            self._on_routing_mismatch,
+        )
+        return ReceivedMessage(body=body, queue=queue, handle=message, route_urn=route_urn)
+
+    def ack(self, message: ReceivedMessage) -> None:
+        if message.handle is None:
+            return
+        self._consumer(message.queue).acknowledge(message.handle)
+
+    def close(self) -> None:  # pragma: no cover - resource cleanup
+        for resource in (*self._producers.values(), *self._consumers.values()):
+            try:
+                resource.close()
+            except Exception:  # noqa: BLE001 - best-effort cleanup
+                pass
+        try:
+            self._client.close()
+        except Exception:  # noqa: BLE001 - best-effort cleanup
+            pass

{babelqueue-1.14.0 → babelqueue-1.15.0}/src/babelqueue/redrive.py

@@ -36,7 +36,7 @@ from typing import Any, Callable, Dict, List, Mapping, Optional, Tuple
 
 from .codec import EnvelopeCodec
 from .replay import HEADER_REPLAY_BYPASS
-from .transport import HeaderPublisher, ReceivedMessage, Transport
+from .transport import HeaderPublisher, ReceivedMessage, Transport, publish_keeping_route
 
 Envelope = Mapping[str, Any]
 Select = Callable[[Envelope], bool]
@@ -88,7 +88,7 @@ def redrive(
     result = RedriveResult()
     for message, envelope in batch:
         if envelope is None:
-            transport.publish(dlq, message.body)  # restore the poison body; never drop it
+            publish_keeping_route(transport, dlq, message.body, message.route_urn)  # restore the poison body; never drop it
             transport.ack(message)
             result.skipped += 1
             result.items.append(RedriveItem("", "", "", "", dlq, "", False))
@@ -109,7 +109,7 @@ def redrive(
         )
 
         if select is not None and not select(envelope):
-            transport.publish(dlq, message.body)  # not selected: restore unchanged
+            publish_keeping_route(transport, dlq, message.body, message.route_urn)  # not selected: restore unchanged
             transport.ack(message)
             result.skipped += 1
             result.items.append(item)
@@ -119,7 +119,7 @@ def redrive(
         item.to = target
 
         if dry_run:
-            transport.publish(dlq, message.body)  # report the plan; restore unchanged
+            publish_keeping_route(transport, dlq, message.body, message.route_urn)  # report the plan; restore unchanged
             transport.ack(message)
             result.skipped += 1
             result.items.append(item)
@@ -130,10 +130,10 @@ def redrive(
         reset["attempts"] = 0
         try:
             item.bypassed = _publish_redriven(
-                transport, target, EnvelopeCodec.encode(reset), bypass
+                transport, target, EnvelopeCodec.encode(reset), bypass, message.route_urn
             )
         except Exception:
-            transport.publish(dlq, message.body)  # restore on a publish failure, then surface
+            publish_keeping_route(transport, dlq, message.body, message.route_urn)  # restore on a publish failure, then surface
             transport.ack(message)
             raise
         transport.ack(message)
@@ -156,14 +156,18 @@ def _decoded(body: str) -> Optional[Dict[str, Any]]:
     return envelope
 
 
-def _publish_redriven(transport: Transport, queue: str, body: str, bypass: bool) -> bool:
+def _publish_redriven(
+    transport: Transport, queue: str, body: str, bypass: bool, route_urn: str = ""
+) -> bool:
     """Re-publish a reset message to ``queue``. When ``bypass`` is set and the transport is a
     :class:`~babelqueue.transport.HeaderPublisher`, stamp the ``bq-replay-bypass`` header and
-    return True; otherwise publish plainly and return False."""
+    return True; otherwise publish plainly and return False. Either way a non-empty ``route_urn``
+    (the dead-lettered message's routing property) is carried back through
+    :class:`~babelqueue.transport.RoutedPublisher` when the transport implements it."""
     if bypass and isinstance(transport, HeaderPublisher):
         transport.publish_with_headers(queue, body, {HEADER_REPLAY_BYPASS: "1"})
         return True
-    transport.publish(queue, body)
+    publish_keeping_route(transport, queue, body, route_urn)
     return False