@kensio/yulin 1.21.20 → 1.21.21

package/dist/service/lambda/function/invoke/sim-lambda-invocation-deadline.d.ts

@@ -14,6 +14,10 @@ interface SimLambdaInvocationDeadlineProperties {
  * waits for a handler that has been timed out, and what it goes on to do
  * reaches nobody, which is the closest an in-process simulation gets to an
  * execution environment being taken away.
+ *
+ * Simulated time standing still holds the handler's timers and the deadline
+ * alike. A stall watch on host time ends an invocation neither of them can
+ * reach, with an error saying why.
  */
 export declare class SimLambdaInvocationDeadline {
     #private;

package/dist/service/lambda/function/invoke/sim-lambda-invocation-deadline.js

@@ -1,6 +1,8 @@
 import { SimLambdaClockTimer } from "./timer/sim-lambda-clock-timer.js";
 import { SimLambdaInvocationTimers } from "./timer/sim-lambda-invocation-timers.js";
 import { simLambdaProcessTimers } from "./timer/sim-lambda-process-timers.js";
+import { SimLambdaStallWatch } from "./sim-lambda-stall-watch.js";
+import { simLambdaStalledError } from "./sim-lambda-stalled.error.js";
 import { simLambdaTimedOutError } from "./sim-lambda-timed-out.error.js";
 const millisecondsPerSecond = 1000;
 /**
@@ -13,6 +15,10 @@ const millisecondsPerSecond = 1000;
  * waits for a handler that has been timed out, and what it goes on to do
  * reaches nobody, which is the closest an in-process simulation gets to an
  * execution environment being taken away.
+ *
+ * Simulated time standing still holds the handler's timers and the deadline
+ * alike. A stall watch on host time ends an invocation neither of them can
+ * reach, with an error saying why.
  */
 export class SimLambdaInvocationDeadline {
     #properties;
@@ -40,6 +46,7 @@ export class SimLambdaInvocationDeadline {
         const ending = () => {
             timers.cancelAll();
             deadline.cancel();
+            stall.cancel();
         };
         const failing = (error) => {
             ending();
@@ -59,7 +66,21 @@ export class SimLambdaInvocationDeadline {
                 }));
             },
         });
+        const stall = new SimLambdaStallWatch({
+            background,
+            timeoutSeconds,
+            waitingOn: () => timers.pending(),
+            stalled: (waitingOn, waitedMilliseconds) => {
+                failing(simLambdaStalledError({
+                    awsRequestId,
+                    at: background.now(),
+                    waitingOn,
+                    waitedMilliseconds,
+                }));
+            },
+        });
         deadline.startAt(new Date(background.now().getTime() + timeoutSeconds * millisecondsPerSecond));
+        stall.start();
         try {
             return await background.outstanding(async () => await racing(timers, stopped, handler, ending));
         }

package/dist/service/lambda/function/invoke/sim-lambda-stall-watch.d.ts

@@ -0,0 +1,38 @@
+import type { BackgroundScheduler } from "../../../../util/background/background.js";
+import type { SimLambdaPendingTimer } from "./timer/sim-lambda-pending-timer.js";
+interface SimLambdaStallWatchProperties {
+    readonly background: BackgroundScheduler;
+    /** The seconds the invocation has to answer in, on the simulated clock. */
+    readonly timeoutSeconds: number;
+    /** The timer the invocation is waiting on, where it is waiting on one. */
+    readonly waitingOn: () => SimLambdaPendingTimer | undefined;
+    /** What happens once the invocation turns out to have no way to finish. */
+    readonly stalled: (waitingOn: SimLambdaPendingTimer, waitedMilliseconds: number) => void;
+}
+/**
+ * A watch on host time for an invocation the simulated clock has left behind.
+ *
+ * A handler's timers wait on the simulation's clock, and so does the
+ * invocation's deadline. Simulated time standing still holds both, and the
+ * invocation runs on until the test framework gives up on the test around it.
+ * Elapsed host time is the only thing separating that from a test meaning to
+ * start an invocation, advance the clock and then wait for it, which is why
+ * host time is what this watches.
+ *
+ * A turn that finds simulated time has moved starts the wait again, so a test
+ * advancing the clock in steps is left alone. The host timer is unreferenced,
+ * and an invocation nobody is driving never holds the process open.
+ */
+export declare class SimLambdaStallWatch {
+    #private;
+    constructor(properties: SimLambdaStallWatchProperties);
+    /**
+     * Start watching, from the instant the clock reads now.
+     */
+    start(): void;
+    /**
+     * Give up watching, as an invocation that has ended does.
+     */
+    cancel(): void;
+}
+export {};

package/dist/service/lambda/function/invoke/sim-lambda-stall-watch.js

@@ -0,0 +1,78 @@
+import { clearTimeout, setTimeout } from "node:timers";
+const millisecondsPerSecond = 1000;
+/** The least host time a stopped clock gets before an invocation is stalled. */
+const shortestWatchMilliseconds = 1000;
+/** The most host time a stopped clock gets, whatever the function's timeout. */
+const longestWatchMilliseconds = 2000;
+/**
+ * A watch on host time for an invocation the simulated clock has left behind.
+ *
+ * A handler's timers wait on the simulation's clock, and so does the
+ * invocation's deadline. Simulated time standing still holds both, and the
+ * invocation runs on until the test framework gives up on the test around it.
+ * Elapsed host time is the only thing separating that from a test meaning to
+ * start an invocation, advance the clock and then wait for it, which is why
+ * host time is what this watches.
+ *
+ * A turn that finds simulated time has moved starts the wait again, so a test
+ * advancing the clock in steps is left alone. The host timer is unreferenced,
+ * and an invocation nobody is driving never holds the process open.
+ */
+export class SimLambdaStallWatch {
+    #properties;
+    #delay;
+    #seenAt = 0;
+    #hostTimer;
+    constructor(properties) {
+        this.#properties = properties;
+        this.#delay = simLambdaStallWatchDelay(properties.timeoutSeconds);
+    }
+    /**
+     * Start watching, from the instant the clock reads now.
+     */
+    start() {
+        this.#seenAt = this.#properties.background.now().getTime();
+        this.#arm();
+    }
+    /**
+     * Give up watching, as an invocation that has ended does.
+     */
+    cancel() {
+        clearTimeout(this.#hostTimer);
+        this.#hostTimer = undefined;
+    }
+    #arm() {
+        this.#hostTimer = setTimeout(() => {
+            this.#hostTimer = undefined;
+            this.#check();
+        }, this.#delay);
+        this.#hostTimer.unref();
+    }
+    /**
+     * See whether the invocation still has a way to finish, and watch on where
+     * it has: either simulated time has moved since the last turn, or the
+     * handler is busy with something other than a timer.
+     */
+    #check() {
+        const now = this.#properties.background.now().getTime();
+        const waitingOn = this.#properties.waitingOn();
+        if (waitingOn === undefined || now !== this.#seenAt) {
+            this.#seenAt = now;
+            this.#arm();
+            return;
+        }
+        this.#properties.stalled(waitingOn, this.#delay);
+    }
+}
+/**
+ * How long the host waits before it calls an invocation stalled.
+ *
+ * The function's own timeout is the bound that fits, since an invocation the
+ * deadline would have ended already has nothing left to wait for. It is held
+ * between one and two seconds. Below that a loaded host could fail a test that
+ * was about to advance the clock, and above it a test framework's own timeout
+ * arrives first and takes the diagnostic with it.
+ */
+function simLambdaStallWatchDelay(timeoutSeconds) {
+    return Math.min(Math.max(timeoutSeconds * millisecondsPerSecond, shortestWatchMilliseconds), longestWatchMilliseconds);
+}

package/dist/service/lambda/function/invoke/sim-lambda-stalled.error.d.ts

@@ -0,0 +1,23 @@
+import { SimLambdaRuntimeError } from "../../error/sim-lambda-runtime.error.js";
+import type { SimLambdaPendingTimer } from "./timer/sim-lambda-pending-timer.js";
+interface SimLambdaStalledProperties {
+    readonly awsRequestId: string;
+    /** The simulated instant the clock has stopped at. */
+    readonly at: Date;
+    /** The timer the invocation is waiting on. */
+    readonly waitingOn: SimLambdaPendingTimer;
+    /** How long the host has watched simulated time stand still. */
+    readonly waitedMilliseconds: number;
+}
+/**
+ * The error an invocation gets when nothing is left that could end it.
+ *
+ * A handler's timers wait on the simulation's clock, and so does the
+ * invocation's own deadline. Simulated time standing still holds both, and the
+ * invocation would otherwise run until the test framework gave up on the test
+ * around it, reporting the test rather than the timer. This names the timer
+ * the handler is waiting on, the instant it is due at, and what to do about
+ * it.
+ */
+export declare function simLambdaStalledError(properties: SimLambdaStalledProperties): SimLambdaRuntimeError;
+export {};

package/dist/service/lambda/function/invoke/sim-lambda-stalled.error.js

@@ -0,0 +1,22 @@
+import { SimLambdaRuntimeError } from "../../error/sim-lambda-runtime.error.js";
+/** What Yulin calls an invocation the clock is never going to release. */
+const stalledErrorType = "Yulin.StalledInvocation";
+/**
+ * The error an invocation gets when nothing is left that could end it.
+ *
+ * A handler's timers wait on the simulation's clock, and so does the
+ * invocation's own deadline. Simulated time standing still holds both, and the
+ * invocation would otherwise run until the test framework gave up on the test
+ * around it, reporting the test rather than the timer. This names the timer
+ * the handler is waiting on, the instant it is due at, and what to do about
+ * it.
+ */
+export function simLambdaStalledError(properties) {
+    const { awsRequestId, at, waitingOn, waitedMilliseconds } = properties;
+    const error = new SimLambdaRuntimeError(stalledErrorType, `${at.toISOString()} ${awsRequestId} Task is waiting on a ${waitingOn.delay} ms timer due at ${waitingOn.dueTime.toISOString()}. Simulated time has stood still for ${waitedMilliseconds} ms of host time, leaving both that timer and the invocation deadline out of reach. Advance the simulation's clock past the timer delay to release it.`);
+    // Nothing in the handler threw, so its frames say nothing about why the
+    // invocation is stuck, and the simulator's own frames say less. The timeout
+    // this stands in for is reported without a stack too.
+    error.stack = `${error.name}: ${error.message}`;
+    return error;
+}

package/dist/service/lambda/function/invoke/timer/sim-lambda-clock-timer.d.ts

@@ -21,6 +21,10 @@ interface SimLambdaClockTimerProperties {
 export declare class SimLambdaClockTimer {
     #private;
     constructor(properties: SimLambdaClockTimerProperties);
+    /** The delay this timer was last started with, in milliseconds. */
+    get delay(): number;
+    /** The simulated instant this timer's work is due to run at. */
+    get dueTime(): Date;
     /**
      * Wait a delay of simulated time, and answer with how long that turned out
      * to be. A delay of nothing leaves the timer due where the clock already

package/dist/service/lambda/function/invoke/timer/sim-lambda-clock-timer.js

@@ -31,6 +31,14 @@ export class SimLambdaClockTimer {
         this.#run = properties.run;
         this.#dueTime = properties.background.now();
     }
+    /** The delay this timer was last started with, in milliseconds. */
+    get delay() {
+        return this.#delay;
+    }
+    /** The simulated instant this timer's work is due to run at. */
+    get dueTime() {
+        return new Date(this.#dueTime);
+    }
     /**
      * Wait a delay of simulated time, and answer with how long that turned out
      * to be. A delay of nothing leaves the timer due where the clock already

package/dist/service/lambda/function/invoke/timer/sim-lambda-invocation-timers.d.ts

@@ -1,4 +1,5 @@
 import type { BackgroundScheduler } from "../../../../../util/background/background.js";
+import type { SimLambdaPendingTimer } from "./sim-lambda-pending-timer.js";
 import { type SimLambdaTimerCallback, SimLambdaTimerHandle, type SimLambdaTimerOwner, type SimLambdaTimers } from "./sim-lambda-timer-handle.js";
 interface SimLambdaInvocationTimersProperties {
     readonly background: BackgroundScheduler;
@@ -31,6 +32,15 @@ export declare class SimLambdaInvocationTimers implements SimLambdaTimers, SimLa
      * Run a callback every time simulated time moves on by a delay.
      */
     setInterval(callback: SimLambdaTimerCallback, delay?: number, ...arguments_: unknown[]): SimLambdaTimerHandle;
+    /**
+     * The timer this invocation is waiting on, the earliest due one where it
+     * has several.
+     *
+     * A timer due at the instant the clock already reads is waiting for nothing:
+     * the next turn of the host event loop runs it. Only a timer the clock has
+     * yet to reach counts.
+     */
+    pending(): SimLambdaPendingTimer | undefined;
     /**
      * Give up one timer, as `clearTimeout` and `clearInterval` do.
      */

package/dist/service/lambda/function/invoke/timer/sim-lambda-invocation-timers.js

@@ -42,6 +42,27 @@ export class SimLambdaInvocationTimers {
             this.#call(callback, arguments_);
         });
     }
+    /**
+     * The timer this invocation is waiting on, the earliest due one where it
+     * has several.
+     *
+     * A timer due at the instant the clock already reads is waiting for nothing:
+     * the next turn of the host event loop runs it. Only a timer the clock has
+     * yet to reach counts.
+     */
+    pending() {
+        const now = this.#background.now().getTime();
+        let earliest;
+        for (const timer of this.#running.values()) {
+            if (timer.dueTime.getTime() > now && isEarlier(timer, earliest)) {
+                earliest = timer;
+            }
+        }
+        if (earliest === undefined) {
+            return undefined;
+        }
+        return { delay: earliest.delay, dueTime: earliest.dueTime };
+    }
     /**
      * Give up one timer, as `clearTimeout` and `clearInterval` do.
      */
@@ -110,3 +131,10 @@ export class SimLambdaInvocationTimers {
         this.#released = undefined;
     }
 }
+/**
+ * Whether a timer comes due before the earliest one found so far. The first
+ * timer looked at has nothing to beat.
+ */
+function isEarlier(timer, earliest) {
+    return earliest === undefined || timer.dueTime < earliest.dueTime;
+}

package/dist/service/lambda/function/invoke/timer/sim-lambda-pending-timer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A timer one invocation is waiting on, and the instant it comes due.
+ */
+export interface SimLambdaPendingTimer {
+    /** The delay the code under test asked for, in milliseconds. */
+    readonly delay: number;
+    /** The simulated instant the timer's work runs at. */
+    readonly dueTime: Date;
+}

package/dist/service/lambda/function/invoke/timer/sim-lambda-pending-timer.js

@@ -0,0 +1 @@
+export {};

package/docs/time/README.md

@@ -197,6 +197,12 @@ simulation's clock during an invocation. Start an invocation without awaiting it
 clock past the timer delay, then await the invocation. Lambda's configured timeout and
 `context.getRemainingTimeInMillis()` use the same clock.
 
+An invocation left waiting on one of those timers while simulated time stands still has nothing to
+end it, because the function's own timeout waits on the same clock. Yulin fails it after a second or
+two of real time with a `Yulin.StalledInvocation` error naming the timer and its delay. Advancing
+the clock resets that wait, in one step or several, so the pattern above keeps working. A handler
+busy with something other than a timer is left alone for as long as it takes.
+
 ### Where real AWS gets the time
 
 Real Lambda has no current-time API. A production handler gets the current time from the machine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.21.20",
+  "version": "1.21.21",
   "description": "AWS system behaviour simulation for isolated unit testing",
   "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",