babelqueue 1.19.0__tar.gz → 1.20.0__tar.gz

{babelqueue-1.19.0 → babelqueue-1.20.0}/.github/workflows/ci.yml

@@ -166,7 +166,7 @@ jobs:
       - uses: actions/checkout@v7
       - name: Verify vendored conformance matches the canonical suite
         run: |
-          git clone --depth 1 --branch v1.2.0 https://github.com/BabelQueue/conformance.git "$RUNNER_TEMP/conformance"
+          git clone --depth 1 --branch v1.4.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.19.0 → babelqueue-1.20.0}/CHANGELOG.md

@@ -9,6 +9,41 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [1.20.0] - 2026-10-17
+
+Conformance suite 1.4.0, [ADR-0031](https://babelqueue.com). The envelope is unchanged
+(`schema_version: 1`); this is a MINOR with one deliberate behaviour change (encode rejects).
+
+### Added
+- `EnvelopeCodec.make(urn, data, *, queue, trace_id, meta=None)`: a producer `meta` write API. The entries
+  land in `meta` next to the core keys (recommended shape `meta.ext.<vendor>`). A collision with a core
+  meta key or a forbidden key raises the new `EnvelopeKeyError` (subclass of `BabelQueueError`, with a
+  `pointer` attribute). `_envelope_shape.CORE_META_KEYS` is the single copy of the core key list.
+- `decode` folds the `urn` alias into `job` (ADR-0031 (c)): a `job` that is missing, empty or only ASCII
+  whitespace (`" \t\n\v\f\r"`; a U+2003 `job` is NOT blank) falls back to `urn` silently; when both carry
+  a value, `job` wins and `urn` is dropped with a warning naming `/urn`. `accepts()` / `urn()` follow the
+  same rule. The decoded envelope never keeps a `urn` key.
+- Tests: the runner now implements the 1.4.0 fields (`expect_preserved` on `forbidden_keys`;
+  `expect_absent_after_reencode`, `apply_dead_letter`, `expect_dead_letter` on `roundtrip`, the latter via
+  `dead_letter.annotate`) plus the `extension_write` and `encode_reject` sections, with a runner
+  self-test proving violations are reported.
+
+### Changed
+- **Behaviour change: `EnvelopeCodec.encode` raises `EnvelopeKeyError`** for an envelope carrying a
+  forbidden key (message-envelope.md section 10) or a top-level `urn`, instead of dropping it with a
+  warning (policy K-15 (a)). Nothing is written. `decode` still warns and drops, so re-encoding a decoded
+  envelope is safe. Code that built an envelope from a raw legacy body and relied on encode to clean it
+  must decode it first (`EnvelopeCodec.encode(EnvelopeCodec.decode(raw))`).
+- `test_all_five_contract_keys_are_covered` is a subset check (the suite adds `/urn` cases).
+- Docs only: the note in the previous release that the Go reference's case-insensitive envelope-key read "is tightened separately" is now closed — Go core 1.14.0 reads envelope keys exactly (case-sensitive, last duplicate wins), so every SDK now decides poison on the same exact-case keys.
+
+### Fixed
+- Raw-body re-encode paths now decode before they encode, so the new `encode` rejection cannot strand a
+  legacy body: the runtime's raw-body RELEASE re-publish (`app.py`), and the SQS and Pulsar attempts
+  reconciliation (Kafka, Azure Service Bus and Artemis already decoded first). A body with a legacy
+  `timestamp` or only a `urn` alias is re-emitted normalised (forbidden key dropped and warned, `urn`
+  folded into `job`); unknown top-level and `meta` keys, including `meta.ext`, are preserved.
+
 ## [1.19.0] - 2026-10-12
 
 ### Changed

{babelqueue-1.19.0 → babelqueue-1.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: babelqueue
-Version: 1.19.0
+Version: 1.20.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
@@ -106,6 +106,29 @@ The envelope is identical to every other SDK's:
 }
 ```
 
+### Extension metadata, forbidden keys and the `urn` alias (1.20.0, ADR-0031)
+
+```python
+# Producer meta: extra keys next to the core meta keys (recommended shape: meta.ext.<vendor>).
+envelope = EnvelopeCodec.make(
+    "urn:babel:orders:created", {"order_id": 1042},
+    queue="orders", meta={"ext": {"acme": {"tier": "gold"}}},
+)
+```
+
+- `meta=` is keyword-only. A key that collides with a core meta key (`id`, `queue`, `lang`,
+  `schema_version`, `created_at`) or with a forbidden key (`max_retries`, `attempts`, `source`, `ts`)
+  raises `EnvelopeKeyError` (a `BabelQueueError`; its `pointer` names the key, e.g. `/meta/ts`).
+- Unknown top-level and `meta` keys of an inbound message survive a decode -> `attempts + 1` -> encode
+  hop (retry, redrive, dead-letter), so a vendor `meta.ext` block is never lost.
+- `EnvelopeCodec.encode` **rejects** an envelope that carries a forbidden key (top-level `timestamp`;
+  `meta.max_retries`, `meta.attempts`, `meta.source`, `meta.ts`) or the inbound-only top-level `urn`
+  alias: it raises `EnvelopeKeyError` instead of dropping the key with a warning. `decode` is unchanged
+  (it still warns and drops), so a decoded envelope can always be re-encoded.
+- `decode` folds `urn` into `job`: a `job` that is missing, empty or only ASCII whitespace (space, `\t`,
+  `\n`, `\v`, `\f`, `\r`) falls back to `urn`; when both carry a value, `job` wins and `urn` is dropped
+  with a warning naming `/urn`. The decoded envelope never keeps a `urn` key.
+
 ### Typed messages (optional)
 
 ```python

{babelqueue-1.19.0 → babelqueue-1.20.0}/README.md

@@ -52,6 +52,29 @@ The envelope is identical to every other SDK's:
 }
 ```
 
+### Extension metadata, forbidden keys and the `urn` alias (1.20.0, ADR-0031)
+
+```python
+# Producer meta: extra keys next to the core meta keys (recommended shape: meta.ext.<vendor>).
+envelope = EnvelopeCodec.make(
+    "urn:babel:orders:created", {"order_id": 1042},
+    queue="orders", meta={"ext": {"acme": {"tier": "gold"}}},
+)
+```
+
+- `meta=` is keyword-only. A key that collides with a core meta key (`id`, `queue`, `lang`,
+  `schema_version`, `created_at`) or with a forbidden key (`max_retries`, `attempts`, `source`, `ts`)
+  raises `EnvelopeKeyError` (a `BabelQueueError`; its `pointer` names the key, e.g. `/meta/ts`).
+- Unknown top-level and `meta` keys of an inbound message survive a decode -> `attempts + 1` -> encode
+  hop (retry, redrive, dead-letter), so a vendor `meta.ext` block is never lost.
+- `EnvelopeCodec.encode` **rejects** an envelope that carries a forbidden key (top-level `timestamp`;
+  `meta.max_retries`, `meta.attempts`, `meta.source`, `meta.ts`) or the inbound-only top-level `urn`
+  alias: it raises `EnvelopeKeyError` instead of dropping the key with a warning. `decode` is unchanged
+  (it still warns and drops), so a decoded envelope can always be re-encoded.
+- `decode` folds `urn` into `job`: a `job` that is missing, empty or only ASCII whitespace (space, `\t`,
+  `\n`, `\v`, `\f`, `\r`) falls back to `urn`; when both carry a value, `job` wins and `urn` is dropped
+  with a warning naming `/urn`. The decoded envelope never keeps a `urn` key.
+
 ### Typed messages (optional)
 
 ```python

{babelqueue-1.19.0 → babelqueue-1.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.19.0"
+version = "1.20.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.19.0 → babelqueue-1.20.0}/src/babelqueue/__init__.py

@@ -41,7 +41,7 @@ from .transport import (
     Transport,
 )
 
-__version__ = "1.19.0"
+__version__ = "1.20.0"
 
 __all__ = [
     "BabelQueue",

{babelqueue-1.19.0 → babelqueue-1.20.0}/src/babelqueue/_envelope_shape.py

@@ -51,6 +51,9 @@ _META = {
     "schema_version": _INTEGER,
     "created_at": _INTEGER,
 }
+#: The core ``meta`` keys of message-envelope.md section 4 (the single copy; the producer ``meta``
+#: write API of the codec rejects a collision with any of them, ADR-0031 (b)).
+CORE_META_KEYS = frozenset(_META)
 _DEAD_LETTER = {
     "reason": _STRING,
     "error": _STRING,

{babelqueue-1.19.0 → babelqueue-1.20.0}/src/babelqueue/app.py

@@ -458,8 +458,9 @@ class BabelQueue:
         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
+        """Release a message whose handler never completed (shutdown): unchanged body
+        (normalised only if it carries a forbidden key or a ``urn`` alias), no backoff, and the
+        runtime adds no ``attempts`` increment. A broker that counts
         deliveries still counts it: on SQS the release bumps ``ApproximateReceiveCount``, so the
         redelivered envelope reads one more attempt (and a ``RedrivePolicy`` sees it too)."""
         self._release(received, received.body, 0.0)
@@ -578,12 +579,15 @@ _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
+    e.g. from a legacy producer) or a ``urn`` alias — then it is re-encoded without it (warned by the codec), so a
     raw-body re-publish never re-emits a key the decode boundary reported as dropped."""
     parsed = parse_envelope(body)
-    if not parsed or not has_forbidden_keys(parsed):
+    # ``urn`` is not a §10 key but ``encode`` rejects it and ADR-0031 (a)/(c) forbid re-emitting it.
+    if not parsed or not (has_forbidden_keys(parsed) or "urn" in parsed):
         return body
-    return EnvelopeCodec.encode(parsed)
+    # ``decode`` (not the raw parse) so the dropped keys — and a top-level ``urn`` alias, folded
+    # into ``job`` — are gone before ``encode``, which rejects them (ADR-0031 (c)).
+    return EnvelopeCodec.encode(EnvelopeCodec.decode(body))
 
 
 def _handler_wants_envelope(fn: Handler) -> bool:

{babelqueue-1.19.0 → babelqueue-1.20.0}/src/babelqueue/codec.py

@@ -16,15 +16,17 @@ import time
 import uuid
 from typing import Any, Dict, List, Mapping, Optional, Tuple
 
-from .exceptions import BabelQueueError
+from ._envelope_shape import CORE_META_KEYS
+from .exceptions import BabelQueueError, EnvelopeKeyError
 
 SCHEMA_VERSION = 1
 SOURCE_LANG = "python"
 
 #: Non-canonical keys (message-envelope.md §10), as ``(container, key)`` pairs where the
 #: container is ``None`` for the top level or ``"meta"``. Policy K-15: decode WARNS and drops
-#: them (old producers keep working); encode NEVER emits them. Encode currently drops them with
-#: a warning; K-15 (a) / R1-E0 will turn that into a rejection (an error) in a future MINOR.
+#: them (old producers keep working); encode NEVER emits them and REJECTS an envelope that
+#: carries one (ADR-0031 (c)). The top-level ``urn`` alias is not in this table: it is an inbound
+#: alias that decode folds into ``job`` (see :meth:`EnvelopeCodec.decode`), but encode rejects it.
 FORBIDDEN_KEYS: Tuple[Tuple[Optional[str], str], ...] = (
     (None, "timestamp"),
     ("meta", "max_retries"),
@@ -33,6 +35,10 @@ FORBIDDEN_KEYS: Tuple[Tuple[Optional[str], str], ...] = (
     ("meta", "ts"),
 )
 
+#: The closed ASCII whitespace set that makes a ``job`` "blank" (cross-SDK parity, GR-5): never a
+#: bare ``str.strip()``, which also strips Unicode spaces such as U+2003.
+_ASCII_WHITESPACE = " \t\n\v\f\r"
+
 #: Logger every forbidden-key warning is reported through (one record per dropped key).
 logger = logging.getLogger("babelqueue.codec")
 
@@ -52,11 +58,7 @@ def strip_forbidden_keys(envelope: Dict[str, Any]) -> List[str]:
         del target[key]
         pointer = "/" + key if container is None else f"/{container}/{key}"
         dropped.append(pointer)
-        logger.warning(
-            "Dropped forbidden envelope key %s from the envelope "
-            "(non-canonical, message-envelope.md §10).",
-            pointer,
-        )
+        _warn_dropped(pointer)
     return dropped
 
 
@@ -76,10 +78,42 @@ def parse_envelope(raw: Any) -> Dict[str, Any]:
 
 
 def has_forbidden_keys(envelope: Mapping[str, Any]) -> bool:
-    """Whether ``envelope`` carries any of the non-canonical keys of message-envelope.md §10."""
+    """Whether ``envelope`` carries any of the non-canonical keys of message-envelope.md §10.
+
+    The top-level ``urn`` alias is NOT included (it is not a §10 key: decode folds it into ``job``),
+    although ``encode`` also rejects it — a caller deciding whether a raw body needs normalising
+    before re-emit must check ``"urn" in envelope`` as well.
+    """
     return _has_forbidden_keys(envelope)
 
 
+def _is_blank(value: Any) -> bool:
+    """Missing, ``None``, empty or only ASCII whitespace; a falsy non-string (``0``, ``false``,
+    ``[]``, ``{}``) is blank too, as in ``job or urn``. A truthy non-string is not blank."""
+    if isinstance(value, str):
+        return value.strip(_ASCII_WHITESPACE) == ""
+    return not value
+
+
+def _warn_dropped(pointer: str) -> None:
+    logger.warning(
+        "Dropped forbidden envelope key %s from the envelope "
+        "(non-canonical, message-envelope.md §10).",
+        pointer,
+    )
+
+
+def _first_encode_violation(envelope: Mapping[str, Any]) -> Optional[str]:
+    """RFC 6901 pointer of the first key encode refuses to write, or ``None``."""
+    for container, key in FORBIDDEN_KEYS:
+        target = envelope if container is None else envelope.get(container)
+        if isinstance(target, Mapping) and key in target:
+            return "/" + key if container is None else f"/{container}/{key}"
+    if "urn" in envelope:
+        return "/urn"
+    return None
+
+
 def _has_forbidden_keys(envelope: Mapping[str, Any]) -> bool:
     for container, key in FORBIDDEN_KEYS:
         target = envelope if container is None else envelope.get(container)
@@ -101,12 +135,18 @@ class EnvelopeCodec:
         *,
         queue: str = "default",
         trace_id: Optional[str] = None,
+        meta: Optional[Mapping[str, Any]] = None,
     ) -> Dict[str, Any]:
         """Build the canonical envelope for a ``(urn, data)`` pair.
 
         ``trace_id`` is reused when given (trace continuation), otherwise a fresh
         UUID is minted. ``attempts`` starts at 0 and is the top-level transport
         counter (kept out of the immutable ``meta`` block).
+
+        ``meta`` (ADR-0031 (b)) adds producer-supplied entries (e.g. ``{"ext": {"acme": 1}}``) to
+        the ``meta`` block next to the core keys. An entry whose key is a core ``meta`` key
+        (``id``, ``queue``, ``lang``, ``schema_version``, ``created_at``) or a forbidden ``meta``
+        key (message-envelope.md §10) raises :class:`~babelqueue.exceptions.EnvelopeKeyError`.
         """
         urn = (urn or "").strip()
         if not urn:
@@ -117,19 +157,36 @@ class EnvelopeCodec:
 
         trace_id = (trace_id or "").strip() or str(uuid.uuid4())
 
-        return {
+        extra: Dict[str, Any] = {}
+        if meta is not None:
+            if not isinstance(meta, Mapping):
+                raise BabelQueueError("The producer meta must be a mapping of string keys to values.")
+            forbidden_meta = {key for container, key in FORBIDDEN_KEYS if container == "meta"}
+            for key, value in meta.items():
+                if key in CORE_META_KEYS or key in forbidden_meta:
+                    raise EnvelopeKeyError(
+                        f"/meta/{key}",
+                        f"The producer meta key /meta/{key} is reserved or forbidden "
+                        "(core meta keys and message-envelope.md §10 keys cannot be set).",
+                    )
+                extra[key] = value
+
+        meta_block: Dict[str, Any] = {
+            "id": str(uuid.uuid4()),
+            "queue": queue,
+            "lang": SOURCE_LANG,
+            "schema_version": SCHEMA_VERSION,
+            "created_at": int(time.time() * 1000),
+        }
+        meta_block.update(extra)
+        envelope: Dict[str, Any] = {
             "job": urn,
             "trace_id": trace_id,
             "data": dict(data),
-            "meta": {
-                "id": str(uuid.uuid4()),
-                "queue": queue,
-                "lang": SOURCE_LANG,
-                "schema_version": SCHEMA_VERSION,
-                "created_at": int(time.time() * 1000),
-            },
+            "meta": meta_block,
             "attempts": 0,
         }
+        return envelope
 
     @staticmethod
     def from_message(message: Any, queue: str = "default") -> Dict[str, Any]:
@@ -152,20 +209,20 @@ class EnvelopeCodec:
     def encode(envelope: Mapping[str, Any]) -> str:
         """Encode the envelope as compact UTF-8 JSON (unescaped unicode/slashes).
 
-        Forbidden keys (message-envelope.md §10) are never emitted: if the mapping carries any,
-        they are dropped (with a warning) from a copy — the caller's mapping is not mutated.
-
-        Transitional: K-15 (a) asks encode to *reject* forbidden keys. Dropping is the interim
-        behaviour until R1-E0, when this call will raise instead — do not rely on encode to
-        clean an envelope; strip it yourself (:func:`strip_forbidden_keys`) if you build one
-        from a legacy source.
+        Forbidden keys (message-envelope.md §10) are never emitted: an envelope that carries one
+        (top-level ``timestamp``; ``meta.max_retries`` / ``meta.attempts`` / ``meta.source`` /
+        ``meta.ts``) or the inbound-only top-level ``urn`` alias raises
+        :class:`~babelqueue.exceptions.EnvelopeKeyError` (ADR-0031 (c)) and nothing is written.
+        Envelopes produced by :meth:`decode` are always safe to re-encode: decode already drops
+        those keys. Unknown, non-forbidden keys are kept as-is.
         """
-        if _has_forbidden_keys(envelope):
-            copy = dict(envelope)
-            if isinstance(copy.get("meta"), Mapping):
-                copy["meta"] = dict(copy["meta"])
-            strip_forbidden_keys(copy)
-            envelope = copy
+        pointer = _first_encode_violation(envelope)
+        if pointer is not None:
+            raise EnvelopeKeyError(
+                pointer,
+                f"Refusing to encode the forbidden envelope key {pointer} "
+                "(non-canonical, message-envelope.md §10).",
+            )
         return json.dumps(envelope, ensure_ascii=False, separators=(",", ":"))
 
     @staticmethod
@@ -175,15 +232,33 @@ class EnvelopeCodec:
         Unknown keys are kept as-is (forward compatibility). Forbidden keys
         (message-envelope.md §10) are dropped and reported as warnings on :data:`logger`
         (policy K-15: warn, never reject), so re-encoding never re-emits them.
+
+        The ``urn`` alias is folded into ``job`` (ADR-0031 (c)): when ``job`` is missing, empty or
+        only ASCII whitespace, the ``urn`` value becomes ``job`` (silently); when both carry a
+        value, ``job`` wins and ``urn`` is dropped with a warning naming ``/urn``. The decoded
+        envelope never keeps a ``urn`` key.
         """
         decoded = parse_envelope(raw)
         strip_forbidden_keys(decoded)
+        if "urn" in decoded:
+            if _is_blank(decoded.get("job")):
+                decoded["job"] = decoded.pop("urn")
+            else:
+                del decoded["urn"]
+                _warn_dropped("/urn")
         return decoded
 
     @staticmethod
     def urn(envelope: Mapping[str, Any]) -> str:
-        """The message URN: canonical ``job``, with ``urn`` accepted as an alias."""
-        return str(envelope.get("job") or envelope.get("urn") or "")
+        """The message URN: canonical ``job``, with ``urn`` accepted as an alias.
+
+        A blank ``job`` (missing, empty or only ASCII whitespace) falls back to ``urn``.
+        """
+        job = envelope.get("job")
+        if isinstance(job, str) and not _is_blank(job):
+            return job
+        alias = envelope.get("urn")
+        return alias if isinstance(alias, str) and not _is_blank(alias) else ""
 
     @staticmethod
     def accepts(envelope: Mapping[str, Any]) -> bool:

{babelqueue-1.19.0 → babelqueue-1.20.0}/src/babelqueue/exceptions.py

@@ -7,6 +7,21 @@ class BabelQueueError(Exception):
     """Base for every recoverable BabelQueue error (bad config, empty URN, ...)."""
 
 
+class EnvelopeKeyError(BabelQueueError):
+    """An envelope key the codec refuses to write (ADR-0031 (b), (c)).
+
+    Raised by :meth:`~babelqueue.codec.EnvelopeCodec.make` when the ``meta`` entries collide with a
+    core ``meta`` key (``id``, ``queue``, ``lang``, ``schema_version``, ``created_at``) or carry a
+    forbidden key, and by :meth:`~babelqueue.codec.EnvelopeCodec.encode` when the envelope holds a
+    forbidden key of message-envelope.md section 10 (including the top-level ``urn`` alias).
+    ``pointer`` is the RFC 6901 pointer of the first offending key (e.g. ``"/meta/ts"``).
+    """
+
+    def __init__(self, pointer: str, message: str) -> None:
+        super().__init__(message)
+        self.pointer = pointer
+
+
 class UnknownUrnError(BabelQueueError):
     """A consumed message carries a URN with no mapped handler (strategy "fail")."""
 

{babelqueue-1.19.0 → babelqueue-1.20.0}/src/babelqueue/pulsar_transport.py

@@ -241,7 +241,7 @@ class PulsarTransport(Transport):
 
         * 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
+          ``urn`` is never rewritten for routing, 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
@@ -254,8 +254,9 @@ class PulsarTransport(Transport):
           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
+          attempts are reconciled (as in the Java and .NET consumers). It receives the raw
+          parsed body, not the decoded envelope the handler gets, so a ``urn`` alias or a
+          forbidden key the decode would drop is still present. 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 {}
@@ -282,8 +283,12 @@ class PulsarTransport(Transport):
 
         out = body
         if has_int_attempts and current != attempts:
-            env["attempts"] = attempts
-            out = EnvelopeCodec.encode(env)
+            # Re-encode from the *decoded* body: ``encode`` rejects forbidden keys / a ``urn`` alias,
+            # which the raw parse above keeps (ADR-0031).
+            env["attempts"] = attempts  # the routing-mismatch hook below sees the reconciled value
+            reencoded = EnvelopeCodec.decode(body)
+            reencoded["attempts"] = attempts
+            out = EnvelopeCodec.encode(reencoded)
 
         if route_urn and route_urn != body_urn and on_routing_mismatch is not None:
             if EnvelopeCodec.accepts(env):

{babelqueue-1.19.0 → babelqueue-1.20.0}/src/babelqueue/sqs_transport.py

@@ -213,8 +213,11 @@ class SqsTransport(Transport):
         native = rc - 1
         if native <= int(env.get("attempts", 0)):
             return body
-        env["attempts"] = native
-        return EnvelopeCodec.encode(env)
+        # Re-encode from the *decoded* body: ``encode`` rejects forbidden keys / a ``urn`` alias,
+        # which the raw parse above keeps (ADR-0031).
+        reencoded = EnvelopeCodec.decode(body)
+        reencoded["attempts"] = native
+        return EnvelopeCodec.encode(reencoded)
 
     # -- Transport ----------------------------------------------------------
 

babelqueue-1.20.0/tests/conformance/CONFORMANCE_VERSION

@@ -0,0 +1 @@
+1.4.0

babelqueue-1.20.0/tests/conformance/fixtures/blank-ascii-job-urn-fallback.json

@@ -0,0 +1,16 @@
+{
+  "job": "  ",
+  "urn": "urn:acme:b",
+  "trace_id": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b",
+  "data": {
+    "order_id": 1042
+  },
+  "meta": {
+    "id": "f1e2d3c4-b5a6-4789-90ab-cdef01234567",
+    "queue": "orders",
+    "lang": "php",
+    "schema_version": 1,
+    "created_at": 1749132727000
+  },
+  "attempts": 0
+}

babelqueue-1.20.0/tests/conformance/fixtures/dead-letter-roundtrip.json

@@ -0,0 +1,23 @@
+{
+  "job": "urn:acme:a",
+  "trace_id": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b",
+  "data": {
+    "order_id": 1042
+  },
+  "meta": {
+    "id": "f1e2d3c4-b5a6-4789-90ab-cdef01234567",
+    "queue": "orders",
+    "lang": "php",
+    "schema_version": 1,
+    "created_at": 1749132727000,
+    "vendor_flag": true,
+    "ext": {
+      "acme": {
+        "tier": "gold",
+        "flags": [1, 2]
+      }
+    }
+  },
+  "extra_top": 1,
+  "attempts": 2
+}

babelqueue-1.20.0/tests/conformance/fixtures/forbidden-key-job-and-urn.json

@@ -0,0 +1,16 @@
+{
+  "job": "urn:acme:a",
+  "urn": "urn:acme:b",
+  "trace_id": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b",
+  "data": {
+    "order_id": 1042
+  },
+  "meta": {
+    "id": "f1e2d3c4-b5a6-4789-90ab-cdef01234567",
+    "queue": "orders",
+    "lang": "php",
+    "schema_version": 1,
+    "created_at": 1749132727000
+  },
+  "attempts": 0
+}

babelqueue-1.20.0/tests/conformance/fixtures/forbidden-key-job-nonascii-space-and-urn.json

@@ -0,0 +1,16 @@
+{
+  "job": " ",
+  "urn": "urn:acme:b",
+  "trace_id": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b",
+  "data": {
+    "order_id": 1042
+  },
+  "meta": {
+    "id": "f1e2d3c4-b5a6-4789-90ab-cdef01234567",
+    "queue": "orders",
+    "lang": "php",
+    "schema_version": 1,
+    "created_at": 1749132727000
+  },
+  "attempts": 0
+}

babelqueue-1.20.0/tests/conformance/fixtures/meta-ext-vendor-roundtrip.json

@@ -0,0 +1,27 @@
+{
+  "job": "urn:acme:a",
+  "trace_id": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b",
+  "data": {
+    "order_id": 1042
+  },
+  "meta": {
+    "id": "f1e2d3c4-b5a6-4789-90ab-cdef01234567",
+    "queue": "orders",
+    "lang": "php",
+    "schema_version": 1,
+    "created_at": 1749132727000,
+    "ext": {
+      "acme": {
+        "tier": "gold",
+        "flags": [1, 2],
+        "limits": {
+          "burst": 10
+        }
+      },
+      "globex": {
+        "region": "eu-west-1"
+      }
+    }
+  },
+  "attempts": 0
+}

babelqueue-1.20.0/tests/conformance/fixtures/urn-only-roundtrip.json

@@ -0,0 +1,15 @@
+{
+  "urn": "urn:acme:b",
+  "trace_id": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b",
+  "data": {
+    "order_id": 1042
+  },
+  "meta": {
+    "id": "f1e2d3c4-b5a6-4789-90ab-cdef01234567",
+    "queue": "orders",
+    "lang": "php",
+    "schema_version": 1,
+    "created_at": 1749132727000
+  },
+  "attempts": 0
+}