Open History to see the last commit
1import serverEntry from '@tanstack/react-start/server-entry'
2import { WorkerEntrypoint } from 'cloudflare:workers'
3import type {
4 Request as WorkersRequest,
5 Response as WorkersResponse,
6} from '@cloudflare/workers-types'
7
8import { getDb } from '#/db/index.ts'
9import type { DbEnv } from '#/db/index.ts'
10import { isAdminRequest } from '#/server/admin.ts'
11import { getAuth } from '#/server/auth.ts'
12import type { KvEnv } from '#/server/kv.ts'
13import type { ProviderEnvironment } from '#/server/providers/types.ts'
14import { withDiscoveryLinks } from '#/server/discovery-links.ts'
15import {
16 markdownForPath,
17 markdownResponse,
18 wantsMarkdown,
19} from '#/server/markdown-pages.ts'
20import { narrativeRoot, wantsJsonRoot } from '#/server/narrative.ts'
21import { enforceRateLimit } from '#/server/rate-limit.ts'
22import { pollAllProviders } from '#/server/ingest/poll-models.ts'
23import {
24 FAL_PRICING_EXTRACT_CRONS,
25 extractFalPricing,
26} from '#/server/ingest/extract-fal-pricing.ts'
27import {
28 VERCEL_PRICING_EXTRACT_CRON,
29 extractVercelPricing,
30} from '#/server/ingest/extract-vercel-pricing.ts'
31import {
32 SPEC_SYNC_SHARD_CRONS,
33 specSyncShard,
34 syncAllProviders,
35} from '#/server/ingest/sync.ts'
36import { recordCompleteness } from '#/server/status.ts'
37import { recordRowShape } from '#/server/row-shape.ts'
38import { runWebhookTick } from '#/server/webhooks.ts'
39import type { SyncDeps } from '#/server/ingest/sync.ts'
40
41// Durable Object class for the US_EGRESS binding (issue #356).
42export { UsEgress } from '#/server/us-egress-object.ts'
43
44// Not exported: workerd treats named exports of the entry module as
45// entrypoints and requires them to be functions/ExportedHandlers.
46const MODELS_POLL_CRON = '*/15 * * * *'
47
48export interface WorkerEnv extends DbEnv, KvEnv, ProviderEnvironment {
49 ADMIN_KEY?: string
50 AI?: Ai
51 AI_GATEWAY_ID?: string
52}
53
54function syncDeps(env: WorkerEnv): SyncDeps {
55 return { db: getDb(env), kv: env.SCHEMA_CACHE, secrets: env }
56}
57
58/**
59 * Public reads are keyless JSON meant for any client — including browser
60 * apps (the hosted examples fetch /v1/schemas live). CORS-open GETs on the
61 * read surface; admin and auth routes are excluded.
62 */
63function isCorsReadPath(pathname: string): boolean {
64 return (
65 (pathname.startsWith('/v1/') && !pathname.startsWith('/v1/admin/')) ||
66 pathname === '/openapi.json' ||
67 pathname === '/llms.txt'
68 )
69}
70
71/**
72 * GETs that Workers Cache may store: catalog, schema and per-provider
73 * OpenAPI reads. The default entrypoint hands these to `CachedReads`, the
74 * one entrypoint with caching on (wrangler.jsonc `exports`). Every other
75 * request skips the cache lookup entirely, which Cloudflare recommends
76 * over answering `no-store` from a cached entrypoint.
77 */
78function isCacheableRead(request: Request, pathname: string): boolean {
79 return (
80 (request.method === 'GET' || request.method === 'HEAD') &&
81 /^\/v1\/(models|providers|schemas|openapi)(\/|$)/.test(pathname)
82 )
83}
84
85function finalize(response: Response, cors: boolean): Response {
86 // New Response: framework responses can carry immutable headers.
87 const headers = new Headers(response.headers)
88 if (cors) headers.set('Access-Control-Allow-Origin', '*')
89 // Workers Cache applies heuristic freshness to a response with no
90 // Cache-Control (a 404 for three minutes, a 200 for two hours). Catalog
91 // and schema reads opt in with `public, max-age`; anything else that
92 // reaches the cached entrypoint, such as an error body, must not be
93 // stored.
94 const cacheControl = headers.get('cache-control') ?? ''
95 if (
96 !cacheControl.includes('public') &&
97 !cacheControl.includes('no-store') &&
98 !cacheControl.includes('private')
99 ) {
100 headers.set('Cache-Control', 'no-store')
101 }
102 return new Response(response.body, {
103 status: response.status,
104 statusText: response.statusText,
105 headers,
106 })
107}
108
109async function handle(request: Request, env: WorkerEnv): Promise<Response> {
110 {
111 // Rate limit the public API (admin-keyed requests are exempt; auth
112 // endpoints have agent-auth's own protections).
113 const url = new URL(request.url)
114 const { pathname } = url
115 const corsRead =
116 isCorsReadPath(pathname) &&
117 (request.method === 'GET' || request.method === 'HEAD')
118 if (request.method === 'OPTIONS' && isCorsReadPath(pathname)) {
119 return new Response(null, {
120 status: 204,
121 headers: {
122 'Access-Control-Allow-Origin': '*',
123 'Access-Control-Allow-Methods': 'GET, HEAD, OPTIONS',
124 'Access-Control-Allow-Headers': 'Content-Type, If-None-Match',
125 'Access-Control-Max-Age': '86400',
126 },
127 })
128 }
129 if (
130 pathname.startsWith('/v1/') &&
131 !isAdminRequest(request, env.ADMIN_KEY)
132 ) {
133 const limited = await enforceRateLimit(
134 getAuth(),
135 getDb(env),
136 env.SCHEMA_CACHE,
137 request,
138 )
139 if (limited) return finalize(limited, corsRead)
140 }
141 // Narrative API root (task 11.2): JSON-accepting GET / gets the MCP
142 // initialize instructions document instead of the SSR landing page.
143 if (pathname === '/' && wantsJsonRoot(request)) {
144 const body = Response.json(narrativeRoot(url.origin))
145 body.headers.set('Vary', 'Accept')
146 return finalize(body, corsRead)
147 }
148 // Markdown content negotiation (task 10.5): Accept: text/markdown on an
149 // HTML page returns markdown instead of SSR.
150 if (wantsMarkdown(request)) {
151 const md = markdownForPath(pathname, url.origin)
152 if (md !== null) return finalize(markdownResponse(md), false)
153 }
154 // TanStack Start's handler takes (request, opts?) — bindings flow in via
155 // the cloudflare:workers env module, not handler arguments. HTML pages
156 // get RFC 8288 discovery Link headers (task 10.2).
157 const response = withDiscoveryLinks(await serverEntry.fetch(request))
158 return finalize(response, corsRead)
159 }
160}
161
162/**
163 * The cached entrypoint. Workers Cache sits in front of its `fetch`: a HIT
164 * never runs the worker (so it is outside the rate limit), a MISS runs the
165 * same pipeline as the default entrypoint. A request with `Authorization`
166 * is cached too, because the responses say `public`.
167 */
168export class CachedReads extends WorkerEntrypoint<WorkerEnv> {
169 // The base class is typed with workers-types; the app with lib.dom (see
170 // src/cloudflare-shim.d.ts). Same objects at runtime.
171 override fetch(request: WorkersRequest): Promise<WorkersResponse> {
172 return handle(
173 request as unknown as Request,
174 this.env,
175 ) as unknown as Promise<WorkersResponse>
176 }
177
178 /**
179 * A purge is scoped to the entrypoint that calls it, so it lives here.
180 * Throws rather than no-ops: a missing `ctx.cache` means caching is off
181 * for this entrypoint (wrangler.jsonc `exports`), and a failed purge
182 * would leave an admin sync invisible for `max-age`.
183 */
184 async purge(): Promise<void> {
185 if (!this.ctx.cache) {
186 throw new Error('CachedReads: ctx.cache is absent; caching is off')
187 }
188 const result = await this.ctx.cache.purge({ purgeEverything: true })
189 if (!result.success) {
190 throw new Error(
191 `CachedReads: purge failed: ${JSON.stringify(result.errors)}`,
192 )
193 }
194 }
195}
196
197export default {
198 async fetch(
199 request: Request,
200 env: WorkerEnv,
201 ctx: ExecutionContext,
202 ): Promise<Response> {
203 const { pathname } = new URL(request.url)
204 if (isCacheableRead(request, pathname)) {
205 return ctx.exports.CachedReads.fetch(request)
206 }
207 const response = await handle(request, env)
208 // An admin write (sync, extract) changes what the cached reads serve;
209 // the crons do not need this because max-age matches their cadence.
210 if (
211 request.method === 'POST' &&
212 pathname.startsWith('/v1/admin/') &&
213 response.ok
214 ) {
215 ctx.waitUntil(
216 ctx.exports.CachedReads.purge().catch((error: unknown) => {
217 console.error(
218 JSON.stringify({ job: 'cache-purge', error: String(error) }),
219 )
220 }),
221 )
222 }
223 return response
224 },
225
226 scheduled(
227 controller: ScheduledController,
228 env: WorkerEnv,
229 ctx: ExecutionContext,
230 ): void {
231 // The models poll runs the full registry in one invocation; the spec
232 // sync is sharded across several cron firings so each shard gets its
233 // own subrequest/CPU/memory budgets (see SPEC_SYNC_SHARD_CRONS). FAL
234 // rate-card extract runs hourly 06:00-11:00 UTC, each firing with its
235 // own budget (FAL_PRICING_EXTRACT_CRONS). Work inside each invocation stays
236 // sequential with per-provider isolation.
237 if (controller.cron === MODELS_POLL_CRON) {
238 ctx.waitUntil(
239 pollAllProviders(syncDeps(env))
240 .then(async (outcomes) => {
241 console.log(JSON.stringify({ job: 'models-poll', outcomes }))
242 // Score completeness once per poll; requests only read the
243 // record. It logs and keeps the old record rather than throw.
244 await recordCompleteness(getDb(env))
245 // Announce a new row shape before the drain so webhooks carry
246 // it. A failure is logged and retried next poll; it does not
247 // hold up webhook delivery.
248 await recordRowShape(getDb(env)).then(
249 (written) => {
250 if (written > 0)
251 console.log(JSON.stringify({ job: 'row-shape', written }))
252 },
253 (error: unknown) => {
254 console.error(
255 JSON.stringify({
256 job: 'row-shape',
257 error: String(error),
258 stack: error instanceof Error ? error.stack : undefined,
259 }),
260 )
261 },
262 )
263 // The 15-min cron also drains the webhook queue (task 6.2).
264 return runWebhookTick(getDb(env))
265 })
266 .then(({ enqueued, outcomes }) => {
267 console.log(JSON.stringify({ job: 'webhooks', enqueued, outcomes }))
268 }),
269 )
270 return
271 }
272 const shard = (SPEC_SYNC_SHARD_CRONS as ReadonlyArray<string>).indexOf(
273 controller.cron,
274 )
275 if (shard >= 0) {
276 ctx.waitUntil(
277 syncAllProviders(syncDeps(env), specSyncShard(shard)).then(
278 (outcomes) => {
279 // Summarize warnings to a count: hundreds of dangling-ref lines
280 // push the blob past what Workers Logs stores, losing the log.
281 const summary = outcomes.map(({ warnings, ...rest }) => ({
282 ...rest,
283 warningCount: warnings.length,
284 }))
285 console.log(
286 JSON.stringify({ job: 'spec-sync', shard, outcomes: summary }),
287 )
288 },
289 ),
290 )
291 return
292 }
293 if (
294 (FAL_PRICING_EXTRACT_CRONS as ReadonlyArray<string>).includes(
295 controller.cron,
296 )
297 ) {
298 ctx.waitUntil(
299 extractFalPricing({
300 ...syncDeps(env),
301 ai: env.AI,
302 gatewayId: env.AI_GATEWAY_ID,
303 }).then((outcome) => {
304 console.log(JSON.stringify({ job: 'fal-pricing-extract', outcome }))
305 }),
306 )
307 return
308 }
309 if (controller.cron === VERCEL_PRICING_EXTRACT_CRON) {
310 ctx.waitUntil(
311 extractVercelPricing(syncDeps(env)).then((outcome) => {
312 console.log(
313 JSON.stringify({ job: 'vercel-pricing-extract', outcome }),
314 )
315 }),
316 )
317 return
318 }
319 console.log(JSON.stringify({ cron: controller.cron, job: 'unknown-cron' }))
320 },
321}