Skip to main content

Run control: queries, updates, reset and activities

Run control lets you work with a durable run while it is open: read its state, send it validated requests, step it back to an earlier point, and steer its activities. Every action is available in the app on the run page, from the CLI, from the API and from @fluidgrids/sdk.

Queries​

A query reads a running function's state without changing it. Declare it, list it in the workflow's options and answer it with ctx.handleQuery:

import { defineQuery, defineUpdate, workflow } from '@fluidgrids/workflows';

export const status = defineQuery<{ stage: string; items: number }>('status');
export const addItem = defineUpdate<{ sku: string }, { items: number }>('addItem');

export const cart = workflow('cart', { queries: [status], updates: [addItem] }, async (ctx) => {
let stage = 'open';
const items: string[] = [];

ctx.handleQuery(status, () => ({ stage, items: items.length }));
ctx.handleUpdate(
addItem,
({ sku }) => {
items.push(sku);
return { items: items.length };
},
{
validate: ({ sku }) => {
if (!sku) throw new Error('sku is required');
if (stage !== 'open') throw new Error('the cart is closed');
},
},
);

await ctx.condition(() => items.length >= 10, '1d');
stage = 'checked-out';
return { items };
});

A query handler runs after the run's history has been replayed and must not change anything: a command, ctx.random(), ctx.uuid() or a new patch inside it throws QueryHandlerSideEffect. ctx.setDefaultQueryHandler answers names no handler takes. A query to a name nobody handles is refused.

Ask a run:

  • In the app: on the run page, select Query, choose the query (or type another name), add arguments as JSON and select Run query. Refuse when can refuse the query when the run has ended or did not complete cleanly.
  • From the CLI: fluidgrids runs query <runId> status, with --args '<json>' and --reject-condition none|not-open|not-completed-cleanly.
  • From the SDK: sdk.fluidgrids.runs.query(runId, 'status', args).

Queries are answered from the history, so they also work on runs that have finished. The built-in queries (Waiting at, fluidgrids runs stack <runId> and --metadata) work on every durable run.

Updates​

An update delivers a request to a running function and returns the handler's result to the caller. The optional validator runs first and read-only: if it throws, the update is rejected and nothing is written to the history. An accepted update is recorded, so replays see it.

  • In the app: Update on the run page, choose the update, add its arguments and Send update. Wait until chooses whether to wait for the handler to complete or only for the update to be accepted.
  • From the CLI: fluidgrids runs update <runId> addItem --args '{"sku":"a"}' waits until the update completes (--wait-for accepted returns earlier). --update-id makes it idempotent: sending the same id twice applies it once. fluidgrids runs update-status <runId> <updateId> reads one update later.
  • From the SDK: runs.update(...) and runs.updateResult(...); workflows.startWithUpdate(...) starts a run and sends it an update in one call.

ctx.setDefaultUpdateHandler handles update names no handler takes. An update that no handler takes is rejected with UpdateNotHandled. Before a function returns, await ctx.condition(() => ctx.allHandlersFinished()) lets running handlers finish.

Resetting a run​

A reset starts a new run with the same workflow id that replays this run's history up to a completed workflow task and continues from there with the current code. The old run is terminated with the reason RESET. Use it to recover runs that failed because of a bug, once the fix is deployed.

  • In the app: Reset on the run page offers Reset to last clean task; on the History tab, Reset on an event resets at that event. You can choose whether to re-apply the signals and updates received after the reset point.

  • From the CLI:

    fluidgrids runs reset <runId> --to last-clean-task --reason 'fixed the parser'
    fluidgrids runs reset <runId> --to 42 # a history event number
    fluidgrids runs reset <runId> --to build-id --build-id <id> # back to before a bad build

    --to takes a history event number, first-task, last-task, last-continue-as-new, build-id or last-clean-task. --no-reapply-signals and --no-reapply-updates leave out what arrived after the reset point.

Controlling activities​

The Activities card on the run page lists the run's open activities with their attempt count. For one activity, or for every open activity of the run:

ActionEffect
PauseThe next attempt is not dispatched until the activity is unpaused. A running attempt learns about the pause at its next heartbeat
UnpauseThe next attempt is dispatched now
Reset attemptsRestart at attempt 1, optionally dropping the heartbeat details. A running attempt is cancelled first
Change optionsA new retry policy and timeouts, from the next attempt on
Complete or FailFor an activity that waits for an asynchronous completion (below)

The CLI has the same commands: fluidgrids activities pause|unpause|reset|update-options <runId>, with --activity-id <id>, --type <type> (a node type or user activity name) or --all to choose the activities.

Pause rules​

A pause rule pauses matching activities in every run of the workspace when they are scheduled or retried, for example while a downstream system is down. Add rules under Settings → Run control → Activity pause rules, with an activity or node type, an optional workflow key, a reason and an optional end time, or from the CLI:

fluidgrids activities pause-rules create --activity-type internal:http --reason 'vendor down' --expires-in 2h
fluidgrids activities pause-rules list
fluidgrids activities pause-rules delete <id>

A workspace can have up to 100 rules. Deleting a rule unpauses what it paused. Pause rules also apply to the matching nodes of canvas runs.

Asynchronous completion​

An activity can end its attempt without a result and let another system finish it later: a user activity calls completeAsync() on a self-hosted worker and hands its task token to that system. The activity then waits until it is completed, failed or times out:

fluidgrids activities complete --task-token-env TASK_TOKEN --result '{"ok":true}'
fluidgrids activities fail --task-token-env TASK_TOKEN --message 'declined'
fluidgrids activities complete <runId> <activityId> --result '{"ok":true}'

fluidgrids activities heartbeat keeps such an activity alive while it waits. Task tokens are read from an environment variable, never from the command line.

Send and Wait as an activity​

With run control on, a durable function can run the Send and Wait for Response node as an activity: ctx.run(n.internal.sendAndWait, { args }) sends the message and parks the activity until the person answers. The answer is the activity's result. The activity's timeouts still apply.

Signalling from canvas workflows and other systems​

The Signal Run node​

The Signal Run node (under Flow in the Node Store) sends a named signal to another run of the workspace from a canvas workflow. Give it the signal name, the target run as JSON ({ "runId": "…" }, or { "workflowKey": "…", "workflowId": "…" } for the latest run of a workflow id) and an optional payload. Its output says whether the signal was delivered, which run received it, and whether a retried attempt had already sent it; a retried node delivers the signal once. By default the node fails when no run takes the signal.

Signal tokens​

A signal token lets an outside system signal one run with a plain HTTPS POST, without a FluidGrids credential. On the run page, open Signal tokens and select New token: choose the signal, a lifetime (1 hour to 90 days) and whether the token is reusable until it expires or spent by its first signal, and optionally limit the IPv4 addresses that may use it. The Signal URL and token are shown once; the sending system posts the signal's payload as JSON to the URL.

fluidgrids signal-token create <runId> --signal approve --ttl 7d # the URL is shown once
fluidgrids signal-token list <runId>
fluidgrids signal-token revoke <id>

Batch operations​

To act on many runs at once, select runs in the Runs list (or filter it) and open Batch: signal, cancel, terminate, reset to the last clean task, pause, unpause or reset activities, change activity options, change run versioning, or export to the archive. Dry run counts the runs first, and a rate limit (1 to 50 runs per second) keeps the job gentle. Batch jobs lists the jobs with their counts and can cancel one.

fluidgrids runs batch signal --key approvals --status running --signal nudge --reason 'resend' --dry-run
fluidgrids runs batch terminate --run-id r1,r2 --reason cleanup
fluidgrids batch list
fluidgrids batch describe <id> --watch
fluidgrids batch cancel <id>

Permissions​

Queries need permission to read the run. Updates, resets, activity actions, signal tokens, pause rules and batch jobs need the matching run permissions. See Roles and permissions.

Next steps​