bazis 0.132.0 → 0.134.0

package/core/workflow/runtime_module/internal/Schedules.ts

@@ -1,43 +1,76 @@
-import { inputSpecOf, parseCron, validateForm } from "../../../../library/workflow";
+import { inputSpecOf, parseCron, validateForm, type ProcessNode } from "../../../../library/workflow";
+import type { ServiceProvider } from "../../../di";
+import { WorkflowPartitions, type ProcessPartition } from "../../contracts/WorkflowPartitions";
 import type { IWorkflowDefinitions, VersionDetails } from "../../definitions_module/services/IWorkflowDefinitions.service";
+import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import { WfJob } from "../model/WfJob.model";
 import type { WorkflowEngine } from "./WorkflowEngine";
 
 const SCHEDULE_ACTOR = { kind: "system", id: "schedule" } as const;
+const MINUTE = 60_000;
+
+/** The `config` of a `scheduleStart`, as validation lets it through. */
+interface ScheduleConfig {
+  readonly cron: string;
+  readonly timezone?: string;
+  readonly from?: string;
+  readonly until?: string;
+  readonly overlap?: "skip" | "queue" | "parallel";
+  readonly catchUp?: boolean;
+  readonly partitions?: "none" | "all" | readonly string[];
+}
+
+/** One place a node fires in: a partition with its time zone. */
+interface Target {
+  readonly partition: string | null;
+  readonly timezone: string | undefined;
+}
 
 /**
- * Scheduled starts (`scheduleStart`, cron in UTC). Every latest published
- * version with such nodes has one `schedule` job, due at the nearest firing of
- * any of them. `reconcile` keeps the jobs in line with the catalog; `fire`
- * starts the instances of a due job and plans the next firing in the same
- * transaction, so a crash never starts one firing twice. Firings missed while
- * no worker ran are not caught up: the next one is planned from now.
+ * Scheduled starts (`scheduleStart`). Every node of a latest published version
+ * has a `schedule` job per partition it runs in, due at its next firing.
+ * `reconcile` keeps the jobs in line with the catalog and `WorkflowPartitions`;
+ * `fire` starts the instance of a due job and plans the next firing in the same
+ * transaction, so a crash never starts one firing twice. With `catchUp` the next
+ * firing is planned from the one just made, so every missed firing runs;
+ * otherwise from now, and those missed while no worker ran are gone.
  */
 export class Schedules {
   constructor(
     private readonly db: RuntimeDbContext,
     private readonly engine: WorkflowEngine,
     private readonly definitions: IWorkflowDefinitions,
+    private readonly languages: WorkflowLanguages,
+    /** The scope: the application's own `WorkflowPartitions` replaces the default. */
+    private readonly services: ServiceProvider,
   ) {}
 
-  /** Adds jobs for new scheduled versions and drops those of replaced or archived ones. */
+  /** Adds jobs for new scheduled nodes and partitions and drops those no longer wanted. */
   async reconcile(now = this.engine.now()): Promise<void> {
-    const versions = (await this.definitions.published()).filter((version) => scheduleNodes(version).length > 0);
-    const wanted = new Map(versions.map((version) => [version.id, version]));
+    const wanted = new Map<string, { readonly version: VersionDetails; readonly nodeId: string; readonly config: ScheduleConfig; readonly target: Target }>();
+    const invalid: string[] = [];
+    for (const version of await this.definitions.published()) {
+      for (const [nodeId, config] of scheduleNodes(version)) {
+        for (const target of await this.targetsOf(version.key, config)) {
+          if (parseCron(config.cron, target.timezone) === undefined) invalid.push(`${version.key}: time zone ${String(target.timezone)} of partition ${String(target.partition)}`);
+          else wanted.set(keyOf(version.id, nodeId, target.partition), { version, nodeId, config, target });
+        }
+      }
+    }
     const added: WfJob[] = [];
     await this.db.transactionScope(async () => {
       // One reconciler at a time across application instances.
       await this.db.database.querySqlRaw("SELECT pg_advisory_xact_lock(hashtext('bazis.workflow.schedules'))");
       const jobs = await this.db.jobs.asNoTracking().where((j) => j.kind.eq("schedule")).toList();
-      const stale = jobs.filter((job) => job.versionId === null || !wanted.has(job.versionId)).map((job) => job.id);
+      const stale = jobs.filter((job) => !wanted.has(keyOf(job.versionId, job.nodeId, job.partition))).map((job) => job.id);
       if (stale.length > 0) await this.db.jobs.asNoTracking().where((j) => j.id.in(stale)).executeDelete();
-      const planned = new Set(jobs.map((job) => job.versionId));
-      for (const version of versions) {
-        if (planned.has(version.id)) continue;
-        const dueAt = nextFiring(version, now);
+      const planned = new Set(jobs.map((job) => keyOf(job.versionId, job.nodeId, job.partition)));
+      for (const [key, { version, nodeId, config, target }] of wanted) {
+        if (planned.has(key)) continue;
+        const dueAt = nextFiring(config, target, now);
         if (dueAt === undefined) continue;
-        const job = Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "schedule" as const, versionId: version.id, dueAt });
+        const job = Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "schedule" as const, versionId: version.id, nodeId, partition: target.partition, dueAt });
         this.db.jobs.add(job);
         added.push(job);
       }
@@ -45,40 +78,74 @@ export class Schedules {
     });
     // The jobs belong to the worker from now on: this context must not hold them.
     for (const job of added) this.db.detach(job);
+    if (invalid.length > 0) throw new Error(`Scheduled starts are not planned for ${invalid.join("; ")}`);
   }
 
-  /** A `schedule` job is due: start an instance from every node firing at this minute and plan the next firing. */
+  /** A `schedule` job is due: start an instance unless `overlap` says otherwise, and plan the next firing. */
   async fire(job: WfJob): Promise<void> {
     const version = job.versionId === null ? undefined : await this.definitions.versionById(job.versionId);
     const latest = version === undefined ? undefined : (await this.definitions.published()).find((item) => item.id === version.id);
-    if (!latest) {
+    const config = latest === undefined || job.nodeId === null ? undefined : scheduleConfig(latest.document.nodes[job.nodeId]);
+    const target = latest === undefined || config === undefined ? undefined : (await this.targetsOf(latest.key, config)).find((item) => item.partition === job.partition);
+    if (!latest || !config || !target) {
       await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
       return;
     }
-    const due = new Date(Math.floor(job.dueAt.getTime() / 60_000) * 60_000);
+    const due = new Date(Math.floor(job.dueAt.getTime() / MINUTE) * MINUTE);
     const graph = this.engine.cache(latest);
+    const { overlap = "parallel" } = config;
     await this.db.transactionScope(async () => {
-      // Planned from now, not from the missed firing: a stopped worker does not catch up.
       const now = this.engine.now();
-      const next = nextFiring(latest, now > due ? now : due);
+      const next = nextFiring(config, target, config.catchUp === true || now <= due ? due : now);
       if (next === undefined) await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
       else await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeUpdate({ dueAt: next, lockedUntil: null, attempts: 0, lastError: null });
-      for (const [nodeId, cron] of scheduleNodes(latest)) {
-        if (!cron.matches(due)) continue;
-        await this.engine.begin(graph, nodeId, { input: validateForm(inputSpecOf(latest.document), {}).value, partition: null, businessKey: null, startedVia: "schedule", actor: SCHEDULE_ACTOR });
+      let queued = false;
+      if (overlap !== "parallel") {
+        await this.engine.lockProcess(latest.key);
+        if (await this.engine.scheduledLive(latest.key, target.partition) > 0) {
+          if (overlap === "skip") return;
+          queued = true;
+        }
       }
+      await this.engine.begin(graph, job.nodeId!, { input: validateForm(inputSpecOf(latest.document), {}).value, partition: target.partition, businessKey: null, startedVia: "schedule", actor: SCHEDULE_ACTOR, queued, scheduledAt: due });
     });
   }
+
+  /** Where a node runs: `none` without a partition, `all` in every enabled one, a list in those not switched off. */
+  private async targetsOf(processKey: string, config: ScheduleConfig): Promise<readonly Target[]> {
+    const { partitions = "none", timezone } = config;
+    if (partitions === "none") return [{ partition: null, timezone }];
+    const known = await this.partitionsOf(processKey);
+    if (partitions === "all") return known.filter((item) => item.enabled).map((item) => ({ partition: item.partition, timezone: timezone ?? item.timezone }));
+    return partitions.flatMap((partition) => {
+      const entry = known.find((item) => item.partition === partition);
+      return entry?.enabled === false ? [] : [{ partition, timezone: timezone ?? entry?.timezone }];
+    });
+  }
+
+  private async partitionsOf(processKey: string): Promise<readonly ProcessPartition[]> {
+    return await this.services.resolve(WorkflowPartitions).of(processKey, { partition: null, language: this.languages.default, actor: null });
+  }
+}
+
+function keyOf(versionId: string | null, nodeId: string | null, partition: string | null): string {
+  return JSON.stringify([versionId, nodeId, partition]);
+}
+
+function scheduleConfig(node: ProcessNode | undefined): ScheduleConfig | undefined {
+  return node?.kind === "scheduleStart" && typeof node.config?.cron === "string" ? node.config as unknown as ScheduleConfig : undefined;
 }
 
-function scheduleNodes(version: VersionDetails) {
+function scheduleNodes(version: VersionDetails): readonly (readonly [string, ScheduleConfig])[] {
   return Object.entries(version.document.nodes).flatMap(([id, node]) => {
-    const cron = node.kind === "scheduleStart" && typeof node.config?.cron === "string" ? parseCron(node.config.cron) : undefined;
-    return cron === undefined ? [] : [[id, cron] as const];
+    const config = scheduleConfig(node);
+    return config === undefined ? [] : [[id, config] as const];
   });
 }
 
-function nextFiring(version: VersionDetails, after: Date): Date | undefined {
-  const times = scheduleNodes(version).map(([, cron]) => cron.next(after)?.getTime()).filter((time): time is number => time !== undefined);
-  return times.length === 0 ? undefined : new Date(Math.min(...times));
+/** The first firing after `after` inside the period of the node. */
+function nextFiring(config: ScheduleConfig, target: Target, after: Date): Date | undefined {
+  const from = config.from === undefined ? undefined : new Date(Date.parse(config.from) - MINUTE);
+  const next = parseCron(config.cron, target.timezone)?.next(from !== undefined && from > after ? from : after);
+  return next === undefined || (config.until !== undefined && next.getTime() > Date.parse(config.until)) ? undefined : next;
 }

package/core/workflow/runtime_module/internal/TimerStep.ts

@@ -2,7 +2,7 @@ import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfJob } from "../model/WfJob.model";
 import type { WorkflowEngine } from "./WorkflowEngine";
 
-/** One `timer` job: a `timerCatch` step or a boundary timer is due. A closed token drops it. */
+/** One `timer` job: a `timerCatch` step or a boundary timer is due. A closed token drops it. A `loop` job works the same way. */
 export class TimerStep {
   constructor(
     private readonly db: RuntimeDbContext,
@@ -18,4 +18,14 @@ export class TimerStep {
       });
     if (fired === null) await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
   }
+
+  async continueLoop(job: WfJob): Promise<void> {
+    const went = job.instanceId === null || job.tokenId === null
+      ? null
+      : await this.engine.inStep(job.instanceId, async (step) => {
+        await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+        return await this.engine.continueLoop(step, job.tokenId!);
+      });
+    if (went === null) await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+  }
 }

package/core/workflow/runtime_module/internal/ToolStep.ts

@@ -4,13 +4,13 @@ import type { WorkflowToolMetadata } from "../../contracts/types";
 import type { WorkflowTools } from "../../internal/WorkflowTools";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfJob } from "../model/WfJob.model";
-import { dataOf, type WorkflowEngine } from "./WorkflowEngine";
+import { dataOf, runActorOf, type WorkflowEngine } from "./WorkflowEngine";
 
 /**
  * One `tool` job: call the service task's Tool and apply the result. The Tool
  * runs outside a transaction, the result is applied in a step transaction; a
  * token closed meanwhile (a cancel) drops it. The Tool runs on behalf of who
- * started the instance, with the token id as its idempotency key: after a crash
+ * started the instance or of the process (`runAs`), with the token id as its idempotency key: after a crash
  * between the call and the step the call may repeat (TOOLS-001 §7).
  */
 /** How long a claimed job belongs to its worker; if it dies, another one takes the job after that. */
@@ -35,7 +35,7 @@ export class ToolStep {
     const graph = await this.engine.graphOf(instance.versionId);
     const node = graph.document.nodes[token.nodeId];
     const name = String(node?.config?.tool ?? "");
-    const input = resolveInput(node?.config?.input ?? {}, dataOf(instance, this.engine.now()));
+    const input = resolveInput(node?.config?.input ?? {}, dataOf(instance, this.engine.now(), token));
     const timeoutMs = stepTimeoutMs(node?.config?.timeout, graph.document);
     // A step may run longer than the lease: another worker must not take the job and call the Tool again meanwhile.
     if (timeoutMs !== undefined && timeoutMs >= LEASE_MS) {
@@ -46,7 +46,7 @@ export class ToolStep {
       ? { callId: token.id, name, status: "error", error: { code: "TOOL_NOT_FOUND", message: `Tool ${name} is not available to processes` }, metadata: {} } as AgentToolResult
       : await runner.run(name, input, {
         idempotencyKey: token.id,
-        actor: { kind: instance.startedByKind, id: instance.startedById },
+        actor: runActorOf(graph.document, instance),
         metadata: { instanceId: instance.id, processKey: instance.processKey, nodeId: token.nodeId, partition: instance.partition, test: false } satisfies WorkflowToolMetadata,
         signal,
         ...(timeoutMs === undefined ? {} : { timeoutMs }),