@sanoma-ai/workflows 0.0.0-stage → 0.1.0

package/dist/config.js

@@ -0,0 +1,247 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { callerFile } from "./define.js";
+import { DRIFT_WORKFLOW, driftWorkflow } from "./drift.js";
+import { statusesOf, unconfigured } from "./env.js";
+import { DriverError, isOp, checkConnector, setupOf, VENDOR, } from "./op.js";
+import { resourceTypesOf, withoutWriteOnly } from "./resource.js";
+import { computeVersion } from "./version.js";
+export const DEFAULT_DATABASE_URL = "postgresql://postgres:dbos@localhost:5433/sanoma";
+/** Returns the config, with the file it is called from as its `file`: its directory is the config's `root`. */
+export function defineConfig(config) {
+    return { ...config, file: config.file ?? callerFile() };
+}
+export function resolveDatabaseUrl(config, env = process.env) {
+    return config.databaseUrl ?? env.SANOMA_DATABASE_URL ?? DEFAULT_DATABASE_URL;
+}
+const isStore = (x) => typeof x?.append === "function" && typeof x.read === "function";
+/** The config's `ledger`, checked, when it gives one. */
+function ledgerOf(config) {
+    if (config.ledger !== undefined && !isStore(config.ledger)) {
+        throw new Error("The config's `ledger` must be a ledger store: leave it out for `postgresLedger` on the config's database, " +
+            "or use `jsonlLedger(dir)` to keep records in files, or `memoryLedger()` to keep them in memory, for tests");
+    }
+    return config.ledger;
+}
+/**
+ * The config's directory, absolute: its `root`, else its `file`'s directory; undefined when it
+ * has neither. No fallback to the working directory: a config found nowhere has no data files,
+ * and says so. What a read that needs only the root calls, rather than `resolveConfig`.
+ */
+export function rootOf(config) {
+    return config.root !== undefined
+        ? resolve(config.root)
+        : config.file !== undefined
+            ? dirname(config.file)
+            : undefined;
+}
+/**
+ * Checks a config and derives what the runtime needs from it: the drivers and fakes from the
+ * connectors' setups (`withSetup`), and from `root`, the app's name (`package.json`) and the
+ * scenarios (`scenarios/`). Throws what `startWorker` would refuse, with the same message, so
+ * `describeConfig`, `SanomaClient.connect` and the app fail the same way the worker does. It
+ * opens nothing and reads no file outside `root`. Each entry
+ * point resolves once: the worker and the client when they start, the app at `startApp`, the
+ * `sanoma` bin when it loads the config.
+ */
+export function resolveConfig(config) {
+    if (!Array.isArray(config.connectors)) {
+        throw new Error("The config needs `connectors`: the connectors its workflows call, as their packages export them");
+    }
+    for (const connector of config.connectors)
+        checkConnector(connector);
+    if (!Array.isArray(config.workflows)) {
+        throw new Error("The config needs `workflows`: an array of defineWorkflow definitions");
+    }
+    if (typeof config.policy !== "function") {
+        throw new Error("The config needs a `policy`; use `allowAll` to allow every operation call");
+    }
+    // An untyped config naming fake drivers would otherwise run live. Delete once sanoma-ops has migrated.
+    if (config.drivers !== undefined || config.fakes !== undefined)
+        throw new Error("The config's `drivers` and `fakes` are gone: each connector carries its driver and its fake; leave them out");
+    const ledger = ledgerOf(config);
+    const root = rootOf(config);
+    const appName = appNameAt(root);
+    const scenarios = scenariosAt(root);
+    const ops = indexConnectors(config.connectors);
+    const driversByVendor = new Map([...makersOf(config.connectors, "driver")].map(([vendor, make]) => [vendor, make()]));
+    const drivers = indexDrivers([...driversByVendor.values()], ops);
+    const fakes = makersOf(config.connectors, "fake");
+    const names = new Map();
+    for (const wf of config.workflows) {
+        if (wf.name === DRIFT_WORKFLOW) {
+            throw new Error(`A workflow is named "${DRIFT_WORKFLOW}", the name of the built-in drift workflow; name it otherwise`);
+        }
+        checkUses(wf, ops, drivers);
+        const other = names.get(wf.name);
+        if (other && other !== wf) {
+            throw new Error(`Two different workflow definitions are named "${wf.name}"; a name can be registered once per process`);
+        }
+        names.set(wf.name, wf);
+    }
+    // Built-in: checking the resources the data files declare against their vendors.
+    const types = resourceTypesOf(config.connectors);
+    if (types.size) {
+        const declared = () => DBOS.runStep(() => readDeclared(root, config.connectors, types), { name: "drift:data-files" });
+        names.set(DRIFT_WORKFLOW, driftWorkflow(types, ops, drivers, declared));
+    }
+    return {
+        appName,
+        databaseUrl: resolveDatabaseUrl(config),
+        // The built-in's code and operations are part of the app's version, like the config's own.
+        version: computeVersion({ appName, workflows: [...names.values()] }),
+        queueName: `sanoma:${appName}`,
+        ops,
+        drivers,
+        driversByVendor,
+        fakes,
+        ...(scenarios && { scenarios }),
+        types,
+        steps: [...new Set([...config.connectors.flatMap((c) => setupOf(c).steps ?? []), ...(config.steps ?? [])])],
+        workflows: names,
+        policy: config.policy,
+        ...(ledger !== undefined && { ledger }),
+        ...(root !== undefined && { root }),
+    };
+}
+/**
+ * What the connectors' setups attach under `key` (`withSetup`), by vendor id in `connectors`
+ * order. One vendor's connectors may name one maker, as copies of one connector do, never two.
+ */
+function makersOf(connectors, key) {
+    const makers = new Map();
+    for (const connector of connectors) {
+        const make = setupOf(connector)[key];
+        if (make === undefined)
+            continue;
+        const vendor = connector[VENDOR].id;
+        const seen = makers.get(vendor);
+        if (seen && seen !== make) {
+            throw new Error(`Two connectors in \`connectors\` attach a ${key} for "${vendor}"; keep one per vendor`);
+        }
+        makers.set(vendor, make);
+    }
+    return makers;
+}
+/**
+ * The `name` of `<root>/package.json`, kept whole (`@acme/ops`), when that file exists and names
+ * one; else "sanoma", as for a config with no `root`. Never a `package.json` above the root: a
+ * parent project's name must not become the app's. A file that is not JSON is refused, naming it.
+ */
+function appNameAt(root) {
+    const file = root === undefined ? undefined : join(root, "package.json");
+    if (file === undefined || !existsSync(file))
+        return "sanoma";
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`${file} is not JSON, so it names no app: ${err.message}`, { cause: err });
+    }
+    const named = manifest?.name;
+    return typeof named === "string" && named.trim() ? named.trim() : "sanoma";
+}
+/** `<root>/scenarios/`, as a `file:` URL to the directory (with its trailing slash), when it is a directory. */
+function scenariosAt(root) {
+    const dir = root === undefined ? undefined : join(root, "scenarios");
+    if (dir === undefined || !statSync(dir, { throwIfNoEntry: false })?.isDirectory())
+        return undefined;
+    return pathToFileURL(`${dir}/`);
+}
+/**
+ * The data files under `root`, as a drift run records them: each resource without its write-only
+ * values, which a run never compares and never records, and the problems.
+ */
+async function readDeclared(root, connectors, types) {
+    // Loaded when a drift run reads the files, not with the worker: the reader parses with oxc-parser.
+    const { readDataFiles } = await import("./resources.js");
+    const { resources, problems } = readDataFiles(root, connectors, types);
+    return {
+        resources: resources.map(({ id, vendor, type, name, desired, refs }) => ({
+            id,
+            vendor,
+            type,
+            name,
+            desired: withoutWriteOnly(types.get(`${vendor}.${type}`).fields, desired),
+            refs,
+        })),
+        problems,
+    };
+}
+function indexConnectors(list) {
+    const map = new Map();
+    for (const connector of list) {
+        for (const resource of Object.values(connector)) {
+            for (const op of Object.values(resource)) {
+                if (!isOp(op))
+                    continue;
+                const seen = map.get(op.id);
+                if (seen && seen !== op)
+                    throw new Error(`Two connectors in \`connectors\` declare ${op.id}`);
+                map.set(op.id, op);
+            }
+        }
+    }
+    return map;
+}
+/**
+ * The drivers' functions by operation id, refusing one no connector declares. A driver that
+ * declares an `env` has each function guarded by it (`guarded`); a fake declares none, so a
+ * sandbox run's calls are not.
+ */
+export function indexDrivers(list, ops) {
+    const map = new Map();
+    for (const d of list) {
+        for (const [key, fn] of Object.entries(d.ops)) {
+            const id = `${d.vendor}.${key}`;
+            if (!ops.has(id)) {
+                throw new Error(`Driver "${d.vendor}" implements ${id}, which no connector in \`connectors\` declares`);
+            }
+            map.set(id, d.env ? guarded(d.vendor, d.env, fn) : fn);
+        }
+    }
+    return map;
+}
+/**
+ * `fn`, refused while the environment leaves a variable `env` declares missing or invalid. The
+ * worker started without it (`startWorker` only warns), and stored credentials load into the
+ * environment as they are set, so the check is made when the function is called, inside the
+ * driver step, and nowhere earlier: not at start, and not before the policy's decision or an
+ * approval hold, so a credential set on the connector page while a call waits for approval is
+ * used when the approver approves. The refusal is the call's own failure, final: recorded as
+ * the call's, and never retried.
+ */
+function guarded(vendor, env, fn) {
+    return async (input, call) => {
+        const why = unconfigured(vendor, statusesOf(env, (name) => process.env[name]));
+        if (why)
+            throw new DriverError(why, { retryable: false });
+        return fn(input, call);
+    };
+}
+/**
+ * Every operation a workflow uses must be one the config's connectors declare, with a driver.
+ * The workflow normally imports the same connector object; a copy is accepted only if it
+ * declares the same effect and retry setting, and the worker's declaration is used either way.
+ */
+function checkUses(wf, ops, impls) {
+    const problems = [];
+    for (const op of wf.uses.filter(isOp)) {
+        const known = ops.get(op.id);
+        if (!known)
+            problems.push(`${op.id} is not declared by any connector in \`connectors\``);
+        else if (known !== op && (known.effect !== op.effect || known.idempotent !== op.idempotent)) {
+            problems.push(`${op.id} is declared with effect "${op.effect}"${op.idempotent ? " (idempotent)" : ""}, ` +
+                `but its connector says "${known.effect}"${known.idempotent ? " (idempotent)" : ""}`);
+        }
+        else if (!impls.has(op.id)) {
+            problems.push(`\`${op.id}\` has no driver: the connector package must attach one`);
+        }
+    }
+    if (problems.length)
+        throw new Error(`Workflow "${wf.name}": ${problems.join("; ")}`);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/credentials.d.ts

@@ -0,0 +1,30 @@
+import { type Db } from "./db.ts";
+import type { Driver } from "./op.ts";
+/** The stored rows of these names, values included: for loading into an environment or checking, never for showing. */
+export declare function storedCredentials(db: Db, names: readonly string[]): Promise<Map<string, {
+    value: string;
+    setBy: string;
+    setAt: string;
+}>>;
+/** Upserts the value and announces it, in one statement, so a worker never hears of a change it cannot read. */
+export declare function storeCredential(db: Db, { name, value, setBy }: {
+    name: string;
+    value: string;
+    setBy: string;
+}): Promise<void>;
+/** Deletes the row, announcing it when there was one. */
+export declare function deleteCredential(db: Db, name: string): Promise<void>;
+/** Stops a worker's credentials listener. */
+export interface CredentialsWatch {
+    close(): Promise<void>;
+}
+/**
+ * Loads the stored values of the declared variables the environment does not set into
+ * `process.env`, then keeps them current: on each change announced, and on reconnecting, it
+ * loads them again, so a value set replaces the one before and a value cleared is deleted. A
+ * name the environment set when this started is never touched, and the names it did set are
+ * deleted on `close`. Logs, per vendor, how many variables each load changed, never a value, and
+ * warns of a reloaded value its schema refuses. A listener that drops reconnects, waiting longer
+ * after each failure, up to 30 s, until it is closed. With no such variable, it connects to nothing.
+ */
+export declare function watchCredentials(databaseUrl: string, drivers: ReadonlyMap<string, Driver>): Promise<CredentialsWatch>;

package/dist/credentials.js

@@ -0,0 +1,193 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { Client } from "pg";
+import { credentialsOf } from "./env.js";
+import { CREDENTIALS_TABLE as TABLE, prepareDatabase } from "./db.js";
+import { info, warn } from "./log.js";
+import { errorMessage } from "./shared.js";
+// Where the credentials set from the app live: one table in the config's database, beside DBOS's
+// own (made by `prepareDatabase` in db.ts). A value is read here only, by the worker to load it
+// into its environment and by the client to check it, and leaves neither. The write
+// (`storeCredential`) and the read (`storedCredentials`) are the only places that touch `value`,
+// so a hosted deployment's encryption goes there.
+/** Where a change is announced, with the variable's name as the payload. */
+const CHANNEL = "sanoma_credentials";
+/** The stored rows of these names, values included: for loading into an environment or checking, never for showing. */
+export async function storedCredentials(db, names) {
+    const { rows } = await db.query(`SELECT name, value, set_by, set_at FROM ${TABLE} WHERE name = ANY($1)`, [names]);
+    return new Map(rows.map((r) => [r.name, { value: r.value, setBy: r.set_by, setAt: r.set_at.toISOString() }]));
+}
+/** Upserts the value and announces it, in one statement, so a worker never hears of a change it cannot read. */
+export async function storeCredential(db, { name, value, setBy }) {
+    await db.query(`WITH stored AS (INSERT INTO ${TABLE} (name, value, set_by) VALUES ($1, $2, $3) ` +
+        "ON CONFLICT (name) DO UPDATE SET value = EXCLUDED.value, set_by = EXCLUDED.set_by, set_at = now() " +
+        `RETURNING name) SELECT pg_notify('${CHANNEL}', name) FROM stored`, [name, value, setBy]);
+}
+/** Deletes the row, announcing it when there was one. */
+export async function deleteCredential(db, name) {
+    await db.query(`WITH gone AS (DELETE FROM ${TABLE} WHERE name = $1 RETURNING name) SELECT pg_notify('${CHANNEL}', name) FROM gone`, [name]);
+}
+/** The longest wait between two attempts to reconnect the listener, and between two warnings that one failed. */
+const RETRY_MAX_MS = 30_000;
+/**
+ * Loads the stored values of the declared variables the environment does not set into
+ * `process.env`, then keeps them current: on each change announced, and on reconnecting, it
+ * loads them again, so a value set replaces the one before and a value cleared is deleted. A
+ * name the environment set when this started is never touched, and the names it did set are
+ * deleted on `close`. Logs, per vendor, how many variables each load changed, never a value, and
+ * warns of a reloaded value its schema refuses. A listener that drops reconnects, waiting longer
+ * after each failure, up to 30 s, until it is closed. With no such variable, it connects to nothing.
+ */
+export async function watchCredentials(databaseUrl, drivers) {
+    const vendors = new Map();
+    for (const [vendor, list] of credentialsOf(drivers, () => undefined)) {
+        for (const { name } of list)
+            if (!process.env[name] && !vendors.has(name))
+                vendors.set(name, vendor);
+    }
+    const names = [...vendors.keys()];
+    if (!names.length)
+        return { close: async () => undefined };
+    /** The listener's connection, from when it connects until it drops or closes. */
+    let db;
+    let closed = false;
+    let reconnecting = false;
+    // One load at a time, so close() can wait for it; the changes announced during one make one more.
+    let loading;
+    let stale = false;
+    async function load(first) {
+        const conn = db;
+        if (closed || !conn)
+            return;
+        const rows = await storedCredentials(conn, names);
+        // Nothing touches the environment once closed: a worker or an app started after may own it.
+        if (closed)
+            return;
+        const changed = names.filter((name) => rows.get(name)?.value !== process.env[name]);
+        const counts = new Map();
+        for (const name of changed) {
+            const value = rows.get(name)?.value;
+            if (value === undefined)
+                delete process.env[name];
+            else
+                process.env[name] = value;
+            const vendor = vendors.get(name);
+            counts.set(vendor, (counts.get(vendor) ?? 0) + 1);
+        }
+        const verb = first ? "loaded" : "reloaded";
+        for (const [vendor, n] of counts)
+            info(`credentials ${verb} for ${vendor} (${n} variable${n === 1 ? "" : "s"})`);
+        // At start, startWorker warns of an invalid one, naming it.
+        if (first)
+            return;
+        for (const list of credentialsOf(drivers, (name) => changed.includes(name) ? process.env[name] : undefined).values()) {
+            for (const c of list) {
+                if (c.status === "invalid")
+                    warn(`the stored ${c.name} is invalid (${c.problem}): calls that read it will fail`);
+            }
+        }
+    }
+    function reload(first = false) {
+        if (loading) {
+            stale = true;
+            return loading;
+        }
+        loading = (async () => {
+            try {
+                do {
+                    stale = false;
+                    await load(first);
+                    first = false;
+                } while (stale);
+            }
+            finally {
+                loading = undefined;
+            }
+        })();
+        return loading;
+    }
+    async function open(first) {
+        const conn = new Client({ connectionString: databaseUrl, keepAlive: true, connectionTimeoutMillis: 10_000 });
+        // Before anything can fail: an error nobody listens for ends the process.
+        conn.on("error", (err) => lost(conn, err));
+        // Before LISTEN, so no change announced from then on is missed.
+        conn.on("notification", () => {
+            if (!closed && conn === db) {
+                reload().catch((err) => warn(`could not reload the credentials: ${errorMessage(err)}`));
+            }
+        });
+        try {
+            if (first)
+                await prepareDatabase(databaseUrl);
+            await conn.connect();
+            if (closed) {
+                await conn.end();
+                return;
+            }
+            db = conn;
+            await conn.query(`LISTEN ${CHANNEL}`);
+            await reload(first);
+        }
+        catch (err) {
+            if (db === conn)
+                db = undefined;
+            await conn.end().catch(() => undefined);
+            throw err;
+        }
+    }
+    /** A connection that dropped: the one listening is replaced; one still connecting fails its own open. */
+    function lost(conn, err) {
+        if (closed || conn !== db)
+            return;
+        db = undefined;
+        void conn.end().catch(() => undefined);
+        warn(`the credentials listener failed (${errorMessage(err)}); reconnecting`);
+        void reconnect();
+    }
+    async function reconnect() {
+        if (reconnecting)
+            return;
+        reconnecting = true;
+        let wait = 1_000;
+        let warnedAt = 0;
+        try {
+            for (;;) {
+                await sleep(wait, undefined, { ref: false });
+                if (closed)
+                    return;
+                try {
+                    await open(false);
+                    return;
+                }
+                catch (err) {
+                    if (Date.now() - warnedAt >= RETRY_MAX_MS) {
+                        warnedAt = Date.now();
+                        warn(`could not reconnect the credentials listener (${errorMessage(err)}); trying again`);
+                    }
+                    wait = Math.min(wait * 2, RETRY_MAX_MS);
+                }
+            }
+        }
+        finally {
+            reconnecting = false;
+        }
+    }
+    try {
+        await open(true);
+    }
+    catch (err) {
+        closed = true;
+        throw err;
+    }
+    return {
+        async close() {
+            closed = true;
+            await loading?.catch(() => undefined);
+            for (const name of names)
+                delete process.env[name];
+            const conn = db;
+            db = undefined;
+            await conn?.end();
+        },
+    };
+}
+//# sourceMappingURL=credentials.js.map

package/dist/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"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"}

package/dist/cucumber.d.ts

@@ -0,0 +1,64 @@
+import { type ISupportCodeLibrary } from "@cucumber/cucumber/api";
+import { type Pickle, type PickleStep, TestStepResultStatus } from "@cucumber/messages";
+import { Query } from "@cucumber/query";
+/** A parameter type the steps' expressions use, as Cucumber's `defineParameterType` takes it. */
+export interface ParameterTypeSpec {
+    name: string;
+    regexp: RegExp | string | readonly (RegExp | string)[];
+    transformer: (...match: string[]) => unknown;
+}
+/** What one run does with its scenarios' steps. */
+export interface SanomaWorld {
+    /** Called before the scenario's first step. */
+    begin(pickle: Pickle): void;
+    /** Runs one step: `expression` is the expression it matched, `values` its parameters. */
+    step(expression: string, values: unknown[], pickleStep: PickleStep): unknown;
+}
+/**
+ * Builds a support code library: the parameter types, then one step definition per expression,
+ * each handing its step to the World. Cucumber keeps one builder per process, so the library is
+ * built here, by hand, in one synchronous stretch (`reset`, register, `finalize`): building it
+ * again in the same process gives the same definitions, where a second `loadSupport` would
+ * import nothing new and find none.
+ */
+export declare function buildLibrary(parameterTypes: readonly ParameterTypeSpec[], expressions: Iterable<string>): ISupportCodeLibrary;
+/** How one step ended. */
+export interface StepResult {
+    status: TestStepResultStatus;
+    /** Why it failed: its error's message. */
+    message?: string;
+    /** The expressions that match it: none for an undefined step, more than one for an ambiguous one. */
+    matches: string[];
+}
+/** What a run read: Cucumber's `Query` of its messages, each file's text, and the files Gherkin could not parse. */
+export interface Report {
+    query: Query;
+    /** Each file's text, by its path relative to the run's `cwd`. */
+    texts: Map<string, string>;
+    /** Files Gherkin could not parse; none of the run's scenarios ran when there are any. */
+    parseErrors: {
+        uri: string;
+        line?: number;
+        message: string;
+    }[];
+}
+/** How each step of a run ended, by its pickle step's id; a step of a pickle that did not run has none. */
+export declare function stepResults({ query }: Report): Map<string, StepResult>;
+/** A pickle's line: its examples row's, or its scenario's. */
+export declare const lineOf: (report: Report, pickle: Pickle) => number;
+/**
+ * Runs the feature files `files` (relative to `cwd`) with the library, serially, in this
+ * process, and reads back what happened. `line`, with a single file, runs only the scenario or
+ * examples row at that line. `makeWorld` makes each scenario's World, given the report so far
+ * (every file and pickle, read before the first scenario starts). A dry run matches the steps
+ * and runs none. A step's error that is a bug in code (`isBug`) is rethrown once the run is
+ * over, rather than reported as the step's failure.
+ */
+export declare function runFeatures(library: ISupportCodeLibrary, makeWorld: (report: Report) => SanomaWorld, { cwd, files, line, dryRun, isBug, }: {
+    cwd: string;
+    files: string[];
+    line?: number;
+    dryRun?: boolean;
+    isBug: (err: unknown) => boolean;
+}): Promise<Report>;
+export { TestStepResultStatus as StepStatus };