anbaric-state-machine 1.0.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "anbaric-state-machine",
+  "version": "1.0.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",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "anbaric-cloud": "^1.0.0",
+    "anbaric-tsapi": "^1.0.0"
+  },
+  "files": [
+    "src"
+  ]
+}

package/src/StateMachine.ts

@@ -0,0 +1,158 @@
+import {Action, Actor, Consumer, Job, JobPersistence, PropertyDefinition, Queue, State} from "anbaric-tsapi";
+import {JobPersistenceFactory} from "./persistence/JobPersistenceFactory";
+import {QueueFactory} from "./scheduling/QueueFactory";
+import {ConsumerFactory} from "./scheduling/ConsumerFactory";
+import {Auditor} from "./auditing/Auditor";
+
+class StateMachine {
+
+    private workflowId: string;
+    private states: Map<string, State>;
+    private startState: string;
+    private dataSchema: Map<string, PropertyDefinition>;
+    private persistence: JobPersistence;
+    private queue: Queue;
+    private consumer: Consumer;
+
+    constructor(workflowId : string, states : Array<State>, startState : string, dataSchema : Array<PropertyDefinition>, persistence : JobPersistence = JobPersistenceFactory.instance(), queue : Queue = QueueFactory.instance()) {
+
+        this.workflowId = workflowId;
+        this.states = new Map(states.map(state => [state.id, state]));
+        this.startState = startState;
+        this.dataSchema = new Map(dataSchema.map(property => [property.id, property]));
+        this.persistence = persistence;
+        this.queue = queue;
+
+        this.consumer = ConsumerFactory.instance(queue)
+        this.consumer.subscribe(workflowId, jobId => this.progressJob(jobId));
+    }
+
+    async startJob(properties?: Map<string, any>, actor? : Actor): Promise<Job> {
+
+        const job = new Job(crypto.randomUUID(), properties, this.startState, this.workflowId,
+            actor?.id ?? this.workflowId);
+
+        if (! this.validateProperties(properties ?? new Map(), true)) throw new Error("Invalid properties");
+
+        if (! this.authorizeActor(actor, job)) {
+            Auditor.instance().audit(job.id, actor, "Unauthorized start", null);
+            throw new Error("Unauthorized");
+        }
+
+        await this.persistence.save(job);
+
+        await this.queue.enqueue(job.id, this.workflowId);
+
+        return job;
+    }
+
+    async updateJob(jobId : string, properties : Map<string, any>, actor : Actor) : Promise<void> {
+
+        if (! this.authorizeActor(actor, await this.persistence.retrieve(jobId))) {
+            Auditor.instance().audit(jobId, actor, "Unauthorized update", null);
+            throw new Error("Unauthorized");
+        }
+
+        if (! this.validateProperties(properties, false)) throw new Error("Invalid properties");
+
+        await this.persistence.updateProperties(jobId, properties);
+        Auditor.instance().audit(jobId, actor, "Properties updated", Object.fromEntries(properties));
+
+        await this.queue.enqueue(jobId, this.workflowId);
+    }
+
+    async executeAction(jobId : string, action : Action) : Promise<void> {
+        const job = await this.persistence.retrieve(jobId);
+
+        if (! action.predicate(job)) throw new Error("Action predicate unmet");
+
+        if (! this.authorizeActor(action.actor, job)) {
+            Auditor.instance().audit(jobId, action.actor, "Unauthorized update", null);
+            throw new Error("Actor not authorized to execute action");
+        }
+
+        const newProperties = await action.run(job);
+
+        if (! this.validateProperties(newProperties, false)) {
+            Auditor.instance().audit(jobId, action.actor, "Invalid properties", Object.fromEntries(newProperties));
+            throw new Error("The action generated invalid properties");
+        }
+
+        await this.persistence.updateProperties(jobId, newProperties);
+        Auditor.instance().audit(jobId, action.actor, "Properties updated", Object.fromEntries(newProperties));
+
+        await this.queue.enqueue(jobId, this.workflowId);
+    }
+
+    private validateProperties(properties : Map<string, any>, isNew : boolean) : boolean {
+        for (const [key, value] of properties) {
+            const definition = this.dataSchema.get(key);
+            if (! definition || ! definition.validation(value)) return false;
+        }
+
+        if (! isNew) return true;
+
+        for (const [key, definition] of this.dataSchema) {
+            if (definition.required && ! properties.has(key)) return false;
+        }
+
+        return true;
+    }
+
+    private async progressJob(jobId : string) : Promise<void> {
+        const auditTransaction = Auditor.instance().transaction();
+        let pristine = true;
+
+        const job = await this.persistence.retrieve(jobId);
+        const currentState = this.states.get(job.stateId!);
+
+        for (const action of currentState?.actions ?? []) {
+            if (! action.predicate(job)) continue;
+
+            if (! this.authorizeActor(action.actor, job)) {
+                auditTransaction.audit(jobId, action.actor, "Unauthorized update", null);
+                continue;
+            }
+
+            const newProperties = await action.run(job);
+
+            if (! this.validateProperties(newProperties, false)) {
+                auditTransaction.audit(jobId, action.actor, "Invalid properties", Object.fromEntries(newProperties));
+                continue;
+            }
+
+            auditTransaction.audit(jobId, action.actor, "Properties updated", Object.fromEntries(newProperties));
+            newProperties.forEach((value, key) => {
+                pristine = false;
+                job.properties.set(key, value);
+            });
+        }
+
+        for (const transition of currentState?.transitions ?? []) {
+            if (! this.states.has(transition.to)) continue;
+            if (job.transition(transition)) {
+                auditTransaction.audit(jobId, undefined, `Transitioned to "${transition.to}"`, null);
+                pristine = false;
+                break;
+            }
+        }
+
+        if (! pristine) {
+            await this.persistence.save(job);
+            await this.queue.enqueue(job.id, this.workflowId);
+        }
+
+        auditTransaction.flush();
+    }
+
+    async cleanUp() : Promise<void> {
+        await this.consumer.cleanUp();
+    }
+
+    private authorizeActor(actor: Actor | undefined, job: Job) : boolean {
+        // TODO
+        return true;
+    }
+}
+
+export { StateMachine }

package/src/actors/Agent.ts

@@ -0,0 +1,16 @@
+import {Actor} from "anbaric-tsapi";
+
+class Agent implements Actor {
+
+    readonly type = "AGENT" as const;
+    readonly id : string;
+    readonly role : string;
+
+    constructor(id : string, role : string) {
+        this.id = id;
+        this.role = role;
+    }
+
+}
+
+export { Agent }

package/src/actors/Code.ts

@@ -0,0 +1,16 @@
+import {Actor} from "anbaric-tsapi";
+
+class Code implements Actor {
+
+    readonly type = "CODE" as const;
+    readonly id : string;
+    readonly role : string;
+
+    constructor(id : string, role : string = "code") {
+        this.id = id;
+        this.role = role;
+    }
+
+}
+
+export { Code }

package/src/actors/Human.ts

@@ -0,0 +1,16 @@
+import {Actor} from "anbaric-tsapi";
+
+class Human implements Actor {
+
+    readonly type = "HUMAN" as const;
+    readonly id : string;
+    readonly role : string;
+
+    constructor(id : string, role : string) {
+        this.id = id;
+        this.role = role;
+    }
+
+}
+
+export { Human }

package/src/auditing/Auditor.ts

@@ -0,0 +1,25 @@
+import {Actor} from "anbaric-tsapi";
+import {AuditorTransaction} from "./AuditorTransaction";
+
+class Auditor {
+
+    private static singleton? : Auditor;
+
+    static instance() : Auditor {
+        if (!Auditor.singleton) {
+            Auditor.singleton = new Auditor();
+        }
+        return Auditor.singleton;
+    }
+
+    audit(jobId : string, actor : Actor | undefined, changeDescription : string, details : any) : void {
+        console.log(`[${jobId}] ${actor?.id ?? "anonymous"} ${changeDescription} ${JSON.stringify(details ?? null)}`);
+    }
+
+    transaction() : AuditorTransaction {
+        return new AuditorTransaction(this);
+    }
+
+}
+
+export { Auditor }

package/src/auditing/AuditorTransaction.ts

@@ -0,0 +1,29 @@
+import {Actor} from "anbaric-tsapi";
+import type {Auditor} from "./Auditor";
+
+type AuditEntry = {
+    jobId : string,
+    actor : Actor | undefined,
+    changeDescription : string,
+    details : any,
+};
+
+class AuditorTransaction {
+
+    private entries = new Array<AuditEntry>();
+
+    constructor(private auditor : Auditor) {}
+
+    audit(jobId : string, actor : Actor | undefined, changeDescription : string, details : any) : void {
+        this.entries.push({ jobId, actor, changeDescription, details });
+    }
+
+    flush() : void {
+        this.entries.forEach(entry =>
+            this.auditor.audit(entry.jobId, entry.actor, entry.changeDescription, entry.details));
+        this.entries = [];
+    }
+
+}
+
+export { AuditorTransaction }

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from "./StateMachine";
+export * from "./actors/Agent";
+export * from "./actors/Code";
+export * from "./actors/Human";
+export * from "./auditing/Auditor";
+export * from "./auditing/AuditorTransaction";
+export * from "./persistence/InMemoryJobPersistence";
+export * from "./persistence/JobPersistenceFactory";
+export * from "./scheduling/InMemoryQueue";
+export * from "./scheduling/PullConsumer";
+export * from "./scheduling/ConsumerFactory";
+export * from "./scheduling/QueueFactory";

package/src/persistence/InMemoryJobPersistence.ts

@@ -0,0 +1,37 @@
+import {Job, JobPersistence} from "anbaric-tsapi";
+
+class InMemoryJobPersistence implements JobPersistence {
+
+    private jobs = new Map<string, Job>();
+
+    async save(job : Job) : Promise<void> {
+        this.jobs.set(job.id, job);
+    }
+
+    async retrieve(id : string) : Promise<Job> {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new Error(`No job found with id "${id}"`);
+        }
+        return job;
+    }
+
+    async delete(id : string) : Promise<void> {
+        this.jobs.delete(id);
+    }
+
+    async list(pageSize : number = 100, page : number = 0) : Promise<Array<Job>> {
+        return Array.from(this.jobs.values()).slice(page * pageSize, (page + 1) * pageSize);
+    }
+
+    async updateProperties(id : string, properties : Map<string, any>) : Promise<void> {
+        const job = await this.retrieve(id);
+        for (const [key, value] of properties) {
+            job.properties.set(key, value);
+        }
+        job.lastUpdated = new Date();
+    }
+
+}
+
+export { InMemoryJobPersistence }

package/src/persistence/JobPersistenceFactory.ts

@@ -0,0 +1,17 @@
+import {JobPersistence} from "anbaric-tsapi";
+import {CloudJobPersistence} from "anbaric-cloud";
+import {InMemoryJobPersistence} from "./InMemoryJobPersistence";
+
+const JobPersistenceFactory = {
+    instance() : JobPersistence {
+        switch (process.env.ANBARIC_JOB_PERSISTENCE_TYPE) {
+            case "cloud":
+                return new CloudJobPersistence();
+            case "memory":
+            default:
+                return new InMemoryJobPersistence();
+        }
+    }
+}
+
+export { JobPersistenceFactory };

package/src/scheduling/ConsumerFactory.ts

@@ -0,0 +1,15 @@
+import {Consumer, Dequeue, Queue} from "anbaric-tsapi";
+import {PushConsumer} from "anbaric-cloud";
+import {PullConsumer} from "./PullConsumer";
+
+const ConsumerFactory = {
+    instance(queue : Queue) : Consumer {
+        if (Dequeue.supports(queue)) {
+            return new PullConsumer(queue);
+        } else {
+            return new PushConsumer();
+        }
+    }
+}
+
+export { ConsumerFactory };

package/src/scheduling/InMemoryQueue.ts

@@ -0,0 +1,29 @@
+import {Dequeue, QueueMessage} from "anbaric-tsapi";
+
+class InMemoryQueue implements Dequeue {
+
+    private ready : Array<QueueMessage> = [];
+    private scheduled : Array<{ message : QueueMessage, due : Date }> = [];
+
+    async enqueue(jobId : string, workflowId : string) : Promise<void> {
+        this.ready.push({ jobId, workflowId });
+    }
+
+    async schedule(jobId : string, workflowId : string, due : Date) : Promise<void> {
+        this.scheduled.push({ message: { jobId, workflowId }, due });
+    }
+
+    async dequeueSome() : Promise<Array<QueueMessage>> {
+        const now = new Date();
+        const released = this.scheduled
+            .filter((entry) => entry.due <= now)
+            .sort((a, b) => a.due.getTime() - b.due.getTime());
+        this.scheduled = this.scheduled.filter((entry) => entry.due > now);
+        const messages = [...this.ready, ...released.map((entry) => entry.message)];
+        this.ready = [];
+        return messages;
+    }
+
+}
+
+export { InMemoryQueue }

package/src/scheduling/PullConsumer.ts

@@ -0,0 +1,54 @@
+import {Consumer, Dequeue, QueueMessage} from "anbaric-tsapi";
+
+type ProcessJob = (jobId : string) => Promise<void>;
+
+class PullConsumer implements Consumer {
+
+    private subscribers = new Map<string, ProcessJob>();
+    private ticker? : NodeJS.Timeout;
+    private draining = false;
+
+    constructor(private queue : Dequeue, private pollIntervalMs : number = 1000) {}
+
+    subscribe(workflowId : string, processJob : ProcessJob) : void {
+        this.subscribers.set(workflowId, processJob);
+        if (!this.ticker) {
+            this.ticker = setInterval(() => void this.drain(), this.pollIntervalMs);
+            this.ticker.unref();
+        }
+    }
+
+    async cleanUp() : Promise<void> {
+        if (this.ticker) clearInterval(this.ticker);
+        this.ticker = undefined;
+        this.subscribers.clear();
+    }
+
+    private async drain() : Promise<void> {
+        if (this.draining) return;
+        this.draining = true;
+        try {
+            for (const message of await this.queue.dequeueSome()) {
+                await this.forward(message);
+            }
+        } finally {
+            this.draining = false;
+        }
+    }
+
+    private async forward(message : QueueMessage) : Promise<void> {
+        const processJob = this.subscribers.get(message.workflowId);
+        if (!processJob) {
+            await this.queue.enqueue(message.jobId, message.workflowId);
+            return;
+        }
+        try {
+            await processJob(message.jobId);
+        } catch {
+            await this.queue.enqueue(message.jobId, message.workflowId);
+        }
+    }
+
+}
+
+export { PullConsumer }

package/src/scheduling/QueueFactory.ts

@@ -0,0 +1,17 @@
+import {Queue} from "anbaric-tsapi";
+import {CloudQueue} from "anbaric-cloud";
+import {InMemoryQueue} from "./InMemoryQueue";
+
+const QueueFactory = {
+    instance() : Queue {
+        switch (process.env.ANBARIC_QUEUE_TYPE) {
+            case "cloud":
+                return new CloudQueue();
+            case "memory":
+            default:
+                return new InMemoryQueue();
+        }
+    }
+}
+
+export { QueueFactory };