sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ CloudTrail/ EventDataStore.ts

import * as cloudtrail from "@distilled.cloud/aws/cloudtrail";
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 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";

/**
 * A field selector inside an advanced event selector. Mirrors the
 * CloudTrail `AdvancedFieldSelector` wire shape.
 */
export interface EventDataStoreFieldSelector {
  /**
   * The event record field to select on (e.g. `eventCategory`,
   * `resources.type`).
   */
  field: string;
  /** Exact-match values. */
  equals?: string[];
  /** Prefix-match values. */
  startsWith?: string[];
  /** Suffix-match values. */
  endsWith?: string[];
  /** Exact-mismatch values. */
  notEquals?: string[];
  /** Prefix-mismatch values. */
  notStartsWith?: string[];
  /** Suffix-mismatch values. */
  notEndsWith?: string[];
}

/**
 * An advanced event selector controlling which events the event data
 * store collects.
 */
export interface EventDataStoreEventSelector {
  /** Descriptive name for the selector. */
  name?: string;
  /** Field selectors that events must match to be collected. */
  fieldSelectors: EventDataStoreFieldSelector[];
}

export interface EventDataStoreProps {
  /**
   * Name of the event data store. Must be 3-128 characters, contain only
   * letters, numbers, periods, underscores, and dashes, and start and end
   * with a letter or number. Renaming updates the store in place (the ARN
   * is the stable identity).
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * Advanced event selectors controlling which events are collected.
   * @default management events
   */
  advancedEventSelectors?: EventDataStoreEventSelector[];
  /**
   * Whether the event data store collects events from all Regions or
   * only the current Region.
   * @default true
   */
  multiRegionEnabled?: boolean;
  /**
   * Whether the event data store collects events for all accounts in an
   * organization.
   * @default false
   */
  organizationEnabled?: boolean;
  /**
   * Retention period, e.g. `"30 days"` or `Duration.days(30)` (minimum
   * 7 days; maximum 2557 days under `EXTENDABLE_RETENTION_PRICING`,
   * 3653 days under `FIXED_RETENTION_PRICING`). Rounded to whole days
   * on the wire.
   * @default 366 days
   */
  retentionPeriod?: Duration.Input;
  /**
   * Whether termination protection is enabled. A protected store cannot
   * be deleted until protection is disabled.
   * @default true (AWS default)
   */
  terminationProtectionEnabled?: boolean;
  /**
   * The billing mode for the event data store.
   * @default "EXTENDABLE_RETENTION_PRICING"
   */
  billingMode?: "EXTENDABLE_RETENTION_PRICING" | "FIXED_RETENTION_PRICING";
  /**
   * KMS key ID (ID, alias, or ARN) used to encrypt the events delivered
   * to the event data store.
   */
  kmsKeyId?: string;
  /**
   * Whether the event data store ingests live events. Synced via
   * `StartEventDataStoreIngestion` / `StopEventDataStoreIngestion`; a
   * stopped store keeps its collected events queryable.
   * @default true (AWS default)
   */
  ingestionEnabled?: boolean;
  /**
   * Tags to apply to the event data store. Merged with internal Alchemy
   * tags.
   */
  tags?: Record<string, string>;
}

export interface EventDataStore extends Resource<
  "AWS.CloudTrail.EventDataStore",
  EventDataStoreProps,
  {
    /** ARN of the event data store (its stable identity). */
    eventDataStoreArn: string;
    /** Name of the event data store. */
    name: string;
    /** Current status (e.g. `ENABLED`, `STARTING_INGESTION`). */
    status: string;
  },
  never,
  Providers
> {}

/**
 * A CloudTrail Lake event data store — an immutable collection of events
 * that can be queried with SQL via CloudTrail Lake.
 *
 * Deleting an event data store schedules it for deletion
 * (`PENDING_DELETION`); AWS purges it after a seven-day wait period during
 * which it incurs no cost. If a store with the same name is still pending
 * deletion, the reconciler restores it instead of creating a duplicate.
 * ### Creating Event Data Stores
 * **Example:** Basic Event Data Store
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const store = yield* AWS.CloudTrail.EventDataStore("Lake", {
 *   retentionPeriod: "7 days",
 *   terminationProtectionEnabled: false,
 * });
 * ```
 *
 * **Example:** Single-Region Store with Custom Selectors
 * ```typescript
 * const store = yield* AWS.CloudTrail.EventDataStore("S3DataEvents", {
 *   multiRegionEnabled: false,
 *   retentionPeriod: "30 days",
 *   terminationProtectionEnabled: false,
 *   advancedEventSelectors: [
 *     {
 *       name: "S3 data events",
 *       fieldSelectors: [
 *         { field: "eventCategory", equals: ["Data"] },
 *         { field: "resources.type", equals: ["AWS::S3::Object"] },
 *       ],
 *     },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const EventDataStore = Resource<EventDataStore>("AWS.CloudTrail.EventDataStore");

/**
 * A just-created or just-restored event data store transitions through
 * `CREATED`/`STARTING_INGESTION` before mutations are accepted; concurrent
 * mutations surface as transient `ConflictException` /
 * `InvalidEventDataStoreStatusException`.
 *
 * Expressed as an explicitly-typed helper: inlining `Effect.retry` in a
 * lifecycle op leaks `Retry.Return`'s conditional into declaration emit
 * and widens the provider layer to an `unknown` R for every consumer of
 * `AWS.providers()`.
 */
const retryWhileSettling = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) =>
      e._tag === "ConflictException" ||
      e._tag === "InvalidEventDataStoreStatusException" ||
      e._tag === "InactiveEventDataStoreException",
    schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
  });

/**
 * Deletion right after another mutation can raise a transient
 * `ConflictException`; already-inactive stores are handled by the caller
 * as success and must NOT be retried.
 */
const retryWhileDeleteConflict = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "ConflictException",
    schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
  });

const toWireSelectors = (
  selectors: EventDataStoreEventSelector[] | undefined,
): cloudtrail.AdvancedEventSelector[] | undefined =>
  selectors?.map((s) => ({
    Name: s.name,
    FieldSelectors: s.fieldSelectors.map((f) => ({
      Field: f.field,
      Equals: f.equals,
      StartsWith: f.startsWith,
      EndsWith: f.endsWith,
      NotEquals: f.notEquals,
      NotStartsWith: f.notStartsWith,
      NotEndsWith: f.notEndsWith,
    })),
  }));

export const EventDataStoreProvider = () =>
  Provider.effect(
    EventDataStore,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: { name?: string | undefined }) {
        if (props.name) {
          return props.name;
        }
        return yield* createPhysicalName({ id, maxLength: 128 });
      });

      const fetchObservedTags = (arn: string) =>
        cloudtrail.listTags({ ResourceIdList: [arn] }).pipe(
          Effect.map((r) => {
            const tags: Record<string, string> = {};
            for (const t of r.ResourceTagList?.[0]?.TagsList ?? []) {
              tags[t.Key] = t.Value ?? "";
            }
            return tags;
          }),
          Effect.orElseSucceed(() => ({}) as Record<string, string>),
        );

      // Look up a store by ARN, tolerating the typed not-found.
      const getByArn = (arn: string) =>
        cloudtrail
          .getEventDataStore({ EventDataStore: arn })
          .pipe(
            Effect.catchTag(
              ["EventDataStoreNotFoundException", "EventDataStoreARNInvalidException"],
              () => Effect.undefined,
            ),
          );

      // Find a store by name, INCLUDING pending-deletion ones — the caller
      // decides whether a `PENDING_DELETION` match should be restored.
      const findByName = (name: string) =>
        cloudtrail.listEventDataStores.pages({}).pipe(
          Stream.runCollect,
          Effect.map((chunk) =>
            Array.from(chunk)
              .flatMap((page) => page.EventDataStores ?? [])
              .find((s) => s.Name === name),
          ),
        );

      return EventDataStore.Provider.of({
        stables: ["eventDataStoreArn", "name"],
        list: () =>
          Effect.gen(function* () {
            const stores = yield* cloudtrail.listEventDataStores.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) => page.EventDataStores ?? []),
              ),
            );
            return stores
              .filter(
                (s) =>
                  s.EventDataStoreArn !== undefined &&
                  s.Name !== undefined &&
                  s.Status !== "PENDING_DELETION",
              )
              .map((s) => ({
                eventDataStoreArn: s.EventDataStoreArn!,
                name: s.Name!,
                status: s.Status ?? "ENABLED",
              }));
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const store = output?.eventDataStoreArn
            ? yield* getByArn(output.eventDataStoreArn)
            : yield* findByName(yield* createName(id, olds ?? {}));
          if (store === undefined || store.Status === "PENDING_DELETION") {
            return undefined;
          }
          const attrs = {
            eventDataStoreArn: store.EventDataStoreArn!,
            name: store.Name!,
            status: store.Status ?? "ENABLED",
          };
          const tags = yield* fetchObservedTags(attrs.eventDataStoreArn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ news }) {
          if (!isResolved(news)) return undefined;
          // Every prop (including the name) is mutable via
          // UpdateEventDataStore — the ARN is the stable identity, so no
          // prop change forces a replacement.
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = yield* createName(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredSelectors = toWireSelectors(news.advancedEventSelectors);
          // The CloudTrail wire unit for RetentionPeriod is whole days.
          const retentionDays = toWireDays(news.retentionPeriod);

          // 1. OBSERVE — prefer the cached ARN, fall back to name lookup.
          let store = output?.eventDataStoreArn
            ? yield* getByArn(output.eventDataStoreArn)
            : yield* findByName(name).pipe(
                Effect.flatMap((s) =>
                  s?.EventDataStoreArn ? getByArn(s.EventDataStoreArn) : Effect.undefined,
                ),
              );

          // A pending-deletion store still holds the name — restore it and
          // let the sync step converge it to the desired state.
          if (store !== undefined && store.Status === "PENDING_DELETION") {
            yield* session.note(`Restoring pending-deletion event data store ${store.Name}`);
            yield* retryWhileSettling(
              cloudtrail.restoreEventDataStore({
                EventDataStore: store.EventDataStoreArn!,
              }),
            );
            store = yield* getByArn(store.EventDataStoreArn!);
          }

          // 2. ENSURE — create if missing; on the AlreadyExists race (or a
          // same-name store pending deletion), converge via name lookup +
          // restore.
          if (store === undefined) {
            yield* session.note(`Creating event data store ${name}`);
            const created = yield* cloudtrail
              .createEventDataStore({
                Name: name,
                AdvancedEventSelectors: desiredSelectors,
                MultiRegionEnabled: news.multiRegionEnabled,
                OrganizationEnabled: news.organizationEnabled,
                RetentionPeriod: retentionDays,
                TerminationProtectionEnabled: news.terminationProtectionEnabled,
                BillingMode: news.billingMode,
                KmsKeyId: news.kmsKeyId,
                StartIngestion: news.ingestionEnabled,
                TagsList: Object.entries({
                  ...news.tags,
                  ...internalTags,
                }).map(([Key, Value]) => ({ Key, Value })),
              })
              .pipe(
                Effect.catchTag("EventDataStoreAlreadyExistsException", () => Effect.undefined),
              );
            if (created?.EventDataStoreArn) {
              store = yield* getByArn(created.EventDataStoreArn);
            } else {
              // AlreadyExists race — the holder may be active (peer created
              // it) or pending deletion (a prior stack run deleted it).
              const existing = yield* findByName(name);
              if (existing?.Status === "PENDING_DELETION") {
                yield* session.note(
                  `Name ${name} is held by a pending-deletion store — restoring it`,
                );
                yield* retryWhileSettling(
                  cloudtrail.restoreEventDataStore({
                    EventDataStore: existing.EventDataStoreArn!,
                  }),
                );
              }
              store = existing?.EventDataStoreArn
                ? yield* getByArn(existing.EventDataStoreArn)
                : undefined;
            }
          }
          if (store === undefined) {
            // Surface the typed not-found from a direct name-keyed get.
            store = yield* cloudtrail.getEventDataStore({
              EventDataStore: name,
            });
          }

          const arn = store.EventDataStoreArn!;

          // 3. SYNC — diff observed against desired, push only the delta.
          const updateDelta: Partial<
            Omit<cloudtrail.UpdateEventDataStoreRequest, "EventDataStore">
          > = {};
          if (store.Name !== name) {
            updateDelta.Name = name;
          }
          if (retentionDays !== undefined && store.RetentionPeriod !== retentionDays) {
            updateDelta.RetentionPeriod = retentionDays;
          }
          if (
            news.multiRegionEnabled !== undefined &&
            store.MultiRegionEnabled !== news.multiRegionEnabled
          ) {
            updateDelta.MultiRegionEnabled = news.multiRegionEnabled;
          }
          if (
            news.organizationEnabled !== undefined &&
            store.OrganizationEnabled !== news.organizationEnabled
          ) {
            updateDelta.OrganizationEnabled = news.organizationEnabled;
          }
          if (
            news.terminationProtectionEnabled !== undefined &&
            store.TerminationProtectionEnabled !== news.terminationProtectionEnabled
          ) {
            updateDelta.TerminationProtectionEnabled = news.terminationProtectionEnabled;
          }
          if (news.billingMode !== undefined && store.BillingMode !== news.billingMode) {
            updateDelta.BillingMode = news.billingMode;
          }
          if (news.kmsKeyId !== undefined && store.KmsKeyId !== news.kmsKeyId) {
            updateDelta.KmsKeyId = news.kmsKeyId;
          }
          if (
            desiredSelectors !== undefined &&
            JSON.stringify(store.AdvancedEventSelectors ?? []) !== JSON.stringify(desiredSelectors)
          ) {
            updateDelta.AdvancedEventSelectors = desiredSelectors;
          }
          if (Object.keys(updateDelta).length > 0) {
            yield* session.note(
              `Updating event data store: ${Object.keys(updateDelta).join(", ")}`,
            );
            store = yield* retryWhileSettling(
              cloudtrail.updateEventDataStore({
                EventDataStore: arn,
                ...updateDelta,
              }),
            );
          }

          // 3b. SYNC ingestion state — only when declared. The store's
          // Status is the observed ingestion state: ENABLED ingests,
          // STOPPED_INGESTION does not. retryWhileSettling rides out the
          // CREATED/STARTING_INGESTION window after create/restore.
          if (news.ingestionEnabled !== undefined) {
            const status = store.Status ?? "ENABLED";
            if (news.ingestionEnabled && status === "STOPPED_INGESTION") {
              yield* session.note(`Starting ingestion for ${name}`);
              yield* retryWhileSettling(
                cloudtrail.startEventDataStoreIngestion({
                  EventDataStore: arn,
                }),
              );
              store = (yield* getByArn(arn)) ?? store;
            } else if (!news.ingestionEnabled && status !== "STOPPED_INGESTION") {
              yield* session.note(`Stopping ingestion for ${name}`);
              yield* retryWhileSettling(
                cloudtrail.stopEventDataStoreIngestion({
                  EventDataStore: arn,
                }),
              );
              store = (yield* getByArn(arn)) ?? store;
            }
          }

          // 3c. SYNC tags against OBSERVED cloud tags (adoption-safe).
          const observedTags = yield* fetchObservedTags(arn);
          const { upsert, removed } = diffTags(observedTags, {
            ...news.tags,
            ...internalTags,
          });
          if (upsert.length > 0) {
            yield* cloudtrail.addTags({
              ResourceId: arn,
              TagsList: upsert.map((t) => ({ Key: t.Key, Value: t.Value })),
            });
          }
          if (removed.length > 0) {
            yield* cloudtrail.removeTags({
              ResourceId: arn,
              TagsList: removed.map((Key) => ({ Key })),
            });
          }

          yield* session.note(arn);
          return {
            eventDataStoreArn: arn,
            name: store.Name ?? name,
            status: store.Status ?? "ENABLED",
          };
        }),
        // DeleteEventDataStore schedules PENDING_DELETION (7-day window, no
        // cost). Idempotent: already-deleted (NotFound/ARNInvalid) and
        // already-pending (Inactive) stores are both success. A protected
        // store fails with the typed
        // `EventDataStoreTerminationProtectedException` — disable
        // `terminationProtectionEnabled` first.
        delete: Effect.fn(function* ({ output }) {
          yield* retryWhileDeleteConflict(
            cloudtrail.deleteEventDataStore({
              EventDataStore: output.eventDataStoreArn,
            }),
          ).pipe(
            Effect.catchTag(
              [
                "EventDataStoreNotFoundException",
                "EventDataStoreARNInvalidException",
                "InactiveEventDataStoreException",
              ],
              () => Effect.void,
            ),
          );
        }),
      });
    }),
  );