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

import * as appsync from "@distilled.cloud/aws/appsync";
import * as iam from "@distilled.cloud/aws/iam";
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 } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { PolicyStatement } from "../IAM/Policy.ts";
import type { Providers } from "../Providers.ts";
import {
  retryConcurrentModification,
  retryWhileRolePropagates,
  sanitizeAppSyncName,
} from "./common.ts";
import type { GraphqlApi } from "./GraphqlApi.ts";

/** The data source types supported by the resource. */
export type DataSourceType =
  | "NONE"
  | "AWS_LAMBDA"
  | "AMAZON_DYNAMODB"
  | "HTTP"
  | "AMAZON_EVENTBRIDGE";

export interface LambdaDataSourceConfig {
  /** ARN of the Lambda function this data source invokes. */
  lambdaFunctionArn: string;
}

export interface DynamodbDataSourceConfig {
  /** Name of the DynamoDB table. */
  tableName: string;
  /**
   * Region the table lives in.
   * @default the ambient AWS region
   */
  awsRegion?: string;
  /** Use the caller's credentials instead of the service role. */
  useCallerCredentials?: boolean;
  /** Whether conflict detection (versioning) is enabled. */
  versioned?: boolean;
}

export interface HttpDataSourceConfig {
  /** The HTTP endpoint, e.g. `https://api.example.com`. */
  endpoint: string;
}

export interface DataSourceProps {
  /**
   * ID of the GraphQL API this data source belongs to. Usually derived
   * from `api.apiId` by the {@link DataSource} wrapper.
   */
  apiId: string;
  /**
   * Name of the data source (`[_A-Za-z][_0-9A-Za-z]*` — no dashes). If
   * omitted, a deterministic name is generated from the app, stage, and
   * logical ID (dashes sanitized to underscores). Changing the name
   * triggers a replacement.
   */
  name?: string;
  /** Description of the data source. */
  description?: string;
  /**
   * The data source type. `NONE` (local compute), `AWS_LAMBDA`,
   * `AMAZON_DYNAMODB`, `HTTP`, or `AMAZON_EVENTBRIDGE`.
   */
  type: DataSourceType;
  /**
   * The ARN of an existing IAM role AppSync assumes to access the target.
   * When omitted (and the type needs one), a service role is created
   * automatically with `appsync.amazonaws.com` trust and least-privilege
   * access to the configured target.
   */
  serviceRoleArn?: string;
  /**
   * Additional IAM policy statements attached to the auto-created service
   * role (ignored when {@link DataSourceProps.serviceRoleArn} is provided).
   */
  policyStatements?: PolicyStatement[];
  /** Lambda target — required when `type` is `AWS_LAMBDA`. */
  lambdaConfig?: LambdaDataSourceConfig;
  /** DynamoDB target — required when `type` is `AMAZON_DYNAMODB`. */
  dynamodbConfig?: DynamodbDataSourceConfig;
  /** HTTP target — required when `type` is `HTTP`. */
  httpConfig?: HttpDataSourceConfig;
}

export interface AppSyncDataSource extends Resource<
  "AWS.AppSync.DataSource",
  DataSourceProps,
  {
    /** The API this data source belongs to. */
    apiId: string;
    /** The data source name (referenced by resolvers and functions). */
    name: string;
    /** The data source ARN. */
    dataSourceArn: string;
    /** The data source type. */
    type: DataSourceType;
    /** The service role AppSync assumes, if any. */
    serviceRoleArn: string | undefined;
    /**
     * Name of the auto-created service role. `undefined` when an explicit
     * {@link DataSourceProps.serviceRoleArn} is used or no role is needed.
     */
    roleName: string | undefined;
  },
  never,
  Providers
> {}

/**
 * An AppSync data source — the target a resolver reads from or writes to.
 *
 * For `AWS_LAMBDA` and `AMAZON_DYNAMODB` targets a least-privilege service
 * role is created automatically (unless an explicit `serviceRoleArn` is
 * given): `lambda:InvokeFunction` on the function, or the DynamoDB
 * read/write actions on the table and its indexes.
 * ### Creating Data Sources
 * **Example:** Lambda data source (auto-created invoke role)
 * ```typescript
 * const ds = yield* AppSync.DataSource("LambdaDS", {
 *   api,
 *   type: "AWS_LAMBDA",
 *   lambdaConfig: { lambdaFunctionArn: fn.functionArn },
 * });
 * ```
 *
 * **Example:** NONE data source (local compute)
 * ```typescript
 * const local = yield* AppSync.DataSource("Local", {
 *   api,
 *   type: "NONE",
 * });
 * ```
 *
 * **Example:** DynamoDB data source
 * ```typescript
 * const ds = yield* AppSync.DataSource("TableDS", {
 *   api,
 *   type: "AMAZON_DYNAMODB",
 *   dynamodbConfig: { tableName: table.tableName },
 * });
 * ```
 *
 * @resource
 */
export const DataSourceResource = Resource<AppSyncDataSource>("AWS.AppSync.DataSource");

export interface DataSourceInputProps extends Omit<
  {
    [K in keyof DataSourceProps]?: Input<DataSourceProps[K]>;
  },
  "apiId" | "type"
> {
  /**
   * The `GraphqlApi` this data source belongs to (preferred). Alternatively
   * pass a raw `apiId`.
   */
  api?: GraphqlApi;
  apiId?: Input<string>;
  type: Input<DataSourceType>;
}

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

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

      const getDataSourceSafe = (apiId: string, name: string) =>
        appsync.getDataSource({ apiId, name }).pipe(
          Effect.map((response) => response.dataSource),
          Effect.catchTag("NotFoundException", () => Effect.undefined),
        );

      /**
       * Least-privilege statements for the auto-created service role,
       * derived from the configured target.
       */
      const buildRolePolicyStatements = (
        news: DataSourceProps,
        region: string,
        accountId: string,
      ): PolicyStatement[] => {
        const statements: PolicyStatement[] = [];
        if (news.type === "AWS_LAMBDA" && news.lambdaConfig !== undefined) {
          const arn = news.lambdaConfig.lambdaFunctionArn;
          statements.push({
            Effect: "Allow",
            Action: ["lambda:InvokeFunction"],
            Resource: /:function:[^:]+:/.test(arn) ? [arn] : [arn, `${arn}:*`],
          });
        }
        if (news.type === "AMAZON_DYNAMODB" && news.dynamodbConfig !== undefined) {
          const tableRegion = news.dynamodbConfig.awsRegion ?? region;
          const tableArn = `arn:aws:dynamodb:${tableRegion}:${accountId}:table/${news.dynamodbConfig.tableName}`;
          statements.push({
            Effect: "Allow",
            Action: [
              "dynamodb:BatchGetItem",
              "dynamodb:BatchWriteItem",
              "dynamodb:ConditionCheckItem",
              "dynamodb:DeleteItem",
              "dynamodb:GetItem",
              "dynamodb:PutItem",
              "dynamodb:Query",
              "dynamodb:Scan",
              "dynamodb:UpdateItem",
            ],
            Resource: [tableArn, `${tableArn}/index/*`],
          });
        }
        statements.push(...(news.policyStatements ?? []));
        return statements;
      };

      const needsServiceRole = (news: DataSourceProps): boolean =>
        news.type === "AWS_LAMBDA" ||
        news.type === "AMAZON_DYNAMODB" ||
        news.type === "AMAZON_EVENTBRIDGE";

      /**
       * Ensure the auto-created service role exists with the
       * `appsync.amazonaws.com` trust policy and the desired inline
       * policy. Idempotent across reconciles.
       */
      const ensureServiceRole = Effect.fn(function* ({
        id,
        roleName,
        statements,
      }: {
        id: string;
        roleName: string;
        statements: PolicyStatement[];
      }) {
        const tags = yield* createInternalTags(id);
        const role = yield* iam
          .createRole({
            RoleName: roleName,
            AssumeRolePolicyDocument: JSON.stringify({
              Version: "2012-10-17",
              Statement: [
                {
                  Effect: "Allow",
                  Principal: { Service: "appsync.amazonaws.com" },
                  Action: "sts:AssumeRole",
                },
              ],
            }),
            Tags: Object.entries(tags).map(([Key, Value]) => ({ Key, Value })),
          })
          .pipe(
            Effect.catchTag("EntityAlreadyExistsException", () =>
              iam.getRole({ RoleName: roleName }),
            ),
          );

        if (statements.length > 0) {
          yield* iam.putRolePolicy({
            RoleName: roleName,
            PolicyName: `${roleName}-policy`,
            PolicyDocument: JSON.stringify({
              Version: "2012-10-17",
              Statement: statements,
            }),
          });
        } else {
          yield* iam
            .deleteRolePolicy({
              RoleName: roleName,
              PolicyName: `${roleName}-policy`,
            })
            .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
        }

        return role.Role.Arn;
      });

      /** Delete the auto-created service role and its inline policies. */
      const deleteServiceRole = Effect.fn(function* (roleName: string) {
        yield* iam.listRolePolicies.items({ RoleName: roleName }).pipe(
          Stream.mapEffect((policyName) =>
            iam
              .deleteRolePolicy({
                RoleName: roleName,
                PolicyName: policyName,
              })
              .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void)),
          ),
          Stream.runDrain,
          Effect.catchTag("NoSuchEntityException", () => Effect.void),
        );
        yield* iam
          .deleteRole({ RoleName: roleName })
          .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
      });

      const toWireConfigs = (news: DataSourceProps, region: string) => ({
        lambdaConfig: news.lambdaConfig,
        dynamodbConfig:
          news.dynamodbConfig === undefined
            ? undefined
            : {
                tableName: news.dynamodbConfig.tableName,
                awsRegion: news.dynamodbConfig.awsRegion ?? region,
                useCallerCredentials: news.dynamodbConfig.useCallerCredentials,
                versioned: news.dynamodbConfig.versioned,
              },
        httpConfig: news.httpConfig,
      });

      const toAttributes = (
        apiId: string,
        ds: appsync.DataSource,
        roleName: string | undefined,
      ): AppSyncDataSource["Attributes"] => ({
        apiId,
        name: ds.name!,
        dataSourceArn: ds.dataSourceArn!,
        type: ds.type as DataSourceType,
        serviceRoleArn: ds.serviceRoleArn,
        roleName,
      });

      return DataSourceResource.Provider.of({
        stables: ["apiId", "name", "dataSourceArn"],

        // Sub-resource keyed entirely by its GraphQL API (apiId) with no global
        // enumeration API of its own — nuke reaches it through the parent's
        // deletion, so enumeration returns empty per the ProviderService
        // doctrine.
        list: () => Effect.succeed([]),

        read: Effect.fn(function* ({ id, olds, output }) {
          const apiId = output?.apiId ?? olds?.apiId;
          if (apiId === undefined) return undefined;
          const name = output?.name ?? (yield* createName(id, olds ?? {}));
          const ds = yield* getDataSourceSafe(apiId, name);
          if (ds?.name == null) return undefined;
          return toAttributes(apiId, ds, output?.roleName);
        }),

        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createName(id, olds ?? {});
          const newName = yield* createName(id, news ?? {});
          if (news.apiId !== olds.apiId || oldName !== newName) {
            return { action: "replace" } as const;
          }
          // type/config/role converge via updateDataSource
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const { region, accountId } = yield* AWSEnvironment.current;
          const apiId = output?.apiId ?? news.apiId;
          const name = output?.name ?? (yield* createName(id, news));
          const configs = toWireConfigs(news, region);

          // Ensure the service role first — the data source cannot point
          // at a Lambda/DynamoDB target without one.
          let serviceRoleArn = news.serviceRoleArn;
          let roleName: string | undefined;
          if (serviceRoleArn === undefined && needsServiceRole(news)) {
            roleName = yield* createPhysicalName({ id, maxLength: 64 });
            serviceRoleArn = yield* ensureServiceRole({
              id,
              roleName,
              statements: buildRolePolicyStatements(news, region, accountId),
            });
          }

          // 1. OBSERVE
          let observed = yield* getDataSourceSafe(apiId, name);

          // 2. ENSURE — a fresh role can take a few seconds to become
          //    assumable by AppSync.
          if (observed?.name == null) {
            const created = yield* appsync
              .createDataSource({
                apiId,
                name,
                description: news.description,
                type: news.type,
                serviceRoleArn,
                ...configs,
              })
              .pipe(retryConcurrentModification, retryWhileRolePropagates);
            observed = created.dataSource!;
            yield* session.note(`Created data source ${name}`);
          } else {
            // 3. SYNC — single update when the observed surface drifted.
            const surface = (ds: {
              description?: string;
              type?: string;
              serviceRoleArn?: string;
              lambdaConfig?: appsync.LambdaDataSourceConfig;
              dynamodbConfig?: appsync.DynamodbDataSourceConfig;
              httpConfig?: appsync.HttpDataSourceConfig;
            }) =>
              JSON.parse(
                JSON.stringify({
                  description: ds.description,
                  type: ds.type,
                  serviceRoleArn: ds.serviceRoleArn,
                  lambdaConfig: ds.lambdaConfig,
                  // AWS normalizes optional booleans into the response;
                  // mirror the defaults so no-ops stay no-ops.
                  dynamodbConfig:
                    ds.dynamodbConfig === undefined
                      ? undefined
                      : {
                          tableName: ds.dynamodbConfig.tableName,
                          awsRegion: ds.dynamodbConfig.awsRegion,
                          useCallerCredentials: ds.dynamodbConfig.useCallerCredentials ?? false,
                          versioned: ds.dynamodbConfig.versioned ?? false,
                        },
                  httpConfig: ds.httpConfig,
                }),
              );
            const desired = surface({
              description: news.description,
              type: news.type,
              serviceRoleArn,
              ...configs,
            });
            if (!deepEqual(surface(observed), desired)) {
              const updated = yield* appsync
                .updateDataSource({
                  apiId,
                  name,
                  description: news.description,
                  type: news.type,
                  serviceRoleArn,
                  ...configs,
                })
                .pipe(retryConcurrentModification, retryWhileRolePropagates);
              observed = updated.dataSource ?? observed;
              yield* session.note(`Updated data source ${name}`);
            }
          }

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

        delete: Effect.fn(function* ({ output }) {
          yield* retryConcurrentModification(
            appsync
              .deleteDataSource({ apiId: output.apiId, name: output.name })
              .pipe(Effect.catchTag("NotFoundException", () => Effect.void)),
          );
          if (output.roleName !== undefined) {
            yield* deleteServiceRole(output.roleName);
          }
        }),
      });
    }),
  );