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

main
ts 432 lines 15.2 KB
Raw
1 import * as aiGateway from "@distilled.cloud/cloudflare/ai-gateway";
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 Predicate from "effect/Predicate";
8 import * as Schedule from "effect/Schedule";
9 import * as Stream from "effect/Stream";
10 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
11 import type { Providers } from "../Providers.ts";
12
13 const TypeId = "Cloudflare.AI.GatewayProvider" as const;
14 type TypeId = typeof TypeId;
15
16 export type GatewayProviderProps = {
17 /**
18 * The AI Gateway the provider config (BYOK key) belongs to. The gateway
19 * must have its `storeId` set to a Secrets Store id — Cloudflare resolves
20 * the key inside that store. Changing the gateway triggers a replacement.
21 */
22 gatewayId: string;
23 /**
24 * The upstream provider the key authenticates against (e.g. `openai`,
25 * `anthropic`, `workers-ai`). Changing the provider triggers a
26 * replacement.
27 */
28 providerSlug: string;
29 /**
30 * Alias distinguishing multiple keys for the same provider. If omitted, a
31 * unique name is generated from the app, stage, and logical ID.
32 *
33 * Cloudflare requires the referenced Secrets Store secret to be named
34 * exactly `{gatewayId}_{providerSlug}_{alias}` and scoped to
35 * `ai_gateway`. Changing the alias triggers a replacement.
36 * @default ${app}-${stage}-${id}
37 */
38 alias?: string;
39 /**
40 * The Secrets Store secret holding the provider API key. The secret must
41 * live in the gateway's `storeId` store, be scoped to `ai_gateway`, and
42 * be named `{gatewayId}_{providerSlug}_{alias}`. Changing the secret
43 * triggers a replacement.
44 */
45 secretId: string;
46 /**
47 * Whether this key is the gateway's default credential for the provider
48 * (used when a request does not name a specific key).
49 * @default false
50 */
51 defaultConfig?: boolean;
52 /**
53 * Maximum number of requests allowed per `rateLimitPeriod` through this
54 * key. Omit for no limit. Changing the limit triggers a replacement
55 * (Cloudflare exposes no update API for provider configs).
56 */
57 rateLimit?: number;
58 /**
59 * The rate limit window in seconds.
60 * @default 60
61 */
62 rateLimitPeriod?: number;
63 };
64
65 export type GatewayProviderAttributes = {
66 /**
67 * Server-generated gateway provider identifier.
68 */
69 providerConfigId: string;
70 /**
71 * The Cloudflare account the gateway provider belongs to.
72 */
73 accountId: string;
74 /**
75 * The AI Gateway the gateway provider belongs to.
76 */
77 gatewayId: string;
78 /**
79 * Alias distinguishing multiple keys for the same provider.
80 */
81 alias: string;
82 /**
83 * The upstream provider the key authenticates against.
84 */
85 providerSlug: string;
86 /**
87 * The Secrets Store secret holding the gateway provider API key.
88 */
89 secretId: string;
90 /**
91 * Masked preview of the secret value.
92 */
93 secretPreview: string;
94 /**
95 * Whether this key is the gateway's default credential for the gateway provider.
96 */
97 defaultConfig: boolean;
98 /**
99 * Maximum number of requests allowed per `rateLimitPeriod`, if limited, for the gateway provider.
100 */
101 rateLimit: number | undefined;
102 /**
103 * The rate limit window in seconds for the gateway provider.
104 */
105 rateLimitPeriod: number | undefined;
106 /**
107 * When the gateway provider was last modified.
108 */
109 modifiedAt: string;
110 };
111
112 export type GatewayProvider = Resource<
113 TypeId,
114 GatewayProviderProps,
115 GatewayProviderAttributes,
116 never,
117 Providers
118 >;
119
120 /**
121 * A BYOK (bring-your-own-key) provider credential on a Cloudflare AI
122 * Gateway.
123 *
124 * Provider configs let the gateway authenticate against upstream model
125 * providers (OpenAI, Anthropic, Workers AI, ...) with your own API key,
126 * stored in Cloudflare Secrets Store. Cloudflare exposes no update API for
127 * provider configs, so every prop change replaces the config (the old one
128 * is deleted first — a gateway allows only one config per provider slug
129 * and alias).
130 *
131 * Cloudflare imposes a strict naming contract: the gateway must reference a
132 * Secrets Store via its `storeId`, and the secret must be scoped to
133 * `ai_gateway` and named exactly `{gatewayId}_{providerSlug}_{alias}`.
134 * ### Creating a Provider Config
135 * **Example:** Bring your own OpenAI key
136 * ```typescript
137 * const store = yield* Cloudflare.SecretsStore.Store("Store");
138 *
139 * const gateway = yield* Cloudflare.AI.Gateway("Gateway", {
140 * id: "my-gateway",
141 * storeId: store.storeId,
142 * });
143 *
144 * // The secret name must be `{gatewayId}_{providerSlug}_{alias}`.
145 * // Prefer `Cloudflare.AI.ProviderKey` to wire this secret automatically.
146 * const secret = yield* Cloudflare.SecretsStore.Secret("OpenAiKey", {
147 * store,
148 * name: "my-gateway_openai_default",
149 * value: yield* Config.Redacted("OPENAI_API_KEY"),
150 * scopes: ["ai_gateway"],
151 * });
152 *
153 * const byok = yield* Cloudflare.AI.GatewayProvider("OpenAi", {
154 * gatewayId: gateway.gatewayId,
155 * providerSlug: "openai",
156 * alias: "default",
157 * secretId: secret.secretId,
158 * defaultConfig: true,
159 * });
160 * ```
161 *
162 * **Example:** Rate-limit a key
163 * ```typescript
164 * const byok = yield* Cloudflare.AI.GatewayProvider("OpenAi", {
165 * gatewayId: gateway.gatewayId,
166 * providerSlug: "openai",
167 * alias: "default",
168 * secretId: secret.secretId,
169 * rateLimit: 100,
170 * rateLimitPeriod: 60,
171 * });
172 * ```
173 *
174 * @see https://developers.cloudflare.com/ai-gateway/configuration/bring-your-own-keys/
175 *
176 * @resource
177 * @product AI Gateway
178 * @category AI
179 */
180 export const GatewayProvider = Resource<GatewayProvider>(TypeId, {
181 aliases: ["Cloudflare.AiGateway.ProviderConfig"],
182 });
183
184 /**
185 * Returns true if the given value is a GatewayProvider resource.
186 */
187 export const isGatewayProvider = (value: unknown): value is GatewayProvider =>
188 Predicate.hasProperty(value, "Type") && value.Type === TypeId;
189
190 export const GatewayProviderProvider = () =>
191 Provider.succeed(GatewayProvider, {
192 stables: ["providerConfigId", "accountId", "gatewayId"],
193 diff: Effect.fn(function* ({ news, output }) {
194 if (!isResolved(news)) return undefined;
195 const { accountId } = yield* yield* CloudflareEnvironment;
196 if ((output?.accountId ?? accountId) !== accountId) {
197 return { action: "replace", deleteFirst: true } as const;
198 }
199 if (output === undefined) return undefined;
200 // Provider configs have no update API — any change is a replacement.
201 // Delete first: a gateway rejects a second config for the same
202 // provider slug/alias with "already exists".
203 // Auto-generated aliases are engine-owned: the deployed alias stays
204 // authoritative even if the generator would name this id differently
205 // today. Only an explicit user-provided alias can force a replace.
206 const newAlias = news.alias ?? output.alias;
207 if (
208 output.gatewayId !== news.gatewayId ||
209 output.providerSlug !== news.providerSlug ||
210 output.alias !== newAlias ||
211 output.secretId !== news.secretId ||
212 output.defaultConfig !== (news.defaultConfig ?? false) ||
213 output.rateLimit !== news.rateLimit ||
214 (output.rateLimitPeriod ?? 60) !== (news.rateLimitPeriod ?? 60)
215 ) {
216 return { action: "replace", deleteFirst: true } as const;
217 }
218 return undefined;
219 }),
220 read: Effect.fn(function* ({ id, olds, output }) {
221 const { accountId } = yield* yield* CloudflareEnvironment;
222 const acct = output?.accountId ?? accountId;
223 const gatewayId = output?.gatewayId ?? (olds?.gatewayId as string | undefined);
224 if (gatewayId === undefined) return undefined;
225
226 const configs = yield* listProviderConfigs(acct, gatewayId);
227 // Cold read — recover from lost state by matching the
228 // deterministic alias.
229 const findConfigByAlias = Effect.gen(function* () {
230 const alias = yield* createAlias(id, olds?.alias);
231 return configs.find((c) => c.alias === alias && c.providerSlug === olds?.providerSlug);
232 });
233 const match = output?.providerConfigId
234 ? configs.find((c) => c.id === output.providerConfigId)
235 : yield* findConfigByAlias;
236 return match ? toAttributes(match, acct) : undefined;
237 }),
238 reconcile: Effect.fn(function* ({ id, news, output }) {
239 const { accountId } = yield* yield* CloudflareEnvironment;
240 // An explicit user-provided alias always wins (an alias change can
241 // reach reconcile as an update when diff saw unresolved inputs, e.g.
242 // a secretId still pending from a same-deploy secret replacement).
243 // Absent that, prefer the deployed alias: regenerating would target a
244 // different resource if the generator's output for this id ever
245 // drifts.
246 const alias = news.alias ?? output?.alias ?? (yield* createAlias(id, undefined));
247 return yield* reconcileProviderConfig({
248 accountId,
249 gatewayId: news.gatewayId as string,
250 alias,
251 providerSlug: news.providerSlug as string,
252 secretId: news.secretId as string,
253 defaultConfig: news.defaultConfig ?? false,
254 rateLimit: news.rateLimit,
255 rateLimitPeriod: news.rateLimitPeriod,
256 currentId: output?.providerConfigId,
257 });
258 }),
259 delete: Effect.fn(function* ({ output }) {
260 yield* aiGateway
261 .deleteProviderConfig({
262 accountId: output.accountId,
263 gatewayId: output.gatewayId,
264 id: output.providerConfigId,
265 })
266 // Cloudflare reports both a missing config and a missing parent
267 // gateway with code 7002 — either way it's already gone.
268 .pipe(Effect.catchTag("ProviderConfigNotFound", () => Effect.void));
269 }),
270 // Provider configs are nested under an AI Gateway, with no account-wide
271 // collection endpoint. Enumerate every gateway in the account, then fan
272 // out (bounded) over them and exhaustively paginate each gateway's
273 // provider configs, hydrating each item into the same Attributes shape
274 // `read` produces (via `toAttributes`). A gateway that disappears between
275 // enumeration and listing returns an empty list, so no per-item not-found
276 // mapping is needed.
277 list: Effect.fn(function* () {
278 const { accountId } = yield* yield* CloudflareEnvironment;
279
280 const gatewayIds = yield* aiGateway.listAiGateways.pages({ accountId }).pipe(
281 Stream.runCollect,
282 Effect.map((chunk) =>
283 Array.from(chunk).flatMap((page) => (page.result ?? []).map((gateway) => gateway.id)),
284 ),
285 );
286
287 const rows = yield* Effect.forEach(
288 gatewayIds,
289 (gatewayId) =>
290 aiGateway.listProviderConfigs.pages({ accountId, gatewayId }).pipe(
291 Stream.runCollect,
292 Effect.map((chunk) =>
293 Array.from(chunk).flatMap((page) =>
294 (page.result ?? []).map((config) => toAttributes(config, accountId)),
295 ),
296 ),
297 ),
298 { concurrency: 10 },
299 );
300 return rows.flat();
301 }),
302 });
303
304 /**
305 * Reconcile a single BYOK provider config toward the desired props.
306 *
307 * A gateway allows only ONE config per (providerSlug, alias). There is no
308 * update API and no get endpoint, so we observe through the list and:
309 * - already-desired occupant → adopt it (idempotent no-op / re-run)
310 * - stale occupant → delete it, then create the desired one
311 * - no occupant → create the desired one
312 *
313 * `createProviderConfig` can still race and fail with
314 * `ProviderConfigAlreadyExists` when a leftover/sibling config the list had
315 * not yet surfaced (eventual consistency) occupies the slot. Retrying the
316 * whole observe→delete→create flow re-observes the now-visible occupant and
317 * converges it, so re-runs and leftover state self-heal instead of failing.
318 * Bounded so the engine never hangs.
319 */
320 const reconcileProviderConfig = (desired: {
321 accountId: string;
322 gatewayId: string;
323 alias: string;
324 providerSlug: string;
325 secretId: string;
326 defaultConfig: boolean;
327 rateLimit: number | undefined;
328 rateLimitPeriod: number | undefined;
329 currentId: string | undefined;
330 }) => {
331 const {
332 accountId,
333 gatewayId,
334 alias,
335 providerSlug,
336 secretId,
337 defaultConfig,
338 rateLimit,
339 rateLimitPeriod,
340 currentId,
341 } = desired;
342
343 const matchesDesired = (attrs: GatewayProviderAttributes) =>
344 attrs.alias === alias &&
345 attrs.providerSlug === providerSlug &&
346 attrs.secretId === secretId &&
347 attrs.defaultConfig === defaultConfig &&
348 attrs.rateLimit === rateLimit &&
349 (attrs.rateLimitPeriod ?? 60) === (rateLimitPeriod ?? 60);
350
351 return Effect.gen(function* () {
352 // Observe the config currently occupying this gateway's (slug, alias).
353 const configs = yield* listProviderConfigs(accountId, gatewayId);
354 const observed =
355 configs.find((c) => c.id === currentId) ??
356 configs.find((c) => c.alias === alias && c.providerSlug === providerSlug);
357
358 if (observed) {
359 const attrs = toAttributes(observed, accountId);
360 if (matchesDesired(attrs)) {
361 return attrs;
362 }
363 // No update API — delete the stale occupant before recreating.
364 yield* aiGateway
365 .deleteProviderConfig({ accountId, gatewayId, id: observed.id })
366 .pipe(Effect.catchTag("ProviderConfigNotFound", () => Effect.void));
367 }
368
369 // Ensure — create. The referenced Secrets Store secret deploys
370 // asynchronously (status `pending` → `active`), so retry the typed
371 // "secret was not found" error with bounded backoff.
372 const created = yield* aiGateway
373 .createProviderConfig({
374 accountId,
375 gatewayId,
376 alias,
377 providerSlug,
378 secretId,
379 defaultConfig,
380 ...(rateLimit !== undefined && { rateLimit }),
381 ...(rateLimitPeriod !== undefined && { rateLimitPeriod }),
382 })
383 .pipe(
384 Effect.retry({
385 while: (e) => e._tag === "ProviderConfigSecretNotFound",
386 schedule: Schedule.spaced("5 seconds"),
387 times: 10,
388 }),
389 );
390 return toAttributes(created, accountId);
391 }).pipe(
392 Effect.retry({
393 while: (e) => e._tag === "ProviderConfigAlreadyExists",
394 schedule: Schedule.spaced("1 second"),
395 times: 5,
396 }),
397 );
398 };
399
400 /**
401 * List all provider configs on a gateway. A missing gateway returns an
402 * empty list on this endpoint, so no not-found mapping is needed.
403 */
404 const listProviderConfigs = (accountId: string, gatewayId: string) =>
405 aiGateway
406 .listProviderConfigs({ accountId, gatewayId, perPage: 50 })
407 .pipe(Effect.map((page) => page.result));
408
409 const createAlias = (id: string, alias: string | undefined) =>
410 Effect.gen(function* () {
411 return alias ?? (yield* createPhysicalName({ id, lowercase: true }));
412 });
413
414 const toAttributes = (
415 config:
416 | aiGateway.CreateProviderConfigResponse
417 | aiGateway.ListProviderConfigsResponse["result"][number],
418 accountId: string,
419 ): GatewayProviderAttributes => ({
420 providerConfigId: config.id,
421 accountId,
422 gatewayId: config.gatewayId,
423 alias: config.alias,
424 providerSlug: config.providerSlug,
425 secretId: config.secretId,
426 secretPreview: config.secretPreview,
427 // Cloudflare returns 0/1 here, not booleans — normalize at the boundary.
428 defaultConfig: Boolean(config.defaultConfig),
429 rateLimit: config.rateLimit ?? undefined,
430 rateLimitPeriod: config.rateLimitPeriod ?? undefined,
431 modifiedAt: config.modifiedAt,
432 });