@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
package/dist/driver.js
ADDED
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
import { FSM } from "@marianmeres/fsm";
|
|
2
|
+
import { clog } from "./log.js";
|
|
3
|
+
import { appendHistory } from "./persistence/history.js";
|
|
4
|
+
import { lockInstance, updateInstance, } from "./persistence/instances.js";
|
|
5
|
+
import { withTransaction } from "./persistence/tx.js";
|
|
6
|
+
import { EXECUTION_STATE, HISTORY_EVENT, JOB_TYPE_ADVANCE, JOB_TYPE_EFFECT_PREFIX, } from "./types.js";
|
|
7
|
+
/**
|
|
8
|
+
* Synthetic event fired by the driver when entering a pure (decision) state,
|
|
9
|
+
* so the user's guarded transitions can route by inspecting context.
|
|
10
|
+
*
|
|
11
|
+
* Pure nodes typically look like:
|
|
12
|
+
*
|
|
13
|
+
* foo: {
|
|
14
|
+
* meta: { kind: "pure" },
|
|
15
|
+
* on: {
|
|
16
|
+
* ENTER: [
|
|
17
|
+
* { target: "go_left", guard: (ctx) => ctx.x > 5 },
|
|
18
|
+
* { target: "go_right" },
|
|
19
|
+
* ],
|
|
20
|
+
* },
|
|
21
|
+
* }
|
|
22
|
+
*/
|
|
23
|
+
export const PURE_ENTER_EVENT = "ENTER";
|
|
24
|
+
/**
|
|
25
|
+
* Maximum number of inline pure-state hops the driver will take within a
|
|
26
|
+
* single advance before bailing out (loop guard against pathological
|
|
27
|
+
* pure-state cycles).
|
|
28
|
+
*/
|
|
29
|
+
const MAX_PURE_HOPS = 64;
|
|
30
|
+
/**
|
|
31
|
+
* The `workflow.advance` job body.
|
|
32
|
+
*
|
|
33
|
+
* Wrapped in a single PG transaction:
|
|
34
|
+
* 1. Lock the instance row.
|
|
35
|
+
* 2. If in a terminal execution_state, no-op.
|
|
36
|
+
* 3. If `outcome` was supplied, apply it via fsm.transition(outcome, data).
|
|
37
|
+
* - Reject → mark failed, append history.
|
|
38
|
+
* 4. Loop on the current state's meta.kind:
|
|
39
|
+
* - terminal → mark completed, return.
|
|
40
|
+
* - pure → fire `ENTER` synthetic event (with guards) and loop.
|
|
41
|
+
* - effectful → enqueue an effect job + mark running, return.
|
|
42
|
+
* - suspending → mark waiting, set wake_at/correlation_token, return.
|
|
43
|
+
*/
|
|
44
|
+
export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
45
|
+
const { instance_id, project_id, outcome, outcome_data, timeout } = payload;
|
|
46
|
+
await withTransaction(pool, async (client) => {
|
|
47
|
+
const row = await lockInstance(client, instance_id);
|
|
48
|
+
if (!row) {
|
|
49
|
+
clog.warn?.(`advance: instance ${instance_id} not found`);
|
|
50
|
+
return;
|
|
51
|
+
}
|
|
52
|
+
if (row.execution_state === EXECUTION_STATE.COMPLETED ||
|
|
53
|
+
row.execution_state === EXECUTION_STATE.FAILED ||
|
|
54
|
+
row.execution_state === EXECUTION_STATE.CANCELLED) {
|
|
55
|
+
clog.debug?.(`advance: instance ${instance_id} already terminal (${row.execution_state}); no-op`);
|
|
56
|
+
return;
|
|
57
|
+
}
|
|
58
|
+
let def;
|
|
59
|
+
try {
|
|
60
|
+
def = registry.requireDefinition(row.definition_id, row.definition_version);
|
|
61
|
+
}
|
|
62
|
+
catch (e) {
|
|
63
|
+
await failInstance(client, row, `Unknown definition ${row.definition_id}@${row.definition_version}: ${String(e)}`);
|
|
64
|
+
return;
|
|
65
|
+
}
|
|
66
|
+
// Construct the FSM at the saved cursor. fromSnapshot skips onEnter
|
|
67
|
+
// (a resume is not entry) and preserves previous.
|
|
68
|
+
const positioned = FSM.fromSnapshot(def.fsm, {
|
|
69
|
+
state: row.cursor,
|
|
70
|
+
previous: row.previous_cursor,
|
|
71
|
+
context: row.context,
|
|
72
|
+
});
|
|
73
|
+
// If an outcome was supplied, apply it. This is the wake-up after an effect
|
|
74
|
+
// completion, a matched signal, or a timer expiry.
|
|
75
|
+
if (outcome !== undefined) {
|
|
76
|
+
const before = positioned.state;
|
|
77
|
+
const result = positioned.transition(outcome, outcome_data ?? undefined, false);
|
|
78
|
+
if (result === null) {
|
|
79
|
+
await appendHistory(client, {
|
|
80
|
+
project_id,
|
|
81
|
+
instance_id,
|
|
82
|
+
event_type: HISTORY_EVENT.TRANSITION_REJECTED,
|
|
83
|
+
from_node: before,
|
|
84
|
+
data: { outcome, outcome_data, reason: "fsm rejected transition" },
|
|
85
|
+
});
|
|
86
|
+
await failInstance(client, row, `fsm rejected outcome "${outcome}" at state "${before}"`);
|
|
87
|
+
return;
|
|
88
|
+
}
|
|
89
|
+
// Optionally merge outcome_data into context here. Convention: handlers
|
|
90
|
+
// return `{ outcome, data }` and the data is the payload — fsm action
|
|
91
|
+
// hooks merge it if the user wires them. We don't auto-merge to keep
|
|
92
|
+
// state shape under the user's control; the data is available via the
|
|
93
|
+
// payload arg to actions/guards.
|
|
94
|
+
await appendHistory(client, {
|
|
95
|
+
project_id,
|
|
96
|
+
instance_id,
|
|
97
|
+
event_type: timeout ? HISTORY_EVENT.TIMEOUT : HISTORY_EVENT.TRANSITION,
|
|
98
|
+
from_node: before,
|
|
99
|
+
to_node: positioned.state,
|
|
100
|
+
data: { outcome, outcome_data },
|
|
101
|
+
});
|
|
102
|
+
}
|
|
103
|
+
// Drive forward through pure states, settling at terminal/effectful/suspending.
|
|
104
|
+
for (let hop = 0; hop < MAX_PURE_HOPS; hop++) {
|
|
105
|
+
const meta = positioned.getCurrentMeta();
|
|
106
|
+
if (!meta) {
|
|
107
|
+
await failInstance(client, row, `state "${positioned.state}" has no meta`);
|
|
108
|
+
return;
|
|
109
|
+
}
|
|
110
|
+
switch (meta.kind) {
|
|
111
|
+
case "terminal": {
|
|
112
|
+
await updateInstance(client, instance_id, {
|
|
113
|
+
cursor: positioned.state,
|
|
114
|
+
previous_cursor: positioned.previous,
|
|
115
|
+
context: positioned.context,
|
|
116
|
+
execution_state: EXECUTION_STATE.COMPLETED,
|
|
117
|
+
wake_at: null,
|
|
118
|
+
correlation_token: null,
|
|
119
|
+
});
|
|
120
|
+
await appendHistory(client, {
|
|
121
|
+
project_id,
|
|
122
|
+
instance_id,
|
|
123
|
+
event_type: HISTORY_EVENT.COMPLETED,
|
|
124
|
+
from_node: positioned.state,
|
|
125
|
+
});
|
|
126
|
+
return;
|
|
127
|
+
}
|
|
128
|
+
case "effectful": {
|
|
129
|
+
// Persist context (any guards/actions may have updated it) + flip to running.
|
|
130
|
+
await updateInstance(client, instance_id, {
|
|
131
|
+
cursor: positioned.state,
|
|
132
|
+
previous_cursor: positioned.previous,
|
|
133
|
+
context: positioned.context,
|
|
134
|
+
execution_state: EXECUTION_STATE.RUNNING,
|
|
135
|
+
wake_at: null,
|
|
136
|
+
});
|
|
137
|
+
await enqueuer.enqueueEffect(client, meta.handler, {
|
|
138
|
+
project_id,
|
|
139
|
+
instance_id,
|
|
140
|
+
handler: meta.handler,
|
|
141
|
+
});
|
|
142
|
+
await appendHistory(client, {
|
|
143
|
+
project_id,
|
|
144
|
+
instance_id,
|
|
145
|
+
event_type: HISTORY_EVENT.EFFECT_DISPATCHED,
|
|
146
|
+
from_node: positioned.state,
|
|
147
|
+
data: { handler: meta.handler },
|
|
148
|
+
});
|
|
149
|
+
return;
|
|
150
|
+
}
|
|
151
|
+
case "suspending": {
|
|
152
|
+
const wake_at = meta.timeoutSec
|
|
153
|
+
? new Date(Date.now() + meta.timeoutSec * 1000)
|
|
154
|
+
: null;
|
|
155
|
+
// correlation_token already on the row (set at create-time or by the user
|
|
156
|
+
// via context). We don't auto-generate one here.
|
|
157
|
+
await updateInstance(client, instance_id, {
|
|
158
|
+
cursor: positioned.state,
|
|
159
|
+
previous_cursor: positioned.previous,
|
|
160
|
+
context: positioned.context,
|
|
161
|
+
execution_state: EXECUTION_STATE.WAITING,
|
|
162
|
+
wake_at,
|
|
163
|
+
});
|
|
164
|
+
await appendHistory(client, {
|
|
165
|
+
project_id,
|
|
166
|
+
instance_id,
|
|
167
|
+
event_type: HISTORY_EVENT.TRANSITION,
|
|
168
|
+
from_node: positioned.state,
|
|
169
|
+
data: { suspended: true, wake_at, matcher: meta.matcher ?? null },
|
|
170
|
+
});
|
|
171
|
+
return;
|
|
172
|
+
}
|
|
173
|
+
case "pure": {
|
|
174
|
+
const before = positioned.state;
|
|
175
|
+
const result = positioned.transition(PURE_ENTER_EVENT, undefined, false);
|
|
176
|
+
if (result === null) {
|
|
177
|
+
await appendHistory(client, {
|
|
178
|
+
project_id,
|
|
179
|
+
instance_id,
|
|
180
|
+
event_type: HISTORY_EVENT.TRANSITION_REJECTED,
|
|
181
|
+
from_node: before,
|
|
182
|
+
data: { event: PURE_ENTER_EVENT, reason: "no guarded transition matched" },
|
|
183
|
+
});
|
|
184
|
+
await failInstance(client, row, `pure state "${before}" did not route on ENTER`);
|
|
185
|
+
return;
|
|
186
|
+
}
|
|
187
|
+
await appendHistory(client, {
|
|
188
|
+
project_id,
|
|
189
|
+
instance_id,
|
|
190
|
+
event_type: HISTORY_EVENT.TRANSITION,
|
|
191
|
+
from_node: before,
|
|
192
|
+
to_node: positioned.state,
|
|
193
|
+
data: { event: PURE_ENTER_EVENT },
|
|
194
|
+
});
|
|
195
|
+
// loop
|
|
196
|
+
break;
|
|
197
|
+
}
|
|
198
|
+
default: {
|
|
199
|
+
await failInstance(client, row, `unknown meta.kind "${String(meta.kind)}" at state "${positioned.state}"`);
|
|
200
|
+
return;
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
await failInstance(client, row, `exceeded ${MAX_PURE_HOPS} pure-state hops (likely cycle)`);
|
|
205
|
+
});
|
|
206
|
+
}
|
|
207
|
+
async function failInstance(client, row, reason) {
|
|
208
|
+
clog.error?.(`workflow instance ${row.id} failed: ${reason}`);
|
|
209
|
+
await updateInstance(client, row.id, {
|
|
210
|
+
execution_state: EXECUTION_STATE.FAILED,
|
|
211
|
+
});
|
|
212
|
+
await appendHistory(client, {
|
|
213
|
+
project_id: row.project_id,
|
|
214
|
+
instance_id: row.id,
|
|
215
|
+
event_type: HISTORY_EVENT.FAILED,
|
|
216
|
+
from_node: row.cursor,
|
|
217
|
+
data: { reason },
|
|
218
|
+
});
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* The `workflow.effect.<handlerName>` job body.
|
|
222
|
+
*
|
|
223
|
+
* 1. Looks up the user handler in the registry by `payload.handler`.
|
|
224
|
+
* 2. Loads the instance to grab the current context (no lock — handlers run
|
|
225
|
+
* outside the advance tx).
|
|
226
|
+
* 3. Runs the handler.
|
|
227
|
+
* 4. On success: enqueues a `workflow.advance` job with the outcome + data.
|
|
228
|
+
* 5. On throw: re-throws so steve records the attempt as failed (steve retries
|
|
229
|
+
* per the job's `max_attempts`). When steve gives up, the on-failed hook in
|
|
230
|
+
* Workflow marks the instance failed.
|
|
231
|
+
*
|
|
232
|
+
* Handlers must be idempotent — steve may retry the handler if a worker crashes
|
|
233
|
+
* mid-execution, and even successful handlers can run twice if completion-write
|
|
234
|
+
* fails after the advance has been enqueued.
|
|
235
|
+
*/
|
|
236
|
+
export async function runEffect(pool, registry, enqueuer, payload, signal) {
|
|
237
|
+
const { instance_id, project_id, handler: handlerName } = payload;
|
|
238
|
+
const handler = registry.requireHandler(handlerName);
|
|
239
|
+
const client = await pool.connect();
|
|
240
|
+
let row;
|
|
241
|
+
try {
|
|
242
|
+
const r = await client.query(`SELECT id, project_id, definition_id, definition_version, cursor,
|
|
243
|
+
previous_cursor, context, execution_state, wake_at,
|
|
244
|
+
correlation_token, created_at, updated_at
|
|
245
|
+
FROM __workflow_instances WHERE id = $1`, [instance_id]);
|
|
246
|
+
row = r.rows[0] ?? null;
|
|
247
|
+
}
|
|
248
|
+
finally {
|
|
249
|
+
client.release();
|
|
250
|
+
}
|
|
251
|
+
if (!row) {
|
|
252
|
+
throw new Error(`effect: instance ${instance_id} not found`);
|
|
253
|
+
}
|
|
254
|
+
const result = await handler({
|
|
255
|
+
instanceId: instance_id,
|
|
256
|
+
projectId: project_id,
|
|
257
|
+
context: row.context,
|
|
258
|
+
signal,
|
|
259
|
+
});
|
|
260
|
+
await enqueuer.enqueueAdvance(pool, {
|
|
261
|
+
project_id,
|
|
262
|
+
instance_id,
|
|
263
|
+
outcome: result.outcome,
|
|
264
|
+
outcome_data: result.data,
|
|
265
|
+
});
|
|
266
|
+
return { outcome: result.outcome, data: result.data };
|
|
267
|
+
}
|
|
268
|
+
/**
|
|
269
|
+
* Called by the Workflow layer when steve gives up on an effect job (all
|
|
270
|
+
* attempts exhausted or expired). Marks the workflow instance as failed.
|
|
271
|
+
*/
|
|
272
|
+
export async function failEffectJob(pool, payload, reason) {
|
|
273
|
+
await withTransaction(pool, async (client) => {
|
|
274
|
+
const row = await lockInstance(client, payload.instance_id);
|
|
275
|
+
if (!row)
|
|
276
|
+
return;
|
|
277
|
+
if (row.execution_state === EXECUTION_STATE.COMPLETED ||
|
|
278
|
+
row.execution_state === EXECUTION_STATE.FAILED ||
|
|
279
|
+
row.execution_state === EXECUTION_STATE.CANCELLED) {
|
|
280
|
+
return;
|
|
281
|
+
}
|
|
282
|
+
await updateInstance(client, row.id, {
|
|
283
|
+
execution_state: EXECUTION_STATE.FAILED,
|
|
284
|
+
});
|
|
285
|
+
await appendHistory(client, {
|
|
286
|
+
project_id: row.project_id,
|
|
287
|
+
instance_id: row.id,
|
|
288
|
+
event_type: HISTORY_EVENT.EFFECT_FAILED,
|
|
289
|
+
from_node: row.cursor,
|
|
290
|
+
data: { handler: payload.handler, reason },
|
|
291
|
+
});
|
|
292
|
+
});
|
|
293
|
+
}
|
|
294
|
+
/** Composite steve job-type string for an effect handler. */
|
|
295
|
+
export function effectJobType(handlerName) {
|
|
296
|
+
return `${JOB_TYPE_EFFECT_PREFIX}${handlerName}`;
|
|
297
|
+
}
|
|
298
|
+
export { JOB_TYPE_ADVANCE };
|
package/dist/log.d.ts
ADDED
package/dist/log.js
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Forward migration for schema version 1.0.0 — creates the three framework
|
|
3
|
+
* tables and their indexes. Expects `ctx.pool` to be a `pg.Pool` (the shape
|
|
4
|
+
* created by {@link createMigrate}).
|
|
5
|
+
*/
|
|
6
|
+
export declare function up(ctx?: Record<string, unknown>): Promise<void>;
|
|
7
|
+
/** Reverse migration — drops the three framework tables. Destructive. */
|
|
8
|
+
export declare function down(ctx?: Record<string, unknown>): Promise<void>;
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
const SQL_UP = `
|
|
2
|
+
-- __workflow_instances: live state of a single running occurrence of a definition
|
|
3
|
+
CREATE TABLE IF NOT EXISTS __workflow_instances (
|
|
4
|
+
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
5
|
+
project_id text NOT NULL,
|
|
6
|
+
definition_id text NOT NULL,
|
|
7
|
+
definition_version text NOT NULL,
|
|
8
|
+
cursor text NOT NULL,
|
|
9
|
+
previous_cursor text NULL,
|
|
10
|
+
context jsonb NOT NULL DEFAULT '{}'::jsonb,
|
|
11
|
+
execution_state text NOT NULL,
|
|
12
|
+
wake_at timestamptz NULL,
|
|
13
|
+
correlation_token text NULL,
|
|
14
|
+
created_at timestamptz NOT NULL DEFAULT now(),
|
|
15
|
+
updated_at timestamptz NOT NULL DEFAULT now()
|
|
16
|
+
);
|
|
17
|
+
|
|
18
|
+
CREATE INDEX IF NOT EXISTS __workflow_instances_scheduler_idx
|
|
19
|
+
ON __workflow_instances (project_id, execution_state, wake_at)
|
|
20
|
+
WHERE wake_at IS NOT NULL;
|
|
21
|
+
|
|
22
|
+
CREATE INDEX IF NOT EXISTS __workflow_instances_correlator_idx
|
|
23
|
+
ON __workflow_instances (project_id, execution_state, correlation_token)
|
|
24
|
+
WHERE correlation_token IS NOT NULL;
|
|
25
|
+
|
|
26
|
+
-- __workflow_inbox: append-only intake of external signals awaiting correlation
|
|
27
|
+
CREATE TABLE IF NOT EXISTS __workflow_inbox (
|
|
28
|
+
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
29
|
+
project_id text NOT NULL,
|
|
30
|
+
received_at timestamptz NOT NULL DEFAULT now(),
|
|
31
|
+
source text NOT NULL,
|
|
32
|
+
correlation_token text NOT NULL,
|
|
33
|
+
payload jsonb NOT NULL,
|
|
34
|
+
processed_at timestamptz NULL
|
|
35
|
+
);
|
|
36
|
+
|
|
37
|
+
CREATE INDEX IF NOT EXISTS __workflow_inbox_unprocessed_idx
|
|
38
|
+
ON __workflow_inbox (project_id, correlation_token)
|
|
39
|
+
WHERE processed_at IS NULL;
|
|
40
|
+
|
|
41
|
+
-- __workflow_history: append-only per-instance audit log
|
|
42
|
+
CREATE TABLE IF NOT EXISTS __workflow_history (
|
|
43
|
+
id bigserial PRIMARY KEY,
|
|
44
|
+
project_id text NOT NULL,
|
|
45
|
+
instance_id uuid NOT NULL,
|
|
46
|
+
at timestamptz NOT NULL DEFAULT now(),
|
|
47
|
+
event_type text NOT NULL,
|
|
48
|
+
from_node text NULL,
|
|
49
|
+
to_node text NULL,
|
|
50
|
+
data jsonb NOT NULL DEFAULT '{}'::jsonb
|
|
51
|
+
);
|
|
52
|
+
|
|
53
|
+
CREATE INDEX IF NOT EXISTS __workflow_history_instance_idx
|
|
54
|
+
ON __workflow_history (instance_id, at);
|
|
55
|
+
`;
|
|
56
|
+
const SQL_DOWN = `
|
|
57
|
+
DROP TABLE IF EXISTS __workflow_history;
|
|
58
|
+
DROP TABLE IF EXISTS __workflow_inbox;
|
|
59
|
+
DROP TABLE IF EXISTS __workflow_instances;
|
|
60
|
+
`;
|
|
61
|
+
/**
|
|
62
|
+
* Forward migration for schema version 1.0.0 — creates the three framework
|
|
63
|
+
* tables and their indexes. Expects `ctx.pool` to be a `pg.Pool` (the shape
|
|
64
|
+
* created by {@link createMigrate}).
|
|
65
|
+
*/
|
|
66
|
+
export async function up(ctx) {
|
|
67
|
+
const { pool } = ctx;
|
|
68
|
+
const client = await pool.connect();
|
|
69
|
+
try {
|
|
70
|
+
await client.query(SQL_UP);
|
|
71
|
+
}
|
|
72
|
+
finally {
|
|
73
|
+
client.release();
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
/** Reverse migration — drops the three framework tables. Destructive. */
|
|
77
|
+
export async function down(ctx) {
|
|
78
|
+
const { pool } = ctx;
|
|
79
|
+
const client = await pool.connect();
|
|
80
|
+
try {
|
|
81
|
+
await client.query(SQL_DOWN);
|
|
82
|
+
}
|
|
83
|
+
finally {
|
|
84
|
+
client.release();
|
|
85
|
+
}
|
|
86
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { Migrate } from "@marianmeres/migrate";
|
|
2
|
+
import type pg from "pg";
|
|
3
|
+
/**
|
|
4
|
+
* Builds a {@link Migrate} instance pre-loaded with the package's schema
|
|
5
|
+
* versions. The caller drives it (`.up('latest')`, `.down(...)`, etc.).
|
|
6
|
+
*
|
|
7
|
+
* The active version is stored in `__workflow_migrations` (one row per change,
|
|
8
|
+
* latest row wins).
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* ```ts
|
|
12
|
+
* import pg from "pg";
|
|
13
|
+
* import { createMigrate } from "@marianmeres/workflow";
|
|
14
|
+
*
|
|
15
|
+
* const pool = new pg.Pool({ ... });
|
|
16
|
+
* const migrate = createMigrate(pool);
|
|
17
|
+
* await migrate.up("latest");
|
|
18
|
+
* ```
|
|
19
|
+
*/
|
|
20
|
+
export declare function createMigrate(pool: pg.Pool, options?: {
|
|
21
|
+
logger?: (...args: unknown[]) => void;
|
|
22
|
+
}): Migrate;
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import { Migrate } from "@marianmeres/migrate";
|
|
2
|
+
import { up as up_1_0_0, down as down_1_0_0 } from "./1_0_0.js";
|
|
3
|
+
const VERSION_TABLE = "__workflow_migrations";
|
|
4
|
+
/**
|
|
5
|
+
* Builds a {@link Migrate} instance pre-loaded with the package's schema
|
|
6
|
+
* versions. The caller drives it (`.up('latest')`, `.down(...)`, etc.).
|
|
7
|
+
*
|
|
8
|
+
* The active version is stored in `__workflow_migrations` (one row per change,
|
|
9
|
+
* latest row wins).
|
|
10
|
+
*
|
|
11
|
+
* @example
|
|
12
|
+
* ```ts
|
|
13
|
+
* import pg from "pg";
|
|
14
|
+
* import { createMigrate } from "@marianmeres/workflow";
|
|
15
|
+
*
|
|
16
|
+
* const pool = new pg.Pool({ ... });
|
|
17
|
+
* const migrate = createMigrate(pool);
|
|
18
|
+
* await migrate.up("latest");
|
|
19
|
+
* ```
|
|
20
|
+
*/
|
|
21
|
+
export function createMigrate(pool, options = {}) {
|
|
22
|
+
const migrate = new Migrate({
|
|
23
|
+
getActiveVersion: getActiveVersion,
|
|
24
|
+
setActiveVersion: setActiveVersion,
|
|
25
|
+
logger: options.logger,
|
|
26
|
+
}, { pool });
|
|
27
|
+
migrate.addVersion("1.0.0", up_1_0_0, down_1_0_0);
|
|
28
|
+
return migrate;
|
|
29
|
+
}
|
|
30
|
+
async function ensureVersionTable(client) {
|
|
31
|
+
await client.query(`CREATE TABLE IF NOT EXISTS ${VERSION_TABLE} (
|
|
32
|
+
id serial PRIMARY KEY,
|
|
33
|
+
version text NULL,
|
|
34
|
+
created_at timestamptz NOT NULL DEFAULT now()
|
|
35
|
+
)`);
|
|
36
|
+
}
|
|
37
|
+
async function getActiveVersion(ctx) {
|
|
38
|
+
const { pool } = ctx;
|
|
39
|
+
const client = await pool.connect();
|
|
40
|
+
try {
|
|
41
|
+
await ensureVersionTable(client);
|
|
42
|
+
const r = await client.query(`SELECT version FROM ${VERSION_TABLE} ORDER BY id DESC LIMIT 1`);
|
|
43
|
+
return r.rows[0]?.version ?? undefined;
|
|
44
|
+
}
|
|
45
|
+
finally {
|
|
46
|
+
client.release();
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
async function setActiveVersion(version, ctx) {
|
|
50
|
+
const { pool } = ctx;
|
|
51
|
+
const client = await pool.connect();
|
|
52
|
+
try {
|
|
53
|
+
await ensureVersionTable(client);
|
|
54
|
+
await client.query(`INSERT INTO ${VERSION_TABLE} (version) VALUES ($1)`, [version ?? null]);
|
|
55
|
+
return version;
|
|
56
|
+
}
|
|
57
|
+
finally {
|
|
58
|
+
client.release();
|
|
59
|
+
}
|
|
60
|
+
}
|
package/dist/mod.d.ts
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module @marianmeres/workflow
|
|
3
|
+
*
|
|
4
|
+
* Durable workflow / orchestration framework for long-lived state machines.
|
|
5
|
+
* Built on PostgreSQL. Instances persist across process restarts, sleep for
|
|
6
|
+
* days waiting for a signal or a timer, and resume from disk via
|
|
7
|
+
* {@link https://jsr.io/@marianmeres/fsm | @marianmeres/fsm}'s `fromSnapshot`.
|
|
8
|
+
* Effects run as {@link https://jsr.io/@marianmeres/steve | @marianmeres/steve}
|
|
9
|
+
* jobs (transactional outbox). The scheduler and inbox correlator are driven
|
|
10
|
+
* by {@link https://jsr.io/@marianmeres/cron | @marianmeres/cron}. Schema is
|
|
11
|
+
* managed by {@link https://jsr.io/@marianmeres/migrate | @marianmeres/migrate}.
|
|
12
|
+
*
|
|
13
|
+
* Ships no domain code — userland brings the definitions, handlers, and
|
|
14
|
+
* matchers. The framework provides the dispatch core and the durability story.
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```typescript
|
|
18
|
+
* import pg from "pg";
|
|
19
|
+
* import { Jobs } from "@marianmeres/steve";
|
|
20
|
+
* import { Cron } from "@marianmeres/cron";
|
|
21
|
+
* import { createMigrate, Workflow } from "@marianmeres/workflow";
|
|
22
|
+
*
|
|
23
|
+
* const pool = new pg.Pool({ /* ... *\/ });
|
|
24
|
+
* await createMigrate(pool).up("latest");
|
|
25
|
+
*
|
|
26
|
+
* const jobs = new Jobs({ db: pool });
|
|
27
|
+
* const wf = new Workflow({
|
|
28
|
+
* db: pool,
|
|
29
|
+
* jobs,
|
|
30
|
+
* definitions: [/* ... *\/],
|
|
31
|
+
* handlers: {/* ... *\/},
|
|
32
|
+
* });
|
|
33
|
+
*
|
|
34
|
+
* await jobs.start(4);
|
|
35
|
+
* await wf.create({ definitionId: "...", definitionVersion: "1.0.0" });
|
|
36
|
+
* ```
|
|
37
|
+
*/
|
|
38
|
+
export { Workflow, type WorkflowOptions } from "./workflow.js";
|
|
39
|
+
export { WorkflowScheduler, type WorkflowSchedulerOptions, } from "./scheduler.js";
|
|
40
|
+
export { WorkflowInboxCorrelator, type WorkflowInboxCorrelatorOptions, } from "./correlator.js";
|
|
41
|
+
export { WorkflowRegistry } from "./registry.js";
|
|
42
|
+
export { validateDefinition, defKey } from "./definition.js";
|
|
43
|
+
export { createMigrate } from "./migrations/index.js";
|
|
44
|
+
export { getHistory } from "./persistence/history.js";
|
|
45
|
+
export { effectJobType, JOB_TYPE_ADVANCE, PURE_ENTER_EVENT, } from "./driver.js";
|
|
46
|
+
export { DEFAULT_PROJECT_ID, EXECUTION_STATE, HISTORY_EVENT, JOB_TYPE_EFFECT_PREFIX, type AdvanceJobPayload, type EffectJobPayload, type ExecutionState, type Handler, type HandlerArgs, type HandlerResult, type HistoryEventType, type HistoryRow, type InboxRow, type Matcher, type MatcherArgs, type NodeMeta, type WorkflowContext, type WorkflowDefinition, type WorkflowInstanceRow, type WorkflowSnapshot, } from "./types.js";
|
package/dist/mod.js
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module @marianmeres/workflow
|
|
3
|
+
*
|
|
4
|
+
* Durable workflow / orchestration framework for long-lived state machines.
|
|
5
|
+
* Built on PostgreSQL. Instances persist across process restarts, sleep for
|
|
6
|
+
* days waiting for a signal or a timer, and resume from disk via
|
|
7
|
+
* {@link https://jsr.io/@marianmeres/fsm | @marianmeres/fsm}'s `fromSnapshot`.
|
|
8
|
+
* Effects run as {@link https://jsr.io/@marianmeres/steve | @marianmeres/steve}
|
|
9
|
+
* jobs (transactional outbox). The scheduler and inbox correlator are driven
|
|
10
|
+
* by {@link https://jsr.io/@marianmeres/cron | @marianmeres/cron}. Schema is
|
|
11
|
+
* managed by {@link https://jsr.io/@marianmeres/migrate | @marianmeres/migrate}.
|
|
12
|
+
*
|
|
13
|
+
* Ships no domain code — userland brings the definitions, handlers, and
|
|
14
|
+
* matchers. The framework provides the dispatch core and the durability story.
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```typescript
|
|
18
|
+
* import pg from "pg";
|
|
19
|
+
* import { Jobs } from "@marianmeres/steve";
|
|
20
|
+
* import { Cron } from "@marianmeres/cron";
|
|
21
|
+
* import { createMigrate, Workflow } from "@marianmeres/workflow";
|
|
22
|
+
*
|
|
23
|
+
* const pool = new pg.Pool({ /* ... *\/ });
|
|
24
|
+
* await createMigrate(pool).up("latest");
|
|
25
|
+
*
|
|
26
|
+
* const jobs = new Jobs({ db: pool });
|
|
27
|
+
* const wf = new Workflow({
|
|
28
|
+
* db: pool,
|
|
29
|
+
* jobs,
|
|
30
|
+
* definitions: [/* ... *\/],
|
|
31
|
+
* handlers: {/* ... *\/},
|
|
32
|
+
* });
|
|
33
|
+
*
|
|
34
|
+
* await jobs.start(4);
|
|
35
|
+
* await wf.create({ definitionId: "...", definitionVersion: "1.0.0" });
|
|
36
|
+
* ```
|
|
37
|
+
*/
|
|
38
|
+
export { Workflow } from "./workflow.js";
|
|
39
|
+
export { WorkflowScheduler, } from "./scheduler.js";
|
|
40
|
+
export { WorkflowInboxCorrelator, } from "./correlator.js";
|
|
41
|
+
export { WorkflowRegistry } from "./registry.js";
|
|
42
|
+
export { validateDefinition, defKey } from "./definition.js";
|
|
43
|
+
export { createMigrate } from "./migrations/index.js";
|
|
44
|
+
export { getHistory } from "./persistence/history.js";
|
|
45
|
+
export { effectJobType, JOB_TYPE_ADVANCE, PURE_ENTER_EVENT, } from "./driver.js";
|
|
46
|
+
export { DEFAULT_PROJECT_ID, EXECUTION_STATE, HISTORY_EVENT, JOB_TYPE_EFFECT_PREFIX, } from "./types.js";
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type pg from "pg";
|
|
2
|
+
import type { HistoryEventType, HistoryRow } from "../types.js";
|
|
3
|
+
type Executor = pg.Pool | pg.PoolClient | pg.Client;
|
|
4
|
+
/**
|
|
5
|
+
* Appends a single audit row to `__workflow_history`. Accepts a pool, a
|
|
6
|
+
* client, or a transaction-bound client — call this inside the same
|
|
7
|
+
* transaction as the state change it describes.
|
|
8
|
+
*/
|
|
9
|
+
export declare function appendHistory(exec: Executor, input: {
|
|
10
|
+
project_id: string;
|
|
11
|
+
instance_id: string;
|
|
12
|
+
event_type: HistoryEventType;
|
|
13
|
+
from_node?: string | null;
|
|
14
|
+
to_node?: string | null;
|
|
15
|
+
data?: Record<string, unknown>;
|
|
16
|
+
}): Promise<void>;
|
|
17
|
+
/**
|
|
18
|
+
* Reads the audit log for an instance in chronological order (oldest first).
|
|
19
|
+
* Useful for `/admin/workflows`-style observability surfaces and tests.
|
|
20
|
+
*
|
|
21
|
+
* @param exec - pool, client, or transaction-bound client
|
|
22
|
+
* @param instance_id - id of the instance whose history to read
|
|
23
|
+
* @param limit - max rows to return; default `200`
|
|
24
|
+
*/
|
|
25
|
+
export declare function getHistory(exec: Executor, instance_id: string, limit?: number): Promise<HistoryRow[]>;
|
|
26
|
+
export {};
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
const SELECT_COLUMNS = `id, project_id, instance_id, at, event_type, from_node, to_node, data`;
|
|
2
|
+
/**
|
|
3
|
+
* Appends a single audit row to `__workflow_history`. Accepts a pool, a
|
|
4
|
+
* client, or a transaction-bound client — call this inside the same
|
|
5
|
+
* transaction as the state change it describes.
|
|
6
|
+
*/
|
|
7
|
+
export async function appendHistory(exec, input) {
|
|
8
|
+
await exec.query(`INSERT INTO __workflow_history
|
|
9
|
+
(project_id, instance_id, event_type, from_node, to_node, data)
|
|
10
|
+
VALUES ($1, $2, $3, $4, $5, $6::jsonb)`, [
|
|
11
|
+
input.project_id,
|
|
12
|
+
input.instance_id,
|
|
13
|
+
input.event_type,
|
|
14
|
+
input.from_node ?? null,
|
|
15
|
+
input.to_node ?? null,
|
|
16
|
+
JSON.stringify(input.data ?? {}),
|
|
17
|
+
]);
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Reads the audit log for an instance in chronological order (oldest first).
|
|
21
|
+
* Useful for `/admin/workflows`-style observability surfaces and tests.
|
|
22
|
+
*
|
|
23
|
+
* @param exec - pool, client, or transaction-bound client
|
|
24
|
+
* @param instance_id - id of the instance whose history to read
|
|
25
|
+
* @param limit - max rows to return; default `200`
|
|
26
|
+
*/
|
|
27
|
+
export async function getHistory(exec, instance_id, limit = 200) {
|
|
28
|
+
const r = await exec.query(`SELECT ${SELECT_COLUMNS} FROM __workflow_history
|
|
29
|
+
WHERE instance_id = $1
|
|
30
|
+
ORDER BY at, id
|
|
31
|
+
LIMIT $2`, [instance_id, limit]);
|
|
32
|
+
return r.rows;
|
|
33
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type pg from "pg";
|
|
2
|
+
import type { InboxRow } from "../types.js";
|
|
3
|
+
type Executor = pg.Pool | pg.PoolClient | pg.Client;
|
|
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 declare function appendInbox(exec: Executor, input: {
|
|
9
|
+
project_id: string;
|
|
10
|
+
source: string;
|
|
11
|
+
correlation_token: string;
|
|
12
|
+
payload: Record<string, unknown>;
|
|
13
|
+
}): Promise<InboxRow>;
|
|
14
|
+
/**
|
|
15
|
+
* Claims a batch of unprocessed inbox rows for the project. Uses
|
|
16
|
+
* `FOR UPDATE SKIP LOCKED` so two concurrent correlator workers don't grab
|
|
17
|
+
* the same row. Caller MUST be inside a transaction and either mark them
|
|
18
|
+
* processed or roll back.
|
|
19
|
+
*/
|
|
20
|
+
export declare function claimUnprocessed(client: pg.PoolClient | pg.Client, project_id: string, limit?: number): Promise<InboxRow[]>;
|
|
21
|
+
/** Marks an inbox row as processed (sets `processed_at = now()`). */
|
|
22
|
+
export declare function markProcessed(exec: Executor, id: string): Promise<void>;
|
|
23
|
+
export {};
|