sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ OAM/ Link.ts

import * as oam from "@distilled.cloud/aws/oam";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { hasAlchemyTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { deleteLinkAndWait, readOamTags, retryOamMutation, syncOamTags } from "./internal.ts";

/**
 * The telemetry resource types that can be shared over a link.
 */
export type LinkResourceType =
  | "AWS::CloudWatch::Metric"
  | "AWS::Logs::LogGroup"
  | "AWS::XRay::Trace"
  | "AWS::ApplicationInsights::Application"
  | "AWS::InternetMonitor::Monitor"
  | "AWS::ApplicationSignals::Service"
  | "AWS::ApplicationSignals::ServiceLevelObjective"
  | (string & {});

export interface LinkProps {
  /**
   * How the link's label appears in the monitoring account. Variables:
   * `$AccountName`, `$AccountEmail`, `$AccountEmailNoDomain`.
   * Changing the label template replaces the link.
   */
  labelTemplate: string;

  /**
   * The telemetry resource types shared from this source account to the
   * monitoring account, e.g. `AWS::CloudWatch::Metric`,
   * `AWS::Logs::LogGroup`, `AWS::XRay::Trace`.
   */
  resourceTypes: LinkResourceType[];

  /**
   * The ARN of the monitoring-account sink to attach to. The sink's policy
   * must permit this account to link. Changing the sink replaces the link.
   * Must be in a **different** account — OAM rejects a link to a sink in
   * the same account.
   */
  sinkIdentifier: string;

  /**
   * Optional filters restricting which log groups and metric namespaces
   * are shared to the monitoring account.
   */
  linkConfiguration?: {
    /**
     * Filter (OAM filter syntax) selecting which log groups are shared,
     * e.g. `LogGroupName LIKE 'aws/lambda/%'`.
     */
    logGroupConfiguration?: { filter: string };
    /**
     * Filter selecting which metric namespaces are shared, e.g.
     * `Namespace NOT LIKE 'AWS/%'`.
     */
    metricConfiguration?: { filter: string };
  };

  /**
   * User tags to attach to the link. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface Link extends Resource<
  "AWS.OAM.Link",
  LinkProps,
  {
    /** The ARN of the link. */
    linkArn: string;
    /** The random ID string that AWS generated as part of the link ARN. */
    linkId: string;
    /** The label that this link displays in the monitoring account. */
    label: string;
    /** The ARN of the sink this link is attached to. */
    sinkArn: string;
  },
  never,
  Providers
> {}

/**
 * A CloudWatch cross-account observability **link** — created in a source
 * account, it attaches to a monitoring-account {@link Sink} and shares the
 * selected telemetry types (metrics, log groups, traces, Application
 * Signals) with that account.
 *
 * The sink must live in a **different** account and its sink policy must
 * authorize this account to link.
 *
 * ### Creating a Link
 * **Example:** Share metrics and logs with a monitoring account
 * ```typescript
 * import * as OAM from "@alchemy.run/aws/OAM";
 *
 * const link = yield* OAM.Link("ToMonitoring", {
 *   labelTemplate: "$AccountName",
 *   resourceTypes: ["AWS::CloudWatch::Metric", "AWS::Logs::LogGroup"],
 *   sinkIdentifier:
 *     "arn:aws:oam:us-west-2:111122223333:sink/1c72e9ec-4d4a-4e...",
 * });
 * ```
 *
 * **Example:** Filter what is shared
 * ```typescript
 * const link = yield* OAM.Link("FilteredLink", {
 *   labelTemplate: "$AccountName",
 *   resourceTypes: ["AWS::CloudWatch::Metric", "AWS::Logs::LogGroup"],
 *   sinkIdentifier: sinkArn,
 *   linkConfiguration: {
 *     logGroupConfiguration: { filter: "LogGroupName LIKE 'aws/lambda/%'" },
 *     metricConfiguration: { filter: "Namespace NOT LIKE 'AWS/%'" },
 *   },
 * });
 * ```
 *
 * @resource
 */
export const Link = Resource<Link>("AWS.OAM.Link");

const toLinkConfiguration = (
  config: LinkProps["linkConfiguration"],
): oam.LinkConfiguration | undefined =>
  config === undefined
    ? undefined
    : {
        ...(config.logGroupConfiguration
          ? {
              LogGroupConfiguration: {
                Filter: config.logGroupConfiguration.filter,
              },
            }
          : {}),
        ...(config.metricConfiguration
          ? {
              MetricConfiguration: {
                Filter: config.metricConfiguration.filter,
              },
            }
          : {}),
      };

const sameResourceTypes = (
  a: readonly string[] | undefined,
  b: readonly string[] | undefined,
): boolean => JSON.stringify([...(a ?? [])].sort()) === JSON.stringify([...(b ?? [])].sort());

const sameLinkConfiguration = (
  a: oam.LinkConfiguration | undefined,
  b: oam.LinkConfiguration | undefined,
): boolean =>
  (a?.LogGroupConfiguration?.Filter ?? null) === (b?.LogGroupConfiguration?.Filter ?? null) &&
  (a?.MetricConfiguration?.Filter ?? null) === (b?.MetricConfiguration?.Filter ?? null);

export const LinkProvider = () =>
  Provider.effect(
    Link,
    Effect.gen(function* () {
      const getLinkByArn = Effect.fn(function* (linkArn: string) {
        return yield* oam
          .getLink({ Identifier: linkArn })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      });

      return Link.Provider.of({
        stables: ["linkArn", "linkId", "label", "sinkArn"],
        list: () =>
          oam.listLinks.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                page.Items.filter((item) => item.Arn != null && item.Id != null).map((item) => ({
                  linkArn: item.Arn!,
                  linkId: item.Id!,
                  label: item.Label ?? "",
                  sinkArn: item.SinkArn ?? "",
                })),
              ),
            ),
          ),
        read: Effect.fn(function* ({ id, output }) {
          // Links are identified by an auto-assigned ARN. With a cached ARN
          // we look it up directly; without one (state persistence failed
          // before the ARN landed) we scan the account's links for the one
          // carrying our ownership tags.
          if (output?.linkArn) {
            const found = yield* getLinkByArn(output.linkArn);
            if (!found?.Arn) return undefined;
            return {
              linkArn: found.Arn,
              linkId: found.Id!,
              label: found.Label ?? "",
              sinkArn: found.SinkArn ?? "",
            };
          }
          const pages = yield* oam.listLinks.pages({}).pipe(Stream.runCollect);
          const items = Array.from(pages).flatMap((page) => page.Items);
          for (const item of items) {
            if (item.Arn == null) continue;
            const tags = yield* readOamTags(item.Arn);
            if (yield* hasAlchemyTags(id, tags)) {
              return {
                linkArn: item.Arn,
                linkId: item.Id!,
                label: item.Label ?? "",
                sinkArn: item.SinkArn ?? "",
              };
            }
          }
          return undefined;
        }),
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          // The label template and the target sink are immutable —
          // UpdateLink only changes resource types and filters.
          if (news.labelTemplate !== olds.labelTemplate) {
            return { action: "replace" } as const;
          }
          if (news.sinkIdentifier !== olds.sinkIdentifier) {
            return { action: "replace" } as const;
          }
          return undefined;
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const desiredConfiguration = toLinkConfiguration(news.linkConfiguration);

          // OBSERVE — the cached ARN is only a hint; a deleted link falls
          // through to create.
          let live = output?.linkArn ? yield* getLinkByArn(output.linkArn) : undefined;

          // ENSURE
          if (live?.Arn == null) {
            live = yield* retryOamMutation(
              oam.createLink({
                LabelTemplate: news.labelTemplate,
                ResourceTypes: news.resourceTypes,
                SinkIdentifier: news.sinkIdentifier,
                LinkConfiguration: desiredConfiguration,
                Tags: news.tags,
              }),
            );
          }
          const linkArn = live!.Arn!;

          // SYNC — resource types + filters, diffed against observed state.
          if (
            !sameResourceTypes(live!.ResourceTypes, news.resourceTypes) ||
            !sameLinkConfiguration(live!.LinkConfiguration, desiredConfiguration)
          ) {
            live = yield* retryOamMutation(
              oam.updateLink({
                Identifier: linkArn,
                ResourceTypes: news.resourceTypes,
                LinkConfiguration: desiredConfiguration,
              }),
            );
          }

          // SYNC tags — against observed cloud tags (adoption-safe).
          yield* syncOamTags(linkArn, id, news.tags);

          yield* session.note(linkArn);
          return {
            linkArn,
            linkId: live!.Id!,
            label: live!.Label ?? "",
            sinkArn: live!.SinkArn ?? "",
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* deleteLinkAndWait(output.linkArn);
        }),
      });
    }),
  );