@nanobpm/urban 0.77.2 → 0.77.3

package/dist/runtime/core/modules/scheduler.d.ts

@@ -4,6 +4,14 @@ export interface SchedulerDeps {
     clearTimer: (handle: unknown) => void;
     /** Current wall-clock time in ms since epoch. */
     now: () => number;
+    /** Optional shutdown signal. When it aborts, a pending {@link schedulerClock} `wait()` clears its
+     *  armed timer and rejects, so a handler parked on the (virtual) clock unwinds at teardown instead
+     *  of wedging whoever awaits it. Under the test kit this is the engine's shutdown signal: a worker
+     *  handler parked on `app.wait()` sits on a virtual timer that no `advanceTime` will fire during
+     *  `engine.close()`, so without this its promise never settles and `close()` hangs (the issue #446
+     *  follow-up — the virtual-timer sibling of the real-time use-after-free). Absent on the live
+     *  scheduler, where real timers always fire on wall-clock time, so `wait()` never rejects there. */
+    readonly signal?: AbortSignal;
 }
 /** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
 export declare const MAX_TIMER_DELAY_MS = 2147483647;

package/dist/runtime/core/modules/scheduler.js

@@ -3,6 +3,13 @@
 // worker handlers. Keeping one definition here — rather than a copy per module — means a
 // test's fake scheduler drives them all the same way, and the "clamp a far-future delay to
 // setTimeout's 32-bit range" rule has a single home.
+/** The rejection surfaced to a `wait()` cancelled by a shutdown {@link SchedulerDeps.signal}: the
+ *  signal's `reason` when it is an {@link Error}, else a generic teardown error. Reusing the reason
+ *  keeps a caller's fail-loud message (e.g. "WasmEngineClient closing") intact. */
+function schedulerAbortError(signal) {
+    const reason = signal.reason;
+    return reason instanceof Error ? reason : new Error("app.wait aborted: scheduler shutting down");
+}
 /** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
 export const MAX_TIMER_DELAY_MS = 2_147_483_647;
 function isTimerHandle(handle) {
@@ -32,9 +39,48 @@ export function defaultScheduler() {
 export function schedulerClock(sched) {
     return {
         now: () => sched.now(),
-        wait: (ms) => new Promise((resolve) => {
+        wait: (ms) => new Promise((resolve, reject) => {
+            const signal = sched.signal;
+            // Already shutting down: reject immediately rather than arm a timer that would outlive the
+            // teardown (and, under the virtual clock, never fire).
+            if (signal?.aborted) {
+                reject(schedulerAbortError(signal));
+                return;
+            }
             const delay = Number.isFinite(ms) && ms > 0 ? Math.min(ms, MAX_TIMER_DELAY_MS) : 0;
-            sched.setTimer(() => resolve(), delay);
+            let settled = false;
+            let onAbort;
+            const handle = sched.setTimer(() => {
+                settled = true;
+                if (onAbort && signal)
+                    signal.removeEventListener("abort", onAbort);
+                resolve();
+            }, delay);
+            // When a shutdown signal is present, a mid-wait abort disarms the timer and rejects, so a
+            // handler parked here unwinds at teardown instead of wedging its awaiter. Inert (no listener,
+            // no behaviour change) on the live scheduler, which supplies no signal.
+            //
+            // `settled` guards the synchronous-timer case: this seam permits `setTimer` to invoke its
+            // callback synchronously (the test `capturingScheduler` does exactly that), which resolves
+            // the wait *before* we get here. Installing an abort listener on that already-settled promise
+            // would leak its closure until the signal fires (and have shutdown clear an already-fired
+            // handle), so skip it entirely when the callback already ran.
+            if (signal && !settled) {
+                onAbort = () => {
+                    sched.clearTimer(handle);
+                    reject(schedulerAbortError(signal));
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+                // Re-entrant seam: `setTimer` above is injectable and may abort `signal` *synchronously*
+                // without firing the timer callback (so `settled` is still false). An abort event is not
+                // replayed to a listener added after the fact, so the listener just registered would never
+                // run and the wait would hang until the runner timeout. Re-check and drive the abort path
+                // by hand — removing the (now-inert) listener first so it cannot also fire and double-reject.
+                if (signal.aborted && !settled) {
+                    signal.removeEventListener("abort", onAbort);
+                    onAbort();
+                }
+            }
         }),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.77.2",
+	"version": "0.77.3",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/runtime/core/modules/scheduler.test.ts

@@ -42,3 +42,108 @@ test("schedulerClock.wait clamps non-positive / non-finite delays to the current
   await schedulerClock(sched).wait(Number.POSITIVE_INFINITY);
   assert.deepEqual(sched.delays, [0, 0, 0]);
 });
+
+// Regression (issue #446 follow-up): a handler parked on `app.wait()` sits on a (virtual) timer that
+// no clock advance fires during teardown, so whoever awaits it — the test kit's `engine.close()` —
+// hangs forever. `schedulerClock().wait()` now honours an optional shutdown `signal`: a mid-wait
+// abort disarms the armed timer and rejects, so the parked handler unwinds at teardown. The live
+// scheduler supplies no signal, so this is wholly inert in production.
+test("schedulerClock.wait disarms its timer and rejects when the shutdown signal aborts mid-wait", async () => {
+  const controller = new AbortController();
+  const cleared: unknown[] = [];
+  let armed: (() => void) | undefined;
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: (fn) => {
+      armed = fn;
+      return 42;
+    },
+    clearTimer: (h) => cleared.push(h),
+  };
+  const waiting = schedulerClock(sched).wait(10_000);
+  assert.equal(typeof armed, "function", "wait must arm a timer while not aborted");
+  controller.abort(new Error("engine shutting down"));
+  await assert.rejects(waiting, /engine shutting down/, "an aborted wait must reject with the signal's reason");
+  assert.deepEqual(cleared, [42], "the armed timer must be cleared on abort so it cannot fire later");
+});
+
+test("schedulerClock.wait rejects immediately (arming no timer) when the signal is already aborted", async () => {
+  const controller = new AbortController();
+  controller.abort(new Error("already shutting down"));
+  let armedCount = 0;
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: () => {
+      armedCount += 1;
+      return 0;
+    },
+    clearTimer: () => {},
+  };
+  await assert.rejects(schedulerClock(sched).wait(1000), /already shutting down/);
+  assert.equal(armedCount, 0, "an already-aborted signal must reject without arming a timer");
+});
+
+// Regression (PR #447 review, scheduler.ts): this seam permits `setTimer` to fire its callback
+// SYNCHRONOUSLY (the `capturingScheduler` above does). When it does — and a shutdown `signal` is
+// present — the wait resolves before we would install the abort listener, so we must NOT install
+// one: attaching a listener to an already-settled promise leaks its closure until the signal fires
+// and later has shutdown clear an already-fired timer handle. A synchronously-resolved wait must
+// leave zero listeners on the signal and must not clear its (already-fired) handle on a later abort.
+test("schedulerClock.wait installs no abort listener when a signalled wait resolves synchronously", async () => {
+  const controller = new AbortController();
+  const cleared: unknown[] = [];
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: (fn) => {
+      fn(); // fire synchronously — the wait resolves before any listener could be installed
+      return 7;
+    },
+    clearTimer: (h) => cleared.push(h),
+  };
+  await schedulerClock(sched).wait(0);
+  // A leaked listener would fire here and clear the stale handle; the fix installs none.
+  controller.abort(new Error("shutting down"));
+  assert.deepEqual(cleared, [], "a synchronously-resolved wait must not install an abort listener");
+});
+// The abort reason is attacker/caller-controlled: guard the case where it is a bare value rather
+// than an Error so `wait()` still rejects with a generic teardown error instead of leaking it.
+test("schedulerClock.wait rejects with a generic teardown error when the abort reason is not an Error", async () => {
+  const controller = new AbortController();
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: () => 0,
+    clearTimer: () => {},
+  };
+  const waiting = schedulerClock(sched).wait(1000);
+  controller.abort("not-an-error");
+  await assert.rejects(waiting, /scheduler shutting down/);
+});
+
+// Regression (PR #447 review, scheduler.ts:108): `setTimer` is an injectable seam that may abort the
+// shutdown `signal` SYNCHRONOUSLY while arming, WITHOUT firing its callback (a re-entrant scheduler).
+// An abort event is not replayed to a listener added after the fact, so a wait that merely installed
+// its listener would hang forever — never rejecting, never clearing the armed timer. `wait()` must
+// re-check `signal.aborted` after installing the listener and drive the abort path by hand.
+test("schedulerClock.wait rejects (and clears its timer) when setTimer aborts the signal synchronously", async () => {
+  const controller = new AbortController();
+  const cleared: unknown[] = [];
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: () => {
+      controller.abort(new Error("aborted during setTimer"));
+      return 99;
+    },
+    clearTimer: (h) => cleared.push(h),
+  };
+  await assert.rejects(
+    schedulerClock(sched).wait(1000),
+    /aborted during setTimer/,
+    "a synchronous mid-arm abort must reject the wait, not leave it hanging",
+  );
+  assert.deepEqual(cleared, [99], "the armed timer must be cleared when the synchronous abort is handled");
+});

package/src/runtime/core/modules/scheduler.ts

@@ -10,6 +10,22 @@ export interface SchedulerDeps {
   clearTimer: (handle: unknown) => void;
   /** Current wall-clock time in ms since epoch. */
   now: () => number;
+  /** Optional shutdown signal. When it aborts, a pending {@link schedulerClock} `wait()` clears its
+   *  armed timer and rejects, so a handler parked on the (virtual) clock unwinds at teardown instead
+   *  of wedging whoever awaits it. Under the test kit this is the engine's shutdown signal: a worker
+   *  handler parked on `app.wait()` sits on a virtual timer that no `advanceTime` will fire during
+   *  `engine.close()`, so without this its promise never settles and `close()` hangs (the issue #446
+   *  follow-up — the virtual-timer sibling of the real-time use-after-free). Absent on the live
+   *  scheduler, where real timers always fire on wall-clock time, so `wait()` never rejects there. */
+  readonly signal?: AbortSignal;
+}
+
+/** The rejection surfaced to a `wait()` cancelled by a shutdown {@link SchedulerDeps.signal}: the
+ *  signal's `reason` when it is an {@link Error}, else a generic teardown error. Reusing the reason
+ *  keeps a caller's fail-loud message (e.g. "WasmEngineClient closing") intact. */
+function schedulerAbortError(signal: AbortSignal): Error {
+  const reason: unknown = signal.reason;
+  return reason instanceof Error ? reason : new Error("app.wait aborted: scheduler shutting down");
 }
 
 /** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
@@ -58,9 +74,47 @@ export function schedulerClock(sched: SchedulerDeps): AppClock {
   return {
     now: () => sched.now(),
     wait: (ms) =>
-      new Promise<void>((resolve) => {
+      new Promise<void>((resolve, reject) => {
+        const signal = sched.signal;
+        // Already shutting down: reject immediately rather than arm a timer that would outlive the
+        // teardown (and, under the virtual clock, never fire).
+        if (signal?.aborted) {
+          reject(schedulerAbortError(signal));
+          return;
+        }
         const delay = Number.isFinite(ms) && ms > 0 ? Math.min(ms, MAX_TIMER_DELAY_MS) : 0;
-        sched.setTimer(() => resolve(), delay);
+        let settled = false;
+        let onAbort: (() => void) | undefined;
+        const handle = sched.setTimer(() => {
+          settled = true;
+          if (onAbort && signal) signal.removeEventListener("abort", onAbort);
+          resolve();
+        }, delay);
+        // When a shutdown signal is present, a mid-wait abort disarms the timer and rejects, so a
+        // handler parked here unwinds at teardown instead of wedging its awaiter. Inert (no listener,
+        // no behaviour change) on the live scheduler, which supplies no signal.
+        //
+        // `settled` guards the synchronous-timer case: this seam permits `setTimer` to invoke its
+        // callback synchronously (the test `capturingScheduler` does exactly that), which resolves
+        // the wait *before* we get here. Installing an abort listener on that already-settled promise
+        // would leak its closure until the signal fires (and have shutdown clear an already-fired
+        // handle), so skip it entirely when the callback already ran.
+        if (signal && !settled) {
+          onAbort = () => {
+            sched.clearTimer(handle);
+            reject(schedulerAbortError(signal));
+          };
+          signal.addEventListener("abort", onAbort, { once: true });
+          // Re-entrant seam: `setTimer` above is injectable and may abort `signal` *synchronously*
+          // without firing the timer callback (so `settled` is still false). An abort event is not
+          // replayed to a listener added after the fact, so the listener just registered would never
+          // run and the wait would hang until the runner timeout. Re-check and drive the abort path
+          // by hand — removing the (now-inert) listener first so it cannot also fire and double-reject.
+          if (signal.aborted && !settled) {
+            signal.removeEventListener("abort", onAbort);
+            onAbort();
+          }
+        }
       }),
   };
 }