Durable Sleep

Durable sleep suspends a Flow until a future instant without holding a worker thread. Call await fx.clock.sleep(label, duration) inside a durable: true Flow — the journal stores wakeAt, releases the run lease, and any instance may resume when due.

For developers building trial reminders, delayed digests, and multi-day provisions on okengine.

Smallest Example

import { on, flow, http } from "okengine";
import { z } from "zod";

export const start = on(
  http.post({
    in: z.object({ email: z.string().email() }),
  }),
  flow({
    durable: true,
    do: async ({ email }, fx) => {
      await fx.step("mark-trial", async () => {
        await fx.call(startTrial, { email });
      });
      await fx.clock.sleep("expiry-window", "3d");
      await fx.step("notify", async () => {
        await fx.send(trialExpiringEmail, { to: email });
      });
    },
  }),
);

curl -X POST http://localhost:6530/trials/start \
  -H "content-type: application/json" \
  -d '{"email":"ada@example.com"}'

Progressive Patterns

From a labelled pause to HTTP parking, nested-call limits, and non-durable behavior:

await fx.clock.sleep("morning-window", "8h");
await fx.clock.sleep("verify-window", "2m");

Sleep Reference

Outcomes of a durable attempt that hits sleep: status "sleeping" with wakeAt and label. After wake, prior fx.step bodies replay from the journal and do not re-execute.

Duration units

Same grammar as fx.clock.ago / fromNow / clock.every:

Integer + unit only — no weeks. "d" is exactly 86_400_000 ms, not a calendar day across DST. Unknown strings parse as 0 ms (wake immediately).

Park Physics

fx.clock.sleep(label, duration)
  → journal entry { kind: "sleep", label, duration, wakeAt }
  → status = sleeping, lease released
  → HTTP / caller sees success (often 204)
  → later: claim due sleep → resume → replay steps → continue after sleep

Any instance may claim the row when wakeAt is due (shared journal + lease). Resume replays completed fx.step values from the journal, then continues past the sleep entry.

Consequence: multi-day sleeps are safe across deploys — the journal row is the schedule, not an in-memory timer.

With Steps

Each verb of durable work binds the same way — checkpoint, park, then more checkpoints:

import { on, flow } from "okengine";
import { userSignedUp } from "@/signals";
import { welcomeEmail } from "@/channels/welcome";

export const sendWelcome = on(
  userSignedUp,
  flow("onboarding.welcome", {
    durable: true,
    do: async ({ email }, fx) => {
      await fx.step("provision", async () => {
        await fx.call(createWorkspace, { email });
      });
      await fx.clock.sleep("morning-window", "8h");
      await fx.step("notify", async () => {
        await fx.send(welcomeEmail, { to: email });
      });
    },
  }),
);

Nested Calls

fx.call of a durable sleeper: the caller receives undefined and continues; the child wakes later as its own run.

Consequence: sleep on the root durable Flow, or split with fx.emit to a consumer — do not nest sleep behind fx.call.

Wake Early

Operators can advance wakeAt to now from Console (waiting-on / wake-early). With a flow resolver, the run resumes immediately; without it, only the wake time moves forward.

Missing or non-sleeping run id → ClockResourceNotFoundError — run "{id}" not found.

Non-durable & Tests

Without a journal session, fx.clock.sleep resolves immediately (tests and sync Flows). There is no thread sleep and no setTimeout.

For deterministic waits in tests, use a frozen clock and advance:

import { createTimeTravel } from "okengine";

const t = createTimeTravel(0);
// Park a durable run with now: () => t.now()
t.advance("7d");
// Resume — sleep entry is past due and continues

Pin journal for the env you need:

Unknown ids throw oke boot: unknown journal driver "…" (expected memory · file · postgres). Postgres without a URL throws oke boot: journal driver "postgres" needs DATABASE_URL.

Full lease / orphan / status tables live on Workflows · Journal.

Troubleshooting

Learn more

• Workflows — durable, fx.step, compensate, full sleep section
• HTTP — request envelope; 204 from park / undefined
• Clock overview — schedules and fx.clock helpers
• Schedules — cron / every (calendar time, not durable pause)
• fx — fx.clock.sleep, fx.step, fx.using
• Configuration — drivers.journal
• Errors — ClockResourceNotFoundError

Next