anbaric-tsapi 1.20.0 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-tsapi",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "These are the shared libraries - types, classes, etc - that both the public state-machine and hosting services share",
   "license": "MIT",
   "author": "chris@anbaric.ai",

package/src/api/auditing/Auditor.ts

@@ -5,8 +5,8 @@ import {Actor} from "../actors/Actor";
    defines no vocabulary. */
 interface Auditor {
 
-    audit(resourceType : string, resourceId : string, actor : Actor, interaction : Array<string>,
-          description : string, details : any) : Promise<void>;
+    audit(appId : string | undefined, resourceType : string, resourceId : string, actor : Actor,
+          interaction : Array<string>, description : string, details : any) : Promise<void>;
 
 }
 

package/src/api/auditing/NoOpAuditor.ts

@@ -6,8 +6,8 @@ import {Auditor} from "./Auditor";
    already audited the interaction. */
 class NoOpAuditor implements Auditor {
 
-    async audit(_resourceType : string, _resourceId : string, _actor : Actor, _interaction : Array<string>,
-                _description : string, _details : any) : Promise<void> {
+    async audit(_appId : string | undefined, _resourceType : string, _resourceId : string, _actor : Actor,
+                _interaction : Array<string>, _description : string, _details : any) : Promise<void> {
     }
 
 }

package/src/api/cloud/AppAware.ts

@@ -0,0 +1,14 @@
+/* A service that knows which deployed app it belongs to. The id always comes
+   from the environment (ANBARIC_APP_ID), never a constructor argument, so a
+   developer never has to supply it. Hosted services (the state machine, the
+   cloud/Postgres stores) implement this; purely local in-memory ones do not. */
+interface AppAware {
+    getAppId() : string;
+}
+
+// The current app's id from the environment, or "" when running outside a
+// deployed app (locally). The single source for every AppAware implementation.
+const currentAppId = () : string => process.env.ANBARIC_APP_ID ?? "";
+
+export { currentAppId };
+export type { AppAware };

package/src/api/cloud/AuditRecord.ts

@@ -1,5 +1,6 @@
 type AuditRecord = {
     id? : string,
+    appId? : string,
     resourceType : string,
     resourceId : string,
     actorId : string,

package/src/api/cloud/QueueMessage.ts

@@ -1,5 +1,6 @@
 type QueueMessage = {
     jobId : string,
+    appId? : string,
     workflowId : string,
     position? : number,
 };

package/src/api/cloud/WorkflowDefinition.ts

@@ -9,6 +9,7 @@ import {Await} from "../actions/Await";
    not part of the graph - awaiting jobs are surfaced separately. */
 type WorkflowDefinition = {
 
+    appId? : string,
     workflowId : string,
     startState : string,
     dataSchema : Array<{ id : string, required : boolean }>,
@@ -23,8 +24,9 @@ type WorkflowDefinition = {
 
 namespace WorkflowDefinition {
 
-    export const describe = (workflowId : string, startState : string,
+    export const describe = (appId : string | undefined, workflowId : string, startState : string,
                              states : Array<State>, dataSchema : Array<PropertyDefinition>) : WorkflowDefinition => ({
+        appId,
         workflowId,
         startState,
         dataSchema: dataSchema.map(property => ({ id: property.id, required: property.required })),

package/src/api/documents/JsonStore.ts

@@ -1,5 +1,6 @@
 import {Actor} from "../actors/Actor";
 import {Auditor} from "../auditing/Auditor";
+import {currentAppId} from "../cloud/AppAware";
 
 /* A schema-validated JSON document store that audits every interaction, keyed
    by collection and id. Public methods audit then defer to ...Internal. */
@@ -9,27 +10,27 @@ abstract class JsonStore {
     }
 
     async create(actor : Actor, id : string, document : any) : Promise<void> {
-        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [JsonStore.Interaction.CREATE], "Document created", document);
+        await this.auditor.audit(currentAppId(), "document", `${this.collection}/${id}`, actor, [JsonStore.Interaction.CREATE], "Document created", document);
         await this.saveInternal(id, document);
     }
 
     async save(actor : Actor, changeDescription : string, id : string, document : any) : Promise<void> {
-        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [JsonStore.Interaction.SAVE], changeDescription, document);
+        await this.auditor.audit(currentAppId(), "document", `${this.collection}/${id}`, actor, [JsonStore.Interaction.SAVE], changeDescription, document);
         await this.saveInternal(id, document);
     }
 
     async retrieve(id : string, actor : Actor) : Promise<any> {
-        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [JsonStore.Interaction.READ], "", null);
+        await this.auditor.audit(currentAppId(), "document", `${this.collection}/${id}`, actor, [JsonStore.Interaction.READ], "", null);
         return this.retrieveInternal(id);
     }
 
     async delete(id : string, actor : Actor) : Promise<void> {
-        await this.auditor.audit("document", `${this.collection}/${id}`, actor, [JsonStore.Interaction.DELETE], "", null);
+        await this.auditor.audit(currentAppId(), "document", `${this.collection}/${id}`, actor, [JsonStore.Interaction.DELETE], "", null);
         await this.deleteInternal(id);
     }
 
     async list(actor : Actor, pageSize? : number, page? : number) : Promise<Array<any>> {
-        await this.auditor.audit("document", `${this.collection}/*`, actor, [JsonStore.Interaction.LIST], "", null);
+        await this.auditor.audit(currentAppId(), "document", `${this.collection}/*`, actor, [JsonStore.Interaction.LIST], "", null);
         return this.listInternal(pageSize, page);
     }
 

package/src/api/jobs/Job.ts

@@ -5,6 +5,10 @@ class Job {
     readonly id : string;
     readonly state: string;
     readonly properties : Map<string, any>;
+    // A workflow is identified by the composite (appId, workflowId): the app the
+    // job's state machine was deployed in, and the machine's own id. appId is
+    // undefined when running outside a deployed app (locally).
+    readonly appId? : string;
     readonly workflowId? : string;
     readonly startedAt : Date;
     readonly startedBy : string;
@@ -20,7 +24,7 @@ class Job {
     awaitMetadata? : WaitForInput;
 
     constructor(id : string, properties : Map<string, any> = new Map(), state: string, workflowId? : string,
-                startedBy : string = "system", startedAt : Date = new Date(),
+                appId? : string, startedBy : string = "system", startedAt : Date = new Date(),
                 lastUpdated : Date = startedAt, killed : boolean = false,
                 status : string = Job.Status.ACTIVE, awaitMetadata? : WaitForInput,
                 waitingFor? : string) {
@@ -29,6 +33,7 @@ class Job {
         this.properties = properties;
         this.state = state;
         this.workflowId = workflowId;
+        this.appId = appId;
         this.startedBy = startedBy;
         this.startedAt = startedAt;
         this.lastUpdated = lastUpdated;

package/src/api/jobs/JobPersistence.ts

@@ -2,6 +2,7 @@ import {Actor} from "../actors/Actor";
 import {Auditor} from "../auditing/Auditor";
 import {Job} from "./Job";
 import {serializeWaitForInput} from "../actions/WaitForInput";
+import {currentAppId} from "../cloud/AppAware";
 
 /* Persists jobs and audits every interaction. Public methods record the
    interaction against the injected auditor and then defer to the abstract
@@ -14,7 +15,7 @@ abstract class JobPersistence {
     async create(actor : Actor,
                job : Job) : Promise<void> {
 
-        await this.auditor.audit("job", job.id, actor, [JobPersistence.Interaction.CREATE], "Job created", job);
+        await this.auditor.audit(job.appId, "job", job.id, actor, [JobPersistence.Interaction.CREATE], "Job created", job);
 
         this.saveInternal(job);
     }
@@ -38,13 +39,14 @@ abstract class JobPersistence {
             change.metadata = serializeWaitForInput(job.awaitMetadata);
         }
 
-        await this.auditor.audit("job", job.id, actor, interaction, changeDescription, change);
+        await this.auditor.audit(job.appId, "job", job.id, actor, interaction, changeDescription, change);
 
         const updatedJob = new Job(
             job.id,
             properties ? this.updateProperties(job.properties, properties) : job.properties,
             state ? state : job.state,
             job.workflowId,
+            job.appId,
             job.startedBy,
             job.startedAt,
             new Date(),
@@ -58,18 +60,18 @@ abstract class JobPersistence {
     }
 
     async kill(id : string, actor : Actor) : Promise<void> {
-        await this.auditor.audit("job", id, actor, [JobPersistence.Interaction.KILL], "Job killed", null);
+        await this.auditor.audit(currentAppId(), "job", id, actor, [JobPersistence.Interaction.KILL], "Job killed", null);
         await this.killInternal(id);
     }
 
     async killOlderThan(lastUpdatedBefore : Date, actor : Actor) : Promise<number> {
-        await this.auditor.audit("job", "*", actor, [JobPersistence.Interaction.KILL],
+        await this.auditor.audit(currentAppId(), "job", "*", actor, [JobPersistence.Interaction.KILL],
             `Jobs not updated since ${lastUpdatedBefore.toISOString()} killed`, null);
         return this.killOlderThanInternal(lastUpdatedBefore);
     }
 
     async countByState(actor : Actor) : Promise<Array<JobPersistence.StateCount>> {
-        await this.auditor.audit("job", "*", actor, [JobPersistence.Interaction.LIST], "", null);
+        await this.auditor.audit(currentAppId(), "job", "*", actor, [JobPersistence.Interaction.LIST], "", null);
         return this.countByStateInternal();
     }
 
@@ -91,17 +93,17 @@ abstract class JobPersistence {
     }
 
     async retrieve(id : string, actor : Actor) : Promise<Job> {
-        await this.auditor.audit("job", id, actor, [JobPersistence.Interaction.READ], "", null);
+        await this.auditor.audit(currentAppId(), "job", id, actor, [JobPersistence.Interaction.READ], "", null);
         return this.retrieveInternal(id);
     }
 
     async delete(id : string, actor : Actor) : Promise<void> {
-        await this.auditor.audit("job", id, actor, [JobPersistence.Interaction.DELETE], "", null);
+        await this.auditor.audit(currentAppId(), "job", id, actor, [JobPersistence.Interaction.DELETE], "", null);
         await this.deleteInternal(id);
     }
 
     async list(actor : Actor, pageSize? : number, page? : number) : Promise<Array<Job>> {
-        await this.auditor.audit("job", "*", actor, [JobPersistence.Interaction.LIST], "", null);
+        await this.auditor.audit(currentAppId(), "job", "*", actor, [JobPersistence.Interaction.LIST], "", null);
         return this.listInternal(pageSize, page);
     }
 

package/src/api/jobs/JobSerialization.ts

@@ -6,6 +6,7 @@ type SerializedJob = {
     state : string,
     properties : Record<string, any>,
     workflowId? : string,
+    appId? : string,
     startedAt? : string,
     startedBy? : string,
     lastUpdated? : string,
@@ -20,6 +21,7 @@ const serializeJob = (job : Job) : SerializedJob => ({
     state: job.state,
     properties: Object.fromEntries(job.properties),
     workflowId: job.workflowId,
+    appId: job.appId,
     startedAt: job.startedAt.toISOString(),
     startedBy: job.startedBy,
     lastUpdated: job.lastUpdated.toISOString(),
@@ -32,7 +34,7 @@ const serializeJob = (job : Job) : SerializedJob => ({
 const deserializeJob = (serialized : SerializedJob) : Job => {
     const startedAt = serialized.startedAt ? new Date(serialized.startedAt) : new Date();
     return new Job(serialized.id, new Map(Object.entries(serialized.properties)), serialized.state,
-        serialized.workflowId, serialized.startedBy ?? "system", startedAt,
+        serialized.workflowId, serialized.appId, serialized.startedBy ?? "system", startedAt,
         serialized.lastUpdated ? new Date(serialized.lastUpdated) : startedAt, serialized.killed ?? false,
         serialized.status ?? Job.Status.ACTIVE,
         serialized.awaitMetadata ? deserializeWaitForInput(serialized.awaitMetadata) : undefined,

package/src/api/secrets/SecretStore.ts

@@ -1,5 +1,6 @@
 import {Actor} from "../actors/Actor";
 import {Auditor} from "../auditing/Auditor";
+import {currentAppId} from "../cloud/AppAware";
 
 /* Stores named secrets and audits every interaction. The secret value is
    never included in an audit record. Public methods audit then defer to the
@@ -10,27 +11,27 @@ abstract class SecretStore {
     }
 
     async create(actor : Actor, name : string, value : string) : Promise<void> {
-        await this.auditor.audit("secret", name, actor, [SecretStore.Interaction.CREATE], "Secret created", null);
+        await this.auditor.audit(currentAppId(), "secret", name, actor, [SecretStore.Interaction.CREATE], "Secret created", null);
         await this.saveInternal(name, value);
     }
 
     async save(actor : Actor, changeDescription : string, name : string, value : string) : Promise<void> {
-        await this.auditor.audit("secret", name, actor, [SecretStore.Interaction.SAVE], changeDescription, null);
+        await this.auditor.audit(currentAppId(), "secret", name, actor, [SecretStore.Interaction.SAVE], changeDescription, null);
         await this.saveInternal(name, value);
     }
 
     async retrieve(name : string, actor : Actor) : Promise<string> {
-        await this.auditor.audit("secret", name, actor, [SecretStore.Interaction.READ], "", null);
+        await this.auditor.audit(currentAppId(), "secret", name, actor, [SecretStore.Interaction.READ], "", null);
         return this.retrieveInternal(name);
     }
 
     async delete(name : string, actor : Actor) : Promise<void> {
-        await this.auditor.audit("secret", name, actor, [SecretStore.Interaction.DELETE], "", null);
+        await this.auditor.audit(currentAppId(), "secret", name, actor, [SecretStore.Interaction.DELETE], "", null);
         await this.deleteInternal(name);
     }
 
     async list(actor : Actor) : Promise<Array<string>> {
-        await this.auditor.audit("secret", "*", actor, [SecretStore.Interaction.LIST], "", null);
+        await this.auditor.audit(currentAppId(), "secret", "*", actor, [SecretStore.Interaction.LIST], "", null);
         return this.listInternal();
     }
 

package/src/api/sql/SqlStore.ts

@@ -1,5 +1,6 @@
 import {Actor} from "../actors/Actor";
 import {Auditor} from "../auditing/Auditor";
+import {currentAppId} from "../cloud/AppAware";
 
 /* A relational (SQL) store for application data. Public methods audit the
    interaction then defer to the abstract ...Internal. `query` returns rows;
@@ -12,12 +13,12 @@ abstract class SqlStore {
     }
 
     async query(actor : Actor, sql : string, parameters : Array<any> = []) : Promise<Array<Record<string, any>>> {
-        await this.auditor.audit("sql", "*", actor, [SqlStore.Interaction.QUERY], sql, null);
+        await this.auditor.audit(currentAppId(), "sql", "*", actor, [SqlStore.Interaction.QUERY], sql, null);
         return this.queryInternal(sql, parameters);
     }
 
     async execute(actor : Actor, sql : string, parameters : Array<any> = []) : Promise<number> {
-        await this.auditor.audit("sql", "*", actor, [SqlStore.Interaction.EXECUTE], sql, null);
+        await this.auditor.audit(currentAppId(), "sql", "*", actor, [SqlStore.Interaction.EXECUTE], sql, null);
         return this.executeInternal(sql, parameters);
     }
 

package/src/api/state-machine/Consumer.ts

@@ -1,6 +1,6 @@
 interface Consumer {
 
-    subscribe(workflowId : string, processJob : (jobId : string) => Promise<void>) : void;
+    subscribe(appId : string | undefined, workflowId : string, processJob : (jobId : string) => Promise<void>) : void;
     cleanUp() : Promise<void>;
 
 }

package/src/api/state-machine/Queue.ts

@@ -2,8 +2,8 @@ import {QueueMessage} from "../cloud/QueueMessage";
 
 interface Queue {
 
-    enqueue(jobId : string, workflowId : string) : Promise<void>;
-    schedule(jobId : string, workflowId : string, due : Date) : Promise<void>;
+    enqueue(jobId : string, appId : string | undefined, workflowId : string) : Promise<void>;
+    schedule(jobId : string, appId : string | undefined, workflowId : string, due : Date) : Promise<void>;
 
 }
 

package/src/index.ts

@@ -26,3 +26,4 @@ export * from "./api/state-machine/Consumer"
 export * from "./api/cloud/QueueMessage"
 export * from "./api/cloud/WorkflowDefinition"
 export * from "./api/cloud/AuditRecord"
+export * from "./api/cloud/AppAware"