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

import * as cloudwatch from "@distilled.cloud/aws/cloudwatch";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
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 { createName, retryConcurrent } from "./common.ts";

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

export type DashboardName = string;
export type DashboardArn = `arn:aws:cloudwatch::${AccountID}:dashboard/${string}`;

export type DashboardPeriodOverride = "inherit" | "auto";
export type DashboardMetricRow = (string | number | boolean | null)[];

export interface DashboardMetricWidgetProperties {
  title?: string;
  region?: string;
  stat?: string;
  period?: number;
  view?: "timeSeries" | "singleValue" | "gauge" | "bar" | "pie";
  stacked?: boolean;
  metrics: DashboardMetricRow[];
  annotations?: Record<string, unknown>;
  yAxis?: Record<string, unknown>;
  legend?: Record<string, unknown>;
  [key: string]: unknown;
}

export interface DashboardTextWidgetProperties {
  markdown: string;
  [key: string]: unknown;
}

export interface DashboardAlarmStatusWidgetProperties {
  alarms: string[];
  title?: string;
  sortBy?: string;
  states?: string[];
  [key: string]: unknown;
}

export interface DashboardLogWidgetProperties {
  query: string;
  region?: string;
  title?: string;
  view?: "table" | "timeSeries" | "bar" | "pie";
  [key: string]: unknown;
}

export interface DashboardMetricWidget {
  type: "metric";
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  properties: DashboardMetricWidgetProperties;
}

export interface DashboardTextWidget {
  type: "text";
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  properties: DashboardTextWidgetProperties;
}

export interface DashboardAlarmStatusWidget {
  type: "alarm";
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  properties: DashboardAlarmStatusWidgetProperties;
}

export interface DashboardLogWidget {
  type: "log";
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  properties: DashboardLogWidgetProperties;
}

export type DashboardWidget =
  | DashboardMetricWidget
  | DashboardTextWidget
  | DashboardAlarmStatusWidget
  | DashboardLogWidget;

export interface DashboardBody {
  start?: string;
  end?: string;
  periodOverride?: DashboardPeriodOverride;
  widgets: DashboardWidget[];
  variables?: Record<string, unknown>[];
}

export interface DashboardProps extends Omit<
  cloudwatch.PutDashboardInput,
  "DashboardName" | "DashboardBody"
> {
  /**
   * Name of the dashboard. If omitted, a unique name is generated.
   */
  name?: DashboardName;
  /**
   * Structured dashboard document. The provider serializes it to the JSON
   * string expected by the CloudWatch API.
   */
  DashboardBody: DashboardBody;
  /**
   * Optional tags to apply to the dashboard.
   *
   * CloudWatch dashboards do not currently support the generic CloudWatch
   * tagging APIs, so these values are accepted for API consistency but are not
   * persisted remotely.
   */
  tags?: Record<string, string>;
}

export interface Dashboard extends Resource<
  "AWS.CloudWatch.Dashboard",
  DashboardProps,
  {
    /** Physical name of the dashboard. */
    dashboardName: DashboardName;
    /** ARN of the dashboard. */
    dashboardArn: DashboardArn;
    /** The parsed dashboard document as last read from CloudWatch. */
    dashboardBody: DashboardBody | undefined;
    /** Tags accepted for API consistency (not persisted remotely). */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon CloudWatch dashboard. The `DashboardBody` is a structured,
 * typed document (metric, text, alarm-status, and log widgets) that the
 * provider serializes to the JSON string CloudWatch expects.
 * ### Creating Dashboards
 * **Example:** Basic Dashboard
 * ```typescript
 * const dashboard = yield* Dashboard("OpsDashboard", {
 *   DashboardBody: {
 *     widgets: [],
 *   },
 * });
 * ```
 *
 * **Example:** Dashboard with Metric and Text Widgets
 * ```typescript
 * const dashboard = yield* Dashboard("PaymentsDashboard", {
 *   DashboardBody: {
 *     widgets: [
 *       {
 *         type: "text",
 *         x: 0, y: 0, width: 6, height: 3,
 *         properties: { markdown: "# Payments service" },
 *       },
 *       {
 *         type: "metric",
 *         x: 0, y: 3, width: 12, height: 6,
 *         properties: {
 *           title: "Payments processed",
 *           metrics: [["MyApp/Payments", "PaymentProcessed"]],
 *           stat: "Sum",
 *           period: 60,
 *           view: "timeSeries",
 *         },
 *       },
 *     ],
 *   },
 * });
 * ```
 *
 * ### Reading Dashboards at Runtime
 * **Example:** Read the Dashboard Body from a Function
 * ```typescript
 * // init — bind the dashboard to the function (see GetDashboard)
 * const getDashboard = yield* AWS.CloudWatch.GetDashboard(dashboard);
 *
 * // runtime
 * const result = yield* getDashboard();
 * const body = JSON.parse(result.DashboardBody ?? "{}");
 * ```
 *
 * @resource
 */
export const Dashboard = Resource<Dashboard>("AWS.CloudWatch.Dashboard");

const serializeDashboardBody = (body: DashboardBody) => JSON.stringify(body);

const parseDashboardBody = (body: string | undefined) => {
  if (!body) {
    return undefined;
  }
  return JSON.parse(body) as DashboardBody;
};

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

      const dashboardArn = (dashboardName: string) =>
        AWSEnvironment.current.pipe(
          Effect.map(
            (env) =>
              `arn:aws:cloudwatch::${env.accountId}:dashboard/${dashboardName}` as DashboardArn,
          ),
        );

      const readDashboard = Effect.fn(function* (dashboardName: string) {
        const output = yield* cloudwatch
          .getDashboard({
            DashboardName: dashboardName,
          })
          .pipe(Effect.catchTag("DashboardNotFoundError", () => Effect.undefined));

        if (!output?.DashboardName) {
          return undefined;
        }

        return {
          dashboardName: output.DashboardName,
          dashboardArn: yield* dashboardArn(output.DashboardName),
          dashboardBody: parseDashboardBody(output.DashboardBody),
          tags: {},
        };
      });

      return {
        stables: ["dashboardName", "dashboardArn"],
        diff: Effect.fn(function* ({ id, olds = {}, news = {} as DashboardProps }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createDashboardName(id, olds);
          const newName = yield* createDashboardName(id, news);

          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.dashboardName ?? (yield* createDashboardName(id, olds ?? {}));
          return yield* readDashboard(name);
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          // Observe — pin the physical name from `output` if present so we
          // never rename an existing dashboard; otherwise derive from
          // desired props.
          const name = output?.dashboardName ?? (yield* createDashboardName(id, news));

          // Ensure — `putDashboard` is a pure upsert. The CloudWatch
          // dashboard API has no separate update path, so we always send
          // the full body and let the API converge.
          yield* retryConcurrent(
            cloudwatch.putDashboard({
              DashboardName: name,
              DashboardBody: serializeDashboardBody(news.DashboardBody),
            }),
          );

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

          const state = yield* readDashboard(name);
          if (!state) {
            return yield* new DashboardUnexpectedResponse({
              message: `failed to read reconciled dashboard '${name}'`,
            });
          }

          // Dashboards do not support the generic CloudWatch tagging APIs,
          // so `tags` is always returned as an empty record.
          return {
            ...state,
            tags: {},
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          // `DeleteDashboards` is idempotent: AWS returns success (not
          // `DashboardNotFoundError`) for names that don't exist, so a
          // re-delete after a state-persistence failure is a safe no-op.
          yield* retryConcurrent(
            cloudwatch.deleteDashboards({
              DashboardNames: [output.dashboardName],
            }),
          );
        }),
        list: () =>
          Effect.gen(function* () {
            // `listDashboards` only returns entry metadata (name/arn/size),
            // not the body, so we re-read each dashboard to produce the full
            // Attributes shape `read` returns.
            const names = yield* cloudwatch.listDashboards.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) =>
                  (page.DashboardEntries ?? [])
                    .map((entry) => entry.DashboardName)
                    .filter((name): name is string => name != null),
                ),
              ),
            );

            const states = yield* Effect.forEach(names, (name) => readDashboard(name), {
              concurrency: 10,
            });

            return states.filter(
              (state): state is NonNullable<typeof state> => state !== undefined,
            );
          }),
      };
    }),
  );