anbaric-state-machine 1.19.0 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-state-machine",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "This is the state machine library that one can use to add state management to an application. It will, by default, be locally runnable but can deployed to the Anbaric Cloud via the CLI",
   "license": "MIT",
   "author": "chris@anbaric.ai",
@@ -15,8 +15,8 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "anbaric-impl-cloud": "^1.19.0",
-    "anbaric-tsapi": "^1.19.0"
+    "anbaric-impl-cloud": "^1.20.0",
+    "anbaric-tsapi": "^1.20.0"
   },
   "files": [
     "src"

package/src/StateMachine.ts

@@ -2,6 +2,7 @@ import {
     Action,
     Actor,
     Auditor,
+    Await,
     Consumer,
     Job,
     JobPersistence,
@@ -11,6 +12,7 @@ import {
     SystemActor,
     WorkflowDefinition
 } from "anbaric-tsapi";
+
 import {JobPersistenceFactory} from "./persistence/JobPersistenceFactory";
 import {QueueFactory} from "./scheduling/QueueFactory";
 import {ConsumerFactory} from "./scheduling/ConsumerFactory";
@@ -33,9 +35,6 @@ class StateMachine {
 
     constructor(workflowId : string, states : Array<State>, startState? : string, dataSchema : Array<PropertyDefinition> = [], persistence : JobPersistence = JobPersistenceFactory.instance(), queue : Queue = QueueFactory.instance(), sameStateDelayMs : number = 5 * 60_000, auditor : Auditor = AuditorFactory.instance()) {
 
-        // A deployed app namespaces its state machines by app id, so the same
-        // workflow id used in two different apps never collides. Run locally
-        // (no app id in the environment) the id is used as given.
         const appId = process.env.ANBARIC_APP_ID;
         this.workflowId = appId ? `${appId}/${workflowId}` : workflowId;
         this.states = new Map(states.map(state => [state.id, state]));
@@ -55,21 +54,8 @@ class StateMachine {
     }
 
     private describe() : WorkflowDefinition {
-        return {
-            workflowId: this.workflowId,
-            startState: this.startState,
-            dataSchema: [...this.dataSchema.values()].map(property => ({ id: property.id, required: property.required })),
-            states: [...this.states.values()].map(state => ({
-                id: state.id,
-                isTerminal: state.isTerminal,
-                actions: state.actions.map(action => ({
-                    name: action.name,
-                    description: action.description,
-                    actor: { id: action.actor.id, type: action.actor.type, roles: action.actor.roles },
-                })),
-                transitions: state.transitions.map(transition => ({ to: transition.to })),
-            })),
-        };
+        return WorkflowDefinition.describe(this.workflowId, this.startState,
+            [...this.states.values()], [...this.dataSchema.values()]);
     }
 
     async startJob(properties?: Map<string, any>, actor : Actor = this.machineActor): Promise<Job> {
@@ -111,6 +97,83 @@ class StateMachine {
         }
     }
 
+    private async progressJob(jobId : string) : Promise<void> {
+
+        const job = await this.persistence.retrieve(jobId, this.machineActor);
+        if (job.killed) return;
+
+        const currentState = this.states.get(job.state);
+        if (currentState?.isTerminal) return;
+
+        // A job resuming from "Awaiting input" (re-enqueued by an update to its
+        // properties) skips its actions entirely and only re-evaluates its
+        // transitions - the input it was parked for drives it on.
+        const wasAwaiting = job.status === Job.Status.AWAITING_INPUT;
+        const involvedActors : Array<Actor> = [];
+        let propertiesChanged = false;
+
+        if (! wasAwaiting) {
+            for (const item of currentState?.actions ?? []) {
+                if (item instanceof Await) {
+                    job.status = Job.Status.AWAITING_INPUT;
+                    job.awaitMetadata = item.waitForInput(job);
+                    job.waitingFor = crypto.randomUUID();
+                    await this.persistence.save(this.machineActor, `Job ${job.id} awaiting input`, job,
+                        propertiesChanged ? job.properties : undefined);
+                    return;
+                }
+
+                if (! item.predicate(job)) continue;
+                if (! this.authorizeActor(item.actor, job)) continue;
+
+                const newProperties = await item.run(job);
+
+                let applied = false;
+                for (const [key, value] of newProperties) {
+                    const problem = this.propertyProblem(key, value);
+                    if (problem) {
+                        console.warn(`[${this.workflowId}] action "${item.name}" set "${key}", which ${problem}, on job ${job.id} — skipping that property.`);
+                        continue;
+                    }
+                    if (job.properties.has(key) && this.sameValue(job.properties.get(key), value)) continue;
+                    job.properties.set(key, value);
+                    propertiesChanged = true;
+                    applied = true;
+                }
+
+                if (applied) involvedActors.push(item.actor);
+            }
+        }
+
+        let newState : string | undefined = undefined;
+        for (const transition of currentState?.transitions ?? []) {
+            if (! this.states.has(transition.to)) continue;
+            if (transition.predicate(job)) {
+                newState = transition.to;
+                break;
+            }
+        }
+
+        // TODO: persistence.save should have the ability to accept multiple actors for this case.
+        if (newState !== undefined) {
+            job.status = Job.Status.ACTIVE;
+            job.awaitMetadata = undefined;
+            job.waitingFor = undefined;
+            await this.persistence.save(involvedActors[0] ?? this.machineActor, `Job ${job.id} progressed automatically`,
+                job, propertiesChanged ? job.properties : undefined, newState);
+            if (! this.states.get(newState)?.isTerminal) await this.queue.enqueue(job.id, this.workflowId);
+            return;
+        }
+
+        // Parked (still awaiting) or nothing changed: leave the job be until the
+        // next update. Otherwise re-check this state after the back-off delay.
+        if (wasAwaiting || ! propertiesChanged) return;
+
+        await this.persistence.save(involvedActors[0] ?? this.machineActor, `Job ${job.id} progressed automatically`,
+            job, job.properties);
+        await this.queue.schedule(job.id, this.workflowId, new Date(Date.now() + this.sameStateDelayMs));
+    }
+
     private async updateJobInternal(actor: Actor, message : string, job: Job, newProperties?: Map<string, any>, newState? : string) {
 
         if (newProperties && !this.validateProperties(newProperties, false)) throw new Error("Invalid properties");
@@ -140,63 +203,6 @@ class StateMachine {
         return undefined;
     }
 
-    private async progressJob(jobId : string) : Promise<void> {
-        let pristine = true;
-
-        const job = await this.persistence.retrieve(jobId, this.machineActor);
-        if (job.killed) return;
-
-        const currentState = this.states.get(job.state);
-
-        if (currentState?.isTerminal) return;
-
-        const involvedActors : Actor[] = [];
-
-        for (const action of currentState?.actions ?? []) {
-            if (! action.predicate(job)) continue;
-            if (! this.authorizeActor(action.actor, job)) continue;
-
-            const newProperties = await action.run(job);
-
-            let applied = false;
-            for (const [key, value] of newProperties) {
-                const problem = this.propertyProblem(key, value);
-                if (problem) {
-                    console.warn(`[${this.workflowId}] action "${action.name}" set "${key}", which ${problem}, on job ${job.id} — skipping that property.`);
-                    continue;
-                }
-                if (job.properties.has(key) && this.sameValue(job.properties.get(key), value)) continue;
-                job.properties.set(key, value);
-                pristine = false;
-                applied = true;
-            }
-
-            if (applied) involvedActors.push(action.actor);
-        }
-
-        let newState : string | undefined = undefined;
-        for (const transition of currentState?.transitions ?? []) {
-            if (! this.states.has(transition.to)) continue;
-            if (transition.predicate(job)) {
-                newState = transition.to;
-                pristine = false;
-                break;
-            }
-        }
-
-        if (pristine) return;
-
-        // TODO: persistence.save should have the ability to accept multiple actors for this case.
-        await this.persistence.save(involvedActors[0] ?? this.machineActor, `Job ${job.id} progressed automatically`, job, job.properties, newState);
-
-        if (this.states.get(newState ?? job.state)?.isTerminal) return;
-        if (newState !== undefined) {
-            await this.queue.enqueue(job.id, this.workflowId);
-        } else {
-            await this.queue.schedule(job.id, this.workflowId, new Date(Date.now() + this.sameStateDelayMs));
-        }
-    }
-
     private sameValue(a : any, b : any) : boolean {
         return a === b || JSON.stringify(a) === JSON.stringify(b);
     }