|
| 1 | +"""Live-Kafka integration tests (opt-in). |
| 2 | +
|
| 3 | +Skipped in the normal suite. Enable with ``BQ_INTEGRATION=1`` and (optionally) ``BQ_KAFKA_BROKERS`` |
| 4 | +(default ``localhost:9092``); requires the ``kafka`` extra (``confluent-kafka``). They exercise the |
| 5 | +real ``confluent_kafka`` produce / poll / commit / seek paths that the fake-based tests in |
| 6 | +``test_kafka_transport.py`` cannot. Every test uses unique topic names and a unique consumer group. |
| 7 | +
|
| 8 | +Scenarios: (1) a handler error is retried up to ``max_attempts`` and then dead-lettered to |
| 9 | +``<queue>.dlq`` with a ``dead_letter`` block; (2) a record whose ``bq-schema-version`` header is |
| 10 | +``"2"`` is gated before any decode and dead-lettered directly, never reaching a handler. |
| 11 | +""" |
| 12 | + |
| 13 | +from __future__ import annotations |
| 14 | + |
| 15 | +import json |
| 16 | +import os |
| 17 | +import time |
| 18 | +import unittest |
| 19 | +import uuid |
| 20 | +from typing import Any, Dict, List, Optional |
| 21 | + |
| 22 | +from babelqueue import BabelQueue |
| 23 | +from babelqueue.kafka_transport import KafkaTransport |
| 24 | + |
| 25 | +URN = "urn:babel:orders:created" |
| 26 | +ENABLED = os.environ.get("BQ_INTEGRATION") == "1" |
| 27 | +BROKERS = os.environ.get("BQ_KAFKA_BROKERS", "localhost:9092") |
| 28 | +DEADLINE_SECONDS = 90.0 |
| 29 | + |
| 30 | + |
| 31 | +def _create_topics(*topics: str) -> None: |
| 32 | + from confluent_kafka.admin import AdminClient, NewTopic |
| 33 | + |
| 34 | + admin = AdminClient({"bootstrap.servers": BROKERS}) |
| 35 | + futures = admin.create_topics([NewTopic(t, num_partitions=1, replication_factor=1) for t in topics]) |
| 36 | + for future in futures.values(): |
| 37 | + future.result(30) |
| 38 | + |
| 39 | + |
| 40 | +def _pop_until(transport: KafkaTransport, queue: str) -> Optional[Dict[str, Any]]: |
| 41 | + """Poll ``queue`` until a record arrives (or the deadline passes); ack it and return its decoded |
| 42 | + envelope. The ack matters: an un-acked record is "abandoned" and the next ``pop`` seeks back to |
| 43 | + it, so a later ``pop`` would hand the very same record out again.""" |
| 44 | + stop = time.monotonic() + DEADLINE_SECONDS |
| 45 | + while time.monotonic() < stop: |
| 46 | + received = transport.pop(queue, timeout=2.0) |
| 47 | + if received is not None: |
| 48 | + transport.ack(received) |
| 49 | + return json.loads(received.body) |
| 50 | + return None |
| 51 | + |
| 52 | + |
| 53 | +@unittest.skipUnless(ENABLED, "live-broker test: set BQ_INTEGRATION=1 (and BQ_KAFKA_BROKERS) to run") |
| 54 | +class KafkaLiveIntegrationTest(unittest.TestCase): |
| 55 | + def setUp(self) -> None: |
| 56 | + suffix = uuid.uuid4().hex[:8] |
| 57 | + self.queue = f"bq-it-orders-{suffix}" |
| 58 | + self.dlq = f"{self.queue}.dlq" |
| 59 | + self.group = f"bq-it-group-{suffix}" |
| 60 | + _create_topics(self.queue, self.dlq) |
| 61 | + self.transports: List[KafkaTransport] = [] |
| 62 | + |
| 63 | + def tearDown(self) -> None: |
| 64 | + for transport in self.transports: |
| 65 | + transport.close() |
| 66 | + |
| 67 | + def _transport(self, group: Optional[str] = None) -> KafkaTransport: |
| 68 | + transport = KafkaTransport(f"kafka://{BROKERS}", group_id=group or self.group) |
| 69 | + self.transports.append(transport) |
| 70 | + return transport |
| 71 | + |
| 72 | + def test_handler_error_retries_then_dead_letters_after_max_attempts(self) -> None: |
| 73 | + calls: List[int] = [] |
| 74 | + app = BabelQueue( |
| 75 | + transport=self._transport(), queue=self.queue, max_attempts=3, dead_letter=True |
| 76 | + ) |
| 77 | + |
| 78 | + @app.handler(URN) |
| 79 | + def boom(data: Dict[str, Any], meta: Dict[str, Any]) -> None: |
| 80 | + calls.append(1) |
| 81 | + raise RuntimeError("boom") |
| 82 | + |
| 83 | + app.publish(URN, {"order_id": 7}, trace_id="trace-it-1") |
| 84 | + |
| 85 | + stop = time.monotonic() + DEADLINE_SECONDS |
| 86 | + while len(calls) < 3 and time.monotonic() < stop: |
| 87 | + app.consume(self.queue, max_messages=1, timeout=2.0, handle_signals=False) |
| 88 | + self.assertEqual(len(calls), 3) |
| 89 | + |
| 90 | + envelope = _pop_until(self._transport(f"{self.group}-dlq"), self.dlq) |
| 91 | + self.assertIsNotNone(envelope, f"nothing arrived on {self.dlq}") |
| 92 | + assert envelope is not None # for the type checker |
| 93 | + self.assertIn("dead_letter", envelope) |
| 94 | + self.assertEqual(envelope["dead_letter"]["reason"], "failed") |
| 95 | + self.assertEqual(envelope["dead_letter"]["original_queue"], self.queue) |
| 96 | + self.assertEqual(envelope["trace_id"], "trace-it-1") |
| 97 | + self.assertEqual(envelope["data"], {"order_id": 7}) |
| 98 | + |
| 99 | + def test_schema_version_gate_rejection_dead_letters_without_running_a_handler(self) -> None: |
| 100 | + from confluent_kafka import Producer |
| 101 | + |
| 102 | + calls: List[int] = [] |
| 103 | + app = BabelQueue( |
| 104 | + transport=self._transport(), queue=self.queue, max_attempts=3, dead_letter=True |
| 105 | + ) |
| 106 | + |
| 107 | + @app.handler(URN) |
| 108 | + def should_not_run(data: Dict[str, Any], meta: Dict[str, Any]) -> None: |
| 109 | + calls.append(1) |
| 110 | + |
| 111 | + # The §6.7 gate decides on the *header* alone, before the body is decoded. The body here is |
| 112 | + # deliberately not a v1 envelope (a "future format"), so this also proves the gate never |
| 113 | + # tries to decode it. Per the gate design, Python annotates the rejection as an |
| 114 | + # ``unknown_urn`` dead-letter record built from whatever the body decodes to (here: nothing). |
| 115 | + raw = f"future-format-{self.queue}".encode("utf-8") |
| 116 | + producer = Producer({"bootstrap.servers": BROKERS}) |
| 117 | + producer.produce( |
| 118 | + self.queue, |
| 119 | + value=raw, |
| 120 | + headers=[("bq-job", URN.encode()), ("bq-schema-version", b"2")], |
| 121 | + ) |
| 122 | + producer.flush(30) |
| 123 | + |
| 124 | + processed = 0 |
| 125 | + stop = time.monotonic() + DEADLINE_SECONDS |
| 126 | + while processed == 0 and time.monotonic() < stop: |
| 127 | + processed = app.consume(self.queue, max_messages=1, timeout=2.0, handle_signals=False) |
| 128 | + self.assertEqual(processed, 1) |
| 129 | + |
| 130 | + dlq_transport = self._transport(f"{self.group}-dlq") |
| 131 | + envelope = _pop_until(dlq_transport, self.dlq) |
| 132 | + self.assertIsNotNone(envelope, f"nothing arrived on {self.dlq}") |
| 133 | + assert envelope is not None # for the type checker |
| 134 | + self.assertEqual(calls, []) |
| 135 | + block = envelope["dead_letter"] |
| 136 | + self.assertEqual(block["reason"], "unknown_urn") |
| 137 | + self.assertEqual(block["original_queue"], self.queue) |
| 138 | + self.assertEqual(block["attempts"], 0) |
| 139 | + self.assertEqual(block["lang"], "python") |
| 140 | + self.assertEqual(block["exception"], "UnknownUrnError") |
| 141 | + self.assertIn("unsupported-schema-version:2", block["error"]) |
| 142 | + |
| 143 | + # Exactly one record was dead-lettered (the gate does not retry or double-write). |
| 144 | + self.assertIsNone(dlq_transport.pop(self.dlq, timeout=3.0), "a second record reached the DLQ") |
| 145 | + |
| 146 | + # The source record was settled: the group's committed offset moved past it. |
| 147 | + self.assertEqual(self._committed_offset(), 1) |
| 148 | + |
| 149 | + def _committed_offset(self) -> int: |
| 150 | + from confluent_kafka import Consumer, TopicPartition |
| 151 | + |
| 152 | + consumer = Consumer( |
| 153 | + {"bootstrap.servers": BROKERS, "group.id": self.group, "enable.auto.commit": False} |
| 154 | + ) |
| 155 | + try: |
| 156 | + stop = time.monotonic() + 30.0 |
| 157 | + offset = -1 |
| 158 | + while time.monotonic() < stop: |
| 159 | + committed = consumer.committed([TopicPartition(self.queue, 0)], timeout=10) |
| 160 | + offset = committed[0].offset |
| 161 | + if offset >= 1: |
| 162 | + break |
| 163 | + time.sleep(0.5) |
| 164 | + return offset |
| 165 | + finally: |
| 166 | + consumer.close() |
0 commit comments