@sanoma-ai/workflows 0.9.0 → 0.10.0

package/src/resource.ts

@@ -1,8 +1,11 @@
+import type { ConnectionRef } from "./connection.ts";
 import { z } from "zod";
 import { checkDatabase, type DatabaseSpec } from "./database.ts";
+import { isRunControlError } from "./errors.ts";
 import { checkHost, type HostSpec } from "./host.ts";
 import { type Connector, type OpSpec, RESOURCE, VENDOR } from "./op.ts";
 import { isSanomaSecret, isSecret, type Secret } from "./secret.ts";
+import { errorMessage } from "./shared.ts";
 import { checkWakeup, type WakeupSpec } from "./wakeup.ts";
 
 /** Which fields of a resource are flagged, by dotted path (`pages.html_url`; a list's items have no index). */
@@ -123,6 +126,47 @@ export interface AfterCreate {
   until?: (output: any) => boolean;
 }
 
+/** How long apply waits between calls of an `afterCreate` operation with `until`, and how many calls it makes. */
+export const AFTER_CREATE_SECONDS = 5;
+export const AFTER_CREATE_CALLS = 120;
+/** How long an `afterCreate` operation may be polled, in all, in milliseconds. */
+export const AFTER_CREATE_MS = AFTER_CREATE_SECONDS * AFTER_CREATE_CALLS * 1000;
+
+/** Why an `afterCreate` operation with `until` did not pass: the time it was given, and its last call's error if that failed. */
+export const afterCreateStuck = (op: string, failed: unknown): string =>
+  `${op} did not pass in ${AFTER_CREATE_MS / 60_000} minutes` +
+  (failed === undefined ? "" : `; its last call failed: ${errorMessage(failed)}`);
+
+/**
+ * Calls one `afterCreate` operation for a new object as apply does: with `until`, again every
+ * few seconds until its output passes, a call that fails meanwhile being one that did not pass;
+ * without, once, a failure thrown. Returns why it did not pass, if it did not. Apply inlines the
+ * same loop in its `run`, which may not close over its `ctx`; an operation's own test calls this.
+ */
+export async function callAfterCreate(
+  hook: AfterCreate,
+  made: { id: string; export: string },
+  call: (op: string, input: unknown) => Promise<unknown>,
+  sleep: (seconds: number) => Promise<void>,
+): Promise<string | undefined> {
+  const given = hook.input(made);
+  let output: unknown;
+  let failed: unknown;
+  for (let n = 0; n < AFTER_CREATE_CALLS && (n === 0 || (hook.until && !hook.until(output))); n++) {
+    if (n > 0) await sleep(AFTER_CREATE_SECONDS);
+    try {
+      output = await call(hook.op, given);
+      failed = undefined;
+    } catch (err) {
+      if (isRunControlError(err) || !hook.until) throw err;
+      output = undefined;
+      failed = err;
+    }
+  }
+  if (hook.until && !hook.until(output)) return afterCreateStuck(hook.op, failed);
+  return undefined;
+}
+
 /**
  * Where a declared resource keeps its brand, its type's `<vendor>.<type>`: a symbol, so a field
  * holding a resource is told from data; a registered one (`Symbol.for`), so a copy of this
@@ -130,7 +174,7 @@ export interface AfterCreate {
  */
 export const DECLARED: unique symbol = Symbol.for("sanoma.declared");
 
-/** A resource a data file declares: `github.repository({ name: "sanoma" })`. */
+/** A resource a data file declares: `github.repository({ owner: "acme", name: "sanoma" })`. */
 export interface Declared<Id extends string = string, T = State> {
   readonly [DECLARED]: Id;
   readonly vendor: string;
@@ -142,6 +186,7 @@ export interface Declared<Id extends string = string, T = State> {
    * checked, and what a drift check compares.
    */
   readonly desired: T;
+  readonly connection?: ConnectionRef;
   /**
    * Where it names another resource: the field's dotted path (a list item's with its index,
    * `teams.0`) to that resource's `<vendor>.<type>:<name>`.
@@ -288,7 +333,10 @@ export interface Resource<
       >
     >,
     Readonly<Pick<ResourceSpec<S>, "identity" | "find" | "host" | "wakeup" | "database" | "afterCreate">> {
-  (desired: Declaring<z.input<S>, R>): Declared<Id, z.input<S>>;
+  (
+    desired: Declaring<z.input<S>, R>,
+    options?: { connection?: ConnectionRef<Id extends `${infer V}.${string}` ? V : string> },
+  ): Declared<Id, z.input<S>>;
   /** `read` and `import`, each effect `read`, idempotent, with the id as `target`; for a writable type, the change operations too. */
   readonly ops: ResourceOps<S, W>;
   /** True when apply may change its objects: it has the change operations. */
@@ -306,7 +354,9 @@ export const isObject = (v: unknown): v is State => typeof v === "object" && v !
 /** `path.name`, or `name` at the top: a field's dotted path. */
 export const joinPath = (path: string, name: string) => (path ? `${path}.${name}` : name);
 
-const isDeclared = (v: unknown): v is Declared => isObject(v) && typeof (v as Partial<Declared>)[DECLARED] === "string";
+/** A declared resource: what a constructor returns, made by any copy of this package. */
+export const isDeclared = (v: unknown): v is Declared =>
+  isObject(v) && typeof (v as Partial<Declared>)[DECLARED] === "string";
 
 /** One order for a list compared as a multiset: by each item's JSON. */
 const canonical = (items: unknown[]) =>
@@ -534,8 +584,8 @@ function pathsIn(value: unknown, paths: ReadonlySet<string>, prefix = ""): strin
  *
  * The ledger records a `handle` as `"<handle>"`, never its bytes (the operations' `opaque`).
  *
- * Calling the result declares one resource, for a data file: `repository({ name: "sanoma" })`
- * is a `Declared`, `{ vendor, type, name: "sanoma", desired, refs: {} }`. It refuses fields the
+ * Calling the result declares one resource, for a data file: `repository({ owner: "acme", name: "sanoma" })`
+ * is a `Declared`, `{ vendor, type, name: "acme/sanoma", desired, refs: {} }`. It refuses fields the
  * schema does not have, fields the vendor owns (unless the identity names them), values the
  * schema rejects, and an empty identity. Where `fields.references` allows it, a field may name
  * another declared resource of that type (`repository_id: site`): `desired` holds, and the
@@ -620,7 +670,17 @@ export function defineResource<
   const owned = new Set(fields.vendorOwned.filter((path) => !named.has(path)));
   const references: References = fields.references ?? {};
   const writeOnly = new Set(fields.writeOnly);
-  const declare = (given: Declaring<z.input<S>, R>): Declared<`${V}.${T}`, z.input<S>> => {
+  const declare = (
+    given: Declaring<z.input<S>, R>,
+    options?: { connection?: ConnectionRef },
+  ): Declared<`${V}.${T}`, z.input<S>> => {
+    const connection = options?.connection;
+    if (
+      connection &&
+      (connection.vendor !== vendor || !new RegExp(`^${vendor}/[a-z][a-z0-9-]{0,63}$`).test(connection.$connection))
+    ) {
+      throw new Error(`${what}: select a declared connection of this connector`);
+    }
     const refs: Record<string, string> = {};
     // Where a secret is given, with list items' indexes: the schema does not judge its marker.
     const secrets = new Set<string>();
@@ -680,6 +740,7 @@ export function defineResource<
       ...(name !== undefined && { name }),
       desired,
       refs: Object.freeze(refs),
+      ...(connection && { connection: Object.freeze({ ...connection }) }),
     });
   };
   const resource = Object.assign(declare, {