The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as aisearch from "@distilled.cloud/cloudflare/aisearch"; |
| 2 | import { deepEqual, isResolved } from "alchemy/Diff"; |
| 3 | import { createPhysicalName } from "alchemy/PhysicalName"; |
| 4 | import * as Provider from "alchemy/Provider"; |
| 5 | import { isResourceOfType, Resource } from "alchemy/Resource"; |
| 6 | import * as Effect from "effect/Effect"; |
| 7 | import * as Schedule from "effect/Schedule"; |
| 8 | import * as Stream from "effect/Stream"; |
| 9 | import { CloudflareEnvironment } from "../CloudflareEnvironment.ts"; |
| 10 | import type { Providers } from "../Providers.ts"; |
| 11 | |
| 12 | const TypeId = "Cloudflare.AI.Search" as const; |
| 13 | type TypeId = typeof TypeId; |
| 14 | |
| 15 | /** |
| 16 | * The kind of data source an AI Search instance indexes. |
| 17 | */ |
| 18 | export type SearchInstanceSourceType = "r2" | "web-crawler"; |
| 19 | |
| 20 | /** |
| 21 | * Generation model used to answer AI Search queries. |
| 22 | */ |
| 23 | export type SearchModel = Exclude<NonNullable<aisearch.CreateInstanceRequest["aiSearchModel"]>, "">; |
| 24 | |
| 25 | /** |
| 26 | * Embedding model used to vectorize indexed content. Cannot be changed |
| 27 | * after creation (it defines the vector space). |
| 28 | */ |
| 29 | export type EmbeddingModel = Exclude< |
| 30 | NonNullable<aisearch.CreateInstanceRequest["embeddingModel"]>, |
| 31 | "" |
| 32 | >; |
| 33 | |
| 34 | /** |
| 35 | * Reranking model applied to retrieved results. |
| 36 | */ |
| 37 | export type RerankingModel = "@cf/baai/bge-reranker-base"; |
| 38 | |
| 39 | /** |
| 40 | * Data-source specific indexing parameters (R2 prefix / include / exclude |
| 41 | * filters, or web-crawler options). |
| 42 | */ |
| 43 | export type SourceParams = NonNullable<aisearch.CreateInstanceRequest["sourceParams"]>; |
| 44 | |
| 45 | /** |
| 46 | * Controls which storage backends are used during indexing. |
| 47 | */ |
| 48 | export type IndexMethod = NonNullable<aisearch.CreateInstanceRequest["indexMethod"]>; |
| 49 | |
| 50 | /** |
| 51 | * Keyword indexing options. |
| 52 | */ |
| 53 | export type IndexingOptions = NonNullable<aisearch.CreateInstanceRequest["indexingOptions"]>; |
| 54 | |
| 55 | /** |
| 56 | * Custom metadata fields extracted at indexing time. |
| 57 | */ |
| 58 | export type CustomMetadata = NonNullable<aisearch.CreateInstanceRequest["customMetadata"]>; |
| 59 | |
| 60 | /** |
| 61 | * Retrieval-time options (boosting and keyword match mode). |
| 62 | */ |
| 63 | export type RetrievalOptions = NonNullable<aisearch.CreateInstanceRequest["retrievalOptions"]>; |
| 64 | |
| 65 | /** |
| 66 | * Public REST endpoint configuration for the instance. |
| 67 | */ |
| 68 | export type PublicEndpointParams = NonNullable< |
| 69 | aisearch.CreateInstanceRequest["publicEndpointParams"] |
| 70 | >; |
| 71 | |
| 72 | /** |
| 73 | * Similarity-cache threshold preset. |
| 74 | */ |
| 75 | export type CacheThreshold = |
| 76 | | "super_strict_match" |
| 77 | | "close_enough" |
| 78 | | "flexible_friend" |
| 79 | | "anything_goes"; |
| 80 | |
| 81 | export type SearchInstanceProps = { |
| 82 | /** |
| 83 | * SearchInstance identifier (the AI Search "name" shown in the dashboard). |
| 84 | * Lowercase alphanumeric, hyphens, and underscores. If omitted, a unique |
| 85 | * id is generated from the app, stage, and logical ID. Changing it |
| 86 | * triggers a replacement. |
| 87 | * @default ${app}-${id}-${stage}-${suffix} |
| 88 | */ |
| 89 | instanceId?: string; |
| 90 | /** |
| 91 | * Namespace this instance belongs to. AI Search instances are |
| 92 | * namespace-scoped; omitting this places the instance in the |
| 93 | * account-provided `default` namespace. Pass a `SearchNamespace`'s |
| 94 | * `name` output to group instances under a custom namespace (which also |
| 95 | * orders this instance after that namespace on deploy and before it on |
| 96 | * destroy). The namespace is immutable — changing it triggers a |
| 97 | * replacement. |
| 98 | * @default "default" |
| 99 | */ |
| 100 | namespace?: string; |
| 101 | /** |
| 102 | * Data source kind: `r2` indexes objects in an R2 bucket, `web-crawler` |
| 103 | * crawls a seed URL. Changing it triggers a replacement. |
| 104 | * @default "r2" |
| 105 | */ |
| 106 | type?: SearchInstanceSourceType; |
| 107 | /** |
| 108 | * Data source: the R2 bucket name (for `type: "r2"`) or the crawl seed |
| 109 | * URL (for `type: "web-crawler"`). Changing it triggers a replacement — |
| 110 | * the index must be rebuilt from scratch. |
| 111 | */ |
| 112 | source: string; |
| 113 | /** |
| 114 | * Source-specific indexing parameters (R2 prefix / include / exclude |
| 115 | * filters, web-crawler crawl and parse options). |
| 116 | */ |
| 117 | sourceParams?: SourceParams; |
| 118 | /** |
| 119 | * Id of the AI Search service token used to access the data source on |
| 120 | * sync. When omitted, Cloudflare provisions one automatically. |
| 121 | */ |
| 122 | tokenId?: string; |
| 123 | /** |
| 124 | * AI Gateway to route model inference calls through. |
| 125 | */ |
| 126 | aiGatewayId?: string; |
| 127 | /** |
| 128 | * Embedding model used to vectorize content. Cannot be changed after |
| 129 | * creation — updating this property triggers a replacement. |
| 130 | * @default service default |
| 131 | */ |
| 132 | embeddingModel?: EmbeddingModel; |
| 133 | /** |
| 134 | * Generation model used to answer AI Search queries. |
| 135 | * @default service default |
| 136 | */ |
| 137 | aiSearchModel?: SearchModel; |
| 138 | /** |
| 139 | * Whether to rewrite the user query before retrieval. |
| 140 | * @default false |
| 141 | */ |
| 142 | rewriteQuery?: boolean; |
| 143 | /** |
| 144 | * Model used to rewrite queries when `rewriteQuery` is enabled. |
| 145 | */ |
| 146 | rewriteModel?: SearchModel; |
| 147 | /** |
| 148 | * Whether custom chunking settings are applied during indexing. |
| 149 | */ |
| 150 | chunk?: boolean; |
| 151 | /** |
| 152 | * Chunk size (in tokens) used when splitting documents for indexing. |
| 153 | * Only affects future indexing runs. |
| 154 | */ |
| 155 | chunkSize?: number; |
| 156 | /** |
| 157 | * Overlap between consecutive chunks, as a percentage (0–30). Only |
| 158 | * affects future indexing runs. |
| 159 | */ |
| 160 | chunkOverlap?: number; |
| 161 | /** |
| 162 | * Controls which storage backends are used during indexing. Defaults to |
| 163 | * vector-only. |
| 164 | */ |
| 165 | indexMethod?: IndexMethod; |
| 166 | /** |
| 167 | * Keyword indexing options (tokenizer selection). |
| 168 | */ |
| 169 | indexingOptions?: IndexingOptions; |
| 170 | /** |
| 171 | * Custom metadata fields extracted at indexing time. |
| 172 | */ |
| 173 | customMetadata?: CustomMetadata; |
| 174 | /** |
| 175 | * Whether the similarity cache is enabled. |
| 176 | * @default false |
| 177 | */ |
| 178 | cache?: boolean; |
| 179 | /** |
| 180 | * Similarity-cache match strictness preset. |
| 181 | */ |
| 182 | cacheThreshold?: CacheThreshold; |
| 183 | /** |
| 184 | * Cache entry TTL in seconds. Allowed values: 600, 1800, 3600, 7200, |
| 185 | * 21600, 43200, 86400, 172800, 259200, 518400. |
| 186 | */ |
| 187 | cacheTtl?: number; |
| 188 | /** |
| 189 | * Whether retrieved results are reranked before generation. |
| 190 | * @default false |
| 191 | */ |
| 192 | reranking?: boolean; |
| 193 | /** |
| 194 | * Model used for reranking when `reranking` is enabled. |
| 195 | */ |
| 196 | rerankingModel?: RerankingModel; |
| 197 | /** |
| 198 | * Retrieval-time options (boosting and keyword match mode). |
| 199 | */ |
| 200 | retrievalOptions?: RetrievalOptions; |
| 201 | /** |
| 202 | * How vector and keyword results are fused: `max` or `rrf` |
| 203 | * (reciprocal rank fusion). |
| 204 | */ |
| 205 | fusionMethod?: "max" | "rrf"; |
| 206 | /** |
| 207 | * Maximum number of results returned by retrieval. |
| 208 | */ |
| 209 | maxNumResults?: number; |
| 210 | /** |
| 211 | * Minimum similarity score for a result to be returned. |
| 212 | */ |
| 213 | scoreThreshold?: number; |
| 214 | /** |
| 215 | * Public REST endpoint configuration (search / chat-completions / MCP). |
| 216 | */ |
| 217 | publicEndpointParams?: PublicEndpointParams; |
| 218 | /** |
| 219 | * Interval between automatic syncs, in seconds. Allowed values: 900, |
| 220 | * 1800, 3600, 7200, 14400, 21600, 43200, 86400. |
| 221 | */ |
| 222 | syncInterval?: number; |
| 223 | /** |
| 224 | * Kick off an initial indexing job right after the instance is first |
| 225 | * created, instead of waiting for the first scheduled sync. The job is |
| 226 | * triggered best-effort and not awaited — the deploy does not block on |
| 227 | * indexing, which can take much longer than a provisioning step should. |
| 228 | * Has no effect on updates or when no `source` is configured. |
| 229 | * @default false |
| 230 | */ |
| 231 | indexOnCreate?: boolean; |
| 232 | }; |
| 233 | |
| 234 | export type SearchInstanceAttributes = { |
| 235 | /** |
| 236 | * AI Search instance id. Lowercase alphanumeric, hyphens, underscores. |
| 237 | */ |
| 238 | instanceId: string; |
| 239 | /** |
| 240 | * The Cloudflare account the instance belongs to. |
| 241 | */ |
| 242 | accountId: string; |
| 243 | /** |
| 244 | * Namespace the instance belongs to (`default` when unspecified). |
| 245 | */ |
| 246 | namespace: string; |
| 247 | /** |
| 248 | * Data source kind (`r2` or `web-crawler`). |
| 249 | */ |
| 250 | type: SearchInstanceSourceType; |
| 251 | /** |
| 252 | * Data source (R2 bucket name or crawl seed URL). |
| 253 | */ |
| 254 | source: string | undefined; |
| 255 | /** |
| 256 | * Id of the AI Search service token used to access the data source. |
| 257 | */ |
| 258 | tokenId: string | undefined; |
| 259 | /** |
| 260 | * AI Gateway inference calls are routed through. |
| 261 | */ |
| 262 | aiGatewayId: string | undefined; |
| 263 | /** |
| 264 | * Embedding model used to vectorize content. |
| 265 | */ |
| 266 | embeddingModel: string | undefined; |
| 267 | /** |
| 268 | * Generation model used to answer queries. |
| 269 | */ |
| 270 | aiSearchModel: string | undefined; |
| 271 | /** |
| 272 | * Current instance status (indexing is asynchronous). |
| 273 | */ |
| 274 | status: string | undefined; |
| 275 | /** |
| 276 | * Whether the instance is paused. |
| 277 | */ |
| 278 | paused: boolean | undefined; |
| 279 | /** |
| 280 | * Id of the public REST endpoint, when enabled. |
| 281 | */ |
| 282 | publicEndpointId: string | undefined; |
| 283 | /** |
| 284 | * When the instance was created. |
| 285 | */ |
| 286 | createdAt: string | undefined; |
| 287 | /** |
| 288 | * When the instance was last modified. |
| 289 | */ |
| 290 | modifiedAt: string | undefined; |
| 291 | }; |
| 292 | |
| 293 | export type SearchInstance = Resource< |
| 294 | TypeId, |
| 295 | SearchInstanceProps, |
| 296 | SearchInstanceAttributes, |
| 297 | never, |
| 298 | Providers |
| 299 | >; |
| 300 | |
| 301 | /** |
| 302 | * A Cloudflare.AI. Search (formerly AutoRAG) instance — a fully managed |
| 303 | * retrieval-augmented generation pipeline over your own data. |
| 304 | * |
| 305 | * An instance continuously indexes a data source (an R2 bucket or a web |
| 306 | * crawl), embeds it into a managed Vectorize index, and answers search and |
| 307 | * chat queries against it. Creation returns immediately; the initial |
| 308 | * indexing run happens asynchronously. |
| 309 | * |
| 310 | * The instance `instanceId`, `namespace`, `type`, `source`, and |
| 311 | * `embeddingModel` are fixed at creation — changing any of them triggers a |
| 312 | * replacement. Everything else (models, chunking, caching, reranking, |
| 313 | * public endpoint, sync interval) is mutable in place. |
| 314 | * |
| 315 | * For the common R2 case, prefer the {@link Search} construct, which also |
| 316 | * mints the service token the indexer needs to read your bucket. Use this |
| 317 | * low-level resource directly when you manage the token yourself, share one |
| 318 | * token across instances, or group instances under a {@link SearchNamespace}. |
| 319 | * |
| 320 | * ### Creating a SearchInstance |
| 321 | * **Example:** R2-backed instance |
| 322 | * An R2 source needs a service token to read the bucket. Either pass a |
| 323 | * `tokenId` (see {@link SearchToken}) or let the {@link Search} |
| 324 | * construct provision one for you. |
| 325 | * ```typescript |
| 326 | * const bucket = yield* Cloudflare.R2.Bucket("docs", {}); |
| 327 | * const instance = yield* Cloudflare.AI.SearchInstance("docs-search", { |
| 328 | * source: bucket.bucketName, |
| 329 | * tokenId: serviceToken.id, |
| 330 | * }); |
| 331 | * ``` |
| 332 | * |
| 333 | * **Example:** Tuned retrieval settings |
| 334 | * ```typescript |
| 335 | * const instance = yield* Cloudflare.AI.SearchInstance("docs-search", { |
| 336 | * source: bucket.bucketName, |
| 337 | * aiSearchModel: "@cf/meta/llama-3.3-70b-instruct-fp8-fast", |
| 338 | * chunkSize: 512, |
| 339 | * chunkOverlap: 64, |
| 340 | * maxNumResults: 20, |
| 341 | * cache: true, |
| 342 | * cacheThreshold: "close_enough", |
| 343 | * }); |
| 344 | * ``` |
| 345 | * |
| 346 | * ### R2 source options |
| 347 | * For an `r2` source, `sourceParams` filters which objects are indexed (all |
| 348 | * fields optional): |
| 349 | * - `prefix` — only index keys under this prefix. |
| 350 | * - `includeItems` / `excludeItems` — micromatch glob patterns (`*` within a |
| 351 | * path segment, `**` across segments; max 10 each). Only objects matching an |
| 352 | * `includeItems` pattern are indexed; `excludeItems` takes precedence. |
| 353 | * - `r2Jurisdiction` — R2 data-residency jurisdiction of the source bucket. |
| 354 | * **Example:** Index only part of a bucket |
| 355 | * ```typescript |
| 356 | * const instance = yield* Cloudflare.AI.SearchInstance("docs-search", { |
| 357 | * source: bucket.bucketName, |
| 358 | * tokenId: serviceToken.id, |
| 359 | * sourceParams: { |
| 360 | * prefix: "docs/", |
| 361 | * includeItems: ["/docs/**"], |
| 362 | * excludeItems: ["/docs/drafts/**"], |
| 363 | * }, |
| 364 | * }); |
| 365 | * ``` |
| 366 | * |
| 367 | * ### Web-crawler source options |
| 368 | * `sourceParams.webCrawler` tunes how a `web-crawler` source is fetched, |
| 369 | * parsed, and stored. All fields are optional. |
| 370 | * |
| 371 | * `parseType` selects how pages are discovered: |
| 372 | * - `"sitemap"` (Cloudflare default) — read `<seed>/sitemap.xml` (discovered |
| 373 | * via `robots.txt`) and index the URLs it lists. |
| 374 | * - `"discover"` — start at `source` and follow links. |
| 375 | * |
| 376 | * `crawlOptions` is no longer accepted by the API — Cloudflare removed it; |
| 377 | * discovery behavior is controlled solely by `parseType`. |
| 378 | * |
| 379 | * `parseOptions` controls how each page is parsed: |
| 380 | * - `useBrowserRendering` — render JS in a headless browser before parsing. |
| 381 | * - `includeImages` — index image content. |
| 382 | * - `specificSitemaps` — explicit sitemap URLs to read (for `"sitemap"`). |
| 383 | * - `contentSelector` — `{ path, selector }[]` CSS selectors scoping which |
| 384 | * part of a page is indexed per URL path. |
| 385 | * - `includeHeaders` — extra request headers sent while crawling. |
| 386 | * |
| 387 | * `storeOptions` overrides where crawled content is stored — Cloudflare |
| 388 | * provisions managed storage by default: |
| 389 | * - `storageId` — R2 bucket name to store crawl output in. |
| 390 | * - `storageType` — `"r2"`. |
| 391 | * - `r2Jurisdiction` — R2 data-residency jurisdiction for the store bucket. |
| 392 | * **Example:** Basic web-crawler instance |
| 393 | * ```typescript |
| 394 | * const instance = yield* Cloudflare.AI.SearchInstance("site-search", { |
| 395 | * type: "web-crawler", |
| 396 | * source: "https://example.com", |
| 397 | * sourceParams: { webCrawler: { parseType: "discover" } }, |
| 398 | * }); |
| 399 | * ``` |
| 400 | * **Example:** Fully-configured crawl |
| 401 | * ```typescript |
| 402 | * const instance = yield* Cloudflare.AI.SearchInstance("site-search", { |
| 403 | * type: "web-crawler", |
| 404 | * source: "https://example.com", |
| 405 | * sourceParams: { |
| 406 | * webCrawler: { |
| 407 | * parseType: "discover", |
| 408 | * parseOptions: { |
| 409 | * useBrowserRendering: true, |
| 410 | * includeImages: false, |
| 411 | * contentSelector: [{ path: "/docs", selector: "main" }], |
| 412 | * }, |
| 413 | * }, |
| 414 | * }, |
| 415 | * }); |
| 416 | * ``` |
| 417 | * **Example:** Sitemap source |
| 418 | * ```typescript |
| 419 | * // Index the URLs listed in one or more sitemaps (the default parse mode). |
| 420 | * const fromSitemap = yield* Cloudflare.AI.SearchInstance("sitemap-search", { |
| 421 | * type: "web-crawler", |
| 422 | * source: "https://example.com", |
| 423 | * sourceParams: { |
| 424 | * webCrawler: { |
| 425 | * parseType: "sitemap", |
| 426 | * parseOptions: { specificSitemaps: ["https://example.com/sitemap.xml"] }, |
| 427 | * }, |
| 428 | * }, |
| 429 | * }); |
| 430 | * ``` |
| 431 | * **Example:** Store crawl output in a specific R2 bucket |
| 432 | * ```typescript |
| 433 | * const instance = yield* Cloudflare.AI.SearchInstance("site-search", { |
| 434 | * type: "web-crawler", |
| 435 | * source: "https://example.com", |
| 436 | * sourceParams: { |
| 437 | * webCrawler: { |
| 438 | * parseType: "discover", |
| 439 | * storeOptions: { storageId: "my-crawl-bucket", storageType: "r2" }, |
| 440 | * }, |
| 441 | * }, |
| 442 | * }); |
| 443 | * ``` |
| 444 | * |
| 445 | * ### Grouping under a namespace |
| 446 | * SearchInstances live in a namespace (the account-provided `default` when |
| 447 | * unspecified). Pass a {@link SearchNamespace}'s `name` to group related |
| 448 | * instances — the engine then orders this instance after the namespace on |
| 449 | * deploy. The namespace is immutable; changing it replaces the instance. |
| 450 | * **Example:** Place the instance in a custom namespace |
| 451 | * ```typescript |
| 452 | * const ns = yield* Cloudflare.AI.SearchNamespace("docs-ns", {}); |
| 453 | * const instance = yield* Cloudflare.AI.SearchInstance("docs-search", { |
| 454 | * source: bucket.bucketName, |
| 455 | * namespace: ns.name, |
| 456 | * }); |
| 457 | * ``` |
| 458 | * |
| 459 | * ### Binding to an Effect Worker |
| 460 | * Bind the instance during the Worker's init phase with |
| 461 | * `Cloudflare.AI.QuerySearch(instance)`, which attaches the |
| 462 | * single-instance `ai_search` binding and returns an Effect-native client |
| 463 | * whose `search` / `chatCompletions` methods return `Effect`s. Provide |
| 464 | * {@link QuerySearchBinding} in the Worker's runtime layer. |
| 465 | * **Example:** Effect Worker that answers from AI Search |
| 466 | * ```typescript |
| 467 | * import * as Cloudflare from "@alchemy.run/cloudflare"; |
| 468 | * import * as Effect from "effect/Effect"; |
| 469 | * import { HttpServerRequest } from "effect/http/HttpServerRequest"; |
| 470 | * import * as HttpServerResponse from "effect/http/HttpServerResponse"; |
| 471 | * |
| 472 | * export default class Api extends Cloudflare.Worker<Api>()( |
| 473 | * "api", |
| 474 | * { main: import.meta.url }, |
| 475 | * Effect.gen(function* () { |
| 476 | * const bucket = yield* Cloudflare.R2.Bucket("docs", {}); |
| 477 | * const instance = yield* Cloudflare.AI.SearchInstance("docs-search", { |
| 478 | * source: bucket.bucketName, |
| 479 | * }); |
| 480 | * const search = yield* Cloudflare.AI.QuerySearch(instance); |
| 481 | * |
| 482 | * return { |
| 483 | * fetch: Effect.gen(function* () { |
| 484 | * const request = yield* HttpServerRequest; |
| 485 | * const query = new URL(request.url).searchParams.get("q") ?? ""; |
| 486 | * const answer = yield* search.chatCompletions({ |
| 487 | * messages: [{ role: "user", content: query }], |
| 488 | * }); |
| 489 | * return yield* HttpServerResponse.json(answer); |
| 490 | * }), |
| 491 | * }; |
| 492 | * }).pipe(Effect.provide(Cloudflare.AI.QuerySearchBinding)), |
| 493 | * ) {} |
| 494 | * ``` |
| 495 | * |
| 496 | * ### Binding to an Async Worker |
| 497 | * For a vanilla `async fetch` Worker, pass the instance under `Worker.env`. |
| 498 | * The engine attaches the same `ai_search` binding and `InferEnv` types |
| 499 | * `env.SEARCH` as the runtime `SearchInstance` handle. |
| 500 | * **Example:** Async Worker via `env` |
| 501 | * ```typescript |
| 502 | * export const Api = Cloudflare.Worker("api", { |
| 503 | * main: "./worker.ts", |
| 504 | * env: { SEARCH: search }, |
| 505 | * }); |
| 506 | * export type ApiEnv = Cloudflare.InferEnv<typeof Api>; |
| 507 | * |
| 508 | * // worker.ts |
| 509 | * export default { |
| 510 | * async fetch(request: Request, env: ApiEnv): Promise<Response> { |
| 511 | * const query = new URL(request.url).searchParams.get("q") ?? ""; |
| 512 | * return Response.json( |
| 513 | * await env.SEARCH.chatCompletions({ |
| 514 | * messages: [{ role: "user", content: query }], |
| 515 | * }), |
| 516 | * ); |
| 517 | * }, |
| 518 | * }; |
| 519 | * ``` |
| 520 | * |
| 521 | * @see https://developers.cloudflare.com/ai-search/ |
| 522 | * |
| 523 | * @resource |
| 524 | * @product AI Search |
| 525 | * @category AI |
| 526 | */ |
| 527 | export const SearchInstance = Resource<SearchInstance>(TypeId, { |
| 528 | aliases: ["Cloudflare.AiSearch.Instance"], |
| 529 | }); |
| 530 | |
| 531 | /** |
| 532 | * Returns true if the given value is a SearchInstance resource. |
| 533 | */ |
| 534 | export const isSearchInstance = (value: unknown): value is SearchInstance => |
| 535 | isResourceOfType(value, TypeId); |
| 536 | |
| 537 | export const SearchInstanceProvider = () => |
| 538 | Provider.succeed(SearchInstance, { |
| 539 | stables: ["instanceId", "accountId", "namespace", "type", "embeddingModel", "createdAt"], |
| 540 | diff: Effect.fn(function* ({ id, olds, news, output }) { |
| 541 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 542 | if (!isResolved(news)) return undefined; |
| 543 | if ((output?.accountId ?? accountId) !== accountId) { |
| 544 | return { action: "replace" } as const; |
| 545 | } |
| 546 | // The namespace is immutable on the Cloudflare side (it is the API |
| 547 | // path) — moving an instance between namespaces is a replacement. The |
| 548 | // new instance lives at a different path, so create-before-delete is |
| 549 | // always safe here regardless of whether the id is pinned. |
| 550 | const newNamespace = resolveNamespace(news.namespace); |
| 551 | const oldNamespace = resolveNamespace(output?.namespace ?? olds.namespace); |
| 552 | if (newNamespace !== oldNamespace) { |
| 553 | return { action: "replace" } as const; |
| 554 | } |
| 555 | // The instance id is its identity — renaming is a replacement. |
| 556 | const oldId = output?.instanceId ?? (yield* createInstanceId(id, olds.instanceId)); |
| 557 | // Auto-generated ids are engine-owned: the deployed id stays |
| 558 | // authoritative even if the generator would name this id differently |
| 559 | // today. Only an explicit user-provided instanceId can force a replace. |
| 560 | const newId = news.instanceId ?? oldId; |
| 561 | if (newId !== oldId) { |
| 562 | return { action: "replace" } as const; |
| 563 | } |
| 564 | // When the user pinned an explicit `instanceId`, the replacement's |
| 565 | // create would collide with the still-existing old instance — the |
| 566 | // old one must be deleted first. Generated ids get a fresh suffix |
| 567 | // from the new SearchInstance ID, so create-before-delete is safe there. |
| 568 | const replace = { |
| 569 | action: "replace", |
| 570 | deleteFirst: news.instanceId !== undefined || undefined, |
| 571 | } as const; |
| 572 | // The data-source kind and location are fixed at creation; changing |
| 573 | // either requires re-indexing from scratch (a replacement). |
| 574 | if ((news.type ?? "r2") !== (output?.type ?? olds.type ?? "r2")) { |
| 575 | return replace; |
| 576 | } |
| 577 | const oldSource = output?.source ?? olds.source; |
| 578 | if (oldSource !== undefined && news.source !== oldSource) { |
| 579 | return replace; |
| 580 | } |
| 581 | // The embedding model defines the vector space and is immutable. |
| 582 | const oldEmbedding = normalize(output?.embeddingModel) ?? olds.embeddingModel; |
| 583 | if ( |
| 584 | news.embeddingModel !== undefined && |
| 585 | oldEmbedding !== undefined && |
| 586 | news.embeddingModel !== oldEmbedding |
| 587 | ) { |
| 588 | return replace; |
| 589 | } |
| 590 | return undefined; |
| 591 | }), |
| 592 | read: Effect.fn(function* ({ id, output, olds }) { |
| 593 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 594 | const acct = output?.accountId ?? accountId; |
| 595 | const namespace = resolveNamespace(output?.namespace ?? olds?.namespace); |
| 596 | // The id is deterministic (explicit prop or generated from the |
| 597 | // logical id + instance id), so a cold read (lost state) resolves |
| 598 | // the same identifier as the original create did. |
| 599 | const instanceId = output?.instanceId ?? (yield* createInstanceId(id, olds?.instanceId)); |
| 600 | const observed = yield* getInstance(acct, namespace, instanceId); |
| 601 | return observed ? toAttributes(observed, acct, namespace) : undefined; |
| 602 | }), |
| 603 | list: Effect.fn(function* () { |
| 604 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 605 | // SearchInstances are namespace-scoped, so enumerate every namespace |
| 606 | // (always including the account-provided `default`) and fan out a |
| 607 | // paginated instance list per namespace. |
| 608 | const namespaces = yield* aisearch.listNamespaces.pages({ accountId }).pipe( |
| 609 | Stream.runCollect, |
| 610 | Effect.map((chunk) => |
| 611 | Array.from(chunk).flatMap((page) => (page.result ?? []).map((ns) => ns.name)), |
| 612 | ), |
| 613 | ); |
| 614 | const allNamespaces = Array.from(new Set(["default", ...namespaces])); |
| 615 | const rows = yield* Effect.forEach( |
| 616 | allNamespaces, |
| 617 | (namespace) => |
| 618 | aisearch.listNamespaceInstances.pages({ accountId, namespace }).pipe( |
| 619 | Stream.runCollect, |
| 620 | Effect.map((chunk) => |
| 621 | Array.from(chunk).flatMap((page) => |
| 622 | (page.result ?? []).map((instance) => toAttributes(instance, accountId, namespace)), |
| 623 | ), |
| 624 | ), |
| 625 | // A namespace deleted between list and fan-out is simply empty. |
| 626 | Effect.catchTag("NamespaceNotFound", () => Effect.succeed([])), |
| 627 | ), |
| 628 | { concurrency: 5 }, |
| 629 | ); |
| 630 | return rows.flat(); |
| 631 | }), |
| 632 | reconcile: Effect.fn(function* ({ id, news, output }) { |
| 633 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 634 | const acct = output?.accountId ?? accountId; |
| 635 | const namespace = resolveNamespace(news.namespace); |
| 636 | const instanceId = output?.instanceId ?? (yield* createInstanceId(id, news.instanceId)); |
| 637 | |
| 638 | // Observe — `output.instanceId` is a cache, not a guarantee: a NotFound |
| 639 | // falls through to "missing" and we recreate. |
| 640 | let observed = yield* getInstance(acct, namespace, instanceId); |
| 641 | |
| 642 | if (!observed) { |
| 643 | // Ensure — greenfield (or out-of-band delete): create with the |
| 644 | // full desired body. If Cloudflare rejects the request because |
| 645 | // the instance already exists (a race), fall through to the |
| 646 | // sync path against the observed instance. |
| 647 | const ensured = yield* aisearch |
| 648 | .createNamespaceInstance({ |
| 649 | accountId: acct, |
| 650 | namespace, |
| 651 | id: instanceId, |
| 652 | type: news.type ?? "r2", |
| 653 | ...toMutableBody(news), |
| 654 | }) |
| 655 | .pipe( |
| 656 | // An out-of-band delete reads as missing while Cloudflare is |
| 657 | // still tearing the instance down; the same id can't be |
| 658 | // created until it finishes. |
| 659 | Effect.retry({ |
| 660 | while: (e) => e._tag === "InstanceDeletionInProgress", |
| 661 | schedule: Schedule.spaced("3 seconds"), |
| 662 | times: 20, |
| 663 | }), |
| 664 | retryTokenPropagation, |
| 665 | Effect.map((created) => ({ |
| 666 | created: true as const, |
| 667 | instance: created as ObservedInstance, |
| 668 | })), |
| 669 | Effect.catchTag("InstanceAlreadyExists", (originalError) => |
| 670 | Effect.gen(function* () { |
| 671 | const existing = yield* getInstance(acct, namespace, instanceId); |
| 672 | if (!existing) return yield* originalError; |
| 673 | return { created: false as const, instance: existing }; |
| 674 | }), |
| 675 | ), |
| 676 | ); |
| 677 | if (ensured.created) { |
| 678 | // Optionally kick off the initial index instead of waiting for |
| 679 | // the first scheduled sync. Best-effort and NOT awaited for |
| 680 | // completion — the deploy must not block on indexing (the |
| 681 | // scheduled sync is the backstop if this transiently fails). |
| 682 | if ((news.indexOnCreate ?? false) && news.source !== undefined) { |
| 683 | yield* aisearch |
| 684 | .createNamespaceInstanceJob({ |
| 685 | accountId: acct, |
| 686 | namespace, |
| 687 | id: instanceId, |
| 688 | }) |
| 689 | .pipe( |
| 690 | Effect.catch((error) => |
| 691 | Effect.logWarning( |
| 692 | "AI Search initial index job failed to start; the scheduled sync will index instead.", |
| 693 | error, |
| 694 | ), |
| 695 | ), |
| 696 | ); |
| 697 | } |
| 698 | // Indexing itself starts asynchronously; we deliberately do NOT |
| 699 | // wait for the first sync to finish. |
| 700 | return toAttributes(ensured.instance, acct, namespace); |
| 701 | } |
| 702 | observed = ensured.instance; |
| 703 | } |
| 704 | |
| 705 | // Sync — diff observed cloud state against the desired mutable |
| 706 | // config; skip the PUT entirely on a no-op. Only fields the user |
| 707 | // actually set participate in the diff; for the rest the observed |
| 708 | // value is preserved in the full PUT body. |
| 709 | const desired = toMutableBody(news); |
| 710 | const observedRecord = observed as unknown as Record<string, unknown>; |
| 711 | const dirty = Object.entries(desired).some( |
| 712 | ([key, value]) => |
| 713 | // Cloudflare's read projection always returns `tokenId: null` |
| 714 | // (the association is write-only), so it can never be diffed |
| 715 | // against desired — excluding it avoids perpetual false drift. |
| 716 | // It still rides along in the create body and in any update PUT |
| 717 | // triggered by other fields. |
| 718 | key !== "tokenId" && |
| 719 | value !== undefined && |
| 720 | !deepEqual(normalize(observedRecord[key]), normalize(value), { |
| 721 | stripNullish: true, |
| 722 | }), |
| 723 | ); |
| 724 | if (!dirty) { |
| 725 | return toAttributes(observed, acct, namespace); |
| 726 | } |
| 727 | |
| 728 | const updated = yield* aisearch |
| 729 | .updateNamespaceInstance({ |
| 730 | accountId: acct, |
| 731 | namespace, |
| 732 | id: instanceId, |
| 733 | ...preserveObserved(observed), |
| 734 | ...defined(desired), |
| 735 | }) |
| 736 | .pipe(retryTokenPropagation); |
| 737 | return toAttributes(updated, acct, namespace); |
| 738 | }), |
| 739 | delete: Effect.fn(function* ({ output }) { |
| 740 | // The managed Vectorize index is torn down asynchronously; a missing |
| 741 | // instance or namespace (already deleted) is success. |
| 742 | yield* aisearch |
| 743 | .deleteNamespaceInstance({ |
| 744 | accountId: output.accountId, |
| 745 | namespace: output.namespace, |
| 746 | id: output.instanceId, |
| 747 | }) |
| 748 | .pipe( |
| 749 | Effect.catchTag(["AiSearchInstanceNotFound", "NamespaceNotFound"], () => Effect.void), |
| 750 | ); |
| 751 | }), |
| 752 | }); |
| 753 | |
| 754 | /** |
| 755 | * Ride out the two eventual-consistency windows Cloudflare opens when an |
| 756 | * instance's source is (re)validated at create/update time: |
| 757 | * |
| 758 | * - `InvalidTokenCredentials` (code 7012, message |
| 759 | * `ai_search_instance_invalid_token`): on a greenfield create Cloudflare |
| 760 | * auto-provisions an R2 service token for the instance to read its source |
| 761 | * bucket, and validates it eventually-consistently. |
| 762 | * - `MissingSitemap` (400, message `missing_sitemap`): a `web-crawler` |
| 763 | * source is fetched synchronously at validation time. A freshly-deployed |
| 764 | * seed (e.g. a brand-new `workers.dev` URL) is reachable from the test's |
| 765 | * own vantage well before Cloudflare's crawler infrastructure can fetch |
| 766 | * it, so the first validation can spuriously report no content. |
| 767 | * |
| 768 | * Both settle within a bounded window; a genuinely invalid token or |
| 769 | * unreachable/empty seed still fails once the retries are exhausted. |
| 770 | */ |
| 771 | const retryTokenPropagation = <A, E extends { _tag: string }, R>(effect: Effect.Effect<A, E, R>) => |
| 772 | effect.pipe( |
| 773 | Effect.retry({ |
| 774 | while: (e) => e._tag === "InvalidTokenCredentials" || e._tag === "MissingSitemap", |
| 775 | // A full-body update PUT re-sends `source`, which makes Cloudflare |
| 776 | // re-validate the (write-only, auto-provisioned) R2 service token and |
| 777 | // re-fetch a web-crawler seed — opening a fresh propagation window each |
| 778 | // time. The window stretches under full-suite parallel load (token |
| 779 | // propagation across the edge contends with every other test's calls), |
| 780 | // so the budget is generous (~2 min). Crucially the per-attempt delay is |
| 781 | // *capped* at 6s (`either` takes the min of the two schedules): an |
| 782 | // uncapped exponential balloons to ~38s gaps by attempt 10, so it polls |
| 783 | // sparsely and detects a settled token tens of seconds late. Capped |
| 784 | // polling detects within 6s of propagation completing while still |
| 785 | // covering a long total window. |
| 786 | schedule: Schedule.min([Schedule.exponential("1 second", 1.5), Schedule.spaced("6 seconds")]), |
| 787 | times: 22, |
| 788 | }), |
| 789 | ); |
| 790 | |
| 791 | type ObservedInstance = aisearch.ReadNamespaceInstanceResponse; |
| 792 | |
| 793 | /** |
| 794 | * Resolve the namespace name an instance lives in, defaulting to the |
| 795 | * account-provided `default` namespace. |
| 796 | */ |
| 797 | const resolveNamespace = (namespace: string | undefined): string => namespace ?? "default"; |
| 798 | |
| 799 | /** |
| 800 | * Read an instance by id within its namespace, mapping "gone" to |
| 801 | * `undefined` — either the instance is missing (`AiSearchInstanceNotFound`, |
| 802 | * code 7002) or its whole namespace is (`NamespaceNotFound`, code 7063). |
| 803 | */ |
| 804 | const getInstance = (accountId: string, namespace: string, id: string) => |
| 805 | aisearch |
| 806 | .readNamespaceInstance({ accountId, namespace, id }) |
| 807 | .pipe( |
| 808 | Effect.catchTag(["AiSearchInstanceNotFound", "NamespaceNotFound"], () => Effect.undefined), |
| 809 | ); |
| 810 | |
| 811 | const createInstanceId = (id: string, instanceId: string | undefined) => |
| 812 | Effect.gen(function* () { |
| 813 | return instanceId ?? (yield* createPhysicalName({ id, lowercase: true })); |
| 814 | }); |
| 815 | |
| 816 | /** |
| 817 | * Cloudflare returns `null` (and sometimes `""` for model enums) for |
| 818 | * unconfigured optional fields; desired-state shapes leave them |
| 819 | * `undefined`. Collapse both to `undefined` for diffing. |
| 820 | */ |
| 821 | const normalize = <T>(value: T | "" | null | undefined): T | undefined => |
| 822 | value === "" || value == null ? undefined : value; |
| 823 | |
| 824 | type MutableBody = ReturnType<typeof toMutableBody>; |
| 825 | |
| 826 | /** |
| 827 | * The mutable slice of the desired state, shaped for the create/update |
| 828 | * request bodies. Immutable props (`id`, `type`) are handled separately. |
| 829 | */ |
| 830 | const toMutableBody = (news: SearchInstanceProps) => ({ |
| 831 | source: news.source as string, |
| 832 | sourceParams: news.sourceParams, |
| 833 | tokenId: news.tokenId as string | undefined, |
| 834 | aiGatewayId: news.aiGatewayId as string | undefined, |
| 835 | embeddingModel: news.embeddingModel, |
| 836 | aiSearchModel: news.aiSearchModel, |
| 837 | rewriteQuery: news.rewriteQuery, |
| 838 | rewriteModel: news.rewriteModel, |
| 839 | chunk: news.chunk, |
| 840 | chunkSize: news.chunkSize, |
| 841 | chunkOverlap: news.chunkOverlap, |
| 842 | indexMethod: news.indexMethod, |
| 843 | indexingOptions: news.indexingOptions, |
| 844 | customMetadata: news.customMetadata, |
| 845 | cache: news.cache, |
| 846 | cacheThreshold: news.cacheThreshold, |
| 847 | cacheTtl: news.cacheTtl, |
| 848 | reranking: news.reranking, |
| 849 | rerankingModel: news.rerankingModel, |
| 850 | retrievalOptions: news.retrievalOptions, |
| 851 | fusionMethod: news.fusionMethod, |
| 852 | maxNumResults: news.maxNumResults, |
| 853 | scoreThreshold: news.scoreThreshold, |
| 854 | publicEndpointParams: news.publicEndpointParams, |
| 855 | syncInterval: news.syncInterval, |
| 856 | }); |
| 857 | |
| 858 | /** |
| 859 | * The update API is a PUT — fields the user did not set are preserved by |
| 860 | * sending the observed values back. Observed `null`s are omitted (the |
| 861 | * field was never configured). |
| 862 | */ |
| 863 | const preserveObserved = (observed: ObservedInstance) => |
| 864 | defined({ |
| 865 | source: normalize(observed.source), |
| 866 | sourceParams: normalize(observed.sourceParams), |
| 867 | tokenId: normalize(observed.tokenId), |
| 868 | aiGatewayId: normalize(observed.aiGatewayId), |
| 869 | embeddingModel: normalize(observed.embeddingModel), |
| 870 | aiSearchModel: normalize(observed.aiSearchModel), |
| 871 | rewriteQuery: normalize(observed.rewriteQuery), |
| 872 | rewriteModel: normalize(observed.rewriteModel), |
| 873 | chunkSize: normalize(observed.chunkSize), |
| 874 | chunkOverlap: normalize(observed.chunkOverlap), |
| 875 | indexMethod: normalize(observed.indexMethod), |
| 876 | indexingOptions: normalize(observed.indexingOptions), |
| 877 | customMetadata: normalize(observed.customMetadata), |
| 878 | cache: normalize(observed.cache), |
| 879 | cacheThreshold: normalize(observed.cacheThreshold), |
| 880 | cacheTtl: normalize(observed.cacheTtl), |
| 881 | reranking: normalize(observed.reranking), |
| 882 | rerankingModel: normalize(observed.rerankingModel), |
| 883 | retrievalOptions: normalize(observed.retrievalOptions), |
| 884 | fusionMethod: normalize(observed.fusionMethod), |
| 885 | maxNumResults: normalize(observed.maxNumResults), |
| 886 | scoreThreshold: normalize(observed.scoreThreshold), |
| 887 | publicEndpointParams: normalize(observed.publicEndpointParams), |
| 888 | syncInterval: normalize(observed.syncInterval), |
| 889 | }) as Partial<MutableBody>; |
| 890 | |
| 891 | /** Strip `undefined` entries so they don't override spread order. */ |
| 892 | const defined = <T extends Record<string, unknown>>(value: T): Partial<T> => |
| 893 | Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined)) as Partial<T>; |
| 894 | |
| 895 | /** |
| 896 | * The instance fields `read` projects, common to the create / read / |
| 897 | * update / list-item response shapes (all optional but `id`). Decoupling |
| 898 | * from the exact distilled response unions lets the namespace-scoped list |
| 899 | * items — which carry a reduced field set — flow through unchanged. |
| 900 | */ |
| 901 | type SearchInstanceLike = { |
| 902 | id: string; |
| 903 | type?: string | null; |
| 904 | source?: string | null; |
| 905 | tokenId?: string | null; |
| 906 | aiGatewayId?: string | null; |
| 907 | embeddingModel?: string | null; |
| 908 | aiSearchModel?: string | null; |
| 909 | status?: string | null; |
| 910 | paused?: boolean | null; |
| 911 | publicEndpointId?: string | null; |
| 912 | createdAt?: string | null; |
| 913 | modifiedAt?: string | null; |
| 914 | }; |
| 915 | |
| 916 | const toAttributes = ( |
| 917 | instance: SearchInstanceLike, |
| 918 | accountId: string, |
| 919 | namespace: string, |
| 920 | ): SearchInstanceAttributes => ({ |
| 921 | instanceId: instance.id, |
| 922 | accountId, |
| 923 | namespace, |
| 924 | // Distilled widens generated string enums to open unions. |
| 925 | type: (normalize(instance.type) ?? "r2") as SearchInstanceSourceType, |
| 926 | source: normalize(instance.source), |
| 927 | tokenId: normalize(instance.tokenId), |
| 928 | aiGatewayId: normalize(instance.aiGatewayId), |
| 929 | embeddingModel: normalize(instance.embeddingModel), |
| 930 | aiSearchModel: normalize(instance.aiSearchModel), |
| 931 | status: normalize(instance.status), |
| 932 | paused: instance.paused ?? undefined, |
| 933 | publicEndpointId: normalize(instance.publicEndpointId), |
| 934 | createdAt: normalize(instance.createdAt), |
| 935 | modifiedAt: normalize(instance.modifiedAt), |
| 936 | }); |