Durable Work Queue Consumer Contract

The durable work queue contract is the reusable Redis-backed primitive for work that must survive channel closure, process restart, or transient database failure.

Purpose

Use this page before adding another durable background queue or when debugging stuck session lifecycle cleanup and persistence retry jobs.

When To Use It

Use a durable queue when losing work would corrupt player or session state. Do not use it for best-effort telemetry, cache refresh, or work that can be recomputed cheaply.

Queue Spec And Key Ownership

Each consumer owns pending, processing, and dead-letter keys through a DurableWorkQueueSpec. Key names should come from the Redis keyspace layer so metrics, admin tools, and cleanup code can find them.

Append Before Signal

Append durable payloads before signaling in-memory workers. If the channel is full or closed, the durable item still exists and can be picked up later.

Processing Recovery

Workers claim pending entries, move them to processing, complete them, retry them, or dead-letter them with error context. Startup should recover abandoned processing entries according to the consumer's policy.

Retry And Dead Letters

Retry payloads should carry enough idempotency context to be safe after requeue. Dead-letter inspect and requeue APIs should expose summaries without leaking huge raw payloads into operator views.

Metrics And New Consumers

Add queue depths, signal outcomes, dead-letter counts, and consumer labels. A new consumer should document its key owner, payload type, idempotency field, retry policy, dead-letter inspection path, and recovery cadence.