bazis 0.134.0 → 0.136.0

package/core/workflow/runtime_module/services/IWorkflowRuntime.service.ts

@@ -16,6 +16,11 @@ export interface StartInstance extends WorkflowAuditOptions {
   readonly actor: WorkflowActor;
   /** The language of the request, for the application's validator; `workflow.language` by default. */
   readonly language?: string;
+  /**
+   * A trial run (WORKFLOW-002 §5.4): Tools change nothing, the application hears
+   * nothing, tasks go only to who started it. It lives for a day.
+   */
+  readonly test?: boolean;
 }
 
 /** One element of a mass start. */
@@ -63,8 +68,14 @@ export interface InstanceSummary {
   /** The instance whose `callProcess` started this one. */
   readonly parentInstanceId: string | null;
   readonly error: { readonly node: string; readonly code: string; readonly message: string } | null;
+  /** The step it failed on. */
+  readonly failedNode: string | null;
+  /** A trial run. */
+  readonly test: boolean;
   readonly createdAt: Date;
   readonly endedAt: Date | null;
+  /** How long it took by the engine's clock; `null` until it ends. */
+  readonly durationMs: number | null;
 }
 
 export interface TokenDetails {
@@ -141,6 +152,8 @@ export interface InstanceListQuery extends WorkflowPaging {
   readonly businessKey?: string;
   readonly startedById?: string;
   readonly parentInstanceId?: string;
+  /** Trial runs are hidden unless asked for: `true` gives only them. Children of a named parent are shown as they are. */
+  readonly test?: boolean;
 }
 
 /**

package/core/workflow/runtime_module/services/WorkflowRuntime.service.ts

@@ -55,7 +55,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     if (!start) throw new WorkflowError("wrong_status", `Process ${processKey} has no manual start`);
     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 });
     if (issues.length > 0) throw new WorkflowError("invalid_input", "The process input is invalid", issues);
-    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 });
+    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, ...(options.test === true ? { test: true } : {}) });
     if (skipped) throw new WorkflowError("conflict", `Instance ${id} with this businessKey is not finished`);
     return await this.instance(id);
   }
@@ -160,6 +160,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     if (query.businessKey !== undefined) source = source.where((i) => i.businessKey.eq(query.businessKey!));
     if (query.startedById !== undefined) source = source.where((i) => i.startedById.eq(query.startedById!));
     if (query.parentInstanceId !== undefined) source = source.where((i) => i.parentInstanceId.eq(query.parentInstanceId!));
+    if (query.test !== undefined || query.parentInstanceId === undefined) source = source.where((i) => i.test.eq(query.test === true));
     const { items, total } = await paginate(source, pageQueryOf(query, { field: "id", dir: "desc" }));
     return { items: items.map(summaryOf), total };
   }
@@ -231,11 +232,20 @@ function summaryOf(row: WfInstance): InstanceSummary {
     startedBy: { kind: row.startedByKind, id: row.startedById },
     parentInstanceId: row.parentInstanceId,
     error: row.error,
+    failedNode: row.error === null || row.error.node === "" ? null : row.error.node,
+    test: row.test,
     createdAt: row.createdAt,
     endedAt: row.endedAt,
+    durationMs: durationOf(row),
   };
 }
 
+/** From the start by the engine's clock: `createdAt` is the clock of the database. */
+function durationOf(row: WfInstance): number | null {
+  const startedAt = typeof row.trigger?.at === "string" ? Date.parse(row.trigger.at) : Number.NaN;
+  return row.endedAt === null || Number.isNaN(startedAt) ? null : row.endedAt.getTime() - startedAt;
+}
+
 function tokenOf(row: WfToken) {
   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 };
 }

package/core/workflow/tasks_module/events/TaskEvents.ts

@@ -1,5 +1,5 @@
 import { OnEvent } from "../../../kernel";
-import { WORKFLOW_INSTANCES_DELETED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED, type WorkflowInstancesDeleted, type WorkflowTaskRequested, type WorkflowTokenClosed } from "../../runtime_module/events/Runtime.events";
+import { WORKFLOW_INSTANCES_DELETED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED, WORKFLOW_TRIAL_TASK_REQUESTED, WORKFLOW_TRIAL_TOKEN_CLOSED, type WorkflowInstancesDeleted, type WorkflowTaskRequested, type WorkflowTokenClosed } from "../../runtime_module/events/Runtime.events";
 import type { TasksDbContext } from "../model/Tasks.dbContext";
 import { WfTask } from "../model/WfTask.model";
 
@@ -10,6 +10,16 @@ export class TaskEvents {
   /** A step started waiting for a person: its task. Repeated events of one token make one task. */
   @OnEvent(WORKFLOW_TASK_REQUESTED)
   async requested(event: WorkflowTaskRequested): Promise<void> {
+    await this.add(event, false);
+  }
+
+  /** The task of a trial run: it goes to who started it, and is marked. */
+  @OnEvent(WORKFLOW_TRIAL_TASK_REQUESTED)
+  async trialRequested(event: WorkflowTaskRequested): Promise<void> {
+    await this.add(event, true);
+  }
+
+  private async add(event: WorkflowTaskRequested, test: boolean): Promise<void> {
     const assignee = "role" in event.assignee ? `role:${event.assignee.role}` : `user:${event.assignee.user}`;
     // Past the change tracker: the scope may go on to update tasks directly, which a context holding one would refuse.
     await this.db.tasks.insertIfAbsent(Object.assign(new WfTask(), {
@@ -18,6 +28,7 @@ export class TaskEvents {
       processKey: event.processKey,
       nodeId: event.nodeId,
       partition: event.partition,
+      test,
       title: event.title,
       assignee,
       form: event.form,
@@ -32,6 +43,11 @@ export class TaskEvents {
     await this.db.tasks.asNoTracking().where((t) => t.tokenId.eq(event.tokenId).and(t.status.in(["open", "claimed"]))).executeUpdate({ status: "cancelled" });
   }
 
+  @OnEvent(WORKFLOW_TRIAL_TOKEN_CLOSED)
+  async trialClosed(event: WorkflowTokenClosed): Promise<void> {
+    await this.closed(event);
+  }
+
   /** Retention deleted the instances: their tasks go too. */
   @OnEvent(WORKFLOW_INSTANCES_DELETED)
   async deleted(event: WorkflowInstancesDeleted): Promise<void> {

package/core/workflow/tasks_module/services/IWorkflowTasks.service.ts

@@ -11,6 +11,8 @@ export interface TaskDetails {
   readonly nodeId: string;
   readonly partition: string | null;
   readonly title: LocalizedText;
+  /** A task of a trial run. */
+  readonly test: boolean;
   readonly assignee: string;
   readonly form: FormSpec | null;
   readonly dueAt: Date | null;

package/core/workflow/tasks_module/services/WorkflowTasks.service.ts

@@ -100,7 +100,7 @@ export class WorkflowTasks extends IWorkflowTasks {
       completedAt: this.clock.now(),
       output: typeof saved === "object" && saved !== null && !Array.isArray(saved) ? saved as Record<string, unknown> : null,
     });
-    await this.events.publish(WORKFLOW_TASK_COMPLETED, { taskId: task.id, instanceId: task.instanceId, processKey: task.processKey, nodeId: task.nodeId, partition: task.partition, actor, request: options.request ?? null });
+    if (!task.test) await this.events.publish(WORKFLOW_TASK_COMPLETED, { taskId: task.id, instanceId: task.instanceId, processKey: task.processKey, nodeId: task.nodeId, partition: task.partition, actor, request: options.request ?? null });
     return await this.get(task.id);
   }
 
@@ -157,6 +157,7 @@ function detailsOf(row: WfTask): TaskDetails {
     nodeId: row.nodeId,
     partition: row.partition,
     title: row.title,
+    test: row.test,
     assignee: row.assignee,
     form: row.form,
     dueAt: row.dueAt,

package/library/redaction/index.ts

@@ -52,6 +52,34 @@ export const MIN_REMEMBERED_SECRET_LENGTH = 10;
 const rememberedSecrets = new Set<string>();
 let longestFirst: readonly string[] = [];
 
+/**
+ * A copy of `value` with these exact strings cut out of every text and key: the
+ * secrets of one call. Unlike {@link rememberSecretValue} it knows nothing of the
+ * rest of the process, so it takes values of any length.
+ */
+export function redactValues<T>(value: T, secrets: readonly string[], replacement = DEFAULT_REPLACEMENT): T {
+  const list = secrets.filter((item) => item !== "").sort((left, right) => right.length - left.length);
+  if (list.length === 0) return value;
+  const text = (source: string) => list.reduce((current, secret) => current.split(secret).join(replacement), source);
+  const seen = new WeakMap<object, unknown>();
+  const walk = (item: unknown): unknown => {
+    if (typeof item === "string") return text(item);
+    if (typeof item !== "object" || item === null || item instanceof Date) return item;
+    if (seen.has(item)) return seen.get(item);
+    if (Array.isArray(item)) {
+      const copy: unknown[] = [];
+      seen.set(item, copy);
+      for (const element of item) copy.push(walk(element));
+      return copy;
+    }
+    const copy: Record<string, unknown> = {};
+    seen.set(item, copy);
+    for (const [key, element] of Object.entries(item)) copy[text(key)] = walk(element);
+    return copy;
+  };
+  return walk(value) as T;
+}
+
 /**
  * Remembers a secret value: from now on every redaction removes it wherever it
  * appears, also in plain text without a marker such as `password=`. `Secret`

package/library/workflow/expressions.ts

@@ -267,6 +267,8 @@ export interface ExpressionScope {
   readonly nodes?: ReadonlySet<string>;
   /** Whether it is read inside a loop body: `$item` and `$index` exist only there. */
   readonly loop?: boolean;
+  /** Whether it is the input of a Tool: `$secrets` exists only there, a value must go nowhere else. */
+  readonly secrets?: boolean;
 }
 
 /** What is wrong with an expression, or `null`: its shape, functions, argument types, paths and limits. */
@@ -333,11 +335,16 @@ function literalArgumentProblem(name: ExprFunctionName, args: readonly unknown[]
 
 /** What is wrong with a `$` path, or `null`. */
 export function checkPath(path: unknown, scope: ExpressionScope = {}): string | null {
-  if (typeof path !== "string" || !DATA_PATH.test(path)) return `path ${JSON.stringify(path)} must look like $input.field, $vars.name, $nodes.Node.field, $event.field, $trigger, $run.id, $now, $item.field or $index`;
+  if (typeof path !== "string" || !DATA_PATH.test(path)) return `path ${JSON.stringify(path)} must look like $input.field, $vars.name, $nodes.Node.field, $event.field, $trigger, $run.id, $now, $item.field, $index or $secrets.NAME`;
   const [root, first] = path.split(".");
   if (root === "$now" && first !== undefined) return "$now has no fields";
   if (root === "$index" && first !== undefined) return "$index has no fields";
   if ((root === "$item" || root === "$index") && scope.loop === false) return `path ${path}: ${root} exists only inside a loop body`;
+  if (root === "$secrets") {
+    if (scope.secrets !== true) return `path ${path}: $secrets exists only in the input of a Tool`;
+    if (first === undefined || path.split(".").length !== 2) return "$secrets needs a name: $secrets.NAME";
+    return null;
+  }
   if (root === "$nodes" && first === undefined) return "$nodes needs a node: $nodes.Node.field";
   if (first === undefined) return null;
   if (root === "$input" && scope.input && !scope.input.has(first)) return `path ${path}: the input has no field ${first}`;

package/library/workflow/index.ts

@@ -22,7 +22,7 @@ export {
 } from "./ProcessDocument";
 export { NODE_KINDS, nodeKindOf, ISO_DURATION, MAX_ITERATIONS, MAX_LOOP_PARALLEL, PROCESS_KEY, ISO_MOMENT, type JsonSchema, type NodeKindDefinition, type NodeRole } from "./nodeKinds";
 export { PROCESS_LIMITS, validateProcess, hasErrors, type ProcessIssue, type ProcessIssueCode, type ValidateProcessOptions } from "./validateProcess";
-export { DATA_PATH, DATA_PATHS, isPath, readPath, resolveInput, type InstanceData } from "./paths";
+export { DATA_PATH, DATA_PATHS, isPath, readPath, resolveInput, secretNames, type InstanceData } from "./paths";
 export {
   EXPRESSION_FUNCTIONS,
   EXPRESSION_LIMITS,
@@ -42,6 +42,7 @@ export {
 } from "./expressions";
 export { ExpressionSyntaxError, parseExpression, printExpression } from "./expressionSyntax";
 export { durationMs } from "./duration";
+export { documentReferences, inputReferences, schemaReferenceKinds, type DocumentReference, type InputReference } from "./references";
 export { isTimeZone, parseCron, type CronSchedule } from "./cron";
 export { processToMermaid } from "./mermaid";
 export { PERSONAL_MASK, maskByMapping, maskBySchema, masksPersonal, personalPaths, personalVariables, readsPersonal } from "./masking";

package/library/workflow/paths.ts

@@ -20,10 +20,12 @@ export interface InstanceData {
   readonly item?: unknown;
   /** Inside a loop body: the number of this iteration, from 0. */
   readonly index?: number;
+  /** Only while the input of a Tool is resolved: the values of `$secrets.NAME`. */
+  readonly secrets?: Readonly<Record<string, string>>;
 }
 
 /** `$input.amount`, `$vars.payment.id`, `$nodes.Pay.paymentId`, `$event.record.id`, `$run.partition`, `$now`, `$item.id`, `$index`. */
-export const DATA_PATH = /^\$(input|vars|nodes|event|trigger|run|now|item|index)((\.[A-Za-z_][A-Za-z0-9_]*)*)$/;
+export const DATA_PATH = /^\$(input|vars|nodes|event|trigger|run|now|item|index|secrets)((\.[A-Za-z_][A-Za-z0-9_]*)*)$/;
 
 /** The roots of `$` paths, for a designer. */
 export const DATA_PATHS: readonly { readonly path: string; readonly description: string }[] = Object.freeze([
@@ -36,8 +38,26 @@ export const DATA_PATHS: readonly { readonly path: string; readonly description:
   { path: "$now", description: "The engine's time" },
   { path: "$item", description: "Inside a loop body: the element of this iteration" },
   { path: "$index", description: "Inside a loop body: the number of this iteration, from 0" },
+  { path: "$secrets.<name>", description: "Only in the input of a Tool: the value of a secret, which goes nowhere else" },
 ]);
 
+/** The secrets a Tool input names, in paths and expressions at any depth. */
+export function secretNames(input: unknown): string[] {
+  const names = new Set<string>();
+  const walk = (value: unknown): void => {
+    if (typeof value === "string") {
+      const match = /^\$secrets\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(value);
+      if (match) names.add(match[1]!);
+    } else if (Array.isArray(value)) {
+      value.forEach(walk);
+    } else if (typeof value === "object" && value !== null) {
+      Object.values(value).forEach(walk);
+    }
+  };
+  walk(input);
+  return [...names];
+}
+
 /** `true` if the value is a path to instance data. */
 export function isPath(value: unknown): value is string {
   return typeof value === "string" && DATA_PATH.test(value);

package/library/workflow/references.ts

@@ -0,0 +1,106 @@
+import { isExpressionNode } from "./expressions";
+import { isPath } from "./paths";
+import type { ProcessDocument } from "./ProcessDocument";
+
+/** One reference in a Tool input or a document: what `x-ref` and `x-ref-keys` of a schema mark. */
+export interface InputReference {
+  readonly kind: string;
+  readonly id: string;
+  /** The area it is looked for in: `x-ref-scope`. */
+  readonly within?: string;
+  /** Where in the input: `/values/status`. */
+  readonly path: string;
+}
+
+/** A reference of a document, and whose it is. */
+export interface DocumentReference extends InputReference {
+  readonly node?: string;
+  readonly variable?: string;
+}
+
+type Json = Record<string, unknown>;
+
+function isObject(value: unknown): value is Json {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Whether a value is known only when the step runs. */
+function isComputed(value: unknown): boolean {
+  return isPath(value) || isExpressionNode(value);
+}
+
+function isId(value: unknown): value is string | number {
+  return (typeof value === "string" && value !== "") || typeof value === "number";
+}
+
+/**
+ * The references in a Tool input by the JSON Schema of the input. A value computed
+ * when the step runs is left out: it is checked then. `x-ref-scope` beginning
+ * with `/` is a JSON Pointer to another field of the input; otherwise it is the area
+ * itself. A reference whose area is computed is left out too.
+ */
+export function inputReferences(schema: unknown, input: unknown): InputReference[] {
+  const out: InputReference[] = [];
+  const within = (source: Json): { readonly known: boolean; readonly value?: string } => {
+    const scope = source["x-ref-scope"];
+    if (typeof scope !== "string") return { known: true };
+    if (!scope.startsWith("/")) return { known: true, value: scope };
+    let current: unknown = input;
+    for (const key of scope.slice(1).split("/")) {
+      current = isObject(current) && Object.hasOwn(current, key) ? current[key] : undefined;
+    }
+    return isId(current) && !isComputed(current) ? { known: true, value: String(current) } : { known: false };
+  };
+  const walk = (source: unknown, value: unknown, path: string): void => {
+    if (!isObject(source) || value === undefined || value === null || isComputed(value)) return;
+    const area = within(source);
+    const add = (kind: string, id: string, at: string) => out.push({ kind, id, ...(area.value === undefined ? {} : { within: area.value }), path: at });
+    if (typeof source["x-ref"] === "string" && isId(value) && area.known) add(source["x-ref"], String(value), path);
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => walk(source.items, item, `${path}/${index}`));
+      return;
+    }
+    if (!isObject(value)) return;
+    if (typeof source["x-ref-keys"] === "string" && area.known) for (const key of Object.keys(value)) add(source["x-ref-keys"], key, `${path}/${key}`);
+    if (isObject(source.properties)) {
+      for (const [key, item] of Object.entries(source.properties)) if (Object.hasOwn(value, key)) walk(item, value[key], `${path}/${key}`);
+    }
+  };
+  walk(schema, input, "");
+  return out;
+}
+
+/** The kinds a schema refers to, whatever the values: each must have an owner. */
+export function schemaReferenceKinds(schema: unknown): string[] {
+  const kinds = new Set<string>();
+  const walk = (source: unknown): void => {
+    if (!isObject(source)) return;
+    for (const key of ["x-ref", "x-ref-keys"]) if (typeof source[key] === "string") kinds.add(source[key]);
+    if (isObject(source.properties)) Object.values(source.properties).forEach(walk);
+    walk(source.items);
+  };
+  walk(schema);
+  return [...kinds];
+}
+
+/**
+ * The references a document holds as literals (WORKFLOW-002 §6.3): in the inputs of
+ * its Tools, by their schemas; the defaults of variables of type `ref`; the processes
+ * it calls. `inputSchemaOf` gives the input schema of a Tool, if it is known.
+ */
+export function documentReferences(document: ProcessDocument, inputSchemaOf: (tool: string) => unknown): DocumentReference[] {
+  const out: DocumentReference[] = [];
+  for (const variable of document.variables ?? []) {
+    if (variable.type === "ref" && typeof variable.ref === "string" && isId(variable.default)) {
+      out.push({ kind: variable.ref, id: String(variable.default), path: "/default", variable: variable.name });
+    }
+  }
+  const handler = document.settings?.errorHandler;
+  if (handler !== undefined) out.push({ kind: "workflow.process", id: handler, path: "/settings/errorHandler" });
+  for (const [node, { kind, config }] of Object.entries(document.nodes)) {
+    if (kind === "callProcess" && typeof config?.process === "string") out.push({ kind: "workflow.process", id: config.process, path: "/process", node });
+    if (kind !== "serviceTask" || typeof config?.tool !== "string") continue;
+    for (const reference of inputReferences(inputSchemaOf(config.tool), config.input)) out.push({ ...reference, node });
+  }
+  return out;
+}

package/library/workflow/validateProcess.ts

@@ -33,6 +33,7 @@ export type ProcessIssueCode =
   | "config_invalid"
   | "unknown_tool"
   | "unknown_process"
+  | "broken_ref"
   | "container_invalid"
   | "flow_across_container"
   | "loop_body"
@@ -64,8 +65,6 @@ export type ProcessIssueCode =
 export const PROCESS_LIMITS = Object.freeze({ nodes: 500, flows: 1000, bytes: 1_000_000 });
 
 const ID = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
-/** Paths that come with later stages of WORKFLOW-002: until then they are an error, not a silent literal. */
-const NOT_YET = /^\$secrets(\.|$)/;
 /** Who a boundary error may hang on: the steps that fail by an error of their own. */
 const CAN_FAIL: ReadonlySet<string | undefined> = new Set(["serviceTask", "callProcess", "loop"]);
 
@@ -446,7 +445,7 @@ function configExpressionProblems(kind: string, config: Json, scope: ExpressionS
       if (problem) out.push(`config.assignments[${index}].value: ${problem}`);
     }
   }
-  if ((kind === "serviceTask" || kind === "callProcess") && config.input !== undefined) walkInput(config.input, "config.input", scope, out);
+  if ((kind === "serviceTask" || kind === "callProcess") && config.input !== undefined) walkInput(config.input, "config.input", kind === "serviceTask" ? { ...scope, secrets: true } : scope, out);
   if (kind === "loop" && config.over !== undefined) {
     const problem = checkExpression(config.over, scope);
     if (problem) out.push(`config.over: ${problem}`);
@@ -474,8 +473,10 @@ function configExpressionProblems(kind: string, config: Json, scope: ExpressionS
 
 function walkInput(value: unknown, at: string, scope: ExpressionScope, out: string[]): void {
   if (typeof value === "string") {
-    if (NOT_YET.test(value)) out.push(`${at}: ${value} is not supported`);
-    else if (isPath(value)) {
+    if (value === "$secrets" || value.startsWith("$secrets.")) {
+      const problem = checkPath(value, scope);
+      if (problem) out.push(`${at}: ${problem}`);
+    } else if (isPath(value)) {
       const problem = checkPath(value, scope);
       if (problem) out.push(`${at}: ${problem}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.134.0",
+  "version": "0.136.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",