@sanoma-ai/workflows 0.2.0 → 0.4.1

package/src/call-workflow.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { defineWorkflow, type WorkflowDefinition } from "./define.ts";
+import { isDirect } from "./direct.ts";
+import type { Op } from "./op.ts";
+import type { CALL_WORKFLOW } from "./shared.ts";
+
+export { CALL_WORKFLOW } from "./shared.ts";
+
+// The built-in `call` workflow: one operation that may be called directly (`isDirect`), as a run.
+// `SanomaClient.call` starts it, as the person, when the policy holds a direct call for an
+// approval, so the approval reaches the Inbox like any run's. It is a workflow like any other,
+// held to the same lint: the call goes through `ctx`, under the policy, in the ledger.
+
+/** The call workflow's input: the operation's id, and its input. */
+export const CallInput = z.object({ op: z.string(), input: z.unknown() });
+
+/**
+ * The call workflow for a config: it `uses` every operation that may be called directly and has
+ * a driver; `resolveConfig` adds it when there is one. A run calls `input.op` with `input.input`,
+ * and returns its output; inside it the call is made as the person who started the run, so a
+ * collection's save records them as `updatedBy`.
+ */
+export function callWorkflow(
+  ops: ReadonlyMap<string, Op>,
+  drivers: ReadonlyMap<string, unknown>,
+  types: ReadonlyMap<string, unknown>,
+): WorkflowDefinition<readonly Op[], typeof CallInput> {
+  const uses = [...ops.values()]
+    .filter((op) => isDirect(op, types) && drivers.has(op.id))
+    .toSorted((a, b) => a.id.localeCompare(b.id));
+  return defineWorkflow({
+    // The literal, held to the one name: the outline finds a workflow by a string, or a const of its own file.
+    name: "call" satisfies typeof CALL_WORKFLOW,
+    title: "Call an operation",
+    trigger: "manual",
+    input: CallInput,
+    uses,
+    // `ctx` refuses an operation that is not in `uses`: one that may not be called directly, or has no driver.
+    run: async (ctx, input) => {
+      const [vendor = "", resource = "", name = ""] = input.op.split(".");
+      return ctx[vendor]![resource]![name]!(input.input);
+    },
+  });
+}

package/src/call.ts

@@ -3,7 +3,9 @@ import { awaitApproval, type CheckedApproval } from "./approvals.ts";
 import { offsetOf } from "./ast.ts";
 import {
   AllMembers,
+  type ApprovalState,
   type ApprovalRequest,
+  type Principal,
   ApprovalRequestSchema,
   SleepFor,
   type SleepRequest,
@@ -22,14 +24,24 @@ import {
   PolicyDeniedError,
   SanomaError,
 } from "./errors.ts";
+import type { Collection } from "./collection.ts";
 import { currentGroup, entry, skipped, write, writeFailure } from "./ledger.ts";
 import { shown } from "./log.ts";
 import { type CallContext, isOp, type Op } from "./op.ts";
 import { callAt, callName, type CallNode } from "./outline.ts";
-import { DecisionSchema, type PolicyCall, policyOpOf, type RecordedDecision } from "./policy.ts";
-import type { Run, WorkerState } from "./run.ts";
+import { allowAll, type Decision, type Policy, type PolicyCall, policyOpOf, type RecordedDecision } from "./policy.ts";
+import type { Run, StartHold, WorkerState } from "./run.ts";
 import { isChangeOp } from "./resource.ts";
-import { APPLY_WORKFLOW, approverLabel, errorMessage, fitsOp } from "./shared.ts";
+import {
+  APPLY_WORKFLOW,
+  approverLabel,
+  CALL_WORKFLOW,
+  DATA_VENDOR,
+  errorMessage,
+  fitsOp,
+  type Saved,
+  WORKFLOW_ACTION,
+} from "./shared.ts";
 
 /** DBOS took the run from this execution: it cancelled the run, or another process took it over. */
 const takenByDbos = (err: unknown) =>
@@ -51,7 +63,7 @@ export function isInfrastructureError(err: unknown, state: Pick<WorkerState, "st
 }
 
 /** The value as the ledger records it: each of the operation's `opaque` fields as `"<name>"`. */
-function recorded(op: Op, value: unknown): unknown {
+export function recorded(op: Op, value: unknown): unknown {
   if (!op.opaque?.length || typeof value !== "object" || value === null || Array.isArray(value)) return value;
   const out: Record<string, unknown> = { ...value };
   for (const name of op.opaque) if (out[name] !== undefined) out[name] = `<${name}>`;
@@ -252,16 +264,6 @@ function strict<T extends object>(obj: T, path: string, workflow: string): T {
   });
 }
 
-/** Checks a policy's answer, and copies it so nothing else the policy returned is recorded. */
-function checkDecision(decision: unknown, opId: string): RecordedDecision {
-  const parsed = DecisionSchema.safeParse(decision);
-  if (parsed.success) return parsed.data;
-  const why = parsed.error.issues[0]?.message ?? "not a decision";
-  throw new Error(
-    `The policy returned ${shown(decision)} for ${opId}: ${why}; use allow(), deny(reason) or approve(approver)`,
-  );
-}
-
 /** The resource instance the call acts on, from the operation's `target`, when it declares one. */
 function targetOf(op: Op, input: unknown): { target?: string } {
   if (!op.target) return {};
@@ -272,35 +274,138 @@ function targetOf(op: Op, input: unknown): { target?: string } {
   return { target };
 }
 
-/** Asks the policy about one call, and checks its answer. Runs inside a step, so it must have no side effects of its own. */
+/**
+ * Asks the policy about one call, with the record a collection's `save` or
+ * `delete` replaces as `before` (`beforeOf`). Runs inside a step, so it must have no side effects
+ * of its own.
+ */
 export async function decide(run: Run, op: Op, input: unknown): Promise<RecordedDecision> {
-  const call: PolicyCall = {
-    op: policyOpOf(op),
-    effect: op.effect,
-    ...targetOf(op, input),
-    input,
-    actor: run.actor,
-    run: { id: run.id, workflow: run.workflow, approvals: structuredClone(run.approvals) },
+  const seen = { id: run.id, workflow: run.workflow, approvals: structuredClone(run.approvals) };
+  const { policy } = run.state;
+  // Keyed by the call (`seq` was taken for it), so a fake answers each read afresh.
+  const before = await beforeOf(policy, op, input, run.state.collections, (get, key) =>
+    driverOf(run, get)?.(
+      { key },
+      { idempotencyKey: `${run.id}:${run.seq}:before`, runId: run.id, opId: get, attempt: 1, secrets: secretsOf(run) },
+    ),
+  );
+  const call = { ...callOf(op, input, run.actor, seen), ...before };
+  return ask(policy, op.id, () => policy(call), run.state);
+}
+
+/** The run's function for an operation: its own fake's in a sandbox run, never a vendor's; else the driver's. */
+const driverOf = (run: Run, id: string) => (run.sandbox === undefined ? run.state.drivers : run.fakeDrivers)?.get(id);
+
+/** The secrets a run's calls read: its own in a sandbox run, else the stored ones. */
+const secretsOf = (run: Run) => (run.sandbox === undefined ? run.state.secrets : run.fakeSecrets!);
+
+/** One call of `op` as `actor` in `run`, as a policy sees it. */
+const callOf = (op: Op, input: unknown, actor: Principal, run: PolicyCall["run"]): PolicyCall => ({
+  op: policyOpOf(op),
+  effect: op.effect,
+  ...targetOf(op, input),
+  input,
+  actor,
+  run,
+});
+
+/**
+ * For a collection's `save` or `delete`, the record it replaces or removes, read once with the
+ * collection's `get` (`read`): `{ before }` when there is one, else nothing, and nothing read
+ * under `allowAll`, which reads no call. A failed read is named, keeping its error's code.
+ */
+export async function beforeOf(
+  policy: Policy,
+  op: Op,
+  input: unknown,
+  collections: ReadonlyMap<string, Collection>,
+  read: (get: string, key: unknown) => Promise<unknown> | undefined,
+): Promise<{ before?: unknown }> {
+  const collection = op.vendor === DATA_VENDOR ? collections.get(op.resource) : undefined;
+  if (policy === allowAll || !collection || (op.name !== "save" && op.name !== "delete")) return {};
+  const key =
+    op.name === "save"
+      ? (input as { record: Record<string, unknown> }).record[collection.key]
+      : (input as { key: unknown }).key;
+  let saved: Saved | null | undefined;
+  try {
+    saved = (await read(`${DATA_VENDOR}.${op.resource}.get`, key)) as Saved | null | undefined;
+  } catch (err) {
+    if (takenByDbos(err)) throw err;
+    throw keepCode(new Error(`Reading the record ${op.id} replaces failed: ${errorMessage(err)}`, { cause: err }), err);
+  }
+  return saved ? { before: saved.record } : {};
+}
+
+/**
+ * Asks `policy` about one call of `op` as `actor` in `run`: a direct call
+ * (`SanomaClient.call`), with the record a collection's write replaces as `before` (`beforeOf`).
+ */
+export function decideCall(
+  policy: Policy,
+  op: Op,
+  input: unknown,
+  actor: Principal,
+  run: PolicyCall["run"],
+  before: Pick<PolicyCall, "before"> = {},
+): RecordedDecision {
+  const call = { ...callOf(op, input, actor, run), ...before };
+  return ask(policy, op.id, () => policy(call));
+}
+
+/**
+ * Asks the policy whether `actor` may start a run of `workflow` with `input` (`Policy.start`, the
+ * action `workflow:<name>`), as `SanomaClient.start` does before it queues one.
+ */
+export function decideStart(
+  policy: Policy,
+  workflow: string,
+  input: unknown,
+  actor: Principal,
+  approvals: readonly ApprovalState[] = [],
+) {
+  return ask(policy, `${WORKFLOW_ACTION}${workflow}`, () => policy.start(actor, workflow, input, approvals));
+}
+
+/** The approval a start's `approve` answer waits on: whom it asks, its title, and the rules that held it. */
+export function startHoldOf(
+  workflow: string,
+  { approver, title, reasons }: Extract<Decision, { kind: "approve" }>,
+): StartHold {
+  return {
+    approver,
+    title: title ?? `${WORKFLOW_ACTION}${workflow} needs ${approverLabel(approver)}`,
+    ...(reasons && { reasons }),
   };
-  let answer: unknown;
+}
+
+/**
+ * The policy's answer about `id` (`answer`), with its version. A policy that fails is named in
+ * the error, with its error's code, unless the worker is stopping (`state`).
+ */
+function ask(
+  policy: Policy,
+  id: string,
+  answer: () => Decision,
+  state: Pick<WorkerState, "stopped"> = { stopped: false },
+): RecordedDecision {
+  let decision: Decision;
   try {
-    answer = await run.state.policy(call);
+    decision = answer();
   } catch (err) {
     // Named here, so the run's error and the ledger say which call the policy failed on, with
     // the code the policy's error had.
-    if (isInfrastructureError(err, run.state)) throw err;
-    throw keepCode(new Error(`The policy failed deciding ${op.id}: ${errorMessage(err)}`, { cause: err }), err);
+    if (isInfrastructureError(err, state)) throw err;
+    throw keepCode(new Error(`The policy failed deciding ${id}: ${errorMessage(err)}`, { cause: err }), err);
   }
-  const decision = checkDecision(answer, op.id);
-  const policyVersion = run.state.policy.version;
-  return policyVersion === undefined ? decision : { ...decision, policyVersion };
+  return policy.version === undefined ? decision : { ...decision, policyVersion: policy.version };
 }
 
 async function callOp(run: Run, id: string, input: unknown, place: Placed) {
   // The worker's declaration, never the workflow's: its effect, schemas and retry setting.
   const op = run.state.ops.get(id);
   // A sandbox run calls its own fakes, never a vendor.
-  const fn = run.sandbox === undefined ? run.state.drivers.get(id) : run.fakeDrivers?.get(id);
+  const fn = driverOf(run, id);
   if (!op || !fn) {
     throw new Error(
       run.sandbox === undefined
@@ -324,24 +429,27 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
   // The decision is recorded as a step, so a replay reuses it instead of asking a policy
   // that may have changed since. The policy must still be deterministic: a run that fails
   // before the step is recorded asks again.
-  const decision = await DBOS.runStep(() => decide(run, op, parsed), { name: `policy:${op.id}` });
+  const decideStep = () => DBOS.runStep(() => decide(run, op, parsed), { name: `policy:${op.id}` });
+  let decision = await decideStep();
   const logged = recorded(op, parsed);
   const call = { type: "op.called", op: op.id, ...place, effect: op.effect, input: logged, decision } as const;
 
-  if (decision.kind === "deny") {
-    const err = new PolicyDeniedError(op.id, decision.reason);
-    await writeFailure(run, entry(run, { ...call, error: errorInfo(err), durationMs: 0 }, { seq }), err);
-    throw err;
-  }
-  if (decision.kind === "approve") {
+  // Each hold is lifted in turn: once one is approved, the policy is asked again, with it.
+  for (;;) {
+    if (decision.kind === "deny") {
+      const err = new PolicyDeniedError(op.id, decision.reason);
+      await writeFailure(run, entry(run, { ...call, decision, error: errorInfo(err), durationMs: 0 }, { seq }), err);
+      throw err;
+    }
+    if (decision.kind !== "approve") break;
     const title = decision.title ?? `${op.id} needs ${approverLabel(decision.approver)}`;
-    // A hold covers the call it held, and any other operations the policy named.
-    const covers = [...new Set([op.id, ...(decision.covers ?? [])])];
     try {
-      await awaitApproval(run, title, { approver: decision.approver, covers }, place, {
+      // A hold covers the call it held.
+      await awaitApproval(run, title, { approver: decision.approver, covers: [op.id] }, place, {
         op: op.id,
         seq,
         input: logged,
+        reasons: decision.reasons,
       });
     } catch (err) {
       if (errorCode(err) === "approval_rejected") {
@@ -351,6 +459,7 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
       }
       throw err;
     }
+    decision = await decideStep();
   }
 
   const started = Date.now();
@@ -363,13 +472,15 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
       async () => {
         const at = Date.now();
         attempt = DBOS.stepStatus?.currentAttempt ?? 1;
-        const secrets = run.sandbox === undefined ? run.state.secrets : run.fakeSecrets!;
+        const secrets = secretsOf(run);
         const context: CallContext = {
           idempotencyKey: `${run.id}:${seq}`,
           runId: run.id,
           opId: op.id,
           attempt,
           secrets,
+          // A call run is the person's direct call held for an approval: made as them, as it would have been.
+          by: run.workflow === CALL_WORKFLOW ? run.actor.id : `run:${run.id}`,
         };
         // A live driver's `env` is checked here, inside the step, by the guard `indexDrivers` put
         // on its function: the refusal is the call's failure, recorded and never retried.
@@ -456,13 +567,14 @@ async function all(run: Run, list: unknown, node: string): Promise<unknown[]> {
 
 /**
  * Waits, durably, until the time or for the duration the request names, and records when it
- * ends. For a duration that is the time the sleep started plus the duration, as the runtime saw
- * it (`Date.now()`, which adds no DBOS call): a replay may compute another, but the store keeps
+ * ends. For a duration that is the record's `at` plus the duration, one read of the runtime's
+ * clock (`Date.now()`, which adds no DBOS call): a replay may compute another, but the store keeps
  * the first record with the id, so the record says what the first execution waited for.
  */
 async function sleep(run: Run, raw: unknown, at: Placed) {
   const req = checkSleep(raw);
   const seq = run.seq++;
+  const started = Date.now();
   let until: number;
   let ms: number;
   if ("until" in req) {
@@ -475,9 +587,9 @@ async function sleep(run: Run, raw: unknown, at: Placed) {
       (req.minutes ?? 0) * 60_000 +
       (req.hours ?? 0) * 3_600_000 +
       (req.days ?? 0) * 86_400_000;
-    until = Date.now() + ms;
+    until = started + ms;
   }
-  await write(run, entry(run, { type: "sleep.started", ...at, until }, { seq }));
+  await write(run, entry(run, { type: "sleep.started", ...at, until }, { seq, at: started }));
   // A time already past waits not at all, and adds no step. A sandbox run never waits.
   if (ms > 0 && run.sandbox === undefined) await DBOS.sleep(ms);
 }