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

import * as keyspaces from "@distilled.cloud/aws/keyspaces";
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 * as Data from "effect/Data";
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 KeyspaceNotReady extends Data.TaggedError("KeyspaceNotReady")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export interface KeyspaceProps {
  /**
   * Name of the keyspace. Must be 1-48 characters of `[a-zA-Z0-9_]`. If
   * omitted a deterministic physical name is generated. Changing the name
   * replaces the keyspace.
   */
  keyspaceName?: string;
  /**
   * User-defined tags for the keyspace.
   */
  tags?: Record<string, string>;
}

export interface Keyspace extends Resource<
  "AWS.Keyspaces.Keyspace",
  KeyspaceProps,
  {
    /**
     * The keyspace's physical name.
     */
    keyspaceName: string;
    /**
     * ARN of the keyspace.
     */
    keyspaceArn: string;
    /**
     * Replication strategy of the keyspace (`SINGLE_REGION` or
     * `MULTI_REGION`).
     */
    replicationStrategy: string;
  },
  never,
  Providers
> {}

/**
 * An Amazon Keyspaces (for Apache Cassandra) keyspace — the top-level
 * container for Cassandra tables.
 *
 * Keyspaces are serverless, free to create, and provisioned near-instantly,
 * so they make excellent building blocks and test fixtures.
 * ### Creating a Keyspace
 * **Example:** Basic Keyspace
 * ```typescript
 * const keyspace = yield* Keyspace("AppData", {});
 * ```
 *
 * **Example:** Named Keyspace with Tags
 * ```typescript
 * const keyspace = yield* Keyspace("AppData", {
 *   keyspaceName: "app_data",
 *   tags: { team: "platform" },
 * });
 * ```
 *
 * @resource
 */
export const Keyspace = Resource<Keyspace>("AWS.Keyspaces.Keyspace");

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

/**
 * Reserved Cassandra system keyspaces that exist in every Amazon Keyspaces
 * account and can never be deleted. Excluded from `list()` so account-wide
 * teardown (`alchemy unsafe nuke`) doesn't loop on undeletable resources.
 */
const SYSTEM_KEYSPACES = new Set([
  "system",
  "system_schema",
  "system_schema_mcs",
  "system_multiregion_info",
]);

export const KeyspaceProvider = () =>
  Provider.effect(
    Keyspace,
    Effect.gen(function* () {
      const toName = (id: string, props: KeyspaceProps) =>
        props.keyspaceName
          ? Effect.succeed(props.keyspaceName)
          : createPhysicalName({ id, maxLength: 48 }).pipe(
              Effect.map((n) => n.replaceAll("-", "_")),
            );

      const readKeyspace = Effect.fn(function* (name: string) {
        return yield* keyspaces
          .getKeyspace({ keyspaceName: name })
          .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);
      });

      return {
        stables: ["keyspaceName", "keyspaceArn"],

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

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.keyspaceName ?? (yield* toName(id, olds ?? {}));
          const found = yield* readKeyspace(name);
          if (found === undefined) return undefined;
          const attrs = {
            keyspaceName: found.keyspaceName,
            keyspaceArn: found.resourceArn,
            replicationStrategy: found.replicationStrategy,
          };
          const tags = yield* readTags(found.resourceArn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ id, news = {}, output, session }) {
          const name = output?.keyspaceName ?? (yield* toName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // 1. Observe — cloud state is authoritative.
          let observed = yield* readKeyspace(name);

          // 2. Ensure — create if missing; tolerate the AlreadyExists race.
          if (observed === undefined) {
            yield* keyspaces
              .createKeyspace({
                keyspaceName: name,
                tags: Object.entries(desiredTags).map(([key, value]) => ({
                  key,
                  value,
                })),
              })
              .pipe(Effect.catchTag("ConflictException", () => Effect.void));
            // Keyspace creation is effectively synchronous, but GetKeyspace can
            // briefly 404 right after create; retry a few times.
            observed = yield* readKeyspace(name).pipe(
              Effect.flatMap((k) =>
                k === undefined
                  ? Effect.fail(new KeyspaceNotReady({ message: `Keyspace '${name}' not found` }))
                  : Effect.succeed(k),
              ),
              Effect.retry({
                schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(10)]),
              }),
            );
          }

          // 3. 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(name);
          return {
            keyspaceName: observed.keyspaceName,
            keyspaceArn: observed.resourceArn,
            replicationStrategy: observed.replicationStrategy,
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          const name = output.keyspaceName;
          yield* keyspaces.deleteKeyspace({ keyspaceName: name }).pipe(
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
            // A keyspace whose tables are still deleting rejects with
            // ConflictException until they are gone — minutes for PITR and
            // restored tables, beyond the point GetTable already 404s.
            Effect.retry({
              while: (e) => e._tag === "ConflictException",
              schedule: Schedule.max([Schedule.fixed("10 seconds"), Schedule.recurs(48)]),
            }),
          );
          // Deletion is asynchronous — wait (bounded) until the keyspace is
          // actually gone so a subsequent recreate with the same name does not
          // hit ConflictException.
          yield* readKeyspace(name).pipe(
            Effect.flatMap((k) =>
              k === undefined
                ? Effect.void
                : Effect.fail(
                    new KeyspaceNotReady({ message: `Keyspace '${name}' still deleting` }),
                  ),
            ),
            Effect.retry({
              schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]),
            }),
            Effect.ignore,
          );
        }),

        list: () =>
          keyspaces.listKeyspaces.items({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk)
                .filter((k) => !SYSTEM_KEYSPACES.has(k.keyspaceName))
                .map((k) => ({
                  keyspaceName: k.keyspaceName,
                  keyspaceArn: k.resourceArn,
                  replicationStrategy: k.replicationStrategy,
                })),
            ),
          ),
      };
    }),
  );