@hogsend/engine 0.40.0 → 0.42.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/package.json +11 -8
- package/src/buckets/check-membership.ts +6 -1
- package/src/campaigns/cohort-sql.ts +198 -0
- package/src/campaigns/define-campaign.ts +207 -28
- package/src/campaigns/reconcile.ts +105 -11
- package/src/campaigns/steps.ts +48 -0
- package/src/connectors/define-action.ts +70 -0
- package/src/container.ts +124 -42
- package/src/destinations/presets/posthog.ts +7 -1
- package/src/index.ts +96 -2
- package/src/journeys/constants.ts +10 -0
- package/src/journeys/define-journey.ts +14 -405
- package/src/journeys/execute-journey-run.ts +641 -0
- package/src/journeys/graph/build-graph.ts +212 -56
- package/src/journeys/journey-boundary.ts +54 -0
- package/src/journeys/journey-context.ts +406 -59
- package/src/journeys/record-once.ts +110 -0
- package/src/lib/blueprint-lock.ts +21 -0
- package/src/lib/blueprints.ts +803 -0
- package/src/lib/campaign-send-key.ts +58 -0
- package/src/lib/connector-actions.ts +203 -19
- package/src/lib/contacts.ts +54 -0
- package/src/lib/email-service-types.ts +4 -1
- package/src/lib/email.ts +13 -2
- package/src/lib/event-names.ts +143 -0
- package/src/lib/feed.ts +77 -57
- package/src/lib/frequency-cap.ts +45 -15
- package/src/lib/hatchet-duration.ts +22 -0
- package/src/lib/html.ts +1 -0
- package/src/lib/ingestion.ts +145 -4
- package/src/lib/journey-suppress.ts +87 -0
- package/src/lib/links.ts +204 -18
- package/src/lib/outbound.ts +20 -0
- package/src/lib/preferences.ts +80 -1
- package/src/lib/tracked.ts +44 -29
- package/src/lib/tracking-event-names.ts +8 -0
- package/src/lib/tracking.ts +1 -5
- package/src/lib/webhook-signing.ts +6 -1
- package/src/lists/channels.ts +75 -0
- package/src/lists/define-list.ts +34 -0
- package/src/lists/registry.ts +29 -2
- package/src/mcp/authoring-guide.ts +160 -0
- package/src/mcp/blueprint-tools.ts +390 -0
- package/src/middleware/require-admin.ts +13 -0
- package/src/routes/admin/api-keys.ts +72 -0
- package/src/routes/admin/blueprints.ts +795 -0
- package/src/routes/admin/campaigns.ts +179 -3
- package/src/routes/admin/emails.ts +13 -0
- package/src/routes/admin/events.ts +55 -0
- package/src/routes/admin/index.ts +4 -0
- package/src/routes/admin/journeys.ts +4 -2
- package/src/routes/admin/links.ts +303 -36
- package/src/routes/admin/lists.ts +51 -0
- package/src/routes/campaigns/index.ts +44 -6
- package/src/routes/email/preferences.ts +50 -13
- package/src/routes/feed/recipient.ts +2 -43
- package/src/routes/index.ts +6 -0
- package/src/routes/lists/index.ts +138 -18
- package/src/routes/tracking/arrive.ts +260 -0
- package/src/routes/tracking/click-pipeline.ts +329 -0
- package/src/routes/tracking/click.ts +5 -270
- package/src/routes/tracking/index.ts +2 -0
- package/src/routes/tracking/vanity.ts +64 -0
- package/src/worker.ts +5 -0
- package/src/workflows/bucket-backfill.ts +4 -2
- package/src/workflows/bucket-reconcile.ts +11 -4
- package/src/workflows/check-alerts.ts +130 -1
- package/src/workflows/journey-blueprint-interpreter.ts +656 -0
- package/src/workflows/send-campaign.ts +574 -180
|
@@ -0,0 +1,656 @@
|
|
|
1
|
+
import type { JsonValue } from "@hatchet-dev/typescript-sdk/v1/types.js";
|
|
2
|
+
import {
|
|
3
|
+
type BlueprintGraph,
|
|
4
|
+
BlueprintNodeExecutionError,
|
|
5
|
+
BlueprintUnreachableNodeError,
|
|
6
|
+
type DurationObject,
|
|
7
|
+
evaluateCondition,
|
|
8
|
+
isReservedEventName,
|
|
9
|
+
type JourneyEdge,
|
|
10
|
+
type JourneyNode,
|
|
11
|
+
type PropertyCondition,
|
|
12
|
+
RESERVED_EVENT_NAMESPACES,
|
|
13
|
+
serializeBlueprintError,
|
|
14
|
+
validateBlueprintGraph,
|
|
15
|
+
} from "@hogsend/core";
|
|
16
|
+
import type {
|
|
17
|
+
JourneyContext,
|
|
18
|
+
JourneyMeta,
|
|
19
|
+
JourneyUser,
|
|
20
|
+
} from "@hogsend/core/types";
|
|
21
|
+
import { type Database, journeyBlueprints, journeyStates } from "@hogsend/db";
|
|
22
|
+
import type { TemplateName } from "@hogsend/email";
|
|
23
|
+
import { and, eq, notInArray } from "drizzle-orm";
|
|
24
|
+
import {
|
|
25
|
+
BLUEPRINT_RUN_EVENT,
|
|
26
|
+
JOURNEY_EXECUTION_TIMEOUT,
|
|
27
|
+
JOURNEY_SCHEDULE_TIMEOUT,
|
|
28
|
+
} from "../journeys/constants.js";
|
|
29
|
+
import { JourneyExitedError } from "../journeys/errors.js";
|
|
30
|
+
import {
|
|
31
|
+
type EventPayloadInput,
|
|
32
|
+
executeJourneyRun,
|
|
33
|
+
} from "../journeys/execute-journey-run.js";
|
|
34
|
+
import { TERMINAL_STATUSES } from "../journeys/journey-context.js";
|
|
35
|
+
import { logTransition } from "../journeys/journey-log.js";
|
|
36
|
+
import { sendConnectorAction } from "../lib/connector-actions.js";
|
|
37
|
+
import { getDb } from "../lib/db.js";
|
|
38
|
+
import { sendEmail } from "../lib/email.js";
|
|
39
|
+
import { hatchet } from "../lib/hatchet.js";
|
|
40
|
+
import { createLogger } from "../lib/logger.js";
|
|
41
|
+
|
|
42
|
+
const logger = createLogger(process.env.LOG_LEVEL);
|
|
43
|
+
|
|
44
|
+
/** A `journey_blueprints` row as Drizzle returns it. */
|
|
45
|
+
export type JourneyBlueprintRow = typeof journeyBlueprints.$inferSelect;
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Build the `JourneyMeta` the shared run lifecycle consumes from a
|
|
49
|
+
* `journey_blueprints` row. The row's trigger/entry/exit/suppress columns
|
|
50
|
+
* mirror `JourneyMeta` 1:1 by design (spec §4) so the SAME enrollment-guard
|
|
51
|
+
* functions `defineJourney` uses receive it verbatim — `status !== "enabled"`
|
|
52
|
+
* is the blueprint's `meta.enabled === false`. The jsonb columns are opaque in
|
|
53
|
+
* `@hogsend/db` (db cannot import core), so this is the single read-site
|
|
54
|
+
* narrowing, per the `campaigns.steps` convention.
|
|
55
|
+
*/
|
|
56
|
+
export function blueprintMetaFromRow(row: JourneyBlueprintRow): JourneyMeta {
|
|
57
|
+
const triggerWhere = (row.triggerWhere ?? undefined) as
|
|
58
|
+
| PropertyCondition[]
|
|
59
|
+
| undefined;
|
|
60
|
+
return {
|
|
61
|
+
id: row.id,
|
|
62
|
+
name: row.name,
|
|
63
|
+
...(row.description ? { description: row.description } : {}),
|
|
64
|
+
enabled: row.status === "enabled",
|
|
65
|
+
trigger: {
|
|
66
|
+
event: row.triggerEvent,
|
|
67
|
+
...(triggerWhere?.length ? { where: triggerWhere } : {}),
|
|
68
|
+
},
|
|
69
|
+
entryLimit: row.entryLimit,
|
|
70
|
+
...(row.entryPeriod
|
|
71
|
+
? { entryPeriod: row.entryPeriod as DurationObject }
|
|
72
|
+
: {}),
|
|
73
|
+
...(row.exitOn?.length
|
|
74
|
+
? { exitOn: row.exitOn as NonNullable<JourneyMeta["exitOn"]> }
|
|
75
|
+
: {}),
|
|
76
|
+
// `{}` / zero duration disables the suppress guard — same contract as
|
|
77
|
+
// JourneyMeta.suppress (the boundary maps it to suppressMs: 0).
|
|
78
|
+
suppress: (row.suppress ?? {}) as DurationObject,
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Errors the per-node wrap must NOT swallow into a `BlueprintNodeExecutionError`:
|
|
84
|
+
* - `JourneyExitedError` — a control-flow signal (exitOn / cancel / the
|
|
85
|
+
* `end-exited` node); the lifecycle catch maps it to `status: "exited"`.
|
|
86
|
+
* - Hatchet's AbortError — a graceful-shutdown RELEASE; wrapping it would
|
|
87
|
+
* defeat the lifecycle's abort detection and poison the enrollment with a
|
|
88
|
+
* false "failed".
|
|
89
|
+
* - Blueprint errors already carrying their node id.
|
|
90
|
+
*/
|
|
91
|
+
function isWalkPassThroughError(err: unknown): boolean {
|
|
92
|
+
if (err instanceof JourneyExitedError) return true;
|
|
93
|
+
if (
|
|
94
|
+
err instanceof BlueprintNodeExecutionError ||
|
|
95
|
+
err instanceof BlueprintUnreachableNodeError
|
|
96
|
+
) {
|
|
97
|
+
return true;
|
|
98
|
+
}
|
|
99
|
+
return (
|
|
100
|
+
err instanceof Error &&
|
|
101
|
+
(err.name === "AbortError" ||
|
|
102
|
+
(err as { code?: string }).code === "ABORT_ERR")
|
|
103
|
+
);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** Narrow a required meta field, throwing the typed node error when absent.
|
|
107
|
+
* Unreachable for a graph that passed `validateBlueprintGraph` (the schema
|
|
108
|
+
* requires per-variant meta) — jsonb defense-in-depth plus TS narrowing. */
|
|
109
|
+
function requireNodeMeta<T>(
|
|
110
|
+
blueprintId: string,
|
|
111
|
+
node: { id: string; type: string },
|
|
112
|
+
field: string,
|
|
113
|
+
value: T | undefined | null,
|
|
114
|
+
): T {
|
|
115
|
+
if (value === undefined || value === null) {
|
|
116
|
+
throw new BlueprintNodeExecutionError(
|
|
117
|
+
blueprintId,
|
|
118
|
+
node.id,
|
|
119
|
+
`${node.type} node is missing required meta.${field}`,
|
|
120
|
+
);
|
|
121
|
+
}
|
|
122
|
+
return value;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
export interface WalkBlueprintGraphOptions {
|
|
126
|
+
blueprintId: string;
|
|
127
|
+
/** A graph that passed {@link validateBlueprintGraph}. */
|
|
128
|
+
graph: BlueprintGraph;
|
|
129
|
+
user: JourneyUser;
|
|
130
|
+
ctx: JourneyContext;
|
|
131
|
+
db: Database;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* Tree-walk a validated blueprint graph, executing each node through the
|
|
136
|
+
* EXACT same primitives a code journey calls (spec §6): `ctx.sleep`,
|
|
137
|
+
* `ctx.waitForEvent`, `ctx.checkpoint`, `ctx.trigger`, `sendEmail()`,
|
|
138
|
+
* `sendConnectorAction()`, `evaluateCondition()`. Every label/idempotencyLabel
|
|
139
|
+
* is the node id — as replay-stable as a hand-authored `ctx.sleep({ label })`
|
|
140
|
+
* — so the existing two-layer exactly-once machinery applies unchanged.
|
|
141
|
+
*
|
|
142
|
+
* The dispatch is an exhaustive `switch` over the FULL `JourneyNodeType`
|
|
143
|
+
* union with a compiler-enforced `never` default (spec §6.1): adding a node
|
|
144
|
+
* type without an interpreter case is a compile error, and the four
|
|
145
|
+
* non-executable display-tier types throw typed errors as defense-in-depth
|
|
146
|
+
* (validation already rejected them).
|
|
147
|
+
*/
|
|
148
|
+
export async function walkBlueprintGraph(
|
|
149
|
+
opts: WalkBlueprintGraphOptions,
|
|
150
|
+
): Promise<void> {
|
|
151
|
+
const { blueprintId, graph, user, ctx, db } = opts;
|
|
152
|
+
|
|
153
|
+
// The execution tier is a compile-asserted narrowing of the display tier,
|
|
154
|
+
// so widening to `JourneyNode` is free — and it is what lets the switch
|
|
155
|
+
// below cover the FULL node-type vocabulary (a `BlueprintNode`-typed switch
|
|
156
|
+
// could not even name the non-executable cases).
|
|
157
|
+
const nodes: JourneyNode[] = graph.nodes;
|
|
158
|
+
const nodesById = new Map<string, JourneyNode>(
|
|
159
|
+
nodes.map((node) => [node.id, node]),
|
|
160
|
+
);
|
|
161
|
+
const outgoing = new Map<string, JourneyEdge[]>();
|
|
162
|
+
for (const edge of graph.edges) {
|
|
163
|
+
const list = outgoing.get(edge.source) ?? [];
|
|
164
|
+
list.push(edge);
|
|
165
|
+
outgoing.set(edge.source, list);
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
const start = nodes.find((node) => node.type === "start");
|
|
169
|
+
if (!start) {
|
|
170
|
+
// Unreachable post-validation (findStartNodeIssues) — defense-in-depth.
|
|
171
|
+
throw new BlueprintNodeExecutionError(
|
|
172
|
+
blueprintId,
|
|
173
|
+
"start",
|
|
174
|
+
"graph has no start node",
|
|
175
|
+
);
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/** The single unconditional next hop. Zero outgoing edges ends the walk —
|
|
179
|
+
* the run returns and the lifecycle marks the enrollment completed, exactly
|
|
180
|
+
* like a code journey's `run()` running off the end of its body. */
|
|
181
|
+
const defaultNext = (node: JourneyNode): string | null => {
|
|
182
|
+
const edges = outgoing.get(node.id) ?? [];
|
|
183
|
+
if (edges.length === 0) return null;
|
|
184
|
+
if (edges.length === 1) {
|
|
185
|
+
// length === 1 → the single element exists; TS can't see that.
|
|
186
|
+
return edges[0]?.target ?? null;
|
|
187
|
+
}
|
|
188
|
+
throw new BlueprintNodeExecutionError(
|
|
189
|
+
blueprintId,
|
|
190
|
+
node.id,
|
|
191
|
+
`a ${node.type} node cannot fork (${edges.length} outgoing edges)`,
|
|
192
|
+
);
|
|
193
|
+
};
|
|
194
|
+
|
|
195
|
+
/** Pick the outgoing edge whose `kind` matches, throwing when absent. */
|
|
196
|
+
const nextByKind = (node: JourneyNode, kind: JourneyEdge["kind"]): string => {
|
|
197
|
+
const edge = (outgoing.get(node.id) ?? []).find((e) => e.kind === kind);
|
|
198
|
+
if (!edge) {
|
|
199
|
+
throw new BlueprintNodeExecutionError(
|
|
200
|
+
blueprintId,
|
|
201
|
+
node.id,
|
|
202
|
+
`no outgoing edge with kind "${kind}"`,
|
|
203
|
+
);
|
|
204
|
+
}
|
|
205
|
+
return edge.target;
|
|
206
|
+
};
|
|
207
|
+
|
|
208
|
+
/** Execute one node; returns the next node id, or null to end the walk. */
|
|
209
|
+
const executeNode = async (node: JourneyNode): Promise<string | null> => {
|
|
210
|
+
switch (node.type) {
|
|
211
|
+
case "start":
|
|
212
|
+
return defaultNext(node);
|
|
213
|
+
|
|
214
|
+
case "sleep": {
|
|
215
|
+
const duration = requireNodeMeta(
|
|
216
|
+
blueprintId,
|
|
217
|
+
node,
|
|
218
|
+
"duration",
|
|
219
|
+
node.meta?.duration,
|
|
220
|
+
);
|
|
221
|
+
await ctx.sleep({
|
|
222
|
+
duration: duration as DurationObject,
|
|
223
|
+
label: node.id,
|
|
224
|
+
});
|
|
225
|
+
return defaultNext(node);
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
case "wait": {
|
|
229
|
+
const event = requireNodeMeta(
|
|
230
|
+
blueprintId,
|
|
231
|
+
node,
|
|
232
|
+
"event",
|
|
233
|
+
node.meta?.event,
|
|
234
|
+
);
|
|
235
|
+
const timeout = requireNodeMeta(
|
|
236
|
+
blueprintId,
|
|
237
|
+
node,
|
|
238
|
+
"timeout",
|
|
239
|
+
node.meta?.timeout,
|
|
240
|
+
);
|
|
241
|
+
const result = await ctx.waitForEvent({
|
|
242
|
+
event,
|
|
243
|
+
timeout: timeout as DurationObject,
|
|
244
|
+
label: node.id,
|
|
245
|
+
});
|
|
246
|
+
// A forking wait branches on the answer (validation guarantees the
|
|
247
|
+
// answered/timedOut pair); a single unconditional edge (or none)
|
|
248
|
+
// continues regardless of the outcome.
|
|
249
|
+
const edges = outgoing.get(node.id) ?? [];
|
|
250
|
+
if (edges.length === 2) {
|
|
251
|
+
return nextByKind(node, result.timedOut ? "timedOut" : "answered");
|
|
252
|
+
}
|
|
253
|
+
return defaultNext(node);
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
case "send": {
|
|
257
|
+
const template = requireNodeMeta(
|
|
258
|
+
blueprintId,
|
|
259
|
+
node,
|
|
260
|
+
"template",
|
|
261
|
+
node.meta?.template,
|
|
262
|
+
);
|
|
263
|
+
// subject omitted → the tracked mailer falls back to the template
|
|
264
|
+
// registry's defaultSubject. idempotencyLabel = the node id (unique
|
|
265
|
+
// per graph), so the derived exactly-once key is branch-stable even
|
|
266
|
+
// when two sends of the same template share a nearest wait label.
|
|
267
|
+
await sendEmail({
|
|
268
|
+
to: user.email,
|
|
269
|
+
userId: user.id,
|
|
270
|
+
journeyStateId: user.stateId,
|
|
271
|
+
template: template as TemplateName,
|
|
272
|
+
journeyName: user.journeyName,
|
|
273
|
+
props: user.properties,
|
|
274
|
+
idempotencyLabel: node.meta?.idempotencyLabel ?? node.id,
|
|
275
|
+
});
|
|
276
|
+
return defaultNext(node);
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
case "connector": {
|
|
280
|
+
const connectorId = requireNodeMeta(
|
|
281
|
+
blueprintId,
|
|
282
|
+
node,
|
|
283
|
+
"connectorId",
|
|
284
|
+
node.meta?.connectorId,
|
|
285
|
+
);
|
|
286
|
+
const action = requireNodeMeta(
|
|
287
|
+
blueprintId,
|
|
288
|
+
node,
|
|
289
|
+
"action",
|
|
290
|
+
node.meta?.action,
|
|
291
|
+
);
|
|
292
|
+
// KNOWN PRE-EXISTING GAP (spec §15): sendConnectorAction's Layer-2
|
|
293
|
+
// backstop covers replays, but in degraded (pre-eviction) mode a
|
|
294
|
+
// crash between the provider call and the status flip can still
|
|
295
|
+
// double-send — same exposure a code journey's connector call has.
|
|
296
|
+
await sendConnectorAction({
|
|
297
|
+
connectorId,
|
|
298
|
+
action,
|
|
299
|
+
idempotencyLabel: node.id,
|
|
300
|
+
});
|
|
301
|
+
return defaultNext(node);
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
case "checkpoint":
|
|
305
|
+
await ctx.checkpoint(node.id);
|
|
306
|
+
return defaultNext(node);
|
|
307
|
+
|
|
308
|
+
case "trigger": {
|
|
309
|
+
const event = requireNodeMeta(
|
|
310
|
+
blueprintId,
|
|
311
|
+
node,
|
|
312
|
+
"event",
|
|
313
|
+
node.meta?.event,
|
|
314
|
+
);
|
|
315
|
+
// Save-time validation rejects reserved namespaces since the check
|
|
316
|
+
// was added, but the graph column is jsonb — a row saved BEFORE the
|
|
317
|
+
// rule (or written out-of-band) must still never forge an
|
|
318
|
+
// engine-emitted event through the ingest pipeline.
|
|
319
|
+
if (isReservedEventName(event)) {
|
|
320
|
+
throw new BlueprintNodeExecutionError(
|
|
321
|
+
blueprintId,
|
|
322
|
+
node.id,
|
|
323
|
+
`trigger node event "${event}" uses a reserved namespace (${RESERVED_EVENT_NAMESPACES.join("/")})`,
|
|
324
|
+
);
|
|
325
|
+
}
|
|
326
|
+
await ctx.trigger({
|
|
327
|
+
event,
|
|
328
|
+
userId: user.id,
|
|
329
|
+
userEmail: user.email,
|
|
330
|
+
idempotencyLabel: node.id,
|
|
331
|
+
});
|
|
332
|
+
return defaultNext(node);
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
case "branch":
|
|
336
|
+
case "decision": {
|
|
337
|
+
const conditions = node.meta?.conditions;
|
|
338
|
+
if (!conditions?.length) {
|
|
339
|
+
throw new BlueprintNodeExecutionError(
|
|
340
|
+
blueprintId,
|
|
341
|
+
node.id,
|
|
342
|
+
`${node.type} node has no conditions to evaluate`,
|
|
343
|
+
);
|
|
344
|
+
}
|
|
345
|
+
// AND across the array (a single composite condition expresses OR).
|
|
346
|
+
// Recorded via ctx.once so the verdict is durable on ANY engine: a
|
|
347
|
+
// decision may read live DB state (event / email_engagement
|
|
348
|
+
// conditions), and a replay re-evaluating it could flip the branch —
|
|
349
|
+
// diverging the positional durable journal AND selecting a different
|
|
350
|
+
// downstream template. Exactly the non-deterministic-discriminant
|
|
351
|
+
// case ctx.once exists for; the node id keys the record.
|
|
352
|
+
const passed = await ctx.once(`decision:${node.id}`, async () => {
|
|
353
|
+
for (const condition of conditions) {
|
|
354
|
+
const matched = await evaluateCondition({
|
|
355
|
+
condition,
|
|
356
|
+
ctx: { db, userId: user.id, journeyContext: user.properties },
|
|
357
|
+
});
|
|
358
|
+
if (!matched) return false;
|
|
359
|
+
}
|
|
360
|
+
return true;
|
|
361
|
+
});
|
|
362
|
+
return nextByKind(
|
|
363
|
+
node,
|
|
364
|
+
passed ? "conditional-true" : "conditional-false",
|
|
365
|
+
);
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
case "end-completed":
|
|
369
|
+
// Terminal: the run returns and the shared lifecycle marks the
|
|
370
|
+
// enrollment completed + pushes journey:completed — identical to a
|
|
371
|
+
// code journey's run() returning normally.
|
|
372
|
+
return null;
|
|
373
|
+
|
|
374
|
+
case "end-exited":
|
|
375
|
+
// Terminal "exited": the SAME primitive a code journey (and promoted
|
|
376
|
+
// blueprint code) calls — a guarded flip to "exited" plus the
|
|
377
|
+
// JourneyExitedError the lifecycle maps to { status: "exited" } without
|
|
378
|
+
// a "failed" write or a journey:failed push. One mechanism, not two.
|
|
379
|
+
return ctx.exit();
|
|
380
|
+
|
|
381
|
+
case "end-failed":
|
|
382
|
+
// Terminal: matches a code journey's thrown error — the lifecycle
|
|
383
|
+
// marks the row "failed" (structured errorMessage via serializeError),
|
|
384
|
+
// pushes journey:failed, and rethrows so the Hatchet run fails.
|
|
385
|
+
throw new BlueprintNodeExecutionError(
|
|
386
|
+
blueprintId,
|
|
387
|
+
node.id,
|
|
388
|
+
"the walk reached an end-failed terminal node",
|
|
389
|
+
);
|
|
390
|
+
|
|
391
|
+
// Non-executable display-tier types (NON_EXECUTABLE_NODE_TYPES).
|
|
392
|
+
// Unreachable in practice — validateBlueprintGraph rejected them at
|
|
393
|
+
// save time AND again at execution time — but the switch covers the
|
|
394
|
+
// FULL JourneyNodeType vocabulary so reaching one throws the typed
|
|
395
|
+
// error instead of walking past it silently (spec §6.1).
|
|
396
|
+
case "sleepUntil":
|
|
397
|
+
case "capture":
|
|
398
|
+
case "digest":
|
|
399
|
+
case "unknown":
|
|
400
|
+
throw new BlueprintNodeExecutionError(
|
|
401
|
+
blueprintId,
|
|
402
|
+
node.id,
|
|
403
|
+
`node type "${node.type}" is not executable in a blueprint`,
|
|
404
|
+
);
|
|
405
|
+
|
|
406
|
+
default: {
|
|
407
|
+
// Compiler-enforced exhaustiveness: adding a JourneyNodeType without
|
|
408
|
+
// an interpreter case is a COMPILE error, not a silent no-op.
|
|
409
|
+
const _exhaustive: never = node;
|
|
410
|
+
throw new BlueprintNodeExecutionError(
|
|
411
|
+
blueprintId,
|
|
412
|
+
(_exhaustive as JourneyNode).id,
|
|
413
|
+
`unhandled node type: ${(_exhaustive as JourneyNode).type}`,
|
|
414
|
+
);
|
|
415
|
+
}
|
|
416
|
+
}
|
|
417
|
+
};
|
|
418
|
+
|
|
419
|
+
let currentId: string | null = start.id;
|
|
420
|
+
let steps = 0;
|
|
421
|
+
while (currentId !== null) {
|
|
422
|
+
const node = nodesById.get(currentId);
|
|
423
|
+
if (!node) {
|
|
424
|
+
// An edge pointed at a node that does not exist. Unreachable post-
|
|
425
|
+
// validation (findInvalidEdgeEndpoints) — defense-in-depth.
|
|
426
|
+
throw new BlueprintUnreachableNodeError(blueprintId, currentId);
|
|
427
|
+
}
|
|
428
|
+
// Acyclicity backstop: a validated graph visits each node at most once,
|
|
429
|
+
// so a walk longer than the node count means a cycle slipped past
|
|
430
|
+
// validation — fail loudly instead of spinning durable sleeps forever.
|
|
431
|
+
steps += 1;
|
|
432
|
+
if (steps > nodes.length) {
|
|
433
|
+
throw new BlueprintNodeExecutionError(
|
|
434
|
+
blueprintId,
|
|
435
|
+
node.id,
|
|
436
|
+
"tree-walk exceeded the graph's node count — the graph is not acyclic",
|
|
437
|
+
);
|
|
438
|
+
}
|
|
439
|
+
try {
|
|
440
|
+
currentId = await executeNode(node);
|
|
441
|
+
} catch (err) {
|
|
442
|
+
if (isWalkPassThroughError(err)) throw err;
|
|
443
|
+
// Any other failure is pinned to the node that raised it, so
|
|
444
|
+
// journeyStates.errorMessage / Studio can point at exactly what broke.
|
|
445
|
+
throw new BlueprintNodeExecutionError(blueprintId, node.id, err);
|
|
446
|
+
}
|
|
447
|
+
}
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
/**
|
|
451
|
+
* A REPLAY (resume recovered by run id) that can no longer execute — the
|
|
452
|
+
* blueprint row vanished, or its stored graph now fails execution-time
|
|
453
|
+
* re-validation — must FAIL the recovered enrollment, not return `skipped`
|
|
454
|
+
* and leave a waiting/active row stranded non-terminal forever. Recovery is by
|
|
455
|
+
* the replay-stable Hatchet run id + journeyId, exactly as `executeJourneyRun`
|
|
456
|
+
* recovers an enrollment; a FRESH (never-enrolled) dispatch recovers nothing
|
|
457
|
+
* and the caller keeps returning `skipped` unchanged.
|
|
458
|
+
*
|
|
459
|
+
* Mirrors the failed path in `executeJourneyRun`: a guarded flip to "failed"
|
|
460
|
+
* (`notInArray(TERMINAL_STATUSES)`, so an already-terminal row is never
|
|
461
|
+
* clobbered) plus the same `journey:failed` side effects (structured
|
|
462
|
+
* errorMessage, failed transition, event push). Returns whether an existing
|
|
463
|
+
* enrollment was recovered for this run.
|
|
464
|
+
*/
|
|
465
|
+
async function failRecoveredBlueprintEnrollment(opts: {
|
|
466
|
+
db: Database;
|
|
467
|
+
blueprintId: string;
|
|
468
|
+
workflowRunId: string;
|
|
469
|
+
userId: string;
|
|
470
|
+
message: string;
|
|
471
|
+
}): Promise<boolean> {
|
|
472
|
+
const { db, blueprintId, workflowRunId, userId, message } = opts;
|
|
473
|
+
if (!workflowRunId) return false;
|
|
474
|
+
|
|
475
|
+
const recovered = await db.query.journeyStates.findFirst({
|
|
476
|
+
where: and(
|
|
477
|
+
eq(journeyStates.hatchetRunId, workflowRunId),
|
|
478
|
+
eq(journeyStates.journeyId, blueprintId),
|
|
479
|
+
),
|
|
480
|
+
});
|
|
481
|
+
if (!recovered) return false;
|
|
482
|
+
|
|
483
|
+
const [failed] = await db
|
|
484
|
+
.update(journeyStates)
|
|
485
|
+
.set({ status: "failed", errorMessage: message, updatedAt: new Date() })
|
|
486
|
+
.where(
|
|
487
|
+
and(
|
|
488
|
+
eq(journeyStates.id, recovered.id),
|
|
489
|
+
notInArray(journeyStates.status, [...TERMINAL_STATUSES]),
|
|
490
|
+
),
|
|
491
|
+
)
|
|
492
|
+
.returning({ id: journeyStates.id });
|
|
493
|
+
// Already terminal — nothing was stranded; the recovery still happened.
|
|
494
|
+
if (!failed) return true;
|
|
495
|
+
|
|
496
|
+
logger.error("blueprint replay failed the recovered enrollment", {
|
|
497
|
+
blueprintId,
|
|
498
|
+
stateId: recovered.id,
|
|
499
|
+
userId,
|
|
500
|
+
error: message,
|
|
501
|
+
});
|
|
502
|
+
logTransition({
|
|
503
|
+
db,
|
|
504
|
+
journeyStateId: recovered.id,
|
|
505
|
+
from: recovered.currentNodeId ?? null,
|
|
506
|
+
to: null,
|
|
507
|
+
action: "failed",
|
|
508
|
+
detail: { error: message },
|
|
509
|
+
});
|
|
510
|
+
await hatchet.events.push("journey:failed", {
|
|
511
|
+
journeyId: blueprintId,
|
|
512
|
+
stateId: recovered.id,
|
|
513
|
+
userId,
|
|
514
|
+
error: message,
|
|
515
|
+
});
|
|
516
|
+
return true;
|
|
517
|
+
}
|
|
518
|
+
|
|
519
|
+
/**
|
|
520
|
+
* The event payload `checkBlueprintTriggers` pushes for each matching enabled
|
|
521
|
+
* blueprint — one push per (blueprint, user) enrollment attempt.
|
|
522
|
+
*/
|
|
523
|
+
export interface BlueprintRunPayload {
|
|
524
|
+
blueprintId: JsonValue;
|
|
525
|
+
blueprintVersion: JsonValue;
|
|
526
|
+
userId: JsonValue;
|
|
527
|
+
userEmail: JsonValue;
|
|
528
|
+
triggerProperties: JsonValue;
|
|
529
|
+
[key: string]: JsonValue;
|
|
530
|
+
}
|
|
531
|
+
|
|
532
|
+
/**
|
|
533
|
+
* The generic blueprint interpreter — ONE statically-registered durable task
|
|
534
|
+
* for ALL blueprints, ever (spec §5): blueprints created/edited/enabled at
|
|
535
|
+
* runtime need no worker redeploy because dispatch is a DB lookup at ingest
|
|
536
|
+
* (`checkBlueprintTriggers`) feeding this task via `blueprint:run`, not a
|
|
537
|
+
* per-blueprint `onEvents` registration.
|
|
538
|
+
*
|
|
539
|
+
* Each run loads the blueprint row, re-validates the stored graph
|
|
540
|
+
* (defense-in-depth — jsonb is not trusted at execution time either), builds
|
|
541
|
+
* the row's `JourneyMeta` mirror, and hands the tree-walk to the SAME
|
|
542
|
+
* `executeJourneyRun` lifecycle `defineJourney` tasks use — identical
|
|
543
|
+
* enrollment guards, replay recovery, journey context, replay-safety
|
|
544
|
+
* boundary, and terminal transitions.
|
|
545
|
+
*/
|
|
546
|
+
export const journeyBlueprintInterpreter = hatchet.durableTask({
|
|
547
|
+
name: "journey-blueprint-interpreter",
|
|
548
|
+
onEvents: [BLUEPRINT_RUN_EVENT],
|
|
549
|
+
executionTimeout: JOURNEY_EXECUTION_TIMEOUT,
|
|
550
|
+
// retries STAYS 0 — same "missed > doubled" rationale as define-journey's
|
|
551
|
+
// task config: a retry replays side effects whose durable status flip may
|
|
552
|
+
// not have committed.
|
|
553
|
+
retries: 0,
|
|
554
|
+
scheduleTimeout: JOURNEY_SCHEDULE_TIMEOUT,
|
|
555
|
+
fn: async (input: BlueprintRunPayload, hatchetCtx) => {
|
|
556
|
+
const db = getDb();
|
|
557
|
+
const blueprintId = input.blueprintId as string;
|
|
558
|
+
// Recovery anchor: a REPLAY resumes under the SAME run id, so a blueprint
|
|
559
|
+
// that has since vanished / gone invalid must fail its recovered
|
|
560
|
+
// enrollment rather than strand it (see failRecoveredBlueprintEnrollment).
|
|
561
|
+
const workflowRunId = hatchetCtx.workflowRunId();
|
|
562
|
+
const userId = input.userId as string;
|
|
563
|
+
|
|
564
|
+
const row = await db.query.journeyBlueprints.findFirst({
|
|
565
|
+
where: eq(journeyBlueprints.id, blueprintId),
|
|
566
|
+
});
|
|
567
|
+
if (!row) {
|
|
568
|
+
logger.warn("blueprint run skipped: blueprint not found", {
|
|
569
|
+
blueprintId,
|
|
570
|
+
});
|
|
571
|
+
const failed = await failRecoveredBlueprintEnrollment({
|
|
572
|
+
db,
|
|
573
|
+
blueprintId,
|
|
574
|
+
workflowRunId,
|
|
575
|
+
userId,
|
|
576
|
+
message: JSON.stringify(
|
|
577
|
+
serializeBlueprintError(
|
|
578
|
+
blueprintId,
|
|
579
|
+
new Error("blueprint row not found at execution time"),
|
|
580
|
+
),
|
|
581
|
+
),
|
|
582
|
+
});
|
|
583
|
+
return failed
|
|
584
|
+
? { status: "failed", reason: "blueprint_not_found" }
|
|
585
|
+
: { status: "skipped", reason: "blueprint_not_found" };
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
// Defense-in-depth (spec §6): a saved blueprint already passed
|
|
589
|
+
// validateBlueprintGraph at save time, but the graph column is still
|
|
590
|
+
// jsonb — never execute it without re-validating.
|
|
591
|
+
const validated = validateBlueprintGraph(row.graph);
|
|
592
|
+
if (!validated.valid) {
|
|
593
|
+
logger.error(
|
|
594
|
+
"blueprint run skipped: stored graph failed execution-time validation",
|
|
595
|
+
{ blueprintId, issues: validated.issues },
|
|
596
|
+
);
|
|
597
|
+
const failed = await failRecoveredBlueprintEnrollment({
|
|
598
|
+
db,
|
|
599
|
+
blueprintId,
|
|
600
|
+
workflowRunId,
|
|
601
|
+
userId,
|
|
602
|
+
message: JSON.stringify(
|
|
603
|
+
serializeBlueprintError(
|
|
604
|
+
blueprintId,
|
|
605
|
+
new Error("stored graph failed execution-time re-validation"),
|
|
606
|
+
),
|
|
607
|
+
),
|
|
608
|
+
});
|
|
609
|
+
return failed
|
|
610
|
+
? { status: "failed", reason: "invalid_blueprint_graph" }
|
|
611
|
+
: { status: "skipped", reason: "invalid_blueprint_graph" };
|
|
612
|
+
}
|
|
613
|
+
|
|
614
|
+
// Version pin (spec §12): the version this run enrolled under, recorded
|
|
615
|
+
// into journeyStates.context.__blueprintVersion on FIRST entry (a replay
|
|
616
|
+
// recovers the existing row — extraContext is never re-written). v1 keeps
|
|
617
|
+
// no graph history, so a drifted row can only execute the CURRENT graph —
|
|
618
|
+
// surface the drift loudly instead of failing the run.
|
|
619
|
+
const enrolledVersion =
|
|
620
|
+
typeof input.blueprintVersion === "number"
|
|
621
|
+
? input.blueprintVersion
|
|
622
|
+
: row.version;
|
|
623
|
+
if (enrolledVersion !== row.version) {
|
|
624
|
+
logger.warn(
|
|
625
|
+
"blueprint version drifted since this run was dispatched; executing the current graph",
|
|
626
|
+
{ blueprintId, enrolledVersion, currentVersion: row.version },
|
|
627
|
+
);
|
|
628
|
+
}
|
|
629
|
+
|
|
630
|
+
const meta = blueprintMetaFromRow(row);
|
|
631
|
+
const graph = validated.graph;
|
|
632
|
+
|
|
633
|
+
return executeJourneyRun({
|
|
634
|
+
meta,
|
|
635
|
+
run: (user, ctx) =>
|
|
636
|
+
walkBlueprintGraph({ blueprintId: row.id, graph, user, ctx, db }),
|
|
637
|
+
input: {
|
|
638
|
+
userId: input.userId,
|
|
639
|
+
userEmail: input.userEmail,
|
|
640
|
+
properties: input.triggerProperties,
|
|
641
|
+
} satisfies EventPayloadInput,
|
|
642
|
+
hatchetCtx,
|
|
643
|
+
extraContext: { __blueprintVersion: enrolledVersion },
|
|
644
|
+
// Serialize this enrollment insert against a concurrent graph edit
|
|
645
|
+
// (updateBlueprint takes the SAME advisory lock around its in-flight
|
|
646
|
+
// count + update) so the run cannot become active between that count and
|
|
647
|
+
// the graph write — the desync window the in-flight gate exists to close.
|
|
648
|
+
serializeEnrollment: true,
|
|
649
|
+
// Structured errorMessage (spec §6.1): { blueprintId, nodeId, message }
|
|
650
|
+
// as JSON in the SAME journeyStates.errorMessage field code journeys
|
|
651
|
+
// use, so Studio's error display needs no blueprint-specific branching.
|
|
652
|
+
serializeError: (err) =>
|
|
653
|
+
JSON.stringify(serializeBlueprintError(row.id, err)),
|
|
654
|
+
});
|
|
655
|
+
},
|
|
656
|
+
});
|