anbaric-state-machine 1.18.1 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-state-machine",
-  "version": "1.18.1",
+  "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.18.1",
-    "anbaric-tsapi": "^1.18.1"
+    "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, role: action.actor.role },
-                })),
-                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);
     }

package/src/actors/Code.ts

@@ -4,11 +4,11 @@ class Code implements Actor {
 
     readonly type = "CODE" as const;
     readonly id : string;
-    readonly role : string;
+    readonly roles : Array<string>;
 
-    constructor(id : string, role : string = "code") {
+    constructor(id : string, roles : Array<string> | string = "code") {
         this.id = id;
-        this.role = role;
+        this.roles = typeof roles === "string" ? [roles] : roles;
     }
 
 }

package/src/actors/Human.ts

@@ -1,18 +1,30 @@
-import {Actor} from "anbaric-tsapi";
+import {IncomingMessage} from "node:http";
+import {Actor, SessionResolver} from "anbaric-tsapi";
+import {SessionResolverFactory} from "../sessions/SessionResolverFactory";
+import {sessionCookie} from "../sessions/sessionCookie";
 
 class Human implements Actor {
 
     readonly type = "HUMAN" as const;
     readonly id : string;
-    readonly role : string;
+    readonly roles : Array<string>;
 
-    constructor(id : string, role : string) {
+    constructor(id : string, roles : Array<string> | string) {
         this.id = id;
-        this.role = role;
+        this.roles = typeof roles === "string" ? [roles] : roles;
     }
 
-    static createFromSession() {
-
+    /* Resolves the browser user behind a request to an app page into a Human,
+       for auditing. Takes the platform session - either the anbaric_session
+       token, or the incoming request to read the cookie from - and asks the
+       platform to verify it (an app cannot: the signing secret is platform
+       only). */
+    static async fromSession(source : string | IncomingMessage,
+                             resolver : SessionResolver = SessionResolverFactory.instance()) : Promise<Human> {
+        const token = typeof source === "string" ? source : sessionCookie(source);
+        const session = token ? await resolver.resolve(token) : undefined;
+        if (!session) throw new Error("Could not resolve the session");
+        return new Human(session.id, session.roles);
     }
 
 }

package/src/index.ts

@@ -11,3 +11,6 @@ export * from "./scheduling/InMemoryQueue";
 export * from "./scheduling/PullConsumer";
 export * from "./scheduling/ConsumerFactory";
 export * from "./scheduling/QueueFactory";
+export * from "./sessions/InMemorySessionResolver";
+export * from "./sessions/SessionResolverFactory";
+export * from "./sessions/sessionCookie";

package/src/sessions/InMemorySessionResolver.ts

@@ -0,0 +1,20 @@
+import {ResolvedSession, SessionResolver} from "anbaric-tsapi";
+
+/* A resolver backed by a seeded token->session map, for local runs and tests.
+   Empty by default, so an unknown token resolves to undefined. */
+class InMemorySessionResolver implements SessionResolver {
+
+    private sessions = new Map<string, ResolvedSession>();
+
+    seed(sessionToken : string, session : ResolvedSession) : this {
+        this.sessions.set(sessionToken, session);
+        return this;
+    }
+
+    async resolve(sessionToken : string) : Promise<ResolvedSession | undefined> {
+        return this.sessions.get(sessionToken);
+    }
+
+}
+
+export { InMemorySessionResolver }

package/src/sessions/SessionResolverFactory.ts

@@ -0,0 +1,16 @@
+import {SessionResolver} from "anbaric-tsapi";
+import {CloudSessionResolver} from "anbaric-impl-cloud";
+import {InMemorySessionResolver} from "./InMemorySessionResolver";
+
+const SessionResolverFactory = {
+    instance() : SessionResolver {
+        switch (process.env.ANBARIC_SESSION_RESOLVER_TYPE) {
+            case "cloud":
+                return new CloudSessionResolver();
+            default:
+                return new InMemorySessionResolver();
+        }
+    }
+}
+
+export { SessionResolverFactory };

package/src/sessions/sessionCookie.ts

@@ -0,0 +1,16 @@
+import {IncomingMessage} from "node:http";
+
+const SESSION_COOKIE = "anbaric_session";
+
+/* Reads the anbaric_session cookie value from an incoming request (or a raw
+   Cookie header string). Returns undefined when the cookie is absent. */
+const sessionCookie = (source : IncomingMessage | string) : string | undefined => {
+    const header = typeof source === "string" ? source : String(source.headers.cookie ?? "");
+    for (const cookie of header.split(";")) {
+        const [name, ...value] = cookie.trim().split("=");
+        if (name === SESSION_COOKIE) return value.join("=");
+    }
+    return undefined;
+};
+
+export { sessionCookie, SESSION_COOKIE }