litestar-queues

litestar-queues

litestar-queues 0.9.0 is the first-party Litestar worker abstraction for task registration, durable queue state, worker lifecycle, schedules, uniqueness, bounded maintenance, execution dispatch, and application-facing task events.

Keep persistence and placement separate:

• A queue backend stores task records, identities, maintenance coordination, and optional event history.
• An execution backend decides where a claimed task runs.
• Worker wakeups are delivery hints. Persisted queue records remain the source of truth.

Code Style Rules

• Use QueuePlugin to wire lifecycle, application state, DI, task discovery, schedules, workers, and CLI commands.
• Put worker settings under QueueConfig(worker=WorkerConfig(...)).
• Inject QueueService with NamedDependency[QueueService]; never use a module-level service from handlers.
• Import public core types from litestar_queues. Import optional backend configuration from its backend submodule (.sqlspec, .advanced_alchemy, .redis, .valkey) and execution configs from litestar_queues or their respective submodules.
• Keep persistent-backend arguments and metadata JSON-serializable. Pass stable object IDs instead of large payloads.
• Use PEP 604 unions (T | None) and async I/O. Prefer msgspec for event/client DTOs unless the project already uses Pydantic.

Quick Reference

Minimal Plugin Setup

from litestar import Litestar, post
from litestar.di import NamedDependency
from litestar_queues import QueueConfig, QueuePlugin, QueueService, WorkerConfig, task


@task("accounts.sync", queue="accounts", retries=3, timeout=300)
async def sync_account(account_id: str) -> dict[str, str]:
    return {"account_id": account_id, "status": "synced"}


@post("/accounts/{account_id:str}/sync")
async def create_sync_job(
    account_id: str,
    queue_service: NamedDependency[QueueService],
) -> dict[str, str]:
    result = await queue_service.enqueue(sync_account, account_id)
    return {"task_id": str(result.id), "status": result.status or "queued"}


app = Litestar(
    route_handlers=[create_sync_job],
    plugins=[
        QueuePlugin(
            QueueConfig(worker=WorkerConfig(placement="server")),
        ),
    ],
)