fleet-framework 0.1.0__py3-none-any.whl

fleet/core/backend.py

@@ -0,0 +1,736 @@
+from __future__ import annotations
+
+import json
+import secrets
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Any, Optional, Protocol, runtime_checkable
+
+import redis.asyncio as aioredis
+
+
+@dataclass
+class RawItem:
+    """Raw backend record. Plugins never see this — primitives wrap it."""
+    id: str
+    payload: bytes
+    tags: dict[str, Any]
+    expires_at: Optional[float]
+    in_use_until: Optional[float]
+
+
+@runtime_checkable
+class Backend(Protocol):
+    async def kv_set(self, ns: str, key: str, value: bytes, ttl_seconds: Optional[int]) -> None: ...
+    async def kv_setnx(
+        self, ns: str, key: str, value: bytes, ttl_seconds: Optional[int]
+    ) -> bool: ...
+    async def kv_get(self, ns: str, key: str) -> Optional[bytes]: ...
+    async def kv_del(self, ns: str, key: str) -> bool: ...
+
+    async def pool_put(
+        self,
+        name: str,
+        item_id: str,
+        payload: bytes,
+        tags: dict[str, Any],
+        ttl_seconds: Optional[int],
+    ) -> None: ...
+
+    async def pool_list(self, name: str) -> list[RawItem]: ...
+    async def pool_remove(self, name: str, item_id: str) -> bool: ...
+    async def pool_release(self, name: str, item_id: str) -> bool: ...
+
+    async def pool_claim_any(
+        self,
+        name: str,
+        where: dict[str, Any],
+        hold_seconds: int,
+    ) -> Optional[RawItem]: ...
+
+    async def lock_acquire(self, name: str, hold_seconds: int, wait_seconds: float) -> Optional[str]: ...
+    async def lock_release(self, name: str, token: str) -> bool: ...
+
+    async def counter_incr(self, name: str, by: int) -> int: ...
+    async def counter_get(self, name: str) -> int: ...
+    async def counter_set(self, name: str, value: int) -> None: ...
+    async def counter_del(self, name: str) -> None: ...
+
+    async def queue_push(self, name: str, body: bytes, *, priority: int = 0) -> None: ...
+    async def queue_size(self, name: str) -> int: ...
+    async def queue_peek(self, name: str, n: int) -> list[bytes]: ...
+    async def pool_size(self, name: str) -> int: ...
+    async def queue_reserve(
+        self, name: str, timeout_seconds: float, visibility_seconds: int
+    ) -> Optional[bytes]: ...
+    async def queue_ack(self, name: str, task_id: str) -> bool: ...
+    async def queue_nack(
+        self, name: str, task_id: str, body: bytes, *, delay_seconds: float
+    ) -> bool: ...
+    async def queue_sweep_expired(self, name: str, now: Optional[float] = None) -> int: ...
+    async def queue_dead(self, name: str, body: bytes) -> None: ...
+    async def dlq_peek(self, name: str, n: int) -> list[bytes]: ...
+    async def dlq_pop(self, name: str, n: int) -> list[bytes]: ...
+    async def dlq_length(self, name: str) -> int: ...
+    async def dlq_clear(self, name: str) -> int: ...
+
+    async def stream_push(
+        self,
+        name: str,
+        envelope: bytes,
+        *,
+        score: float,
+        max_len: int,
+        ttl_seconds: int,
+    ) -> None: ...
+    async def stream_pop(self, name: str, n: int) -> list[bytes]: ...
+    async def stream_peek(self, name: str, n: int) -> list[bytes]: ...
+    async def stream_length(self, name: str) -> int: ...
+    async def stream_trim(self, name: str, *, max_len: int, ttl_seconds: int) -> None: ...
+
+    async def event_publish(self, topic: str, body: bytes) -> None: ...
+
+    async def worker_register(
+        self, automation_type: str, worker_id: str, hardware: dict[str, Any]
+    ) -> None: ...
+    async def worker_get_config(
+        self, automation_type: str, worker_id: str
+    ) -> tuple[dict[str, Any], int]: ...
+    async def worker_set_config(
+        self, automation_type: str, worker_id: str, config: dict[str, Any]
+    ) -> tuple[dict[str, Any], int]: ...
+    async def worker_set_state(
+        self,
+        automation_type: str,
+        worker_id: str,
+        state: str,
+        last_error: Optional[str],
+        last_seen: float,
+    ) -> None: ...
+    async def worker_set_stats(
+        self, automation_type: str, worker_id: str, stats: dict[str, Any]
+    ) -> None: ...
+    async def worker_stats_push(
+        self,
+        automation_type: str,
+        worker_id: str,
+        ts: float,
+        frame: dict[str, Any],
+        *,
+        max_entries: int = 240,
+    ) -> None: ...
+    async def worker_stats_history(
+        self,
+        automation_type: str,
+        worker_id: str,
+        *,
+        since: float = 0,
+        limit: int = 240,
+    ) -> list[dict[str, Any]]: ...
+    async def worker_get(
+        self, automation_type: str, worker_id: str
+    ) -> Optional[dict[str, Any]]: ...
+    async def worker_list(
+        self, automation_type: Optional[str] = None
+    ) -> list[tuple[str, str]]: ...
+    async def worker_remove(self, automation_type: str, worker_id: str) -> bool: ...
+
+    async def catalog_set(self, automation_type: str, doc: bytes) -> None: ...
+    async def catalog_get(self, automation_type: str) -> Optional[bytes]: ...
+    async def catalog_all(self) -> dict[str, bytes]: ...
+
+
+class RedisBackend:
+    KV_KEY = "fleet:kv:{ns}:{key}"
+    POOL_HASH = "fleet:pool:{name}"
+    POOL_CLAIM = "fleet:pool:{name}:claim:{id}"
+    LOCK_KEY = "fleet:lock:{name}"
+    COUNTER_KEY = "fleet:counter:{name}"
+    QUEUE_KEY = "fleet:queue:{name}"
+    QUEUE_HIGH = "fleet:queue:{name}:high"
+    QUEUE_LOW = "fleet:queue:{name}:low"
+    QUEUE_PROCESSING = "fleet:queue:{name}:processing"  # ZSET task_id -> deadline
+    QUEUE_PROCESSING_BODY = "fleet:queue:{name}:processing:body"  # HASH task_id -> body
+    QUEUE_SCHEDULED = "fleet:queue:{name}:scheduled"  # ZSET body -> ready_at
+    QUEUE_DEAD = "fleet:queue:{name}:dead"
+    STREAM_KEY = "stream:{name}"  # unprefixed: docs + tests refer to this layout
+    EVENT_CHANNEL = "event:{topic}"
+    CATALOG_HASH = "fleet:catalog"
+    WORKER_FIELD = "wkr:{at}:{wid}:{field}"
+    WORKER_TYPE_INDEX = "wkrs:{at}"
+    WORKER_ALL_INDEX = "wkrs:all"
+
+    def __init__(self, url: str = "redis://localhost:6379/0") -> None:
+        self._r: aioredis.Redis = aioredis.from_url(url, decode_responses=False)
+
+    @property
+    def r(self) -> aioredis.Redis:
+        return self._r
+
+    async def aclose(self) -> None:
+        try:
+            await self._r.aclose()
+        except Exception:
+            pass
+
+    async def kv_set(self, ns: str, key: str, value: bytes, ttl_seconds: Optional[int]) -> None:
+        k = self.KV_KEY.format(ns=ns, key=key)
+        if ttl_seconds is not None and ttl_seconds > 0:
+            await self._r.set(k, value, ex=ttl_seconds)
+        else:
+            await self._r.set(k, value)
+
+    async def kv_setnx(
+        self, ns: str, key: str, value: bytes, ttl_seconds: Optional[int]
+    ) -> bool:
+        k = self.KV_KEY.format(ns=ns, key=key)
+        if ttl_seconds is not None and ttl_seconds > 0:
+            res = await self._r.set(k, value, ex=ttl_seconds, nx=True)
+        else:
+            res = await self._r.set(k, value, nx=True)
+        return bool(res)
+
+    async def kv_get(self, ns: str, key: str) -> Optional[bytes]:
+        return await self._r.get(self.KV_KEY.format(ns=ns, key=key))
+
+    async def kv_del(self, ns: str, key: str) -> bool:
+        return bool(await self._r.delete(self.KV_KEY.format(ns=ns, key=key)))
+
+    # Pool = hash {item_id -> json blob}. Claims are separate keys with TTL
+    # so a crashed slot's claim auto-expires.
+
+    @staticmethod
+    def _encode_item(payload: bytes, tags: dict[str, Any], expires_at: Optional[float]) -> bytes:
+        from base64 import b64encode
+        return json.dumps({
+            "p": b64encode(payload).decode("ascii"),
+            "t": tags,
+            "x": expires_at,
+        }).encode("utf-8")
+
+    @staticmethod
+    def _decode_item(raw: bytes) -> tuple[bytes, dict[str, Any], Optional[float]]:
+        from base64 import b64decode
+        d = json.loads(raw.decode("utf-8"))
+        return b64decode(d["p"]), d["t"], d.get("x")
+
+    async def pool_put(
+        self,
+        name: str,
+        item_id: str,
+        payload: bytes,
+        tags: dict[str, Any],
+        ttl_seconds: Optional[int],
+    ) -> None:
+        expires_at = time.time() + ttl_seconds if (ttl_seconds and ttl_seconds > 0) else None
+        encoded = self._encode_item(payload, tags, expires_at)
+        await self._r.hset(self.POOL_HASH.format(name=name), item_id, encoded)
+        # Per-item expiry is enforced on read; opportunistic prune on every put.
+        await self._prune_pool(name)
+
+    async def _prune_pool(self, name: str) -> None:
+        key = self.POOL_HASH.format(name=name)
+        all_items = await self._r.hgetall(key)
+        now = time.time()
+        to_del: list[bytes] = []
+        for item_id, raw in all_items.items():
+            try:
+                _, _, expires_at = self._decode_item(raw)
+            except Exception:
+                to_del.append(item_id)
+                continue
+            if expires_at is not None and expires_at < now:
+                to_del.append(item_id)
+        if to_del:
+            await self._r.hdel(key, *to_del)
+
+    async def pool_list(self, name: str) -> list[RawItem]:
+        key = self.POOL_HASH.format(name=name)
+        raw_items = await self._r.hgetall(key)
+        now = time.time()
+        out: list[RawItem] = []
+        for item_id_b, raw in raw_items.items():
+            try:
+                payload, tags, expires_at = self._decode_item(raw)
+            except Exception:
+                continue
+            if expires_at is not None and expires_at < now:
+                continue
+            item_id = item_id_b.decode("utf-8") if isinstance(item_id_b, bytes) else item_id_b
+            claim_key = self.POOL_CLAIM.format(name=name, id=item_id)
+            ttl = await self._r.pttl(claim_key)
+            in_use_until = (now + ttl / 1000.0) if ttl > 0 else None
+            out.append(RawItem(
+                id=item_id,
+                payload=payload,
+                tags=tags,
+                expires_at=expires_at,
+                in_use_until=in_use_until,
+            ))
+        return out
+
+    async def pool_remove(self, name: str, item_id: str) -> bool:
+        deleted = await self._r.hdel(self.POOL_HASH.format(name=name), item_id)
+        await self._r.delete(self.POOL_CLAIM.format(name=name, id=item_id))
+        return bool(deleted)
+
+    async def pool_release(self, name: str, item_id: str) -> bool:
+        return bool(await self._r.delete(self.POOL_CLAIM.format(name=name, id=item_id)))
+
+    async def pool_claim_any(
+        self,
+        name: str,
+        where: dict[str, Any],
+        hold_seconds: int,
+    ) -> Optional[RawItem]:
+        # Atomic claim is SET NX EX per-item; on race we move on.
+        items = await self.pool_list(name)
+        items.sort(key=lambda x: (x.expires_at or 0), reverse=True)
+        for item in items:
+            if item.in_use_until is not None:
+                continue
+            if not all(item.tags.get(k) == v for k, v in where.items()):
+                continue
+            claim_key = self.POOL_CLAIM.format(name=name, id=item.id)
+            ok = await self._r.set(claim_key, "1", nx=True, ex=hold_seconds)
+            if ok:
+                return item
+        return None
+
+    async def lock_acquire(self, name: str, hold_seconds: int, wait_seconds: float) -> Optional[str]:
+        key = self.LOCK_KEY.format(name=name)
+        token = secrets.token_hex(16)
+        deadline = time.monotonic() + max(0.0, wait_seconds)
+        backoff = 0.05
+        while True:
+            ok = await self._r.set(key, token, nx=True, ex=max(1, hold_seconds))
+            if ok:
+                return token
+            if time.monotonic() >= deadline:
+                return None
+            import asyncio
+            await asyncio.sleep(min(backoff, deadline - time.monotonic()))
+            backoff = min(backoff * 2, 0.5)
+
+    async def lock_release(self, name: str, token: str) -> bool:
+        # Token-checked DEL: prevents releasing a lock that expired and was re-acquired.
+        script = (
+            'if redis.call("GET", KEYS[1]) == ARGV[1] '
+            'then return redis.call("DEL", KEYS[1]) else return 0 end'
+        )
+        key = self.LOCK_KEY.format(name=name)
+        result = await self._r.eval(script, 1, key, token)
+        return bool(result)
+
+    async def counter_incr(self, name: str, by: int) -> int:
+        return int(await self._r.incrby(self.COUNTER_KEY.format(name=name), by))
+
+    async def counter_get(self, name: str) -> int:
+        raw = await self._r.get(self.COUNTER_KEY.format(name=name))
+        return int(raw) if raw is not None else 0
+
+    async def counter_set(self, name: str, value: int) -> None:
+        await self._r.set(self.COUNTER_KEY.format(name=name), value)
+
+    async def counter_del(self, name: str) -> None:
+        await self._r.delete(self.COUNTER_KEY.format(name=name))
+
+    def _queue_key_for_priority(self, name: str, priority: int) -> str:
+        if priority > 0:
+            return self.QUEUE_HIGH.format(name=name)
+        if priority < 0:
+            return self.QUEUE_LOW.format(name=name)
+        return self.QUEUE_KEY.format(name=name)
+
+    def _queue_keys_priority_order(self, name: str) -> list[str]:
+        return [
+            self.QUEUE_HIGH.format(name=name),
+            self.QUEUE_KEY.format(name=name),
+            self.QUEUE_LOW.format(name=name),
+        ]
+
+    async def queue_push(self, name: str, body: bytes, *, priority: int = 0) -> None:
+        await self._r.rpush(self._queue_key_for_priority(name, priority), body)
+
+    async def queue_size(self, name: str) -> int:
+        # Includes high + normal + low so /metrics is honest.
+        total = 0
+        for k in self._queue_keys_priority_order(name):
+            total += int(await self._r.llen(k))
+        return total
+
+    async def queue_peek(self, name: str, n: int) -> list[bytes]:
+        if n <= 0:
+            return []
+        out: list[bytes] = []
+        for k in self._queue_keys_priority_order(name):
+            remaining = n - len(out)
+            if remaining <= 0:
+                break
+            chunk = await self._r.lrange(k, 0, remaining - 1)
+            out.extend(chunk)
+        return out
+
+    async def pool_size(self, name: str) -> int:
+        return int(await self._r.hlen(self.POOL_HASH.format(name=name)))
+
+    async def _drain_scheduled(self, name: str) -> None:
+        now = time.time()
+        sched = self.QUEUE_SCHEDULED.format(name=name)
+        due = await self._r.zrangebyscore(sched, 0, now)
+        if not due:
+            return
+        pipe = self._r.pipeline()
+        pipe.zremrangebyscore(sched, 0, now)
+        for body in due:
+            pipe.rpush(self.QUEUE_KEY.format(name=name), body)
+        await pipe.execute()
+
+    async def _wait_for_body(self, name: str, timeout_seconds: float) -> Optional[bytes]:
+        # BLPOP supports multi-key with priority order; first non-empty wins.
+        # 0 timeout means "forever", so sub-second falls back to a poll loop.
+        import asyncio
+        keys = self._queue_keys_priority_order(name)
+        if timeout_seconds >= 1.0:
+            res = await self._r.blpop(keys, timeout=int(timeout_seconds))
+            if res is None:
+                return None
+            _key, body = res
+            return body
+        deadline = time.monotonic() + max(0.0, timeout_seconds)
+        while time.monotonic() < deadline:
+            for k in keys:
+                body = await self._r.lpop(k)
+                if body is not None:
+                    return body
+            await asyncio.sleep(0.05)
+        return None
+
+    async def queue_reserve(
+        self, name: str, timeout_seconds: float, visibility_seconds: int
+    ) -> Optional[bytes]:
+        await self._drain_scheduled(name)
+        body = await self._wait_for_body(name, timeout_seconds)
+        if body is None:
+            return None
+        try:
+            envelope = json.loads(body.decode("utf-8"))
+            task_id = str(envelope.get("id", ""))
+        except Exception:
+            task_id = uuid.uuid4().hex
+        if not task_id:
+            return body
+        deadline = time.time() + max(1, visibility_seconds)
+        pipe = self._r.pipeline()
+        pipe.zadd(self.QUEUE_PROCESSING.format(name=name), {task_id: deadline})
+        pipe.hset(self.QUEUE_PROCESSING_BODY.format(name=name), task_id, body)
+        await pipe.execute()
+        return body
+
+    async def queue_ack(self, name: str, task_id: str) -> bool:
+        pipe = self._r.pipeline()
+        pipe.zrem(self.QUEUE_PROCESSING.format(name=name), task_id)
+        pipe.hdel(self.QUEUE_PROCESSING_BODY.format(name=name), task_id)
+        results = await pipe.execute()
+        return bool(results and results[0])
+
+    async def queue_nack(
+        self, name: str, task_id: str, body: bytes, *, delay_seconds: float
+    ) -> bool:
+        # Remove the reservation; either re-enqueue immediately or schedule.
+        pipe = self._r.pipeline()
+        pipe.zrem(self.QUEUE_PROCESSING.format(name=name), task_id)
+        pipe.hdel(self.QUEUE_PROCESSING_BODY.format(name=name), task_id)
+        if delay_seconds > 0:
+            ready_at = time.time() + delay_seconds
+            pipe.zadd(self.QUEUE_SCHEDULED.format(name=name), {body: ready_at})
+        else:
+            pipe.rpush(self.QUEUE_KEY.format(name=name), body)
+        await pipe.execute()
+        return True
+
+    async def queue_sweep_expired(self, name: str, now: Optional[float] = None) -> int:
+        now = now if now is not None else time.time()
+        proc_key = self.QUEUE_PROCESSING.format(name=name)
+        body_key = self.QUEUE_PROCESSING_BODY.format(name=name)
+        expired_ids = await self._r.zrangebyscore(proc_key, 0, now)
+        if not expired_ids:
+            return 0
+        bodies = await self._r.hmget(body_key, expired_ids)
+        pipe = self._r.pipeline()
+        for tid, body in zip(expired_ids, bodies, strict=True):
+            if body is None:
+                continue
+            pipe.rpush(self.QUEUE_KEY.format(name=name), body)
+            pipe.zrem(proc_key, tid)
+            pipe.hdel(body_key, tid)
+        await pipe.execute()
+        return sum(1 for b in bodies if b is not None)
+
+    async def queue_dead(self, name: str, body: bytes) -> None:
+        await self._r.rpush(self.QUEUE_DEAD.format(name=name), body)
+
+    async def dlq_peek(self, name: str, n: int) -> list[bytes]:
+        return list(await self._r.lrange(self.QUEUE_DEAD.format(name=name), 0, max(0, n - 1)))
+
+    async def dlq_pop(self, name: str, n: int) -> list[bytes]:
+        key = self.QUEUE_DEAD.format(name=name)
+        out: list[bytes] = []
+        for _ in range(n):
+            b = await self._r.lpop(key)
+            if b is None:
+                break
+            out.append(b)
+        return out
+
+    async def dlq_length(self, name: str) -> int:
+        return int(await self._r.llen(self.QUEUE_DEAD.format(name=name)))
+
+    async def dlq_clear(self, name: str) -> int:
+        length = await self.dlq_length(name)
+        await self._r.delete(self.QUEUE_DEAD.format(name=name))
+        return length
+
+    async def stream_push(
+        self,
+        name: str,
+        envelope: bytes,
+        *,
+        score: float,
+        max_len: int,
+        ttl_seconds: int,
+    ) -> None:
+        key = self.STREAM_KEY.format(name=name)
+        pipe = self._r.pipeline()
+        pipe.zadd(key, {envelope: score})
+        if ttl_seconds > 0:
+            pipe.zremrangebyscore(key, 0, score - ttl_seconds)
+        if max_len > 0:
+            pipe.zremrangebyrank(key, 0, -(max_len + 1))
+        pipe.publish(self.EVENT_CHANNEL.format(topic=f"{name}.emit"), str(score))
+        await pipe.execute()
+
+    async def stream_pop(self, name: str, n: int) -> list[bytes]:
+        raw = await self._r.zpopmin(self.STREAM_KEY.format(name=name), n)
+        return [m for m, _score in raw]
+
+    async def stream_peek(self, name: str, n: int) -> list[bytes]:
+        return list(await self._r.zrange(self.STREAM_KEY.format(name=name), 0, n - 1))
+
+    async def stream_length(self, name: str) -> int:
+        return int(await self._r.zcard(self.STREAM_KEY.format(name=name)))
+
+    async def stream_trim(self, name: str, *, max_len: int, ttl_seconds: int) -> None:
+        key = self.STREAM_KEY.format(name=name)
+        now = time.time()
+        pipe = self._r.pipeline()
+        if ttl_seconds > 0:
+            pipe.zremrangebyscore(key, 0, now - ttl_seconds)
+        if max_len > 0:
+            pipe.zremrangebyrank(key, 0, -(max_len + 1))
+        await pipe.execute()
+
+    async def event_publish(self, topic: str, body: bytes) -> None:
+        await self._r.publish(self.EVENT_CHANNEL.format(topic=topic), body)
+
+    def _wkey(self, at: str, wid: str, field: str) -> str:
+        return self.WORKER_FIELD.format(at=at, wid=wid, field=field)
+
+    async def worker_register(
+        self, automation_type: str, worker_id: str, hardware: dict[str, Any]
+    ) -> None:
+        at, wid = automation_type, worker_id
+        await self._r.set(self._wkey(at, wid, "hardware"), json.dumps(hardware).encode("utf-8"))
+        await self._r.sadd(self.WORKER_TYPE_INDEX.format(at=at), wid)
+        await self._r.sadd(self.WORKER_ALL_INDEX, f"{at}|{wid}")
+        if not await self._r.exists(self._wkey(at, wid, "gen")):
+            await self._r.set(self._wkey(at, wid, "gen"), "0")
+        if not await self._r.exists(self._wkey(at, wid, "config")):
+            await self._r.set(self._wkey(at, wid, "config"), b"{}")
+
+    async def worker_get_config(
+        self, automation_type: str, worker_id: str
+    ) -> tuple[dict[str, Any], int]:
+        raw_cfg = await self._r.get(self._wkey(automation_type, worker_id, "config"))
+        raw_gen = await self._r.get(self._wkey(automation_type, worker_id, "gen"))
+        cfg = json.loads(raw_cfg.decode("utf-8")) if raw_cfg else {}
+        gen = int(raw_gen.decode("utf-8")) if raw_gen else 0
+        return cfg, gen
+
+    async def worker_set_config(
+        self, automation_type: str, worker_id: str, config: dict[str, Any]
+    ) -> tuple[dict[str, Any], int]:
+        at, wid = automation_type, worker_id
+        await self._r.set(self._wkey(at, wid, "config"), json.dumps(config).encode("utf-8"))
+        new_gen = await self._r.incr(self._wkey(at, wid, "gen"))
+        return config, int(new_gen)
+
+    async def worker_set_state(
+        self,
+        automation_type: str,
+        worker_id: str,
+        state: str,
+        last_error: Optional[str],
+        last_seen: float,
+    ) -> None:
+        key = self._wkey(automation_type, worker_id, "state")
+        await self._r.hset(
+            key,
+            mapping={
+                "state": state,
+                "last_seen": str(last_seen),
+                "last_error": last_error or "",
+            },
+        )
+
+    async def worker_set_stats(
+        self, automation_type: str, worker_id: str, stats: dict[str, Any]
+    ) -> None:
+        await self._r.set(
+            self._wkey(automation_type, worker_id, "stats"),
+            json.dumps(stats).encode("utf-8"),
+        )
+
+    async def worker_stats_push(
+        self,
+        automation_type: str,
+        worker_id: str,
+        ts: float,
+        frame: dict[str, Any],
+        *,
+        max_entries: int = 240,
+    ) -> None:
+        key = self._wkey(automation_type, worker_id, "stats:history")
+        body = json.dumps(frame, default=str).encode("utf-8")
+        pipe = self._r.pipeline()
+        pipe.zadd(key, {body: ts})
+        if max_entries > 0:
+            pipe.zremrangebyrank(key, 0, -(max_entries + 1))
+        await pipe.execute()
+
+    async def worker_stats_history(
+        self,
+        automation_type: str,
+        worker_id: str,
+        *,
+        since: float = 0,
+        limit: int = 240,
+    ) -> list[dict[str, Any]]:
+        key = self._wkey(automation_type, worker_id, "stats:history")
+        raw = await self._r.zrangebyscore(key, since, "+inf", start=0, num=limit)
+        out: list[dict[str, Any]] = []
+        for entry in raw:
+            try:
+                out.append(json.loads(entry.decode("utf-8") if isinstance(entry, bytes) else entry))
+            except Exception:
+                continue
+        return out
+
+    async def worker_get(
+        self, automation_type: str, worker_id: str
+    ) -> Optional[dict[str, Any]]:
+        at, wid = automation_type, worker_id
+        is_member = await self._r.sismember(self.WORKER_TYPE_INDEX.format(at=at), wid)
+        if not is_member:
+            return None
+        raw_hw = await self._r.get(self._wkey(at, wid, "hardware"))
+        raw_stats = await self._r.get(self._wkey(at, wid, "stats"))
+        cfg, gen = await self.worker_get_config(at, wid)
+        state_h = await self._r.hgetall(self._wkey(at, wid, "state"))
+        state_d = {
+            (k.decode("utf-8") if isinstance(k, bytes) else k):
+            (v.decode("utf-8") if isinstance(v, bytes) else v)
+            for k, v in state_h.items()
+        }
+        return {
+            "hardware": json.loads(raw_hw.decode("utf-8")) if raw_hw else {},
+            "config": cfg,
+            "config_gen": gen,
+            "state": state_d.get("state", "IDLE"),
+            "last_seen": float(state_d.get("last_seen") or 0),
+            "last_error": state_d.get("last_error") or None,
+            "stats": json.loads(raw_stats.decode("utf-8")) if raw_stats else {},
+        }
+
+    async def worker_list(
+        self, automation_type: Optional[str] = None
+    ) -> list[tuple[str, str]]:
+        if automation_type is None:
+            raw = await self._r.smembers(self.WORKER_ALL_INDEX)
+            out: list[tuple[str, str]] = []
+            for entry in raw:
+                s = entry.decode("utf-8") if isinstance(entry, bytes) else entry
+                at, _, wid = s.partition("|")
+                if wid:
+                    out.append((at, wid))
+            return out
+        raw = await self._r.smembers(self.WORKER_TYPE_INDEX.format(at=automation_type))
+        return [
+            (automation_type, e.decode("utf-8") if isinstance(e, bytes) else e)
+            for e in raw
+        ]
+
+    async def worker_remove(self, automation_type: str, worker_id: str) -> bool:
+        at, wid = automation_type, worker_id
+        is_member = await self._r.sismember(self.WORKER_TYPE_INDEX.format(at=at), wid)
+        if not is_member:
+            return False
+        for field in ("hardware", "config", "gen", "state", "stats"):
+            await self._r.delete(self._wkey(at, wid, field))
+        await self._r.srem(self.WORKER_TYPE_INDEX.format(at=at), wid)
+        await self._r.srem(self.WORKER_ALL_INDEX, f"{at}|{wid}")
+        return True
+
+    async def catalog_set(self, automation_type: str, doc: bytes) -> None:
+        await self._r.hset(self.CATALOG_HASH, automation_type, doc)
+
+    async def catalog_get(self, automation_type: str) -> Optional[bytes]:
+        return await self._r.hget(self.CATALOG_HASH, automation_type)
+
+    async def catalog_all(self) -> dict[str, bytes]:
+        raw = await self._r.hgetall(self.CATALOG_HASH)
+        return {
+            (k.decode("utf-8") if isinstance(k, bytes) else k): v
+            for k, v in raw.items()
+        }
+
+
+def backend_from_url(url: str) -> Backend:
+    """Construct a Backend from a URL by scheme.
+
+    Built-in schemes:
+        redis://...      -> RedisBackend
+        rediss://...     -> RedisBackend (TLS)
+        memory://        -> InMemoryBackend (single-process)
+
+    Third-party schemes can register via the `fleet.backends` entry-point
+    group. The entry-point name is the URL scheme; the loaded callable
+    receives the full URL and must return an object implementing Backend.
+    """
+    scheme = url.split("://", 1)[0].lower() if "://" in url else url.lower()
+    if scheme in ("redis", "rediss"):
+        return RedisBackend(url)
+    if scheme in ("memory", "mem"):
+        from fleet.core.memory_backend import InMemoryBackend
+        return InMemoryBackend(url)
+    if scheme in ("sqlite", "file"):
+        from fleet.core.sqlite_backend import SqliteBackend
+        return SqliteBackend(url)
+    try:
+        from importlib.metadata import entry_points
+        eps = entry_points(group="fleet.backends")
+    except Exception:
+        eps = []
+    for ep in eps:
+        if ep.name.lower() == scheme:
+            factory = ep.load()
+            return factory(url)
+    raise ValueError(
+        f"no backend registered for scheme '{scheme}'. "
+        "built-in: redis://, rediss://, memory://. "
+        "third-party: install a package that exposes a 'fleet.backends' entry-point."
+    )
+
+
+__all__ = ["Backend", "RawItem", "RedisBackend", "backend_from_url"]