sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SNS/ Topic.ts

import * as sns from "@distilled.cloud/aws/sns";
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 * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Stream from "effect/Stream";
import type { AccountID } from "../Environment.ts";
import { normalizePolicyDocument } from "../IAM/Policy.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";

export type TopicName = string;
export type TopicArn = `arn:aws:sns:${RegionID}:${AccountID}:${TopicName}`;

export interface TopicProps {
  /**
   * Name of the topic.
   * @default ${app}-${stage}-${id}?.fifo
   */
  topicName?: string;
  /**
   * Whether to create a FIFO topic.
   * @default false
   */
  fifo?: boolean;
  /**
   * Raw SNS topic attributes keyed by AWS attribute name.
   * Use this for delivery policies, tracing, KMS, signatures, archive policy, and
   * other SNS topic attributes not modeled as first-class props.
   */
  attributes?: Record<string, string>;
  /**
   * SNS data protection policy JSON for the topic.
   *
   * TODO(sam): should this be a typed object that we serialize/deserialize?
   */
  dataProtectionPolicy?: string;
  /**
   * User-defined tags to apply to the topic.
   */
  tags?: Record<string, string>;
}

export interface Topic extends Resource<
  "AWS.SNS.Topic",
  TopicProps,
  {
    topicArn: TopicArn;
    topicName: TopicName;
    fifo: boolean;
    attributes: Record<string, string>;
    dataProtectionPolicy: string | undefined;
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon SNS topic for fan-out messaging and notifications.
 *
 * `Topic` owns the SNS topic lifecycle while raw AWS topic attributes remain
 * available through the `attributes` prop so the full core pub/sub surface can
 * be configured without waiting on additional typed wrappers. A topic name is
 * auto-generated unless you provide one explicitly.
 * ### Creating Topics
 * **Example:** Standard Topic
 * ```typescript
 * import * as SNS from "@alchemy.run/aws/SNS";
 *
 * const topic = yield* SNS.Topic("OrdersTopic");
 * ```
 *
 * **Example:** Topic with Display Name
 * ```typescript
 * const topic = yield* SNS.Topic("NotificationsTopic", {
 *   attributes: {
 *     DisplayName: "App Notifications",
 *   },
 * });
 * ```
 *
 * **Example:** FIFO Topic
 * ```typescript
 * const topic = yield* SNS.Topic("OrdersFifoTopic", {
 *   fifo: true,
 *   attributes: {
 *     ContentBasedDeduplication: "true",
 *   },
 * });
 * ```
 *
 * ### Runtime Publishing
 * Bind publish operations in the init phase and use them in runtime
 * handlers.
 *
 * **Example:** Publish from a handler
 * ```typescript
 * // init
 * const publish = yield* SNS.Publish(topic);
 *
 * return {
 *   fetch: Effect.gen(function* () {
 *     // runtime
 *     yield* publish({
 *       Message: JSON.stringify({ orderId: "123" }),
 *       Subject: "OrderCreated",
 *     });
 *     return HttpServerResponse.text("Published");
 *   }),
 * };
 * ```
 *
 * ### Subscriptions
 * Subscribe a Lambda function to process messages published to the
 * topic. The subscription and invoke permissions are created
 * automatically.
 *
 * **Example:** Process topic notifications
 * ```typescript
 * // init
 * yield* SNS.consumeTopicNotifications(topic, (stream) =>
 *   stream.pipe(
 *     Stream.runForEach((message) =>
 *       Effect.log(`Received: ${message.Message}`),
 *     ),
 *   ),
 * );
 * ```
 *
 * @resource
 */
export const Topic = Resource<Topic>("AWS.SNS.Topic");

export const TopicProvider = () =>
  Provider.succeed(Topic, {
    // AWS account/region collection: `listTopics` enumerates every topic ARN
    // in the ambient account+region (paginated, ARN-only), then each ARN is
    // hydrated via `readTopic` into the exact `read` Attributes shape
    // (attributes + tags + data protection policy). Per-item not-found is
    // handled inside `readTopic` (returns undefined) for topics deleted
    // between enumeration and hydration.
    list: Effect.fn(function* () {
      const topicArns = yield* sns.listTopics.pages({}).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.Topics ?? [])
              .map((topic) => topic.TopicArn)
              .filter((arn): arn is string => typeof arn === "string"),
          ),
        ),
      );

      const rows = yield* Effect.forEach(
        topicArns,
        (topicArn) =>
          readTopic({
            id: "",
            topicArn,
            topicName: topicArn.split(":").at(-1) ?? topicArn,
          }),
        { concurrency: 10 },
      );

      return rows.filter((row): row is NonNullable<typeof row> => row !== undefined);
    }),
    read: Effect.fn(function* ({ id, olds, output }) {
      const topicName = output?.topicName ?? (yield* toTopicName(id, olds ?? {}));

      const state = yield* readTopic({
        id,
        topicArn: output?.topicArn,
        topicName,
      });
      if (!state) return undefined;
      // Reconcile manages (and returns) only the declared attributes; SNS
      // also reports server-filled ones (`Policy`, `Owner`, subscription
      // counters). Project onto the declared keys so an untouched topic
      // does not read as drifted, keeping the persisted value wherever SNS
      // returns an equivalent JSON document in its own form.
      const declared = olds ? toAttributes(olds) : undefined;
      const attrs = {
        ...state,
        attributes: declared
          ? Object.fromEntries(
              Object.entries(declared).flatMap(([name, value]) => {
                const observed = state.attributes[name];
                return observed === undefined
                  ? []
                  : [[name, sameDocument(value, observed) ? value : observed]];
              }),
            )
          : state.attributes,
        dataProtectionPolicy:
          output?.dataProtectionPolicy !== undefined &&
          state.dataProtectionPolicy !== undefined &&
          sameDocument(output.dataProtectionPolicy, state.dataProtectionPolicy)
            ? output.dataProtectionPolicy
            : state.dataProtectionPolicy,
      };
      return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
    }),
    stables: ["topicArn", "topicName", "fifo"],
    diff: Effect.fn(function* ({ id, news = {}, olds = {} }) {
      if (!isResolved(news)) return undefined;
      if ((news.fifo ?? false) !== (olds.fifo ?? false)) {
        return { action: "replace" } as const;
      }

      const oldTopicName = yield* toTopicName(id, olds);
      const newTopicName = yield* toTopicName(id, news);

      if (oldTopicName !== newTopicName) {
        return { action: "replace" } as const;
      }

      if (olds.dataProtectionPolicy !== undefined && news.dataProtectionPolicy === undefined) {
        return { action: "replace" } as const;
      }
    }),
    reconcile: Effect.fn(function* ({ id, news = {}, olds, session }) {
      const topicName = yield* toTopicName(id, news);
      const internalTags = yield* createInternalTags(id);
      const desiredTags = { ...internalTags, ...news.tags };
      const desiredAttributes = toAttributes(news);
      const isFifo = news.fifo ?? false;

      // Observe + ensure — `createTopic` is idempotent for an identical
      // (name, FifoTopic) pair, so we use it both to ensure-on-greenfield
      // and to fetch the ARN for adoption. We deliberately pass ONLY the
      // FifoTopic attribute (which is stable at create time): AWS rejects
      // createTopic for an existing topic if any other attribute, tag,
      // or DataProtectionPolicy differs from what's already attached.
      // Mutable attributes are reconciled below against observed state.
      const createResponse = yield* sns.createTopic({
        Name: topicName,
        Attributes: isFifo ? { FifoTopic: "true" } : undefined,
      });
      const topicArn = createResponse.TopicArn;
      if (!topicArn) {
        return yield* Effect.die(new Error(`createTopic returned no ARN`));
      }

      // Sync attributes — fetch observed cloud attributes and apply only
      // the delta.
      const observedState = yield* sns
        .getTopicAttributes({ TopicArn: topicArn })
        .pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
      const observedAttributes = toAttributeMap(observedState?.Attributes);

      for (const [name, value] of Object.entries(desiredAttributes)) {
        if (observedAttributes[name] !== value) {
          yield* sns.setTopicAttributes({
            TopicArn: topicArn,
            AttributeName: name,
            AttributeValue: value,
          });
        }
      }

      // Reset previously-user-specified attributes that the user no
      // longer specifies. Use `olds.attributes` (the prior props) — NOT
      // `output.attributes`, which on adoption holds every attribute SNS
      // returns and would erroneously try to reset SNS-managed values
      // like the auto-generated Policy.
      const previouslyManaged = olds?.attributes ?? {};
      for (const name of Object.keys(previouslyManaged)) {
        if (!(name in desiredAttributes) && name !== "FifoTopic") {
          yield* sns.setTopicAttributes({
            TopicArn: topicArn,
            AttributeName: name,
          });
        }
      }

      // Sync tags — diff observed cloud tags against desired so that an
      // adoption-takeover (cloud tags identify a different logical id)
      // correctly rewrites ownership tags.
      const observedTagsResp = yield* sns
        .listTagsForResource({ ResourceArn: topicArn })
        .pipe(
          Effect.catchTag("ResourceNotFoundException", () =>
            Effect.succeed({ Tags: [] as sns.Tag[] }),
          ),
        );
      const observedTags = toTagMap(observedTagsResp.Tags);
      const { removed, upsert } = diffTags(observedTags, desiredTags);

      if (upsert.length > 0) {
        yield* sns.tagResource({
          ResourceArn: topicArn,
          Tags: upsert,
        });
      }

      if (removed.length > 0) {
        yield* sns.untagResource({
          ResourceArn: topicArn,
          TagKeys: removed,
        });
      }

      // Sync data protection policy — observed ↔ desired. SNS rejects
      // getDataProtectionPolicy on FIFO topics, so we skip it there.
      let observedPolicy: string | undefined;
      if (!isFifo) {
        observedPolicy = yield* sns.getDataProtectionPolicy({ ResourceArn: topicArn }).pipe(
          Effect.map((r) => r.DataProtectionPolicy),
          Effect.catchTags({
            NotFoundException: () => Effect.undefined,
            InvalidParameterException: () => Effect.undefined,
          }),
        );
      }
      if (
        !isFifo &&
        news.dataProtectionPolicy !== undefined &&
        news.dataProtectionPolicy !== observedPolicy
      ) {
        yield* sns.putDataProtectionPolicy({
          ResourceArn: topicArn,
          DataProtectionPolicy: news.dataProtectionPolicy,
        });
      }

      yield* session.note(topicArn);

      return {
        topicArn: topicArn as TopicArn,
        topicName,
        fifo: isFifo,
        attributes: desiredAttributes,
        dataProtectionPolicy: news.dataProtectionPolicy ?? observedPolicy,
        tags: desiredTags,
      };
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* sns
        .deleteTopic({
          TopicArn: output.topicArn,
        })
        .pipe(
          Effect.catchTags({
            NotFoundException: () => Effect.void,
            InvalidParameterException: () => Effect.void,
          }),
        );
    }),
  });

const toTopicName = Effect.fn(function* (id: string, props: TopicProps) {
  if (props.topicName) {
    return props.topicName;
  }

  const baseName = yield* createPhysicalName({
    id,
    maxLength: props.fifo ? 256 - ".fifo".length : 256,
  });

  return props.fifo ? `${baseName}.fifo` : baseName;
});

const toAttributes = (props: TopicProps): Record<string, string> => ({
  ...props.attributes,
  ...(props.fifo ? { FifoTopic: "true" } : undefined),
});

// Whether two attribute values mean the same: equal strings, or JSON
// documents (policies) that differ only in SNS's formatting.
const sameDocument = (a: string, b: string) =>
  a === b || normalizePolicyDocument(a) === normalizePolicyDocument(b);

const toTagMap = (tags: sns.Tag[] | undefined): Record<string, string> =>
  Object.fromEntries(
    (tags ?? [])
      .filter(
        (tag): tag is Required<Pick<sns.Tag, "Key" | "Value">> =>
          typeof tag.Key === "string" && typeof tag.Value === "string",
      )
      .map((tag) => [tag.Key, tag.Value]),
  );

const toAttributeMap = (
  attributes: Record<string, string | undefined> | undefined,
): Record<string, string> =>
  Object.fromEntries(
    Object.entries(attributes ?? {}).filter(
      (entry): entry is [string, string] => typeof entry[1] === "string",
    ),
  );

const findTopicArnByName = Effect.fn(function* (topicName: string) {
  const match = yield* sns.listTopics.items({}).pipe(
    Stream.filter((topic) => topic.TopicArn?.split(":").at(-1) === topicName),
    Stream.runHead,
    Effect.map(Option.getOrUndefined),
  );
  return match?.TopicArn;
});

const readTopic = Effect.fn(function* ({
  topicArn,
  topicName,
}: {
  id: string;
  topicArn?: string;
  topicName: string;
}) {
  const resolvedTopicArn = topicArn ?? (yield* findTopicArnByName(topicName));

  if (!resolvedTopicArn) {
    return undefined;
  }

  const topicState = yield* Effect.all(
    [
      sns.getTopicAttributes({
        TopicArn: resolvedTopicArn,
      }),
      sns.listTagsForResource({
        ResourceArn: resolvedTopicArn,
      }),
      sns
        .getDataProtectionPolicy({
          ResourceArn: resolvedTopicArn,
        })
        .pipe(
          Effect.map((response) => response.DataProtectionPolicy),
          Effect.catchTag(
            ["NotFoundException", "FifoTopicDataProtectionUnsupported"],
            () => Effect.undefined,
          ),
        ),
    ],
    { concurrency: "unbounded" },
  ).pipe(
    Effect.catchTags({
      NotFoundException: () => Effect.undefined,
      InvalidParameterException: () => Effect.undefined,
    }),
    // `list()` hydrates every topic in the account, so a topic deleted by a
    // parallel test between enumeration and hydration surfaces here —
    // `listTagsForResource` reports it as `ResourceNotFoundException`. Treat a
    // vanished topic as "not present" rather than failing the whole listing.
    Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
  );

  if (!topicState) {
    return undefined;
  }

  const [attributes, tags, dataProtectionPolicy] = topicState;

  const topicAttributes = toAttributeMap(attributes.Attributes);

  const apiTags = toTagMap(tags.Tags);
  return {
    topicArn: resolvedTopicArn as TopicArn,
    topicName: topicAttributes.TopicArn?.split(":").at(-1) ?? topicName,
    fifo: topicAttributes.FifoTopic === "true",
    attributes: topicAttributes,
    dataProtectionPolicy,
    tags: apiTags,
  };
});