@marianmeres/workflow 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +240 -0
- package/API.md +529 -0
- package/CLAUDE.md +3 -0
- package/LICENSE +21 -0
- package/README.md +227 -0
- package/dist/correlator.d.ts +56 -0
- package/dist/correlator.js +144 -0
- package/dist/definition.d.ts +20 -0
- package/dist/definition.js +109 -0
- package/dist/driver.d.ts +71 -0
- package/dist/driver.js +298 -0
- package/dist/log.d.ts +3 -0
- package/dist/log.js +3 -0
- package/dist/migrations/1_0_0.d.ts +8 -0
- package/dist/migrations/1_0_0.js +86 -0
- package/dist/migrations/index.d.ts +22 -0
- package/dist/migrations/index.js +60 -0
- package/dist/mod.d.ts +46 -0
- package/dist/mod.js +46 -0
- package/dist/persistence/history.d.ts +26 -0
- package/dist/persistence/history.js +33 -0
- package/dist/persistence/inbox.d.ts +23 -0
- package/dist/persistence/inbox.js +37 -0
- package/dist/persistence/instances.d.ts +50 -0
- package/dist/persistence/instances.js +112 -0
- package/dist/persistence/tx.d.ts +6 -0
- package/dist/persistence/tx.js +25 -0
- package/dist/registry.d.ts +36 -0
- package/dist/registry.js +78 -0
- package/dist/scheduler.d.ts +49 -0
- package/dist/scheduler.js +67 -0
- package/dist/types.d.ts +155 -0
- package/dist/types.js +33 -0
- package/dist/workflow.d.ts +82 -0
- package/dist/workflow.js +129 -0
- package/package.json +39 -0
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
const SELECT_COLUMNS = `
|
|
2
|
+
id, project_id, received_at, source, correlation_token, payload, processed_at
|
|
3
|
+
`;
|
|
4
|
+
/**
|
|
5
|
+
* Inserts an external signal into `__workflow_inbox`. The correlator will
|
|
6
|
+
* pick it up on its next tick and attempt to match it to a waiting instance.
|
|
7
|
+
*/
|
|
8
|
+
export async function appendInbox(exec, input) {
|
|
9
|
+
const r = await exec.query(`INSERT INTO __workflow_inbox (project_id, source, correlation_token, payload)
|
|
10
|
+
VALUES ($1, $2, $3, $4::jsonb)
|
|
11
|
+
RETURNING ${SELECT_COLUMNS}`, [
|
|
12
|
+
input.project_id,
|
|
13
|
+
input.source,
|
|
14
|
+
input.correlation_token,
|
|
15
|
+
JSON.stringify(input.payload),
|
|
16
|
+
]);
|
|
17
|
+
return r.rows[0];
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Claims a batch of unprocessed inbox rows for the project. Uses
|
|
21
|
+
* `FOR UPDATE SKIP LOCKED` so two concurrent correlator workers don't grab
|
|
22
|
+
* the same row. Caller MUST be inside a transaction and either mark them
|
|
23
|
+
* processed or roll back.
|
|
24
|
+
*/
|
|
25
|
+
export async function claimUnprocessed(client, project_id, limit = 100) {
|
|
26
|
+
const r = await client.query(`SELECT ${SELECT_COLUMNS} FROM __workflow_inbox
|
|
27
|
+
WHERE project_id = $1
|
|
28
|
+
AND processed_at IS NULL
|
|
29
|
+
ORDER BY received_at
|
|
30
|
+
LIMIT $2
|
|
31
|
+
FOR UPDATE SKIP LOCKED`, [project_id, limit]);
|
|
32
|
+
return r.rows;
|
|
33
|
+
}
|
|
34
|
+
/** Marks an inbox row as processed (sets `processed_at = now()`). */
|
|
35
|
+
export async function markProcessed(exec, id) {
|
|
36
|
+
await exec.query(`UPDATE __workflow_inbox SET processed_at = now() WHERE id = $1`, [id]);
|
|
37
|
+
}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import type pg from "pg";
|
|
2
|
+
import { type ExecutionState, type WorkflowContext, type WorkflowInstanceRow } from "../types.js";
|
|
3
|
+
type Executor = pg.Pool | pg.PoolClient | pg.Client;
|
|
4
|
+
/**
|
|
5
|
+
* Inserts a new workflow instance row in `execution_state='pending'` at the
|
|
6
|
+
* provided cursor (typically `def.fsm.initial`). Caller is responsible for
|
|
7
|
+
* enqueuing the first `workflow.advance` job.
|
|
8
|
+
*/
|
|
9
|
+
export declare function createInstance(exec: Executor, input: {
|
|
10
|
+
project_id: string;
|
|
11
|
+
definition_id: string;
|
|
12
|
+
definition_version: string;
|
|
13
|
+
cursor: string;
|
|
14
|
+
context: WorkflowContext;
|
|
15
|
+
correlation_token?: string | null;
|
|
16
|
+
}): Promise<WorkflowInstanceRow>;
|
|
17
|
+
/** Reads a workflow instance by id, or `null` if not found. No lock. */
|
|
18
|
+
export declare function findInstance(exec: Executor, id: string): Promise<WorkflowInstanceRow | null>;
|
|
19
|
+
/** Loads with a row-level lock — caller MUST be inside a transaction. */
|
|
20
|
+
export declare function lockInstance(client: pg.PoolClient | pg.Client, id: string): Promise<WorkflowInstanceRow | null>;
|
|
21
|
+
/**
|
|
22
|
+
* Partial-update of a workflow instance row. Only fields present in `patch`
|
|
23
|
+
* are written; `updated_at` is bumped automatically.
|
|
24
|
+
*/
|
|
25
|
+
export declare function updateInstance(exec: Executor, id: string, patch: {
|
|
26
|
+
cursor?: string;
|
|
27
|
+
previous_cursor?: string | null;
|
|
28
|
+
context?: WorkflowContext;
|
|
29
|
+
execution_state?: ExecutionState;
|
|
30
|
+
wake_at?: Date | null;
|
|
31
|
+
correlation_token?: string | null;
|
|
32
|
+
}): Promise<WorkflowInstanceRow>;
|
|
33
|
+
/**
|
|
34
|
+
* Atomically transitions waiting+due rows to `pending` and clears their
|
|
35
|
+
* `wake_at`. Returns the ids of rows that flipped — caller dispatches advance
|
|
36
|
+
* jobs for each.
|
|
37
|
+
*
|
|
38
|
+
* Atomic on the row so two concurrent scheduler ticks can't double-dispatch.
|
|
39
|
+
*/
|
|
40
|
+
export declare function claimDueWakeUps(exec: Executor, project_id: string, limit?: number): Promise<Array<{
|
|
41
|
+
id: string;
|
|
42
|
+
correlation_token: string | null;
|
|
43
|
+
}>>;
|
|
44
|
+
/**
|
|
45
|
+
* Finds the single waiting instance for this project + correlation token, if any.
|
|
46
|
+
* Used by the inbox correlator. Does not lock (correlator processes one signal
|
|
47
|
+
* at a time inside its own tx).
|
|
48
|
+
*/
|
|
49
|
+
export declare function findWaitingByCorrelation(exec: Executor, project_id: string, correlation_token: string): Promise<WorkflowInstanceRow | null>;
|
|
50
|
+
export {};
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
import { EXECUTION_STATE, } from "../types.js";
|
|
2
|
+
const SELECT_COLUMNS = `
|
|
3
|
+
id, project_id, definition_id, definition_version,
|
|
4
|
+
cursor, previous_cursor, context, execution_state,
|
|
5
|
+
wake_at, correlation_token, created_at, updated_at
|
|
6
|
+
`;
|
|
7
|
+
/**
|
|
8
|
+
* Inserts a new workflow instance row in `execution_state='pending'` at the
|
|
9
|
+
* provided cursor (typically `def.fsm.initial`). Caller is responsible for
|
|
10
|
+
* enqueuing the first `workflow.advance` job.
|
|
11
|
+
*/
|
|
12
|
+
export async function createInstance(exec, input) {
|
|
13
|
+
const r = await exec.query(`INSERT INTO __workflow_instances
|
|
14
|
+
(project_id, definition_id, definition_version, cursor, context, execution_state, correlation_token)
|
|
15
|
+
VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7)
|
|
16
|
+
RETURNING ${SELECT_COLUMNS}`, [
|
|
17
|
+
input.project_id,
|
|
18
|
+
input.definition_id,
|
|
19
|
+
input.definition_version,
|
|
20
|
+
input.cursor,
|
|
21
|
+
JSON.stringify(input.context),
|
|
22
|
+
EXECUTION_STATE.PENDING,
|
|
23
|
+
input.correlation_token ?? null,
|
|
24
|
+
]);
|
|
25
|
+
return r.rows[0];
|
|
26
|
+
}
|
|
27
|
+
/** Reads a workflow instance by id, or `null` if not found. No lock. */
|
|
28
|
+
export async function findInstance(exec, id) {
|
|
29
|
+
const r = await exec.query(`SELECT ${SELECT_COLUMNS} FROM __workflow_instances WHERE id = $1`, [id]);
|
|
30
|
+
return r.rows[0] ?? null;
|
|
31
|
+
}
|
|
32
|
+
/** Loads with a row-level lock — caller MUST be inside a transaction. */
|
|
33
|
+
export async function lockInstance(client, id) {
|
|
34
|
+
const r = await client.query(`SELECT ${SELECT_COLUMNS} FROM __workflow_instances WHERE id = $1 FOR UPDATE`, [id]);
|
|
35
|
+
return r.rows[0] ?? null;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Partial-update of a workflow instance row. Only fields present in `patch`
|
|
39
|
+
* are written; `updated_at` is bumped automatically.
|
|
40
|
+
*/
|
|
41
|
+
export async function updateInstance(exec, id, patch) {
|
|
42
|
+
const sets = [];
|
|
43
|
+
const values = [];
|
|
44
|
+
let i = 1;
|
|
45
|
+
if (patch.cursor !== undefined) {
|
|
46
|
+
sets.push(`cursor = $${i++}`);
|
|
47
|
+
values.push(patch.cursor);
|
|
48
|
+
}
|
|
49
|
+
if (patch.previous_cursor !== undefined) {
|
|
50
|
+
sets.push(`previous_cursor = $${i++}`);
|
|
51
|
+
values.push(patch.previous_cursor);
|
|
52
|
+
}
|
|
53
|
+
if (patch.context !== undefined) {
|
|
54
|
+
sets.push(`context = $${i++}::jsonb`);
|
|
55
|
+
values.push(JSON.stringify(patch.context));
|
|
56
|
+
}
|
|
57
|
+
if (patch.execution_state !== undefined) {
|
|
58
|
+
sets.push(`execution_state = $${i++}`);
|
|
59
|
+
values.push(patch.execution_state);
|
|
60
|
+
}
|
|
61
|
+
if (patch.wake_at !== undefined) {
|
|
62
|
+
sets.push(`wake_at = $${i++}`);
|
|
63
|
+
values.push(patch.wake_at);
|
|
64
|
+
}
|
|
65
|
+
if (patch.correlation_token !== undefined) {
|
|
66
|
+
sets.push(`correlation_token = $${i++}`);
|
|
67
|
+
values.push(patch.correlation_token);
|
|
68
|
+
}
|
|
69
|
+
sets.push(`updated_at = now()`);
|
|
70
|
+
values.push(id);
|
|
71
|
+
const r = await exec.query(`UPDATE __workflow_instances SET ${sets.join(", ")} WHERE id = $${i}
|
|
72
|
+
RETURNING ${SELECT_COLUMNS}`, values);
|
|
73
|
+
return r.rows[0];
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Atomically transitions waiting+due rows to `pending` and clears their
|
|
77
|
+
* `wake_at`. Returns the ids of rows that flipped — caller dispatches advance
|
|
78
|
+
* jobs for each.
|
|
79
|
+
*
|
|
80
|
+
* Atomic on the row so two concurrent scheduler ticks can't double-dispatch.
|
|
81
|
+
*/
|
|
82
|
+
export async function claimDueWakeUps(exec, project_id, limit = 100) {
|
|
83
|
+
const r = await exec.query(`UPDATE __workflow_instances
|
|
84
|
+
SET execution_state = $2,
|
|
85
|
+
wake_at = NULL,
|
|
86
|
+
updated_at = now()
|
|
87
|
+
WHERE id IN (
|
|
88
|
+
SELECT id FROM __workflow_instances
|
|
89
|
+
WHERE project_id = $1
|
|
90
|
+
AND execution_state = $3
|
|
91
|
+
AND wake_at IS NOT NULL
|
|
92
|
+
AND wake_at <= now()
|
|
93
|
+
ORDER BY wake_at
|
|
94
|
+
LIMIT $4
|
|
95
|
+
FOR UPDATE SKIP LOCKED
|
|
96
|
+
)
|
|
97
|
+
RETURNING id, correlation_token`, [project_id, EXECUTION_STATE.PENDING, EXECUTION_STATE.WAITING, limit]);
|
|
98
|
+
return r.rows;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Finds the single waiting instance for this project + correlation token, if any.
|
|
102
|
+
* Used by the inbox correlator. Does not lock (correlator processes one signal
|
|
103
|
+
* at a time inside its own tx).
|
|
104
|
+
*/
|
|
105
|
+
export async function findWaitingByCorrelation(exec, project_id, correlation_token) {
|
|
106
|
+
const r = await exec.query(`SELECT ${SELECT_COLUMNS} FROM __workflow_instances
|
|
107
|
+
WHERE project_id = $1
|
|
108
|
+
AND execution_state = $2
|
|
109
|
+
AND correlation_token = $3
|
|
110
|
+
LIMIT 1`, [project_id, EXECUTION_STATE.WAITING, correlation_token]);
|
|
111
|
+
return r.rows[0] ?? null;
|
|
112
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type pg from "pg";
|
|
2
|
+
/**
|
|
3
|
+
* Runs `fn` inside a single PG transaction on a checked-out client.
|
|
4
|
+
* Commits on resolve, rolls back on throw. Always releases the client.
|
|
5
|
+
*/
|
|
6
|
+
export declare function withTransaction<T>(pool: pg.Pool, fn: (client: pg.PoolClient) => Promise<T>): Promise<T>;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Runs `fn` inside a single PG transaction on a checked-out client.
|
|
3
|
+
* Commits on resolve, rolls back on throw. Always releases the client.
|
|
4
|
+
*/
|
|
5
|
+
export async function withTransaction(pool, fn) {
|
|
6
|
+
const client = await pool.connect();
|
|
7
|
+
try {
|
|
8
|
+
await client.query("BEGIN");
|
|
9
|
+
const result = await fn(client);
|
|
10
|
+
await client.query("COMMIT");
|
|
11
|
+
return result;
|
|
12
|
+
}
|
|
13
|
+
catch (err) {
|
|
14
|
+
try {
|
|
15
|
+
await client.query("ROLLBACK");
|
|
16
|
+
}
|
|
17
|
+
catch {
|
|
18
|
+
// rollback best-effort; surface the original error
|
|
19
|
+
}
|
|
20
|
+
throw err;
|
|
21
|
+
}
|
|
22
|
+
finally {
|
|
23
|
+
client.release();
|
|
24
|
+
}
|
|
25
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import type { Handler, Matcher, WorkflowDefinition } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* In-memory registry of definitions, handlers, and matchers. Built once at
|
|
4
|
+
* startup; immutable after construction (use `Workflow`'s constructor).
|
|
5
|
+
*
|
|
6
|
+
* Definitions are keyed by `<id>@<version>` — pin-and-freeze: each instance
|
|
7
|
+
* runs on its birth-version forever. Keep old versions in code until the last
|
|
8
|
+
* instance using them completes.
|
|
9
|
+
*/
|
|
10
|
+
export declare class WorkflowRegistry {
|
|
11
|
+
#private;
|
|
12
|
+
/**
|
|
13
|
+
* Validates and stores definitions, handlers, and matchers. Throws on the
|
|
14
|
+
* first structural problem (unknown handler, unknown transition target,
|
|
15
|
+
* missing meta, etc.) or on duplicate `(id, version)` registration.
|
|
16
|
+
*/
|
|
17
|
+
constructor(input: {
|
|
18
|
+
definitions: WorkflowDefinition[];
|
|
19
|
+
handlers: Record<string, Handler>;
|
|
20
|
+
matchers?: Record<string, Matcher>;
|
|
21
|
+
});
|
|
22
|
+
/** Looks up a definition by `(id, version)`. Returns `undefined` if not registered. */
|
|
23
|
+
getDefinition(id: string, version: string): WorkflowDefinition | undefined;
|
|
24
|
+
/** Like {@link getDefinition} but throws if the definition is not registered. */
|
|
25
|
+
requireDefinition(id: string, version: string): WorkflowDefinition;
|
|
26
|
+
/** Looks up a registered handler by name. Returns `undefined` if missing. */
|
|
27
|
+
getHandler(name: string): Handler | undefined;
|
|
28
|
+
/** Like {@link getHandler} but throws if the handler is not registered. */
|
|
29
|
+
requireHandler(name: string): Handler;
|
|
30
|
+
/** Looks up a registered matcher by name. Returns `undefined` if missing. */
|
|
31
|
+
getMatcher(name: string): Matcher | undefined;
|
|
32
|
+
/** Like {@link getMatcher} but throws if the matcher is not registered. */
|
|
33
|
+
requireMatcher(name: string): Matcher;
|
|
34
|
+
/** List of all registered handler names. Stable order not guaranteed. */
|
|
35
|
+
handlerNames(): string[];
|
|
36
|
+
}
|
package/dist/registry.js
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import { defKey, validateDefinition } from "./definition.js";
|
|
2
|
+
/**
|
|
3
|
+
* In-memory registry of definitions, handlers, and matchers. Built once at
|
|
4
|
+
* startup; immutable after construction (use `Workflow`'s constructor).
|
|
5
|
+
*
|
|
6
|
+
* Definitions are keyed by `<id>@<version>` — pin-and-freeze: each instance
|
|
7
|
+
* runs on its birth-version forever. Keep old versions in code until the last
|
|
8
|
+
* instance using them completes.
|
|
9
|
+
*/
|
|
10
|
+
export class WorkflowRegistry {
|
|
11
|
+
#definitions = new Map();
|
|
12
|
+
#handlers = new Map();
|
|
13
|
+
#matchers = new Map();
|
|
14
|
+
/**
|
|
15
|
+
* Validates and stores definitions, handlers, and matchers. Throws on the
|
|
16
|
+
* first structural problem (unknown handler, unknown transition target,
|
|
17
|
+
* missing meta, etc.) or on duplicate `(id, version)` registration.
|
|
18
|
+
*/
|
|
19
|
+
constructor(input) {
|
|
20
|
+
for (const [name, fn] of Object.entries(input.handlers)) {
|
|
21
|
+
this.#handlers.set(name, fn);
|
|
22
|
+
}
|
|
23
|
+
for (const [name, fn] of Object.entries(input.matchers ?? {})) {
|
|
24
|
+
this.#matchers.set(name, fn);
|
|
25
|
+
}
|
|
26
|
+
const handlerNames = new Set(this.#handlers.keys());
|
|
27
|
+
const matcherNames = new Set(this.#matchers.keys());
|
|
28
|
+
for (const def of input.definitions) {
|
|
29
|
+
validateDefinition(def, {
|
|
30
|
+
handlers: handlerNames,
|
|
31
|
+
matchers: matcherNames,
|
|
32
|
+
});
|
|
33
|
+
const key = defKey(def.id, def.version);
|
|
34
|
+
if (this.#definitions.has(key)) {
|
|
35
|
+
throw new Error(`Workflow definition already registered: ${key}`);
|
|
36
|
+
}
|
|
37
|
+
this.#definitions.set(key, def);
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
/** Looks up a definition by `(id, version)`. Returns `undefined` if not registered. */
|
|
41
|
+
getDefinition(id, version) {
|
|
42
|
+
return this.#definitions.get(defKey(id, version));
|
|
43
|
+
}
|
|
44
|
+
/** Like {@link getDefinition} but throws if the definition is not registered. */
|
|
45
|
+
requireDefinition(id, version) {
|
|
46
|
+
const def = this.getDefinition(id, version);
|
|
47
|
+
if (!def) {
|
|
48
|
+
throw new Error(`Unknown workflow definition: ${defKey(id, version)}`);
|
|
49
|
+
}
|
|
50
|
+
return def;
|
|
51
|
+
}
|
|
52
|
+
/** Looks up a registered handler by name. Returns `undefined` if missing. */
|
|
53
|
+
getHandler(name) {
|
|
54
|
+
return this.#handlers.get(name);
|
|
55
|
+
}
|
|
56
|
+
/** Like {@link getHandler} but throws if the handler is not registered. */
|
|
57
|
+
requireHandler(name) {
|
|
58
|
+
const h = this.#handlers.get(name);
|
|
59
|
+
if (!h)
|
|
60
|
+
throw new Error(`Unregistered handler: "${name}"`);
|
|
61
|
+
return h;
|
|
62
|
+
}
|
|
63
|
+
/** Looks up a registered matcher by name. Returns `undefined` if missing. */
|
|
64
|
+
getMatcher(name) {
|
|
65
|
+
return this.#matchers.get(name);
|
|
66
|
+
}
|
|
67
|
+
/** Like {@link getMatcher} but throws if the matcher is not registered. */
|
|
68
|
+
requireMatcher(name) {
|
|
69
|
+
const m = this.#matchers.get(name);
|
|
70
|
+
if (!m)
|
|
71
|
+
throw new Error(`Unregistered matcher: "${name}"`);
|
|
72
|
+
return m;
|
|
73
|
+
}
|
|
74
|
+
/** List of all registered handler names. Stable order not guaranteed. */
|
|
75
|
+
handlerNames() {
|
|
76
|
+
return [...this.#handlers.keys()];
|
|
77
|
+
}
|
|
78
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import type { Cron } from "@marianmeres/cron";
|
|
2
|
+
import type { Workflow } from "./workflow.js";
|
|
3
|
+
/** Options accepted by {@link WorkflowScheduler}. */
|
|
4
|
+
export interface WorkflowSchedulerOptions {
|
|
5
|
+
/**
|
|
6
|
+
* Externally-owned `@marianmeres/cron` `Cron` instance. The scheduler
|
|
7
|
+
* registers its tick handler on this instance when `register()` is called.
|
|
8
|
+
* The consumer owns the lifecycle: `await cron.start(N)` / `await cron.stop()`.
|
|
9
|
+
*/
|
|
10
|
+
cron: Cron;
|
|
11
|
+
/** The Workflow whose instances this scheduler wakes (used for `db`, `projectId`, `enqueueAdvance`). */
|
|
12
|
+
workflow: Workflow;
|
|
13
|
+
/** Cron expression for the tick. Default: every minute. */
|
|
14
|
+
tickExpression?: string;
|
|
15
|
+
/** IANA timezone for the cron expression. */
|
|
16
|
+
timezone?: string | null;
|
|
17
|
+
/** Maximum number of due rows claimed per tick. Default: 100. */
|
|
18
|
+
tickBatchSize?: number;
|
|
19
|
+
/** Custom name for the registered cron job. Default: `workflow.scheduler.<projectId>`. */
|
|
20
|
+
tickName?: string;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Cron-driven scheduler that wakes time-suspended workflow instances.
|
|
24
|
+
*
|
|
25
|
+
* On each tick it atomically flips waiting+due rows to `pending` (clearing
|
|
26
|
+
* their `wake_at`) and dispatches a `workflow.advance` job for each, carrying
|
|
27
|
+
* `outcome: 'TIMEOUT'`.
|
|
28
|
+
*
|
|
29
|
+
* The scheduler does not own its `Cron`. The caller constructs a `Cron`, passes
|
|
30
|
+
* it in, and runs its lifecycle (`start` / `stop`). Call `register()` once
|
|
31
|
+
* after construction to attach the tick; `unregister()` to detach.
|
|
32
|
+
*/
|
|
33
|
+
export declare class WorkflowScheduler {
|
|
34
|
+
#private;
|
|
35
|
+
readonly cron: Cron;
|
|
36
|
+
readonly projectId: string;
|
|
37
|
+
readonly tickExpression: string;
|
|
38
|
+
readonly tickName: string;
|
|
39
|
+
constructor(options: WorkflowSchedulerOptions);
|
|
40
|
+
/**
|
|
41
|
+
* Registers the tick on the injected `Cron`. Idempotent — re-registering an
|
|
42
|
+
* existing name updates the expression/options but preserves `next_run_at`.
|
|
43
|
+
*/
|
|
44
|
+
register(): Promise<void>;
|
|
45
|
+
/** Removes the tick from the injected `Cron`. */
|
|
46
|
+
unregister(): Promise<void>;
|
|
47
|
+
/** Runs one tick immediately. Exposed for testing and on-demand wakes. */
|
|
48
|
+
tickOnce(): Promise<number>;
|
|
49
|
+
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { clog } from "./log.js";
|
|
2
|
+
import { claimDueWakeUps } from "./persistence/instances.js";
|
|
3
|
+
const DEFAULT_TICK_EXPRESSION = "* * * * *";
|
|
4
|
+
/**
|
|
5
|
+
* Cron-driven scheduler that wakes time-suspended workflow instances.
|
|
6
|
+
*
|
|
7
|
+
* On each tick it atomically flips waiting+due rows to `pending` (clearing
|
|
8
|
+
* their `wake_at`) and dispatches a `workflow.advance` job for each, carrying
|
|
9
|
+
* `outcome: 'TIMEOUT'`.
|
|
10
|
+
*
|
|
11
|
+
* The scheduler does not own its `Cron`. The caller constructs a `Cron`, passes
|
|
12
|
+
* it in, and runs its lifecycle (`start` / `stop`). Call `register()` once
|
|
13
|
+
* after construction to attach the tick; `unregister()` to detach.
|
|
14
|
+
*/
|
|
15
|
+
export class WorkflowScheduler {
|
|
16
|
+
cron;
|
|
17
|
+
projectId;
|
|
18
|
+
tickExpression;
|
|
19
|
+
tickName;
|
|
20
|
+
#workflow;
|
|
21
|
+
#tickBatchSize;
|
|
22
|
+
#timezone;
|
|
23
|
+
constructor(options) {
|
|
24
|
+
this.cron = options.cron;
|
|
25
|
+
this.#workflow = options.workflow;
|
|
26
|
+
this.projectId = options.workflow.projectId;
|
|
27
|
+
this.tickExpression = options.tickExpression ?? DEFAULT_TICK_EXPRESSION;
|
|
28
|
+
this.tickName = options.tickName ?? `workflow.scheduler.${this.projectId}`;
|
|
29
|
+
this.#tickBatchSize = options.tickBatchSize ?? 100;
|
|
30
|
+
this.#timezone = options.timezone;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Registers the tick on the injected `Cron`. Idempotent — re-registering an
|
|
34
|
+
* existing name updates the expression/options but preserves `next_run_at`.
|
|
35
|
+
*/
|
|
36
|
+
async register() {
|
|
37
|
+
await this.cron.register(this.tickName, this.tickExpression, async () => {
|
|
38
|
+
await this.#tick();
|
|
39
|
+
}, {
|
|
40
|
+
timezone: this.#timezone,
|
|
41
|
+
});
|
|
42
|
+
}
|
|
43
|
+
/** Removes the tick from the injected `Cron`. */
|
|
44
|
+
async unregister() {
|
|
45
|
+
await this.cron.unregister(this.tickName);
|
|
46
|
+
}
|
|
47
|
+
/** Runs one tick immediately. Exposed for testing and on-demand wakes. */
|
|
48
|
+
async tickOnce() {
|
|
49
|
+
return await this.#tick();
|
|
50
|
+
}
|
|
51
|
+
async #tick() {
|
|
52
|
+
const claimed = await claimDueWakeUps(this.#workflow.db, this.projectId, this.#tickBatchSize);
|
|
53
|
+
if (claimed.length === 0)
|
|
54
|
+
return 0;
|
|
55
|
+
clog.debug?.(`scheduler: claimed ${claimed.length} due wake-ups`);
|
|
56
|
+
for (const row of claimed) {
|
|
57
|
+
const payload = {
|
|
58
|
+
project_id: this.projectId,
|
|
59
|
+
instance_id: row.id,
|
|
60
|
+
timeout: true,
|
|
61
|
+
outcome: "TIMEOUT",
|
|
62
|
+
};
|
|
63
|
+
await this.#workflow.enqueueAdvance(this.#workflow.db, payload);
|
|
64
|
+
}
|
|
65
|
+
return claimed.length;
|
|
66
|
+
}
|
|
67
|
+
}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
import type { FSMConfig, FSMSnapshot } from "@marianmeres/fsm";
|
|
2
|
+
/**
|
|
3
|
+
* Default project id used when none is supplied. Mirrors the convention from
|
|
4
|
+
* `@marianmeres/cron`.
|
|
5
|
+
*/
|
|
6
|
+
export declare const DEFAULT_PROJECT_ID = "_default";
|
|
7
|
+
/** Execution-lifecycle states. Independent of the FSM cursor. */
|
|
8
|
+
export declare const EXECUTION_STATE: {
|
|
9
|
+
readonly PENDING: "pending";
|
|
10
|
+
readonly RUNNING: "running";
|
|
11
|
+
readonly WAITING: "waiting";
|
|
12
|
+
readonly COMPLETED: "completed";
|
|
13
|
+
readonly FAILED: "failed";
|
|
14
|
+
readonly CANCELLED: "cancelled";
|
|
15
|
+
};
|
|
16
|
+
/** Union of all valid {@link EXECUTION_STATE} string values. */
|
|
17
|
+
export type ExecutionState = (typeof EXECUTION_STATE)[keyof typeof EXECUTION_STATE];
|
|
18
|
+
/** Per-node metadata stored on each FSM state's `meta` field. Discriminated by `kind`. */
|
|
19
|
+
export type NodeMeta = {
|
|
20
|
+
kind: "pure";
|
|
21
|
+
} | {
|
|
22
|
+
kind: "effectful";
|
|
23
|
+
handler: string;
|
|
24
|
+
} | {
|
|
25
|
+
kind: "suspending";
|
|
26
|
+
matcher?: string;
|
|
27
|
+
timeoutSec?: number;
|
|
28
|
+
} | {
|
|
29
|
+
kind: "terminal";
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* Context carried by a workflow instance. Plain JSON. Accumulates across nodes.
|
|
33
|
+
*/
|
|
34
|
+
export type WorkflowContext = Record<string, unknown>;
|
|
35
|
+
/**
|
|
36
|
+
* A workflow definition: pure, JSON-serializable data. The fsm config carries
|
|
37
|
+
* per-state {@link NodeMeta} on its `meta` field; the driver dispatches on
|
|
38
|
+
* `meta.kind`. Outcome labels are fsm events.
|
|
39
|
+
*/
|
|
40
|
+
export interface WorkflowDefinition<TState extends string = string, TEvent extends string = string> {
|
|
41
|
+
id: string;
|
|
42
|
+
version: string;
|
|
43
|
+
fsm: FSMConfig<TState, TEvent, WorkflowContext>;
|
|
44
|
+
}
|
|
45
|
+
/** Result returned by an effectful node's handler. */
|
|
46
|
+
export interface HandlerResult {
|
|
47
|
+
outcome: string;
|
|
48
|
+
data?: Record<string, unknown>;
|
|
49
|
+
}
|
|
50
|
+
/** Arguments passed to an effectful handler. */
|
|
51
|
+
export interface HandlerArgs {
|
|
52
|
+
instanceId: string;
|
|
53
|
+
projectId: string;
|
|
54
|
+
context: WorkflowContext;
|
|
55
|
+
signal?: AbortSignal;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Userland effect-handler signature. Referenced from a node's
|
|
59
|
+
* `meta.handler` by string id. Must return `{ outcome, data? }` — the
|
|
60
|
+
* `outcome` label drives the next FSM transition. Handlers must be
|
|
61
|
+
* idempotent (steve may retry them after worker crashes).
|
|
62
|
+
*/
|
|
63
|
+
export type Handler = (args: HandlerArgs) => Promise<HandlerResult> | HandlerResult;
|
|
64
|
+
/** Arguments passed to a matcher predicate. */
|
|
65
|
+
export interface MatcherArgs {
|
|
66
|
+
instanceId: string;
|
|
67
|
+
projectId: string;
|
|
68
|
+
context: WorkflowContext;
|
|
69
|
+
signal: InboxRow;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Userland signal-matcher signature. Referenced from a suspending node's
|
|
73
|
+
* `meta.matcher` by string id. Returns true if the incoming inbox signal
|
|
74
|
+
* belongs to this waiting instance. The correlation token is just the
|
|
75
|
+
* index — the matcher is the semantic gate.
|
|
76
|
+
*/
|
|
77
|
+
export type Matcher = (args: MatcherArgs) => boolean | Promise<boolean>;
|
|
78
|
+
/** A single row from `__workflow_instances`. Matches the schema 1:1. */
|
|
79
|
+
export interface WorkflowInstanceRow {
|
|
80
|
+
id: string;
|
|
81
|
+
project_id: string;
|
|
82
|
+
definition_id: string;
|
|
83
|
+
definition_version: string;
|
|
84
|
+
cursor: string;
|
|
85
|
+
previous_cursor: string | null;
|
|
86
|
+
context: WorkflowContext;
|
|
87
|
+
execution_state: ExecutionState;
|
|
88
|
+
wake_at: Date | null;
|
|
89
|
+
correlation_token: string | null;
|
|
90
|
+
created_at: Date;
|
|
91
|
+
updated_at: Date;
|
|
92
|
+
}
|
|
93
|
+
/** A single row from `__workflow_inbox`. */
|
|
94
|
+
export interface InboxRow {
|
|
95
|
+
id: string;
|
|
96
|
+
project_id: string;
|
|
97
|
+
received_at: Date;
|
|
98
|
+
source: string;
|
|
99
|
+
correlation_token: string;
|
|
100
|
+
payload: Record<string, unknown>;
|
|
101
|
+
processed_at: Date | null;
|
|
102
|
+
}
|
|
103
|
+
/** Event types recorded in `__workflow_history`. */
|
|
104
|
+
export declare const HISTORY_EVENT: {
|
|
105
|
+
readonly CREATED: "created";
|
|
106
|
+
readonly TRANSITION: "transition";
|
|
107
|
+
readonly EFFECT_DISPATCHED: "effect_dispatched";
|
|
108
|
+
readonly EFFECT_COMPLETED: "effect_completed";
|
|
109
|
+
readonly EFFECT_FAILED: "effect_failed";
|
|
110
|
+
readonly SIGNAL_RECEIVED: "signal_received";
|
|
111
|
+
readonly SIGNAL_REJECTED: "signal_rejected";
|
|
112
|
+
readonly TIMEOUT: "timeout";
|
|
113
|
+
readonly TRANSITION_REJECTED: "transition_rejected";
|
|
114
|
+
readonly COMPLETED: "completed";
|
|
115
|
+
readonly FAILED: "failed";
|
|
116
|
+
readonly CANCELLED: "cancelled";
|
|
117
|
+
};
|
|
118
|
+
/** Union of all valid {@link HISTORY_EVENT} string values. */
|
|
119
|
+
export type HistoryEventType = (typeof HISTORY_EVENT)[keyof typeof HISTORY_EVENT];
|
|
120
|
+
/** A single row from `__workflow_history`. */
|
|
121
|
+
export interface HistoryRow {
|
|
122
|
+
id: number;
|
|
123
|
+
project_id: string;
|
|
124
|
+
instance_id: string;
|
|
125
|
+
at: Date;
|
|
126
|
+
event_type: HistoryEventType;
|
|
127
|
+
from_node: string | null;
|
|
128
|
+
to_node: string | null;
|
|
129
|
+
data: Record<string, unknown>;
|
|
130
|
+
}
|
|
131
|
+
/** Steve job type for "advance this instance one step". */
|
|
132
|
+
export declare const JOB_TYPE_ADVANCE = "workflow.advance";
|
|
133
|
+
/** Steve job-type prefix for effect-handler jobs. Full type is `workflow.effect.<handlerName>`. */
|
|
134
|
+
export declare const JOB_TYPE_EFFECT_PREFIX = "workflow.effect.";
|
|
135
|
+
/** Payload of a `workflow.advance` job. */
|
|
136
|
+
export interface AdvanceJobPayload {
|
|
137
|
+
project_id: string;
|
|
138
|
+
instance_id: string;
|
|
139
|
+
/** Optional outcome label to apply before dispatching. Set when an effect/signal completes. */
|
|
140
|
+
outcome?: string;
|
|
141
|
+
/** Optional payload to merge into context via the outcome's `data` field. */
|
|
142
|
+
outcome_data?: Record<string, unknown>;
|
|
143
|
+
/** Marks this advance as a TIMEOUT wake-up (so the driver emits a TIMEOUT outcome). */
|
|
144
|
+
timeout?: boolean;
|
|
145
|
+
[key: string]: unknown;
|
|
146
|
+
}
|
|
147
|
+
/** Payload of a `workflow.effect.<handlerName>` job. */
|
|
148
|
+
export interface EffectJobPayload {
|
|
149
|
+
project_id: string;
|
|
150
|
+
instance_id: string;
|
|
151
|
+
handler: string;
|
|
152
|
+
[key: string]: unknown;
|
|
153
|
+
}
|
|
154
|
+
/** Convenience re-export — the FSM snapshot shape the driver passes around. */
|
|
155
|
+
export type WorkflowSnapshot = FSMSnapshot<string, WorkflowContext>;
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Default project id used when none is supplied. Mirrors the convention from
|
|
3
|
+
* `@marianmeres/cron`.
|
|
4
|
+
*/
|
|
5
|
+
export const DEFAULT_PROJECT_ID = "_default";
|
|
6
|
+
/** Execution-lifecycle states. Independent of the FSM cursor. */
|
|
7
|
+
export const EXECUTION_STATE = {
|
|
8
|
+
PENDING: "pending",
|
|
9
|
+
RUNNING: "running",
|
|
10
|
+
WAITING: "waiting",
|
|
11
|
+
COMPLETED: "completed",
|
|
12
|
+
FAILED: "failed",
|
|
13
|
+
CANCELLED: "cancelled",
|
|
14
|
+
};
|
|
15
|
+
/** Event types recorded in `__workflow_history`. */
|
|
16
|
+
export const HISTORY_EVENT = {
|
|
17
|
+
CREATED: "created",
|
|
18
|
+
TRANSITION: "transition",
|
|
19
|
+
EFFECT_DISPATCHED: "effect_dispatched",
|
|
20
|
+
EFFECT_COMPLETED: "effect_completed",
|
|
21
|
+
EFFECT_FAILED: "effect_failed",
|
|
22
|
+
SIGNAL_RECEIVED: "signal_received",
|
|
23
|
+
SIGNAL_REJECTED: "signal_rejected",
|
|
24
|
+
TIMEOUT: "timeout",
|
|
25
|
+
TRANSITION_REJECTED: "transition_rejected",
|
|
26
|
+
COMPLETED: "completed",
|
|
27
|
+
FAILED: "failed",
|
|
28
|
+
CANCELLED: "cancelled",
|
|
29
|
+
};
|
|
30
|
+
/** Steve job type for "advance this instance one step". */
|
|
31
|
+
export const JOB_TYPE_ADVANCE = "workflow.advance";
|
|
32
|
+
/** Steve job-type prefix for effect-handler jobs. Full type is `workflow.effect.<handlerName>`. */
|
|
33
|
+
export const JOB_TYPE_EFFECT_PREFIX = "workflow.effect.";
|