sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Timestream/ DbInstance.ts

import * as influxdb from "@distilled.cloud/aws/timestream-influxdb";
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 Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as EffectStream from "effect/Stream";
import type { Providers } from "../Providers.ts";

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

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

export type DbInstanceStatus = influxdb.Status;

export interface DbInstanceProps {
  /**
   * Name that uniquely identifies the DB instance. Must be 3–40 characters,
   * start with a letter, and contain only lowercase letters, numbers, and
   * hyphens.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * The compute instance type to run InfluxDB on (e.g. `db.influx.medium`).
   */
  dbInstanceType: influxdb.DbInstanceType;
  /**
   * The amount of storage to allocate, in GiB.
   */
  allocatedStorage: number;
  /**
   * The IDs of the VPC subnets the DB instance is attached to.
   */
  vpcSubnetIds: string[];
  /**
   * The VPC security group IDs to associate with the DB instance.
   */
  vpcSecurityGroupIds: string[];
  /**
   * The initial InfluxDB admin password. Stored in AWS Secrets Manager by
   * Timestream; supplied only at creation. Must be alphanumeric
   * (`[a-zA-Z0-9]+`, 8-64 characters). Pass a redacted value, e.g.
   * `Redacted.make("SuperSecretPassword1")`.
   */
  password: Redacted.Redacted<string>;
  /**
   * The initial InfluxDB admin username.
   * @default "admin"
   */
  username?: string;
  /**
   * The name of the initial InfluxDB organization.
   */
  organization?: string;
  /**
   * The name of the initial InfluxDB bucket.
   */
  bucket?: string;
  /**
   * The storage tier (IOPS profile) for the DB instance.
   */
  dbStorageType?: influxdb.DbStorageType;
  /**
   * Whether the DB instance has a public IP and is reachable from the internet.
   * @default false
   */
  publiclyAccessible?: boolean;
  /**
   * Single- or multi-AZ deployment.
   * @default "SINGLE_AZ"
   */
  deploymentType?: influxdb.DeploymentType;
  /**
   * The identifier of an InfluxDB parameter group to associate.
   */
  dbParameterGroupIdentifier?: string;
  /**
   * Log delivery (S3) configuration for InfluxDB engine logs.
   */
  logDeliveryConfiguration?: influxdb.LogDeliveryConfiguration;
  /**
   * The port InfluxDB listens on.
   * @default 8086
   */
  port?: number;
  /**
   * The network protocol (IPv4 or dual-stack).
   */
  networkType?: influxdb.NetworkType;
  /**
   * Tags to associate with the DB instance.
   */
  tags?: Record<string, string>;
}

export interface DbInstance extends Resource<
  "AWS.Timestream.DbInstance",
  DbInstanceProps,
  {
    /**
     * Service-assigned unique identifier for the DB instance.
     */
    id: string;
    /**
     * The DB instance's name.
     */
    name: string;
    /**
     * ARN of the DB instance.
     */
    arn: string;
    /**
     * Current lifecycle status of the DB instance.
     */
    status: DbInstanceStatus | undefined;
    /**
     * The connection endpoint (host) for the DB instance.
     */
    endpoint: string | undefined;
    /**
     * The port InfluxDB is listening on.
     */
    port: number | undefined;
    /**
     * ARN of the Secrets Manager secret holding the InfluxDB auth parameters.
     */
    influxAuthParametersSecretArn: string | undefined;
    /**
     * The compute instance type backing the DB instance.
     */
    dbInstanceType: influxdb.DbInstanceType | undefined;
    /**
     * The allocated storage, in GiB.
     */
    allocatedStorage: number | undefined;
    /**
     * The subnets the DB instance is attached to.
     */
    vpcSubnetIds: string[];
    /**
     * Current tags reported for the DB instance.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon Timestream for InfluxDB DB instance — a managed, single-tenant
 * InfluxDB engine for time-series workloads.
 *
 * `DbInstance` owns the instance's lifecycle and its mutable configuration
 * (instance type, storage, port, parameter group, log delivery, deployment
 * type, and tags). Networking (subnets, security groups), the initial
 * credentials, organization, and bucket are fixed at creation.
 *
 * :::caution
 * Provisioning a DB instance takes ~15–20 minutes and incurs EC2-backed cost.
 * :::
 * ### Creating DB Instances
 * **Example:** Basic InfluxDB Instance
 * ```typescript
 * import * as Timestream from "@alchemy.run/aws/Timestream";
 *
 * const influx = yield* Timestream.DbInstance("Influx", {
 *   name: "my-influx",
 *   dbInstanceType: "db.influx.medium",
 *   allocatedStorage: 20,
 *   vpcSubnetIds: [subnetA.subnetId, subnetB.subnetId],
 *   vpcSecurityGroupIds: [securityGroup.groupId],
 *   password: Redacted.make("SuperSecretPassword1"),
 * });
 * ```
 *
 * @resource
 */
export const DbInstance = Resource<DbInstance>("AWS.Timestream.DbInstance");

const createInstanceName = (id: string, props: { name?: string | undefined }) =>
  Effect.gen(function* () {
    if (props.name) {
      return props.name;
    }
    return yield* createPhysicalName({ id, maxLength: 40 });
  });

const toAttrs = (
  instance: influxdb.GetDbInstanceOutput,
  tags: Record<string, string>,
): DbInstance["Attributes"] => ({
  id: instance.id,
  name: instance.name,
  arn: instance.arn,
  status: instance.status,
  endpoint: instance.endpoint,
  port: instance.port,
  influxAuthParametersSecretArn: instance.influxAuthParametersSecretArn,
  dbInstanceType: instance.dbInstanceType,
  allocatedStorage: instance.allocatedStorage,
  vpcSubnetIds: instance.vpcSubnetIds,
  tags,
});

const fetchTags = Effect.fn(function* (arn: string) {
  const response = yield* influxdb
    .listTagsForResource({ resourceArn: arn })
    .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  const tags = response?.tags ?? {};
  return Object.fromEntries(
    Object.entries(tags).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
  );
});

const readInstanceById = Effect.fn(function* (identifier: string) {
  const instance = yield* influxdb
    .getDbInstance({ identifier })
    .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  if (!instance) return undefined;
  return toAttrs(instance, yield* fetchTags(instance.arn));
});

const findInstanceByName = Effect.fn(function* (name: string) {
  const summaries = yield* influxdb.listDbInstances.pages({}).pipe(
    EffectStream.runCollect,
    Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.items ?? [])),
  );
  const match = summaries.find((summary) => summary.name === name);
  if (!match) return undefined;
  return yield* readInstanceById(match.id);
});

/**
 * A DB instance still transitioning toward the awaited status — retried by
 * {@link waitForStatus}'s bounded schedule.
 */
class DbInstanceNotReady extends Data.TaggedError("DbInstanceNotReady")<{
  readonly identifier: string;
  readonly status: string | undefined;
}> {}

/**
 * A DB instance whose asynchronous provisioning converged to a terminal
 * failure status (`FAILED` / `REBOOT_FAILED`).
 */
export class DbInstanceProvisioningFailed extends Data.TaggedError("DbInstanceProvisioningFailed")<{
  readonly identifier: string;
  readonly status: string;
}> {}

// 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, {
    // ParseError: a CREATING instance can transiently decode incompletely
    // while fields are still being populated — treat it as not-ready.
    while: (e) => e._tag === "DbInstanceNotReady" || e._tag === "ParseError",
    // Provisioning is slow (~15–20 min); poll every 20s up to ~30 min.
    schedule: Schedule.max([Schedule.spaced("20 seconds"), Schedule.recurs(90)]),
  });

const waitForStatus = (identifier: string, target: "AVAILABLE" | "DELETED") =>
  retryWhileNotReady(
    Effect.gen(function* () {
      const instance = yield* influxdb
        .getDbInstance({ identifier })
        .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      if (target === "DELETED") {
        if (instance === undefined) return;
        return yield* new DbInstanceNotReady({ identifier, status: instance.status });
      }
      if (instance?.status === "AVAILABLE") return;
      if (instance?.status === "FAILED" || instance?.status === "REBOOT_FAILED") {
        return yield* new DbInstanceProvisioningFailed({
          identifier,
          status: instance.status,
        });
      }
      return yield* new DbInstanceNotReady({ identifier, status: instance?.status });
    }),
  );

export const DbInstanceProvider = () =>
  Provider.effect(
    DbInstance,
    Effect.gen(function* () {
      return {
        stables: ["id", "arn", "name"],
        list: () =>
          Effect.gen(function* () {
            const summaries = yield* influxdb.listDbInstances.pages({}).pipe(
              EffectStream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.items ?? [])),
            );
            const hydrated = yield* Effect.forEach(
              summaries,
              (summary) => readInstanceById(summary.id),
              { concurrency: 5 },
            );
            return hydrated.filter(
              (attrs): attrs is DbInstance["Attributes"] => attrs !== undefined,
            );
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const state = output?.id
            ? yield* readInstanceById(output.id)
            : yield* findInstanceByName(yield* createInstanceName(id, olds ?? {}));
          if (!state) return undefined;
          return (yield* hasAlchemyTags(id, state.tags as Tags)) ? state : Unowned(state);
        }),
        diff: Effect.fn(function* ({ id, news, olds = {} }) {
          if (!isResolved(news)) return;
          const oldName = yield* createInstanceName(id, olds);
          const newName = yield* createInstanceName(id, news);
          // Name and the networking/credential aspects are immutable — changing
          // any of them requires a replacement.
          const arraysDiffer = (a?: string[], b?: string[]) =>
            JSON.stringify([...(a ?? [])].sort()) !== JSON.stringify([...(b ?? [])].sort());
          if (
            oldName !== newName ||
            arraysDiffer(olds.vpcSubnetIds, news.vpcSubnetIds) ||
            arraysDiffer(olds.vpcSecurityGroupIds, news.vpcSecurityGroupIds) ||
            olds.username !== news.username ||
            olds.organization !== news.organization ||
            olds.bucket !== news.bucket ||
            olds.publiclyAccessible !== news.publiclyAccessible ||
            olds.networkType !== news.networkType
          ) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          if (!news) {
            return yield* new DbInstanceInvalidProps({
              message: "Timestream DbInstance requires props",
            });
          }
          const name = output?.name ?? (yield* createInstanceName(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 rather than
          // duplicated.
          let state = output?.id
            ? yield* readInstanceById(output.id)
            : yield* findInstanceByName(name);

          // Ensure — create if missing, then wait for AVAILABLE.
          if (state === undefined) {
            const created = yield* influxdb.createDbInstance({
              name,
              dbInstanceType: news.dbInstanceType,
              allocatedStorage: news.allocatedStorage,
              vpcSubnetIds: news.vpcSubnetIds,
              vpcSecurityGroupIds: news.vpcSecurityGroupIds,
              password: Redacted.value(news.password),
              username: news.username,
              organization: news.organization,
              bucket: news.bucket,
              dbStorageType: news.dbStorageType,
              publiclyAccessible: news.publiclyAccessible,
              deploymentType: news.deploymentType,
              dbParameterGroupIdentifier: news.dbParameterGroupIdentifier,
              logDeliveryConfiguration: news.logDeliveryConfiguration,
              port: news.port,
              networkType: news.networkType,
              tags: desiredTags,
            });
            yield* session.note(`Creating DB instance ${name} (${created.id})...`);
            yield* waitForStatus(created.id, "AVAILABLE");
            state = yield* readInstanceById(created.id);
            if (state === undefined) {
              return yield* new DbInstanceUnexpectedResponse({
                message: `failed to read created DB instance ${name}`,
              });
            }
          }

          // Sync mutable settings via UpdateDbInstance. It is a partial upsert;
          // only send it when a mutable aspect drifted from observed state.
          const needsUpdate =
            (news.dbInstanceType !== undefined && news.dbInstanceType !== state.dbInstanceType) ||
            (news.allocatedStorage !== undefined &&
              news.allocatedStorage !== state.allocatedStorage) ||
            (news.port !== undefined && news.port !== state.port) ||
            news.dbParameterGroupIdentifier !== undefined ||
            news.logDeliveryConfiguration !== undefined ||
            news.deploymentType !== undefined ||
            news.dbStorageType !== undefined;
          if (needsUpdate) {
            yield* influxdb.updateDbInstance({
              identifier: state.id,
              dbInstanceType: news.dbInstanceType,
              allocatedStorage: news.allocatedStorage,
              port: news.port,
              dbParameterGroupIdentifier: news.dbParameterGroupIdentifier,
              logDeliveryConfiguration: news.logDeliveryConfiguration,
              deploymentType: news.deploymentType,
              dbStorageType: news.dbStorageType,
            });
            yield* waitForStatus(state.id, "AVAILABLE");
            yield* session.note(`Updated DB instance ${name}`);
          }

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

          yield* session.note(state.arn);

          const final = yield* readInstanceById(state.id);
          if (!final) {
            return yield* new DbInstanceUnexpectedResponse({
              message: `failed to read reconciled DB instance ${name}`,
            });
          }
          return final;
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* influxdb
            .deleteDbInstance({ identifier: output.id })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
          yield* waitForStatus(output.id, "DELETED");
        }),
      };
    }),
  );