sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ObservabilityAdmin/ TelemetryRule.ts

import * as logs from "@distilled.cloud/aws/cloudwatch-logs";
import * as ec2 from "@distilled.cloud/aws/ec2";
import * as obs from "@distilled.cloud/aws/observabilityadmin";
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 { toWireDays } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

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

/**
 * Where a telemetry rule delivers the telemetry it enables. Mirrors the wire
 * `TelemetryDestinationConfiguration`, with the retention period expressed as
 * a `Duration.Input` instead of the wire's `RetentionInDays`.
 */
export interface TelemetryRuleDestination extends Omit<
  obs.TelemetryDestinationConfiguration,
  "RetentionInDays"
> {
  /**
   * How long CloudWatch Logs retains the telemetry delivered by this rule.
   * Accepts any `Duration.Input` (e.g. `"30 days"`, `Duration.days(90)`);
   * converted to whole days on the wire (`RetentionInDays`).
   */
  Retention?: Duration.Input;
}

export interface TelemetryRuleProps {
  /**
   * Name of the telemetry rule. If omitted, a deterministic physical name is
   * generated. Changing the name replaces the rule.
   */
  ruleName?: string;
  /**
   * The type of telemetry the rule enables — `"Logs"`, `"Metrics"`, or
   * `"Traces"`.
   */
  telemetryType: obs.TelemetryType;
  /**
   * The AWS resource type the rule applies to, e.g. `"AWS::EC2::VPC"`.
   */
  resourceType?: obs.ResourceType;
  /**
   * The telemetry sources the rule enables, e.g. `["VPC_FLOW_LOGS"]`.
   */
  telemetrySourceTypes?: obs.TelemetrySourceType[];
  /**
   * Where the enabled telemetry is delivered (destination type, pattern,
   * retention, and per-source parameters such as VPC flow-log format).
   */
  destinationConfiguration?: TelemetryRuleDestination;
  /**
   * Organization-level scope selector (organization rules only).
   */
  scope?: string;
  /**
   * Criteria selecting which resources the rule configures (such as
   * resource tags). The expression format is service-defined (the console's
   * tag filter builder produces it); an invalid expression is rejected with
   * `ValidationException: Invalid resource selection criteria`. Without
   * selection criteria the rule applies to every resource of `resourceType`
   * in the account.
   */
  selectionCriteria?: string;
  /**
   * Whether the rule's telemetry parameters may be updated after creation.
   */
  allowFieldUpdates?: boolean;
  /**
   * Regions the rule applies to. Mutually exclusive with `allRegions`.
   */
  regions?: string[];
  /**
   * Apply the rule in all regions. Mutually exclusive with `regions`.
   */
  allRegions?: boolean;
  /**
   * User-defined tags for the rule.
   */
  tags?: Record<string, string>;
}

export interface TelemetryRule extends Resource<
  "AWS.ObservabilityAdmin.TelemetryRule",
  TelemetryRuleProps,
  {
    /** The name of the telemetry rule. */
    ruleName: string;
    /** The ARN of the telemetry rule. */
    ruleArn: string;
    /** The telemetry type the rule enables. */
    telemetryType: string | undefined;
    /** The resource type the rule applies to. */
    resourceType: string | undefined;
    /** The tags applied to the rule. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * A CloudWatch **telemetry rule** (Observability Admin) — automatically
 * enables telemetry (such as VPC flow logs) for AWS resources in your
 * account that match the rule's criteria.
 *
 * The account must be onboarded to CloudWatch telemetry config (see
 * `ObservabilityAdmin.TelemetryConfig`) before rules can be created.
 *
 * ### Creating a Telemetry Rule
 * **Example:** Enable VPC flow logs for the account's VPCs
 * ```typescript
 * import * as ObservabilityAdmin from "@alchemy.run/aws/ObservabilityAdmin";
 *
 * // Onboard the account to telemetry config first.
 * const telemetry = yield* ObservabilityAdmin.TelemetryConfig("Telemetry");
 *
 * const rule = yield* ObservabilityAdmin.TelemetryRule("FlowLogs", {
 *   resourceType: "AWS::EC2::VPC",
 *   telemetryType: "Logs",
 *   telemetrySourceTypes: ["VPC_FLOW_LOGS"],
 *   destinationConfiguration: {
 *     DestinationType: "cloud-watch-logs",
 *     Retention: "30 days",
 *   },
 * });
 * ```
 *
 * **Example:** Custom flow-log parameters
 * ```typescript
 * const rule = yield* ObservabilityAdmin.TelemetryRule("FlowLogs", {
 *   resourceType: "AWS::EC2::VPC",
 *   telemetryType: "Logs",
 *   telemetrySourceTypes: ["VPC_FLOW_LOGS"],
 *   destinationConfiguration: {
 *     DestinationType: "cloud-watch-logs",
 *     Retention: "90 days",
 *     VPCFlowLogParameters: {
 *       TrafficType: "REJECT",
 *       MaxAggregationInterval: 600,
 *     },
 *   },
 * });
 * ```
 *
 * @resource
 */
export const TelemetryRule = Resource<TelemetryRule>("AWS.ObservabilityAdmin.TelemetryRule");

/** Normalize the wire tag map (values may be undefined) to a plain record. */
const toTagRecord = (
  tags: { [key: string]: string | undefined } | undefined,
): Record<string, string> =>
  Object.fromEntries(
    Object.entries(tags ?? {}).filter((entry): entry is [string, string] => entry[1] !== undefined),
  );

const sameJson = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);

/**
 * True when any field the desired rule declares differs from the observed
 * rule. Fields the desired rule leaves unset are don't-cares (AWS echoes
 * service defaults for them).
 */
const ruleNeedsUpdate = (
  desired: obs.TelemetryRule,
  observed: obs.TelemetryRule | undefined,
): boolean => {
  if (observed === undefined) return true;
  const observedByKey = new Map<string, unknown>(Object.entries(observed));
  return Object.entries(desired).some(([key, value]) => !sameJson(value, observedByKey.get(key)));
};

const vpcFlowLogGroupName = "/aws/vpc";

const isVpcFlowLogRule = (rule: obs.TelemetryRule | undefined): boolean =>
  rule?.ResourceType === "AWS::EC2::VPC" &&
  rule.TelemetryType === "Logs" &&
  rule.TelemetrySourceTypes?.includes("VPC_FLOW_LOGS") === true &&
  rule.DestinationConfiguration?.DestinationType === "cloud-watch-logs";

const isManagedVpcFlowLog = (
  flowLog: ec2.FlowLog,
): flowLog is ec2.FlowLog & { FlowLogId: string } =>
  flowLog.FlowLogId !== undefined &&
  flowLog.ResourceId?.startsWith("vpc-") === true &&
  flowLog.LogGroupName === vpcFlowLogGroupName &&
  flowLog.LogDestinationType === "cloud-watch-logs" &&
  flowLog.Tags?.some(
    (tag) => tag.Key === "CloudWatchTelemetryRuleManaged" && tag.Value === "true",
  ) === true;

class TelemetryRuleStillExists extends Data.TaggedError("TelemetryRuleStillExists")<{
  readonly ruleName: string;
}> {}

class ManagedVpcFlowLogDeleteFailed extends Data.TaggedError("ManagedVpcFlowLogDeleteFailed")<{
  readonly failures: ec2.UnsuccessfulItem[];
}> {}

class ManagedVpcFlowLogsStillExist extends Data.TaggedError("ManagedVpcFlowLogsStillExist")<{
  readonly flowLogIds: string[];
}> {}

class ManagedVpcLogGroupStillExists extends Data.TaggedError("ManagedVpcLogGroupStillExists")<{
  readonly logGroupName: string;
}> {}

const cleanupObservationSchedule = Schedule.max([Schedule.fixed("1 second"), Schedule.recurs(10)]);

/** Project props to the wire `TelemetryRule` struct (dropping undefineds). */
const toWireRule = (props: TelemetryRuleProps): obs.TelemetryRule =>
  JSON.parse(
    JSON.stringify({
      ResourceType: props.resourceType,
      TelemetryType: props.telemetryType,
      TelemetrySourceTypes: props.telemetrySourceTypes,
      DestinationConfiguration:
        props.destinationConfiguration === undefined
          ? undefined
          : (() => {
              const { Retention, ...rest } = props.destinationConfiguration;
              return {
                ...rest,
                RetentionInDays: toWireDays(Retention),
              };
            })(),
      Scope: props.scope,
      SelectionCriteria: props.selectionCriteria,
      AllowFieldUpdates: props.allowFieldUpdates,
      Regions: props.regions,
      AllRegions: props.allRegions,
    }),
  );

export const TelemetryRuleProvider = () =>
  Provider.effect(
    TelemetryRule,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: TelemetryRuleProps) {
        return props.ruleName ?? (yield* createPhysicalName({ id }));
      });

      const readRule = Effect.fn(function* (identifier: string) {
        return yield* obs
          .getTelemetryRule({ RuleIdentifier: identifier })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      });

      const waitUntilRuleAbsent = Effect.fn(function* (ruleName: string) {
        yield* readRule(ruleName).pipe(
          Effect.flatMap((rule) =>
            rule === undefined
              ? Effect.void
              : Effect.fail(new TelemetryRuleStillExists({ ruleName })),
          ),
          Effect.retry({
            while: (error) => error._tag === "TelemetryRuleStillExists",
            schedule: cleanupObservationSchedule,
          }),
        );
      });

      const matchingRulesRemain = Effect.fn(function* () {
        const summaries = yield* obs.listTelemetryRules.items({}).pipe(
          Stream.runCollect,
          Effect.map((items) => Array.from(items)),
        );
        const rules = yield* Effect.forEach(
          summaries.flatMap((summary) =>
            summary.RuleName === undefined ? [] : [summary.RuleName],
          ),
          readRule,
          { concurrency: 4 },
        );
        return rules.some((rule) => isVpcFlowLogRule(rule?.TelemetryRule));
      });

      const listManagedVpcFlowLogs = () =>
        ec2.describeFlowLogs
          .items({
            Filter: [
              {
                Name: "tag:CloudWatchTelemetryRuleManaged",
                Values: ["true"],
              },
              { Name: "log-group-name", Values: [vpcFlowLogGroupName] },
            ],
          })
          .pipe(
            Stream.runCollect,
            Effect.map((items) => Array.from(items).filter(isManagedVpcFlowLog)),
          );

      const waitUntilManagedFlowLogsAbsent = Effect.fn(function* (deletedIds: string[]) {
        const deleted = new Set(deletedIds);
        yield* listManagedVpcFlowLogs().pipe(
          Effect.flatMap((flowLogs) => {
            const remaining = flowLogs
              .map((flowLog) => flowLog.FlowLogId)
              .filter((flowLogId) => deleted.has(flowLogId));
            return remaining.length === 0
              ? Effect.void
              : Effect.fail(
                  new ManagedVpcFlowLogsStillExist({
                    flowLogIds: remaining,
                  }),
                );
          }),
          Effect.retry({
            while: (error) => error._tag === "ManagedVpcFlowLogsStillExist",
            schedule: cleanupObservationSchedule,
          }),
        );
      });

      const waitUntilVpcLogGroupAbsent = logs
        .describeLogGroups({
          logGroupNamePrefix: vpcFlowLogGroupName,
          limit: 1,
        })
        .pipe(
          Effect.flatMap((response) =>
            response.logGroups?.some((group) => group.logGroupName === vpcFlowLogGroupName) === true
              ? Effect.fail(
                  new ManagedVpcLogGroupStillExists({
                    logGroupName: vpcFlowLogGroupName,
                  }),
                )
              : Effect.void,
          ),
          Effect.retry({
            while: (error) => error._tag === "ManagedVpcLogGroupStillExists",
            schedule: cleanupObservationSchedule,
          }),
        );

      const cleanupManagedVpcFlowLogs = Effect.fn(function* () {
        const managed = yield* listManagedVpcFlowLogs();
        const flowLogIds = managed.map((flowLog) => flowLog.FlowLogId);
        if (flowLogIds.length > 0) {
          yield* ec2.deleteFlowLogs({ FlowLogIds: flowLogIds }).pipe(
            Effect.flatMap((response) => {
              const failures = (response.Unsuccessful ?? []).filter(
                (failure) => failure.Error?.Code !== "InvalidFlowLogId.NotFound",
              );
              return failures.length === 0
                ? Effect.void
                : Effect.fail(new ManagedVpcFlowLogDeleteFailed({ failures }));
            }),
            Effect.retry({
              while: (error) => error._tag === "ManagedVpcFlowLogDeleteFailed",
              schedule: cleanupObservationSchedule,
            }),
          );
          yield* waitUntilManagedFlowLogsAbsent(flowLogIds);
        }

        // `/aws/vpc` is shared by all Observability Admin-managed VPC flow
        // logs. Delete it only after no flow log of any ownership still uses
        // the destination; otherwise deleting the group would destroy user
        // logs or another rule's delivery target.
        const groupConsumers = yield* ec2.describeFlowLogs
          .items({
            Filter: [{ Name: "log-group-name", Values: [vpcFlowLogGroupName] }],
          })
          .pipe(Stream.runCollect);
        if (groupConsumers.length > 0) return;

        yield* logs.deleteLogGroup({ logGroupName: vpcFlowLogGroupName }).pipe(
          Effect.retry({
            while: (error) =>
              error._tag === "OperationAbortedException" ||
              error._tag === "ServiceUnavailableException",
            schedule: cleanupObservationSchedule,
          }),
          Effect.catchTag("ResourceNotFoundException", () => Effect.void),
        );
        yield* waitUntilVpcLogGroupAbsent;
      });

      const readTags = Effect.fn(function* (ruleArn: string) {
        return yield* obs.listTagsForResource({ ResourceARN: ruleArn }).pipe(
          Effect.map((r) => toTagRecord(r.Tags)),
          Effect.catchTag("ResourceNotFoundException", () =>
            Effect.succeed({} as Record<string, string>),
          ),
        );
      });

      const toAttrs = (rule: obs.GetTelemetryRuleOutput, tags: Record<string, string>) => ({
        ruleName: rule.RuleName ?? "",
        ruleArn: rule.RuleArn ?? "",
        telemetryType: rule.TelemetryRule?.TelemetryType,
        resourceType: rule.TelemetryRule?.ResourceType,
        tags,
      });

      const readAttrs = Effect.fn(function* (identifier: string) {
        const rule = yield* readRule(identifier);
        if (rule === undefined || rule.RuleArn === undefined) return undefined;
        const tags = yield* readTags(rule.RuleArn);
        return toAttrs(rule, tags);
      });

      return TelemetryRule.Provider.of({
        stables: ["ruleName", "ruleArn"],

        list: () =>
          obs.listTelemetryRules.items({}).pipe(
            Stream.runCollect,
            Effect.flatMap((summaries) =>
              Effect.forEach(
                Array.from(summaries).flatMap((s) =>
                  s.RuleName === undefined ? [] : [s.RuleName],
                ),
                (name) => readAttrs(name),
                { concurrency: 4 },
              ),
            ),
            Effect.map((attrs) => attrs.flatMap((a) => (a === undefined ? [] : [a]))),
          ),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.ruleName ?? (yield* createName(id, olds ?? {}));
          const attrs = yield* readAttrs(name);
          if (attrs === undefined) return undefined;
          return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
        }),

        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          // The name is the only immutable property; the rule configuration
          // is updatable in place via UpdateTelemetryRule.
          if ((yield* createName(id, olds)) !== (yield* createName(id, news))) {
            return { action: "replace" } as const;
          }
          return undefined;
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const props = news!;
          const name = output?.ruleName ?? (yield* createName(id, props));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...props.tags, ...internalTags };
          const desiredRule = toWireRule(props);

          // 1. Observe — cloud state is authoritative.
          let observed = yield* readRule(name);

          // 2. Ensure — create if missing; a ConflictException means a peer
          //    created the same-named rule concurrently, so re-observe.
          if (observed === undefined) {
            yield* obs
              .createTelemetryRule({
                RuleName: name,
                Rule: desiredRule,
                Tags: desiredTags,
              })
              .pipe(Effect.catchTag("ConflictException", () => Effect.void));
            // The read-after-create is eventually consistent; wait (bounded)
            // for the rule to materialize.
            observed = yield* readRule(name).pipe(
              Effect.flatMap((rule) =>
                rule === undefined
                  ? Effect.fail(
                      new TelemetryRuleNotReady({
                        message: `telemetry rule '${name}' not yet visible`,
                      }),
                    )
                  : Effect.succeed(rule),
              ),
              Effect.retry({
                schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(8)]),
              }),
            );
          } else if (ruleNeedsUpdate(desiredRule, observed.TelemetryRule)) {
            // 3. Sync — UpdateTelemetryRule replaces the whole rule config;
            //    apply only on an actual delta against OBSERVED state.
            yield* obs.updateTelemetryRule({
              RuleIdentifier: name,
              Rule: desiredRule,
            });
            observed = (yield* readRule(name)) ?? observed;
          }

          // 3b. Sync tags — diff against OBSERVED cloud tags.
          const ruleArn = observed.RuleArn!;
          const observedTags = yield* readTags(ruleArn);
          const { removed, upsert } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* obs.tagResource({
              ResourceARN: ruleArn,
              Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }
          if (removed.length > 0) {
            yield* obs.untagResource({
              ResourceARN: ruleArn,
              TagKeys: removed,
            });
          }

          yield* session.note(name);
          const tags = yield* readTags(ruleArn);
          return toAttrs(observed, tags);
        }),

        delete: Effect.fn(function* ({ output, olds }) {
          // Capture the live rule before deleting it so adoption and drift do
          // not make cleanup decisions from stale desired state.
          const observed = yield* readRule(output.ruleName);
          const deletedRule =
            observed?.TelemetryRule ?? (olds === undefined ? undefined : toWireRule(olds));
          yield* obs
            .deleteTelemetryRule({ RuleIdentifier: output.ruleName })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
          yield* waitUntilRuleAbsent(output.ruleName);

          // Observability Admin asynchronously creates EC2 flow logs and the
          // shared `/aws/vpc` destination for VPC_FLOW_LOGS rules, but deleting
          // the rule does not remove them. Reap only when this was such a rule
          // and no other live rule can own the shared managed resources.
          if (isVpcFlowLogRule(deletedRule) && !(yield* matchingRulesRemain())) {
            yield* cleanupManagedVpcFlowLogs();
          }
        }),
      });
    }),
  );