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

main
ts 204 lines 8.1 KB
Raw
1 import type { Server } from "node:http";
2 import * as Cause from "effect/Cause";
3 import * as Context from "effect/Context";
4 import * as Data from "effect/Data";
5 import * as Deferred from "effect/Deferred";
6 import * as Effect from "effect/Effect";
7 import * as Exit from "effect/Exit";
8 import * as Fiber from "effect/Fiber";
9 import * as Scope from "effect/Scope";
10
11 export class ManagedHttpShutdownInvalidProps extends Data.TaggedError(
12 "ManagedHttpShutdownInvalidProps",
13 )<{
14 readonly message: string;
15 readonly cause?: unknown;
16 }> {}
17
18 export class ManagedHttpShutdownOperationFailed extends Data.TaggedError(
19 "ManagedHttpShutdownOperationFailed",
20 )<{
21 readonly message: string;
22 readonly cause?: unknown;
23 }> {}
24
25 /** Internal HTTP and dependency lifetimes, separate from managed run fibers. */
26 export class ManagedHttpShutdown extends Context.Service<
27 ManagedHttpShutdown,
28 {
29 readonly scope: Scope.Closeable;
30 readonly dependencies: Scope.Closeable;
31 readonly servers: Set<Server>;
32 readonly drainTimeoutMs: number;
33 readonly isStopping: () => boolean;
34 readonly observeRequest: (fiber: Fiber.Fiber<unknown, unknown>) => void;
35 readonly runnerFinished: (exit: Exit.Exit<unknown, unknown>, last: boolean) => void;
36 }
37 >()("Alchemy.Runtime.ManagedHttpShutdown") {}
38
39 /**
40 * Coordinate shutdown of an Alchemy-owned Fly Service process, including HTTP
41 * requests, background runners, and their shared dependencies.
42 *
43 * The Fly bootstrap enables this when `ALCHEMY_FLY_SHUTDOWN_TIMEOUT_MS` is set.
44 * The Service provider sets it for managed Services using blue/green or an
45 * explicit shutdown policy. Raw images and external servers own their shutdown.
46 *
47 * This is a process-entrypoint helper, not a request timeout or a general-purpose
48 * Effect combinator. Running it installs process-wide SIGTERM and SIGINT
49 * listeners. They coexist with other listeners, but cannot prevent another
50 * listener from exiting the process. Importing this module installs no listeners.
51 *
52 * Shutdown stops HTTP acceptance and interrupts background runners concurrently.
53 * Existing responses and request finalizers drain before shared dependencies
54 * close. Deadlines start on a signal, runner failure, completion of all runner
55 * bodies, or program completion, not after `timeoutMs` of normal execution.
56 *
57 * At 80% of the budget, remaining HTTP connections are forcibly closed. At 90%,
58 * a native timer calls `process.exit(1)`, even if Effect finalizers are still
59 * running. This reserves time before Fly's own termination deadline; it does
60 * not guarantee cleanup completes. These timers require a responsive event loop.
61 * Repeated signals do not extend the budget. Listeners and timers are removed
62 * when the wrapper's scope closes, unless the process exits first.
63 *
64 * @param program - The whole managed process program, not an individual handler.
65 * @param timeoutMs - Fly's configured shutdown budget, from 1 to 300000 ms.
66 * @returns Whether shutdown was requested before the program completed.
67 * Cleanup failures and exceeded drain deadlines fail the Effect; the caller
68 * owns the normal process exit after successful cleanup.
69 * @internal
70 */
71 export const withManagedHttpShutdown = (
72 program: Effect.Effect<unknown, unknown>,
73 timeoutMs: number,
74 ) =>
75 Effect.gen(function* () {
76 if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 300_000) {
77 return yield* new ManagedHttpShutdownInvalidProps({
78 message: "ALCHEMY_FLY_SHUTDOWN_TIMEOUT_MS must be a positive integer at most 300000",
79 });
80 }
81
82 const signal = yield* Deferred.make<void>();
83 const scope = yield* Scope.make("parallel");
84 const dependencies = yield* Scope.make();
85 const servers = new Set<Server>();
86 let stopping = false;
87 let drained = false;
88 let timedOut = false;
89 const runnerFailures: Cause.Cause<unknown>[] = [];
90 const requestFailures: Cause.Cause<unknown>[] = [];
91 const requests = new Set<Fiber.Fiber<unknown, unknown>>();
92 let drainDeadline: ReturnType<typeof setTimeout> | undefined;
93 let deadline: ReturnType<typeof setTimeout> | undefined;
94 // Leave time for request/instance finalizers, then for Fly's own stop deadline.
95 const drainTimeoutMs = Math.floor(timeoutMs * 0.8);
96 const exitTimeoutMs = Math.min(Math.floor(timeoutMs * 0.9), 2 ** 31 - 1);
97
98 // Native timers remain independent of uninterruptible Effect finalizers.
99 const beginShutdown = () => {
100 if (stopping) return;
101 stopping = true;
102 drainDeadline = setTimeout(() => {
103 if (drained) return;
104 timedOut = true;
105 console.error("Managed HTTP drain deadline exceeded; closing connections.");
106 for (const server of servers) server.closeAllConnections();
107 }, drainTimeoutMs);
108 deadline = setTimeout(() => {
109 console.error("Managed HTTP shutdown deadline exceeded; exiting.");
110 process.exit(1);
111 }, exitTimeoutMs);
112 };
113
114 yield* Effect.acquireRelease(
115 Effect.sync(() => {
116 const onSignal = () => {
117 beginShutdown();
118 Deferred.doneUnsafe(signal, Effect.void);
119 };
120 process.on("SIGTERM", onSignal);
121 process.on("SIGINT", onSignal);
122 return onSignal;
123 }),
124 (onSignal) =>
125 Effect.sync(() => {
126 process.off("SIGTERM", onSignal);
127 process.off("SIGINT", onSignal);
128 if (drainDeadline !== undefined) clearTimeout(drainDeadline);
129 if (deadline !== undefined) clearTimeout(deadline);
130 }),
131 );
132 yield* Effect.addFinalizer((exit) => Scope.close(dependencies, exit));
133 yield* Effect.addFinalizer((exit) => Scope.close(scope, exit));
134
135 const fiber = yield* program.pipe(
136 Effect.provideService(ManagedHttpShutdown, {
137 scope,
138 dependencies,
139 servers,
140 drainTimeoutMs,
141 isStopping: () => stopping,
142 observeRequest: (request) => {
143 if (requests.has(request)) return;
144 requests.add(request);
145 request.addObserver((exit) => {
146 requests.delete(request);
147 if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause)) {
148 requestFailures.push(exit.cause);
149 console.error("Managed HTTP request cleanup failed", Cause.pretty(exit.cause));
150 }
151 });
152 },
153 runnerFinished: (exit, last) => {
154 if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause)) {
155 runnerFailures.push(exit.cause);
156 console.error("Managed process cleanup failed", Cause.pretty(exit.cause));
157 beginShutdown();
158 Deferred.doneUnsafe(signal, Effect.void);
159 } else if (last) {
160 beginShutdown();
161 }
162 },
163 }),
164 Effect.forkChild,
165 );
166 const interrupted = yield* Effect.raceFirst(
167 Deferred.await(signal).pipe(Effect.as(true)),
168 Fiber.await(fiber).pipe(Effect.as(false)),
169 );
170 yield* Effect.sync(beginShutdown);
171 // Neither HTTP drain nor one worker's finalizers may delay another's stop.
172 const [httpExit, programExit] = yield* Effect.all(
173 [
174 Scope.close(scope, Exit.void).pipe(Effect.exit),
175 Effect.gen(function* () {
176 if (interrupted) yield* Fiber.interrupt(fiber);
177 return yield* Fiber.await(fiber);
178 }),
179 ],
180 { concurrency: "unbounded" },
181 );
182 // Socket closure is not completion of the request fiber's finalizers.
183 yield* Fiber.awaitAll(requests);
184 drained = true;
185 const dependencyExit = yield* Scope.close(dependencies, programExit).pipe(Effect.exit);
186 const failures = runnerFailures.concat(
187 requestFailures,
188 [httpExit, programExit, dependencyExit].flatMap((exit) =>
189 Exit.isFailure(exit) && !(interrupted && Cause.hasInterruptsOnly(exit.cause))
190 ? [exit.cause]
191 : [],
192 ),
193 );
194 for (const cause of failures) {
195 yield* Effect.logError("Managed process cleanup failed", cause);
196 }
197 if (failures.length > 0) return yield* Effect.failCause(failures[0]!);
198 if (timedOut) {
199 return yield* new ManagedHttpShutdownOperationFailed({
200 message: "Managed process drain deadline exceeded",
201 });
202 }
203 return interrupted;
204 }).pipe(Effect.scoped);