Skip to main content

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.

SettingMeaning
Signal nameThe name to wait for
ConsumeFirst takes one signal; All collects every signal of that name that has arrived
Limit waitA duration, or an absolute deadline. Without a limit the node waits until a signal arrives
Payload schemaOptional 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 signalWorkflowRun mutation, or runs.signal(runId, name, payload) in @fluidgrids/sdk.
  • From another durable function: ctx.signalRun(target, signal, payload), or ctx.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.

Next steps​