@sanoma-ai/workflows 0.11.16 → 0.11.18

package/src/schedules.ts

@@ -140,23 +140,38 @@ interface TimeMatcher {
   /** The first instant strictly after `date` that matches; one that does not at the end of its search horizon. */
   nextWakeupTime(date: Date | number): Date;
 }
-type TimeMatcherClass = new (pattern: string, timezone?: string) => TimeMatcher;
+export type TimeMatcherClass = new (pattern: string, timezone?: string) => TimeMatcher;
 
 let matcherClass: TimeMatcherClass | undefined;
 
 /**
- * DBOS's `TimeMatcher`, from `dist/src/scheduler/crontab.js` beside its main module: the package's
- * exports leave it out (dbos-sdk 5.2.11), so it is loaded by path, and a test holds it there.
+ * The file DBOS's `TimeMatcher` is in, `dist/src/scheduler/crontab.js` beside its main module, as
+ * `require` resolves the package: its exports leave it out (dbos-sdk 5.2.11), so it is loaded by
+ * path, and a test holds it there.
  */
+export const timeMatcherFile = (require: NodeJS.Require): string =>
+  join(dirname(require.resolve("@dbos-inc/dbos-sdk")), "scheduler", "crontab.js");
+
+/** DBOS's `TimeMatcher`, required from its file (`timeMatcherFile`), or the one `useTimeMatcher` gave. */
 export function timeMatcher(): TimeMatcherClass {
   if (matcherClass) return matcherClass;
   const require = createRequire(import.meta.url);
-  const file = join(dirname(require.resolve("@dbos-inc/dbos-sdk")), "scheduler", "crontab.js");
+  const file = timeMatcherFile(require);
   const loaded = (require(file) as { TimeMatcher?: unknown }).TimeMatcher;
   if (typeof loaded !== "function") throw new Error(`DBOS's cron parser is not in ${file} any more`);
   return (matcherClass = loaded as TimeMatcherClass);
 }
 
+/**
+ * From now on, DBOS's cron parser is `matcher`, where it cannot be required by path: workerd,
+ * which bundles the runtime, and imports it by its file.
+ */
+export function useTimeMatcher(matcher: TimeMatcherClass): void {
+  if (typeof matcher !== "function")
+    throw new Error("DBOS's cron parser (TimeMatcher) is not in its scheduler's crontab.js any more");
+  matcherClass = matcher;
+}
+
 /**
  * When `schedule` (a cron expression read in `timezone`, UTC without one) fires next, strictly
  * after `from`: as DBOS's scheduler finds it. Throws for a schedule that never fires.

package/src/schema.ts

@@ -13,7 +13,15 @@ import { recordSchemaOf } from "./collection.ts";
 import type { ResolvedConfig } from "./config.ts";
 import { jsonSchemaOf } from "./define.ts";
 import { isObject } from "./resource.ts";
-import { CHANGE_MERGE, DATA_VENDOR, EFFECTS, groupNamesOf, type PeopleResource, WORKFLOW_ACTION } from "./shared.ts";
+import {
+  CHANGE_MERGE,
+  DATA_VENDOR,
+  EFFECTS,
+  groupNamesOf,
+  isBatch,
+  type PeopleResource,
+  WORKFLOW_ACTION,
+} from "./shared.ts";
 
 // The Cedar schema a company's policies are validated and decided against: made from the
 // resolved config and the people, in memory for the evaluator, and written as text to
@@ -90,7 +98,8 @@ const WRITES = new Set(["save", "delete"]);
  * - `entity Group enum [...]`, the declared groups, `agents` and `visitors`, so a policy naming another fails
  *   validation; `entity Principal in [Group] { onBehalfOf?: Principal }`; `Collection`;
  *   `Target in [Collection]`; `Workflow`;
- * - an action per operation id, in its effect's group (`effect:money`), on a `Target`, with
+ * - an action per operation id (a collection's `saveMany` excepted: the policy decides each of
+ *   its entries as a `save` or `delete`), in its effect's group (`effect:money`), on a `Target`, with
  *   `context` `{ input, before? }`: `input` from the operation's input schema, `before` the record
  *   as it was for a collection's `save` and `delete`; `sanoma.change.merge` on a `Change`, whose
  *   attributes are a change's facts (`ChangeFacts`), so a rule reads `resource.touches`;
@@ -112,7 +121,9 @@ function buildSchema(
   });
   const actions: CedarSchemaJson[string]["actions"] = { [START]: {} };
   for (const effect of EFFECTS) actions[`effect:${effect}`] = {};
-  for (const op of [...resolved.ops.values()].toSorted((a, b) => a.id.localeCompare(b.id))) {
+  // A collection's batch is no action: the policy decides each of its entries as a save or a delete.
+  const ops = [...resolved.ops.values()].filter((op) => !isBatch(op));
+  for (const op of ops.toSorted((a, b) => a.id.localeCompare(b.id))) {
     const collection =
       op.vendor === DATA_VENDOR && WRITES.has(op.name) ? resolved.collections.get(op.resource) : undefined;
     const before = collection && typeOf(recordSchemaOf(collection));

package/src/secret.ts

@@ -101,14 +101,18 @@ export type Resolved<T> = T extends Secret
 
 /**
  * `value` with each secret marker in it replaced by the stored value: generated and stored first
- * for one with `generate` and none stored. A marker naming nothing stored fails the call, for good.
+ * for one with `generate` and none stored. A marker naming nothing stored fails the call, for good,
+ * before the driver changes anything at the vendor (`secret_not_set`, which the ledger tells).
  */
 export async function resolveSecrets<T>(value: T, secrets: Secrets): Promise<Resolved<T>> {
   const resolve = async (v: unknown): Promise<unknown> => {
     if (isSecret(v)) {
       const stored = v.generate ? await secrets.ensure(v.$secret, generateSecret) : await secrets.get(v.$secret);
       if (stored === undefined) {
-        throw new DriverError(`The secret ${v.$secret} is not set: store it before applying`, { retryable: false });
+        throw new DriverError(
+          `The secret ${v.$secret} has no value: store it (or, where sanoma.config.ts binds it, set what the binding reads), then try again`,
+          { retryable: false, vendorCode: "secret_not_set" },
+        );
       }
       return stored;
     }

package/src/shared.ts

@@ -55,6 +55,14 @@ export const APPLY_WORKFLOW = "apply";
  */
 export const DATA_VENDOR = "data";
 
+/** The one operation of a collection that stands for others: `saveMany`, each entry a `save` or `delete`. */
+export const BATCH = "saveMany";
+export const isBatch = (op: Pick<OpEntry, "vendor" | "name">): boolean =>
+  op.vendor === DATA_VENDOR && op.name === BATCH;
+/** The ids of the operations a batch's entries are: its collection's `save` and `delete`. */
+export const entryOpsOf = (op: Pick<OpEntry, "resource">): string[] =>
+  ["save", "delete"].map((name) => `${DATA_VENDOR}.${op.resource}.${name}`);
+
 /** Every effect an operation may have, each an action group (`effect:<effect>`) of the Cedar schema. */
 export const EFFECTS = ["read", "write", "publish", "send", "money", "access"] as const satisfies readonly Effect[];
 
@@ -68,11 +76,16 @@ export const WORKFLOW_ACTION = "workflow:";
  */
 export function previewRequests(
   workflow: Pick<WorkflowEntry, "name" | "ops">,
-  ops: ReadonlyMap<string, Pick<OpEntry, "effect">>,
+  ops: ReadonlyMap<string, Pick<OpEntry, "effect" | "vendor" | "resource" | "name">>,
 ): Omit<PreviewRequest, "principal">[] {
+  // A batch is asked as its entries, the save and the delete the policy decides: no rule names it.
+  const asked = workflow.ops.flatMap((id) => {
+    const op = ops.get(id);
+    return op && isBatch(op) ? entryOpsOf(op) : [id];
+  });
   return [
     { action: { id: `${WORKFLOW_ACTION}${workflow.name}` } },
-    ...workflow.ops.map((id) => {
+    ...[...new Set(asked)].map((id) => {
       const effect = ops.get(id)?.effect;
       return { action: effect === undefined ? { id } : { id, effect }, inRun: true };
     }),
@@ -203,6 +216,12 @@ type Range<V> = { gt?: V; gte?: V; lt?: V; lte?: V };
 /** How many records a collection's `list` answers: `default` when the query names no `limit`, `max` at most. */
 export const LIST_LIMIT = { default: 100, max: 1000 } as const;
 
+/** How many entries (records and deletes together) a collection's `saveMany` takes at most. */
+export const BATCH_LIMIT = 1000;
+
+/** What a collection's `delete` answers, and `saveMany` for each of its deletes: whether there was a record. */
+export type Deleted = { key: string; deleted: boolean };
+
 /** The kinds of value a field holds: text, a number, true or false, a date (ISO 8601) or a person's id. */
 export const FIELD_TYPES = ["text", "number", "boolean", "date", "person"] as const;
 
@@ -673,10 +692,27 @@ export interface WorkflowFn<I, O> {
 /** An operation a site may call directly (a read, or a collection's write), as the person on the page. */
 export type OpFn<I, O> = (input: I) => Promise<O>;
 
-/** A collection as a site's `api.data.<name>` has it: its four operations (`Saved`, `ListQuery`). */
+/** A collection as a site's `api.data.<name>` has it: its six operations (`Saved`, `ListQuery`, `Deleted`). */
 export interface CollectionApi<R> {
   get: OpFn<{ key: string }, Saved<R> | null>;
   list(query?: ListQuery<R>): Promise<Saved<R>[]>;
+  /** How many records there are, or match `where` (as `list` takes it). */
+  count(query?: Pick<ListQuery<R>, "where">): Promise<{ count: number }>;
   save: OpFn<{ record: R; ifAbsent?: boolean; ifRecord?: Record<string, unknown> }, Saved<R>>;
-  delete: OpFn<{ key: string }, { deleted: boolean }>;
+  /**
+   * Saves and deletes together, all or none, at most `BATCH_LIMIT` entries, each key once: the
+   * records' receipts then the deletes' answers, in the order sent. The policy decides each entry
+   * as its own `save` or `delete`; a deny refuses the batch (`policy_denied`, with the `denied`
+   * keys), a hold holds it whole, and a record an entry's `ifRecord` or `ifAbsent` refuses refuses
+   * it (status 409, `record_changed`) with every such entry in `conflicts: { key, current }[]`.
+   */
+  saveMany: OpFn<
+    {
+      records?: { record: R; ifAbsent?: boolean; ifRecord?: Record<string, unknown> }[];
+      deletes?: { key: string; ifRecord?: Record<string, unknown> }[];
+    },
+    (Saved<R> | Deleted)[]
+  >;
+  /** Deletes the record, or with `ifRecord` only while it still matches (status 409, `record_changed`, otherwise). */
+  delete: OpFn<{ key: string; ifRecord?: Record<string, unknown> }, Deleted>;
 }

package/src/sites.ts

@@ -16,6 +16,8 @@ import {
   BUILT_IN_WORKFLOWS,
   DATA_VENDOR,
   DOMAIN_NAME,
+  entryOpsOf,
+  isBatch,
   LOCALE,
   SITE_NAME,
   siteKey,
@@ -80,7 +82,7 @@ export function readSites(
    */
   const refused = (call: SiteCall, login: string | undefined): string | undefined => {
     const why = `a visitor's call to ${KIND_NAMES[call.kind]} "${call.target}" is refused`;
-    let action: string;
+    let actions: string[];
     let group: string;
     if (call.kind === "workflow") {
       if (BUILT_IN_WORKFLOWS.has(call.target)) return `${why}: a visitor may not start the runtime's own workflows`;
@@ -88,22 +90,24 @@ export function readSites(
       if (call.method !== undefined && call.method !== "start") {
         return `${why}: a visitor reads only the result of a run it started`;
       }
-      [action, group] = [`${WORKFLOW_ACTION}${call.target}`, START];
+      [actions, group] = [[`${WORKFLOW_ACTION}${call.target}`], START];
     } else {
-      action = call.kind === "op" ? call.target : `${DATA_VENDOR}.${call.target}.${call.method}`;
+      const action = call.kind === "op" ? call.target : `${DATA_VENDOR}.${call.target}.${call.method}`;
       const op = ops.get(action);
       if (!op) return undefined;
-      group = `effect:${op.effect}`;
+      // A batch is its entries to the policy: the save and the delete each need a permit.
+      [actions, group] = [isBatch(op) ? entryOpsOf(op) : [action], `effect:${op.effect}`];
     }
     if (!permits) return undefined;
     const [scopes, principal] =
       login === undefined
         ? [[ANONYMOUS], `== Sanoma::Principal::"${ANONYMOUS}"`]
         : [[ANONYMOUS, VISITORS], `in Sanoma::Group::"${VISITORS}"`];
-    if (permits(new Set(scopes), action, group)) return undefined;
+    const missing = actions.filter((action) => !permits(new Set(scopes), action, group));
+    if (!missing.length) return undefined;
     return (
-      `${why}: no permit in policies/ names ${scopes.join(" or ")} for ${action}. ` +
-      `Add: permit (principal ${principal}, action == Sanoma::Action::"${action}", resource);`
+      `${why}: no permit in policies/ names ${scopes.join(" or ")} for ${missing.join(" or ")}. ` +
+      `Add: ${missing.map((a) => `permit (principal ${principal}, action == Sanoma::Action::"${a}", resource);`).join(" ")}`
     );
   };
 

package/src/source.ts

@@ -40,6 +40,20 @@ export interface Source {
   diff?(id: string): Promise<DraftDiff>;
   /** Closes the draft `id`: its checkout removed and its branch deleted, whatever it held; nothing when it is gone. */
   closeDraft?(id: string): Promise<void>;
+  /**
+   * The draft `id`'s branch as a git bundle (`git bundle create`), for a clone elsewhere (an agent
+   * box's) to fetch: its commits since `since`, a commit that clone has, or the whole branch when
+   * `since` is absent or a commit this repository lacks; no bytes when the clone has them all.
+   * The branch's head beside it. A bundle holds commits and the branch's name alone: no remote,
+   * no config, no credential.
+   */
+  bundle?(id: string, opts?: { since?: string }): Promise<{ bytes: Uint8Array; head: string }>;
+  /**
+   * Takes a bundle of the draft `id`'s branch made elsewhere (an agent box's new commits on it):
+   * its commits fetched, then the draft's checkout fast-forwarded to them. Refused unless that is
+   * a fast-forward that leaves what the checkout holds uncommitted in place. The branch's head after.
+   */
+  unbundle?(id: string, bytes: Uint8Array): Promise<{ head: string }>;
   /**
    * `sanoma check` on the draft `id`, as a child in its checkout, one at a time in the process. A
    * check that gives no result (a config that does not load, no install, a timeout) is a result