sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Logs/ LogGroup.ts

import * as logs from "@distilled.cloud/aws/cloudwatch-logs";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, tagRecord } from "alchemy/Tags";
import { toWireDays } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { AccountID } from "../Environment.ts";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";

export type LogGroupName = string;
export type LogGroupArn = `arn:aws:logs:${RegionID}:${AccountID}:log-group:${LogGroupName}`;
export type LogGroupClass = logs.LogGroupClass;

export interface LogGroupProps {
  /**
   * Name of the log group. If omitted, a unique name is generated.
   */
  logGroupName?: string;
  /**
   * How long CloudWatch retains log events. If omitted, logs are kept
   * indefinitely. Accepts any `Duration.Input` (e.g. `"7 days"`,
   * `Duration.days(7)`; a bare number is milliseconds); the wire unit is
   * whole days (`retentionInDays`) and must resolve to one of the retention
   * values CloudWatch accepts (1, 3, 5, 7, 14, 30, ...).
   */
  retention?: Duration.Input;
  /**
   * Optional KMS key identifier used to encrypt the log group.
   */
  kmsKeyId?: string;
  /**
   * Log class for the log group. Changing this value replaces the log group.
   * @default "STANDARD"
   */
  logGroupClass?: LogGroupClass;
  /**
   * Whether deletion protection is enabled for the log group.
   * @default false
   */
  deletionProtectionEnabled?: boolean;
  /**
   * User-defined tags to apply to the log group.
   */
  tags?: Record<string, string>;
}

export interface LogGroup extends Resource<
  "AWS.Logs.LogGroup",
  LogGroupProps,
  {
    logGroupName: LogGroupName;
    logGroupArn: LogGroupArn;
    retentionInDays?: number;
    kmsKeyId?: string;
    logGroupClass: LogGroupClass;
    deletionProtectionEnabled: boolean;
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * A CloudWatch Logs log group — the container for log streams and the unit
 * that retention, encryption, metric filters, and subscriptions attach to.
 * ### Creating Log Groups
 * **Example:** ECS Task Log Group
 * ```typescript
 * const logs = yield* LogGroup("TaskLogs", {
 *   retention: "7 days",
 * });
 * ```
 *
 * **Example:** Encrypted Log Group with Deletion Protection
 * ```typescript
 * const key = yield* AWS.KMS.Key("LogsKey");
 * const logs = yield* LogGroup("AuditLogs", {
 *   retention: "30 days",
 *   kmsKeyId: key.keyArn,
 *   deletionProtectionEnabled: true,
 * });
 * ```
 *
 * ### Writing Custom Log Events
 * Declare a `LogStream` and use the `PutLogEvents` binding inside a Lambda
 * function (or the batching `LogEventSink` for high-volume streams).
 *
 * **Example:** Custom Audit Trail from a Lambda Function
 * ```typescript
 * // init
 * const logGroup = yield* AWS.Logs.LogGroup("AuditLogs", {
 *   retention: "30 days",
 * });
 * const stream = yield* AWS.Logs.LogStream("AuditStream", {
 *   logGroupName: logGroup.logGroupName,
 *   logStreamName: "audit",
 * });
 * const putLogEvents = yield* AWS.Logs.PutLogEvents(logGroup);
 *
 * // runtime
 * yield* putLogEvents({
 *   logStreamName: "audit",
 *   logEvents: [{ timestamp, message: "user.login id=123" }],
 * });
 * ```
 *
 * ### Consuming Log Events
 * **Example:** React to Error Logs
 * ```typescript
 * // Subscribe a Lambda handler to matching events (creates the
 * // subscription filter + invoke permission automatically).
 * yield* AWS.Logs.consumeLogEvents(
 *   logGroup,
 *   { filterPattern: "?ERROR ?Error" },
 *   (events) =>
 *     Stream.runForEach(events, (event) =>
 *       Effect.log(`${event.logStream}: ${event.message}`),
 *     ),
 * );
 * ```
 *
 * ### Metrics
 * **Example:** Count Errors with a Metric Filter
 * ```typescript
 * yield* AWS.Logs.MetricFilter("ErrorCount", {
 *   logGroupName: logGroup.logGroupName,
 *   filterPattern: '"ERROR"',
 *   metricTransformations: [{
 *     metricName: "ErrorCount",
 *     metricNamespace: "MyApp",
 *     metricValue: "1",
 *   }],
 * });
 * ```
 *
 * @resource
 */
export const LogGroup = Resource<LogGroup>("AWS.Logs.LogGroup");

export const LogGroupProvider = () =>
  Provider.effect(
    LogGroup,
    Effect.gen(function* () {
      const toLogGroupName = (id: string, props: { logGroupName?: string } = {}) =>
        props.logGroupName
          ? Effect.succeed(props.logGroupName)
          : createPhysicalName({ id, maxLength: 512 });
      const toLogGroupClass = (props: { logGroupClass?: LogGroupClass } = {}): LogGroupClass =>
        props.logGroupClass ?? "STANDARD";
      // describeLogGroups returns ARNs with a trailing `:*` while reconcile
      // constructs them without — normalize so refresh/adoption never reports
      // phantom drift and interpolated IAM ARNs (`${arn}:*`) stay correct.
      const normalizeLogGroupArn = (arn: string): LogGroupArn =>
        (arn.endsWith(":*") ? arn.slice(0, -2) : arn) as LogGroupArn;
      const observe = Effect.fn(function* (logGroupName: string) {
        return yield* logs.describeLogGroups.items({ logGroupNamePrefix: logGroupName }).pipe(
          Stream.filter((group) => group.logGroupName === logGroupName),
          Stream.runHead,
          Effect.map(Option.getOrUndefined),
        );
      });

      return {
        stables: ["logGroupArn", "logGroupName"],
        // AWS account/region collection: paginate `describeLogGroups`
        // exhaustively, then hydrate each group's tags via
        // `listTagsForResource` (bounded concurrency) into the exact `read`
        // Attributes shape.
        list: () =>
          Effect.gen(function* () {
            const { accountId, region } = yield* AWSEnvironment.current;
            const groups = yield* logs.describeLogGroups.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.logGroups ?? [])),
            );

            return yield* Effect.forEach(
              groups.filter(
                (
                  group,
                ): group is logs.LogGroup & {
                  logGroupName: string;
                  arn: string;
                } => group.logGroupName != null && group.arn != null,
              ),
              (group) =>
                Effect.gen(function* () {
                  const tagArn =
                    `arn:aws:logs:${region}:${accountId}:log-group:${group.logGroupName}` as LogGroupArn;
                  const tags = yield* logs.listTagsForResource({ resourceArn: tagArn }).pipe(
                    Effect.map((r): Record<string, string> =>
                      Object.fromEntries(
                        Object.entries(r.tags ?? {}).filter(
                          (entry): entry is [string, string] => typeof entry[1] === "string",
                        ),
                      ),
                    ),
                    Effect.catchTag("ResourceNotFoundException", () =>
                      Effect.succeed({} as Record<string, string>),
                    ),
                  );
                  return {
                    logGroupName: group.logGroupName,
                    logGroupArn: normalizeLogGroupArn(group.arn),
                    retentionInDays: group.retentionInDays,
                    kmsKeyId: group.kmsKeyId,
                    logGroupClass: group.logGroupClass ?? "STANDARD",
                    deletionProtectionEnabled: group.deletionProtectionEnabled ?? false,
                    tags,
                  };
                }),
              { concurrency: 10 },
            );
          }),
        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return;
          if ((yield* toLogGroupName(id, olds ?? {})) !== (yield* toLogGroupName(id, news ?? {}))) {
            return { action: "replace" } as const;
          }
          if (toLogGroupClass(olds ?? {}) !== toLogGroupClass(news ?? {})) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const logGroupName = output?.logGroupName ?? (yield* toLogGroupName(id, olds ?? {}));
          const match = yield* observe(logGroupName);
          if (!match?.arn) {
            return undefined;
          }
          return {
            logGroupName,
            logGroupArn: normalizeLogGroupArn(match.arn),
            retentionInDays: match.retentionInDays,
            kmsKeyId: match.kmsKeyId,
            logGroupClass: match.logGroupClass ?? "STANDARD",
            deletionProtectionEnabled: match.deletionProtectionEnabled ?? false,
            tags: yield* logs
              .listTagsForResource({ resourceArn: normalizeLogGroupArn(match.arn) })
              .pipe(
                Effect.map((r) => tagRecord(r.tags)),
                Effect.catchTag("ResourceNotFoundException", () =>
                  Effect.succeed({} as Record<string, string>),
                ),
              ),
          };
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const logGroupName = output?.logGroupName ?? (yield* toLogGroupName(id, news));
          // `output.logGroupArn` may be state written by an older provider
          // version (or anything else) that persisted `describeLogGroups`'
          // trailing `:*` form — normalize before it reaches the tagging
          // APIs, which reject that suffix with "Invalid resourceArn".
          const arn = normalizeLogGroupArn(
            (output?.logGroupArn ??
              `arn:aws:logs:${region}:${accountId}:log-group:${logGroupName}`) as LogGroupArn,
          );
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };
          // Wire unit is whole days (retentionInDays).
          const desiredRetention = toWireDays(news.retention);

          // Observe - fetch live state. `describeLogGroups` returns
          // retention/kms info so we can diff against desired without
          // trusting `olds` or `output`.
          let observed = yield* observe(logGroupName);

          // Ensure - create if missing. `createLogGroup` accepts tags and
          // kmsKeyId on first create; tolerate `ResourceAlreadyExistsException`
          // (race with peer reconciler) and re-read.
          if (!observed?.arn) {
            yield* logs
              .createLogGroup({
                logGroupName,
                kmsKeyId: news.kmsKeyId,
                tags: desiredTags,
                logGroupClass: news.logGroupClass,
                deletionProtectionEnabled: news.deletionProtectionEnabled,
              })
              .pipe(Effect.catchTag("ResourceAlreadyExistsException", () => Effect.void));
            observed = yield* observe(logGroupName);
          }

          // Sync KMS key - create accepts kmsKeyId, but updates require the
          // association API. Disassociating only affects newly ingested events.
          const observedKmsKeyId = observed?.kmsKeyId;
          if (news.kmsKeyId !== observedKmsKeyId) {
            if (news.kmsKeyId === undefined) {
              if (observedKmsKeyId !== undefined) {
                yield* logs
                  .disassociateKmsKey({ logGroupName })
                  .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
              }
            } else {
              yield* logs.associateKmsKey({
                logGroupName,
                kmsKeyId: news.kmsKeyId,
              });
            }
          }

          // Sync deletion protection - destroy disables it before deletion, but
          // normal deploys should still converge the live flag to desired state.
          const desiredDeletionProtection = news.deletionProtectionEnabled ?? false;
          const observedDeletionProtection = observed?.deletionProtectionEnabled ?? false;
          if (desiredDeletionProtection !== observedDeletionProtection) {
            yield* logs.putLogGroupDeletionProtection({
              logGroupIdentifier: logGroupName,
              deletionProtectionEnabled: desiredDeletionProtection,
            });
          }

          // Sync retention - observed to desired.
          const observedRetention = observed?.retentionInDays;
          if (desiredRetention !== observedRetention) {
            if (desiredRetention === undefined) {
              yield* logs
                .deleteRetentionPolicy({
                  logGroupName,
                })
                .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
            } else {
              yield* logs.putRetentionPolicy({
                logGroupName,
                retentionInDays: desiredRetention,
              });
            }
          }

          // Sync tags - list observed tags then diff against desired so
          // adoption rewrites ownership tags correctly.
          const observedTags = yield* logs.listTagsForResource({ resourceArn: arn }).pipe(
            Effect.map((r): Record<string, string> =>
              Object.fromEntries(
                Object.entries(r.tags ?? {}).filter(
                  (entry): entry is [string, string] => typeof entry[1] === "string",
                ),
              ),
            ),
            Effect.orElseSucceed(() => ({}) as Record<string, string>),
          );
          const { removed, upsert } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* logs.tagResource({
              resourceArn: arn,
              tags: Object.fromEntries(upsert.map((tag) => [tag.Key, tag.Value])),
            });
          }
          if (removed.length > 0) {
            yield* logs.untagResource({
              resourceArn: arn,
              tagKeys: removed,
            });
          }

          yield* session.note(arn);

          return {
            logGroupName,
            logGroupArn: arn,
            retentionInDays: desiredRetention,
            kmsKeyId: news.kmsKeyId,
            logGroupClass: observed?.logGroupClass ?? toLogGroupClass(news),
            deletionProtectionEnabled: desiredDeletionProtection,
            tags: desiredTags,
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* logs
            .putLogGroupDeletionProtection({
              logGroupIdentifier: output.logGroupName,
              deletionProtectionEnabled: false,
            })
            .pipe(
              Effect.retry({
                while: (error) =>
                  error._tag === "OperationAbortedException" ||
                  error._tag === "ServiceUnavailableException",
                schedule: Schedule.exponential(100),
                times: 8,
              }),
              Effect.catchTag("ResourceNotFoundException", () => Effect.void),
            );
          yield* logs
            .deleteLogGroup({
              logGroupName: output.logGroupName,
            })
            .pipe(
              Effect.retry({
                while: (error) =>
                  error._tag === "OperationAbortedException" ||
                  error._tag === "ServiceUnavailableException",
                schedule: Schedule.exponential(100),
                times: 8,
              }),
              Effect.catchTag("ResourceNotFoundException", () => Effect.void),
            );

          const remaining = yield* Effect.repeat(
            logs.describeLogGroups.items({ logGroupNamePrefix: output.logGroupName }).pipe(
              Stream.filter((group) => group.logGroupName === output.logGroupName),
              Stream.runHead,
              Effect.map(Option.isSome),
            ),
            {
              schedule: Schedule.fixed("250 millis"),
              until: (present) => !present,
              times: 20,
            },
          );
          if (remaining) {
            return yield* Effect.die(
              new Error(
                `CloudWatch log group ${output.logGroupName} remained observable after delete`,
              ),
            );
          }
        }),
      };
    }),
  );