@marianmeres/workflow 1.0.1 → 2.2.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 +207 -94
- package/API.md +277 -157
- package/README.md +182 -83
- package/dist/correlator.d.ts +31 -14
- package/dist/correlator.js +130 -73
- package/dist/definition.d.ts +5 -1
- package/dist/definition.js +54 -1
- package/dist/driver.d.ts +28 -23
- package/dist/driver.js +223 -59
- package/dist/migrations/1_1_0.d.ts +11 -0
- package/dist/migrations/1_1_0.js +61 -0
- package/dist/migrations/1_2_0.d.ts +16 -0
- package/dist/migrations/1_2_0.js +44 -0
- package/dist/migrations/index.js +5 -1
- package/dist/mod.d.ts +8 -5
- package/dist/mod.js +7 -4
- package/dist/persistence/history.d.ts +1 -1
- package/dist/persistence/history.js +3 -3
- package/dist/persistence/inbox.d.ts +9 -3
- package/dist/persistence/inbox.js +16 -7
- package/dist/persistence/instances.d.ts +46 -13
- package/dist/persistence/instances.js +78 -33
- package/dist/scheduler.d.ts +33 -9
- package/dist/scheduler.js +45 -21
- package/dist/types.d.ts +126 -13
- package/dist/types.js +28 -2
- package/dist/workflow.d.ts +76 -4
- package/dist/workflow.js +237 -35
- package/docs/_archive/analysis/00-overview-and-roadmap.md +233 -0
- package/docs/_archive/analysis/01-durability.md +404 -0
- package/docs/_archive/analysis/02-correlation.md +228 -0
- package/docs/_archive/analysis/03-definition-and-api.md +248 -0
- package/docs/_archive/analysis/04-docs-tests-ops.md +191 -0
- package/docs/_archive/analysis/PROGRESS.md +172 -0
- package/docs/_archive/analysis/README.md +38 -0
- package/package.json +9 -8
package/dist/correlator.js
CHANGED
|
@@ -1,23 +1,37 @@
|
|
|
1
|
+
import { SIGNAL_MATCHED_EVENT } from "./driver.js";
|
|
1
2
|
import { clog } from "./log.js";
|
|
2
3
|
import { appendHistory } from "./persistence/history.js";
|
|
3
4
|
import { claimUnprocessed, markProcessed } from "./persistence/inbox.js";
|
|
4
|
-
import {
|
|
5
|
+
import { findByCorrelation, findTerminalByCorrelation } from "./persistence/instances.js";
|
|
5
6
|
import { withTransaction } from "./persistence/tx.js";
|
|
6
7
|
import { EXECUTION_STATE, HISTORY_EVENT, } from "./types.js";
|
|
7
8
|
const DEFAULT_TICK_EXPRESSION = "* * * * *";
|
|
8
9
|
/**
|
|
9
|
-
* Cron-driven correlator that matches `__workflow_inbox` rows to
|
|
10
|
-
*
|
|
10
|
+
* Cron-driven correlator that matches `__workflow_inbox` rows to workflow
|
|
11
|
+
* instances. On each tick it claims a batch of unprocessed rows
|
|
12
|
+
* (`FOR UPDATE SKIP LOCKED`) and, per row, finds the live instance owning the
|
|
13
|
+
* correlation token:
|
|
11
14
|
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
15
|
+
* | Instance | Action |
|
|
16
|
+
* | ----------------------------------------------- | --------------------------------------------------- |
|
|
17
|
+
* | none / terminal | mark processed (+ `signal_rejected` if terminal) |
|
|
18
|
+
* | live but not `waiting` | defer |
|
|
19
|
+
* | `waiting` at a node that has no `MATCHED` edge | defer |
|
|
20
|
+
* | `waiting`, matcher says no | `signal_rejected`, mark processed |
|
|
21
|
+
* | `waiting`, matcher says yes | poke an advance; the advance does the rest |
|
|
22
|
+
*
|
|
23
|
+
* "Defer" means: leave the row unprocessed and look at it again next tick. A
|
|
24
|
+
* signal that arrives before its wait point — the instance is still running the
|
|
25
|
+
* step that emits the token, or sits at a timer-only node — is early, not
|
|
26
|
+
* wrong; consuming it would lose it, and delivering it to a node with no
|
|
27
|
+
* `MATCHED` edge would fail the instance.
|
|
28
|
+
*
|
|
29
|
+
* The correlator only pokes: it never writes the instance row. The advance
|
|
30
|
+
* transitions the instance, records `signal_received` and marks the inbox row
|
|
31
|
+
* processed in one transaction, so a crashed poke is simply re-poked next tick.
|
|
32
|
+
*
|
|
33
|
+
* Starvation note: rows are claimed `ORDER BY received_at LIMIT tickBatchSize`,
|
|
34
|
+
* so a backlog of deferred rows larger than the batch would shadow newer ones.
|
|
21
35
|
*
|
|
22
36
|
* Like {@link WorkflowScheduler}, the correlator does not own its `Cron`. The
|
|
23
37
|
* caller constructs a `Cron`, passes it in, runs its lifecycle. Call
|
|
@@ -25,7 +39,7 @@ const DEFAULT_TICK_EXPRESSION = "* * * * *";
|
|
|
25
39
|
*/
|
|
26
40
|
export class WorkflowInboxCorrelator {
|
|
27
41
|
cron;
|
|
28
|
-
|
|
42
|
+
tenantId;
|
|
29
43
|
tickExpression;
|
|
30
44
|
tickName;
|
|
31
45
|
#workflow;
|
|
@@ -34,9 +48,9 @@ export class WorkflowInboxCorrelator {
|
|
|
34
48
|
constructor(options) {
|
|
35
49
|
this.cron = options.cron;
|
|
36
50
|
this.#workflow = options.workflow;
|
|
37
|
-
this.
|
|
51
|
+
this.tenantId = options.workflow.tenantId;
|
|
38
52
|
this.tickExpression = options.tickExpression ?? DEFAULT_TICK_EXPRESSION;
|
|
39
|
-
this.tickName = options.tickName ?? `workflow.correlator.${this.
|
|
53
|
+
this.tickName = options.tickName ?? `workflow.correlator.${this.tenantId}`;
|
|
40
54
|
this.#tickBatchSize = options.tickBatchSize ?? 100;
|
|
41
55
|
this.#timezone = options.timezone;
|
|
42
56
|
}
|
|
@@ -55,90 +69,133 @@ export class WorkflowInboxCorrelator {
|
|
|
55
69
|
async unregister() {
|
|
56
70
|
await this.cron.unregister(this.tickName);
|
|
57
71
|
}
|
|
58
|
-
/**
|
|
72
|
+
/**
|
|
73
|
+
* Runs one tick immediately. Exposed for testing and on-demand matches.
|
|
74
|
+
* Returns the number of rows resolved — poked, rejected or marked processed.
|
|
75
|
+
* Deferred rows are not counted; they are still there next tick.
|
|
76
|
+
*/
|
|
59
77
|
async tickOnce() {
|
|
60
78
|
return await this.#tick();
|
|
61
79
|
}
|
|
62
80
|
async #tick() {
|
|
63
|
-
|
|
64
|
-
await withTransaction(this.#workflow.db, async (client) => {
|
|
65
|
-
const rows = await claimUnprocessed(client, this.
|
|
81
|
+
const pokes = [];
|
|
82
|
+
const resolved = await withTransaction(this.#workflow.db, async (client) => {
|
|
83
|
+
const rows = await claimUnprocessed(client, this.tenantId, this.#tickBatchSize);
|
|
84
|
+
// One poke per instance per tick: a second signal for the same
|
|
85
|
+
// instance would be fenced out by the first anyway, and deferring it
|
|
86
|
+
// keeps it for the instance's next wait point.
|
|
87
|
+
const poked = new Set();
|
|
88
|
+
let n = 0;
|
|
66
89
|
for (const row of rows) {
|
|
67
|
-
await this.#processOne(client, row)
|
|
68
|
-
|
|
90
|
+
if (await this.#processOne(client, row, poked, pokes))
|
|
91
|
+
n++;
|
|
69
92
|
}
|
|
93
|
+
return n;
|
|
70
94
|
});
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
95
|
+
// Deliberately after the commit: the advance blocks on the inbox row's
|
|
96
|
+
// lock, which this tick holds until then, and steve's insert needs a pool
|
|
97
|
+
// connection of its own — enqueuing under the claim risks starving the
|
|
98
|
+
// pool. Nothing is lost if the process dies here; the row is still
|
|
99
|
+
// unprocessed, so the next tick pokes again.
|
|
100
|
+
for (const payload of pokes) {
|
|
101
|
+
await this.#workflow.enqueueAdvance(this.#workflow.db, payload);
|
|
102
|
+
}
|
|
103
|
+
if (resolved > 0)
|
|
104
|
+
clog.debug?.(`correlator: resolved ${resolved} signals`);
|
|
105
|
+
return resolved;
|
|
106
|
+
}
|
|
107
|
+
/** Leaves the row unprocessed for a later tick. Always returns `false`. */
|
|
108
|
+
#defer(row, reason) {
|
|
109
|
+
clog.debug?.(`correlator: deferring inbox row ${row.id} (${reason})`);
|
|
110
|
+
return false;
|
|
74
111
|
}
|
|
75
|
-
|
|
76
|
-
|
|
112
|
+
/**
|
|
113
|
+
* True if the row was resolved, false if it was deferred. A delivery is
|
|
114
|
+
* resolved by appending to `pokes` — the tick enqueues those after it commits.
|
|
115
|
+
*/
|
|
116
|
+
async #processOne(client, row, poked, pokes) {
|
|
117
|
+
const instance = await findByCorrelation(client, this.tenantId, row.correlation_token);
|
|
118
|
+
// A token no live instance owns is an upstream bug, not something to wait
|
|
119
|
+
// for. (A completed or cancelled instance has its token cleared, so it
|
|
120
|
+
// lands here too — only failed ones are still findable.)
|
|
77
121
|
if (!instance) {
|
|
122
|
+
clog.warn?.(`correlator: no live instance for token "${row.correlation_token}" (inbox row ${row.id})`);
|
|
123
|
+
const terminal = await findTerminalByCorrelation(client, this.tenantId, row.correlation_token);
|
|
124
|
+
if (terminal) {
|
|
125
|
+
await appendHistory(client, {
|
|
126
|
+
tenant_id: this.tenantId,
|
|
127
|
+
instance_id: terminal.id,
|
|
128
|
+
event_type: HISTORY_EVENT.SIGNAL_REJECTED,
|
|
129
|
+
from_node: terminal.cursor,
|
|
130
|
+
data: {
|
|
131
|
+
source: row.source,
|
|
132
|
+
inbox_id: row.id,
|
|
133
|
+
reason: `instance is ${terminal.execution_state}`,
|
|
134
|
+
},
|
|
135
|
+
});
|
|
136
|
+
}
|
|
78
137
|
await markProcessed(client, row.id);
|
|
79
|
-
return;
|
|
138
|
+
return true;
|
|
139
|
+
}
|
|
140
|
+
if (instance.execution_state !== EXECUTION_STATE.WAITING) {
|
|
141
|
+
return this.#defer(row, `instance ${instance.id} is not waiting yet`);
|
|
142
|
+
}
|
|
143
|
+
if (poked.has(instance.id)) {
|
|
144
|
+
return this.#defer(row, `instance ${instance.id} already poked this tick`);
|
|
80
145
|
}
|
|
81
146
|
const def = this.#workflow.registry.getDefinition(instance.definition_id, instance.definition_version);
|
|
82
|
-
const stateCfg = def?.fsm
|
|
83
|
-
|
|
147
|
+
const stateCfg = def?.fsm
|
|
148
|
+
.states[instance.cursor];
|
|
149
|
+
// A node with no MATCHED (or wildcard) edge is not a delivery target:
|
|
150
|
+
// poking it would make the fsm reject the transition and fail the
|
|
151
|
+
// instance. Typically a timer-only delay node on the way to the real wait.
|
|
152
|
+
const on = stateCfg?.on ?? {};
|
|
153
|
+
if (!(SIGNAL_MATCHED_EVENT in on) && !("*" in on)) {
|
|
154
|
+
return this.#defer(row, `node "${instance.cursor}" does not accept MATCHED`);
|
|
155
|
+
}
|
|
84
156
|
// Run matcher if any. No matcher = correlation_token alone is the gate.
|
|
85
|
-
|
|
157
|
+
const meta = stateCfg?.meta;
|
|
86
158
|
if (meta && meta.kind === "suspending" && meta.matcher) {
|
|
87
|
-
|
|
88
|
-
if (!matcherFn) {
|
|
89
|
-
clog.error?.(`correlator: matcher "${meta.matcher}" not registered for instance ${instance.id}`);
|
|
90
|
-
await appendHistory(client, {
|
|
91
|
-
project_id: this.projectId,
|
|
92
|
-
instance_id: instance.id,
|
|
93
|
-
event_type: HISTORY_EVENT.SIGNAL_REJECTED,
|
|
94
|
-
from_node: instance.cursor,
|
|
95
|
-
data: { reason: `unregistered matcher "${meta.matcher}"` },
|
|
96
|
-
});
|
|
97
|
-
await markProcessed(client, row.id);
|
|
98
|
-
return;
|
|
99
|
-
}
|
|
159
|
+
let matched;
|
|
100
160
|
try {
|
|
161
|
+
const matcherFn = this.#workflow.registry.requireMatcher(meta.matcher);
|
|
101
162
|
matched = await matcherFn({
|
|
102
163
|
instanceId: instance.id,
|
|
103
|
-
|
|
164
|
+
tenantId: this.tenantId,
|
|
104
165
|
context: instance.context,
|
|
105
166
|
signal: row,
|
|
106
167
|
});
|
|
107
168
|
}
|
|
108
169
|
catch (e) {
|
|
170
|
+
// Deferring keeps a transient failure (a lookup, an HTTP call) from
|
|
171
|
+
// consuming the signal for good. A deterministic throw retries every
|
|
172
|
+
// tick with an error line — noisy, but not silent.
|
|
109
173
|
clog.error?.(`correlator: matcher "${meta.matcher}" threw: ${e}`);
|
|
110
|
-
|
|
174
|
+
return this.#defer(row, "matcher threw");
|
|
175
|
+
}
|
|
176
|
+
if (!matched) {
|
|
177
|
+
await appendHistory(client, {
|
|
178
|
+
tenant_id: this.tenantId,
|
|
179
|
+
instance_id: instance.id,
|
|
180
|
+
event_type: HISTORY_EVENT.SIGNAL_REJECTED,
|
|
181
|
+
from_node: instance.cursor,
|
|
182
|
+
data: { source: row.source, inbox_id: row.id },
|
|
183
|
+
});
|
|
184
|
+
await markProcessed(client, row.id);
|
|
185
|
+
return true;
|
|
111
186
|
}
|
|
112
187
|
}
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
data: { source: row.source, inbox_id: row.id },
|
|
120
|
-
});
|
|
121
|
-
await markProcessed(client, row.id);
|
|
122
|
-
return;
|
|
123
|
-
}
|
|
124
|
-
await appendHistory(client, {
|
|
125
|
-
project_id: this.projectId,
|
|
126
|
-
instance_id: instance.id,
|
|
127
|
-
event_type: HISTORY_EVENT.SIGNAL_RECEIVED,
|
|
128
|
-
from_node: instance.cursor,
|
|
129
|
-
data: { source: row.source, inbox_id: row.id },
|
|
130
|
-
});
|
|
131
|
-
await markProcessed(client, row.id);
|
|
132
|
-
// Flip to pending so the scheduler / a re-tick won't double-fire. The
|
|
133
|
-
// advance handler will load and route based on cursor/meta.
|
|
134
|
-
await client.query(`UPDATE __workflow_instances
|
|
135
|
-
SET execution_state = $2, wake_at = NULL, updated_at = now()
|
|
136
|
-
WHERE id = $1`, [instance.id, EXECUTION_STATE.PENDING]);
|
|
137
|
-
await this.#workflow.enqueueAdvance(this.#workflow.db, {
|
|
138
|
-
project_id: this.projectId,
|
|
188
|
+
// Poke only — no write to the instance row. The advance re-reads the inbox
|
|
189
|
+
// row under a lock, transitions, and marks it processed in one transaction;
|
|
190
|
+
// the fence makes a duplicate poke a no-op.
|
|
191
|
+
poked.add(instance.id);
|
|
192
|
+
pokes.push({
|
|
193
|
+
tenant_id: this.tenantId,
|
|
139
194
|
instance_id: instance.id,
|
|
140
|
-
|
|
141
|
-
|
|
195
|
+
kind: "signal",
|
|
196
|
+
expected_seq: instance.seq,
|
|
197
|
+
inbox_id: row.id,
|
|
142
198
|
});
|
|
199
|
+
return true;
|
|
143
200
|
}
|
|
144
201
|
}
|
package/dist/definition.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type
|
|
1
|
+
import { type WorkflowDefinition } from "./types.js";
|
|
2
2
|
/**
|
|
3
3
|
* Validates a workflow definition against a set of registered handler/matcher
|
|
4
4
|
* names. Throws on any structural problem.
|
|
@@ -11,6 +11,10 @@ import type { WorkflowDefinition } from "./types.js";
|
|
|
11
11
|
* - every `suspending` state's matcher (if present) is in `availableMatchers`
|
|
12
12
|
* - every transition target string resolves to a defined state
|
|
13
13
|
* - at least one terminal state exists
|
|
14
|
+
* - every node has an edge for the events it will actually receive: `ENTER` at a
|
|
15
|
+
* pure node, `TIMEOUT` where there is a `timeoutSec`, `MATCHED` where there is
|
|
16
|
+
* a matcher; an effectful node has at least one outcome edge, a suspending one
|
|
17
|
+
* has some way to wake, and a terminal one has none
|
|
14
18
|
*/
|
|
15
19
|
export declare function validateDefinition(def: WorkflowDefinition, available: {
|
|
16
20
|
handlers: ReadonlySet<string>;
|
package/dist/definition.js
CHANGED
|
@@ -1,3 +1,6 @@
|
|
|
1
|
+
import { PURE_ENTER_EVENT, SIGNAL_MATCHED_EVENT, TIMEOUT_EVENT, } from "./types.js";
|
|
2
|
+
/** fsm's catch-all event key: matched when the specific event has no edge. */
|
|
3
|
+
const WILDCARD_EVENT = "*";
|
|
1
4
|
/**
|
|
2
5
|
* Validates a workflow definition against a set of registered handler/matcher
|
|
3
6
|
* names. Throws on any structural problem.
|
|
@@ -10,6 +13,10 @@
|
|
|
10
13
|
* - every `suspending` state's matcher (if present) is in `availableMatchers`
|
|
11
14
|
* - every transition target string resolves to a defined state
|
|
12
15
|
* - at least one terminal state exists
|
|
16
|
+
* - every node has an edge for the events it will actually receive: `ENTER` at a
|
|
17
|
+
* pure node, `TIMEOUT` where there is a `timeoutSec`, `MATCHED` where there is
|
|
18
|
+
* a matcher; an effectful node has at least one outcome edge, a suspending one
|
|
19
|
+
* has some way to wake, and a terminal one has none
|
|
13
20
|
*/
|
|
14
21
|
export function validateDefinition(def, available) {
|
|
15
22
|
if (!def.id || typeof def.id !== "string") {
|
|
@@ -33,13 +40,27 @@ export function validateDefinition(def, available) {
|
|
|
33
40
|
const stateNames = new Set(Object.keys(def.fsm.states));
|
|
34
41
|
let terminalCount = 0;
|
|
35
42
|
for (const [stateName, stateCfg] of Object.entries(def.fsm.states)) {
|
|
43
|
+
// Typed as required by `WorkflowStateConfig`, but a JS caller can still
|
|
44
|
+
// hand us anything, so the runtime shape is checked all the same.
|
|
36
45
|
const meta = stateCfg.meta;
|
|
37
46
|
if (!meta || typeof meta !== "object") {
|
|
38
47
|
throw new Error(`Workflow definition "${def.id}@${def.version}": state "${stateName}" is missing meta`);
|
|
39
48
|
}
|
|
40
49
|
const kind = meta.kind;
|
|
50
|
+
// The events this node will actually be sent are decided by its kind, and
|
|
51
|
+
// an fsm that rejects one fails the instance — after any side effect at
|
|
52
|
+
// this node has already run. So the edges are checked here, not at runtime.
|
|
53
|
+
const on = stateCfg.on;
|
|
54
|
+
const events = new Set(Object.keys(on ?? {}));
|
|
55
|
+
const hasWildcard = events.has(WILDCARD_EVENT);
|
|
56
|
+
const accepts = (event) => events.has(event) || hasWildcard;
|
|
41
57
|
switch (kind) {
|
|
42
58
|
case "pure":
|
|
59
|
+
if (!accepts(PURE_ENTER_EVENT)) {
|
|
60
|
+
throw new Error(`Workflow definition "${def.id}@${def.version}": ` +
|
|
61
|
+
`pure state "${stateName}" has no "${PURE_ENTER_EVENT}" ` +
|
|
62
|
+
`(or "${WILDCARD_EVENT}") transition and could only fail on entry`);
|
|
63
|
+
}
|
|
43
64
|
break;
|
|
44
65
|
case "effectful": {
|
|
45
66
|
const h = meta.handler;
|
|
@@ -51,6 +72,11 @@ export function validateDefinition(def, available) {
|
|
|
51
72
|
throw new Error(`Workflow definition "${def.id}@${def.version}": ` +
|
|
52
73
|
`state "${stateName}" references unregistered handler "${h}"`);
|
|
53
74
|
}
|
|
75
|
+
if (events.size === 0) {
|
|
76
|
+
throw new Error(`Workflow definition "${def.id}@${def.version}": ` +
|
|
77
|
+
`effectful state "${stateName}" has no transitions, ` +
|
|
78
|
+
`so every outcome of "${h}" would be rejected`);
|
|
79
|
+
}
|
|
54
80
|
break;
|
|
55
81
|
}
|
|
56
82
|
case "suspending": {
|
|
@@ -64,10 +90,38 @@ export function validateDefinition(def, available) {
|
|
|
64
90
|
throw new Error(`Workflow definition "${def.id}@${def.version}": ` +
|
|
65
91
|
`state "${stateName}" references unregistered matcher "${m}"`);
|
|
66
92
|
}
|
|
93
|
+
if (!accepts(SIGNAL_MATCHED_EVENT)) {
|
|
94
|
+
throw new Error(`Workflow definition "${def.id}@${def.version}": ` +
|
|
95
|
+
`suspending state "${stateName}" has a matcher but no ` +
|
|
96
|
+
`"${SIGNAL_MATCHED_EVENT}" (or "${WILDCARD_EVENT}") transition`);
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
const t = meta.timeoutSec;
|
|
100
|
+
if (t !== undefined) {
|
|
101
|
+
if (typeof t !== "number" || !Number.isFinite(t) || t <= 0) {
|
|
102
|
+
throw new Error(`Workflow definition "${def.id}@${def.version}": ` +
|
|
103
|
+
`suspending state "${stateName}" timeoutSec must be a finite ` +
|
|
104
|
+
`number greater than 0, got ${JSON.stringify(t)}`);
|
|
105
|
+
}
|
|
106
|
+
if (!accepts(TIMEOUT_EVENT)) {
|
|
107
|
+
throw new Error(`Workflow definition "${def.id}@${def.version}": ` +
|
|
108
|
+
`suspending state "${stateName}" has a timeoutSec but no ` +
|
|
109
|
+
`"${TIMEOUT_EVENT}" (or "${WILDCARD_EVENT}") transition`);
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
else if (!accepts(SIGNAL_MATCHED_EVENT)) {
|
|
113
|
+
throw new Error(`Workflow definition "${def.id}@${def.version}": ` +
|
|
114
|
+
`suspending state "${stateName}" can never wake: ` +
|
|
115
|
+
`no timeoutSec and no "${SIGNAL_MATCHED_EVENT}" ` +
|
|
116
|
+
`(or "${WILDCARD_EVENT}") transition`);
|
|
67
117
|
}
|
|
68
118
|
break;
|
|
69
119
|
}
|
|
70
120
|
case "terminal":
|
|
121
|
+
if (events.size > 0) {
|
|
122
|
+
throw new Error(`Workflow definition "${def.id}@${def.version}": ` +
|
|
123
|
+
`terminal state "${stateName}" must have no transitions`);
|
|
124
|
+
}
|
|
71
125
|
terminalCount++;
|
|
72
126
|
break;
|
|
73
127
|
default:
|
|
@@ -75,7 +129,6 @@ export function validateDefinition(def, available) {
|
|
|
75
129
|
`state "${stateName}" has unknown meta.kind "${String(kind)}"`);
|
|
76
130
|
}
|
|
77
131
|
// transition target validation
|
|
78
|
-
const on = stateCfg.on;
|
|
79
132
|
for (const [eventName, transition] of Object.entries(on ?? {})) {
|
|
80
133
|
const targets = [];
|
|
81
134
|
if (typeof transition === "string") {
|
package/dist/driver.d.ts
CHANGED
|
@@ -1,23 +1,6 @@
|
|
|
1
1
|
import type pg from "pg";
|
|
2
2
|
import type { WorkflowRegistry } from "./registry.js";
|
|
3
|
-
import { type AdvanceJobPayload, type EffectJobPayload, JOB_TYPE_ADVANCE } from "./types.js";
|
|
4
|
-
/**
|
|
5
|
-
* Synthetic event fired by the driver when entering a pure (decision) state,
|
|
6
|
-
* so the user's guarded transitions can route by inspecting context.
|
|
7
|
-
*
|
|
8
|
-
* Pure nodes typically look like:
|
|
9
|
-
*
|
|
10
|
-
* foo: {
|
|
11
|
-
* meta: { kind: "pure" },
|
|
12
|
-
* on: {
|
|
13
|
-
* ENTER: [
|
|
14
|
-
* { target: "go_left", guard: (ctx) => ctx.x > 5 },
|
|
15
|
-
* { target: "go_right" },
|
|
16
|
-
* ],
|
|
17
|
-
* },
|
|
18
|
-
* }
|
|
19
|
-
*/
|
|
20
|
-
export declare const PURE_ENTER_EVENT = "ENTER";
|
|
3
|
+
import { type AdvanceJobPayload, type EffectJobPayload, JOB_TYPE_ADVANCE, PURE_ENTER_EVENT, SIGNAL_MATCHED_EVENT } from "./types.js";
|
|
21
4
|
/**
|
|
22
5
|
* Function the driver uses to enqueue follow-up steve jobs. Supplied by the
|
|
23
6
|
* `Workflow` class — the driver itself doesn't reach back into steve.Jobs.
|
|
@@ -32,6 +15,11 @@ export interface JobEnqueuer {
|
|
|
32
15
|
* Wrapped in a single PG transaction:
|
|
33
16
|
* 1. Lock the instance row.
|
|
34
17
|
* 2. If in a terminal execution_state, no-op.
|
|
18
|
+
* 2b. If the payload's fence (`expected_seq`) does not match the locked row, or
|
|
19
|
+
* the row is not in the state this `kind` of advance expects, no-op — the job
|
|
20
|
+
* is a duplicate, or a zombie from a step the instance already left.
|
|
21
|
+
* 2c. `kind: "signal"` → lock the inbox row; it supplies the outcome data and is
|
|
22
|
+
* marked processed in this same transaction.
|
|
35
23
|
* 3. If `outcome` was supplied, apply it via fsm.transition(outcome, data).
|
|
36
24
|
* - Reject → mark failed, append history.
|
|
37
25
|
* 4. Loop on the current state's meta.kind:
|
|
@@ -41,15 +29,28 @@ export interface JobEnqueuer {
|
|
|
41
29
|
* - suspending → mark waiting, set wake_at/correlation_token, return.
|
|
42
30
|
*/
|
|
43
31
|
export declare function runAdvance(pool: pg.Pool, registry: WorkflowRegistry, enqueuer: JobEnqueuer, payload: AdvanceJobPayload): Promise<void>;
|
|
32
|
+
/**
|
|
33
|
+
* Called by the Workflow layer when steve gives up on an advance job — every
|
|
34
|
+
* attempt threw, or the job expired once too often to keep re-dispatching it.
|
|
35
|
+
* Without this the instance would sit in `pending`/`running` with nothing left
|
|
36
|
+
* that could ever move it.
|
|
37
|
+
*
|
|
38
|
+
* Fenced like every other write: an advance that lost the race to a later one
|
|
39
|
+
* must not fail the instance that later one moved on.
|
|
40
|
+
*/
|
|
41
|
+
export declare function failAdvanceJob(pool: pg.Pool, payload: AdvanceJobPayload, reason: string, jobUid?: string): Promise<void>;
|
|
44
42
|
/**
|
|
45
43
|
* The `workflow.effect.<handlerName>` job body.
|
|
46
44
|
*
|
|
47
45
|
* 1. Looks up the user handler in the registry by `payload.handler`.
|
|
48
46
|
* 2. Loads the instance to grab the current context (no lock — handlers run
|
|
49
47
|
* outside the advance tx).
|
|
50
|
-
* 3.
|
|
51
|
-
*
|
|
52
|
-
*
|
|
48
|
+
* 3. Checks the fence: the handler runs only if the row is still at the `seq`
|
|
49
|
+
* that dispatched it. A row that moved on means this job is a duplicate or a
|
|
50
|
+
* zombie — skip, so the side effect does not fire twice.
|
|
51
|
+
* 4. Runs the handler.
|
|
52
|
+
* 5. On success: enqueues a `workflow.advance` job with the outcome + data.
|
|
53
|
+
* 6. On throw: re-throws so steve records the attempt as failed (steve retries
|
|
53
54
|
* per the job's `max_attempts`). When steve gives up, the on-failed hook in
|
|
54
55
|
* Workflow marks the instance failed.
|
|
55
56
|
*
|
|
@@ -60,12 +61,16 @@ export declare function runAdvance(pool: pg.Pool, registry: WorkflowRegistry, en
|
|
|
60
61
|
export declare function runEffect(pool: pg.Pool, registry: WorkflowRegistry, enqueuer: JobEnqueuer, payload: EffectJobPayload, signal?: AbortSignal): Promise<{
|
|
61
62
|
outcome: string;
|
|
62
63
|
data?: Record<string, unknown>;
|
|
64
|
+
} | {
|
|
65
|
+
skipped: "stale";
|
|
63
66
|
}>;
|
|
64
67
|
/**
|
|
65
68
|
* Called by the Workflow layer when steve gives up on an effect job (all
|
|
66
|
-
* attempts exhausted or expired). Marks the workflow instance as failed
|
|
69
|
+
* attempts exhausted or expired). Marks the workflow instance as failed —
|
|
70
|
+
* unless the job is fenced out, i.e. it belongs to a step the instance has
|
|
71
|
+
* already left, in which case a dead job must not kill a healthy instance.
|
|
67
72
|
*/
|
|
68
73
|
export declare function failEffectJob(pool: pg.Pool, payload: EffectJobPayload, reason: string): Promise<void>;
|
|
69
74
|
/** Composite steve job-type string for an effect handler. */
|
|
70
75
|
export declare function effectJobType(handlerName: string): string;
|
|
71
|
-
export { JOB_TYPE_ADVANCE };
|
|
76
|
+
export { JOB_TYPE_ADVANCE, PURE_ENTER_EVENT, SIGNAL_MATCHED_EVENT };
|