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

import * as TSW from "@distilled.cloud/aws/timestream-write";
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 { toWireDays, toWireHours } 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 EffectStream from "effect/Stream";
import { AWSEnvironment, type AccountID } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
import { withWriteEndpoint } from "./internal.ts";

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

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

export type TableArn =
  `arn:aws:timestream:${RegionID}:${AccountID}:database/${string}/table/${string}`;

export type TableStatus = "ACTIVE" | "DELETING" | "RESTORING";

export interface TableRetentionProperties {
  /**
   * How long data stays in the memory store before moving to the magnetic
   * store. Rounded to whole hours on the wire
   * (`MemoryStoreRetentionPeriodInHours`).
   */
  memoryStoreRetention: Duration.Input;
  /**
   * How long data stays in the magnetic store before deletion. Rounded to
   * whole days on the wire (`MagneticStoreRetentionPeriodInDays`).
   */
  magneticStoreRetention: Duration.Input;
}

export interface TableProps {
  /**
   * Name of the database that owns this table. Pass the `databaseName` of a
   * {@link Database} resource.
   */
  databaseName: string;
  /**
   * Name of the table. Must be unique within the database and between 3 and
   * 256 characters.
   * @default ${app}-${stage}-${id}
   */
  tableName?: string;
  /**
   * Retention configuration for the table's memory and magnetic stores.
   * @default { memoryStoreRetention: "6 hours", magneticStoreRetention: "73000 days" }
   */
  retentionProperties?: TableRetentionProperties;
  /**
   * Magnetic store write configuration, including whether late-arriving data
   * is written to the magnetic store and where rejected records are logged.
   */
  magneticStoreWriteProperties?: TSW.MagneticStoreWriteProperties;
  /**
   * Partitioning schema for the table.
   */
  schema?: TSW.Schema;
  /**
   * Tags to associate with the table.
   */
  tags?: Record<string, string>;
}

export interface Table extends Resource<
  "AWS.Timestream.Table",
  TableProps,
  {
    /**
     * The table's physical name.
     */
    tableName: string;
    /**
     * Name of the database that owns the table.
     */
    databaseName: string;
    /**
     * ARN of the table.
     */
    tableArn: TableArn;
    /**
     * Current lifecycle status of the table.
     */
    tableStatus: TableStatus;
    /**
     * Effective retention configuration for the table.
     */
    retentionProperties: TSW.RetentionProperties | undefined;
    /**
     * Effective magnetic store write configuration.
     */
    magneticStoreWriteProperties: TSW.MagneticStoreWriteProperties | undefined;
    /**
     * Current tags reported for the table.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon Timestream for LiveAnalytics table — a time-series store inside a
 * {@link Database}.
 *
 * `Table` owns the table's lifecycle and its mutable configuration: memory and
 * magnetic store retention, magnetic store write behavior, and tags. A table
 * name is auto-generated from the app, stage, and logical ID unless you provide
 * one.
 *
 * :::note
 * Timestream for LiveAnalytics is closed to new AWS customers. Accounts that
 * were not already onboarded receive `TimestreamNotOnboarded` on every
 * operation.
 * :::
 * ### Creating Tables
 * **Example:** Basic Table
 * ```typescript
 * import * as Timestream from "@alchemy.run/aws/Timestream";
 *
 * const database = yield* Timestream.Database("Metrics");
 * const table = yield* Timestream.Table("Cpu", {
 *   databaseName: database.databaseName,
 * });
 * ```
 *
 * **Example:** Table with Retention Tuning
 * ```typescript
 * const table = yield* Timestream.Table("Cpu", {
 *   databaseName: database.databaseName,
 *   retentionProperties: {
 *     memoryStoreRetention: "24 hours",
 *     magneticStoreRetention: "365 days",
 *   },
 * });
 * ```
 *
 * ### Writing Points
 * **Example:** Write records from a handler
 * ```typescript
 * // init
 * const writeRecords = yield* Timestream.WriteRecords(table);
 *
 * return {
 *   fetch: Effect.gen(function* () {
 *     // runtime
 *     yield* writeRecords({
 *       Records: [
 *         {
 *           Dimensions: [{ Name: "host", Value: "web-1" }],
 *           MeasureName: "cpu",
 *           MeasureValue: "42.0",
 *           MeasureValueType: "DOUBLE",
 *           Time: `${Date.now()}`,
 *           TimeUnit: "MILLISECONDS",
 *         },
 *       ],
 *     });
 *     return HttpServerResponse.text("ok");
 *   }),
 * };
 * ```
 *
 * @resource
 */
export const Table = Resource<Table>("AWS.Timestream.Table");

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

const toTagRecord = (
  tags: Array<{ Key: string; Value: string }> | undefined,
): Record<string, string> => Object.fromEntries((tags ?? []).map((tag) => [tag.Key, tag.Value]));

/**
 * Convert the alchemy-shaped {@link TableRetentionProperties} (Duration
 * inputs) to Timestream's wire shape (whole hours / whole days).
 */
const toWireRetention = (
  retention: TableRetentionProperties | undefined,
): TSW.RetentionProperties | undefined =>
  retention === undefined
    ? undefined
    : {
        MemoryStoreRetentionPeriodInHours: toWireHours(retention.memoryStoreRetention)!,
        MagneticStoreRetentionPeriodInDays: toWireDays(retention.magneticStoreRetention)!,
      };

const readTable = Effect.fn(function* (databaseName: string, tableName: string) {
  const response = yield* withWriteEndpoint(
    TSW.describeTable({ DatabaseName: databaseName, TableName: tableName }),
  ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  if (!response?.Table) {
    return undefined;
  }
  const table = response.Table;
  const tagsResponse = yield* withWriteEndpoint(
    TSW.listTagsForResource({ ResourceARN: table.Arn! }),
  ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  if (!tagsResponse) {
    return undefined;
  }
  return {
    tableName: table.TableName!,
    databaseName: table.DatabaseName!,
    tableArn: table.Arn as TableArn,
    tableStatus: (table.TableStatus ?? "ACTIVE") as TableStatus,
    retentionProperties: table.RetentionProperties,
    magneticStoreWriteProperties: table.MagneticStoreWriteProperties,
    tags: toTagRecord(tagsResponse.Tags),
  } satisfies Table["Attributes"];
});

export const TableProvider = () =>
  Provider.effect(
    Table,
    Effect.gen(function* () {
      return {
        stables: ["tableName", "databaseName", "tableArn"],
        // Enumerate every Timestream table in the ambient account/region.
        // `listTables` with no `DatabaseName` lists across all databases; it is
        // paginated, so collect every page and hydrate each into the `read`
        // Attributes shape.
        list: () =>
          Effect.gen(function* () {
            const refs = yield* withWriteEndpoint(
              TSW.listTables.pages({}).pipe(EffectStream.runCollect),
            ).pipe(
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) =>
                  (page.Tables ?? []).flatMap((table) =>
                    table.DatabaseName && table.TableName
                      ? [
                          {
                            databaseName: table.DatabaseName,
                            tableName: table.TableName,
                          },
                        ]
                      : [],
                  ),
                ),
              ),
            );
            const hydrated = yield* Effect.forEach(
              refs,
              (ref) => readTable(ref.databaseName, ref.tableName),
              { concurrency: 10 },
            );
            return hydrated.filter((attrs): attrs is Table["Attributes"] => attrs !== undefined);
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const databaseName = output?.databaseName ?? olds?.databaseName;
          if (!databaseName) return undefined;
          const tableName = output?.tableName ?? (yield* createTableName(id, olds ?? {}));
          const state = yield* readTable(databaseName, tableName);
          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* createTableName(id, olds);
          const newName = yield* createTableName(id, news);
          // Table name or its owning database is immutable — either requires a
          // replacement.
          if (oldName !== newName || olds.databaseName !== news.databaseName) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          if (!news?.databaseName) {
            return yield* new TimestreamTableInvalidProps({
              message: "Timestream Table requires a databaseName",
            });
          }
          const { accountId, region } = yield* AWSEnvironment.current;
          const databaseName = news.databaseName;
          const tableName = output?.tableName ?? (yield* createTableName(id, news));
          const tableArn =
            `arn:aws:timestream:${region}:${accountId}:database/${databaseName}/table/${tableName}` as TableArn;
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };
          const desiredRetention = toWireRetention(news.retentionProperties);

          // Observe.
          let state = yield* readTable(databaseName, tableName);

          // Ensure — create if missing; tolerate a ConflictException race.
          if (state === undefined) {
            yield* withWriteEndpoint(
              TSW.createTable({
                DatabaseName: databaseName,
                TableName: tableName,
                RetentionProperties: desiredRetention,
                MagneticStoreWriteProperties: news.magneticStoreWriteProperties,
                Schema: news.schema,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              }),
            ).pipe(Effect.catchTag("ConflictException", () => Effect.void));
            yield* session.note(`Creating table ${tableName}...`);
            state = yield* readTable(databaseName, tableName);
            if (state === undefined) {
              return yield* new TimestreamTableUnexpectedResponse({
                message: `failed to read created table ${tableName}`,
              });
            }
          }

          // Sync retention / magnetic-store-write config — diff the desired
          // wire values against observed cloud state and skip the API call
          // entirely on a no-op.
          const retentionDrifted =
            desiredRetention !== undefined &&
            (state.retentionProperties?.MemoryStoreRetentionPeriodInHours !==
              desiredRetention.MemoryStoreRetentionPeriodInHours ||
              state.retentionProperties?.MagneticStoreRetentionPeriodInDays !==
                desiredRetention.MagneticStoreRetentionPeriodInDays);
          if (retentionDrifted || news.magneticStoreWriteProperties !== undefined) {
            yield* withWriteEndpoint(
              TSW.updateTable({
                DatabaseName: databaseName,
                TableName: tableName,
                RetentionProperties: desiredRetention,
                MagneticStoreWriteProperties: news.magneticStoreWriteProperties,
                Schema: news.schema,
              }),
            );
            yield* session.note(`Updated table ${tableName} configuration`);
          }

          // Sync tags — diff against observed cloud tags.
          const { removed, upsert } = diffTags(state.tags, desiredTags);
          if (removed.length > 0) {
            yield* withWriteEndpoint(
              TSW.untagResource({ ResourceARN: tableArn, TagKeys: removed }),
            );
          }
          if (upsert.length > 0) {
            yield* withWriteEndpoint(
              TSW.tagResource({
                ResourceARN: tableArn,
                Tags: upsert.map(({ Key, Value }) => ({ Key, Value })),
              }),
            );
          }

          yield* session.note(tableArn);

          const final = yield* readTable(databaseName, tableName);
          if (!final) {
            return yield* new TimestreamTableUnexpectedResponse({
              message: `failed to read reconciled table ${tableName}`,
            });
          }
          return final;
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* withWriteEndpoint(
            TSW.deleteTable({
              DatabaseName: output.databaseName,
              TableName: output.tableName,
            }),
          ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      };
    }),
  );