Server Placement Topology (placement="server") Litestar CLI launches ServerWorkerSupervisor alongside web workers, sharing EphemeralQueueBackend or persistent backends across OS processes. Litestar CLI Parent ServerWorkerSupervisor Spawns alongside `litestar run` Propagates Ephemeral SQLite path Isolates web workers from queue loop Shared Queue Storage Ephemeral / SQL / Redis Default: EphemeralQueueBackend Cross-process WAL SQLite + events Requires shared backend if web > 1 Supervised Worker Child litestar queues run Single scheduler leader Auto-restarts on unexpected exit Clean SIGTERM drain on shutdown
ASGI Placement Topology (placement="asgi") Each ASGI lifespan starts an in-process Worker sharing the asyncio event loop and InMemoryQueueBackend or persistent storage. ASGI Lifespan Startup QueuePlugin.on_cli_init Starts inside ASGI lifespan Works with TestClient / Uvicorn Zero extra OS processes Shared Event Loop InMemoryQueueBackend Instant in-memory asyncio.Event wakeup Direct ChannelsPlugin memory fan-out Single-process development & tests In-Process Worker Task Worker.start() Executes coroutines & sync threads Shares app.state & DI container Graceful cancel on lifespan exit
External Placement Topology (placement="external") Web pods only enqueue tasks and serve SSE/WS streams while dedicated worker pods run litestar queues run or run-consumer with run_app_lifespan=True. Web Tier (Stateless Pods) placement="external" Zero background workers in web pods Enqueues records & serves HTTP/SSE Horizontal web autoscaling Durable Storage & Broker SQLSpec / Alchemy / Redis Native wakeups (LISTEN/NOTIFY, Pub/Sub) Or broker transport (Pub/Sub, SQS, Kafka) Cross-process QueueEventLog replay Dedicated Worker Fleet litestar queues run Enters ASGI lifespan (`run_app_lifespan`) Or `litestar queues run-consumer` Independent CPU/memory scaling
Serverless Scale-to-Zero Placement Zero idle workers; enqueue dispatches directly to Cloud Tasks or Cloud Run Jobs while Cloud Scheduler triggers /_litestar-queues/maintenance. Scale-to-Zero Web Service schedules_on_enqueue=True Dispatches future ETA at enqueue time Mounts `/_litestar-queues/cloud-tasks` Mounts `/_litestar-queues/maintenance` Managed Cloud Dispatch Cloud Tasks + Cloud Run Fast Push Lane (<= 30m HTTP OIDC) Heavy Batch Lane (Cloud Run Jobs) Task-level `execution_backend="..."` Periodic Maintenance QueueMaintenanceService Cloud Scheduler OIDC POST or Job Reconciles external refs & stale leases Fires cron schedules & prunes TTL