Signals and Wait for Signal
A signal delivers a named payload to a run that is already running: an approval, a cancellation request, a new item to process. Signals work the same way for durable functions and for canvas workflows.
Receiving signals in code
Declare the signal, list it in the workflow's options, and wait for it:
export const approve = defineSignal<{ by: string }>('approve');
export const cancel = defineSignal<{ reason: string }>('cancel');
export const order = workflow('order', { signals: [approve, cancel] }, async (ctx, input: { id: string }) => {
ctx.onSignal(cancel, ({ reason }) => { ctx.log.info(`Cancel requested: ${reason}`); });
const { by } = await ctx.signalReceived(approve);
return { approvedBy: by };
});
ctx.signalReceived(signal)returns a promise for the next signal of that name.ctx.onSignal(signal, handler)runs a handler for every signal of that name, in the order they arrived.- Signals that arrive before the function waits for them are kept in the history and delivered when it does.
The declared payload types become part of the workflow's interface, and a payload that does not match is refused when it is sent.
Waiting for a signal on the canvas
The Wait for Signal node (under Flow in the Node Store) parks a canvas run until a signal of a given name arrives, or until a time limit passes.
| Setting | Meaning |
|---|---|
| Signal name | The name to wait for |
| Consume | First takes one signal; All collects every signal of that name that has arrived |
| Limit wait | A duration, or an absolute deadline. Without a limit the node waits until a signal arrives |
| Payload schema | Optional JSON Schema; a payload that does not match is refused |
The node has two outputs: received, with signal and payload (or items for All), and timedOut. A signal sent before the run reaches the node is held, up to 100 per name, and consumed when the node parks.
Sending a signal
- In the app: on a waiting run, select Signal, choose the signal and fill in the form generated from its schema, or paste JSON.
- From the CLI:
fluidgrids signal <runId> approve --payload '{"by":"ana"}' - From the API or SDK: the
signalWorkflowRunmutation, orruns.signal(runId, name, payload)in@fluidgrids/sdk. - From another durable function:
ctx.signalRun(target, signal, payload), orctx.signalParent(signal, payload)to reach the run that started this one.
Each signal can carry an idempotency key. Sending the same key twice delivers the signal once and tells the second caller it was a duplicate. A signal to a run that has finished is refused.
Signals are not counted as runs.
Asking a run where it is
Every durable run answers two built-in questions without changing anything: the Waiting at panel on the run page, and fluidgrids runs stack <runId>, show the lines of code the function is waiting on.
Queries and updates
A query reads a running function's state through a handler (ctx.handleQuery) without changing it. An update delivers a validated request and returns a result to the caller (ctx.handleUpdate); a rejected update leaves no trace in the history. See Run control.
Signals from canvas workflows and outside systems
The Signal Run node sends a signal from a canvas workflow to another run, and a signal token gives an outside system a URL that signals one run without a FluidGrids credential. See Run control.