sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ CloudWatch/ MetricStream.ts

import * as cloudwatch from "@distilled.cloud/aws/cloudwatch";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { AWSEnvironment, type AccountID } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
import { createName, readResourceTags, retryConcurrent, updateResourceTags } from "./common.ts";

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

export type MetricStreamName = string;
export type MetricStreamArn = `arn:aws:cloudwatch:${RegionID}:${AccountID}:metric-stream/${string}`;

export interface MetricStreamProps extends Omit<cloudwatch.PutMetricStreamInput, "Name" | "Tags"> {
  /**
   * Name of the metric stream. If omitted, a unique name is generated.
   */
  name?: MetricStreamName;
  /**
   * Whether the stream should be running after deployment.
   * @default true
   */
  enabled?: boolean;
  /**
   * Optional tags to apply to the metric stream.
   */
  tags?: Record<string, string>;
}

export interface MetricStream extends Resource<
  "AWS.CloudWatch.MetricStream",
  MetricStreamProps,
  {
    /** Physical name of the metric stream. */
    metricStreamName: MetricStreamName;
    /** ARN of the metric stream. */
    metricStreamArn: MetricStreamArn;
    /** Current state of the stream (`running` or `stopped`). */
    state: string | undefined;
    /** The full metric stream description as last read from CloudWatch. */
    metricStream: cloudwatch.GetMetricStreamOutput;
    /** Tags on the metric stream, including the internal Alchemy ownership tags. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * A CloudWatch metric stream — continuously exports CloudWatch metrics to
 * a Kinesis Data Firehose delivery stream (and on to S3, Datadog, etc.).
 * ### Creating Metric Streams
 * **Example:** Firehose Delivery Stream
 * ```typescript
 * const stream = yield* MetricStream("MetricsExport", {
 *   FirehoseArn: "arn:aws:firehose:us-east-1:123456789012:deliverystream/example",
 *   RoleArn: "arn:aws:iam::123456789012:role/example",
 *   OutputFormat: "json",
 * });
 * ```
 *
 * **Example:** Stream Only Selected Namespaces
 * ```typescript
 * const stream = yield* MetricStream("LambdaMetricsExport", {
 *   FirehoseArn: firehose.deliveryStreamArn,
 *   RoleArn: role.roleArn,
 *   OutputFormat: "json",
 *   IncludeFilters: [{ Namespace: "AWS/Lambda" }],
 * });
 * ```
 *
 * ### Reading Metric Streams at Runtime
 * **Example:** Read the Stream's State from a Function
 * ```typescript
 * // init — bind the stream to the function (see GetMetricStream)
 * const getMetricStream = yield* AWS.CloudWatch.GetMetricStream(stream);
 *
 * // runtime
 * const result = yield* getMetricStream();
 * const state = result.State; // "running" | "stopped"
 * ```
 *
 * @resource
 */
export const MetricStream = Resource<MetricStream>("AWS.CloudWatch.MetricStream");

export const MetricStreamProvider = () =>
  Provider.effect(
    MetricStream,
    Effect.gen(function* () {
      const createMetricStreamName = (id: string, props: { name?: string } = {}) =>
        createName(id, props.name, 255);

      const metricStreamArn = (name: string) =>
        AWSEnvironment.current.pipe(
          Effect.map(
            (env) =>
              `arn:aws:cloudwatch:${env.region}:${env.accountId}:metric-stream/${name}` as MetricStreamArn,
          ),
        );

      const readMetricStream = Effect.fn(function* (name: string) {
        const output = yield* cloudwatch
          .getMetricStream({
            Name: name,
          })
          .pipe(
            Effect.catchTags({
              InvalidParameterValueException: () => Effect.undefined,
              ResourceNotFoundException: () => Effect.undefined,
            }),
          );

        if (!output?.Name || !output.Arn) {
          return undefined;
        }

        const tags = yield* readResourceTags(output.Arn).pipe(
          Effect.catchTags({
            ResourceNotFoundException: () => Effect.succeed({}),
            InvalidParameterValueException: () => Effect.succeed({}),
          }),
        );

        return {
          metricStreamName: output.Name,
          metricStreamArn: output.Arn as MetricStreamArn,
          state: output.State,
          metricStream: output,
          tags,
        };
      });

      const syncMetricStreamState = Effect.fn(function* ({
        name,
        enabled,
      }: {
        name: string;
        enabled: boolean | undefined;
      }) {
        if (enabled === false) {
          yield* retryConcurrent(
            cloudwatch.stopMetricStreams({
              Names: [name],
            }),
          );
          return;
        }

        yield* retryConcurrent(
          cloudwatch.startMetricStreams({
            Names: [name],
          }),
        );
      });

      return {
        stables: ["metricStreamName", "metricStreamArn"],
        diff: Effect.fn(function* ({ id, olds = {}, news = {} as Input<MetricStreamProps> }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createMetricStreamName(id, olds);
          const newName = yield* createMetricStreamName(id, news);

          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
        }),
        list: () =>
          Effect.gen(function* () {
            // Enumerate every metric stream in the account/region. The list
            // op only returns summary entries, so re-read each by name to
            // produce the full Attributes shape `read` returns.
            const entries = yield* cloudwatch.listMetricStreams.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Entries ?? [])),
            );

            const results = yield* Effect.forEach(
              entries,
              (entry) => (entry.Name ? readMetricStream(entry.Name) : Effect.undefined),
              { concurrency: 10 },
            );

            return results.filter(
              (state): state is NonNullable<typeof state> => state !== undefined,
            );
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.metricStreamName ?? (yield* createMetricStreamName(id, olds ?? {}));
          const state = yield* readMetricStream(name);
          if (!state) return undefined;
          return (yield* hasAlchemyTags(id, state.tags)) ? state : Unowned(state);
        }),
        reconcile: Effect.fn(function* ({ id, news, olds, output, session }) {
          // Observe — pin the physical name from `output` if present;
          // otherwise derive from desired props. Read existing so we have
          // a baseline for tag-diffing on adoption.
          const name = output?.metricStreamName ?? (yield* createMetricStreamName(id, news));
          const existing = yield* readMetricStream(name);

          // Ensure — `putMetricStream` is an upsert; we send the full
          // desired config every reconcile.
          yield* retryConcurrent(
            cloudwatch.putMetricStream({
              ...news,
              Name: name,
            }),
          );

          // Sync running state — `enabled` drives start/stop independently
          // of the put call.
          yield* syncMetricStreamState({
            name,
            enabled: news.enabled,
          });

          // Sync tags — diff against `olds.tags` when we have prior state,
          // otherwise fall back to what we observed (adoption path).
          const tags = yield* updateResourceTags({
            id,
            resourceArn: yield* metricStreamArn(name),
            olds: olds?.tags ?? existing?.tags,
            news: news.tags,
          });

          yield* session.note(yield* metricStreamArn(name));

          const state = yield* readMetricStream(name);
          if (!state) {
            return yield* new MetricStreamUnexpectedResponse({
              message: `failed to read reconciled metric stream '${name}'`,
            });
          }

          return {
            ...state,
            tags,
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          const existing = yield* readMetricStream(output.metricStreamName);
          if (!existing) {
            return;
          }

          yield* retryConcurrent(
            cloudwatch.deleteMetricStream({
              Name: output.metricStreamName,
            }),
          ).pipe(Effect.catchTag("InvalidParameterValueException", () => Effect.void));
        }),
      };
    }),
  );