sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ XRay/ Group.ts

import * as xray from "@distilled.cloud/aws/xray";
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, createTagsList, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

export interface GroupProps {
  /**
   * Name of the group (1-32 characters). `Default` is reserved by X-Ray for
   * the built-in group that matches all traces.
   *
   * Changing the name replaces the group.
   * @default ${app}-${stage}-${id}
   */
  groupName?: string;
  /**
   * The filter expression defining the criteria by which traces belong to
   * the group, e.g. `service("my-api") AND responsetime > 2`.
   */
  filterExpression: string;
  /**
   * Whether to enable insights for the group. Insights detect anomalies in
   * the group's traces.
   * @default false
   */
  insightsEnabled?: boolean;
  /**
   * Whether insights should generate EventBridge notifications. Requires
   * `insightsEnabled: true`.
   * @default false
   */
  notificationsEnabled?: boolean;
  /**
   * Tags to apply to the group. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface Group extends Resource<
  "AWS.XRay.Group",
  GroupProps,
  {
    /**
     * Name of the group.
     */
    groupName: string;
    /**
     * ARN of the group.
     */
    groupArn: string;
  },
  never,
  Providers
> {}

/**
 * An AWS X-Ray group that collects traces matching a filter expression, for
 * focused service maps, analytics, and insights.
 * ### Creating Groups
 * **Example:** Group traces for one service
 * ```typescript
 * import * as XRay from "@alchemy.run/aws/XRay";
 *
 * const group = yield* XRay.Group("ApiGroup", {
 *   filterExpression: 'service("my-api")',
 * });
 * ```
 *
 * **Example:** Group slow requests with insights enabled
 * ```typescript
 * const group = yield* XRay.Group("SlowRequests", {
 *   filterExpression: "responsetime > 2",
 *   insightsEnabled: true,
 *   notificationsEnabled: true,
 * });
 * ```
 *
 * @resource
 */
export const Group = Resource<Group>("AWS.XRay.Group");

/**
 * Raised when a `Group` is configured with the reserved group name
 * `Default`, which X-Ray uses for the built-in group matching all traces.
 */
export class XRayReservedGroupName extends Data.TaggedError("XRayReservedGroupName")<{
  message: string;
}> {}

const validateGroupName = (props: Pick<GroupProps, "groupName">) =>
  props.groupName === "Default"
    ? Effect.fail(
        new XRayReservedGroupName({
          message: '"Default" is reserved for the built-in X-Ray group — choose another groupName.',
        }),
      )
    : Effect.void;

export const GroupProvider = () =>
  Provider.effect(
    Group,
    Effect.gen(function* () {
      const createGroupName = Effect.fn(function* (
        id: string,
        props: Pick<GroupProps, "groupName">,
      ) {
        // X-Ray group names are limited to 32 characters.
        return props.groupName ?? (yield* createPhysicalName({ id, maxLength: 32 }));
      });

      const desiredInsights = (props: GroupProps) => ({
        InsightsEnabled: props.insightsEnabled ?? false,
        NotificationsEnabled: props.notificationsEnabled ?? false,
      });

      const observeGroup = (groupName: string) =>
        xray.getGroup({ GroupName: groupName }).pipe(
          Effect.map((r) => r.Group),
          // Typed synthetic tag for a missing group.
          Effect.catchTag("GroupNotFound", () => Effect.undefined),
        );

      const observedTags = (groupArn: string) =>
        xray.listTagsForResource.items({ ResourceARN: groupArn }).pipe(
          Stream.runCollect,
          Effect.map((chunk) => Object.fromEntries(Array.from(chunk).map((t) => [t.Key, t.Value]))),
          Effect.catchTag("ResourceNotFoundException", () =>
            Effect.succeed({} as Record<string, string>),
          ),
        );

      return Group.Provider.of({
        stables: ["groupName", "groupArn"],
        list: () =>
          Effect.gen(function* () {
            const groups = yield* xray.getGroups.items({}).pipe(Stream.runCollect);
            return Array.from(groups).flatMap((group) =>
              group.GroupName && group.GroupARN && group.GroupName !== "Default"
                ? [{ groupName: group.GroupName, groupArn: group.GroupARN }]
                : [],
            );
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const groupName = output?.groupName ?? (yield* createGroupName(id, olds ?? {}));
          const found = yield* observeGroup(groupName);
          if (!found?.GroupARN) return undefined;
          const attrs = { groupName, groupArn: found.GroupARN };
          const tags = yield* observedTags(found.GroupARN);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          yield* validateGroupName(news ?? {});
          const oldName = yield* createGroupName(id, olds ?? {});
          const newName = yield* createGroupName(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* validateGroupName(news);
          const groupName = output?.groupName ?? (yield* createGroupName(id, news));
          const insights = desiredInsights(news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE — cloud state is authoritative.
          let live = yield* observeGroup(groupName);

          // 2. ENSURE — create when missing; a concurrent create surfaces as
          //    the typed GroupAlreadyExists tag, which we treat as a race
          //    and re-observe.
          if (live === undefined) {
            live = yield* xray
              .createGroup({
                GroupName: groupName,
                FilterExpression: news.filterExpression,
                InsightsConfiguration: insights,
                Tags: createTagsList(desiredTags),
              })
              .pipe(
                Effect.map((r) => r.Group),
                Effect.catchTag("GroupAlreadyExists", () => observeGroup(groupName)),
              );
          }

          // 3. SYNC — diff the OBSERVED filter expression and insights
          //    configuration against the desired state; update only on drift.
          const observedInsights = live?.InsightsConfiguration ?? {};
          const inSync =
            live !== undefined &&
            live.FilterExpression === news.filterExpression &&
            (observedInsights.InsightsEnabled ?? false) === insights.InsightsEnabled &&
            (observedInsights.NotificationsEnabled ?? false) === insights.NotificationsEnabled;
          if (!inSync) {
            live = yield* xray
              .updateGroup({
                GroupName: groupName,
                FilterExpression: news.filterExpression,
                InsightsConfiguration: insights,
              })
              .pipe(Effect.map((r) => r.Group));
          }

          const groupArn = live?.GroupARN ?? output?.groupArn;

          // 3b. SYNC TAGS — diff against OBSERVED cloud tags so adoption
          //     converges (create-time Tags only apply on first create).
          if (groupArn !== undefined) {
            const currentTags = yield* observedTags(groupArn);
            const { upsert, removed } = diffTags(currentTags, desiredTags);
            if (upsert.length > 0) {
              yield* xray.tagResource({ ResourceARN: groupArn, Tags: upsert });
            }
            if (removed.length > 0) {
              yield* xray.untagResource({
                ResourceARN: groupArn,
                TagKeys: removed,
              });
            }
          }

          yield* session.note(groupName);
          return { groupName, groupArn: groupArn! };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* xray.deleteGroup({ GroupName: output.groupName }).pipe(
            // Typed synthetic tag for a missing group — idempotent delete.
            Effect.catchTag("GroupNotFound", () => Effect.void),
          );
        }),
      });
    }),
  );