babelqueue 1.0.0__tar.gz → 1.1.0__tar.gz

babelqueue-1.1.0/.github/FUNDING.yml

@@ -0,0 +1,2 @@
+# Shows a "Sponsor" button on this repository.
+github: muhammetsafak

{babelqueue-1.0.0 → babelqueue-1.1.0}/.github/workflows/ci.yml

@@ -44,14 +44,14 @@ jobs:
       - name: Install (dev + all adapters for type context)
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,celery,django,redis,amqp]"
+          pip install -e ".[dev,celery,django,redis,amqp,sqs]"
       - name: Ruff
         run: ruff check src tests
       - name: Mypy
         run: mypy
 
   integration:
-    name: Redis integration
+    name: Broker integration (Redis · RabbitMQ · SQS)
     runs-on: ubuntu-latest
     services:
       redis:
@@ -72,6 +72,12 @@ jobs:
           --health-interval 10s
           --health-timeout 5s
           --health-retries 15
+      # Free, SQS-compatible broker for the SqsTransport round-trip. The native
+      # image is shell-less, so readiness is polled by a TCP-probe step below.
+      elasticmq:
+        image: softwaremill/elasticmq-native:1.6.11
+        ports:
+          - 9324:9324
     steps:
       - uses: actions/checkout@v5
 
@@ -83,12 +89,26 @@ jobs:
       - name: Install (all adapters — full coverage with brokers)
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[redis,amqp,celery,django,dev]"
+          pip install -e ".[redis,amqp,sqs,celery,django,dev]"
+
+      - name: Wait for ElasticMQ
+        run: |
+          for i in $(seq 1 30); do
+            if (echo > /dev/tcp/localhost/9324) >/dev/null 2>&1; then
+              echo "ElasticMQ port 9324 open"; exit 0
+            fi
+            sleep 2
+          done
+          echo "ElasticMQ did not open port 9324"; exit 1
 
       - name: Run full suite with coverage gate (>=90%)
         env:
           BABELQUEUE_TEST_REDIS: redis://localhost:6379/0
           BABELQUEUE_TEST_AMQP: amqp://guest:guest@localhost:5672/
+          SQS_ENDPOINT: http://localhost:9324
+          AWS_REGION: us-east-1
+          AWS_ACCESS_KEY_ID: test
+          AWS_SECRET_ACCESS_KEY: test
         run: pytest --cov=babelqueue --cov-report=term-missing --cov-fail-under=90
 
   conformance:

{babelqueue-1.0.0 → babelqueue-1.1.0}/CHANGELOG.md

@@ -7,7 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 The envelope wire format is versioned separately by `meta.schema_version`
 (currently **1**) — see the contract at [babelqueue.com](https://babelqueue.com).
 
-## [Unreleased]
+## [1.1.0] - 2026-06-12
+
+### Added
+- **Amazon SQS transport** (`babelqueue[sqs]`, `boto3`) — `SqsTransport`, selected by
+  the `sqs://` URL scheme (e.g. `sqs://us-east-1?endpoint=http://localhost:4566` for
+  LocalStack). Implements [§3 of the broker-bindings contract](https://babelqueue.com):
+  the canonical envelope is the `MessageBody`, projected onto native `MessageAttributes`
+  (`bq-job`/`bq-trace-id`/`bq-message-id`/`bq-schema-version`/`bq-source-lang`/`bq-created-at`);
+  visibility-timeout reserve → `delete_message` ack; `attempts` reconciled to
+  `ApproximateReceiveCount − 1` (never lowering a runtime-incremented count). Supports
+  FIFO (`MessageGroupId`/`MessageDeduplicationId` = `meta.id`), content-based dedup,
+  configurable wait/visibility, and a `queue_url_prefix` that skips `GetQueueUrl`. A
+  client can be injected for tests/DI. 16 unit tests run against a fake client (no boto3,
+  no broker); a LocalStack integration test round-trips the real `boto3` path. The
+  envelope is unchanged (`schema_version: 1`); SQS is purely additive. Ships as a MINOR.
 
 ## [1.0.0] - 2026-06-07
 
@@ -85,7 +99,8 @@ reference at [babelqueue.com](https://babelqueue.com).
 - 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/v1.0.0...HEAD
+[Unreleased]: https://github.com/BabelQueue/babelqueue-python/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/BabelQueue/babelqueue-python/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/BabelQueue/babelqueue-python/compare/v0.5.0...v1.0.0
 [0.5.0]: https://github.com/BabelQueue/babelqueue-python/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/BabelQueue/babelqueue-python/compare/v0.3.0...v0.4.0

{babelqueue-1.0.0 → babelqueue-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: babelqueue
-Version: 1.0.0
+Version: 1.1.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
@@ -35,6 +35,8 @@ Provides-Extra: django
 Requires-Dist: django>=4.2; extra == 'django'
 Provides-Extra: redis
 Requires-Dist: redis>=4; extra == 'redis'
+Provides-Extra: sqs
+Requires-Dist: boto3>=1.26; extra == 'sqs'
 Description-Content-Type: text/markdown
 
 # BabelQueue for Python

{babelqueue-1.0.0 → babelqueue-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.0.0"
+version = "1.1.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"
@@ -31,6 +31,7 @@ dependencies = []
 # Optional runtime drivers + framework adapters — standard, zero-heavy-dep.
 redis = ["redis>=4"]
 amqp = ["pika>=1.3"]
+sqs = ["boto3>=1.26"]
 celery = ["celery>=5"]
 django = ["django>=4.2"]
 dev = ["pytest>=7", "pytest-cov>=4", "mypy>=1.8", "ruff>=0.5"]

{babelqueue-1.0.0 → babelqueue-1.1.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__ = "1.0.0"
+__version__ = "1.1.0"
 
 __all__ = [
     "BabelQueue",

babelqueue-1.1.0/src/babelqueue/sqs_transport.py

@@ -0,0 +1,209 @@
+"""Amazon SQS transport. Requires the ``sqs`` extra:
+
+    pip install "babelqueue[sqs]"
+
+Producing sends the canonical envelope as the message body and projects the
+contract envelope fields onto native SQS ``MessageAttributes`` (``bq-job`` = URN,
+``bq-trace-id`` = trace_id, ``bq-message-id`` = meta.id, plus ``bq-schema-version`` /
+``bq-source-lang`` / ``bq-created-at``) — so a Go/PHP/... peer can route on ``bq-job``
+and correlate on ``bq-trace-id`` without parsing the body. Consuming uses the
+visibility-timeout reservation model (``receive_message`` -> process ->
+``delete_message``); the authoritative attempt count is the broker's
+``ApproximateReceiveCount``, reconciled onto the envelope as ``attempts = count - 1``.
+
+This implements §3 of the broker-bindings contract. The envelope is unchanged
+(``schema_version`` stays 1); SQS is purely additive.
+
+URL form: ``sqs://[region][?endpoint=...&prefix=...&fifo=1&group_id=...&wait_time=20]``
+(e.g. ``sqs://us-east-1?endpoint=http://localhost:4566`` for LocalStack). Credentials
+come from the standard AWS default provider chain. For richer setups, build the
+transport directly and pass it via ``BabelQueue(transport=...)``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from urllib.parse import parse_qs, urlsplit
+
+from .codec import EnvelopeCodec
+from .transport import ReceivedMessage, Transport
+
+
+class SqsTransport(Transport):
+    def __init__(
+        self,
+        url: str = "sqs://",
+        *,
+        client: Any = None,
+        region: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        queue_url_prefix: Optional[str] = None,
+        wait_time: Optional[int] = None,
+        visibility_timeout: Optional[int] = None,
+        fifo: bool = False,
+        message_group_id: Optional[str] = None,
+        content_dedup: bool = False,
+    ) -> None:
+        parts = urlsplit(url) if url else urlsplit("sqs://")
+        q = parse_qs(parts.query)
+
+        self._region = region or (parts.hostname or None)
+        self._endpoint = endpoint or _q1(q, "endpoint")
+        self._queue_url_prefix = queue_url_prefix or _q1(q, "prefix")
+        self._wait_time = wait_time if wait_time is not None else _qint(q, "wait_time")
+        self._visibility_timeout = (
+            visibility_timeout if visibility_timeout is not None else _qint(q, "visibility_timeout")
+        )
+        self._fifo = fifo or _qbool(q, "fifo")
+        self._message_group_id = message_group_id or _q1(q, "group_id")
+        self._content_dedup = content_dedup or _qbool(q, "content_dedup")
+        self._urls: Dict[str, str] = {}
+
+        if client is not None:
+            self._sqs = client
+            return
+        try:
+            import boto3
+        except ImportError as exc:  # pragma: no cover - import guard
+            raise ImportError(
+                "SqsTransport requires the 'boto3' package. Install with "
+                'pip install "babelqueue[sqs]".'
+            ) from exc
+        kwargs: Dict[str, Any] = {}
+        if self._region:
+            kwargs["region_name"] = self._region
+        if self._endpoint:
+            kwargs["endpoint_url"] = self._endpoint
+        self._sqs = boto3.client("sqs", **kwargs)  # pragma: no cover - needs AWS/LocalStack
+
+    # -- helpers ------------------------------------------------------------
+
+    def _resolve_url(self, name: str) -> str:
+        cached = self._urls.get(name)
+        if cached is not None:
+            return cached
+        if self._queue_url_prefix:
+            url = self._queue_url_prefix.rstrip("/") + "/" + name
+        else:
+            url = self._sqs.get_queue_url(QueueName=name)["QueueUrl"]
+        self._urls[name] = url
+        return url
+
+    @staticmethod
+    def _attributes(body: str) -> Dict[str, Dict[str, str]]:
+        """Project the envelope's contract fields onto SQS MessageAttributes — a
+        redundant, routable view of the body (the body stays authoritative)."""
+        try:
+            env: Dict[str, Any] = EnvelopeCodec.decode(body)
+        except (ValueError, TypeError):  # pragma: no cover - decode is defensive
+            return {}
+        meta = env.get("meta") or {}
+
+        def s(v: Any) -> Dict[str, str]:
+            return {"DataType": "String", "StringValue": str(v)}
+
+        def n(v: Any) -> Dict[str, str]:
+            return {"DataType": "Number", "StringValue": str(v)}
+
+        attrs: Dict[str, Dict[str, str]] = {}
+        if env.get("job"):
+            attrs["bq-job"] = s(env["job"])
+        if env.get("trace_id"):
+            attrs["bq-trace-id"] = s(env["trace_id"])
+        if meta.get("id"):
+            attrs["bq-message-id"] = s(meta["id"])
+        if meta.get("schema_version") is not None:
+            attrs["bq-schema-version"] = n(meta["schema_version"])
+        if meta.get("lang"):
+            attrs["bq-source-lang"] = s(meta["lang"])
+        if meta.get("created_at") is not None:
+            attrs["bq-created-at"] = n(meta["created_at"])
+        return attrs
+
+    @staticmethod
+    def _reconcile(body: str, receive_count: Any) -> str:
+        """Set attempts to max(current, ApproximateReceiveCount - 1): a first delivery
+        reads 0, a natively-redelivered message reflects its true count, and a
+        runtime-incremented counter is never lowered."""
+        try:
+            rc = int(receive_count)
+        except (ValueError, TypeError):
+            return body
+        if rc <= 1:
+            return body
+        env = EnvelopeCodec.decode(body)
+        if not env:
+            return body
+        native = rc - 1
+        if native <= int(env.get("attempts", 0)):
+            return body
+        env["attempts"] = native
+        return EnvelopeCodec.encode(env)
+
+    # -- Transport ----------------------------------------------------------
+
+    def publish(self, queue: str, body: str) -> None:
+        params: Dict[str, Any] = {"QueueUrl": self._resolve_url(queue), "MessageBody": body}
+        attrs = self._attributes(body)
+        if attrs:
+            params["MessageAttributes"] = attrs
+        if self._fifo:
+            params["MessageGroupId"] = self._message_group_id or queue
+            if not self._content_dedup:
+                msg_id = (EnvelopeCodec.decode(body).get("meta") or {}).get("id")
+                if msg_id:
+                    params["MessageDeduplicationId"] = msg_id
+        self._sqs.send_message(**params)
+
+    def pop(self, queue: str, timeout: float = 1.0) -> Optional[ReceivedMessage]:
+        wait = int(timeout) if timeout and timeout > 0 else 0
+        if wait > 20:
+            wait = 20
+        if self._wait_time is not None and self._wait_time < wait:
+            wait = self._wait_time
+        params: Dict[str, Any] = {
+            "QueueUrl": self._resolve_url(queue),
+            "MaxNumberOfMessages": 1,
+            "WaitTimeSeconds": wait,
+            "MessageAttributeNames": ["All"],
+            "AttributeNames": ["ApproximateReceiveCount"],
+        }
+        if self._visibility_timeout is not None:
+            params["VisibilityTimeout"] = self._visibility_timeout
+        resp = self._sqs.receive_message(**params)
+        messages = resp.get("Messages") or []
+        if not messages:
+            return None
+        msg = messages[0]
+        body = msg.get("Body", "")
+        receive_count = (msg.get("Attributes") or {}).get("ApproximateReceiveCount")
+        if receive_count is not None:
+            body = self._reconcile(body, receive_count)
+        return ReceivedMessage(body=body, queue=queue, handle=msg.get("ReceiptHandle"))
+
+    def ack(self, message: ReceivedMessage) -> None:
+        if not message.handle:
+            return
+        self._sqs.delete_message(
+            QueueUrl=self._resolve_url(message.queue), ReceiptHandle=message.handle
+        )
+
+
+def _q1(q: Dict[str, list], key: str) -> Optional[str]:
+    values = q.get(key)
+    return values[0] if values else None
+
+
+def _qint(q: Dict[str, list], key: str) -> Optional[int]:
+    v = _q1(q, key)
+    if v is None:
+        return None
+    try:
+        return int(v)
+    except ValueError:  # pragma: no cover - defensive
+        return None
+
+
+def _qbool(q: Dict[str, list], key: str) -> bool:
+    v = _q1(q, key)
+    return v is not None and v.lower() in ("1", "true", "yes", "on")

{babelqueue-1.0.0 → babelqueue-1.1.0}/src/babelqueue/transport.py

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

babelqueue-1.1.0/tests/conformance/manifest.json

@@ -0,0 +1,97 @@
+{
+  "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"
+    }
+  ],
+  "sqs": {
+    "description": "Amazon SQS binding conformance (broker-bindings.md §3). Every SDK that ships an SQS transport must satisfy these. The envelope body stays byte-identical (the 'cases' above); these lock the native projection + reconciliation the binding adds. Per-message values reuse fixtures/order-created.json so the expected attributes are deterministic.",
+    "attribute_projection": {
+      "description": "On produce, the transport MUST project these native MessageAttributes from the envelope (a redundant, routable view of the body; ids/strings are DataType String, counters are DataType Number). Applies to every SQS-producing SDK.",
+      "envelope_file": "fixtures/order-created.json",
+      "message_attributes": {
+        "bq-job":            { "DataType": "String", "StringValue": "urn:babel:orders:created" },
+        "bq-trace-id":       { "DataType": "String", "StringValue": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b" },
+        "bq-message-id":     { "DataType": "String", "StringValue": "f1e2d3c4-b5a6-4789-90ab-cdef01234567" },
+        "bq-schema-version": { "DataType": "Number", "StringValue": "1" },
+        "bq-source-lang":    { "DataType": "String", "StringValue": "php" },
+        "bq-created-at":     { "DataType": "Number", "StringValue": "1749132727000" }
+      }
+    },
+    "attempts_reconciliation": {
+      "description": "On consume, attempts = max(body.attempts, ApproximateReceiveCount - 1): a first delivery reads 0, an absent/garbage count is ignored, a runtime-incremented count is never lowered. Applies to SDKs that reconcile the envelope body on consume (the framework-less/runtime transports). A drop-in driver that surfaces the broker's native delivery count instead (e.g. Laravel's SqsJob.attempts() = ApproximateReceiveCount) is exempt — it documents that divergence.",
+      "cases": [
+        { "name": "first-delivery",        "body_attempts": 0, "approximate_receive_count": "1",            "expected_attempts": 0 },
+        { "name": "third-delivery",        "body_attempts": 0, "approximate_receive_count": "3",            "expected_attempts": 2 },
+        { "name": "native-exceeds-body",   "body_attempts": 2, "approximate_receive_count": "5",            "expected_attempts": 4 },
+        { "name": "never-lower-runtime",   "body_attempts": 5, "approximate_receive_count": "1",            "expected_attempts": 5 },
+        { "name": "garbage-count-ignored", "body_attempts": 4, "approximate_receive_count": "not-a-number", "expected_attempts": 4 },
+        { "name": "absent-count",          "body_attempts": 3, "approximate_receive_count": null,           "expected_attempts": 3 }
+      ]
+    }
+  }
+}

babelqueue-1.1.0/tests/test_sqs_conformance.py

@@ -0,0 +1,53 @@
+"""Amazon SQS binding conformance: the vendored manifest's ``sqs`` block locks the
+§3 MessageAttributes projection and the ``attempts = ApproximateReceiveCount - 1``
+reconciliation. No boto3, no broker — pure transport logic against golden values."""
+
+from __future__ import annotations
+
+import json
+import os
+import unittest
+
+from babelqueue import EnvelopeCodec
+from babelqueue.sqs_transport import SqsTransport
+
+CONFORMANCE = os.path.join(os.path.dirname(__file__), "conformance")
+
+
+class SqsConformanceTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        with open(os.path.join(CONFORMANCE, "manifest.json"), encoding="utf-8") as fh:
+            cls.sqs = json.load(fh)["sqs"]
+
+    def test_attribute_projection(self) -> None:
+        projection = self.sqs["attribute_projection"]
+        with open(os.path.join(CONFORMANCE, projection["envelope_file"]), encoding="utf-8") as fh:
+            body = fh.read()
+
+        got = SqsTransport._attributes(body)
+        want = projection["message_attributes"]
+
+        self.assertEqual(set(got), set(want))
+        for key, expected in want.items():
+            self.assertEqual(got[key]["DataType"], expected["DataType"], key)
+            self.assertEqual(got[key]["StringValue"], expected["StringValue"], key)
+
+    def test_attempts_reconciliation(self) -> None:
+        for case in self.sqs["attempts_reconciliation"]["cases"]:
+            env = EnvelopeCodec.make("urn:babel:orders:created", {"x": 1})
+            env["attempts"] = case["body_attempts"]
+            body = EnvelopeCodec.encode(env)
+
+            receive_count = case["approximate_receive_count"]
+            out = body if receive_count is None else SqsTransport._reconcile(body, receive_count)
+
+            self.assertEqual(
+                EnvelopeCodec.decode(out)["attempts"],
+                case["expected_attempts"],
+                case["name"],
+            )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()

babelqueue-1.1.0/tests/test_sqs_transport.py

@@ -0,0 +1,299 @@
+"""Tests for the Amazon SQS transport.
+
+The unit tests inject a fake SQS client, so they run without ``boto3`` and without
+a broker. A separate integration test round-trips against LocalStack and is skipped
+unless ``boto3`` + a reachable endpoint are present (CI runs it).
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+import uuid
+
+from babelqueue import BabelQueue, EnvelopeCodec
+from babelqueue.sqs_transport import SqsTransport
+from babelqueue.transport import ReceivedMessage, make_transport
+
+
+class FakeSQS:
+    """In-memory SQS API — no boto3, no network."""
+
+    def __init__(self, err: Exception | None = None) -> None:
+        self.visible: dict[str, list[dict]] = {}
+        self.sent: list[dict] = []
+        self.deleted: list[str] = []
+        self.get_url_calls = 0
+        self.last_receive: dict | None = None
+        self.err = err
+        self._n = 0
+
+    def get_queue_url(self, QueueName):  # noqa: N803 - AWS API casing
+        self.get_url_calls += 1
+        if self.err:
+            raise self.err
+        return {"QueueUrl": "http://fake/" + QueueName}
+
+    def send_message(self, **kw):
+        if self.err:
+            raise self.err
+        self.sent.append(kw)
+        self._n += 1
+        handle = f"rh-{self._n}"
+        self.visible.setdefault(kw["QueueUrl"], []).append(
+            {
+                "Body": kw["MessageBody"],
+                "MessageAttributes": kw.get("MessageAttributes"),
+                "ReceiptHandle": handle,
+                "Attributes": {"ApproximateReceiveCount": "1"},
+            }
+        )
+        return {"MessageId": handle}
+
+    def receive_message(self, **kw):
+        self.last_receive = kw
+        if self.err:
+            raise self.err
+        q = self.visible.get(kw["QueueUrl"], [])
+        if not q:
+            return {}
+        return {"Messages": [q.pop(0)]}
+
+    def delete_message(self, **kw):
+        if self.err:
+            raise self.err
+        self.deleted.append(kw["ReceiptHandle"])
+        return {}
+
+    def seed(self, url: str, body: str, receive_count: int) -> None:
+        self._n += 1
+        self.visible.setdefault(url, []).append(
+            {
+                "Body": body,
+                "ReceiptHandle": f"seed-{self._n}",
+                "Attributes": {"ApproximateReceiveCount": str(receive_count)},
+            }
+        )
+
+
+def _attr(sent: dict, key: str) -> str:
+    return sent["MessageAttributes"][key]["StringValue"]
+
+
+class SqsTransportUnitTest(unittest.TestCase):
+    def _tr(self, **kw) -> tuple[SqsTransport, FakeSQS]:
+        fake = FakeSQS()
+        return SqsTransport("sqs://", client=fake, queue_url_prefix="http://fake", **kw), fake
+
+    def test_publish_projects_contract_attributes(self):
+        tr, fake = self._tr()
+        env = EnvelopeCodec.make("urn:babel:orders:created", {"order_id": 1042}, queue="orders")
+        body = EnvelopeCodec.encode(env)
+        tr.publish("orders", body)
+
+        self.assertEqual(len(fake.sent), 1)
+        sent = fake.sent[0]
+        self.assertEqual(sent["QueueUrl"], "http://fake/orders")
+        self.assertEqual(sent["MessageBody"], body)  # byte-identical
+        self.assertEqual(_attr(sent, "bq-job"), env["job"])
+        self.assertEqual(_attr(sent, "bq-trace-id"), env["trace_id"])
+        self.assertEqual(_attr(sent, "bq-message-id"), env["meta"]["id"])
+        self.assertEqual(_attr(sent, "bq-schema-version"), "1")
+        self.assertEqual(_attr(sent, "bq-source-lang"), "python")
+        self.assertEqual(_attr(sent, "bq-created-at"), str(env["meta"]["created_at"]))
+        # Type discipline: ids String, counters Number.
+        self.assertEqual(sent["MessageAttributes"]["bq-job"]["DataType"], "String")
+        self.assertEqual(sent["MessageAttributes"]["bq-schema-version"]["DataType"], "Number")
+
+    def test_pop_reconciles_attempts_from_receive_count(self):
+        tr, fake = self._tr()
+        env = EnvelopeCodec.make("urn:babel:orders:created", {"x": 1}, queue="orders")
+        fake.seed("http://fake/orders", EnvelopeCodec.encode(env), 3)  # 3rd delivery -> attempts 2
+        msg = tr.pop("orders", timeout=0)
+        self.assertIsNotNone(msg)
+        self.assertEqual(EnvelopeCodec.decode(msg.body)["attempts"], 2)
+
+    def test_pop_does_not_lower_runtime_attempts(self):
+        tr, fake = self._tr()
+        env = EnvelopeCodec.make("urn:babel:orders:created", {"x": 1})
+        env["attempts"] = 5
+        fake.seed("http://fake/default", EnvelopeCodec.encode(env), 1)
+        msg = tr.pop("default", timeout=0)
+        self.assertEqual(EnvelopeCodec.decode(msg.body)["attempts"], 5)
+
+    def test_pop_empty_returns_none(self):
+        tr, _ = self._tr()
+        self.assertIsNone(tr.pop("orders", timeout=0))
+
+    def test_ack_deletes_by_receipt_handle(self):
+        tr, fake = self._tr()
+        fake.seed("http://fake/orders", '{"job":"u","trace_id":"t","data":{},"meta":{"schema_version":1},"attempts":0}', 1)
+        msg = tr.pop("orders", timeout=0)
+        tr.ack(msg)
+        self.assertEqual(fake.deleted, [msg.handle])
+
+    def test_ack_noop_on_empty_handle(self):
+        tr, fake = self._tr()
+        tr.ack(ReceivedMessage(body="", queue="orders", handle=None))
+        self.assertEqual(fake.deleted, [])
+
+    def test_fifo_sets_group_and_dedup(self):
+        tr, fake = self._tr(fifo=True)
+        env = EnvelopeCodec.make("urn:babel:orders:created", {"x": 1}, queue="orders.fifo")
+        tr.publish("orders.fifo", EnvelopeCodec.encode(env))
+        sent = fake.sent[0]
+        self.assertEqual(sent["MessageGroupId"], "orders.fifo")
+        self.assertEqual(sent["MessageDeduplicationId"], env["meta"]["id"])
+
+    def test_content_dedup_omits_dedup_id(self):
+        tr, fake = self._tr(fifo=True, content_dedup=True, message_group_id="grp")
+        tr.publish("orders.fifo", '{"job":"u","trace_id":"t","data":{},"meta":{"id":"m1","schema_version":1},"attempts":0}')
+        sent = fake.sent[0]
+        self.assertEqual(sent["MessageGroupId"], "grp")
+        self.assertNotIn("MessageDeduplicationId", sent)
+
+    def test_resolve_via_get_queue_url_and_caches(self):
+        fake = FakeSQS()
+        tr = SqsTransport("sqs://", client=fake)  # no prefix -> GetQueueUrl path
+        body = '{"job":"u","trace_id":"t","data":{},"meta":{"schema_version":1,"lang":"python"},"attempts":0}'
+        for _ in range(3):
+            tr.publish("orders", body)
+        self.assertEqual(fake.sent[0]["QueueUrl"], "http://fake/orders")
+        self.assertEqual(fake.get_url_calls, 1)  # cached
+
+    def test_pop_applies_visibility_and_wait_options(self):
+        tr, fake = self._tr(visibility_timeout=45, wait_time=5)
+        tr.pop("orders", timeout=30)
+        self.assertEqual(fake.last_receive["VisibilityTimeout"], 45)
+        self.assertEqual(fake.last_receive["WaitTimeSeconds"], 5)  # 30 -> clamp 20 -> cap 5
+        self.assertEqual(fake.last_receive["MessageAttributeNames"], ["All"])
+        self.assertEqual(fake.last_receive["AttributeNames"], ["ApproximateReceiveCount"])
+
+    def test_url_parses_region_endpoint_prefix_fifo(self):
+        fake = FakeSQS()
+        tr = SqsTransport(
+            "sqs://eu-west-1?endpoint=http://ls:4566&prefix=http://ls:4566/000000000000&fifo=1&group_id=g&wait_time=7",
+            client=fake,
+        )
+        self.assertEqual(tr._region, "eu-west-1")
+        self.assertEqual(tr._endpoint, "http://ls:4566")
+        self.assertTrue(tr._fifo)
+        self.assertEqual(tr._message_group_id, "g")
+        self.assertEqual(tr._wait_time, 7)
+        # prefix resolution avoids GetQueueUrl
+        tr.publish("orders.fifo", '{"job":"u","trace_id":"t","data":{},"meta":{"id":"m","schema_version":1}}')
+        self.assertEqual(fake.sent[0]["QueueUrl"], "http://ls:4566/000000000000/orders.fifo")
+
+    def test_reconcile_ignores_garbage_and_undecodable(self):
+        tr, fake = self._tr()
+        fake.seed("http://fake/orders", '{"job":"u","trace_id":"t","data":{},"meta":{"schema_version":1},"attempts":4}', 0)
+        fake.visible["http://fake/orders"][0]["Attributes"]["ApproximateReceiveCount"] = "not-a-number"
+        msg = tr.pop("orders", timeout=0)
+        self.assertEqual(EnvelopeCodec.decode(msg.body)["attempts"], 4)
+
+        fake.seed("http://fake/orders", "not-json", 3)  # rc>1 but undecodable body
+        msg2 = tr.pop("orders", timeout=0)
+        self.assertEqual(msg2.body, "not-json")
+
+    def test_attributes_empty_for_undecodable_body(self):
+        self.assertEqual(SqsTransport._attributes("}{not json"), {})
+
+    def test_errors_propagate(self):
+        boom = RuntimeError("boom")
+        fail = SqsTransport("sqs://", client=FakeSQS(err=boom))  # no prefix -> GetQueueUrl errors
+        with self.assertRaises(RuntimeError):
+            fail.publish("orders", '{"job":"u","trace_id":"t","data":{},"meta":{"schema_version":1}}')
+        with self.assertRaises(RuntimeError):
+            fail.pop("orders", timeout=0)
+        with self.assertRaises(RuntimeError):
+            fail.ack(ReceivedMessage(body="", queue="orders", handle="h"))
+
+    def test_round_trip_through_app(self):
+        fake = FakeSQS()
+        tr = SqsTransport("sqs://", client=fake, queue_url_prefix="http://fake")
+        app = BabelQueue(transport=tr, queue="orders")
+        seen: dict = {}
+
+        @app.handler("urn:babel:orders:created")
+        def _on(data, meta):
+            seen.update({"data": data, "meta": meta})
+
+        msg_id = app.publish("urn:babel:orders:created", {"order_id": 7})
+        processed = app.consume("orders", max_messages=1, timeout=0)
+        self.assertEqual(processed, 1)
+        self.assertEqual(seen["data"]["order_id"], 7)
+        self.assertEqual(seen["meta"]["id"], msg_id)
+        self.assertEqual(len(fake.deleted), 1)  # acked/deleted
+
+    def test_make_transport_routes_sqs_scheme(self):
+        # The scheme dispatches to SqsTransport; without boto3 it surfaces a clear
+        # install hint (covers the make_transport branch). With boto3 present this
+        # would construct a real client, so only assert the branch is reached.
+        try:
+            import boto3  # noqa: F401
+            self.skipTest("boto3 installed — real client would be built")
+        except ImportError:
+            with self.assertRaises(ImportError):
+                make_transport("sqs://")
+
+
+def _sqs_available() -> bool:
+    try:
+        import boto3
+    except ImportError:
+        return False
+    endpoint = os.environ.get("SQS_ENDPOINT", "http://localhost:4566")
+    try:
+        client = boto3.client(
+            "sqs",
+            region_name=os.environ.get("AWS_REGION", "us-east-1"),
+            endpoint_url=endpoint,
+            aws_access_key_id=os.environ.get("AWS_ACCESS_KEY_ID", "test"),
+            aws_secret_access_key=os.environ.get("AWS_SECRET_ACCESS_KEY", "test"),
+        )
+        client.list_queues()
+        return True
+    except Exception:  # pragma: no cover - connection failure
+        return False
+
+
+@unittest.skipUnless(_sqs_available(), "no reachable LocalStack SQS at SQS_ENDPOINT")
+class SqsLocalStackIntegrationTest(unittest.TestCase):
+    def setUp(self) -> None:
+        import boto3
+
+        self.endpoint = os.environ.get("SQS_ENDPOINT", "http://localhost:4566")
+        self.region = os.environ.get("AWS_REGION", "us-east-1")
+        os.environ.setdefault("AWS_ACCESS_KEY_ID", "test")
+        os.environ.setdefault("AWS_SECRET_ACCESS_KEY", "test")
+        self.raw = boto3.client("sqs", region_name=self.region, endpoint_url=self.endpoint)
+        self.queue = f"bq-it-{uuid.uuid4().hex}"
+        self.raw.create_queue(QueueName=self.queue)
+
+    def tearDown(self) -> None:
+        try:
+            url = self.raw.get_queue_url(QueueName=self.queue)["QueueUrl"]
+            self.raw.delete_queue(QueueUrl=url)
+        except Exception:
+            pass
+
+    def test_produce_consume_round_trip(self):
+        url = f"sqs://{self.region}?endpoint={self.endpoint}"
+        app = BabelQueue(url, queue=self.queue)
+        seen: dict = {}
+        app.register("urn:babel:orders:created", lambda data, meta: seen.update(data))
+        msg_id = app.publish("urn:babel:orders:created", {"order_id": 1042})
+        self.assertTrue(msg_id)
+
+        # publish carried the contract attributes; verify them off the raw queue too
+        processed = 0
+        for _ in range(30):
+            processed = app.consume(self.queue, max_messages=1, timeout=1)
+            if processed:
+                break
+        self.assertEqual(processed, 1)
+        self.assertEqual(seen.get("order_id"), 1042)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()

babelqueue-1.0.0/tests/conformance/manifest.json

@@ -1,71 +0,0 @@
-{
-  "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"
-    }
-  ]
-}