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

main
ts 497 lines 18.4 KB
Raw
1 import { Readable } from "node:stream";
2 import { pipeline } from "node:stream/promises";
3 import type { ReadableStream as NodeReadableStream } from "node:stream/web";
4 import * as Http from "alchemy/Http";
5 import type {
6 ALBEvent,
7 ALBResult,
8 APIGatewayProxyEvent,
9 APIGatewayProxyResult,
10 LambdaFunctionURLEvent,
11 LambdaFunctionURLResult,
12 } from "aws-lambda";
13 import * as Config from "effect/Config";
14 import * as Effect from "effect/Effect";
15 import * as HttpEffect from "effect/http/HttpEffect";
16 import * as HttpMiddleware from "effect/http/HttpMiddleware";
17 import * as HttpServerRequest from "effect/http/HttpServerRequest";
18 import * as HttpServerResponse from "effect/http/HttpServerResponse";
19 import * as Option from "effect/Option";
20 import type { Scope } from "effect/Scope";
21 import { type InvocationTimeoutError, withInvocationDeadline } from "./InvocationDeadline.ts";
22
23 export const isFunctionURLEvent = (event: any): event is LambdaFunctionURLEvent =>
24 event.requestContext?.http?.method !== undefined;
25
26 /**
27 * REST API (v1) AWS_PROXY events have a top-level `httpMethod` and a
28 * `requestContext.resourcePath` field. They lack the `requestContext.http.*`
29 * shape of Function URL / HTTP API (v2) events.
30 */
31 export const isApiGatewayProxyEvent = (event: any): event is APIGatewayProxyEvent =>
32 typeof event?.httpMethod === "string" && event?.requestContext?.resourcePath !== undefined;
33
34 /**
35 * Application Load Balancer target events carry a `requestContext.elb` marker
36 * (the target group ARN) and a top-level `httpMethod` + `path`.
37 */
38 export const isAlbEvent = (event: any): event is ALBEvent =>
39 typeof event?.httpMethod === "string" && event?.requestContext?.elb !== undefined;
40
41 // `HttpMiddleware.tracer` records the request on the `http.server` span only
42 // when the request finishes. A span the backstop flush ends early would ship
43 // without it, so record the method and path up front.
44 const annotateRequestSpan = <A, E, R>(self: Effect.Effect<A, E, R>) =>
45 Effect.gen(function* () {
46 const request = yield* HttpServerRequest.HttpServerRequest;
47 const span = yield* Effect.option(Effect.currentSpan);
48 if (Option.isSome(span)) {
49 span.value.attribute("http.request.method", request.method);
50 span.value.attribute("url.path", new URL(request.url, "http://localhost").pathname);
51 }
52 return yield* self;
53 });
54
55 export const makeFunctionHttpHandler = <Req>(
56 handler: Http.HttpEffect<Req>,
57 options: {
58 /** Return Function URL responses as a {@link FunctionURLStream}. */
59 responseStream?: boolean;
60 } = {},
61 ) => {
62 // `HttpMiddleware.tracer` creates the `http.server` root span per request
63 // (continuing an incoming `traceparent`), matching the Worker bridge's
64 // fetch path. With the default no-op tracer this is free; with a telemetry
65 // exporter installed the span is exported when the invocation scope
66 // flushes.
67 //
68 // The invocation deadline sits INSIDE the span, so a request that runs
69 // past the Function's `timeout` is interrupted within it: the `http.server`
70 // span ends with `InvocationTimeoutError`, with every child span ended by
71 // the interruption. No response is sent: the dispatcher holds the
72 // invocation until Lambda's own timeout answers it. The dispatcher's outer
73 // guard stands down when this one takes the deadline; see
74 // `withInvocationDeadline`.
75 const safeHandler = handler.pipe(
76 Http.safeHttpEffect,
77 withInvocationDeadline(),
78 annotateRequestSpan,
79 HttpMiddleware.tracer,
80 );
81 return (
82 event: any,
83 ):
84 | Effect.Effect<
85 ALBResult | APIGatewayProxyResult | LambdaFunctionURLResult | FunctionURLStream,
86 InvocationTimeoutError,
87 Exclude<Effect.Services<typeof handler>, HttpServerRequest.HttpServerRequest | Scope>
88 >
89 | undefined => {
90 if (isFunctionURLEvent(event)) {
91 const webRequest = functionUrlEventToWebRequest(event);
92 const request = HttpServerRequest.fromWeb(webRequest).modify({
93 url: webRequest.url,
94 remoteAddress: Option.some(event.requestContext.http.sourceIp),
95 });
96 // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- safeHandler handles failures other than the invocation deadline; generic Exclude on R can't be proven statically
97 return safeHandler.pipe(
98 Effect.provideService(HttpServerRequest.HttpServerRequest, request),
99 Effect.flatMap((response): Effect.Effect<LambdaFunctionURLResult | FunctionURLStream> =>
100 options.responseStream
101 ? toFunctionURLStream(response)
102 : toLambdaFunctionURLResult(response),
103 ),
104 ) as Effect.Effect<
105 LambdaFunctionURLResult | FunctionURLStream,
106 InvocationTimeoutError,
107 Exclude<Effect.Services<typeof handler>, HttpServerRequest.HttpServerRequest | Scope>
108 >;
109 }
110 if (isAlbEvent(event)) {
111 const webRequest = albEventToWebRequest(event);
112 const request = HttpServerRequest.fromWeb(webRequest).modify({
113 url: webRequest.url,
114 });
115 // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- safeHandler handles failures other than the invocation deadline; generic Exclude on R can't be proven statically
116 return safeHandler.pipe(
117 Effect.provideService(HttpServerRequest.HttpServerRequest, request),
118 // The ALB result shape is the API Gateway v1 result shape (statusCode,
119 // headers, multiValueHeaders, body, isBase64Encoded); ALB reads
120 // whichever of headers/multiValueHeaders matches the target group's
121 // multi-value-headers setting.
122 Effect.flatMap(toApiGatewayProxyResult),
123 ) as Effect.Effect<
124 ALBResult,
125 InvocationTimeoutError,
126 Exclude<Effect.Services<typeof handler>, HttpServerRequest.HttpServerRequest | Scope>
127 >;
128 }
129 if (isApiGatewayProxyEvent(event)) {
130 const webRequest = apiGatewayProxyEventToWebRequest(event);
131 const request = HttpServerRequest.fromWeb(webRequest).modify({
132 url: webRequest.url,
133 remoteAddress: Option.fromNullishOr(event.requestContext?.identity?.sourceIp),
134 });
135 // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- safeHandler handles failures other than the invocation deadline; generic Exclude on R can't be proven statically
136 return safeHandler.pipe(
137 Effect.provideService(HttpServerRequest.HttpServerRequest, request),
138 Effect.flatMap(toApiGatewayProxyResult),
139 ) as Effect.Effect<
140 APIGatewayProxyResult,
141 InvocationTimeoutError,
142 Exclude<Effect.Services<typeof handler>, HttpServerRequest.HttpServerRequest | Scope>
143 >;
144 }
145 };
146 };
147
148 const functionUrlEventToWebRequest = (event: LambdaFunctionURLEvent): Request => {
149 // `requestContext.http.protocol` is the HTTP version ("HTTP/1.1"), never a
150 // URL scheme — without `x-forwarded-proto` (real Function URLs always set
151 // it; local emulators may not) fall back to https.
152 const protocol = event.headers["x-forwarded-proto"] ?? "https";
153 const host = event.headers.host ?? event.requestContext.domainName;
154 const url = `${protocol}://${host}${event.rawPath}${event.rawQueryString ? `?${event.rawQueryString}` : ""}`;
155 const method = event.requestContext.http.method;
156 const headers = new Headers();
157 for (const [key, value] of Object.entries(event.headers)) {
158 if (value !== undefined) {
159 headers.set(key, value);
160 }
161 }
162 if (event.cookies?.length) {
163 headers.set("cookie", event.cookies.join("; "));
164 }
165
166 let body: string | ArrayBuffer | undefined;
167 if (event.body !== undefined) {
168 body = event.isBase64Encoded
169 ? Uint8Array.from(atob(event.body), (c) => c.charCodeAt(0)).buffer
170 : event.body;
171 }
172
173 return new Request(url, {
174 method,
175 headers,
176 body: body && method !== "GET" && method !== "HEAD" ? body : undefined,
177 });
178 };
179
180 const albEventToWebRequest = (event: ALBEvent): Request => {
181 const headers = new Headers();
182 if (event.multiValueHeaders) {
183 for (const [key, values] of Object.entries(event.multiValueHeaders)) {
184 if (!values) continue;
185 for (const value of values) {
186 if (value !== undefined && value !== null) {
187 headers.append(key, value);
188 }
189 }
190 }
191 }
192 if (event.headers) {
193 for (const [key, value] of Object.entries(event.headers)) {
194 if (value !== undefined && value !== null && !headers.has(key)) {
195 headers.set(key, value);
196 }
197 }
198 }
199
200 const protocol = headers.get("x-forwarded-proto") ?? headers.get("X-Forwarded-Proto") ?? "http";
201 const host = headers.get("host") ?? headers.get("Host") ?? "alb";
202
203 // Unlike API Gateway, ALB does NOT URL-decode the path or query-string
204 // parameters — they arrive still percent-encoded, so join them verbatim
205 // (re-encoding would double-encode).
206 const queryParts: string[] = [];
207 if (event.multiValueQueryStringParameters) {
208 for (const [k, vs] of Object.entries(event.multiValueQueryStringParameters)) {
209 if (!vs) continue;
210 for (const v of vs) {
211 queryParts.push(`${k}=${v ?? ""}`);
212 }
213 }
214 } else if (event.queryStringParameters) {
215 for (const [k, v] of Object.entries(event.queryStringParameters)) {
216 if (v === undefined || v === null) continue;
217 queryParts.push(`${k}=${v}`);
218 }
219 }
220 const queryString = queryParts.length > 0 ? `?${queryParts.join("&")}` : "";
221
222 const url = `${protocol}://${host}${event.path ?? "/"}${queryString}`;
223 const method = event.httpMethod;
224
225 let body: string | ArrayBuffer | undefined;
226 if (event.body !== null && event.body !== undefined) {
227 body = event.isBase64Encoded
228 ? Uint8Array.from(atob(event.body), (c) => c.charCodeAt(0)).buffer
229 : event.body;
230 }
231
232 return new Request(url, {
233 method,
234 headers,
235 body: body && method !== "GET" && method !== "HEAD" ? body : undefined,
236 });
237 };
238
239 const apiGatewayProxyEventToWebRequest = (event: APIGatewayProxyEvent): Request => {
240 const headers = new Headers();
241 if (event.multiValueHeaders) {
242 for (const [key, values] of Object.entries(event.multiValueHeaders)) {
243 if (!values) continue;
244 for (const value of values) {
245 if (value !== undefined && value !== null) {
246 headers.append(key, value);
247 }
248 }
249 }
250 }
251 if (event.headers) {
252 for (const [key, value] of Object.entries(event.headers)) {
253 if (value !== undefined && value !== null && !headers.has(key)) {
254 headers.set(key, value);
255 }
256 }
257 }
258
259 const protocol = headers.get("x-forwarded-proto") ?? headers.get("X-Forwarded-Proto") ?? "https";
260 const host =
261 headers.get("host") ?? headers.get("Host") ?? event.requestContext.domainName ?? "lambda";
262 const stage = event.requestContext.stage;
263 // API Gateway prefixes paths with the stage when invoked via the default
264 // execute-api endpoint; `event.path` already contains that. Use it as-is.
265 const path = event.path ?? "/";
266
267 const queryParts: string[] = [];
268 if (event.multiValueQueryStringParameters) {
269 for (const [k, vs] of Object.entries(event.multiValueQueryStringParameters)) {
270 if (!vs) continue;
271 for (const v of vs) {
272 queryParts.push(`${encodeURIComponent(k)}=${encodeURIComponent(v ?? "")}`);
273 }
274 }
275 } else if (event.queryStringParameters) {
276 for (const [k, v] of Object.entries(event.queryStringParameters)) {
277 if (v === undefined || v === null) continue;
278 queryParts.push(`${encodeURIComponent(k)}=${encodeURIComponent(v)}`);
279 }
280 }
281 const queryString = queryParts.length > 0 ? `?${queryParts.join("&")}` : "";
282
283 const url = `${protocol}://${host}${path}${queryString}`;
284 const method = event.httpMethod;
285
286 let body: string | ArrayBuffer | undefined;
287 if (event.body !== null && event.body !== undefined) {
288 body = event.isBase64Encoded
289 ? Uint8Array.from(atob(event.body), (c) => c.charCodeAt(0)).buffer
290 : event.body;
291 }
292
293 // Reference `stage` so static analysis sees it as used; the variable is
294 // useful when constructing fully-qualified URLs in downstream code.
295 void stage;
296
297 return new Request(url, {
298 method,
299 headers,
300 body: body && method !== "GET" && method !== "HEAD" ? body : undefined,
301 });
302 };
303
304 const toLambdaFunctionURLResult = (
305 response: HttpServerResponse.HttpServerResponse,
306 ): Effect.Effect<LambdaFunctionURLResult> =>
307 Effect.gen(function* () {
308 const context = yield* Effect.context();
309 const webResponse = HttpServerResponse.toWeb(response, { context });
310 const headers = new Headers(webResponse.headers);
311 const cookies = typeof headers.getSetCookie === "function" ? headers.getSetCookie() : [];
312
313 headers.delete("set-cookie");
314
315 if (!webResponse.body) {
316 return {
317 statusCode: webResponse.status,
318 headers: Object.fromEntries(headers.entries()),
319 cookies: cookies.length > 0 ? cookies : undefined,
320 };
321 }
322
323 const bytes = new Uint8Array(yield* Effect.promise(() => webResponse.arrayBuffer()));
324 const isTextual = isTextualContentType(headers.get("content-type"));
325 const body =
326 bytes.length === 0
327 ? undefined
328 : isTextual
329 ? new TextDecoder().decode(bytes)
330 : Buffer.from(bytes).toString("base64");
331
332 return {
333 statusCode: webResponse.status,
334 headers: Object.fromEntries(headers.entries()),
335 body,
336 cookies: cookies.length > 0 ? cookies : undefined,
337 isBase64Encoded: body !== undefined && !isTextual ? true : undefined,
338 };
339 });
340
341 const toApiGatewayProxyResult = (
342 response: HttpServerResponse.HttpServerResponse,
343 ): Effect.Effect<APIGatewayProxyResult> =>
344 Effect.gen(function* () {
345 const context = yield* Effect.context();
346 const webResponse = HttpServerResponse.toWeb(response, { context });
347 const headers = new Headers(webResponse.headers);
348
349 const multiValueHeaders: { [name: string]: string[] } = {};
350 const singleHeaders: { [name: string]: string } = {};
351 for (const [key, value] of headers.entries()) {
352 if (multiValueHeaders[key]) {
353 multiValueHeaders[key].push(value);
354 } else {
355 multiValueHeaders[key] = [value];
356 singleHeaders[key] = value;
357 }
358 }
359
360 if (!webResponse.body) {
361 return {
362 statusCode: webResponse.status,
363 headers: singleHeaders,
364 multiValueHeaders,
365 body: "",
366 };
367 }
368
369 const bytes = new Uint8Array(yield* Effect.promise(() => webResponse.arrayBuffer()));
370 const isTextual = isTextualContentType(headers.get("content-type"));
371 const isBase64 = bytes.length > 0 && !isTextual;
372 const body =
373 bytes.length === 0
374 ? ""
375 : isTextual
376 ? new TextDecoder().decode(bytes)
377 : Buffer.from(bytes).toString("base64");
378
379 return {
380 statusCode: webResponse.status,
381 headers: singleHeaders,
382 multiValueHeaders,
383 body,
384 isBase64Encoded: isBase64,
385 };
386 });
387
388 const isTextualContentType = (contentType: string | null): boolean => {
389 if (!contentType) {
390 return false;
391 }
392
393 const normalized = contentType.toLowerCase();
394 return (
395 normalized.startsWith("text/") ||
396 normalized.includes("json") ||
397 normalized.includes("xml") ||
398 normalized.includes("javascript") ||
399 normalized.includes("form-urlencoded")
400 );
401 };
402
403 /**
404 * Set by the deploy when the Function URL uses `invokeMode:
405 * "RESPONSE_STREAM"`; the runtime then exports a streaming handler.
406 */
407 export const RESPONSE_STREAM_ENV = "ALCHEMY_LAMBDA_RESPONSE_STREAM";
408
409 interface ResponseStreamMetadata {
410 statusCode: number;
411 headers: Record<string, string>;
412 cookies?: string[];
413 }
414
415 /** The `awslambda` global the Lambda Node.js runtime installs. */
416 interface AwsLambdaGlobal {
417 streamifyResponse: (
418 handler: (event: any, responseStream: NodeJS.WritableStream, context: any) => Promise<void>,
419 ) => (event: any, context: any) => Promise<any>;
420 HttpResponseStream: {
421 from: (
422 stream: NodeJS.WritableStream,
423 metadata: ResponseStreamMetadata,
424 ) => NodeJS.WritableStream;
425 };
426 }
427
428 const awslambda = () => (globalThis as unknown as { awslambda?: AwsLambdaGlobal }).awslambda;
429
430 /**
431 * Whether this sandbox serves a `RESPONSE_STREAM` Function URL. Dies on a
432 * malformed flag: the deploy writes it, so a bad value is a deploy bug, not
433 * something a handler can recover from.
434 */
435 export const isResponseStreaming: Effect.Effect<boolean> = Config.Boolean(RESPONSE_STREAM_ENV).pipe(
436 Config.withDefault(false),
437 Effect.map((streaming) => streaming && awslambda() !== undefined),
438 Effect.orDie,
439 );
440
441 /** A Function URL response whose body is still being produced. */
442 interface FunctionURLStream {
443 readonly _tag: "FunctionURLStream";
444 readonly metadata: ResponseStreamMetadata;
445 readonly body: ReadableStream<Uint8Array> | null;
446 }
447
448 // As in the Cloudflare Worker bridge, the body stream takes over the request
449 // scope and closes it when it finishes: the dispatcher returns as soon as
450 // the headers are ready, and sees the scope as ejected.
451 const toFunctionURLStream = (
452 response: HttpServerResponse.HttpServerResponse,
453 ): Effect.Effect<FunctionURLStream> =>
454 Effect.map(Effect.context(), (context) => {
455 const webResponse = HttpServerResponse.toWeb(HttpEffect.scopeTransferToStream(response), {
456 context,
457 });
458 const headers = new Headers(webResponse.headers);
459 const cookies = headers.getSetCookie();
460 headers.delete("set-cookie");
461 return {
462 _tag: "FunctionURLStream",
463 metadata: {
464 statusCode: webResponse.status,
465 headers: Object.fromEntries(headers.entries()),
466 ...(cookies.length > 0 ? { cookies } : {}),
467 },
468 body: webResponse.body,
469 };
470 });
471
472 const isFunctionURLStream = (result: unknown): result is FunctionURLStream =>
473 (result as FunctionURLStream | undefined)?._tag === "FunctionURLStream";
474
475 /**
476 * Wrap the Lambda dispatcher with `awslambda.streamifyResponse`. A Function
477 * URL response is piped into the response stream as its body is produced;
478 * any other listener's result (an SQS batch response, a direct `Invoke`) is
479 * written as JSON, which a buffered `Invoke` returns as its payload.
480 */
481 export const streamifyHandler = (dispatch: (event: any, context: any) => Promise<unknown>) => {
482 const aws = awslambda()!;
483 return aws.streamifyResponse(async (event, responseStream, context) => {
484 const result = await dispatch(event, context);
485 if (!isFunctionURLStream(result)) {
486 responseStream.end(JSON.stringify(result) ?? "");
487 return;
488 }
489 const stream = aws.HttpResponseStream.from(responseStream, result.metadata);
490 if (result.body === null) {
491 // The metadata prelude is only flushed by a write.
492 stream.end("");
493 return;
494 }
495 await pipeline(Readable.fromWeb(result.body as unknown as NodeReadableStream), stream);
496 });
497 };