@hogsend/engine 0.38.0 → 0.38.2

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.38.0",
3
+ "version": "0.38.2",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -42,14 +42,14 @@
42
42
  "svix": "^1.95.1",
43
43
  "winston": "^3.19.0",
44
44
  "zod": "^4.4.3",
45
- "@hogsend/core": "^0.38.0",
46
- "@hogsend/db": "^0.38.0",
47
- "@hogsend/email": "^0.38.0",
48
- "@hogsend/plugin-posthog": "^0.38.0",
49
- "@hogsend/plugin-resend": "^0.38.0"
45
+ "@hogsend/core": "^0.38.2",
46
+ "@hogsend/db": "^0.38.2",
47
+ "@hogsend/email": "^0.38.2",
48
+ "@hogsend/plugin-posthog": "^0.38.2",
49
+ "@hogsend/plugin-resend": "^0.38.2"
50
50
  },
51
51
  "optionalDependencies": {
52
- "@hogsend/plugin-postmark": "^0.38.0"
52
+ "@hogsend/plugin-postmark": "^0.38.2"
53
53
  },
54
54
  "devDependencies": {
55
55
  "@types/node": "^22.15.3",
@@ -12,3 +12,12 @@
12
12
  */
13
13
  export const JOURNEY_EXECUTION_TIMEOUT_HOURS = 720;
14
14
  export const JOURNEY_EXECUTION_TIMEOUT = `${JOURNEY_EXECUTION_TIMEOUT_HOURS}h`;
15
+
16
+ /**
17
+ * Max time a journey task may wait in the queue for a worker slot before Hatchet
18
+ * cancels it (`scheduleTimeout`). The SDK default (~5m) is too tight for a
19
+ * durable-wait RESUME that re-queues during a redeploy when every worker slot is
20
+ * momentarily saturated — the resume would be cancelled and the enrollment
21
+ * stranded. 15m gives resumes head-room to land on a freed slot.
22
+ */
23
+ export const JOURNEY_SCHEDULE_TIMEOUT = "15m";
@@ -19,7 +19,10 @@ import { createLogger } from "../lib/logger.js";
19
19
  import { emitOutbound } from "../lib/outbound.js";
20
20
  import { resolveTimezoneWithSource } from "../lib/timezone.js";
21
21
  import { getClientScheduleDefaults } from "./client-defaults-singleton.js";
22
- import { JOURNEY_EXECUTION_TIMEOUT } from "./constants.js";
22
+ import {
23
+ JOURNEY_EXECUTION_TIMEOUT,
24
+ JOURNEY_SCHEDULE_TIMEOUT,
25
+ } from "./constants.js";
23
26
  import { JourneyExitedError } from "./errors.js";
24
27
  import {
25
28
  createMemoize,
@@ -93,7 +96,20 @@ export function defineJourney(options: {
93
96
  name: `journey-${meta.id}`,
94
97
  onEvents: [meta.trigger.event],
95
98
  executionTimeout: JOURNEY_EXECUTION_TIMEOUT,
99
+ // retries STAYS 0 — deliberately. A retry replays `run()` from the top, and
100
+ // the tracked mailer / connector machinery is "missed > doubled": a `queued`
101
+ // row is RE-DRIVEN and a failed send NULLs its idempotency key (tracked.ts
102
+ // ~150-176, 496-514). That is safe only while nothing re-invokes a run whose
103
+ // `provider.send()` already delivered but whose durable status flip didn't
104
+ // commit — turning retries on would re-deliver that email/connector message
105
+ // (a DUPLICATE). Enabling retries requires making sends provider-idempotent
106
+ // first (Resend/Postmark `Idempotency-Key`); tracked as a follow-up.
96
107
  retries: 0,
108
+ // `scheduleTimeout` widens the queue-wait ceiling (SDK default ~5m) so a
109
+ // durable-wait RESUME re-queued during a redeploy's slot saturation reclaims
110
+ // a slot instead of being cancelled (which strands the enrollment). Unlike
111
+ // retries this adds NO replay — it is pure head-room, so it is safe on its own.
112
+ scheduleTimeout: JOURNEY_SCHEDULE_TIMEOUT,
97
113
  fn: async (input: EventPayloadInput, hatchetCtx) => {
98
114
  const db = getDb();
99
115
  const userId = input.userId as string;
@@ -103,42 +119,6 @@ export function defineJourney(options: {
103
119
  string | number | boolean | null
104
120
  >;
105
121
 
106
- if (!meta.enabled) {
107
- return { status: "skipped", reason: "journey_disabled" };
108
- }
109
-
110
- const configOverride = await db.query.journeyConfigs.findFirst({
111
- where: eq(journeyConfigs.journeyId, meta.id),
112
- });
113
- if (configOverride && !configOverride.enabled) {
114
- return { status: "skipped", reason: "journey_disabled_by_admin" };
115
- }
116
-
117
- if (meta.trigger.where?.length) {
118
- if (
119
- !evaluatePropertyConditions({
120
- conditions: meta.trigger.where,
121
- properties,
122
- })
123
- ) {
124
- return { status: "skipped", reason: "trigger_conditions_not_met" };
125
- }
126
- }
127
-
128
- const entryAllowed = await checkEntryLimit({
129
- db,
130
- journey: meta,
131
- userId,
132
- });
133
- if (!entryAllowed.allowed) {
134
- return { status: "skipped", reason: entryAllowed.reason };
135
- }
136
-
137
- const prefs = await checkEmailPreferences({ db, userId });
138
- if (prefs.unsubscribed) {
139
- return { status: "skipped", reason: "user_unsubscribed" };
140
- }
141
-
142
122
  // The replay-stable anchor for this enrollment: the Hatchet run id is
143
123
  // preserved across replays of the SAME logical durable run (crash / OOM /
144
124
  // eviction / redeploy mid-run), whereas a freshly-minted journeyStates.id
@@ -146,14 +126,19 @@ export function defineJourney(options: {
146
126
  // on it so a replay re-derives the SAME stateId and the SAME keys.
147
127
  const workflowRunId = hatchetCtx.workflowRunId();
148
128
 
149
- // REPLAY RECOVERY (must run before the active-state guard / insert).
150
- // A replay-from-top of the same run must reuse the enrollment it already
151
- // created — otherwise, for a journey whose prior enrollment reached a
152
- // TERMINAL status (the normal end state for unlimited/once_per_period), the
153
- // active-state guard would miss it, a fresh stateId would be minted, and the
154
- // derived keys would no longer collide → a duplicate send. Recovering by the
155
- // run-stable id makes the replay deterministic regardless of the prior row's
156
- // status.
129
+ // REPLAY RECOVERY — must run BEFORE the enrollment guards below. An
130
+ // eviction-capable Hatchet engine (hatchet-lite >= v0.80.0) replays `fn`
131
+ // from the top on every durable-wait resume, so every statement above the
132
+ // first durable primitive re-runs on each resume. The enrollment guards
133
+ // (entryLimit / preferences / trigger conditions / enabled / active-state)
134
+ // are ENTRY gates: re-running them on a resume is wrong. In particular a
135
+ // `once` journey's own entry-limit guard would find the row it created on
136
+ // first entry and skip EVERY resume, stranding the journey in `waiting` and
137
+ // silently dropping all sends after the first. Recovering by the run-stable
138
+ // id first lets a resume reuse its enrollment and bypass the entry gates (a
139
+ // resume is not an entry). It also keeps the original purpose: a journey
140
+ // whose prior enrollment reached a TERMINAL status (unlimited /
141
+ // once_per_period) recovers the SAME stateId so derived keys still collide.
157
142
  const recovered = workflowRunId
158
143
  ? await db.query.journeyStates.findFirst({
159
144
  where: and(
@@ -164,7 +149,49 @@ export function defineJourney(options: {
164
149
  : undefined;
165
150
 
166
151
  let state = recovered;
152
+
153
+ // FIRST ENTRY ONLY — the enrollment guards gate ENTRY, not resume. A
154
+ // recovered enrollment already passed them on first entry, so it skips
155
+ // straight to resuming the run. (Sends inside `run` still re-check
156
+ // subscription via `ctx.guard.isSubscribed()` after every wait, so
157
+ // bypassing the entry-time preference gate never emails an unsubscriber.)
167
158
  if (!state) {
159
+ if (!meta.enabled) {
160
+ return { status: "skipped", reason: "journey_disabled" };
161
+ }
162
+
163
+ const configOverride = await db.query.journeyConfigs.findFirst({
164
+ where: eq(journeyConfigs.journeyId, meta.id),
165
+ });
166
+ if (configOverride && !configOverride.enabled) {
167
+ return { status: "skipped", reason: "journey_disabled_by_admin" };
168
+ }
169
+
170
+ if (meta.trigger.where?.length) {
171
+ if (
172
+ !evaluatePropertyConditions({
173
+ conditions: meta.trigger.where,
174
+ properties,
175
+ })
176
+ ) {
177
+ return { status: "skipped", reason: "trigger_conditions_not_met" };
178
+ }
179
+ }
180
+
181
+ const entryAllowed = await checkEntryLimit({
182
+ db,
183
+ journey: meta,
184
+ userId,
185
+ });
186
+ if (!entryAllowed.allowed) {
187
+ return { status: "skipped", reason: entryAllowed.reason };
188
+ }
189
+
190
+ const prefs = await checkEmailPreferences({ db, userId });
191
+ if (prefs.unsubscribed) {
192
+ return { status: "skipped", reason: "user_unsubscribed" };
193
+ }
194
+
168
195
  const activeState = await db.query.journeyStates.findFirst({
169
196
  where: and(
170
197
  eq(journeyStates.userId, userId),
@@ -219,9 +246,14 @@ export function defineJourney(options: {
219
246
  // Independent I/O — fetch the contact row and PostHog person props
220
247
  // concurrently. PostHog failures fall through to undefined.
221
248
  const [contact, posthogProperties] = await Promise.all([
222
- db.query.contacts.findFirst({
223
- where: eq(contacts.externalId, userId),
224
- }),
249
+ // Both legs are best-effort tz inputs: a failure here must fall through
250
+ // to the client-default tz, never reject the `Promise.all` and throw out
251
+ // of `fn` BEFORE the try/catch below (which would strand the row —
252
+ // already inserted "active" — outside the failure handling). The PostHog
253
+ // leg already `.catch`es; mirror it on the contact read.
254
+ db.query.contacts
255
+ .findFirst({ where: eq(contacts.externalId, userId) })
256
+ .catch(() => undefined),
225
257
  posthog?.getPersonProperties(userId).catch(() => undefined),
226
258
  ]);
227
259