sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Keyspaces/ Table.ts

import * as keyspaces from "@distilled.cloud/aws/keyspaces";
import * as keyspacesstreams from "@distilled.cloud/aws/keyspacesstreams";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import { 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 type { Providers } from "../Providers.ts";

export class KeyspacesTableNotReady extends Data.TaggedError("KeyspacesTableNotReady")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

/**
 * A Cassandra column definition. `type` is a CQL data type such as `text`,
 * `int`, `uuid`, `timestamp`, `blob`, or a collection like `list<text>`.
 */
export interface KeyspacesColumn {
  /** Column name. */
  name: string;
  /** CQL data type, e.g. `text`, `int`, `uuid`. */
  type: string;
}

/**
 * A clustering key column and its sort order.
 */
export interface KeyspacesClusteringKey {
  /** Name of a column also present in `columns`. */
  name: string;
  /**
   * Sort order for the clustering key.
   * @default "ASC"
   */
  orderBy?: "ASC" | "DESC";
}

/**
 * Read/write throughput mode for a table.
 */
export interface KeyspacesCapacity {
  /**
   * Billing mode.
   * @default "PAY_PER_REQUEST"
   */
  throughputMode: "PAY_PER_REQUEST" | "PROVISIONED";
  /** Provisioned read capacity units (only for `PROVISIONED`). */
  readCapacityUnits?: number;
  /** Provisioned write capacity units (only for `PROVISIONED`). */
  writeCapacityUnits?: number;
}

/**
 * Change data capture (CDC) stream configuration for a table.
 */
export interface KeyspacesCdcSpecification {
  /**
   * Whether CDC is enabled on the table.
   */
  status: "ENABLED" | "DISABLED";
  /**
   * What data is written to the table's stream for each changed row.
   * @default "NEW_AND_OLD_IMAGES"
   */
  viewType?: "NEW_IMAGE" | "OLD_IMAGE" | "KEYS_ONLY" | "NEW_AND_OLD_IMAGES";
}

export interface TableProps {
  /**
   * Name of the parent keyspace. Changing it replaces the table.
   */
  keyspaceName: string;
  /**
   * Name of the table. Must be 1-48 characters of `[a-zA-Z0-9_]`. If omitted a
   * deterministic physical name is generated. Changing the name replaces the
   * table.
   */
  tableName?: string;
  /**
   * All columns in the table, including those used as partition and clustering
   * keys. Adding new columns is applied in place; removing or retyping columns
   * replaces the table.
   */
  columns: KeyspacesColumn[];
  /**
   * Names of the columns forming the partition key (at least one). Changing
   * the partition key replaces the table.
   */
  partitionKeys: string[];
  /**
   * Columns forming the clustering (sort) key. Changing them replaces the
   * table.
   */
  clusteringKeys?: KeyspacesClusteringKey[];
  /**
   * Names of static columns (shared across all rows of a partition).
   */
  staticColumns?: string[];
  /**
   * Read/write throughput mode.
   * @default { throughputMode: "PAY_PER_REQUEST" }
   */
  capacity?: KeyspacesCapacity;
  /**
   * Enables point-in-time recovery (continuous backups).
   * @default false
   */
  pointInTimeRecovery?: boolean;
  /**
   * Enables row-level TTL on the table. Required before per-row TTLs can be
   * set. Enabling TTL cannot be undone without replacing the table.
   * @default false
   */
  ttlEnabled?: boolean;
  /**
   * Default TTL applied to all rows, e.g. `"1 day"` or `Duration.hours(12)`.
   * The API stores whole seconds. Requires `ttlEnabled`.
   */
  defaultTimeToLive?: Duration.Input;
  /**
   * Change data capture (CDC) stream configuration. Enabling CDC creates a
   * stream that captures row-level changes for 24 hours; consume it with the
   * `TableStreams` binding or the `keyspacesstreams` data-plane API.
   */
  cdcSpecification?: KeyspacesCdcSpecification;
  /**
   * User-defined tags for the table.
   */
  tags?: Record<string, string>;
}

export interface Table extends Resource<
  "AWS.Keyspaces.Table",
  TableProps,
  {
    /**
     * Name of the keyspace containing the table.
     */
    keyspaceName: string;
    /**
     * The table's physical name.
     */
    tableName: string;
    /**
     * ARN of the table.
     */
    tableArn: string;
    /**
     * Lifecycle status of the table (e.g. `CREATING`, `ACTIVE`).
     */
    status: string;
    /**
     * ARN of the most recent CDC stream, when `cdcSpecification` is enabled.
     */
    latestStreamArn: string | undefined;
  },
  never,
  Providers
> {}

/**
 * An Amazon Keyspaces (for Apache Cassandra) table.
 *
 * Tables are serverless and provisioned asynchronously (`CREATING` ->
 * `ACTIVE`), usually within a minute; the provider waits for `ACTIVE`
 * (bounded) before returning. Schema mutations (adding columns, changing
 * capacity/TTL/PITR) are applied in place; changing keys replaces the table.
 * ### Creating a Table
 * **Example:** Simple Key-Value Table
 * ```typescript
 * const table = yield* Table("Sessions", {
 *   keyspaceName: keyspace.keyspaceName,
 *   columns: [
 *     { name: "id", type: "uuid" },
 *     { name: "data", type: "text" },
 *   ],
 *   partitionKeys: ["id"],
 * });
 * ```
 *
 * **Example:** Table with a Clustering Key and TTL
 * ```typescript
 * const table = yield* Table("Events", {
 *   keyspaceName: keyspace.keyspaceName,
 *   columns: [
 *     { name: "device", type: "text" },
 *     { name: "ts", type: "timestamp" },
 *     { name: "payload", type: "blob" },
 *   ],
 *   partitionKeys: ["device"],
 *   clusteringKeys: [{ name: "ts", orderBy: "DESC" }],
 *   ttlEnabled: true,
 *   defaultTimeToLive: "1 day",
 * });
 * ```
 *
 * ### Change Data Capture
 * **Example:** CDC-Enabled Table
 * ```typescript
 * const table = yield* Table("Orders", {
 *   keyspaceName: keyspace.keyspaceName,
 *   columns: [
 *     { name: "id", type: "uuid" },
 *     { name: "total", type: "int" },
 *   ],
 *   partitionKeys: ["id"],
 *   cdcSpecification: {
 *     status: "ENABLED",
 *     viewType: "NEW_AND_OLD_IMAGES",
 *   },
 * });
 * // table.latestStreamArn → consume via the TableStreams binding
 * ```
 *
 * @resource
 */
export const Table = Resource<Table>("AWS.Keyspaces.Table");

const toTagRecord = (tags: keyspaces.Tag[] | undefined): Record<string, string> =>
  Object.fromEntries((tags ?? []).map((t) => [t.key, t.value]));

const buildSchema = (props: TableProps): keyspaces.SchemaDefinition => ({
  allColumns: props.columns.map((c) => ({ name: c.name, type: c.type })),
  partitionKeys: props.partitionKeys.map((name) => ({ name })),
  clusteringKeys: props.clusteringKeys?.map((c) => ({
    name: c.name,
    orderBy: c.orderBy ?? "ASC",
  })),
  staticColumns: props.staticColumns?.map((name) => ({ name })),
});

const activeStatuses = new Set(["ACTIVE"]);

export const TableProvider = () =>
  Provider.effect(
    Table,
    Effect.gen(function* () {
      const toName = (id: string, props: Partial<TableProps>) =>
        props.tableName
          ? Effect.succeed(props.tableName)
          : createPhysicalName({ id, maxLength: 48 }).pipe(
              Effect.map((n) => n.replaceAll("-", "_")),
            );

      const readTable = Effect.fn(function* (keyspaceName: string, tableName: string) {
        return yield* keyspaces
          .getTable({ keyspaceName, tableName })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      });

      const readTags = Effect.fn(function* (arn: string) {
        const tags = yield* keyspaces.listTagsForResource.items({ resourceArn: arn }).pipe(
          Stream.runCollect,
          Effect.map((c) => Array.from(c)),
          Effect.orElseSucceed(() => []),
        );
        return toTagRecord(tags);
      });

      // Resolve the most recent CDC stream's ARN (streams are labeled with
      // their creation timestamp; the lexicographically greatest label is the
      // latest). Only meaningful while CDC is (or was recently) enabled.
      const readLatestStreamArn = Effect.fn(function* (keyspaceName: string, tableName: string) {
        const response = yield* keyspacesstreams
          .listStreams({ keyspaceName, tableName })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
        const sorted = [...(response?.streams ?? [])].sort((a, b) =>
          b.streamLabel.localeCompare(a.streamLabel),
        );
        return sorted[0]?.streamArn;
      });

      const isCdcEnabled = (table: keyspaces.GetTableResponse) => {
        const status = table.cdcSpecification?.status;
        return status === "ENABLED" || status === "ENABLING";
      };

      // A freshly-enabled stream can lag ListStreams visibility briefly;
      // poll (bounded ~60s) and fall back to undefined rather than failing
      // the reconcile.
      const waitForStreamArn = Effect.fn(function* (keyspaceName: string, tableName: string) {
        return yield* readLatestStreamArn(keyspaceName, tableName).pipe(
          Effect.flatMap((arn) =>
            arn !== undefined
              ? Effect.succeed<string | undefined>(arn)
              : Effect.fail(
                  new KeyspacesTableNotReady({
                    message: `CDC stream for '${keyspaceName}.${tableName}' not yet visible`,
                  }),
                ),
          ),
          Effect.retry({
            schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(12)]),
          }),
          Effect.orElseSucceed(() => undefined),
        );
      });

      // Bounded readiness wait; Keyspaces tables typically reach ACTIVE within
      // a minute. Budget ~5 min (60 * 5s). When `requiredColumns` is provided
      // the wait also blocks until those columns are visible in the schema —
      // AddColumn updates return before the table transitions out of ACTIVE and
      // the new columns propagate to GetTable with a short lag.
      const waitForActive = Effect.fn(function* (
        keyspaceName: string,
        tableName: string,
        requiredColumns?: readonly string[],
      ) {
        const policy = Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(60)]);
        return yield* readTable(keyspaceName, tableName).pipe(
          Effect.flatMap((table) => {
            if (table === undefined) {
              return Effect.fail(
                new KeyspacesTableNotReady({ message: `Keyspaces table '${tableName}' not found` }),
              );
            }
            if (!activeStatuses.has(table.status ?? "")) {
              return Effect.fail(
                new KeyspacesTableNotReady({
                  message: `Keyspaces table '${tableName}' not active (status: ${table.status})`,
                }),
              );
            }
            if (requiredColumns !== undefined) {
              const present = new Set(
                (table.schemaDefinition?.allColumns ?? []).map((c) => c.name),
              );
              const missing = requiredColumns.filter((c) => !present.has(c));
              if (missing.length > 0) {
                return Effect.fail(
                  new KeyspacesTableNotReady({
                    message: `Keyspaces table '${tableName}' missing columns: ${missing.join(", ")}`,
                  }),
                );
              }
            }
            return Effect.succeed(table);
          }),
          Effect.retry({ schedule: policy }),
        );
      });

      const toCapacity = (
        capacity: KeyspacesCapacity | undefined,
      ): keyspaces.CapacitySpecification | undefined =>
        capacity === undefined
          ? undefined
          : {
              throughputMode: capacity.throughputMode,
              readCapacityUnits: capacity.readCapacityUnits,
              writeCapacityUnits: capacity.writeCapacityUnits,
            };

      return {
        stables: ["keyspaceName", "tableName", "tableArn"],

        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return undefined;
          const oldProps = olds as TableProps | undefined;
          if (oldProps === undefined) return undefined;
          if (news.keyspaceName !== oldProps.keyspaceName) {
            return { action: "replace" } as const;
          }
          if ((yield* toName(id, oldProps)) !== (yield* toName(id, news))) {
            return { action: "replace" } as const;
          }
          // Keys and column removals/retypes require a replacement; pure
          // column additions are handled in reconcile via UpdateTable.
          const newCols = new Map(news.columns.map((c) => [c.name, c.type]));
          const removedOrRetyped = oldProps.columns.some((c) => newCols.get(c.name) !== c.type);
          const keysChanged =
            JSON.stringify([...news.partitionKeys].sort()) !==
              JSON.stringify([...oldProps.partitionKeys].sort()) ||
            JSON.stringify(
              (news.clusteringKeys ?? []).map((c) => `${c.name}:${c.orderBy ?? "ASC"}`).sort(),
            ) !==
              JSON.stringify(
                (oldProps.clusteringKeys ?? [])
                  .map((c) => `${c.name}:${c.orderBy ?? "ASC"}`)
                  .sort(),
              ) ||
            JSON.stringify([...(news.staticColumns ?? [])].sort()) !==
              JSON.stringify([...(oldProps.staticColumns ?? [])].sort());
          if (removedOrRetyped || keysChanged) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const props = (olds ?? {}) as Partial<TableProps>;
          const keyspaceName = output?.keyspaceName ?? props.keyspaceName;
          if (keyspaceName === undefined) return undefined;
          const tableName = output?.tableName ?? (yield* toName(id, props));
          const found = yield* readTable(keyspaceName, tableName);
          if (found === undefined || found.status === "DELETING") {
            return undefined;
          }
          const attrs = {
            keyspaceName: found.keyspaceName,
            tableName: found.tableName,
            tableArn: found.resourceArn,
            status: found.status ?? "ACTIVE",
            latestStreamArn: isCdcEnabled(found)
              ? yield* readLatestStreamArn(found.keyspaceName, found.tableName)
              : undefined,
          };
          const tags = yield* readTags(found.resourceArn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const props = news as TableProps;
          const keyspaceName = props.keyspaceName;
          const tableName = output?.tableName ?? (yield* toName(id, props));
          // The Keyspaces API expects the default TTL in whole seconds.
          const desiredTtlSeconds = toWireSeconds(props.defaultTimeToLive);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...props.tags };

          // 1. Observe — cloud state is authoritative.
          let observed = yield* readTable(keyspaceName, tableName);

          // 2. Ensure — create if missing; tolerate the AlreadyExists race.
          if (observed === undefined) {
            yield* keyspaces
              .createTable({
                keyspaceName,
                tableName,
                schemaDefinition: buildSchema(props),
                capacitySpecification: toCapacity(props.capacity),
                pointInTimeRecovery: props.pointInTimeRecovery ? { status: "ENABLED" } : undefined,
                ttl: props.ttlEnabled ? { status: "ENABLED" } : undefined,
                defaultTimeToLive: desiredTtlSeconds,
                cdcSpecification:
                  props.cdcSpecification?.status === "ENABLED"
                    ? {
                        status: "ENABLED",
                        viewType: props.cdcSpecification.viewType ?? "NEW_AND_OLD_IMAGES",
                      }
                    : undefined,
                tags: Object.entries(desiredTags).map(([key, value]) => ({
                  key,
                  value,
                })),
              })
              .pipe(Effect.catchTag("ConflictException", () => Effect.void));
          }

          observed = yield* waitForActive(keyspaceName, tableName);

          // 3. Sync mutable aspects against observed state.
          const update: keyspaces.UpdateTableRequest = {
            keyspaceName,
            tableName,
          };
          let needsUpdate = false;

          const observedCols = new Set(
            (observed.schemaDefinition?.allColumns ?? []).map((c) => c.name),
          );
          const addColumns = props.columns.filter((c) => !observedCols.has(c.name));
          if (addColumns.length > 0) {
            update.addColumns = addColumns.map((c) => ({
              name: c.name,
              type: c.type,
            }));
            needsUpdate = true;
          }

          const desiredCapacity = toCapacity(props.capacity);
          if (
            desiredCapacity !== undefined &&
            (desiredCapacity.throughputMode !== observed.capacitySpecification?.throughputMode ||
              (desiredCapacity.throughputMode === "PROVISIONED" &&
                (desiredCapacity.readCapacityUnits !==
                  observed.capacitySpecification?.readCapacityUnits ||
                  desiredCapacity.writeCapacityUnits !==
                    observed.capacitySpecification?.writeCapacityUnits)))
          ) {
            update.capacitySpecification = desiredCapacity;
            needsUpdate = true;
          }

          const desiredPitr = props.pointInTimeRecovery ? "ENABLED" : "DISABLED";
          if (desiredPitr !== (observed.pointInTimeRecovery?.status ?? "DISABLED")) {
            update.pointInTimeRecovery = { status: desiredPitr };
            needsUpdate = true;
          }

          if (props.ttlEnabled && observed.ttl?.status !== "ENABLED") {
            update.ttl = { status: "ENABLED" };
            needsUpdate = true;
          }
          if (desiredTtlSeconds !== undefined && desiredTtlSeconds !== observed.defaultTimeToLive) {
            update.defaultTimeToLive = desiredTtlSeconds;
            needsUpdate = true;
          }

          const desiredCdcEnabled = props.cdcSpecification?.status === "ENABLED";
          if (desiredCdcEnabled !== isCdcEnabled(observed)) {
            update.cdcSpecification = desiredCdcEnabled
              ? {
                  status: "ENABLED",
                  viewType: props.cdcSpecification?.viewType ?? "NEW_AND_OLD_IMAGES",
                }
              : { status: "DISABLED" };
            needsUpdate = true;
          }

          if (needsUpdate) {
            yield* keyspaces.updateTable(update);
            observed = yield* waitForActive(
              keyspaceName,
              tableName,
              props.columns.map((c) => c.name),
            );
          }

          // 3b. Sync tags — diff against OBSERVED cloud tags.
          const observedTags = yield* readTags(observed.resourceArn);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* keyspaces.tagResource({
              resourceArn: observed.resourceArn,
              tags: upsert.map((t) => ({ key: t.Key, value: t.Value })),
            });
          }
          if (removed.length > 0) {
            yield* keyspaces.untagResource({
              resourceArn: observed.resourceArn,
              tags: removed.map((key) => ({ key, value: "" })),
            });
          }

          yield* session.note(`${keyspaceName}.${tableName}`);
          return {
            keyspaceName: observed.keyspaceName,
            tableName: observed.tableName,
            tableArn: observed.resourceArn,
            status: observed.status ?? "ACTIVE",
            latestStreamArn: isCdcEnabled(observed)
              ? yield* waitForStreamArn(observed.keyspaceName, observed.tableName)
              : undefined,
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          const { keyspaceName, tableName } = output;
          yield* keyspaces.deleteTable({ keyspaceName, tableName }).pipe(
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
            // A table still CREATING/UPDATING rejects delete with
            // ConflictException; retry until it settles.
            Effect.retry({
              while: (e) => e._tag === "ConflictException",
              schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(24)]),
            }),
          );
          // Wait (bounded) until the table is gone so the parent keyspace can
          // be deleted without a ConflictException.
          yield* readTable(keyspaceName, tableName).pipe(
            Effect.flatMap((t) =>
              t === undefined
                ? Effect.void
                : Effect.fail(
                    new KeyspacesTableNotReady({ message: `Table '${tableName}' still deleting` }),
                  ),
            ),
            // Point-in-time-recovery tables take minutes to finish deleting.
            Effect.retry({
              schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(36)]),
            }),
            Effect.ignore,
          );
        }),

        // Table is keyed by a parent keyspace and cannot be enumerated
        // account-wide without iterating every keyspace; treated as a
        // sub-resource per the factory list() convention.
        list: () => Effect.succeed([]),
      };
    }),
  );