babelqueue 1.13.0__tar.gz → 1.15.0__tar.gz

babelqueue-1.15.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

{babelqueue-1.13.0 → babelqueue-1.15.0}/.github/workflows/ci.yml

@@ -118,7 +118,8 @@ jobs:
       - uses: actions/checkout@v5
       - name: Verify vendored conformance matches the canonical suite
         run: |
-          git clone --depth 1 https://github.com/BabelQueue/conformance.git "$RUNNER_TEMP/conformance"
+          git clone --depth 1 --branch v1.0.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"
           diff -ru "$RUNNER_TEMP/conformance/schema"        "tests/conformance/schema"

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

@@ -9,6 +9,114 @@ 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
+- **Graceful shutdown** of `BabelQueue.consume()`: on SIGTERM/SIGINT the loop sets a stop flag,
+  takes no new message, lets the in-flight handler finish (or releases the message unchanged once
+  the new `shutdown_timeout` — default 30 s — expires), restores the previous signal handlers and
+  closes the transport. Handlers are installed only on the main thread (`handle_signals=False`
+  opts out); a second signal forces an immediate exit with the message released. A plain
+  `KeyboardInterrupt` keeps its previous behaviour. New `BabelQueue.stop()` ends the loop from any
+  thread after the in-flight message.
+- `Redeliverer` protocol (`redeliver(message, body, delay)`) — a transport's native
+  release; the runtime uses it for retries, unknown-URN `RELEASE` and shutdown releases, and
+  falls back to publish + ack otherwise. New `retry_backoff` / `unknown_urn_release_delay`
+  settings feed its delay.
+- Conformance runners for the `roundtrip`, `data_shape`, `forbidden_keys` and
+  `payload_schema_unicode` sections (none skipped).
+- `.github/dependabot.yml` (pip + GitHub Actions, weekly).
+
+### Changed
+- **SQS release** (broker-bindings §3.5): retries, unknown-URN `RELEASE` and shutdown releases
+  **always** call `ChangeMessageVisibility` instead of re-sending, so the broker's
+  `ApproximateReceiveCount` carries the attempt count. There is no send + delete fallback. The
+  default delay for `retry_backoff` and `unknown_urn_release_delay` is **0 s** (immediate
+  redelivery); a delay outside 0..43200 s (including `inf`/`nan`) is clamped with a warning on the
+  `babelqueue.sqs` logger. A message without a receipt handle is not released (warning); one
+  without a receive count is released but its attempts cannot advance (warning).
+  **Poison-loop risk:** a message that always fails is redelivered immediately until
+  `max_attempts` — configure a native SQS `RedrivePolicy` (`maxReceiveCount` ≥ `max_attempts`) as
+  the backstop and a non-zero `retry_backoff` where needed. A shutdown release also counts as a
+  receive on SQS, so keep `shutdown_timeout` above the longest handler time.
+- Delivery semantics are documented as **at-least-once**: a handler that finishes right as the
+  shutdown deadline fires may be released and run again.
+- The SQS, Kafka, Pulsar, Azure Service Bus and Artemis transports' header/property projections
+  read the envelope without logging a false forbidden-key drop (the body is sent unchanged).
+
+### Fixed
+- The five forbidden envelope keys (`timestamp`, `meta.max_retries`, `meta.attempts`,
+  `meta.source`, `meta.ts` — message-envelope §10) are dropped on decode with a warning on the
+  `babelqueue.codec` logger, and never written on encode. **Transitional:** encode currently drops
+  them with a warning; a future MINOR (K-15 / R1-E0) will reject them instead. A raw-body release
+  republish now strips them too (a clean body is re-sent byte for byte); DLQ redrive still restores
+  the original bytes unchanged.
+- `BabelQueue.stop()` called before `consume()` starts is now honoured instead of being cleared.
+- A failed acknowledgement of an already-processed message (e.g. SQS `DeleteMessage` after a
+  successful handler, an unknown-URN `DELETE`, or a dead-letter publish) is no longer treated as a
+  handler failure: the message is **not** released or retried; the failure is logged at `ERROR`
+  on the new `babelqueue.app` logger and the broker redelivers it on its own (SQS: after the
+  visibility timeout). The consume loop keeps running.
+
 ## [1.13.0] - 2026-06-21
 
 ### Added

{babelqueue-1.13.0 → babelqueue-1.15.0}/PKG-INFO

@@ -1,12 +1,12 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: babelqueue
-Version: 1.13.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
@@ -35,7 +35,7 @@ Provides-Extra: dev
 Requires-Dist: mypy>=1.8; extra == 'dev'
 Requires-Dist: pytest-cov>=4; extra == 'dev'
 Requires-Dist: pytest>=7; extra == 'dev'
-Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: ruff<0.16,>=0.5; extra == 'dev'
 Provides-Extra: django
 Requires-Dist: django>=4.2; extra == 'django'
 Provides-Extra: gdpr
@@ -174,6 +174,27 @@ app.run()                               # consume forever (Ctrl-C to stop)
   and `memory://` (in-process, great for tests/local). Bring your own by passing
   `transport=...`.
 
+- **Graceful shutdown:** SIGTERM/SIGINT finish the in-flight handler, or release
+  the message unchanged once `shutdown_timeout` expires. Delivery is
+  **at-least-once** — keep handlers idempotent (see the idempotency helper).
+
+### SQS release and poison messages
+
+On a handler failure, unknown-URN `release` or shutdown release, the SQS
+transport **always** releases with `ChangeMessageVisibility` (broker-bindings
+§3.5) — it never re-sends a copy. The broker's `ApproximateReceiveCount` is the
+attempt counter, so a shutdown release also consumes an attempt. The default
+delay is **0 s** (`retry_backoff` / `unknown_urn_release_delay`), i.e. the
+message is visible again immediately; delays outside 0..43200 s are clamped with
+a warning.
+
+**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
+queue as the broker-side backstop, and set a non-zero `retry_backoff` if the
+handler's dependencies need time to recover.
+
 ### Sharing a Redis queue with Laravel
 
 By default the Redis transport owns its queue end-to-end (`RPUSH` to produce;

{babelqueue-1.13.0 → babelqueue-1.15.0}/README.md

@@ -120,6 +120,27 @@ app.run()                               # consume forever (Ctrl-C to stop)
   and `memory://` (in-process, great for tests/local). Bring your own by passing
   `transport=...`.
 
+- **Graceful shutdown:** SIGTERM/SIGINT finish the in-flight handler, or release
+  the message unchanged once `shutdown_timeout` expires. Delivery is
+  **at-least-once** — keep handlers idempotent (see the idempotency helper).
+
+### SQS release and poison messages
+
+On a handler failure, unknown-URN `release` or shutdown release, the SQS
+transport **always** releases with `ChangeMessageVisibility` (broker-bindings
+§3.5) — it never re-sends a copy. The broker's `ApproximateReceiveCount` is the
+attempt counter, so a shutdown release also consumes an attempt. The default
+delay is **0 s** (`retry_backoff` / `unknown_urn_release_delay`), i.e. the
+message is visible again immediately; delays outside 0..43200 s are clamped with
+a warning.
+
+**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
+queue as the broker-side backstop, and set a non-zero `retry_backoff` if the
+handler's dependencies need time to recover.
+
 ### Sharing a Redis queue with Laravel
 
 By default the Redis transport owns its queue end-to-end (`RPUSH` to produce;

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

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.13.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",
@@ -42,7 +42,7 @@ otel = ["opentelemetry-api>=1.20"]
 gdpr = ["cryptography>=42"]
 celery = ["celery>=5"]
 django = ["django>=4.2"]
-dev = ["pytest>=7", "pytest-cov>=4", "mypy>=1.8", "ruff>=0.5"]
+dev = ["pytest>=7", "pytest-cov>=4", "mypy>=1.8", "ruff>=0.5,<0.16"]
 
 [project.urls]
 Homepage = "https://babelqueue.com"

{babelqueue-1.13.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, Transport
+from .transport import (
+    HeaderPublisher,
+    InMemoryTransport,
+    ReceivedMessage,
+    Redeliverer,
+    RoutedPublisher,
+    Transport,
+)
 
-__version__ = "1.13.0"
+__version__ = "1.15.0"
 
 __all__ = [
     "BabelQueue",
@@ -45,6 +52,8 @@ __all__ = [
     "InMemoryTransport",
     "ReceivedMessage",
     "HeaderPublisher",
+    "Redeliverer",
+    "RoutedPublisher",
     "BabelQueueError",
     "UnknownUrnError",
     "DecryptError",