sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ApiGateway/ RestApiEventSource.ts

import type * as lambda from "aws-lambda";
import * as Context from "effect/Context";
import type * as Effect from "effect/Effect";
import type { RestApi } from "./RestApi.ts";

/**
 * The event shape a REST API route handler receives — the API Gateway v1
 * Lambda proxy event (`httpMethod`, `resource`, `pathParameters`, `body`,
 * `requestContext`, …).
 */
export type RestApiEvent = lambda.APIGatewayProxyEvent;

/**
 * The result a REST API route handler may return. Returning `void` means
 * `{ statusCode: 200, body: "" }`.
 */
export type RestApiResult = lambda.APIGatewayProxyResult | undefined | void;

export interface RestApiRouteProps {
  /**
   * The resource path this handler serves, e.g. `/`, `/items`, or a greedy
   * proxy like `/{proxy+}`. Intermediate path segments are materialized as
   * `ApiGateway.Resource`s automatically.
   * @default "/"
   */
  path?: string;
  /**
   * The HTTP verb to serve (`GET`, `POST`, …) or `ANY` for all verbs.
   * @default "ANY"
   */
  httpMethod?: string;
}

export type RestApiEventSourceService = <Req = never>(
  api: RestApi,
  props: RestApiRouteProps,
  handler: (event: RestApiEvent) => Effect.Effect<RestApiResult, never, Req>,
) => Effect.Effect<void, never, never>;

/**
 * Event source connecting a {@link RestApi} route to the hosting Lambda
 * function.
 *
 * At deploy time the Lambda implementation (`Lambda.RestApiEventSource`)
 * materializes the path `Resource`s, the `Method` with an `AWS_PROXY`
 * integration, and the invoke `Permission` for the route — and registers
 * each of them as bindings on the API so any `Deployment` of the same API
 * is ordered after them. At runtime it dispatches matching REST proxy
 * events to the handler. Subscribe routes with {@link onRestApiRoute} and
 * provide `Lambda.RestApiEventSource` on the hosting function.
 *
 * ### Handling REST API routes
 * **Example:** Serve GET /items from a Lambda
 * ```typescript
 * export default MyFunction.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const api = yield* ApiGateway.RestApi("Api", {
 *       endpointConfiguration: { types: ["REGIONAL"] },
 *     });
 *
 *     yield* ApiGateway.onRestApiRoute(
 *       api,
 *       { path: "/items", httpMethod: "GET" },
 *       (event) =>
 *         Effect.succeed({
 *           statusCode: 200,
 *           body: JSON.stringify({ items: [] }),
 *         }),
 *     );
 *
 *     const deployment = yield* ApiGateway.Deployment("Release", {
 *       restApi: api,
 *     });
 *     yield* ApiGateway.Stage("Prod", {
 *       restApi: api,
 *       stageName: "prod",
 *       deploymentId: deployment.deploymentId,
 *     });
 *
 *     return {};
 *   }).pipe(Effect.provide(Lambda.RestApiEventSource)),
 * );
 * ```
 *
 * @binding
 */
export class RestApiEventSource extends Context.Service<
  RestApiEventSource,
  RestApiEventSourceService
>()("AWS.ApiGateway.RestApiEventSource") {}

/**
 * Subscribe an Effect handler to a route of an API Gateway v1
 * {@link RestApi}.
 *
 * Provide `Lambda.RestApiEventSource` on the hosting function to satisfy
 * the requirement.
 *
 * @param api The REST API.
 * @param props The path + verb to serve.
 * @param handler Invoked once per proxy event for the route.
 *
 * @example
 * ```typescript
 * yield* ApiGateway.onRestApiRoute(api, { path: "/", httpMethod: "GET" }, () =>
 *   Effect.succeed({ statusCode: 200, body: "ok" }),
 * );
 * ```
 */
export function onRestApiRoute<Req = never>(
  api: RestApi,
  props: RestApiRouteProps,
  handler: (event: RestApiEvent) => Effect.Effect<RestApiResult, never, Req>,
): Effect.Effect<void, never, RestApiEventSource> {
  return RestApiEventSource.use((source) => source(api, props, handler));
}