Add function overload to startAndWaitForPorts

and document it better

Author: emily-shen

.changeset/orange-keys-chew.md

@@ -0,0 +1,7 @@
+---
+'@cloudflare/containers': patch
+---
+
+add function overload to startAndWaitForPorts()
+
+You can now use `startAndWaitForPorts({startOptions: {envVars: {FOO:"BAR"}}})` instead of `startAndWaitForPorts(undefined, {},  {envVars: {FOO:"BAR"}})`, although that is still supported.

README.md

@@ -24,7 +24,7 @@ import { Container, getRandom } from '@cloudflare/containers';
 export class MyContainer extends Container {
   // Configure default port for the container
   defaultPort = 8080;
-  sleepAfter = "1m";
+  sleepAfter = '1m';
 }
 
 export default {
@@ -34,7 +34,7 @@ export default {
     // If you want to route requests to a specific container,
     // pass a unique container identifier to .get()
 
-    if (pathname.startsWith("/specific/")) {
+    if (pathname.startsWith('/specific/')) {
       // In this case, each unique pathname will spawn a new container
       let id = env.MY_CONTAINER.idFromName(pathname);
       let stub = env.MY_CONTAINER.get(id);
@@ -54,9 +54,9 @@ export default {
 
 ## API Reference
 
-### Container Class
+### `Container` Class
 
-The main class that extends a container-enbled Durable Object to provide additional container-specific functionality.
+The `Container` class that extends a container-enbled Durable Object to provide additional container-specific functionality.
 
 #### Properties
 
@@ -83,6 +83,7 @@ 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
@@ -97,16 +98,45 @@ If you don't stop the container here, the activity tracker will be renewed, and
 
 - `fetch(request)`: Default handler to forward HTTP requests to the container. Can be overridden.
 - `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.
-  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.
-  **Do not use 'containerFetch' when trying to send a Request object with a websocket, until [this issue is addressed](https://github.com/cloudflare/workerd/issues/2319).
-  You can overcome this limitation by doing:
-  `container.fetch(switchPort(request, port))`
+    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.
+    \*\*Do not use 'containerFetch' when trying to send a Request object with a websocket, until [this issue is addressed](https://github.com/cloudflare/workerd/issues/2319).
+    You can overcome this limitation by doing:
+    `container.fetch(switchPort(request, port))`
+
+- `startAndWaitForPorts(args: StartAndWaitForPortsOptions): Promise<void>`
+
+  Starts the container and then waits for specified ports to be ready. Prioritises `ports` passed in to the function, then `requiredPorts` if set, then `defaultPort`.
+
+  ```typescript
+  export interface StartAndWaitForPortsOptions {
+    startOptions?: {
+      /** Environment variables to pass to the container */
+      envVars?: Record<string, string>;
+      /** Custom entrypoint to override container default */
+      entrypoint?: string[];
+      /** Whether to enable internet access for the container */
+      enableInternet?: boolean;
+    };
+    /** Ports to check */
+    ports?: number | number[];
+    cancellationOptions?: {
+      /** Abort signal to cancel start and port checking */
+      abort?: AbortSignal;
+      /** Max time to wait for container to start, in milliseconds */
+      instanceGetTimeoutMS?: number;
+      /** Max time to wait for ports to be ready, in milliseconds */
+      portReadyTimeoutMS?: number;
+      /** Polling interval for checking container has started or ports are ready, in milliseconds */
+      waitInterval?: number;
+    };
+  }
+  ```
 
 - `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(signal = SIGTERM)`: Sends the specified signal to the container.
 - `destroy()`: Forcefully destroys the container.
 - `getState()`: Get the current container state.
@@ -131,7 +161,7 @@ export class MyContainer extends Container {
 
   // Set how long the container should stay active without requests
   // Supported formats: "10m" (minutes), "30s" (seconds), "1h" (hours), or a number (seconds)
-  sleepAfter = "10m";
+  sleepAfter = '10m';
 
   // Lifecycle method called when container starts
   override onStart(): void {
@@ -153,9 +183,7 @@ export class MyContainer extends Container {
 
   // Lifecycle method when the container class considers the activity to be expired
   override onActivityExpired() {
-    console.log(
-      'Container activity expired'
-    );
+    console.log('Container activity expired');
     await this.destroy();
   }
 
@@ -170,7 +198,6 @@ export class MyContainer extends Container {
 
   // Handle incoming requests
   async fetch(request: Request): Promise<Response> {
-
     // Default implementation forwards requests to the container
     // This will automatically renew the activity timeout
     return await this.containerFetch(request);
@@ -205,13 +232,13 @@ export class ConfiguredContainer extends Container {
   defaultPort = 9000;
 
   // Set the timeout for sleeping the container after inactivity
-  sleepAfter = "2h";
+  sleepAfter = '2h';
 
   // Environment variables to pass to the container
   envVars = {
     NODE_ENV: 'production',
     LOG_LEVEL: 'info',
-    APP_PORT: '9000'
+    APP_PORT: '9000',
   };
 
   // Custom entrypoint to run in the container
@@ -249,18 +276,16 @@ export class MultiPortContainer extends Container {
       if (url.pathname.startsWith('/api')) {
         // API server runs on port 3000
         return await this.containerFetch(request, 3000);
-      }
-      else if (url.pathname.startsWith('/admin')) {
+      } else if (url.pathname.startsWith('/admin')) {
         // Admin interface runs on port 8080
         return await this.containerFetch(request, 8080);
-      }
-      else {
+      } else {
         // Public website runs on port 80
         return await this.containerFetch(request, 80);
       }
     } catch (error) {
       return new Response(`Error: ${error instanceof Error ? error.message : String(error)}`, {
-        status: 500
+        status: 500,
       });
     }
   }
@@ -283,21 +308,22 @@ export class FetchStyleContainer extends Container {
       const response = await this.containerFetch('/api/data', {
         method: 'POST',
         headers: {
-          'Content-Type': 'application/json'
+          'Content-Type': 'application/json',
         },
-        body: JSON.stringify({ query: 'example' })
+        body: JSON.stringify({ query: 'example' }),
       });
 
       // You can also specify a port with this syntax
-      const adminResponse = await this.containerFetch('https://example.com/admin',
+      const adminResponse = await this.containerFetch(
+        'https://example.com/admin',
         { method: 'GET' },
-        3000   // port
+        3000 // port
       );
 
       return response;
     } catch (error) {
       return new Response(`Error: ${error instanceof Error ? error.message : String(error)}`, {
-        status: 500
+        status: 500,
       });
     }
   }
@@ -316,7 +342,7 @@ export class TimeoutContainer extends Container {
   defaultPort = 8080;
 
   // Set timeout to 30 minutes of inactivity
-  sleepAfter = "30m";  // Supports "30s", "5m", "1h" formats, or a number in seconds
+  sleepAfter = '30m'; // Supports "30s", "5m", "1h" formats, or a number in seconds
 
   // Custom method that will extend the container's lifetime
   async performBackgroundTask(data: any): Promise<void> {
@@ -337,11 +363,14 @@ export class TimeoutContainer extends Container {
     if (url.pathname === '/task') {
       await this.performBackgroundTask();
 
-      return new Response(JSON.stringify({
-        success: true,
-        message: 'Background task executed',
-        nextStop: `Container will shut down after ${this.sleepAfter} of inactivity`
-      }), { headers: { 'Content-Type': 'application/json' } });
+      return new Response(
+        JSON.stringify({
+          success: true,
+          message: 'Background task executed',
+          nextStop: `Container will shut down after ${this.sleepAfter} of inactivity`,
+        }),
+        { headers: { 'Content-Type': 'application/json' } }
+      );
     }
 
     // For all other requests, forward to the container
@@ -354,7 +383,7 @@ export class TimeoutContainer extends Container {
 ### Using Load Balancing
 
 This package includes a `getRandom` helper which routes requests to one of N instances.
-In the future, this will be automatically handled  with smart by Cloudflare Containers
+In the future, this will be automatically handled with smart by Cloudflare Containers
 with autoscaling set to true, but is not yet implemented.
 
 ```typescript
@@ -382,7 +411,7 @@ export default {
     }
 
     return new Response('Not found', { status: 404 });
-  }
+  },
 };
 ```
 

example-node/src/index.ts

@@ -33,13 +33,10 @@ export default {
 
     if (pathname.startsWith('/startAndWaitForPorts')) {
       const containerInstance = getContainer(env.MY_CONTAINER, pathname);
-      await containerInstance.startAndWaitForPorts(
-        undefined,
-        {},
-        {
-          envVars: { MESSAGE: 'hi from start and wait for ports' },
-        }
-      );
+      await containerInstance.startAndWaitForPorts({
+        startOptions: { envVars: { MESSAGE: 'hi from start and wait for ports' } },
+      });
+
       return containerInstance.fetch(request);
     }
 

src/lib/container.ts

@@ -7,6 +7,8 @@ import type {
   ScheduleSQL,
   State,
   WaitOptions,
+  CancellationOptions,
+  StartAndWaitForPortsOptions,
 } from '../types';
 import { generateId, parseTimeExpression } from './helpers';
 import { DurableObject } from 'cloudflare:workers';
@@ -379,16 +381,38 @@ export class Container<Env = unknown> extends DurableObject<Env> {
    * @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
    */
+  public async startAndWaitForPorts(args: StartAndWaitForPortsOptions): Promise<void>;
   public async startAndWaitForPorts(
     ports?: number | number[],
-    cancellationOptions?: {
-      abort?: AbortSignal;
-      instanceGetTimeoutMS?: number;
-      portReadyTimeoutMS?: number;
-      waitInterval?: number;
-    },
+    cancellationOptions?: CancellationOptions,
+    startOptions?: ContainerStartConfigOptions
+  ): Promise<void>;
+  public async startAndWaitForPorts(
+    portsOrArgs?: number | number[] | StartAndWaitForPortsOptions,
+    cancellationOptions?: CancellationOptions,
+    startOptions?: ContainerStartConfigOptions
+  ): Promise<void>;
+  public async startAndWaitForPorts(
+    portsOrArgs?: number | number[] | StartAndWaitForPortsOptions,
+    cancellationOptions?: CancellationOptions,
     startOptions?: ContainerStartConfigOptions
   ): Promise<void> {
+    // Parse arguments to handle different overload signatures
+    let ports: number | number[] | undefined;
+    let resolvedCancellationOptions: CancellationOptions | undefined = {};
+    let resolvedStartOptions: ContainerStartConfigOptions | undefined = {};
+
+    if (typeof portsOrArgs === 'object' && portsOrArgs !== null && !Array.isArray(portsOrArgs)) {
+      // Object-based overload: { startOptions?, ports?, cancellationOptions? }
+      ports = portsOrArgs.ports;
+      resolvedCancellationOptions = portsOrArgs.cancellationOptions;
+      resolvedStartOptions = portsOrArgs.startOptions;
+    } else {
+      ports = portsOrArgs;
+      resolvedCancellationOptions = cancellationOptions;
+      resolvedStartOptions = startOptions;
+    }
+
     // Determine which ports to check
     const portsToCheck = await this.getPortsToCheck(ports);
 
@@ -409,15 +433,15 @@ export class Container<Env = unknown> extends DurableObject<Env> {
     await this.syncPendingStoppedEvents();
 
     // Prepare to start the container
-    cancellationOptions ??= {};
-    let containerGetRetries = cancellationOptions.instanceGetTimeoutMS
-      ? Math.ceil(cancellationOptions.instanceGetTimeoutMS / INSTANCE_POLL_INTERVAL_MS)
+    resolvedCancellationOptions ??= {};
+    let containerGetRetries = resolvedCancellationOptions.instanceGetTimeoutMS
+      ? Math.ceil(resolvedCancellationOptions.instanceGetTimeoutMS / INSTANCE_POLL_INTERVAL_MS)
       : TRIES_TO_GET_CONTAINER;
 
     const waitOptions = {
-      abort: cancellationOptions.abort,
+      abort: resolvedCancellationOptions.abort,
       retries: containerGetRetries,
-      waitInterval: cancellationOptions.waitInterval ?? INSTANCE_POLL_INTERVAL_MS,
+      waitInterval: resolvedCancellationOptions.waitInterval ?? INSTANCE_POLL_INTERVAL_MS,
       portToCheck: portsToCheck[0],
     };
 
@@ -428,11 +452,11 @@ export class Container<Env = unknown> extends DurableObject<Env> {
     });
 
     // Start the container if it's not running
-    const triesUsed = await this.startContainerIfNotRunning(waitOptions, startOptions);
+    const triesUsed = await this.startContainerIfNotRunning(waitOptions, resolvedStartOptions);
 
     // Check each port
-    let totalPortReadyTries = cancellationOptions.portReadyTimeoutMS
-      ? Math.ceil(cancellationOptions.portReadyTimeoutMS / INSTANCE_POLL_INTERVAL_MS)
+    let totalPortReadyTries = resolvedCancellationOptions.portReadyTimeoutMS
+      ? Math.ceil(resolvedCancellationOptions.portReadyTimeoutMS / INSTANCE_POLL_INTERVAL_MS)
       : TRIES_TO_GET_PORTS;
     const triesLeft = totalPortReadyTries - triesUsed;
 

src/types/index.ts

@@ -43,7 +43,6 @@ export interface ContainerOptions {
   enableInternet?: boolean;
 }
 
-
 /**
  * Function to handle container events
  */
@@ -61,6 +60,19 @@ export interface ContainerStartConfigOptions {
   enableInternet?: boolean;
 }
 
+export interface StartAndWaitForPortsOptions {
+  startOptions?: ContainerStartConfigOptions;
+  ports?: number | number[];
+  cancellationOptions?: CancellationOptions;
+}
+
+export interface CancellationOptions {
+  abort?: AbortSignal;
+  instanceGetTimeoutMS?: number;
+  portReadyTimeoutMS?: number;
+  waitInterval?: number;
+}
+
 export interface WaitOptions {
   abort?: AbortSignal;
   retries: number;