sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ DynamoDB/ BindingHttp.ts

import type { Input } from "alchemy/Input";
import type * as Output from "alchemy/Output";
import * as Effect from "effect/Effect";
import * as AWSBindings from "../AWSBindings.ts";
import type { PolicyStatement } from "../IAM/Policy.ts";
import { regionFromArn } from "../Lambda/BindingHttp.ts";
import type { Table } from "./Table.ts";

/**
 * Shared scaffolding for AWS DynamoDB HTTP bindings.
 *
 * NOT exported from `index.ts` — every near-identical `{Op}Http.ts` in this
 * service is a thin `Layer.effect(Cap, make…HttpBinding({ … }))` over one of
 * the builders below. Everything except the operation, the IAM action list,
 * and the granted ARNs is boilerplate. Genuinely-different bindings
 * (multi-table batches/transactions, restores, the batched sink) stay
 * bespoke but share {@link grantTables} / {@link tablesRegion}.
 *
 * Every binding works on any host (see `AWSBindings.ts`):
 *
 * - on a host that runs as an IAM role the deploy-time grant goes on that
 *   role and requests use the ambient `Credentials` / `Region`;
 * - on any other host the grant goes on the Role Alchemy creates for it, and
 *   each operation is resolved with `AWSBindings.withCredentials` to sign
 *   with that Role in the bound table's region (parsed from its ARN).
 */

/**
 * Grant the host `policyStatements` under `label`, recorded as
 * `Allow(<host>, <label>)` (see `AWSBindings.Bind`). Deploy-only: the grant
 * sits behind the `__ALCHEMY_RUNTIME__` guard so the bundler drops it.
 */
export const GrantTables = Effect.gen(function* () {
  const bind = yield* AWSBindings.Bind;
  return Effect.fn(function* (label: string, policyStatements: () => Input<PolicyStatement>[]) {
    if (!globalThis.__ALCHEMY_RUNTIME__) {
      yield* bind`${label}`({ policyStatements: policyStatements() });
    }
  });
});

/**
 * The region a host with a created key signs requests in, for
 * `AWSBindings.withCredentials`: the region of the bound tables, parsed from
 * their ARNs (which this binds onto the host). Tables bound together must
 * share one region.
 *
 * The ARN is used rather than `Table.region` because tables whose state
 * predates that attribute keep their old attributes until their next update.
 */
export const tablesRegion = Effect.fn(function* (tables: readonly Table[]) {
  const arns: Effect.Effect<string>[] = [];
  for (const table of tables) {
    arns.push(yield* table.tableArn);
  }
  return Effect.gen(function* () {
    const regions = [...new Set((yield* Effect.all(arns)).map(regionFromArn))];
    if (regions.length !== 1) {
      return yield* Effect.die(
        new Error(
          `DynamoDB tables bound together must share one AWS region, got: ${regions.join(", ")}`,
        ),
      );
    }
    return regions[0]!;
  });
});

/**
 * Build the impl Effect for an account-level operation (`ListTables`,
 * `DescribeLimits`): the runtime callable passes the caller's request
 * through unchanged and the deploy-time half grants `actions` on `*`
 * (these DynamoDB actions do not support resource-level permissions).
 */
export const makeAccountHttpBinding = <I, A, E, R>(options: {
  /** Fully-qualified binding tag, e.g. `AWS.DynamoDB.ListTables`. */
  tag: string;
  /**
   * The distilled operation, invoked with the caller's request as-is.
   * Resolved with the host's credentials (see `AWSBindings.withCredentials`),
   * signing in the stack's region on a host with a created key.
   */
  operation: Effect.Effect<(input: I) => Effect.Effect<A, E>, never, R>;
  /** IAM actions granted on `*`. */
  actions: readonly string[];
}) =>
  Effect.gen(function* () {
    const grantTables = yield* GrantTables;
    const op = yield* AWSBindings.withCredentials(options.operation);

    return Effect.fn(function* () {
      yield* grantTables(`${options.tag}()`, () => [
        {
          Effect: "Allow",
          Action: [...options.actions],
          Resource: ["*"],
        },
      ]);
      return Effect.fn(options.tag)(function* (request?: I) {
        return yield* op((request ?? {}) as I);
      });
    });
  });

/**
 * Build the impl Effect for a table-scoped operation: the runtime callable
 * injects the bound {@link Table}'s physical name as `TableName` and the
 * deploy-time half grants `actions` on `resources` (default: the table ARN).
 */
export const makeTableHttpBinding = <I extends { TableName?: string }, A, E, R>(options: {
  /** Fully-qualified binding tag, e.g. `AWS.DynamoDB.GetItem`. */
  tag: string;
  /**
   * The distilled operation; `TableName` is injected from the table.
   * Resolved with the host's credentials (see `AWSBindings.withCredentials`),
   * signing in the table's region on a host with a created key.
   */
  operation: Effect.Effect<(input: I) => Effect.Effect<A, E>, never, R>;
  /** IAM actions granted on `resources`. */
  actions: readonly string[];
  /** ARNs the actions are granted on. @default the table ARN */
  resources?: (table: Table) => (string | Output.Output<string>)[];
}) =>
  Effect.gen(function* () {
    const grantTables = yield* GrantTables;
    return Effect.fn(function* (table: Table) {
      const TableName = yield* table.tableName;
      // resolved per bind because a host with a created key signs in the table's own region
      const op = yield* AWSBindings.withCredentials(options.operation, tablesRegion([table]));
      yield* grantTables(`${options.tag}(${table.LogicalId})`, () => [
        {
          Effect: "Allow",
          Action: [...options.actions],
          Resource: options.resources?.(table) ?? [table.tableArn],
        },
      ]);
      return Effect.fn(`${options.tag}(${table.LogicalId})`)(function* (
        request?: Omit<I, "TableName">,
      ) {
        return yield* op({
          ...request,
          TableName: yield* TableName,
        } as I);
      });
    });
  });

/**
 * Build the impl Effect for an ARN-scoped operation: the runtime callable
 * injects the bound {@link Table}'s ARN under `key` (`ResourceArn` for the
 * tagging APIs, `TableArn` for the export APIs) and the deploy-time half
 * grants `actions` on `resources` (default: the table ARN).
 */
export const makeTableArnHttpBinding = <
  K extends "ResourceArn" | "TableArn",
  I extends { [P in K]?: string },
  A,
  E,
  R,
>(options: {
  /** Fully-qualified binding tag, e.g. `AWS.DynamoDB.ListTagsOfResource`. */
  tag: string;
  /** The request field the table ARN is injected under. */
  key: K;
  /**
   * The distilled operation; the table ARN is injected under `key`.
   * Resolved with the host's credentials (see `AWSBindings.withCredentials`),
   * signing in the table's region on a host with a created key.
   */
  operation: Effect.Effect<(input: I) => Effect.Effect<A, E>, never, R>;
  /** IAM actions granted on `resources`. */
  actions: readonly string[];
  /** ARNs the actions are granted on. @default the table ARN */
  resources?: (table: Table) => (string | Output.Output<string>)[];
}) =>
  Effect.gen(function* () {
    const grantTables = yield* GrantTables;
    return Effect.fn(function* (table: Table) {
      const TableArn = yield* table.tableArn;
      // resolved per bind because a host with a created key signs in the table's own region
      const op = yield* AWSBindings.withCredentials(
        options.operation,
        Effect.succeed(Effect.map(TableArn, regionFromArn)),
      );
      yield* grantTables(`${options.tag}(${table.LogicalId})`, () => [
        {
          Effect: "Allow",
          Action: [...options.actions],
          Resource: options.resources?.(table) ?? [table.tableArn],
        },
      ]);
      return Effect.fn(`${options.tag}(${table.LogicalId})`)(function* (request?: Omit<I, K>) {
        return yield* op({
          ...request,
          [options.key]: yield* TableArn,
        } as I);
      });
    });
  });

/**
 * Build the impl Effect for an operation whose request carries its own
 * identifiers (a PartiQL statement, a backup or export ARN): the bound
 * {@link Table} only scopes the deploy-time IAM grant (and, on an external
 * host, the signing region); the request passes through unchanged.
 */
export const makeTableIamHttpBinding = <I, A, E, R>(options: {
  /** Fully-qualified binding tag, e.g. `AWS.DynamoDB.ExecuteStatement`. */
  tag: string;
  /**
   * The distilled operation, invoked with the caller's request as-is.
   * Resolved with the host's credentials (see `AWSBindings.withCredentials`),
   * signing in the table's region on a host with a created key.
   */
  operation: Effect.Effect<(input: I) => Effect.Effect<A, E>, never, R>;
  /** IAM actions granted on `resources`. */
  actions: readonly string[];
  /** ARNs the actions are granted on. */
  resources: (table: Table) => (string | Output.Output<string>)[];
}) =>
  Effect.gen(function* () {
    const grantTables = yield* GrantTables;
    return Effect.fn(function* (table: Table) {
      // resolved per bind because a host with a created key signs in the table's own region
      const op = yield* AWSBindings.withCredentials(options.operation, tablesRegion([table]));
      yield* grantTables(`${options.tag}(${table.LogicalId})`, () => [
        {
          Effect: "Allow",
          Action: [...options.actions],
          Resource: options.resources(table),
        },
      ]);
      return Effect.fn(`${options.tag}(${table.LogicalId})`)(function* (request: I) {
        return yield* op(request);
      });
    });
  });