The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type * as cf from "@cloudflare/workers-types"; |
| 2 | import { makeFetchRpcStub } from "alchemy/Rpc"; |
| 3 | import type { RuntimeContext } from "alchemy/RuntimeContext"; |
| 4 | import * as Duration from "effect/Duration"; |
| 5 | import * as Effect from "effect/Effect"; |
| 6 | import type { HttpClientError } from "effect/http/HttpClientError"; |
| 7 | import type * as HttpClientRequest from "effect/http/HttpClientRequest"; |
| 8 | import type * as HttpClientResponse from "effect/http/HttpClientResponse"; |
| 9 | import type { HttpServerError } from "effect/http/HttpServerError"; |
| 10 | import type * as HttpServerRequest from "effect/http/HttpServerRequest"; |
| 11 | import type * as HttpServerResponse from "effect/http/HttpServerResponse"; |
| 12 | import * as Schedule from "effect/Schedule"; |
| 13 | import type * as Scope from "effect/Scope"; |
| 14 | import * as Semaphore from "effect/Semaphore"; |
| 15 | import * as Sink from "effect/Sink"; |
| 16 | import type * as Socket from "effect/socket/Socket"; |
| 17 | import * as Stream from "effect/Stream"; |
| 18 | import { |
| 19 | fromCloudflareFetcher, |
| 20 | type Fetcher, |
| 21 | type SocketAddress, |
| 22 | type SocketOptions, |
| 23 | } from "../Fetcher.ts"; |
| 24 | import { DurableObjectState } from "../Workers/DurableObjectState.ts"; |
| 25 | import { |
| 26 | ContainerCrashedError, |
| 27 | ContainerError, |
| 28 | ContainerNotRunningError, |
| 29 | ContainerRateLimitedError, |
| 30 | NoContainerInstanceError, |
| 31 | type ContainerStartupOptions, |
| 32 | } from "./Container.ts"; |
| 33 | import { httpSchemePort } from "./ContainerPlatform.ts"; |
| 34 | |
| 35 | export type ContainerExecOptions = cf.ContainerExecOptions; |
| 36 | export type ContainerExecOutput = cf.ExecOutput; |
| 37 | export type ContainerInfo = cf.ContainerInfo; |
| 38 | export type ContainerSnapshot = cf.ContainerSnapshot; |
| 39 | export type ContainerSnapshotOptions = cf.ContainerSnapshotOptions; |
| 40 | |
| 41 | /** Errors a container `start` can fail with. */ |
| 42 | export type ContainerStartError = |
| 43 | | ContainerError |
| 44 | | NoContainerInstanceError |
| 45 | | ContainerRateLimitedError; |
| 46 | |
| 47 | /** Errors a container port can fail with before the request reaches it. */ |
| 48 | export type ContainerPortError = ContainerError | ContainerNotRunningError | ContainerCrashedError; |
| 49 | |
| 50 | /** |
| 51 | * A port inside the container. Each request waits until the port accepts |
| 52 | * connections, then is sent exactly once. A port never starts the container: |
| 53 | * a stopped container fails with {@link ContainerNotRunningError}. |
| 54 | */ |
| 55 | export interface ContainerPort { |
| 56 | fetch( |
| 57 | request: HttpClientRequest.HttpClientRequest, |
| 58 | ): Effect.Effect< |
| 59 | HttpClientResponse.HttpClientResponse, |
| 60 | ContainerPortError | HttpClientError, |
| 61 | RuntimeContext |
| 62 | >; |
| 63 | fetch( |
| 64 | request: HttpServerRequest.HttpServerRequest, |
| 65 | ): Effect.Effect< |
| 66 | HttpServerResponse.HttpServerResponse, |
| 67 | ContainerPortError | HttpServerError, |
| 68 | RuntimeContext |
| 69 | >; |
| 70 | connect(address: SocketAddress | string, options?: SocketOptions): Socket.Socket; |
| 71 | } |
| 72 | |
| 73 | /** A native process, owned by the scope that called {@link ContainerClient.exec}. */ |
| 74 | export interface ContainerProcess { |
| 75 | /** Process ID inside the container. */ |
| 76 | readonly pid: number; |
| 77 | /** Whether the process has a pseudo-terminal. */ |
| 78 | readonly isPty: boolean; |
| 79 | /** Piped standard input. Completing the sink closes stdin. */ |
| 80 | readonly stdin: Sink.Sink<void, Uint8Array, never, ContainerError, RuntimeContext> | undefined; |
| 81 | /** Piped standard output. Consume this or call output(), not both. */ |
| 82 | readonly stdout: Stream.Stream<Uint8Array, ContainerError, RuntimeContext> | undefined; |
| 83 | /** Standard error, absent when ignored or combined with stdout. */ |
| 84 | readonly stderr: Stream.Stream<Uint8Array, ContainerError, RuntimeContext> | undefined; |
| 85 | /** Wait for completion. Nonzero exit codes are returned normally. */ |
| 86 | readonly exitCode: Effect.Effect<number, ContainerError, RuntimeContext>; |
| 87 | /** Collect output once. For large output, consume stdout and stderr concurrently. */ |
| 88 | output(): Effect.Effect<ContainerExecOutput, ContainerError, RuntimeContext>; |
| 89 | /** Signal this process. Defaults to SIGTERM; child processes are not signaled. */ |
| 90 | kill(signal?: number): Effect.Effect<void, ContainerError, RuntimeContext>; |
| 91 | /** Resize the process's pseudo-terminal. */ |
| 92 | resize(cols: number, rows: number): Effect.Effect<void, ContainerError, RuntimeContext>; |
| 93 | } |
| 94 | |
| 95 | /** |
| 96 | * The container bound to the current Durable Object — what `yield* Sandbox` |
| 97 | * returns. Binding never starts the container: call {@link start} before |
| 98 | * using it. `start` is idempotent and coordinated across every handle in the |
| 99 | * Durable Object, so calling it at the top of each operation is cheap. |
| 100 | * |
| 101 | * A Durable Object has one container instance. When several Durable |
| 102 | * Object-managed Containers are bound to it, each handle starts its own image, |
| 103 | * and every handle controls that same instance: start one image at a time. |
| 104 | */ |
| 105 | export interface ContainerClient { |
| 106 | /** |
| 107 | * This Container's prepared image reference, the key `start()` selects by |
| 108 | * default. Fails with {@link ContainerError} when the Container publishes no |
| 109 | * image to this Durable Object (fleet Containers and Containers without an |
| 110 | * image source). |
| 111 | */ |
| 112 | readonly image: Effect.Effect<string, ContainerError, RuntimeContext>; |
| 113 | /** Whether the container process is running; this does not imply port readiness. */ |
| 114 | readonly running: Effect.Effect<boolean, ContainerError, RuntimeContext>; |
| 115 | /** |
| 116 | * Start the container unless it is already running. Concurrent calls start |
| 117 | * it once. Returns before ports are ready; {@link getTcpPort} waits for them. |
| 118 | * Options apply only when this call actually starts the container. |
| 119 | * |
| 120 | * A Durable Object-managed Container starts its own {@link image} unless |
| 121 | * `options` names an `image` or a `containerSnapshot`. A no-op while any |
| 122 | * image is running: `destroy()` first to switch images. |
| 123 | */ |
| 124 | start( |
| 125 | options?: ContainerStartupOptions, |
| 126 | ): Effect.Effect<void, ContainerStartError, RuntimeContext>; |
| 127 | /** Stop the container immediately. */ |
| 128 | destroy(error?: unknown): Effect.Effect<void, ContainerError, RuntimeContext>; |
| 129 | /** Signal the container's main process. */ |
| 130 | signal(signo: number): Effect.Effect<void, ContainerError, RuntimeContext>; |
| 131 | /** |
| 132 | * Wait for the container to exit, preserving failures in the Effect error channel. |
| 133 | * Cloudflare often reports a failed start here rather than from `start`, so a start |
| 134 | * it had no instance for fails with `NoContainerInstanceError` and a rate-limited one |
| 135 | * with `ContainerRateLimitedError`, as `start` does. |
| 136 | */ |
| 137 | monitor(): Effect.Effect<void, ContainerStartError, RuntimeContext>; |
| 138 | /** Running image and labels, or null when stopped. */ |
| 139 | inspect(): Effect.Effect<ContainerInfo | null, ContainerError, RuntimeContext>; |
| 140 | /** A port inside the container whose requests wait until it accepts connections. */ |
| 141 | getTcpPort(port: number): Effect.Effect<ContainerPort, never, RuntimeContext>; |
| 142 | /** |
| 143 | * Execute an argument vector without a shell. The container must already |
| 144 | * be started. Scope closure kills this process with SIGKILL; descendants |
| 145 | * are not signaled. Supply an explicit shell when shell syntax is needed. |
| 146 | */ |
| 147 | exec( |
| 148 | cmd: string[], |
| 149 | options?: ContainerExecOptions, |
| 150 | ): Effect.Effect<ContainerProcess, ContainerError, RuntimeContext | Scope.Scope>; |
| 151 | /** |
| 152 | * Save the writable root filesystem. Memory and running processes are not |
| 153 | * captured. Restore by passing the handle to start({ containerSnapshot }). |
| 154 | */ |
| 155 | snapshotContainer( |
| 156 | options?: ContainerSnapshotOptions, |
| 157 | ): Effect.Effect<ContainerSnapshot, ContainerError, RuntimeContext>; |
| 158 | /** Set the idle timeout for this Durable Object instance, in milliseconds. */ |
| 159 | setInactivityTimeout( |
| 160 | durationMs: number | bigint, |
| 161 | ): Effect.Effect<void, ContainerError, RuntimeContext>; |
| 162 | /** Intercept matching outbound HTTP requests. Re-register after each start. */ |
| 163 | interceptOutboundHttp( |
| 164 | addr: string, |
| 165 | binding: Fetcher, |
| 166 | ): Effect.Effect<void, ContainerError, RuntimeContext>; |
| 167 | /** Intercept all outbound HTTP requests. Re-register after each start. */ |
| 168 | interceptAllOutboundHttp(binding: Fetcher): Effect.Effect<void, ContainerError, RuntimeContext>; |
| 169 | /** Intercept matching outbound HTTPS requests. Re-register after each start. */ |
| 170 | interceptOutboundHttps( |
| 171 | addr: string, |
| 172 | binding: Fetcher, |
| 173 | ): Effect.Effect<void, ContainerError, RuntimeContext>; |
| 174 | } |
| 175 | |
| 176 | /** |
| 177 | * Names the container handle reserves. A container's RPC shape cannot |
| 178 | * declare them: the handle's own method would shadow the RPC call. |
| 179 | */ |
| 180 | export type ReservedContainerKey = keyof ContainerClient | "~alchemy/Id"; |
| 181 | |
| 182 | const containerError = (cause: unknown) => |
| 183 | new ContainerError({ |
| 184 | message: cause instanceof Error ? cause.message : String(cause), |
| 185 | cause, |
| 186 | }); |
| 187 | |
| 188 | // Every constant below is taken from Cloudflare's own `@cloudflare/containers` |
| 189 | // runtime (`dist/lib/container.js`) so readiness matches `startAndWaitForPorts`: |
| 190 | // INSTANCE_POLL_INTERVAL_MS = 300 → fixed poll interval |
| 191 | // PING_TIMEOUT_MS = 5_000 → per-probe cap |
| 192 | // TIMEOUT_TO_GET_CONTAINER_MS = 8_000 → find + start an instance |
| 193 | // TIMEOUT_TO_GET_PORTS_MS = 20_000 → wait for the port to listen |
| 194 | const READINESS_POLL_INTERVAL = Duration.millis(300); |
| 195 | const READINESS_PROBE_TIMEOUT = Duration.seconds(5); |
| 196 | const GET_CONTAINER_RETRIES = Math.ceil(8_000 / 300); |
| 197 | const PORT_READY_RETRIES = Math.ceil(20_000 / 300); |
| 198 | // When rate limited, back off hard: hammering `start()` only prolongs it. |
| 199 | const RATE_LIMIT_BACKOFF = Duration.seconds(2); |
| 200 | const RATE_LIMIT_RETRIES = 5; |
| 201 | // Covers the transient "Network connection lost" window on the real request. |
| 202 | const REQUEST_RETRIES = 3; |
| 203 | |
| 204 | // Native classifies the same message phrases via `isErrorOfType`. |
| 205 | const errorText = (e: unknown) => (e instanceof Error ? e.message : String(e)).toLowerCase(); |
| 206 | // Native does not match the second phrase: Cloudflare sends it when the |
| 207 | // application is at its `max_instances` cap. |
| 208 | const isNoInstanceError = (e: unknown) => |
| 209 | errorText(e).includes( |
| 210 | "there is no container instance that can be provided to this durable object", |
| 211 | ) || errorText(e).includes("maximum number of running container instances exceeded"); |
| 212 | const isRateLimitedError = (e: unknown) => |
| 213 | errorText(e).includes("you are requesting too many containers per second"); |
| 214 | |
| 215 | const classifyStartError = (cause: unknown): ContainerStartError => |
| 216 | isRateLimitedError(cause) |
| 217 | ? new ContainerRateLimitedError({ message: "Rate limited starting container", cause }) |
| 218 | : isNoInstanceError(cause) |
| 219 | ? new NoContainerInstanceError({ message: "No container instance available", cause }) |
| 220 | : containerError(cause); |
| 221 | |
| 222 | /** |
| 223 | * Per-container coordination: a start mutex and the ports confirmed ready |
| 224 | * since the last start. Keyed on the native `ctx.container`, which is one |
| 225 | * object per Durable Object instance, so every handle in the object (several |
| 226 | * layers may each `yield*` the same container) shares it. Racing callers then |
| 227 | * never both call `container.start()` ("already running", |
| 228 | * cloudflare/containers#173). |
| 229 | */ |
| 230 | const coordination = new WeakMap< |
| 231 | object, |
| 232 | { readonly startMutex: Semaphore.Semaphore; readonly readyPorts: Set<number> } |
| 233 | >(); |
| 234 | |
| 235 | const coordinationFor = (container: cf.Container) => { |
| 236 | let entry = coordination.get(container); |
| 237 | if (!entry) { |
| 238 | entry = { startMutex: Semaphore.makeUnsafe(1), readyPorts: new Set<number>() }; |
| 239 | coordination.set(container, entry); |
| 240 | } |
| 241 | return entry; |
| 242 | }; |
| 243 | |
| 244 | // workers-types and the DOM lib declare the same web stream / AbortSignal |
| 245 | // classes in separate modules, so values crossing between them need a cast. |
| 246 | const toReadable = ( |
| 247 | stream: cf.ReadableStream | null | undefined, |
| 248 | ): Stream.Stream<Uint8Array, ContainerError> | undefined => { |
| 249 | if (!stream) return undefined; |
| 250 | return Stream.fromReadableStream({ |
| 251 | evaluate: () => stream as unknown as ReadableStream<Uint8Array>, |
| 252 | onError: containerError, |
| 253 | }); |
| 254 | }; |
| 255 | |
| 256 | const toWritable = ( |
| 257 | stream: cf.WritableStream | null | undefined, |
| 258 | ): Sink.Sink<void, Uint8Array, never, ContainerError> | undefined => { |
| 259 | if (!stream) return undefined; |
| 260 | return Sink.fromWritableStream({ |
| 261 | evaluate: () => stream as unknown as WritableStream<Uint8Array>, |
| 262 | onError: containerError, |
| 263 | }); |
| 264 | }; |
| 265 | |
| 266 | /** Abort the exec when either the Effect is interrupted or the caller aborts. */ |
| 267 | const combineSignals = ( |
| 268 | interrupt: AbortSignal, |
| 269 | caller: cf.AbortSignal | undefined, |
| 270 | ): cf.AbortSignal => { |
| 271 | const combined = caller |
| 272 | ? AbortSignal.any([interrupt, caller as unknown as AbortSignal]) |
| 273 | : interrupt; |
| 274 | return combined as unknown as cf.AbortSignal; |
| 275 | }; |
| 276 | |
| 277 | const fromProcess = (process: cf.ExecProcess): ContainerProcess => { |
| 278 | // Once the exit code is observed, the PID may be reused: stop signaling it. |
| 279 | let exited = false; |
| 280 | const markExited = Effect.sync(() => { |
| 281 | exited = true; |
| 282 | }); |
| 283 | |
| 284 | return { |
| 285 | pid: process.pid, |
| 286 | isPty: process.isPty, |
| 287 | stdin: toWritable(process.stdin), |
| 288 | stdout: toReadable(process.stdout), |
| 289 | stderr: toReadable(process.stderr), |
| 290 | exitCode: Effect.tryPromise({ |
| 291 | try: () => process.exitCode, |
| 292 | catch: containerError, |
| 293 | }).pipe(Effect.tap(() => markExited)), |
| 294 | output: () => |
| 295 | Effect.tryPromise({ |
| 296 | try: () => process.output(), |
| 297 | catch: containerError, |
| 298 | }).pipe(Effect.tap(() => markExited)), |
| 299 | kill: (signal) => |
| 300 | Effect.try({ |
| 301 | try: () => { |
| 302 | if (!exited) process.kill(signal); |
| 303 | }, |
| 304 | catch: containerError, |
| 305 | }), |
| 306 | resize: (cols, rows) => |
| 307 | Effect.try({ |
| 308 | try: () => process.resize(cols, rows), |
| 309 | catch: containerError, |
| 310 | }), |
| 311 | }; |
| 312 | }; |
| 313 | |
| 314 | /** |
| 315 | * @internal Adapt `ctx.container` to the Effect client. The container is |
| 316 | * looked up on every call, never at construction: the client is also built |
| 317 | * while planning a Worker, where no Durable Object state exists. |
| 318 | */ |
| 319 | export const fromContainer = ( |
| 320 | getContainer: () => cf.Container | undefined, |
| 321 | /** The key of this Container's image in `ctx.container.images`. */ |
| 322 | imageKey?: string, |
| 323 | ): ContainerClient => { |
| 324 | const attached = Effect.suspend(() => { |
| 325 | const container = getContainer(); |
| 326 | return container |
| 327 | ? Effect.succeed(container) |
| 328 | : Effect.fail( |
| 329 | new ContainerError({ message: "No container is attached to this Durable Object." }), |
| 330 | ); |
| 331 | }); |
| 332 | |
| 333 | const call = <A>(f: (container: cf.Container) => A) => |
| 334 | Effect.flatMap(attached, (container) => |
| 335 | Effect.try({ try: () => f(container), catch: containerError }), |
| 336 | ); |
| 337 | |
| 338 | const callAsync = <A>(f: (container: cf.Container) => Promise<A>) => |
| 339 | Effect.flatMap(attached, (container) => |
| 340 | Effect.tryPromise({ try: () => f(container), catch: containerError }), |
| 341 | ); |
| 342 | |
| 343 | const running = call((container) => container.running ?? false); |
| 344 | |
| 345 | const ownImage = (container: cf.Container) => |
| 346 | imageKey === undefined ? undefined : container.images?.[imageKey]; |
| 347 | |
| 348 | const image = Effect.flatMap(attached, (container) => { |
| 349 | const ref = ownImage(container); |
| 350 | return ref === undefined |
| 351 | ? Effect.fail( |
| 352 | new ContainerError({ |
| 353 | message: `Container '${imageKey}' publishes no image to this Durable Object.`, |
| 354 | }), |
| 355 | ) |
| 356 | : Effect.succeed(ref); |
| 357 | }); |
| 358 | |
| 359 | /** Default `image` to this Container's own image. */ |
| 360 | const withOwnImage = ( |
| 361 | container: cf.Container, |
| 362 | options: ContainerStartupOptions | undefined, |
| 363 | ): ContainerStartupOptions | undefined => { |
| 364 | if (options?.image !== undefined || options?.containerSnapshot !== undefined) return options; |
| 365 | const ref = ownImage(container); |
| 366 | return ref === undefined ? options : ({ ...options, image: ref } as ContainerStartupOptions); |
| 367 | }; |
| 368 | |
| 369 | const start = (options?: ContainerStartupOptions) => |
| 370 | Effect.gen(function* () { |
| 371 | const container = yield* attached; |
| 372 | // Fast path: the steady state is one cheap `running` read, no lock. |
| 373 | if (container.running) return; |
| 374 | const { startMutex, readyPorts } = coordinationFor(container); |
| 375 | yield* Semaphore.withPermits( |
| 376 | startMutex, |
| 377 | 1, |
| 378 | )( |
| 379 | Effect.gen(function* () { |
| 380 | // Re-check under the lock: a racing caller may have started it. |
| 381 | if (container.running) return; |
| 382 | // Nothing listens on a fresh start; re-probe every port. |
| 383 | readyPorts.clear(); |
| 384 | yield* Effect.try({ |
| 385 | try: () => container.start(withOwnImage(container, options)), |
| 386 | catch: classifyStartError, |
| 387 | }).pipe( |
| 388 | Effect.retry({ |
| 389 | while: (e) => e._tag === "ContainerRateLimitedError", |
| 390 | schedule: Schedule.spaced(RATE_LIMIT_BACKOFF), |
| 391 | times: RATE_LIMIT_RETRIES, |
| 392 | }), |
| 393 | ); |
| 394 | // Once the process exits (stopped, crashed, slept) its ports stop |
| 395 | // listening: forget them so the next request re-probes. |
| 396 | yield* Effect.forkDetach( |
| 397 | Effect.tryPromise({ try: () => container.monitor(), catch: containerError }).pipe( |
| 398 | Effect.ignore, |
| 399 | Effect.ensuring(Effect.sync(() => readyPorts.clear())), |
| 400 | ), |
| 401 | ); |
| 402 | }), |
| 403 | ); |
| 404 | }).pipe( |
| 405 | Effect.retry({ |
| 406 | while: (e) => e._tag === "NoContainerInstanceError", |
| 407 | schedule: Schedule.spaced(READINESS_POLL_INTERVAL), |
| 408 | times: GET_CONTAINER_RETRIES, |
| 409 | }), |
| 410 | ); |
| 411 | |
| 412 | // A single readiness probe: any response (even non-2xx) proves the port |
| 413 | // accepts connections. A process that has exited is a crash, not "not ready". |
| 414 | const probePort = (container: cf.Container, port: number) => { |
| 415 | const notReady = (cause: unknown) => |
| 416 | container.running |
| 417 | ? new ContainerError({ message: `Container port ${port} is not ready`, cause }) |
| 418 | : new ContainerCrashedError({ |
| 419 | message: `Container exited while waiting for port ${port}`, |
| 420 | cause, |
| 421 | }); |
| 422 | return Effect.tryPromise({ |
| 423 | try: () => |
| 424 | httpSchemePort(container.getTcpPort(port)).fetch("http://containerstarthealthcheck"), |
| 425 | catch: notReady, |
| 426 | }).pipe( |
| 427 | Effect.timeout(READINESS_PROBE_TIMEOUT), |
| 428 | Effect.asVoid, |
| 429 | Effect.mapError((error) => (error._tag === "TimeoutError" ? notReady(error) : error)), |
| 430 | ); |
| 431 | }; |
| 432 | |
| 433 | const waitForPort = (port: number) => |
| 434 | Effect.gen(function* () { |
| 435 | const container = yield* attached; |
| 436 | const { readyPorts } = coordinationFor(container); |
| 437 | if (readyPorts.has(port)) return container; |
| 438 | if (!container.running) { |
| 439 | return yield* new ContainerNotRunningError({ |
| 440 | message: `Container is not running; call start() before using port ${port}.`, |
| 441 | }); |
| 442 | } |
| 443 | yield* probePort(container, port).pipe( |
| 444 | Effect.retry({ |
| 445 | while: (e) => e._tag === "ContainerError", |
| 446 | schedule: Schedule.spaced(READINESS_POLL_INTERVAL), |
| 447 | times: PORT_READY_RETRIES, |
| 448 | }), |
| 449 | ); |
| 450 | readyPorts.add(port); |
| 451 | return container; |
| 452 | }); |
| 453 | |
| 454 | // The container is resolved per request, so a port can be taken while the |
| 455 | // Durable Object is constructed, before the container starts. |
| 456 | const getTcpPort = (port: number) => |
| 457 | Effect.succeed<ContainerPort>({ |
| 458 | // Wait for readiness (bounded), then send the real request once. Only a |
| 459 | // not-yet-ready port or a transport blip is retried. |
| 460 | fetch: ((request: HttpClientRequest.HttpClientRequest) => |
| 461 | waitForPort(port).pipe( |
| 462 | // `fetch` accepts client and server requests alike. |
| 463 | Effect.andThen((container) => |
| 464 | fromCloudflareFetcher(httpSchemePort(container.getTcpPort(port))).fetch(request), |
| 465 | ), |
| 466 | Effect.retry({ |
| 467 | while: (e: { _tag: string }) => |
| 468 | e._tag === "ContainerError" || e._tag === "HttpClientError", |
| 469 | schedule: Schedule.spaced(READINESS_POLL_INTERVAL), |
| 470 | times: REQUEST_RETRIES, |
| 471 | }), |
| 472 | )) as unknown as ContainerPort["fetch"], |
| 473 | connect: (address, options) => { |
| 474 | const container = getContainer(); |
| 475 | if (!container) throw new Error("No container is attached to this Durable Object."); |
| 476 | return fromCloudflareFetcher(httpSchemePort(container.getTcpPort(port))).connect( |
| 477 | address, |
| 478 | options, |
| 479 | ); |
| 480 | }, |
| 481 | }); |
| 482 | |
| 483 | const startProcess = (cmd: string[], options?: ContainerExecOptions) => |
| 484 | Effect.flatMap(attached, (container) => |
| 485 | Effect.tryPromise({ |
| 486 | try: (interrupt) => |
| 487 | container.exec(cmd, { |
| 488 | ...options, |
| 489 | signal: combineSignals(interrupt, options?.signal), |
| 490 | }), |
| 491 | catch: containerError, |
| 492 | }), |
| 493 | ).pipe(Effect.map(fromProcess)); |
| 494 | |
| 495 | return { |
| 496 | image, |
| 497 | running, |
| 498 | start, |
| 499 | destroy: (error) => callAsync((container) => container.destroy(error)), |
| 500 | signal: (signo) => call((container) => container.signal(signo)), |
| 501 | monitor: () => |
| 502 | Effect.flatMap(attached, (container) => |
| 503 | Effect.tryPromise({ try: () => container.monitor(), catch: classifyStartError }), |
| 504 | ), |
| 505 | inspect: () => callAsync((container) => container.inspect()), |
| 506 | getTcpPort, |
| 507 | exec: (cmd, options) => |
| 508 | Effect.acquireRelease( |
| 509 | startProcess(cmd, options), |
| 510 | // SIGKILL a process that is still running when its scope closes. |
| 511 | (process) => Effect.ignore(process.kill(9)), |
| 512 | { interruptible: true }, |
| 513 | ), |
| 514 | snapshotContainer: (options = {}) => |
| 515 | callAsync((container) => container.snapshotContainer(options)), |
| 516 | setInactivityTimeout: (durationMs) => |
| 517 | callAsync((container) => container.setInactivityTimeout(durationMs)), |
| 518 | // workerd forwards intercepted requests over RPC and accepts only a |
| 519 | // native Fetcher, which every Alchemy Fetcher carries as `raw`. |
| 520 | interceptOutboundHttp: (addr, binding) => |
| 521 | callAsync((container) => container.interceptOutboundHttp(addr, binding.raw)), |
| 522 | interceptAllOutboundHttp: (binding) => |
| 523 | callAsync((container) => container.interceptAllOutboundHttp(binding.raw)), |
| 524 | interceptOutboundHttps: (addr, binding) => |
| 525 | callAsync((container) => container.interceptOutboundHttps(addr, binding.raw)), |
| 526 | }; |
| 527 | }; |
| 528 | |
| 529 | /** |
| 530 | * @internal What `yield* Container` runs inside a Durable Object: register the |
| 531 | * container's bindings, then return its handle. Methods declared on the |
| 532 | * container's RPC shape are sent to its port-3000 server; the handle's own |
| 533 | * methods take precedence. |
| 534 | */ |
| 535 | export const makeContainerHandle = Effect.fnUntraced(function* ( |
| 536 | id: string, |
| 537 | binding: Effect.Effect<unknown, never, any>, |
| 538 | ) { |
| 539 | yield* binding; |
| 540 | const state = yield* DurableObjectState; |
| 541 | const client = fromContainer(() => state.container, id); |
| 542 | const rpcPort = client.getTcpPort(3000); |
| 543 | return makeFetchRpcStub<ContainerClient>({ |
| 544 | // RPC methods only run inside the Durable Object, where RuntimeContext is |
| 545 | // always present; the stub's fetch type cannot carry it. |
| 546 | fetch: (request) => |
| 547 | // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- erases RuntimeContext; RPC calls only run at runtime |
| 548 | rpcPort.pipe(Effect.flatMap((port) => port.fetch(request))) as Effect.Effect< |
| 549 | HttpClientResponse.HttpClientResponse, |
| 550 | unknown |
| 551 | >, |
| 552 | baseUrl: "http://container", |
| 553 | base: { ...client, "~alchemy/Id": id }, |
| 554 | }); |
| 555 | }); |