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

import * as ag from "@distilled.cloud/aws/api-gateway";
import { deepEqual, isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, tagRecord } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import { deleteRestApiAndWait, restApiArn, retryOnApiStatusUpdating, syncTags } from "./common.ts";

export interface RestApiProps {
  /**
   * Name of the REST API.
   *
   * If omitted, Alchemy generates a deterministic physical name.
   */
  name?: string;
  /** Description of the REST API. */
  description?: string;
  /** A version identifier for the API. */
  version?: string;
  /** ID of an existing REST API to clone the new API from. */
  cloneFrom?: string;
  /** Media types treated as binary (e.g. `image/png`; a star-slash-star entry covers all types). */
  binaryMediaTypes?: string[];
  /** Minimum response size in bytes that triggers compression (0-10485760); unset disables compression. */
  minimumCompressionSize?: number;
  /**
   * Where API Gateway reads the API key on requests (`HEADER` or `AUTHORIZER`).
   * @default "HEADER"
   */
  apiKeySource?: ag.ApiKeySourceType;
  /** Endpoint type for the API (EDGE, REGIONAL, or PRIVATE). */
  endpointConfiguration?: ag.EndpointConfiguration;
  /** Resource policy document as a JSON string. */
  policy?: string;
  /**
   * Disable the default `execute-api` endpoint (serve only via custom domains).
   * @default false
   */
  disableExecuteApiEndpoint?: boolean;
  /** Minimum TLS version served by the API endpoint. */
  securityPolicy?: ag.SecurityPolicy;
  /** Access mode of the API endpoint. */
  endpointAccessMode?: ag.EndpointAccessMode;
  /** User-defined tags (Alchemy internal tags are merged automatically). */
  tags?: Record<string, string>;
}

/**
 * Structured metadata a child resource attaches to its RestApi via `.bind`.
 *
 * These bindings are the mechanism by which Methods, Resources, Authorizers,
 * and other REST-API-scoped children declare a reverse dependency on the API
 * itself. The presence of any such binding is what forces `RestApi.create` to
 * run *after* every child has been created — which is exactly the ordering
 * CloudFormation asks users to write manually via `DependsOn`.
 *
 * Consumers should not construct these directly; the child resource
 * constructors (e.g. `Method`, `Resource`) handle binding on behalf of the
 * user.
 */
export type RestApiBinding =
  | {
      kind: "method";
      methodId: Input<string>;
      restApiId: Input<string>;
      resourceId: Input<string>;
      httpMethod: Input<string>;
    }
  | {
      kind: "resource";
      resourceId: Input<string>;
      parentId: Input<string>;
      pathPart: Input<string>;
    }
  | {
      kind: "authorizer";
      authorizerId: Input<string>;
    };

export interface RestApi extends Resource<
  "AWS.ApiGateway.RestApi",
  RestApiProps,
  {
    restApiId: string;
    rootResourceId: string;
    name: string;
    description: string | undefined;
    version: string | undefined;
    binaryMediaTypes: string[] | undefined;
    minimumCompressionSize: number | undefined;
    apiKeySource: ag.ApiKeySourceType | undefined;
    endpointConfiguration: ag.EndpointConfiguration | undefined;
    policy: string | undefined;
    disableExecuteApiEndpoint: boolean | undefined;
    securityPolicy: ag.SecurityPolicy | undefined;
    endpointAccessMode: ag.EndpointAccessMode | undefined;
    tags: Record<string, string>;
  },
  RestApiBinding,
  Providers
> {}

/**
 * An Amazon API Gateway REST API (v1).
 *
 * `RestApi` is the root of an API Gateway v1 stack. Every other ApiGateway
 * resource — `Resource`, `Method`, `Authorizer`, `Deployment`, `Stage` —
 * hangs off a `RestApi`. The only identity you need to thread through your
 * stack is the `RestApi` value itself: child resources accept `restApi: api`
 * and register themselves back onto the API so that deployments and stages
 * wait for them without any user-authored dependency lists.
 * ### Getting started
 * A minimal API Gateway stack is four pieces: the `RestApi`, one or more
 * `Method`s, a `Deployment` that snapshots those methods, and a `Stage` that
 * exposes the deployment at a URL.
 *
 * **Example:** Mock HTTP GET on the root path
 * ```typescript
 * import * as ApiGateway from "@alchemy.run/aws/ApiGateway";
 *
 * const api = yield* ApiGateway.RestApi("Api", {
 *   endpointConfiguration: { types: ["REGIONAL"] },
 * });
 *
 * yield* ApiGateway.Method("GetRoot", {
 *   restApi: api,
 *   httpMethod: "GET",
 *   authorizationType: "NONE",
 *   integration: { type: "MOCK" },
 * });
 *
 * const deployment = yield* ApiGateway.Deployment("Release", {
 *   restApi: api,
 * });
 *
 * const stage = yield* ApiGateway.Stage("Prod", {
 *   restApi: api,
 *   stageName: "prod",
 *   deploymentId: deployment.deploymentId,
 * });
 * ```
 *
 * ### How dependencies flow
 * Writing `restApi: api` on a child (rather than `restApiId: api.restApiId`)
 * does two things: it threads the restApi id through, and it registers a
 * `RestApiBinding` back onto the API. The Alchemy scheduler sees those
 * bindings as reverse edges from children into the API, and `Deployment`
 * reads them to express a transitive dependency on every child. You never
 * have to write a `DependsOn` list or a `triggers` hash — adding a new
 * `Method` automatically orders it before the next `Deployment`.
 *
 * ### Private REST APIs
 * **Example:** Private REST API
 * ```typescript
 * const api = yield* ApiGateway.RestApi("PrivateApi", {
 *   endpointConfiguration: {
 *     types: ["PRIVATE"],
 *     vpcEndpointIds: [endpoint.vpcEndpointId],
 *   },
 *   policy: JSON.stringify({
 *     Version: "2012-10-17",
 *     Statement: [{
 *       Effect: "Allow",
 *       Principal: "*",
 *       Action: "execute-api:Invoke",
 *       Resource: "*",
 *     }],
 *   }),
 * });
 * ```
 *
 * ### Binary payloads
 * **Example:** Enable binary media types
 * ```typescript
 * const api = yield* ApiGateway.RestApi("BinaryApi", {
 *   binaryMediaTypes: ["application/octet-stream", "image/png"],
 *   minimumCompressionSize: 1024,
 * });
 * ```
 *
 * ### Endpoint hardening
 * **Example:** Disable the default execute-api endpoint
 * ```typescript
 * const api = yield* ApiGateway.RestApi("CustomDomainOnlyApi", {
 *   endpointConfiguration: { types: ["REGIONAL"] },
 *   disableExecuteApiEndpoint: true,
 * });
 * ```
 *
 * @resource
 */
export const RestApi = Resource<RestApi>("AWS.ApiGateway.RestApi");

const generatedName = (id: string, props: RestApiProps) =>
  props.name
    ? Effect.succeed(props.name)
    : createPhysicalName({
        id,
        maxLength: 128,
      });

const snapshotFromApi = (api: ag.RestApi) => ({
  restApiId: api.id!,
  rootResourceId: api.rootResourceId!,
  name: api.name ?? "",
  description: api.description,
  version: api.version,
  binaryMediaTypes: api.binaryMediaTypes,
  minimumCompressionSize: api.minimumCompressionSize,
  apiKeySource: api.apiKeySource,
  endpointConfiguration: api.endpointConfiguration,
  policy: api.policy,
  disableExecuteApiEndpoint: api.disableExecuteApiEndpoint,
  securityPolicy: api.securityPolicy,
  endpointAccessMode: api.endpointAccessMode,
  tags: tagRecord(api.tags),
});

const patchReplace = (path: string, value: string): ag.PatchOperation => ({
  op: "replace",
  path,
  value,
});

const encodeJsonPointerSegment = (s: string) => s.replace(/~/g, "~0").replace(/\//g, "~1");

const binaryMediaTypePath = (mediaType: string) =>
  `/binaryMediaTypes/${encodeJsonPointerSegment(mediaType)}`;

const buildBinaryMediaTypePatches = (
  prev: string[] | undefined,
  next: string[] | undefined,
): ag.PatchOperation[] => {
  const prevSet = [...new Set(prev ?? [])];
  const nextSet = [...new Set(next ?? [])];
  const patches: ag.PatchOperation[] = [];
  for (const m of prevSet) {
    if (!nextSet.includes(m)) {
      patches.push({ op: "remove", path: binaryMediaTypePath(m) });
    }
  }
  for (const m of nextSet) {
    if (!prevSet.includes(m)) {
      patches.push({
        op: "add",
        path: binaryMediaTypePath(m),
        value: m,
      });
    }
  }
  return patches;
};

const buildUpdatePatches = (
  news: RestApiProps,
  prev: RestApi["Attributes"],
): ag.PatchOperation[] => {
  const patches: ag.PatchOperation[] = [];
  if (news.name !== undefined && news.name !== prev.name) {
    patches.push(patchReplace("/name", news.name));
  }
  if (news.description !== prev.description) {
    patches.push(patchReplace("/description", news.description ?? ""));
  }
  if (news.version !== prev.version) {
    patches.push(patchReplace("/version", news.version ?? ""));
  }
  patches.push(...buildBinaryMediaTypePatches(prev.binaryMediaTypes, news.binaryMediaTypes));
  if (news.minimumCompressionSize !== prev.minimumCompressionSize) {
    patches.push(
      patchReplace("/minimumCompressionSize", String(news.minimumCompressionSize ?? "")),
    );
  }
  if (news.apiKeySource !== prev.apiKeySource) {
    patches.push(patchReplace("/apiKeySource", news.apiKeySource ?? "HEADER"));
  }
  if (news.policy !== prev.policy) {
    patches.push(patchReplace("/policy", news.policy ?? ""));
  }
  if (news.disableExecuteApiEndpoint !== prev.disableExecuteApiEndpoint) {
    patches.push(
      patchReplace("/disableExecuteApiEndpoint", String(!!news.disableExecuteApiEndpoint)),
    );
  }
  if (news.securityPolicy !== prev.securityPolicy) {
    patches.push(patchReplace("/securityPolicy", news.securityPolicy ?? "TLS_1_0"));
  }
  if (news.endpointAccessMode !== prev.endpointAccessMode) {
    patches.push(patchReplace("/endpointAccessMode", news.endpointAccessMode ?? ""));
  }
  return patches;
};

export const RestApiProvider = () =>
  Provider.effect(
    RestApi,
    Effect.gen(function* () {
      // Ensure — create the REST API in full and return its snapshot. Used by
      // `precreate` (cycle members) and by `reconcile` when the API is
      // missing (greenfield outside a cycle, or deleted out of band).
      const createApi = Effect.fn(function* (
        id: string,
        news: RestApiProps,
        session: { note: (message: string) => Effect.Effect<void> },
      ) {
        const name = yield* generatedName(id, news);
        const internalTags = yield* createInternalTags(id);
        const allTags = { ...news.tags, ...internalTags };
        const created = yield* retryOnApiStatusUpdating(
          ag.createRestApi({
            name,
            description: news.description,
            version: news.version,
            cloneFrom: news.cloneFrom,
            binaryMediaTypes: news.binaryMediaTypes,
            minimumCompressionSize: news.minimumCompressionSize,
            apiKeySource: news.apiKeySource,
            endpointConfiguration: news.endpointConfiguration,
            policy: news.policy,
            tags: allTags,
            disableExecuteApiEndpoint: news.disableExecuteApiEndpoint,
            securityPolicy: news.securityPolicy,
            endpointAccessMode: news.endpointAccessMode,
          }),
        );
        if (!created.id || !created.rootResourceId) {
          return yield* Effect.die("createRestApi missing id or rootResourceId");
        }
        yield* session.note(`Created REST API ${created.id}`);
        const full = yield* ag.getRestApi({ restApiId: created.id });
        return snapshotFromApi(full);
      });

      return {
        stables: ["restApiId", "rootResourceId"] as const,
        diff: Effect.fn(function* ({ news: newsIn, olds }) {
          if (!isResolved(newsIn)) return;
          const news = newsIn as RestApiProps;
          if (
            // Endpoint type, private endpoint IDs, and IP address type are part
            // of the REST API endpoint shape; replacing avoids partial endpoint
            // drift that API Gateway cannot consistently patch in place.
            !deepEqual(news.endpointConfiguration?.types, olds.endpointConfiguration?.types) ||
            !deepEqual(
              news.endpointConfiguration?.vpcEndpointIds,
              olds.endpointConfiguration?.vpcEndpointIds,
            ) ||
            !deepEqual(
              news.endpointConfiguration?.ipAddressType,
              olds.endpointConfiguration?.ipAddressType,
            )
          ) {
            return { action: "replace" } as const;
          }
        }),
        // Enumerate every REST API in the account/region. `getRestApis` is a
        // paginated collection op (items field "items"); collect every page and
        // map each item through the same snapshot helper `read` uses so each
        // element is a complete `Attributes` shape.
        list: () =>
          ag.getRestApis.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.items ?? [])
                  .filter((api): api is ag.RestApi & { id: string } => api.id != null)
                  .map((api) => snapshotFromApi(api)),
              ),
            ),
          ),
        read: Effect.fn(function* ({ output }) {
          if (!output?.restApiId) return undefined;
          const api = yield* ag
            .getRestApi({ restApiId: output.restApiId })
            .pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
          if (!api?.id) return undefined;
          return snapshotFromApi(api);
        }),
        // The REST API is brought up in two phases. `precreate` creates the
        // REST API in full so child resources (`Method`, `Resource`, etc.)
        // can resolve `api.restApiId` and start their own creates — this is
        // the cycle-breaker that lets children register themselves back onto
        // the API via `restApi.bind`. `create` then runs last — after every
        // bound child — and is effectively a no-op that re-reads the API to
        // publish the final snapshot. The key property is that any
        // `Deployment` referencing `api.*` outputs will see a value produced
        // only after every bound child has settled, because the bindings on
        // the API force `create` to wait for them before returning.
        precreate: Effect.fn(function* ({ id, news: newsIn, session }) {
          if (!isResolved(newsIn)) {
            return yield* Effect.die("RestApi props were not resolved");
          }
          const news = newsIn as RestApiProps;
          return yield* createApi(id, news, session);
        }),
        reconcile: Effect.fn(function* ({ id, news: newsIn, output, session }) {
          const { region } = yield* AWSEnvironment.current;
          if (!isResolved(newsIn)) {
            return yield* Effect.die("RestApi props were not resolved");
          }
          const news = newsIn as RestApiProps;

          // Observe — fetch live cloud state. `output` is treated as a
          // cache for the stable id only. Only cycle members are precreated,
          // so a greenfield create outside a cycle arrives without one.
          const observed = output?.restApiId
            ? yield* ag
                .getRestApi({ restApiId: output.restApiId })
                .pipe(Effect.catchTag("NotFoundException", () => Effect.undefined))
            : undefined;
          // Ensure — create the API when it is missing.
          const observedSnapshot = observed?.id
            ? snapshotFromApi(observed)
            : yield* createApi(id, news, session);
          const restApiId = observedSnapshot.restApiId;

          // Sync mutable scalar fields — diff observed cloud state against
          // desired and emit only the delta as PATCH operations.
          const patches = buildUpdatePatches(news, observedSnapshot);
          if (patches.length > 0) {
            yield* retryOnApiStatusUpdating(
              ag.updateRestApi({
                restApiId,
                patchOperations: patches,
              }),
            );
          }

          // Sync tags — observed ↔ desired so adoption converges without
          // fighting the existing tag set.
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };
          if (!deepEqual(observedSnapshot.tags, desiredTags)) {
            const arn = restApiArn(region, restApiId);
            yield* syncTags({
              resourceArn: arn,
              oldTags: observedSnapshot.tags,
              newTags: desiredTags,
            });
          }

          yield* session.note(`Reconciled REST API ${restApiId}`);

          // Re-read so the returned attributes reflect what's actually in
          // the cloud after all sync steps.
          const final = yield* ag.getRestApi({ restApiId });
          if (!final.id) {
            return yield* Effect.die("getRestApi missing id after reconcile");
          }
          return snapshotFromApi(final);
        }),
        delete: Effect.fn(function* ({ output, session }) {
          yield* deleteRestApiAndWait(output.restApiId);
          yield* session.note(`Deleted REST API ${output.restApiId}`);
        }),
      };
    }),
  );