babelqueue 1.5.0__tar.gz → 1.7.0__tar.gz

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

@@ -7,6 +7,32 @@ 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.6.0] - 2026-06-14
+
+### Added
+- **Redis/Laravel reservation parity** — the Redis transport can now consume a
+  **shared** Laravel BabelQueue Redis queue using Laravel's reserved-set / reliable-queue
+  semantics, not just a Python-owned queue. Enable it with the `laravel=1` URL flag
+  (`redis://host:6379/0?laravel=1`) or `RedisTransport(..., laravel_compat=True)`. In this
+  mode the key layout is Laravel's stock Redis queue ([§1 of the broker-bindings
+  contract](https://babelqueue.com/docs/spec/1.x/broker-bindings#redis)): a `queues:<name>`
+  ready list, a `queues:<name>:reserved` **sorted set** scored by a `retry_after` deadline
+  (default 60s), a `queues:<name>:delayed` set, and a `queues:<name>:notify` wake-up list.
+  Reserve, ack and release run the **byte-for-byte same Lua scripts** Laravel uses, so the
+  reserved member a Python worker writes is identical to a Laravel worker's — either side can
+  ack (`ZREM`) the other's reservation, so a Python worker and a Laravel worker share one
+  Redis queue without losing or double-processing messages. Before each pop, expired
+  reserved/delayed jobs migrate back to the ready list, so a crashed worker's in-flight job
+  is re-reserved exactly as Laravel does. Tunable via `?prefix=` / `?retry_after=` (or the
+  `key_prefix` / `retry_after` constructor args). The default Python-owned reliable-queue
+  mode (`BLMOVE` + `<queue>:processing` list) is unchanged and stays the default, so existing
+  callers are unaffected. The reservation logic is fully unit-tested with an injected
+  in-memory Redis double (no `redis` package, no broker); a live cross-runtime PHP↔Python
+  shared-queue round-trip is covered by the integration suite where a real Redis is present.
+  The envelope is unchanged (`schema_version: 1`); this is purely additive. Ships as a MINOR.
+
 ## [1.5.0] - 2026-06-13
 
 ### Added
@@ -173,7 +199,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.2.0...HEAD
+[Unreleased]: https://github.com/BabelQueue/babelqueue-python/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/BabelQueue/babelqueue-python/compare/v1.5.0...v1.6.0
 [1.2.0]: https://github.com/BabelQueue/babelqueue-python/compare/v1.1.0...v1.2.0
 [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: babelqueue
-Version: 1.5.0
+Version: 1.7.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
@@ -164,9 +164,35 @@ app.run()                               # consume forever (Ctrl-C to stop)
 - **Retry & dead-letter:** failures are retried up to `max_attempts` (bumping the
   envelope's `attempts`); enable `dead_letter=True` to quarantine exhausted
   messages on `<queue>.dlq`. `on_unknown_urn` = `fail` | `delete` | `release` | `dead_letter`.
-- **Transports:** `redis://` (reliable-queue pattern), `amqp://` (RabbitMQ via
-  `pika`, with the contract AMQP properties) and `memory://` (in-process, great for
-  tests/local). Bring your own by passing `transport=...`.
+- **Transports:** `redis://` (reliable-queue pattern; add `?laravel=1` to share a
+  Redis queue with a Laravel BabelQueue worker using its reserved-set semantics —
+  see below), `amqp://` (RabbitMQ via `pika`, with the contract AMQP properties)
+  and `memory://` (in-process, great for tests/local). Bring your own by passing
+  `transport=...`.
+
+### Sharing a Redis queue with Laravel
+
+By default the Redis transport owns its queue end-to-end (`RPUSH` to produce;
+`BLMOVE` into a `<queue>:processing` list to reserve; `LREM` on ack). To consume a
+**shared** Laravel BabelQueue Redis queue instead, enable Laravel-compatible mode:
+
+```python
+app = BabelQueue("redis://localhost:6379/0?laravel=1", queue="orders")
+# or: RedisTransport("redis://localhost:6379/0", laravel_compat=True)
+```
+
+This replicates Laravel's stock Redis reservation exactly ([§1 of the
+broker-bindings contract](https://babelqueue.com/docs/spec/1.x/broker-bindings#redis)):
+the ready list is `queues:<name>`, reservations move into the `queues:<name>:reserved`
+**sorted set** scored by a `retry_after` deadline (default 60s), with a
+`queues:<name>:delayed` set and a `queues:<name>:notify` wake-up list. Reserve, ack
+and release run the **byte-for-byte same Lua scripts** Laravel uses, so the reserved
+member a Python worker writes is identical to a Laravel worker's — either side can
+ack (`ZREM`) the other's reservation, so a Python worker and a Laravel worker share
+one queue without losing or double-processing messages. Before each pop, expired
+reserved/delayed jobs migrate back to the ready list, so a crashed worker's
+in-flight job is re-reserved. Options: `?prefix=queues:` and `?retry_after=60`
+(or the `key_prefix` / `retry_after` constructor args).
 
 ## Framework adapters — Celery & Django
 

{babelqueue-1.5.0 → babelqueue-1.7.0}/README.md

@@ -114,9 +114,35 @@ app.run()                               # consume forever (Ctrl-C to stop)
 - **Retry & dead-letter:** failures are retried up to `max_attempts` (bumping the
   envelope's `attempts`); enable `dead_letter=True` to quarantine exhausted
   messages on `<queue>.dlq`. `on_unknown_urn` = `fail` | `delete` | `release` | `dead_letter`.
-- **Transports:** `redis://` (reliable-queue pattern), `amqp://` (RabbitMQ via
-  `pika`, with the contract AMQP properties) and `memory://` (in-process, great for
-  tests/local). Bring your own by passing `transport=...`.
+- **Transports:** `redis://` (reliable-queue pattern; add `?laravel=1` to share a
+  Redis queue with a Laravel BabelQueue worker using its reserved-set semantics —
+  see below), `amqp://` (RabbitMQ via `pika`, with the contract AMQP properties)
+  and `memory://` (in-process, great for tests/local). Bring your own by passing
+  `transport=...`.
+
+### Sharing a Redis queue with Laravel
+
+By default the Redis transport owns its queue end-to-end (`RPUSH` to produce;
+`BLMOVE` into a `<queue>:processing` list to reserve; `LREM` on ack). To consume a
+**shared** Laravel BabelQueue Redis queue instead, enable Laravel-compatible mode:
+
+```python
+app = BabelQueue("redis://localhost:6379/0?laravel=1", queue="orders")
+# or: RedisTransport("redis://localhost:6379/0", laravel_compat=True)
+```
+
+This replicates Laravel's stock Redis reservation exactly ([§1 of the
+broker-bindings contract](https://babelqueue.com/docs/spec/1.x/broker-bindings#redis)):
+the ready list is `queues:<name>`, reservations move into the `queues:<name>:reserved`
+**sorted set** scored by a `retry_after` deadline (default 60s), with a
+`queues:<name>:delayed` set and a `queues:<name>:notify` wake-up list. Reserve, ack
+and release run the **byte-for-byte same Lua scripts** Laravel uses, so the reserved
+member a Python worker writes is identical to a Laravel worker's — either side can
+ack (`ZREM`) the other's reservation, so a Python worker and a Laravel worker share
+one queue without losing or double-processing messages. Before each pop, expired
+reserved/delayed jobs migrate back to the ready list, so a crashed worker's
+in-flight job is re-reserved. Options: `?prefix=queues:` and `?retry_after=60`
+(or the `key_prefix` / `retry_after` constructor args).
 
 ## Framework adapters — Celery & Django
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.5.0"
+version = "1.7.0"
 description = "Polyglot Queues, Simplified — the Python core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers."
 readme = "README.md"
 requires-python = ">=3.9"

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

@@ -11,15 +11,16 @@ and dead-letter helpers. Framework adapters (Celery, Django, ...) build on this.
 
 from __future__ import annotations
 
-from . import dead_letter
+from . import dead_letter, idempotency
 from .app import BabelQueue
 from .codec import SCHEMA_VERSION, SOURCE_LANG, EnvelopeCodec
 from .contracts import HasTraceId, PolyglotMessage
+from .idempotency import IdempotencyStore, InMemoryStore
 from .exceptions import BabelQueueError, UnknownUrnError
 from .routing import UnknownUrnStrategy
 from .transport import InMemoryTransport, ReceivedMessage, Transport
 
-__version__ = "1.2.0"
+__version__ = "1.6.0"
 
 __all__ = [
     "BabelQueue",
@@ -35,5 +36,8 @@ __all__ = [
     "BabelQueueError",
     "UnknownUrnError",
     "dead_letter",
+    "idempotency",
+    "IdempotencyStore",
+    "InMemoryStore",
     "__version__",
 ]

babelqueue-1.7.0/src/babelqueue/exceptions.py

@@ -0,0 +1,25 @@
+"""Exception hierarchy for BabelQueue."""
+
+from __future__ import annotations
+
+
+class BabelQueueError(Exception):
+    """Base for every recoverable BabelQueue error (bad config, empty URN, ...)."""
+
+
+class UnknownUrnError(BabelQueueError):
+    """A consumed message carries a URN with no mapped handler (strategy "fail")."""
+
+
+class InvalidPayloadError(BabelQueueError):
+    """A message's ``data`` does not match the JSON Schema registered for its URN (ADR-0024).
+
+    Raised by the producer-side :func:`babelqueue.schema.validate` and the consumer-side
+    :func:`babelqueue.schema.wrap`; the latter lets the runtime redeliver (and eventually
+    dead-letter) a poison message.
+    """
+
+    def __init__(self, urn: str, violation: str) -> None:
+        super().__init__(f"data for {urn!r} does not match its URN schema: {violation}")
+        self.urn = urn
+        self.violation = violation

babelqueue-1.7.0/src/babelqueue/idempotency.py

@@ -0,0 +1,95 @@
+"""Optional idempotency helper (ADR-0022): dedupe a consume handler on ``meta.id``.
+
+The Python mirror of the PHP ``BabelQueue\\Idempotency`` and Go ``idempotency``
+helpers. It wraps a handler so a message whose ``meta.id`` was already processed
+successfully is skipped instead of run again, composing with the runtime's
+ack-on-return / redeliver-on-raise contract::
+
+    from babelqueue import BabelQueue
+    from babelqueue.idempotency import InMemoryStore, wrap
+
+    app = BabelQueue("redis://localhost:6379/0", queue="orders")
+    store = InMemoryStore()
+    app.register("urn:babel:orders:created", wrap(store, on_order_created))
+
+A previously-seen id returns early (the runtime acks it, so the broker stops
+redelivering); a raising handler leaves the id unmarked so a redelivery runs it again
+(retry / dead-letter still apply); a message with no usable ``meta.id`` runs unchanged.
+This is "seen-set" post-success dedupe — not exactly-once and not in-flight concurrency
+locking; a transactional / outbox mode is a documented future direction.
+"""
+
+from __future__ import annotations
+
+import functools
+import threading
+from typing import Any, Callable, Mapping, Protocol, runtime_checkable
+
+Handler = Callable[..., None]
+
+
+@runtime_checkable
+class IdempotencyStore(Protocol):
+    """A record of message ids already processed, keyed on ``meta.id``."""
+
+    def seen(self, message_id: str) -> bool:
+        """Whether this id has already been processed (remembered)."""
+
+    def remember(self, message_id: str) -> None:
+        """Record this id as processed."""
+
+    def forget(self, message_id: str) -> None:
+        """Drop an id from the store (manual eviction; a backend may also expire ids)."""
+
+
+class InMemoryStore:
+    """Process-local, thread-safe :class:`IdempotencyStore`.
+
+    For tests and single-process consumers; it is not shared across workers and not
+    persistent — use a Redis- or database-backed store for production fleets.
+    """
+
+    def __init__(self) -> None:
+        self._seen: set[str] = set()
+        self._lock = threading.Lock()
+
+    def seen(self, message_id: str) -> bool:
+        with self._lock:
+            return message_id in self._seen
+
+    def remember(self, message_id: str) -> None:
+        with self._lock:
+            self._seen.add(message_id)
+
+    def forget(self, message_id: str) -> None:
+        with self._lock:
+            self._seen.discard(message_id)
+
+
+def wrap(store: IdempotencyStore, handler: Handler) -> Handler:
+    """Wrap ``handler`` so a message whose ``meta.id`` was already processed is skipped.
+
+    The returned callable keeps ``handler``'s signature (via :func:`functools.wraps`),
+    so the runtime's introspection still passes it the right number of positional args
+    (``data, meta`` or ``data, meta, envelope``).
+    """
+
+    @functools.wraps(handler)
+    def wrapped(*args: Any) -> None:
+        meta = args[1] if len(args) > 1 and isinstance(args[1], Mapping) else {}
+        message_id = meta.get("id")
+
+        # No usable id → cannot dedupe; run the handler unchanged.
+        if not isinstance(message_id, str) or message_id == "":
+            handler(*args)
+            return
+
+        # Already processed on an earlier delivery: return so the runtime acks it.
+        if store.seen(message_id):
+            return
+
+        # First success wins; a raise here leaves the id unmarked → retry/DLQ apply.
+        handler(*args)
+        store.remember(message_id)
+
+    return wrapped

babelqueue-1.7.0/src/babelqueue/redis_transport.py

@@ -0,0 +1,254 @@
+"""Redis transport. Requires the ``redis`` extra:
+
+    pip install "babelqueue[redis]"
+
+Two reservation modes share one class, selected by ``laravel_compat``:
+
+**Python-owned (default).** Producing is ``RPUSH queue body``; consuming atomically
+moves the head to a per-queue processing list (``BLMOVE``) so an in-flight message
+survives a worker crash, and ``ack`` removes it from that processing list. Simple,
+self-contained, and the right choice for a queue this runtime owns end-to-end.
+
+**Laravel-compatible (``laravel_compat=True``).** Replicates Laravel's stock Redis
+queue reservation so a Python worker can share one Redis queue with a PHP/Laravel
+worker without losing or double-processing messages (§1 of the broker-bindings
+contract). The key layout is Laravel's: a ``queues:<name>`` ready list, a
+``queues:<name>:reserved`` sorted set scored by a retry-after deadline, a
+``queues:<name>:delayed`` sorted set, and a ``queues:<name>:notify`` wake-up list.
+Reserve/ack/release run the **byte-for-byte same Lua scripts** Laravel uses, so the
+reserved-set member a Python worker writes is identical to what a Laravel worker
+writes — either side can therefore ack (``ZREM``) the other's reservation. Before
+each pop the transport migrates expired reserved/delayed jobs back to the ready
+list, so a crashed worker's in-flight job is re-reserved exactly as Laravel does.
+
+The envelope is unchanged (``schema_version`` stays 1); Redis is purely additive.
+
+URL form: ``redis://host:port/db[?laravel=1&prefix=queues:&retry_after=60]``.
+For richer setups, build the transport directly and pass ``BabelQueue(transport=...)``.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+from urllib.parse import parse_qs, urlsplit
+
+from .transport import ReceivedMessage, Transport
+
+# Laravel's stock Redis queue Lua scripts (Illuminate\Queue\LuaScripts). Replicated
+# verbatim so the reserved-set member byte form matches Laravel's — that exact match
+# is what lets a Python and a Laravel worker ack each other's reservations.
+
+# KEYS[1]=ready list, KEYS[2]=notify list; ARGV[1]=payload.
+_PUSH = """
+redis.call('rpush', KEYS[1], ARGV[1])
+redis.call('rpush', KEYS[2], 1)
+"""
+
+# KEYS[1]=ready, KEYS[2]=reserved, KEYS[3]=notify; ARGV[1]=reserved-until score.
+# Returns {original_job, reserved_member}; the reserved member is the attempts+1
+# re-encoding stored in the reserved set and is the ack handle.
+_POP = """
+local job = redis.call('lpop', KEYS[1])
+local reserved = false
+
+if(job ~= false) then
+    reserved = cjson.decode(job)
+    reserved['attempts'] = reserved['attempts'] + 1
+    reserved = cjson.encode(reserved)
+    redis.call('zadd', KEYS[2], ARGV[1], reserved)
+    redis.call('lpop', KEYS[3])
+end
+
+return {job, reserved}
+"""
+
+# KEYS[1]=delayed, KEYS[2]=reserved; ARGV[1]=reserved member, ARGV[2]=available-at.
+_RELEASE = """
+redis.call('zrem', KEYS[2], ARGV[1])
+redis.call('zadd', KEYS[1], ARGV[2], ARGV[1])
+return true
+"""
+
+# KEYS[1]=from (reserved/delayed), KEYS[2]=ready, KEYS[3]=notify; ARGV[1]=now,
+# ARGV[2]=batch size (-1 = all). Moves jobs whose score has expired back to ready.
+_MIGRATE = """
+local val = redis.call('zrangebyscore', KEYS[1], '-inf', ARGV[1], 'limit', 0, ARGV[2])
+
+if(next(val) ~= nil) then
+    redis.call('zremrangebyrank', KEYS[1], 0, #val - 1)
+
+    for i = 1, #val, 100 do
+        redis.call('rpush', KEYS[2], unpack(val, i, math.min(i+99, #val)))
+        for j = i, math.min(i+99, #val) do
+            redis.call('rpush', KEYS[3], 1)
+        end
+    end
+end
+
+return val
+"""
+
+
+class RedisTransport(Transport):
+    def __init__(
+        self,
+        url: str = "redis://localhost:6379/0",
+        *,
+        client: Any = None,
+        processing_suffix: str = ":processing",
+        laravel_compat: bool = False,
+        key_prefix: str = "queues:",
+        retry_after: int = 60,
+        block_for: Optional[float] = None,
+    ) -> None:
+        parts = urlsplit(url) if url else urlsplit("redis://")
+        q = parse_qs(parts.query)
+
+        self._processing_suffix = processing_suffix
+        self._laravel_compat = laravel_compat or _qbool(q, "laravel") or _qbool(q, "laravel_compat")
+        self._key_prefix = key_prefix if "prefix" not in q else (_q1(q, "prefix") or key_prefix)
+        self._retry_after = retry_after if "retry_after" not in q else _qint(q, "retry_after", retry_after)
+        self._block_for = block_for
+
+        if client is not None:
+            self._redis = client
+            return
+        try:
+            import redis
+        except ImportError as exc:  # pragma: no cover - import guard
+            raise ImportError(
+                "RedisTransport requires the 'redis' package. Install with "
+                'pip install "babelqueue[redis]".'
+            ) from exc
+        self._redis = redis.Redis.from_url(url, decode_responses=True)
+
+    # -- key helpers --------------------------------------------------------
+
+    def _processing(self, queue: str) -> str:
+        return f"{queue}{self._processing_suffix}"
+
+    def _ready(self, queue: str) -> str:
+        """The Laravel ready-list key for a logical queue name (``queues:<name>``)."""
+        return f"{self._key_prefix}{queue}"
+
+    # -- Transport ----------------------------------------------------------
+
+    def publish(self, queue: str, body: str) -> None:
+        if not self._laravel_compat:
+            self._redis.rpush(queue, body)
+            return
+        ready = self._ready(queue)
+        self._redis.eval(_PUSH, 2, ready, f"{ready}:notify", body)
+
+    def pop(self, queue: str, timeout: float = 1.0) -> Optional[ReceivedMessage]:
+        if not self._laravel_compat:
+            return self._pop_owned(queue, timeout)
+        return self._pop_laravel(queue, timeout)
+
+    def ack(self, message: ReceivedMessage) -> None:
+        if not self._laravel_compat:
+            self._redis.lrem(self._processing(message.queue), 1, message.handle)
+            return
+        if not message.handle:
+            return
+        self._redis.zrem(f"{self._ready(message.queue)}:reserved", message.handle)
+
+    def release(self, message: ReceivedMessage, delay: int = 0) -> None:
+        """Return a reserved Laravel job to the (delayed) ready set for retry.
+
+        No-op in Python-owned mode (the runtime re-publishes instead). In
+        Laravel-compatible mode this is ``ZREM :reserved`` + ``ZADD :delayed`` —
+        the exact bookkeeping Laravel's release performs.
+        """
+        if not self._laravel_compat or not message.handle:
+            return
+        ready = self._ready(message.queue)
+        self._redis.eval(
+            _RELEASE, 2, f"{ready}:delayed", f"{ready}:reserved",
+            message.handle, int(time.time()) + int(delay),
+        )
+
+    def close(self) -> None:  # pragma: no cover
+        self._redis.close()
+
+    # -- Python-owned reliable queue ----------------------------------------
+
+    def _pop_owned(self, queue: str, timeout: float) -> Optional[ReceivedMessage]:
+        # redis-py types the BLMOVE timeout as int, but Redis accepts a float
+        # (sub-second) timeout; passing it through is correct at runtime.
+        body = self._redis.blmove(queue, self._processing(queue), timeout, "LEFT", "RIGHT")  # type: ignore[arg-type]
+        if body is None:
+            return None
+        text = _as_text(body)
+        return ReceivedMessage(body=text, queue=queue, handle=text)
+
+    # -- Laravel-compatible reservation -------------------------------------
+
+    def _pop_laravel(self, queue: str, timeout: float) -> Optional[ReceivedMessage]:
+        ready = self._ready(queue)
+        self._migrate(ready)
+
+        result = self._redis.eval(
+            _POP, 3, ready, f"{ready}:reserved", f"{ready}:notify",
+            int(time.time()) + self._retry_after,
+        )
+        job, reserved = _pop_result(result)
+        if job is None or reserved is None:
+            # Nothing ready right now; optionally block on the notify list so a
+            # concurrently-pushed job wakes us, then retry once (mirrors Laravel).
+            block = self._block_for if self._block_for is not None else timeout
+            if block and block > 0 and self._redis.blpop([f"{ready}:notify"], block):
+                result = self._redis.eval(
+                    _POP, 3, ready, f"{ready}:reserved", f"{ready}:notify",
+                    int(time.time()) + self._retry_after,
+                )
+                job, reserved = _pop_result(result)
+            if job is None or reserved is None:
+                return None
+
+        # The reserved member (attempts already incremented) is both the consumed
+        # body and the ack handle, so ZREM removes exactly this reservation.
+        return ReceivedMessage(body=_as_text(reserved), queue=queue, handle=_as_text(reserved))
+
+    def _migrate(self, ready: str) -> None:
+        now = int(time.time())
+        # Delayed jobs that are due, then reserved jobs whose retry-after lapsed
+        # (a crashed worker's in-flight job) — both move back to the ready list.
+        self._redis.eval(_MIGRATE, 3, f"{ready}:delayed", ready, f"{ready}:notify", now, -1)
+        self._redis.eval(_MIGRATE, 3, f"{ready}:reserved", ready, f"{ready}:notify", now, -1)
+
+
+def _as_text(value: Any) -> str:
+    """Normalise a Redis reply to ``str`` (bytes when ``decode_responses`` is off)."""
+    return value if isinstance(value, str) else value.decode()
+
+
+def _pop_result(result: Any) -> tuple[Optional[Any], Optional[Any]]:
+    """Unpack the ``{job, reserved}`` reply; ``false`` Lua values arrive as ``None``."""
+    if not result or len(result) < 2:
+        return None, None
+    job, reserved = result[0], result[1]
+    if not job or not reserved:
+        return None, None
+    return job, reserved
+
+
+def _q1(q: dict, key: str) -> Optional[str]:
+    values = q.get(key)
+    return values[0] if values else None
+
+
+def _qint(q: dict, key: str, default: int) -> int:
+    v = _q1(q, key)
+    if v is None:
+        return default
+    try:
+        return int(v)
+    except ValueError:  # pragma: no cover - defensive
+        return default
+
+
+def _qbool(q: dict, key: str) -> bool:
+    v = _q1(q, key)
+    return v is not None and v.lower() in ("1", "true", "yes", "on")