babelqueue 0.2.0__tar.gz → 0.4.0__tar.gz

{babelqueue-0.2.0 → babelqueue-0.4.0}/.github/workflows/ci.yml

@@ -45,6 +45,15 @@ jobs:
           --health-interval 5s
           --health-timeout 3s
           --health-retries 10
+      rabbitmq:
+        image: rabbitmq:3
+        ports:
+          - 5672:5672
+        options: >-
+          --health-cmd "rabbitmq-diagnostics -q ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 15
     steps:
       - uses: actions/checkout@v4
 
@@ -53,12 +62,13 @@ jobs:
         with:
           python-version: '3.12'
 
-      - name: Install (with redis extra)
+      - name: Install (with redis + amqp extras)
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[redis,dev]"
+          pip install -e ".[redis,amqp,dev]"
 
-      - name: Run tests (Redis transport included)
+      - name: Run tests (Redis + RabbitMQ transports included)
         env:
           BABELQUEUE_TEST_REDIS: redis://localhost:6379/0
+          BABELQUEUE_TEST_AMQP: amqp://guest:guest@localhost:5672/
         run: pytest

{babelqueue-0.2.0 → babelqueue-0.4.0}/CHANGELOG.md

@@ -9,6 +9,25 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-06-06
+
+### Added
+- `EnvelopeCodec.urn()` — resolve the URN (`job`, accepting `urn` as an alias).
+- `EnvelopeCodec.accepts()` — consumer-side envelope validation (rejects empty URN,
+  unsupported `meta.schema_version`, blank `trace_id`, non-object `data`).
+- Shared **cross-SDK conformance suite** under `tests/conformance/` (vendored from
+  the canonical `conformance/` set) plus a `test_conformance.py` runner.
+
+## [0.3.0] - 2026-06-06
+
+### Added
+- **RabbitMQ transport** (`PikaTransport`, `amqp://`): durable queue, persistent
+  delivery, `basic_get` + manual ack, and the contract AMQP properties (`type`=URN,
+  `correlation_id`=trace_id, `x-schema-version`/`x-source-lang`/`x-attempts`).
+  Optional `[amqp]` extra (lazy `pika` import) — the core stays zero-dep.
+
+## [0.2.0] - 2026-06-06
+
 ### Added
 - **Runtime** — `BabelQueue(broker_url=...)` app with a `@app.handler("urn:...")`
   decorator, `publish()`, and a `consume()` / `run()` loop. Routes by URN over the
@@ -16,8 +35,8 @@ The envelope wire format is versioned separately by `meta.schema_version`
   `on_unknown_urn` strategies (`fail`/`delete`/`release`/`dead_letter`).
 - **Transports** — a pluggable `Transport` abstraction with `InMemoryTransport`
   (`memory://`, for tests/local) and `RedisTransport` (`redis://`, reliable-queue
-  pattern via `BLMOVE` + a processing list). Redis client is an optional extra
-  (`pip install "babelqueue[redis]"`), imported lazily — the core stays zero-dep.
+  pattern via `BLMOVE` + a processing list). Redis client is an optional `[redis]`
+  extra, imported lazily — the core stays zero-dep.
 
 ## [0.1.0] - 2026-06-06
 
@@ -36,5 +55,8 @@ The envelope wire format is versioned separately by `meta.schema_version`
 - Pre-1.0: the public API may change before the `1.0.0` tag.
 - The core has **zero runtime dependencies** (standard library only); Python `>=3.9`.
 
-[Unreleased]: https://github.com/BabelQueue/babelqueue-python/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/BabelQueue/babelqueue-python/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/BabelQueue/babelqueue-python/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/BabelQueue/babelqueue-python/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/BabelQueue/babelqueue-python/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/BabelQueue/babelqueue-python/releases/tag/v0.1.0

{babelqueue-0.2.0 → babelqueue-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: babelqueue
-Version: 0.2.0
+Version: 0.4.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
@@ -114,17 +114,19 @@ dlq = dead_letter.annotate(envelope, "failed", "orders", attempts=3, error="boom
 
 ## Runtime — produce & consume
 
-For an end-to-end app, use `BabelQueue` with a broker. Redis support comes via an
-extra:
+For an end-to-end app, use `BabelQueue` with a broker. Broker clients come via
+extras:
 
 ```bash
-pip install "babelqueue[redis]"
+pip install "babelqueue[redis]"   # redis://
+pip install "babelqueue[amqp]"    # amqp:// (RabbitMQ)
 ```
 
 ```python
 from babelqueue import BabelQueue
 
 app = BabelQueue("redis://localhost:6379/0", queue="orders")
+# or: BabelQueue("amqp://guest:guest@localhost:5672/", queue="orders")
 
 @app.handler("urn:babel:orders:created")
 def on_order_created(data, meta):       # AI/ML, data processing, anything
@@ -144,16 +146,17 @@ app.run()                               # consume forever (Ctrl-C to stop)
 - **Retry & dead-letter:** failures are retried up to `max_attempts` (bumping the
   envelope's `attempts`); enable `dead_letter=True` to quarantine exhausted
   messages on `<queue>.dlq`. `on_unknown_urn` = `fail` | `delete` | `release` | `dead_letter`.
-- **Transports:** `redis://` (reliable-queue pattern) and `memory://` (in-process,
-  great for tests/local). Bring your own by passing `transport=...`.
+- **Transports:** `redis://` (reliable-queue pattern), `amqp://` (RabbitMQ via
+  `pika`, with the contract AMQP properties) and `memory://` (in-process, great for
+  tests/local). Bring your own by passing `transport=...`.
 
-> RabbitMQ (`pika`) and **Celery** / **Django** adapters are the next iterations.
+> **Celery** / **Django** adapters are the next iterations.
 
 ## What's here
 
 The codec/contracts/dead-letter (zero-dep core) **and** the `BabelQueue` runtime
-above (in-memory built in; Redis via the `[redis]` extra). For framework
-integration, the Celery and Django adapters are planned.
+above (in-memory built in; Redis via `[redis]`, RabbitMQ via `[amqp]`). For
+framework integration, the Celery and Django adapters are planned.
 
 ## Testing
 

{babelqueue-0.2.0 → babelqueue-0.4.0}/README.md

@@ -82,17 +82,19 @@ dlq = dead_letter.annotate(envelope, "failed", "orders", attempts=3, error="boom
 
 ## Runtime — produce & consume
 
-For an end-to-end app, use `BabelQueue` with a broker. Redis support comes via an
-extra:
+For an end-to-end app, use `BabelQueue` with a broker. Broker clients come via
+extras:
 
 ```bash
-pip install "babelqueue[redis]"
+pip install "babelqueue[redis]"   # redis://
+pip install "babelqueue[amqp]"    # amqp:// (RabbitMQ)
 ```
 
 ```python
 from babelqueue import BabelQueue
 
 app = BabelQueue("redis://localhost:6379/0", queue="orders")
+# or: BabelQueue("amqp://guest:guest@localhost:5672/", queue="orders")
 
 @app.handler("urn:babel:orders:created")
 def on_order_created(data, meta):       # AI/ML, data processing, anything
@@ -112,16 +114,17 @@ app.run()                               # consume forever (Ctrl-C to stop)
 - **Retry & dead-letter:** failures are retried up to `max_attempts` (bumping the
   envelope's `attempts`); enable `dead_letter=True` to quarantine exhausted
   messages on `<queue>.dlq`. `on_unknown_urn` = `fail` | `delete` | `release` | `dead_letter`.
-- **Transports:** `redis://` (reliable-queue pattern) and `memory://` (in-process,
-  great for tests/local). Bring your own by passing `transport=...`.
+- **Transports:** `redis://` (reliable-queue pattern), `amqp://` (RabbitMQ via
+  `pika`, with the contract AMQP properties) and `memory://` (in-process, great for
+  tests/local). Bring your own by passing `transport=...`.
 
-> RabbitMQ (`pika`) and **Celery** / **Django** adapters are the next iterations.
+> **Celery** / **Django** adapters are the next iterations.
 
 ## What's here
 
 The codec/contracts/dead-letter (zero-dep core) **and** the `BabelQueue` runtime
-above (in-memory built in; Redis via the `[redis]` extra). For framework
-integration, the Celery and Django adapters are planned.
+above (in-memory built in; Redis via `[redis]`, RabbitMQ via `[amqp]`). For
+framework integration, the Celery and Django adapters are planned.
 
 ## Testing
 

{babelqueue-0.2.0 → babelqueue-0.4.0}/pyproject.toml

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

@@ -19,7 +19,7 @@ from .exceptions import BabelQueueError, UnknownUrnError
 from .routing import UnknownUrnStrategy
 from .transport import InMemoryTransport, ReceivedMessage, Transport
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "BabelQueue",

{babelqueue-0.2.0 → babelqueue-0.4.0}/src/babelqueue/codec.py

@@ -94,3 +94,36 @@ class EnvelopeCodec:
         except (ValueError, TypeError):
             return {}
         return decoded if isinstance(decoded, dict) else {}
+
+    @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 "")
+
+    @staticmethod
+    def accepts(envelope: Mapping[str, Any]) -> bool:
+        """Whether a consumer should accept this envelope (consumer-side validation).
+
+        Rejects messages with no URN, an unsupported ``meta.schema_version``, a
+        missing/blank ``trace_id``, or a non-object ``data`` / non-integer
+        ``attempts``. (Accepts the ``urn`` alias, unlike the producer JSON Schema.)
+        """
+        if EnvelopeCodec.urn(envelope) == "":
+            return False
+
+        meta = envelope.get("meta")
+        if not isinstance(meta, dict) or meta.get("schema_version") != SCHEMA_VERSION:
+            return False
+
+        if not isinstance(envelope.get("data"), dict):
+            return False
+
+        attempts = envelope.get("attempts")
+        if not isinstance(attempts, int) or isinstance(attempts, bool):
+            return False
+
+        trace_id = envelope.get("trace_id")
+        if not isinstance(trace_id, str) or trace_id == "":
+            return False
+
+        return True

babelqueue-0.4.0/src/babelqueue/pika_transport.py

@@ -0,0 +1,109 @@
+"""RabbitMQ transport over AMQP 0-9-1. Requires the ``amqp`` extra:
+
+    pip install "babelqueue[amqp]"
+
+Producing publishes the envelope to a durable queue with persistent delivery and
+the AMQP properties that are part of the cross-language contract (``type`` = URN,
+``correlation_id`` = trace_id, ``message_id`` = meta.id, ``x-schema-version`` /
+``x-source-lang`` / ``x-attempts`` headers) — so a Go/PHP consumer can route on
+``properties.type`` without parsing the body. Consuming uses ``basic_get`` + manual
+ack (at-least-once), matching the PHP RabbitMQ driver.
+
+Connection is lazy; it (re)connects on first use and after a drop.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+from .transport import ReceivedMessage, Transport
+
+
+class PikaTransport(Transport):
+    def __init__(self, url: str) -> None:
+        try:
+            import pika
+        except ImportError as exc:  # pragma: no cover - import guard
+            raise ImportError(
+                "PikaTransport requires the 'pika' package. Install with "
+                'pip install "babelqueue[amqp]".'
+            ) from exc
+
+        self._pika = pika
+        self._url = url
+        self._connection: Any = None
+        self._channel: Any = None
+        self._declared: set[str] = set()
+
+    # -- connection / topology ---------------------------------------------
+
+    def _chan(self) -> Any:
+        if self._connection is None or self._connection.is_closed:
+            self._connection = self._pika.BlockingConnection(self._pika.URLParameters(self._url))
+            self._channel = None
+            self._declared.clear()
+        if self._channel is None or self._channel.is_closed:
+            self._channel = self._connection.channel()
+        return self._channel
+
+    def _declare(self, queue: str) -> None:
+        if queue not in self._declared:
+            self._chan().queue_declare(queue=queue, durable=True)
+            self._declared.add(queue)
+
+    def _properties(self, body: str) -> Any:
+        """AMQP properties derived from the envelope (part of the wire contract)."""
+        try:
+            envelope: Dict[str, Any] = json.loads(body)
+        except (ValueError, TypeError):
+            return self._pika.BasicProperties(content_type="application/json", delivery_mode=2)
+
+        meta = envelope.get("meta") or {}
+        headers = {
+            "x-schema-version": meta.get("schema_version"),
+            "x-source-lang": meta.get("lang"),
+            "x-attempts": envelope.get("attempts", 0),
+        }
+        return self._pika.BasicProperties(
+            content_type="application/json",
+            content_encoding="utf-8",
+            delivery_mode=2,  # persistent
+            message_id=meta.get("id"),
+            correlation_id=envelope.get("trace_id"),
+            type=envelope.get("job"),
+            app_id="babelqueue",
+            headers={k: v for k, v in headers.items() if v is not None},
+        )
+
+    # -- Transport ----------------------------------------------------------
+
+    def publish(self, queue: str, body: str) -> None:
+        self._declare(queue)
+        self._chan().basic_publish(
+            exchange="",
+            routing_key=queue,
+            body=body.encode("utf-8"),
+            properties=self._properties(body),
+        )
+
+    def pop(self, queue: str, timeout: float = 1.0) -> Optional[ReceivedMessage]:
+        self._declare(queue)
+        method, _props, body = self._chan().basic_get(queue=queue, auto_ack=False)
+        if method is None:
+            # Nothing ready — sleep (heartbeat-safe) so the caller doesn't busy-loop.
+            if timeout and timeout > 0:
+                self._connection.sleep(timeout)
+            return None
+        text = body.decode("utf-8") if isinstance(body, (bytes, bytearray)) else str(body)
+        return ReceivedMessage(body=text, queue=queue, handle=method.delivery_tag)
+
+    def ack(self, message: ReceivedMessage) -> None:
+        self._chan().basic_ack(delivery_tag=message.handle)
+
+    def close(self) -> None:  # pragma: no cover
+        try:
+            if self._connection is not None and self._connection.is_open:
+                self._connection.close()
+        except Exception:
+            pass

{babelqueue-0.2.0 → babelqueue-0.4.0}/src/babelqueue/transport.py

@@ -75,8 +75,12 @@ def make_transport(broker_url: str) -> Transport:
         from .redis_transport import RedisTransport
 
         return RedisTransport(broker_url)
+    if scheme in ("amqp", "amqps"):
+        from .pika_transport import PikaTransport
+
+        return PikaTransport(broker_url)
 
     raise BabelQueueError(
-        f"Unsupported broker scheme {scheme!r}. Use 'memory://' or 'redis://', "
-        "or pass your own Transport via BabelQueue(transport=...)."
+        f"Unsupported broker scheme {scheme!r}. Use 'memory://', 'redis://' or "
+        "'amqp://', or pass your own Transport via BabelQueue(transport=...)."
     )

babelqueue-0.4.0/tests/conformance/fixtures/invalid-missing-urn.json

@@ -0,0 +1,14 @@
+{
+  "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-0.4.0/tests/conformance/fixtures/invalid-unknown-schema-version.json

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

babelqueue-0.4.0/tests/conformance/fixtures/unicode-and-numbers.json

@@ -0,0 +1,20 @@
+{
+  "job": "urn:babel:catalog:item.indexed",
+  "trace_id": "3f7a1d2e-9b4c-4a8d-bc1e-0f5a6b7c8d90",
+  "data": {
+    "title": "Café — naïve ☕",
+    "qty": 7,
+    "price_cents": 1299,
+    "ratio": 0.5,
+    "active": true,
+    "note": null
+  },
+  "meta": {
+    "id": "b2c3d4e5-f607-4890-a1b2-c3d4e5f60718",
+    "queue": "catalog",
+    "lang": "python",
+    "schema_version": 1,
+    "created_at": 1749132727000
+  },
+  "attempts": 2
+}

babelqueue-0.4.0/tests/conformance/fixtures/urn-alias.json

@@ -0,0 +1,15 @@
+{
+  "urn": "urn:babel:orders:created",
+  "trace_id": "9c1e0b44-7a2d-4e6f-8a10-2b3c4d5e6f70",
+  "data": {
+    "order_id": 1042
+  },
+  "meta": {
+    "id": "a1b2c3d4-e5f6-4789-90ab-cdef01234567",
+    "queue": "orders",
+    "lang": "go",
+    "schema_version": 1,
+    "created_at": 1749132727000
+  },
+  "attempts": 0
+}

babelqueue-0.4.0/tests/conformance/manifest.json

@@ -0,0 +1,71 @@
+{
+  "schema_version": 1,
+  "description": "Cross-SDK conformance cases. Every BabelQueue SDK core must satisfy these against the canonical wire envelope. Per-message fields (meta.id, trace_id, meta.created_at) are intrinsically unique and are NOT asserted by value.",
+  "cases": [
+    {
+      "name": "order-created",
+      "file": "fixtures/order-created.json",
+      "valid": true,
+      "description": "A normal produced envelope.",
+      "expect": {
+        "urn": "urn:babel:orders:created",
+        "data": { "order_id": 1042 },
+        "attempts": 0,
+        "lang": "php",
+        "schema_version": 1
+      }
+    },
+    {
+      "name": "urn-alias",
+      "file": "fixtures/urn-alias.json",
+      "valid": true,
+      "description": "Consumers MUST accept 'urn' as an inbound alias for 'job'.",
+      "expect": {
+        "urn": "urn:babel:orders:created",
+        "data": { "order_id": 1042 },
+        "attempts": 0,
+        "lang": "go",
+        "schema_version": 1
+      }
+    },
+    {
+      "name": "dead-lettered",
+      "file": "fixtures/dead-lettered.json",
+      "valid": true,
+      "description": "A dead-lettered message: original preserved + additive dead_letter block.",
+      "expect": {
+        "urn": "urn:babel:orders:created",
+        "data": { "order_id": 1042 },
+        "attempts": 3,
+        "lang": "php",
+        "schema_version": 1,
+        "dead_letter": { "reason": "failed", "original_queue": "orders" }
+      }
+    },
+    {
+      "name": "unicode-and-numbers",
+      "file": "fixtures/unicode-and-numbers.json",
+      "valid": true,
+      "description": "UTF-8 strings, integers, an exact float, boolean and null round-trip identically.",
+      "expect": {
+        "urn": "urn:babel:catalog:item.indexed",
+        "data": { "title": "Café — naïve ☕", "qty": 7, "price_cents": 1299, "ratio": 0.5, "active": true, "note": null },
+        "attempts": 2,
+        "lang": "python",
+        "schema_version": 1
+      }
+    },
+    {
+      "name": "invalid-unknown-schema-version",
+      "file": "fixtures/invalid-unknown-schema-version.json",
+      "valid": false,
+      "reason": "meta.schema_version is not a version this SDK supports"
+    },
+    {
+      "name": "invalid-missing-urn",
+      "file": "fixtures/invalid-missing-urn.json",
+      "valid": false,
+      "reason": "no 'job' or 'urn' — the message has no identity"
+    }
+  ]
+}

babelqueue-0.4.0/tests/conformance/schema/message-envelope.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://babelqueue.com/contracts/message-envelope.schema.json",
+  "title": "BabelQueueMessageEnvelope",
+  "description": "The canonical, language-agnostic BabelQueue wire envelope (schema_version 1). This schema is authoritative alongside contracts/message-envelope.md.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["job", "trace_id", "data", "meta", "attempts"],
+  "properties": {
+    "job": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The message URN — language-agnostic identity. Canonical producer field name. Consumers also accept 'urn' as an inbound alias. Never a class name.",
+      "examples": ["urn:babel:orders:created", "urn:babel:orders:invoice.requested"]
+    },
+    "urn": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Inbound alias for 'job'. Accepted by consumers for interoperability; producers SHOULD emit 'job'."
+    },
+    "trace_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Cross-service correlation id. Generated by the first producer, preserved and forwarded unchanged by every SDK across every hop."
+    },
+    "data": {
+      "type": "object",
+      "description": "Pure, JSON-encodable business payload. No language-specific types. Numbers/time/binary per contracts/message-envelope.md section 6.",
+      "additionalProperties": true
+    },
+    "meta": {
+      "type": "object",
+      "description": "Producer-set, immutable descriptive metadata.",
+      "additionalProperties": true,
+      "required": ["id", "queue", "lang", "schema_version", "created_at"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Unique id for THIS message (distinct from trace_id)."
+        },
+        "queue": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Logical queue name (not the broker key)."
+        },
+        "lang": {
+          "type": "string",
+          "enum": ["php", "go", "python", "java", "dotnet", "node"],
+          "description": "Producer language tag."
+        },
+        "schema_version": {
+          "type": "integer",
+          "const": 1,
+          "description": "Envelope schema version. Consumers MUST reject versions they do not support."
+        },
+        "created_at": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Production time as Unix epoch MILLISECONDS, UTC."
+        }
+      }
+    },
+    "attempts": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Top-level transport retry counter, mutated by the broker/worker. Deliberately kept OUT of the immutable meta block."
+    },
+    "dead_letter": {
+      "type": "object",
+      "description": "Optional. Present ONLY on messages sitting on a dead-letter queue (ADR-0009). Additive, so it does not change schema_version. Normal consumers ignore it.",
+      "additionalProperties": true,
+      "required": ["reason", "failed_at", "original_queue", "attempts"],
+      "properties": {
+        "reason": {
+          "type": "string",
+          "enum": ["failed", "unknown_urn", "poison"],
+          "description": "Why the message was dead-lettered."
+        },
+        "error": {
+          "type": ["string", "null"],
+          "description": "Human-readable error message, if any."
+        },
+        "exception": {
+          "type": ["string", "null"],
+          "description": "Producer-language exception/type name, if any (informational, language-specific)."
+        },
+        "failed_at": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Dead-letter time as Unix epoch milliseconds, UTC."
+        },
+        "original_queue": {
+          "type": "string",
+          "description": "The queue the message was consumed from before dead-lettering."
+        },
+        "attempts": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Delivery attempts made before dead-lettering."
+        },
+        "lang": {
+          "type": "string",
+          "enum": ["php", "go", "python", "java", "dotnet", "node"],
+          "description": "Language of the SDK that dead-lettered the message."
+        }
+      }
+    }
+  }
+}

babelqueue-0.4.0/tests/fixtures/dead-lettered.json

@@ -0,0 +1,24 @@
+{
+  "job": "urn:babel:orders:created",
+  "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": 3,
+  "dead_letter": {
+    "reason": "failed",
+    "error": "Payment gateway timeout",
+    "exception": "App\\Exceptions\\GatewayTimeout",
+    "failed_at": 1749132730000,
+    "original_queue": "orders",
+    "attempts": 3,
+    "lang": "php"
+  }
+}

babelqueue-0.4.0/tests/fixtures/order-created.json

@@ -0,0 +1,15 @@
+{
+  "job": "urn:babel:orders:created",
+  "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-0.4.0/tests/test_conformance.py

@@ -0,0 +1,58 @@
+"""Runs the shared cross-SDK conformance suite (vendored under tests/conformance/).
+
+The same manifest + fixtures are run by every BabelQueue SDK; passing here proves
+this SDK reads/writes the canonical envelope identically to the others.
+"""
+
+from __future__ import annotations
+
+import json
+import unittest
+from pathlib import Path
+
+from babelqueue import EnvelopeCodec
+
+SUITE = Path(__file__).parent / "conformance"
+MANIFEST = json.loads((SUITE / "manifest.json").read_text(encoding="utf-8"))
+
+
+class ConformanceTest(unittest.TestCase):
+    def test_suite_is_present(self) -> None:
+        self.assertEqual(MANIFEST["schema_version"], 1)
+        self.assertGreaterEqual(len(MANIFEST["cases"]), 6)
+
+    def test_cases(self) -> None:
+        for case in MANIFEST["cases"]:
+            with self.subTest(case=case["name"]):
+                raw = (SUITE / case["file"]).read_text(encoding="utf-8")
+                env = EnvelopeCodec.decode(raw)
+                self.assertNotEqual(env, {}, "fixture must decode")
+
+                if not case["valid"]:
+                    self.assertFalse(
+                        EnvelopeCodec.accepts(env),
+                        f"{case['name']} must be rejected: {case.get('reason')}",
+                    )
+                    continue
+
+                expect = case["expect"]
+                self.assertTrue(EnvelopeCodec.accepts(env), f"{case['name']} must be accepted")
+                self.assertEqual(EnvelopeCodec.urn(env), expect["urn"])
+                self.assertEqual(env["attempts"], expect["attempts"])
+                self.assertEqual(env["meta"]["lang"], expect["lang"])
+                self.assertEqual(env["meta"]["schema_version"], expect["schema_version"])
+
+                if "data" in expect:
+                    self.assertEqual(env["data"], expect["data"])
+
+                if "dead_letter" in expect:
+                    for key, value in expect["dead_letter"].items():
+                        self.assertEqual(env["dead_letter"][key], value)
+
+                # Per-message fields must be present (not asserted by value).
+                self.assertIn("id", env["meta"])
+                self.assertTrue(env["trace_id"])
+
+
+if __name__ == "__main__":
+    unittest.main()

babelqueue-0.4.0/tests/test_pika_transport.py

@@ -0,0 +1,98 @@
+"""Integration tests for the RabbitMQ (pika) transport.
+
+Skipped unless a broker is reachable (the `pika` package installed and a broker at
+``BABELQUEUE_TEST_AMQP`` / localhost). The CI ``integration`` job runs these
+against a RabbitMQ service; locally they skip cleanly.
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+import uuid
+
+try:
+    import pika as _pika
+except ImportError:  # pragma: no cover
+    _pika = None
+
+from babelqueue import BabelQueue, EnvelopeCodec
+
+AMQP_URL = os.environ.get("BABELQUEUE_TEST_AMQP", "amqp://guest:guest@localhost:5672/")
+
+
+def _amqp_available() -> bool:
+    if _pika is None:
+        return False
+    try:
+        conn = _pika.BlockingConnection(_pika.URLParameters(AMQP_URL))
+        conn.close()
+        return True
+    except Exception:  # pragma: no cover - connection failure
+        return False
+
+
+@unittest.skipUnless(_amqp_available(), f"no reachable RabbitMQ at {AMQP_URL}")
+class PikaTransportTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.queue = f"bqtest-{uuid.uuid4().hex}"
+        self.conn = _pika.BlockingConnection(_pika.URLParameters(AMQP_URL))
+        self.ctl = self.conn.channel()
+
+    def tearDown(self) -> None:
+        for q in (self.queue, f"{self.queue}.dlq"):
+            try:
+                self.ctl.queue_delete(queue=q)
+            except Exception:
+                pass
+        self.conn.close()
+
+    def _depth(self, queue: str) -> int:
+        method = self.ctl.queue_declare(queue=queue, durable=True, passive=True)
+        return method.method.message_count
+
+    def test_publish_consume_round_trip_and_ack(self) -> None:
+        app = BabelQueue(AMQP_URL, queue=self.queue)
+        seen = {}
+
+        @app.handler("urn:babel:orders:created")
+        def handle(data, meta):  # noqa: ANN001
+            seen.update(data)
+
+        app.publish("urn:babel:orders:created", {"order_id": 42})
+        processed = app.consume(max_messages=1, timeout=3)
+
+        self.assertEqual(processed, 1)
+        self.assertEqual(seen, {"order_id": 42})
+        self.assertEqual(self._depth(self.queue), 0)  # acked
+
+    def test_publish_sets_contract_amqp_properties(self) -> None:
+        app = BabelQueue(AMQP_URL, queue=self.queue)
+        app.publish("urn:babel:orders:created", {"order_id": 1}, trace_id="trace-amqp")
+
+        method, props, body = self.ctl.basic_get(queue=self.queue, auto_ack=True)
+        self.assertIsNotNone(method)
+        self.assertEqual(props.type, "urn:babel:orders:created")     # route on properties.type
+        self.assertEqual(props.correlation_id, "trace-amqp")         # trace_id
+        self.assertEqual(props.content_type, "application/json")
+        self.assertEqual(props.delivery_mode, 2)                     # persistent
+        self.assertEqual(props.app_id, "babelqueue")
+
+    def test_failure_dead_letters(self) -> None:
+        app = BabelQueue(AMQP_URL, queue=self.queue, max_attempts=1, dead_letter=True)
+
+        @app.handler("urn:babel:orders:created")
+        def handle(data, meta):  # noqa: ANN001
+            raise RuntimeError("boom")
+
+        app.publish("urn:babel:orders:created", {"order_id": 1})
+        app.consume(max_messages=2, timeout=3)
+
+        self.assertEqual(self._depth(f"{self.queue}.dlq"), 1)
+        _m, _p, body = self.ctl.basic_get(queue=f"{self.queue}.dlq", auto_ack=True)
+        env = EnvelopeCodec.decode(body.decode("utf-8"))
+        self.assertEqual(env["dead_letter"]["reason"], "failed")
+
+
+if __name__ == "__main__":
+    unittest.main()