next: more cleanup

Remove unused exports
Tidy up error checking a bit
Make getState wrap container.running since we do not know the stopping state

Author: emily-shen

src/index.ts

@@ -1,9 +1,2 @@
 export { Container } from './lib/container';
-export { getRandom, loadBalance, getContainer, switchPort } from './lib/utils';
-export type {
-  ContainerOptions,
-  ContainerEventHandler,
-  ContainerMessage,
-  StopParams,
-  State,
-} from './types';
+export type { State } from './types';

src/lib/container.ts

@@ -1,9 +1,7 @@
-import type { ContainerOptions, ContainerStartOptions, StopParams, State } from '../types';
+import type { ContainerStartOptions, Signal, SignalInteger, State } from '../types';
 import { parseTimeExpression } from './helpers';
 import { DurableObject } from 'cloudflare:workers';
 
-const CONTAINER_STATE_KEY = '__CF_CONTAINER_STATE';
-
 const PING_TIMEOUT_MS = 5000;
 
 const DEFAULT_SLEEP_AFTER = '10m'; // Default sleep after inactivity time
@@ -13,8 +11,6 @@ const INSTANCE_POLL_INTERVAL_MS = 300; // Default interval for polling container
 // to see if the container is up at all.
 const FALLBACK_PORT_TO_CHECK = 33;
 
-export type Signal = 'SIGKILL' | 'SIGINT' | 'SIGTERM';
-export type SignalInteger = number;
 const signalToNumbers: Record<Signal, SignalInteger> = {
   SIGINT: 2,
   SIGTERM: 15,
@@ -29,20 +25,21 @@ const signalToNumbers: Record<Signal, SignalInteger> = {
 
 // ==== Error helpers ====
 
-function isErrorOfType(e: unknown, matchingString: string): boolean {
-  const errorString = e instanceof Error ? e.message : String(e);
-  return errorString.toLowerCase().includes(matchingString);
-}
+const MAX_INSTANCES_ERROR = 'Maximum number of running container instances exceeded';
 
 const NO_CONTAINER_INSTANCE_ERROR =
   'there is no container instance that can be provided to this durable object';
 
-/** we can retry start */
-const isNoInstanceError = (error: unknown): boolean =>
-  isErrorOfType(error, NO_CONTAINER_INSTANCE_ERROR);
-
 const NOT_LISTENING_ERROR = 'the container is not listening';
-const isNotListeningError = (error: unknown): boolean => isErrorOfType(error, NOT_LISTENING_ERROR);
+
+function isErrorOfType(e: unknown, matchingString: string): boolean {
+  const errorString = e instanceof Error ? e.message : String(e);
+  return errorString.toLowerCase().includes(matchingString);
+}
+
+function retryableError(e: unknown): boolean {
+  return isErrorOfType(e, NO_CONTAINER_INSTANCE_ERROR) || isErrorOfType(e, MAX_INSTANCES_ERROR);
+}
 
 /**
  * Combines the existing user-defined signal with a signal that aborts after the timeout specified by waitInterval.
@@ -67,71 +64,6 @@ function addTimeoutSignals(
   return controller.signal;
 }
 
-// ===============================
-//     CONTAINER STATE WRAPPER
-// ===============================
-
-/**
- * ContainerState is a wrapper around a DO storage to store and get
- * the container state.
- * It's useful to track which kind of events have been handled by the user,
- * a transition to a new state won't be successful unless the user's hook has been
- * triggered and waited for.
- * A user hook might be repeated multiple times if they throw errors.
- */
-class ContainerState {
-  status?: State;
-  constructor(private storage: DurableObject['ctx']['storage']) {}
-
-  async setRunning() {
-    await this.setStatusAndupdate('running');
-  }
-
-  async setHealthy() {
-    await this.setStatusAndupdate('healthy');
-  }
-
-  async setStopping() {
-    await this.setStatusAndupdate('stopping');
-  }
-
-  async setStopped() {
-    await this.setStatusAndupdate('stopped');
-  }
-
-  async setStoppedWithCode(exitCode: number) {
-    this.status = { status: 'stopped_with_code', lastChange: Date.now(), exitCode };
-    await this.update();
-  }
-
-  async getState(): Promise<State> {
-    if (!this.status) {
-      const state = await this.storage.get<State>(CONTAINER_STATE_KEY);
-      if (!state) {
-        this.status = {
-          status: 'stopped',
-          lastChange: Date.now(),
-        };
-        await this.update();
-      } else {
-        this.status = state;
-      }
-    }
-
-    return this.status!;
-  }
-
-  private async setStatusAndupdate(status: State['status']) {
-    this.status = { status: status, lastChange: Date.now() };
-    await this.update();
-  }
-
-  private async update() {
-    if (!this.status) throw new Error('status should be init');
-    await this.storage.put<State>(CONTAINER_STATE_KEY, this.status);
-  }
-}
-
 // ===============================
 // ===============================
 //     MAIN CONTAINER CLASS
@@ -156,12 +88,12 @@ export class Container<Env = unknown> extends DurableObject<Env> {
   envVars: ContainerStartOptions['env'] = {};
   entrypoint: ContainerStartOptions['entrypoint'];
   enableInternet: ContainerStartOptions['enableInternet'] = true;
-
+  public container: NonNullable<DurableObject['ctx']['container']>;
   // =========================
   //     PUBLIC INTERFACE
   // =========================
 
-  constructor(ctx: DurableObject['ctx'], env: Env, options?: ContainerOptions) {
+  constructor(ctx: DurableObject['ctx'], env: Env) {
     super(ctx, env);
 
     if (ctx.container === undefined) {
@@ -170,51 +102,24 @@ export class Container<Env = unknown> extends DurableObject<Env> {
       );
     }
 
-    this.state = new ContainerState(this.ctx.storage);
-
     this.ctx.blockConcurrencyWhile(async () => {
       await this.ctx.container?.setInactivityTimeout(parseTimeExpression(this.sleepAfter) * 1000);
     });
 
     this.container = ctx.container;
 
-    // Apply options if provided
-    if (options) {
-      if (options.defaultPort !== undefined) this.defaultPort = options.defaultPort;
-      if (options.sleepAfter !== undefined) this.sleepAfter = options.sleepAfter;
-    }
-
     // we are not setting up a global monitor because we cannot guarantee the DO will be alive when the container stops
     // if (this.container.running) {
     //   this.monitor ??= this.setupMonitorCallbacks();
     // }
   }
   /**
    * Gets the current state of the container
-   * @returns Promise<State>
    */
-  async getState(): Promise<State> {
-    return { ...(await this.state.getState()) };
-  }
-
-  /**
-   *
-   * Returns a promise that resolves when the container is ready.
-   * By default readiness is defined as being able to successfully fetch 'http://ping' on the specified port.
-   *
-   * This can be overriden by the user and will be called when starting the container
-   *
-   * If called by us, this will receive a port to check, which might be the target port of a fetch if this was called during fetch.
-   * The user could choose to ignore this port, or check other ports as well.
-   * It will also receive an abort signal which is a combination of a user provided signal and a timeout signal.
-   *
-   * If called by the user it won't receive these parameters :/
-   *
-   */
-  public async readinessCheck(portToCheck?: number, signal?: AbortSignal): Promise<void> {
-    await this.container
-      .getTcpPort(portToCheck ?? FALLBACK_PORT_TO_CHECK)
-      .fetch('http://ping', { signal });
+  getState(): State {
+    return {
+      status: this.container.running ? ('running' as const) : ('stopped' as const),
+    };
   }
 
   /**
@@ -292,7 +197,7 @@ export class Container<Env = unknown> extends DurableObject<Env> {
       if (options.signal?.aborted) {
         throw new Error('Container start aborted by user signal');
       }
-      if (!this.container.running && (attempt === 0 || isNoInstanceError(lastError))) {
+      if (!this.container.running && (attempt === 0 || retryableError(lastError))) {
         const resolvedEnvVars = options.envVars ?? this.envVars;
         const resolvedEntrypoint = options.entrypoint ?? this.entrypoint;
         this.container.start({
@@ -309,20 +214,24 @@ export class Container<Env = unknown> extends DurableObject<Env> {
       try {
         // by default this pings the container
         const timeoutSignal = addTimeoutSignals(options.signal, options.pingTimeoutMs);
-        await this.readinessCheck(portToCheck, timeoutSignal);
+        await this.container
+          .getTcpPort(portToCheck)
+          .fetch('http://ping', { signal: timeoutSignal });
+
+        // the ping was successful, exit the loop
         break;
       } catch (e) {
         if (this.container.running) {
-          // return if the user has specified that we don't need to wait for the container application to be ready
-          if (isNotListeningError(e) && !options.waitForReady) {
+          // exit loop if the user has specified that we don't need to wait for the container application to be ready
+          if (isErrorOfType(e, NOT_LISTENING_ERROR) && !options.waitForReady) {
             break;
           }
           // otherwise fallthrough to retry the ping...
         } else {
           // we tried to start the container but it is now not running
           await startupMonitor.catch(async err => {
             // if the error is cloudchamberd not providing a container in time, we can retry
-            if (isNoInstanceError(err)) {
+            if (retryableError(err)) {
               lastError = err;
             } else {
               // for any other reason, we should assume the container crashed and give up
@@ -349,7 +258,7 @@ export class Container<Env = unknown> extends DurableObject<Env> {
         }
       }
 
-      // wait a bit before retrying
+      // Wait a bit before retrying
       await Promise.race([
         new Promise(res => setTimeout(res, INSTANCE_POLL_INTERVAL_MS)),
         userSignalPromise,
@@ -368,10 +277,6 @@ export class Container<Env = unknown> extends DurableObject<Env> {
     // this.monitor ??= this.setupMonitorCallbacks();
   }
 
-  // =======================
-  //     LIFECYCLE HOOKS
-  // =======================
-
   /**
    * Send a signal to the container.
    * @param signal - The signal to send to the container (default: 15 for SIGTERM)
@@ -422,17 +327,12 @@ export class Container<Env = unknown> extends DurableObject<Env> {
   //   throw error;
   // }
 
-  // ============
-  //     HTTP
-  // ============
-
   // this should not be overridden by the user
   override async fetch(request: Request): Promise<Response> {
     const portFromUrl = new URL(request.url).port;
     const targetPort = this.defaultPort ?? (portFromUrl ? parseInt(portFromUrl) : undefined);
     if (targetPort === undefined) {
       throw new Error(
-        // TODO: update this with a docs url.
         'No port configured for this container. Set the `defaultPort` in your Container subclass, or specify a port on your request url`.'
       );
     }
@@ -444,9 +344,6 @@ export class Container<Env = unknown> extends DurableObject<Env> {
     return await tcpPort.fetch(request.url.replace('https:', 'http:'), request);
   }
 
-  public container: NonNullable<DurableObject['ctx']['container']>;
-  private state: ContainerState;
-
   // we are not setting up a global monitor because we cannot guarantee the DO will be alive when the container stops
   // private monitor: Promise<unknown> | undefined;
 

src/types/index.ts

@@ -10,62 +10,9 @@ export type ContainerStartOptions = NonNullable<
   Parameters<NonNullable<DurableObject['ctx']['container']>['start']>[0]
 >;
 
-/**
- * Message structure for communication with containers
- */
-export interface ContainerMessage<T = unknown> {
-  type: string;
-  payload?: T;
-}
-
-// Container state interface removed
-
-/**
- * Options for container configuration
- */
-export interface ContainerOptions {
-  /** Optional ID for the container */
-  id?: string;
-
-  /** Default port number to connect to (defaults to container.defaultPort) */
-  defaultPort?: number;
-
-  /** How long to keep the container alive without activity */
-  sleepAfter?: string | number;
-
-  /** 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;
-}
-
-/**
- * Function to handle container events
- */
-export type ContainerEventHandler = () => void | Promise<void>;
-
-/**
- * Params sent to `onStop` method when the container stops
- */
-export type StopParams = {
-  exitCode: number;
-  reason: 'exit' | 'runtime_signal';
+export type State = {
+  status: 'running' | 'stopped';
 };
 
-export type State = {
-  lastChange: number;
-} & (
-  | {
-      // 'running' means that the container is trying to start and is transitioning to a healthy status.
-      //           onStop might be triggered if there is an exit code, and it will transition to 'stopped'.
-      status: 'running' | 'stopping' | 'stopped' | 'healthy';
-    }
-  | {
-      status: 'stopped_with_code';
-      exitCode?: number;
-    }
-);
+export type Signal = 'SIGKILL' | 'SIGINT' | 'SIGTERM';
+export type SignalInteger = number;