babelqueue 1.23.0__tar.gz → 1.25.0__tar.gz

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

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

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

@@ -14,7 +14,7 @@ jobs:
     # Recommended for PyPI Trusted Publishing — configure a "pypi" environment +
     # a trusted publisher on PyPI (repo BabelQueue/babelqueue-python, this workflow).
     environment: pypi
-    # redis_layout (conformance 1.7.0) drives the real Lua scripts: a real redis:7 is mandatory,
+    # redis_layout (conformance 1.7.0+) drives the real Lua scripts: a real redis:7 is mandatory,
     # exactly as in ci.yml's `conformance` job — without it the cases are reported as failures.
     services:
       redis:
@@ -28,7 +28,7 @@ jobs:
           --health-retries 10
     env:
       # The pinned conformance release (ADR-0032). Keep identical to ci.yml.
-      BQ_CONFORMANCE_VERSION: 1.7.0
+      BQ_CONFORMANCE_VERSION: 1.9.0
       BQ_FETCH_SH_SHA256: 8bb6ba567b288fb0ac71a70fd17041b2503df119e01998d76fdad372570bf849
     permissions:
       id-token: write   # PyPI Trusted Publishing (OIDC) — no API token needed

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

@@ -9,6 +9,158 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [1.25.0] - 2026-11-01
+
+### Changed (dashboard-breaking) — `babelqueue.otel` follows the OpenTelemetry messaging semantic conventions v1.44.0 (ADR-0038)
+- **Span names change with no overlap:** `publish <urn>` becomes `send <queue>` and
+  `process <urn>` becomes `process <queue>` (the bare `send` / `process` when there is no queue).
+  The URN is never in the span name now (it is unbounded); it is the `babelqueue.urn` attribute.
+  The producer's `messaging.destination.name` is the queue the message is published to (it was the
+  URN), so a producer span and its consumer span share one destination. **Saved queries and
+  dashboards that filter on the old span names or on the producer destination must be updated.**
+- **`messaging.system` is now the broker when you pass it.** `wrap_handler(..., system="kafka")` and
+  `publish(..., system="kafka")` (`redis`, `rabbitmq`, `aws_sqs`, `servicebus`, `pulsar`, `kafka`,
+  `activemq`; any other value is written as given). **Omitting `system` keeps `babelqueue`, which is
+  deprecated** (a one-time warning is logged); what an absent `system` means after the deprecation
+  window is not decided yet, so pass it now.
+- New span attributes: `messaging.operation.type` / `messaging.operation.name` (`send` or
+  `process`), `babelqueue.urn`, `babelqueue.schema_version`, `babelqueue.attempts` and, on a failure,
+  `error.type` (`module.QualName` of the exception, the bare name for builtins) with an explicit
+  `ERROR` status whose description is the exception message. `consumer_group="..."` on
+  `wrap_handler` writes `messaging.consumer.group.name`.
+- **Dual-emit for this MINOR only:** the deprecated `messaging.operation` (`publish` / `process`) and
+  `messaging.babelqueue.attempts` are still written next to their replacements. **The next MINOR
+  removes both.**
+- `babelqueue.otel.SEMCONV_VERSION` (`1.44.0`) and `SEMCONV_SCHEMA_URL` (`https://opentelemetry.io/schemas/1.44.0`)
+  are public; create the tracer and meter with the schema URL
+  (`trace.get_tracer("orders", schema_url=otel.SEMCONV_SCHEMA_URL)`).
+- A `trace_id` that is not a UUID is still preserved byte for byte and hashed for the OTel TraceID
+  (`trace_id_of` is unchanged); `wrap_handler` now logs a warning once per distinct value
+  (message-envelope.md 5.1, ADR-0038 section 7). Nothing is rejected or regenerated.
+
+### Added
+- **Standard metrics (ADR-0039), opt-in.** Pass `meter=` to `wrap_handler` and `publish` to record
+  `messaging.process.duration` (histogram, `s`, semconv bucket advice where the API supports it),
+  `messaging.client.consumed.messages`, `messaging.client.sent.messages` and `babelqueue.retries`
+  (counters, `{message}`; `retries` counts a delivery with `attempts > 0`). The attributes are
+  `messaging.system`, `messaging.operation.name`, `messaging.destination.name` (when known) and
+  `error.type` (on failure); never the URN, an id, the attempt count or a dead-letter reason. With no
+  `meter` nothing is recorded.
+- **`babelqueue.dlq.messages` and the dead-letter observer seam (ADR-0039 section 5).**
+  `BabelQueue(..., dead_letter_observer=callback)` calls `callback(DeadLetterEvent(queue,
+  dead_letter_queue, reason))` once per dead-letter the runtime carried out, after the DLQ write is
+  confirmed (`BabelQueue._write_dead_letter`, the one chokepoint for exhausted retries, an unknown
+  URN, a poison body and a version-gated raw body) or after an SDK-initiated native dead-letter. A
+  failed write, a native no-op (SQS) and a broker-side dead-letter are not reported; an exception
+  raised by the observer is logged and never changes how the message is settled.
+  `otel.dead_letter_observer(meter, system=...)` is the observer that counts the metric.
+  New exports: `DeadLetterEvent`, `DeadLetterObserver`, and the `NativeDeadLetterSettler` protocol.
+- **`NativeDeadLetterSettler`**: the optional native-settle variant
+  `settle_native_dead_letter(message, reason, description) -> bool` next to `NativeSettler`
+  (unchanged). When a transport implements it the runtime prefers it and reports a dead-letter only
+  on `True`; `AsbTransport` implements it, the SQS no-op does not.
+- **`BabelQueue.publish_envelope(urn, data, *, queue=None, trace_id=None, headers=None)`** returns a
+  `PublishResult(envelope, error)` pair instead of raising. After a transport failure it still
+  carries the envelope that was handed to the transport (so `otel.publish` can put `meta.id` and
+  `trace_id` on a failed span); after a `make` or `encode` failure `envelope` is `None`. `publish`
+  and `publish_with_headers` delegate to it and behave exactly as before (an empty `queue` still
+  resolves to the default queue). `otel.publish` falls back to a duck-typed `app.publish(...)` for
+  objects that do not have it.
+- Conformance **1.9.0** is vendored; the `span-shape`, `trace-id` and `metrics` sections (and the six
+  new `traceparent` cases) run and pass.
+- **W3C `traceparent` / `tracestate` on the Kafka, Pulsar, Artemis and Azure Service Bus
+  transports (ADR-0028; broker-bindings 4.3, 5.2, 6.3, 7.2).** Each transport now implements the
+  `HeaderPublisher` capability: `publish_with_headers(queue, body, headers)` carries the headers
+  out of band beside the `bq-*` / `bq_*` projection (Kafka record headers, Pulsar message
+  properties, Artemis AMQP 1.0 application-properties, Azure Service Bus application properties).
+  The projection wins a key collision, and the body is byte-identical to a plain `publish`.
+  `pop` surfaces every non-projection header on `ReceivedMessage.headers` (so
+  `babelqueue.otel.wrap_handler` links the consumer span to the producer's across these brokers);
+  the projection keys themselves are never leaked, and `bq-replay-bypass` (ADR-0027) passes
+  through. A Kafka retry parks the consumed record's `traceparent` / `tracestate` on the tier topic
+  (the re-inject consumer already keeps every header except `bq-delay` / `bq-original-topic`), so
+  a retried message stays in the original trace. Retry tier names, `retry_tiers_ms` and the
+  poison / DLQ shapes are unchanged. `babelqueue.headers.out_of_band_headers` is the shared helper.
+- **`RedrivePublisher` capability and `redrive(bypass=True)` on the header-capable transports.**
+  Kafka, Pulsar, Artemis and Azure Service Bus becoming `HeaderPublisher`s means
+  `redrive(..., bypass=True)` now really stamps the `bq-replay-bypass` marker on them
+  (`RedriveItem.bypassed` is `True`; it was `False` before, because the transports could not carry
+  headers), and the write goes through the transport's header-carrying path. So that this path
+  loses nothing the ordinary redrive write keeps, `Kafka` and `Pulsar` implement the new optional
+  `publish_redriven(queue, body, headers, route_urn, key)`: Kafka's is the broker-confirmed settle
+  write (a delivery failure raises `KafkaDeliveryError`, the DLQ record is restored and not
+  committed past) and carries the DLQ record key unchanged; Pulsar's pins `bq-job` to the
+  dead-lettered delivery's routing property. `redrive` uses it when the transport has it.
+- **`AsbTransport.settle_native_dead_letter(message, reason, description) -> bool`** (ADR-0039
+  section 5.1): the optional native-settle variant that reports what it did. It performs the same
+  settle as `settle_native` (which is unchanged) and returns `True` when the receiver's
+  `dead_letter_message` ran, `False` when it only abandoned the lock or had no handle.
+
+## [1.24.0] - 2026-10-26
+
+Implements conformance **1.8.0** (vendored from the `v1.8.0` release asset, verified with
+`fetch.sh --check`; `BQ_CONFORMANCE_VERSION` is now `1.8.0` in `ci.yml` and `release.yml`). The
+envelope stays at `schema_version: 1`; nothing here touches the wire (ADR-0037). The new
+`version_gate_pulsar`, `version_gate_artemis`, `version_gate_sqs` and `version_gate_asb` sections run
+and pass (17 cases each; Python has the `on_unknown_urn` option, so no row is skipped). A MINOR.
+
+### Changed (behaviour)
+- **With the DLQ off, SQS and Azure Service Bus no longer drop a version-gated message or retry a
+  poison body; they are left to the broker's native mechanism (ADR-0037 decision 1 rule 3 and
+  decision 2 "Go and Python"; broker-bindings 3.5, 4.5, 5.7; owner decision 2026-10-25).**
+  - *Version-gated message* (an unsupported `bq-schema-version`), `dead_letter` off and a strategy
+    other than `DELETE` or `DEAD_LETTER`: it used to be acknowledged and dropped. It is now **not**
+    acknowledged. SQS: no `DeleteMessage`; visibility expiry redelivers it (the gate rejects it
+    again) and the queue's `RedrivePolicy` moves it to the native DLQ after `maxReceiveCount`. Azure
+    Service Bus: an explicit native `DeadLetter` (reason `unsupported schema version`) into
+    `$DeadLetterQueue` instead of `Complete`.
+  - *Poison body* (invalid JSON or an identity-less object), `dead_letter` off and a strategy other
+    than `DELETE` or `DEAD_LETTER`: it used to take the bounded `FAIL` path (re-publish an empty
+    envelope up to `max_attempts`, then drop). On SQS and Azure Service Bus it is now settled
+    natively **on the first delivery** exactly as above (Azure Service Bus reason `poison`): no
+    re-publish, no retry, no ack, body unchanged, the event is logged. Every other transport
+    (Pulsar, Artemis, AMQP, Kafka, Redis, memory) keeps its behaviour; `DELETE` (ack and drop),
+    `dead_letter=True` and the `DEAD_LETTER` strategy (the raw record, then ack) are unchanged on
+    SQS and Azure Service Bus too.
+  - A deployment that relied on SQS/Azure Service Bus silently dropping these messages now needs a
+    `RedrivePolicy` (SQS) or accepts them in `$DeadLetterQueue` (Azure Service Bus), or sets
+    `dead_letter=True` / `on_unknown_urn=DELETE`.
+
+### Fixed
+- **SQS: the default dead-letter queue name is now `<queue>-dlq` (FIFO `<queue>-dlq.fifo`) (ADR-0037
+  decision 7).** The old default `<queue>.dlq` was never a valid Amazon SQS queue name (a name may hold only
+  alphanumerics, hyphens and underscores, plus one `.fifo` suffix), so a DLQ write by default could not find a
+  queue on real SQS. `dead_letter_suffix` now defaults to `None` ("not set"); unless `dead_letter_queue` is set
+  the runtime asks the transport's new optional `DeadLetterNamer` capability
+  (`dead_letter_queue_name(queue, suffix)`, exported from `babelqueue`), which `SqsTransport` implements. The
+  runtime also hands it an explicit `dead_letter_suffix`; on a FIFO queue the `.fifo` suffix always stays last,
+  an explicit suffix included: `orders.fifo` with `dead_letter_suffix="-x"` is `orders-x.fifo`, never
+  `orders.fifo-x` (an SQS FIFO name must end in `.fifo`; before, that explicit suffix produced the uncreatable
+  `orders.fifo-x`). An explicit queue name behaves as before; every other transport keeps `<queue>.dlq` (the
+  attribute `App.dead_letter_suffix` is `None` instead of `".dlq"` until set). Deployments
+  that relied on the SQS default must name the DLQ `<queue>-dlq`, or pass `dead_letter_suffix=".dlq"` /
+  `dead_letter_queue=` to keep the old name. An explicitly empty `dead_letter_suffix=""` now counts as "no suffix" on SQS (`-dlq`); before, it made the DLQ the source queue itself.
+
+### Added
+- **`babelqueue.transport.NativeSettler`**, an optional `Transport` capability
+  (`settle_native(message, reason, description)`). With the DLQ off the runtime calls it instead of
+  acknowledging a version-gated message (and, on the poison route, instead of the bounded retry) on
+  a transport that offers it; the decision follows the capability, never the transport's name.
+  `SqsTransport.settle_native` is a deliberate no-op on the wire; `AsbTransport.settle_native`
+  dead-letters natively (falling back to `abandon_message` for a receiver without
+  `dead_letter_message`). Transports without it are unchanged.
+- **`babelqueue.transport.Abandoner` and `AsbTransport.abandon`.** When the dead-letter write of a
+  *version-gated* message fails, Azure Service Bus now `Abandon`s the peek-lock (broker-bindings 4.5,
+  "A failed write `Abandon`s it") so the broker redelivers it at once, instead of leaving it locked until
+  the lock lapses (up to 5 minutes). Only that branch abandons (owner decision 2026-10-25): `AsbTransport`
+  is deliberately **not** a `Rewinder`, so a graceful-shutdown release and a failed retry re-publish keep
+  their previous handling (a copy is re-published and the original completed), and a failed dead-letter
+  write of a poison body is still left to its lock. Tests pin all three. The `version_gate_asb` runner
+  asserts the `Abandon` on its `unsettled` rows.
+- Conformance `version_gate_*` runners (`version_gate_pulsar` / `version_gate_artemis` through the
+  runtime, `version_gate_sqs` / `version_gate_asb` through the real transports) and their entries in
+  the results writer.
+
 ## [1.23.0] - 2026-10-25
 
 Implements ADR-0036 (post-R1 parity) decisions 2, 4, 5 and 6. A MINOR: every change is a

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: babelqueue
-Version: 1.23.0
+Version: 1.25.0
 Summary: Polyglot Queues, Simplified — the Python core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers.
 Project-URL: Homepage, https://babelqueue.com
 Project-URL: Source, https://github.com/BabelQueue/babelqueue-python
@@ -212,8 +212,13 @@ untrimmed; Azure Service Bus and Artemis also accept the integer `1`). A message
 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 (the incoming body, byte-identical,
-with no `dead_letter` block) 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
+with no `dead_letter` block) when `dead_letter` is enabled (or `on_unknown_urn=DEAD_LETTER`), and
+`on_unknown_urn=DELETE` drops it, whatever `max_attempts` is. With `dead_letter` off, **SQS and Azure
+Service Bus no longer drop it** (ADR-0037): it is left to the broker's native mechanism and logged
+(SQS: no `DeleteMessage`, so visibility expiry redelivers it — the gate rejects it again — and the
+queue's `RedrivePolicy` moves it to the native DLQ after `maxReceiveCount`; Azure Service Bus: an
+explicit native `DeadLetter` with reason `unsupported schema version` into `$DeadLetterQueue`
+instead of `Complete`). Kafka, Artemis and Pulsar still acknowledge and drop it. 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:
@@ -253,10 +258,17 @@ a warning. A **per-message delay** at publish time is
 standard queue; a larger value, or any per-message delay on a FIFO queue, raises
 `BabelQueueError` instead of being truncated or dropped).
 
+**Poison bodies.** A body that does not decode, or has no identity, is never retried by the SDK
+(ADR-0037): `dead_letter=True` writes the ADR-0035 record to the DLQ (`<queue>-dlq` on SQS, `<queue>.dlq` elsewhere) and then deletes it,
+`on_unknown_urn=DELETE` deletes it, and with the DLQ off it is **not deleted and not re-sent**: the
+transport's `settle_native` capability leaves it to SQS on the first delivery (visibility expiry,
+then the queue's `RedrivePolicy`; the event is logged). Azure Service Bus does the same with a native
+`DeadLetter` (reason `poison`). Every other transport keeps the bounded retry up to `max_attempts`.
+
 **Poison-loop risk:** a message that always fails is redelivered at once until
 `max_attempts` is reached. If the receive count is unavailable the SDK cannot
 advance attempts at all. **Configure a native `RedrivePolicy`**
-(`maxReceiveCount` ≥ `max_attempts`, pointing at `<queue>.dlq`) on every SQS
+(`maxReceiveCount` ≥ `max_attempts`, pointing at `<queue>-dlq`, the SQS default DLQ name: FIFO `<queue>-dlq.fifo`, because an SQS queue name cannot contain a dot; `dead_letter_queue` overrides it, and `dead_letter_suffix` replaces `-dlq`, placed before `.fifo` on a FIFO queue) on every SQS
 queue as the broker-side backstop, and set a non-zero `retry_backoff` if the
 handler's dependencies need time to recover.
 

{babelqueue-1.23.0 → babelqueue-1.25.0}/README.md

@@ -158,8 +158,13 @@ untrimmed; Azure Service Bus and Artemis also accept the integer `1`). A message
 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 (the incoming body, byte-identical,
-with no `dead_letter` block) 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
+with no `dead_letter` block) when `dead_letter` is enabled (or `on_unknown_urn=DEAD_LETTER`), and
+`on_unknown_urn=DELETE` drops it, whatever `max_attempts` is. With `dead_letter` off, **SQS and Azure
+Service Bus no longer drop it** (ADR-0037): it is left to the broker's native mechanism and logged
+(SQS: no `DeleteMessage`, so visibility expiry redelivers it — the gate rejects it again — and the
+queue's `RedrivePolicy` moves it to the native DLQ after `maxReceiveCount`; Azure Service Bus: an
+explicit native `DeadLetter` with reason `unsupported schema version` into `$DeadLetterQueue`
+instead of `Complete`). Kafka, Artemis and Pulsar still acknowledge and drop it. 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:
@@ -199,10 +204,17 @@ a warning. A **per-message delay** at publish time is
 standard queue; a larger value, or any per-message delay on a FIFO queue, raises
 `BabelQueueError` instead of being truncated or dropped).
 
+**Poison bodies.** A body that does not decode, or has no identity, is never retried by the SDK
+(ADR-0037): `dead_letter=True` writes the ADR-0035 record to the DLQ (`<queue>-dlq` on SQS, `<queue>.dlq` elsewhere) and then deletes it,
+`on_unknown_urn=DELETE` deletes it, and with the DLQ off it is **not deleted and not re-sent**: the
+transport's `settle_native` capability leaves it to SQS on the first delivery (visibility expiry,
+then the queue's `RedrivePolicy`; the event is logged). Azure Service Bus does the same with a native
+`DeadLetter` (reason `poison`). Every other transport keeps the bounded retry up to `max_attempts`.
+
 **Poison-loop risk:** a message that always fails is redelivered at once until
 `max_attempts` is reached. If the receive count is unavailable the SDK cannot
 advance attempts at all. **Configure a native `RedrivePolicy`**
-(`maxReceiveCount` ≥ `max_attempts`, pointing at `<queue>.dlq`) on every SQS
+(`maxReceiveCount` ≥ `max_attempts`, pointing at `<queue>-dlq`, the SQS default DLQ name: FIFO `<queue>-dlq.fifo`, because an SQS queue name cannot contain a dot; `dead_letter_queue` overrides it, and `dead_letter_suffix` replaces `-dlq`, placed before `.fifo` on a FIFO queue) on every SQS
 queue as the broker-side backstop, and set a non-zero `retry_backoff` if the
 handler's dependencies need time to recover.
 

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

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

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

@@ -15,6 +15,7 @@ from . import dead_letter, gdpr, headers, idempotency, outbox, redrive, replay
 from .app import BabelQueue
 from .codec import SCHEMA_VERSION, SOURCE_LANG, EnvelopeCodec
 from .contracts import HasTraceId, PolyglotMessage
+from .dead_letter import DeadLetterEvent, DeadLetterObserver, NativeDeadLetterSettler
 from .gdpr import Cipher, protect, unprotect
 from .headers import headers_from_context
 from .idempotency import IdempotencyStore, InMemoryStore
@@ -30,19 +31,23 @@ from .exceptions import BabelQueueError, DecryptError, UnknownUrnError
 from .replay import HEADER_REPLAY_BYPASS, bypass_external_effects, is_replay
 from .routing import UnknownUrnStrategy
 from .transport import (
+    Abandoner,
     BatchPopper,
+    DeadLetterNamer,
     DeadLetterWriter,
     HeaderPublisher,
     InMemoryTransport,
+    NativeSettler,
     ReceivedMessage,
     Redeliverer,
+    RedrivePublisher,
     Rewinder,
     RoutedPublisher,
     SettlePublisher,
     Transport,
 )
 
-__version__ = "1.23.0"
+__version__ = "1.25.0"
 
 __all__ = [
     "BabelQueue",
@@ -55,10 +60,17 @@ __all__ = [
     "Transport",
     "InMemoryTransport",
     "ReceivedMessage",
+    "Abandoner",
     "BatchPopper",
+    "DeadLetterNamer",
     "DeadLetterWriter",
     "HeaderPublisher",
+    "NativeSettler",
+    "NativeDeadLetterSettler",
+    "DeadLetterEvent",
+    "DeadLetterObserver",
     "Redeliverer",
+    "RedrivePublisher",
     "Rewinder",
     "RoutedPublisher",
     "SettlePublisher",