Workflows
A workflow is a job that takes more than one go: charge a card, wait for the warehouse to confirm, send a reminder in three days if nobody answered. Each part can fail on its own, some of them wait for something outside Edge, and the whole thing can take days. A workflow lets you write that as a function and have Edge carry it through, across failures, deploys and long waits.
A run is a sequence of steps
A run is one function and one input. Edge calls the function once per step: a POST /_jobs/workflow/{name} on the background runner, with the step's name and the step's input. The first step is always start. Your function looks at the step name, does that part of the work, and answers with what comes next:
| Answer | What Edge does |
|---|---|
next | Saves the next step's input and runs it now |
sleep | Saves it, and runs it after a delay or at a time (up to 30 days) |
wait | Saves it, and runs it when a signal arrives — or a timeout step if none does |
done | Marks the run completed, with an optional output |
fail | Marks the run failed, without retrying |
So one function usually holds every step of its workflow, routed on step:
function handler(request, env) {
const { step, input } = JSON.parse(request.body);
if (step === 'start') return answer({ next: { step: 'charge', input } });
// …
}Edge keeps the input, and nothing else
Between steps, the function is not running. Nothing waits in memory, so a sleep of a week costs nothing and survives any number of deploys. The only thing Edge carries from one step to the next is the input your answer gave it, up to 256 KiB. Anything bigger belongs in a private data object or env.kv, with its key in the input.
That is also why a step cannot simply sleep in its own code: the sandbox has no timers, and a step that holds a runner for a day would be paying for the wait. Answer sleep instead.
A step can run more than once
Delivery is at least once, the same as every background job. If a step fails in a way worth retrying — a timeout, a crash, a 5xx answer — Edge runs the same step again with the same input, up to the run's retries (default 2), waiting a little longer each time. If a worker stops halfway through a step, the step runs again. Write each step so that running it twice does the same as running it once: key a charge on the run id and the step, or check whether the work is already done before doing it.
A step that answers fail, a 4xx, or something that is not one of the five answers ends the run as failed. A failed run can be retried from the step that failed.
Signals come from outside
A step that answers wait names a signal, such as approved. The run sits in waiting until someone sends that signal — a person through the API or CLI, an agent, or a function with env.workflow.signal — and then the next step runs with the signal's payload. If the signal arrives before the run is waiting for it, Edge keeps it (up to 10) and the run goes straight on when it asks. A signal sent twice with the same key counts once.
If no signal arrives in time, the run goes to the wait's on_timeout step, or fails if there is none.
Limits
A run has up to 200 steps and 90 days. A distribution can have 1,000 runs that are running, sleeping or waiting. The limits page has the rest.
Next
Build a multi-step workflow walks through a whole one.