@webda/workflow 0.0.0-stage → 4.0.0-beta.14

package/lib/workflow.service.d.ts

@@ -0,0 +1,685 @@
+import { Service, ServiceParameters, SimpleOperationContext, type OperationContext } from "@webda/core";
+import { type FlowDefinition, type FlowDefinitionData, type FlowError, type JournalEntry } from "./graph.js";
+import { type ScheduledTask } from "./interpreter.js";
+import { type WorkflowControls } from "./hooks.js";
+import { WorkflowInstance, type WorkflowLauncher } from "./models/workflowinstance.model.js";
+import { WorkflowTask } from "./models/workflowtask.model.js";
+import { WorkflowSignal } from "./models/workflowsignal.model.js";
+import { Workflow as StoredWorkflow } from "./models/workflow.model.js";
+/**
+ * Output schema of every flow launch operation
+ */
+export declare const LAUNCH_OUTPUT_SCHEMA = "Webda/WorkflowLaunch.output";
+/**
+ * `runAt` of a wait without timeout (JSON has no Infinity)
+ */
+export declare const NO_TIMEOUT: number;
+/**
+ * A stored workflow registered on this replica
+ */
+interface RegisteredStoredFlow {
+    /**
+     * Flow ID
+     */
+    flowId: string;
+    /**
+     * Version
+     */
+    version: string;
+    /**
+     * Updated by
+     */
+    updatedBy?: string;
+    /**
+     * JSON of its crons, to notice a change
+     */
+    crons: string;
+    /**
+     * Export ids of the crons registered for it: only those are removed
+     */
+    cronIds: string[];
+}
+/**
+ * Abort signal of the current workflow task attempt
+ *
+ * It is aborted on timeout, when the worker loses the task lease, and when the service stops. An operation run by a
+ * workflow should observe it to stop early: an attempt that keeps running is ignored, and the task may run again
+ * (operations are assumed idempotent).
+ * @returns the signal, undefined outside a workflow task
+ */
+export declare function useAbortSignal(): AbortSignal | undefined;
+/**
+ * An attempt running on this replica
+ */
+interface RunningAttempt {
+    /**
+     * Task
+     */
+    task: WorkflowTask;
+    /**
+     * Controller
+     */
+    controller: AbortController;
+}
+/**
+ * Parameters of the {@link WorkflowService}
+ */
+export declare class WorkflowServiceParameters extends ServiceParameters {
+    /**
+     * Interval between two polls of the worker (ms)
+     * @default 1000
+     */
+    pollInterval: number;
+    /**
+     * Maximum number of tasks running at once on this replica
+     * @default 10
+     */
+    concurrency: number;
+    /**
+     * Lease of a claimed task (ms), renewed while it runs
+     * @default 60000
+     */
+    leaseDuration: number;
+    /**
+     * Maximum size of the journal and input of an instance (bytes of JSON)
+     * @default 262144
+     */
+    maxContextSize: number;
+    /**
+     * Run the worker loop on this replica
+     * @default true
+     */
+    worker: boolean;
+    /**
+     * Allow `useSystem` tasks in stored workflows
+     * @default false
+     */
+    allowStoredSystem: boolean;
+    /**
+     * How long a signal sent before any wait is kept (Duration syntax)
+     * @default "1d"
+     */
+    signalTtl: string;
+    /**
+     * Interval of the recovery sweep (ms): an active instance not updated for this long and without a live task is
+     * replayed
+     * @default 60000
+     */
+    sweepInterval: number;
+    /**
+     * Grace period of stop() for the running attempts (ms), then they are aborted and their outcome dropped
+     * @default 30000
+     */
+    stopTimeout: number;
+    /**
+     * Flows to register
+     */
+    flows?: FlowDefinitionData[];
+    /**
+     * Maximum size of a signal payload (bytes of JSON)
+     * @default 65536
+     */
+    maxSignalPayload: number;
+    /**
+     * Maximum number of unexpired buffered signals per `(event, key)`: a new one past it is refused
+     * @default 100
+     */
+    maxBufferedSignals: number;
+    /**
+     * Role needed to create, update or delete a stored workflow
+     * @default "workflow-admin"
+     */
+    storedWorkflowRole: string;
+    /**
+     * PubSub service announcing the stored workflow changes to the other replicas
+     */
+    syncPubSub?: string;
+    /**
+     * Without `syncPubSub`, interval between two reloads of the stored workflows (ms)
+     * @default 60000
+     */
+    syncInterval: number;
+    /**
+     * @override
+     * @param params - the input parameters
+     * @returns this
+     */
+    load(params?: any): this;
+}
+/**
+ * Runs durable workflows: registers each flow as an operation, launches instances and runs their tasks
+ *
+ * Every replica runs the worker loop: a task is claimed with a lease (a conditional patch on `leaseUntil`), so it
+ * runs on one replica at a time. Its outcome goes to the instance journal (a conditional patch on `revision`), then
+ * the flow is replayed to find the next tasks.
+ *
+ * @WebdaModda WorkflowService
+ */
+export declare class WorkflowService<T extends WorkflowServiceParameters = WorkflowServiceParameters> extends Service<T> implements WorkflowControls {
+    /**
+     * Flows registered on this service, by flow id
+     */
+    protected flows: Map<string, FlowDefinition>;
+    /**
+     * Every version registered of each flow, for migrate
+     */
+    protected versions: Map<string, Map<string, FlowDefinition>>;
+    /**
+     * Flows of the modules (compiled `.flow.ts`) registered by this service
+     */
+    protected moduleFlows: Set<string>;
+    /**
+     * Worker id, the lease owner of the tasks it claims
+     */
+    protected workerId: `${string}-${string}-${string}-${string}-${string}`;
+    /**
+     * Attempts running on this replica, by task uuid
+     */
+    protected running: Map<string, RunningAttempt>;
+    /**
+     * Tasks reclaimed after too many crashes: they fail without running
+     */
+    protected crashed: WeakSet<WorkflowTask>;
+    /**
+     * The service is stopping: nothing more is claimed
+     */
+    protected stopping: boolean;
+    /**
+     * Poll in progress
+     */
+    protected pollPromise?: Promise<void>;
+    /**
+     * Last recovery sweep (ms)
+     */
+    protected lastSweep: number;
+    /**
+     * Executions started by the worker loop
+     */
+    protected executions: Set<Promise<void>>;
+    /**
+     * Worker loop timer
+     */
+    protected timer?: NodeJS.Timeout;
+    /**
+     * Stored workflows registered here, by workflow uuid
+     */
+    protected storedFlows: Map<string, RegisteredStoredFlow>;
+    /**
+     * Stored workflows reload timer
+     */
+    protected syncTimer?: NodeJS.Timeout;
+    /**
+     * Subscription to the stored workflow changes
+     */
+    protected syncConsumer?: {
+        cancel: () => any;
+    };
+    /**
+     * @override
+     */
+    resolve(): this;
+    /**
+     * Register the flows compiled from the `.flow.ts` files (`flows` of the modules), with their crons
+     *
+     * The first WorkflowService to resolve registers them; the typed calls are resolved in {@link init}, once every
+     * service registered its operations.
+     */
+    protected registerModuleFlows(): void;
+    /**
+     * The operation a typed call (`target: { class, method }`) runs: the operation of the configured service whose
+     * instance is of that class (matched by constructor name, the class or an ancestor)
+     * @param target - the target of the task
+     * @param target.class - the service class name
+     * @param target.method - the method name
+     * @returns the operation id, or why there is none: no service (missing) or several (ambiguous)
+     */
+    resolveTarget(target: {
+        class: string;
+        method: string;
+    }): {
+        operation?: string;
+        missing?: string;
+        ambiguous?: string;
+    };
+    /**
+     * Resolve the typed calls of a flow body in place
+     * @param body - the statements
+     * @returns the problems, by statement id
+     */
+    protected resolveTargets(body: any[]): {
+        missing: string[];
+        ambiguous: string[];
+    };
+    /**
+     * Point every typed call of the compiled flows at the operation of the configured service of its class
+     *
+     * A flow whose service is not configured (a packaged unit without it) is removed with its crons; a call that several
+     * services serve, or a flow whose operation was taken over, stops the startup.
+     * @throws FatalInitError on an ambiguous call, or a flow id taken by another operation
+     */
+    protected resolveModuleTargets(): void;
+    /**
+     * Remove a module flow: its operation and its crons
+     * @param id - the flow id
+     */
+    protected unregisterModuleFlow(id: string): void;
+    /**
+     * @override
+     */
+    init(): Promise<this>;
+    /**
+     * Stop the worker loop
+     *
+     * Running attempts get `stopTimeout` to finish, then they are aborted and their outcome dropped: their lease
+     * expires and another worker runs them again.
+     * @override
+     */
+    stop(): Promise<void>;
+    /**
+     * Register a schema in the validator and the application
+     * @param name - schema name
+     * @param schema - the JSON schema
+     */
+    protected registerSchema(name: string, schema: any): void;
+    /**
+     * Register a flow as an operation `<flow id>` served by {@link launch}
+     * @param def - the flow definition
+     */
+    registerFlow(def: FlowDefinition): void;
+    /**
+     * Get a registered flow
+     * @param flowId - the flow id
+     * @returns the definition
+     */
+    getFlow(flowId: string): FlowDefinition | undefined;
+    /**
+     * Find a flow registered on any WorkflowService, by its operation
+     * @param flowId - the flow id
+     * @returns the current definition, undefined when the operation is not a flow
+     */
+    resolveFlow(flowId: string | undefined): FlowDefinition | undefined;
+    /**
+     * Find a version of a flow
+     * @param flowId - the flow id
+     * @param version - the version
+     * @returns the definition
+     */
+    getFlowVersion(flowId: string, version: string): FlowDefinition | undefined;
+    /**
+     * Role needed to write a stored workflow
+     * @returns the role
+     */
+    getStoredWorkflowRole(): string;
+    /**
+     * Validate and stamp stored workflows on save, and register them once saved
+     */
+    protected listenStored(): void;
+    /**
+     * Validate a stored workflow about to be saved and stamp its version and last saver
+     * @param workflow - the workflow as it will be saved
+     * @param target - the data written: receives `version` and `updatedBy`
+     */
+    protected prepareStored(workflow: any, target: any): void;
+    /**
+     * Validate a stored workflow
+     * @param workflow - the workflow
+     * @throws BadRequest when its name, graph or options are refused
+     */
+    validateStored(workflow: any): void;
+    /**
+     * The flow served by an operation, if it is a flow
+     * @param flowId - the operation id
+     * @returns the flow of the WorkflowService serving the operation
+     */
+    protected operationFlow(flowId: string): FlowDefinition | undefined;
+    /**
+     * User a stored flow runs as when the system launches it: its last saver
+     * @param flowId - the flow id
+     * @returns the user id, undefined when unknown
+     */
+    storedRunAs(flowId: string): string | undefined;
+    /**
+     * Identity of a new instance: a stored flow never runs as the system, it runs as its last saver
+     * @param def - the flow
+     * @param launcher - the identity of the caller (launch) or of the parent instance (child flows)
+     * @returns the launcher of the instance
+     * @throws Forbidden when a stored flow launched by the system has no user to run as
+     */
+    protected instanceLauncher(def: FlowDefinition, launcher: WorkflowLauncher): WorkflowLauncher;
+    /**
+     * Identity of a child flow, which must be allowed to call the flow operation like a launch
+     * @param def - the child flow
+     * @param launcher - the launcher of the parent
+     * @param input - the child input
+     * @returns the launcher of the child
+     * @throws TaskError Forbidden when the child may not be started
+     */
+    protected childLauncher(def: FlowDefinition, launcher: WorkflowLauncher, input: any): Promise<WorkflowLauncher>;
+    /**
+     * A stored workflow changed on this replica: register it here and tell the others
+     * @param uuid - the workflow uuid
+     */
+    protected storedChanged(uuid: string): Promise<void>;
+    /**
+     * Register, re-register or remove a stored workflow from the store
+     * @param uuid - the workflow uuid
+     */
+    protected syncStored(uuid: string): Promise<void>;
+    /**
+     * Validate then register a stored workflow; an invalid one is removed and logged
+     * @param workflow - the stored workflow
+     * @returns true when registered
+     */
+    protected registerStored(workflow: StoredWorkflow): boolean;
+    /**
+     * Register a stored workflow as a flow, with its crons
+     * @param workflow - the stored workflow
+     */
+    protected applyStored(workflow: StoredWorkflow): void;
+    /**
+     * Remove a stored workflow: its operation and its crons (running instances keep their pinned definition)
+     * @param uuid - the workflow uuid
+     */
+    protected unregisterStored(uuid: string): void;
+    /**
+     * Load every stored workflow: register the new and changed ones, remove the deleted ones
+     */
+    protected reloadStored(): Promise<void>;
+    /**
+     * Follow the stored workflow changes of the other replicas: through `syncPubSub`, or a reload every
+     * `syncInterval`
+     */
+    protected startSync(): void;
+    /**
+     * Launch the flow of the current operation, as the caller
+     * @param args - the flow parameters, in order
+     * @returns the instance uuid
+     */
+    launch(...args: any[]): Promise<{
+        uuid: string;
+    }>;
+    /**
+     * Create an instance and run it to its first tasks
+     * @param def - the flow definition, pinned in the instance
+     * @param input - the flow input
+     * @param launcher - the identity of the steps
+     * @param options - the parent of an awaited child, a fixed uuid (created once)
+     * @param options.parent - parent instance and task key
+     * @param options.parent.instance - parent instance uuid
+     * @param options.parent.key - task key in the parent
+     * @param options.uuid - uuid of the instance: an existing one is not created again
+     * @returns the instance
+     */
+    protected createInstance(def: FlowDefinition, input: Record<string, any>, launcher: WorkflowLauncher, options?: {
+        parent?: {
+            instance: string;
+            key: string;
+        };
+        uuid?: string;
+    }): Promise<WorkflowInstance>;
+    /**
+     * Start the worker loop
+     */
+    protected startWorker(): void;
+    /**
+     * One iteration of the worker loop: claim due tasks and run them in the background
+     * @returns the poll in progress, it ends when the tasks are claimed and started
+     */
+    protected poll(): Promise<void>;
+    /**
+     * Run the recovery sweep when `sweepInterval` passed since the last one
+     */
+    protected maybeSweep(): Promise<void>;
+    /**
+     * Replay the stranded instances: active, not updated for `sweepInterval`, without a PENDING or RUNNING task
+     *
+     * A crash between two steps leaves such an instance: replay is idempotent, and the revision CAS of
+     * {@link advance} guards against a concurrent writer.
+     * @returns the number of instances replayed
+     */
+    protected sweep(): Promise<number>;
+    /**
+     * One poll: claim the due tasks and run them
+     * @returns the number of tasks claimed
+     */
+    protected tick(): Promise<number>;
+    /**
+     * Claim the due tasks, up to the free slots of this replica
+     *
+     * The PENDING tasks due now, and the RUNNING ones whose lease expired (their worker crashed)
+     * @returns the tasks claimed
+     */
+    protected claimDue(): Promise<WorkflowTask[]>;
+    /**
+     * Claim a task with a lease: a conditional patch on its `leaseUntil`
+     *
+     * Reclaiming an expired lease counts as a new attempt.
+     * @param task - the task, as queried
+     * @param extra - other fields to set with the claim
+     * @returns true when this worker holds the task
+     */
+    protected claim(task: WorkflowTask, extra?: Partial<WorkflowTask>): Promise<boolean>;
+    /**
+     * Run a claimed task, write its outcome and advance its instance
+     *
+     * Every write of the attempt is conditional on the lease this worker holds: an attempt whose lease was lost (its
+     * worker was too slow and another one reclaimed it) drops its outcome.
+     * @param task - the task
+     * @param advance - advance the instance after the outcome is journaled
+     */
+    protected execute(task: WorkflowTask, advance?: boolean): Promise<void>;
+    /**
+     * Conditional patch of a task row on the lease this worker holds
+     * @param task - the task, with the lease this worker holds
+     * @param data - the changes
+     * @returns false when another worker holds the lease now
+     */
+    protected patchLeased(task: WorkflowTask, data: Partial<WorkflowTask>): Promise<boolean>;
+    /**
+     * Check this worker still holds the lease of a task, and extend it
+     * @param task - the task
+     * @returns false when the lease was lost
+     */
+    protected holdsLease(task: WorkflowTask): Promise<boolean>;
+    /**
+     * Extend the lease of a running task, abort the attempt when the lease was lost
+     * @param task - the task
+     */
+    protected renewLease(task: WorkflowTask): Promise<void>;
+    /**
+     * Record the end of an attempt, if this worker still holds its lease
+     *
+     * `leaseUntil` becomes the end time, never 0: a worker that queried the task before cannot claim it again.
+     * @param task - the task
+     * @param data - status and outcome
+     * @returns false when the lease was lost
+     */
+    protected finishTask(task: WorkflowTask, data: Partial<WorkflowTask>): Promise<boolean>;
+    /**
+     * Create the next attempt of a failed task, after the backoff delay
+     * @param task - the failed attempt
+     */
+    protected scheduleRetry(task: WorkflowTask): Promise<void>;
+    /**
+     * Run the operation (or built-in) of a task
+     * @param task - the task
+     * @param instance - its instance
+     * @param controller - aborted on timeout
+     * @returns the result
+     */
+    protected runTask(task: WorkflowTask, instance: WorkflowInstance, controller: AbortController): Promise<any>;
+    /**
+     * Build the context of the launcher: the session is rebuilt from the user id, so the permissions are fresh
+     * @param launcher - the launcher
+     * @param input - the operation input
+     * @returns the context
+     */
+    protected launcherContext(launcher: WorkflowLauncher, input: any): SimpleOperationContext;
+    /**
+     * Convert an error to the data the flow sees
+     * @param err - the error
+     * @param operation - the operation of the task
+     * @returns the flow error
+     */
+    protected toFlowError(err: any, operation: string): FlowError;
+    /**
+     * Write a task outcome to the instance journal: a conditional patch on `revision`, retried on conflict
+     *
+     * The first outcome of a key wins. A journal over `maxContextSize` fails the instance.
+     * @param instanceId - the instance uuid
+     * @param key - the task key
+     * @param entry - the outcome
+     * @returns true when the outcome is in the journal
+     */
+    protected writeJournal(instanceId: string, key: string, entry: JournalEntry): Promise<boolean>;
+    /**
+     * Patch an instance if its revision did not change
+     * @param instance - the instance as read
+     * @param data - the changes
+     * @returns false when another writer changed it first
+     */
+    protected patchInstance(instance: WorkflowInstance, data: Partial<WorkflowInstance>): Promise<boolean>;
+    /**
+     * Replay an instance and act on the result: finish it, or create its missing tasks
+     * @param instanceId - the instance uuid
+     */
+    protected advance(instanceId: string): Promise<void>;
+    /**
+     * Create the task of a scheduled key, unless a PENDING or RUNNING one exists
+     * @param instance - the instance
+     * @param scheduled - the task to run
+     * @returns true when the task was resolved at once (a buffered signal): the journal changed
+     */
+    protected scheduleTask(instance: WorkflowInstance, scheduled: ScheduledTask): Promise<boolean>;
+    /**
+     * Start an awaited child flow: the task waits for the child instance, which runs as the same launcher
+     * @param instance - the parent instance
+     * @param scheduled - the task, its operation is a flow id
+     * @param index - row index of the key
+     * @returns true when the child finished at once: the parent journal changed
+     */
+    protected scheduleChild(instance: WorkflowInstance, scheduled: ScheduledTask, index: number): Promise<boolean>;
+    /**
+     * Journal the end of a child into its parent: its output, its error, or `Cancelled`
+     * @param childId - the child instance uuid
+     */
+    protected deliverToParent(childId: string): Promise<void>;
+    /**
+     * Cancel an instance, its live tasks and the children it waits on
+     * @param uuid - the instance uuid
+     */
+    cancelInstance(uuid: string): Promise<void>;
+    /**
+     * Cancel an instance and, recursively, the children it waits on
+     * @param uuid - the instance uuid
+     * @returns false when the instance was not running
+     */
+    protected cancelTree(uuid: string): Promise<boolean>;
+    /**
+     * Mark a task row CANCELLED, conditionally on its lease: whoever holds it can no longer write its outcome
+     * @param row - the task row, as read
+     */
+    protected supersede(row: WorkflowTask): Promise<void>;
+    /**
+     * Restart a failed instance: drop the outcome that failed it and every outcome journaled after it, then replay
+     * @param uuid - the instance uuid
+     */
+    retryInstance(uuid: string): Promise<void>;
+    /**
+     * Move a running instance to another version of its flow
+     *
+     * Refused when a journaled or live task key has no statement in the target graph.
+     * @param uuid - the instance uuid
+     * @param version - the target version, the latest registered when undefined
+     */
+    migrateInstance(uuid: string, version?: string): Promise<void>;
+    /**
+     * Deliver a signal: resolve the waits on `(event, key)` whose instance accepts the caller, or buffer it when
+     * nothing waits
+     * @param event - event name
+     * @param key - business key
+     * @param payload - the result of the waits
+     * @returns the number of waits resolved
+     */
+    signal(event: string, key: string, payload?: any): Promise<{
+        delivered: number;
+    }>;
+    /**
+     * The waits on `(event, key)` of active instances
+     * @param event - event name
+     * @param key - business key
+     * @returns the waits and their instance
+     */
+    protected waitsFor(event: string, key: string): Promise<{
+        instance: WorkflowInstance;
+        task: WorkflowTask;
+    }[]>;
+    /**
+     * Whether a sender may signal a wait: the launcher, the system, and the users in the `allow` of the wait
+     * @param context - the sender
+     * @param instance - the instance waiting
+     * @param task - the wait
+     * @returns true when allowed
+     */
+    protected canSignal(context: OperationContext, instance: WorkflowInstance, task: WorkflowTask): Promise<boolean>;
+    /**
+     * Save a signal nothing waits for yet
+     * @param context - the sender
+     * @param event - event name
+     * @param key - business key
+     * @param payload - the payload
+     * @returns the buffered signal
+     */
+    protected bufferSignal(context: OperationContext, event: string, key: string, payload: any): Promise<WorkflowSignal>;
+    /**
+     * Deliver a just buffered signal to a wait created while it was being saved
+     * @param signal - the buffered signal
+     * @returns true when a wait consumed it
+     */
+    protected deliverBuffered(signal: WorkflowSignal): Promise<boolean>;
+    /**
+     * Resolve a new wait with the oldest unexpired buffered signal its instance accepts
+     * @param instance - the instance
+     * @param task - the wait
+     * @returns true when a signal was consumed
+     */
+    protected consumeBuffered(instance: WorkflowInstance, task: WorkflowTask): Promise<boolean>;
+    /**
+     * Consume a buffered signal for a wait: its sender is checked now, against this instance
+     * @param signal - the buffered signal
+     * @param instance - the instance waiting
+     * @param task - the wait
+     * @param advance - advance the instance once the payload is journaled
+     * @returns true when consumed and delivered
+     */
+    protected consumeSignal(signal: WorkflowSignal, instance: WorkflowInstance, task: WorkflowTask, advance: boolean): Promise<boolean>;
+    /**
+     * Resolve a wait with a payload: claimed like a task, so it resolves once
+     * @param task - the wait
+     * @param payload - its result
+     * @param advance - advance the instance once the payload is journaled
+     * @returns false when the wait was already resolved or timed out
+     */
+    protected resolveWait(task: WorkflowTask, payload: any, advance?: boolean): Promise<boolean>;
+    /**
+     * End of a `Workflow.Sleep`
+     * @param input - `{ duration?: string, until?: number }`
+     * @param now - the current time
+     * @returns when the timer fires
+     */
+    protected sleepUntil(input: any, now: number): number;
+    /**
+     * Create a task row, unless another worker created the same row first
+     * @param instance - the instance uuid
+     * @param scheduled - the task
+     * @param launcherId - user id of the launcher
+     * @param runAt - when it becomes runnable
+     * @param attempt - attempt number
+     * @param index - row index of the key, when known
+     * @param extra - other fields of the row
+     * @returns the task created, undefined when another worker created it
+     */
+    protected createTask(instance: string, scheduled: ScheduledTask, launcherId: string | undefined, runAt: number, attempt: number, index?: number, extra?: Partial<WorkflowTask>): Promise<WorkflowTask | undefined>;
+}
+export default WorkflowService;
+//# sourceMappingURL=workflow.service.d.ts.map