sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Calls/ TurnKey.ts

import * as calls from "@distilled.cloud/cloudflare/calls";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import * as Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.Calls.TurnKey" as const;
type TypeId = typeof TypeId;

export type TurnKeyProps = {
  /**
   * A short description of the TURN key, not shown to end users and not
   * unique. Mutable in place. If omitted, a unique name is generated from
   * the app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
};

export type TurnKeyAttributes = {
  /**
   * Cloudflare-generated unique identifier for the TURN key. Used in the
   * credential-minting API path
   * (`https://rtc.live.cloudflare.com/v1/turn/keys/{keyId}/credentials/generate`).
   */
  keyId: string;
  /**
   * The Cloudflare account the TURN key belongs to.
   */
  accountId: string;
  /**
   * TURN key secret (bearer token) used to mint short-lived TURN
   * credentials. Returned only at creation time and never re-readable —
   * Alchemy persists it in state and carries it forward across updates.
   */
  key: Redacted.Redacted<string>;
  /**
   * A short description of the TURN key.
   */
  name: string;
  /**
   * When the TURN key was created.
   */
  created: string;
  /**
   * When the TURN key was last modified.
   */
  modified: string;
};

export type TurnKey = Resource<TypeId, TurnKeyProps, TurnKeyAttributes, never, Providers>;

/**
 * A Cloudflare Realtime (formerly "Calls") TURN key.
 *
 * A TURN key authenticates your backend against Cloudflare's managed TURN
 * service: you exchange the create-only `key` (a bearer token) for
 * short-lived TURN credentials that WebRTC clients use to relay traffic
 * through Cloudflare's network. The only configurable property is the
 * human-readable `name`, which is mutable in place.
 * ### Creating a TURN key
 * **Example:** TURN key with a generated name
 * ```typescript
 * const turnKey = yield* Cloudflare.Calls.TurnKey("turn", {});
 * ```
 *
 * **Example:** TURN key with an explicit name
 * ```typescript
 * const turnKey = yield* Cloudflare.Calls.TurnKey("turn", {
 *   name: "my-turn-key",
 * });
 * ```
 *
 * ### Using the key
 * **Example:** Minting TURN credentials server-side
 * ```typescript
 * // keyId is public — it appears in the credential-minting URL:
 * const keyId = turnKey.keyId;
 *
 * // The key is redacted — POST it as a bearer token to
 * // https://rtc.live.cloudflare.com/v1/turn/keys/{keyId}/credentials/generate
 * const apiToken = turnKey.key; // Redacted<string>
 * ```
 *
 * @see https://developers.cloudflare.com/realtime/turn/
 *
 * @resource
 * @product Calls
 * @category Media
 */
export const TurnKey = Resource<TurnKey>(TypeId);

/**
 * Returns true if the given value is a TurnKey resource.
 */
export const isTurnKey = (value: unknown): value is TurnKey =>
  Predicate.hasProperty(value, "Type") && value.Type === TypeId;

export const TurnKeyProvider = () =>
  Provider.succeed(TurnKey, {
    stables: ["keyId", "accountId", "key", "created"],
    diff: Effect.fn(function* ({ output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (output !== undefined && output.accountId !== accountId) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ output }) {
      // The TURN key secret is returned only at creation time, so a key
      // cannot be re-hydrated without prior state — no cold read /
      // adoption path.
      if (!output?.keyId) return undefined;
      const observed = yield* getTurnKey(output.accountId, output.keyId);
      return observed ? toAttributes(observed, output.accountId, output.key) : undefined;
    }),
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Account-scoped collection: paginate the TURN keys list exhaustively.
      // The list response carries every readable field (uid/name/created/
      // modified) — the bearer `key` is returned only at creation and is
      // never re-readable, so we hydrate it as an empty redacted value to
      // match exactly what `read` would produce on a cold (stateless) read.
      return yield* calls.listTurns.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((turnKey) =>
              toAttributes(turnKey, accountId, Redacted.make("")),
            ),
          ),
        ),
      );
    }),
    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = yield* createTurnKeyName(id, news.name);

      // Observe — the keyId cached on `output` is a hint, not a guarantee:
      // a missing key (code 20008) falls through and we recreate.
      const observed = output?.keyId
        ? yield* getTurnKey(output.accountId ?? accountId, output.keyId)
        : undefined;

      if (!observed || !output) {
        // Ensure — greenfield (or out-of-band delete): create and capture
        // the create-only key. Names are not unique on Cloudflare's side,
        // so there is no AlreadyExists race to tolerate.
        const created = yield* calls.createTurn({ accountId, name });
        return toAttributes(created, accountId, Redacted.make(created.key ?? ""));
      }

      // Sync — the only mutable aspect is `name`; diff observed cloud
      // state against desired and skip the PUT entirely on a no-op.
      if (observed.name === name) {
        return toAttributes(observed, output.accountId, output.key);
      }
      const updated = yield* calls.updateTurn({
        accountId: output.accountId,
        keyId: output.keyId,
        name,
      });
      return toAttributes(updated, output.accountId, output.key);
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* calls
        .deleteTurn({ accountId: output.accountId, keyId: output.keyId })
        .pipe(Effect.catchTag("TurnKeyNotFound", () => Effect.void));
    }),
  });

/**
 * Read a TURN key by id, mapping "gone" (`TurnKeyNotFound`, Cloudflare
 * error code 20008) to `undefined`.
 */
const getTurnKey = (accountId: string, keyId: string) =>
  calls
    .getTurn({ accountId, keyId })
    .pipe(Effect.catchTag("TurnKeyNotFound", () => Effect.undefined));

const createTurnKeyName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    return name ?? (yield* createPhysicalName({ id, lowercase: true }));
  });

const toAttributes = (
  turnKey: calls.GetTurnResponse | calls.CreateTurnResponse | calls.UpdateTurnResponse,
  accountId: string,
  key: Redacted.Redacted<string>,
): TurnKeyAttributes => ({
  keyId: turnKey.uid ?? "",
  accountId,
  key,
  name: turnKey.name ?? "",
  created: turnKey.created ?? "",
  modified: turnKey.modified ?? "",
});