sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ RUM/ AppMonitor.ts

import * as logs from "@distilled.cloud/aws/cloudwatch-logs";
import * as rum from "@distilled.cloud/aws/rum";
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 } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";

/**
 * Configuration for how the CloudWatch RUM web client collects data from
 * your application's user sessions.
 */
export interface AppMonitorConfiguration {
  /**
   * The ID of the Amazon Cognito identity pool used to authorize the sending
   * of data to RUM.
   */
  identityPoolId?: string;
  /**
   * Pages in your application excluded from RUM data collection. You can't
   * specify both `excludedPages` and `includedPages`.
   */
  excludedPages?: string[];
  /**
   * If your application has pages that RUM should collect data from and
   * others it should not, list the pages to collect here. You can't specify
   * both `excludedPages` and `includedPages`.
   */
  includedPages?: string[];
  /**
   * Pages to be displayed with a "favorite" icon in the CloudWatch RUM
   * console.
   */
  favoritePages?: string[];
  /**
   * The portion of user sessions to sample for RUM data collection, between
   * 0 and 1 (e.g. `0.1` samples 10% of sessions).
   * @default 0.1
   */
  sessionSampleRate?: number;
  /**
   * The ARN of the guest IAM role attached to the Cognito identity pool that
   * authorizes sending data to RUM.
   */
  guestRoleArn?: string;
  /**
   * Whether the RUM web client sets a cookie so that RUM can collect data
   * about user sessions across page views.
   * @default false
   */
  allowCookies?: boolean;
  /**
   * The kinds of telemetry to collect: `"errors"`, `"performance"`, and/or
   * `"http"`.
   */
  telemetries?: ("errors" | "performance" | "http")[];
  /**
   * Whether RUM sends client-side traces to AWS X-Ray for sampled sessions.
   * @default false
   */
  enableXRay?: boolean;
}

export interface AppMonitorProps {
  /**
   * Name of the app monitor. Changing the name replaces the app monitor.
   * @default ${app}-${stage}-${id}
   */
  appMonitorName?: string;
  /**
   * The top-level internet domain name your application has administrative
   * authority over, e.g. `example.com` or `*.example.com`. Specify exactly
   * one of `domain` or `domainList`.
   */
  domain?: string;
  /**
   * List of internet domain names your application has administrative
   * authority over (up to 5). Specify exactly one of `domain` or
   * `domainList`.
   */
  domainList?: string[];
  /**
   * Configuration for how the RUM web client collects session data.
   */
  appMonitorConfiguration?: AppMonitorConfiguration;
  /**
   * Whether the app monitor copies the telemetry data it collects to a
   * CloudWatch Logs log group in your account (retained for 30 days).
   * @default false
   */
  cwLogEnabled?: boolean;
  /**
   * Whether the app monitor accepts custom events sent by the RUM web
   * client.
   * @default "DISABLED"
   */
  customEvents?: "ENABLED" | "DISABLED";
  /**
   * Tags to apply to the app monitor. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface AppMonitor extends Resource<
  "AWS.RUM.AppMonitor",
  AppMonitorProps,
  {
    /**
     * Name of the app monitor.
     */
    appMonitorName: string;
    /**
     * Unique ID of the app monitor (used by the RUM web client configuration).
     */
    appMonitorId: string;
    /**
     * ARN of the app monitor.
     */
    appMonitorArn: string;
  },
  never,
  Providers
> {}

/**
 * An Amazon CloudWatch RUM app monitor that collects client-side telemetry
 * (page load times, JavaScript errors, user behavior) from your web
 * application.
 * ### Creating App Monitors
 * **Example:** Monitor a single domain
 * ```typescript
 * import * as RUM from "@alchemy.run/aws/RUM";
 *
 * const monitor = yield* RUM.AppMonitor("SiteMonitor", {
 *   domain: "example.com",
 * });
 * ```
 *
 * **Example:** Sample all sessions and collect every telemetry type
 * ```typescript
 * const monitor = yield* RUM.AppMonitor("SiteMonitor", {
 *   domain: "*.example.com",
 *   appMonitorConfiguration: {
 *     sessionSampleRate: 1,
 *     telemetries: ["errors", "performance", "http"],
 *     allowCookies: true,
 *   },
 * });
 * ```
 *
 * ### Log Retention and Custom Events
 * **Example:** Copy telemetry to CloudWatch Logs and accept custom events
 * ```typescript
 * const monitor = yield* RUM.AppMonitor("SiteMonitor", {
 *   domainList: ["example.com", "app.example.com"],
 *   cwLogEnabled: true,
 *   customEvents: "ENABLED",
 * });
 * ```
 *
 * @resource
 */
export const AppMonitor = Resource<AppMonitor>("AWS.RUM.AppMonitor");

/**
 * Raised when an `AppMonitor` is configured with both or neither of
 * `domain` / `domainList` — the API requires exactly one.
 */
export class RumAppMonitorInvalidDomains extends Data.TaggedError("RumAppMonitorInvalidDomains")<{
  message: string;
}> {}

const validateDomains = (props: Pick<AppMonitorProps, "domain" | "domainList">) => {
  const hasDomain = props.domain !== undefined;
  const hasDomainList = (props.domainList?.length ?? 0) > 0;
  if (hasDomain === hasDomainList) {
    return Effect.fail(
      new RumAppMonitorInvalidDomains({
        message: hasDomain
          ? "specify exactly one of domain or domainList, not both."
          : "an AppMonitor requires either domain or domainList.",
      }),
    );
  }
  return Effect.void;
};

const sameStringList = (a: readonly string[] | undefined, b: readonly string[] | undefined) => {
  const left = [...(a ?? [])].sort();
  const right = [...(b ?? [])].sort();
  return left.length === right.length && left.every((v, i) => v === right[i]);
};

const desiredConfiguration = (props: AppMonitorProps): rum.AppMonitorConfiguration | undefined => {
  const c = props.appMonitorConfiguration;
  if (c === undefined) return undefined;
  return {
    IdentityPoolId: c.identityPoolId,
    ExcludedPages: c.excludedPages,
    IncludedPages: c.includedPages,
    FavoritePages: c.favoritePages,
    SessionSampleRate: c.sessionSampleRate,
    GuestRoleArn: c.guestRoleArn,
    AllowCookies: c.allowCookies,
    Telemetries: c.telemetries,
    EnableXRay: c.enableXRay,
  };
};

/** Compares only the fields the user explicitly configured against the observed cloud state. */
const configurationInSync = (
  observed: rum.AppMonitorConfiguration | undefined,
  desired: rum.AppMonitorConfiguration | undefined,
) => {
  if (desired === undefined) return true;
  const o = observed ?? {};
  return (
    (desired.IdentityPoolId === undefined || o.IdentityPoolId === desired.IdentityPoolId) &&
    (desired.ExcludedPages === undefined ||
      sameStringList(o.ExcludedPages, desired.ExcludedPages)) &&
    (desired.IncludedPages === undefined ||
      sameStringList(o.IncludedPages, desired.IncludedPages)) &&
    (desired.FavoritePages === undefined ||
      sameStringList(o.FavoritePages, desired.FavoritePages)) &&
    (desired.SessionSampleRate === undefined ||
      o.SessionSampleRate === desired.SessionSampleRate) &&
    (desired.GuestRoleArn === undefined || o.GuestRoleArn === desired.GuestRoleArn) &&
    (desired.AllowCookies === undefined || (o.AllowCookies ?? false) === desired.AllowCookies) &&
    (desired.Telemetries === undefined || sameStringList(o.Telemetries, desired.Telemetries)) &&
    (desired.EnableXRay === undefined || (o.EnableXRay ?? false) === desired.EnableXRay)
  );
};

const appMonitorArn = (region: string, accountId: string, name: string) =>
  `arn:aws:rum:${region}:${accountId}:appmonitor/${name}`;

export const AppMonitorProvider = () =>
  Provider.effect(
    AppMonitor,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: Pick<AppMonitorProps, "appMonitorName">,
      ) {
        return props.appMonitorName ?? (yield* createPhysicalName({ id, maxLength: 64 }));
      });

      const observeMonitor = (name: string) =>
        rum.getAppMonitor({ Name: name }).pipe(
          Effect.map((r) => r.AppMonitor),
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );

      return AppMonitor.Provider.of({
        stables: ["appMonitorName", "appMonitorId", "appMonitorArn"],
        list: () =>
          Effect.gen(function* () {
            const { accountId, region } = yield* AWSEnvironment.current;
            const summaries = yield* rum.listAppMonitors.items({}).pipe(Stream.runCollect);
            return Array.from(summaries).flatMap((monitor) =>
              monitor.Name !== undefined && monitor.Id !== undefined
                ? [
                    {
                      appMonitorName: monitor.Name,
                      appMonitorId: monitor.Id,
                      appMonitorArn: appMonitorArn(region, accountId, monitor.Name),
                    },
                  ]
                : [],
            );
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const name = output?.appMonitorName ?? (yield* createName(id, olds ?? {}));
          const found = yield* observeMonitor(name);
          if (found?.Id === undefined) return undefined;
          const attrs = {
            appMonitorName: name,
            appMonitorId: found.Id,
            appMonitorArn: appMonitorArn(region, accountId, name),
          };
          const tags = Object.fromEntries(
            Object.entries(found.Tags ?? {}).filter(
              (t): t is [string, string] => t[1] !== undefined,
            ),
          );
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          yield* validateDomains(news ?? {});
          const oldName = yield* createName(id, olds ?? {});
          const newName = yield* createName(id, news ?? {});
          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
          // fall through: engine default update logic for mutable fields
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          yield* validateDomains(news);
          const { accountId, region } = yield* AWSEnvironment.current;
          const name = output?.appMonitorName ?? (yield* createName(id, news));
          const arn = appMonitorArn(region, accountId, name);
          const internalTags = yield* createInternalTags(id);
          const desiredTags: Record<string, string> = {
            ...news.tags,
            ...internalTags,
          };
          const desiredConfig = desiredConfiguration(news);
          const desiredCwLogEnabled = news.cwLogEnabled ?? false;
          const desiredCustomEvents = news.customEvents ?? "DISABLED";

          // 1. OBSERVE — cloud state is authoritative; output is only a
          //    cache of the derived physical name.
          let live = yield* observeMonitor(name);

          // 2. ENSURE — create when missing; a concurrent create surfaces as
          //    the typed ConflictException, which we treat as a race and
          //    re-observe. CreateAppMonitor is eventually consistent — an
          //    immediate GetAppMonitor can still miss it, and persisting an
          //    undefined appMonitorId poisons every downstream binding env —
          //    so poll (bounded) until the monitor is observable.
          if (live === undefined) {
            yield* rum
              .createAppMonitor({
                Name: name,
                Domain: news.domain,
                DomainList: news.domainList,
                Tags: desiredTags,
                AppMonitorConfiguration: desiredConfig,
                CwLogEnabled: desiredCwLogEnabled,
                CustomEvents: { Status: desiredCustomEvents },
              })
              .pipe(
                Effect.asVoid,
                Effect.catchTag("ConflictException", () => Effect.void),
              );
            live = yield* observeMonitor(name).pipe(
              Effect.repeat({
                schedule: Schedule.spaced("2 seconds"),
                until: (monitor) => monitor !== undefined,
                times: 15,
              }),
            );
          }

          // 3. SYNC — diff the OBSERVED domain(s), configuration, log
          //    setting, and custom-events status against the desired state;
          //    update only on drift.
          const inSync =
            live !== undefined &&
            (news.domain === undefined || live.Domain === news.domain) &&
            (news.domainList === undefined || sameStringList(live.DomainList, news.domainList)) &&
            configurationInSync(live.AppMonitorConfiguration, desiredConfig) &&
            (live.DataStorage?.CwLog?.CwLogEnabled ?? false) === desiredCwLogEnabled &&
            (live.CustomEvents?.Status ?? "DISABLED") === desiredCustomEvents;
          if (!inSync) {
            yield* rum.updateAppMonitor({
              Name: name,
              Domain: news.domain,
              DomainList: news.domainList,
              AppMonitorConfiguration: desiredConfig,
              CwLogEnabled: desiredCwLogEnabled,
              CustomEvents: { Status: desiredCustomEvents },
            });
            live = yield* observeMonitor(name);
          }

          // 3b. SYNC TAGS — diff against OBSERVED cloud tags so adoption
          //     converges (create-time Tags only apply on first create).
          const currentTags = Object.fromEntries(
            Object.entries(live?.Tags ?? {}).filter(
              (t): t is [string, string] => t[1] !== undefined,
            ),
          );
          const { upsert, removed } = diffTags(currentTags, desiredTags);
          if (upsert.length > 0) {
            yield* rum.tagResource({
              ResourceArn: arn,
              Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }
          if (removed.length > 0) {
            yield* rum.untagResource({ ResourceArn: arn, TagKeys: removed });
          }

          yield* session.note(name);
          return {
            appMonitorName: name,
            appMonitorId: live?.Id ?? output?.appMonitorId!,
            appMonitorArn: arn,
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* rum.deleteAppMonitor({ Name: output.appMonitorName }).pipe(
            // idempotent — the monitor may already be gone
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
          );

          // When cwLogEnabled is (or was ever) on, RUM vends telemetry into
          // a log group named
          //   /aws/vendedlogs/RUMService_{appMonitorName}{first 8 hex chars of Id}
          // and deleteAppMonitor does NOT remove it — without this reap every
          // deleted log-enabled monitor leaks an orphaned log group. Match
          // the observed groups against the monitor's Id so a sibling
          // monitor whose name extends ours is never reaped by accident.
          const logGroupPrefix = `/aws/vendedlogs/RUMService_${output.appMonitorName}`;
          const idHex = output.appMonitorId.replaceAll("-", "");
          const groups = yield* logs
            .describeLogGroups({ logGroupNamePrefix: logGroupPrefix })
            .pipe(Effect.map((r) => r.logGroups ?? []));
          yield* Effect.forEach(
            groups.flatMap((g) =>
              g.logGroupName !== undefined &&
              idHex.startsWith(g.logGroupName.slice(logGroupPrefix.length))
                ? [g.logGroupName]
                : [],
            ),
            (logGroupName) =>
              logs
                .deleteLogGroup({ logGroupName })
                .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void)),
          );
        }),
      });
    }),
  );