babelqueue 1.7.0__tar.gz → 1.9.0__tar.gz

{babelqueue-1.7.0 → babelqueue-1.9.0}/.github/workflows/ci.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Install (with Celery + Django adapters)
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,celery,django]"
+          pip install -e ".[dev,celery,django,otel]" opentelemetry-sdk
 
       - name: Run tests
         run: pytest
@@ -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,artemis]"
+          pip install -e ".[dev,celery,django,redis,amqp,sqs,azureservicebus,artemis,otel]" opentelemetry-sdk
       - 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,artemis,celery,django,dev]"
+          pip install -e ".[redis,amqp,sqs,azureservicebus,artemis,celery,django,dev,otel]" opentelemetry-sdk
 
       - name: Wait for ElasticMQ
         run: |

{babelqueue-1.7.0 → babelqueue-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: babelqueue
-Version: 1.7.0
+Version: 1.9.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
@@ -40,6 +40,8 @@ Provides-Extra: django
 Requires-Dist: django>=4.2; extra == 'django'
 Provides-Extra: kafka
 Requires-Dist: confluent-kafka>=2.3; extra == 'kafka'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
 Provides-Extra: pulsar
 Requires-Dist: pulsar-client>=3.4; extra == 'pulsar'
 Provides-Extra: redis

{babelqueue-1.7.0 → babelqueue-1.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.7.0"
+version = "1.9.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"
@@ -36,6 +36,7 @@ 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"]
+otel = ["opentelemetry-api>=1.20"]
 celery = ["celery>=5"]
 django = ["django>=4.2"]
 dev = ["pytest>=7", "pytest-cov>=4", "mypy>=1.8", "ruff>=0.5"]

{babelqueue-1.7.0 → babelqueue-1.9.0}/src/babelqueue/__init__.py

@@ -11,7 +11,7 @@ and dead-letter helpers. Framework adapters (Celery, Django, ...) build on this.
 
 from __future__ import annotations
 
-from . import dead_letter, idempotency
+from . import dead_letter, idempotency, redrive
 from .app import BabelQueue
 from .codec import SCHEMA_VERSION, SOURCE_LANG, EnvelopeCodec
 from .contracts import HasTraceId, PolyglotMessage
@@ -37,6 +37,7 @@ __all__ = [
     "UnknownUrnError",
     "dead_letter",
     "idempotency",
+    "redrive",
     "IdempotencyStore",
     "InMemoryStore",
     "__version__",

babelqueue-1.9.0/src/babelqueue/otel.py

@@ -0,0 +1,176 @@
+"""Optional OpenTelemetry tracing (ADR-0025): produce/consume spans correlated across hops.
+
+The Python mirror of the Go ``babelqueue-go/otel`` module. It emits a CONSUMER span per
+handled message and a PRODUCER span per publish, correlating them across every hop and SDK
+through the envelope's ``trace_id`` — a UUID, which maps 1:1 to a 128-bit OTel trace id. The
+wire envelope is untouched (GR-1) and the core never imports OpenTelemetry: this module is
+only importable with the ``[otel]`` extra (``pip install babelqueue[otel]``), exactly like the
+optional transport drivers.
+
+    from opentelemetry import trace
+    from babelqueue import BabelQueue, otel
+
+    tracer = trace.get_tracer("orders")
+    app = BabelQueue("redis://localhost:6379/0", queue="orders")
+    app.register("urn:babel:orders:created", otel.wrap_handler(tracer, on_order_created))
+    # producer side:
+    otel.publish(tracer, app, "urn:babel:orders:created", {"order_id": 1042})
+
+Every hop that shares a ``trace_id`` shares one OTel trace. Exact cross-hop *span*
+parent-child linkage (W3C ``traceparent`` as a transport header) is a documented follow-up.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import inspect
+from typing import Any, Callable, Mapping, Optional
+
+from opentelemetry.context import Context
+from opentelemetry.trace import (
+    NonRecordingSpan,
+    SpanContext,
+    SpanKind,
+    TraceFlags,
+    Tracer,
+    set_span_in_context,
+)
+
+Handler = Callable[..., None]
+
+_SYSTEM = "babelqueue"
+_MASK_128 = (1 << 128) - 1
+
+
+def trace_id_of(trace_id: str) -> int:
+    """Map an envelope ``trace_id`` to a deterministic 128-bit OTel trace id.
+
+    A UUID maps to its 16 raw bytes; any other string is hashed (SHA-256, first 16 bytes).
+    The result is never zero (OTel's invalid trace id). The inverse of :func:`uuid_of` for
+    the UUID case.
+    """
+    raw = _uuid_bytes(trace_id)
+    if raw is not None:
+        n = int.from_bytes(raw, "big")
+        if n != 0:
+            return n
+    digest = hashlib.sha256(trace_id.encode("utf-8")).digest()[:16]
+    return int.from_bytes(digest, "big") or 1
+
+
+def uuid_of(trace_id_int: int) -> str:
+    """Format a 128-bit OTel trace id as a canonical UUID string.
+
+    The form a producer stamps into the message's ``trace_id`` so a consumer can recover the
+    same trace id via :func:`trace_id_of`.
+    """
+    h = format(trace_id_int & _MASK_128, "032x")
+    return f"{h[0:8]}-{h[8:12]}-{h[12:16]}-{h[16:20]}-{h[20:32]}"
+
+
+def _uuid_bytes(s: str) -> Optional[bytes]:
+    h = s.replace("-", "")
+    if len(h) != 32:
+        return None
+    try:
+        return bytes.fromhex(h)
+    except ValueError:
+        return None
+
+
+def _span_id_of(trace_id: str) -> int:
+    """Derive a deterministic, non-zero 64-bit span id so the remote parent context is valid
+    (a span needs a valid parent to inherit a specific trace)."""
+    digest = hashlib.sha256(("babelqueue-span:" + trace_id).encode("utf-8")).digest()[:8]
+    return int.from_bytes(digest, "big") or 1
+
+
+def _parent_context(trace_id: str) -> Context:
+    sc = SpanContext(
+        trace_id=trace_id_of(trace_id),
+        span_id=_span_id_of(trace_id),
+        is_remote=True,
+        trace_flags=TraceFlags(TraceFlags.SAMPLED),
+    )
+    return set_span_in_context(NonRecordingSpan(sc))
+
+
+def _wants_envelope(fn: Handler) -> bool:
+    """True if ``fn`` takes a 3rd positional arg (the full envelope) or ``*args``."""
+    try:
+        params = list(inspect.signature(fn).parameters.values())
+    except (TypeError, ValueError):  # pragma: no cover - builtins / C callables
+        return False
+    positional = [
+        p for p in params if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+    ]
+    return any(p.kind == p.VAR_POSITIONAL for p in params) or len(positional) >= 3
+
+
+def wrap_handler(tracer: Tracer, handler: Handler) -> Handler:
+    """Wrap a consume handler to emit a CONSUMER span per message, in the OTel trace derived
+    from the envelope's ``trace_id``.
+
+    Register it like any handler: ``app.register(urn, wrap_handler(tracer, handler))``. The
+    wrapper's ``*args`` signature makes the runtime pass the full envelope (``data, meta,
+    envelope``), so it can read ``trace_id``/``job`` even when the inner handler only wants
+    ``(data, meta)``. A raising handler records the exception on the span and re-raises, so the
+    runtime's retry / dead-letter path still applies.
+    """
+
+    def wrapped(*args: Any) -> None:
+        envelope = args[2] if len(args) > 2 and isinstance(args[2], Mapping) else {}
+        meta = args[1] if len(args) > 1 and isinstance(args[1], Mapping) else {}
+        trace_id = str(envelope.get("trace_id") or "")
+        urn = str(envelope.get("job") or envelope.get("urn") or "")
+
+        attributes: dict[str, Any] = {
+            "messaging.system": _SYSTEM,
+            "messaging.operation": "process",
+            "messaging.destination.name": str(meta.get("queue") or ""),
+            "messaging.message.id": str(meta.get("id") or ""),
+            "messaging.message.conversation_id": trace_id,
+            "messaging.babelqueue.attempts": int(envelope.get("attempts", 0) or 0),
+        }
+        context = _parent_context(trace_id) if trace_id else None
+
+        with tracer.start_as_current_span(
+            "process " + urn,
+            context=context,
+            kind=SpanKind.CONSUMER,
+            attributes=attributes,
+        ):
+            if _wants_envelope(handler):
+                handler(*args)
+            else:
+                handler(args[0], args[1])
+
+    return wrapped
+
+
+def publish(
+    tracer: Tracer,
+    app: Any,
+    urn: str,
+    data: Mapping[str, Any],
+    *,
+    queue: Optional[str] = None,
+) -> str:
+    """Publish via a PRODUCER span ``publish <urn>``, carrying the active trace's id into the
+    message's ``trace_id`` so the downstream consumer recovers the same trace.
+
+    Behaves like ``app.publish`` (returns the message id); ``app`` is any object exposing
+    ``publish(urn, data, *, queue=None, trace_id=None) -> str``.
+    """
+    attributes = {
+        "messaging.system": _SYSTEM,
+        "messaging.operation": "publish",
+        "messaging.destination.name": urn,
+    }
+    with tracer.start_as_current_span(
+        "publish " + urn, kind=SpanKind.PRODUCER, attributes=attributes
+    ) as span:
+        trace_id = uuid_of(span.get_span_context().trace_id)
+        message_id = app.publish(urn, data, queue=queue, trace_id=trace_id)
+        span.set_attribute("messaging.message.id", message_id)
+        return message_id

babelqueue-1.9.0/src/babelqueue/redrive.py

@@ -0,0 +1,165 @@
+"""Optional DLQ redrive tooling (ADR-0026): safe replay off the dead-letter queue.
+
+The Python mirror of the Go ``Redrive``. It reads dead-lettered messages off a DLQ and
+re-publishes each to its source queue (its ``dead_letter.original_queue``) or a chosen
+``to_queue``, **reset for reprocessing**: the ``dead_letter`` block is removed and ``attempts``
+reset to 0, while ``job``, ``trace_id``, ``data`` and ``meta`` are preserved verbatim. It is
+the operator-side counterpart to the runtime's dead-letter routing — the contract leaves
+redrive to tooling, and this is that tool.
+
+    from babelqueue import BabelQueue
+    from babelqueue.redrive import redrive
+
+    app = BabelQueue("redis://localhost:6379/0")
+    result = redrive(app.transport, "orders.dlq")                        # back to each source
+    result = redrive(app.transport, "orders.dlq", to_queue="sandbox")    # safe sandbox replay
+    plan = redrive(app.transport, "orders.dlq", dry_run=True)            # inspect, change nothing
+
+Messages are drained from the DLQ first and then processed, so restored messages (skipped,
+dry-run, or undecodable) are never re-encountered in the same run; a DLQ message is
+acknowledged only after a successful re-publish, and an undecodable body is restored, not
+dropped.
+
+Replay safety today is sandbox routing (``to_queue``) + ``dry_run``. The **Replay-Bypass**
+guard — a ``bq-replay-bypass`` transport header surfaced to handlers so a replay can skip
+external side-effects (don't re-charge, don't re-email) — is a documented phase two: like the
+OpenTelemetry ``traceparent`` follow-up, it carries out-of-band metadata as a transport header
+and so touches the runtime + every transport binding. Until then, sandbox routing is the
+safe-replay answer.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Mapping, Optional, Tuple
+
+from .codec import EnvelopeCodec
+from .transport import ReceivedMessage, Transport
+
+Envelope = Mapping[str, Any]
+Select = Callable[[Envelope], bool]
+
+
+@dataclass
+class RedriveItem:
+    """What happened to one message during a redrive run."""
+
+    message_id: str
+    trace_id: str
+    urn: str
+    reason: str
+    from_queue: str
+    to: str  # target queue (the plan, even on a dry run; "" when skipped/undecodable)
+    redriven: bool  # True only when actually re-published to ``to``
+
+
+@dataclass
+class RedriveResult:
+    """Summary of a redrive run."""
+
+    redriven: int = 0
+    skipped: int = 0
+    items: List[RedriveItem] = field(default_factory=list)
+
+
+def redrive(
+    transport: Transport,
+    dlq: str,
+    *,
+    to_queue: Optional[str] = None,
+    max: int = 0,
+    dry_run: bool = False,
+    select: Optional[Select] = None,
+    timeout: float = 1.0,
+) -> RedriveResult:
+    """Move dead-lettered messages off ``dlq`` and replay them; see the module docstring."""
+    # Drain up to ``max`` messages (or all available) before processing any of them.
+    batch: List[Tuple[ReceivedMessage, Optional[Dict[str, Any]]]] = []
+    while max == 0 or len(batch) < max:
+        message = transport.pop(dlq, timeout)
+        if message is None:
+            break
+        batch.append((message, _decoded(message.body)))
+
+    result = RedriveResult()
+    for message, envelope in batch:
+        if envelope is None:
+            transport.publish(dlq, message.body)  # restore the poison body; never drop it
+            transport.ack(message)
+            result.skipped += 1
+            result.items.append(RedriveItem("", "", "", "", dlq, "", False))
+            continue
+
+        meta_raw = envelope.get("meta")
+        meta: Mapping[str, Any] = meta_raw if isinstance(meta_raw, Mapping) else {}
+        dl_raw = envelope.get("dead_letter")
+        dead_letter: Mapping[str, Any] = dl_raw if isinstance(dl_raw, Mapping) else {}
+        item = RedriveItem(
+            message_id=str(meta.get("id", "")),
+            trace_id=str(envelope.get("trace_id", "")),
+            urn=EnvelopeCodec.urn(envelope),
+            reason=str(dead_letter.get("reason", "")),
+            from_queue=dlq,
+            to="",
+            redriven=False,
+        )
+
+        if select is not None and not select(envelope):
+            transport.publish(dlq, message.body)  # not selected: restore unchanged
+            transport.ack(message)
+            result.skipped += 1
+            result.items.append(item)
+            continue
+
+        target = to_queue or _source_queue_of(envelope)
+        item.to = target
+
+        if dry_run:
+            transport.publish(dlq, message.body)  # report the plan; restore unchanged
+            transport.ack(message)
+            result.skipped += 1
+            result.items.append(item)
+            continue
+
+        reset = dict(envelope)
+        reset.pop("dead_letter", None)
+        reset["attempts"] = 0
+        try:
+            transport.publish(target, EnvelopeCodec.encode(reset))
+        except Exception:
+            transport.publish(dlq, message.body)  # restore on a publish failure, then surface
+            transport.ack(message)
+            raise
+        transport.ack(message)
+        item.redriven = True
+        result.redriven += 1
+        result.items.append(item)
+
+    return result
+
+
+def _decoded(body: str) -> Optional[Dict[str, Any]]:
+    """Decode a DLQ body, or None when it is not a redrivable envelope.
+
+    ``EnvelopeCodec.decode`` returns ``{}`` for malformed/non-object input; an object with no
+    string ``job`` is likewise not redrivable.
+    """
+    envelope = EnvelopeCodec.decode(body)
+    if not envelope or not isinstance(envelope.get("job"), str):
+        return None
+    return envelope
+
+
+def _source_queue_of(envelope: Envelope) -> str:
+    """Default redrive target: ``dead_letter.original_queue``, falling back to ``meta.queue``."""
+    dead_letter = envelope.get("dead_letter")
+    if isinstance(dead_letter, Mapping):
+        original = dead_letter.get("original_queue")
+        if isinstance(original, str) and original:
+            return original
+    meta = envelope.get("meta")
+    if isinstance(meta, Mapping):
+        queue = meta.get("queue")
+        if isinstance(queue, str):
+            return queue
+    return ""

babelqueue-1.9.0/tests/test_otel.py

@@ -0,0 +1,131 @@
+"""Tests for the optional OpenTelemetry module (ADR-0025).
+
+Skipped when OpenTelemetry is not installed (the ``[otel]`` extra); CI installs it so these
+run and count toward coverage.
+"""
+
+import pytest
+
+pytest.importorskip("opentelemetry")
+
+from opentelemetry.sdk.trace import TracerProvider  # noqa: E402
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor  # noqa: E402
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import (  # noqa: E402
+    InMemorySpanExporter,
+)
+from opentelemetry.trace import SpanKind  # noqa: E402
+
+from babelqueue import otel  # noqa: E402
+
+_TRACE_ID = "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b"
+
+
+def _recorder():
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    return provider.get_tracer("test"), exporter
+
+
+def _envelope(trace_id=_TRACE_ID, attempts=0):
+    return {
+        "job": "urn:babel:orders:created",
+        "trace_id": trace_id,
+        "data": {"order_id": 1},
+        "meta": {"id": "m1", "queue": "orders"},
+        "attempts": attempts,
+    }
+
+
+class FakeApp:
+    """An object exposing publish(urn, data, *, queue, trace_id) -> str, recording calls."""
+
+    def __init__(self):
+        self.calls = []
+
+    def publish(self, urn, data, *, queue=None, trace_id=None):
+        self.calls.append({"urn": urn, "data": data, "queue": queue, "trace_id": trace_id})
+        return "msg-123"
+
+
+def test_trace_id_round_trip():
+    tid = otel.trace_id_of(_TRACE_ID)
+    assert tid != 0
+    assert otel.uuid_of(tid) == _TRACE_ID
+    # a non-uuid trace_id maps deterministically to a valid, distinct trace id
+    assert otel.trace_id_of("not-a-uuid") == otel.trace_id_of("not-a-uuid")
+    assert otel.trace_id_of("not-a-uuid") != 0
+    assert otel.trace_id_of("not-a-uuid") != tid
+    # 32 chars but not hex → not a UUID, so it is hashed
+    assert otel.trace_id_of("z" * 32) != 0
+
+
+def test_wrap_handler_span_in_trace_with_attrs():
+    tracer, exporter = _recorder()
+    seen = {}
+
+    def handler(data, meta, envelope):
+        seen["called"] = True
+
+    env = _envelope()
+    otel.wrap_handler(tracer, handler)(env["data"], env["meta"], env)
+
+    assert seen.get("called")
+    spans = exporter.get_finished_spans()
+    assert len(spans) == 1
+    span = spans[0]
+    assert span.name == "process urn:babel:orders:created"
+    assert span.kind == SpanKind.CONSUMER
+    assert span.context.trace_id == otel.trace_id_of(_TRACE_ID)
+    assert span.attributes["messaging.message.conversation_id"] == _TRACE_ID
+    assert span.attributes["messaging.message.id"] == "m1"
+    assert span.attributes["messaging.destination.name"] == "orders"
+
+
+def test_wrap_handler_two_arg_inner():
+    tracer, exporter = _recorder()
+    got = {}
+
+    def handler(data, meta):  # only two positional args
+        got["data"] = data
+
+    env = _envelope()
+    # the runtime passes (data, meta, envelope); the wrapper forwards only what the inner wants
+    otel.wrap_handler(tracer, handler)(env["data"], env["meta"], env)
+
+    assert got["data"] == env["data"]
+    assert len(exporter.get_finished_spans()) == 1
+
+
+def test_wrap_handler_records_error():
+    tracer, exporter = _recorder()
+
+    def handler(data, meta, envelope):
+        raise ValueError("boom")
+
+    env = _envelope()
+    with pytest.raises(ValueError):
+        otel.wrap_handler(tracer, handler)(env["data"], env["meta"], env)
+
+    span = exporter.get_finished_spans()[0]
+    assert span.status.status_code.name == "ERROR"
+    assert len(span.events) >= 1  # the recorded exception
+
+
+def test_publish_stamps_trace_id_from_span():
+    tracer, exporter = _recorder()
+    app = FakeApp()
+
+    message_id = otel.publish(tracer, app, "urn:babel:orders:created", {"order_id": 7})
+
+    assert message_id == "msg-123"
+    spans = exporter.get_finished_spans()
+    assert len(spans) == 1
+    span = spans[0]
+    assert span.kind == SpanKind.PRODUCER
+    assert span.attributes["messaging.message.id"] == "msg-123"
+
+    stamped = app.calls[0]["trace_id"]
+    # the published trace_id encodes the producer span's trace, so a consumer recovers it
+    assert stamped == otel.uuid_of(span.context.trace_id)
+    assert otel.trace_id_of(stamped) == span.context.trace_id

babelqueue-1.9.0/tests/test_redrive.py

@@ -0,0 +1,139 @@
+"""Tests for the optional DLQ redrive tooling (ADR-0026)."""
+
+import pytest
+
+from babelqueue import dead_letter
+from babelqueue.codec import EnvelopeCodec
+from babelqueue.redrive import redrive
+from babelqueue.transport import InMemoryTransport
+
+
+def _dead_letter(transport, dlq, urn, original_queue, data=None):
+    env = EnvelopeCodec.make(urn, data or {}, queue=original_queue)
+    annotated = dead_letter.annotate(env, "failed", original_queue, 3, error="boom")
+    transport.publish(dlq, EnvelopeCodec.encode(annotated))
+    return annotated
+
+
+def _drain(transport, queue):
+    out = []
+    while True:
+        message = transport.pop(queue, 0)
+        if message is None:
+            break
+        out.append(EnvelopeCodec.decode(message.body))
+        transport.ack(message)
+    return out
+
+
+def test_redrive_to_source():
+    t = InMemoryTransport()
+    orig = _dead_letter(t, "orders.dlq", "urn:babel:orders:created", "orders", {"order_id": 1})
+
+    result = redrive(t, "orders.dlq")
+
+    assert result.redriven == 1 and result.skipped == 0
+    got = _drain(t, "orders")
+    assert len(got) == 1
+    assert "dead_letter" not in got[0]
+    assert got[0]["attempts"] == 0
+    assert got[0]["trace_id"] == orig["trace_id"]
+    assert got[0]["data"] == {"order_id": 1}
+    assert EnvelopeCodec.urn(got[0]) == "urn:babel:orders:created"
+    assert _drain(t, "orders.dlq") == []
+
+
+def test_redrive_to_sandbox():
+    t = InMemoryTransport()
+    _dead_letter(t, "orders.dlq", "urn:babel:orders:created", "orders")
+
+    result = redrive(t, "orders.dlq", to_queue="sandbox")
+
+    assert result.redriven == 1
+    assert _drain(t, "orders") == []
+    assert len(_drain(t, "sandbox")) == 1
+
+
+def test_redrive_dry_run():
+    t = InMemoryTransport()
+    _dead_letter(t, "orders.dlq", "urn:babel:orders:created", "orders")
+
+    result = redrive(t, "orders.dlq", dry_run=True)
+
+    assert result.redriven == 0 and result.skipped == 1
+    assert result.items[0].to == "orders"
+    assert result.items[0].redriven is False
+    assert _drain(t, "orders") == []
+    dlq = _drain(t, "orders.dlq")
+    assert len(dlq) == 1 and "dead_letter" in dlq[0]
+
+
+def test_redrive_select():
+    t = InMemoryTransport()
+    _dead_letter(t, "dlq", "urn:babel:orders:created", "orders")
+    _dead_letter(t, "dlq", "urn:babel:emails:welcome", "emails")
+
+    result = redrive(t, "dlq", select=lambda e: EnvelopeCodec.urn(e) == "urn:babel:orders:created")
+
+    assert result.redriven == 1 and result.skipped == 1
+    assert len(_drain(t, "orders")) == 1
+    assert _drain(t, "emails") == []
+    assert len(_drain(t, "dlq")) == 1  # the unselected one is restored
+
+
+def test_redrive_max():
+    t = InMemoryTransport()
+    for _ in range(3):
+        _dead_letter(t, "dlq", "urn:babel:orders:created", "orders")
+
+    result = redrive(t, "dlq", max=2)
+
+    assert result.redriven == 2
+    assert len(_drain(t, "dlq")) == 1  # Max respected
+
+
+def test_redrive_no_dead_letter_falls_back_to_meta_queue():
+    t = InMemoryTransport()
+    # a plain (never dead-lettered) envelope on the DLQ — redrive falls back to meta.queue
+    env = EnvelopeCodec.make("urn:babel:orders:created", {}, queue="orders")
+    t.publish("dlq", EnvelopeCodec.encode(env))
+
+    result = redrive(t, "dlq")
+
+    assert result.redriven == 1
+    assert len(_drain(t, "orders")) == 1
+
+
+class _FailOnTarget(InMemoryTransport):
+    """An in-memory transport that refuses to publish to one queue."""
+
+    def __init__(self, fail_queue):
+        super().__init__()
+        self._fail_queue = fail_queue
+
+    def publish(self, queue, body):
+        if queue == self._fail_queue:
+            raise RuntimeError("publish refused")
+        super().publish(queue, body)
+
+
+def test_redrive_publish_failure_restores():
+    t = _FailOnTarget("orders")
+    _dead_letter(t, "dlq", "urn:babel:orders:created", "orders")
+
+    with pytest.raises(RuntimeError):
+        redrive(t, "dlq")
+
+    assert len(_drain(t, "dlq")) == 1  # restored to the DLQ, not lost
+    assert _drain(t, "orders") == []  # nothing reached the source queue
+
+
+def test_redrive_undecodable_restored():
+    t = InMemoryTransport()
+    t.publish("dlq", "not-json{{{")
+
+    result = redrive(t, "dlq")
+
+    assert result.redriven == 0 and result.skipped == 1
+    message = t.pop("dlq", 0)
+    assert message is not None and message.body == "not-json{{{"