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

import type * as LambdaWeb from "@distilled.cloud/aws/lambda-web";
import { deepEqual, isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import type { Providers } from "../Providers.ts";
import { connectorOfRevision, releaseEgressConnector, sameConnector } from "./WebFunctionEgress.ts";
import {
  deleteEndpoint,
  endpointIdentityChanged,
  endpointLimits,
  getEndpoint,
  latestRevisionId,
  servedRevisions,
  syncEndpoint,
  toEndpointName,
  validateWebFunctionSettings,
  type WebFunctionAuthType,
  type WebFunctionCanary,
  type WebFunctionEndpointType,
  type WebFunctionRevisionWeight,
} from "./WebFunctionEndpointSync.ts";

export const WebFunctionEndpointTypeId = "AWS.Lambda.WebFunctionEndpoint" as const;
export type WebFunctionEndpointTypeId = typeof WebFunctionEndpointTypeId;

/** The parts of a Web Function an endpoint routes to. */
export interface WebFunctionRef {
  functionName: string;
  revisionId: string;
}

/**
 * A resource or its declaration (e.g. a `WebFunction` class), which is
 * yielded for you.
 */
type Ref<T> = T | Effect.Effect<T, never, Providers>;

export interface WebFunctionEndpointProps {
  /**
   * The Web Function this endpoint serves: the `AWS.Lambda.WebFunction`
   * resource, or its class declaration. The endpoint routes traffic to the
   * function's latest revision and follows it on every deploy. Changing
   * the function recreates the endpoint, which gets a new URL.
   */
  function: Ref<WebFunctionRef>;
  /**
   * Name of the endpoint. Your server receives it in the
   * `lambda-web-endpoint-name` request header. Letters, digits, `-` and
   * `_`, up to 64 characters. Changing it recreates the endpoint, which gets
   * a new URL.
   * @default the logical ID
   */
  endpointName?: string;
  /**
   * Who may call the endpoint. `"ApplicationManaged"` forwards every request
   * (a public endpoint; authenticate in your application). `"IamAuth"`
   * requires SigV4-signed requests from principals with
   * `lambda:InvokeWebFunctionEndpoint`. Changes apply in place.
   */
  authType: WebFunctionAuthType;
  /**
   * Additional AWS Regions to serve from. When set, the endpoint is
   * `MultiRegion`: one global domain with latency-based routing across the
   * home Region and these Regions. Changing it recreates the endpoint, which
   * gets a new URL.
   */
  regions?: string[];
  /**
   * Maximum number of execution environments this endpoint uses per Region
   * (2–10,000). Endpoints scale independently. Changes apply in place.
   */
  maxEnvironments?: number;
  /**
   * Maximum requests per second this endpoint accepts, enforced per Region.
   * Excess requests receive HTTP 429; `0` disables the endpoint. Changes
   * apply in place.
   */
  rateLimit?: number;
  /**
   * Roll out deploys gradually on this endpoint: the revision a deploy
   * publishes gets `weight` percent of traffic and the revision the
   * endpoint served before keeps the rest. Set it to `100` (or remove
   * `canary`) to promote, or `0` to roll back. Independent of the function's
   * own `canary`.
   */
  canary?: WebFunctionCanary;
  /**
   * Description of the endpoint.
   */
  description?: string;
}

export interface WebFunctionEndpoint extends Resource<
  WebFunctionEndpointTypeId,
  WebFunctionEndpointProps,
  {
    /** Name of the Web Function the endpoint serves. */
    functionName: string;
    /** ARN of the Web Function the endpoint serves. */
    functionArn: string;
    /** Auth type of the endpoint. */
    authType: WebFunctionAuthType;
    /**
     * `HomeRegion`, or `MultiRegion` when `regions` is set: one global
     * domain that routes each request to the nearest Region.
     */
    endpointType: WebFunctionEndpointType;
    /** Name of the endpoint. */
    endpointName: string;
    /** ARN of the endpoint, the resource for `lambda:InvokeWebFunctionEndpoint`. */
    endpointArn: string;
    /** Lambda-allocated domain of the endpoint. */
    domainName: string;
    /** HTTPS URL of the endpoint (`https://<domainName>`). */
    url: string;
    /**
     * The function's latest revision, which the endpoint routes all traffic
     * to, or `canary.weight` percent while a canary runs.
     */
    revisionId: string;
    /**
     * How the endpoint splits traffic: one revision at 100, or the stable
     * revision and the canary while a canary runs.
     */
    revisionWeights: WebFunctionRevisionWeight[];
    /**
     * Requests per second the endpoint allows, as observed. Lets
     * `alchemy drift` detect out-of-band changes.
     */
    rateLimit?: number;
    /**
     * Cap on the endpoint's execution environments, as observed. Lets
     * `alchemy drift` detect out-of-band changes.
     */
    maxEnvironments?: number;
  },
  never,
  Providers
> {}

const WebFunctionEndpointResource = Resource<WebFunctionEndpoint>(WebFunctionEndpointTypeId);

/** Yield a `function` declaration so the endpoint references the resource. */
/** The settings Lambda limits, as numbers (Outputs resolve at deploy). */
const checkEndpointProps = (id: string, props: WebFunctionEndpointProps) =>
  validateWebFunctionSettings(`AWS.Lambda.WebFunctionEndpoint "${id}"`, {
    rateLimit: typeof props.rateLimit === "number" ? props.rateLimit : undefined,
    maxEnvironments: typeof props.maxEnvironments === "number" ? props.maxEnvironments : undefined,
    canary: typeof props.canary?.weight === "number" ? props.canary : undefined,
  });

const resolveEndpointProps = (
  id: string,
  props: WebFunctionEndpointProps | Effect.Effect<WebFunctionEndpointProps, never, Providers>,
): Effect.Effect<WebFunctionEndpointProps, never, Providers> =>
  Effect.gen(function* () {
    const resolved = Effect.isEffect(props) ? yield* props : props;
    if (globalThis.__ALCHEMY_RUNTIME__) return resolved;
    const fn = Effect.isEffect(resolved.function) ? yield* resolved.function : resolved.function;
    // Declaration props can't fail: surface the invalid value as a defect,
    // which still stops the plan with its message.
    yield* checkEndpointProps(id, resolved).pipe(
      Effect.catchTag("WebFunctionInvalidConfig", (e) => Effect.die(e)),
    );
    return { ...resolved, function: fn };
  });

/**
 * An additional HTTPS endpoint for an `AWS.Lambda.WebFunction`.
 *
 * Every Web Function has a built-in endpoint, configured on the function.
 * Add a `WebFunctionEndpoint` for each extra way in: its own URL, auth type,
 * environment cap, and rate limit. Endpoints scale independently of each
 * other but serve the same code, so a burst on one can't use up another's
 * environments. Your server tells them apart by the
 * `lambda-web-endpoint-name` request header, which callers can't forge.
 *
 * ### Adding an endpoint
 * **Example:** A public webhook endpoint next to a private one
 * ```typescript
 * const api = yield* AWS.Lambda.WebFunction("Api", {
 *   main: "./src/server.ts",
 *   authType: "IamAuth",
 * });
 *
 * const webhooks = yield* AWS.Lambda.WebFunctionEndpoint("Webhooks", {
 *   function: api,
 *   authType: "ApplicationManaged",
 *   rateLimit: 100,
 *   maxEnvironments: 2,
 * });
 *
 * webhooks.url; // https://<id>.<shard>.lambda-web.<region>.on.aws
 * ```
 *
 * **Example:** With a class-form Web Function
 * Pass the class itself (here `Api`, declared with
 * `class Api extends AWS.Lambda.WebFunction<Api>()(...)`); the endpoint
 * yields it for you.
 * ```typescript
 * const webhooks = yield* AWS.Lambda.WebFunctionEndpoint("Webhooks", {
 *   function: Api,
 *   authType: "ApplicationManaged",
 * });
 * ```
 *
 * ### Canary deploys
 * **Example:** Roll out to the public endpoint more slowly
 * ```typescript
 * // The function's own endpoint takes each deploy at once; this one
 * // sends 5% to the new revision until you raise or remove `canary`.
 * const webhooks = yield* AWS.Lambda.WebFunctionEndpoint("Webhooks", {
 *   function: api,
 *   authType: "ApplicationManaged",
 *   canary: { weight: 5 },
 * });
 * ```
 *
 * ### Routing by endpoint
 * **Example:** Serve only webhook routes on the public endpoint
 * ```typescript
 * // src/server.ts (a Hono app)
 * app.use(async (c, next) => {
 *   const endpoint = c.req.header("lambda-web-endpoint-name");
 *   if (endpoint === "Webhooks" && !c.req.path.startsWith("/webhooks/")) {
 *     return c.notFound();
 *   }
 *   await next();
 * });
 * ```
 *
 * @resource
 */
export const WebFunctionEndpoint: typeof WebFunctionEndpointResource = Object.assign(
  (
    id: string,
    props: WebFunctionEndpointProps | Effect.Effect<WebFunctionEndpointProps, never, Providers>,
  ) => WebFunctionEndpointResource(id, resolveEndpointProps(id, props)),
  WebFunctionEndpointResource,
);

/** A declared `function` resolves to the resource before the provider runs. */
const functionOf = (props: WebFunctionEndpointProps): WebFunctionRef =>
  props.function as WebFunctionRef;

export const WebFunctionEndpointProvider = () =>
  Provider.effect(
    WebFunctionEndpoint,
    Effect.gen(function* () {
      const nameOf = (id: string, props: { endpointName?: string } | undefined) =>
        props?.endpointName ?? toEndpointName(id);

      const toAttributes = (
        functionName: string,
        endpoint: LambdaWeb.GetWebFunctionEndpointResponse,
        revisionId: string,
      ): WebFunctionEndpoint["Attributes"] => ({
        functionName,
        functionArn: endpoint.functionArn,
        authType: endpoint.authType as WebFunctionAuthType,
        endpointType: endpoint.endpointType as WebFunctionEndpointType,
        endpointName: endpoint.endpointName,
        endpointArn: endpoint.endpointArn,
        domainName: endpoint.domainName,
        url: `https://${endpoint.domainName}`,
        revisionId,
        revisionWeights: servedRevisions(endpoint),
        ...endpointLimits(endpoint),
      });

      return {
        stables: ["functionName", "endpointName", "endpointArn"],
        diff: Effect.fn(function* ({ id, olds, news, output }) {
          if (!isResolved(news)) return;
          yield* validateWebFunctionSettings(`AWS.Lambda.WebFunctionEndpoint "${id}"`, {
            rateLimit: news.rateLimit,
            maxEnvironments: news.maxEnvironments,
            canary: news.canary,
          });
          if (!output || !olds) return undefined;
          // A different function, name, type, or Region set is a different
          // endpoint (and URL). The name is shared with the old endpoint on
          // the same function, so the old one must go first.
          const sameFunction = functionOf(news).functionName === output.functionName;
          const sameName = nameOf(id, news) === output.endpointName;
          if (!sameFunction || !sameName) {
            return { action: "replace" };
          }
          if (endpointIdentityChanged(olds, news)) {
            return { action: "replace", deleteFirst: true };
          }
          if (deepEqual(olds, news)) return { action: "noop" };
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const functionName =
            output?.functionName ?? (olds ? functionOf(olds).functionName : undefined);
          if (functionName === undefined) return undefined;
          const endpointName = output?.endpointName ?? nameOf(id, olds);
          const endpoint = yield* getEndpoint(functionName, endpointName);
          // Endpoints carry their function's tags: ownership follows the
          // function's.
          return endpoint === undefined
            ? undefined
            : toAttributes(functionName, endpoint, latestRevisionId(endpoint, output?.revisionId));
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          // Values that were Outputs at plan are resolved now.
          yield* checkEndpointProps(id, news);
          const functionName = functionOf(news).functionName;
          const endpointName = output?.endpointName ?? nameOf(id, news);
          const previous = yield* getEndpoint(functionName, endpointName);
          const revisionId = functionOf(news).revisionId;
          const endpoint = yield* syncEndpoint({
            functionName,
            spec: {
              endpointName,
              authType: news.authType,
              regions: news.regions,
              maxEnvironments: news.maxEnvironments,
              rateLimit: news.rateLimit,
              description: news.description,
              canary: news.canary,
            },
            revisionId,
            published: output?.revisionId,
            session,
          });
          // Moving off a revision whose egress connector the new one no
          // longer uses (e.g. `vpc` removed) may leave it unused.
          const stillServed = new Set(servedRevisions(endpoint).map((w) => w.revisionId));
          for (const { revisionId: previousRevisionId } of previous
            ? servedRevisions(previous)
            : []) {
            if (stillServed.has(previousRevisionId)) continue;
            const previousConnector = yield* connectorOfRevision(functionName, previousRevisionId);
            const currentConnector = yield* connectorOfRevision(functionName, revisionId);
            if (
              previousConnector !== undefined &&
              !sameConnector(previousConnector, currentConnector)
            ) {
              yield* releaseEgressConnector({
                functionName,
                connectorArn: previousConnector,
                session,
              });
            }
          }
          yield* session.note(`https://${endpoint.domainName}`);
          return toAttributes(functionName, endpoint, revisionId);
        }),
        delete: Effect.fn(function* ({ output }) {
          // Deleting the function deletes its endpoints too; a missing
          // function or endpoint is already deleted.
          yield* deleteEndpoint(output.functionName, output.endpointName);
        }),
      };
    }),
  );