babelqueue 1.3.0__tar.gz → 1.5.0__tar.gz

{babelqueue-1.3.0 → babelqueue-1.5.0}/.github/workflows/ci.yml

@@ -44,7 +44,7 @@ jobs:
       - name: Install (dev + all adapters for type context)
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,celery,django,redis,amqp,sqs,azureservicebus]"
+          pip install -e ".[dev,celery,django,redis,amqp,sqs,azureservicebus,artemis]"
       - name: Ruff
         run: ruff check src tests
       - name: Mypy
@@ -89,7 +89,7 @@ jobs:
       - name: Install (all adapters — full coverage with brokers)
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[redis,amqp,sqs,azureservicebus,celery,django,dev]"
+          pip install -e ".[redis,amqp,sqs,azureservicebus,artemis,celery,django,dev]"
 
       - name: Wait for ElasticMQ
         run: |

{babelqueue-1.3.0 → babelqueue-1.5.0}/.gitignore

@@ -12,3 +12,6 @@ venv/
 .coverage
 coverage.xml
 htmlcov/
+
+# CommitBrief local config and cache
+.commitbrief/

{babelqueue-1.3.0 → babelqueue-1.5.0}/CHANGELOG.md

@@ -7,6 +7,46 @@ 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).
 
+## [1.5.0] - 2026-06-13
+
+### Added
+- **Apache ActiveMQ Artemis transport** (`babelqueue[artemis]`, `python-qpid-proton`) —
+  `ArtemisTransport`, selected by the `artemis://` (or `artemis+ssl://`) URL scheme (e.g.
+  `artemis://localhost:5672`; or pass an injected `connection`). Artemis speaks **AMQP 1.0**
+  (not RabbitMQ's 0-9-1), so the transport uses the `python-qpid-proton` blocking client.
+  Implements [§7 of the broker-bindings
+  contract](https://babelqueue.com/docs/spec/1.x/broker-bindings#apache-activemq-artemis): the
+  canonical envelope is the message body, projected onto the AMQP fields a JMS peer reads —
+  `correlation-id` = `trace_id` (JMSCorrelationID), `creation-time` = `meta.created_at`
+  (JMSTimestamp), the `x-opt-jms-type` annotation = URN (JMSType, the AMQP-JMS mapping), plus
+  the `bq-schema-version`/`bq-source-lang`/`bq-attempts`/`bq-app-id` application properties.
+  Consume reserves one message at a time (`receive` → process → `accept`); `attempts` is
+  reconciled to `max(body, delivery_count)` — the AMQP delivery-count header is 0-based, so it
+  maps directly with no −1 (the Java JMS binding reads the 1-based `JMSXDeliveryCount` and
+  subtracts 1, arriving at the same 0-based `attempts`), and the `max` never lowers a higher
+  body count carried by a republish-driven retry. The projection + reconciliation + pop/ack
+  flow are unit-tested with no broker and no `python-qpid-proton` (the proton import is lazy;
+  the transport talks to an injected connection fake); the publish flow that builds a real
+  proton `Message` is exercised wherever proton is installed. The envelope is unchanged
+  (`schema_version: 1`); Apache ActiveMQ Artemis is purely additive. Ships as a MINOR.
+
+## [1.4.0] - 2026-06-13
+
+### Added
+- **Apache Kafka transport** (`babelqueue[kafka]`, `confluent-kafka`) — `KafkaTransport`,
+  selected by the `kafka://` URL scheme (e.g. `kafka://host:9092`; or pass an injected
+  `producer` + `consumer_factory`). Implements [§6 of the broker-bindings
+  contract](https://babelqueue.com/docs/spec/1.x/broker-bindings#apache-kafka): the record
+  **value** is the canonical envelope, projected onto native Kafka record headers (UTF-8 byte
+  strings) — `bq-job` = URN, `bq-trace-id`, `bq-message-id`, plus `bq-schema-version`/
+  `bq-source-lang`/`bq-attempts` — with the record timestamp mirroring `meta.created_at`.
+  Consume is **process-then-commit** (`pop` reserves via `poll` with `enable.auto.commit=false`,
+  `ack` commits the offset); the **`bq-attempts` header is the authoritative attempt counter**
+  (the body's `attempts` is the fallback for non-BabelQueue producers). The projection +
+  reconciliation + publish/pop/ack flow are unit-tested with no broker and no `confluent-kafka`
+  (the kafka import is lazy; the transport talks to injected producer/consumer fakes). The
+  envelope is unchanged (`schema_version: 1`); Apache Kafka is purely additive. Ships as a MINOR.
+
 ## [1.3.0] - 2026-06-13
 
 ### Added

{babelqueue-1.3.0 → babelqueue-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: babelqueue
-Version: 1.3.0
+Version: 1.5.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
@@ -24,6 +24,8 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Provides-Extra: amqp
 Requires-Dist: pika>=1.3; extra == 'amqp'
+Provides-Extra: artemis
+Requires-Dist: python-qpid-proton>=0.39; extra == 'artemis'
 Provides-Extra: azureservicebus
 Requires-Dist: azure-identity>=1.15; extra == 'azureservicebus'
 Requires-Dist: azure-servicebus>=7.11; extra == 'azureservicebus'
@@ -36,6 +38,8 @@ Requires-Dist: pytest>=7; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
 Provides-Extra: django
 Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: kafka
+Requires-Dist: confluent-kafka>=2.3; extra == 'kafka'
 Provides-Extra: pulsar
 Requires-Dist: pulsar-client>=3.4; extra == 'pulsar'
 Provides-Extra: redis

{babelqueue-1.3.0 → babelqueue-1.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.3.0"
+version = "1.5.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"
@@ -34,6 +34,8 @@ amqp = ["pika>=1.3"]
 sqs = ["boto3>=1.26"]
 azureservicebus = ["azure-servicebus>=7.11", "azure-identity>=1.15"]
 pulsar = ["pulsar-client>=3.4"]
+kafka = ["confluent-kafka>=2.3"]
+artemis = ["python-qpid-proton>=0.39"]
 celery = ["celery>=5"]
 django = ["django>=4.2"]
 dev = ["pytest>=7", "pytest-cov>=4", "mypy>=1.8", "ruff>=0.5"]

babelqueue-1.5.0/src/babelqueue/artemis_transport.py

@@ -0,0 +1,227 @@
+"""Apache ActiveMQ Artemis transport over AMQP 1.0. Requires the ``artemis`` extra:
+
+    pip install "babelqueue[artemis]"
+
+Artemis speaks AMQP 1.0 (not the 0-9-1 of RabbitMQ), so this transport uses the
+``python-qpid-proton`` blocking client rather than ``pika``. Producing sends the canonical
+envelope as the message body and projects the contract envelope fields onto the AMQP
+properties a JMS peer reads: ``correlation-id`` = trace_id (JMSCorrelationID), ``creation-time``
+= meta.created_at (JMSTimestamp), the ``x-opt-jms-type`` message annotation = URN (JMSType, the
+AMQP-JMS mapping), plus the ``bq_`` application properties (``bq_schema_version`` /
+``bq_source_lang`` / ``bq_attempts`` / ``bq_app_id``; underscores, since JMS property names must
+be valid Java identifiers) — so a Java (JMS) or .NET/Node/... peer
+routes and correlates without parsing the body. The URN in the body's ``job`` field stays
+authoritative.
+
+Consuming reserves one message at a time (``receive`` -> process -> ``accept``); the
+authoritative attempt count is the envelope's ``attempts`` (the body), reconciled against the
+broker's native AMQP ``delivery-count`` as ``attempts = max(body, delivery_count)`` — no -1,
+because the AMQP header counter is 0-based (0 on first delivery), counting prior failed
+deliveries. (The Java JMS binding reads ``JMSXDeliveryCount`` which is 1-based and subtracts 1,
+arriving at the same 0-based ``attempts``.) A message left un-accepted is redelivered
+(at-least-once).
+
+This implements §7 of the broker-bindings contract. The envelope is unchanged
+(``schema_version`` stays 1); Apache ActiveMQ Artemis is purely additive.
+
+URL form: ``artemis://host:5672`` (or ``artemis+ssl://`` for TLS) — translated to the
+``amqp://`` / ``amqps://`` proton speaks. For credentials or a custom connection, build the
+transport directly and pass it via ``BabelQueue(transport=...)`` or
+``ArtemisTransport(connection=...)``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .codec import EnvelopeCodec
+from .transport import ReceivedMessage, Transport
+
+JMS_TYPE_ANNOTATION = "x-opt-jms-type"
+APP_ID = "babelqueue"
+
+
+class ArtemisTransport(Transport):
+    def __init__(
+        self,
+        url: str = "artemis://localhost:5672",
+        *,
+        connection: Any = None,
+        credit: int = 1,
+        receive_timeout_millis: int = 1000,
+        **connect_options: Any,
+    ) -> None:
+        self._url = url or "artemis://localhost:5672"
+        self._credit = credit
+        self._receive_timeout_millis = receive_timeout_millis
+        self._connect_options = connect_options
+        self._senders: Dict[str, Any] = {}
+        self._receivers: Dict[str, Any] = {}
+
+        if connection is not None:
+            self._connection = connection
+            return
+        self._connection = self._build_connection()  # pragma: no cover - needs Artemis / network
+
+    def _build_connection(self) -> Any:  # pragma: no cover - needs Artemis / network
+        try:
+            from proton.utils import BlockingConnection
+        except ImportError as exc:
+            raise ImportError(
+                "ArtemisTransport requires the 'python-qpid-proton' package. Install with "
+                'pip install "babelqueue[artemis]".'
+            ) from exc
+        return BlockingConnection(self._to_amqp_url(self._url), **self._connect_options)
+
+    # -- helpers ------------------------------------------------------------
+
+    @staticmethod
+    def _to_amqp_url(url: str) -> str:
+        """``artemis://`` -> ``amqp://`` and ``artemis+ssl://`` -> ``amqps://`` (proton's schemes)."""
+        if url.startswith("artemis+ssl://"):
+            return "amqps://" + url[len("artemis+ssl://"):]
+        if url.startswith("artemis://"):
+            return "amqp://" + url[len("artemis://"):]
+        return url
+
+    def _sender(self, queue: str) -> Any:
+        sender = self._senders.get(queue)
+        if sender is None:
+            sender = self._connection.create_sender(queue)
+            self._senders[queue] = sender
+        return sender
+
+    def _receiver(self, queue: str) -> Any:
+        receiver = self._receivers.get(queue)
+        if receiver is None:
+            receiver = self._connection.create_receiver(queue, credit=self._credit)
+            self._receivers[queue] = receiver
+        return receiver
+
+    @staticmethod
+    def _projection(body: str) -> Dict[str, str]:
+        """AMQP application properties (string->string) — a redundant, routable view of the
+        body: bq_schema_version/bq_source_lang/bq_attempts/bq_app_id. §7.2 (the URN is carried
+        by the x-opt-jms-type annotation, trace_id by correlation-id). The names use UNDERSCORES,
+        not hyphens: a JMS property name must be a valid Java identifier, and every Artemis SDK
+        uses the same JMS-legal form for cross-protocol parity."""
+        env = EnvelopeCodec.decode(body)
+        if not env:
+            return {}
+        meta = env.get("meta") or {}
+
+        props: Dict[str, str] = {}
+        if meta.get("schema_version") is not None:
+            props["bq_schema_version"] = str(meta["schema_version"])
+        if meta.get("lang"):
+            props["bq_source_lang"] = str(meta["lang"])
+        props["bq_attempts"] = str(int(env.get("attempts", 0) or 0))
+        props["bq_app_id"] = APP_ID
+        return props
+
+    @staticmethod
+    def _jms_type(body: str) -> str:
+        env = EnvelopeCodec.decode(body)
+        return str(env["job"]) if env and env.get("job") else ""
+
+    @staticmethod
+    def _correlation_id(body: str) -> str:
+        env = EnvelopeCodec.decode(body)
+        return str(env["trace_id"]) if env and env.get("trace_id") else ""
+
+    @staticmethod
+    def _creation_seconds(body: str) -> Optional[float]:
+        """proton's creation_time is float seconds; the contract's created_at is epoch ms."""
+        env = EnvelopeCodec.decode(body)
+        meta = (env or {}).get("meta") or {}
+        created_at = meta.get("created_at")
+        if created_at is None:
+            return None
+        try:
+            return int(created_at) / 1000.0
+        except (TypeError, ValueError):  # pragma: no cover - defensive
+            return None
+
+    def _message(self, body: str) -> Any:
+        """Build the proton Message projecting the §7 JMS-readable metadata."""
+        from proton import Message, symbol
+
+        message: Any = Message(body=body)
+        props = self._projection(body)
+        if props:
+            message.properties = props
+        correlation_id = self._correlation_id(body)
+        if correlation_id:
+            message.correlation_id = correlation_id
+        creation = self._creation_seconds(body)
+        if creation is not None:
+            message.creation_time = creation
+        jms_type = self._jms_type(body)
+        if jms_type:
+            message.annotations = {symbol(JMS_TYPE_ANNOTATION): jms_type}
+        return message
+
+    @staticmethod
+    def _reconcile(body: str, delivery_count: Any) -> str:
+        """Set attempts to max(current, delivery_count). The AMQP delivery-count header is
+        0-based (0 on first delivery), so it maps directly to attempts with no -1. The runtime
+        retries by republishing with attempts+1 in the body (delivery-count back to 0), so a
+        republished message must not have its higher body count lowered."""
+        try:
+            dc = int(delivery_count)
+        except (ValueError, TypeError):
+            return body
+        if dc <= 0:
+            return body
+        env = EnvelopeCodec.decode(body)
+        if not env or dc <= int(env.get("attempts", 0) or 0):
+            return body
+        env["attempts"] = dc
+        return EnvelopeCodec.encode(env)
+
+    @staticmethod
+    def _delivery_count(message: Any) -> int:
+        value = getattr(message, "delivery_count", 0)
+        try:
+            return int(value)
+        except (TypeError, ValueError):  # pragma: no cover - defensive
+            return 0
+
+    @staticmethod
+    def _payload(message: Any) -> str:
+        body = getattr(message, "body", None)
+        if isinstance(body, bytes):
+            return body.decode("utf-8")
+        return str(body) if body is not None else ""
+
+    # -- Transport ----------------------------------------------------------
+
+    def publish(self, queue: str, body: str) -> None:
+        self._sender(queue).send(self._message(body))
+
+    def pop(self, queue: str, timeout: float = 1.0) -> Optional[ReceivedMessage]:
+        wait = self._receive_timeout_millis / 1000.0
+        if timeout and timeout > 0:
+            wait = timeout
+        receiver = self._receiver(queue)
+        try:
+            message = receiver.receive(timeout=wait)
+        except Exception as exc:  # noqa: BLE001 - proton raises proton.Timeout on no message
+            if type(exc).__name__ == "Timeout":
+                return None
+            raise
+        if message is None:  # pragma: no cover - defensive (real client raises instead)
+            return None
+        body = self._reconcile(self._payload(message), self._delivery_count(message))
+        return ReceivedMessage(body=body, queue=queue, handle=receiver)
+
+    def ack(self, message: ReceivedMessage) -> None:
+        if message.handle is None:
+            return
+        message.handle.accept()
+
+    def close(self) -> None:  # pragma: no cover - resource cleanup
+        try:
+            self._connection.close()
+        except Exception:  # noqa: BLE001 - best-effort cleanup
+            pass

babelqueue-1.5.0/src/babelqueue/kafka_transport.py

@@ -0,0 +1,181 @@
+"""Apache Kafka transport. Requires the ``kafka`` extra:
+
+    pip install "babelqueue[kafka]"
+
+Producing writes the canonical envelope as the record value and projects the contract
+envelope fields onto native Kafka record headers (UTF-8 byte strings): ``bq-job`` = URN,
+``bq-trace-id`` = trace_id, ``bq-message-id`` = meta.id, plus ``bq-schema-version`` /
+``bq-source-lang`` / ``bq-attempts`` — so a Java/.NET/... peer can route on ``bq-job``
+without parsing the body — with the record timestamp mirroring ``meta.created_at``.
+Consuming is process-then-commit: ``poll`` reserves a record (``enable.auto.commit=false``)
+and ``ack`` commits the offset only after the handler returns (at-least-once). Kafka has no
+native delivery count, so the ``bq-attempts`` header is the authoritative retry counter (the
+body's ``attempts`` is the fallback for non-BabelQueue producers); the runtime owns retry by
+republishing with attempts+1 and dead-letters to ``<queue>.dlq``.
+
+This implements §6 of the broker-bindings contract. The envelope is unchanged
+(``schema_version`` stays 1); Apache Kafka is purely additive.
+
+URL form: ``kafka://host:9092[,host2:9092]``. The default consumer group is ``babelqueue``.
+For a custom client, build the transport directly and pass it via ``BabelQueue(transport=...)``
+or ``KafkaTransport(producer=..., consumer_factory=...)``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from .codec import EnvelopeCodec
+from .transport import ReceivedMessage, Transport
+
+Headers = List[Tuple[str, bytes]]
+
+
+def _brokers_from_url(url: str) -> str:
+    rest = url.split("://", 1)[1] if "://" in url else url
+    return rest.split("/", 1)[0] or "localhost:9092"
+
+
+class KafkaTransport(Transport):
+    def __init__(
+        self,
+        url: str = "kafka://localhost:9092",
+        *,
+        producer: Any = None,
+        consumer_factory: Optional[Callable[[str], Any]] = None,
+        group_id: str = "babelqueue",
+        **client_config: Any,
+    ) -> None:
+        self._brokers = _brokers_from_url(url or "kafka://localhost:9092")
+        self._group_id = group_id
+        self._client_config = client_config
+        self._producer = producer
+        self._consumer_factory = consumer_factory
+        self._consumers: Dict[str, Any] = {}
+
+    # -- helpers ------------------------------------------------------------
+
+    def _producer_(self) -> Any:
+        if self._producer is None:
+            self._producer = self._build_producer()  # pragma: no cover - needs Kafka / network
+        return self._producer
+
+    def _build_producer(self) -> Any:  # pragma: no cover - needs Kafka / network
+        from confluent_kafka import Producer
+
+        return Producer({"bootstrap.servers": self._brokers, **self._client_config})
+
+    def _consumer(self, queue: str) -> Any:
+        consumer = self._consumers.get(queue)
+        if consumer is None:
+            if self._consumer_factory is not None:
+                consumer = self._consumer_factory(queue)
+            else:
+                consumer = self._build_consumer(queue)  # pragma: no cover - needs Kafka / network
+            self._consumers[queue] = consumer
+        return consumer
+
+    def _build_consumer(self, queue: str) -> Any:  # pragma: no cover - needs Kafka / network
+        from confluent_kafka import Consumer
+
+        consumer = Consumer(
+            {
+                "bootstrap.servers": self._brokers,
+                "group.id": self._group_id,
+                "enable.auto.commit": False,
+                "auto.offset.reset": "earliest",
+                **self._client_config,
+            }
+        )
+        consumer.subscribe([queue])
+        return consumer
+
+    @staticmethod
+    def _projection(body: str) -> Headers:
+        """Native Kafka record headers (UTF-8 byte values) — a redundant, routable view of the
+        body: bq-job/bq-trace-id/bq-message-id + bq-schema-version/lang/attempts. §6.3."""
+        env = EnvelopeCodec.decode(body)
+        if not env:
+            return []
+        meta = env.get("meta") or {}
+
+        headers: Headers = []
+
+        def add(key: str, value: Any) -> None:
+            if value is not None and value != "":
+                headers.append((key, str(value).encode("utf-8")))
+
+        add("bq-job", env.get("job"))
+        add("bq-trace-id", env.get("trace_id"))
+        add("bq-message-id", meta.get("id"))
+        if meta.get("schema_version") is not None:
+            headers.append(("bq-schema-version", str(meta["schema_version"]).encode("utf-8")))
+        add("bq-source-lang", meta.get("lang"))
+        headers.append(("bq-attempts", str(int(env.get("attempts", 0) or 0)).encode("utf-8")))
+        return headers
+
+    @staticmethod
+    def _reconcile(body: str, headers: Any) -> str:
+        """Set attempts to the authoritative bq-attempts header (falling back to the body's own
+        attempts when the header is absent/unparseable — a non-BabelQueue producer). §6.5."""
+        env = EnvelopeCodec.decode(body)
+        if not env:
+            return body
+        attempts = int(env.get("attempts", 0) or 0)
+        for key, value in headers or []:
+            if key == "bq-attempts":
+                raw = value.decode("utf-8") if isinstance(value, (bytes, bytearray)) else str(value)
+                try:
+                    attempts = int(raw)
+                except (ValueError, TypeError):
+                    pass
+                break
+        if attempts == int(env.get("attempts", 0) or 0):
+            return body
+        env["attempts"] = attempts
+        return EnvelopeCodec.encode(env)
+
+    @staticmethod
+    def _payload(message: Any) -> str:
+        value = message.value()
+        if isinstance(value, (bytes, bytearray)):
+            return value.decode("utf-8")
+        return str(value) if value is not None else ""
+
+    # -- Transport ----------------------------------------------------------
+
+    def publish(self, queue: str, body: str) -> None:
+        env = EnvelopeCodec.decode(body)
+        meta = env.get("meta") or {}
+        producer = self._producer_()
+        kwargs: Dict[str, Any] = {"value": body.encode("utf-8"), "headers": self._projection(body)}
+        created_at = meta.get("created_at")
+        if created_at:
+            kwargs["timestamp"] = int(created_at)
+        producer.produce(queue, **kwargs)
+        producer.poll(0)
+
+    def pop(self, queue: str, timeout: float = 1.0) -> Optional[ReceivedMessage]:
+        wait = timeout if timeout and timeout > 0 else 1.0
+        message = self._consumer(queue).poll(wait)
+        if message is None or message.error() is not None:
+            return None
+        body = self._reconcile(self._payload(message), message.headers())
+        return ReceivedMessage(body=body, queue=queue, handle=message)
+
+    def ack(self, message: ReceivedMessage) -> None:
+        if message.handle is None:
+            return
+        self._consumer(message.queue).commit(message=message.handle, asynchronous=False)
+
+    def close(self) -> None:  # pragma: no cover - resource cleanup
+        try:
+            if self._producer is not None:
+                self._producer.flush()
+        except Exception:  # noqa: BLE001 - best-effort cleanup
+            pass
+        for consumer in self._consumers.values():
+            try:
+                consumer.close()
+            except Exception:  # noqa: BLE001 - best-effort cleanup
+                pass

{babelqueue-1.3.0 → babelqueue-1.5.0}/src/babelqueue/transport.py

@@ -91,9 +91,17 @@ def make_transport(broker_url: str) -> Transport:
         from .pulsar_transport import PulsarTransport
 
         return PulsarTransport(broker_url)
+    if scheme == "kafka":
+        from .kafka_transport import KafkaTransport
+
+        return KafkaTransport(broker_url)
+    if scheme in ("artemis", "artemis+ssl"):
+        from .artemis_transport import ArtemisTransport
+
+        return ArtemisTransport(broker_url)
 
     raise BabelQueueError(
         f"Unsupported broker scheme {scheme!r}. Use 'memory://', 'redis://', "
-        "'amqp://', 'sqs://', 'sb://' or 'pulsar://', or pass your own Transport via "
-        "BabelQueue(transport=...)."
+        "'amqp://', 'sqs://', 'sb://', 'pulsar://', 'kafka://' or 'artemis://', or pass your "
+        "own Transport via BabelQueue(transport=...)."
     )

{babelqueue-1.3.0 → babelqueue-1.5.0}/tests/conformance/manifest.json

@@ -148,5 +148,57 @@
         { "name": "native-equals-body",        "body_attempts": 3, "redelivery_count": 3, "expected_attempts": 3 }
       ]
     }
+  },
+  "kafka": {
+    "description": "Apache Kafka binding conformance (broker-bindings.md §6). Every SDK that ships a Kafka transport must satisfy these. The record value is the byte-identical envelope (the 'cases' above); these lock the bq- header projection + the bq-attempts-authoritative reconciliation the binding adds. Per-message values reuse fixtures/order-created.json so the expected projection is deterministic.",
+    "property_projection": {
+      "description": "On produce, the transport MUST project these native Kafka record headers from the envelope, all UTF-8 byte strings (Kafka headers are bytes, so integers are stringified): bq-job = job (the URN), bq-trace-id = trace_id, bq-message-id = meta.id, bq-schema-version = str(meta.schema_version), bq-source-lang = meta.lang, bq-attempts = str(attempts). The record value is the byte-identical envelope and the record timestamp mirrors meta.created_at (Unix ms). Applies to every Kafka-producing SDK.",
+      "envelope_file": "fixtures/order-created.json",
+      "headers": {
+        "bq-job":            "urn:babel:orders:created",
+        "bq-trace-id":       "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b",
+        "bq-message-id":     "f1e2d3c4-b5a6-4789-90ab-cdef01234567",
+        "bq-schema-version": "1",
+        "bq-source-lang":    "php",
+        "bq-attempts":       "0"
+      }
+    },
+    "attempts_reconciliation": {
+      "description": "On consume, attempts = the bq-attempts header when present (AUTHORITATIVE — Kafka has no native delivery count), else the body's own attempts (the fallback for a non-BabelQueue producer). This is NOT a max: the header overrides the body even when lower. A null header_attempts means the header is absent. The rule is identical across all five Kafka SDKs.",
+      "cases": [
+        { "name": "header-matches-body",            "body_attempts": 0, "header_attempts": 0,    "expected_attempts": 0 },
+        { "name": "header-present",                 "body_attempts": 0, "header_attempts": 2,    "expected_attempts": 2 },
+        { "name": "header-absent-falls-back",       "body_attempts": 3, "header_attempts": null, "expected_attempts": 3 },
+        { "name": "header-authoritative-overrides", "body_attempts": 5, "header_attempts": 1,    "expected_attempts": 1 },
+        { "name": "header-higher-than-body",        "body_attempts": 1, "header_attempts": 4,    "expected_attempts": 4 }
+      ]
+    }
+  },
+  "artemis": {
+    "description": "Apache ActiveMQ Artemis binding conformance (broker-bindings.md §7). Every SDK that ships an Artemis transport must satisfy these. The message body stays byte-identical (the 'cases' above); these lock the AMQP-1.0 projection + reconciliation the binding adds. Per-message values reuse fixtures/order-created.json so the expected projection is deterministic.",
+    "property_projection": {
+      "description": "On produce, the transport MUST project the envelope onto the AMQP a JMS peer reads: the x-opt-jms-type message annotation = job (the URN, the AMQP-JMS mapping of JMSType), correlation-id = trace_id (JMSCorrelationID), creation-time = meta.created_at (JMSTimestamp, Unix ms), plus the bq_ application properties, all string-valued. The names use UNDERSCORES (bq_schema_version, not bq-schema-version): JMS property names must be valid Java identifiers (no hyphens), and the Java binding consumes/produces over JMS, so every Artemis SDK uses the JMS-legal underscore form for cross-protocol parity. bq_schema_version = str(meta.schema_version), bq_source_lang = meta.lang, bq_attempts = str(attempts), bq_app_id = 'babelqueue'. The body is the byte-identical envelope. Unlike Kafka/Pulsar, the URN / trace_id / message-id are NOT bq_ properties — they ride the JMS-native slots. Applies to every Artemis-producing SDK.",
+      "envelope_file": "fixtures/order-created.json",
+      "jms_type_annotation": "x-opt-jms-type",
+      "jms_type": "urn:babel:orders:created",
+      "correlation_id": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b",
+      "properties": {
+        "bq_schema_version": "1",
+        "bq_source_lang":    "php",
+        "bq_attempts":       "0",
+        "bq_app_id":         "babelqueue"
+      }
+    },
+    "attempts_reconciliation": {
+      "description": "On consume, attempts = max(body.attempts, delivery-count): the AMQP delivery-count header is 0-based (0 on first delivery) so it maps directly with NO -1, a runtime-incremented body count is never lowered, and delivery-count 0 leaves the body's own count untouched (the runtime/App retries by republishing with attempts+1, which resets the broker's delivery-count to 0). The Java JMS binding reads the 1-based JMSXDeliveryCount and subtracts 1, arriving at the same 0-based attempts. The rule is identical across the native-consumer SDKs (.NET/Java/Node) and the Transport+App SDKs (Python/Go).",
+      "cases": [
+        { "name": "first-delivery",           "body_attempts": 0, "delivery_count": 0, "expected_attempts": 0 },
+        { "name": "third-delivery",            "body_attempts": 0, "delivery_count": 2, "expected_attempts": 2 },
+        { "name": "native-exceeds-body",       "body_attempts": 2, "delivery_count": 5, "expected_attempts": 5 },
+        { "name": "never-lower-runtime",       "body_attempts": 5, "delivery_count": 1, "expected_attempts": 5 },
+        { "name": "first-delivery-keeps-body", "body_attempts": 4, "delivery_count": 0, "expected_attempts": 4 },
+        { "name": "native-equals-body",        "body_attempts": 3, "delivery_count": 3, "expected_attempts": 3 }
+      ]
+    }
   }
 }

{babelqueue-1.3.0 → babelqueue-1.5.0}/tests/test_app.py

@@ -118,7 +118,7 @@ class AppTest(unittest.TestCase):
         from babelqueue import BabelQueueError
 
         with self.assertRaises(BabelQueueError):
-            BabelQueue("kafka://localhost:9092")
+            BabelQueue("frobnicate://localhost:9092")
 
 
 if __name__ == "__main__":

babelqueue-1.5.0/tests/test_artemis_conformance.py

@@ -0,0 +1,50 @@
+"""Apache ActiveMQ Artemis binding conformance: the vendored manifest's ``artemis`` block locks
+the §7 AMQP projection (the string-valued ``bq-`` application properties + the JMS-native
+``x-opt-jms-type`` / ``correlation-id`` mappings) and the ``attempts = max(body, delivery_count)``
+reconciliation (the AMQP delivery-count is 0-based, so no −1). No qpid-proton, no broker — pure
+transport logic against golden values."""
+
+from __future__ import annotations
+
+import json
+import os
+import unittest
+
+from babelqueue import EnvelopeCodec
+from babelqueue.artemis_transport import ArtemisTransport
+
+CONFORMANCE = os.path.join(os.path.dirname(__file__), "conformance")
+
+
+class ArtemisConformanceTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        with open(os.path.join(CONFORMANCE, "manifest.json"), encoding="utf-8") as fh:
+            cls.artemis = json.load(fh)["artemis"]
+
+    def test_property_projection(self) -> None:
+        projection = self.artemis["property_projection"]
+        with open(os.path.join(CONFORMANCE, projection["envelope_file"]), encoding="utf-8") as fh:
+            body = fh.read()
+
+        self.assertEqual(ArtemisTransport._projection(body), projection["properties"])
+        self.assertEqual(ArtemisTransport._jms_type(body), projection["jms_type"])
+        self.assertEqual(ArtemisTransport._correlation_id(body), projection["correlation_id"])
+
+    def test_attempts_reconciliation(self) -> None:
+        for case in self.artemis["attempts_reconciliation"]["cases"]:
+            env = EnvelopeCodec.make("urn:babel:orders:created", {"x": 1})
+            env["attempts"] = case["body_attempts"]
+            body = EnvelopeCodec.encode(env)
+
+            out = ArtemisTransport._reconcile(body, case["delivery_count"])
+
+            self.assertEqual(
+                EnvelopeCodec.decode(out)["attempts"],
+                case["expected_attempts"],
+                case["name"],
+            )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()

babelqueue-1.5.0/tests/test_artemis_transport.py

@@ -0,0 +1,205 @@
+"""Apache ActiveMQ Artemis (AMQP 1.0) transport tests.
+
+The projection helpers, the ``attempts = max(body, delivery_count)`` reconciliation (no -1,
+the AMQP counter is 0-based), and the pop/ack reservation flow run with no broker and no
+``python-qpid-proton`` (the transport's proton import is lazy). The publish flow, which builds a
+real proton ``Message``, is skipped unless ``python-qpid-proton`` is installed.
+"""
+
+from __future__ import annotations
+
+import unittest
+from unittest import mock
+
+from babelqueue import EnvelopeCodec
+from babelqueue.artemis_transport import ArtemisTransport
+from babelqueue.transport import ReceivedMessage, make_transport
+
+try:
+    import proton  # noqa: F401
+
+    HAVE_PROTON = True
+except ImportError:
+    HAVE_PROTON = False
+
+URN = "urn:babel:orders:created"
+
+
+def body(attempts: int = 0, trace_id: str = "trace-1") -> str:
+    env = EnvelopeCodec.make(URN, {"order_id": 1042}, queue="orders", trace_id=trace_id)
+    env["attempts"] = attempts
+    return EnvelopeCodec.encode(env)
+
+
+class FakeMessage:
+    """Duck-typed proton Message for the consume path (no proton needed)."""
+
+    def __init__(self, raw: str, delivery_count: int = 0) -> None:
+        self.body = raw
+        self.delivery_count = delivery_count
+
+
+class Timeout(Exception):
+    """Stands in for proton.Timeout — matched by class name, like the real transport."""
+
+
+class FakeSender:
+    def __init__(self) -> None:
+        self.sent: list = []
+
+    def send(self, message) -> None:
+        self.sent.append(message)
+
+
+class FakeReceiver:
+    def __init__(self, messages=()) -> None:
+        self._messages = list(messages)
+        self.accepted = 0
+
+    def receive(self, timeout=None):
+        if not self._messages:
+            raise Timeout("no message")
+        return self._messages.pop(0)
+
+    def accept(self) -> None:
+        self.accepted += 1
+
+
+class FakeConnection:
+    def __init__(self, sender=None, receiver=None) -> None:
+        self._sender = sender if sender is not None else FakeSender()
+        self._receiver = receiver if receiver is not None else FakeReceiver()
+        self.closed = False
+
+    def create_sender(self, address):
+        return self._sender
+
+    def create_receiver(self, address, credit=1):
+        return self._receiver
+
+    def close(self) -> None:
+        self.closed = True
+
+
+class ArtemisProjectionTest(unittest.TestCase):
+    def test_application_properties_mirror_the_contract_fields(self) -> None:
+        props = ArtemisTransport._projection(body(attempts=2))
+        self.assertEqual("1", props["bq_schema_version"])
+        self.assertEqual("python", props["bq_source_lang"])
+        self.assertEqual("2", props["bq_attempts"])
+        self.assertEqual("babelqueue", props["bq_app_id"])
+        # The URN and trace_id ride JMS-native slots, not application properties.
+        self.assertNotIn("bq_job", props)
+        self.assertNotIn("bq_trace_id", props)
+
+    def test_jms_type_and_correlation_id_come_from_the_body(self) -> None:
+        self.assertEqual(URN, ArtemisTransport._jms_type(body()))
+        self.assertEqual("trace-1", ArtemisTransport._correlation_id(body(trace_id="trace-1")))
+
+    def test_creation_time_is_seconds_from_created_at_millis(self) -> None:
+        raw = body()
+        created_at = EnvelopeCodec.decode(raw)["meta"]["created_at"]
+        self.assertAlmostEqual(created_at / 1000.0, ArtemisTransport._creation_seconds(raw))
+
+    def test_projection_helpers_tolerate_garbage(self) -> None:
+        self.assertEqual({}, ArtemisTransport._projection("not-json"))
+        self.assertEqual("", ArtemisTransport._jms_type("not-json"))
+        self.assertEqual("", ArtemisTransport._correlation_id("not-json"))
+        self.assertIsNone(ArtemisTransport._creation_seconds("not-json"))
+
+
+class ArtemisReconcileTest(unittest.TestCase):
+    def test_first_delivery_keeps_body_count(self) -> None:
+        self.assertEqual(0, EnvelopeCodec.decode(ArtemisTransport._reconcile(body(0), 0))["attempts"])
+
+    def test_delivery_count_raises_attempts_no_minus_one(self) -> None:
+        # AMQP delivery-count is 0-based: count 3 == 3 prior redeliveries == attempts 3.
+        out = ArtemisTransport._reconcile(body(0), 3)
+        self.assertEqual(3, EnvelopeCodec.decode(out)["attempts"])
+
+    def test_body_count_never_lowered_by_delivery_count(self) -> None:
+        out = ArtemisTransport._reconcile(body(5), 2)
+        self.assertEqual(5, EnvelopeCodec.decode(out)["attempts"])
+
+    def test_non_numeric_delivery_count_is_ignored(self) -> None:
+        raw = body(1)
+        self.assertEqual(raw, ArtemisTransport._reconcile(raw, None))
+
+
+class ArtemisConsumeTest(unittest.TestCase):
+    def test_pop_reconciles_and_acks_via_the_receiver(self) -> None:
+        receiver = FakeReceiver([FakeMessage(body(0), delivery_count=2)])
+        transport = ArtemisTransport(connection=FakeConnection(receiver=receiver))
+
+        message = transport.pop("orders")
+        self.assertIsNotNone(message)
+        self.assertEqual(2, EnvelopeCodec.decode(message.body)["attempts"])
+
+        transport.ack(message)
+        self.assertEqual(1, receiver.accepted)
+
+    def test_pop_returns_none_on_timeout(self) -> None:
+        transport = ArtemisTransport(connection=FakeConnection(receiver=FakeReceiver([])))
+        self.assertIsNone(transport.pop("orders"))
+
+    def test_pop_propagates_non_timeout_errors(self) -> None:
+        class Broken:
+            def receive(self, timeout=None):
+                raise ConnectionError("link detached")
+
+        transport = ArtemisTransport(connection=FakeConnection(receiver=Broken()))
+        with self.assertRaises(ConnectionError):
+            transport.pop("orders")
+
+    def test_pop_decodes_bytes_payload(self) -> None:
+        receiver = FakeReceiver([FakeMessage(body(0).encode("utf-8"))])
+        transport = ArtemisTransport(connection=FakeConnection(receiver=receiver))
+        self.assertEqual(URN, EnvelopeCodec.decode(transport.pop("orders").body)["job"])
+
+    def test_ack_without_handle_is_a_no_op(self) -> None:
+        transport = ArtemisTransport(connection=FakeConnection())
+        transport.ack(ReceivedMessage(body=body(), queue="orders", handle=None))  # no raise
+
+    def test_close_closes_the_connection(self) -> None:
+        connection = FakeConnection()
+        transport = ArtemisTransport(connection=connection)
+        transport.close()
+        self.assertTrue(connection.closed)
+
+
+class ArtemisUrlTest(unittest.TestCase):
+    def test_scheme_is_translated_to_proton(self) -> None:
+        self.assertEqual("amqp://h:5672", ArtemisTransport._to_amqp_url("artemis://h:5672"))
+        self.assertEqual("amqps://h:5671", ArtemisTransport._to_amqp_url("artemis+ssl://h:5671"))
+        self.assertEqual("amqp://h:5672", ArtemisTransport._to_amqp_url("amqp://h:5672"))
+
+    def test_factory_resolves_the_artemis_scheme(self) -> None:
+        # Patch the connection build so the scheme is exercised without opening a socket
+        # (whether or not python-qpid-proton is installed).
+        with mock.patch.object(ArtemisTransport, "_build_connection", return_value=FakeConnection()):
+            for url in ("artemis://localhost:5672", "artemis+ssl://localhost:5671"):
+                self.assertIsInstance(make_transport(url), ArtemisTransport)
+
+
+@unittest.skipUnless(HAVE_PROTON, "python-qpid-proton not installed")
+class ArtemisPublishTest(unittest.TestCase):
+    def test_publish_projects_the_envelope_onto_a_proton_message(self) -> None:
+        from proton import symbol
+
+        sender = FakeSender()
+        transport = ArtemisTransport(connection=FakeConnection(sender=sender))
+
+        transport.publish("orders", body(attempts=0, trace_id="trace-xyz"))
+
+        self.assertEqual(1, len(sender.sent))
+        message = sender.sent[0]
+        self.assertEqual("trace-xyz", message.correlation_id)
+        self.assertEqual("1", message.properties["bq_schema_version"])
+        self.assertEqual("babelqueue", message.properties["bq_app_id"])
+        self.assertEqual(URN, dict(message.annotations)[symbol("x-opt-jms-type")])
+        # The body is the byte-identical canonical envelope.
+        self.assertEqual(URN, EnvelopeCodec.decode(message.body)["job"])
+
+
+if __name__ == "__main__":
+    unittest.main()

babelqueue-1.5.0/tests/test_kafka_conformance.py

@@ -0,0 +1,52 @@
+"""Apache Kafka binding conformance: the vendored manifest's ``kafka`` block locks the §6
+header projection (bq-* UTF-8 byte strings) and the ``attempts`` reconciliation (the
+``bq-attempts`` header is authoritative when present, else the body — NOT a max). No
+confluent-kafka, no broker — pure transport logic against golden values."""
+
+from __future__ import annotations
+
+import json
+import os
+import unittest
+
+from babelqueue import EnvelopeCodec
+from babelqueue.kafka_transport import KafkaTransport
+
+CONFORMANCE = os.path.join(os.path.dirname(__file__), "conformance")
+
+
+class KafkaConformanceTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        with open(os.path.join(CONFORMANCE, "manifest.json"), encoding="utf-8") as fh:
+            cls.kafka = json.load(fh)["kafka"]
+
+    def test_property_projection(self) -> None:
+        projection = self.kafka["property_projection"]
+        with open(os.path.join(CONFORMANCE, projection["envelope_file"]), encoding="utf-8") as fh:
+            body = fh.read()
+
+        got = {key: value.decode("utf-8") for key, value in KafkaTransport._projection(body)}
+        self.assertEqual(got, projection["headers"])
+
+    def test_attempts_reconciliation(self) -> None:
+        for case in self.kafka["attempts_reconciliation"]["cases"]:
+            env = EnvelopeCodec.make("urn:babel:orders:created", {"x": 1})
+            env["attempts"] = case["body_attempts"]
+            body = EnvelopeCodec.encode(env)
+
+            headers = []
+            if case["header_attempts"] is not None:
+                headers = [("bq-attempts", str(case["header_attempts"]).encode("utf-8"))]
+
+            out = KafkaTransport._reconcile(body, headers)
+
+            self.assertEqual(
+                EnvelopeCodec.decode(out)["attempts"],
+                case["expected_attempts"],
+                case["name"],
+            )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()

babelqueue-1.5.0/tests/test_kafka_transport.py

@@ -0,0 +1,171 @@
+"""Apache Kafka transport tests.
+
+The header projection and the ``attempts`` reconciliation (authoritative ``bq-attempts``
+header, body fallback) — and the full publish / pop / ack flow — run with no broker and no
+``confluent-kafka`` (the kafka import is lazy and the transport talks to injected
+producer/consumer fakes). Only ``_build_producer``/``_build_consumer`` need the real package.
+"""
+
+from __future__ import annotations
+
+import unittest
+
+from babelqueue import EnvelopeCodec
+from babelqueue.kafka_transport import KafkaTransport
+from babelqueue.transport import ReceivedMessage, make_transport
+
+URN = "urn:babel:orders:created"
+
+
+def body(attempts: int = 0) -> str:
+    env = EnvelopeCodec.decode(
+        EnvelopeCodec.encode(EnvelopeCodec.make(URN, {"order_id": 1042}, queue="orders"))
+    )
+    env["attempts"] = attempts
+    return EnvelopeCodec.encode(env)
+
+
+def header_map(headers):
+    return {k: (v.decode("utf-8") if isinstance(v, (bytes, bytearray)) else v) for k, v in headers}
+
+
+class FakeMessage:
+    def __init__(self, value, headers=None, err=None) -> None:
+        self._value = value
+        self._headers = headers or []
+        self._err = err
+
+    def value(self):
+        return self._value
+
+    def headers(self):
+        return self._headers
+
+    def error(self):
+        return self._err
+
+
+class FakeProducer:
+    def __init__(self) -> None:
+        self.produced = []
+
+    def produce(self, topic, value=None, headers=None, timestamp=None, **kw) -> None:
+        self.produced.append({"topic": topic, "value": value, "headers": headers, "timestamp": timestamp})
+
+    def poll(self, _t):
+        return 0
+
+    def flush(self, *a):
+        return 0
+
+
+class FakeConsumer:
+    def __init__(self, messages=()) -> None:
+        self._messages = list(messages)
+        self.committed = []
+
+    def poll(self, timeout=None):
+        return self._messages.pop(0) if self._messages else None
+
+    def commit(self, message=None, asynchronous=True) -> None:
+        self.committed.append(message)
+
+    def close(self) -> None:
+        pass
+
+
+def transport(producer=None, consumer=None) -> KafkaTransport:
+    producer = producer if producer is not None else FakeProducer()
+    consumer = consumer if consumer is not None else FakeConsumer()
+    return KafkaTransport(producer=producer, consumer_factory=lambda _q: consumer)
+
+
+class KafkaProjectionTest(unittest.TestCase):
+    def test_projection_maps_contract_headers(self):
+        raw = body()
+        env = EnvelopeCodec.decode(raw)
+        headers = header_map(KafkaTransport._projection(raw))
+
+        self.assertEqual(headers["bq-job"], URN)
+        self.assertEqual(headers["bq-trace-id"], env["trace_id"])
+        self.assertEqual(headers["bq-message-id"], env["meta"]["id"])
+        self.assertEqual(headers["bq-schema-version"], str(env["meta"]["schema_version"]))
+        self.assertEqual(headers["bq-source-lang"], env["meta"]["lang"])
+        self.assertEqual(headers["bq-attempts"], "0")
+
+    def test_projection_values_are_bytes(self):
+        for _key, value in KafkaTransport._projection(body(3)):
+            self.assertIsInstance(value, bytes)
+
+    def test_projection_of_garbage_is_empty(self):
+        self.assertEqual(KafkaTransport._projection("not-json"), [])
+
+    def test_reconcile_header_is_authoritative(self):
+        out = KafkaTransport._reconcile(body(0), [("bq-attempts", b"2")])
+        self.assertEqual(EnvelopeCodec.decode(out)["attempts"], 2)
+
+    def test_reconcile_absent_header_falls_back_to_body(self):
+        raw = body(3)
+        self.assertEqual(KafkaTransport._reconcile(raw, []), raw)
+
+    def test_reconcile_garbage_header_falls_back(self):
+        raw = body(3)
+        self.assertEqual(KafkaTransport._reconcile(raw, [("bq-attempts", b"x")]), raw)
+
+
+class KafkaPublishTest(unittest.TestCase):
+    def test_publish_writes_value_headers_and_timestamp(self):
+        raw = body()
+        env = EnvelopeCodec.decode(raw)
+        producer = FakeProducer()
+        transport(producer=producer).publish("orders", raw)
+
+        self.assertEqual(len(producer.produced), 1)
+        rec = producer.produced[0]
+        self.assertEqual(rec["topic"], "orders")
+        self.assertEqual(rec["value"], raw.encode("utf-8"))
+        self.assertEqual(rec["timestamp"], env["meta"]["created_at"])
+        self.assertEqual(header_map(rec["headers"])["bq-job"], URN)
+
+
+class KafkaConsumeTest(unittest.TestCase):
+    def test_pop_reconciles_attempts_and_returns_handle(self):
+        message = FakeMessage(body(0).encode("utf-8"), headers=[("bq-attempts", b"2")])
+        consumer = FakeConsumer([message])
+        tr = transport(consumer=consumer)
+
+        msg = tr.pop("orders")
+
+        self.assertIsNotNone(msg)
+        self.assertIs(msg.handle, message)
+        self.assertEqual(EnvelopeCodec.decode(msg.body)["attempts"], 2)
+
+    def test_pop_empty_returns_none(self):
+        self.assertIsNone(transport(consumer=FakeConsumer([])).pop("orders"))
+
+    def test_pop_error_returns_none(self):
+        message = FakeMessage(body().encode("utf-8"), err="partition eof")
+        self.assertIsNone(transport(consumer=FakeConsumer([message])).pop("orders"))
+
+    def test_ack_commits_the_reserved_message(self):
+        message = FakeMessage(body().encode("utf-8"))
+        consumer = FakeConsumer([message])
+        tr = transport(consumer=consumer)
+
+        tr.ack(tr.pop("orders"))
+
+        self.assertEqual(consumer.committed, [message])
+
+    def test_ack_noop_without_handle(self):
+        transport().ack(ReceivedMessage(body="", queue="orders", handle=None))  # no error
+
+
+class KafkaSchemeTest(unittest.TestCase):
+    def test_make_transport_routes_kafka_scheme_lazily(self):
+        # Construction is lazy (no client built), so it succeeds with no confluent-kafka.
+        tr = make_transport("kafka://localhost:9092")
+        self.assertIsInstance(tr, KafkaTransport)
+
+
+if __name__ == "__main__":
+    unittest.main()