akadze 0.1.0__tar.gz

akadze-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 g4st3r
+
+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.

akadze-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: akadze
+Version: 0.1.0
+Summary: Postgres-backed task queue. The broker is PostgreSQL.
+License: MIT
+License-File: LICENSE
+Keywords: postgres,queue,worker,tasks
+Author: g4st3r
+Requires-Python: >=3.13,<3.14
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: asyncpg (>=0.30.0,<0.31.0)
+Requires-Dist: croniter (>=6.0.0,<7.0.0)
+Requires-Dist: pydantic (>=2.10.0,<3.0.0)
+Requires-Dist: sqlalchemy[asyncio] (>=2.0.40,<3.0.0)
+Project-URL: Homepage, https://github.com/g4st3r-d3v/akadze
+Project-URL: Repository, https://github.com/g4st3r-d3v/akadze
+Description-Content-Type: text/markdown
+
+# akadze
+
+[![ci](https://github.com/g4st3r-d3v/akadze/actions/workflows/ci.yml/badge.svg)](https://github.com/g4st3r-d3v/akadze/actions/workflows/ci.yml)
+
+Postgres-backed task queue: enqueue work and run it in a worker. Periodic schedules run in that same process.
+
+Shape is familiar if you know Celery. The broker is PostgreSQL (`FOR UPDATE SKIP LOCKED` + lease), not Redis or RabbitMQ.
+
+**Status:** alpha. Enqueue, the worker, periodic schedules, retry, and queue maintenance run on Postgres.
+
+## Goals
+
+- Small library, no product domain
+- Tasks, retries, lease recovery
+- Periodic cron and interval schedules run inside the worker
+- Clear Python call surface; CLI for migrate and worker
+
+## Non-goals (for now)
+
+- HTTP / REST / web UI (another library or app owns that)
+- Replacing any product service queue
+- Multi-broker adapters
+- Distributed tracing / full observability suite
+
+## First task
+
+Install the library, point it at the application database, and create the `akadze` schema. The tables live in that schema; they are not part of the application's own migrations.
+
+```bash
+poetry install
+export AKADZE_DATABASE_URL=postgresql://akadze:akadze@localhost:5432/akadze
+akadze migrate
+```
+
+Save this as `demo.py`. `enqueue` runs in the caller's transaction, so a rollback removes the job.
+
+```python
+import asyncio
+
+from akadze import Akadze
+
+app = Akadze(database_url="postgresql://akadze:akadze@localhost:5432/akadze")
+
+
+@app.task("hello")
+async def hello(name: str) -> str:
+    return f"hello {name}"
+
+
+async def main() -> None:
+    async with app.engine.begin() as connection:
+        await hello.using(session=connection).enqueue(name="ada")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Run the worker from the directory that contains `demo.py`. It loads `demo:app` from there, claims the job, runs `hello`, and sets the row to `succeeded`. Stop it with Ctrl-C: the worker takes no new jobs and waits up to 10 seconds (`shutdown_timeout`) for the ones already running. Whatever is still running goes back to the queue, and an attempt is not spent. Periodic tasks run in this same process; there is no separate beat.
+
+If a heartbeat does not succeed within 30 seconds, the worker stops and puts unfinished jobs back on the queue. An attempt is not spent. A synchronous task runs in a thread. Stopping the worker does not stop that thread.
+
+A claim that fills every free slot is followed by another claim immediately. Otherwise the worker waits up to `poll_interval` (1 second). The wait is at least half of that, so idle workers do not poll in step or spin. A job can run more than once if its worker disappears.
+
+```bash
+python demo.py
+akadze worker demo:app
+```
+
+`akadze.jobs.state` is then `succeeded`. A higher `priority` is claimed first. `result` is optional. Pass enqueue options (`delay`, `run_at`, `priority`, `unique_key`, `expires_at`) through `using(...)`, not as task arguments. `expires_at` must be timezone-aware. A job that has already expired is cancelled before it runs. A second enqueue with the same active `unique_key` raises `DuplicateJob` and does not abort the rest of the caller's transaction.
+
+Enqueue the follow-up job on the `complete_tx` connection so it commits only if this job succeeds:
+
+```python
+from akadze import current
+
+async with current().complete_tx() as connection:
+    await next_step.using(session=connection).enqueue()
+```
+
+To commit your own writes together with the transition to `succeeded`, take the connection from `current().complete_tx()`. If this run no longer owns the job, or the job was cancelled or has expired, the block raises and those writes roll back. An error inside the block rolls the writes back and spends an attempt.
+
+```python
+from akadze import current
+
+async with current().complete_tx() as connection:
+    await connection.execute(...)
+```
+
+`akadze.testing.drain(app)` runs every job that is ready now. `assert_enqueued(app, "hello", name="ada")` checks that a queued or running job has those arguments.
+
+`queue_snapshot(engine)` reads committed rows: how many jobs are in each queue and state, how long the oldest ready job has waited, and how many are running. Count outcomes in an `on_transition` hook. Do not log task arguments or results.
+
+Do not copy this package's SQL into the application's Alembic history. Deploy runs `akadze migrate`, or `await migrate(database_url)`, against the same database. The engine disables asyncpg's statement cache so a transaction-mode pool such as PgBouncer can sit in front.
+
+Tests use `AKADZE_DATABASE_URL` and drop schema `akadze` in that database. The database name must be `akadze` or end with `_test`.
+
+## Release
+
+Create a tag `vX.Y.Z` that matches the version in `pyproject.toml` and push it. GitHub Actions runs the tests, publishes the wheel to PyPI, and opens a GitHub release.
+
+PyPI trusted publishing, set once on the project `akadze`:
+
+- Owner: `g4st3r-d3v`
+- Repository: `akadze`
+- Workflow: `release.yml`
+- Environment: `pypi`
+
+After that publish succeeds, an application installs the package from PyPI:
+
+```bash
+pip install akadze
+```
+
+## Layout
+
+```text
+akadze/   # library package
+tests/
+```
+
+Design notes: [`g4st3r-d3v/akadze-harness`](https://github.com/g4st3r-d3v/akadze-harness) (`HUB.md`). This repo is code-only.
+
+## License
+
+MIT
+

akadze-0.1.0/README.md

@@ -0,0 +1,126 @@
+# akadze
+
+[![ci](https://github.com/g4st3r-d3v/akadze/actions/workflows/ci.yml/badge.svg)](https://github.com/g4st3r-d3v/akadze/actions/workflows/ci.yml)
+
+Postgres-backed task queue: enqueue work and run it in a worker. Periodic schedules run in that same process.
+
+Shape is familiar if you know Celery. The broker is PostgreSQL (`FOR UPDATE SKIP LOCKED` + lease), not Redis or RabbitMQ.
+
+**Status:** alpha. Enqueue, the worker, periodic schedules, retry, and queue maintenance run on Postgres.
+
+## Goals
+
+- Small library, no product domain
+- Tasks, retries, lease recovery
+- Periodic cron and interval schedules run inside the worker
+- Clear Python call surface; CLI for migrate and worker
+
+## Non-goals (for now)
+
+- HTTP / REST / web UI (another library or app owns that)
+- Replacing any product service queue
+- Multi-broker adapters
+- Distributed tracing / full observability suite
+
+## First task
+
+Install the library, point it at the application database, and create the `akadze` schema. The tables live in that schema; they are not part of the application's own migrations.
+
+```bash
+poetry install
+export AKADZE_DATABASE_URL=postgresql://akadze:akadze@localhost:5432/akadze
+akadze migrate
+```
+
+Save this as `demo.py`. `enqueue` runs in the caller's transaction, so a rollback removes the job.
+
+```python
+import asyncio
+
+from akadze import Akadze
+
+app = Akadze(database_url="postgresql://akadze:akadze@localhost:5432/akadze")
+
+
+@app.task("hello")
+async def hello(name: str) -> str:
+    return f"hello {name}"
+
+
+async def main() -> None:
+    async with app.engine.begin() as connection:
+        await hello.using(session=connection).enqueue(name="ada")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Run the worker from the directory that contains `demo.py`. It loads `demo:app` from there, claims the job, runs `hello`, and sets the row to `succeeded`. Stop it with Ctrl-C: the worker takes no new jobs and waits up to 10 seconds (`shutdown_timeout`) for the ones already running. Whatever is still running goes back to the queue, and an attempt is not spent. Periodic tasks run in this same process; there is no separate beat.
+
+If a heartbeat does not succeed within 30 seconds, the worker stops and puts unfinished jobs back on the queue. An attempt is not spent. A synchronous task runs in a thread. Stopping the worker does not stop that thread.
+
+A claim that fills every free slot is followed by another claim immediately. Otherwise the worker waits up to `poll_interval` (1 second). The wait is at least half of that, so idle workers do not poll in step or spin. A job can run more than once if its worker disappears.
+
+```bash
+python demo.py
+akadze worker demo:app
+```
+
+`akadze.jobs.state` is then `succeeded`. A higher `priority` is claimed first. `result` is optional. Pass enqueue options (`delay`, `run_at`, `priority`, `unique_key`, `expires_at`) through `using(...)`, not as task arguments. `expires_at` must be timezone-aware. A job that has already expired is cancelled before it runs. A second enqueue with the same active `unique_key` raises `DuplicateJob` and does not abort the rest of the caller's transaction.
+
+Enqueue the follow-up job on the `complete_tx` connection so it commits only if this job succeeds:
+
+```python
+from akadze import current
+
+async with current().complete_tx() as connection:
+    await next_step.using(session=connection).enqueue()
+```
+
+To commit your own writes together with the transition to `succeeded`, take the connection from `current().complete_tx()`. If this run no longer owns the job, or the job was cancelled or has expired, the block raises and those writes roll back. An error inside the block rolls the writes back and spends an attempt.
+
+```python
+from akadze import current
+
+async with current().complete_tx() as connection:
+    await connection.execute(...)
+```
+
+`akadze.testing.drain(app)` runs every job that is ready now. `assert_enqueued(app, "hello", name="ada")` checks that a queued or running job has those arguments.
+
+`queue_snapshot(engine)` reads committed rows: how many jobs are in each queue and state, how long the oldest ready job has waited, and how many are running. Count outcomes in an `on_transition` hook. Do not log task arguments or results.
+
+Do not copy this package's SQL into the application's Alembic history. Deploy runs `akadze migrate`, or `await migrate(database_url)`, against the same database. The engine disables asyncpg's statement cache so a transaction-mode pool such as PgBouncer can sit in front.
+
+Tests use `AKADZE_DATABASE_URL` and drop schema `akadze` in that database. The database name must be `akadze` or end with `_test`.
+
+## Release
+
+Create a tag `vX.Y.Z` that matches the version in `pyproject.toml` and push it. GitHub Actions runs the tests, publishes the wheel to PyPI, and opens a GitHub release.
+
+PyPI trusted publishing, set once on the project `akadze`:
+
+- Owner: `g4st3r-d3v`
+- Repository: `akadze`
+- Workflow: `release.yml`
+- Environment: `pypi`
+
+After that publish succeeds, an application installs the package from PyPI:
+
+```bash
+pip install akadze
+```
+
+## Layout
+
+```text
+akadze/   # library package
+tests/
+```
+
+Design notes: [`g4st3r-d3v/akadze-harness`](https://github.com/g4st3r-d3v/akadze-harness) (`HUB.md`). This repo is code-only.
+
+## License
+
+MIT

akadze-0.1.0/akadze/__about__.py

@@ -0,0 +1,3 @@
+"""Public version. Bump with releases; keep scaffold honest about 0.x."""
+
+__version__ = "0.1.0"

akadze-0.1.0/akadze/__init__.py

@@ -0,0 +1,28 @@
+"""Postgres task queue. The broker is PostgreSQL."""
+
+from akadze.app import Akadze
+from akadze.context import current
+from akadze.enqueue import request_cancel
+from akadze.exc import AkadzeError, Cancel, DuplicateJob, EnqueueError, Fail, Retry, Snooze
+from akadze.queue import QueueSnapshot, StateCount, queue_snapshot
+from akadze.schema import applied_versions, migrate
+from akadze.worker import Worker
+
+__all__ = [
+    "Akadze",
+    "AkadzeError",
+    "Cancel",
+    "DuplicateJob",
+    "EnqueueError",
+    "Fail",
+    "QueueSnapshot",
+    "Retry",
+    "Snooze",
+    "StateCount",
+    "Worker",
+    "applied_versions",
+    "current",
+    "migrate",
+    "queue_snapshot",
+    "request_cancel",
+]

akadze-0.1.0/akadze/app.py

@@ -0,0 +1,103 @@
+"""Registry of tasks. The engine belongs to the worker, not to enqueue."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import timedelta
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+from akadze.exc import AkadzeError
+from akadze.hooks import Hooks
+from akadze.periodic import Schedule
+from akadze.schema import async_database_url
+from akadze.task import Task
+
+
+class Akadze:
+    def __init__(
+        self,
+        *,
+        engine: AsyncEngine | None = None,
+        database_url: str | None = None,
+        grace: timedelta = timedelta(minutes=1),
+        retention: timedelta = timedelta(days=7),
+    ) -> None:
+        if engine is None and database_url is None:
+            raise AkadzeError("Akadze needs an engine or a database_url")
+        self.engine = engine or create_async_engine(
+            async_database_url(database_url or ""),
+            connect_args={"statement_cache_size": 0},
+        )
+        self._owns_engine = engine is None
+        self.grace = grace
+        self.retention = retention
+        self.hooks = Hooks()
+        self.tasks: dict[str, Task[Any]] = {}
+        self.schedules: list[Schedule] = []
+
+    def task[**P](
+        self,
+        name: str,
+        *,
+        queue: str = "default",
+        max_attempts: int = 3,
+        timeout: timedelta | None = None,
+        priority: int = 0,
+    ) -> Callable[[Callable[P, Any]], Task[P]]:
+        if max_attempts < 1:
+            raise AkadzeError("max_attempts must be at least 1")
+        if timeout is not None and timeout <= timedelta(0):
+            raise AkadzeError("timeout must be positive")
+
+        def decorate(fn: Callable[P, Any]) -> Task[P]:
+            if name in self.tasks:
+                raise AkadzeError(f"task {name} is already registered")
+            registered: Task[P] = Task(
+                self,
+                name,
+                fn,
+                queue=queue,
+                max_attempts=max_attempts,
+                timeout=timeout,
+                priority=priority,
+            )
+            self.tasks[name] = registered
+            return registered
+
+        return decorate
+
+    def periodic(
+        self,
+        name: str,
+        *,
+        cron: str | None = None,
+        every: timedelta | None = None,
+        overlap: bool = True,
+        queue: str = "default",
+        max_attempts: int = 3,
+        timeout: timedelta | None = None,
+    ) -> Callable[[Callable[..., Any]], Task[Any]]:
+        if (cron is None) == (every is None):
+            raise AkadzeError("periodic needs cron or every")
+        if every is not None and every <= timedelta(0):
+            raise AkadzeError("every must be positive")
+
+        def decorate(fn: Callable[..., Any]) -> Task[Any]:
+            registered = self.task(
+                name,
+                queue=queue,
+                max_attempts=max_attempts,
+                timeout=timeout,
+            )(fn)
+            self.schedules.append(
+                Schedule(name=name, cron=cron, every=every, overlap=overlap, queue=queue)
+            )
+            return registered
+
+        return decorate
+
+    async def aclose(self) -> None:
+        if self._owns_engine:
+            await self.engine.dispose()

akadze-0.1.0/akadze/args.py

@@ -0,0 +1,58 @@
+"""Validate task arguments against the function signature."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any, cast, get_type_hints
+
+from pydantic import BaseModel, ConfigDict, ValidationError, create_model
+
+from akadze.exc import EnqueueError
+
+
+def argument_model(fn: Callable[..., Any]) -> type[BaseModel]:
+    signature = inspect.signature(fn)
+    hints = get_type_hints(fn)
+    fields: dict[str, Any] = {}
+    for name, param in signature.parameters.items():
+        if param.kind in (param.VAR_POSITIONAL, param.VAR_KEYWORD):
+            raise EnqueueError(f"task {fn.__name__} cannot take *args or **kwargs")
+        if param.kind is param.POSITIONAL_ONLY:
+            raise EnqueueError(f"task {fn.__name__} cannot take positional-only arguments")
+        annotation = hints.get(name, Any)
+        default: Any = ... if param.default is inspect.Parameter.empty else param.default
+        fields[name] = (annotation, default)
+    model = create_model(
+        f"{fn.__name__}Args",
+        __config__=ConfigDict(extra="forbid"),
+        **fields,
+    )
+    return cast(type[BaseModel], model)
+
+
+def dump_arguments(
+    model: type[BaseModel],
+    arguments: dict[str, Any],
+    *,
+    task: str,
+) -> dict[str, Any]:
+    try:
+        parsed = model.model_validate(arguments)
+    except ValidationError as exc:
+        raise EnqueueError(f"invalid arguments for task {task}") from exc
+    dumped = parsed.model_dump(mode="json")
+    if not isinstance(dumped, dict):
+        raise EnqueueError(f"invalid arguments for task {task}")
+    return dumped
+
+
+def load_arguments(model: type[BaseModel], payload: dict[str, Any]) -> dict[str, Any]:
+    try:
+        parsed = model.model_validate(payload)
+    except ValidationError:
+        raise RuntimeError("invalid arguments") from None
+    dumped = parsed.model_dump()
+    if not isinstance(dumped, dict):
+        raise RuntimeError("invalid arguments")
+    return dumped

akadze-0.1.0/akadze/cli.py

@@ -0,0 +1,117 @@
+"""CLI entrypoints: worker, beat, migrate."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import os
+import signal
+import sys
+
+from akadze.__about__ import __version__
+from akadze.app import Akadze
+from akadze.schema import MigrateError, applied_versions, migrate, redact_database_url
+from akadze.worker import Worker
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="akadze", description="Postgres-backed task queue")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    worker = sub.add_parser("worker", help="Claim and run registered tasks")
+    worker.add_argument("app", help="Import path of an Akadze app, for example demo:app")
+    worker.add_argument("--slots", type=int, default=1)
+    worker.add_argument("--queue", action="append", dest="queues")
+    sub.add_parser("beat", help="Unused: periodic tasks run inside the worker")
+    sub.add_parser("migrate", help="Apply schema migrations")
+
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 0
+    if args.command == "migrate":
+        return _run_migrate()
+    if args.command == "beat":
+        print(
+            "periodic tasks run inside `akadze worker`; there is no beat process",
+            file=sys.stderr,
+        )
+        return 1
+    if args.command == "worker":
+        return _run_worker(args.app, slots=args.slots, queues=args.queues)
+
+    print(f"akadze {__version__}: `{args.command}` is not implemented yet.", file=sys.stderr)
+    return 1
+
+
+async def _newly_applied(database_url: str) -> list[str]:
+    before = set(await applied_versions(database_url))
+    await migrate(database_url)
+    after = await applied_versions(database_url)
+    return [version for version in after if version not in before]
+
+
+def _run_migrate() -> int:
+    database_url = os.environ.get("AKADZE_DATABASE_URL", "").strip()
+    if not database_url:
+        print("AKADZE_DATABASE_URL is not set", file=sys.stderr)
+        return 2
+    try:
+        applied = asyncio.run(_newly_applied(database_url))
+    except (MigrateError, ValueError, OSError) as exc:
+        print(f"migrate failed: {redact_database_url(str(exc), database_url)}", file=sys.stderr)
+        return 1
+    if applied:
+        for version in applied:
+            print(f"applied {version}")
+    else:
+        print("schema up to date")
+    return 0
+
+
+def _run_worker(spec: str, *, slots: int, queues: list[str] | None) -> int:
+    app = _load_app(spec)
+    worker = Worker(app, slots=slots, queues=queues)
+
+    async def _run() -> None:
+        try:
+            await _serve(worker)
+        finally:
+            await app.aclose()
+
+    try:
+        asyncio.run(_run())
+    except (ValueError, OSError) as exc:
+        print(f"worker failed: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+async def _serve(worker: Worker) -> None:
+    stop = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, stop.set)
+    await worker.serve(stop)
+
+
+def _load_app(spec: str) -> Akadze:
+    module_name, separator, attribute = spec.partition(":")
+    if separator != ":" or not module_name or not attribute:
+        print("app must look like package.module:app", file=sys.stderr)
+        raise SystemExit(2)
+    cwd = os.getcwd()
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+    module = importlib.import_module(module_name)
+    app = getattr(module, attribute, None)
+    if not isinstance(app, Akadze):
+        print(f"{spec} is not an Akadze app", file=sys.stderr)
+        raise SystemExit(2)
+    return app
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

akadze-0.1.0/akadze/context.py

@@ -0,0 +1,67 @@
+"""The job that is running on this task, and a transaction that finishes it."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+
+from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine
+
+from akadze.exc import AkadzeError
+
+_Finish = Callable[[AsyncConnection], Awaitable[None]]
+
+
+@dataclass
+class _Run:
+    engine: AsyncEngine
+    finish: _Finish
+    done: bool = False
+    busy: bool = False
+
+
+_current: ContextVar[_Run | None] = ContextVar("akadze_run", default=None)
+
+
+class Context:
+    """Handle for the job executing on this asyncio task."""
+
+    def __init__(self, run: _Run) -> None:
+        self._run = run
+
+    @asynccontextmanager
+    async def complete_tx(self) -> AsyncIterator[AsyncConnection]:
+        """Yield a connection. On a clean exit the job is finished in that transaction."""
+
+        if self._run.done:
+            raise AkadzeError("job is already complete")
+        if self._run.busy:
+            raise AkadzeError("complete_tx() is already open")
+        self._run.busy = True
+        try:
+            async with self._run.engine.begin() as connection:
+                yield connection
+                await self._run.finish(connection)
+            self._run.done = True
+        finally:
+            self._run.busy = False
+
+
+def current() -> Context:
+    """Return the job running on this asyncio task."""
+
+    run = _current.get()
+    if run is None:
+        raise AkadzeError("current() is only valid inside a running job")
+    return Context(run)
+
+
+def bind_run(engine: AsyncEngine, finish: _Finish) -> tuple[_Run, Token[_Run | None]]:
+    run = _Run(engine=engine, finish=finish)
+    return run, _current.set(run)
+
+
+def reset_run(token: Token[_Run | None]) -> None:
+    _current.reset(token)