@voltro/workflow 0.1.0

package/dist/cluster.d.ts

@@ -0,0 +1,112 @@
+import { ConfigError } from 'effect';
+import { Cron } from 'effect';
+import { Duration } from 'effect';
+import { Layer } from 'effect';
+import { Sharding } from '@effect/cluster';
+import { SqlClient } from '@effect/sql';
+import { SqlError } from '@effect/sql';
+import { WorkflowEngine } from '@effect/workflow';
+
+export declare interface ClusterCronSpec {
+    /** Stable schedule name — used as the cluster cron's identity. */
+    readonly name: string;
+    /** Compiled cron (timezone already baked in by `Cron.parse`). */
+    readonly cron: Cron.Cron;
+    /** The wrapped firing — records the run row + invokes the user
+     *  handler. Plain async; we lift it into an Effect. Must not throw
+     *  in a way that breaks the cluster cron loop — the framework's
+     *  recording wrapper swallows its own errors. */
+    readonly execute: () => Promise<void>;
+    /** Skip a firing whose scheduled time is older than this — the
+     *  cluster's built-in backfill guard. Defaults to "1 day". */
+    readonly skipIfOlderThan?: Duration.DurationInput;
+}
+
+/** Default port for the cluster's single-runner listener. Override per deploy. */
+export declare const DEFAULT_RUNNER_LISTEN_PORT: 34000;
+
+/**
+ * Build the cluster-cron layer for one schedule. Returns a
+ * `Layer<never, never, Sharding>` — the framework provides `Sharding`
+ * by merging this into the same runtime as the cluster workflow
+ * engine (see `workflowEngineLayer({ extraShardingLayers })`).
+ */
+export declare const makeClusterCronLayer: (spec: ClusterCronSpec) => Layer.Layer<never, never, Sharding.Sharding>;
+
+/** Resolve the runner host/port the SAME way `workflowEngineLayer` does:
+ *  explicit option → `POD_IP` → `VOLTRO_WORKFLOW_RUNNER_HOST` → loopback;
+ *  port from option → `VOLTRO_WORKFLOW_RUNNER_PORT` → default. */
+export declare const resolveRunnerIdentity: (opts: {
+    readonly runnerStorage: RunnerStorage;
+    readonly runnerListenHost?: string | undefined;
+    readonly runnerListenPort?: number | undefined;
+}) => RunnerIdentity;
+
+/** Resolved cluster-runner address + the silent-resume-breaker flag.
+ *  Single source of truth for both the engine layer and the
+ *  `/_voltro/inspect/cluster` snapshot, so the CLI never reports an
+ *  address that differs from the one the runner actually advertises. */
+export declare interface RunnerIdentity {
+    readonly host: string;
+    readonly port: number;
+    /** True iff a SQL-backed runner advertises a loopback host — other
+     *  pods can't reach it, so cross-pod workflow resume silently breaks. */
+    readonly localhostRisk: boolean;
+}
+
+/**
+ * Runner-storage backend for `@effect/cluster.SingleRunner`.
+ *
+ *   - `'sql'`     — durable across crashes + multi-instance scale-out.
+ *                   Used for postgres / mysql / mariadb / mssql.
+ *   - `'memory'`  — durable replay within the SAME process; no
+ *                   horizontal scale-out. Used for `sqlite` because
+ *                   `@effect/cluster.SqlRunnerStorage` has no SQLite
+ *                   lock-acquisition branch (`pg_advisory_lock` and
+ *                   `GET_LOCK` aren't available there).
+ */
+export declare type RunnerStorage = 'sql' | 'memory';
+
+/**
+ * Compose the dialect's SqlClient → SingleRunner → ClusterWorkflowEngine
+ * into a single layer that user code provides to its program to get
+ * durable workflows.
+ *
+ * `extraShardingLayers` (e.g. `ClusterCron` layers from
+ * `cluster`-coordinated schedules) are merged into the same runtime so
+ * they share the runner identity + shard map.
+ *
+ * For dev / tests where no real engine is available, see
+ * `inMemoryWorkflowEngineLayer`.
+ */
+export declare const workflowEngineLayer: (options: WorkflowEngineLayerOptions) => Layer.Layer<WorkflowEngine.WorkflowEngine>;
+
+export declare interface WorkflowEngineLayerOptions {
+    /**
+     * The dialect's SqlClient layer (postgres / mysql / mariadb / mssql).
+     * For `runnerStorage: 'memory'` it's still required so the cluster's
+     * Sharding infra has a SqlClient to satisfy — even though no SQL
+     * runs through it for sqlite, the layer's resource lifecycle keeps
+     * the cluster's accounting clean.
+     */
+    readonly sqlClientLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>;
+    /** `'sql'` for postgres / mysql / mariadb / mssql, `'memory'` for sqlite. */
+    readonly runnerStorage: RunnerStorage;
+    readonly runnerListenHost?: string;
+    readonly runnerListenPort?: number;
+    /**
+     * Extra layers that need the cluster's `Sharding` service — most
+     * prominently `ClusterCron` layers for `cluster`-coordinated
+     * schedules (plan 45). They're merged into the SAME runtime as the
+     * workflow engine so they share the single `SingleRunner` /
+     * `Sharding` instance (one runner identity, one shard map). The
+     * framework passes these in; user code never touches `Sharding`
+     * directly.
+     *
+     * Each layer requires the cluster's `Sharding` service; that
+     * requirement is satisfied by `clusterLayer` below.
+     */
+    readonly extraShardingLayers?: ReadonlyArray<Layer.Layer<never, never, Sharding.Sharding>>;
+}
+
+export { }

package/dist/cluster.js

@@ -0,0 +1,2 @@
+import { i as e, n as t, r as n, t as r } from "./cluster-Cl6mB2rW.js";
+export { t as DEFAULT_RUNNER_LISTEN_PORT, r as makeClusterCronLayer, n as resolveRunnerIdentity, e as workflowEngineLayer };

package/dist/clusterTestSuite.d.ts

@@ -0,0 +1,84 @@
+import { ConfigError } from 'effect';
+import { Layer } from 'effect';
+import { Sharding } from '@effect/cluster';
+import { SqlClient } from '@effect/sql';
+import { SqlError } from '@effect/sql';
+
+/**
+ * Everything a dialect supplies to run the cluster-engine suite against
+ * its database. The scenarios are otherwise identical across dialects.
+ */
+export declare interface ClusterEngineFixture {
+    /** Dialect label for the describe block + workflow-name suffix. */
+    readonly name: string;
+    /** The dialect's `SqlClient` layer (postgres/mysql/mariadb/mssql/sqlite).
+     *  Typed via the engine's own option so `@voltro/testing` needs no
+     *  direct `@effect/sql` dependency. */
+    readonly sqlClientLayer: WorkflowEngineLayerOptions['sqlClientLayer'];
+    /** `'sql'` for server dialects, `'memory'` for sqlite. */
+    readonly runnerStorage: 'sql' | 'memory';
+    /** Base cluster-runner listen port (distinct per dialect so suites can
+     *  run side by side). The suite uses `port`, `port+1`, `port+2`. */
+    readonly runnerPort: number;
+    /** True iff this dialect supports cross-process workflow resume
+     *  (= `runnerStorage: 'sql'`). Gates the resume + dormancy scenarios. */
+    readonly clusterResume: boolean;
+    /** Is the database reachable? Soft-skips the whole suite when not (CI
+     *  without docker, a dialect's container down). SQLite returns true. */
+    readonly reachable: () => Promise<boolean>;
+}
+
+/**
+ * Register the cluster-engine suite for one dialect. Each
+ * `@voltro/sql-*` (or the workflow package) calls this from a thin
+ * `cluster.<dialect>.integration.test.ts` with its fixture.
+ */
+export declare const runClusterEngineSuite: (fixture: ClusterEngineFixture) => void;
+
+/**
+ * Runner-storage backend for `@effect/cluster.SingleRunner`.
+ *
+ *   - `'sql'`     — durable across crashes + multi-instance scale-out.
+ *                   Used for postgres / mysql / mariadb / mssql.
+ *   - `'memory'`  — durable replay within the SAME process; no
+ *                   horizontal scale-out. Used for `sqlite` because
+ *                   `@effect/cluster.SqlRunnerStorage` has no SQLite
+ *                   lock-acquisition branch (`pg_advisory_lock` and
+ *                   `GET_LOCK` aren't available there).
+ */
+declare type RunnerStorage = 'sql' | 'memory';
+
+/** Lightweight TCP reachability probe for a dialect's database — the
+ *  soft-skip a fixture's `reachable()` uses (cheaper than a full connect).
+ *  SQLite fixtures just return `true` directly. */
+export declare const tcpReachable: (host: string, port: number, timeoutMs?: number) => Promise<boolean>;
+
+declare interface WorkflowEngineLayerOptions {
+    /**
+     * The dialect's SqlClient layer (postgres / mysql / mariadb / mssql).
+     * For `runnerStorage: 'memory'` it's still required so the cluster's
+     * Sharding infra has a SqlClient to satisfy — even though no SQL
+     * runs through it for sqlite, the layer's resource lifecycle keeps
+     * the cluster's accounting clean.
+     */
+    readonly sqlClientLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>;
+    /** `'sql'` for postgres / mysql / mariadb / mssql, `'memory'` for sqlite. */
+    readonly runnerStorage: RunnerStorage;
+    readonly runnerListenHost?: string;
+    readonly runnerListenPort?: number;
+    /**
+     * Extra layers that need the cluster's `Sharding` service — most
+     * prominently `ClusterCron` layers for `cluster`-coordinated
+     * schedules (plan 45). They're merged into the SAME runtime as the
+     * workflow engine so they share the single `SingleRunner` /
+     * `Sharding` instance (one runner identity, one shard map). The
+     * framework passes these in; user code never touches `Sharding`
+     * directly.
+     *
+     * Each layer requires the cluster's `Sharding` service; that
+     * requirement is satisfied by `clusterLayer` below.
+     */
+    readonly extraShardingLayers?: ReadonlyArray<Layer.Layer<never, never, Sharding.Sharding>>;
+}
+
+export { }

package/dist/clusterTestSuite.js

@@ -0,0 +1,180 @@
+import { C as e, m as t, p as n, v as r, x as i } from "./primitives-CWy1iu5w.js";
+import { i as a } from "./src-CNeLb-4L.js";
+import { i as o, t as s } from "./cluster-Cl6mB2rW.js";
+import { Cron as c, Deferred as l, Effect as u, Fiber as d, Layer as f, Schema as p } from "effect";
+import { beforeAll as m, describe as h, expect as g, test as _ } from "vitest";
+//#region src/clusterTestSuite.ts
+var v = async (e, t, n = 750) => {
+	try {
+		let r = await import("node:net");
+		return await new Promise((i) => {
+			let a = new r.Socket(), o = setTimeout(() => {
+				a.destroy(), i(!1);
+			}, n);
+			a.once("connect", () => {
+				clearTimeout(o), a.end(), i(!0);
+			}), a.once("error", () => {
+				clearTimeout(o), i(!1);
+			}), a.connect(t, e);
+		});
+	} catch {
+		return !1;
+	}
+}, y = (e, t) => u.gen(function* () {
+	let n = yield* u.sync(() => Date.now() + t);
+	for (; !e();) {
+		if (Date.now() > n) return !1;
+		yield* u.sleep("250 millis");
+	}
+	return !0;
+}), b = (v) => {
+	let b = `${v.name}-${Date.now()}`, x = (e, t) => o({
+		sqlClientLayer: v.sqlClientLayer,
+		runnerStorage: v.runnerStorage,
+		runnerListenPort: e,
+		...t && t.length > 0 ? { extraShardingLayers: t } : {}
+	});
+	h(`cluster workflow engine — ${v.name}`, () => {
+		let o = !1;
+		m(async () => {
+			o = await v.reachable(), o || console.warn(`[skip] cluster suite — ${v.name} not reachable`);
+		}, 1e4), _("a two-step workflow runs end-to-end", async () => {
+			if (!o) return;
+			let e = `clusterTwoStep_${b}`, n = r({
+				name: e,
+				payload: { id: p.String },
+				success: p.Number,
+				idempotencyKey: ({ id: t }) => `${e}:${t}`
+			}), i = n.toLayer(() => u.gen(function* () {
+				let e = yield* t({
+					name: "first",
+					success: p.Number,
+					execute: u.succeed(40)
+				});
+				return yield* t({
+					name: "second",
+					success: p.Number,
+					execute: u.succeed(e + 2)
+				});
+			}));
+			g(await u.runPromise(u.scoped(n.execute({ id: `e2e-${b}` }).pipe(u.provide(i.pipe(f.provideMerge(x(v.runnerPort)))))))).toBe(42);
+		}, 3e4), _("idempotency-key journal — same payload returns same result", async () => {
+			if (!o) return;
+			let e = `clusterIdempotency_${b}`, n = 0, i = r({
+				name: e,
+				payload: { id: p.String },
+				success: p.Number,
+				idempotencyKey: ({ id: t }) => `${e}:${t}`
+			}), a = i.toLayer(() => t({
+				name: "compute",
+				success: p.Number,
+				execute: u.sync(() => (n++, n * 100))
+			})).pipe(f.provideMerge(x(v.runnerPort))), [s, c] = await u.runPromise(u.scoped(u.gen(function* () {
+				return [yield* i.execute({ id: `same-${b}` }), yield* i.execute({ id: `same-${b}` })];
+			}).pipe(u.provide(a))));
+			g(s).toBe(c), g(n).toBe(1);
+		}, 3e4), _("ClusterCron fires its execute on the shard owner", async () => {
+			if (!o) return;
+			let e = await u.runPromise(l.make()), t = 0, n = s({
+				name: `clusterCron_${b}`,
+				cron: c.unsafeParse("*/1 * * * * *", "UTC"),
+				execute: async () => {
+					t += 1, await u.runPromise(l.succeed(e, !0)).catch(() => {});
+				}
+			});
+			g(await u.runPromise(u.scoped(u.gen(function* () {
+				return yield* f.build(x(v.runnerPort + 1, [n])), yield* l.await(e).pipe(u.timeout("25 seconds"), u.orElseSucceed(() => !1));
+			})))).toBe(!0), g(t).toBeGreaterThanOrEqual(1);
+		}, 35e3), _.runIf(v.clusterResume)("a sleeping workflow resumes on a fresh runner after the first is torn down", async () => {
+			if (!o) return;
+			let e = `dormancyResume_${b}`, i = [], a = [], s = () => r({
+				name: e,
+				payload: { id: p.String },
+				success: p.String,
+				idempotencyKey: ({ id: t }) => `${e}:${t}`
+			}), c = (e, r) => e.toLayer(() => u.gen(function* () {
+				return yield* t({
+					name: "step1",
+					success: p.Void,
+					execute: u.sync(() => {
+						i.push(r);
+					})
+				}), yield* n({
+					name: "nap",
+					duration: "30 seconds"
+				}), yield* t({
+					name: "step2",
+					success: p.Void,
+					execute: u.sync(() => {
+						a.push(r);
+					})
+				}), "done";
+			})), l = v.runnerPort + 2, m = (e) => {
+				let t = s();
+				return {
+					wf: t,
+					layer: c(t, e).pipe(f.provideMerge(x(l)))
+				};
+			}, h = { id: `resume-${b}` }, _ = await u.runPromise(u.scoped(u.gen(function* () {
+				let { wf: e, layer: t } = m("A"), n = yield* f.build(t), r = yield* u.forkDaemon(e.execute(h).pipe(u.provide(n), u.ignore));
+				return (yield* y(() => i.length > 0, 6e4)) ? (yield* u.sleep("1 second"), r) : yield* u.die(/* @__PURE__ */ Error("runner A never executed step1"));
+			})));
+			await u.runPromise(d.interrupt(_).pipe(u.ignore)), g(i).toEqual(["A"]), g(a).toEqual([]), g(await u.runPromise(u.scoped(u.gen(function* () {
+				let { wf: e, layer: t } = m("B"), n = yield* f.build(t);
+				return yield* e.execute(h).pipe(u.provide(n), u.timeout("45 seconds"), u.orElseSucceed(() => "TIMEOUT"));
+			})))).toBe("done"), g(i).toEqual(["A"]), g(a).toEqual(["B"]);
+		}, 12e4), _.runIf(v.clusterResume)("dormancy loop: a wake signal survives teardown and is cleared on resume", async () => {
+			if (!o) return;
+			let s = `dormancyLoop_${b}`, c = `wr_${s}`, l = [], m = /* @__PURE__ */ new Map(), h = a({
+				store: {
+					insert: async (e, t) => t,
+					update: async () => null,
+					query: async () => []
+				},
+				wakeups: {
+					register: async (e, t) => {
+						m.set(e, { wakeAt: t });
+					},
+					cancel: async (e) => {
+						m.delete(e);
+					}
+				}
+			}), _ = () => r({
+				name: s,
+				payload: { id: p.String },
+				success: p.String,
+				idempotencyKey: ({ id: e }) => `${s}:${e}`
+			}), S = (r, a) => r.toLayer(() => u.gen(function* () {
+				return yield* t({
+					name: "step1",
+					success: p.Void,
+					execute: u.void
+				}), yield* n({
+					name: "nap",
+					duration: "30 seconds"
+				}), yield* t({
+					name: "step2",
+					success: p.Void,
+					execute: u.sync(() => {
+						l.push(a);
+					})
+				}), "done";
+			}).pipe(u.locally(i, c), u.provideService(e, h))), C = v.runnerPort + 2, w = (e) => {
+				let t = _();
+				return {
+					wf: t,
+					layer: S(t, e).pipe(f.provideMerge(x(C)))
+				};
+			}, T = { id: `loop-${b}` }, E = await u.runPromise(u.scoped(u.gen(function* () {
+				let { wf: e, layer: t } = w("A"), n = yield* f.build(t), r = yield* u.forkDaemon(e.execute(T).pipe(u.provide(n), u.ignore));
+				return (yield* y(() => m.has(c), 6e4)) ? (yield* u.sleep("1 second"), r) : yield* u.die(/* @__PURE__ */ Error("workflow never registered a wakeup"));
+			})));
+			await u.runPromise(d.interrupt(E).pipe(u.ignore)), g(m.has(c)).toBe(!0), g(l).toEqual([]), g(await u.runPromise(u.scoped(u.gen(function* () {
+				let { wf: e, layer: t } = w("B"), n = yield* f.build(t);
+				return yield* e.execute(T).pipe(u.provide(n), u.timeout("45 seconds"), u.orElseSucceed(() => "TIMEOUT"));
+			})))).toBe("done"), g(l).toEqual(["B"]), g(m.has(c)).toBe(!1);
+		}, 12e4);
+	});
+};
+//#endregion
+export { b as runClusterEngineSuite, v as tcpReachable };