@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 555 lines 22.4 KB
Raw
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 });