better-supabase 0.5.0 → 0.6.0

package/dist/workflow-sdk/builder/index.js

@@ -0,0 +1,250 @@
+import { t as WORKFLOW_ATTRIBUTES } from "../../attributes-5dYul0u0.js";
+import { c as topologicalOrder, i as durationMs, l as validateGraph, s as isGraphRecord } from "../../graph-BGyLLFLX.js";
+import { n as executeGraph, t as approvalToken } from "../../executor-C-R4pucm.js";
+import { o as runForKey, r as contextAttributes } from "../../workflow-sdk-C2WJ_G2O.js";
+import { start } from "workflow/api";
+import { getStepMetadata, getWorkflowMetadata } from "workflow";
+//#region src/workflow-sdk/builder/builder.ts
+/** The env flag the Workflow SDK reads before it starts or runs dynamic source. */
+const DYNAMIC_WORKFLOWS_ENV = "WORKFLOW_EXPERIMENTAL_DYNAMIC_WORKFLOWS";
+/** The Workflow SDK's limit on dynamic source. */
+const DYNAMIC_SOURCE_MAX_BYTES = 131072;
+const EXPORT_NAME = "workflow";
+const literal = (value) => JSON.stringify(value ?? null);
+const aliasOf = (node, index) => `n${index}_${node.id.replaceAll(/[^A-Za-z0-9_]/g, "_").slice(0, 40)}`;
+const RUNTIME = `  const results = {};
+  const ran = Object.create(null);
+  const runKey = meta !== null && typeof meta === "object" && typeof meta.runKey === "string" ? meta.runKey : "";
+  function read(path) {
+    const parts = path.split(".");
+    let value = parts[0] === "input" ? input : results;
+    for (let i = 1; i < parts.length; i++) {
+      if (Array.isArray(value)) value = value[Number(parts[i])];
+      else if (value !== null && typeof value === "object") value = value[parts[i]];
+      else return undefined;
+    }
+    return value;
+  }
+  function same(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+  }
+  function test(c) {
+    const actual = read(c.path);
+    switch (c.op) {
+      case "equals": return same(actual, c.value);
+      case "notEquals": return !same(actual, c.value);
+      case "exists": return actual !== undefined && actual !== null;
+      case "truthy": return Boolean(actual);
+      case "greaterThan": return typeof actual === "number" && typeof c.value === "number" && actual > c.value;
+      case "lessThan": return typeof actual === "number" && typeof c.value === "number" && actual < c.value;
+      case "contains": return typeof actual === "string" ? typeof c.value === "string" && actual.includes(c.value) : Array.isArray(actual) && actual.some((item) => same(item, c.value));
+      default: return false;
+    }
+  }
+  function took(source, branch) {
+    return source in ran && (branch === null || String(ran[source]) === branch);
+  }
+`;
+function nodeBody(node, alias) {
+	const id = literal(node.id);
+	switch (node.kind) {
+		case "trigger": return `results[${id}] = input;\n    ran[${id}] = true;`;
+		case "step": return `const output = await steps.${alias ?? ""}({ node: ${id}, step: ${literal(node.step)}, config: ${literal(node.config ?? {})}, input, results: Object.assign({}, results), runKey });
+    results[${id}] = output === undefined ? null : output;
+    ran[${id}] = true;`;
+		case "sleep": return `await sleep(${literal(durationMs(node.config?.["duration"]))});
+    results[${id}] = null;
+    ran[${id}] = true;`;
+		case "approval": return `const payload = await createHook({ token: runKey + ":" + ${id} });
+    results[${id}] = payload === undefined ? null : payload;
+    ran[${id}] = !(payload !== null && typeof payload === "object" && !Array.isArray(payload) && payload.approved === false);`;
+		case "condition": return `const outcome = test(${literal(node.config ?? {})});
+    results[${id}] = outcome;
+    ran[${id}] = outcome;`;
+		default: {
+			const unknown = node.kind;
+			throw new TypeError(`workflow-builder: unknown node kind ${String(unknown)}`);
+		}
+	}
+}
+const guard = (edges) => edges.map((edge) => `took(${literal(edge.source)}, ${edge.branch === void 0 ? "null" : literal(edge.branch)})`).join(" || ");
+/**
+* Compiles a graph to Workflow SDK dynamic source: plain JavaScript that
+* calls each step node through its own alias, sleeps with `sleep` and waits
+* on approvals with `createHook({ token: "<runKey>:<node>" })`. It runs the
+* same way `executeGraph` does. Throws when the graph is invalid or the
+* source is over 128 KiB. Pass it as `compile` to `createBuilder`.
+*/
+function compileGraph(graph) {
+	const errors = validateGraph(graph);
+	if (errors.length > 0) throw new TypeError(`workflow-builder: ${errors.join("; ")}`);
+	const order = topologicalOrder(graph) ?? [];
+	const incoming = /* @__PURE__ */ new Map();
+	for (const edge of graph.edges) incoming.set(edge.target, [...incoming.get(edge.target) ?? [], edge]);
+	const aliases = {};
+	const blocks = order.map((node, index) => {
+		let alias;
+		if (node.kind === "step") {
+			alias = aliasOf(node, index);
+			aliases[alias] = node.step ?? "";
+		}
+		const body = nodeBody(node, alias);
+		const comment = `  // ${node.kind} node ${String(index)}`;
+		if (node.kind === "trigger") return `${comment}\n  {\n    ${body}\n  }`;
+		return `${comment}\n  if (${guard(incoming.get(node.id) ?? [])}) {\n    ${body}\n  }`;
+	});
+	const source = `async function ${EXPORT_NAME}(input, meta) {
+  "use workflow";
+${RUNTIME}
+${blocks.join("\n")}
+  return Object.assign({}, results);
+}
+`;
+	const bytes = new TextEncoder().encode(source).length;
+	if (bytes > 131072) throw new RangeError(`workflow-builder: the compiled source is ${bytes} bytes; dynamic workflows take at most ${DYNAMIC_SOURCE_MAX_BYTES}`);
+	return {
+		engine: "workflow-sdk",
+		format: 1,
+		exportName: EXPORT_NAME,
+		source,
+		aliases
+	};
+}
+/** `value` as a compiled graph, or `undefined` when it isn't one. */
+function compiledGraphOf(value) {
+	if (!isGraphRecord(value) || value["engine"] !== "workflow-sdk" || value["format"] !== 1 || typeof value["source"] !== "string" || typeof value["exportName"] !== "string" || !isGraphRecord(value["aliases"])) return;
+	const aliases = {};
+	for (const [alias, step] of Object.entries(value["aliases"])) {
+		if (typeof step !== "string") return void 0;
+		aliases[alias] = step;
+	}
+	return {
+		engine: "workflow-sdk",
+		format: 1,
+		exportName: value["exportName"],
+		source: value["source"],
+		aliases
+	};
+}
+const dynamicEnabled = () => {
+	const raw = globalThis.process?.env?.[DYNAMIC_WORKFLOWS_ENV];
+	return raw === "1" || raw?.toLowerCase() === "true";
+};
+function contextOf(call) {
+	const actor = call.actor === void 0 ? void 0 : {
+		id: call.actor,
+		kind: "user"
+	};
+	return {
+		...actor === void 0 ? {} : { actor },
+		...call.tenant === void 0 ? {} : { tenant: call.tenant }
+	};
+}
+/**
+* The `start` for `createBuilder`: starts the published version as dynamic
+* source when dynamic workflows are on, and through `executor` otherwise.
+* The source is always compiled from the version's graph; a stored
+* compiled form is never run. Runs carry
+* `bs.tenant`, `bs.actor`, `bs.definition`, `bs.version` and `bs.key`, and
+* a repeated key returns the first run.
+*/
+function graphStarter(options) {
+	return async (call) => {
+		const key = call.idempotencyKey;
+		const existing = await runForKey(key, options.world);
+		if (existing !== void 0) return existing;
+		const graph = call.version.graph ?? {
+			nodes: [],
+			edges: []
+		};
+		const meta = {
+			runKey: key,
+			definition: call.definition.id,
+			version: call.version.version
+		};
+		const startOptions = {
+			attributes: {
+				...contextAttributes(contextOf(call)),
+				[WORKFLOW_ATTRIBUTES.definition]: call.definition.id,
+				[WORKFLOW_ATTRIBUTES.version]: String(call.version.version),
+				[WORKFLOW_ATTRIBUTES.key]: key
+			},
+			...options.world === void 0 ? {} : { world: options.world }
+		};
+		if (options.dynamic ?? dynamicEnabled()) {
+			const compiled = compileGraph(graph);
+			const steps = {};
+			for (const [alias, name] of Object.entries(compiled.aliases)) {
+				const step = options.steps[name];
+				if (step === void 0) throw new Error(`better-supabase: the graph uses step "${name}", which was not passed to graphStarter`);
+				steps[alias] = step;
+			}
+			return (await start(compiled.source, [call.input, meta], {
+				...startOptions,
+				experimental_dynamic: {
+					steps,
+					exportName: compiled.exportName
+				}
+			})).runId;
+		}
+		if (options.executor === void 0) throw new Error(`better-supabase: dynamic workflows are off (${DYNAMIC_WORKFLOWS_ENV}); pass an executor to graphStarter`);
+		return (await start(options.executor, [
+			graph,
+			call.input,
+			meta
+		], startOptions)).runId;
+	};
+}
+/**
+* Wraps a step so it records its node in `workflow_node_runs`: `running`
+* with the attempt when it starts, then `completed` with its output or
+* `failed` with the error. Call the result inside a `"use step"` function;
+* a failed record never fails the step.
+*
+* ```ts
+* const report = nodeRunReporter(serviceBuilder.nodeRuns);
+* export async function sendEmail(call: GraphStepCall) {
+*   "use step";
+*   return report(call, () => email.send(call.config));
+* }
+* ```
+*/
+function nodeRunReporter(sink) {
+	const record = async (input) => {
+		try {
+			await sink.record(input);
+		} catch {}
+	};
+	return async (call, run) => {
+		const runId = getWorkflowMetadata().workflowRunId;
+		const attempt = getStepMetadata().attempt;
+		await record({
+			run: runId,
+			node: call.node,
+			status: "running",
+			attempt
+		});
+		try {
+			const output = await run();
+			await record({
+				run: runId,
+				node: call.node,
+				status: "completed",
+				attempt,
+				output
+			});
+			return output;
+		} catch (cause) {
+			await record({
+				run: runId,
+				node: call.node,
+				status: "failed",
+				attempt,
+				error: cause instanceof Error ? cause.message : String(cause)
+			});
+			throw cause;
+		}
+	};
+}
+//#endregion
+export { DYNAMIC_SOURCE_MAX_BYTES, DYNAMIC_WORKFLOWS_ENV, approvalToken, compileGraph, compiledGraphOf, executeGraph, graphStarter, nodeRunReporter };

package/dist/workflow-sdk/index.d.ts

@@ -0,0 +1,14 @@
+import { a as StartOnEventOptions, c as contextAttributes, d as startFor, f as startOnEvent, i as StartForOptions, l as hookMetadata, m as workflowStarter, n as HookForbiddenError, o as WorkflowFn, p as workflowContext, r as ProtectWebHandlerOptions, s as authorizeHook, t as AuthorizeHookOptions, u as protectWebHandler } from "../workflow-sdk-B3yLD6Br.js";
+//#region src/workflow-sdk/attributes.d.ts
+/** The attributes the Supabase World's status trigger copies into `workflow_runs`. */
+export declare const WORKFLOW_ATTRIBUTES: {
+  readonly tenant: "bs.tenant";
+  readonly actor: "bs.actor";
+  readonly key: "bs.key";
+  /** The builder definition a run started from; its alerts match on it. */
+  readonly definition: "bs.definition";
+  /** The builder version number a run started from. */
+  readonly version: "bs.version";
+};
+//#endregion
+export { type AuthorizeHookOptions, HookForbiddenError, type ProtectWebHandlerOptions, type StartForOptions, type StartOnEventOptions, type WorkflowFn, authorizeHook, contextAttributes, hookMetadata, protectWebHandler, startFor, startOnEvent, workflowContext, workflowStarter };

package/dist/workflow-sdk/index.js

@@ -0,0 +1,3 @@
+import { t as WORKFLOW_ATTRIBUTES } from "../attributes-5dYul0u0.js";
+import { a as protectWebHandler, c as startOnEvent, i as hookMetadata, l as workflowContext, n as authorizeHook, r as contextAttributes, s as startFor, t as HookForbiddenError, u as workflowStarter } from "../workflow-sdk-C2WJ_G2O.js";
+export { HookForbiddenError, WORKFLOW_ATTRIBUTES, authorizeHook, contextAttributes, hookMetadata, protectWebHandler, startFor, startOnEvent, workflowContext, workflowStarter };

package/dist/workflow-sdk/world/index.d.ts

@@ -0,0 +1,107 @@
+import { Pool } from "pg";
+import { World } from "@workflow/world";
+//#region src/sql/modules/workflow-sdk-world-ddl.generated.d.ts
+/** The `@workflow/world-postgres` version the DDL below was generated from. */
+export declare const WORLD_POSTGRES_VERSION = "5.0.2";
+//#endregion
+//#region src/sql/modules/workflow-sdk-world.d.ts
+declare const WORKFLOW_DELIVERY_MODES: readonly ["poll", "pg_net"];
+type WorkflowDeliveryMode = (typeof WORKFLOW_DELIVERY_MODES)[number];
+//#endregion
+//#region src/workflow-sdk/world/world.d.ts
+/**
+ * The `@workflow/world` protocol this World speaks: the package version its
+ * types and queue format come from. Its tables come from
+ * `@workflow/world-postgres` at `WORLD_POSTGRES_VERSION`.
+ */
+export declare const WORKFLOW_WORLD_PROTOCOL = "5.0.2";
+interface SupabaseWorldOptions {
+  /** A Postgres connection string with access to the `workflow` schema and the jobs functions. */
+  readonly connectionString?: string;
+  /** An existing pool instead of `connectionString`; `close()` leaves it open. */
+  readonly pool?: Pool;
+  /**
+   * How messages reach the flow route. `poll` (default) claims them in this
+   * process and posts to the route; `pg_net` leaves delivery to
+   * `dispatch_workflow_deliveries()` on a pg_cron schedule, for serverless
+   * hosts with no long-running process.
+   */
+  readonly delivery?: WorkflowDeliveryMode;
+  /** The flow route the poller posts to. Defaults to `WORKFLOW_FLOW_URL`, then `WORKFLOW_LOCAL_BASE_URL` or `http://localhost:$PORT` plus `/.well-known/workflow/v1/flow`. */
+  readonly flowUrl?: string;
+  /**
+   * The secret deliveries are signed with. Required to accept `pg_net`
+   * deliveries; read from the Vault secret `workflow_delivery_secret` when
+   * unset. A poller with a secret signs too, and the route then refuses
+   * unsigned requests.
+   */
+  readonly deliverySecret?: string;
+  /**
+   * A 32-byte master key (base64 or hex) that each run's AES-256 key is
+   * derived from (HKDF-SHA256). Read from the Vault secret
+   * `workflow_encryption_key` when unset; without one, run data is stored
+   * unencrypted.
+   */
+  readonly encryptionKey?: string;
+  /** The jobs queue the messages wait in (`sql.modules.workflow-sdk-world.options.queue`). */
+  readonly queue?: string;
+  /** The schema of the jobs functions, default `better_supabase`. */
+  readonly schema?: string;
+  /** Deliveries in flight at once in poll mode (default 50). */
+  readonly concurrency?: number;
+  /** Milliseconds between polls of an empty queue (default 250). */
+  readonly pollInterval?: number;
+  /** Seconds a claimed message stays leased; the delivery extends it while it runs (default 60). */
+  readonly lease?: number;
+  /**
+   * Seconds a poll delivery may wait for the flow route before it is
+   * aborted, failed and retried; the lease stops being extended then
+   * (default 300, at least `lease`).
+   */
+  readonly deliveryTimeout?: number;
+  /** The queue namespace, as `WORKFLOW_QUEUE_NAMESPACE`. */
+  readonly namespace?: string;
+}
+/** The flow route: `flowUrl`, `WORKFLOW_FLOW_URL`, or the local server. */
+export declare function resolveFlowUrl(flowUrl?: string): string;
+/** A 32-byte key from base64 or hex. */
+export declare function parseMasterKey(value: string): Uint8Array;
+/** The run's AES-256 key: HKDF-SHA256 of the master key with info `run:<runId>`. */
+export declare function deriveRunKey(master: Uint8Array, runId: string): Promise<Uint8Array>;
+/** `t=<unix>,v1=<hex>` over `<t>.<job>.<body>`. */
+export declare function signDelivery(secret: string, job: string, body: string, now?: number): Promise<string>;
+/** Whether `header` signs `job` and `body` with `secret` within five minutes of `now`. */
+export declare function verifyDelivery(secret: string, header: string | null, job: string, body: string, now?: number): Promise<boolean>;
+/** The World plus the delivery helpers the tests and routes use. */
+type SupabaseWorld = World & {
+  start(): Promise<void>;
+  close(): Promise<void>;
+  /** Claims and delivers the due messages once (poll mode); resolves with how many it delivered. */
+  deliverOnce(): Promise<number>;
+};
+/**
+ * A Workflow SDK World on Supabase Postgres: the run, step, event, hook and
+ * stream tables of `@workflow/world-postgres` (installed by the
+ * `workflow-sdk-world` SQL module), with messages in the jobs module's
+ * queue instead of graphile-worker.
+ *
+ * ```ts
+ * // workflow.config or WORKFLOW_TARGET_WORLD=better-supabase/workflow-sdk/world
+ * export default createSupabaseWorld({ delivery: "pg_net" });
+ * ```
+ */
+export declare function createSupabaseWorld(options?: SupabaseWorldOptions): SupabaseWorld;
+/** The options `createWorld()` reads from the environment. */
+export declare function worldOptionsFromEnv(source?: Readonly<Record<string, string | undefined>>): SupabaseWorldOptions;
+/**
+ * The World from the environment, the factory the Workflow SDK calls for
+ * `WORKFLOW_TARGET_WORLD=better-supabase/workflow-sdk/world`: the connection
+ * from `WORKFLOW_POSTGRES_URL`, `SUPABASE_DB_URL` or `DATABASE_URL`, and
+ * `WORKFLOW_DELIVERY`, `WORKFLOW_FLOW_URL`, `WORKFLOW_DELIVERY_SECRET`,
+ * `WORKFLOW_ENCRYPTION_KEY`, `WORKFLOW_DELIVERY_QUEUE`,
+ * `WORKFLOW_QUEUE_NAMESPACE`, `WORKFLOW_POSTGRES_WORKER_CONCURRENCY` and
+ * `WORKFLOW_POSTGRES_POLL_INTERVAL_MS`.
+ */
+export declare function createWorld(): SupabaseWorld;
+//#endregion
+export { type SupabaseWorld, type SupabaseWorldOptions, type WorkflowDeliveryMode, createWorld as default };