@cloudflare/containers 0.0.27 → 0.0.29

package/dist/lib/container.d.ts

@@ -1,4 +1,4 @@
-import type { ContainerOptions, ContainerStartOptions, ContainerStartConfigOptions, Schedule, StopParams, State } from '../types';
+import type { ContainerOptions, ContainerStartOptions, ContainerStartConfigOptions, Schedule, StopParams, State, WaitOptions, CancellationOptions, StartAndWaitForPortsOptions } from '../types';
 import { DurableObject } from 'cloudflare:workers';
 export type Signal = 'SIGKILL' | 'SIGINT' | 'SIGTERM';
 export type SignalInteger = number;
@@ -16,84 +16,59 @@ export declare class Container<Env = unknown> extends DurableObject<Env> {
      */
     getState(): Promise<State>;
     /**
-     * Start the container if it's not running and set up monitoring
+     * Start the container if it's not running and set up monitoring and lifecycle hooks,
+     * without waiting for ports to be ready.
      *
-     * This method handles the core container startup process without waiting for ports to be ready.
-     * It will automatically retry if the container fails to start, up to maxTries attempts.
+     * It will automatically retry if the container fails to start, using the specified waitOptions
      *
-     * It's useful when you need to:
-     * - Start a container without blocking until a port is available
-     * - Initialize a container that doesn't expose ports
-     * - Perform custom port availability checks separately
-     *
-     * The method applies the container configuration from your instance properties by default, but allows
-     * overriding these values for this specific startup:
-     * - Environment variables (defaults to this.envVars)
-     * - Custom entrypoint commands (defaults to this.entrypoint)
-     * - Internet access settings (defaults to this.enableInternet)
-     *
-     * It also sets up monitoring to track container lifecycle events and automatically
-     * calls the onStop handler when the container terminates.
      *
      * @example
-     * // Basic usage in a custom Container implementation
-     * async customInitialize() {
-     *   // Start the container without waiting for a port
-     *   await this.start();
-     *
-     *   // Perform additional initialization steps
-     *   // that don't require port access
-     * }
-     *
-     * @example
-     * // Start with custom configuration
      * await this.start({
      *   envVars: { DEBUG: 'true', NODE_ENV: 'development' },
      *   entrypoint: ['npm', 'run', 'dev'],
      *   enableInternet: false
      * });
      *
-     * @param options - Optional configuration to override instance defaults
-     * @param waitOptions - Optional wait configuration with abort signal for cancellation
+     * @param startOptions - Override `envVars`, `entrypoint` and `enableInternet` on a per-instance basis
+     * @param waitOptions - Optional wait configuration with abort signal for cancellation. Default ~8s timeout.
      * @returns A promise that resolves when the container start command has been issued
      * @throws Error if no container context is available or if all start attempts fail
      */
-    start(options?: ContainerStartConfigOptions, waitOptions?: {
-        signal?: AbortSignal;
-    }): Promise<void>;
+    start(startOptions?: ContainerStartConfigOptions, waitOptions?: WaitOptions): Promise<void>;
     /**
-     * Start the container and wait for ports to be available
-     *
-     * This method builds on start() by adding port availability verification:
-     * 1. Calls start() to ensure the container is running
-     * 2. If no ports are specified and requiredPorts is not set, it uses defaultPort (if set)
-     * 3. If no ports can be determined, it calls onStart and renewActivityTimeout immediately
-     * 4. For each specified port, it polls until the port is available or maxTries is reached
-     * 5. When all ports are available, it triggers onStart and renewActivityTimeout
+     * Start the container and wait for ports to be available.
      *
-     * The method prioritizes port sources in this order:
-     * 1. Ports specified directly in the method call
-     * 2. requiredPorts class property (if set)
-     * 3. defaultPort (if neither of the above is specified)
+     * For each specified port, it polls until the port is available or `cancellationOptions.portReadyTimeoutMS` is reached.
      *
      * @param ports - The ports to wait for (if undefined, uses requiredPorts or defaultPort)
-     * @param cancellationOptions
-     * @param startOptions Override configuration on a per instance for env vars, entrypoint command and internet access
-     * @throws Error if port checks fail after maxTries attempts
-     */
-    startAndWaitForPorts(ports?: number | number[], cancellationOptions?: {
-        abort?: AbortSignal;
-        instanceGetTimeoutMS?: number;
-        portReadyTimeoutMS?: number;
-        waitInterval?: number;
-    }, startOptions?: ContainerStartConfigOptions): Promise<void>;
-    /**
-     * Shuts down the container.
+     * @param cancellationOptions - Options to configure timeouts, polling intereva, and abort signal
+     * @param startOptions Override configuration on a per-instance basis for env vars, entrypoint command and internet access
+     * @returns A promise that resolves when the container has been started and the ports are listening
+     * @throws Error if port checks fail after the specified timeout or if the container fails to start.
+     */
+    startAndWaitForPorts(args: StartAndWaitForPortsOptions): Promise<void>;
+    startAndWaitForPorts(ports?: number | number[], cancellationOptions?: CancellationOptions, startOptions?: ContainerStartConfigOptions): Promise<void>;
+    startAndWaitForPorts(portsOrArgs?: number | number[] | StartAndWaitForPortsOptions, cancellationOptions?: CancellationOptions, startOptions?: ContainerStartConfigOptions): Promise<void>;
+    /**
+     *
+     * Waits for a specified port to be ready
+     *
+     * Returns the number of tries used to get the port, or throws if it couldn't get the port within the specified retry limits.
+     *
+     * @param waitOptions -
+     * - `portToCheck`: The port number to check
+     * - `abort`: Optional AbortSignal to cancel waiting
+     * - `retries`: Number of retries before giving up (default: TRIES_TO_GET_PORTS)
+     * - `waitInterval`: Interval between retries in milliseconds (default: INSTANCE_POLL_INTERVAL_MS)
+     */
+    waitForPort(waitOptions: WaitOptions): Promise<number>;
+    /**
+     * Send a signal to the container.
      * @param signal - The signal to send to the container (default: 15 for SIGTERM)
      */
     stop(signal?: Signal | SignalInteger): Promise<void>;
     /**
-     * Destroys the container. It will trigger onError instead of onStop.
+     * Destroys the container with a SIGKILL. Triggers onStop.
      */
     destroy(): Promise<void>;
     /**
@@ -109,7 +84,7 @@ export declare class Container<Env = unknown> extends DurableObject<Env> {
     onStop(_: StopParams): void | Promise<void>;
     /**
      * Lifecycle method called when the container is running, and the activity timeout
-     * expiration has been reached.
+     * expiration (set by `sleepAfter`) has been reached.
      *
      * If you want to shutdown the container, you should call this.stop() here
      *
@@ -130,7 +105,10 @@ export declare class Container<Env = unknown> extends DurableObject<Env> {
      */
     renewActivityTimeout(): void;
     /**
-     * Schedule a task to be executed in the future
+     * Schedule a task to be executed in the future.
+     *
+     * We strongly recommend using this instead of the `alarm` handler.
+     *
      * @template T Type of the payload data
      * @param when When to execute the task (Date object or number of seconds delay)
      * @param callback Name of the method to call
@@ -140,26 +118,26 @@ export declare class Container<Env = unknown> extends DurableObject<Env> {
     schedule<T = string>(when: Date | number, callback: string, payload?: T): Promise<Schedule<T>>;
     /**
      * Send a request to the container (HTTP or WebSocket) using standard fetch API signature
-     * Based on containers-starter-go implementation
      *
-     * This method handles HTTP requests to the container. WebSocket requests done outside the DO*
-     * won't work until https://github.com/cloudflare/workerd/issues/2319 is addressed. Until then, please use `switchPort` + `fetch()`.
+     * This method handles HTTP requests to the container.
+     *
+     * WebSocket requests done outside the DO won't work until https://github.com/cloudflare/workerd/issues/2319 is addressed.
+     * Until then, please use `switchPort` + `fetch()`.
      *
      * Method supports multiple signatures to match standard fetch API:
      * - containerFetch(request: Request, port?: number)
      * - containerFetch(url: string | URL, init?: RequestInit, port?: number)
      *
-     * @param requestOrUrl The request object or URL string/object to send to the container
-     * @param portOrInit Port number or fetch RequestInit options
-     * @param portParam Optional port number when using URL+init signature
-     * @returns A Response from the container, or WebSocket connection
+     * Starts the container if not already running, and waits for the target port to be ready.
+     *
+     * @returns A Response from the container
      */
     containerFetch(requestOrUrl: Request | string | URL, portOrInit?: number | RequestInit, portParam?: number): Promise<Response>;
     /**
-     * Handle fetch requests to the Container
-     * Default implementation forwards all HTTP and WebSocket requests to the container
-     * Override this in your subclass to specify a port or implement custom request handling
      *
+     * Fetch handler on the Container class.
+     * By default this forwards all requests to the container by calling `containerFetch`.
+     * Use `switchPort` to specify which port on the container to target, or this will use `defaultPort`.
      * @param request The request to handle
      */
     fetch(request: Request): Promise<Response>;
@@ -174,7 +152,19 @@ export declare class Container<Env = unknown> extends DurableObject<Env> {
      */
     private sql;
     private requestAndPortFromContainerFetchArgs;
+    /**
+     *
+     * The method prioritizes port sources in this order:
+     * 1. Ports specified directly in the method call
+     * 2. `requiredPorts` class property (if set)
+     * 3. `defaultPort` (if neither of the above is specified)
+     * 4. Falls back to port 33 if none of the above are set
+     */
     private getPortsToCheck;
+    /**
+     * Tries to start a container if it's not already running
+     * Returns the number of tries used
+     */
     private startContainerIfNotRunning;
     private setupMonitorCallbacks;
     deleteSchedules(name: string): void;