sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Containers/ ContainerClient.ts

import type * as cf from "@cloudflare/workers-types";
import { makeFetchRpcStub } from "alchemy/Rpc";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import type { HttpClientError } from "effect/http/HttpClientError";
import type * as HttpClientRequest from "effect/http/HttpClientRequest";
import type * as HttpClientResponse from "effect/http/HttpClientResponse";
import type { HttpServerError } from "effect/http/HttpServerError";
import type * as HttpServerRequest from "effect/http/HttpServerRequest";
import type * as HttpServerResponse from "effect/http/HttpServerResponse";
import * as Schedule from "effect/Schedule";
import type * as Scope from "effect/Scope";
import * as Semaphore from "effect/Semaphore";
import * as Sink from "effect/Sink";
import type * as Socket from "effect/socket/Socket";
import * as Stream from "effect/Stream";
import {
  fromCloudflareFetcher,
  type Fetcher,
  type SocketAddress,
  type SocketOptions,
} from "../Fetcher.ts";
import { DurableObjectState } from "../Workers/DurableObjectState.ts";
import {
  ContainerCrashedError,
  ContainerError,
  ContainerNotRunningError,
  ContainerRateLimitedError,
  NoContainerInstanceError,
  type ContainerStartupOptions,
} from "./Container.ts";
import { httpSchemePort } from "./ContainerPlatform.ts";

export type ContainerExecOptions = cf.ContainerExecOptions;
export type ContainerExecOutput = cf.ExecOutput;
export type ContainerInfo = cf.ContainerInfo;
export type ContainerSnapshot = cf.ContainerSnapshot;
export type ContainerSnapshotOptions = cf.ContainerSnapshotOptions;

/** Errors a container `start` can fail with. */
export type ContainerStartError =
  | ContainerError
  | NoContainerInstanceError
  | ContainerRateLimitedError;

/** Errors a container port can fail with before the request reaches it. */
export type ContainerPortError = ContainerError | ContainerNotRunningError | ContainerCrashedError;

/**
 * A port inside the container. Each request waits until the port accepts
 * connections, then is sent exactly once. A port never starts the container:
 * a stopped container fails with {@link ContainerNotRunningError}.
 */
export interface ContainerPort {
  fetch(
    request: HttpClientRequest.HttpClientRequest,
  ): Effect.Effect<
    HttpClientResponse.HttpClientResponse,
    ContainerPortError | HttpClientError,
    RuntimeContext
  >;
  fetch(
    request: HttpServerRequest.HttpServerRequest,
  ): Effect.Effect<
    HttpServerResponse.HttpServerResponse,
    ContainerPortError | HttpServerError,
    RuntimeContext
  >;
  connect(address: SocketAddress | string, options?: SocketOptions): Socket.Socket;
}

/** A native process, owned by the scope that called {@link ContainerClient.exec}. */
export interface ContainerProcess {
  /** Process ID inside the container. */
  readonly pid: number;
  /** Whether the process has a pseudo-terminal. */
  readonly isPty: boolean;
  /** Piped standard input. Completing the sink closes stdin. */
  readonly stdin: Sink.Sink<void, Uint8Array, never, ContainerError, RuntimeContext> | undefined;
  /** Piped standard output. Consume this or call output(), not both. */
  readonly stdout: Stream.Stream<Uint8Array, ContainerError, RuntimeContext> | undefined;
  /** Standard error, absent when ignored or combined with stdout. */
  readonly stderr: Stream.Stream<Uint8Array, ContainerError, RuntimeContext> | undefined;
  /** Wait for completion. Nonzero exit codes are returned normally. */
  readonly exitCode: Effect.Effect<number, ContainerError, RuntimeContext>;
  /** Collect output once. For large output, consume stdout and stderr concurrently. */
  output(): Effect.Effect<ContainerExecOutput, ContainerError, RuntimeContext>;
  /** Signal this process. Defaults to SIGTERM; child processes are not signaled. */
  kill(signal?: number): Effect.Effect<void, ContainerError, RuntimeContext>;
  /** Resize the process's pseudo-terminal. */
  resize(cols: number, rows: number): Effect.Effect<void, ContainerError, RuntimeContext>;
}

/**
 * The container bound to the current Durable Object — what `yield* Sandbox`
 * returns. Binding never starts the container: call {@link start} before
 * using it. `start` is idempotent and coordinated across every handle in the
 * Durable Object, so calling it at the top of each operation is cheap.
 *
 * A Durable Object has one container instance. When several Durable
 * Object-managed Containers are bound to it, each handle starts its own image,
 * and every handle controls that same instance: start one image at a time.
 */
export interface ContainerClient {
  /**
   * This Container's prepared image reference, the key `start()` selects by
   * default. Fails with {@link ContainerError} when the Container publishes no
   * image to this Durable Object (fleet Containers and Containers without an
   * image source).
   */
  readonly image: Effect.Effect<string, ContainerError, RuntimeContext>;
  /** Whether the container process is running; this does not imply port readiness. */
  readonly running: Effect.Effect<boolean, ContainerError, RuntimeContext>;
  /**
   * Start the container unless it is already running. Concurrent calls start
   * it once. Returns before ports are ready; {@link getTcpPort} waits for them.
   * Options apply only when this call actually starts the container.
   *
   * A Durable Object-managed Container starts its own {@link image} unless
   * `options` names an `image` or a `containerSnapshot`. A no-op while any
   * image is running: `destroy()` first to switch images.
   */
  start(
    options?: ContainerStartupOptions,
  ): Effect.Effect<void, ContainerStartError, RuntimeContext>;
  /** Stop the container immediately. */
  destroy(error?: unknown): Effect.Effect<void, ContainerError, RuntimeContext>;
  /** Signal the container's main process. */
  signal(signo: number): Effect.Effect<void, ContainerError, RuntimeContext>;
  /**
   * Wait for the container to exit, preserving failures in the Effect error channel.
   * Cloudflare often reports a failed start here rather than from `start`, so a start
   * it had no instance for fails with `NoContainerInstanceError` and a rate-limited one
   * with `ContainerRateLimitedError`, as `start` does.
   */
  monitor(): Effect.Effect<void, ContainerStartError, RuntimeContext>;
  /** Running image and labels, or null when stopped. */
  inspect(): Effect.Effect<ContainerInfo | null, ContainerError, RuntimeContext>;
  /** A port inside the container whose requests wait until it accepts connections. */
  getTcpPort(port: number): Effect.Effect<ContainerPort, never, RuntimeContext>;
  /**
   * Execute an argument vector without a shell. The container must already
   * be started. Scope closure kills this process with SIGKILL; descendants
   * are not signaled. Supply an explicit shell when shell syntax is needed.
   */
  exec(
    cmd: string[],
    options?: ContainerExecOptions,
  ): Effect.Effect<ContainerProcess, ContainerError, RuntimeContext | Scope.Scope>;
  /**
   * Save the writable root filesystem. Memory and running processes are not
   * captured. Restore by passing the handle to start({ containerSnapshot }).
   */
  snapshotContainer(
    options?: ContainerSnapshotOptions,
  ): Effect.Effect<ContainerSnapshot, ContainerError, RuntimeContext>;
  /** Set the idle timeout for this Durable Object instance, in milliseconds. */
  setInactivityTimeout(
    durationMs: number | bigint,
  ): Effect.Effect<void, ContainerError, RuntimeContext>;
  /** Intercept matching outbound HTTP requests. Re-register after each start. */
  interceptOutboundHttp(
    addr: string,
    binding: Fetcher,
  ): Effect.Effect<void, ContainerError, RuntimeContext>;
  /** Intercept all outbound HTTP requests. Re-register after each start. */
  interceptAllOutboundHttp(binding: Fetcher): Effect.Effect<void, ContainerError, RuntimeContext>;
  /** Intercept matching outbound HTTPS requests. Re-register after each start. */
  interceptOutboundHttps(
    addr: string,
    binding: Fetcher,
  ): Effect.Effect<void, ContainerError, RuntimeContext>;
}

/**
 * Names the container handle reserves. A container's RPC shape cannot
 * declare them: the handle's own method would shadow the RPC call.
 */
export type ReservedContainerKey = keyof ContainerClient | "~alchemy/Id";

const containerError = (cause: unknown) =>
  new ContainerError({
    message: cause instanceof Error ? cause.message : String(cause),
    cause,
  });

// Every constant below is taken from Cloudflare's own `@cloudflare/containers`
// runtime (`dist/lib/container.js`) so readiness matches `startAndWaitForPorts`:
//   INSTANCE_POLL_INTERVAL_MS   = 300    → fixed poll interval
//   PING_TIMEOUT_MS             = 5_000  → per-probe cap
//   TIMEOUT_TO_GET_CONTAINER_MS = 8_000  → find + start an instance
//   TIMEOUT_TO_GET_PORTS_MS     = 20_000 → wait for the port to listen
const READINESS_POLL_INTERVAL = Duration.millis(300);
const READINESS_PROBE_TIMEOUT = Duration.seconds(5);
const GET_CONTAINER_RETRIES = Math.ceil(8_000 / 300);
const PORT_READY_RETRIES = Math.ceil(20_000 / 300);
// When rate limited, back off hard: hammering `start()` only prolongs it.
const RATE_LIMIT_BACKOFF = Duration.seconds(2);
const RATE_LIMIT_RETRIES = 5;
// Covers the transient "Network connection lost" window on the real request.
const REQUEST_RETRIES = 3;

// Native classifies the same message phrases via `isErrorOfType`.
const errorText = (e: unknown) => (e instanceof Error ? e.message : String(e)).toLowerCase();
// Native does not match the second phrase: Cloudflare sends it when the
// application is at its `max_instances` cap.
const isNoInstanceError = (e: unknown) =>
  errorText(e).includes(
    "there is no container instance that can be provided to this durable object",
  ) || errorText(e).includes("maximum number of running container instances exceeded");
const isRateLimitedError = (e: unknown) =>
  errorText(e).includes("you are requesting too many containers per second");

const classifyStartError = (cause: unknown): ContainerStartError =>
  isRateLimitedError(cause)
    ? new ContainerRateLimitedError({ message: "Rate limited starting container", cause })
    : isNoInstanceError(cause)
      ? new NoContainerInstanceError({ message: "No container instance available", cause })
      : containerError(cause);

/**
 * Per-container coordination: a start mutex and the ports confirmed ready
 * since the last start. Keyed on the native `ctx.container`, which is one
 * object per Durable Object instance, so every handle in the object (several
 * layers may each `yield*` the same container) shares it. Racing callers then
 * never both call `container.start()` ("already running",
 * cloudflare/containers#173).
 */
const coordination = new WeakMap<
  object,
  { readonly startMutex: Semaphore.Semaphore; readonly readyPorts: Set<number> }
>();

const coordinationFor = (container: cf.Container) => {
  let entry = coordination.get(container);
  if (!entry) {
    entry = { startMutex: Semaphore.makeUnsafe(1), readyPorts: new Set<number>() };
    coordination.set(container, entry);
  }
  return entry;
};

// workers-types and the DOM lib declare the same web stream / AbortSignal
// classes in separate modules, so values crossing between them need a cast.
const toReadable = (
  stream: cf.ReadableStream | null | undefined,
): Stream.Stream<Uint8Array, ContainerError> | undefined => {
  if (!stream) return undefined;
  return Stream.fromReadableStream({
    evaluate: () => stream as unknown as ReadableStream<Uint8Array>,
    onError: containerError,
  });
};

const toWritable = (
  stream: cf.WritableStream | null | undefined,
): Sink.Sink<void, Uint8Array, never, ContainerError> | undefined => {
  if (!stream) return undefined;
  return Sink.fromWritableStream({
    evaluate: () => stream as unknown as WritableStream<Uint8Array>,
    onError: containerError,
  });
};

/** Abort the exec when either the Effect is interrupted or the caller aborts. */
const combineSignals = (
  interrupt: AbortSignal,
  caller: cf.AbortSignal | undefined,
): cf.AbortSignal => {
  const combined = caller
    ? AbortSignal.any([interrupt, caller as unknown as AbortSignal])
    : interrupt;
  return combined as unknown as cf.AbortSignal;
};

const fromProcess = (process: cf.ExecProcess): ContainerProcess => {
  // Once the exit code is observed, the PID may be reused: stop signaling it.
  let exited = false;
  const markExited = Effect.sync(() => {
    exited = true;
  });

  return {
    pid: process.pid,
    isPty: process.isPty,
    stdin: toWritable(process.stdin),
    stdout: toReadable(process.stdout),
    stderr: toReadable(process.stderr),
    exitCode: Effect.tryPromise({
      try: () => process.exitCode,
      catch: containerError,
    }).pipe(Effect.tap(() => markExited)),
    output: () =>
      Effect.tryPromise({
        try: () => process.output(),
        catch: containerError,
      }).pipe(Effect.tap(() => markExited)),
    kill: (signal) =>
      Effect.try({
        try: () => {
          if (!exited) process.kill(signal);
        },
        catch: containerError,
      }),
    resize: (cols, rows) =>
      Effect.try({
        try: () => process.resize(cols, rows),
        catch: containerError,
      }),
  };
};

/**
 * @internal Adapt `ctx.container` to the Effect client. The container is
 * looked up on every call, never at construction: the client is also built
 * while planning a Worker, where no Durable Object state exists.
 */
export const fromContainer = (
  getContainer: () => cf.Container | undefined,
  /** The key of this Container's image in `ctx.container.images`. */
  imageKey?: string,
): ContainerClient => {
  const attached = Effect.suspend(() => {
    const container = getContainer();
    return container
      ? Effect.succeed(container)
      : Effect.fail(
          new ContainerError({ message: "No container is attached to this Durable Object." }),
        );
  });

  const call = <A>(f: (container: cf.Container) => A) =>
    Effect.flatMap(attached, (container) =>
      Effect.try({ try: () => f(container), catch: containerError }),
    );

  const callAsync = <A>(f: (container: cf.Container) => Promise<A>) =>
    Effect.flatMap(attached, (container) =>
      Effect.tryPromise({ try: () => f(container), catch: containerError }),
    );

  const running = call((container) => container.running ?? false);

  const ownImage = (container: cf.Container) =>
    imageKey === undefined ? undefined : container.images?.[imageKey];

  const image = Effect.flatMap(attached, (container) => {
    const ref = ownImage(container);
    return ref === undefined
      ? Effect.fail(
          new ContainerError({
            message: `Container '${imageKey}' publishes no image to this Durable Object.`,
          }),
        )
      : Effect.succeed(ref);
  });

  /** Default `image` to this Container's own image. */
  const withOwnImage = (
    container: cf.Container,
    options: ContainerStartupOptions | undefined,
  ): ContainerStartupOptions | undefined => {
    if (options?.image !== undefined || options?.containerSnapshot !== undefined) return options;
    const ref = ownImage(container);
    return ref === undefined ? options : ({ ...options, image: ref } as ContainerStartupOptions);
  };

  const start = (options?: ContainerStartupOptions) =>
    Effect.gen(function* () {
      const container = yield* attached;
      // Fast path: the steady state is one cheap `running` read, no lock.
      if (container.running) return;
      const { startMutex, readyPorts } = coordinationFor(container);
      yield* Semaphore.withPermits(
        startMutex,
        1,
      )(
        Effect.gen(function* () {
          // Re-check under the lock: a racing caller may have started it.
          if (container.running) return;
          // Nothing listens on a fresh start; re-probe every port.
          readyPorts.clear();
          yield* Effect.try({
            try: () => container.start(withOwnImage(container, options)),
            catch: classifyStartError,
          }).pipe(
            Effect.retry({
              while: (e) => e._tag === "ContainerRateLimitedError",
              schedule: Schedule.spaced(RATE_LIMIT_BACKOFF),
              times: RATE_LIMIT_RETRIES,
            }),
          );
          // Once the process exits (stopped, crashed, slept) its ports stop
          // listening: forget them so the next request re-probes.
          yield* Effect.forkDetach(
            Effect.tryPromise({ try: () => container.monitor(), catch: containerError }).pipe(
              Effect.ignore,
              Effect.ensuring(Effect.sync(() => readyPorts.clear())),
            ),
          );
        }),
      );
    }).pipe(
      Effect.retry({
        while: (e) => e._tag === "NoContainerInstanceError",
        schedule: Schedule.spaced(READINESS_POLL_INTERVAL),
        times: GET_CONTAINER_RETRIES,
      }),
    );

  // A single readiness probe: any response (even non-2xx) proves the port
  // accepts connections. A process that has exited is a crash, not "not ready".
  const probePort = (container: cf.Container, port: number) => {
    const notReady = (cause: unknown) =>
      container.running
        ? new ContainerError({ message: `Container port ${port} is not ready`, cause })
        : new ContainerCrashedError({
            message: `Container exited while waiting for port ${port}`,
            cause,
          });
    return Effect.tryPromise({
      try: () =>
        httpSchemePort(container.getTcpPort(port)).fetch("http://containerstarthealthcheck"),
      catch: notReady,
    }).pipe(
      Effect.timeout(READINESS_PROBE_TIMEOUT),
      Effect.asVoid,
      Effect.mapError((error) => (error._tag === "TimeoutError" ? notReady(error) : error)),
    );
  };

  const waitForPort = (port: number) =>
    Effect.gen(function* () {
      const container = yield* attached;
      const { readyPorts } = coordinationFor(container);
      if (readyPorts.has(port)) return container;
      if (!container.running) {
        return yield* new ContainerNotRunningError({
          message: `Container is not running; call start() before using port ${port}.`,
        });
      }
      yield* probePort(container, port).pipe(
        Effect.retry({
          while: (e) => e._tag === "ContainerError",
          schedule: Schedule.spaced(READINESS_POLL_INTERVAL),
          times: PORT_READY_RETRIES,
        }),
      );
      readyPorts.add(port);
      return container;
    });

  // The container is resolved per request, so a port can be taken while the
  // Durable Object is constructed, before the container starts.
  const getTcpPort = (port: number) =>
    Effect.succeed<ContainerPort>({
      // Wait for readiness (bounded), then send the real request once. Only a
      // not-yet-ready port or a transport blip is retried.
      fetch: ((request: HttpClientRequest.HttpClientRequest) =>
        waitForPort(port).pipe(
          // `fetch` accepts client and server requests alike.
          Effect.andThen((container) =>
            fromCloudflareFetcher(httpSchemePort(container.getTcpPort(port))).fetch(request),
          ),
          Effect.retry({
            while: (e: { _tag: string }) =>
              e._tag === "ContainerError" || e._tag === "HttpClientError",
            schedule: Schedule.spaced(READINESS_POLL_INTERVAL),
            times: REQUEST_RETRIES,
          }),
        )) as unknown as ContainerPort["fetch"],
      connect: (address, options) => {
        const container = getContainer();
        if (!container) throw new Error("No container is attached to this Durable Object.");
        return fromCloudflareFetcher(httpSchemePort(container.getTcpPort(port))).connect(
          address,
          options,
        );
      },
    });

  const startProcess = (cmd: string[], options?: ContainerExecOptions) =>
    Effect.flatMap(attached, (container) =>
      Effect.tryPromise({
        try: (interrupt) =>
          container.exec(cmd, {
            ...options,
            signal: combineSignals(interrupt, options?.signal),
          }),
        catch: containerError,
      }),
    ).pipe(Effect.map(fromProcess));

  return {
    image,
    running,
    start,
    destroy: (error) => callAsync((container) => container.destroy(error)),
    signal: (signo) => call((container) => container.signal(signo)),
    monitor: () =>
      Effect.flatMap(attached, (container) =>
        Effect.tryPromise({ try: () => container.monitor(), catch: classifyStartError }),
      ),
    inspect: () => callAsync((container) => container.inspect()),
    getTcpPort,
    exec: (cmd, options) =>
      Effect.acquireRelease(
        startProcess(cmd, options),
        // SIGKILL a process that is still running when its scope closes.
        (process) => Effect.ignore(process.kill(9)),
        { interruptible: true },
      ),
    snapshotContainer: (options = {}) =>
      callAsync((container) => container.snapshotContainer(options)),
    setInactivityTimeout: (durationMs) =>
      callAsync((container) => container.setInactivityTimeout(durationMs)),
    // workerd forwards intercepted requests over RPC and accepts only a
    // native Fetcher, which every Alchemy Fetcher carries as `raw`.
    interceptOutboundHttp: (addr, binding) =>
      callAsync((container) => container.interceptOutboundHttp(addr, binding.raw)),
    interceptAllOutboundHttp: (binding) =>
      callAsync((container) => container.interceptAllOutboundHttp(binding.raw)),
    interceptOutboundHttps: (addr, binding) =>
      callAsync((container) => container.interceptOutboundHttps(addr, binding.raw)),
  };
};

/**
 * @internal What `yield* Container` runs inside a Durable Object: register the
 * container's bindings, then return its handle. Methods declared on the
 * container's RPC shape are sent to its port-3000 server; the handle's own
 * methods take precedence.
 */
export const makeContainerHandle = Effect.fnUntraced(function* (
  id: string,
  binding: Effect.Effect<unknown, never, any>,
) {
  yield* binding;
  const state = yield* DurableObjectState;
  const client = fromContainer(() => state.container, id);
  const rpcPort = client.getTcpPort(3000);
  return makeFetchRpcStub<ContainerClient>({
    // RPC methods only run inside the Durable Object, where RuntimeContext is
    // always present; the stub's fetch type cannot carry it.
    fetch: (request) =>
      // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- erases RuntimeContext; RPC calls only run at runtime
      rpcPort.pipe(Effect.flatMap((port) => port.fetch(request))) as Effect.Effect<
        HttpClientResponse.HttpClientResponse,
        unknown
      >,
    baseUrl: "http://container",
    base: { ...client, "~alchemy/Id": id },
  });
});