sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Notifications/ NotificationConfiguration.ts

import * as notifications from "@distilled.cloud/aws/notifications";
import { Unowned } from "alchemy/AdoptPolicy";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { hasAlchemyTags } from "alchemy/Tags";
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 { Providers } from "../Providers.ts";
import {
  pinNotificationsRegion,
  readNotificationsTags,
  syncNotificationsTags,
} from "./internal.ts";

/**
 * How long User Notifications aggregates events of the same kind into a
 * single notification before delivering it.
 */
export type AggregationDuration = "LONG" | "SHORT" | "NONE";

export interface NotificationConfigurationProps {
  /**
   * Name of the notification configuration. Must be unique in the account
   * (letters, numbers, underscores and hyphens). If omitted, a unique name
   * is generated from the app, stage and logical ID. The name can be
   * changed in place (no replacement).
   */
  name?: string;

  /**
   * Human-readable description of the configuration.
   * @default "Managed by Alchemy"
   */
  description?: string;

  /**
   * How long to aggregate matching events into a single notification:
   * `LONG` (12 hours), `SHORT` (5 minutes) or `NONE` (no aggregation).
   * @default "NONE"
   */
  aggregationDuration?: AggregationDuration;

  /**
   * User tags to attach to the configuration. Merged with internal
   * Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface NotificationConfiguration extends Resource<
  "AWS.Notifications.NotificationConfiguration",
  NotificationConfigurationProps,
  {
    /** The ARN of the notification configuration (regionless). */
    notificationConfigurationArn: string;
    /** The unique name of the configuration. */
    name: string;
    /** The description of the configuration. */
    description: string;
    /**
     * Current status: `ACTIVE`, `PARTIALLY_ACTIVE`, `INACTIVE` (no event
     * rules / channels associated yet) or `DELETING`.
     */
    status: string;
  },
  never,
  Providers
> {}

/**
 * An AWS User Notifications **notification configuration** — the container
 * that groups {@link EventRule}s (which events to notify on) and delivery
 * channels (where notifications go: Console bell, email contacts, chat).
 *
 * User Notifications is a global service managed from `us-east-1`; the
 * provider pins the control-plane region automatically, so the resource
 * works from a stack deployed in any region.
 *
 * ### Creating a Notification Configuration
 * **Example:** Basic configuration
 * ```typescript
 * import * as Notifications from "@alchemy.run/aws/Notifications";
 *
 * const config = yield* Notifications.NotificationConfiguration("Alerts", {
 *   description: "Deployment alerts",
 * });
 * ```
 *
 * **Example:** Aggregate duplicate events for 5 minutes
 * ```typescript
 * const config = yield* Notifications.NotificationConfiguration("Alerts", {
 *   description: "Deployment alerts",
 *   aggregationDuration: "SHORT",
 *   tags: { team: "platform" },
 * });
 * ```
 *
 * ### Adding Event Rules
 * **Example:** Notify on CloudWatch alarm state changes
 * ```typescript
 * const rule = yield* Notifications.EventRule("AlarmRule", {
 *   notificationConfigurationArn: config.notificationConfigurationArn,
 *   source: "aws.cloudwatch",
 *   eventType: "CloudWatch Alarm State Change",
 *   regions: ["us-west-2"],
 * });
 * ```
 *
 * @resource
 */
export const NotificationConfiguration = Resource<NotificationConfiguration>(
  "AWS.Notifications.NotificationConfiguration",
);

const DEFAULT_DESCRIPTION = "Managed by Alchemy";

/**
 * Retry a mutation while the service reports a transitional-lock
 * `ConflictException` (e.g. an event rule of this configuration is still
 * `DELETING`). Bounded (~40s). Explicitly typed so `Effect.retry`'s
 * conditional return type doesn't widen the provider layer in declaration
 * emit.
 */
const retryWhileConflict = <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("2 seconds"), Schedule.recurs(20)]),
  });

export const NotificationConfigurationProvider = () =>
  Provider.effect(
    NotificationConfiguration,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: NotificationConfigurationProps) {
        return props.name ?? (yield* createPhysicalName({ id }));
      });

      // Names are unique account-wide (CreateNotificationConfiguration
      // rejects duplicates with ConflictException), so a name scan is a
      // reliable identity fallback when the ARN cache is missing.
      const findByName = Effect.fn(function* (name: string) {
        return yield* pinNotificationsRegion(
          notifications.listNotificationConfigurations.items({}).pipe(
            Stream.filter((item) => item.name === name),
            Stream.runHead,
            Effect.map(Option.getOrUndefined),
          ),
        );
      });

      const getByArn = Effect.fn(function* (arn: string) {
        return yield* pinNotificationsRegion(
          notifications
            .getNotificationConfiguration({ arn })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined)),
        );
      });

      const toAttrs = (live: {
        arn: string;
        name: string;
        description: string;
        status: string;
      }) => ({
        notificationConfigurationArn: live.arn,
        name: live.name,
        description: live.description,
        status: live.status,
      });

      return NotificationConfiguration.Provider.of({
        stables: ["notificationConfigurationArn"],

        list: () =>
          pinNotificationsRegion(
            notifications.listNotificationConfigurations.items({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).map(toAttrs)),
            ),
          ),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.name ?? (yield* createName(id, olds ?? {}));
          const found = output?.notificationConfigurationArn
            ? yield* getByArn(output.notificationConfigurationArn)
            : yield* findByName(name);
          if (!found) return undefined;
          const attrs = toAttrs(found);
          const tags = yield* readNotificationsTags(found.arn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        // Everything (including the name) is mutable in place — no diff
        // needed; the engine's default update path always reconciles.

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const desiredName = yield* createName(id, news);
          const desiredDescription = news.description ?? DEFAULT_DESCRIPTION;

          // OBSERVE — cloud state is authoritative; the cached ARN falls
          // through to a name scan when it no longer resolves.
          let live = output?.notificationConfigurationArn
            ? yield* getByArn(output.notificationConfigurationArn)
            : yield* findByName(desiredName);

          // ENSURE — create when missing; ConflictException means a peer
          // created the same-named configuration concurrently → re-observe.
          if (live === undefined) {
            const created = yield* pinNotificationsRegion(
              notifications
                .createNotificationConfiguration({
                  name: desiredName,
                  description: desiredDescription,
                  aggregationDuration: news.aggregationDuration,
                  tags: news.tags,
                })
                .pipe(Effect.catchTag("ConflictException", () => Effect.undefined)),
            );
            live = created ? yield* getByArn(created.arn) : yield* findByName(desiredName);
          }
          const arn = live!.arn;

          // SYNC settings — diff observed name/description/aggregation
          // against desired and update only on change. An absent
          // aggregationDuration prop leaves the observed value untouched.
          const wantsAggregation = news.aggregationDuration;
          const aggregationDrifted =
            wantsAggregation !== undefined &&
            (live!.aggregationDuration ?? "NONE") !== wantsAggregation;
          if (
            live!.name !== desiredName ||
            live!.description !== desiredDescription ||
            aggregationDrifted
          ) {
            yield* pinNotificationsRegion(
              notifications.updateNotificationConfiguration({
                arn,
                name: desiredName,
                description: desiredDescription,
                ...(wantsAggregation !== undefined
                  ? { aggregationDuration: wantsAggregation }
                  : {}),
              }),
            );
          }

          // SYNC tags — against observed cloud tags (adoption-safe).
          yield* syncNotificationsTags(arn, id, news.tags);

          const fresh = yield* getByArn(arn);
          yield* session.note(arn);
          return toAttrs(fresh ?? live!);
        }),

        delete: Effect.fn(function* ({ output }) {
          // Idempotent — deleting also cascades any remaining event rules.
          // Retry the transitional lock (a rule still DELETING blocks the
          // configuration delete with a ConflictException).
          yield* notifications
            .deleteNotificationConfiguration({
              arn: output.notificationConfigurationArn,
            })
            .pipe(
              pinNotificationsRegion,
              retryWhileConflict,
              Effect.catchTag("ResourceNotFoundException", () => Effect.void),
            );
        }),
      });
    }),
  );