sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ AppSync/ GraphqlApi.ts

import * as appsync from "@distilled.cloud/aws/appsync";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
import { toWireMillis, toWireSeconds } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import { retryConcurrentModification, syncAppSyncTags, tagRecord } from "./common.ts";

/**
 * The primary authentication mode of a GraphQL API.
 */
export type AuthenticationType =
  | "API_KEY"
  | "AWS_IAM"
  | "AMAZON_COGNITO_USER_POOLS"
  | "OPENID_CONNECT"
  | "AWS_LAMBDA";

export interface UserPoolAuthConfig {
  /** The Cognito user pool ID. */
  userPoolId: string;
  /**
   * The region the user pool lives in.
   * @default the ambient AWS region
   */
  awsRegion?: string;
  /**
   * What to do for requests that don't match an `appIdClientRegex`.
   * @default "ALLOW"
   */
  defaultAction?: "ALLOW" | "DENY";
  /** Regular expression matching allowed user pool app client IDs. */
  appIdClientRegex?: string;
}

export interface LambdaAuthorizerConfig {
  /**
   * The ARN of the Lambda authorizer function (or an alias/version
   * qualified ARN). AppSync must be allowed to invoke it — attach a
   * `Lambda.Permission` with principal `appsync.amazonaws.com`.
   */
  authorizerUri: string;
  /**
   * How long AppSync caches an authorizer response, e.g. `"5 minutes"` or
   * `Duration.seconds(300)` (0 disables caching, max 1 hour). Sent to AWS
   * as whole seconds.
   * @default "300 seconds"
   */
  authorizerResultTtl?: Duration.Input;
  /** Regular expression the authorization token must match before invoking. */
  identityValidationExpression?: string;
}

export interface OpenIDConnectAuthConfig {
  /** The OIDC issuer URL. */
  issuer: string;
  /** The client identifier the token audience must match. */
  clientId?: string;
  /** How long a token is valid after `iat`, e.g. `"1 hour"`. */
  iatTTL?: Duration.Input;
  /** How long a token is valid after `auth_time`, e.g. `"1 hour"`. */
  authTTL?: Duration.Input;
}

export interface AdditionalAuthProvider {
  /** The authentication mode of this additional provider. */
  authenticationType: AuthenticationType;
  /** Cognito user pool config (for `AMAZON_COGNITO_USER_POOLS`). */
  userPoolConfig?: Omit<UserPoolAuthConfig, "defaultAction">;
  /** OIDC config (for `OPENID_CONNECT`). */
  openIDConnectConfig?: OpenIDConnectAuthConfig;
  /** Lambda authorizer config (for `AWS_LAMBDA`). */
  lambdaAuthorizerConfig?: LambdaAuthorizerConfig;
}

export interface ApiCacheConfig {
  /**
   * The cache instance type, e.g. `"SMALL"`, `"MEDIUM"`, `"LARGE"` (or the
   * legacy `T2_SMALL`-style types).
   */
  type: appsync.ApiCacheType;
  /**
   * Caching behavior: `"FULL_REQUEST_CACHING"` caches every resolver,
   * `"PER_RESOLVER_CACHING"` caches only resolvers that opt in.
   */
  behavior: appsync.ApiCachingBehavior;
  /** TTL for cache entries, e.g. `"60 seconds"` (1 second–1 hour). */
  ttl: Duration.Input;
  /** Encrypt cache entries in transit. Immutable after creation. */
  transitEncryptionEnabled?: boolean;
  /** Encrypt cache entries at rest. Immutable after creation. */
  atRestEncryptionEnabled?: boolean;
  /**
   * Whether cache health metrics are emitted to CloudWatch.
   * @default "DISABLED"
   */
  healthMetricsConfig?: appsync.CacheHealthMetricsConfig;
}

export interface GraphqlApiProps {
  /**
   * Name of the API. If omitted, a deterministic physical name is
   * generated from the app, stage, and logical ID. Names are mutable.
   */
  name?: string;
  /**
   * The primary authentication mode.
   * @default "API_KEY"
   */
  authenticationType?: AuthenticationType;
  /**
   * The GraphQL schema (SDL string). Applied via `startSchemaCreation`
   * and awaited until the schema is active. Resolvers can only be
   * attached to types/fields that exist in this schema.
   */
  schema?: string;
  /**
   * Cognito user pool config — required when `authenticationType` is
   * `AMAZON_COGNITO_USER_POOLS`.
   */
  userPoolConfig?: UserPoolAuthConfig;
  /**
   * OIDC config — required when `authenticationType` is `OPENID_CONNECT`.
   */
  openIDConnectConfig?: OpenIDConnectAuthConfig;
  /**
   * Lambda authorizer config — required when `authenticationType` is
   * `AWS_LAMBDA`.
   */
  lambdaAuthorizerConfig?: LambdaAuthorizerConfig;
  /**
   * Additional authentication modes beyond the primary one.
   */
  additionalAuthenticationProviders?: AdditionalAuthProvider[];
  /**
   * CloudWatch Logs configuration. Requires a role AppSync can assume
   * with log-delivery permissions.
   */
  logConfig?: appsync.LogConfig;
  /**
   * Whether AWS X-Ray tracing is enabled.
   * @default false
   */
  xrayEnabled?: boolean;
  /**
   * `GLOBAL` (public endpoint) or `PRIVATE` (VPC-only). Immutable —
   * changing it triggers a replacement.
   * @default "GLOBAL"
   */
  visibility?: "GLOBAL" | "PRIVATE";
  /**
   * `GRAPHQL` (standard) or `MERGED` (merged API). Immutable — changing
   * it triggers a replacement.
   * @default "GRAPHQL"
   */
  apiType?: "GRAPHQL" | "MERGED";
  /**
   * Whether introspection queries are allowed.
   * @default "ENABLED"
   */
  introspectionConfig?: "ENABLED" | "DISABLED";
  /** Maximum depth a query is allowed to reach (0 disables the limit). */
  queryDepthLimit?: number;
  /** Maximum number of resolvers a query may invoke (0 disables the limit). */
  resolverCountLimit?: number;
  /**
   * Server-side API cache. **Cache instances bill hourly** while
   * provisioned; omit to run without a cache. Provisioning is
   * asynchronous (~10–20 minutes to reach `AVAILABLE`); reconcile does
   * not wait for it.
   */
  cache?: ApiCacheConfig;
  /**
   * Environment variables exposed to `APPSYNC_JS` resolver and function
   * code via `ctx.env`. The whole map is replaced on each change; pass
   * `{}` to clear all variables. When omitted, environment variables are
   * left unmanaged.
   */
  environmentVariables?: Record<string, string>;
  /**
   * Tags to apply to the API. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface GraphqlApi extends Resource<
  "AWS.AppSync.GraphqlApi",
  GraphqlApiProps,
  {
    /** The unique API ID. */
    apiId: string;
    /** The API's ARN. */
    apiArn: string;
    /** The API name. */
    name: string;
    /** The GraphQL endpoint (`https://{id}.appsync-api.{region}.amazonaws.com/graphql`). */
    graphqlUrl: string;
    /** The real-time (WebSocket subscriptions) endpoint. */
    realtimeUrl: string | undefined;
    /** The primary authentication mode. */
    authenticationType: AuthenticationType;
  },
  never,
  Providers
> {}

/**
 * An AWS AppSync GraphQL API.
 *
 * Owns the API, its SDL schema (applied via `startSchemaCreation` and
 * awaited until active), its authentication modes, and an optional
 * server-side cache. Pair with {@link DataSource}, {@link Resolver},
 * and {@link ApiKey} to serve GraphQL over Lambda or DynamoDB.
 * ### Creating a GraphQL API
 * **Example:** API-key authenticated API with a schema
 * ```typescript
 * import * as AppSync from "@alchemy.run/aws/AppSync";
 *
 * const api = yield* AppSync.GraphqlApi("Api", {
 *   schema: `
 *     type Query { hello: String! }
 *     schema { query: Query }
 *   `,
 * });
 * const key = yield* AppSync.ApiKey("Key", { api });
 * ```
 *
 * ### Authentication Modes
 * **Example:** Lambda authorizer
 * ```typescript
 * const api = yield* AppSync.GraphqlApi("Api", {
 *   authenticationType: "AWS_LAMBDA",
 *   lambdaAuthorizerConfig: { authorizerUri: authorizer.functionArn },
 *   schema,
 * });
 * // AppSync must be allowed to invoke the authorizer:
 * yield* AWS.Lambda.Permission("AppSyncInvoke", {
 *   functionName: authorizer.functionName,
 *   principal: "appsync.amazonaws.com",
 *   action: "lambda:InvokeFunction",
 *   sourceArn: api.apiArn,
 * });
 * ```
 *
 * **Example:** Cognito user pools as an additional auth mode
 * ```typescript
 * const api = yield* AppSync.GraphqlApi("Api", {
 *   authenticationType: "API_KEY",
 *   additionalAuthenticationProviders: [
 *     {
 *       authenticationType: "AMAZON_COGNITO_USER_POOLS",
 *       userPoolConfig: { userPoolId: pool.userPoolId },
 *     },
 *   ],
 *   schema,
 * });
 * ```
 *
 * ### Caching
 * **Example:** Full-request server-side cache (bills hourly!)
 * ```typescript
 * const api = yield* AppSync.GraphqlApi("Api", {
 *   schema,
 *   cache: { type: "SMALL", behavior: "FULL_REQUEST_CACHING", ttl: "60 seconds" },
 * });
 * ```
 *
 * ### Environment Variables
 * **Example:** Expose variables to resolver code via ctx.env
 * ```typescript
 * const api = yield* AppSync.GraphqlApi("Api", {
 *   schema,
 *   environmentVariables: { STAGE: "prod" },
 * });
 * // in APPSYNC_JS resolver code:
 * //   export function response(ctx) { return ctx.env.STAGE; }
 * ```
 *
 * @resource
 */
export const GraphqlApi = Resource<GraphqlApi>("AWS.AppSync.GraphqlApi");

/** Schema creation finished in the `FAILED` state. */
export class SchemaCreationFailed extends Data.TaggedError("SchemaCreationFailed")<{
  readonly apiId: string;
  readonly details: string | undefined;
}> {}

/** Schema creation did not settle within the bounded polling window. */
export class SchemaCreationTimedOut extends Data.TaggedError("SchemaCreationTimedOut")<{
  readonly apiId: string;
  readonly status: string | undefined;
}> {}

const toWireOidcConfig = (
  config: OpenIDConnectAuthConfig | undefined,
): appsync.OpenIDConnectConfig | undefined =>
  config === undefined
    ? undefined
    : {
        issuer: config.issuer,
        clientId: config.clientId,
        // The AppSync API expresses both token TTLs in milliseconds.
        iatTTL: toWireMillis(config.iatTTL),
        authTTL: toWireMillis(config.authTTL),
      };

const toWireLambdaAuthorizerConfig = (
  config: LambdaAuthorizerConfig | undefined,
): appsync.LambdaAuthorizerConfig | undefined =>
  config === undefined
    ? undefined
    : {
        authorizerUri: config.authorizerUri,
        // The wire field carries the unit; the prop is a Duration.Input.
        authorizerResultTtlInSeconds: toWireSeconds(config.authorizerResultTtl),
        identityValidationExpression: config.identityValidationExpression,
      };

const toWireUserPoolConfig = (
  config: UserPoolAuthConfig | undefined,
  region: string,
): appsync.UserPoolConfig | undefined =>
  config === undefined
    ? undefined
    : {
        userPoolId: config.userPoolId,
        awsRegion: config.awsRegion ?? region,
        defaultAction: config.defaultAction ?? "ALLOW",
        appIdClientRegex: config.appIdClientRegex,
      };

const toWireAdditionalProviders = (
  providers: AdditionalAuthProvider[] | undefined,
  region: string,
): appsync.AdditionalAuthenticationProvider[] | undefined =>
  providers === undefined
    ? undefined
    : providers.map((provider) => ({
        authenticationType: provider.authenticationType,
        userPoolConfig:
          provider.userPoolConfig === undefined
            ? undefined
            : {
                userPoolId: provider.userPoolConfig.userPoolId,
                awsRegion: provider.userPoolConfig.awsRegion ?? region,
                appIdClientRegex: provider.userPoolConfig.appIdClientRegex,
              },
        openIDConnectConfig: toWireOidcConfig(provider.openIDConnectConfig),
        lambdaAuthorizerConfig: toWireLambdaAuthorizerConfig(provider.lambdaAuthorizerConfig),
      }));

/**
 * Canonicalize the wire-facing auth/limit surface of an API so observed
 * and desired states compare structurally (dropping undefined members).
 */
const authSurface = (api: {
  name?: string;
  authenticationType?: string;
  userPoolConfig?: appsync.UserPoolConfig;
  openIDConnectConfig?: appsync.OpenIDConnectConfig;
  lambdaAuthorizerConfig?: appsync.LambdaAuthorizerConfig;
  additionalAuthenticationProviders?: appsync.AdditionalAuthenticationProvider[];
  xrayEnabled?: boolean;
  introspectionConfig?: string;
  queryDepthLimit?: number;
  resolverCountLimit?: number;
  logConfig?: appsync.LogConfig;
}) =>
  JSON.parse(
    JSON.stringify({
      name: api.name,
      authenticationType: api.authenticationType,
      userPoolConfig: api.userPoolConfig,
      openIDConnectConfig: api.openIDConnectConfig,
      lambdaAuthorizerConfig: {
        ...api.lambdaAuthorizerConfig,
        // AWS normalizes the TTL default (300) into the response
        authorizerResultTtlInSeconds:
          api.lambdaAuthorizerConfig === undefined
            ? undefined
            : (api.lambdaAuthorizerConfig.authorizerResultTtlInSeconds ?? 300),
      },
      additionalAuthenticationProviders: api.additionalAuthenticationProviders?.map((p) => ({
        ...p,
        lambdaAuthorizerConfig:
          p.lambdaAuthorizerConfig === undefined
            ? undefined
            : {
                ...p.lambdaAuthorizerConfig,
                authorizerResultTtlInSeconds:
                  p.lambdaAuthorizerConfig.authorizerResultTtlInSeconds ?? 300,
              },
      })),
      xrayEnabled: api.xrayEnabled ?? false,
      introspectionConfig: api.introspectionConfig ?? "ENABLED",
      queryDepthLimit: api.queryDepthLimit ?? 0,
      resolverCountLimit: api.resolverCountLimit ?? 0,
      logConfig: api.logConfig,
    }),
  );

export const GraphqlApiProvider = () =>
  Provider.effect(
    GraphqlApi,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: Pick<GraphqlApiProps, "name">) {
        return props.name ?? (yield* createPhysicalName({ id, maxLength: 64 }));
      });

      const getApiSafe = (apiId: string) =>
        appsync.getGraphqlApi({ apiId }).pipe(
          Effect.map((response) => response.graphqlApi),
          Effect.catchTag("NotFoundException", () => Effect.undefined),
        );

      /** Find an API by exact name (fallback when no apiId is cached). */
      const findApiByName = Effect.fn(function* (name: string) {
        const pages = yield* appsync.listGraphqlApis.pages({}).pipe(Stream.runCollect);
        return Array.from(pages)
          .flatMap((page) => page.graphqlApis ?? [])
          .find((api) => api.name === name);
      });

      const toAttributes = (api: appsync.GraphqlApi): GraphqlApi["Attributes"] => ({
        apiId: api.apiId!,
        apiArn: api.arn!,
        name: api.name!,
        graphqlUrl: api.uris?.GRAPHQL ?? "",
        realtimeUrl: api.uris?.REALTIME,
        authenticationType: api.authenticationType as AuthenticationType,
      });

      /**
       * Apply the SDL schema and poll until the creation settles.
       * `startSchemaCreation` is asynchronous; polling is bounded (~60s —
       * schema creation is normally seconds).
       */
      const applySchema = Effect.fn(function* (apiId: string, schema: string) {
        const definition = yield* Effect.sync(() => new TextEncoder().encode(schema));
        yield* retryConcurrentModification(appsync.startSchemaCreation({ apiId, definition }));
        const final = yield* appsync.getSchemaCreationStatus({ apiId }).pipe(
          Effect.repeat({
            schedule: Schedule.fixed("1 second"),
            until: (response) => response.status !== "PROCESSING",
            times: 60,
          }),
        );
        if (final.status === "FAILED") {
          return yield* new SchemaCreationFailed({
            apiId,
            details: final.details,
          });
        }
        if (final.status === "PROCESSING") {
          return yield* new SchemaCreationTimedOut({
            apiId,
            status: final.status,
          });
        }
      });

      /**
       * Converge the optional server-side cache: create when desired and
       * missing, update on drift, delete when no longer desired. Creation
       * is asynchronous and NOT awaited (10–20 minutes to AVAILABLE).
       */
      const syncCache = Effect.fn(function* (apiId: string, desired: ApiCacheConfig | undefined) {
        const observed = yield* appsync.getApiCache({ apiId }).pipe(
          Effect.map((response) => response.apiCache),
          Effect.catchTag("NotFoundException", () => Effect.undefined),
        );
        if (desired === undefined) {
          if (observed !== undefined) {
            yield* retryConcurrentModification(
              appsync
                .deleteApiCache({ apiId })
                .pipe(Effect.catchTag("NotFoundException", () => Effect.void)),
            );
          }
          return;
        }
        // The wire TTL is whole seconds.
        const desiredTtl = toWireSeconds(desired.ttl)!;
        if (observed === undefined) {
          yield* retryConcurrentModification(
            appsync.createApiCache({
              apiId,
              type: desired.type,
              apiCachingBehavior: desired.behavior,
              ttl: desiredTtl,
              transitEncryptionEnabled: desired.transitEncryptionEnabled,
              atRestEncryptionEnabled: desired.atRestEncryptionEnabled,
              healthMetricsConfig: desired.healthMetricsConfig,
            }),
          );
          return;
        }
        const drifted =
          observed.type !== desired.type ||
          observed.apiCachingBehavior !== desired.behavior ||
          observed.ttl !== desiredTtl ||
          (desired.healthMetricsConfig !== undefined &&
            observed.healthMetricsConfig !== desired.healthMetricsConfig);
        if (drifted) {
          yield* retryConcurrentModification(
            appsync.updateApiCache({
              apiId,
              type: desired.type,
              apiCachingBehavior: desired.behavior,
              ttl: desiredTtl,
              healthMetricsConfig: desired.healthMetricsConfig,
            }),
          );
        }
      });

      /**
       * Converge resolver environment variables (`ctx.env`). The AWS API
       * replaces the whole map on PUT, so a single drift-guarded call
       * suffices. Skipped entirely when the prop is unmanaged.
       */
      const syncEnvironmentVariables = Effect.fn(function* (
        apiId: string,
        desired: Record<string, string> | undefined,
      ) {
        if (desired === undefined) return;
        const observed = yield* appsync
          .getGraphqlApiEnvironmentVariables({ apiId })
          .pipe(Effect.map((response) => response.environmentVariables ?? {}));
        if (!deepEqual(tagRecord(observed), desired)) {
          yield* retryConcurrentModification(
            appsync.putGraphqlApiEnvironmentVariables({
              apiId,
              environmentVariables: desired,
            }),
          );
        }
      });

      return GraphqlApi.Provider.of({
        stables: ["apiId", "apiArn", "graphqlUrl", "realtimeUrl"],

        list: () =>
          Effect.gen(function* () {
            const pages = yield* appsync.listGraphqlApis.pages({}).pipe(Stream.runCollect);
            return Array.from(pages)
              .flatMap((page) => page.graphqlApis ?? [])
              .filter((api) => api.apiId != null)
              .map(toAttributes);
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const api =
            output?.apiId !== undefined
              ? yield* getApiSafe(output.apiId)
              : yield* findApiByName(yield* createName(id, olds ?? {}));
          if (api?.apiId == null) return undefined;
          const attrs = toAttributes(api);
          const tags = tagRecord(api.tags);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (
            (news.visibility ?? "GLOBAL") !== (olds.visibility ?? "GLOBAL") ||
            (news.apiType ?? "GRAPHQL") !== (olds.apiType ?? "GRAPHQL")
          ) {
            return { action: "replace" } as const;
          }
          // name/auth/schema/cache/limits/tags converge via update
        }),

        reconcile: Effect.fn(function* ({ id, news, olds, output, session }) {
          const { region } = yield* AWSEnvironment.current;
          const name = news.name ?? (yield* createName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };
          const authenticationType = news.authenticationType ?? "API_KEY";

          const desired = {
            name,
            authenticationType,
            userPoolConfig: toWireUserPoolConfig(news.userPoolConfig, region),
            openIDConnectConfig: toWireOidcConfig(news.openIDConnectConfig),
            lambdaAuthorizerConfig: toWireLambdaAuthorizerConfig(news.lambdaAuthorizerConfig),
            additionalAuthenticationProviders: toWireAdditionalProviders(
              news.additionalAuthenticationProviders,
              region,
            ),
            xrayEnabled: news.xrayEnabled,
            introspectionConfig: news.introspectionConfig,
            queryDepthLimit: news.queryDepthLimit,
            resolverCountLimit: news.resolverCountLimit,
            logConfig: news.logConfig,
          };

          // 1. OBSERVE — the cached apiId is only a hint; fall back to a
          //    name scan so interrupted deploys converge.
          let observed =
            output?.apiId !== undefined
              ? yield* getApiSafe(output.apiId)
              : yield* findApiByName(name);

          // 2. ENSURE
          let justCreated = false;
          if (observed?.apiId == null) {
            const created = yield* retryConcurrentModification(
              appsync.createGraphqlApi({
                ...desired,
                visibility: news.visibility,
                apiType: news.apiType,
                tags: desiredTags,
              }),
            );
            observed = created.graphqlApi!;
            justCreated = true;
            yield* session.note(`Created GraphQL API ${observed.apiId}`);
          }
          const apiId = observed.apiId!;

          // 3. SYNC — one update call when the observed auth/limit surface
          //    drifted from the desired one.
          if (!justCreated && !deepEqual(authSurface(observed), authSurface(desired))) {
            const updated = yield* retryConcurrentModification(
              appsync.updateGraphqlApi({ apiId, ...desired }),
            );
            observed = updated.graphqlApi ?? observed;
            yield* session.note(`Updated GraphQL API ${apiId}`);
          }

          // 3b. SYNC SCHEMA — `startSchemaCreation` replaces the schema
          //     wholesale (idempotent). Apply on first provision, on
          //     adoption, and whenever the desired SDL changed; the
          //     previous props are only a hint to skip the no-op call.
          if (
            news.schema !== undefined &&
            (justCreated || output === undefined || olds?.schema !== news.schema)
          ) {
            yield* applySchema(apiId, news.schema);
            yield* session.note(`Applied schema to ${apiId}`);
          }

          // 3c. SYNC CACHE
          yield* syncCache(apiId, news.cache);

          // 3d. SYNC ENVIRONMENT VARIABLES (ctx.env in resolver code).
          yield* syncEnvironmentVariables(apiId, news.environmentVariables);

          // 3e. SYNC TAGS — against OBSERVED cloud tags.
          if (observed.arn !== undefined) {
            yield* syncAppSyncTags({
              resourceArn: observed.arn,
              oldTags: tagRecord(observed.tags),
              newTags: desiredTags,
            });
          }

          yield* session.note(apiId);
          return toAttributes(observed);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* retryConcurrentModification(
            appsync
              .deleteGraphqlApi({ apiId: output.apiId })
              .pipe(Effect.catchTag("NotFoundException", () => Effect.void)),
          );
        }),
      });
    }),
  );