Durable Worker
Adapt Redis-backed background work with Postgres Run records, restart recovery and explicit effect idempotency.
Background work in a separate process
Submit a batch job over HTTP, inspect its progress and Timeline, or request cancellation. A separate Worker consumes Redis commands; Postgres stores admission, Run state and audit events. Use this foundation when work must outlive an individual HTTP request. It is a long-running, single-active profile, not a serverless backend.
Prepare the local services
You need Docker Compose, the application toolchain, and free local ports 55432 (Postgres), 56379 (Redis) and 43120 (API). Set DATABASE_URL, REDIS_URL, WORKER_TENANT_ID, WORKER_PROJECT_ID and API_AUTH_TOKEN using the copied README.
Start the services, apply migrations, then start the Worker and API in separate terminals. Compose does not apply the schema. Migrations require both hosts stopped; back up the database before an upgrade. This is a local development profile, not production service provisioning.
Where to make changes
shared/work.ts # job input and output schemas
shared/postgres-projection-store.ts # durable Run/Timeline storage
targets/worker/handler.ts # batch behavior and sample effect
targets/worker/main.ts # Worker startup, recovery and shutdown
targets/api/app.ts # admission, status and controls
targets/api/main.ts # projection host lifetime
targets/migrate.ts # schema migration entrypointReplace the batch schema and handler first. An existing application can host admission and projection in its own server; it need not run this example API. Keep the Worker separately owned, and never import another target's executable entrypoint. See Workers and background execution for the runtime APIs.
Design effects for redelivery
Delivery is at least once: a crash can cause a claimed command to execute again. The sample uses a unique Run/item key in Postgres to avoid duplicate sample writes. Your external effects need their own idempotency mechanism. Cancellation does not undo effects already committed.
Startup recovers persisted commands and Run projections. This profile permits one API/projection host and one Worker host per shared store/key scope, not an autoscaling fleet. API readiness alone does not prove a Worker is consuming work; monitor queued age as well as host presence.
Before exposing the API
Replace the local bearer-token boundary with application authentication, per-Run authorization, rate limits and deployment controls. Read the copied README's recovery and backup procedures before changing storage or topology.
Service-backed tests require disposable Postgres and Redis test URLs; otherwise they skip, not pass. See Testing and verification. Selecting this source does not qualify a production deployment.