@sanoma-ai/workflows 0.0.0-stage → 0.1.0

package/src/resources.ts

@@ -0,0 +1,256 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { parsed } from "./ast.ts";
+import { rootOf, type SanomaConfig } from "./config.ts";
+import { type DataFile, type DataFileExport, type DataValue, readDataFile, Reference } from "./datafile.ts";
+import { type Connector, VENDOR } from "./op.ts";
+import type { Span } from "./outline.ts";
+import { type Declared, type Resource, resourceTypesOf } from "./resource.ts";
+import { problemLine } from "./shared.ts";
+
+/** A resource a data file declares, as read from the file without running it. */
+export interface DeclaredResource {
+  /** `<file>#<export>`, the file relative to the config's root, with `/`: `resources/identity/github.ts#website`. */
+  id: string;
+  /** The data file it is declared in, as `id` names it: `resources/identity/github.ts`. */
+  file: string;
+  vendor: string;
+  type: string;
+  /** Its import id: what the type's `find` makes of its fields. */
+  name: string;
+  /** Its `export const` statement, as UTF-16 offsets into the file's text. */
+  span: Span;
+  /** Its fields, as its type checked them: each resource it names as that resource's `name`. */
+  desired: Record<string, unknown>;
+  /**
+   * Where it names another declared resource: the field's dotted path (a list item's with its
+   * index, `teams.0`) to that resource's id.
+   */
+  refs: Record<string, string>;
+}
+
+/** Something wrong in the data files, or in finding them. */
+export interface ResourceProblem {
+  /**
+   * The data file, relative to the config's root, with `/`: `resources/identity/github.ts`.
+   * Absent, with `line` and `column`, when the problem is the config's: it has no root.
+   */
+  file?: string;
+  /** From 1. */
+  line?: number;
+  /** From 1, in UTF-16 code units. */
+  column?: number;
+  message: string;
+}
+
+/** What the data files declare: each resource read without problems, and the problems. */
+export interface DataFiles {
+  /** By file and then in file order, less any with a problem, and any that names one. */
+  resources: DeclaredResource[];
+  /** By file, line and column. */
+  problems: ResourceProblem[];
+}
+
+/**
+ * The resources the config's data files declare, read without importing or running them; throws
+ * one error listing every problem, each at `file:line:column`, for a test or CI to fail on.
+ * `describeConfig` lists the same, with the problems beside them instead.
+ */
+export function readResources(config: SanomaConfig): DeclaredResource[] {
+  const { resources, problems } = readDataFiles(rootOf(config), config.connectors);
+  if (problems.length) {
+    const lines = problems.map((p) => `  ${problemLine(p)}`);
+    throw new Error(`The resources' data files have problems:\n${lines.join("\n")}`);
+  }
+  return resources;
+}
+
+interface FileEntry {
+  /** Relative to the config's root, with `/`. */
+  rel: string;
+  data: DataFile;
+  /** Records a problem at an offset into the file. */
+  problem: (offset: number, message: string) => void;
+}
+
+/**
+ * Reads `resources/` under `root`, the config's directory: each `.ts` file in it but
+ * `*.test.ts`, `*.d.ts` and `node_modules`, parsed with oxc and held to the data-file subset
+ * (`readDataFile`). A constructor import (`@sanoma-ai/connector-github/resources`) is matched to the
+ * connector whose `info.package` it names, never imported; each resource is checked by calling
+ * its type, as running the file would, with each resource it names given as that resource.
+ *
+ * Problems: anything outside the subset, a constructor or data file the config does not know, a
+ * type the connector does not declare, a value the type refuses (a reference where its type
+ * takes none among them), a reference cycle, and two resources of one type with one name.
+ */
+export function readDataFiles(
+  root: string | undefined,
+  connectors: readonly Connector<any, any>[],
+  types: ReadonlyMap<string, Resource> = resourceTypesOf(connectors),
+): DataFiles {
+  const problems: ResourceProblem[] = [];
+  if (root === undefined) {
+    problems.push({
+      message:
+        "The config has no root, so its data files cannot be found: make it with defineConfig, which records its file, or set its `root`",
+    });
+    return { resources: [], problems };
+  }
+
+  const files = new Map<string, FileEntry>();
+  for (const path of dataFilesUnder(join(root, "resources"))) {
+    const rel = relative(root, path).split(sep).join("/");
+    const source = readFileSync(path, "utf8");
+    const { program, problems: syntax, at } = parsed(source, path);
+    const data = readDataFile(program, path, join(root, "resources"));
+    const problem = (offset: number, message: string) => problems.push({ file: rel, ...at(offset), message });
+    for (const p of syntax) problems.push({ file: rel, ...p });
+    for (const p of data.problems) problem(p.start, p.message);
+    files.set(path, { rel, data, problem });
+  }
+
+  // Each connector's constructors entry, `<info.package>/resources`, to its vendor.
+  const entries = new Map<string, string>();
+  for (const connector of connectors) {
+    const { id, info } = connector[VENDOR];
+    if (info?.package) entries.set(`${info.package}/resources`, id);
+  }
+
+  // What each file's names stand for, and every resource read by its id.
+  const vendors = new Map<FileEntry, Map<string, string>>();
+  const named = new Map<FileEntry, Map<string, string>>();
+  const declarations = new Map<string, { file: FileEntry; exp: DataFileExport }>();
+  for (const [path, file] of files) {
+    const fileVendors = new Map<string, string>();
+    const fileNamed = new Map<string, string>();
+    for (const imp of file.data.imports) {
+      if (imp.kind === "constructors") {
+        const vendor = entries.get(imp.source);
+        if (vendor === undefined) {
+          file.problem(
+            imp.start,
+            `"${imp.source}" is not the resources entry of a connector in the config's \`connectors\`: add the connector, and import from its package's \`/resources\``,
+          );
+        } else if (imp.imported !== vendor) {
+          file.problem(
+            imp.start,
+            `"${imp.source}" exports its constructors as ${vendor}: \`import { ${vendor} } from "${imp.source}"\``,
+          );
+        } else {
+          fileVendors.set(imp.local, vendor);
+        }
+        continue;
+      }
+      const other = files.get(resolve(dirname(path), imp.source));
+      if (!other) {
+        file.problem(imp.start, `"${imp.source}" is not a data file under resources/`);
+      } else if (!other.data.declared.includes(imp.imported)) {
+        file.problem(imp.start, `${imp.imported} is not a resource ${other.rel} declares`);
+      } else if (other.data.exports.some((e) => e.name === imp.imported)) {
+        fileNamed.set(imp.local, `${other.rel}#${imp.imported}`);
+      }
+      // Else its value was refused, and reported in its file: a reference to it fails quietly.
+    }
+    for (const exp of file.data.exports) {
+      const id = `${file.rel}#${exp.name}`;
+      fileNamed.set(exp.name, id);
+      declarations.set(id, { file, exp });
+    }
+    vendors.set(file, fileVendors);
+    named.set(file, fileNamed);
+  }
+
+  // Each resource after the ones it names, which it is given as they are declared.
+  const done = new Map<string, { declared: Declared; refs: Record<string, string> } | undefined>();
+  const visiting: string[] = [];
+  const byName = new Map<string, string>();
+  function declare(id: string) {
+    if (done.has(id)) return done.get(id);
+    const { file, exp } = declarations.get(id)!;
+    if (visiting.includes(id)) {
+      file.problem(exp.start, `${id} refers to itself: ${[...visiting.slice(visiting.indexOf(id)), id].join(" → ")}`);
+      return undefined;
+    }
+    visiting.push(id);
+    const result = build(file, exp);
+    visiting.pop();
+    if (result) {
+      const { vendor, type, name } = result.declared;
+      const key = `${vendor}.${type} ${JSON.stringify(name)}`;
+      const first = byName.get(key);
+      if (first === undefined) byName.set(key, id);
+      else {
+        file.problem(
+          exp.start,
+          `${key} is declared twice, also as ${first}: declare each resource once, and import it where it is used`,
+        );
+        done.set(id, undefined);
+        return undefined;
+      }
+    }
+    done.set(id, result);
+    return result;
+  }
+
+  function build(file: FileEntry, exp: DataFileExport) {
+    // An unknown constructors import was reported with the import.
+    const vendor = vendors.get(file)!.get(exp.vendor);
+    if (vendor === undefined) return undefined;
+    const resource = types.get(`${vendor}.${exp.type}`);
+    if (!resource) {
+      const known = [...types.values()].filter((r) => r.vendor === vendor).map((r) => r.type);
+      file.problem(exp.start, `${vendor} has no resource type ${exp.type}: its types are ${known.join(", ")}`);
+      return undefined;
+    }
+    const refs: Record<string, string> = {};
+    let ok = true;
+    // The fields with each name of a resource as that resource, and where each is named.
+    const given = (v: DataValue, at: string): unknown => {
+      if (v instanceof Reference) {
+        // A name that did not resolve was reported where it is bound.
+        const target = named.get(file)!.get(v.name);
+        const declared = target === undefined ? undefined : declare(target)?.declared;
+        if (!declared) ok = false;
+        else refs[at] = target!;
+        return declared;
+      }
+      if (Array.isArray(v)) return v.map((item, i) => given(item, `${at}.${i}`));
+      if (v === null || typeof v !== "object") return v;
+      return Object.fromEntries(Object.entries(v).map(([k, item]) => [k, given(item, at ? `${at}.${k}` : k)]));
+    };
+    const fields = given(exp.desired, "");
+    if (!ok) return undefined;
+    try {
+      // Checked as running the file would: by the resource type, which allows a resource only where its `fields.references` say.
+      return { declared: resource(fields as never), refs };
+    } catch (e) {
+      // One line per problem: zod's own spans lines.
+      file.problem(exp.start, `export const ${exp.name}: ${(e as Error).message.replaceAll(/\s*\n\s*/g, " ")}`);
+      return undefined;
+    }
+  }
+
+  const resources: DeclaredResource[] = [];
+  for (const [id, { file, exp }] of declarations) {
+    const result = declare(id);
+    if (!result) continue;
+    const { vendor, type, name, desired } = result.declared;
+    resources.push({ id, file: file.rel, vendor, type, name, span: [exp.start, exp.end], desired, refs: result.refs });
+  }
+  problems.sort(
+    (a, b) =>
+      (a.file ?? "").localeCompare(b.file ?? "") || (a.line ?? 0) - (b.line ?? 0) || (a.column ?? 0) - (b.column ?? 0),
+  );
+  return { resources, problems };
+}
+
+/** The data files under `dir`, sorted: regular `.ts` files, less tests, declarations and `node_modules`; none when `dir` is not a directory. */
+function dataFilesUnder(dir: string): string[] {
+  if (!statSync(dir, { throwIfNoEntry: false })?.isDirectory()) return [];
+  return readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((d) => d.isFile() && d.name.endsWith(".ts") && !d.name.endsWith(".test.ts") && !d.name.endsWith(".d.ts"))
+    .map((d) => join(d.parentPath, d.name))
+    .filter((path) => !relative(dir, path).split(sep).includes("node_modules"))
+    .toSorted();
+}

package/src/run.ts

@@ -0,0 +1,91 @@
+import type { ApprovalState, Principal, WorkflowDefinition } from "./define.ts";
+import type { Fake } from "./fake.ts";
+import type { LedgerStore } from "./ledger.ts";
+import type { DriverFn, Op } from "./op.ts";
+import type { CallNode } from "./outline.ts";
+import type { Policy } from "./policy.ts";
+import type { Resource } from "./resource.ts";
+import type { Steps } from "./steps.ts";
+
+/** What the DBOS workflow receives: the workflow's input, who started the run, and for a sandbox run its scenario. */
+export interface RunArgs {
+  input: unknown;
+  startedBy: Principal;
+  /** The scenario a sandbox run is seeded from; the run calls the fakes instead of the drivers. */
+  sandbox?: string;
+}
+
+/**
+ * What one `startWorker` call runs with. DBOS registrations are process-wide and outlive a
+ * shutdown, so each run takes the state current when it starts and keeps it: a run left over
+ * from a stopped worker never reads a newer worker's drivers or policy.
+ */
+export interface WorkerState {
+  /** The config's `appName`, recorded on every ledger record. */
+  app: string;
+  /** The operations as the config's connectors declare them, by id. */
+  ops: Map<string, Op>;
+  /** The drivers' functions, by operation id, each guarded by its driver's `env` (`indexDrivers` in config.ts). */
+  drivers: Map<string, DriverFn>;
+  /** The makers of the config's fake vendors, by vendor id: a sandbox run makes its own of each when it is seeded. */
+  fakes: Map<string, () => Fake<any, any>>;
+  /** Where sandbox runs' scenarios are, the resource types their steps may name, and the steps the connectors ship. */
+  scenarios?: URL;
+  types: ReadonlyMap<string, Resource>;
+  steps: readonly Steps[];
+  /** Its `version`, when it has one, is recorded with each of its decisions. */
+  policy: Policy;
+  ledger: LedgerStore;
+  /**
+   * The config's workflows by name, the built-in `drift` among them. A run takes its definition
+   * from here, by the name it was registered under: a process registers each name with DBOS once,
+   * and each worker's config says what it runs. Scenarios name them too.
+   */
+  workflows: Map<string, WorkflowDefinition<any, any>>;
+  /** Each workflow's outline, by name: read once when the worker starts, every run is held to it (`call_not_in_outline`). */
+  outlines: Map<string, WorkflowOutline>;
+  /**
+   * Set when the worker stops, before DBOS shuts down. DBOS abandons a stopped worker's run
+   * functions, which then fail as their next DBOS call finds the database closed. Such a failure,
+   * one with none of our codes, is not recorded: the run recovered on the next worker records
+   * how it really ends (see `isInfrastructureError`).
+   */
+  stopped: boolean;
+}
+
+/** What a run keeps in memory. Rebuilt the same way when DBOS replays the run. */
+export interface Run {
+  id: string;
+  workflow: string;
+  actor: Principal;
+  /** The scenario a sandbox run is seeded from; unset for a live run. */
+  sandbox?: string;
+  /** A sandbox run's own fakes' functions, by operation id, from `seedSandbox`; unset for a live run. */
+  fakeDrivers?: Map<string, DriverFn>;
+  approvals: ApprovalState[];
+  /** The next ledger `seq`. Advanced only outside steps, so a replay counts the same way. */
+  seq: number;
+  /**
+   * The last `ctx` call queued. Each call waits for the one before it, so a run's calls run one
+   * at a time, in program order, even under `Promise.all`. Never rejects.
+   */
+  tail: Promise<unknown>;
+  /**
+   * Set while a `ctx.all` runs, so a second one started before it settles is refused. The
+   * member a call belongs to travels with the call (`currentGroup` in ledger.ts), not here.
+   */
+  inAll: boolean;
+  /** Set when the workflow body has returned or thrown. A call still queued then is refused. */
+  ended: boolean;
+  /** The workflow's outline, which every `ctx` call is placed in (`placeCall`). */
+  outline: WorkflowOutline;
+  state: WorkerState;
+}
+
+/** What `placeCall` holds a run's `ctx` calls to: the file's lines, so a frame's line and column become an offset, and the outline's call nodes. */
+export interface WorkflowOutline {
+  file: string;
+  /** `lineStartsOf` the file's text, `\n` line endings. */
+  lineStarts: readonly number[];
+  calls: readonly CallNode[];
+}

package/src/sandbox.ts

@@ -0,0 +1,157 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { indexDrivers } from "./config.ts";
+import { opIdsOf } from "./define.ts";
+import { SanomaError } from "./errors.ts";
+import type { Fake, ResourceFake } from "./fake.ts";
+import { entry, type LedgerRecord, write } from "./ledger.ts";
+import type { DriverFn } from "./op.ts";
+import type { Run } from "./run.ts";
+import { type Given, loadScenarios, type Scenario } from "./scenario.ts";
+import { errorMessage } from "./shared.ts";
+
+/*
+ * What a worker does for a sandbox run, imported only when it starts one: kept apart from
+ * `scenario.ts`, which the app reads too, because it needs DBOS and the ledger.
+ */
+
+/** True for a fake that holds resources (`ResourceFake`, as `@sanoma-ai/bridge`'s `tfFake` is). */
+const holdsResources = (fake: Fake<unknown>): fake is Fake<unknown> & ResourceFake =>
+  "override" in fake && "put" in fake && "remove" in fake;
+
+/**
+ * The error a sandbox run of the scenario fails with when it seeds a resource of a vendor whose
+ * fake (one of `fakes`, by vendor) holds none, or whose connector attaches no fake; undefined
+ * when every vendor it seeds a resource of has a `ResourceFake`. Pure.
+ */
+export function missingResourceFake(
+  scenario: Pick<Scenario, "name" | "given">,
+  fakes: ReadonlyMap<string, Fake<unknown>>,
+): SanomaError | undefined {
+  const plain = scenario.given.filter((g): g is Extract<Given, { resource: string }> => {
+    if (!("resource" in g)) return false;
+    const fake = fakes.get(g.vendor);
+    return !fake || !holdsResources(fake);
+  });
+  if (plain.length === 0) return undefined;
+  const resources = [...new Set(plain.map((g) => g.resource))];
+  const vendors = [...new Set(plain.map((g) => g.vendor))];
+  const why = vendors.map((v) =>
+    fakes.has(v) ? `${v}'s fake holds no resources (it is not a tfFake)` : `${v}'s connector attaches no fake`,
+  );
+  return new SanomaError(
+    "invalid_input",
+    `Scenario "${scenario.name}" seeds ${resources.join(", ")}, but ${why.join("; ")}`,
+    {
+      scenario: scenario.name,
+      resources,
+    },
+  );
+}
+
+/**
+ * Seeds one resource into the run's own fake of its vendor: put with its fields, or removed.
+ * A seed the fake refuses (a field the provider's shape lacks, say) fails the scenario, naming
+ * the step, as the other seed-time refusals do.
+ */
+export function seedResource(
+  scenario: string,
+  copy: ResourceFake,
+  given: Extract<Given, { resource: string }>,
+): Extract<LedgerRecord, { type: "scenario.seeded" }>["seeds"][number] {
+  const { resource, type, name } = given;
+  try {
+    if ("gone" in given) {
+      copy.remove(type, name);
+      return { resource, name, gone: true };
+    }
+    copy.put(type, name, given.fields);
+    return { resource, name, fields: given.fields };
+  } catch (err) {
+    throw new SanomaError(
+      "invalid_input",
+      `Scenario "${scenario}" cannot seed ${resource} "${name}" ("${given.step}"): ${errorMessage(err)}`,
+      { scenario, step: given.step, resource, name },
+      { cause: err },
+    );
+  }
+}
+
+/**
+ * Seeds a sandbox run of the scenario `name`, from the worker, in one step: reads the scenario,
+ * checks that it runs this workflow, makes the run's own fakes (each vendor's maker, called once
+ * for the run), checks that every operation the workflow uses or the scenario seeds has one and
+ * that every resource it seeds has a fake holding resources, calls each `Given` operation
+ * through them, puts or removes each `Given` resource in them, injects the faults into them,
+ * then puts their functions on the run. The run then calls those only, so sandbox runs share no
+ * state when the makers make a new fake each. The step's checkpoint never stands in for them: a
+ * run whose seeding is replayed from it has none, and fails, since a sandbox run does not
+ * survive a worker restart.
+ */
+export async function seedSandbox(run: Run, name: string): Promise<void> {
+  const { state } = run;
+  let copies: Map<string, DriverFn> | undefined;
+  const { seeds } = await DBOS.runStep(
+    async () => {
+      // Read in the step, so a recovered run never reads a feature file edited or renamed since.
+      const { scenarios, errors } = await loadScenarios(state);
+      const scenario = scenarios.find((s) => s.name === name);
+      if (!scenario) {
+        const why = errors.length ? `; these files did not load: ${errors.map((e) => e.message).join("; ")}` : "";
+        throw new SanomaError("invalid_input", `No scenario named "${name}"${why}`, { scenario: name });
+      }
+      if (scenario.workflow !== run.workflow) {
+        throw new SanomaError("invalid_input", `Scenario "${name}" runs ${scenario.workflow}, not ${run.workflow}`, {
+          scenario: name,
+          workflow: scenario.workflow,
+        });
+      }
+      const fakes = new Map([...state.fakes].map(([vendor, make]) => [vendor, make()]));
+      const drivers = indexDrivers(
+        [...fakes.values()].map((f) => f.driver),
+        state.ops,
+      );
+      const uses = opIdsOf(state.workflows.get(run.workflow)!);
+      const seeding = scenario.given.flatMap((g) => ("op" in g ? [g.op] : []));
+      const missing = [...new Set([...uses, ...seeding])].filter((id) => !drivers.has(id));
+      if (missing.length) {
+        throw new SanomaError(
+          "invalid_input",
+          `A sandbox run of ${run.workflow} has no fake for ${missing.join(", ")}: no fake its connectors attach implements ${missing.length > 1 ? "them" : "it"}`,
+          { scenario: name, missing },
+        );
+      }
+      const plain = missingResourceFake(scenario, fakes);
+      if (plain) throw plain;
+      const seeded: Extract<LedgerRecord, { type: "scenario.seeded" }>["seeds"] = [];
+      for (const [i, given] of scenario.given.entries()) {
+        if ("fault" in given) continue;
+        if ("op" in given) {
+          const call = { idempotencyKey: `${run.id}:seed:${i}`, runId: run.id, opId: given.op, attempt: 1 };
+          const output = await drivers.get(given.op)!(given.input, call);
+          seeded.push({ op: given.op, input: given.input, output });
+          continue;
+        }
+        // Checked above: the vendor's fake holds resources.
+        seeded.push(seedResource(name, fakes.get(given.vendor) as Fake<unknown> & ResourceFake, given));
+      }
+      for (const given of scenario.given) {
+        if ("fault" in given) fakes.get(state.ops.get(given.op)!.vendor)![given.fault](given.op);
+      }
+      copies = drivers;
+      return { seeds: seeded };
+    },
+    { name: "sandbox:seed" },
+  );
+  if (!copies) {
+    // Replayed from its checkpoint (after a worker restart, or in a fork), so the run has no fakes.
+    // The records written before the restart hold the seqs from here on: the failure goes after them.
+    run.seq = Math.max(run.seq, ...(await state.ledger.read(run.id)).map((r) => r.seq + 1));
+    throw new SanomaError(
+      "invalid_input",
+      `Sandbox run ${run.id} was interrupted by a worker restart and the fakes' state is gone; start the scenario again`,
+      { runId: run.id, scenario: name },
+    );
+  }
+  run.fakeDrivers = copies;
+  await write(run, entry(run, { type: "scenario.seeded", scenario: name, seeds }));
+}