sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ApiGatewayV2/ Integration.ts

import * as agw2 from "@distilled.cloud/aws/apigatewayv2";
import { deepEqual, isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { toWireMillis } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import type { Providers } from "../Providers.ts";
import type { Api } from "./Api.ts";
import { collectAllPages, retryOnTooManyRequests } from "./common.ts";

export interface IntegrationProps {
  /**
   * ID of the API this integration belongs to. Usually derived from
   * `api.apiId` by the {@link Integration} wrapper.
   */
  apiId: string;
  /**
   * The integration type. `AWS_PROXY` (Lambda proxy) is the common case
   * for both HTTP and WebSocket APIs; `HTTP_PROXY` forwards to an HTTP
   * endpoint; `MOCK` (WebSocket only) returns a static response.
   */
  integrationType: agw2.IntegrationType;
  /**
   * The integration endpoint:
   *
   * - `AWS_PROXY` on an HTTP API — the Lambda function ARN.
   * - `AWS_PROXY` on a WebSocket API — the full invocation URI
   *   (`arn:aws:apigateway:{region}:lambda:path/2015-03-31/functions/{functionArn}/invocations`).
   * - `HTTP_PROXY` — the HTTP URL.
   * - private integrations — the ELB listener / Cloud Map service ARN.
   */
  integrationUri?: string;
  /**
   * The HTTP method the integration uses when calling the backend
   * (`POST` for Lambda; for `HTTP_PROXY` routes usually `ANY`).
   */
  integrationMethod?: string;
  /**
   * The Lambda event payload format for HTTP API `AWS_PROXY` integrations.
   * `2.0` is the modern shape (same as Lambda Function URLs).
   * @default "2.0" for HTTP AWS_PROXY (AWS defaults to "1.0" — the wrapper does not override; set explicitly)
   */
  payloadFormatVersion?: string;
  /**
   * `INTERNET` (default) or `VPC_LINK` for private integrations.
   */
  connectionType?: agw2.ConnectionType;
  /**
   * The VPC link ID when `connectionType` is `VPC_LINK`.
   */
  connectionId?: string;
  /**
   * IAM credentials ARN for the integration (or
   * `arn:aws:iam::*:user/*` to use caller credentials).
   */
  credentialsArn?: string;
  /** Description of the integration. */
  description?: string;
  /**
   * AWS service integration subtype (e.g. `SQS-SendMessage`) for
   * first-class AWS service integrations on HTTP APIs.
   */
  integrationSubtype?: string;
  /** Passthrough behavior (WebSocket APIs only). */
  passthroughBehavior?: agw2.PassthroughBehavior;
  /** Request parameter mappings. */
  requestParameters?: { [key: string]: string | undefined };
  /** Request templates (WebSocket APIs only). */
  requestTemplates?: { [key: string]: string | undefined };
  /** Response parameter mappings (HTTP APIs). */
  responseParameters?: {
    [key: string]: { [key: string]: string | undefined } | undefined;
  };
  /** Template selection expression (WebSocket APIs only). */
  templateSelectionExpression?: string;
  /**
   * Integration timeout (e.g. `"29 seconds"` or `Duration.seconds(29)`;
   * a bare number is milliseconds). 50–29000 ms for WebSocket APIs,
   * 50–30000 ms for HTTP APIs. Sent to the API in whole milliseconds
   * (`TimeoutInMillis`).
   */
  timeout?: Duration.Input;
  /** TLS configuration for private integrations. */
  tlsConfig?: agw2.TlsConfigInput;
  /** Content handling strategy (WebSocket APIs only). */
  contentHandlingStrategy?: agw2.ContentHandlingStrategy;
}

export interface IntegrationType extends Resource<
  "AWS.ApiGatewayV2.Integration",
  IntegrationProps,
  {
    /** The API this integration belongs to. */
    apiId: string;
    /** The integration identifier. */
    integrationId: string;
    integrationType: agw2.IntegrationType;
    integrationUri: string | undefined;
    integrationMethod: string | undefined;
    payloadFormatVersion: string | undefined;
    connectionType: agw2.ConnectionType | undefined;
    connectionId: string | undefined;
    credentialsArn: string | undefined;
    description: string | undefined;
    integrationSubtype: string | undefined;
    passthroughBehavior: agw2.PassthroughBehavior | undefined;
    requestParameters: { [key: string]: string | undefined } | undefined;
    requestTemplates: { [key: string]: string | undefined } | undefined;
    responseParameters:
      | { [key: string]: { [key: string]: string | undefined } | undefined }
      | undefined;
    templateSelectionExpression: string | undefined;
    timeoutInMillis: number | undefined;
    contentHandlingStrategy: agw2.ContentHandlingStrategy | undefined;
  },
  never,
  Providers
> {}

/**
 * An API Gateway v2 Integration — the backend target a Route forwards to.
 *
 * For HTTP APIs the common integration is `AWS_PROXY` with payload format
 * `2.0`, pointing directly at a Lambda function ARN. For WebSocket APIs the
 * `integrationUri` must be the full Lambda invocation URI.
 * ### Lambda proxy integration (HTTP API)
 * **Example:** AWS_PROXY integration with payload 2.0
 * ```typescript
 * const integration = yield* ApiGatewayV2.Integration("Fn", {
 *   api,
 *   integrationType: "AWS_PROXY",
 *   integrationUri: fn.functionArn,
 *   payloadFormatVersion: "2.0",
 * });
 * ```
 *
 * ### HTTP proxy integration
 * **Example:** Forward to an external HTTP endpoint
 * ```typescript
 * const integration = yield* ApiGatewayV2.Integration("Upstream", {
 *   api,
 *   integrationType: "HTTP_PROXY",
 *   integrationUri: "https://example.com/{proxy}",
 *   integrationMethod: "ANY",
 *   payloadFormatVersion: "1.0",
 * });
 * ```
 *
 * @resource
 */
export const IntegrationResource = Resource<IntegrationType>("AWS.ApiGatewayV2.Integration");

export interface IntegrationInputProps extends Omit<
  {
    [K in keyof IntegrationProps]?: Input<IntegrationProps[K]>;
  },
  "apiId" | "integrationType"
> {
  /**
   * The `Api` this integration belongs to (preferred). Alternatively pass
   * a raw `apiId`.
   */
  api?: Api;
  apiId?: Input<string>;
  integrationType: Input<agw2.IntegrationType>;
}

/**
 * User-facing wrapper for the Integration resource. Accepts `api: Api` as
 * the idiomatic way to attach an integration to an API.
 */
export const Integration = (id: string, props: IntegrationInputProps) =>
  Effect.gen(function* () {
    const { api, ...rest } = props;
    const apiId = rest.apiId ?? api?.apiId;
    if (!apiId) {
      return yield* Effect.die(
        "Integration requires either `api` (preferred) or an explicit `apiId`.",
      );
    }
    return yield* IntegrationResource(id, { ...rest, apiId } as any);
  });

const snapshotFromIntegration = (
  apiId: string,
  integ: agw2.GetIntegrationResult,
): IntegrationType["Attributes"] => ({
  apiId,
  integrationId: integ.IntegrationId!,
  integrationType: integ.IntegrationType ?? "AWS_PROXY",
  integrationUri: integ.IntegrationUri,
  integrationMethod: integ.IntegrationMethod,
  payloadFormatVersion: integ.PayloadFormatVersion,
  connectionType: integ.ConnectionType,
  connectionId: integ.ConnectionId,
  credentialsArn: integ.CredentialsArn,
  description: integ.Description,
  integrationSubtype: integ.IntegrationSubtype,
  passthroughBehavior: integ.PassthroughBehavior,
  requestParameters: integ.RequestParameters,
  requestTemplates: integ.RequestTemplates,
  responseParameters: integ.ResponseParameters,
  templateSelectionExpression: integ.TemplateSelectionExpression,
  timeoutInMillis: integ.TimeoutInMillis,
  contentHandlingStrategy: integ.ContentHandlingStrategy,
});

const desiredRequest = (news: IntegrationProps) => ({
  IntegrationType: news.integrationType,
  IntegrationUri: news.integrationUri,
  IntegrationMethod: news.integrationMethod,
  PayloadFormatVersion: news.payloadFormatVersion,
  ConnectionType: news.connectionType,
  ConnectionId: news.connectionId,
  CredentialsArn: news.credentialsArn,
  Description: news.description,
  IntegrationSubtype: news.integrationSubtype,
  PassthroughBehavior: news.passthroughBehavior,
  RequestParameters: news.requestParameters,
  RequestTemplates: news.requestTemplates,
  ResponseParameters: news.responseParameters,
  TemplateSelectionExpression: news.templateSelectionExpression,
  TimeoutInMillis: toWireMillis(news.timeout),
  TlsConfig: news.tlsConfig,
  ContentHandlingStrategy: news.contentHandlingStrategy,
});

export const IntegrationProvider = () =>
  Provider.effect(
    IntegrationResource,
    Effect.gen(function* () {
      const getIntegrationSafe = (apiId: string, integrationId: string) =>
        agw2
          .getIntegration({ ApiId: apiId, IntegrationId: integrationId })
          .pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));

      return IntegrationResource.Provider.of({
        stables: ["apiId", "integrationId"],

        list: () =>
          Effect.gen(function* () {
            const apis = yield* collectAllPages((NextToken) => agw2.getApis({ NextToken }));
            const perApi = yield* Effect.forEach(
              apis.filter((api) => api.ApiId != null),
              (api) =>
                collectAllPages((NextToken) =>
                  agw2.getIntegrations({ ApiId: api.ApiId!, NextToken }),
                ).pipe(
                  Effect.map((items) =>
                    items
                      .filter((integ) => integ.IntegrationId != null)
                      .map((integ) => snapshotFromIntegration(api.ApiId!, integ)),
                  ),
                  // API deleted between list and getIntegrations — skip it.
                  Effect.catchTag("NotFoundException", () =>
                    Effect.succeed([] as IntegrationType["Attributes"][]),
                  ),
                ),
              { concurrency: 5 },
            );
            return perApi.flat();
          }),

        read: Effect.fn(function* ({ output }) {
          if (!output?.apiId || !output.integrationId) return undefined;
          const integ = yield* getIntegrationSafe(output.apiId, output.integrationId);
          if (!integ?.IntegrationId) return undefined;
          return snapshotFromIntegration(output.apiId, integ);
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (news.apiId !== olds.apiId) {
            return { action: "replace" } as const;
          }
        }),

        reconcile: Effect.fn(function* ({ news, output, session }) {
          const apiId = output?.apiId ?? news.apiId;

          // 1. OBSERVE
          let observed = output?.integrationId
            ? yield* getIntegrationSafe(apiId, output.integrationId)
            : undefined;

          // 2. ENSURE
          if (!observed?.IntegrationId) {
            observed = yield* retryOnTooManyRequests(
              agw2.createIntegration({ ApiId: apiId, ...desiredRequest(news) }),
            );
            yield* session.note(`Created integration ${observed.IntegrationId}`);
            return snapshotFromIntegration(apiId, observed);
          }

          // 3. SYNC — compare the observed snapshot against desired and
          //    update only on drift.
          const snapshot = snapshotFromIntegration(apiId, observed);
          const desired = desiredRequest(news);
          const drift =
            snapshot.integrationType !== desired.IntegrationType ||
            snapshot.integrationUri !== desired.IntegrationUri ||
            snapshot.integrationMethod !== desired.IntegrationMethod ||
            (desired.PayloadFormatVersion !== undefined &&
              snapshot.payloadFormatVersion !== desired.PayloadFormatVersion) ||
            (desired.ConnectionType !== undefined &&
              snapshot.connectionType !== desired.ConnectionType) ||
            snapshot.connectionId !== desired.ConnectionId ||
            snapshot.credentialsArn !== desired.CredentialsArn ||
            snapshot.description !== desired.Description ||
            snapshot.integrationSubtype !== desired.IntegrationSubtype ||
            (desired.PassthroughBehavior !== undefined &&
              snapshot.passthroughBehavior !== desired.PassthroughBehavior) ||
            (desired.RequestParameters !== undefined &&
              !deepEqual(snapshot.requestParameters, desired.RequestParameters)) ||
            (desired.RequestTemplates !== undefined &&
              !deepEqual(snapshot.requestTemplates, desired.RequestTemplates)) ||
            (desired.ResponseParameters !== undefined &&
              !deepEqual(snapshot.responseParameters, desired.ResponseParameters)) ||
            snapshot.templateSelectionExpression !== desired.TemplateSelectionExpression ||
            (desired.TimeoutInMillis !== undefined &&
              snapshot.timeoutInMillis !== desired.TimeoutInMillis) ||
            (desired.ContentHandlingStrategy !== undefined &&
              snapshot.contentHandlingStrategy !== desired.ContentHandlingStrategy);
          if (drift) {
            const updated = yield* retryOnTooManyRequests(
              agw2.updateIntegration({
                ApiId: apiId,
                IntegrationId: snapshot.integrationId,
                ...desired,
              }),
            );
            yield* session.note(`Updated integration ${snapshot.integrationId}`);
            return snapshotFromIntegration(apiId, updated);
          }

          return snapshot;
        }),

        delete: Effect.fn(function* ({ output, session }) {
          yield* retryOnTooManyRequests(
            agw2
              .deleteIntegration({
                ApiId: output.apiId,
                IntegrationId: output.integrationId,
              })
              .pipe(Effect.catchTag("NotFoundException", () => Effect.void)),
          );
          yield* session.note(`Deleted integration ${output.integrationId}`);
        }),
      });
    }),
  );