Public: anyone can read this; the crew can change it.

A durable job: an app writes steps, sleeps and waits in plain code, and the forge carries it across sleeps, restarts and days #11596

shipped production is serving it opened this has it

Landed in pull #11678 · run

opened this

Why. Prior art the owner named: Vercel's workflow ("use workflow", steps, sleep) and Cloudflare's Durable Objects alarms and Workflows. What they give is one thing: code that reads top to bottom, can wait an hour or a week without a process running, survives a deploy, and never repeats a step that already finished. With timers (the issue before this) the forge has the only server-side piece that needs; the rest is a small library in the app template.

What.

  • In the template, with no dependency:

``ts export const remind = job("remind", async (ctx, input) => { const order = await ctx.step("load", () => loadOrder(input.id)); await ctx.sleep("wait", { days: 3 }); if (!(await ctx.step("paid?", () => isPaid(order)))) await ctx.step("email", () => sendReminder(order)); const reply = await ctx.waitFor("reply", { event: reply:${order.id}, timeout: { days: 7 } }); return reply ?? "no reply"; }); await remind.start({ id }, { key: remind:${id} }); ``

  • How it runs: each step result is saved in the app's own data, keyed by job run and step name. sleep and waitFor save where the job is, arm a forge timer and return; the process is free to stop. When the timer fires (or the event is sent with job.signal(event, data)), the job function runs again from the top and every finished step returns its saved result at once, so it continues where it left off. Steps must be safe to retry until they return; the docs say so in two lines with the idempotency helper.
  • A step that throws is retried with backoff (declared per step, default 3), then the run is failed and the owner is asked once, as for a schedule.
  • A deploy in the middle is fine: saved steps are data. A changed job is detected (a step name that no longer exists) and the run is failed plainly rather than continuing wrongly; version lets old runs finish on old code paths when the author wants.
  • Seen and steered: the app's page lists job runs (name, key, started, where it is now: running, sleeping until, waiting for, done, failed), with Cancel and Retry from the failed step; the API and an MCP tool answer the same.
  • Limits: step results up to 256 KB each; runs per app and timers per app are settings.

Acceptance. Tests with a fake clock and a process that is killed between steps: a job with step → sleep 3 days → step → waitFor finishes with each step executed exactly once; a signal wakes a waiting job; a thrown step retries then fails with one ask; a restart of the forge and of the app mid-sleep changes nothing. The template's README has a "Jobs" section of one screen with the example above. A worked example ships in the template: a reminder that waits a day.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs