Section Overview
Durable Jobs
Define backend work in code and let StackShift run it to completion with retries, state, steps, and event-based resumption.
Durable Jobs overview
Durable Jobs is the reliable execution engine for backend work on StackShift. Deploy the app. Offload the work.
Goal
Understand when to move backend work into Durable Jobs and what StackShift guarantees after a job starts.
Expected result
You can explain Durable Jobs as one product concept: jobs execute work, steps divide it, state remembers progress, and events resume paused runs.
Quick Start
Install the SDK, initialize a client, enqueue a job, add a worker handler, and inspect the run.
Goal
Run your first Durable Job from TypeScript.
Expected result
A job run is queued, invoked, completed, and visible in the Durable Jobs timeline.
Core Concepts
The vocabulary behind Durable Jobs: jobs, steps, runs, queues, state, events, and idempotency.
Goal
Learn the small set of concepts needed to build reliable backend flows.
Expected result
The Durable Jobs API reads as one system instead of separate queue, workflow, and state products.
Using Queues
Use queues for background execution, retry policy, delayed jobs, and concurrency control.
Goal
Move work out of request handlers while keeping retries and visibility.
Expected result
Background work runs outside the request path and can be retried safely.
Durable Jobs workflows
Use steps and events to build multi-step jobs that can retry, pause, and resume.
Goal
Build a backend flow that survives retries and external waiting.
Expected result
A multi-step job resumes from saved state instead of starting over.
Idempotency
Use idempotency keys so duplicate requests do not create duplicate work.
Goal
Make job starts safe for retries, webhooks, signups, and payments.
Expected result
Duplicate requests reuse the same run instead of doing the same side effect twice.
Event Waiting + Correlation
Pause a workflow until the right external event arrives, then resume the correct run.
Goal
Use event waiting and correlation keys for user actions, payments, webhooks, and external approvals.
Expected result
The right workflow resumes even when many workflows are waiting for the same event name.
State Store
Use durable state for progress, deduplication, counters, TTL-backed markers, and locks.
Goal
Store small pieces of durable job memory without adding a separate database table for every workflow concern.
Expected result
Workflow progress and deduplication survive retries and process restarts.
Retries & Failure Handling
Durable Jobs retries transient failures, preserves completed steps, and gives failed work a clear recovery path.
Goal
Configure retries without repeating completed side effects.
Expected result
Failures are visible, retryable, and safer because completed steps are remembered.
Scheduling & Delayed Jobs
Run jobs later for reminders, follow-ups, retry windows, cleanup, and recurring backend work.
Goal
Schedule backend work without keeping a process alive or relying on request timing.
Expected result
Delayed work runs at the intended time and remains visible before execution.
Observability
Inspect each job run through status, attempts, logs, payload, result, errors, and timeline.
Goal
Debug Durable Jobs without guessing where the run stopped.
Expected result
You can answer whether a job is queued, running, waiting, completed, failed, or canceled.
Real-World Examples
Common backend flows that fit Durable Jobs: verification email, payment provisioning, and file processing.
Goal
Copy a realistic starting point for common backend workflows.
Expected result
You have practical templates for common production backend work.
Best Practices
Short rules for writing Durable Jobs that behave well in production.
Goal
Avoid the most common reliability mistakes.
Expected result
Your jobs are safer to retry, easier to observe, and easier to resume.