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