sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Lambda/ HttpServer.ts

import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
import type { ReadableStream as NodeReadableStream } from "node:stream/web";
import * as Http from "alchemy/Http";
import type {
  ALBEvent,
  ALBResult,
  APIGatewayProxyEvent,
  APIGatewayProxyResult,
  LambdaFunctionURLEvent,
  LambdaFunctionURLResult,
} from "aws-lambda";
import * as Config from "effect/Config";
import * as Effect from "effect/Effect";
import * as HttpEffect from "effect/http/HttpEffect";
import * as HttpMiddleware from "effect/http/HttpMiddleware";
import * as HttpServerRequest from "effect/http/HttpServerRequest";
import * as HttpServerResponse from "effect/http/HttpServerResponse";
import * as Option from "effect/Option";
import type { Scope } from "effect/Scope";
import { type InvocationTimeoutError, withInvocationDeadline } from "./InvocationDeadline.ts";

export const isFunctionURLEvent = (event: any): event is LambdaFunctionURLEvent =>
  event.requestContext?.http?.method !== undefined;

/**
 * REST API (v1) AWS_PROXY events have a top-level `httpMethod` and a
 * `requestContext.resourcePath` field. They lack the `requestContext.http.*`
 * shape of Function URL / HTTP API (v2) events.
 */
export const isApiGatewayProxyEvent = (event: any): event is APIGatewayProxyEvent =>
  typeof event?.httpMethod === "string" && event?.requestContext?.resourcePath !== undefined;

/**
 * Application Load Balancer target events carry a `requestContext.elb` marker
 * (the target group ARN) and a top-level `httpMethod` + `path`.
 */
export const isAlbEvent = (event: any): event is ALBEvent =>
  typeof event?.httpMethod === "string" && event?.requestContext?.elb !== undefined;

// `HttpMiddleware.tracer` records the request on the `http.server` span only
// when the request finishes. A span the backstop flush ends early would ship
// without it, so record the method and path up front.
const annotateRequestSpan = <A, E, R>(self: Effect.Effect<A, E, R>) =>
  Effect.gen(function* () {
    const request = yield* HttpServerRequest.HttpServerRequest;
    const span = yield* Effect.option(Effect.currentSpan);
    if (Option.isSome(span)) {
      span.value.attribute("http.request.method", request.method);
      span.value.attribute("url.path", new URL(request.url, "http://localhost").pathname);
    }
    return yield* self;
  });

export const makeFunctionHttpHandler = <Req>(
  handler: Http.HttpEffect<Req>,
  options: {
    /** Return Function URL responses as a {@link FunctionURLStream}. */
    responseStream?: boolean;
  } = {},
) => {
  // `HttpMiddleware.tracer` creates the `http.server` root span per request
  // (continuing an incoming `traceparent`), matching the Worker bridge's
  // fetch path. With the default no-op tracer this is free; with a telemetry
  // exporter installed the span is exported when the invocation scope
  // flushes.
  //
  // The invocation deadline sits INSIDE the span, so a request that runs
  // past the Function's `timeout` is interrupted within it: the `http.server`
  // span ends with `InvocationTimeoutError`, with every child span ended by
  // the interruption. No response is sent: the dispatcher holds the
  // invocation until Lambda's own timeout answers it. The dispatcher's outer
  // guard stands down when this one takes the deadline; see
  // `withInvocationDeadline`.
  const safeHandler = handler.pipe(
    Http.safeHttpEffect,
    withInvocationDeadline(),
    annotateRequestSpan,
    HttpMiddleware.tracer,
  );
  return (
    event: any,
  ):
    | Effect.Effect<
        ALBResult | APIGatewayProxyResult | LambdaFunctionURLResult | FunctionURLStream,
        InvocationTimeoutError,
        Exclude<Effect.Services<typeof handler>, HttpServerRequest.HttpServerRequest | Scope>
      >
    | undefined => {
    if (isFunctionURLEvent(event)) {
      const webRequest = functionUrlEventToWebRequest(event);
      const request = HttpServerRequest.fromWeb(webRequest).modify({
        url: webRequest.url,
        remoteAddress: Option.some(event.requestContext.http.sourceIp),
      });
      // 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
      return safeHandler.pipe(
        Effect.provideService(HttpServerRequest.HttpServerRequest, request),
        Effect.flatMap((response): Effect.Effect<LambdaFunctionURLResult | FunctionURLStream> =>
          options.responseStream
            ? toFunctionURLStream(response)
            : toLambdaFunctionURLResult(response),
        ),
      ) as Effect.Effect<
        LambdaFunctionURLResult | FunctionURLStream,
        InvocationTimeoutError,
        Exclude<Effect.Services<typeof handler>, HttpServerRequest.HttpServerRequest | Scope>
      >;
    }
    if (isAlbEvent(event)) {
      const webRequest = albEventToWebRequest(event);
      const request = HttpServerRequest.fromWeb(webRequest).modify({
        url: webRequest.url,
      });
      // 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
      return safeHandler.pipe(
        Effect.provideService(HttpServerRequest.HttpServerRequest, request),
        // The ALB result shape is the API Gateway v1 result shape (statusCode,
        // headers, multiValueHeaders, body, isBase64Encoded); ALB reads
        // whichever of headers/multiValueHeaders matches the target group's
        // multi-value-headers setting.
        Effect.flatMap(toApiGatewayProxyResult),
      ) as Effect.Effect<
        ALBResult,
        InvocationTimeoutError,
        Exclude<Effect.Services<typeof handler>, HttpServerRequest.HttpServerRequest | Scope>
      >;
    }
    if (isApiGatewayProxyEvent(event)) {
      const webRequest = apiGatewayProxyEventToWebRequest(event);
      const request = HttpServerRequest.fromWeb(webRequest).modify({
        url: webRequest.url,
        remoteAddress: Option.fromNullishOr(event.requestContext?.identity?.sourceIp),
      });
      // 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
      return safeHandler.pipe(
        Effect.provideService(HttpServerRequest.HttpServerRequest, request),
        Effect.flatMap(toApiGatewayProxyResult),
      ) as Effect.Effect<
        APIGatewayProxyResult,
        InvocationTimeoutError,
        Exclude<Effect.Services<typeof handler>, HttpServerRequest.HttpServerRequest | Scope>
      >;
    }
  };
};

const functionUrlEventToWebRequest = (event: LambdaFunctionURLEvent): Request => {
  // `requestContext.http.protocol` is the HTTP version ("HTTP/1.1"), never a
  // URL scheme — without `x-forwarded-proto` (real Function URLs always set
  // it; local emulators may not) fall back to https.
  const protocol = event.headers["x-forwarded-proto"] ?? "https";
  const host = event.headers.host ?? event.requestContext.domainName;
  const url = `${protocol}://${host}${event.rawPath}${event.rawQueryString ? `?${event.rawQueryString}` : ""}`;
  const method = event.requestContext.http.method;
  const headers = new Headers();
  for (const [key, value] of Object.entries(event.headers)) {
    if (value !== undefined) {
      headers.set(key, value);
    }
  }
  if (event.cookies?.length) {
    headers.set("cookie", event.cookies.join("; "));
  }

  let body: string | ArrayBuffer | undefined;
  if (event.body !== undefined) {
    body = event.isBase64Encoded
      ? Uint8Array.from(atob(event.body), (c) => c.charCodeAt(0)).buffer
      : event.body;
  }

  return new Request(url, {
    method,
    headers,
    body: body && method !== "GET" && method !== "HEAD" ? body : undefined,
  });
};

const albEventToWebRequest = (event: ALBEvent): Request => {
  const headers = new Headers();
  if (event.multiValueHeaders) {
    for (const [key, values] of Object.entries(event.multiValueHeaders)) {
      if (!values) continue;
      for (const value of values) {
        if (value !== undefined && value !== null) {
          headers.append(key, value);
        }
      }
    }
  }
  if (event.headers) {
    for (const [key, value] of Object.entries(event.headers)) {
      if (value !== undefined && value !== null && !headers.has(key)) {
        headers.set(key, value);
      }
    }
  }

  const protocol = headers.get("x-forwarded-proto") ?? headers.get("X-Forwarded-Proto") ?? "http";
  const host = headers.get("host") ?? headers.get("Host") ?? "alb";

  // Unlike API Gateway, ALB does NOT URL-decode the path or query-string
  // parameters — they arrive still percent-encoded, so join them verbatim
  // (re-encoding would double-encode).
  const queryParts: string[] = [];
  if (event.multiValueQueryStringParameters) {
    for (const [k, vs] of Object.entries(event.multiValueQueryStringParameters)) {
      if (!vs) continue;
      for (const v of vs) {
        queryParts.push(`${k}=${v ?? ""}`);
      }
    }
  } else if (event.queryStringParameters) {
    for (const [k, v] of Object.entries(event.queryStringParameters)) {
      if (v === undefined || v === null) continue;
      queryParts.push(`${k}=${v}`);
    }
  }
  const queryString = queryParts.length > 0 ? `?${queryParts.join("&")}` : "";

  const url = `${protocol}://${host}${event.path ?? "/"}${queryString}`;
  const method = event.httpMethod;

  let body: string | ArrayBuffer | undefined;
  if (event.body !== null && event.body !== undefined) {
    body = event.isBase64Encoded
      ? Uint8Array.from(atob(event.body), (c) => c.charCodeAt(0)).buffer
      : event.body;
  }

  return new Request(url, {
    method,
    headers,
    body: body && method !== "GET" && method !== "HEAD" ? body : undefined,
  });
};

const apiGatewayProxyEventToWebRequest = (event: APIGatewayProxyEvent): Request => {
  const headers = new Headers();
  if (event.multiValueHeaders) {
    for (const [key, values] of Object.entries(event.multiValueHeaders)) {
      if (!values) continue;
      for (const value of values) {
        if (value !== undefined && value !== null) {
          headers.append(key, value);
        }
      }
    }
  }
  if (event.headers) {
    for (const [key, value] of Object.entries(event.headers)) {
      if (value !== undefined && value !== null && !headers.has(key)) {
        headers.set(key, value);
      }
    }
  }

  const protocol = headers.get("x-forwarded-proto") ?? headers.get("X-Forwarded-Proto") ?? "https";
  const host =
    headers.get("host") ?? headers.get("Host") ?? event.requestContext.domainName ?? "lambda";
  const stage = event.requestContext.stage;
  // API Gateway prefixes paths with the stage when invoked via the default
  // execute-api endpoint; `event.path` already contains that. Use it as-is.
  const path = event.path ?? "/";

  const queryParts: string[] = [];
  if (event.multiValueQueryStringParameters) {
    for (const [k, vs] of Object.entries(event.multiValueQueryStringParameters)) {
      if (!vs) continue;
      for (const v of vs) {
        queryParts.push(`${encodeURIComponent(k)}=${encodeURIComponent(v ?? "")}`);
      }
    }
  } else if (event.queryStringParameters) {
    for (const [k, v] of Object.entries(event.queryStringParameters)) {
      if (v === undefined || v === null) continue;
      queryParts.push(`${encodeURIComponent(k)}=${encodeURIComponent(v)}`);
    }
  }
  const queryString = queryParts.length > 0 ? `?${queryParts.join("&")}` : "";

  const url = `${protocol}://${host}${path}${queryString}`;
  const method = event.httpMethod;

  let body: string | ArrayBuffer | undefined;
  if (event.body !== null && event.body !== undefined) {
    body = event.isBase64Encoded
      ? Uint8Array.from(atob(event.body), (c) => c.charCodeAt(0)).buffer
      : event.body;
  }

  // Reference `stage` so static analysis sees it as used; the variable is
  // useful when constructing fully-qualified URLs in downstream code.
  void stage;

  return new Request(url, {
    method,
    headers,
    body: body && method !== "GET" && method !== "HEAD" ? body : undefined,
  });
};

const toLambdaFunctionURLResult = (
  response: HttpServerResponse.HttpServerResponse,
): Effect.Effect<LambdaFunctionURLResult> =>
  Effect.gen(function* () {
    const context = yield* Effect.context();
    const webResponse = HttpServerResponse.toWeb(response, { context });
    const headers = new Headers(webResponse.headers);
    const cookies = typeof headers.getSetCookie === "function" ? headers.getSetCookie() : [];

    headers.delete("set-cookie");

    if (!webResponse.body) {
      return {
        statusCode: webResponse.status,
        headers: Object.fromEntries(headers.entries()),
        cookies: cookies.length > 0 ? cookies : undefined,
      };
    }

    const bytes = new Uint8Array(yield* Effect.promise(() => webResponse.arrayBuffer()));
    const isTextual = isTextualContentType(headers.get("content-type"));
    const body =
      bytes.length === 0
        ? undefined
        : isTextual
          ? new TextDecoder().decode(bytes)
          : Buffer.from(bytes).toString("base64");

    return {
      statusCode: webResponse.status,
      headers: Object.fromEntries(headers.entries()),
      body,
      cookies: cookies.length > 0 ? cookies : undefined,
      isBase64Encoded: body !== undefined && !isTextual ? true : undefined,
    };
  });

const toApiGatewayProxyResult = (
  response: HttpServerResponse.HttpServerResponse,
): Effect.Effect<APIGatewayProxyResult> =>
  Effect.gen(function* () {
    const context = yield* Effect.context();
    const webResponse = HttpServerResponse.toWeb(response, { context });
    const headers = new Headers(webResponse.headers);

    const multiValueHeaders: { [name: string]: string[] } = {};
    const singleHeaders: { [name: string]: string } = {};
    for (const [key, value] of headers.entries()) {
      if (multiValueHeaders[key]) {
        multiValueHeaders[key].push(value);
      } else {
        multiValueHeaders[key] = [value];
        singleHeaders[key] = value;
      }
    }

    if (!webResponse.body) {
      return {
        statusCode: webResponse.status,
        headers: singleHeaders,
        multiValueHeaders,
        body: "",
      };
    }

    const bytes = new Uint8Array(yield* Effect.promise(() => webResponse.arrayBuffer()));
    const isTextual = isTextualContentType(headers.get("content-type"));
    const isBase64 = bytes.length > 0 && !isTextual;
    const body =
      bytes.length === 0
        ? ""
        : isTextual
          ? new TextDecoder().decode(bytes)
          : Buffer.from(bytes).toString("base64");

    return {
      statusCode: webResponse.status,
      headers: singleHeaders,
      multiValueHeaders,
      body,
      isBase64Encoded: isBase64,
    };
  });

const isTextualContentType = (contentType: string | null): boolean => {
  if (!contentType) {
    return false;
  }

  const normalized = contentType.toLowerCase();
  return (
    normalized.startsWith("text/") ||
    normalized.includes("json") ||
    normalized.includes("xml") ||
    normalized.includes("javascript") ||
    normalized.includes("form-urlencoded")
  );
};

/**
 * Set by the deploy when the Function URL uses `invokeMode:
 * "RESPONSE_STREAM"`; the runtime then exports a streaming handler.
 */
export const RESPONSE_STREAM_ENV = "ALCHEMY_LAMBDA_RESPONSE_STREAM";

interface ResponseStreamMetadata {
  statusCode: number;
  headers: Record<string, string>;
  cookies?: string[];
}

/** The `awslambda` global the Lambda Node.js runtime installs. */
interface AwsLambdaGlobal {
  streamifyResponse: (
    handler: (event: any, responseStream: NodeJS.WritableStream, context: any) => Promise<void>,
  ) => (event: any, context: any) => Promise<any>;
  HttpResponseStream: {
    from: (
      stream: NodeJS.WritableStream,
      metadata: ResponseStreamMetadata,
    ) => NodeJS.WritableStream;
  };
}

const awslambda = () => (globalThis as unknown as { awslambda?: AwsLambdaGlobal }).awslambda;

/**
 * Whether this sandbox serves a `RESPONSE_STREAM` Function URL. Dies on a
 * malformed flag: the deploy writes it, so a bad value is a deploy bug, not
 * something a handler can recover from.
 */
export const isResponseStreaming: Effect.Effect<boolean> = Config.Boolean(RESPONSE_STREAM_ENV).pipe(
  Config.withDefault(false),
  Effect.map((streaming) => streaming && awslambda() !== undefined),
  Effect.orDie,
);

/** A Function URL response whose body is still being produced. */
interface FunctionURLStream {
  readonly _tag: "FunctionURLStream";
  readonly metadata: ResponseStreamMetadata;
  readonly body: ReadableStream<Uint8Array> | null;
}

// As in the Cloudflare Worker bridge, the body stream takes over the request
// scope and closes it when it finishes: the dispatcher returns as soon as
// the headers are ready, and sees the scope as ejected.
const toFunctionURLStream = (
  response: HttpServerResponse.HttpServerResponse,
): Effect.Effect<FunctionURLStream> =>
  Effect.map(Effect.context(), (context) => {
    const webResponse = HttpServerResponse.toWeb(HttpEffect.scopeTransferToStream(response), {
      context,
    });
    const headers = new Headers(webResponse.headers);
    const cookies = headers.getSetCookie();
    headers.delete("set-cookie");
    return {
      _tag: "FunctionURLStream",
      metadata: {
        statusCode: webResponse.status,
        headers: Object.fromEntries(headers.entries()),
        ...(cookies.length > 0 ? { cookies } : {}),
      },
      body: webResponse.body,
    };
  });

const isFunctionURLStream = (result: unknown): result is FunctionURLStream =>
  (result as FunctionURLStream | undefined)?._tag === "FunctionURLStream";

/**
 * Wrap the Lambda dispatcher with `awslambda.streamifyResponse`. A Function
 * URL response is piped into the response stream as its body is produced;
 * any other listener's result (an SQS batch response, a direct `Invoke`) is
 * written as JSON, which a buffered `Invoke` returns as its payload.
 */
export const streamifyHandler = (dispatch: (event: any, context: any) => Promise<unknown>) => {
  const aws = awslambda()!;
  return aws.streamifyResponse(async (event, responseStream, context) => {
    const result = await dispatch(event, context);
    if (!isFunctionURLStream(result)) {
      responseStream.end(JSON.stringify(result) ?? "");
      return;
    }
    const stream = aws.HttpResponseStream.from(responseStream, result.metadata);
    if (result.body === null) {
      // The metadata prelude is only flushed by a write.
      stream.end("");
      return;
    }
    await pipeline(Readable.fromWeb(result.body as unknown as NodeReadableStream), stream);
  });
};