@marianmeres/workflow 1.0.0 → 2.1.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 +8 -7
package/README.md
CHANGED
|
@@ -27,19 +27,19 @@ Required peer: a PostgreSQL connection (`pg.Pool`).
|
|
|
27
27
|
A workflow is a **finite state machine with durable, long-lived instances**. Three concepts kept rigorously separate:
|
|
28
28
|
|
|
29
29
|
- **Definition** — Static, versioned, JSON-serializable graph of states. Pure data; handler/matcher ids are strings.
|
|
30
|
-
- **Instance** — One running occurrence of a definition. Lives as a row in `__workflow_instances`. Carries a
|
|
30
|
+
- **Instance** — One running occurrence of a definition. Lives as a row in `__workflow_instances`. Carries a _cursor_ (current node) and a separate _execution_state_ (lifecycle status).
|
|
31
31
|
- **Driver** — The advance engine. Stateless. Loads an instance, applies an outcome, dispatches the next step. Implemented as a steve job handler.
|
|
32
32
|
|
|
33
33
|
Each FSM state declares its **node kind** via `meta`:
|
|
34
34
|
|
|
35
|
-
| Kind
|
|
36
|
-
|
|
37
|
-
| `pure`
|
|
38
|
-
| `effectful`
|
|
35
|
+
| Kind | When the driver sees this state |
|
|
36
|
+
| ------------ | ------------------------------------------------------------------------------------------------- |
|
|
37
|
+
| `pure` | Fire `ENTER` to route via guards. Inline-expand. |
|
|
38
|
+
| `effectful` | Enqueue an effect handler job. Wait for completion. |
|
|
39
39
|
| `suspending` | Park the instance (`waiting`). Wake on `wake_at` (`TIMEOUT`) or matched inbox signal (`MATCHED`). |
|
|
40
|
-
| `terminal`
|
|
40
|
+
| `terminal` | Mark instance `completed`. |
|
|
41
41
|
|
|
42
|
-
The user's handler returns `{ outcome, data }`. The driver calls `fsm.transition(outcome, data)`. The transition table picks the next state. There is no AI nondeterminism inside the FSM logic — return a label, look up the next node.
|
|
42
|
+
The user's handler returns `{ outcome, data }`. The driver calls `fsm.transition(outcome, data)`. The transition table picks the next state. `data` is the transition payload only; a handler that wants a value kept for later nodes returns it in `context` — a shallow patch merged before the transition. There is no AI nondeterminism inside the FSM logic — return a label, look up the next node.
|
|
43
43
|
|
|
44
44
|
## Example
|
|
45
45
|
|
|
@@ -50,81 +50,90 @@ import pg from "pg";
|
|
|
50
50
|
import { Jobs } from "@marianmeres/steve";
|
|
51
51
|
import { Cron } from "@marianmeres/cron";
|
|
52
52
|
import {
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
53
|
+
createMigrate,
|
|
54
|
+
Workflow,
|
|
55
|
+
type WorkflowDefinition,
|
|
56
|
+
WorkflowInboxCorrelator,
|
|
57
|
+
WorkflowScheduler,
|
|
58
58
|
} from "@marianmeres/workflow";
|
|
59
59
|
|
|
60
60
|
// 1. Define the workflow (pure data — handler/matcher names are strings)
|
|
61
61
|
const stockReplenishment: WorkflowDefinition = {
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
62
|
+
id: "stock_replenishment",
|
|
63
|
+
version: "1.0.0",
|
|
64
|
+
fsm: {
|
|
65
|
+
initial: "detect_low_stock",
|
|
66
|
+
states: {
|
|
67
|
+
detect_low_stock: {
|
|
68
|
+
meta: { kind: "effectful", handler: "checkInventory" },
|
|
69
|
+
on: { LOW: "send_order", OK: "_end_ok" },
|
|
70
|
+
},
|
|
71
|
+
send_order: {
|
|
72
|
+
meta: { kind: "effectful", handler: "sendOrderEmail" },
|
|
73
|
+
on: { SENT: "await_reply", FAILED: "_end_failed" },
|
|
74
|
+
},
|
|
75
|
+
await_reply: {
|
|
76
|
+
meta: { kind: "suspending", matcher: "matchEmailReply", timeoutSec: 60 },
|
|
77
|
+
on: { MATCHED: "classify_reply", TIMEOUT: "_end_timeout" },
|
|
78
|
+
},
|
|
79
|
+
classify_reply: {
|
|
80
|
+
meta: { kind: "effectful", handler: "aiClassifyReply" },
|
|
81
|
+
on: {
|
|
82
|
+
CONFIRMED: "write_order",
|
|
83
|
+
DENIED: "_end_denied",
|
|
84
|
+
UNKNOWN: "_end_unknown",
|
|
85
|
+
},
|
|
86
|
+
},
|
|
87
|
+
write_order: {
|
|
88
|
+
meta: { kind: "effectful", handler: "persistOrder" },
|
|
89
|
+
on: { OK: "_end_ok" },
|
|
90
|
+
},
|
|
91
|
+
_end_ok: { meta: { kind: "terminal" }, on: {} },
|
|
92
|
+
_end_failed: { meta: { kind: "terminal" }, on: {} },
|
|
93
|
+
_end_timeout: { meta: { kind: "terminal" }, on: {} },
|
|
94
|
+
_end_denied: { meta: { kind: "terminal" }, on: {} },
|
|
95
|
+
_end_unknown: { meta: { kind: "terminal" }, on: {} },
|
|
96
|
+
},
|
|
97
|
+
},
|
|
94
98
|
};
|
|
95
99
|
|
|
96
100
|
// 2. Connect + migrate
|
|
97
|
-
const pool = new pg.Pool({
|
|
101
|
+
const pool = new pg.Pool({/* ... */});
|
|
98
102
|
await createMigrate(pool).up("latest");
|
|
99
103
|
|
|
100
104
|
// 3. Construct the runtime: steve.Jobs + cron.Cron are owned by *you*. The
|
|
101
105
|
// workflow framework attaches its handlers to them and the consumer owns
|
|
102
106
|
// the start/stop lifecycle. Share them with your app's other job/cron work
|
|
103
107
|
// if you want — they coexist by type/name on the same underlying tables.
|
|
104
|
-
|
|
108
|
+
//
|
|
109
|
+
// `autoCleanup` is not optional in practice: it runs steve's reaper, which
|
|
110
|
+
// is the only thing that notices a job whose worker died mid-run. Without
|
|
111
|
+
// it such a job sits in `running` forever and its instance never moves
|
|
112
|
+
// again. See "Persistence Guarantees" below.
|
|
113
|
+
const jobs = new Jobs({ db: pool, autoCleanup: true });
|
|
105
114
|
const cron = new Cron({ db: pool });
|
|
106
115
|
|
|
107
116
|
// 4. Construct the Workflow. It registers `workflow.advance` + one
|
|
108
117
|
// `workflow.effect.<name>` handler per registered handler on the injected
|
|
109
118
|
// Jobs (via `jobs.setHandler`).
|
|
110
119
|
const wf = new Workflow({
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
120
|
+
db: pool,
|
|
121
|
+
jobs,
|
|
122
|
+
tenantId: "default",
|
|
123
|
+
definitions: [stockReplenishment],
|
|
124
|
+
handlers: {
|
|
125
|
+
checkInventory: async (args) => ({ outcome: "LOW", data: { stock: 3 } }),
|
|
126
|
+
sendOrderEmail: async (args) => ({ outcome: "SENT", data: { messageId: "..." } }),
|
|
127
|
+
aiClassifyReply: async (args) => ({ outcome: "CONFIRMED", data: {} }),
|
|
128
|
+
persistOrder: async (args) => ({ outcome: "OK", data: { orderId: "..." } }),
|
|
129
|
+
},
|
|
130
|
+
matchers: {
|
|
131
|
+
matchEmailReply: ({ signal }) => signal.source === "email",
|
|
132
|
+
},
|
|
124
133
|
});
|
|
125
134
|
|
|
126
135
|
// 5. Attach the scheduler + correlator ticks to the injected Cron.
|
|
127
|
-
const scheduler
|
|
136
|
+
const scheduler = new WorkflowScheduler({ cron, workflow: wf });
|
|
128
137
|
const correlator = new WorkflowInboxCorrelator({ cron, workflow: wf });
|
|
129
138
|
await scheduler.register();
|
|
130
139
|
await correlator.register();
|
|
@@ -135,18 +144,18 @@ await cron.start(2);
|
|
|
135
144
|
|
|
136
145
|
// 7. Create an instance
|
|
137
146
|
const instance = await wf.create({
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
147
|
+
definitionId: "stock_replenishment",
|
|
148
|
+
definitionVersion: "1.0.0",
|
|
149
|
+
correlationToken: crypto.randomUUID(),
|
|
141
150
|
});
|
|
142
151
|
|
|
143
152
|
// 8. When an external signal arrives, append it to the inbox. The
|
|
144
153
|
// correlator's next tick matches it to the waiting instance and fires
|
|
145
154
|
// `MATCHED` on the FSM.
|
|
146
155
|
await wf.appendInbox({
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
156
|
+
source: "email",
|
|
157
|
+
correlationToken: instance.correlation_token!,
|
|
158
|
+
payload: { subject: "Re: order", body: "yes please" },
|
|
150
159
|
});
|
|
151
160
|
|
|
152
161
|
// 9. Graceful shutdown — stop what you started.
|
|
@@ -154,6 +163,10 @@ await cron.stop();
|
|
|
154
163
|
await jobs.stop();
|
|
155
164
|
```
|
|
156
165
|
|
|
166
|
+
There is a clickable version of all of this in [`example/`](./example): the same wiring,
|
|
167
|
+
a graph you can watch an instance walk, and a button for each way it can go wrong. See
|
|
168
|
+
[The interactive example](#the-interactive-example).
|
|
169
|
+
|
|
157
170
|
## How It Works
|
|
158
171
|
|
|
159
172
|
```
|
|
@@ -173,18 +186,23 @@ await jobs.stop();
|
|
|
173
186
|
PostgreSQL
|
|
174
187
|
```
|
|
175
188
|
|
|
176
|
-
The framework owns no runtime processes. It registers job and cron handlers on the `Jobs` and `Cron` instances you pass in; you call `start()` / `stop()` on them. This lets the workflow's jobs/crons coexist with your application's own — they share `__job` / `__cron` tables and coexist by `type` / `name`. Sharing one runtime per process is cheaper than running parallel pollers.
|
|
189
|
+
The framework owns no runtime processes. It registers job and cron handlers on the `Jobs` and `Cron` instances you pass in; you call `start()` / `stop()` on them. This lets the workflow's jobs/crons coexist with your application's own — they share `__job` / `__cron` tables and coexist by `type` / `name`. Sharing one runtime per process is cheaper than running parallel pollers — and safer: a `Jobs` or `Cron` that polls these tables without the workflow handlers attached silently noops the work it claims (see [Failure Modes](#failure-modes)).
|
|
177
190
|
|
|
178
|
-
A single steve job type — **`workflow.advance`** — encapsulates one step of the driver. Its payload is `{
|
|
191
|
+
A single steve job type — **`workflow.advance`** — encapsulates one step of the driver. Its payload is `{ tenant_id, instance_id, kind, expected_seq, outcome?, outcome_data?, inbox_id? }`. The handler:
|
|
179
192
|
|
|
180
193
|
1. Locks the instance row inside a transaction.
|
|
181
|
-
2.
|
|
182
|
-
3.
|
|
183
|
-
4.
|
|
194
|
+
2. Drops the job if the instance is already terminal, if `expected_seq` no longer matches the row's `seq` (the fence — see below), or if the row is not in the state this `kind` of advance expects.
|
|
195
|
+
3. If an `outcome` was supplied (wake from effect / signal / timer), applies it via `fsm.transition(outcome, data)`. If the FSM rejects, the instance is marked `failed`.
|
|
196
|
+
4. Loops on the current state's `meta.kind`, settling at the first terminal / effectful / suspending state and persisting the new cursor + execution_state — and bumping `seq` — in the same transaction.
|
|
197
|
+
5. For effectful nodes, enqueues a **`workflow.effect.<handlerName>`** steve job carrying that new `seq`. On its success, the effect handler enqueues a fresh advance carrying the outcome. On terminal failure, the instance is marked `failed`.
|
|
198
|
+
|
|
199
|
+
**The advance is the only writer of instance rows** (bar the job-failure hooks and the `cancel` / `retry` admin calls, which settle a row directly and bump `seq` with it). Everything else — the scheduler, the correlator — only _pokes_: it reads what looks due and enqueues an advance for it. A poke that is lost to a crash costs nothing, because whatever made the row look due is still true next tick; a poke that arrives twice costs nothing, because the second one is fenced out.
|
|
200
|
+
|
|
201
|
+
The **fence** is the `seq` column. Every settle-point write bumps it, and every advance/effect job carries the value it was issued against. A job whose value no longer matches belongs to a step the instance has already left — a duplicate, or a zombie from a worker that hung — and is dropped with a debug log rather than applied to a row that moved on.
|
|
184
202
|
|
|
185
|
-
The **scheduler** runs as a registered cron job (default `* * * * *`). Each tick
|
|
203
|
+
The **scheduler** runs as a registered cron job (default `* * * * *`). Each tick is read-only: it selects `waiting` rows whose `wake_at` has passed and pokes one `TIMEOUT` advance per row (the advance re-checks due-ness under the lock and clears `wake_at`). A second scan pokes instances stuck in `pending` for longer than `stalePendingSec` — the residue of a crash between `create()`'s commit and steve's job insert, which happens on its own connection.
|
|
186
204
|
|
|
187
|
-
The **correlator** runs as a registered cron job (default `* * * * *`). Each tick claims a batch of unprocessed `__workflow_inbox` rows, finds the
|
|
205
|
+
The **correlator** runs as a registered cron job (default `* * * * *`). Each tick claims a batch of unprocessed `__workflow_inbox` rows, finds the live instance owning the `correlation_token`, runs the user's `matcher` for the current state, and pokes a `MATCHED` advance carrying the _inbox row id_. The advance re-reads that row under a lock and marks it processed in the same transaction as the transition, so a signal is never consumed without being delivered.
|
|
188
206
|
|
|
189
207
|
## Versioning Definitions
|
|
190
208
|
|
|
@@ -192,18 +210,43 @@ Each instance row stores `definition_version`. The framework looks up the defini
|
|
|
192
210
|
|
|
193
211
|
## Persistence Guarantees & Idempotency
|
|
194
212
|
|
|
195
|
-
- The
|
|
196
|
-
-
|
|
197
|
-
- **Handlers must be idempotent.**
|
|
213
|
+
- **The instance write is one PG transaction.** Cursor, execution_state, wake_at, `seq` and history are written together, and a signal delivery marks its inbox row processed in that same transaction. The follow-up _job_ insert is not part of it: steve creates jobs on its own connection, so a job can exist for a transaction that ended up rolling back.
|
|
214
|
+
- **Job delivery is therefore at-least-once, and fenced.** A duplicate advance or effect job is recognized by `seq` and dropped. The fence is what makes the extra deliveries harmless, not their absence. `seq` arrives with schema 1.2.0 — run `createMigrate(pool).up("latest")` when upgrading.
|
|
215
|
+
- **Handlers must be idempotent.** The fence protects the _instance row_, not the outside world. A handler can still run twice — a worker that completed the side effect and then died before steve recorded the attempt gets retried. Use upserts, idempotency keys, or check the existing state.
|
|
216
|
+
- **Run `Jobs` with `autoCleanup: true`** (or call `jobs.cleanup()` periodically). Steve's reaper is the only thing that marks a job whose worker died as `expired`; without it that job stays `running` forever and its instance never moves again. With it, the framework re-queues the identical payload up to `redispatchLimit` times before giving up and failing the instance — the fence makes the re-queue a no-op if the dead worker's transaction did commit.
|
|
217
|
+
- **A `pending` instance is re-poked** after `stalePendingSec` (default 300s), which covers the crash window between `create()`'s commit and steve's job insert.
|
|
218
|
+
|
|
219
|
+
## Signals: early, late, deferred
|
|
220
|
+
|
|
221
|
+
`appendInbox` never blocks on the instance being ready for the signal. What the correlator does with a row depends on what it finds behind the token:
|
|
222
|
+
|
|
223
|
+
| Situation | What happens |
|
|
224
|
+
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
|
|
225
|
+
| Instance is `waiting` at a node that accepts `MATCHED`, matcher says yes | Advance poked; `signal_received` + the transition commit with the row's `processed_at` |
|
|
226
|
+
| Matcher says no | `signal_rejected` history; row marked processed |
|
|
227
|
+
| Matcher throws | Row deferred — re-examined next tick, with an error log |
|
|
228
|
+
| Instance is live but not `waiting` yet (still running the step that emits the token) | Row deferred |
|
|
229
|
+
| Instance is `waiting` at a node with no `MATCHED` edge (e.g. a timer-only delay) | Row deferred |
|
|
230
|
+
| No live instance owns the token, or the one that did has failed | Row marked processed with a warn log (plus `signal_rejected` history if a terminal instance exists) |
|
|
231
|
+
|
|
232
|
+
"Deferred" means the row stays unprocessed and is looked at again on the next tick — an early signal is early, not wrong. Only one signal per instance is poked per tick; the rest defer, because a second one would be fenced out anyway.
|
|
233
|
+
|
|
234
|
+
Two consequences worth knowing: a deferred row is retried indefinitely (a permanently-throwing matcher logs on every tick), and rows are claimed `ORDER BY received_at LIMIT tickBatchSize`, so a deferred backlog larger than the batch would shadow newer rows.
|
|
198
235
|
|
|
199
236
|
## Failure Modes
|
|
200
237
|
|
|
201
|
-
| Failure
|
|
202
|
-
|
|
203
|
-
| Effect handler throws repeatedly
|
|
204
|
-
|
|
|
205
|
-
|
|
|
206
|
-
|
|
|
238
|
+
| Failure | Behavior |
|
|
239
|
+
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
240
|
+
| Effect handler throws repeatedly | Steve retries the job `effectMaxAttempts` times, then the instance is marked `failed`; `effect_failed` history entry. |
|
|
241
|
+
| Advance job throws repeatedly | Steve retries the job `advanceMaxAttempts` times (default 10, ~17min of backoff), then the instance is marked `failed` with the last attempt's error message. |
|
|
242
|
+
| Worker dies mid-job | Steve's reaper (needs `autoCleanup`) marks the job `expired` — steve never retries those. The framework re-queues the identical payload, up to `redispatchLimit` dispatches in total, then fails the instance. |
|
|
243
|
+
| Lost advance: the side effect happened but the follow-up advance was never enqueued | The effect job is retried (if the enqueue threw) or re-dispatched after expiry (if the process died). Either way the handler runs again — the instance never left that `seq`, so the fence lets it through — and the advance is enqueued. **This is why handlers must be idempotent.** |
|
|
244
|
+
| FSM rejects the outcome label | Instance marked `failed`; `transition_rejected` history entry. |
|
|
245
|
+
| Pure node with no guard matching | Instance marked `failed`; `transition_rejected` history entry. |
|
|
246
|
+
| Definition missing on advance | Instance marked `failed`. Keep old versions registered until drained. |
|
|
247
|
+
| A `failed` instance you want back | `wf.retry(id)` puts it back to `pending` at its current cursor and re-runs that node — no new instance, no replay of the effects it already did. `wf.retry(id, { force: true })` covers a `running` one whose worker died. Nothing is fixed by retrying alone: fix the cause first. |
|
|
248
|
+
| An instance that should not finish at all | `wf.cancel(id, reason?)` marks it `cancelled` (terminal) and drops its timer and its correlation token. Jobs already in flight for it are fenced out — a queued effect job skips its handler rather than firing the side effect. |
|
|
249
|
+
| A second `Jobs` or `Cron` in a process that never registered the workflow handlers | **Silent data loss.** Both libraries fall back to a noop for an unknown `type` / `name`: steve marks the job completed, cron marks the tick run and advances `next_run_at`. Share one runtime per process, or make sure every process that starts a `Jobs`/`Cron` on these tables also constructs the `Workflow` and calls `register()`. |
|
|
207
250
|
|
|
208
251
|
## Observability
|
|
209
252
|
|
|
@@ -216,7 +259,63 @@ const events = await getHistory(pool, instanceId);
|
|
|
216
259
|
|
|
217
260
|
## Multi-tenancy
|
|
218
261
|
|
|
219
|
-
Pass `
|
|
262
|
+
Pass `tenantId` to `Workflow`, `WorkflowScheduler`, and `WorkflowInboxCorrelator`. All three tables (and Cron's internal tables) carry `tenant_id`, so instances, inbox rows, history, and the tick registrations are scoped: a `Workflow` only ever sees its own tenant's rows.
|
|
263
|
+
|
|
264
|
+
**The queues are not scoped, though.** Both steve and cron claim the next due row globally — no tenant filter, no type filter — and both fall back to a noop for work they have no handler for. So running one process per tenant against a shared database does _not_ isolate them: process A will claim process B's jobs and cron ticks, and silently noop the ones whose handler it does not have. That is safe only when every such process registers the _same_ definitions, handlers, and ticks (which makes the per-process scoping pointless anyway).
|
|
265
|
+
|
|
266
|
+
The supported shape today is one runtime per database, serving whichever tenants it has definitions for. Tenant scoping is for keeping data apart, not for partitioning workers.
|
|
267
|
+
|
|
268
|
+
## Breaking changes in 2.0
|
|
269
|
+
|
|
270
|
+
- **`project_id` renamed to `tenant_id` throughout**, aligning with the
|
|
271
|
+
ecosystem's tenant-scoping convention (`@marianmeres/cron`,
|
|
272
|
+
`@marianmeres/steve`). This covers the DB column on all three tables, the
|
|
273
|
+
`tenant_id` field on `WorkflowInstanceRow` / `InboxRow` / `HistoryRow`, the
|
|
274
|
+
`tenantId` option on `Workflow` / `WorkflowScheduler` /
|
|
275
|
+
`WorkflowInboxCorrelator`, the `tenantId` key in `HandlerArgs` / `MatcherArgs`,
|
|
276
|
+
the `tenant_id` key in `AdvanceJobPayload` / `EffectJobPayload`, and the
|
|
277
|
+
`DEFAULT_TENANT_ID` export (was `DEFAULT_PROJECT_ID`).
|
|
278
|
+
|
|
279
|
+
Run `createMigrate(pool).up("latest")` once on upgrade. Schema version 1.1.0
|
|
280
|
+
renames the column in place on all three tables, preserving existing data. It
|
|
281
|
+
is idempotent, and `down("1.0.0")` reverses it.
|
|
282
|
+
|
|
283
|
+
Jobs enqueued by 1.0.x carry the old `project_id` key in their steve payload.
|
|
284
|
+
The driver reads either key, so anything already queued at upgrade time drains
|
|
285
|
+
normally. That fallback is a transitional shim and will be removed in a later
|
|
286
|
+
major.
|
|
287
|
+
|
|
288
|
+
- **Requires `@marianmeres/cron` 3.x**, which performed the same rename on its
|
|
289
|
+
own tables. If you are upgrading an existing database, run its migration once
|
|
290
|
+
too — the cron tick registrations otherwise fail against the legacy column:
|
|
291
|
+
|
|
292
|
+
```typescript
|
|
293
|
+
import { Cron } from "@marianmeres/cron";
|
|
294
|
+
await Cron.migrate(pool);
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
Fresh installs need no action. `@marianmeres/steve` 3.x self-heals its own
|
|
298
|
+
schema on init, so it needs nothing either.
|
|
299
|
+
|
|
300
|
+
## The interactive example
|
|
301
|
+
|
|
302
|
+
A control panel for one workflow instance: create it, approve it, reject it, let its timer
|
|
303
|
+
run out, hand it a signal its matcher declines, break the effect that books it, cancel it,
|
|
304
|
+
retry it — and watch the graph, the history and the inbox as each of those lands.
|
|
305
|
+
|
|
306
|
+
```sh
|
|
307
|
+
createdb example_workflow # or point EXAMPLE_PG_* at a database you already have
|
|
308
|
+
deno task example # → http://127.0.0.1:8000
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
The highlighted node is the cursor; the badge on it is the execution state. The countdown
|
|
312
|
+
is `wake_at`. The tick panel switches the scheduler and correlator to manual, so you can
|
|
313
|
+
watch the poke model one press at a time — and since every field on the page was read back
|
|
314
|
+
out of PostgreSQL, stopping the server mid-wait and starting it again changes nothing.
|
|
315
|
+
|
|
316
|
+
See [`example/`](./example) — the workflow itself (definition, handlers, matcher) is
|
|
317
|
+
[`example/workflow.ts`](./example/workflow.ts), which is the shortest complete answer to
|
|
318
|
+
"what does userland actually write?".
|
|
220
319
|
|
|
221
320
|
## API
|
|
222
321
|
|
package/dist/correlator.d.ts
CHANGED
|
@@ -16,22 +16,35 @@ export interface WorkflowInboxCorrelatorOptions {
|
|
|
16
16
|
timezone?: string | null;
|
|
17
17
|
/** Maximum number of inbox rows claimed per tick. Default: 100. */
|
|
18
18
|
tickBatchSize?: number;
|
|
19
|
-
/** Custom name for the registered cron job. Default: `workflow.correlator.<
|
|
19
|
+
/** Custom name for the registered cron job. Default: `workflow.correlator.<tenantId>`. */
|
|
20
20
|
tickName?: string;
|
|
21
21
|
}
|
|
22
22
|
/**
|
|
23
|
-
* Cron-driven correlator that matches `__workflow_inbox` rows to
|
|
24
|
-
*
|
|
23
|
+
* Cron-driven correlator that matches `__workflow_inbox` rows to workflow
|
|
24
|
+
* instances. On each tick it claims a batch of unprocessed rows
|
|
25
|
+
* (`FOR UPDATE SKIP LOCKED`) and, per row, finds the live instance owning the
|
|
26
|
+
* correlation token:
|
|
25
27
|
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
28
|
+
* | Instance | Action |
|
|
29
|
+
* | ----------------------------------------------- | --------------------------------------------------- |
|
|
30
|
+
* | none / terminal | mark processed (+ `signal_rejected` if terminal) |
|
|
31
|
+
* | live but not `waiting` | defer |
|
|
32
|
+
* | `waiting` at a node that has no `MATCHED` edge | defer |
|
|
33
|
+
* | `waiting`, matcher says no | `signal_rejected`, mark processed |
|
|
34
|
+
* | `waiting`, matcher says yes | poke an advance; the advance does the rest |
|
|
35
|
+
*
|
|
36
|
+
* "Defer" means: leave the row unprocessed and look at it again next tick. A
|
|
37
|
+
* signal that arrives before its wait point — the instance is still running the
|
|
38
|
+
* step that emits the token, or sits at a timer-only node — is early, not
|
|
39
|
+
* wrong; consuming it would lose it, and delivering it to a node with no
|
|
40
|
+
* `MATCHED` edge would fail the instance.
|
|
41
|
+
*
|
|
42
|
+
* The correlator only pokes: it never writes the instance row. The advance
|
|
43
|
+
* transitions the instance, records `signal_received` and marks the inbox row
|
|
44
|
+
* processed in one transaction, so a crashed poke is simply re-poked next tick.
|
|
45
|
+
*
|
|
46
|
+
* Starvation note: rows are claimed `ORDER BY received_at LIMIT tickBatchSize`,
|
|
47
|
+
* so a backlog of deferred rows larger than the batch would shadow newer ones.
|
|
35
48
|
*
|
|
36
49
|
* Like {@link WorkflowScheduler}, the correlator does not own its `Cron`. The
|
|
37
50
|
* caller constructs a `Cron`, passes it in, runs its lifecycle. Call
|
|
@@ -40,7 +53,7 @@ export interface WorkflowInboxCorrelatorOptions {
|
|
|
40
53
|
export declare class WorkflowInboxCorrelator {
|
|
41
54
|
#private;
|
|
42
55
|
readonly cron: Cron;
|
|
43
|
-
readonly
|
|
56
|
+
readonly tenantId: string;
|
|
44
57
|
readonly tickExpression: string;
|
|
45
58
|
readonly tickName: string;
|
|
46
59
|
constructor(options: WorkflowInboxCorrelatorOptions);
|
|
@@ -51,6 +64,10 @@ export declare class WorkflowInboxCorrelator {
|
|
|
51
64
|
register(): Promise<void>;
|
|
52
65
|
/** Removes the tick from the injected `Cron`. */
|
|
53
66
|
unregister(): Promise<void>;
|
|
54
|
-
/**
|
|
67
|
+
/**
|
|
68
|
+
* Runs one tick immediately. Exposed for testing and on-demand matches.
|
|
69
|
+
* Returns the number of rows resolved — poked, rejected or marked processed.
|
|
70
|
+
* Deferred rows are not counted; they are still there next tick.
|
|
71
|
+
*/
|
|
55
72
|
tickOnce(): Promise<number>;
|
|
56
73
|
}
|