@rotorsoft/act 1.24.1 → 1.25.0

package/dist/index.js

@@ -931,6 +931,18 @@ function resolveSettleConfig(options) {
   SettleOptionsSchema.parse(options);
   return options;
 }
+var MAX_SHUTDOWN_GRACE_MS = 3e4;
+var DEFAULT_SHUTDOWN_GRACE_MS = 1e4;
+var ShutdownOptionsSchema = z2.object({
+  // `0` is legal and is exactly today's behavior: stop scheduling and
+  // return without waiting.
+  graceMs: z2.number().min(0).optional()
+}).loose();
+function resolveShutdownConfig(options) {
+  if (options === void 0) return void 0;
+  ShutdownOptionsSchema.parse(options);
+  return options;
+}
 var ActOptionsSchema = z2.object({
   maxSubscribedStreams: z2.number().int().min(1).optional(),
   settleDebounceMs: z2.number().int().min(0).optional()
@@ -2636,6 +2648,16 @@ var DrainController = class {
   /** Worker timer (ACT-1103). Set when `start()` is active, undefined otherwise. */
   _worker;
   _stopped = false;
+  /**
+   * Resolves when the cycle currently in flight finishes; `undefined` when
+   * no cycle is running (#1442). `_locked` answers "is a cycle running?" for
+   * the overlap guard; this answers "tell me when it is done" for a graceful
+   * shutdown, which needs to await the handler rather than abandon it
+   * mid-`await` with the stream still leased. Never rejects — `drain()`
+   * contains its own errors — so awaiting it is always safe.
+   */
+  _inflight;
+  _inflight_done;
   _deps;
   constructor(deps) {
     this._deps = deps;
@@ -2668,6 +2690,24 @@ var DrainController = class {
   get armed() {
     return this._armed;
   }
+  /**
+   * The cycle currently in flight, or `undefined` when idle (#1442). A
+   * graceful shutdown awaits this so an in-flight handler reaches its `ack`
+   * — which releases the stream's lease — instead of being abandoned with
+   * the lease held until it expires.
+   */
+  get inflight() {
+    return this._inflight;
+  }
+  /**
+   * This lane's configured lease budget, or `undefined` when the lane didn't
+   * pin one. It is the operator's own statement of how long a handler may
+   * legitimately hold a stream, which makes it the right basis for a
+   * shutdown grace budget (#1442).
+   */
+  get lease_millis() {
+    return this._deps.defaults?.leaseMillis;
+  }
   /** Lane this controller drains (undefined = legacy single-lane span). */
   get lane() {
     return this._deps.lane;
@@ -2714,6 +2754,9 @@ var DrainController = class {
     const leaseMillis = d.leaseMillis ?? options.leaseMillis ?? 1e4;
     try {
       this._locked = true;
+      this._inflight = new Promise((done) => {
+        this._inflight_done = done;
+      });
       const lagging = Math.ceil(streamLimit * this._ratio);
       const leading = streamLimit - lagging;
       const cycle = await run_drain_cycle(
@@ -2755,6 +2798,9 @@ var DrainController = class {
       return EMPTY_DRAIN;
     } finally {
       this._locked = false;
+      this._inflight = void 0;
+      this._inflight_done?.();
+      this._inflight_done = void 0;
     }
   }
 };
@@ -3512,29 +3558,87 @@ var Act = class {
   /** True after the first `shutdown()` call. Guards idempotency. */
   _shutdown_promise;
   /**
-   * Per-instance teardown: remove lifecycle listeners, stop the
-   * correlation worker, cancel any pending settle cycle, and tear
-   * down the cross-process notify subscription.
+   * Per-instance teardown: stop scheduling new work, give drain cycles
+   * already in flight a bounded chance to finish, then remove lifecycle
+   * listeners and tear down the cross-process notify subscription.
+   *
+   * The order is deliberate (#1442). Scheduling stops first, so nothing new
+   * is claimed while teardown runs. Then in-flight cycles are awaited up to
+   * `graceMs`: a reaction handler parked on an `await` holds its stream's
+   * lease until it acks, so abandoning it costs the replacement worker up to
+   * `leaseMillis` of dead time on that stream and discards the round of work
+   * (which #1418 then redelivers). Listeners come off *after* that wait, not
+   * before, so an `acked` / `blocked` subscriber still observes the work
+   * that completed during the grace window.
    *
-   * Idempotent — repeated calls return the same promise. Registered
-   * automatically with the global `dispose()` registry at construction,
-   * so process-wide `dispose()()` covers it; test helpers (or operators
-   * that mint short-lived Acts) call it explicitly for prompt cleanup.
+   * The budget is a ceiling, not a delay — teardown continues the moment the
+   * last in-flight cycle finishes. When it is exhausted, teardown proceeds
+   * anyway: one stuck handler must not hang a deploy, which is the failure
+   * mode an unbounded wait would trade for.
+   *
+   * Idempotent — repeated calls return the same promise, and the first
+   * call's `graceMs` is the one that applies. Registered automatically with
+   * the global `dispose()` registry at construction, so process-wide
+   * `dispose()()` covers it; test helpers (or operators that mint
+   * short-lived Acts) call it explicitly for prompt cleanup.
+   *
+   * @param options - See {@link ShutdownOptions}. Defaults the grace budget
+   *   to the largest lane `leaseMillis` (capped at 30s).
    */
-  shutdown() {
+  shutdown(options) {
     if (!this._shutdown_promise) {
+      resolveShutdownConfig(options);
       this._shutdown_promise = (async () => {
-        this._emitter.removeAllListeners();
         this.stop_correlations();
         this.stop_settling();
         this._breaker.stop();
         for (const c of this._drain_controllers.values()) c.stop();
+        await this._await_inflight(options?.graceMs);
+        this._emitter.removeAllListeners();
         const disposer = await this._notify_disposer;
         if (disposer) await disposer();
       })();
     }
     return this._shutdown_promise;
   }
+  /**
+   * Wait for every in-flight drain cycle, or for the grace budget to elapse,
+   * whichever comes first. Cycle promises never reject (`drain()` contains
+   * its own errors), so this never throws.
+   *
+   * An omitted budget is derived from the lanes that actually have a cycle
+   * in flight: their `leaseMillis` is the operator's own statement of how
+   * long one of their handlers may hold a stream, which makes it the honest
+   * ceiling for how long teardown should wait for that handler. A parked
+   * lane that pinned no lease contributes `drain()`'s own fallback, and the
+   * whole thing is capped so a long-leased lane cannot hold a deploy open.
+   * Idle lanes do not count — nothing is running on them to wait for.
+   */
+  _derive_grace_ms(running) {
+    let max = 0;
+    for (const c of running)
+      max = Math.max(max, c.lease_millis ?? DEFAULT_SHUTDOWN_GRACE_MS);
+    return Math.min(max, MAX_SHUTDOWN_GRACE_MS);
+  }
+  async _await_inflight(grace_ms) {
+    const running = [...this._drain_controllers.values()].filter(
+      (c) => c.inflight !== void 0
+    );
+    if (running.length === 0) return;
+    const grace = grace_ms ?? this._derive_grace_ms(running);
+    if (grace <= 0) return;
+    const inflight = running.map((c) => c.inflight);
+    let timer;
+    const budget = new Promise((resolve) => {
+      timer = setTimeout(resolve, grace);
+      timer.unref();
+    });
+    try {
+      await Promise.race([Promise.all(inflight), budget]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   /**
    * Subscribe to {@link Store.notify} when both the store and the
    * registry support it. Returns the disposer (or `undefined` when no