feat: Add hard timeout functionality to Container class

- Adds hardTimeout configuration option with duration parsing
- Implements hard timeout timer that starts on container initialization
- Hard timeout never resets (unlike soft timeout which resets on activity)
- Provides onHardTimeoutExpired() hook for custom cleanup logic
- Hard timeout takes precedence over soft timeout when both expire
- Comprehensive test coverage including timeout interactions
- Improved Jest configuration for Cloudflare Workers environment

Author: Talador12

jest.config.js

@@ -6,6 +6,10 @@ module.exports = {
   transform: {
     '^.+\\.ts$': ['ts-jest', { tsconfig: 'tsconfig.json' }]
   },
+  moduleNameMapper: {
+    '^cloudflare:workers$': '<rootDir>/src/tests/__mocks__/cloudflare-workers.js'
+  },
+  setupFilesAfterEnv: ['<rootDir>/src/tests/setup.ts'],
   collectCoverage: true,
   coverageDirectory: 'coverage',
   coverageReporters: ['text', 'lcov'],

package-lock.json

@@ -227,6 +227,11 @@ export class Container<Env = unknown> extends DurableObject<Env> {
   // The container won't get a SIGKILL if this threshold is triggered.
   sleepAfter: string | number = DEFAULT_SLEEP_AFTER;
 
+  // Timeout after which the container will be forcefully killed
+  // This timeout is absolute from container start time, regardless of activity
+  // When this timeout expires, the container is sent a SIGKILL signal
+  timeout?: string | number;
+
   // Container configuration properties
   // Set these properties directly in your container instance
   envVars: ContainerStartOptions['env'] = {};
@@ -261,6 +266,7 @@ export class Container<Env = unknown> extends DurableObject<Env> {
     if (options) {
       if (options.defaultPort !== undefined) this.defaultPort = options.defaultPort;
       if (options.sleepAfter !== undefined) this.sleepAfter = options.sleepAfter;
+      if (options.timeout !== undefined) this.timeout = options.timeout;
     }
 
     // Create schedules table if it doesn't exist
@@ -577,6 +583,23 @@ export class Container<Env = unknown> extends DurableObject<Env> {
     await this.stop();
   }
 
+  /**
+   * Called when the timeout expires and the container needs to be forcefully killed.
+   * This is a timeout that is absolute from container start time, regardless of activity.
+   * When this timeout expires, the container will be forcefully killed with SIGKILL.
+   * 
+   * Override this method in subclasses to handle timeout events.
+   * By default, this method calls `this.destroy()` to forcefully kill the container.
+   */
+  public async onHardTimeoutExpired(): Promise<void> {
+    if (!this.container.running) {
+      return;
+    }
+
+    console.log(`Container timeout expired after ${this.timeout}. Forcefully killing container.`);
+    await this.destroy();
+  }
+
   /**
    * Error handler for container errors
    * Override this method in subclasses to handle container errors
@@ -598,6 +621,18 @@ export class Container<Env = unknown> extends DurableObject<Env> {
     this.sleepAfterMs = Date.now() + timeoutInMs;
   }
 
+  /**
+   * Set up the timeout when the container starts
+   * This is called internally when the container starts
+   */
+  private setupTimeout() {
+    if (this.timeout) {
+      const timeoutMs = parseTimeExpression(this.timeout) * 1000;
+      this.containerStartTime = Date.now();
+      this.timeoutMs = this.containerStartTime + timeoutMs;
+    }
+  }
+
   // ==================
   //     SCHEDULING
   // ==================
@@ -798,6 +833,8 @@ export class Container<Env = unknown> extends DurableObject<Env> {
   private monitorSetup = false;
 
   private sleepAfterMs = 0;
+  private timeoutMs?: number;
+  private containerStartTime?: number;
 
   // ==========================
   //     GENERAL HELPERS
@@ -946,6 +983,9 @@ export class Container<Env = unknown> extends DurableObject<Env> {
         await this.scheduleNextAlarm();
         this.container.start(startConfig);
         this.monitor = this.container.monitor();
+        
+        // Set up timeout when container starts
+        this.setupTimeout();
       } else {
         await this.scheduleNextAlarm();
       }
@@ -1147,15 +1187,24 @@ export class Container<Env = unknown> extends DurableObject<Env> {
       return;
     }
 
+    // Check timeout first (takes priority over activity timeout)
+    if (this.isTimeoutExpired()) {
+      await this.onHardTimeoutExpired();
+      return;
+    }
+
     if (this.isActivityExpired()) {
       await this.onActivityExpired();
       // renewActivityTimeout makes sure we don't spam calls here
       this.renewActivityTimeout();
       return;
     }
 
-    // Math.min(3m or maxTime, sleepTimeout)
+    // Math.min(3m or maxTime, sleepTimeout, timeout)
     minTime = Math.min(minTimeFromSchedules, minTime, this.sleepAfterMs);
+    if (this.timeoutMs) {
+      minTime = Math.min(minTime, this.timeoutMs);
+    }
     const timeout = Math.max(0, minTime - Date.now());
 
     // await a sleep for maxTime to keep the DO alive for
@@ -1167,7 +1216,7 @@ export class Container<Env = unknown> extends DurableObject<Env> {
         return;
       }
 
-      this.timeout = setTimeout(() => {
+      this.timeoutId = setTimeout(() => {
         resolve();
       }, timeout);
     });
@@ -1178,7 +1227,7 @@ export class Container<Env = unknown> extends DurableObject<Env> {
     // the next alarm is the one that decides if it should stop the loop.
   }
 
-  timeout?: ReturnType<typeof setTimeout>;
+  timeoutId?: ReturnType<typeof setTimeout>;
   resolve?: () => void;
 
   // synchronises container state with the container source of truth to process events
@@ -1292,4 +1341,8 @@ export class Container<Env = unknown> extends DurableObject<Env> {
   private isActivityExpired(): boolean {
     return this.sleepAfterMs <= Date.now();
   }
+
+  private isTimeoutExpired(): boolean {
+    return this.timeoutMs !== undefined && this.timeoutMs <= Date.now();
+  }
 }

src/lib/container.ts

@@ -0,0 +1,26 @@
+// Mock for cloudflare:workers module
+const DurableObject = class MockDurableObject {
+  constructor(ctx, env) {
+    this.ctx = ctx;
+    this.env = env;
+  }
+  
+  fetch() {
+    return new Response('Mock response');
+  }
+  
+  async alarm() {
+    // Mock alarm implementation
+  }
+};
+
+// Mock ExecutionContext
+const ExecutionContext = class MockExecutionContext {
+  waitUntil() {}
+  passThroughOnException() {}
+};
+
+module.exports = {
+  DurableObject,
+  ExecutionContext
+};