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

main
ts 338 lines 12.2 KB
Raw
1 import * as aisearch from "@distilled.cloud/cloudflare/aisearch";
2 import { isResolved } from "alchemy/Diff";
3 import { createPhysicalName } from "alchemy/PhysicalName";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Effect from "effect/Effect";
7 import * as Option from "effect/Option";
8 import * as Predicate from "effect/Predicate";
9 import * as Redacted from "effect/Redacted";
10 import * as Schedule from "effect/Schedule";
11 import * as Stream from "effect/Stream";
12 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
13 import type { Providers } from "../Providers.ts";
14
15 const TypeId = "Cloudflare.AI.SearchToken" as const;
16 type TypeId = typeof TypeId;
17
18 export type SearchTokenProps = {
19 /**
20 * Display name for the service token. Mutable in place.
21 * If omitted, a unique name is generated from the app, stage, and
22 * logical ID.
23 * @default ${app}-${id}-${stage}-${suffix}
24 */
25 name?: string;
26 /**
27 * Id of the underlying Cloudflare API token AI Search authenticates
28 * with when syncing the data source. The token must carry the
29 * "AI Search Index Engine" permission group — Cloudflare validates it
30 * on create/update and rejects tokens without it.
31 */
32 cfApiId: string;
33 /**
34 * Plaintext value of the underlying Cloudflare API token. Write-only —
35 * Cloudflare never returns it, so rotation is detected against the
36 * previously-persisted props rather than observed cloud state.
37 */
38 cfApiKey: Redacted.Redacted<string>;
39 /**
40 * Whether this is a legacy (account-level instance) token.
41 * @default false
42 */
43 legacy?: boolean;
44 };
45
46 export type TokenAttributes = {
47 /**
48 * AI Search service token id (a UUID). Stable across updates.
49 */
50 id: string;
51 /**
52 * The Cloudflare account the token belongs to.
53 */
54 accountId: string;
55 /**
56 * Display name of the service token.
57 */
58 name: string;
59 /**
60 * Id of the underlying Cloudflare API token.
61 */
62 cfApiId: string;
63 /**
64 * Whether the token is enabled.
65 */
66 enabled: boolean | undefined;
67 /**
68 * Whether this is a legacy (account-level instance) token.
69 */
70 legacy: boolean | undefined;
71 /**
72 * When the token was created.
73 */
74 createdAt: string | undefined;
75 /**
76 * When the token was last modified.
77 */
78 modifiedAt: string | undefined;
79 /**
80 * Who created the token.
81 */
82 createdBy: string | undefined;
83 /**
84 * Who last modified the token.
85 */
86 modifiedBy: string | undefined;
87 };
88
89 export type SearchToken = Resource<TypeId, SearchTokenProps, TokenAttributes, never, Providers>;
90
91 /**
92 * A Cloudflare.AI. Search service token — the credential AI Search uses to
93 * access your data source (R2 bucket, Vectorize index, Workers AI) when
94 * indexing.
95 *
96 * The token wraps an existing Cloudflare API token (`cfApiId` +
97 * `cfApiKey`). That API token must carry the "AI Search Index Engine"
98 * permission group — Cloudflare validates the credential on create and
99 * update and rejects tokens without it. Pair it with
100 * `Cloudflare.ApiToken.AccountApiToken` to mint the underlying API token in the
101 * same stack, then reference the service token's `id` from an AI Search
102 * instance's `tokenId` prop.
103 * ### Creating a Token
104 * **Example:** Minting the underlying API token in the same stack
105 * ```typescript
106 * const apiToken = yield* Cloudflare.ApiToken.AccountApiToken("SearchTokenSource", {
107 * policies: [
108 * {
109 * effect: "allow",
110 * permissionGroups: ["AI Search Index Engine"],
111 * resources: { [`com.cloudflare.api.account.${accountId}`]: "*" },
112 * },
113 * ],
114 * });
115 * const token = yield* Cloudflare.AI.SearchToken("SearchToken", {
116 * cfApiId: apiToken.tokenId,
117 * cfApiKey: apiToken.value,
118 * });
119 * ```
120 *
121 * ### Using the Token from a SearchInstance
122 * **Example:** Wiring the token into an AI Search instance
123 * ```typescript
124 * const search = yield* Cloudflare.AI.Search("Search", {
125 * source: bucket,
126 * tokenId: token.id,
127 * });
128 * ```
129 *
130 * @see https://developers.cloudflare.com/ai-search/
131 *
132 * @resource
133 * @product AI Search
134 * @category AI
135 */
136 export const SearchToken = Resource<SearchToken>(TypeId, {
137 aliases: ["Cloudflare.AiSearch.Token"],
138 });
139
140 /**
141 * Returns true if the given value is a SearchToken resource.
142 */
143 export const isSearchToken = (value: unknown): value is SearchToken =>
144 Predicate.hasProperty(value, "Type") && value.Type === TypeId;
145
146 export const SearchTokenProvider = () =>
147 Provider.succeed(SearchToken, {
148 stables: ["id", "accountId", "createdAt", "createdBy"],
149 diff: Effect.fn(function* ({ news, output }) {
150 const { accountId } = yield* yield* CloudflareEnvironment;
151 if (!isResolved(news)) return undefined;
152 if ((output?.accountId ?? accountId) !== accountId) {
153 return { action: "replace" } as const;
154 }
155 // Everything (name, credentials, legacy flag) is mutable via PUT —
156 // let the engine apply its default update logic.
157 return undefined;
158 }),
159 read: Effect.fn(function* ({ id, output, olds }) {
160 const { accountId } = yield* yield* CloudflareEnvironment;
161 const acct = output?.accountId ?? accountId;
162 const observed = output?.id
163 ? yield* getToken(acct, output.id)
164 : // Cold read (lost state): the display name is deterministic, so
165 // scan the token list for it.
166 yield* findTokenByName(acct, yield* createTokenName(id, olds?.name));
167 return observed ? toAttributes(observed, acct) : undefined;
168 }),
169 reconcile: Effect.fn(function* ({ id, news, olds, output }) {
170 const { accountId } = yield* yield* CloudflareEnvironment;
171 const acct = output?.accountId ?? accountId;
172 const name = yield* createTokenName(id, news.name);
173
174 // Observe — `output.id` is a cache, not a guarantee: a missing
175 // token falls through to "missing" and we recreate. Without an id
176 // (greenfield or adoption-by-name), scan the list for the
177 // deterministic display name.
178 const observed = output?.id
179 ? yield* getToken(acct, output.id)
180 : yield* findTokenByName(acct, name);
181
182 const body = {
183 name,
184 cfApiId: news.cfApiId as string,
185 cfApiKey: Redacted.value(news.cfApiKey as Redacted.Redacted<string>),
186 // Cloudflare defaults an omitted `legacy` to `true`, and legacy
187 // (account-level instance) tokens cannot be managed via the per-token
188 // routes — GET/DELETE `/ai-search/tokens/{id}` return 401, so they can
189 // never be read or deleted, leaking on every teardown. Force
190 // non-legacy unless the caller explicitly opts in.
191 legacy: news.legacy ?? false,
192 };
193
194 if (!observed) {
195 // Ensure — create with the full desired body. A freshly minted
196 // underlying API token propagates eventually-consistently, so a
197 // transient `InvalidTokenCredentials` (code 7012) is retried
198 // briefly before being treated as a real validation failure.
199 const created = yield* aisearch
200 .createToken({ accountId: acct, ...body })
201 .pipe(retryTokenPropagation);
202 return toAttributes(created, acct);
203 }
204
205 // Sync — Cloudflare never returns `cfApiKey`, so the secret cannot
206 // be diffed against observed state; fall back to the previously
207 // persisted props for the key only. Everything else diffs against
208 // the observed cloud state.
209 const keyRotated =
210 olds === undefined ||
211 olds.cfApiKey === undefined ||
212 !isResolved(olds.cfApiKey) ||
213 Redacted.value(olds.cfApiKey) !== body.cfApiKey;
214 const dirty =
215 keyRotated ||
216 observed.name !== name ||
217 observed.cfApiId !== body.cfApiId ||
218 (news.legacy !== undefined && (observed.legacy ?? undefined) !== news.legacy);
219 if (!dirty) {
220 return toAttributes(observed, acct);
221 }
222
223 // The update is a PUT and always requires the full credential pair.
224 const updated = yield* aisearch
225 .updateToken({ accountId: acct, id: observed.id, ...body })
226 .pipe(retryTokenPropagation);
227 return toAttributes(updated, acct);
228 }),
229 list: () =>
230 // Service tokens are account-scoped (`/accounts/{id}/ai-search/tokens`),
231 // not nested under an instance — one paginated list per account.
232 Effect.gen(function* () {
233 const { accountId } = yield* yield* CloudflareEnvironment;
234 return yield* aisearch.listTokens.pages({ accountId, perPage: 50 }).pipe(
235 Stream.runCollect,
236 Effect.map((chunk) =>
237 Array.from(chunk).flatMap((page) =>
238 // The list item shape matches the create/read response, so the
239 // emitted Attributes are identical to `read` (the write-only
240 // `cfApiKey` is never part of Attributes anyway).
241 (page.result ?? []).map((t) => toAttributes(t, accountId)),
242 ),
243 ),
244 // AI Search isn't enabled on every account — the route is gated
245 // rather than returning an empty list. Treat it as "none".
246 Effect.catchTag("InvalidRoute", () => Effect.succeed([])),
247 );
248 }),
249 delete: Effect.fn(function* ({ output }) {
250 // A missing token (already deleted) is success. An AI Search
251 // instance that referenced this token may still be deleting
252 // asynchronously — Cloudflare rejects the delete with
253 // `token_in_use_by_instances` until the instance is gone, so ride
254 // that out briefly.
255 yield* aisearch.deleteToken({ accountId: output.accountId, id: output.id }).pipe(
256 Effect.retry({
257 while: (e) => e._tag === "TokenInUseByInstances",
258 // Allow brief asynchronous teardown, but surface a token still
259 // referenced by another instance instead of stalling cleanup.
260 schedule: Schedule.spaced("5 seconds"),
261 times: 8,
262 }),
263 Effect.catchTag("TokenNotFound", () => Effect.void),
264 );
265 }),
266 });
267
268 type ObservedToken = aisearch.CreateTokenResponse;
269
270 /**
271 * Read a token by id, mapping "gone" (`TokenNotFound`, Cloudflare error
272 * code 7075) to `undefined`. The read response declares every field
273 * optional, so observed identity fields are re-asserted from the request.
274 */
275 const getToken = (accountId: string, id: string) =>
276 aisearch.readToken({ accountId, id }).pipe(
277 Effect.map((t): ObservedToken => ({
278 id: t.id ?? id,
279 name: t.name ?? "",
280 cfApiId: t.cfApiId ?? "",
281 createdAt: t.createdAt ?? "",
282 modifiedAt: t.modifiedAt ?? "",
283 createdBy: t.createdBy,
284 enabled: t.enabled,
285 legacy: t.legacy,
286 modifiedBy: t.modifiedBy,
287 })),
288 Effect.catchTag("TokenNotFound", () => Effect.undefined),
289 );
290
291 /**
292 * Scan the account's service tokens for an exact display-name match
293 * (used for cold reads and greenfield creates after lost state). The
294 * `search` query param chokes on long strings (generated physical names
295 * can hit the limit), so this streams all pages and filters client-side.
296 */
297 const findTokenByName = (accountId: string, name: string) =>
298 aisearch.listTokens.items({ accountId, perPage: 50 }).pipe(
299 Stream.filter((t) => t.name === name),
300 Stream.runHead,
301 Effect.map(Option.getOrUndefined),
302 );
303
304 const createTokenName = (id: string, name: string | undefined) =>
305 Effect.gen(function* () {
306 return name ?? (yield* createPhysicalName({ id, lowercase: true }));
307 });
308
309 /**
310 * A freshly minted underlying API token may not have propagated yet when
311 * AI Search validates it — ride out transient `InvalidTokenCredentials`
312 * (code 7012) with a short, bounded retry. Genuinely invalid credentials
313 * still fail after the retries are exhausted.
314 */
315 const retryTokenPropagation = <A, E extends { _tag: string }, R>(effect: Effect.Effect<A, E, R>) =>
316 effect.pipe(
317 Effect.retry({
318 while: (e) => e._tag === "InvalidTokenCredentials",
319 schedule: Schedule.exponential("1 second"),
320 times: 6,
321 }),
322 );
323
324 const toAttributes = (
325 token: ObservedToken | aisearch.UpdateTokenResponse,
326 accountId: string,
327 ): TokenAttributes => ({
328 id: token.id,
329 accountId,
330 name: token.name,
331 cfApiId: token.cfApiId,
332 enabled: token.enabled ?? undefined,
333 legacy: token.legacy ?? undefined,
334 createdAt: token.createdAt || undefined,
335 modifiedAt: token.modifiedAt || undefined,
336 createdBy: token.createdBy ?? undefined,
337 modifiedBy: token.modifiedBy ?? undefined,
338 });