sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ AI/ SearchNamespace.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 { isResourceOfType, Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

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

export type SearchNamespaceProps = {
  /**
   * Namespace name. Lowercase letters, digits, and hyphens; must start and
   * end with an alphanumeric character; 1-28 characters. The name is the
   * namespace's identity (it appears in the API path) and cannot be
   * renamed — changing it triggers a replacement. If omitted, a unique
   * name is generated from the app, stage, and logical ID.
   * @default ${app}-${id}-${stage}-${suffix}
   */
  name?: string;
  /**
   * Optional human-readable description for the namespace.
   * Max 256 characters.
   */
  description?: string;
};

export type SearchNamespaceAttributes = {
  /**
   * Namespace name (its identity within the account).
   */
  name: string;
  /**
   * The Cloudflare account the namespace belongs to.
   */
  accountId: string;
  /**
   * Human-readable description, when set.
   */
  description: string | undefined;
  /**
   * When the namespace was created.
   */
  createdAt: string | undefined;
};

export type SearchNamespace = Resource<
  TypeId,
  SearchNamespaceProps,
  SearchNamespaceAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare.AI. Search namespace — a logical grouping for AI Search
 * instances within an account.
 *
 * Namespaces partition AI Search (formerly AutoRAG) instances: each
 * namespace owns its own set of namespace-scoped instances and can be
 * searched or queried as a unit. The namespace `name` is its identity —
 * changing it triggers a replacement; only the `description` is mutable
 * in place.
 *
 * The account-provided `default` namespace is reserved: it always exists
 * and Cloudflare disallows modifying or deleting it. Alchemy adopts it so
 * it can be referenced and bound, but never updates or tears it down.
 *
 * ### Creating a Namespace
 * **Example:** Generated name
 * ```typescript
 * const ns = yield* Cloudflare.AI.SearchNamespace("docs", {});
 * ```
 *
 * **Example:** Explicit name and description
 * ```typescript
 * const ns = yield* Cloudflare.AI.SearchNamespace("docs", {
 *   name: "docs-search",
 *   description: "Search over the product documentation",
 * });
 * ```
 *
 * ### Updating a Namespace
 * **Example:** Change the description in place
 * Only the `description` is mutable; changing `name` replaces the namespace.
 * ```typescript
 * const ns = yield* Cloudflare.AI.SearchNamespace("docs", {
 *   name: "docs-search",
 *   description: "Search over docs and changelogs",
 * });
 * ```
 *
 * ### Grouping pipelines
 * Group {@link Search} pipelines under the namespace by passing the
 * namespace resource itself to each pipeline's `namespace` prop. The engine
 * orders each pipeline after the namespace on deploy and tears them down
 * before it on destroy.
 * **Example:** Two pipelines in one namespace
 * ```typescript
 * const ns = yield* Cloudflare.AI.SearchNamespace("docs", {});
 * const guides = yield* Cloudflare.AI.Search("guides", {
 *   source: guidesBucket,
 *   namespace: ns,
 * });
 * const api = yield* Cloudflare.AI.Search("api", {
 *   source: apiBucket,
 *   namespace: ns,
 * });
 * ```
 *
 * ### Binding to an Effect Worker
 * Bind the namespace with `Cloudflare.AI.QuerySearchNamespace(namespace)`,
 * which attaches the `ai_search_namespace` binding and returns a client
 * whose `.get(name)` selects an instance within the namespace at runtime.
 * Provide {@link QuerySearchNamespaceBinding} in the Worker's runtime
 * layer.
 * **Example:** Select an instance per request
 * ```typescript
 * import * as Cloudflare from "@alchemy.run/cloudflare";
 * import * as Effect from "effect/Effect";
 * import { HttpServerRequest } from "effect/http/HttpServerRequest";
 * import * as HttpServerResponse from "effect/http/HttpServerResponse";
 *
 * export default class Api extends Cloudflare.Worker<Api>()(
 *   "api",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const ns = yield* Cloudflare.AI.QuerySearchNamespace(Docs);
 *
 *     return {
 *       fetch: Effect.gen(function* () {
 *         const url = new URL((yield* HttpServerRequest).url);
 *         const instance = url.searchParams.get("instance") ?? "guides";
 *         const query = url.searchParams.get("q") ?? "";
 *         const answer = yield* ns.get(instance).chatCompletions({
 *           messages: [{ role: "user", content: query }],
 *         });
 *         return yield* HttpServerResponse.json(answer);
 *       }),
 *     };
 *   }).pipe(Effect.provide(Cloudflare.AI.QuerySearchNamespaceBinding)),
 * ) {}
 * ```
 *
 * ### Binding to an Async Worker
 * For a vanilla `async fetch` Worker, pass the namespace under `Worker.env`.
 * `InferEnv` types `env.SEARCH` as the runtime `SearchNamespace` handle.
 * **Example:** Async Worker via `env`
 * ```typescript
 * export const Api = Cloudflare.Worker("api", {
 *   main: "./worker.ts",
 *   env: { SEARCH: namespace },
 * });
 * export type ApiEnv = Cloudflare.InferEnv<typeof Api>;
 *
 * // worker.ts
 * export default {
 *   async fetch(request: Request, env: ApiEnv): Promise<Response> {
 *     const query = new URL(request.url).searchParams.get("q") ?? "";
 *     return Response.json(
 *       await env.SEARCH.get("guides").chatCompletions({
 *         messages: [{ role: "user", content: query }],
 *       }),
 *     );
 *   },
 * };
 * ```
 *
 * @see https://developers.cloudflare.com/ai-search/
 *
 * @resource
 * @product AI Search
 * @category AI
 */
export const SearchNamespace = Resource<SearchNamespace>(TypeId, {
  aliases: ["Cloudflare.AiSearch.Namespace"],
});

/**
 * Returns true if the given value is a SearchNamespace resource.
 */
export const isSearchNamespace = (value: unknown): value is SearchNamespace =>
  isResourceOfType(value, TypeId);

export const SearchNamespaceProvider = () =>
  Provider.succeed(SearchNamespace, {
    stables: ["name", "accountId", "createdAt"],
    diff: Effect.fn(function* ({ id, olds, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!isResolved(news)) return undefined;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // The name is the namespace's identity (it is the API path
      // parameter) — renaming is a replacement. Props are all optional, so a
      // no-props resource resolves `news`/`olds` to `undefined` at runtime.
      const oldName = output?.name ?? (yield* createNamespaceName(id, olds?.name));
      // Auto-generated names are engine-owned: the deployed name stays
      // authoritative even if the generator would name this id differently
      // today. Only an explicit user-provided name can force a replace.
      const newName = news?.name ?? oldName;
      if (newName !== oldName) {
        // A user-pinned name collides with the still-existing old
        // namespace only when both resolve to the same string — they
        // don't here, so create-before-delete is safe.
        return { action: "replace" } as const;
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ id, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      // The name is deterministic (explicit prop or generated from the
      // logical id), so a cold read (lost state) resolves the same
      // identifier as the original create did.
      const name = output?.name ?? (yield* createNamespaceName(id, olds?.name));
      const observed = yield* getNamespace(acct, name);
      return observed ? toAttributes(observed, acct) : undefined;
    }),
    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      // Props are all optional, so a no-props resource resolves `news` to
      // `undefined` at runtime — fall back to the empty desired shape.
      const props = news ?? {};
      const name = output?.name ?? (yield* createNamespaceName(id, props.name));

      // Observe — `output.name` is a cache, not a guarantee: a missing
      // namespace falls through to create.
      let observed = yield* getNamespace(acct, name);

      if (!observed) {
        // Ensure — greenfield (or out-of-band delete). A concurrent
        // create surfaces as `NamespaceAlreadyExists` — treat it as a
        // race and fall through to the sync path against the observed
        // namespace.
        const ensured = yield* aisearch
          .createNamespace({
            accountId: acct,
            name,
            description: props.description,
          })
          .pipe(
            Effect.map((created) => ({ created: true as const, ns: created })),
            Effect.catchTag("NamespaceAlreadyExists", (originalError) =>
              Effect.gen(function* () {
                const existing = yield* getNamespace(acct, name);
                if (!existing) return yield* originalError;
                return { created: false as const, ns: existing };
              }),
            ),
          );
        if (ensured.created) {
          return toAttributes(ensured.ns, acct);
        }
        observed = ensured.ns;
      }

      // The account-provided `default` namespace is reserved: it always
      // exists and its metadata cannot be modified
      // (`cannot_modify_default_namespace`). Adopt it as-is so it can be
      // referenced/bound, but never attempt to mutate it.
      if (name === "default") {
        return toAttributes(observed, acct);
      }

      // Sync — the description is the only mutable aspect. Diff observed
      // cloud state against desired; skip the PUT entirely on a no-op.
      const observedDescription = normalize(observed.description);
      if (observedDescription === props.description) {
        return toAttributes(observed, acct);
      }
      const updated = yield* aisearch
        .updateNamespace({
          accountId: acct,
          name,
          // `null` clears a previously-set description.
          description: props.description ?? null,
        })
        .pipe(
          // The observe read can be eventually consistent: a namespace
          // deleted out-of-band may still appear in `readNamespace` and
          // then 404 here. Treat that as "missing" and recreate with the
          // desired shape.
          Effect.catchTag("NamespaceNotFound", () =>
            aisearch.createNamespace({
              accountId: acct,
              name,
              description: props.description,
            }),
          ),
        );
      return toAttributes(updated, acct);
    }),
    delete: Effect.fn(function* ({ output }) {
      // The account-provided `default` namespace cannot be deleted
      // (`cannot_modify_default_namespace`); binding/adopting it must never
      // tear it down, so its delete is a no-op.
      if (output.name === "default") return;
      // A missing namespace (already deleted) is success. Instances inside
      // the namespace must be deleted first — the engine orders that via
      // the `namespace` reference on dependent resources.
      yield* aisearch
        .deleteNamespace({ accountId: output.accountId, name: output.name })
        .pipe(Effect.catchTag("NamespaceNotFound", () => Effect.void));
    }),
    // Account-scoped collection: namespaces are enumerated directly under
    // the account (no parent fan-out). Exhaustively paginate `listNamespaces`
    // and hydrate each item into the exact `read` Attributes shape.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* aisearch.listNamespaces.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? [])
              // The account-provided `default` namespace can't be deleted
              // (`cannot_modify_default_namespace`); never enumerate it for
              // account-wide teardown.
              .filter((ns) => ns.name !== "default")
              .map((ns) => toAttributes(ns, accountId)),
          ),
        ),
      );
    }),
  });

type ObservedNamespace = aisearch.ReadNamespaceResponse;

/**
 * Read a namespace by name, mapping "gone" (`NamespaceNotFound`,
 * Cloudflare error code 7063) to `undefined`.
 */
const getNamespace = (accountId: string, name: string) =>
  aisearch
    .readNamespace({ accountId, name })
    .pipe(Effect.catchTag("NamespaceNotFound", () => Effect.undefined));

const createNamespaceName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    // Cloudflare restricts namespace names to lowercase alphanumerics and
    // hyphens, 1-28 characters.
    return name ?? (yield* createPhysicalName({ id, lowercase: true, maxLength: 28 }));
  });

/**
 * Cloudflare returns `null` for an unset description; desired-state
 * shapes leave it `undefined`. Collapse both to `undefined` for diffing.
 */
const normalize = <T>(value: T | null | undefined): T | undefined => value ?? undefined;

const toAttributes = (
  ns: ObservedNamespace | aisearch.CreateNamespaceResponse | aisearch.UpdateNamespaceResponse,
  accountId: string,
): SearchNamespaceAttributes => ({
  name: ns.name,
  accountId,
  description: normalize(ns.description),
  createdAt: ns.createdAt,
});