@dudousxd/nestjs-durable 0.60.0 → 0.61.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/dist/index.d.cts CHANGED
@@ -764,6 +764,27 @@ interface DurableModuleSharedOptions {
764
764
  controlPlane?: ControlPlane;
765
765
  /** Interval (ms) for the durable-timer poller. `0` disables it. Defaults to 1000. Operator only. */
766
766
  timerPollMs?: number;
767
+ /**
768
+ * The longest wait (ms) between two timer polls while there is nothing to do. After a poll that
769
+ * found no work the wait doubles from `timerPollMs` up to this, and goes back to `timerPollMs` as
770
+ * soon as there is work or any run event (here, or from another instance over the control plane).
771
+ * It never outlasts a known due time: before each longer wait the poller reads when the next timer,
772
+ * blocked-run recovery poll, persisted schedule or in-process `schedules` window is due. What it
773
+ * delays is recovery only: a crashed instance's runs, execution timeouts and the stalled/
774
+ * buffered-signal sweeps are picked up at most this late. A value at or below `timerPollMs` keeps
775
+ * the fixed tick, and so does an engine with neither a control plane nor a run queue (a run another
776
+ * instance starts reaches it only through the pending-run poll). Defaults to 5000. Operator only.
777
+ */
778
+ maxIdleIntervalMs?: number;
779
+ /**
780
+ * How often (ms) the timer poller lists the settled runs that still owe a lifecycle event, and
781
+ * heals the ones that missed a newly announced subscriber. That listing is the recovery path for a
782
+ * publish that never happened (the live publish gets a 30 s grace first) and filters runs by tag,
783
+ * so running it on every tick cost a scan of the runs table each second for nothing. The run-wait
784
+ * delivery and registry heartbeat still run every tick. A failed sweep is retried on the next tick.
785
+ * `0` sweeps on every tick (the old behavior). Defaults to 10000. Operator only.
786
+ */
787
+ owedLifecycleSweepMs?: number;
767
788
  /**
768
789
  * Auto-create the durable tables on boot via `store.ensureSchema()`. Defaults to true. Turn
769
790
  * off in production and call the store adapter's `ensure*DurableSchema()` from a migration.
package/dist/index.d.ts CHANGED
@@ -764,6 +764,27 @@ interface DurableModuleSharedOptions {
764
764
  controlPlane?: ControlPlane;
765
765
  /** Interval (ms) for the durable-timer poller. `0` disables it. Defaults to 1000. Operator only. */
766
766
  timerPollMs?: number;
767
+ /**
768
+ * The longest wait (ms) between two timer polls while there is nothing to do. After a poll that
769
+ * found no work the wait doubles from `timerPollMs` up to this, and goes back to `timerPollMs` as
770
+ * soon as there is work or any run event (here, or from another instance over the control plane).
771
+ * It never outlasts a known due time: before each longer wait the poller reads when the next timer,
772
+ * blocked-run recovery poll, persisted schedule or in-process `schedules` window is due. What it
773
+ * delays is recovery only: a crashed instance's runs, execution timeouts and the stalled/
774
+ * buffered-signal sweeps are picked up at most this late. A value at or below `timerPollMs` keeps
775
+ * the fixed tick, and so does an engine with neither a control plane nor a run queue (a run another
776
+ * instance starts reaches it only through the pending-run poll). Defaults to 5000. Operator only.
777
+ */
778
+ maxIdleIntervalMs?: number;
779
+ /**
780
+ * How often (ms) the timer poller lists the settled runs that still owe a lifecycle event, and
781
+ * heals the ones that missed a newly announced subscriber. That listing is the recovery path for a
782
+ * publish that never happened (the live publish gets a 30 s grace first) and filters runs by tag,
783
+ * so running it on every tick cost a scan of the runs table each second for nothing. The run-wait
784
+ * delivery and registry heartbeat still run every tick. A failed sweep is retried on the next tick.
785
+ * `0` sweeps on every tick (the old behavior). Defaults to 10000. Operator only.
786
+ */
787
+ owedLifecycleSweepMs?: number;
767
788
  /**
768
789
  * Auto-create the durable tables on boot via `store.ensureSchema()`. Defaults to true. Turn
769
790
  * off in production and call the store adapter's `ensure*DurableSchema()` from a migration.
package/dist/index.js CHANGED
@@ -3107,6 +3107,7 @@ var TenantEventRepublisher = class {
3107
3107
  };
3108
3108
 
3109
3109
  // src/timer-poller.ts
3110
+ import * as durableCore from "@dudousxd/nestjs-durable-core";
3110
3111
  import { DURABLE_OPTIONS_CANONICAL as DURABLE_OPTIONS_CANONICAL6, WorkflowEngine as WorkflowEngine3, runSchedules, workflowName as workflowName3 } from "@dudousxd/nestjs-durable-core";
3111
3112
  import { Inject as Inject7, Injectable as Injectable10, Optional as Optional3 } from "@nestjs/common";
3112
3113
  function _ts_decorate10(decorators, target, key, desc) {
@@ -3135,6 +3136,8 @@ function _ts_param7(paramIndex, decorator) {
3135
3136
  };
3136
3137
  }
3137
3138
  __name(_ts_param7, "_ts_param");
3139
+ var SWEEP_FAILED = Symbol("sweep failed");
3140
+ var nextScheduleFireAt2 = durableCore.nextScheduleFireAt;
3138
3141
  var TimerPoller = class {
3139
3142
  static {
3140
3143
  __name(this, "TimerPoller");
@@ -3147,6 +3150,15 @@ var TimerPoller = class {
3147
3150
  /** The sweep in flight, so shutdown can wait for it instead of racing the store's close. */
3148
3151
  current;
3149
3152
  unsubscribeEnqueued;
3153
+ unsubscribeEvents;
3154
+ /** Set by shutdown: the backoff loop stops scheduling polls. */
3155
+ stopped = false;
3156
+ /** Something happened (a run event, an enqueue nudge) since the last poll started. */
3157
+ activity = false;
3158
+ /** Ends the backoff loop's current wait early (set only while it waits). */
3159
+ endWait;
3160
+ /** When the owed-lifecycle listing last succeeded (see {@link owedSweepDue}). */
3161
+ owedSweptAt;
3150
3162
  constructor(engine, options, leases = new SweepLeases()) {
3151
3163
  this.engine = engine;
3152
3164
  this.options = options;
@@ -3157,6 +3169,7 @@ var TimerPoller = class {
3157
3169
  if (!isDrivingOperator(this.options)) return;
3158
3170
  this.engine.consumeRuns?.();
3159
3171
  this.unsubscribeEnqueued = this.engine.onEnqueued((runId) => {
3172
+ this.noteActivity();
3160
3173
  if (typeof this.engine.runEnqueued === "function") {
3161
3174
  this.engine.runEnqueued(runId);
3162
3175
  return;
@@ -3165,14 +3178,102 @@ var TimerPoller = class {
3165
3178
  console.error(`[nestjs-durable] could not run enqueued run ${runId}:`, error);
3166
3179
  });
3167
3180
  });
3168
- void this.poll();
3169
3181
  const intervalMs = this.options.timerPollMs ?? 1e3;
3182
+ const maxIdleMs = this.options.maxIdleIntervalMs ?? 5e3;
3183
+ if (intervalMs > 0 && maxIdleMs > intervalMs && this.canBackOff()) {
3184
+ this.unsubscribeEvents = this.engine.subscribe(() => this.noteActivity());
3185
+ void this.loop(intervalMs, maxIdleMs);
3186
+ return;
3187
+ }
3188
+ void this.poll();
3170
3189
  if (intervalMs > 0) {
3171
3190
  this.timer = setInterval(() => void this.poll(), intervalMs);
3172
3191
  this.timer.unref?.();
3173
3192
  }
3174
3193
  }
3175
3194
  /**
3195
+ * Whether polls may be spaced out while idle: the engine must reach new runs without the
3196
+ * pending-run poll and say when its next timer is due, and the in-process schedules must be able
3197
+ * to say when their next window is. Optional calls throughout: an older core keeps the fixed tick.
3198
+ */
3199
+ canBackOff() {
3200
+ if (this.engine.idleBackoffSupported !== true) return false;
3201
+ if (typeof this.engine.nextDueAt !== "function") return false;
3202
+ if ((this.options.schedules?.length ?? 0) > 0 && nextScheduleFireAt2 === void 0) return false;
3203
+ return true;
3204
+ }
3205
+ noteActivity() {
3206
+ this.activity = true;
3207
+ this.endWait?.();
3208
+ }
3209
+ /**
3210
+ * Poll, then wait: `intervalMs` after a poll that found work (or while anything happened), else
3211
+ * twice the last wait up to `maxIdleMs`, cut short so the next poll runs no later than the earliest
3212
+ * known due time. A run event or an enqueue nudge ends a wait at once.
3213
+ */
3214
+ async loop(intervalMs, maxIdleMs) {
3215
+ let wait = intervalMs;
3216
+ while (!this.stopped) {
3217
+ const arrived = this.activity;
3218
+ this.activity = false;
3219
+ const worked = await this.poll();
3220
+ if (this.stopped) return;
3221
+ const idle = !worked && !arrived && !this.activity;
3222
+ wait = idle ? Math.min(wait * 2, maxIdleMs) : intervalMs;
3223
+ let next = wait;
3224
+ if (next > intervalMs) next = await this.untilDue(next, intervalMs);
3225
+ if (this.stopped) return;
3226
+ if (this.activity) next = Math.min(next, intervalMs);
3227
+ await new Promise((resolve) => {
3228
+ const done = /* @__PURE__ */ __name(() => {
3229
+ clearTimeout(timer);
3230
+ this.endWait = void 0;
3231
+ resolve();
3232
+ }, "done");
3233
+ const timer = setTimeout(done, next);
3234
+ timer.unref?.();
3235
+ this.endWait = () => {
3236
+ if (this.stopped || next > intervalMs) done();
3237
+ };
3238
+ });
3239
+ }
3240
+ }
3241
+ /**
3242
+ * `wait`, shortened so the next poll runs no later than the earliest known due time: the engine's
3243
+ * next timer, blocked-run recovery poll or persisted schedule, and the next window of the
3244
+ * in-process `schedules`. Never below `intervalMs` (the regular tick catches what is due sooner). A
3245
+ * failed read keeps the regular tick.
3246
+ */
3247
+ async untilDue(wait, intervalMs) {
3248
+ try {
3249
+ const now = Date.now();
3250
+ const stored = await this.engine.nextDueAt(now + wait, {
3251
+ persistedSchedules: this.options.persistedSchedules === true
3252
+ });
3253
+ const schedules = this.options.schedules;
3254
+ const scheduled = schedules && schedules.length > 0 && nextScheduleFireAt2 ? nextScheduleFireAt2(this.engine, schedules, now) : void 0;
3255
+ let due = wait;
3256
+ for (const at of [
3257
+ stored,
3258
+ scheduled
3259
+ ]) {
3260
+ if (at !== void 0) due = Math.min(due, at - Date.now());
3261
+ }
3262
+ return Math.max(intervalMs, due);
3263
+ } catch {
3264
+ return intervalMs;
3265
+ }
3266
+ }
3267
+ /**
3268
+ * Whether this poll lists the owed lifecycle runs: until a sweep that listed them succeeded, then
3269
+ * once per `owedLifecycleSweepMs` (a clock that went back lists them again).
3270
+ */
3271
+ owedSweepDue(now) {
3272
+ const every = this.options.owedLifecycleSweepMs ?? 1e4;
3273
+ const last = this.owedSweptAt;
3274
+ return every <= 0 || last === void 0 || now < last || now - last >= every;
3275
+ }
3276
+ /**
3176
3277
  * Stop polling and wait for the sweep in flight (bounded by `shutdownTimeoutMs`, default 10s).
3177
3278
  * Nest runs every `onModuleDestroy` before any `onApplicationShutdown`, so returning here only once
3178
3279
  * the sweep has settled means no store call is still pending when the registrar drains and the
@@ -3181,8 +3282,11 @@ var TimerPoller = class {
3181
3282
  * from the later `engine.drain()`, so poll wait plus drain stay within one `shutdownTimeoutMs`.
3182
3283
  */
3183
3284
  async onModuleDestroy() {
3285
+ this.stopped = true;
3184
3286
  if (this.timer) clearInterval(this.timer);
3287
+ this.endWait?.();
3185
3288
  this.unsubscribeEnqueued?.();
3289
+ this.unsubscribeEvents?.();
3186
3290
  if (!isDrivingOperator(this.options)) return;
3187
3291
  this.engine.beginDrain?.();
3188
3292
  if (!this.current) return;
@@ -3208,7 +3312,7 @@ var TimerPoller = class {
3208
3312
  * the rest of the tick would silently widen one subsystem's outage into all of them.
3209
3313
  */
3210
3314
  poll() {
3211
- if (this.polling) return this.current ?? Promise.resolve();
3315
+ if (this.polling) return this.current ?? Promise.resolve(true);
3212
3316
  this.polling = true;
3213
3317
  const run = this.pollOnce().finally(() => {
3214
3318
  this.polling = false;
@@ -3217,31 +3321,44 @@ var TimerPoller = class {
3217
3321
  this.current = run;
3218
3322
  return run;
3219
3323
  }
3324
+ /** One poll of every sweep. Resolves whether it found work (or a sweep failed): see {@link loop}. */
3220
3325
  async pollOnce() {
3221
- {
3222
- await this.sweep("runPending", () => this.engine.runPending());
3223
- await this.sweep("recoverIncomplete", () => this.engine.recoverIncomplete());
3224
- await this.sweep("resumeDueTimers", () => this.engine.resumeDueTimers());
3225
- await this.sweep("sweepTimeouts", () => this.engine.sweepTimeouts());
3226
- await this.sweep("sweepStalled", () => this.leases.run("stalled-pager", async () => this.engine.sweepStalled?.()));
3227
- await this.sweep("sweepBufferedSignals", () => this.leases.run("buffered-signals", async () => this.engine.sweepBufferedSignals?.()));
3228
- await this.sweep("sweepExpiredSignalIds", () => this.leases.run("signal-ids", async () => this.engine.sweepExpiredSignalIds?.()));
3229
- await this.sweep("sweepLifecycleEvents", async () => this.engine.sweepLifecycleEvents?.());
3230
- const schedules = this.options.schedules;
3231
- if (schedules && schedules.length > 0) {
3232
- await this.sweep("schedules", () => runSchedules(this.engine, schedules, Date.now()));
3233
- }
3234
- if (this.options.persistedSchedules) {
3235
- await this.sweep("persistedSchedules", () => this.engine.schedules.tick());
3236
- }
3326
+ let worked = false;
3327
+ const note = /* @__PURE__ */ __name((result) => {
3328
+ if (result === SWEEP_FAILED || Array.isArray(result) && result.length > 0) worked = true;
3329
+ }, "note");
3330
+ note(await this.sweep("runPending", () => this.engine.runPending()));
3331
+ note(await this.sweep("recoverIncomplete", () => this.engine.recoverIncomplete()));
3332
+ note(await this.sweep("resumeDueTimers", () => this.engine.resumeDueTimers()));
3333
+ note(await this.sweep("sweepTimeouts", () => this.engine.sweepTimeouts()));
3334
+ note(await this.sweep("sweepStalled", () => this.leases.run("stalled-pager", async () => this.engine.sweepStalled?.())));
3335
+ note(await this.sweep("sweepBufferedSignals", () => this.leases.run("buffered-signals", async () => this.engine.sweepBufferedSignals?.())));
3336
+ note(await this.sweep("sweepExpiredSignalIds", () => this.leases.run("signal-ids", async () => this.engine.sweepExpiredSignalIds?.())));
3337
+ const now = Date.now();
3338
+ const owed = this.owedSweepDue(now);
3339
+ note(await this.sweep("sweepLifecycleEvents", async () => {
3340
+ const published = await this.engine.sweepLifecycleEvents?.(void 0, void 0, {
3341
+ owed
3342
+ });
3343
+ if (owed) this.owedSweptAt = now;
3344
+ return published;
3345
+ }));
3346
+ const schedules = this.options.schedules;
3347
+ if (schedules && schedules.length > 0) {
3348
+ note(await this.sweep("schedules", () => runSchedules(this.engine, schedules, Date.now())));
3349
+ }
3350
+ if (this.options.persistedSchedules) {
3351
+ note(await this.sweep("persistedSchedules", () => this.engine.schedules.tick()));
3237
3352
  }
3353
+ return worked;
3238
3354
  }
3239
3355
  /** Run one sweep, absorbing and reporting its failure — see {@link poll}. */
3240
3356
  async sweep(name, run) {
3241
3357
  try {
3242
- await run();
3358
+ return await run();
3243
3359
  } catch (error) {
3244
3360
  console.error(`[nestjs-durable] timer poll: ${name} failed; continuing:`, error);
3361
+ return SWEEP_FAILED;
3245
3362
  }
3246
3363
  }
3247
3364
  };