sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ AI/ SearchToken.ts

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

const TypeId = "Cloudflare.AI.SearchToken" as const;
type TypeId = typeof TypeId;

export type SearchTokenProps = {
  /**
   * Display name for the service token. Mutable in place.
   * If omitted, a unique name is generated from the app, stage, and
   * logical ID.
   * @default ${app}-${id}-${stage}-${suffix}
   */
  name?: string;
  /**
   * Id of the underlying Cloudflare API token AI Search authenticates
   * with when syncing the data source. The token must carry the
   * "AI Search Index Engine" permission group — Cloudflare validates it
   * on create/update and rejects tokens without it.
   */
  cfApiId: string;
  /**
   * Plaintext value of the underlying Cloudflare API token. Write-only —
   * Cloudflare never returns it, so rotation is detected against the
   * previously-persisted props rather than observed cloud state.
   */
  cfApiKey: Redacted.Redacted<string>;
  /**
   * Whether this is a legacy (account-level instance) token.
   * @default false
   */
  legacy?: boolean;
};

export type TokenAttributes = {
  /**
   * AI Search service token id (a UUID). Stable across updates.
   */
  id: string;
  /**
   * The Cloudflare account the token belongs to.
   */
  accountId: string;
  /**
   * Display name of the service token.
   */
  name: string;
  /**
   * Id of the underlying Cloudflare API token.
   */
  cfApiId: string;
  /**
   * Whether the token is enabled.
   */
  enabled: boolean | undefined;
  /**
   * Whether this is a legacy (account-level instance) token.
   */
  legacy: boolean | undefined;
  /**
   * When the token was created.
   */
  createdAt: string | undefined;
  /**
   * When the token was last modified.
   */
  modifiedAt: string | undefined;
  /**
   * Who created the token.
   */
  createdBy: string | undefined;
  /**
   * Who last modified the token.
   */
  modifiedBy: string | undefined;
};

export type SearchToken = Resource<TypeId, SearchTokenProps, TokenAttributes, never, Providers>;

/**
 * A Cloudflare.AI. Search service token — the credential AI Search uses to
 * access your data source (R2 bucket, Vectorize index, Workers AI) when
 * indexing.
 *
 * The token wraps an existing Cloudflare API token (`cfApiId` +
 * `cfApiKey`). That API token must carry the "AI Search Index Engine"
 * permission group — Cloudflare validates the credential on create and
 * update and rejects tokens without it. Pair it with
 * `Cloudflare.ApiToken.AccountApiToken` to mint the underlying API token in the
 * same stack, then reference the service token's `id` from an AI Search
 * instance's `tokenId` prop.
 * ### Creating a Token
 * **Example:** Minting the underlying API token in the same stack
 * ```typescript
 * const apiToken = yield* Cloudflare.ApiToken.AccountApiToken("SearchTokenSource", {
 *   policies: [
 *     {
 *       effect: "allow",
 *       permissionGroups: ["AI Search Index Engine"],
 *       resources: { [`com.cloudflare.api.account.${accountId}`]: "*" },
 *     },
 *   ],
 * });
 * const token = yield* Cloudflare.AI.SearchToken("SearchToken", {
 *   cfApiId: apiToken.tokenId,
 *   cfApiKey: apiToken.value,
 * });
 * ```
 *
 * ### Using the Token from a SearchInstance
 * **Example:** Wiring the token into an AI Search instance
 * ```typescript
 * const search = yield* Cloudflare.AI.Search("Search", {
 *   source: bucket,
 *   tokenId: token.id,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/ai-search/
 *
 * @resource
 * @product AI Search
 * @category AI
 */
export const SearchToken = Resource<SearchToken>(TypeId, {
  aliases: ["Cloudflare.AiSearch.Token"],
});

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

export const SearchTokenProvider = () =>
  Provider.succeed(SearchToken, {
    stables: ["id", "accountId", "createdAt", "createdBy"],
    diff: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!isResolved(news)) return undefined;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // Everything (name, credentials, legacy flag) is mutable via PUT —
      // let the engine apply its default update logic.
      return undefined;
    }),
    read: Effect.fn(function* ({ id, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      const observed = output?.id
        ? yield* getToken(acct, output.id)
        : // Cold read (lost state): the display name is deterministic, so
          // scan the token list for it.
          yield* findTokenByName(acct, yield* createTokenName(id, olds?.name));
      return observed ? toAttributes(observed, acct) : undefined;
    }),
    reconcile: Effect.fn(function* ({ id, news, olds, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      const name = yield* createTokenName(id, news.name);

      // Observe — `output.id` is a cache, not a guarantee: a missing
      // token falls through to "missing" and we recreate. Without an id
      // (greenfield or adoption-by-name), scan the list for the
      // deterministic display name.
      const observed = output?.id
        ? yield* getToken(acct, output.id)
        : yield* findTokenByName(acct, name);

      const body = {
        name,
        cfApiId: news.cfApiId as string,
        cfApiKey: Redacted.value(news.cfApiKey as Redacted.Redacted<string>),
        // Cloudflare defaults an omitted `legacy` to `true`, and legacy
        // (account-level instance) tokens cannot be managed via the per-token
        // routes — GET/DELETE `/ai-search/tokens/{id}` return 401, so they can
        // never be read or deleted, leaking on every teardown. Force
        // non-legacy unless the caller explicitly opts in.
        legacy: news.legacy ?? false,
      };

      if (!observed) {
        // Ensure — create with the full desired body. A freshly minted
        // underlying API token propagates eventually-consistently, so a
        // transient `InvalidTokenCredentials` (code 7012) is retried
        // briefly before being treated as a real validation failure.
        const created = yield* aisearch
          .createToken({ accountId: acct, ...body })
          .pipe(retryTokenPropagation);
        return toAttributes(created, acct);
      }

      // Sync — Cloudflare never returns `cfApiKey`, so the secret cannot
      // be diffed against observed state; fall back to the previously
      // persisted props for the key only. Everything else diffs against
      // the observed cloud state.
      const keyRotated =
        olds === undefined ||
        olds.cfApiKey === undefined ||
        !isResolved(olds.cfApiKey) ||
        Redacted.value(olds.cfApiKey) !== body.cfApiKey;
      const dirty =
        keyRotated ||
        observed.name !== name ||
        observed.cfApiId !== body.cfApiId ||
        (news.legacy !== undefined && (observed.legacy ?? undefined) !== news.legacy);
      if (!dirty) {
        return toAttributes(observed, acct);
      }

      // The update is a PUT and always requires the full credential pair.
      const updated = yield* aisearch
        .updateToken({ accountId: acct, id: observed.id, ...body })
        .pipe(retryTokenPropagation);
      return toAttributes(updated, acct);
    }),
    list: () =>
      // Service tokens are account-scoped (`/accounts/{id}/ai-search/tokens`),
      // not nested under an instance — one paginated list per account.
      Effect.gen(function* () {
        const { accountId } = yield* yield* CloudflareEnvironment;
        return yield* aisearch.listTokens.pages({ accountId, perPage: 50 }).pipe(
          Stream.runCollect,
          Effect.map((chunk) =>
            Array.from(chunk).flatMap((page) =>
              // The list item shape matches the create/read response, so the
              // emitted Attributes are identical to `read` (the write-only
              // `cfApiKey` is never part of Attributes anyway).
              (page.result ?? []).map((t) => toAttributes(t, accountId)),
            ),
          ),
          // AI Search isn't enabled on every account — the route is gated
          // rather than returning an empty list. Treat it as "none".
          Effect.catchTag("InvalidRoute", () => Effect.succeed([])),
        );
      }),
    delete: Effect.fn(function* ({ output }) {
      // A missing token (already deleted) is success. An AI Search
      // instance that referenced this token may still be deleting
      // asynchronously — Cloudflare rejects the delete with
      // `token_in_use_by_instances` until the instance is gone, so ride
      // that out briefly.
      yield* aisearch.deleteToken({ accountId: output.accountId, id: output.id }).pipe(
        Effect.retry({
          while: (e) => e._tag === "TokenInUseByInstances",
          // Allow brief asynchronous teardown, but surface a token still
          // referenced by another instance instead of stalling cleanup.
          schedule: Schedule.spaced("5 seconds"),
          times: 8,
        }),
        Effect.catchTag("TokenNotFound", () => Effect.void),
      );
    }),
  });

type ObservedToken = aisearch.CreateTokenResponse;

/**
 * Read a token by id, mapping "gone" (`TokenNotFound`, Cloudflare error
 * code 7075) to `undefined`. The read response declares every field
 * optional, so observed identity fields are re-asserted from the request.
 */
const getToken = (accountId: string, id: string) =>
  aisearch.readToken({ accountId, id }).pipe(
    Effect.map((t): ObservedToken => ({
      id: t.id ?? id,
      name: t.name ?? "",
      cfApiId: t.cfApiId ?? "",
      createdAt: t.createdAt ?? "",
      modifiedAt: t.modifiedAt ?? "",
      createdBy: t.createdBy,
      enabled: t.enabled,
      legacy: t.legacy,
      modifiedBy: t.modifiedBy,
    })),
    Effect.catchTag("TokenNotFound", () => Effect.undefined),
  );

/**
 * Scan the account's service tokens for an exact display-name match
 * (used for cold reads and greenfield creates after lost state). The
 * `search` query param chokes on long strings (generated physical names
 * can hit the limit), so this streams all pages and filters client-side.
 */
const findTokenByName = (accountId: string, name: string) =>
  aisearch.listTokens.items({ accountId, perPage: 50 }).pipe(
    Stream.filter((t) => t.name === name),
    Stream.runHead,
    Effect.map(Option.getOrUndefined),
  );

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

/**
 * A freshly minted underlying API token may not have propagated yet when
 * AI Search validates it — ride out transient `InvalidTokenCredentials`
 * (code 7012) with a short, bounded retry. Genuinely invalid credentials
 * still fail after the retries are exhausted.
 */
const retryTokenPropagation = <A, E extends { _tag: string }, R>(effect: Effect.Effect<A, E, R>) =>
  effect.pipe(
    Effect.retry({
      while: (e) => e._tag === "InvalidTokenCredentials",
      schedule: Schedule.exponential("1 second"),
      times: 6,
    }),
  );

const toAttributes = (
  token: ObservedToken | aisearch.UpdateTokenResponse,
  accountId: string,
): TokenAttributes => ({
  id: token.id,
  accountId,
  name: token.name,
  cfApiId: token.cfApiId,
  enabled: token.enabled ?? undefined,
  legacy: token.legacy ?? undefined,
  createdAt: token.createdAt || undefined,
  modifiedAt: token.modifiedAt || undefined,
  createdBy: token.createdBy ?? undefined,
  modifiedBy: token.modifiedBy ?? undefined,
});