sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ IVSChat/ Room.ts

import * as ivschat from "@distilled.cloud/aws/ivschat";
import { Unowned } from "alchemy/AdoptPolicy";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
  retryWhileHandlerPermissionPropagating,
  retryWhileThrottled,
  syncIvsChatTags,
  toTagRecord,
} from "./internal.ts";

export interface RoomMessageReviewHandler {
  /**
   * ARN of the Lambda function that reviews messages before they are
   * delivered to the room.
   */
  uri?: string;
  /**
   * What happens to a message if the review handler errors or times out:
   * `ALLOW` delivers it, `DENY` drops it.
   * @default "ALLOW"
   */
  fallbackResult?: "ALLOW" | "DENY";
}

/**
 * The binding contract of a room: the message review event source
 * (`IVSChat.onReviewMessage`) contributes the reviewing Lambda's ARN as the
 * room's `messageReviewHandler`, which the provider merges with
 * `props.messageReviewHandler` and syncs onto the room.
 */
export interface RoomBinding {
  /** Review handler injected by `IVSChat.onReviewMessage`. */
  messageReviewHandler?: RoomMessageReviewHandler;
}

export interface RoomProps {
  /**
   * Name of the room (not unique). If omitted, a deterministic physical
   * name is generated. Room names are mutable — changing the name
   * updates the room in place.
   */
  roomName?: string;
  /**
   * Maximum number of messages per second that can be sent to the room
   * (`1` - `10`).
   * @default 10
   */
  maximumMessageRatePerSecond?: number;
  /**
   * Maximum number of characters in a single message (`1` - `500`).
   * @default 500
   */
  maximumMessageLength?: number;
  /**
   * A Lambda-backed handler that reviews (and can modify or deny)
   * messages before delivery. Prefer wiring it through
   * `IVSChat.onReviewMessage` — the event source also creates the invoke
   * Permission and registers the runtime handler.
   * @default no review handler
   */
  messageReviewHandler?: RoomMessageReviewHandler;
  /**
   * ARNs or IDs of `LoggingConfiguration`s that record the room's chat
   * messages.
   */
  loggingConfigurationIdentifiers?: string[];
  /**
   * Tags to apply to the room. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface Room extends Resource<
  "AWS.IVSChat.Room",
  RoomProps,
  {
    /**
     * The room's physical name.
     */
    roomName: string;
    /**
     * ARN of the room.
     */
    roomArn: string;
    /**
     * Unique ID of the room.
     */
    roomId: string;
  },
  RoomBinding,
  Providers
> {}

/**
 * An Amazon IVS Chat room — a virtual space where chat participants
 * exchange messages over WebSocket connections.
 *
 * Clients connect with chat tokens minted at runtime via
 * `CreateChatToken`; message rate/length limits, a Lambda review handler,
 * and logging configurations are all managed on the room.
 * ### Creating Rooms
 * **Example:** Basic Room
 * ```typescript
 * import * as IVSChat from "@alchemy.run/aws/IVSChat";
 *
 * const room = yield* IVSChat.Room("LiveChat");
 * ```
 *
 * **Example:** Room with Message Limits
 * ```typescript
 * const room = yield* IVSChat.Room("LiveChat", {
 *   maximumMessageRatePerSecond: 5,
 *   maximumMessageLength: 200,
 * });
 * ```
 *
 * ### Logging
 * **Example:** Room with Chat Logging
 * ```typescript
 * const logging = yield* IVSChat.LoggingConfiguration("ChatLogs", {
 *   destinationConfiguration: {
 *     cloudWatchLogs: { logGroupName: logGroup.logGroupName },
 *   },
 * });
 * const room = yield* IVSChat.Room("LiveChat", {
 *   loggingConfigurationIdentifiers: [logging.loggingConfigurationArn],
 * });
 * ```
 *
 * ### Message Review
 * **Example:** Review Messages with a Lambda Handler
 * ```typescript
 * // inside a Lambda Function's effect — the handler reviews every message
 * // sent to the room before delivery (allow / modify / deny)
 * const room = yield* IVSChat.Room("LiveChat");
 * yield* IVSChat.onReviewMessage(room, (event) =>
 *   Effect.succeed(
 *     event.Content.includes("banned-word")
 *       ? { ReviewResult: "DENY", Attributes: { Reason: "moderated" } }
 *       : undefined,
 *   ),
 * );
 * // on the Function effect:
 * // .pipe(Effect.provide(Lambda.RoomMessageReviewEventSource))
 * ```
 *
 * @resource
 */
export const Room = Resource<Room>("AWS.IVSChat.Room");

/**
 * Raised when the IVS Chat API returns a room missing its ARN, ID, or
 * name.
 */
export class IvsChatRoomIncomplete extends Data.TaggedError("IvsChatRoomIncomplete")<{
  message: string;
}> {}

/**
 * Two different Lambda functions were registered as the same room's message
 * review handler — IVS Chat supports exactly one handler per room.
 */
export class ConflictingRoomMessageReviewHandler extends Data.TaggedError(
  "ConflictingRoomMessageReviewHandler",
)<{ readonly uris: readonly string[] }> {}

/**
 * The room's desired `messageReviewHandler`: `props.messageReviewHandler`
 * merged with the handler contributed through the binding contract
 * (`IVSChat.onReviewMessage`). Fails when two different handler URIs are
 * declared. Returns `undefined` when no handler is desired (which clears
 * any associated handler on update).
 */
const resolveMessageReviewHandler = Effect.fn(function* (
  news: RoomProps,
  bindings: ReadonlyArray<RoomBinding | { data?: RoomBinding }>,
) {
  const contributions = [
    news.messageReviewHandler,
    ...bindings.map(
      (binding) =>
        (binding as { data?: RoomBinding }).data?.messageReviewHandler ??
        (binding as RoomBinding).messageReviewHandler,
    ),
  ].filter((handler) => handler !== undefined);
  let resolved: RoomMessageReviewHandler | undefined;
  for (const handler of contributions) {
    if (resolved?.uri !== undefined && handler.uri !== undefined && resolved.uri !== handler.uri) {
      return yield* new ConflictingRoomMessageReviewHandler({
        uris: [resolved.uri, handler.uri],
      });
    }
    resolved = { ...resolved, ...handler };
  }
  return resolved;
});

type RoomState = {
  arn?: string | undefined;
  id?: string | undefined;
  name?: string | undefined;
  maximumMessageRatePerSecond?: number | undefined;
  maximumMessageLength?: number | undefined;
  messageReviewHandler?: ivschat.MessageReviewHandler | undefined;
  tags?: { [key: string]: string | undefined } | undefined;
  loggingConfigurationIdentifiers?: string[] | undefined;
};

export const RoomProvider = () =>
  Provider.effect(
    Room,
    Effect.gen(function* () {
      const toName = (id: string, props: RoomProps) =>
        props.roomName
          ? Effect.succeed(props.roomName)
          : createPhysicalName({ id, maxLength: 128 });

      const toAttrs = Effect.fn(function* (room: RoomState) {
        if (!room.arn || !room.id || !room.name) {
          return yield* new IvsChatRoomIncomplete({
            message: "IVS Chat room is missing its ARN, ID, or name",
          });
        }
        return {
          roomName: room.name,
          roomArn: room.arn,
          roomId: room.id,
        };
      });

      const getByIdentifier = Effect.fn(function* (identifier: string) {
        return yield* ivschat.getRoom({ identifier }).pipe(
          retryWhileThrottled,
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );
      });

      /** `ListRooms` filters by name server-side; match exactly. */
      const findByName = Effect.fn(function* (name: string) {
        const summaries = yield* ivschat.listRooms.pages({ name }).pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.rooms)),
          retryWhileThrottled,
        );
        const match = summaries.find((s) => s.name === name && s.arn);
        return match?.arn ? yield* getByIdentifier(match.arn) : undefined;
      });

      return {
        stables: ["roomArn", "roomId"],

        read: Effect.fn(function* ({ id, olds, output }) {
          const room = output?.roomArn
            ? yield* getByIdentifier(output.roomArn)
            : yield* findByName(yield* toName(id, olds ?? {}));
          if (room === undefined) return undefined;
          const attrs = yield* toAttrs(room);
          return (yield* hasAlchemyTags(id, toTagRecord(room.tags))) ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session, bindings }) {
          const name = yield* toName(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };
          const messageReviewHandler = yield* resolveMessageReviewHandler(news, bindings);

          // 1. Observe.
          let observed: RoomState | undefined = output?.roomArn
            ? yield* getByIdentifier(output.roomArn)
            : yield* findByName(name);

          // 2. Ensure — create if missing.
          if (observed === undefined) {
            observed = yield* ivschat
              .createRoom({
                name,
                maximumMessageRatePerSecond: news.maximumMessageRatePerSecond,
                maximumMessageLength: news.maximumMessageLength,
                messageReviewHandler,
                loggingConfigurationIdentifiers: news.loggingConfigurationIdentifiers,
                tags: desiredTags,
              })
              .pipe(retryWhileThrottled, retryWhileHandlerPermissionPropagating);
          }
          const arn = observed.arn;
          if (arn === undefined) {
            return yield* new IvsChatRoomIncomplete({
              message: "IVS Chat CreateRoom returned no room ARN",
            });
          }

          // 3. Sync — every room setting is mutable via UpdateRoom; apply
          // only the drifted fields.
          const patch: Partial<ivschat.UpdateRoomRequest> = {};
          if (observed.name !== name) patch.name = name;
          if (
            news.maximumMessageRatePerSecond !== undefined &&
            observed.maximumMessageRatePerSecond !== news.maximumMessageRatePerSecond
          ) {
            patch.maximumMessageRatePerSecond = news.maximumMessageRatePerSecond;
          }
          if (
            news.maximumMessageLength !== undefined &&
            observed.maximumMessageLength !== news.maximumMessageLength
          ) {
            patch.maximumMessageLength = news.maximumMessageLength;
          }
          // Handler sync: `uri: ""` disassociates, and the API defaults
          // fallbackResult to ALLOW — compare normalized values so a
          // no-handler desire converges from either direction.
          const observedHandlerUri = observed.messageReviewHandler?.uri ?? "";
          const desiredHandlerUri = messageReviewHandler?.uri ?? "";
          const observedFallback = observed.messageReviewHandler?.fallbackResult ?? "ALLOW";
          const desiredFallback = messageReviewHandler?.fallbackResult ?? "ALLOW";
          if (
            observedHandlerUri !== desiredHandlerUri ||
            (desiredHandlerUri !== "" && observedFallback !== desiredFallback)
          ) {
            patch.messageReviewHandler = messageReviewHandler ?? { uri: "" };
          }
          if (
            news.loggingConfigurationIdentifiers !== undefined &&
            JSON.stringify(observed.loggingConfigurationIdentifiers ?? []) !==
              JSON.stringify(news.loggingConfigurationIdentifiers)
          ) {
            patch.loggingConfigurationIdentifiers = news.loggingConfigurationIdentifiers;
          }
          if (Object.keys(patch).length > 0) {
            yield* ivschat
              .updateRoom({ identifier: arn, ...patch })
              .pipe(retryWhileThrottled, retryWhileHandlerPermissionPropagating);
          }

          // 3b. Sync tags — diff against OBSERVED cloud tags.
          yield* syncIvsChatTags(arn, desiredTags);

          // 4. Return fresh attributes.
          const final = yield* getByIdentifier(arn);
          if (final === undefined) {
            return yield* new IvsChatRoomIncomplete({
              message: `IVS Chat room '${arn}' vanished during reconcile`,
            });
          }
          yield* session.note(arn);
          return yield* toAttrs(final);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* ivschat.deleteRoom({ identifier: output.roomArn }).pipe(
            retryWhileThrottled,
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
          );
        }),

        list: () =>
          ivschat.listRooms.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.rooms)),
            Effect.flatMap(
              Effect.forEach(
                (summary) =>
                  toAttrs(summary).pipe(
                    // Tolerate a malformed/deleted summary — drop it.
                    Effect.catchTag("IvsChatRoomIncomplete", () => Effect.undefined),
                  ),
                { concurrency: 5 },
              ),
            ),
            Effect.map((items) => items.filter((item) => item !== undefined)),
          ),
      };
    }),
  );