@marianmeres/workflow 2.1.0 → 3.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 +146 -89
- package/API.md +27 -13
- package/README.md +91 -13
- package/dist/correlator.d.ts +1 -1
- package/dist/correlator.js +25 -21
- package/dist/definition.d.ts +1 -1
- package/dist/driver.d.ts +17 -10
- package/dist/driver.js +60 -64
- package/dist/migrations/1_0_0.d.ts +5 -4
- package/dist/migrations/1_0_0.js +6 -20
- package/dist/migrations/1_1_0.d.ts +3 -2
- package/dist/migrations/1_1_0.js +5 -23
- package/dist/migrations/1_2_0.d.ts +3 -2
- package/dist/migrations/1_2_0.js +4 -18
- package/dist/migrations/index.d.ts +15 -5
- package/dist/migrations/index.js +16 -38
- package/dist/mod.d.ts +19 -13
- package/dist/mod.js +14 -8
- package/dist/persistence/history.d.ts +10 -10
- package/dist/persistence/history.js +23 -22
- package/dist/persistence/inbox.d.ts +12 -13
- package/dist/persistence/inbox.js +40 -31
- package/dist/persistence/instances.d.ts +25 -20
- package/dist/persistence/instances.js +99 -103
- package/dist/registry.d.ts +1 -1
- package/dist/scheduler.d.ts +5 -4
- package/dist/scheduler.js +1 -1
- package/dist/workflow.d.ts +33 -11
- package/dist/workflow.js +44 -33
- package/package.json +89 -39
- package/dist/persistence/tx.d.ts +0 -6
- package/dist/persistence/tx.js +0 -25
package/dist/driver.js
CHANGED
|
@@ -2,8 +2,7 @@ import { FSM } from "@marianmeres/fsm";
|
|
|
2
2
|
import { clog } from "./log.js";
|
|
3
3
|
import { appendHistory } from "./persistence/history.js";
|
|
4
4
|
import { lockInboxRow, markProcessed } from "./persistence/inbox.js";
|
|
5
|
-
import { lockInstance, updateInstance } from "./persistence/instances.js";
|
|
6
|
-
import { withTransaction } from "./persistence/tx.js";
|
|
5
|
+
import { findInstance, lockInstance, updateInstance } from "./persistence/instances.js";
|
|
7
6
|
import { EXECUTION_STATE, HISTORY_EVENT, JOB_TYPE_ADVANCE, JOB_TYPE_EFFECT_PREFIX, PURE_ENTER_EVENT, SIGNAL_MATCHED_EVENT, } from "./types.js";
|
|
8
7
|
/**
|
|
9
8
|
* Reads the tenant scope off a job payload, tolerating the legacy `project_id`
|
|
@@ -43,7 +42,8 @@ const MAX_PURE_HOPS = 64;
|
|
|
43
42
|
/**
|
|
44
43
|
* The `workflow.advance` job body.
|
|
45
44
|
*
|
|
46
|
-
* Wrapped in a single PG transaction
|
|
45
|
+
* Wrapped in a single PG transaction (`db.transaction()`; a call made from
|
|
46
|
+
* inside a caller's own transaction on the same driver joins that one):
|
|
47
47
|
* 1. Lock the instance row.
|
|
48
48
|
* 2. If in a terminal execution_state, no-op.
|
|
49
49
|
* 2b. If the payload's fence (`expected_seq`) does not match the locked row, or
|
|
@@ -59,17 +59,19 @@ const MAX_PURE_HOPS = 64;
|
|
|
59
59
|
* - effectful → enqueue an effect job + mark running, return.
|
|
60
60
|
* - suspending → mark waiting, set wake_at/correlation_token, return.
|
|
61
61
|
*/
|
|
62
|
-
export async function runAdvance(
|
|
62
|
+
export async function runAdvance(db, registry, enqueuer, payload) {
|
|
63
63
|
const { instance_id } = payload;
|
|
64
64
|
const tenant_id = payloadTenantId(payload);
|
|
65
65
|
const kind = advanceKind(payload);
|
|
66
|
-
await
|
|
67
|
-
const row = await lockInstance(
|
|
66
|
+
await db.transaction(async (tx) => {
|
|
67
|
+
const row = await lockInstance(tx, instance_id);
|
|
68
68
|
if (!row) {
|
|
69
|
-
// Also the window where the creating transaction has not committed yet
|
|
70
|
-
//
|
|
71
|
-
// can be claimed first
|
|
72
|
-
//
|
|
69
|
+
// Also the window where the creating transaction has not committed yet:
|
|
70
|
+
// a queue on a database connection of its own inserts the job outside
|
|
71
|
+
// that transaction, so the job can be claimed first. (A queue that
|
|
72
|
+
// shares the workflow's driver inserts it inside, and never gets here.)
|
|
73
|
+
// Throw rather than drop the only job the instance will ever get —
|
|
74
|
+
// steve retries.
|
|
73
75
|
throw new Error(`advance: instance ${instance_id} not found`);
|
|
74
76
|
}
|
|
75
77
|
if (row.execution_state === EXECUTION_STATE.COMPLETED ||
|
|
@@ -99,7 +101,8 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
99
101
|
(payload.kind === "signal" &&
|
|
100
102
|
row.execution_state !== EXECUTION_STATE.WAITING) ||
|
|
101
103
|
(payload.kind === "timeout" &&
|
|
102
|
-
(row.execution_state !== EXECUTION_STATE.WAITING ||
|
|
104
|
+
(row.execution_state !== EXECUTION_STATE.WAITING ||
|
|
105
|
+
!row.wake_at ||
|
|
103
106
|
row.wake_at > new Date()))) {
|
|
104
107
|
clog.debug?.(`advance: ${payload.kind} precondition not met (${row.execution_state}); no-op`);
|
|
105
108
|
return;
|
|
@@ -111,7 +114,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
111
114
|
let outcome_data = payload.outcome_data;
|
|
112
115
|
let inbox = null;
|
|
113
116
|
if (payload.kind === "signal" && payload.inbox_id) {
|
|
114
|
-
inbox = await lockInboxRow(
|
|
117
|
+
inbox = await lockInboxRow(tx, payload.inbox_id);
|
|
115
118
|
if (!inbox || inbox.processed_at) {
|
|
116
119
|
clog.debug?.(`advance: inbox row ${payload.inbox_id} already delivered; no-op`);
|
|
117
120
|
return;
|
|
@@ -130,7 +133,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
130
133
|
def = registry.requireDefinition(row.definition_id, row.definition_version);
|
|
131
134
|
}
|
|
132
135
|
catch (e) {
|
|
133
|
-
await failInstance(
|
|
136
|
+
await failInstance(tx, row, `Unknown definition ${row.definition_id}@${row.definition_version}: ${String(e)}`);
|
|
134
137
|
return;
|
|
135
138
|
}
|
|
136
139
|
// Construct the FSM at the saved cursor. fromSnapshot skips onEnter
|
|
@@ -150,14 +153,14 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
150
153
|
const before = positioned.state;
|
|
151
154
|
const result = positioned.transition(outcome, outcome_data ?? undefined, false);
|
|
152
155
|
if (result === null) {
|
|
153
|
-
await appendHistory(
|
|
156
|
+
await appendHistory(tx, {
|
|
154
157
|
tenant_id,
|
|
155
158
|
instance_id,
|
|
156
159
|
event_type: HISTORY_EVENT.TRANSITION_REJECTED,
|
|
157
160
|
from_node: before,
|
|
158
161
|
data: { outcome, outcome_data, reason: "fsm rejected transition" },
|
|
159
162
|
});
|
|
160
|
-
await failInstance(
|
|
163
|
+
await failInstance(tx, row, `fsm rejected outcome "${outcome}" at state "${before}"`);
|
|
161
164
|
return;
|
|
162
165
|
}
|
|
163
166
|
// `outcome_data` stays the fsm payload and is never auto-merged: what
|
|
@@ -165,7 +168,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
165
168
|
// what the handler explicitly returned in `HandlerResult.context`
|
|
166
169
|
// (merged above).
|
|
167
170
|
if (kind === "effect" && payload.handler) {
|
|
168
|
-
await appendHistory(
|
|
171
|
+
await appendHistory(tx, {
|
|
169
172
|
tenant_id,
|
|
170
173
|
instance_id,
|
|
171
174
|
event_type: HISTORY_EVENT.EFFECT_COMPLETED,
|
|
@@ -174,21 +177,19 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
174
177
|
});
|
|
175
178
|
}
|
|
176
179
|
if (inbox) {
|
|
177
|
-
await appendHistory(
|
|
180
|
+
await appendHistory(tx, {
|
|
178
181
|
tenant_id,
|
|
179
182
|
instance_id,
|
|
180
183
|
event_type: HISTORY_EVENT.SIGNAL_RECEIVED,
|
|
181
184
|
from_node: before,
|
|
182
185
|
data: { inbox_id: inbox.id, source: inbox.source },
|
|
183
186
|
});
|
|
184
|
-
await markProcessed(
|
|
187
|
+
await markProcessed(tx, inbox.id);
|
|
185
188
|
}
|
|
186
|
-
await appendHistory(
|
|
189
|
+
await appendHistory(tx, {
|
|
187
190
|
tenant_id,
|
|
188
191
|
instance_id,
|
|
189
|
-
event_type: kind === "timeout"
|
|
190
|
-
? HISTORY_EVENT.TIMEOUT
|
|
191
|
-
: HISTORY_EVENT.TRANSITION,
|
|
192
|
+
event_type: kind === "timeout" ? HISTORY_EVENT.TIMEOUT : HISTORY_EVENT.TRANSITION,
|
|
192
193
|
from_node: before,
|
|
193
194
|
to_node: positioned.state,
|
|
194
195
|
data: { outcome, outcome_data, ...tokenPatch },
|
|
@@ -198,12 +199,12 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
198
199
|
for (let hop = 0; hop < MAX_PURE_HOPS; hop++) {
|
|
199
200
|
const meta = positioned.getCurrentMeta();
|
|
200
201
|
if (!meta) {
|
|
201
|
-
await failInstance(
|
|
202
|
+
await failInstance(tx, row, `state "${positioned.state}" has no meta`);
|
|
202
203
|
return;
|
|
203
204
|
}
|
|
204
205
|
switch (meta.kind) {
|
|
205
206
|
case "terminal": {
|
|
206
|
-
await updateInstance(
|
|
207
|
+
await updateInstance(tx, instance_id, {
|
|
207
208
|
cursor: positioned.state,
|
|
208
209
|
previous_cursor: positioned.previous,
|
|
209
210
|
context: positioned.context,
|
|
@@ -211,7 +212,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
211
212
|
wake_at: null,
|
|
212
213
|
correlation_token: null,
|
|
213
214
|
}, { bumpSeq: true });
|
|
214
|
-
await appendHistory(
|
|
215
|
+
await appendHistory(tx, {
|
|
215
216
|
tenant_id,
|
|
216
217
|
instance_id,
|
|
217
218
|
event_type: HISTORY_EVENT.COMPLETED,
|
|
@@ -221,7 +222,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
221
222
|
}
|
|
222
223
|
case "effectful": {
|
|
223
224
|
// Persist context (any guards/actions may have updated it) + flip to running.
|
|
224
|
-
const settled = await updateInstance(
|
|
225
|
+
const settled = await updateInstance(tx, instance_id, {
|
|
225
226
|
cursor: positioned.state,
|
|
226
227
|
previous_cursor: positioned.previous,
|
|
227
228
|
context: positioned.context,
|
|
@@ -229,14 +230,19 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
229
230
|
wake_at: null,
|
|
230
231
|
...tokenPatch,
|
|
231
232
|
}, { bumpSeq: true });
|
|
232
|
-
|
|
233
|
+
// Issued inside this transaction's callback: on a queue that
|
|
234
|
+
// shares the workflow's driver the effect job commits with the
|
|
235
|
+
// row it was dispatched from, or not at all (a transactional
|
|
236
|
+
// outbox). On a queue with a connection of its own the insert
|
|
237
|
+
// stands alone, and `runEffect`'s fence covers the gap.
|
|
238
|
+
await enqueuer.enqueueEffect(meta.handler, {
|
|
233
239
|
tenant_id,
|
|
234
240
|
instance_id,
|
|
235
241
|
handler: meta.handler,
|
|
236
242
|
seq: settled.seq,
|
|
237
243
|
cursor: settled.cursor,
|
|
238
244
|
});
|
|
239
|
-
await appendHistory(
|
|
245
|
+
await appendHistory(tx, {
|
|
240
246
|
tenant_id,
|
|
241
247
|
instance_id,
|
|
242
248
|
event_type: HISTORY_EVENT.EFFECT_DISPATCHED,
|
|
@@ -251,7 +257,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
251
257
|
: null;
|
|
252
258
|
// The token is whatever create() set or the handler returned — the
|
|
253
259
|
// driver never generates one.
|
|
254
|
-
const settled = await updateInstance(
|
|
260
|
+
const settled = await updateInstance(tx, instance_id, {
|
|
255
261
|
cursor: positioned.state,
|
|
256
262
|
previous_cursor: positioned.previous,
|
|
257
263
|
context: positioned.context,
|
|
@@ -267,7 +273,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
267
273
|
clog.warn?.(`advance: instance ${instance_id} waits at "${positioned.state}" ` +
|
|
268
274
|
`with no correlation_token — no signal can reach it`);
|
|
269
275
|
}
|
|
270
|
-
await appendHistory(
|
|
276
|
+
await appendHistory(tx, {
|
|
271
277
|
tenant_id,
|
|
272
278
|
instance_id,
|
|
273
279
|
event_type: HISTORY_EVENT.TRANSITION,
|
|
@@ -280,7 +286,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
280
286
|
const before = positioned.state;
|
|
281
287
|
const result = positioned.transition(PURE_ENTER_EVENT, undefined, false);
|
|
282
288
|
if (result === null) {
|
|
283
|
-
await appendHistory(
|
|
289
|
+
await appendHistory(tx, {
|
|
284
290
|
tenant_id,
|
|
285
291
|
instance_id,
|
|
286
292
|
event_type: HISTORY_EVENT.TRANSITION_REJECTED,
|
|
@@ -290,10 +296,10 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
290
296
|
reason: "no guarded transition matched",
|
|
291
297
|
},
|
|
292
298
|
});
|
|
293
|
-
await failInstance(
|
|
299
|
+
await failInstance(tx, row, `pure state "${before}" did not route on ENTER`);
|
|
294
300
|
return;
|
|
295
301
|
}
|
|
296
|
-
await appendHistory(
|
|
302
|
+
await appendHistory(tx, {
|
|
297
303
|
tenant_id,
|
|
298
304
|
instance_id,
|
|
299
305
|
event_type: HISTORY_EVENT.TRANSITION,
|
|
@@ -305,20 +311,20 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
|
|
|
305
311
|
break;
|
|
306
312
|
}
|
|
307
313
|
default: {
|
|
308
|
-
await failInstance(
|
|
314
|
+
await failInstance(tx, row, `unknown meta.kind "${String(meta.kind)}" at state "${positioned.state}"`);
|
|
309
315
|
return;
|
|
310
316
|
}
|
|
311
317
|
}
|
|
312
318
|
}
|
|
313
|
-
await failInstance(
|
|
319
|
+
await failInstance(tx, row, `exceeded ${MAX_PURE_HOPS} pure-state hops (likely cycle)`);
|
|
314
320
|
});
|
|
315
321
|
}
|
|
316
|
-
async function failInstance(
|
|
322
|
+
async function failInstance(db, row, reason, extra = {}) {
|
|
317
323
|
clog.error?.(`workflow instance ${row.id} failed: ${reason}`);
|
|
318
|
-
await updateInstance(
|
|
324
|
+
await updateInstance(db, row.id, {
|
|
319
325
|
execution_state: EXECUTION_STATE.FAILED,
|
|
320
326
|
}, { bumpSeq: true });
|
|
321
|
-
await appendHistory(
|
|
327
|
+
await appendHistory(db, {
|
|
322
328
|
tenant_id: row.tenant_id,
|
|
323
329
|
instance_id: row.id,
|
|
324
330
|
event_type: HISTORY_EVENT.FAILED,
|
|
@@ -335,9 +341,9 @@ async function failInstance(client, row, reason, extra = {}) {
|
|
|
335
341
|
* Fenced like every other write: an advance that lost the race to a later one
|
|
336
342
|
* must not fail the instance that later one moved on.
|
|
337
343
|
*/
|
|
338
|
-
export async function failAdvanceJob(
|
|
339
|
-
await
|
|
340
|
-
const row = await lockInstance(
|
|
344
|
+
export async function failAdvanceJob(db, payload, reason, jobUid) {
|
|
345
|
+
await db.transaction(async (tx) => {
|
|
346
|
+
const row = await lockInstance(tx, payload.instance_id);
|
|
341
347
|
if (!row)
|
|
342
348
|
return;
|
|
343
349
|
if (payload.expected_seq !== undefined && row.seq !== payload.expected_seq) {
|
|
@@ -349,7 +355,7 @@ export async function failAdvanceJob(pool, payload, reason, jobUid) {
|
|
|
349
355
|
row.execution_state === EXECUTION_STATE.CANCELLED) {
|
|
350
356
|
return;
|
|
351
357
|
}
|
|
352
|
-
await failInstance(
|
|
358
|
+
await failInstance(tx, row, reason, { job_uid: jobUid ?? null });
|
|
353
359
|
});
|
|
354
360
|
}
|
|
355
361
|
/**
|
|
@@ -371,30 +377,20 @@ export async function failAdvanceJob(pool, payload, reason, jobUid) {
|
|
|
371
377
|
* mid-execution, and even successful handlers can run twice if completion-write
|
|
372
378
|
* fails after the advance has been enqueued.
|
|
373
379
|
*/
|
|
374
|
-
export async function runEffect(
|
|
380
|
+
export async function runEffect(db, registry, enqueuer, payload, signal) {
|
|
375
381
|
const { instance_id, handler: handlerName } = payload;
|
|
376
382
|
const tenant_id = payloadTenantId(payload);
|
|
377
383
|
const handler = registry.requireHandler(handlerName);
|
|
378
|
-
const
|
|
379
|
-
let row;
|
|
380
|
-
try {
|
|
381
|
-
const r = await client.query(`SELECT id, tenant_id, definition_id, definition_version, cursor,
|
|
382
|
-
previous_cursor, context, execution_state, wake_at,
|
|
383
|
-
correlation_token, seq, created_at, updated_at
|
|
384
|
-
FROM __workflow_instances WHERE id = $1`, [instance_id]);
|
|
385
|
-
row = r.rows[0] ?? null;
|
|
386
|
-
}
|
|
387
|
-
finally {
|
|
388
|
-
client.release();
|
|
389
|
-
}
|
|
384
|
+
const row = await findInstance(db, instance_id);
|
|
390
385
|
if (!row) {
|
|
391
386
|
throw new Error(`effect: instance ${instance_id} not found`);
|
|
392
387
|
}
|
|
393
388
|
if (payload.seq !== undefined && row.seq !== payload.seq) {
|
|
394
389
|
if (row.seq < payload.seq) {
|
|
395
|
-
// The dispatching advance has not committed yet
|
|
396
|
-
//
|
|
397
|
-
//
|
|
390
|
+
// The dispatching advance has not committed yet: a queue on a database
|
|
391
|
+
// connection of its own inserts the job outside that transaction, so
|
|
392
|
+
// the job can be claimed before it lands. Throw to retry. (A queue
|
|
393
|
+
// that shares the workflow's driver inserts it inside: no such window.)
|
|
398
394
|
throw new Error(`effect: instance ${instance_id} not yet at seq ${payload.seq} (row.seq=${row.seq})`);
|
|
399
395
|
}
|
|
400
396
|
clog.debug?.(`effect: stale ${handlerName} (row.seq=${row.seq}, job seq=${payload.seq}); skipped`);
|
|
@@ -410,7 +406,7 @@ export async function runEffect(pool, registry, enqueuer, payload, signal) {
|
|
|
410
406
|
context: row.context,
|
|
411
407
|
signal,
|
|
412
408
|
});
|
|
413
|
-
await enqueuer.enqueueAdvance(
|
|
409
|
+
await enqueuer.enqueueAdvance({
|
|
414
410
|
tenant_id,
|
|
415
411
|
instance_id,
|
|
416
412
|
kind: "effect",
|
|
@@ -429,9 +425,9 @@ export async function runEffect(pool, registry, enqueuer, payload, signal) {
|
|
|
429
425
|
* unless the job is fenced out, i.e. it belongs to a step the instance has
|
|
430
426
|
* already left, in which case a dead job must not kill a healthy instance.
|
|
431
427
|
*/
|
|
432
|
-
export async function failEffectJob(
|
|
433
|
-
await
|
|
434
|
-
const row = await lockInstance(
|
|
428
|
+
export async function failEffectJob(db, payload, reason) {
|
|
429
|
+
await db.transaction(async (tx) => {
|
|
430
|
+
const row = await lockInstance(tx, payload.instance_id);
|
|
435
431
|
if (!row)
|
|
436
432
|
return;
|
|
437
433
|
if (payload.seq !== undefined && row.seq !== payload.seq) {
|
|
@@ -443,10 +439,10 @@ export async function failEffectJob(pool, payload, reason) {
|
|
|
443
439
|
row.execution_state === EXECUTION_STATE.CANCELLED) {
|
|
444
440
|
return;
|
|
445
441
|
}
|
|
446
|
-
await updateInstance(
|
|
442
|
+
await updateInstance(tx, row.id, {
|
|
447
443
|
execution_state: EXECUTION_STATE.FAILED,
|
|
448
444
|
}, { bumpSeq: true });
|
|
449
|
-
await appendHistory(
|
|
445
|
+
await appendHistory(tx, {
|
|
450
446
|
tenant_id: row.tenant_id,
|
|
451
447
|
instance_id: row.id,
|
|
452
448
|
event_type: HISTORY_EVENT.EFFECT_FAILED,
|
|
@@ -1,8 +1,9 @@
|
|
|
1
|
+
import type { MigrateContext } from "@marianmeres/sqlkit/migrate";
|
|
1
2
|
/**
|
|
2
3
|
* Forward migration for schema version 1.0.0 — creates the three framework
|
|
3
|
-
* tables and their indexes.
|
|
4
|
-
*
|
|
4
|
+
* tables and their indexes. Runs on the driver {@link createMigrate} hands every
|
|
5
|
+
* worker, inside the step's transaction.
|
|
5
6
|
*/
|
|
6
|
-
export declare function up(
|
|
7
|
+
export declare function up({ db }: MigrateContext): Promise<void>;
|
|
7
8
|
/** Reverse migration — drops the three framework tables. Destructive. */
|
|
8
|
-
export declare function down(
|
|
9
|
+
export declare function down({ db }: MigrateContext): Promise<void>;
|
package/dist/migrations/1_0_0.js
CHANGED
|
@@ -60,27 +60,13 @@ DROP TABLE IF EXISTS __workflow_instances;
|
|
|
60
60
|
`;
|
|
61
61
|
/**
|
|
62
62
|
* Forward migration for schema version 1.0.0 — creates the three framework
|
|
63
|
-
* tables and their indexes.
|
|
64
|
-
*
|
|
63
|
+
* tables and their indexes. Runs on the driver {@link createMigrate} hands every
|
|
64
|
+
* worker, inside the step's transaction.
|
|
65
65
|
*/
|
|
66
|
-
export async function up(
|
|
67
|
-
|
|
68
|
-
const client = await pool.connect();
|
|
69
|
-
try {
|
|
70
|
-
await client.query(SQL_UP);
|
|
71
|
-
}
|
|
72
|
-
finally {
|
|
73
|
-
client.release();
|
|
74
|
-
}
|
|
66
|
+
export async function up({ db }) {
|
|
67
|
+
await db.exec(SQL_UP);
|
|
75
68
|
}
|
|
76
69
|
/** Reverse migration — drops the three framework tables. Destructive. */
|
|
77
|
-
export async function down(
|
|
78
|
-
|
|
79
|
-
const client = await pool.connect();
|
|
80
|
-
try {
|
|
81
|
-
await client.query(SQL_DOWN);
|
|
82
|
-
}
|
|
83
|
-
finally {
|
|
84
|
-
client.release();
|
|
85
|
-
}
|
|
70
|
+
export async function down({ db }) {
|
|
71
|
+
await db.exec(SQL_DOWN);
|
|
86
72
|
}
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { MigrateContext } from "@marianmeres/sqlkit/migrate";
|
|
1
2
|
/**
|
|
2
3
|
* Forward migration for schema version 1.1.0 — renames `project_id` to
|
|
3
4
|
* `tenant_id` on all three framework tables, aligning with the ecosystem's
|
|
@@ -6,6 +7,6 @@
|
|
|
6
7
|
* The rename is in place: existing data is preserved. Idempotent — safe to run
|
|
7
8
|
* against a schema that already uses `tenant_id`.
|
|
8
9
|
*/
|
|
9
|
-
export declare function up(
|
|
10
|
+
export declare function up({ db }: MigrateContext): Promise<void>;
|
|
10
11
|
/** Reverse migration — renames `tenant_id` back to `project_id`. Non-destructive. */
|
|
11
|
-
export declare function down(
|
|
12
|
+
export declare function down({ db }: MigrateContext): Promise<void>;
|
package/dist/migrations/1_1_0.js
CHANGED
|
@@ -23,11 +23,7 @@ function renameColumn(table, from, to) {
|
|
|
23
23
|
END $$;
|
|
24
24
|
`;
|
|
25
25
|
}
|
|
26
|
-
const TABLES = [
|
|
27
|
-
"__workflow_instances",
|
|
28
|
-
"__workflow_inbox",
|
|
29
|
-
"__workflow_history",
|
|
30
|
-
];
|
|
26
|
+
const TABLES = ["__workflow_instances", "__workflow_inbox", "__workflow_history"];
|
|
31
27
|
const SQL_UP = TABLES.map((t) => renameColumn(t, "project_id", "tenant_id")).join("\n");
|
|
32
28
|
const SQL_DOWN = TABLES.map((t) => renameColumn(t, "tenant_id", "project_id")).join("\n");
|
|
33
29
|
/**
|
|
@@ -38,24 +34,10 @@ const SQL_DOWN = TABLES.map((t) => renameColumn(t, "tenant_id", "project_id")).j
|
|
|
38
34
|
* The rename is in place: existing data is preserved. Idempotent — safe to run
|
|
39
35
|
* against a schema that already uses `tenant_id`.
|
|
40
36
|
*/
|
|
41
|
-
export async function up(
|
|
42
|
-
|
|
43
|
-
const client = await pool.connect();
|
|
44
|
-
try {
|
|
45
|
-
await client.query(SQL_UP);
|
|
46
|
-
}
|
|
47
|
-
finally {
|
|
48
|
-
client.release();
|
|
49
|
-
}
|
|
37
|
+
export async function up({ db }) {
|
|
38
|
+
await db.exec(SQL_UP);
|
|
50
39
|
}
|
|
51
40
|
/** Reverse migration — renames `tenant_id` back to `project_id`. Non-destructive. */
|
|
52
|
-
export async function down(
|
|
53
|
-
|
|
54
|
-
const client = await pool.connect();
|
|
55
|
-
try {
|
|
56
|
-
await client.query(SQL_DOWN);
|
|
57
|
-
}
|
|
58
|
-
finally {
|
|
59
|
-
client.release();
|
|
60
|
-
}
|
|
41
|
+
export async function down({ db }) {
|
|
42
|
+
await db.exec(SQL_DOWN);
|
|
61
43
|
}
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { MigrateContext } from "@marianmeres/sqlkit/migrate";
|
|
1
2
|
/**
|
|
2
3
|
* Forward migration for schema version 1.2.0 — adds the `seq` fencing token to
|
|
3
4
|
* `__workflow_instances`, plus the partial index the scheduler's stale-`pending`
|
|
@@ -11,6 +12,6 @@
|
|
|
11
12
|
* change: existing rows are not rewritten and start at `0`. The index is partial
|
|
12
13
|
* on a transient state, so it stays tiny.
|
|
13
14
|
*/
|
|
14
|
-
export declare function up(
|
|
15
|
+
export declare function up({ db }: MigrateContext): Promise<void>;
|
|
15
16
|
/** Reverse migration — drops `seq`. Destructive only of the fence itself. */
|
|
16
|
-
export declare function down(
|
|
17
|
+
export declare function down({ db }: MigrateContext): Promise<void>;
|
package/dist/migrations/1_2_0.js
CHANGED
|
@@ -21,24 +21,10 @@ ALTER TABLE __workflow_instances DROP COLUMN IF EXISTS seq;
|
|
|
21
21
|
* change: existing rows are not rewritten and start at `0`. The index is partial
|
|
22
22
|
* on a transient state, so it stays tiny.
|
|
23
23
|
*/
|
|
24
|
-
export async function up(
|
|
25
|
-
|
|
26
|
-
const client = await pool.connect();
|
|
27
|
-
try {
|
|
28
|
-
await client.query(SQL_UP);
|
|
29
|
-
}
|
|
30
|
-
finally {
|
|
31
|
-
client.release();
|
|
32
|
-
}
|
|
24
|
+
export async function up({ db }) {
|
|
25
|
+
await db.exec(SQL_UP);
|
|
33
26
|
}
|
|
34
27
|
/** Reverse migration — drops `seq`. Destructive only of the fence itself. */
|
|
35
|
-
export async function down(
|
|
36
|
-
|
|
37
|
-
const client = await pool.connect();
|
|
38
|
-
try {
|
|
39
|
-
await client.query(SQL_DOWN);
|
|
40
|
-
}
|
|
41
|
-
finally {
|
|
42
|
-
client.release();
|
|
43
|
-
}
|
|
28
|
+
export async function down({ db }) {
|
|
29
|
+
await db.exec(SQL_DOWN);
|
|
44
30
|
}
|
|
@@ -1,11 +1,21 @@
|
|
|
1
|
-
import { Migrate } from "@marianmeres/migrate";
|
|
2
|
-
import type
|
|
1
|
+
import type { Migrate } from "@marianmeres/migrate";
|
|
2
|
+
import { type MigrateContext } from "@marianmeres/sqlkit/migrate";
|
|
3
|
+
import { type PgDb } from "@marianmeres/sqlkit/pg";
|
|
3
4
|
/**
|
|
4
5
|
* Builds a {@link Migrate} instance pre-loaded with the package's schema
|
|
5
6
|
* versions. The caller drives it (`.up('latest')`, `.down(...)`, etc.).
|
|
6
7
|
*
|
|
8
|
+
* It is sqlkit's migrate wiring over `db`: a run holds an advisory lock, so two
|
|
9
|
+
* processes booting at once wait for each other, and each version is applied in
|
|
10
|
+
* a transaction of its own, together with its version mark.
|
|
11
|
+
*
|
|
7
12
|
* The active version is stored in `__workflow_migrations` (one row per change,
|
|
8
|
-
* latest row wins).
|
|
13
|
+
* latest row wins). A table an earlier version of this package created is read
|
|
14
|
+
* and continued as it is.
|
|
15
|
+
*
|
|
16
|
+
* @param db - a `pg.Pool`, a connected `pg.Client`, or a sqlkit `Driver` of the
|
|
17
|
+
* `pg` dialect. Never closed here.
|
|
18
|
+
* @throws {TypeError} If `db` is none of the three.
|
|
9
19
|
*
|
|
10
20
|
* @example
|
|
11
21
|
* ```ts
|
|
@@ -17,6 +27,6 @@ import type pg from "pg";
|
|
|
17
27
|
* await migrate.up("latest");
|
|
18
28
|
* ```
|
|
19
29
|
*/
|
|
20
|
-
export declare function createMigrate(
|
|
30
|
+
export declare function createMigrate(db: PgDb, options?: {
|
|
21
31
|
logger?: (...args: unknown[]) => void;
|
|
22
|
-
}): Migrate
|
|
32
|
+
}): Migrate<MigrateContext>;
|
package/dist/migrations/index.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { createMigrate as createDriverMigrate, } from "@marianmeres/sqlkit/migrate";
|
|
2
|
+
import { toPgDriver } from "@marianmeres/sqlkit/pg";
|
|
2
3
|
import { down as down_1_0_0, up as up_1_0_0 } from "./1_0_0.js";
|
|
3
4
|
import { down as down_1_1_0, up as up_1_1_0 } from "./1_1_0.js";
|
|
4
5
|
import { down as down_1_2_0, up as up_1_2_0 } from "./1_2_0.js";
|
|
@@ -7,8 +8,17 @@ const VERSION_TABLE = "__workflow_migrations";
|
|
|
7
8
|
* Builds a {@link Migrate} instance pre-loaded with the package's schema
|
|
8
9
|
* versions. The caller drives it (`.up('latest')`, `.down(...)`, etc.).
|
|
9
10
|
*
|
|
11
|
+
* It is sqlkit's migrate wiring over `db`: a run holds an advisory lock, so two
|
|
12
|
+
* processes booting at once wait for each other, and each version is applied in
|
|
13
|
+
* a transaction of its own, together with its version mark.
|
|
14
|
+
*
|
|
10
15
|
* The active version is stored in `__workflow_migrations` (one row per change,
|
|
11
|
-
* latest row wins).
|
|
16
|
+
* latest row wins). A table an earlier version of this package created is read
|
|
17
|
+
* and continued as it is.
|
|
18
|
+
*
|
|
19
|
+
* @param db - a `pg.Pool`, a connected `pg.Client`, or a sqlkit `Driver` of the
|
|
20
|
+
* `pg` dialect. Never closed here.
|
|
21
|
+
* @throws {TypeError} If `db` is none of the three.
|
|
12
22
|
*
|
|
13
23
|
* @example
|
|
14
24
|
* ```ts
|
|
@@ -20,45 +30,13 @@ const VERSION_TABLE = "__workflow_migrations";
|
|
|
20
30
|
* await migrate.up("latest");
|
|
21
31
|
* ```
|
|
22
32
|
*/
|
|
23
|
-
export function createMigrate(
|
|
24
|
-
const migrate =
|
|
25
|
-
|
|
26
|
-
setActiveVersion: setActiveVersion,
|
|
33
|
+
export function createMigrate(db, options = {}) {
|
|
34
|
+
const migrate = createDriverMigrate(toPgDriver(db), {
|
|
35
|
+
table: VERSION_TABLE,
|
|
27
36
|
logger: options.logger,
|
|
28
|
-
}
|
|
37
|
+
});
|
|
29
38
|
migrate.addVersion("1.0.0", up_1_0_0, down_1_0_0);
|
|
30
39
|
migrate.addVersion("1.1.0", up_1_1_0, down_1_1_0);
|
|
31
40
|
migrate.addVersion("1.2.0", up_1_2_0, down_1_2_0);
|
|
32
41
|
return migrate;
|
|
33
42
|
}
|
|
34
|
-
async function ensureVersionTable(client) {
|
|
35
|
-
await client.query(`CREATE TABLE IF NOT EXISTS ${VERSION_TABLE} (
|
|
36
|
-
id serial PRIMARY KEY,
|
|
37
|
-
version text NULL,
|
|
38
|
-
created_at timestamptz NOT NULL DEFAULT now()
|
|
39
|
-
)`);
|
|
40
|
-
}
|
|
41
|
-
async function getActiveVersion(ctx) {
|
|
42
|
-
const { pool } = ctx;
|
|
43
|
-
const client = await pool.connect();
|
|
44
|
-
try {
|
|
45
|
-
await ensureVersionTable(client);
|
|
46
|
-
const r = await client.query(`SELECT version FROM ${VERSION_TABLE} ORDER BY id DESC LIMIT 1`);
|
|
47
|
-
return r.rows[0]?.version ?? undefined;
|
|
48
|
-
}
|
|
49
|
-
finally {
|
|
50
|
-
client.release();
|
|
51
|
-
}
|
|
52
|
-
}
|
|
53
|
-
async function setActiveVersion(version, ctx) {
|
|
54
|
-
const { pool } = ctx;
|
|
55
|
-
const client = await pool.connect();
|
|
56
|
-
try {
|
|
57
|
-
await ensureVersionTable(client);
|
|
58
|
-
await client.query(`INSERT INTO ${VERSION_TABLE} (version) VALUES ($1)`, [version ?? null]);
|
|
59
|
-
return version;
|
|
60
|
-
}
|
|
61
|
-
finally {
|
|
62
|
-
client.release();
|
|
63
|
-
}
|
|
64
|
-
}
|
package/dist/mod.d.ts
CHANGED
|
@@ -4,11 +4,14 @@
|
|
|
4
4
|
* Durable workflow / orchestration framework for long-lived state machines.
|
|
5
5
|
* Built on PostgreSQL. Instances persist across process restarts, sleep for
|
|
6
6
|
* days waiting for a signal or a timer, and resume from disk via
|
|
7
|
-
* {@link https://
|
|
8
|
-
* Effects run as {@link https://
|
|
7
|
+
* {@link https://www.npmjs.com/package/@marianmeres/fsm | @marianmeres/fsm}'s `fromSnapshot`.
|
|
8
|
+
* Effects run as {@link https://www.npmjs.com/package/@marianmeres/steve | @marianmeres/steve}
|
|
9
9
|
* jobs (transactional outbox). The scheduler and inbox correlator are driven
|
|
10
|
-
* by {@link https://
|
|
11
|
-
*
|
|
10
|
+
* by {@link https://www.npmjs.com/package/@marianmeres/cron | @marianmeres/cron}.
|
|
11
|
+
* Every statement runs through
|
|
12
|
+
* {@link https://www.npmjs.com/package/@marianmeres/sqlkit | @marianmeres/sqlkit},
|
|
13
|
+
* which also runs the schema migrations
|
|
14
|
+
* ({@link https://www.npmjs.com/package/@marianmeres/migrate | @marianmeres/migrate}).
|
|
12
15
|
*
|
|
13
16
|
* Ships no domain code — userland brings the definitions, handlers, and
|
|
14
17
|
* matchers. The framework provides the dispatch core and the durability story.
|
|
@@ -20,6 +23,9 @@
|
|
|
20
23
|
* import { Cron } from "@marianmeres/cron";
|
|
21
24
|
* import { createMigrate, Workflow } from "@marianmeres/workflow";
|
|
22
25
|
*
|
|
26
|
+
* // `db` is a pg.Pool, a connected pg.Client, or a sqlkit Driver. Give the
|
|
27
|
+
* // same one to Jobs and Workflow: they then share transactions, so a job is
|
|
28
|
+
* // enqueued in the same transaction as the instance write it belongs to.
|
|
23
29
|
* const pool = new pg.Pool({ /* ... *\/ });
|
|
24
30
|
* await createMigrate(pool).up("latest");
|
|
25
31
|
*
|
|
@@ -38,12 +44,12 @@
|
|
|
38
44
|
* await wf.create({ definitionId: "...", definitionVersion: "1.0.0" });
|
|
39
45
|
* ```
|
|
40
46
|
*/
|
|
41
|
-
export {
|
|
42
|
-
export {
|
|
43
|
-
export {
|
|
44
|
-
export {
|
|
45
|
-
export {
|
|
46
|
-
export {
|
|
47
|
-
export {
|
|
48
|
-
export {
|
|
49
|
-
export {
|
|
47
|
+
export { WorkflowInboxCorrelator, type WorkflowInboxCorrelatorOptions, } from "./correlator.ts";
|
|
48
|
+
export { defKey, validateDefinition } from "./definition.ts";
|
|
49
|
+
export { effectJobType, JOB_TYPE_ADVANCE, PURE_ENTER_EVENT } from "./driver.ts";
|
|
50
|
+
export { createMigrate } from "./migrations/index.ts";
|
|
51
|
+
export { getHistory } from "./persistence/history.ts";
|
|
52
|
+
export { WorkflowRegistry } from "./registry.ts";
|
|
53
|
+
export { type SchedulerTickResult, WorkflowScheduler, type WorkflowSchedulerOptions, } from "./scheduler.ts";
|
|
54
|
+
export { type AdvanceJobPayload, type AdvanceKind, DEFAULT_TENANT_ID, type EffectJobPayload, EXECUTION_STATE, type ExecutionState, type Handler, type HandlerArgs, type HandlerResult, HISTORY_EVENT, type HistoryEventType, type HistoryRow, type InboxRow, JOB_TYPE_EFFECT_PREFIX, type Matcher, type MatcherArgs, type NodeMeta, type WorkflowContext, type WorkflowDefinition, type WorkflowFSMConfig, type WorkflowInstanceRow, type WorkflowSnapshot, type WorkflowStateConfig, } from "./types.ts";
|
|
55
|
+
export { Workflow, type WorkflowOptions } from "./workflow.ts";
|