kickdown 0.4.0a1__py3-none-any.whl

kickdown/__init__.py

@@ -0,0 +1,13 @@
+from .client import Client
+from .models import Performable, Stats, Task
+from .queue import Queue
+from .server import Server
+
+__all__ = [
+    "Client",
+    "Performable",
+    "Queue",
+    "Server",
+    "Stats",
+    "Task",
+]

kickdown/client.py

@@ -0,0 +1,32 @@
+import asyncio
+
+from .log import default_logger
+from .models import Task
+from .queue import Queue
+from .store import Store
+
+
+class Client:
+    def __init__(self, redis_url: str):
+        self._store = Store(redis_url)
+        self.logger = default_logger()
+
+    def queue(self, name: str) -> Queue:
+        return Queue(name, self._store)
+
+    async def enqueue(self, task: Task) -> str:
+        await self.queue(task.queue).push(task)
+        self.logger.info(
+            f"jid={task.jid} accepted",
+            extra={"queue": task.queue, "operation": task.operation},
+        )
+        return task.jid
+
+    async def close(self):
+        await asyncio.to_thread(self._store.close)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_exc_info):
+        await self.close()

kickdown/consumer.py

@@ -0,0 +1,144 @@
+import asyncio
+import logging
+import time
+from collections import deque
+from collections.abc import Awaitable, Callable, Mapping
+
+from pydantic import ValidationError
+
+from .log import default_logger
+from .models import Performable, Task
+from .queue import Queue
+from .store import Store, StoreError
+
+_default_pop_timeout = 5
+_retry_delay = 1
+_backoff_coefficient = 1.5
+
+
+class Consumer:
+    def __init__(
+        self,
+        store: Store,
+        workers: Mapping[tuple[str, str], Performable],
+        concurrency: int = 1,
+        logger: logging.Logger | None = None,
+    ):
+        self._store = store
+        self._workers = workers
+        self._queues: dict[str, Queue] = {
+            name: Queue(name, store)
+            for name in sorted({worker.queue for worker in workers.values()})
+        }
+        self._order: deque[str] = deque(self._queues)
+        self._semaphore = asyncio.Semaphore(concurrency)
+        self.logger = logger or default_logger()
+        self._tasks: set[asyncio.Task] = set()
+
+    async def consume(self) -> None:
+        while True:
+            await self._semaphore.acquire()
+
+            try:
+                task = await asyncio.to_thread(
+                    self._store.pop, self._poll_order(), _default_pop_timeout
+                )
+            except StoreError as err:
+                self._semaphore.release()
+                self.logger.error(
+                    "redis error while popping task", extra={"error": str(err)}
+                )
+                await asyncio.sleep(_default_pop_timeout)
+                continue
+            except ValidationError as err:
+                self._semaphore.release()
+                self.logger.error(
+                    "failed to parse task payload", extra={"error": str(err)}
+                )
+                continue
+
+            if task is None:
+                self._semaphore.release()
+                continue
+
+            handle = asyncio.create_task(self._run_task(task))
+            self._tasks.add(handle)
+            handle.add_done_callback(self._tasks.discard)
+
+    async def drain(self) -> None:
+        if self._tasks:
+            await asyncio.gather(*self._tasks, return_exceptions=True)
+
+    def _poll_order(self) -> list[str]:
+        order = list(self._order)
+        self._order.rotate(-1)
+        return order
+
+    def _queue(self, name: str) -> Queue:
+        # a payload naming a queue we do not serve is malformed, but its stats
+        # should still land on the queue it claims
+        return self._queues.get(name) or Queue(name, self._store)
+
+    async def _run_task(self, task: Task) -> None:
+        queue = self._queue(task.queue)
+        failure: Exception | None = None
+        try:
+            worker = self._workers.get((task.queue, task.operation))
+            if worker is None:
+                self.logger.error(
+                    f"no worker registered for task jid={task.jid}",
+                    extra={
+                        "jid": task.jid,
+                        "queue": task.queue,
+                        "operation": task.operation,
+                    },
+                )
+                await self._increment(queue.increment_failed)
+                return
+
+            self.logger.info(
+                f"jid={task.jid} started",
+                extra={"queue": task.queue, "operation": task.operation},
+            )
+            await worker.perform(task.params)
+            self.logger.info(f"jid={task.jid} done")
+            await self._increment(queue.increment_processed)
+        except Exception as err:  # noqa: BLE001 - worker code is arbitrary; retry boundary must catch anything
+            failure = err
+        finally:
+            self._semaphore.release()
+
+        if failure is None:
+            return
+
+        if task.retry_count > 0:
+            delay = _retry_delay * _backoff_coefficient**task.attempt
+            self.logger.warning(
+                f"jid={task.jid} failed, retrying in {delay:.1f}s "
+                f"({task.retry_count} attempt(s) left)",
+                extra={"error": str(failure)},
+            )
+            retry_task = task.model_copy(
+                update={
+                    "retry_count": task.retry_count - 1,
+                    "attempt": task.attempt + 1,
+                }
+            )
+            try:
+                await queue.schedule(retry_task, time.time() + delay)
+            except StoreError as schedule_err:
+                self.logger.error(
+                    f"jid={task.jid} failed to schedule retry",
+                    extra={"error": str(schedule_err)},
+                )
+        else:
+            self.logger.error(
+                f"jid={task.jid} failed permanently", extra={"error": str(failure)}
+            )
+            await self._increment(queue.increment_failed)
+
+    async def _increment(self, increment: Callable[[], Awaitable[None]]) -> None:
+        try:
+            await increment()
+        except StoreError as err:
+            self.logger.error("failed to update stats", extra={"error": str(err)})

kickdown/log.py

@@ -0,0 +1,14 @@
+import logging
+import sys
+
+_logger_name = "kickdown"
+
+
+def default_logger() -> logging.Logger:
+    logger = logging.getLogger(_logger_name)
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+    return logger

kickdown/models.py

@@ -0,0 +1,26 @@
+from typing import Annotated, Protocol, runtime_checkable
+
+from pydantic import BaseModel, Field
+from uuid_extensions import uuid7str
+
+
+@runtime_checkable
+class Performable(Protocol):
+    queue: str
+    operation: str
+
+    async def perform(self, payload: dict) -> None: ...
+
+
+class Task(BaseModel):
+    queue: str
+    operation: str
+    params: dict
+    jid: Annotated[str, Field(default_factory=lambda: uuid7str())]
+    retry_count: Annotated[int, Field(default=1)]
+    attempt: Annotated[int, Field(default=0)]
+
+
+class Stats(BaseModel):
+    processed: int = 0
+    failed: int = 0

kickdown/queue.py

@@ -0,0 +1,60 @@
+import asyncio
+
+from .models import Stats, Task
+from .store import Store
+
+
+class Queue:
+    """
+    A named queue: every per-queue operation, bound to one name.
+
+    Wraps the synchronous `Store` calls in threads, so callers stay async.
+    """
+
+    def __init__(self, name: str, store: Store):
+        self._name = name
+        self._store = store
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def __repr__(self) -> str:
+        return f"Queue({self._name!r})"
+
+    async def push(self, task: Task) -> None:
+        await asyncio.to_thread(self._store.push, task)
+
+    async def schedule(self, task: Task, run_at: float) -> None:
+        await asyncio.to_thread(self._store.schedule, task, run_at)
+
+    async def pending(self) -> list[Task]:
+        return await asyncio.to_thread(self._store.pending, self._name)
+
+    async def length(self) -> int:
+        return await asyncio.to_thread(self._store.queue_length, self._name)
+
+    async def scheduled(self) -> list[Task]:
+        return await asyncio.to_thread(self._store.scheduled, self._name)
+
+    async def scheduled_length(self) -> int:
+        return await asyncio.to_thread(self._store.scheduled_length, self._name)
+
+    async def enqueue_due(self, now: float, limit: int) -> int:
+        return await asyncio.to_thread(self._store.enqueue_due, self._name, now, limit)
+
+    async def purge(self) -> int:
+        """Drops every pending task, returning how many were dropped.
+
+        Scheduled tasks and the processed/failed counters are left alone.
+        """
+        return await asyncio.to_thread(self._store.purge, self._name)
+
+    async def stats(self) -> Stats:
+        return await asyncio.to_thread(self._store.stats, self._name)
+
+    async def increment_processed(self) -> None:
+        await asyncio.to_thread(self._store.increment_processed, self._name)
+
+    async def increment_failed(self) -> None:
+        await asyncio.to_thread(self._store.increment_failed, self._name)

kickdown/scheduler.py

@@ -0,0 +1,47 @@
+import asyncio
+import logging
+import time
+
+from .log import default_logger
+from .queue import Queue
+from .store import StoreError
+
+_default_poll_interval = 1
+_default_batch_size = 100
+
+
+class Scheduler:
+    """Moves tasks whose scheduled time has come back into their queues."""
+
+    def __init__(
+        self,
+        queues: list[Queue],
+        poll_interval: float = _default_poll_interval,
+        logger: logging.Logger | None = None,
+    ):
+        self._queues = queues
+        self._poll_interval = poll_interval
+        self.logger = logger or default_logger()
+
+    async def run(self) -> None:
+        while True:
+            await self._tick()
+            await asyncio.sleep(self._poll_interval)
+
+    async def _tick(self) -> None:
+        now = time.time()
+        for queue in self._queues:
+            try:
+                moved = await queue.enqueue_due(now, _default_batch_size)
+            except StoreError as err:
+                self.logger.error(
+                    "redis error while enqueueing due tasks",
+                    extra={"queue": queue.name, "error": str(err)},
+                )
+                continue
+
+            if moved:
+                self.logger.info(
+                    f"scheduler enqueued {moved} due task(s)",
+                    extra={"queue": queue.name},
+                )

kickdown/server.py

@@ -0,0 +1,151 @@
+import asyncio
+import signal
+from collections.abc import Awaitable, Callable
+
+from .consumer import Consumer
+from .log import default_logger
+from .models import Performable, Task
+from .queue import Queue
+from .scheduler import Scheduler
+from .store import Store, StoreError
+from .web import Web
+
+Hook = Callable[[], Awaitable[None]]
+
+
+class Server:
+    def __init__(
+        self,
+        redis_url: str,
+        concurrency: int = 1,
+        web_port: int = 3030,
+        admin_username: str | None = None,
+        admin_password: str | None = None,
+    ):
+        self._store = Store(redis_url)
+        self._concurrency = concurrency
+        self._web_port = web_port
+        self._admin_username = admin_username
+        self._admin_password = admin_password
+        self._startup_hooks: list[Hook] = []
+        self._shutdown_hooks: list[Hook] = []
+        self._worker: dict[tuple[str, str], Performable] = {}
+        self.logger = default_logger()
+
+    @property
+    def store(self) -> Store:
+        return self._store
+
+    @property
+    def queues(self) -> list[Queue]:
+        return [
+            Queue(name, self._store)
+            for name in sorted({worker.queue for worker in self._worker.values()})
+        ]
+
+    def queue(self, name: str) -> Queue:
+        return Queue(name, self._store)
+
+    def add_workers(self, *args: Performable):
+        for worker in args:
+            self._worker[(worker.queue, worker.operation)] = worker
+
+    async def enqueue(self, task: Task) -> str:
+        await self.queue(task.queue).push(task)
+        self.logger.info(
+            f"jid={task.jid} accepted",
+            extra={"queue": task.queue, "operation": task.operation},
+        )
+        return task.jid
+
+    def on_startup(self, fn: Hook) -> Hook:
+        self._startup_hooks.append(fn)
+        return fn
+
+    def on_shutdown(self, fn: Hook) -> Hook:
+        self._shutdown_hooks.append(fn)
+        return fn
+
+    async def run(self):
+        if not self._worker:
+            raise RuntimeError(
+                "No workers registered. Register them with add_workers() before running the server."
+            )
+
+        try:
+            await asyncio.to_thread(self._store.ping)
+        except StoreError as e:
+            raise RuntimeError(f"Redis connection failed: {e}") from e
+
+        consumer = Consumer(
+            store=self._store,
+            workers=self._worker,
+            concurrency=self._concurrency,
+            logger=self.logger,
+        )
+        scheduler = Scheduler(queues=self.queues, logger=self.logger)
+        web = Web(
+            port=self._web_port,
+            server=self,
+            admin_username=self._admin_username,
+            admin_password=self._admin_password,
+        )
+
+        await self._run_hooks(self._startup_hooks, "startup")
+
+        stop_event = asyncio.Event()
+        loop = asyncio.get_running_loop()
+        for sig in (signal.SIGTERM, signal.SIGINT):
+            loop.add_signal_handler(sig, stop_event.set)
+
+        self.logger.info(
+            f"server starting (queues={[q.name for q in self.queues]}, "
+            f"concurrency={self._concurrency}, web_port={self._web_port})"
+        )
+
+        consume_task = asyncio.create_task(consumer.consume(), name="consumer")
+        schedule_task = asyncio.create_task(scheduler.run(), name="scheduler")
+        web_task = asyncio.create_task(web.run(), name="web")
+        stop_task = asyncio.create_task(stop_event.wait(), name="stop")
+
+        try:
+            await asyncio.wait(
+                [consume_task, schedule_task, web_task, stop_task],
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+
+            for task in (consume_task, schedule_task, web_task):
+                if task.done() and not task.cancelled():
+                    exc = task.exception()
+                    if exc is not None:
+                        self.logger.error(
+                            f"{task.get_name()} task failed unexpectedly",
+                            extra={"error": str(exc)},
+                        )
+        finally:
+            self.logger.info("server shutting down")
+            consume_task.cancel()
+            schedule_task.cancel()
+            web_task.cancel()
+            stop_task.cancel()
+            await asyncio.gather(
+                consume_task, schedule_task, web_task, stop_task, return_exceptions=True
+            )
+            await consumer.drain()
+
+            await self._run_hooks(self._shutdown_hooks, "shutdown")
+
+            await asyncio.to_thread(self._store.close)
+
+    async def _run_hooks(self, hooks: list[Hook], phase: str) -> None:
+        for hook in hooks:
+            try:
+                await hook()
+            except Exception as err:  # noqa: BLE001 - hook code is arbitrary; must not abort the server
+                self.logger.error(
+                    f"{phase} hook failed",
+                    extra={
+                        "hook": getattr(hook, "__name__", repr(hook)),
+                        "error": str(err),
+                    },
+                )

kickdown/store.py

@@ -0,0 +1,162 @@
+from typing import cast
+
+from redis import Redis
+from redis.exceptions import RedisError
+
+from .models import Stats, Task
+
+
+class StoreError(Exception):
+    pass
+
+
+# Moves due tasks from a queue's scheduled set (KEYS[1]) into the queue itself
+# (KEYS[2]), atomically: a crash between the removal and the push would lose
+# them. Only the payloads actually pushed are removed, so tasks that become due
+# mid-script are left for the next sweep instead of being dropped.
+_ENQUEUE_DUE_LUA = """
+local due = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[1], 'LIMIT', 0, ARGV[2])
+if #due == 0 then
+    return 0
+end
+redis.call('RPUSH', KEYS[2], unpack(due))
+redis.call('ZREM', KEYS[1], unpack(due))
+return #due
+"""
+
+
+class Store:
+    _QUEUE_PREFIX = "kickdown:queue:"
+    _STATS_PREFIX = "kickdown:stats:"
+    _SCHEDULED_PREFIX = "kickdown:scheduled:"
+
+    def __init__(self, redis_url: str):
+        self._redis = Redis.from_url(redis_url)
+        self._enqueue_due = self._redis.register_script(_ENQUEUE_DUE_LUA)
+
+    @classmethod
+    def queue_key(cls, name: str) -> str:
+        return f"{cls._QUEUE_PREFIX}{name}"
+
+    @classmethod
+    def scheduled_key(cls, name: str) -> str:
+        return f"{cls._SCHEDULED_PREFIX}{name}"
+
+    @classmethod
+    def _processed_key(cls, queue: str) -> str:
+        return f"{cls._STATS_PREFIX}{queue}:processed"
+
+    @classmethod
+    def _failed_key(cls, queue: str) -> str:
+        return f"{cls._STATS_PREFIX}{queue}:failed"
+
+    def ping(self) -> None:
+        try:
+            self._redis.ping()
+        except RedisError as e:
+            raise StoreError(str(e)) from e
+
+    def push(self, task: Task) -> None:
+        try:
+            self._redis.rpush(self.queue_key(task.queue), task.model_dump_json())
+        except RedisError as e:
+            raise StoreError(str(e)) from e
+
+    def schedule(self, task: Task, run_at: float) -> None:
+        try:
+            self._redis.zadd(
+                self.scheduled_key(task.queue), {task.model_dump_json(): run_at}
+            )
+        except RedisError as e:
+            raise StoreError(str(e)) from e
+
+    def enqueue_due(self, queue: str, now: float, limit: int) -> int:
+        try:
+            moved = self._enqueue_due(
+                keys=[self.scheduled_key(queue), self.queue_key(queue)],
+                args=[now, limit],
+            )
+        except RedisError as e:
+            raise StoreError(str(e)) from e
+        return cast(int, moved)
+
+    def scheduled(self, queue: str) -> list[Task]:
+        try:
+            raw_tasks = cast(
+                list[bytes], self._redis.zrange(self.scheduled_key(queue), 0, -1)
+            )
+            return [Task.model_validate_json(raw) for raw in raw_tasks]
+        except RedisError as e:
+            raise StoreError(str(e)) from e
+
+    def scheduled_length(self, queue: str) -> int:
+        try:
+            return cast(int, self._redis.zcard(self.scheduled_key(queue)))
+        except RedisError as e:
+            raise StoreError(str(e)) from e
+
+    def pending(self, queue: str) -> list[Task]:
+        try:
+            raw_tasks = cast(
+                list[bytes], self._redis.lrange(self.queue_key(queue), 0, -1)
+            )
+            return [Task.model_validate_json(raw) for raw in raw_tasks]
+        except RedisError as e:
+            raise StoreError(str(e)) from e
+
+    def purge(self, queue: str) -> int:
+        try:
+            # MULTI/EXEC so the reported count is exactly what was dropped
+            pipe = self._redis.pipeline()
+            pipe.llen(self.queue_key(queue))
+            pipe.delete(self.queue_key(queue))
+            length, _ = cast(tuple[int, int], pipe.execute())
+        except RedisError as e:
+            raise StoreError(str(e)) from e
+        return length
+
+    def queue_length(self, queue: str) -> int:
+        try:
+            return cast(int, self._redis.llen(self.queue_key(queue)))
+        except RedisError as e:
+            raise StoreError(str(e)) from e
+
+    def pop(self, queues: list[str], timeout: int) -> Task | None:
+        try:
+            keys = [self.queue_key(queue) for queue in queues]
+            result = cast(
+                tuple[bytes, bytes] | None,
+                self._redis.blpop(keys, timeout=timeout),
+            )
+        except RedisError as e:
+            raise StoreError(str(e)) from e
+        if result is None:
+            return None
+        _, raw = result
+        return Task.model_validate_json(raw)
+
+    def increment_processed(self, queue: str) -> None:
+        try:
+            self._redis.incr(self._processed_key(queue))
+        except RedisError as e:
+            raise StoreError(str(e)) from e
+
+    def increment_failed(self, queue: str) -> None:
+        try:
+            self._redis.incr(self._failed_key(queue))
+        except RedisError as e:
+            raise StoreError(str(e)) from e
+
+    def stats(self, queue: str) -> Stats:
+        try:
+            processed = cast(bytes | None, self._redis.get(self._processed_key(queue)))
+            failed = cast(bytes | None, self._redis.get(self._failed_key(queue)))
+            return Stats(
+                processed=int(processed) if processed else 0,
+                failed=int(failed) if failed else 0,
+            )
+        except RedisError as e:
+            raise StoreError(str(e)) from e
+
+    def close(self) -> None:
+        self._redis.close()

kickdown/web/__init__.py

@@ -0,0 +1,98 @@
+import asyncio
+import secrets
+from html import escape
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+import uvicorn
+from fastapi import Depends, FastAPI, HTTPException
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.security import HTTPBasic, HTTPBasicCredentials
+from fastapi.staticfiles import StaticFiles
+
+from ..queue import Queue
+from ..store import Store, StoreError
+
+_ASSETS_DIR = Path(__file__).parent / "assets"
+_ADMIN_TEMPLATE = (Path(__file__).parent / "admin.html").read_text()
+
+_security = HTTPBasic(auto_error=False)
+
+
+@runtime_checkable
+class ServerLike(Protocol):
+    @property
+    def store(self) -> Store: ...
+
+    @property
+    def queues(self) -> list[Queue]: ...
+
+
+class Web:
+    def __init__(
+        self,
+        port: int,
+        server: ServerLike,
+        admin_username: str | None = None,
+        admin_password: str | None = None,
+    ):
+        self._port = port
+        self._server = server
+        self._admin_username = admin_username
+        self._admin_password = admin_password
+        self._api = FastAPI()
+        self._api.get("/live")(self._live)
+        self._api.get("/ready", response_model=None)(self._ready)
+        self._api.get("/admin", response_class=HTMLResponse)(self._admin)
+        self._api.mount("/admin/assets", StaticFiles(directory=_ASSETS_DIR), name="admin-assets")
+
+    async def _live(self) -> dict:
+        return {"status": "ok"}
+
+    async def _ready(self) -> dict | JSONResponse:
+        try:
+            await asyncio.to_thread(self._server.store.ping)
+        except StoreError:
+            return JSONResponse(status_code=503, content={"status": "redis unavailable"})
+        return {"status": "ok"}
+
+    def _authorized(self, credentials: HTTPBasicCredentials | None) -> bool:
+        if not (self._admin_username and self._admin_password):
+            return True
+        return (
+            credentials is not None
+            and secrets.compare_digest(credentials.username, self._admin_username)
+            and secrets.compare_digest(credentials.password, self._admin_password)
+        )
+
+    async def _admin(self, credentials: HTTPBasicCredentials | None = Depends(_security)) -> HTMLResponse:
+        if not self._authorized(credentials):
+            raise HTTPException(status_code=401, detail="Unauthorized", headers={"WWW-Authenticate": "Basic"})
+        return HTMLResponse(await self._render_admin())
+
+    async def _render_admin(self) -> str:
+        queues = self._server.queues
+        stats = await asyncio.gather(*(queue.stats() for queue in queues))
+        lengths = await asyncio.gather(*(queue.length() for queue in queues))
+        scheduled = await asyncio.gather(*(queue.scheduled_length() for queue in queues))
+
+        if queues:
+            rows = "\n".join(
+                f"<tr><td>{escape(queue.name)}</td><td>{length}</td>"
+                f"<td>{due}</td><td class=\"muted\">&mdash;</td></tr>"
+                for queue, length, due in zip(queues, lengths, scheduled, strict=True)
+            )
+        else:
+            rows = '<tr><td colspan="4">No queues registered</td></tr>'
+
+        return (
+            _ADMIN_TEMPLATE.replace("__TOTAL_PROCESSED__", str(sum(s.processed for s in stats)))
+            .replace("__TOTAL_FAILED__", str(sum(s.failed for s in stats)))
+            .replace("__TOTAL_SCHEDULED__", str(sum(scheduled)))
+            .replace("__QUEUE_ROWS__", rows)
+        )
+
+    async def run(self) -> None:
+        config = uvicorn.Config(self._api, host="0.0.0.0", port=self._port, log_level="error")
+        server = uvicorn.Server(config)
+        await server.serve()

kickdown/web/admin.html

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <title>kickdown admin</title>
+        <link rel="stylesheet" href="/admin/assets/admin.css">
+    </head>
+    <body>
+        <header>
+            <h1>kickdown</h1>
+        </header>
+
+        <section class="summary">
+            <div class="stat processed">
+                <span class="value">__TOTAL_PROCESSED__</span>
+                <span class="label">processed</span>
+            </div>
+            <div class="stat failed">
+                <span class="value">__TOTAL_FAILED__</span>
+                <span class="label">failed</span>
+            </div>
+            <div class="stat scheduled">
+                <span class="value">__TOTAL_SCHEDULED__</span>
+                <span class="label">scheduled</span>
+            </div>
+        </section>
+
+        <table class="queues">
+            <thead>
+                <tr>
+                    <th>Queue</th>
+                    <th>Pending</th>
+                    <th>Scheduled</th>
+                    <th>In-flight</th>
+                </tr>
+            </thead>
+            <tbody>
+                __QUEUE_ROWS__
+            </tbody>
+        </table>
+
+        <script src="/admin/assets/admin.js"></script>
+    </body>
+</html>

kickdown/web/assets/admin.css

@@ -0,0 +1,95 @@
+:root {
+    color-scheme: light dark;
+    --bg: #0f1115;
+    --panel: #171a21;
+    --text: #e6e6e6;
+    --muted: #9aa0ab;
+    --danger: #ff5c5c;
+    --pending: #e5a13a;
+    --border: #262b35;
+}
+
+* {
+    box-sizing: border-box;
+}
+
+body {
+    margin: 0;
+    padding: 2rem;
+    background: var(--bg);
+    color: var(--text);
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+h1 {
+    margin: 0 0 1.5rem;
+    font-size: 1.25rem;
+    font-weight: 600;
+}
+
+.summary {
+    display: flex;
+    gap: 1rem;
+    margin-bottom: 2rem;
+}
+
+.stat {
+    background: var(--panel);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 1rem 1.5rem;
+    min-width: 140px;
+}
+
+.stat .value {
+    display: block;
+    font-size: 2rem;
+    font-weight: 700;
+}
+
+.stat .label {
+    display: block;
+    color: var(--muted);
+    text-transform: uppercase;
+    font-size: 0.75rem;
+    letter-spacing: 0.05em;
+}
+
+.stat.failed .value {
+    color: var(--danger);
+}
+
+.stat.scheduled .value {
+    color: var(--pending);
+}
+
+table.queues {
+    width: 100%;
+    border-collapse: collapse;
+    background: var(--panel);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    overflow: hidden;
+}
+
+table.queues th,
+table.queues td {
+    text-align: left;
+    padding: 0.6rem 1rem;
+    border-bottom: 1px solid var(--border);
+}
+
+table.queues th {
+    color: var(--muted);
+    font-size: 0.75rem;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+}
+
+table.queues tr:last-child td {
+    border-bottom: none;
+}
+
+table.queues td.muted {
+    color: var(--muted);
+}

kickdown/web/assets/admin.js

@@ -0,0 +1 @@
+setTimeout(() => window.location.reload(), 5000);

kickdown-0.4.0a1.dist-info/METADATA

@@ -0,0 +1,273 @@
+Metadata-Version: 2.5
+Name: kickdown
+Version: 0.4.0a1
+Summary: A Redis-backed background job queue for Python
+Project-URL: Homepage, https://github.com/vklokov/kickdown
+Project-URL: Repository, https://github.com/vklokov/kickdown
+Project-URL: Issues, https://github.com/vklokov/kickdown/issues
+Project-URL: Changelog, https://github.com/vklokov/kickdown/blob/main/CHANGELOG.md
+Author-email: Vladimir Klokov <klokov.dev@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,background,jobs,queue,redis,tasks,worker
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: fastapi>=0.136.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: redis~=7.4
+Requires-Dist: uuid7>=0.1.0
+Requires-Dist: uvicorn>=0.34.0
+Description-Content-Type: text/markdown
+
+# kickdown
+
+A Redis-backed background job queue for Python.
+
+## Usage
+
+### Defining a worker
+
+Implement the `Performable` protocol: declare which queue a worker consumes
+from and which `operation` name identifies it, plus the async `perform` method.
+
+```python
+class SendEmailWorker:
+    queue = "emails"
+    operation = "send_email"
+
+    async def perform(self, payload: dict) -> None:
+        recipient = payload["to"]
+        # ... send email
+```
+
+Any number of queues is supported — a worker's `queue` attribute is what
+determines which Redis list it consumes from. The server automatically polls
+every queue that has at least one registered worker.
+
+### Running the server
+
+```python
+import asyncio
+from kickdown import Server
+from your_workers import SendEmailWorker, ExportReportWorker
+
+server = Server(
+    redis_url="redis://localhost:6379",
+    concurrency=5,  # optional, default: 1 - max tasks processed concurrently
+)
+server.add_workers(SendEmailWorker(), ExportReportWorker())
+
+asyncio.run(server.run())
+```
+
+`add_workers` accepts any number of `Performable` instances. Workers are
+resolved by their `(queue, operation)` pair, so the same `operation` name can
+be reused safely across different queues.
+
+Queues are polled with equal frequency in round-robin order — there is
+currently no notion of priority between queues.
+
+### Enqueueing jobs
+
+```python
+from kickdown import Client, Task
+
+client = Client(redis_url="redis://localhost:6379")
+
+task = Task(
+    queue="emails",
+    operation="send_email",
+    params={"to": "user@example.com"},
+)
+jid = await client.enqueue(task)
+```
+
+`enqueue` returns the job ID (`jid`) that can be used for tracing. It is
+generated automatically (a time-sortable `uuid7`) if not set explicitly on
+the `Task`.
+
+`Client` can also be used as an async context manager, which closes the
+underlying Redis connection on exit:
+
+```python
+async with Client(redis_url="redis://localhost:6379") as client:
+    await client.enqueue(task)
+```
+
+`Server` can enqueue tasks too, using the same Redis connection — handy for
+a worker that needs to schedule a follow-up task, or for enqueueing from a
+startup hook, without opening a separate `Client`:
+
+```python
+jid = await server.enqueue(task)
+```
+
+#### Retries
+
+`retry_count` (default `1`) on `Task` sets how many times a failed task is
+retried before being dropped. On failure, the consumer re-enqueues the task
+with `retry_count` decremented by one and `attempt` incremented by one, after
+an exponentially growing delay. Once `retry_count` reaches `0` the task is
+dropped.
+
+The delay is `1s * 1.5 ** attempt` — both the base delay and the backoff
+coefficient are fixed in the library and cannot be configured per task:
+
+| Retry | Delay |
+| ----- | ----- |
+| 1st   | 1.0s  |
+| 2nd   | 1.5s  |
+| 3rd   | 2.3s  |
+
+A retried task is not held in memory while it waits: it goes into the queue's
+scheduled sorted set in Redis (`kickdown:scheduled:{name}`, scored by its due
+timestamp), and a scheduler loop running inside every server moves due tasks
+back into the queue. So a retry survives a process restart, and the
+concurrency slot is freed immediately instead of being blocked for the whole
+delay.
+
+A server only sweeps the queues it has workers for, which is also the only
+place its own retries can land.
+
+Note that a task is still lost if the process dies *while its worker is
+running* — closing that window is the next step (an in-flight list per
+consumer plus a reaper).
+
+Queue names are raw identifiers (e.g. `"default"`, `"emails"`). The client
+constructs the full Redis key internally as `kickdown:queue:{name}`.
+
+### Inspecting a queue
+
+`client.queue(name)` returns a `Queue` handle — every per-queue operation
+lives on it, so the queue name is given once instead of on every call:
+
+```python
+emails = client.queue("emails")
+
+# Tasks waiting to be processed (non-destructive)
+tasks = await emails.pending()
+count = await emails.length()
+
+# Tasks waiting for their retry delay to elapse
+retries = await emails.scheduled()
+
+# Cumulative processed/failed counters
+stats = await emails.stats()
+print(stats.processed, stats.failed)
+```
+
+Enqueueing stays on the client (`client.enqueue(task)`): a `Task` already
+carries its own `queue`, and that field remains the single source of truth
+for routing.
+
+`purge()` drops every task waiting in the queue and returns how many were
+dropped. It does not touch scheduled tasks or the counters, and there is no
+undo:
+
+```python
+dropped = await emails.purge()
+```
+
+`processed` counts tasks whose worker completed successfully; `failed`
+counts tasks that were permanently dropped (retries exhausted, or no
+worker registered for the task's `operation`).
+
+### Lifecycle hooks
+
+Register async callbacks to run on server startup and shutdown — useful for
+initialising shared resources like database pools.
+
+```python
+server = Server(redis_url=...)
+
+@server.on_startup
+async def init_db():
+    app.db = await asyncpg.create_pool(DATABASE_URL)
+
+@server.on_shutdown
+async def close_db():
+    await app.db.close()
+```
+
+Both methods can also be called directly instead of used as decorators:
+
+```python
+server.on_startup(init_db)
+server.on_shutdown(close_db)
+```
+
+Startup hooks run after the Redis connection is verified, before the
+consumer starts. Shutdown hooks run after the consumer stops (whether by
+`SIGTERM`/`SIGINT` or an unexpected error), before the Redis connection is
+closed.
+
+### Logging
+
+`Client` and `Server` each expose a plain `logging.Logger` as `.logger`,
+pre-configured to write text to stdout — there's no custom logger
+interface to implement. To use your own logger (different format, handler,
+sink, etc.), just assign it:
+
+```python
+import logging
+
+server.logger = logging.getLogger("myapp.kickdown")
+client.logger = logging.getLogger("myapp.kickdown")
+```
+
+`Client` logs when a task is accepted. `Server` logs process start/shutdown
+(with the polled queues and concurrency), and each task's start,
+completion, retries and permanent failures — every task-related message
+includes the task's `jid`.
+
+### Healthcheck
+
+`Server` always starts a small HTTP server for liveness/readiness probes,
+on the port given by `web_port` (default `3030`):
+
+```python
+server = Server(redis_url=..., web_port=3030)
+```
+
+```
+GET /live   -> 200 {"status": "ok"}                         # process is up
+GET /ready  -> 200 {"status": "ok"}                          # Redis reachable
+            -> 503 {"status": "redis unavailable"}           # Redis unreachable
+```
+
+### Admin page
+
+`GET /admin` renders an HTML dashboard: a summary block with total
+processed/failed counters (aggregated across all queues, from the same
+counters as `client.stats()`), and a table of every polled queue with its
+current pending count (how many tasks are physically waiting in it).
+
+By default it's open to anyone who can reach the port. To require HTTP
+Basic Auth, set both `admin_username` and `admin_password`:
+
+```python
+server = Server(
+    redis_url=...,
+    admin_username="alice",
+    admin_password="secret",
+)
+```
+
+If either is left unset, `/admin` requires no credentials.
+
+## Scaling
+
+`Server.run()` uses a single asyncio event loop with an `asyncio.Semaphore`
+to cap concurrent task execution within the process — this is a good fit
+since `Performable.perform` is a coroutine. To scale across CPU cores or
+machines, run multiple `Server` processes against the same Redis instance;
+each process independently pops from the shared queues, so Redis balances
+the work between them without any extra coordination.

kickdown-0.4.0a1.dist-info/RECORD

@@ -0,0 +1,18 @@
+kickdown/__init__.py,sha256=MWGFtF65s3-oJ1duf7pTEwaRzj2jET8az5z8KvxlwdA,224
+kickdown/client.py,sha256=zo8eNcbf3yyBvqDn1wEl5lzT7zMIZADoaJH_De5ROik,809
+kickdown/consumer.py,sha256=E4-IHwEHbkgInvWuiuBuzYCH6ANg3VdAojRW6AVYS0g,5054
+kickdown/log.py,sha256=QrwyR4KwJgvqV4JUa3HMy6OBoVqfd1mpviwoOc2oxzo,400
+kickdown/models.py,sha256=F5E1cRC09pUoV9Lh-V6eOzbDobQvrGYaNQsN9h-N4KI,583
+kickdown/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kickdown/queue.py,sha256=V0I0wu8LrwZV5kewqUjEKz73qd1tf8K4jvaAxlZ1cpA,1972
+kickdown/scheduler.py,sha256=wb17YgO8Px6QLrKeildpHQuibutq7PEhVCWxLFx9p58,1331
+kickdown/server.py,sha256=ydXVtxtzG2QTi4J3DFJTA-gtE_ReaNCG3epiMZDMiB0,5059
+kickdown/store.py,sha256=dADwPw2mXW4qdhv22wB0hMxINBi2msUOJhIEalBOVMI,5365
+kickdown/web/__init__.py,sha256=64q0t1gcVCraryPVkxP6LE7-SuZjBtx5Z8Gyo_dMhHw,3645
+kickdown/web/admin.html,sha256=eD8n8lgAainfjOqGC-hCElEfoa4kutQ5Lf74B6u7dPg,1345
+kickdown/web/assets/admin.css,sha256=IMVkbuEyobT3h5r_NCAuOykKmACfc2t5C8VsCInfAOQ,1584
+kickdown/web/assets/admin.js,sha256=_5pHZNIZctM-x3XgrNH37NQMwrDyCb6VblTvOHkWPTA,50
+kickdown-0.4.0a1.dist-info/METADATA,sha256=dY9fsDP7XlqPKFBI0aWd_1lJKO7T3tPvY-uFRpCmNw0,8710
+kickdown-0.4.0a1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+kickdown-0.4.0a1.dist-info/licenses/LICENSE,sha256=cViUjOoePpSXj9vB-Ckzg1zdh8I9wIb3SciUnifkQCA,1072
+kickdown-0.4.0a1.dist-info/RECORD,,

kickdown-0.4.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

kickdown-0.4.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladimir Klokov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.