@protobase/server 0.67.8 → 0.67.10

package/dist/workflows/options.js

@@ -0,0 +1,19 @@
+//#region src/workflows/options.ts
+const schemaPattern = /^[a-z_][a-z0-9_]*$/;
+const secretName = /^[A-Z_][A-Z0-9_]*$/;
+/** The schema of the options, checked. */
+const workflowsSchema = (options = {}) => {
+	const schema = options.schema ?? "workflows";
+	if (!schemaPattern.test(schema)) throw new Error(`Invalid workflows schema "${schema}": use lowercase letters, digits and "_"`);
+	if (schema.length > 63) throw new Error(`Invalid workflows schema "${schema}": at most 63 characters`);
+	return schema;
+};
+/** The secrets workflows may read, by name, from `env`; startup stops on a name that is invalid or unset. */
+const workflowSecrets = (options, env) => Object.fromEntries((options.secrets ?? []).map((name) => {
+	if (!secretName.test(name)) throw new Error(`workflows.secrets: "${name}" is not an environment variable name; use capitals, digits and "_"`);
+	const value = env[name];
+	if (value === void 0 || value === "") throw new Error(`workflows.secrets names ${name}, which is not set`);
+	return [name, value];
+}));
+//#endregion
+export { workflowSecrets, workflowsSchema };

package/dist/workflows/piece-step.js

@@ -0,0 +1,11 @@
+import { StepError } from "@protobase/workflows";
+//#region src/workflows/piece-step.ts
+/**
+* The `app:piece` step, which a definition may name but which runs no piece yet: it fails with `Piece.Error` until the
+* app's plugins give it a handler that sends through the plugin context's guarded fetch.
+*/
+const pieceStep = async () => {
+	throw new StepError("Piece.Error", "No piece runs in this app yet");
+};
+//#endregion
+export { pieceStep };

package/dist/workflows/records-step.js

@@ -0,0 +1,114 @@
+import { HttpProblem } from "../problem.js";
+import { tenantScope } from "../tenant.js";
+import { issueTicket } from "../files/ticket.js";
+import { assistantRecords, toolEntry } from "../assistant/records.js";
+import { runFileRef } from "./run-files.js";
+import { sql } from "kysely";
+import { StepError } from "@protobase/workflows";
+//#region src/workflows/records-step.ts
+const ticketSeconds = 60;
+/**
+* The session a run's records steps act in: the user who saved the version the run pinned, with the roles they hold
+* now in the run's tenant, so a workflow never does more than its last editor may do today.
+*/
+const saverSession = async ({ deps, schema, roles }, runId) => {
+	const { rows } = await sql`select v.saved_by, r.tenant_id from ${sql.id(schema, "runs")} r
+    join ${sql.id(schema, "versions")} v on v.workflow_id = r.workflow_id and v.version = r.version where r.id = ${runId}`.execute(deps().db);
+	const row = rows[0];
+	if (!row?.saved_by) throw new StepError("Records.Refused", "The run's version was not saved by a user, so its steps act on no records");
+	const tenant = row.tenant_id ?? void 0;
+	const held = await roles({
+		id: row.saved_by,
+		...tenant !== void 0 && { tenant }
+	});
+	if (held.length === 0) throw new StepError("Records.Refused", "The workflow's last editor holds no role here any more, so its steps act on no records");
+	return {
+		user: {
+			id: row.saved_by,
+			roles: held
+		},
+		...tenant !== void 0 && {
+			tenant,
+			organization: { id: tenant }
+		}
+	};
+};
+const withTickets = async (deps, session, resource, data, runId) => {
+	const entry = toolEntry(deps, resource);
+	const result = { ...data };
+	for (const [name, value] of Object.entries(data)) {
+		const field = entry.model.fields[name];
+		if (field?.type === "decimal" && typeof value === "number") result[name] = String(value);
+		if (!field?.file || value === null || typeof value !== "object") continue;
+		if (!deps.files) throw new StepError("States.TaskFailed", "The app keeps no files");
+		const ref = runFileRef(runId, value, `data.${name}`);
+		const scope = {
+			tenant: String(tenantScope(entry, session)?.tenantValue ?? ""),
+			resource: entry.name,
+			field: name,
+			user: String(session.user.id)
+		};
+		result[name] = await issueTicket(deps.files.signer, {
+			provider: ref.provider,
+			path: ref.path,
+			name: ref.name,
+			...ref.size !== void 0 && { size: ref.size }
+		}, {}, scope, Math.floor(Date.now() / 1e3) + ticketSeconds);
+	}
+	return result;
+};
+const text = (value, name) => {
+	if (typeof value !== "string" || value === "") throw new StepError("Records.InvalidArguments", `${name} must be text`);
+	return value;
+};
+const keyOf = (value) => {
+	if (typeof value === "string" || typeof value === "number") return value;
+	if (Array.isArray(value) && value.every((part) => typeof part === "string" || typeof part === "number")) return value;
+	throw new StepError("Records.InvalidArguments", "key must be text, a number or a list of them");
+};
+const rowOf = (value, name) => {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new StepError("Records.InvalidArguments", `${name} must be an object of field values`);
+	return value;
+};
+const refusedAs = (error) => {
+	if (error instanceof HttpProblem) throw new StepError("Records.Refused", `${error.status} ${error.title}: ${error.detail}`);
+	throw error;
+};
+const run = async (input, operation, args, { runId }) => {
+	const resource = text(args.resource, "resource");
+	const deps = input.deps();
+	const session = await saverSession(input, runId);
+	const records = assistantRecords(deps, session);
+	if (operation === "get") return (await records.get(resource, keyOf(args.key))).record;
+	if (operation === "update") return (await records.update(resource, keyOf(args.key), await withTickets(deps, session, resource, rowOf(args.data, "data"), runId))).record;
+	if (operation === "list") return { records: (await records.list(resource, {
+		...args.filter !== void 0 && { filter: text(args.filter, "filter") },
+		...args.order_by !== void 0 && { order_by: text(args.order_by, "order_by") },
+		...args.limit !== void 0 && { page_size: Number(args.limit) }
+	})).items.map(({ etag: _, permissions: __, ...record }) => record) };
+	if (Array.isArray(args.data)) {
+		const operations = [];
+		for (const [index, item] of args.data.entries()) operations.push({
+			op: "create",
+			resource,
+			data: await withTickets(deps, session, resource, rowOf(item, `data[${index}]`), runId)
+		});
+		return (await records.batch(operations)).flatMap((result) => result.op === "create" ? [result.record] : []);
+	}
+	return (await records.create(resource, await withTickets(deps, session, resource, rowOf(args.data, "data"), runId))).record;
+};
+/**
+* The `app:records.*` steps: `create`, `update`, `get` and `list` through the app's API as the workflow's last editor,
+* so its access rules, tenant scope, validation and write hooks apply as they do to that user's own requests.
+*/
+const recordsSteps = (input) => {
+	const step = (operation) => (args, context) => run(input, operation, rowOf(args ?? {}, "Arguments"), context).catch(refusedAs);
+	return {
+		"app:records.create": step("create"),
+		"app:records.update": step("update"),
+		"app:records.get": step("get"),
+		"app:records.list": step("list")
+	};
+};
+//#endregion
+export { recordsSteps };

package/dist/workflows/run-files.js

@@ -0,0 +1,70 @@
+import { cleanName, formatUri, parseUri } from "../files/uri.js";
+import { readLimited } from "../webhooks/table/read-limited.js";
+import { StepError } from "@protobase/workflows";
+//#region src/workflows/run-files.ts
+/** The most bytes of one file a workflow stores or reads, as the `http` step reads at most. */
+const runFileLimit = 10485760;
+/** The provider a run's files are kept in. */
+const provider = "private";
+const prefix = (runId) => `workflows/${runId}/`;
+const runStore = (files) => {
+	const kept = files?.providers[provider];
+	if (!kept) throw new StepError("States.TaskFailed", `The app keeps no files: workflows store theirs with the "${provider}" file provider`);
+	if (kept.public) throw new StepError("States.TaskFailed", `The "${provider}" file provider is public, so workflows keep no files in it: anyone could read them`);
+	return kept.store;
+};
+/**
+* Stores bytes a step of the run got, such as an answer's body, as a file of the run's own, under a name of the
+* runner's choosing: no part of its path comes from the workflow or the answer.
+*/
+const storeRunFile = async (files, runId, bytes, name, type) => {
+	const store = runStore(files);
+	const path = `${prefix(runId)}${crypto.randomUUID()}`;
+	await store.put(path, new Blob([bytes]).stream());
+	const clean = cleanName(name);
+	return {
+		uri: formatUri({
+			provider,
+			path,
+			name: clean,
+			size: bytes.length
+		}),
+		name: clean,
+		type,
+		size: bytes.length
+	};
+};
+/** Whether a value has a file value's shape, all four fields; an object with only a `uri` is other data. */
+const isFileValue = (value) => {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const { uri, name, type, size } = value;
+	return typeof uri === "string" && typeof name === "string" && typeof type === "string" && typeof size === "number";
+};
+/**
+* The file a file value names, when it is one the run stored itself; a step fails on any other, so a workflow cannot
+* mail, send or attach a file of the app's by naming its URI.
+*/
+const runFileRef = (runId, value, field) => {
+	const ref = isFileValue(value) ? parseUri(value.uri) : void 0;
+	if (!ref) throw new StepError("States.TaskFailed", `${field} is not a file value ({ uri, name, type, size })`);
+	if (ref.provider !== provider || !ref.path.startsWith(prefix(runId))) throw new StepError("States.TaskFailed", `${field} is not a file this run stored; a step takes only the files of its own run`);
+	const type = value.type;
+	return {
+		...ref,
+		...typeof type === "string" && { type }
+	};
+};
+/** The bytes of a file the run stored itself, read up to `runFileLimit`. */
+const readRunFile = async (files, runId, value, field) => {
+	const ref = runFileRef(runId, value, field);
+	const stream = await runStore(files).read(ref.path);
+	if (!stream) throw new StepError("States.TaskFailed", `${field} names a file that is gone`);
+	const bytes = await readLimited(new Response(stream), 10485761);
+	if (bytes.length > 10485760) throw new StepError("States.TaskFailed", `${field} is larger than ${runFileLimit / 1024 / 1024} MiB`);
+	return {
+		ref,
+		bytes
+	};
+};
+//#endregion
+export { isFileValue, readRunFile, runFileLimit, runFileRef, storeRunFile };

package/dist/workflows/save-hook.js

@@ -0,0 +1,20 @@
+import { badRequest } from "../problem.js";
+import { sql } from "kysely";
+import { checkDefinition, problemText } from "@protobase/workflows";
+//#region src/workflows/save-hook.ts
+/**
+* Checks a workflow's definition on every save that changes it, against the language's schema and the named-reads
+* profile, with the step types the app has, and keeps it as the version the table's trigger numbered, saved by the
+* caller. A refusal is a 400 problem naming each state and field, also listed as `problems`; the write rolls back.
+*/
+const workflowSaveHook = (schema, stepTypes) => async (event, trx) => {
+	if (event.resource.name !== "workflows" || !event.after) return;
+	if (event.operation !== "create" && event.operation !== "update") return;
+	if (event.operation === "update" && event.after.version === event.before?.version) return;
+	const problems = checkDefinition(event.after.definition, { resources: stepTypes });
+	if (problems.length > 0) throw badRequest("invalid-workflow", `The workflow cannot be saved: ${problems.map(problemText).join("; ")}`, { problems });
+	await sql`insert into ${sql.id(schema, "versions")} (workflow_id, version, definition, saved_by, tenant_id)
+    select w.id, w.version, w.definition, ${String(event.user.id)}, w.tenant_id from ${sql.id(schema, "workflows")} w where w.id = ${String(event.after.id)}`.execute(trx);
+};
+//#endregion
+export { workflowSaveHook };

package/dist/workflows/schema-sql.js

@@ -0,0 +1,147 @@
+import { quoteIdent } from "../changes/capture-sql.js";
+/** The comment the schema's function carries, which the startup check reads. */
+const workflowsComment = `Protobase workflows 3`;
+const commentVersion = (comment) => {
+	const match = comment?.match(/^Protobase workflows (\d+)$/);
+	return match ? Number(match[1]) : void 0;
+};
+const ms = (from, to) => `(floor(extract(epoch from ("${to}" - "${from}")) * 1000)::bigint)`;
+/**
+* The workflows, each version of their definitions as it was saved, their runs and every step of a run. A run pins
+* the version it started on, and a run with a key is started once per workflow and key; a step is saved once per scope and number, which is what keeps a repeated segment from
+* saving it twice.
+*/
+const tablesSql = (schema) => {
+	const s = quoteIdent(schema);
+	return `create table if not exists ${s}."workflows" (
+  "id" uuid primary key default gen_random_uuid(),
+  "name" text not null,
+  "description" text,
+  "definition" jsonb not null,
+  "version" integer,
+  "tenant_id" text,
+  "created_at" timestamptz not null default now(),
+  "updated_at" timestamptz not null default now()
+);
+
+create table if not exists ${s}."versions" (
+  "workflow_id" uuid not null references ${s}."workflows" ("id") on delete cascade,
+  "version" integer not null,
+  "definition" jsonb not null,
+  "saved_by" text,
+  "tenant_id" text,
+  "saved_at" timestamptz not null default now(),
+  primary key ("workflow_id", "version")
+);
+
+create table if not exists ${s}."runs" (
+  "id" uuid primary key default gen_random_uuid(),
+  "workflow_id" uuid not null references ${s}."workflows" ("id") on delete cascade,
+  "version" integer,
+  "input" jsonb,
+  "key" text,
+  "status" text not null default 'queued' check ("status" in ('queued', 'running', 'waiting', 'succeeded', 'failed')),
+  "output" jsonb,
+  "error" text,
+  "cause" text,
+  "resume_at" timestamptz,
+  "started_by" text,
+  "tenant_id" text,
+  "created_at" timestamptz not null default now(),
+  "finished_at" timestamptz,
+  "duration_ms" bigint generated always as (${ms("created_at", "finished_at")}) stored,
+  foreign key ("workflow_id", "version") references ${s}."versions" ("workflow_id", "version")
+);
+
+create table if not exists ${s}."steps" (
+  "id" bigint generated always as identity primary key,
+  "run_id" uuid not null references ${s}."runs" ("id") on delete cascade,
+  "tenant_id" text,
+  "scope" text not null,
+  "seq" integer not null,
+  "state" text not null,
+  "type" text not null,
+  "status" text not null check ("status" in ('succeeded', 'retrying', 'caught', 'failed')),
+  "attempt" integer not null,
+  "input" jsonb,
+  "output" jsonb,
+  "assigned" jsonb,
+  "next" text,
+  "resume_at" timestamptz,
+  "error" text,
+  "cause" text,
+  "logs" jsonb not null,
+  "started_at" timestamptz not null,
+  "finished_at" timestamptz not null,
+  "duration_ms" bigint generated always as (${ms("started_at", "finished_at")}) stored,
+  unique ("run_id", "scope", "seq")
+)`;
+};
+/** An index for each filter and sort the API takes, and pg_trgm ones for the search over names. */
+const indexesSql = (schema) => {
+	const s = quoteIdent(schema);
+	return `create extension if not exists pg_trgm;
+create index if not exists "workflows_tenant" on ${s}."workflows" ("tenant_id");
+create index if not exists "workflows_name" on ${s}."workflows" ("name");
+create index if not exists "workflows_updated_at" on ${s}."workflows" ("updated_at");
+create index if not exists "workflows_name_search" on ${s}."workflows" using gin ("name" gin_trgm_ops);
+create index if not exists "versions_tenant" on ${s}."versions" ("tenant_id");
+alter table ${s}."runs" add column if not exists "key" text;
+create unique index if not exists "runs_key" on ${s}."runs" ("workflow_id", "key");
+create index if not exists "runs_workflow" on ${s}."runs" ("workflow_id", "created_at");
+create index if not exists "runs_tenant" on ${s}."runs" ("tenant_id");
+create index if not exists "runs_status" on ${s}."runs" ("status");
+create index if not exists "runs_created_at" on ${s}."runs" ("created_at");
+create index if not exists "steps_tenant" on ${s}."steps" ("tenant_id");
+create index if not exists "steps_status" on ${s}."steps" ("status");
+create index if not exists "steps_state" on ${s}."steps" ("state")`;
+};
+/** The triggers `functionsSql` makes, which the startup check finds on their tables. */
+const workflowsTriggers = ["workflow_version", "run_version"];
+/**
+* A workflow numbers its next version as a save changes its definition, in the row the write returns, so its ETag is
+* the saved row's; the save hook keeps that version's definition and who saved it. A run takes its workflow's current
+* version as it is created, and refuses a workflow of another tenant as one that is not there, and one that has no
+* saved version.
+*/
+const functionsSql = (schema) => {
+	const s = quoteIdent(schema);
+	return `create or replace function ${s}."workflow_version"() returns trigger
+language plpgsql as $$
+begin
+  if tg_op = 'INSERT' then
+    new.version := 1;
+    return new;
+  end if;
+  -- The write holds the row, so a save in another transaction numbers its version after this one.
+  new.version := case when new.definition is distinct from old.definition then coalesce(old.version, 0) + 1 else old.version end;
+  new.updated_at := now();
+  return new;
+end
+$$;
+drop trigger if exists "workflow_version" on ${s}."workflows";
+create trigger "workflow_version" before insert or update on ${s}."workflows" for each row execute function ${s}."workflow_version"();
+
+create or replace function ${s}."run_version"() returns trigger
+language plpgsql as $$
+declare
+  found record;
+begin
+  select w.id, w.version, w.tenant_id into found from ${s}."workflows" w where w.id = new.workflow_id;
+  -- Another tenant's workflow is refused as one that is not there, so a start tells nothing of other tenants.
+  if found.id is null or new.tenant_id is distinct from found.tenant_id then
+    raise exception 'There is no workflow % here', new.workflow_id using errcode = '23503';
+  end if;
+  if found.version is null then
+    raise exception 'Workflow % has no saved version', new.workflow_id using errcode = '23503';
+  end if;
+  new.version := found.version;
+  return new;
+end
+$$;
+comment on function ${s}."run_version"() is '${workflowsComment}';
+drop trigger if exists "run_version" on ${s}."runs";
+create trigger "run_version" before insert on ${s}."runs" for each row execute function ${s}."run_version"()`;
+};
+//#endregion
+export { commentVersion, functionsSql, indexesSql, tablesSql, workflowsComment, workflowsTriggers };

package/dist/workflows/schema.d.ts

@@ -0,0 +1,11 @@
+import { WorkflowsOptions } from "./options.js";
+import { Db } from "@protobase/query";
+//#region src/workflows/schema.d.ts
+/**
+ * The SQL that brings the `workflows` schema to what `workflows` needs: its tables, indexes and the triggers that number a
+ * workflow's versions and pin a run's; `undefined` when current. Tables are never dropped.
+ */
+export declare const workflowsMigration: (db: Db, options?: WorkflowsOptions) => Promise<string | undefined>;
+/** Refuses to go on while the `workflows` schema lacks what `workflows` needs; the project's migrations add it. */
+export declare const checkWorkflowsSchema: (db: Db, options?: WorkflowsOptions) => Promise<void>;
+//#endregion

package/dist/workflows/schema.js

@@ -0,0 +1,41 @@
+import { quoteIdent } from "../changes/capture-sql.js";
+import { migrationCommand } from "../changes/capture-schema.js";
+import { workflowsSchema } from "./options.js";
+import { commentVersion, functionsSql, indexesSql, tablesSql, workflowsTriggers } from "./schema-sql.js";
+import { sql } from "kysely";
+//#region src/workflows/schema.ts
+const readWorkflowsSchema = async (db, schema) => {
+	const steps = `${quoteIdent(schema)}."steps"`;
+	const { rows } = await sql`select to_regclass(${steps}) is not null as found,
+    (select obj_description(p.oid, 'pg_proc') from pg_proc p join pg_namespace n on n.oid = p.pronamespace where n.nspname = ${schema} and p.proname = 'run_version') as comment,
+    (select count(*)::int from pg_trigger t join pg_class c on c.oid = t.tgrelid join pg_namespace n on n.oid = c.relnamespace
+      where n.nspname = ${schema} and not t.tgisinternal and t.tgname = any(${workflowsTriggers})) as triggers`.execute(db);
+	const row = rows[0];
+	return {
+		tables: row.found,
+		current: row.found && commentVersion(row.comment) === 3 && row.triggers === workflowsTriggers.length
+	};
+};
+/**
+* The SQL that brings the `workflows` schema to what `workflows` needs: its tables, indexes and the triggers that number a
+* workflow's versions and pin a run's; `undefined` when current. Tables are never dropped.
+*/
+const workflowsMigration = async (db, options = {}) => {
+	const schema = workflowsSchema(options);
+	const found = await readWorkflowsSchema(db, schema);
+	if (found.current) return void 0;
+	return `${[
+		`create schema if not exists ${quoteIdent(schema)}`,
+		...found.tables ? [] : [tablesSql(schema)],
+		indexesSql(schema),
+		functionsSql(schema)
+	].join(";\n\n")};`;
+};
+/** Refuses to go on while the `workflows` schema lacks what `workflows` needs; the project's migrations add it. */
+const checkWorkflowsSchema = async (db, options = {}) => {
+	const schema = workflowsSchema(options);
+	if ((await readWorkflowsSchema(db, schema)).current) return;
+	throw new Error(`The ${schema} schema is missing or behind this version of Protobase. Write it as a migration with \`${migrationCommand}\`, apply it with the project's migrations, then start again.`);
+};
+//#endregion
+export { checkWorkflowsSchema, workflowsMigration };

package/dist/workflows/segment-job.js

@@ -0,0 +1,51 @@
+import { defineJob } from "../jobs/define-job.js";
+import { postgresRunStore } from "./store.js";
+import { createRunner } from "@protobase/workflows";
+//#region src/workflows/segment-job.ts
+/** The job that runs one segment of a workflow run. */
+const segmentJobName = "workflows.segment";
+/**
+* The runner on the app's jobs: each segment is a `workflows.segment` job, kept once per run while it waits. Its
+* timeout is above a segment's time plus the longest step's, so a job that times out is a worker that died, and its
+* next try takes the run up from its last saved step.
+*/
+const workflowsRunner = ({ schema, tasks, secrets }) => {
+	let job;
+	const store = postgresRunStore(schema);
+	const queue = { schedule: async (db, run, at) => void await job.enqueue(db, { run }, {
+		key: run,
+		...at && { runAt: at }
+	}) };
+	const runner = createRunner({
+		store,
+		queue,
+		tasks: {},
+		secrets
+	});
+	job = defineJob({
+		name: segmentJobName,
+		run: ({ run }, context) => createRunner({
+			store,
+			queue,
+			tasks: tasks(context),
+			secrets
+		}).segment(context.db, run, context.signal).catch(async (error) => {
+			if (context.job.attempt >= context.job.maxAttempts) await store.update(context.db, run, {
+				status: "failed",
+				error: "States.Runtime",
+				cause: `The run's segment failed ${context.job.attempt} times in a row`
+			});
+			throw error;
+		}),
+		maxAttempts: 10,
+		retryDelay: "5 seconds",
+		timeout: "10 minutes",
+		concurrency: 5
+	});
+	return {
+		runner,
+		job
+	};
+};
+//#endregion
+export { segmentJobName, workflowsRunner };

package/dist/workflows/start-hook.js

@@ -0,0 +1,26 @@
+import { notFound } from "../problem.js";
+import { requestAccess, requireOperation } from "../request-access.js";
+import { deletedRows } from "../params.js";
+import { fetchReadable } from "../fetch-readable.js";
+import { checkRunInput } from "./input-limits.js";
+//#region src/workflows/start-hook.ts
+/**
+* Starts a run as it is created through the API, in the write's transaction: it refuses an input over its limits and
+* a workflow the caller cannot read in their tenant (404, as the API answers for it), and queues the run's first
+* segment, which runs once the write commits. The resource records who started it, as the run's author.
+*/
+const runStartHook = (runner, deps) => async (event, trx) => {
+	if (event.resource.name !== "workflow_runs" || event.operation !== "create" || !event.after) return;
+	checkRunInput(event.after.input);
+	const entry = deps().registry.find("workflows");
+	const access = await requestAccess(deps(), entry, {
+		user: event.user,
+		...event.tenant !== void 0 && { tenant: event.tenant }
+	});
+	requireOperation(access, "read");
+	const key = access.full.fields[access.full.primaryKey[0]];
+	if (!await fetchReadable(trx, access, [String(event.after.workflow_id)], deletedRows(access.full, false), { fields: [key] })) throw notFound(`No ${entry.name} with this key`);
+	await runner.start(trx, String(event.after.id));
+};
+//#endregion
+export { runStartHook };

package/dist/workflows/start-workflow.d.ts

@@ -0,0 +1,26 @@
+import { TenantValue } from "../types.js";
+import { Db } from "@protobase/query";
+//#region src/workflows/start-workflow.d.ts
+export type StartWorkflowOptions = {
+  /** The workflow's id. */
+  workflow: string;
+  /** What its states read as `$states.context.Execution.Input`; at most 1 MiB as JSON, nested at most 64 deep. */
+  input?: unknown;
+  /** The workflow's tenant, in an app with tenants. */
+  tenant?: TenantValue;
+  /** Who or what started it, as the run records it. */
+  startedBy?: string;
+  /**
+   * Starts it once per workflow and key, such as `orders:42` for what a trigger found ready: a start with a key the
+   * workflow has a run for already starts nothing and returns that run's id.
+   */
+  key?: string;
+  /** The schema of `workflows`, when the config names another. Default `workflows`. */
+  schema?: string;
+};
+/**
+ * Starts a run of a workflow from the app's own code, such as a job or a write hook, and returns the run's id. In
+ * `db`'s own transaction when it is one, so the run starts when the caller's writes commit, or not at all.
+ */
+export declare const startWorkflow: (db: Db, { workflow, input, tenant, startedBy, key, schema }: StartWorkflowOptions) => Promise<string>;
+//#endregion

package/dist/workflows/start-workflow.js

@@ -0,0 +1,28 @@
+import { currentJobs } from "../jobs/current.js";
+import { checkRunInput } from "./input-limits.js";
+import { segmentJobName } from "./segment-job.js";
+import { sql } from "kysely";
+//#region src/workflows/start-workflow.ts
+/**
+* Starts a run of a workflow from the app's own code, such as a job or a write hook, and returns the run's id. In
+* `db`'s own transaction when it is one, so the run starts when the caller's writes commit, or not at all.
+*/
+const startWorkflow = async (db, { workflow, input, tenant, startedBy, key, schema = "workflows" }) => {
+	checkRunInput(input);
+	const job = currentJobs().definition(segmentJobName);
+	if (!job) throw new Error("Workflows are not running in this app: add `workflows: {}` to protobase.config.ts");
+	const runs = sql.id(schema, "runs");
+	const { rows } = await sql`insert into ${runs} (workflow_id, input, tenant_id, started_by, key)
+    values (${workflow}, ${input === void 0 ? null : JSON.stringify(input)}::jsonb, ${tenant === void 0 ? null : String(tenant)}, ${startedBy ?? null}, ${key ?? null})
+    on conflict (workflow_id, key) do nothing returning id`.execute(db);
+	if (rows.length === 0) {
+		const existing = (await sql`select id, status from ${runs} where workflow_id = ${workflow} and key = ${key}`.execute(db)).rows[0];
+		if (existing.status === "queued") await job.enqueue(db, { run: existing.id }, { key: existing.id });
+		return existing.id;
+	}
+	const id = rows[0].id;
+	await job.enqueue(db, { run: id }, { key: id });
+	return id;
+};
+//#endregion
+export { startWorkflow };

package/dist/workflows/step-types.js

@@ -0,0 +1,34 @@
+import { httpStep } from "./http-step.js";
+import { mailStep } from "./mail-step.js";
+import { pieceStep } from "./piece-step.js";
+import { recordsSteps } from "./records-step.js";
+//#region src/workflows/step-types.ts
+/** The step types a Task names as its `Resource`, as the language report lists them. */
+const stepTypeNames = [
+	"app:http",
+	"app:records.create",
+	"app:records.update",
+	"app:records.get",
+	"app:records.list",
+	"app:mail.send",
+	"app:piece"
+];
+/** The step types of one segment, which sends mail with the mailer of the job that runs it. */
+const stepTypes = ({ deps, schema, roles, allowPrivateAddresses }, mail) => {
+	const files = () => deps().files;
+	return {
+		"app:http": httpStep({
+			allowPrivateAddresses,
+			files
+		}),
+		...recordsSteps({
+			deps,
+			schema,
+			roles
+		}),
+		"app:mail.send": mailStep(() => mail, files),
+		"app:piece": pieceStep
+	};
+};
+//#endregion
+export { stepTypeNames, stepTypes };

package/dist/workflows/store.js

@@ -0,0 +1,42 @@
+import { sql } from "kysely";
+//#region src/workflows/store.ts
+const json = (value) => value === void 0 ? null : JSON.stringify(value);
+/** The runner's store over the `workflows` schema: runs with their pinned version, and their steps. */
+const postgresRunStore = (schema) => {
+	const runs = sql.id(schema, "runs");
+	const versions = sql.id(schema, "versions");
+	const steps = sql.id(schema, "steps");
+	return {
+		load: async (db, id) => {
+			const { rows } = await sql`select r.id, v.definition, r.input, r.status, r.created_at as "startedAt"
+        from ${runs} r join ${versions} v on v.workflow_id = r.workflow_id and v.version = r.version where r.id = ${id}`.execute(db);
+			return rows[0];
+		},
+		steps: async (db, id) => {
+			const { rows } = await sql`select scope, seq, state, status, attempt, output, assigned, next, resume_at as "resumeAt", error, cause
+        from ${steps} where run_id = ${id} order by scope, seq`.execute(db);
+			return rows;
+		},
+		save: async (db, id, step) => {
+			const { rows } = await sql`insert into ${steps}
+        (run_id, tenant_id, scope, seq, state, type, status, attempt, input, output, assigned, next, resume_at, error, cause, logs, started_at, finished_at)
+        select r.id, r.tenant_id, ${step.scope}, ${step.seq}, ${step.state}, ${step.type}, ${step.status}, ${step.attempt}, ${json(step.input)}::jsonb,
+          ${json(step.output)}::jsonb, ${json(step.assigned)}::jsonb, ${step.next}, ${step.resumeAt ?? null}, ${step.error ?? null}, ${step.cause ?? null},
+          ${JSON.stringify(step.logs)}::jsonb, ${step.startedAt}, ${step.finishedAt}
+        from ${runs} r where r.id = ${id}
+        on conflict (run_id, scope, seq) do nothing returning id`.execute(db);
+			return rows.length > 0;
+		},
+		update: async (db, id, change) => {
+			const ended = change.status === "succeeded" || change.status === "failed";
+			await sql`update ${runs} set status = ${change.status},
+          resume_at = ${change.status === "waiting" ? change.resumeAt : null},
+          output = ${change.status === "succeeded" ? json(change.output) : null}::jsonb,
+          error = ${change.status === "failed" ? change.error : null}, cause = ${change.status === "failed" ? change.cause : null},
+          finished_at = ${ended ? sql`now()` : sql`null`}
+        where id = ${id} and status not in ('succeeded', 'failed')`.execute(db);
+		}
+	};
+};
+//#endregion
+export { postgresRunStore };