sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ FinSpace/ KxEnvironment.ts

import * as finspace from "@distilled.cloud/aws/finspace";
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, type Tags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as EffectStream from "effect/Stream";
import type { Providers } from "../Providers.ts";

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

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

export type KxEnvironmentStatus = finspace.EnvironmentStatus;
export type TransitGatewayConfiguration = finspace.TransitGatewayConfiguration;
export type CustomDNSServer = finspace.CustomDNSServer;

export interface KxEnvironmentProps {
  /**
   * Name of the kdb environment.
   * @default ${app}-${id}-${stage}-${suffix}
   */
  name?: string;
  /**
   * A description of the kdb environment.
   */
  description?: string;
  /**
   * The KMS key id used to encrypt data in the environment. Required;
   * changing it replaces the environment.
   */
  kmsKeyId: string;
  /**
   * Transit gateway to attach so on-prem kdb clients can reach the
   * environment. Attached once via `UpdateKxEnvironmentNetwork` after the
   * environment is created; FinSpace does not support changing an attached
   * network, so changing an existing configuration replaces the environment.
   */
  transitGatewayConfiguration?: TransitGatewayConfiguration;
  /**
   * Custom DNS servers to resolve on-prem hostnames from inside the
   * environment. Attached together with `transitGatewayConfiguration`;
   * changing an existing configuration replaces the environment.
   */
  customDNSConfiguration?: CustomDNSServer[];
  /**
   * Tags to associate with the environment.
   */
  tags?: Record<string, string>;
}

export interface KxEnvironment extends Resource<
  "AWS.FinSpace.KxEnvironment",
  KxEnvironmentProps,
  {
    /**
     * Service-assigned unique identifier of the kdb environment.
     */
    environmentId: string;
    /**
     * ARN of the kdb environment.
     */
    environmentArn: string;
    /**
     * The environment's name.
     */
    name: string;
    /**
     * Current lifecycle status of the environment.
     */
    status: KxEnvironmentStatus | undefined;
    /**
     * ID of the KMS key encrypting the environment.
     */
    kmsKeyId: string | undefined;
    /**
     * The environment's description.
     */
    description: string | undefined;
    /**
     * The transit gateway attached to the environment, if any.
     */
    transitGatewayConfiguration: TransitGatewayConfiguration | undefined;
    /**
     * The custom DNS servers configured on the environment, if any.
     */
    customDNSConfiguration: CustomDNSServer[] | undefined;
    /**
     * Current tags reported for the environment.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon FinSpace Managed kdb environment — the account-level container
 * that kdb databases, clusters, users, volumes and scaling groups live in.
 *
 * :::caution
 * kdb environment provisioning is slow (tens of minutes) and the service is
 * gated to onboarded accounts. Live lifecycle tests are gated behind
 * `AWS_TEST_FINSPACE=1`.
 * :::
 * ### Creating kdb Environments
 * **Example:** Basic kdb Environment
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const key = yield* AWS.KMS.Key("KdbKey", {});
 * const env = yield* AWS.FinSpace.KxEnvironment("Kdb", {
 *   kmsKeyId: key.keyArn,
 *   description: "managed kdb environment",
 * });
 * ```
 *
 * ### Connecting to On-Prem Networks
 * **Example:** Attach a Transit Gateway
 * ```typescript
 * const env = yield* AWS.FinSpace.KxEnvironment("Kdb", {
 *   kmsKeyId: key.keyArn,
 *   transitGatewayConfiguration: {
 *     transitGatewayID: "tgw-0123456789abcdef0",
 *     routableCIDRSpace: "10.0.0.0/16",
 *   },
 *   customDNSConfiguration: [
 *     { customDNSServerName: "dns.corp.example", customDNSServerIP: "10.0.0.2" },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const KxEnvironment = Resource<KxEnvironment>("AWS.FinSpace.KxEnvironment");

const createKxEnvironmentName = (id: string, props: { name?: string | undefined }) =>
  props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 255 });

const fetchKxTags = Effect.fn(function* (arn: string) {
  const response = yield* finspace
    .listTagsForResource({ resourceArn: arn })
    .pipe(
      Effect.catchTag(
        ["ResourceNotFoundException", "InvalidRequestException"],
        () => Effect.undefined,
      ),
    );
  return Object.fromEntries(
    Object.entries(response?.tags ?? {}).flatMap(([key, value]) =>
      value === undefined ? [] : [[key, value] as const],
    ),
  );
});

const isGone = (status: KxEnvironmentStatus | undefined) =>
  status === "DELETED" || status === "DELETING" || status === "DELETE_REQUESTED";

const sameJson = (a: unknown, b: unknown) =>
  JSON.stringify(a ?? null) === JSON.stringify(b ?? null);

interface KxEnvironmentView {
  environmentId?: string;
  environmentArn?: string;
  name?: string;
  status?: KxEnvironmentStatus;
  kmsKeyId?: string;
  description?: string;
  transitGatewayConfiguration?: TransitGatewayConfiguration;
  customDNSConfiguration?: CustomDNSServer[];
}

const toKxAttributes = Effect.fn(function* (env: KxEnvironmentView, fallbackId: string) {
  const environmentArn = env.environmentArn ?? "";
  const attrs: KxEnvironment["Attributes"] = {
    environmentId: env.environmentId ?? fallbackId,
    environmentArn,
    name: env.name ?? "",
    status: env.status,
    kmsKeyId: env.kmsKeyId,
    description: env.description,
    transitGatewayConfiguration: env.transitGatewayConfiguration,
    customDNSConfiguration: env.customDNSConfiguration
      ? [...env.customDNSConfiguration]
      : undefined,
    tags: environmentArn ? yield* fetchKxTags(environmentArn) : {},
  };
  return attrs;
});

const readKxEnvironmentById = Effect.fn(function* (environmentId: string) {
  const response = yield* finspace
    .getKxEnvironment({ environmentId })
    .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  if (!response || isGone(response.status)) return undefined;
  return response;
});

const findKxEnvironmentByName = Effect.fn(function* (name: string) {
  const environments = yield* finspace.listKxEnvironments.items({}).pipe(
    EffectStream.runCollect,
    Effect.map((chunk) => Array.from(chunk)),
  );
  return environments.find((env) => env.name === name && !isGone(env.status));
});

/**
 * A kdb environment still transitioning toward the awaited status — retried
 * by the bounded schedule in {@link waitForKxEnvironmentStatus}.
 */
class KxEnvironmentNotReady extends Data.TaggedError("KxEnvironmentNotReady")<{
  readonly environmentId: string;
  readonly status: string | undefined;
}> {}

/**
 * A kdb environment whose asynchronous provisioning converged to the
 * terminal `FAILED_CREATION` status.
 */
export class KxEnvironmentProvisioningFailed extends Data.TaggedError(
  "KxEnvironmentProvisioningFailed",
)<{
  readonly environmentId: string;
  readonly status: string | undefined;
}> {}

// Explicitly-typed retry wrapper — an inline `Effect.retry` in provider
// lifecycle code leaks `Retry.Return`'s conditional type into declaration
// emit and widens the provider layer to `unknown` for every consumer of
// `AWS.providers()`.
const retryWhileNotReady = <A, E extends { readonly _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "KxEnvironmentNotReady",
    // kdb environment provisioning is slow; poll every 20s up to ~40 min.
    schedule: Schedule.max([Schedule.spaced("20 seconds"), Schedule.recurs(120)]),
  });

// Deleting an environment that is still creating/updating surfaces as a
// Conflict — bounded retry through it. Explicitly typed for the same
// declaration-emit reason as retryWhileNotReady.
const retryThroughConflict = <A, E extends { readonly _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "ConflictException",
    schedule: Schedule.max([Schedule.spaced("15 seconds"), Schedule.recurs(8)]),
  });

const waitForKxEnvironmentStatus = (environmentId: string, target: "CREATED" | "DELETED") =>
  retryWhileNotReady(
    Effect.gen(function* () {
      const response = yield* finspace
        .getKxEnvironment({ environmentId })
        .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      const status = response?.status;
      if (target === "DELETED") {
        if (response === undefined || isGone(status)) return;
        return yield* new KxEnvironmentNotReady({ environmentId, status });
      }
      if (status === "CREATED") return;
      if (status === "FAILED_CREATION") {
        return yield* new KxEnvironmentProvisioningFailed({ environmentId, status });
      }
      return yield* new KxEnvironmentNotReady({ environmentId, status });
    }),
  );

export const KxEnvironmentProvider = () =>
  Provider.effect(
    KxEnvironment,
    Effect.gen(function* () {
      return {
        stables: ["environmentId", "environmentArn"],
        list: () =>
          Effect.gen(function* () {
            const environments = yield* finspace.listKxEnvironments.items({}).pipe(
              EffectStream.runCollect,
              Effect.map((chunk) => Array.from(chunk)),
            );
            return yield* Effect.forEach(
              environments.filter((env) => !isGone(env.status)),
              (env) => toKxAttributes(env, env.environmentId ?? ""),
              { concurrency: 5 },
            );
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const env = output?.environmentId
            ? yield* readKxEnvironmentById(output.environmentId)
            : yield* findKxEnvironmentByName(yield* createKxEnvironmentName(id, olds ?? {}));
          if (!env) return undefined;
          const attrs = yield* toKxAttributes(env, output?.environmentId ?? "");
          return (yield* hasAlchemyTags(id, attrs.tags as Tags)) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return;
          if (olds === undefined) return;
          // The KMS key is fixed at creation.
          if (olds.kmsKeyId !== news.kmsKeyId) {
            return { action: "replace" } as const;
          }
          // FinSpace does not support changing or detaching an attached
          // network (UpdateKxEnvironmentNetwork is attach-once).
          const hadNetwork =
            olds.transitGatewayConfiguration !== undefined ||
            olds.customDNSConfiguration !== undefined;
          if (
            hadNetwork &&
            (!sameJson(olds.transitGatewayConfiguration, news.transitGatewayConfiguration) ||
              !sameJson(olds.customDNSConfiguration, news.customDNSConfiguration))
          ) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          if (!news) {
            return yield* new KxEnvironmentInvalidProps({
              message: "FinSpace KxEnvironment requires props",
            });
          }
          const name = yield* createKxEnvironmentName(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // Observe — prefer the cached id; fall back to a name lookup so a
          // create whose state failed to persist is adopted, not duplicated.
          let env: KxEnvironmentView | undefined = output?.environmentId
            ? yield* readKxEnvironmentById(output.environmentId)
            : yield* findKxEnvironmentByName(name);

          // Ensure — create if missing, then wait for CREATED.
          if (env === undefined) {
            const created = yield* finspace.createKxEnvironment({
              name,
              description: news.description,
              kmsKeyId: news.kmsKeyId,
              tags: desiredTags,
            });
            if (!created.environmentId) {
              return yield* new KxEnvironmentUnexpectedResponse({
                message: `CreateKxEnvironment for '${name}' returned no id`,
              });
            }
            yield* session.note(`Creating kdb environment ${name} (${created.environmentId})...`);
            yield* waitForKxEnvironmentStatus(created.environmentId, "CREATED");
            env = yield* readKxEnvironmentById(created.environmentId);
            if (env === undefined) {
              return yield* new KxEnvironmentUnexpectedResponse({
                message: `failed to read created kdb environment ${name}`,
              });
            }
          }
          const environmentId = env.environmentId;
          if (environmentId === undefined) {
            return yield* new KxEnvironmentUnexpectedResponse({
              message: `kdb environment '${name}' has no environmentId`,
            });
          }

          // Sync network — UpdateKxEnvironmentNetwork is attach-once: apply
          // only when a network is desired and none is observed. (Changing
          // an attached network is a replacement — see diff.)
          const wantsNetwork =
            news.transitGatewayConfiguration !== undefined ||
            news.customDNSConfiguration !== undefined;
          const hasNetwork =
            env.transitGatewayConfiguration !== undefined ||
            (env.customDNSConfiguration !== undefined && env.customDNSConfiguration.length > 0);
          if (wantsNetwork && !hasNetwork) {
            yield* finspace.updateKxEnvironmentNetwork({
              environmentId,
              transitGatewayConfiguration: news.transitGatewayConfiguration,
              customDNSConfiguration: news.customDNSConfiguration,
            });
            yield* session.note(`Attaching network to kdb environment ${name}...`);
            yield* waitForKxEnvironmentStatus(environmentId, "CREATED");
            env = (yield* readKxEnvironmentById(environmentId)) ?? env;
          }

          // Sync mutable settings — only call UpdateKxEnvironment on drift.
          const needsUpdate =
            name !== env.name ||
            (news.description !== undefined && news.description !== env.description);
          if (needsUpdate) {
            yield* finspace.updateKxEnvironment({
              environmentId,
              name,
              description: news.description,
            });
            yield* session.note(`Updated kdb environment ${name}`);
          }

          // Sync tags — diff against observed cloud tags.
          const attrs = yield* toKxAttributes(env, environmentId);
          if (attrs.environmentArn) {
            const { removed, upsert } = diffTags(attrs.tags, desiredTags);
            if (removed.length > 0) {
              yield* finspace.untagResource({
                resourceArn: attrs.environmentArn,
                tagKeys: removed,
              });
            }
            if (upsert.length > 0) {
              yield* finspace.tagResource({
                resourceArn: attrs.environmentArn,
                tags: Object.fromEntries(upsert.map(({ Key, Value }) => [Key, Value])),
              });
            }
          }

          yield* session.note(attrs.environmentArn);

          const final = yield* readKxEnvironmentById(environmentId);
          if (!final) {
            return yield* new KxEnvironmentUnexpectedResponse({
              message: `failed to read reconciled kdb environment ${name}`,
            });
          }
          return yield* toKxAttributes(final, environmentId);
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* retryThroughConflict(
            finspace
              .deleteKxEnvironment({ environmentId: output.environmentId })
              .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void)),
          );
          yield* waitForKxEnvironmentStatus(output.environmentId, "DELETED");
        }),
      };
    }),
  );