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

import * as cloudwatch from "@distilled.cloud/aws/cloudwatch";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Stream from "effect/Stream";
import { AWSEnvironment, type AccountID } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
import { createName, readResourceTags, retryConcurrent, updateResourceTags } from "./common.ts";

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

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

export type InsightRuleName = string;
export type InsightRuleArn = `arn:aws:cloudwatch:${RegionID}:${AccountID}:insight-rule/${string}`;

export interface CloudWatchLogRuleFilter {
  Match: string;
  In: string[];
}

export interface CloudWatchLogRuleDefinition {
  Schema: {
    Name: "CloudWatchLogRule";
    Version: 1;
  };
  LogGroupNames?: string[];
  LogGroupARNs?: string[];
  LogFormat: "JSON" | "CLF" | (string & {});
  Contribution: {
    Keys: string[];
    ValueOf?: string;
    Filters?: CloudWatchLogRuleFilter[];
  };
  AggregateOn: "Count" | "Sum" | (string & {});
}

export interface InsightRuleProps extends Omit<
  cloudwatch.PutInsightRuleInput,
  "RuleDefinition" | "RuleName" | "Tags"
> {
  /**
   * Name of the insight rule. If omitted, a unique name is generated.
   */
  name?: InsightRuleName;
  /**
   * Optional tags to apply to the insight rule.
   */
  tags?: Record<string, string>;
  /**
   * Typed Contributor Insights rule definition. The provider serializes this
   * object to the JSON string expected by the CloudWatch API.
   */
  RuleDefinition?: CloudWatchLogRuleDefinition;
}

export interface InsightRule extends Resource<
  "AWS.CloudWatch.InsightRule",
  InsightRuleProps,
  {
    /** Physical name of the insight rule. */
    ruleName: InsightRuleName;
    /** ARN of the insight rule. */
    ruleArn: InsightRuleArn;
    /** Current state of the rule (`ENABLED` or `DISABLED`). */
    state: string | undefined;
    /** The full InsightRule description as last read from CloudWatch. */
    insightRule: cloudwatch.InsightRule;
    /** Tags on the insight rule, including the internal Alchemy ownership tags. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * A CloudWatch Contributor Insights rule — analyzes log group entries to
 * surface the top-N contributors (IPs, user IDs, …) to a metric derived
 * from structured logs.
 * ### Creating Insight Rules
 * **Example:** Rule Definition
 * ```typescript
 * const rule = yield* InsightRule("TopContributors", {
 *   RuleState: "ENABLED",
 *   RuleDefinition: {
 *     Schema: {
 *       Name: "CloudWatchLogRule",
 *       Version: 1,
 *     },
 *     LogGroupNames: ["/my-app/access-logs"],
 *     LogFormat: "JSON",
 *     Contribution: {
 *       Keys: ["$.ip"],
 *     },
 *     AggregateOn: "Count",
 *   },
 * });
 * ```
 *
 * ### Reading Reports at Runtime
 * **Example:** Fetch the Rule's Top Contributors from a Function
 * ```typescript
 * // init — bind the rule to the function (see GetInsightRuleReport)
 * const getInsightRuleReport = yield* AWS.CloudWatch.GetInsightRuleReport(rule);
 *
 * // runtime
 * const now = yield* Effect.sync(() => Date.now());
 * const report = yield* getInsightRuleReport({
 *   StartTime: new Date(now - 3_600_000),
 *   EndTime: new Date(now),
 *   Period: 300,
 * });
 * ```
 *
 * @resource
 */
export const InsightRule = Resource<InsightRule>("AWS.CloudWatch.InsightRule");

const failureMessage = (failures: cloudwatch.PartialFailure[] | undefined) =>
  (failures ?? [])
    .map(
      (failure) =>
        `${failure.FailureResource ?? "unknown"}: ${failure.FailureCode ?? failure.ExceptionType ?? "failed"}`,
    )
    .join(", ");

const toPutInsightRuleInput = ({
  RuleDefinition,
  ...input
}: InsightRuleProps): cloudwatch.PutInsightRuleInput => ({
  ...input,
  RuleDefinition: RuleDefinition ? JSON.stringify(RuleDefinition) : undefined,
});

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

      const ruleArn = (name: string) =>
        AWSEnvironment.current.pipe(
          Effect.map(
            (env) =>
              `arn:aws:cloudwatch:${env.region}:${env.accountId}:insight-rule/${name}` as InsightRuleArn,
          ),
        );

      const readInsightRule = Effect.fn(function* (name: string) {
        const insightRule = yield* cloudwatch.describeInsightRules.pages({}).pipe(
          Stream.mapEffect(
            Effect.fn(function* (page) {
              return page.InsightRules?.find((candidate) => candidate.Name === name);
            }),
          ),
          Stream.filter((candidate) => candidate !== undefined),
          Stream.runHead,
          Effect.map(Option.getOrUndefined),
        );

        if (!insightRule?.Name) {
          return undefined;
        }

        const arn = yield* ruleArn(insightRule.Name);
        const tags = yield* readResourceTags(arn).pipe(
          Effect.catchTag("ResourceNotFoundException", () => Effect.succeed({})),
        );

        return {
          ruleName: insightRule.Name,
          ruleArn: arn,
          state: insightRule.State,
          insightRule,
          tags,
        };
      });

      return {
        stables: ["ruleName", "ruleArn"],
        diff: Effect.fn(function* ({ id, olds = {}, news = {} as Input<InsightRuleProps> }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createRuleName(id, olds);
          const newName = yield* createRuleName(id, news);

          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.ruleName ?? (yield* createRuleName(id, olds ?? {}));
          const state = yield* readInsightRule(name);
          if (!state) return undefined;
          return (yield* hasAlchemyTags(id, state.tags)) ? state : Unowned(state);
        }),
        reconcile: Effect.fn(function* ({ id, news, olds, output, session }) {
          // Observe — pin the physical name from `output` if present;
          // otherwise derive from desired props. Read whatever exists in
          // CloudWatch so we have a baseline for tag-diffing on adoption.
          const name = output?.ruleName ?? (yield* createRuleName(id, news));
          const existing = yield* readInsightRule(name);

          // Ensure — `putInsightRule` is an upsert; sending the full
          // desired config every reconcile converges the cloud.
          yield* retryConcurrent(
            cloudwatch.putInsightRule({
              ...toPutInsightRuleInput(news),
              RuleName: name,
            }),
          );

          // Sync tags — diff against `olds.tags` when we have prior state,
          // otherwise fall back to what we observed. Adoption flows take
          // the latter path.
          const tags = yield* updateResourceTags({
            id,
            resourceArn: yield* ruleArn(name),
            olds: olds?.tags ?? existing?.tags,
            news: news.tags,
          });

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

          const state = yield* readInsightRule(name);
          if (!state) {
            return yield* new InsightRuleUnexpectedResponse({
              message: `failed to read reconciled insight rule '${name}'`,
            });
          }

          return {
            ...state,
            tags,
          };
        }),
        list: () =>
          Effect.gen(function* () {
            // Enumerate every Contributor Insights rule in the account/region
            // by exhaustively paginating `describeInsightRules` (items live
            // under the `InsightRules` field). ARNs are reconstructed from the
            // ambient region/account since the API returns names only.
            const { accountId, region } = yield* AWSEnvironment.current;
            const rules = yield* cloudwatch.describeInsightRules.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) =>
                  (page.InsightRules ?? []).filter(
                    (
                      candidate,
                    ): candidate is typeof candidate & {
                      Name: string;
                    } =>
                      candidate.Name != null &&
                      // Rules owned by another service reject
                      // DeleteInsightRules with AccessDenied. DynamoDB
                      // Contributor Insights rules are the pathological case:
                      // they report `ManagedRule: false` yet still can only
                      // be removed through DynamoDB (verified live), so match
                      // both the flag and the documented name prefix. Keep
                      // them out of enumeration for account-wide teardown
                      // (nuke).
                      candidate.ManagedRule !== true &&
                      !candidate.Name.startsWith("DynamoDBContributorInsights-"),
                  ),
                ),
              ),
            );

            const attrs: InsightRule["Attributes"][] = yield* Effect.forEach(
              rules,
              (insightRule) => {
                const arn =
                  `arn:aws:cloudwatch:${region}:${accountId}:insight-rule/${insightRule.Name}` as InsightRuleArn;
                return readResourceTags(arn).pipe(
                  Effect.catchTag("ResourceNotFoundException", () => Effect.succeed({})),
                  Effect.map((tags) => ({
                    ruleName: insightRule.Name,
                    ruleArn: arn,
                    state: insightRule.State,
                    insightRule,
                    tags,
                  })),
                );
              },
              { concurrency: 10 },
            );
            return attrs;
          }),
        delete: Effect.fn(function* ({ output }) {
          const existing = yield* readInsightRule(output.ruleName);
          if (!existing) {
            return;
          }

          const response = yield* retryConcurrent(
            cloudwatch.deleteInsightRules({
              RuleNames: [output.ruleName],
            }),
          );

          if ((response.Failures?.length ?? 0) > 0) {
            return yield* new InsightRuleOperationFailed({
              message: `failed to delete insight rule '${output.ruleName}': ${failureMessage(response.Failures)}`,
            });
          }
        }),
      };
    }),
  );