Skip to content

Litestar Queues

Litestar Queues Litestar Queues

Async task queues, supervised workers, cron schedules, realtime SSE & WebSocket event streams, and decoupled storage & execution backends for Litestar.

Decoupled Storage & Execution Architecture

litestar-queues separates where task state lives (BaseQueueBackend) from how execution is triggered (BaseExecutionBackend). External transports and cloud dispatchers carry only an ID-only {"version": 1, "task_id": "<uuid>"} envelope—never serializing task arguments, retry counters, or results onto the wire.

Decoupled Task Storage vs Execution Transport QueueService.enqueue writes the authoritative QueuedTaskRecord to BaseQueueBackend while BaseExecutionBackend carries only an ID-only version 1 task_id envelope. Litestar Route / Caller QueueService.enqueue() @task.enqueue(...) / enqueue_many() Validates TaskDefinition & options Computes unique_key & delay QueuedBackgroundTask 1. Persist Record 2. Dispatch ID Authoritative Task Storage BaseQueueBackend (QueuedTaskRecord) Arguments • Status • Leases • Retries • Results SQLSpec (11 DBs) • Advanced Alchemy • Redis • Valkey ID-Only Execution Transport {"version": 1, "task_id": "<uuid>"} Never carries task arguments or retry state on wire Local • Cloud Tasks • Cloud Run • Pub/Sub • SQS • Kafka Worker / Push Target claim_task(task_id) Claims authoritative record Runs WorkerHeartbeatManager Resolves DI & TaskExecutionContext complete_task / fail_task
Epoch-Fenced Task Claim, Heartbeat & Settlement Every heartbeat and terminal transition validates status='running', expected_retry_count, and expected_execution_ref to prevent zombie workers from overwriting reclaimed tasks. 1. Atomic Claim dequeue_tasks / claim_task Transitions pending/scheduled -> running Captures retry_count & execution_ref Stamps started_at & heartbeat_at FOR UPDATE SKIP LOCKED / Lua 2. Fenced Heartbeat Loop heartbeat_tasks(..., expected_*) Requires status == "running" Requires retry_count == expected Requires execution_ref == expected Lease lost -> cancel execution 3. Fenced Settlement complete_task / fail_task Conditional CAS on epoch + lease Persists result or schedules retry Updates TaskReservation uniqueness Emits QueueEvent via publisher

Platform Capabilities

  • Decoupled Task Storage


    Store authoritative task records in SQLSpec (11 database dialects), Advanced Alchemy (SQLAlchemy 2.0), Redis 8.1+, Valkey 6+, cross-process Ephemeral SQLite, or in-memory storage.

    Explore Storage Backends

  • Serverless & Broker Transports


    Route interactive tasks to Google Cloud Tasks OIDC webhooks, heavy batch jobs to Cloud Run Jobs, or distribute work through Pub/Sub, AWS SQS, RabbitMQ, and Apache Kafka.

    Execution & Operations

  • Flexible Worker Placements


    Start with zero-config CLI-supervised workers (placement="server"), run in-process for tests (placement="asgi"), or scale dedicated external worker fleets (placement="external").

    Workers & Placements

  • Realtime SSE & WebSocket Streams


    Emit structured progress percentages, stage updates, and logs from inside running tasks to durable QueueEventLog history and live /queues/events streams.

    Events & Observability

  • Cron & Interval Schedules


    Declare recurring tasks with 5-field cron expressions or fixed intervals, timezone awareness, catch-up policies, and fenced leader claims.

    Recurring Schedules

  • Fenced Leases & Uniqueness


    Prevent duplicate execution and zombie worker overwrites with (expected_retry_count, expected_execution_ref) CAS fencing and unique_until deduplication windows.

    Task Options & Uniqueness

Install

uv add litestar-queues
pip install litestar-queues
pdm add litestar-queues
poetry add litestar-queues

Quickstart Preview

Define a background task with @task, register QueuePlugin, and inject QueueService into any Litestar route handler:

app.py
"""Minimal runnable Litestar Queues quickstart application."""

from uuid import UUID

from litestar import Litestar, get, post
from litestar.di import NamedDependency
from litestar.exceptions import NotFoundException
from litestar.params import FromPath, FromQuery

from litestar_queues import QueueConfig, QueuePlugin, QueueService, task


@task(queue="reports")
async def render_report(report_id: str, requested_by: str) -> dict[str, str]:
    """Render an analytics report in the background."""
    return {"report_id": report_id, "requested_by": requested_by, "status": "ready"}


@post("/reports/{report_id:str}")
async def start_report(
    report_id: FromPath[str],
    queue_service: NamedDependency[QueueService],
    requested_by: FromQuery[str] = "team@example.com",
) -> dict[str, str]:
    """Enqueue a background report job and return its tracking ID."""
    handle = await queue_service.enqueue(render_report, report_id, requested_by=requested_by)
    return {"task_id": str(handle.id), "status": handle.status or "pending"}


@get("/tasks/{task_id:uuid}")
async def get_report_status(task_id: FromPath[UUID], queue_service: NamedDependency[QueueService]) -> dict[str, object]:
    """Inspect the status and return value of a queued task."""
    record = await queue_service.get_task(task_id)
    if record is None:
        raise NotFoundException(detail=f"Task {task_id} not found")
    return {
        "task_id": str(record.id),
        "status": record.status,
        "is_terminal": record.is_terminal,
        "result": record.result,
    }


app = Litestar(route_handlers=[start_report, get_report_status], plugins=[QueuePlugin(config=QueueConfig())])

Run your application with the Litestar CLI—QueuePlugin automatically supervises a background worker alongside your web server:

litestar --app app:app run --reload