bazis 0.132.0 → 0.134.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/core/agent/AgentToolExecutor.ts +5 -0
  2. package/core/agent/Tool.contract.ts +2 -2
  3. package/core/agent/metadata.ts +11 -0
  4. package/core/infra/connectors/codex/CodexAppServerClient.ts +1 -1
  5. package/core/scripts/di-generate.ts +8 -0
  6. package/core/tools/StandardTools.module.ts +14 -0
  7. package/core/tools/generated/deps.ts +10 -0
  8. package/core/tools/index.ts +8 -0
  9. package/core/tools/orm/OrmEntity.references.ts +71 -0
  10. package/core/tools/orm/ormEntityTools.ts +423 -0
  11. package/core/workflow/contracts/WorkflowError.ts +2 -1
  12. package/core/workflow/contracts/WorkflowPartitions.ts +29 -0
  13. package/core/workflow/contracts/WorkflowProcessUsage.ts +8 -0
  14. package/core/workflow/definitions_module/WorkflowDefinitions.module.ts +7 -2
  15. package/core/workflow/definitions_module/access/Definitions.permissions.ts +4 -2
  16. package/core/workflow/definitions_module/access/ProcessPartition.lookup.ts +27 -0
  17. package/core/workflow/definitions_module/code/CodeProcessPublisher.ts +5 -4
  18. package/core/workflow/definitions_module/events/Definitions.events.ts +1 -1
  19. package/core/workflow/definitions_module/http/Processes.controller.ts +21 -5
  20. package/core/workflow/definitions_module/services/IWorkflowDefinitions.service.ts +10 -0
  21. package/core/workflow/definitions_module/services/WorkflowDefinitions.service.ts +28 -2
  22. package/core/workflow/generated/deps.ts +12 -2
  23. package/core/workflow/index.ts +5 -0
  24. package/core/workflow/runtime_module/WorkflowRuntime.module.ts +9 -0
  25. package/core/workflow/runtime_module/background/WorkflowRetention.ts +2 -2
  26. package/core/workflow/runtime_module/events/Runtime.events.ts +4 -4
  27. package/core/workflow/runtime_module/http/Instances.controller.ts +14 -2
  28. package/core/workflow/runtime_module/internal/ChildCalls.ts +186 -0
  29. package/core/workflow/runtime_module/internal/EventDelivery.ts +234 -0
  30. package/core/workflow/runtime_module/internal/GraphCache.ts +7 -1
  31. package/core/workflow/runtime_module/internal/RunLimits.ts +134 -0
  32. package/core/workflow/runtime_module/internal/RuntimeProcessUsage.ts +13 -0
  33. package/core/workflow/runtime_module/internal/Schedules.ts +97 -30
  34. package/core/workflow/runtime_module/internal/TimerStep.ts +11 -1
  35. package/core/workflow/runtime_module/internal/ToolStep.ts +4 -4
  36. package/core/workflow/runtime_module/internal/WorkflowEngine.ts +544 -132
  37. package/core/workflow/runtime_module/internal/WorkflowJobs.ts +44 -6
  38. package/core/workflow/runtime_module/model/WfHistory.model.ts +1 -1
  39. package/core/workflow/runtime_module/model/WfInstance.model.ts +7 -4
  40. package/core/workflow/runtime_module/model/WfJob.model.ts +18 -8
  41. package/core/workflow/runtime_module/model/WfToken.model.ts +5 -3
  42. package/core/workflow/runtime_module/services/IWorkflowRuntime.service.ts +59 -4
  43. package/core/workflow/runtime_module/services/WorkflowRuntime.service.ts +72 -42
  44. package/core/workflow/tasks_module/events/TaskEvents.ts +4 -8
  45. package/core/workflow/tasks_module/services/WorkflowTasks.service.ts +1 -1
  46. package/library/workflow/ProcessDocument.ts +14 -0
  47. package/library/workflow/cron.ts +103 -24
  48. package/library/workflow/expressions.ts +5 -1
  49. package/library/workflow/index.ts +2 -2
  50. package/library/workflow/masking.ts +17 -3
  51. package/library/workflow/mermaid.ts +22 -6
  52. package/library/workflow/nodeKinds.ts +123 -9
  53. package/library/workflow/palette.ts +3 -1
  54. package/library/workflow/paths.ts +10 -4
  55. package/library/workflow/structure.ts +33 -4
  56. package/library/workflow/validateProcess.ts +141 -17
  57. package/package.json +2 -1
@@ -2,6 +2,9 @@ import type { ServiceProvider } from "../../../di";
2
2
  import { WorkflowClock } from "../../contracts/WorkflowClock";
3
3
  import { RuntimeDbContext } from "../model/Runtime.dbContext";
4
4
  import type { WfJob } from "../model/WfJob.model";
5
+ import { ChildCalls } from "./ChildCalls";
6
+ import { RunLimits } from "./RunLimits";
7
+ import { EventDelivery } from "./EventDelivery";
5
8
  import { Schedules } from "./Schedules";
6
9
  import { TimerStep } from "./TimerStep";
7
10
  import { LEASE_MS, ToolStep } from "./ToolStep";
@@ -31,7 +34,7 @@ export class WorkflowJobs {
31
34
  const now = scope.resolve(WorkflowClock).now();
32
35
  return await db.transactionScope(async () => {
33
36
  const jobs = await db.jobs
34
- .where((j) => j.kind.in(["tool", "timer", "schedule"]).and(j.dueAt.lte(now)).and(j.lockedUntil.isNull().or(j.lockedUntil.lt(now))))
37
+ .where((j) => j.dueAt.lte(now).and(j.lockedUntil.isNull().or(j.lockedUntil.lt(now))))
35
38
  .orderBy((j) => j.id)
36
39
  .take(batchSize)
37
40
  .forUpdate({ skipLocked: true })
@@ -51,9 +54,43 @@ export class WorkflowJobs {
51
54
  async run(job: WfJob, signal: AbortSignal): Promise<void> {
52
55
  const scope = this.services.createScope();
53
56
  try {
54
- if (job.kind === "timer") await scope.resolve(TimerStep).run(job);
55
- else if (job.kind === "schedule") await scope.resolve(Schedules).fire(job);
56
- else await scope.resolve(ToolStep).run(job, signal);
57
+ switch (job.kind) {
58
+ case "timer":
59
+ await scope.resolve(TimerStep).run(job);
60
+ break;
61
+ case "loop":
62
+ await scope.resolve(TimerStep).continueLoop(job);
63
+ break;
64
+ case "schedule":
65
+ await scope.resolve(Schedules).fire(job);
66
+ break;
67
+ case "call":
68
+ await scope.resolve(ChildCalls).call(job);
69
+ break;
70
+ case "returned":
71
+ await scope.resolve(ChildCalls).returned(job);
72
+ break;
73
+ case "cancelChildren":
74
+ await scope.resolve(ChildCalls).cancelChildren(job);
75
+ break;
76
+ case "runTimeout":
77
+ await scope.resolve(RunLimits).runTimeout(job);
78
+ break;
79
+ case "release":
80
+ await scope.resolve(RunLimits).release(job);
81
+ break;
82
+ case "errorHandler":
83
+ await scope.resolve(RunLimits).errorHandler(job);
84
+ break;
85
+ case "event":
86
+ await scope.resolve(EventDelivery).deliverLater(job);
87
+ break;
88
+ case "eventStart":
89
+ await scope.resolve(EventDelivery).startLater(job);
90
+ break;
91
+ default:
92
+ await scope.resolve(ToolStep).run(job, signal);
93
+ }
57
94
  } catch (error) {
58
95
  this.report("job failed", error, { job: job.id, instance: job.instanceId, attempts: job.attempts });
59
96
  await this.giveUpOrDelay(job, error).catch((failure: unknown) => this.report("job failure handling failed", failure, { job: job.id }));
@@ -62,11 +99,12 @@ export class WorkflowJobs {
62
99
  }
63
100
  }
64
101
 
65
- /** Matches the scheduled starts against the published versions. */
102
+ /** Matches the scheduled starts against the published versions and gives a free place to whoever still waits for one. */
66
103
  async reconcile(): Promise<void> {
67
104
  const scope = this.services.createScope();
68
105
  try {
69
106
  await scope.resolve(Schedules).reconcile();
107
+ await scope.resolve(RunLimits).releaseWaiting();
70
108
  } catch (error) {
71
109
  this.report("scheduled starts could not be planned", error);
72
110
  } finally {
@@ -89,7 +127,7 @@ export class WorkflowJobs {
89
127
  await engine.inStep(job.instanceId, async (step) => {
90
128
  await db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
91
129
  const token = step.tokens.find((t) => t.id === job.tokenId);
92
- if (token && token.status === "waiting" && step.instance.status === "running") engine.fail(step, token, "job_failed", message.slice(0, 1000));
130
+ if (token && token.status === "waiting" && step.instance.status === "running") await engine.fail(step, token, "job_failed", message.slice(0, 1000));
93
131
  });
94
132
  } finally {
95
133
  await scope.dispose();
@@ -1,7 +1,7 @@
1
1
  import { Column, Entity, ForeignKey, Index, UUID } from "../../../orm";
2
2
  import { WfInstance } from "./WfInstance.model";
3
3
 
4
- export type HistoryType = "started" | "entered" | "left" | "tool" | "assigned" | "skipped" | "timer" | "event" | "error" | "retried" | "cancelled" | "completed";
4
+ export type HistoryType = "started" | "queued" | "released" | "entered" | "left" | "tool" | "assigned" | "iteration" | "called" | "returned" | "skipped" | "timer" | "event" | "error" | "retried" | "cancelled" | "timedOut" | "handler" | "completed";
5
5
 
6
6
  /** The journal of an instance, append only. Its v7 ids give the order. */
7
7
  @ForeignKey(() => WfInstance, { properties: ["instanceId"], onDelete: "cascade" })
@@ -1,9 +1,12 @@
1
1
  import { Column, Entity, Index, UUID } from "../../../orm";
2
2
 
3
- /** `completed` and `cancelled` are finished: retention deletes them. `failed` waits for retry or cancel. */
4
- export type InstanceStatus = "running" | "completed" | "cancelled" | "failed";
3
+ /**
4
+ * `completed`, `cancelled` and `timedOut` are finished: retention deletes them.
5
+ * `failed` waits for retry or cancel, `pending` for a free place (`maxConcurrent`, `sameKey: "queue"`).
6
+ */
7
+ export type InstanceStatus = "pending" | "running" | "completed" | "cancelled" | "failed" | "timedOut";
5
8
 
6
- export type StartedVia = "manual" | "event" | "schedule";
9
+ export type StartedVia = "manual" | "event" | "schedule" | "callProcess" | "errorHandler";
7
10
 
8
11
  /**
9
12
  * One run of a process. Bound to the version it started with: a new publication
@@ -62,7 +65,7 @@ export class WfInstance {
62
65
  @Column({ type: "boolean" })
63
66
  test = false;
64
67
 
65
- /** The instance whose `callProcess` started this one (stage 3). */
68
+ /** The instance whose `callProcess` started this one, and the waiting token there. */
66
69
  @Index()
67
70
  @Column({ type: "text", nullable: true })
68
71
  parentInstanceId: string | null = null;
@@ -1,12 +1,22 @@
1
1
  import { Column, Entity, ForeignKey, Index, UUID } from "../../../orm";
2
2
  import { WfInstance } from "./WfInstance.model";
3
3
 
4
- /** `tool` calls a service task's Tool; `timer`, `retry` and `schedule` come with their stages. */
5
- export type JobKind = "tool" | "timer" | "retry" | "schedule";
4
+ /**
5
+ * `tool` calls a service task's Tool, `timer` fires a timer, `schedule` starts a
6
+ * scheduled process, `loop` goes on with a loop after a batch of iterations.
7
+ * `call` starts a called process, `returned` tells the caller it ended,
8
+ * `cancelChildren` closes what a closed step called. `runTimeout` ends a run that
9
+ * took too long, `release` starts instances that wait for a place, `errorHandler`
10
+ * starts the process that handles a failure. `event` delivers what `emitLater`
11
+ * wrote, `eventStart` starts a process by an event after `delay` or `debounce`.
12
+ */
13
+ export type JobKind = "tool" | "timer" | "schedule" | "loop" | "call" | "returned" | "cancelChildren" | "runTimeout" | "release" | "errorHandler" | "event" | "eventStart";
6
14
 
7
15
  /**
8
16
  * Deferred work of the worker, created in the same transaction as the waiting
9
- * token. Application instances claim it with `FOR UPDATE SKIP LOCKED`.
17
+ * token. Application instances claim it with `FOR UPDATE SKIP LOCKED`. A
18
+ * transaction holds the row of one instance only: what another instance must do
19
+ * goes through a job, so that two instances never wait for each other.
10
20
  */
11
21
  @ForeignKey(() => WfInstance, { properties: ["instanceId"], onDelete: "cascade" })
12
22
  @Entity({ table: "bazis_wf2_run_jobs" })
@@ -17,7 +27,7 @@ export class WfJob {
17
27
  @Column({ type: "text" })
18
28
  kind: JobKind = "tool";
19
29
 
20
- /** `null` for a `schedule` job: its instance does not exist yet. */
30
+ /** `null` for `schedule`, `event` and `eventStart` jobs: the instance does not exist yet. */
21
31
  @Index()
22
32
  @Column({ type: "text", nullable: true })
23
33
  instanceId: string | null = null;
@@ -26,7 +36,7 @@ export class WfJob {
26
36
  @Column({ type: "text", nullable: true })
27
37
  tokenId: string | null = null;
28
38
 
29
- /** The version a `schedule` job starts. */
39
+ /** The version a `schedule` or `eventStart` job starts. */
30
40
  @Column({ type: "text", nullable: true })
31
41
  versionId: string | null = null;
32
42
 
@@ -34,16 +44,16 @@ export class WfJob {
34
44
  @Column({ type: "datetime" })
35
45
  dueAt = new Date(0);
36
46
 
37
- /** What a job carries besides its token: an event to deliver (stage 4). */
47
+ /** What a job carries besides its token: the caller to tell, the process to release. */
38
48
  @Column({ type: "json", nullable: true })
39
49
  payload: unknown = null;
40
50
 
41
- /** Jobs with one key merge into the last: `debounce` of an event start (stage 4). */
51
+ /** Jobs with one key merge into the last: `debounce` of an event start. */
42
52
  @Index()
43
53
  @Column({ type: "text", nullable: true })
44
54
  dedupeKey: string | null = null;
45
55
 
46
- /** The partition and the start node of a `schedule` job (stage 4). */
56
+ /** The partition and the start node of a `schedule` or `eventStart` job. */
47
57
  @Column({ type: "text", nullable: true })
48
58
  partition: string | null = null;
49
59
 
@@ -2,8 +2,9 @@ import { Column, Entity, ForeignKey, Index, UUID } from "../../../orm";
2
2
  import { WfInstance } from "./WfInstance.model";
3
3
 
4
4
  /**
5
- * `active` passes a node, `waiting` waits for a Tool, a task or a join, `done`
6
- * moved on, `cancelled` was closed by a cancel, `failed` waits for a retry.
5
+ * `active` passes a node, `waiting` waits for a Tool, a task, a join, a loop or a
6
+ * called process, `done` moved on, `cancelled` was closed by a cancel, `failed`
7
+ * waits for a retry.
7
8
  */
8
9
  export type TokenStatus = "active" | "waiting" | "done" | "cancelled" | "failed";
9
10
 
@@ -28,10 +29,11 @@ export class WfToken {
28
29
  @Column({ type: "text" })
29
30
  status: TokenStatus = "active";
30
31
 
32
+ /** A step's result; a loop keeps its progress here while it runs. */
31
33
  @Column({ type: "json", nullable: true })
32
34
  output: unknown = null;
33
35
 
34
- /** The loop token this one runs inside, with its iteration and what only the body sees (stage 3). */
36
+ /** The loop token this one runs inside, with its iteration and what only the body sees: `Locals` of the engine. */
35
37
  @Column({ type: "text", nullable: true })
36
38
  parentTokenId: string | null = null;
37
39
 
@@ -1,5 +1,6 @@
1
1
  import type { AccessFilter } from "../../../access";
2
2
  import type { FormIssue } from "../../../../library/workflow";
3
+ import type { OrmTransaction } from "../../../orm";
3
4
  import type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging } from "../../contracts/types";
4
5
  import type { HistoryType } from "../model/WfHistory.model";
5
6
  import type { InstanceStatus, StartedVia } from "../model/WfInstance.model";
@@ -17,6 +18,30 @@ export interface StartInstance extends WorkflowAuditOptions {
17
18
  readonly language?: string;
18
19
  }
19
20
 
21
+ /** One element of a mass start. */
22
+ export interface StartManyItem {
23
+ readonly input?: unknown;
24
+ /** What the instance is about: required, it is what `sameKey` compares. */
25
+ readonly businessKey: string;
26
+ }
27
+
28
+ export interface StartMany extends WorkflowAuditOptions {
29
+ readonly items: readonly StartManyItem[];
30
+ readonly partition?: string | null;
31
+ readonly actor: WorkflowActor;
32
+ readonly language?: string;
33
+ }
34
+
35
+ /**
36
+ * What became of one element: `started` (the instance may wait as `pending`),
37
+ * `skipped` (`sameKey: "skip"` and `instanceId` is the unfinished one) or `rejected`
38
+ * (no `businessKey`, invalid input).
39
+ */
40
+ export type StartManyResult =
41
+ | { readonly status: "started"; readonly businessKey: string; readonly instanceId: string; readonly instanceStatus: InstanceStatus }
42
+ | { readonly status: "skipped"; readonly businessKey: string; readonly instanceId: string; readonly reason: "same_key" }
43
+ | { readonly status: "rejected"; readonly businessKey: string | null; readonly reason: "business_key_required" | "invalid_input"; readonly issues?: readonly FormIssue[] };
44
+
20
45
  export interface CancelInstance extends WorkflowAuditOptions {
21
46
  readonly reason?: string | null;
22
47
  readonly actor: WorkflowActor;
@@ -35,6 +60,8 @@ export interface InstanceSummary {
35
60
  readonly businessKey: string | null;
36
61
  readonly startedVia: StartedVia;
37
62
  readonly startedBy: WorkflowActor;
63
+ /** The instance whose `callProcess` started this one. */
64
+ readonly parentInstanceId: string | null;
38
65
  readonly error: { readonly node: string; readonly code: string; readonly message: string } | null;
39
66
  readonly createdAt: Date;
40
67
  readonly endedAt: Date | null;
@@ -44,6 +71,9 @@ export interface TokenDetails {
44
71
  readonly id: string;
45
72
  readonly nodeId: string;
46
73
  readonly viaFlowId: string | null;
74
+ /** Inside a loop body: the token of the loop and the number of the iteration. */
75
+ readonly parentTokenId: string | null;
76
+ readonly iteration: number | null;
47
77
  readonly status: TokenStatus;
48
78
  readonly output: unknown;
49
79
  readonly createdAt: Date;
@@ -70,18 +100,32 @@ export interface HistoryEntry {
70
100
  readonly at: Date;
71
101
  }
72
102
 
103
+ /** What led to an event: `$trigger.cause` of the instances it starts. `instanceId` makes `ignoreOwn` work. */
104
+ export interface EmitCause {
105
+ readonly instanceId?: string;
106
+ readonly [key: string]: unknown;
107
+ }
108
+
73
109
  export interface EmitOptions extends WorkflowAuditOptions {
74
110
  /** Which waits it is for: `order:42`. Waits without a correlation take any event of the key. */
75
111
  readonly correlation?: string | null;
76
- /** Only the waits of this partition; it is also the partition of instances the event starts. */
112
+ /**
113
+ * Only the waits of this partition; it is also the partition of instances the
114
+ * event starts, and only processes `WorkflowPartitions` connects to it start.
115
+ */
77
116
  readonly partition?: string | null;
78
117
  /** On whose behalf started instances run; `{ kind: "system", id: "event:<key>" }` by default. */
79
118
  readonly actor?: WorkflowActor;
119
+ readonly cause?: EmitCause | null;
80
120
  }
81
121
 
82
122
  export interface EmitResult {
83
123
  /** Instances started by an `eventStart`. */
84
124
  readonly started: readonly string[];
125
+ /** Processes with `sameKey: "skip"` that did not start: an instance with the key is not finished. */
126
+ readonly skipped: readonly { readonly processKey: string; readonly instanceId: string }[];
127
+ /** Processes that start later: `debounce` or `delay` of their `eventStart`. */
128
+ readonly deferred: readonly { readonly processKey: string }[];
85
129
  /** Instances whose `eventWait` or `boundaryEvent` took the event. */
86
130
  readonly continued: readonly string[];
87
131
  /** Processes with an `eventStart` whose input the payload did not pass. */
@@ -96,17 +140,21 @@ export interface InstanceListQuery extends WorkflowPaging {
96
140
  readonly processKey?: string;
97
141
  readonly businessKey?: string;
98
142
  readonly startedById?: string;
143
+ readonly parentInstanceId?: string;
99
144
  }
100
145
 
101
146
  /**
102
147
  * Runs published versions (WORKFLOW-001 §4). Errors are {@link WorkflowError}:
103
- * `not_found`, `archived`, `invalid_input` with the issues, `wrong_status`.
148
+ * `not_found`, `archived`, `invalid_input` with the issues, `wrong_status`,
149
+ * `conflict` when `sameKey: "skip"` refuses a start.
104
150
  */
105
151
  export abstract class IWorkflowRuntime {
106
- /** Starts the latest version of a process from its manual start. */
152
+ /** Starts the latest version of a process from its manual start. It may wait as `pending` (`maxConcurrent`, `sameKey: "queue"`). */
107
153
  abstract start(processKey: string, options: StartInstance): Promise<InstanceDetails>;
154
+ /** Starts an instance per element, each in its own transaction, and says what became of each. */
155
+ abstract startMany(processKey: string, options: StartMany): Promise<readonly StartManyResult[]>;
108
156
  abstract cancel(instanceId: string, options: CancelInstance): Promise<InstanceDetails>;
109
- /** Retries the failed steps of a `failed` instance. */
157
+ /** Retries the failed steps of a `failed` instance. An instance called by another one is retried through its caller. */
110
158
  abstract retry(instanceId: string, options: RetryInstance): Promise<InstanceDetails>;
111
159
  /** Finishes a user task's wait with the form output and moves on; `wrong_status` when the token no longer waits. */
112
160
  abstract completeToken(tokenId: string, output: unknown, actor: WorkflowActor, options?: { readonly language?: string }): Promise<InstanceDetails>;
@@ -115,6 +163,13 @@ export abstract class IWorkflowRuntime {
115
163
  * `eventStart` for the key, and moves the instances waiting for it.
116
164
  */
117
165
  abstract emit(eventKey: string, payload?: unknown, options?: EmitOptions): Promise<EmitResult>;
166
+ /**
167
+ * Writes an event in the application's transaction: it is delivered as `emit`
168
+ * after the commit and is gone with a rollback. Needs the same `DatabaseProvider`
169
+ * as the process tables. Who it reached is not known at this point: a payload a
170
+ * process refuses goes to the log.
171
+ */
172
+ abstract emitLater(tx: OrmTransaction, eventKey: string, payload?: unknown, options?: EmitOptions): Promise<void>;
118
173
  /** Instances, newest first. */
119
174
  abstract instances(query?: InstanceListQuery): Promise<WorkflowPage<InstanceSummary>>;
120
175
  abstract instance(instanceId: string): Promise<InstanceDetails>;
@@ -1,16 +1,18 @@
1
1
  import { grantsToWhere } from "../../../access";
2
- import { paginate } from "../../../orm";
3
- import { inputSpecOf, type FormIssue, type FormSpec } from "../../../../library/workflow";
2
+ import { paginate, type OrmTransaction } from "../../../orm";
3
+ import { inputSpecOf, type FormSpec } from "../../../../library/workflow";
4
4
  import { isUuid, pageQueryOf, type WorkflowActor, type WorkflowPage } from "../../contracts/types";
5
5
  import { WorkflowError } from "../../contracts/WorkflowError";
6
6
  import type { ServiceProvider } from "../../../di";
7
7
  import { WorkflowInputValidator } from "../../contracts/WorkflowInputValidator";
8
8
  import type { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
9
9
  import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
10
+ import type { EventDelivery, EventMessage } from "../internal/EventDelivery";
10
11
  import type { WorkflowEngine } from "../internal/WorkflowEngine";
11
12
  import type { RuntimeDbContext } from "../model/Runtime.dbContext";
12
13
  import type { WfHistory } from "../model/WfHistory.model";
13
14
  import type { WfInstance } from "../model/WfInstance.model";
15
+ import { WfJob } from "../model/WfJob.model";
14
16
  import type { WfToken } from "../model/WfToken.model";
15
17
  import {
16
18
  IWorkflowRuntime,
@@ -23,15 +25,19 @@ import {
23
25
  type InstanceSummary,
24
26
  type RetryInstance,
25
27
  type StartInstance,
28
+ type StartMany,
29
+ type StartManyResult,
26
30
  } from "./IWorkflowRuntime.service";
27
31
 
28
- const STATUSES = new Set(["running", "completed", "cancelled", "failed"]);
32
+ const STATUSES = new Set(["pending", "running", "completed", "cancelled", "failed", "timedOut"]);
33
+ const MAX_START_MANY = 1000;
29
34
  const EVENT_KEY = /^[a-z][a-z0-9_-]*(\.[a-z][a-z0-9_-]*)+$/;
30
35
 
31
36
  export class WorkflowRuntime extends IWorkflowRuntime {
32
37
  constructor(
33
38
  private readonly db: RuntimeDbContext,
34
39
  private readonly engine: WorkflowEngine,
40
+ private readonly delivery: EventDelivery,
35
41
  private readonly definitions: IWorkflowDefinitions,
36
42
  /** The scope: the input validator is asked here, so that the application's own registration replaces the default. */
37
43
  private readonly services: ServiceProvider,
@@ -49,16 +55,48 @@ export class WorkflowRuntime extends IWorkflowRuntime {
49
55
  if (!start) throw new WorkflowError("wrong_status", `Process ${processKey} has no manual start`);
50
56
  const { value, issues } = await this.validator().validate(inputSpecOf(version.document), options.input, { purpose: "input", processKey, partition, language: options.language ?? this.languages.default, actor: options.actor });
51
57
  if (issues.length > 0) throw new WorkflowError("invalid_input", "The process input is invalid", issues);
52
- const id = await this.engine.begin(this.engine.cache(version), start[0], { input: value, partition, businessKey, startedVia: "manual", actor: options.actor, request: options.request ?? null });
58
+ const { id, skipped } = await this.engine.begin(this.engine.cache(version), start[0], { input: value, partition, businessKey, startedVia: "manual", actor: options.actor, request: options.request ?? null });
59
+ if (skipped) throw new WorkflowError("conflict", `Instance ${id} with this businessKey is not finished`);
53
60
  return await this.instance(id);
54
61
  }
55
62
 
63
+ async startMany(processKey: string, options: StartMany): Promise<readonly StartManyResult[]> {
64
+ actorOf(options.actor);
65
+ const partition = optionalText(options.partition, "partition");
66
+ if (!Array.isArray(options.items) || options.items.length === 0 || options.items.length > MAX_START_MANY) throw new WorkflowError("invalid_input", `items must be a list of 1–${MAX_START_MANY}`);
67
+ const version = await this.definitions.latest(processKey);
68
+ const start = Object.entries(version.document.nodes).find(([, node]) => node.kind === "manualStart");
69
+ if (!start) throw new WorkflowError("wrong_status", `Process ${processKey} has no manual start`);
70
+ const graph = this.engine.cache(version);
71
+ const results: StartManyResult[] = [];
72
+ for (const item of options.items) {
73
+ const businessKey = typeof item?.businessKey === "string" && item.businessKey !== "" && item.businessKey.length <= 200 ? item.businessKey : null;
74
+ if (businessKey === null) {
75
+ results.push({ status: "rejected", businessKey: null, reason: "business_key_required" });
76
+ continue;
77
+ }
78
+ const { value, issues } = await this.validator().validate(inputSpecOf(version.document), item.input, { purpose: "input", processKey, partition, language: options.language ?? this.languages.default, actor: options.actor });
79
+ if (issues.length > 0) {
80
+ results.push({ status: "rejected", businessKey, reason: "invalid_input", issues });
81
+ continue;
82
+ }
83
+ const { id, skipped } = await this.engine.begin(graph, start[0], { input: value, partition, businessKey, startedVia: "manual", actor: options.actor, request: options.request ?? null });
84
+ if (skipped) {
85
+ results.push({ status: "skipped", businessKey, instanceId: id, reason: "same_key" });
86
+ continue;
87
+ }
88
+ const row = await this.db.instances.asNoTracking().firstOrDefault((i) => i.id.eq(id));
89
+ results.push({ status: "started", businessKey, instanceId: id, instanceStatus: row?.status ?? "running" });
90
+ }
91
+ return results;
92
+ }
93
+
56
94
  async cancel(instanceId: string, options: CancelInstance): Promise<InstanceDetails> {
57
95
  actorOf(options.actor);
58
96
  const reason = optionalText(options.reason, "reason", 1000);
59
97
  if (!isUuid(instanceId)) throw notFound(instanceId);
60
98
  const done = await this.engine.inStep(instanceId, async (step) => {
61
- if (step.instance.status !== "running" && step.instance.status !== "failed") throw new WorkflowError("wrong_status", `Instance is ${step.instance.status}`);
99
+ if (step.instance.status !== "pending" && step.instance.status !== "running" && step.instance.status !== "failed") throw new WorkflowError("wrong_status", `Instance is ${step.instance.status}`);
62
100
  await this.engine.cancel(step, reason, options.actor, options.request ?? null);
63
101
  return true;
64
102
  });
@@ -71,6 +109,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
71
109
  if (!isUuid(instanceId)) throw notFound(instanceId);
72
110
  const done = await this.engine.inStep(instanceId, async (step) => {
73
111
  if (step.instance.status !== "failed") throw new WorkflowError("wrong_status", `Only a failed instance is retried; this one is ${step.instance.status}`);
112
+ if (step.instance.parentInstanceId !== null) throw new WorkflowError("wrong_status", `This instance was called by ${step.instance.parentInstanceId}: retry that one`);
74
113
  await this.engine.retry(step, options.actor, options.request ?? null);
75
114
  return true;
76
115
  });
@@ -99,46 +138,18 @@ export class WorkflowRuntime extends IWorkflowRuntime {
99
138
  }
100
139
 
101
140
  async emit(eventKey: string, payload: unknown = {}, options: EmitOptions = {}): Promise<EmitResult> {
102
- if (typeof eventKey !== "string" || !EVENT_KEY.test(eventKey)) throw new WorkflowError("invalid_input", "eventKey must look like payments.received");
103
- if (typeof payload !== "object" || payload === null || Array.isArray(payload)) throw new WorkflowError("invalid_input", "payload must be a JSON object");
104
- const data = payload as Record<string, unknown>;
105
- const correlation = optionalText(options.correlation, "correlation");
106
- const partition = optionalText(options.partition, "partition");
107
- const actor = options.actor ?? { kind: "system" as const, id: `event:${eventKey}` };
108
- actorOf(actor);
109
-
110
- let waits = this.db.subscriptions.asNoTracking().where((s) => s.eventKey.eq(eventKey));
111
- waits = correlation === null ? waits.where((s) => s.correlation.isNull()) : waits.where((s) => s.correlation.isNull().or(s.correlation.eq(correlation)));
112
- if (partition !== null) waits = waits.where((s) => s.partition.eq(partition));
113
- const continued = new Set<string>();
114
- for (const wait of await waits.orderBy((s) => s.id).toList()) {
115
- const moved = await this.engine.inStep(wait.instanceId, async (step) => {
116
- await this.db.subscriptions.asNoTracking().where((s) => s.id.eq(wait.id)).executeDelete();
117
- return await this.engine.eventReceived(step, wait.tokenId, eventKey, data);
118
- });
119
- if (moved === true) continued.add(wait.instanceId);
120
- }
141
+ return await this.delivery.emit(messageOf(eventKey, payload, options));
142
+ }
121
143
 
122
- const started: string[] = [];
123
- const rejected: { processKey: string; issues: readonly FormIssue[] }[] = [];
124
- for (const version of await this.definitions.published()) {
125
- for (const [nodeId, node] of Object.entries(version.document.nodes)) {
126
- if (node.kind !== "eventStart" || node.config?.event !== eventKey) continue;
127
- // An event carries more than a process needs: fields the input does not declare are dropped, not refused.
128
- const { value, issues: all } = await this.validator().validate(inputSpecOf(version.document), data, { purpose: "input", processKey: version.key, partition, language: this.languages.default, actor });
129
- const issues = all.filter((issue) => issue.code !== "unknown");
130
- if (issues.length > 0) {
131
- rejected.push({ processKey: version.key, issues });
132
- continue;
133
- }
134
- started.push(await this.engine.begin(this.engine.cache(version), nodeId, { input: value, partition, businessKey: correlation, startedVia: "event", actor, request: options.request ?? null, event: { key: eventKey, payload: data } }));
135
- }
136
- }
137
- return { started, continued: [...continued], rejected };
144
+ async emitLater(tx: OrmTransaction, eventKey: string, payload: unknown = {}, options: EmitOptions = {}): Promise<void> {
145
+ const message = messageOf(eventKey, payload, options);
146
+ const now = this.engine.now();
147
+ const job = Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "event" as const, partition: message.partition, dueAt: now, payload: message, createdAt: now });
148
+ await tx.use(this.db, (db) => db.jobs.insertIfAbsent(job, { conflictBy: (j) => [j.id] }));
138
149
  }
139
150
 
140
151
  async instances(query: InstanceListQuery = {}): Promise<WorkflowPage<InstanceSummary>> {
141
- if (query.status !== undefined && !STATUSES.has(query.status)) throw new WorkflowError("invalid_input", "status must be running, completed, cancelled or failed");
152
+ if (query.status !== undefined && !STATUSES.has(query.status)) throw new WorkflowError("invalid_input", "status must be pending, running, completed, cancelled, failed or timedOut");
142
153
  const where = query.access === undefined ? "all" : grantsToWhere(query.access);
143
154
  if (where === "none") return { items: [], total: 0 };
144
155
  let source = this.db.instances.asNoTracking();
@@ -148,6 +159,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
148
159
  if (query.processKey !== undefined) source = source.where((i) => i.processKey.eq(query.processKey!));
149
160
  if (query.businessKey !== undefined) source = source.where((i) => i.businessKey.eq(query.businessKey!));
150
161
  if (query.startedById !== undefined) source = source.where((i) => i.startedById.eq(query.startedById!));
162
+ if (query.parentInstanceId !== undefined) source = source.where((i) => i.parentInstanceId.eq(query.parentInstanceId!));
151
163
  const { items, total } = await paginate(source, pageQueryOf(query, { field: "id", dir: "desc" }));
152
164
  return { items: items.map(summaryOf), total };
153
165
  }
@@ -174,6 +186,23 @@ export class WorkflowRuntime extends IWorkflowRuntime {
174
186
  }
175
187
  }
176
188
 
189
+ /** An event as the delivery takes it; what cannot be delivered is refused here. */
190
+ function messageOf(eventKey: string, payload: unknown, options: EmitOptions): EventMessage {
191
+ if (typeof eventKey !== "string" || !EVENT_KEY.test(eventKey)) throw new WorkflowError("invalid_input", "eventKey must look like payments.received");
192
+ if (typeof payload !== "object" || payload === null || Array.isArray(payload)) throw new WorkflowError("invalid_input", "payload must be a JSON object");
193
+ const actor = options.actor ?? { kind: "system" as const, id: `event:${eventKey}` };
194
+ actorOf(actor);
195
+ return {
196
+ eventKey,
197
+ payload: payload as Record<string, unknown>,
198
+ correlation: optionalText(options.correlation, "correlation"),
199
+ partition: optionalText(options.partition, "partition"),
200
+ actor,
201
+ request: options.request ?? null,
202
+ cause: options.cause ?? null,
203
+ };
204
+ }
205
+
177
206
  function notFound(instanceId: string): WorkflowError {
178
207
  return new WorkflowError("not_found", `Instance ${instanceId} does not exist`);
179
208
  }
@@ -200,6 +229,7 @@ function summaryOf(row: WfInstance): InstanceSummary {
200
229
  businessKey: row.businessKey,
201
230
  startedVia: row.startedVia,
202
231
  startedBy: { kind: row.startedByKind, id: row.startedById },
232
+ parentInstanceId: row.parentInstanceId,
203
233
  error: row.error,
204
234
  createdAt: row.createdAt,
205
235
  endedAt: row.endedAt,
@@ -207,7 +237,7 @@ function summaryOf(row: WfInstance): InstanceSummary {
207
237
  }
208
238
 
209
239
  function tokenOf(row: WfToken) {
210
- return { id: row.id, nodeId: row.nodeId, viaFlowId: row.viaFlowId, status: row.status, output: row.output, createdAt: row.createdAt, endedAt: row.endedAt };
240
+ return { id: row.id, nodeId: row.nodeId, viaFlowId: row.viaFlowId, parentTokenId: row.parentTokenId, iteration: row.iteration, status: row.status, output: row.output, createdAt: row.createdAt, endedAt: row.endedAt };
211
241
  }
212
242
 
213
243
  function historyOf(row: WfHistory): HistoryEntry {
@@ -1,5 +1,4 @@
1
1
  import { OnEvent } from "../../../kernel";
2
- import { UniqueViolationError } from "../../../orm";
3
2
  import { WORKFLOW_INSTANCES_DELETED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED, type WorkflowInstancesDeleted, type WorkflowTaskRequested, type WorkflowTokenClosed } from "../../runtime_module/events/Runtime.events";
4
3
  import type { TasksDbContext } from "../model/Tasks.dbContext";
5
4
  import { WfTask } from "../model/WfTask.model";
@@ -12,7 +11,8 @@ export class TaskEvents {
12
11
  @OnEvent(WORKFLOW_TASK_REQUESTED)
13
12
  async requested(event: WorkflowTaskRequested): Promise<void> {
14
13
  const assignee = "role" in event.assignee ? `role:${event.assignee.role}` : `user:${event.assignee.user}`;
15
- this.db.tasks.add(Object.assign(new WfTask(), {
14
+ // Past the change tracker: the scope may go on to update tasks directly, which a context holding one would refuse.
15
+ await this.db.tasks.insertIfAbsent(Object.assign(new WfTask(), {
16
16
  tokenId: event.tokenId,
17
17
  instanceId: event.instanceId,
18
18
  processKey: event.processKey,
@@ -22,12 +22,8 @@ export class TaskEvents {
22
22
  assignee,
23
23
  form: event.form,
24
24
  dueAt: event.dueAt,
25
- }));
26
- try {
27
- await this.db.saveChanges();
28
- } catch (error) {
29
- if (!(error instanceof UniqueViolationError)) throw error;
30
- }
25
+ createdAt: new Date(),
26
+ }), { conflictBy: (t) => [t.tokenId] });
31
27
  }
32
28
 
33
29
  /** The step closed otherwise than by its task: the task is cancelled. */
@@ -93,7 +93,7 @@ export class WorkflowTasks extends IWorkflowTasks {
93
93
  if (error instanceof WorkflowError && error.code === "wrong_status") await this.close(task.tokenId, "cancelled");
94
94
  throw error;
95
95
  }
96
- const saved = instance.nodes[task.nodeId];
96
+ const saved = instance.tokens.find((t) => t.id === task.tokenId)?.output;
97
97
  await this.db.tasks.asNoTracking().where((t) => t.id.eq(task.id)).executeUpdate({
98
98
  status: "completed",
99
99
  completedById: actor.id,
@@ -18,6 +18,8 @@ export type NodeKind =
18
18
  | "userTask"
19
19
  | "serviceTask"
20
20
  | "assign"
21
+ | "loop"
22
+ | "callProcess"
21
23
  | "timerCatch"
22
24
  | "eventWait"
23
25
  | "exclusiveGateway"
@@ -32,6 +34,8 @@ export interface ProcessNode {
32
34
  readonly title: LocalizedText;
33
35
  /** Boundary nodes only: the step the node is attached to. */
34
36
  readonly attachedTo?: string;
37
+ /** The `loop` whose body the node belongs to. */
38
+ readonly parent?: string;
35
39
  readonly config?: Readonly<Record<string, unknown>>;
36
40
  /** The application's data by namespace; the engine does not read it. */
37
41
  readonly extensions?: Readonly<Record<string, unknown>>;
@@ -77,8 +81,18 @@ export interface ProcessLogSettings {
77
81
 
78
82
  /** Settings of a process: they are part of the version. */
79
83
  export interface ProcessSettings {
84
+ /** On whose behalf steps run: who started the instance (the default) or the process's own system actor. */
85
+ readonly runAs?: "starter" | "process";
86
+ /** How long the whole run may take, waits included: an ISO duration. */
87
+ readonly runTimeout?: string;
80
88
  /** The default `timeout` of steps with a Tool: an ISO duration. */
81
89
  readonly stepTimeout?: string;
90
+ /** How many instances of the process run at once; the rest wait as `pending`. */
91
+ readonly maxConcurrent?: number;
92
+ /** A new start with the `businessKey` of an unfinished instance: run as well, do not start, or wait for it. */
93
+ readonly sameKey?: "allow" | "skip" | "queue";
94
+ /** The key of the process to start when an instance fails or times out. */
95
+ readonly errorHandler?: string;
82
96
  readonly log?: ProcessLogSettings;
83
97
  }
84
98