sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ KinesisVideo/ Stream.ts

import * as kv from "@distilled.cloud/aws/kinesis-video";
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 { toWireHours } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Stream_ from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
  compactTags,
  retryWhileResourceInUse,
  retryWhileSettling,
  waitForStreamActive,
  waitForStreamGone,
} from "./internal.ts";

export interface StreamProps {
  /**
   * Name of the video stream. Changing the name replaces the stream.
   * Must be unique per account and region.
   * @default a generated physical name
   */
  streamName?: string;
  /**
   * Name of the device that writes to the stream. Kinesis Video Streams
   * does not currently use this name, but it is stored with the stream
   * metadata and can be updated in place.
   */
  deviceName?: string;
  /**
   * Media type of the stream as a MIME type (e.g. `video/h264`). Consumers
   * can use it to determine how to process the stream. Updated in place.
   */
  mediaType?: string;
  /**
   * The ID (or alias/ARN) of the KMS key used to encrypt stream data.
   * Changing the key replaces the stream.
   * @default the AWS-managed `aws/kinesisvideo` key
   */
  kmsKeyId?: string;
  /**
   * How long stream data is retained. Zero duration means no retention —
   * data is only available live. Accepts any `Duration.Input` (e.g.
   * `"24 hours"`, `Duration.hours(24)`; a bare number is milliseconds); the
   * wire unit is whole hours. Adjusted in place via `UpdateDataRetention`.
   * @default 0
   */
  dataRetention?: Duration.Input;
  /**
   * Tags to apply to the stream. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface Stream extends Resource<
  "AWS.KinesisVideo.Stream",
  StreamProps,
  {
    streamName: string;
    streamArn: string;
  },
  {},
  Providers
> {}

/**
 * An Amazon Kinesis Video Stream for ingesting, storing, and consuming
 * live video.
 *
 * Stream creation is asynchronous — the provider waits (bounded) for the
 * stream to become `ACTIVE` before returning. `deviceName` and `mediaType`
 * are updated in place; `dataRetention` converges via `UpdateDataRetention`;
 * changing `streamName` or `kmsKeyId` replaces the stream.
 * ### Creating Streams
 * **Example:** Basic Video Stream
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const stream = yield* AWS.KinesisVideo.Stream("Camera");
 * ```
 *
 * **Example:** Stream with Retention and Media Type
 * ```typescript
 * const stream = yield* AWS.KinesisVideo.Stream("Camera", {
 *   mediaType: "video/h264",
 *   dataRetention: "24 hours",
 *   tags: { Environment: "production" },
 * });
 * ```
 *
 * ### Reading Media
 * Bind data-plane read operations in the init phase and use them in
 * runtime handlers. The bindings resolve the per-stream data endpoint
 * (`GetDataEndpoint`) automatically.
 *
 * **Example:** HLS Playback URL
 * ```typescript
 * // init
 * const getHls = yield* AWS.KinesisVideo.GetHLSStreamingSessionURL(stream);
 *
 * // runtime
 * const { HLSStreamingSessionURL } = yield* getHls({ PlaybackMode: "LIVE" });
 * ```
 *
 * **Example:** Raw Media
 * ```typescript
 * // init
 * const getMedia = yield* AWS.KinesisVideo.GetMedia(stream);
 *
 * // runtime
 * const media = yield* getMedia({
 *   StartSelector: { StartSelectorType: "EARLIEST" },
 * });
 * ```
 *
 * @resource
 */
export const Stream = Resource<Stream>("AWS.KinesisVideo.Stream");

export const StreamProvider = () =>
  Provider.effect(
    Stream,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: { streamName?: string | undefined },
      ) {
        return props.streamName ?? (yield* createPhysicalName({ id, maxLength: 256 }));
      });

      const observeStream = Effect.fn(function* (streamName: string) {
        return yield* kv.describeStream({ StreamName: streamName }).pipe(
          Effect.map((r) => r.StreamInfo),
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );
      });

      const fetchObservedTags = Effect.fn(function* (streamArn: string) {
        return yield* kv.listTagsForStream({ StreamARN: streamArn }).pipe(
          Effect.map((r) => compactTags(r.Tags)),
          Effect.catchTag("ResourceNotFoundException", () =>
            Effect.succeed({} as Record<string, string>),
          ),
        );
      });

      return Stream.Provider.of({
        stables: ["streamName", "streamArn"],

        list: () =>
          Effect.gen(function* () {
            const pages = yield* kv.listStreams.pages({}).pipe(Stream_.runCollect);
            return Array.from(pages)
              .flatMap((page) => page.StreamInfoList ?? [])
              .filter((info) => info.StreamName !== undefined && info.StreamARN !== undefined)
              .map((info) => ({
                streamName: info.StreamName!,
                streamArn: info.StreamARN!,
              }));
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const streamName = output?.streamName ?? (yield* createName(id, olds ?? {}));
          const info = yield* observeStream(streamName);
          if (info?.StreamARN === undefined || info.Status === "DELETING") {
            return undefined;
          }
          const attrs = {
            streamName,
            streamArn: info.StreamARN,
          };
          const tags = yield* fetchObservedTags(info.StreamARN);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createName(id, olds ?? {});
          const newName = yield* createName(id, news ?? {});
          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
          // The KMS key is bound at creation and cannot be changed in place.
          if (olds?.kmsKeyId !== news?.kmsKeyId) {
            return { action: "replace" } as const;
          }
          // deviceName/mediaType/dataRetention/tags fall through to
          // the default update path (reconcile applies the deltas).
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          // `news` is undefined when the resource is declared without props
          // (`Stream("Id")`) — normalize WITHOUT a destructuring default
          // (defaults widen the inferred Props type).
          const props = news ?? {};
          const streamName = output?.streamName ?? (yield* createName(id, props));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...props.tags, ...internalTags };
          // Wire unit is whole hours (DataRetentionInHours).
          const desiredRetention = toWireHours(props.dataRetention);

          // 1. OBSERVE — cloud state is authoritative
          let info = yield* observeStream(streamName);

          // A previous incarnation still in DELETING blocks re-creation of
          // the same name — wait for the purge to finish, then recreate.
          if (info?.Status === "DELETING") {
            yield* session.note(`waiting for previous stream ${streamName} to finish deleting...`);
            yield* waitForStreamGone(streamName);
            info = undefined;
          }

          // 2. ENSURE — create if missing; a `ResourceInUseException` means a
          // peer created it concurrently (or a prior incarnation is still
          // DELETING — retried inside the helper), so fall through to
          // observation. Creation is async; wait for ACTIVE (bounded).
          if (info === undefined) {
            yield* retryWhileResourceInUse(
              kv.createStream({
                StreamName: streamName,
                DeviceName: props.deviceName,
                MediaType: props.mediaType,
                KmsKeyId: props.kmsKeyId,
                DataRetentionInHours: desiredRetention ?? 0,
                Tags: desiredTags,
              }),
            ).pipe(
              Effect.catchTag("ResourceInUseException", () =>
                Effect.succeed({ StreamARN: undefined }),
              ),
            );
            yield* session.note(`creating stream ${streamName}...`);
            info = yield* waitForStreamActive(streamName);
          } else if (info.Status !== "ACTIVE") {
            // A CREATING/UPDATING stream rejects mutations — wait it out.
            info = yield* waitForStreamActive(streamName);
          }
          const streamArn = info.StreamARN!;

          // 3. SYNC — deviceName/mediaType (versioned update; only when the
          // observed metadata differs from the desired state)
          if (
            (props.deviceName !== undefined && props.deviceName !== info.DeviceName) ||
            (props.mediaType !== undefined && props.mediaType !== info.MediaType)
          ) {
            yield* retryWhileSettling(
              kv.updateStream({
                StreamARN: streamArn,
                CurrentVersion: info.Version!,
                DeviceName: props.deviceName,
                MediaType: props.mediaType,
              }),
            );
            // UpdateStream is async: it bumps the version and transitions
            // through UPDATING. Wait for BOTH the version bump and ACTIVE so
            // the next versioned mutation uses a fresh version.
            info = yield* waitForStreamActive(streamName, info.Version);
          }

          // 3b. SYNC — data retention (delta-based API: INCREASE/DECREASE by
          // the difference between observed and desired)
          const observedRetention = info.DataRetentionInHours ?? 0;
          if (desiredRetention !== undefined && desiredRetention !== observedRetention) {
            yield* retryWhileSettling(
              kv.updateDataRetention({
                StreamARN: streamArn,
                CurrentVersion: info.Version!,
                Operation:
                  desiredRetention > observedRetention
                    ? "INCREASE_DATA_RETENTION"
                    : "DECREASE_DATA_RETENTION",
                DataRetentionChangeInHours: Math.abs(desiredRetention - observedRetention),
              }),
            );
            info = yield* waitForStreamActive(streamName, info.Version);
          }

          // 3c. SYNC TAGS — diff against OBSERVED cloud tags so adoption
          // converges
          const observedTags = yield* fetchObservedTags(streamArn);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* retryWhileSettling(
              kv.tagStream({
                StreamARN: streamArn,
                Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
              }),
            );
          }
          if (removed.length > 0) {
            yield* retryWhileSettling(
              kv.untagStream({
                StreamARN: streamArn,
                TagKeyList: removed,
              }),
            );
          }

          yield* session.note(streamArn);
          return { streamName, streamArn };
        }),

        delete: Effect.fn(function* ({ output }) {
          // A CREATING/UPDATING stream rejects deletion with
          // ResourceInUseException — retry through the transition (bounded).
          yield* retryWhileResourceInUse(kv.deleteStream({ StreamARN: output.streamArn })).pipe(
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
          );
          // DeleteStream is accepted immediately; the name stays reserved
          // until the stream is fully purged. Wait it out so destroy (and
          // the suite's out-of-band list) don't race a still-ACTIVE row.
          yield* waitForStreamGone(output.streamName);
        }),
      });
    }),
  );