@xyne/workflow-sdk 3.2.39 → 3.2.40

package/dist/runtime/workflow-runtime.js

@@ -23,10 +23,72 @@ import { CredentialResolver } from '../engine/credential-resolver.js';
 import { headerValue } from '../ingest/headers.js';
 import { parseInboundBody } from '../ingest/body.js';
 import { matchesTriggerFilter } from '../ingest/filter.js';
+import { isDelayedStart, readAnchor, resolveStartAt, startNeedsPayload, startSkipReason, } from '../ingest/start-policy.js';
 import { CronTrigger } from '../triggers/cron-trigger.js';
 import { PauseStep } from '../engine/pause-step.js';
 import { leafStepId } from '../engine/node-path.js';
-// ─── Helpers ───
+/** Why an event was not admitted, for logs and for the error a manual run gets. */
+function reasonOf(decision) {
+    if (decision.kind === 'gone')
+        return `the subject is gone (${decision.reason})`;
+    switch (decision.by) {
+        case 'scope':
+            return 'this workflow does not watch that event';
+        case 'conditions':
+            return "the workflow's conditions did not match";
+    }
+}
+/**
+ * How early a wake-up is tolerated before the run re-arms itself.
+ *
+ * A delayed job can fire a little early (clock skew between the queue and this
+ * process), and a host sweeper re-enqueueing a run whose job was lost can be
+ * eager. Neither should admit an event before its moment, because admission is
+ * what reads the world.
+ */
+const EARLY_WAKE_TOLERANCE_MS = 1_000;
+/**
+ * The fields whose values are actually known while editing.
+ *
+ * A sibling field may hold `{{trigger.projectId}}` — a promise about run time,
+ * not an id. A loader filtering by it would search for the literal text and
+ * quietly find nothing, so references are dropped here and offered separately as
+ * `config` for the rare loader that wants the raw text.
+ */
+function literalValues(config) {
+    const out = {};
+    for (const [key, value] of Object.entries(config)) {
+        if (isPlainObject(value)) {
+            // Follow the form as deep as a field path can go: `repository.id` is a
+            // usable filter even when its neighbour `repository.name` is a reference.
+            out[key] = literalValues(value);
+            continue;
+        }
+        if (holdsRef(value))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Whether a value is waiting on run time anywhere inside it.
+ *
+ * An array is all-or-nothing: dropping the one element that holds a reference
+ * would hand the loader a shorter list and no sign that it is short, which reads
+ * as a narrower filter rather than an unanswerable one.
+ */
+function holdsRef(value) {
+    if (typeof value === 'string')
+        return value.includes('{{');
+    if (Array.isArray(value))
+        return value.some(holdsRef);
+    if (isPlainObject(value))
+        return Object.values(value).some(holdsRef);
+    return false;
+}
 function messageOf(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -375,14 +437,24 @@ export class WorkflowRuntime {
     }
     // ─── Trigger Firing ───
     /**
-     * Dispatch a domain event. Finds all active workflows that match,
-     * hydrates payloads, applies filters, and enqueues executions.
+     * Dispatch a domain event to every active workflow watching for it.
+     *
+     * Each candidate goes through the same admission as any other entry path —
+     * `accepts`, then {@link admit} — so an event workflow, a webhook workflow and
+     * a manual run all decide the same way. Hydration is shared across candidates:
+     * fifty workflows on one ticket update cost one read, not fifty.
      *
      * Returns the execution IDs that were created.
      */
     async dispatchEvent(event) {
         const workflows = await this.persistence.findActiveWorkflows(event.type, event.metadata);
         const executionIds = [];
+        const hydrations = new Map();
+        const triggerEvent = {
+            type: event.type,
+            payload: event.payload,
+            ...(event.occurredAt !== undefined ? { occurredAt: event.occurredAt } : {}),
+        };
         for (const workflow of workflows) {
             const config = parseWorkflowConfig(workflow.config);
             if (!this.connectors.hasTrigger(config.trigger.type))
@@ -390,30 +462,12 @@ export class WorkflowRuntime {
             const trigger = this.connectors.getTrigger(config.trigger.type);
             if (!(trigger instanceof EventTrigger))
                 continue;
-            // Hydrate lightweight payload → full context
-            let payload = { ...event.payload };
-            if (trigger.hydratePayload) {
-                try {
-                    payload = await trigger.hydratePayload(payload);
-                }
-                catch (err) {
-                    this.log.warn(`dispatchEvent: hydratePayload failed for workflow ${workflow.id}: ${err instanceof Error ? err.message : String(err)}`);
-                    continue;
-                }
-            }
-            // Filter — does this event match this workflow's trigger config?
-            if (!trigger.matchFilters(config.trigger.config, payload)) {
-                continue;
-            }
-            // And the author's filter, before a run exists.
-            if (!matchesTriggerFilter(config.trigger.filter, payload, config.variables)) {
+            const armed = await this.arm(workflow, config, triggerEvent, { hydrations });
+            if (armed.kind === 'dropped') {
+                this.log.info(`dispatchEvent: ${event.type} not admitted by workflow ${workflow.id} — ${armed.reason}`);
                 continue;
             }
-            const execId = await this.createAndEnqueue(workflow, {
-                type: event.type,
-                ...payload,
-            });
-            executionIds.push(execId);
+            executionIds.push(armed.executionId);
         }
         return executionIds;
     }
@@ -432,7 +486,8 @@ export class WorkflowRuntime {
      * 4. The trigger's own `verify` accepts the request — else 401.
      * 5. The body is parsed from the raw bytes — else 400.
      * 6. The trigger turns the request into events and a reply.
-     * 7. Each event must pass the workflow's trigger filter, or it is dropped.
+     * 7. Each event is admitted the same way every other entry path is — `accepts`,
+     *    then hydration, then the trigger's own filter and the author's — or dropped.
      * 8. Survivors are enqueued before the reply is returned.
      *
      * Reasons for a rejection go to the log; responses stay generic.
@@ -499,9 +554,12 @@ export class WorkflowRuntime {
         const translation = await trigger.handleRequest({ ...request, body }, triggerConfig, ctx);
         const executionIds = [];
         for (const event of translation.events) {
-            if (!matchesTriggerFilter(config.trigger.filter, event.payload, config.variables))
+            const armed = await this.arm(workflow, config, event, { triggerCtx: ctx });
+            if (armed.kind === 'dropped') {
+                this.log.info(`webhook ${workflowId}: ${event.type} not admitted — ${armed.reason}`);
                 continue;
-            executionIds.push(await this.createAndEnqueue(workflow, { type: event.type, ...event.payload }, { publicTrigger: true }));
+            }
+            executionIds.push(armed.executionId);
         }
         return {
             reply: translation.reply ?? { status: 200, body: { ok: true } },
@@ -579,11 +637,11 @@ export class WorkflowRuntime {
         if (errors.length > 0) {
             throw new Error(`Invalid trigger payload: ${errors.map((e) => e.message).join('; ')}`);
         }
-        const triggerPayload = {
-            type: config.trigger.type,
-            ...payload,
-        };
-        return this.createAndEnqueue(workflow, triggerPayload);
+        const armed = await this.arm(workflow, config, { type: config.trigger.type, payload });
+        if (armed.kind === 'dropped') {
+            throw new Error(`Workflow did not accept this run: ${armed.reason}`);
+        }
+        return armed.executionId;
     }
     /**
      * Start a workflow from the API trigger route.
@@ -610,7 +668,11 @@ export class WorkflowRuntime {
         if (errors.length > 0) {
             throw new Error(`Invalid trigger payload: ${errors.map((e) => e.message).join('; ')}`);
         }
-        return this.createAndEnqueue(workflow, { type: config.trigger.type, ...payload }, { publicTrigger: true });
+        const armed = await this.arm(workflow, config, { type: config.trigger.type, payload });
+        if (armed.kind === 'dropped') {
+            throw new Error(`Workflow did not accept this run: ${armed.reason}`);
+        }
+        return armed.executionId;
     }
     /**
      * What the API trigger route needs before it builds a payload: the trigger's
@@ -1177,7 +1239,13 @@ export class WorkflowRuntime {
         const exec = await this.persistence.getExecution(executionId);
         if (!exec)
             return { status: 'not_found' };
-        if (!['PENDING', 'EXTERNAL_WAIT'].includes(exec.status)) {
+        if (exec.status === 'SCHEDULED') {
+            const activation = await this.activate(exec);
+            if (activation.kind !== 'started') {
+                return { status: 'skipped', reason: activation.reason };
+            }
+        }
+        else if (!['PENDING', 'EXTERNAL_WAIT'].includes(exec.status)) {
             return {
                 status: 'skipped',
                 reason: `execution status is ${exec.status}`,
@@ -1266,30 +1334,298 @@ export class WorkflowRuntime {
             });
             if (data === null)
                 return null; // nothing new, skip
-            return this.createAndEnqueue(workflow, {
-                type: config.trigger.type,
-                ...data,
-            });
+            return this.admitAndEnqueue(workflow, config, data);
         }
         // Pure cron — always fire
         const payload = trigger.buildPayload
             ? trigger.buildPayload(config.trigger.config)
             : { firedAt: new Date().toISOString() };
-        return this.createAndEnqueue(workflow, {
+        return this.admitAndEnqueue(workflow, config, payload);
+    }
+    /** A cron tick's payload, through the same admission as every other event. */
+    async admitAndEnqueue(workflow, config, payload) {
+        const event = {
             type: config.trigger.type,
-            ...payload,
-        });
+            payload,
+            occurredAt: new Date().toISOString(),
+        };
+        const armed = await this.arm(workflow, config, event);
+        if (armed.kind === 'dropped') {
+            this.log.info(`cron tick for workflow ${workflow.id} not admitted — ${armed.reason}`);
+            return null;
+        }
+        return armed.executionId;
+    }
+    /**
+     * Choices for one config field, from the step or trigger that owns it.
+     *
+     * Authoring, not running: this answers a person editing a form, so it runs as
+     * THEM. The tenant comes from the workflow being edited, or from the folder a
+     * new one is being created in — either way from a record the caller has just
+     * been authorized against, never from the request body.
+     */
+    async getFieldOptions(ctx, input) {
+        const attributes = await this.optionsScope(ctx, input);
+        const component = input.kind === 'step'
+            ? this.connectors.hasStep(input.type)
+                ? this.connectors.getStep(input.type)
+                : null
+            : this.connectors.hasTrigger(input.type)
+                ? this.connectors.getTrigger(input.type)
+                : null;
+        if (!component)
+            throw new ResourceNotFoundError(input.kind, input.type);
+        const getOptions = component.getOptions?.bind(component);
+        // Not every field is a picker, and a component need not offer any. Nothing
+        // to say is an empty page, not an error — the editor falls back to a text box.
+        if (!getOptions)
+            return { items: [] };
+        const config = input.config ?? {};
+        // A half-filled form is the NORMAL state here — the author may not have
+        // chosen a connection yet, and that is a question the loader answers with a
+        // notice ("Choose a connection first"), not a failure the editor should
+        // raise. Hand over what resolved; let the component say what it needs.
+        let credentials = {};
+        try {
+            credentials = await this.credentialResolver.resolve(attributes, component, config);
+        }
+        catch (err) {
+            this.log.info(`field options for ${input.kind} "${input.type}": no usable credential yet — ${messageOf(err)}`);
+        }
+        const optionsCtx = {
+            field: input.field,
+            config,
+            literal: literalValues(config),
+            ...(input.search !== undefined ? { search: input.search } : {}),
+            ...(input.cursor !== undefined ? { cursor: input.cursor } : {}),
+            ...(input.values !== undefined ? { values: input.values } : {}),
+            credentials,
+            attributes,
+            services: this.services,
+            caller: ctx,
+            ...(input.signal !== undefined ? { signal: input.signal } : {}),
+        };
+        return getOptions(optionsCtx);
+    }
+    /**
+     * Whose data the picker may read.
+     *
+     * This lookup is not really a capability check — it is how the TENANT is
+     * derived. `attributes` decides which workspace's credential the loader runs
+     * with, and the only trustworthy source for that is a record the caller has
+     * already been authorized against. Take it from the request body instead and
+     * anyone can ask one workspace's connector to list another's channels. That is
+     * why there is no ungated version of this.
+     *
+     * So the action asked for is the weakest that proves the caller belongs to the
+     * tenant: reading the workflow in front of them, or being allowed to create one
+     * in the folder they are working in. Browsing and naming stored ids share it
+     * deliberately — `workflow:update` locked a read-only viewer out of resolving
+     * labels, so they saw raw ids where the author saw names, and splitting the two
+     * only moved the problem: the weaker half would then leak the stronger half back
+     * by letting a reader name ids it guessed.
+     *
+     * What a picker then SHOWS is settled by the credential, not by a second
+     * per-person rule: whoever may read the workflow sees what that workflow's
+     * connection can reach. That is deliberate — the credential belongs to the
+     * workspace, and narrowing it per viewer would be a policy the connector
+     * cannot express and the tenant did not ask for.
+     */
+    async optionsScope(ctx, input) {
+        if (input.workflowId !== undefined) {
+            const { record } = await this.authorizedWorkflow(ctx, input.workflowId, 'workflow:read');
+            return record.attributes;
+        }
+        if (input.folderId !== undefined) {
+            const { record } = await this.authorizedFolder(ctx, input.folderId, 'workflow:create');
+            return record.attributes;
+        }
+        throw new Error('Field options need the workflow being edited, or the folder for a new one');
     }
     // ─── Internal ───
-    async createAndEnqueue(workflow, triggerPayload, opts) {
+    /**
+     * Arm one event for one workflow: start a run now, or park one until its moment.
+     *
+     * The binding's start policy decides which. An immediate binding is admitted
+     * here and now. A delayed one is armed on SCOPE alone — `accepts` — and stores
+     * the raw event; the conditions that decide whether it acts are judged when it
+     * fires, by {@link activate}. That is deliberate: a rule like "escalate if still
+     * unassigned after two hours" must arm even when the ticket is assigned right
+     * now, or it can never fire.
+     */
+    async arm(workflow, config, event, opts) {
+        const start = config.trigger.start;
+        if (!isDelayedStart(start))
+            return this.startNow(workflow, config, event, opts);
+        const trigger = this.connectors.getTrigger(config.trigger.type);
+        if (!trigger.accepts(event, config.trigger.config)) {
+            return { kind: 'dropped', reason: reasonOf({ kind: 'rejected', by: 'scope' }) };
+        }
+        // Only an anchor that lives in the payload costs a read here — "two hours
+        // after the event" needs none. What it reads is used for the TIME alone and
+        // then dropped: the run is armed from the raw event and enriched again when
+        // it fires, which is what makes the wait worth anything.
+        let anchorPayload = { ...event.payload };
+        const hydrate = startNeedsPayload(start) ? trigger.hydrate?.bind(trigger) : undefined;
+        if (hydrate) {
+            const hydrated = await this.hydrateFor(workflow, trigger, hydrate, event, config.trigger.config, opts);
+            if (hydrated.kind === 'gone') {
+                return { kind: 'dropped', reason: reasonOf({ kind: 'gone', reason: hydrated.reason }) };
+            }
+            anchorPayload = hydrated.payload;
+        }
+        const anchorValue = start?.kind === 'at' ? readAnchor(start.anchor, anchorPayload, config.variables) : undefined;
+        const when = resolveStartAt(start, event, anchorValue, new Date());
+        if (when.kind === 'skip')
+            return { kind: 'dropped', reason: startSkipReason(when.reason) };
+        if (when.kind === 'now')
+            return this.startNow(workflow, config, event, opts);
+        const executionId = await this.createAndEnqueue(workflow, {}, { scheduled: { when, event } });
+        return { kind: 'scheduled', executionId, fireAt: when.at };
+    }
+    /** Admit now, and enqueue the run if the event survives. */
+    async startNow(workflow, config, event, opts) {
+        const decision = await this.admit(workflow, config, event, opts);
+        if (decision.kind !== 'ok')
+            return { kind: 'dropped', reason: reasonOf(decision) };
+        const executionId = await this.createAndEnqueue(workflow, {
+            type: event.type,
+            ...decision.payload,
+        });
+        return { kind: 'started', executionId };
+    }
+    /**
+     * A scheduled run's moment has come.
+     *
+     * Everything that could have changed while it waited is re-read here: the
+     * workflow definition (it may have been switched off or edited), and the event's
+     * subject (it may have moved on, or stopped existing). The run is then admitted
+     * exactly as an arriving event would be — same `admit`, same filters — which is
+     * what makes "in two hours" behave like "now".
+     */
+    async activate(exec) {
+        const origin = exec.origin;
+        if (!origin) {
+            // A scheduled run is admitted from the event on its record. Without one
+            // there is nothing to admit, and nothing worth walking.
+            return this.endScheduled(exec.id, 'CANCELLED', 'the scheduled run has no stored event');
+        }
+        const workflow = await this.persistence.getWorkflow(exec.workflowId);
+        if (!workflow || workflow.status !== 'ACTIVE') {
+            return this.endScheduled(exec.id, 'CANCELLED', 'the workflow is no longer active');
+        }
+        const fireAt = exec.fireAt?.getTime() ?? Number.NaN;
+        if (!Number.isNaN(fireAt) && fireAt - Date.now() > EARLY_WAKE_TOLERANCE_MS) {
+            // Woken early — re-arm rather than read the world before the moment.
+            await this.queue.enqueue({
+                executionId: exec.id,
+                delay: fireAt - Date.now(),
+                singletonKey: exec.id,
+            });
+            return { kind: 'deferred', reason: `not due until ${exec.fireAt?.toISOString() ?? 'its fire time'}` };
+        }
+        const config = parseWorkflowConfig(workflow.config);
+        if (!this.connectors.hasTrigger(config.trigger.type)) {
+            return this.endScheduled(exec.id, 'CANCELLED', `trigger "${config.trigger.type}" is no longer registered`);
+        }
+        const decision = await this.admit(workflow, config, origin.event);
+        if (decision.kind !== 'ok') {
+            return this.endScheduled(exec.id, decision.kind === 'gone' ? 'CANCELLED' : 'SKIPPED', reasonOf(decision));
+        }
+        // The context is built HERE, not when the run was armed: a run that has not
+        // started has nothing to read, and `context.trigger` should only ever mean
+        // the payload the run actually acts on.
+        const context = this.initialContext(workflow, {
+            type: origin.event.type,
+            ...decision.payload,
+        });
+        await this.persistence.persistState(exec.id, {
+            context: JSON.stringify(context),
+            attributes: context.workflow.attributes,
+        });
+        await this.persistence.updateExecutionStatus(exec.id, 'PENDING');
+        this.log.info(`execution ${exec.id} admitted at its scheduled time`);
+        return { kind: 'started' };
+    }
+    /** End a scheduled run that will never act, saying why on the run itself. */
+    async endScheduled(executionId, status, reason) {
+        await this.persistence.updateExecutionStatus(executionId, status, reason);
+        this.log.info(`scheduled execution ${executionId} ended as ${status}: ${reason}`);
+        return { kind: 'ended', status, reason };
+    }
+    /**
+     * Admit one event to one workflow — the single place that decides whether an
+     * event deserves a run, and with what data.
+     *
+     * Every entry path goes through here: a domain dispatch, a webhook delivery, a
+     * cron tick, a manual run. That is the point. Filtering used to happen at two
+     * points on one path, one point on another and nowhere at all on the rest, so
+     * the same author-written filter meant different things depending on how the
+     * run started.
+     *
+     * In order: `accepts` prunes on the raw event — the trigger's one say, and it
+     * is about what arrived — then `hydrate` resolves ids into objects once, and the
+     * author's conditions judge the enriched payload. What this returns is frozen
+     * into `context.trigger` and never re-read: a step that needs the world as it is
+     * later reads it itself.
+     */
+    async admit(workflow, config, event, opts) {
+        const trigger = this.connectors.getTrigger(config.trigger.type);
+        const triggerConfig = config.trigger.config;
+        if (!trigger.accepts(event, triggerConfig))
+            return { kind: 'rejected', by: 'scope' };
+        let payload = { ...event.payload };
+        const hydrate = trigger.hydrate?.bind(trigger);
+        if (hydrate) {
+            const hydrated = await this.hydrateFor(workflow, trigger, hydrate, event, triggerConfig, opts);
+            if (hydrated.kind === 'gone')
+                return hydrated;
+            payload = hydrated.payload;
+        }
+        if (!matchesTriggerFilter(config.trigger.filter, payload, config.variables)) {
+            return { kind: 'rejected', by: 'conditions' };
+        }
+        return { kind: 'ok', payload };
+    }
+    /** One hydration, shared by key across the candidates of a single dispatch. */
+    async hydrateFor(workflow, trigger, hydrate, event, triggerConfig, opts) {
+        const key = trigger.hydrationKey?.(event);
+        const memoKey = key === undefined ? undefined : `${trigger.type}:${key}`;
+        const cached = memoKey === undefined ? undefined : opts?.hydrations?.get(memoKey);
+        if (cached)
+            return cached;
+        let result;
+        try {
+            const ctx = opts?.triggerCtx ?? (await this.triggerCtxFor(workflow, trigger, triggerConfig));
+            result = await hydrate(event, triggerConfig, ctx);
+        }
+        catch (err) {
+            // Enrichment failing is no licence to run on bare ids — drop the event and
+            // say why, the same outcome as a subject that no longer exists.
+            this.log.warn(`hydrate failed for workflow ${workflow.id}: ${messageOf(err)}`);
+            result = { kind: 'gone', reason: `hydration failed: ${messageOf(err)}` };
+        }
+        if (memoKey !== undefined)
+            opts?.hydrations?.set(memoKey, result);
+        return result;
+    }
+    /** Credentials and tenant for a trigger's server-side hooks. */
+    async triggerCtxFor(workflow, trigger, triggerConfig) {
+        const attributes = workflow.attributes;
+        const credentials = await this.credentialResolver.resolve(attributes, trigger, triggerConfig);
+        return { credentials, attributes, baseUrl: this.baseUrl };
+    }
+    /**
+     * The context a run starts with — its identity, its tenant, the author's
+     * constants, and the trigger payload it acts on.
+     *
+     * Built in one place because it is built at two moments: when an immediate run
+     * is created, and when a delayed one is admitted. Those must produce the same
+     * shape, or a rule would behave differently for having waited.
+     */
+    initialContext(workflow, triggerPayload) {
         const metadata = JSON.parse(workflow.metadata ?? '{}');
-        // Mark executions started by an UNAUTHENTICATED public trigger (webhook) so
-        // privileged steps (e.g. SEND_EMAIL, code execution) can refuse to run for
-        // them. Set server-side on a per-execution copy of the metadata — never
-        // sourced from attacker-controlled trigger data.
-        if (opts?.publicTrigger)
-            metadata['publicTrigger'] = true;
-        const initialContext = {
+        return {
             workflow: {
                 id: workflow.id,
                 // The execution's tenant, carried by the resource. The executor
@@ -1302,12 +1638,34 @@ export class WorkflowRuntime {
             steps: {},
             vars: projectVariables(parseWorkflowConfig(workflow.config).variables),
         };
+    }
+    async createAndEnqueue(workflow, triggerPayload, opts) {
+        const scheduled = opts?.scheduled;
+        const attributes = workflow.attributes;
         const execId = await this.persistence.createExecution({
             workflowId: workflow.id,
-            status: 'PENDING',
-            context: JSON.stringify(initialContext),
-            attributes: initialContext.workflow.attributes,
+            status: scheduled ? 'SCHEDULED' : 'PENDING',
+            context: scheduled ? '{}' : JSON.stringify(this.initialContext(workflow, triggerPayload)),
+            attributes,
+            ...(scheduled
+                ? {
+                    fireAt: scheduled.when.at,
+                    origin: { event: scheduled.event, anchor: scheduled.when.anchor },
+                }
+                : {}),
         });
+        if (scheduled) {
+            // The delay is the fast path; `fireAt` on the row is the truth. A host that
+            // sweeps for overdue runs makes a lost job late rather than lost.
+            await this.queue.enqueue({
+                executionId: execId,
+                delay: Math.max(0, scheduled.when.at.getTime() - Date.now()),
+                singletonKey: execId,
+            });
+            this.log.info(`scheduled execution ${execId} for workflow ${workflow.id} at ` +
+                `${scheduled.when.at.toISOString()} (anchor: ${scheduled.when.anchor.source})`);
+            return execId;
+        }
         await this.queue.enqueue({ executionId: execId });
         this.log.info(`created execution ${execId} for workflow ${workflow.id}`);
         return execId;