@cloudflare/containers 0.0.18 → 0.0.20

package/README.md

@@ -63,11 +63,10 @@ The main class that extends a container-enbled Durable Object to provide additio
 - `defaultPort?`: Optional default port to use when communicating with the container. If not set, you must specify port in containerFetch calls
 - `requiredPorts?`: Array of ports that should be checked for availability during container startup. Used by startAndWaitForPorts when no specific ports are provided.
 - `sleepAfter`: How long to keep the container alive without activity (format: number for seconds, or string like "5m", "30s", "1h")
-- `manualStart`: If true, container won't start automatically on DO start (default: false). Set as a class property or via constructor options.
 - `env`: Environment variables to pass to the container (Record<string, string>)
 - `entrypoint?`: Custom entrypoint to override container default (string[])
 - `enableInternet`: Whether to enable internet access for the container (boolean, default: true)
-- Lifecycle methods: `onStart`, `onStop`, `onError`
+- Lifecycle methods: `onStart`, `onStop`, `onError`, `onActivityExpired`
 
 #### Constructor Options
 
@@ -75,8 +74,6 @@ The main class that extends a container-enbled Durable Object to provide additio
 constructor(ctx: any, env: Env, options?: {
   defaultPort?: number;           // Override default port
   sleepAfter?: string | number;   // Override sleep timeout
-  manualStart?: boolean; // Disable automatic container start (preferred way)
-  explicitContainerStart?: boolean; // Legacy option, use manualStart instead
   env?: Record<string, string>;   // Environment variables to pass to the container
   entrypoint?: string[];          // Custom entrypoint to override container default
   enableInternet?: boolean;       // Whether to enable internet access for the container
@@ -86,23 +83,31 @@ constructor(ctx: any, env: Env, options?: {
 #### Methods
 
 ##### Lifecycle Methods
+All lifecycle methods can be implemented as async if needed.
 
 - `onStart()`: Called when container starts successfully - override to add custom behavior
 - `onStop()`: Called when container shuts down - override to add custom behavior
 - `onError(error)`: Called when container encounters an error - override to add custom behavior
+- `onActivityExpired()`: Called when the activity is expired - override to add custom behavior, like communicating with the container to see if it should be shutdown.
+
+By default, it calls `ctx.container.destroy()`.
+If you don't stop the container here, the activity tracker will be renewed, and this lifecycle hook will be called again when the timer re-expires.
 
 ##### Container Methods
 
 - `fetch(request)`: Default handler to forward HTTP requests to the container. Can be overridden.
-- `containerFetch(...)`: Sends an HTTP or WebSocket request to the container. Supports both standard fetch API signatures:
+- `containerFetch(...)`: Sends an HTTP request to the container. Supports both standard fetch API signatures:
   - `containerFetch(request, port?)`: Traditional signature with Request object
   - `containerFetch(url, init?, port?)`: Standard fetch-like signature with URL string/object and RequestInit options
-  Either port parameter or defaultPort must be specified. Automatically detects WebSocket upgrade requests.
+  Either port parameter or defaultPort must be specified.
+  When you call any of the fetch functions, the activity will be automatically renewed, and if the container will be started if not already running.
 - `start()`: Starts the container if it's not running and sets up monitoring, without waiting for any ports to be ready.
 - `startAndWaitForPorts(ports?, maxTries?)`: Starts the container using `start()` and then waits for specified ports to be ready. If no ports are specified, uses `requiredPorts` or `defaultPort`. If no ports can be determined, just starts the container without port checks.
-- `stop(reason?)`: Stops the container
+- `stop(signal = SIGTERM)`: Sends the specified signal to the container.
+- `destroy()`: Forcefully destroys the container.
 - `renewActivityTimeout()`: Manually renews the container activity timeout (extends container lifetime)
 - `stopDueToInactivity()`: Called automatically when the container times out due to inactivity
+- `alarm()`: Default alarm handler. It's in charge of renewing the container activity and keeping the durable object alive. You can override `alarm()`, but because its functionality is currently vital to managing the container lifecycle, we recommend calling `schedule` to schedule tasks instead.
 
 ### Utility Functions
 
@@ -131,6 +136,8 @@ export class MyContainer extends Container {
   // Lifecycle method called when container shuts down
   override onStop(): void {
     console.log('Container stopped!');
+    // you can also call startAndWaitForPorts() again
+    //   this.startAndWaitForPorts();
   }
 
   // Lifecycle method called on errors
@@ -139,6 +146,14 @@ export class MyContainer extends Container {
     throw error;
   }
 
+  // Lifecycle method when the container class considers the activity to be expired
+  override onActivityExpired() {
+    console.log(
+      'Container activity expired'
+    );
+    await this.destroy();
+  }
+
   // Custom method that will extend the container's lifetime
   async performBackgroundTask(): Promise<void> {
     // Do some work...
@@ -205,72 +220,6 @@ export class ConfiguredContainer extends Container {
 }
 ```
 
-### Manual Container Start Example
-
-For more control over container lifecycle, you can use the `explicitContainerStart` option to disable automatic container startup:
-
-```typescript
-import { Container } from '@cloudflare/containers';
-
-export class ManualStartContainer extends Container {
-  // Configure default port for the container
-  defaultPort = 8080;
-
-  // Specify multiple required ports that must be ready before the container is considered started
-  // if this is not specified, by default, you will wait only defaultPort
-  requiredPorts = [8080, 9090, 3000];
-
-  // Disable automatic container startup
-  manualStart = true;
-
-  constructor(ctx: any, env: any) {
-    // You can also set explicitContainerStart via constructor options
-    // super(ctx, env, {
-    //   explicitContainerStart: true
-    // });
-    super(ctx, env);
-  }
-
-  /**
-   * Handle incoming requests - start the container on demand
-   */
-  async fetch(request: Request): Promise<Response> {
-    const url = new URL(request.url);
-
-    // Start the container if it's not already running
-    if (!this.ctx.container.running) {
-      try {
-        // Handle different startup paths
-        if (url.pathname === '/start') {
-          // Just start the container without waiting for any ports
-          await this.start();
-          return new Response('Container started but ports not yet verified!');
-        }
-        else if (url.pathname === '/start-api') {
-          // Only wait for the API port (3000)
-          await this.startAndWaitForPorts(3000);
-          return new Response('API port is ready!');
-        }
-        else if (url.pathname === '/start-all') {
-          // Wait for all required ports (uses requiredPorts property)
-          await this.startAndWaitForPorts();
-          return new Response('All container ports are ready!');
-        }
-        else {
-          // For other paths, just wait for the default port
-          await this.startAndWaitForPorts(this.defaultPort);
-        }
-      } catch (error) {
-        return new Response(`Failed to start container: ${error}`, { status: 500 });
-      }
-    }
-
-    // For all other requests, forward to the container
-    return await this.containerFetch(request);
-  }
-}
-```
-
 ### Multiple Ports and Custom Routing
 
 You can create a container that doesn't use a default port and instead routes traffic to different ports based on request path or other factors:

package/dist/lib/container.d.ts

@@ -1,5 +1,7 @@
 import type { ContainerOptions, ContainerStartOptions, ContainerStartConfigOptions, Schedule, StopParams } from '../types';
 import { DurableObject } from 'cloudflare:workers';
+export type Signal = 'SIGKILL' | 'SIGINT' | 'SIGTERM';
+export type SignalInteger = number;
 export declare class Container<Env = unknown> extends DurableObject<Env> {
     defaultPort?: number;
     requiredPorts?: number[];
@@ -84,7 +86,7 @@ export declare class Container<Env = unknown> extends DurableObject<Env> {
      * Shuts down the container.
      * @param signal - The signal to send to the container (default: 15 for SIGTERM)
      */
-    stop(signal?: number): Promise<void>;
+    stop(signal?: Signal | SignalInteger): Promise<void>;
     /**
      * Destroys the container. It will trigger onError instead of onStop.
      */
@@ -100,6 +102,15 @@ export declare class Container<Env = unknown> extends DurableObject<Env> {
      * @param params - Object containing exitCode and reason for the stop
      */
     onStop(_: StopParams): void | Promise<void>;
+    /**
+     * Lifecycle method called when the container is running, and the activity timeout
+     * expiration has been reached.
+     *
+     * If you want to shutdown the container, you should call this.destroy() here
+     *
+     * By default, this method calls `this.destroy()`
+     */
+    onActivityExpired(): Promise<void>;
     /**
      * Error handler for container errors
      * Override this method in subclasses to handle container errors
@@ -153,7 +164,6 @@ export declare class Container<Env = unknown> extends DurableObject<Env> {
     private state;
     private monitor;
     private monitorSetup;
-    private openStreamCount;
     private sleepAfterMs;
     private blockConcurrencyThrowable;
     /**
@@ -163,6 +173,7 @@ export declare class Container<Env = unknown> extends DurableObject<Env> {
     private requestAndPortFromContainerFetchArgs;
     private startContainerIfNotRunning;
     private setupMonitorCallbacks;
+    deleteSchedules(name: string): void;
     /**
      * Method called when an alarm fires
      * Executes any scheduled tasks that are due
@@ -171,13 +182,16 @@ export declare class Container<Env = unknown> extends DurableObject<Env> {
         isRetry: boolean;
         retryCount: number;
     }): Promise<void>;
+    timeout?: ReturnType<typeof setTimeout>;
+    resolve?: () => void;
     private syncPendingStoppedEvents;
     private callOnStop;
     /**
      * Schedule the next alarm based on upcoming tasks
-     * @private
      */
-    private scheduleNextAlarm;
+    scheduleNextAlarm(ms?: number): Promise<void>;
+    listSchedules<T = string>(name: string): Promise<Schedule<T>[]>;
+    private toSchedule;
     /**
      * Get a scheduled task by ID
      * @template T Type of the payload data

package/dist/lib/container.js

@@ -7,14 +7,14 @@ import { DurableObject } from 'cloudflare:workers';
 // ====================
 const NO_CONTAINER_INSTANCE_ERROR = 'there is no container instance that can be provided to this durable object';
 const RUNTIME_SIGNALLED_ERROR = 'runtime signalled the container to exit:';
-const UNEXPECTED_EDIT_ERROR = 'container exited with unexpected exit code:';
+const UNEXPECTED_EXIT_ERROR = 'container exited with unexpected exit code:';
 const NOT_LISTENING_ERROR = 'the container is not listening';
 const CONTAINER_STATE_KEY = '__CF_CONTAINER_STATE';
 // maxRetries before scheduling next alarm is purposely set to 3,
 // as according to DO docs at https://developers.cloudflare.com/durable-objects/api/alarms/
 // the maximum amount for alarm retries is 6.
-const MAX_ALAEM_RETRIES = 3;
-const PING_TIMEOUT_MS = 1500;
+const MAX_ALARM_RETRIES = 3;
+const PING_TIMEOUT_MS = 5000;
 const DEFAULT_SLEEP_AFTER = '10m'; // Default sleep after inactivity time
 const INSTANCE_POLL_INTERVAL_MS = 300; // Default interval for polling container state
 // Timeout for getting container instance and launching a VM
@@ -34,6 +34,11 @@ const FALLBACK_PORT_TO_CHECK = 33;
 // Since the timing isn't working, hard coding a max attempts seems
 // to be the only viable solution for now
 const TEMPORARY_HARDCODED_ATTEMPT_MAX = 6;
+const signalToNumbers = {
+    SIGINT: 2,
+    SIGTERM: 15,
+    SIGKILL: 9,
+};
 // =====================
 // =====================
 //   HELPER FUNCTIONS
@@ -47,7 +52,7 @@ function isErrorOfType(e, matchingString) {
 const isNoInstanceError = (error) => isErrorOfType(error, NO_CONTAINER_INSTANCE_ERROR);
 const isRuntimeSignalledError = (error) => isErrorOfType(error, RUNTIME_SIGNALLED_ERROR);
 const isNotListeningError = (error) => isErrorOfType(error, NOT_LISTENING_ERROR);
-const isContainerExitNonZeroError = (error) => isErrorOfType(error, UNEXPECTED_EDIT_ERROR);
+const isContainerExitNonZeroError = (error) => isErrorOfType(error, UNEXPECTED_EXIT_ERROR);
 function getExitCodeFromError(error) {
     if (!(error instanceof Error)) {
         return null;
@@ -62,8 +67,8 @@ function getExitCodeFromError(error) {
     if (isContainerExitNonZeroError(error)) {
         return +error.message
             .toLowerCase()
-            .slice(error.message.toLowerCase().indexOf(UNEXPECTED_EDIT_ERROR) +
-            UNEXPECTED_EDIT_ERROR.length +
+            .slice(error.message.toLowerCase().indexOf(UNEXPECTED_EXIT_ERROR) +
+            UNEXPECTED_EXIT_ERROR.length +
             1);
     }
     return null;
@@ -85,31 +90,6 @@ function addTimeoutSignal(existingSignal, timeoutMs) {
     controller.signal.addEventListener('abort', () => clearTimeout(timeoutId));
     return controller.signal;
 }
-// ==== Stream helpers ====
-function attachOnClosedHook(stream, onClosed) {
-    let destructor = () => {
-        onClosed();
-        destructor = null;
-    };
-    // we pass the readableStream through a transform stream to detect if the
-    // body has been closed.
-    const transformStream = new TransformStream({
-        transform(chunk, controller) {
-            controller.enqueue(chunk);
-        },
-        flush() {
-            if (destructor) {
-                destructor();
-            }
-        },
-        cancel() {
-            if (destructor) {
-                destructor();
-            }
-        },
-    });
-    return stream.pipeThrough(transformStream);
-}
 // ===============================
 //     CONTAINER STATE WRAPPER
 // ===============================
@@ -385,7 +365,7 @@ export class Container extends DurableObject {
                         if (i === triesLeft - 1) {
                             try {
                                 // TODO: Remove attempts, the end user doesn't care about this
-                                this.onError(`Failed to verify port ${port} is available after ${options.retries} attempts, last error: ${errorMessage}`);
+                                await this.onError(`Failed to verify port ${port} is available after ${options.retries} attempts, last error: ${errorMessage}`);
                             }
                             catch { }
                             throw e;
@@ -419,8 +399,8 @@ export class Container extends DurableObject {
      * Shuts down the container.
      * @param signal - The signal to send to the container (default: 15 for SIGTERM)
      */
-    async stop(signal = 15) {
-        this.container.signal(signal);
+    async stop(signal = 'SIGTERM') {
+        this.container.signal(typeof signal === 'string' ? signalToNumbers[signal] : signal);
     }
     /**
      * Destroys the container. It will trigger onError instead of onStop.
@@ -443,6 +423,17 @@ export class Container extends DurableObject {
     onStop(_) {
         // Default implementation does nothing
     }
+    /**
+     * Lifecycle method called when the container is running, and the activity timeout
+     * expiration has been reached.
+     *
+     * If you want to shutdown the container, you should call this.destroy() here
+     *
+     * By default, this method calls `this.destroy()`
+     */
+    async onActivityExpired() {
+        await this.stop();
+    }
     /**
      * Error handler for container errors
      * Override this method in subclasses to handle container errors
@@ -562,33 +553,7 @@ export class Container extends DurableObject {
         try {
             // Renew the activity timeout whenever a request is proxied
             this.renewActivityTimeout();
-            if (request.body != null) {
-                this.openStreamCount++;
-                const destructor = () => {
-                    this.openStreamCount--;
-                    this.renewActivityTimeout();
-                };
-                const readable = attachOnClosedHook(request.body, destructor);
-                request = new Request(request, { body: readable });
-            }
             const res = await tcpPort.fetch(containerUrl, request);
-            if (res.webSocket) {
-                this.openStreamCount++;
-                // TODO: This does not seem to work :(
-                res.webSocket.addEventListener('close', async () => {
-                    this.openStreamCount--;
-                    this.renewActivityTimeout();
-                });
-            }
-            else if (res.body != null) {
-                this.openStreamCount++;
-                const destructor = () => {
-                    this.openStreamCount--;
-                    this.renewActivityTimeout();
-                };
-                const readable = attachOnClosedHook(res.body, destructor);
-                return new Response(readable, res);
-            }
             return res;
         }
         catch (e) {
@@ -631,8 +596,6 @@ export class Container extends DurableObject {
     state;
     monitor;
     monitorSetup = false;
-    // openStreamCount keeps track of the number of open streams to the container
-    openStreamCount = 0;
     sleepAfterMs = 0;
     // ==========================
     //     GENERAL HELPERS
@@ -655,16 +618,10 @@ export class Container extends DurableObject {
      */
     sql(strings, ...values) {
         let query = '';
-        try {
-            // Construct the SQL query with placeholders
-            query = strings.reduce((acc, str, i) => acc + str + (i < values.length ? '?' : ''), '');
-            // Execute the SQL query with the provided values
-            return [...this.ctx.storage.sql.exec(query, ...values)];
-        }
-        catch (e) {
-            console.error(`Failed to execute SQL query: ${query}`, e);
-            throw this.onError(e);
-        }
+        // Construct the SQL query with placeholders
+        query = strings.reduce((acc, str, i) => acc + str + (i < values.length ? '?' : ''), '');
+        // Execute the SQL query with the provided values
+        return [...this.ctx.storage.sql.exec(query, ...values)];
     }
     requestAndPortFromContainerFetchArgs(requestOrUrl, portOrInit, portParam) {
         let request;
@@ -821,14 +778,26 @@ export class Container extends DurableObject {
                 await this.state.setStoppedWithCode(exitCode);
                 this.monitorSetup = false;
                 this.monitor = undefined;
+                return;
             }
             try {
                 // TODO: Be able to retrigger onError
                 await this.onError(error);
             }
             catch { }
+        })
+            .finally(() => {
+            this.monitorSetup = false;
+            if (this.timeout) {
+                if (this.resolve)
+                    this.resolve();
+                clearTimeout(this.timeout);
+            }
         });
     }
+    deleteSchedules(name) {
+        this.sql `DELETE FROM container_schedules WHERE callback = ${name}`;
+    }
     // ============================
     //     ALARMS AND SCHEDULES
     // ============================
@@ -837,7 +806,7 @@ export class Container extends DurableObject {
      * Executes any scheduled tasks that are due
      */
     async alarm(alarmProps) {
-        if (alarmProps.isRetry && alarmProps.retryCount > MAX_ALAEM_RETRIES) {
+        if (alarmProps.isRetry && alarmProps.retryCount > MAX_ALARM_RETRIES) {
             const scheduleCount = Number(this.sql `SELECT COUNT(*) as count FROM container_schedules`[0]?.count) || 0;
             const hasScheduledTasks = scheduleCount > 0;
             if (hasScheduledTasks || this.container.running) {
@@ -849,18 +818,19 @@ export class Container extends DurableObject {
         // The only way for this DO to stop having alarms is:
         //  1. The container is not running anymore.
         //  2. Activity expired and it exits.
-        await this.ctx.storage.setAlarm(Date.now() + 1000);
+        const prevAlarm = Date.now();
+        await this.ctx.storage.setAlarm(prevAlarm);
         await this.ctx.storage.sync();
         const now = Math.floor(Date.now() / 1000);
         // Get all schedules that should be executed now
         const result = this.sql `
          SELECT * FROM container_schedules;
        `;
-        let maxTime = 0;
+        let minTime = Date.now() + 3 * 60 * 1000;
         // Process each due schedule
         for (const row of result) {
             if (row.time > now) {
-                maxTime = Math.max(maxTime, row.time * 1000);
+                minTime = Math.min(minTime, row.time * 1000);
                 continue;
             }
             const callback = this[row.callback];
@@ -891,25 +861,36 @@ export class Container extends DurableObject {
         }
         if (this.isActivityExpired()) {
             await this.stopDueToInactivity();
-            await this.ctx.storage.sync();
+            // renewActivityTimeout makes sure we don't spam calls here
+            this.renewActivityTimeout();
+            return;
+        }
+        const alarmNow = await this.ctx.storage.getAlarm();
+        if (alarmNow !== prevAlarm) {
+            await this.ctx.storage.setAlarm(Date.now());
             return;
         }
         // Math.min(3m or maxTime, sleepTimeout)
-        maxTime = maxTime === 0 ? Date.now() + 60 * 3 * 1000 : maxTime;
-        maxTime = Math.min(maxTime, this.sleepAfterMs);
-        const timeout = Math.max(0, maxTime - Date.now());
-        await this.ctx.storage.setAlarm(timeout + Date.now());
-        await this.ctx.storage.sync();
+        minTime = Math.min(minTime, this.sleepAfterMs);
+        const timeout = Math.max(0, minTime - Date.now());
         // await a sleep for maxTime to keep the DO alive for
         // at least this long
         await new Promise(resolve => {
-            setTimeout(() => {
+            this.resolve = resolve;
+            if (!this.container.running) {
+                resolve();
+                return;
+            }
+            this.timeout = setTimeout(() => {
                 resolve();
             }, timeout);
         });
+        await this.ctx.storage.setAlarm(Date.now());
         // we exit and we have another alarm,
         // the next alarm is the one that decides if it should stop the loop.
     }
+    timeout;
+    resolve;
     // synchronises container state with the container source of truth to process events
     async syncPendingStoppedEvents() {
         const state = await this.state.getState();
@@ -940,37 +921,34 @@ export class Container extends DurableObject {
     }
     /**
      * Schedule the next alarm based on upcoming tasks
-     * @private
      */
     async scheduleNextAlarm(ms = 1000) {
-        const existingAlarm = await this.ctx.storage.getAlarm();
         const nextTime = ms + Date.now();
         // if not already set
-        if (existingAlarm === null || existingAlarm > nextTime || existingAlarm < Date.now()) {
-            await this.ctx.storage.setAlarm(nextTime);
-            await this.ctx.storage.sync();
+        if (this.timeout) {
+            if (this.resolve)
+                this.resolve();
+            clearTimeout(this.timeout);
         }
+        await this.ctx.storage.setAlarm(nextTime);
+        await this.ctx.storage.sync();
     }
-    /**
-     * Get a scheduled task by ID
-     * @template T Type of the payload data
-     * @param id ID of the scheduled task
-     * @returns The Schedule object or undefined if not found
-     */
-    async getSchedule(id) {
+    async listSchedules(name) {
         const result = this.sql `
-      SELECT * FROM container_schedules WHERE id = ${id} LIMIT 1
+      SELECT * FROM container_schedules WHERE callback = ${name} LIMIT 1
     `;
         if (!result || result.length === 0) {
-            return undefined;
+            return [];
         }
-        const schedule = result[0];
+        return result.map((this.toSchedule));
+    }
+    toSchedule(schedule) {
         let payload;
         try {
             payload = JSON.parse(schedule.payload);
         }
         catch (e) {
-            console.error(`Error parsing payload for schedule ${id}:`, e);
+            console.error(`Error parsing payload for schedule ${schedule.id}:`, e);
             payload = undefined;
         }
         if (schedule.type === 'delayed') {
@@ -991,6 +969,22 @@ export class Container extends DurableObject {
             time: schedule.time,
         };
     }
+    /**
+     * Get a scheduled task by ID
+     * @template T Type of the payload data
+     * @param id ID of the scheduled task
+     * @returns The Schedule object or undefined if not found
+     */
+    async getSchedule(id) {
+        const result = this.sql `
+      SELECT * FROM container_schedules WHERE id = ${id} LIMIT 1
+    `;
+        if (!result || result.length === 0) {
+            return undefined;
+        }
+        const schedule = result[0];
+        return this.toSchedule(schedule);
+    }
     isActivityExpired() {
         return this.sleepAfterMs <= Date.now();
     }
@@ -999,11 +993,11 @@ export class Container extends DurableObject {
      */
     async stopDueToInactivity() {
         const alreadyStopped = !this.container.running;
-        const hasOpenStream = this.openStreamCount > 0;
-        if (alreadyStopped || hasOpenStream) {
-            return;
+        if (alreadyStopped) {
+            return false;
         }
-        await this.stop();
+        await this.onActivityExpired();
+        return true;
     }
 }
 //# sourceMappingURL=container.js.map