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

import * as TSQ from "@distilled.cloud/aws/timestream-query";
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 Option from "effect/Option";
import * as EffectStream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { withQueryEndpoint } from "./internal.ts";

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

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

export type ScheduledQueryState = TSQ.ScheduledQueryState;

export interface ScheduledQueryErrorReportS3 {
  /**
   * Name of the S3 bucket where error reports for failed runs are written.
   */
  bucketName: string;
  /**
   * Object key prefix for error report objects.
   */
  objectKeyPrefix?: string;
  /**
   * Server-side encryption for error report objects.
   * @default "SSE_S3"
   */
  encryptionOption?: TSQ.S3EncryptionOption;
}

export interface ScheduledQueryProps {
  /**
   * Name of the scheduled query. Must be unique within the account and
   * region.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * The SQL the scheduled query runs on each invocation.
   */
  queryString: string;
  /**
   * When to run the query — a cron (`cron(0 12 * * ? *)`) or rate
   * (`rate(1 hour)`) expression.
   */
  scheduleExpression: string;
  /**
   * ARN of the SNS topic Timestream notifies after each run.
   */
  notificationTopicArn: string;
  /**
   * ARN of the IAM role Timestream assumes to run the query, write results,
   * publish notifications, and write error reports.
   */
  executionRoleArn: string;
  /**
   * Where results are written (a Timestream table with measure/dimension
   * mappings). Omit for queries whose results are not materialized.
   */
  targetConfiguration?: TSQ.TargetConfiguration;
  /**
   * S3 location where error reports for failed runs are written.
   */
  errorReportS3: ScheduledQueryErrorReportS3;
  /**
   * The KMS key used to encrypt the scheduled query resource at rest. When
   * omitted, Timestream uses an AWS-owned key.
   */
  kmsKeyId?: string;
  /**
   * Whether the schedule is active.
   * @default "ENABLED"
   */
  state?: ScheduledQueryState;
  /**
   * Tags to associate with the scheduled query.
   */
  tags?: Record<string, string>;
}

export interface ScheduledQuery extends Resource<
  "AWS.Timestream.ScheduledQuery",
  ScheduledQueryProps,
  {
    /**
     * ARN of the scheduled query.
     */
    scheduledQueryArn: string;
    /**
     * The scheduled query's physical name.
     */
    name: string;
    /**
     * Whether the schedule is currently active.
     */
    state: ScheduledQueryState;
    /**
     * Current tags reported for the scheduled query.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon Timestream for LiveAnalytics scheduled query — a SQL query
 * Timestream runs on a cron/rate schedule, materializing results into a
 * target table and notifying an SNS topic after each run.
 *
 * Only the `state` (ENABLED/DISABLED) is mutable in place; changing the
 * query, schedule, notification topic, role, target, error report location,
 * or KMS key replaces the scheduled query. Tags sync in place.
 *
 * :::note
 * Timestream for LiveAnalytics is closed to new AWS customers. Accounts that
 * were not already onboarded receive `TimestreamNotOnboarded` (a specialized
 * `AccessDenied`) on every operation.
 * :::
 * ### Creating Scheduled Queries
 * **Example:** Hourly Rollup
 * ```typescript
 * import * as Timestream from "@alchemy.run/aws/Timestream";
 *
 * const rollup = yield* Timestream.ScheduledQuery("HourlyRollup", {
 *   queryString: `SELECT host, AVG(measure_value::double) AS avg_cpu
 *                 FROM "metrics"."cpu"
 *                 WHERE time > ago(1h) GROUP BY host`,
 *   scheduleExpression: "rate(1 hour)",
 *   notificationTopicArn: topic.topicArn,
 *   executionRoleArn: role.roleArn,
 *   errorReportS3: { bucketName: bucket.bucketName },
 *   targetConfiguration: {
 *     TimestreamConfiguration: {
 *       DatabaseName: database.databaseName,
 *       TableName: rollupTable.tableName,
 *       TimeColumn: "time",
 *       DimensionMappings: [{ Name: "host", DimensionValueType: "VARCHAR" }],
 *       MultiMeasureMappings: {
 *         TargetMultiMeasureName: "cpu_rollup",
 *         MultiMeasureAttributeMappings: [
 *           { SourceColumn: "avg_cpu", MeasureValueType: "DOUBLE" },
 *         ],
 *       },
 *     },
 *   },
 * });
 * ```
 *
 * **Example:** Pausing a Schedule
 * ```typescript
 * const rollup = yield* Timestream.ScheduledQuery("HourlyRollup", {
 *   // ... unchanged configuration ...
 *   state: "DISABLED",
 * });
 * ```
 *
 * @resource
 */
export const ScheduledQuery = Resource<ScheduledQuery>("AWS.Timestream.ScheduledQuery");

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

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

const readScheduledQuery = Effect.fn(function* (scheduledQueryArn: string) {
  const response = yield* withQueryEndpoint(
    TSQ.describeScheduledQuery({ ScheduledQueryArn: scheduledQueryArn }),
  ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  if (!response?.ScheduledQuery) {
    return undefined;
  }
  const scheduledQuery = response.ScheduledQuery;
  const tags = yield* withQueryEndpoint(
    TSQ.listTagsForResource.items({ ResourceARN: scheduledQuery.Arn }).pipe(
      EffectStream.runCollect,
      Effect.map((chunk) => Array.from(chunk)),
    ),
  ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  if (!tags) {
    return undefined;
  }
  return {
    scheduledQueryArn: scheduledQuery.Arn,
    name: scheduledQuery.Name,
    state: scheduledQuery.State,
    tags: toTagRecord(tags),
  } satisfies ScheduledQuery["Attributes"];
});

const findScheduledQueryByName = Effect.fn(function* (name: string) {
  const match = yield* withQueryEndpoint(
    TSQ.listScheduledQueries.pages({}).pipe(
      EffectStream.map((page) => page.ScheduledQueries ?? []),
      EffectStream.flattenIterable,
      EffectStream.filter((summary) => summary.Name === name),
      EffectStream.runHead,
    ),
  ).pipe(Effect.map(Option.getOrUndefined));
  if (!match) return undefined;
  return yield* readScheduledQuery(match.Arn);
});

export const ScheduledQueryProvider = () =>
  Provider.effect(
    ScheduledQuery,
    Effect.gen(function* () {
      return {
        stables: ["scheduledQueryArn", "name"],
        list: () =>
          Effect.gen(function* () {
            const summaries = yield* withQueryEndpoint(
              TSQ.listScheduledQueries.pages({}).pipe(EffectStream.runCollect),
            ).pipe(
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) => page.ScheduledQueries ?? []),
              ),
            );
            const hydrated = yield* Effect.forEach(
              summaries,
              (summary) => readScheduledQuery(summary.Arn),
              { concurrency: 5 },
            );
            return hydrated.filter(
              (attrs): attrs is ScheduledQuery["Attributes"] => attrs !== undefined,
            );
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const state = output?.scheduledQueryArn
            ? yield* readScheduledQuery(output.scheduledQueryArn)
            : yield* findScheduledQueryByName(yield* createScheduledQueryName(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) || olds === undefined) return;
          const oldName = yield* createScheduledQueryName(id, olds);
          const newName = yield* createScheduledQueryName(id, news);
          // Only State is mutable via UpdateScheduledQuery — every other
          // aspect requires a replacement.
          const changed = (a: unknown, b: unknown) =>
            JSON.stringify(a ?? null) !== JSON.stringify(b ?? null);
          if (
            oldName !== newName ||
            olds.queryString !== news.queryString ||
            olds.scheduleExpression !== news.scheduleExpression ||
            olds.notificationTopicArn !== news.notificationTopicArn ||
            olds.executionRoleArn !== news.executionRoleArn ||
            olds.kmsKeyId !== news.kmsKeyId ||
            changed(olds.targetConfiguration, news.targetConfiguration) ||
            changed(olds.errorReportS3, news.errorReportS3)
          ) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          if (!news) {
            return yield* new ScheduledQueryInvalidProps({
              message: "Timestream ScheduledQuery requires props",
            });
          }
          const name = output?.name ?? (yield* createScheduledQueryName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // Observe — prefer the cached ARN; fall back to a name lookup so a
          // create whose state failed to persist is adopted, not duplicated.
          let state = output?.scheduledQueryArn
            ? yield* readScheduledQuery(output.scheduledQueryArn)
            : yield* findScheduledQueryByName(name);

          // Ensure — create if missing; tolerate a ConflictException race.
          if (state === undefined) {
            yield* withQueryEndpoint(
              TSQ.createScheduledQuery({
                Name: name,
                QueryString: news.queryString,
                ScheduleConfiguration: {
                  ScheduleExpression: news.scheduleExpression,
                },
                NotificationConfiguration: {
                  SnsConfiguration: { TopicArn: news.notificationTopicArn },
                },
                ScheduledQueryExecutionRoleArn: news.executionRoleArn,
                TargetConfiguration: news.targetConfiguration,
                ErrorReportConfiguration: {
                  S3Configuration: {
                    BucketName: news.errorReportS3.bucketName,
                    ObjectKeyPrefix: news.errorReportS3.objectKeyPrefix,
                    EncryptionOption: news.errorReportS3.encryptionOption,
                  },
                },
                KmsKeyId: news.kmsKeyId,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              }),
            ).pipe(Effect.catchTag("ConflictException", () => Effect.void));
            yield* session.note(`Creating scheduled query ${name}...`);
            state = yield* findScheduledQueryByName(name);
            if (state === undefined) {
              return yield* new ScheduledQueryUnexpectedResponse({
                message: `failed to read created scheduled query ${name}`,
              });
            }
          }

          // Sync state — the only in-place mutable aspect.
          const desiredState = news.state ?? "ENABLED";
          if (state.state !== desiredState) {
            yield* withQueryEndpoint(
              TSQ.updateScheduledQuery({
                ScheduledQueryArn: state.scheduledQueryArn,
                State: desiredState,
              }),
            );
            yield* session.note(`Updated scheduled query ${name} state to ${desiredState}`);
          }

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

          yield* session.note(state.scheduledQueryArn);

          const final = yield* readScheduledQuery(state.scheduledQueryArn);
          if (!final) {
            return yield* new ScheduledQueryUnexpectedResponse({
              message: `failed to read reconciled scheduled query ${name}`,
            });
          }
          return final;
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* withQueryEndpoint(
            TSQ.deleteScheduledQuery({
              ScheduledQueryArn: output.scheduledQueryArn,
            }),
          ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      };
    }),
  );