The best way to control Claude Code, Codex and more from any computer or phone

main
ts 936 lines 34.3 KB
Raw
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 });