Skip to content
Source
Sign inSign up
TanStack/schemas
Open History to see the last commit

provider-openapi.ts

469 lines14.6 KB

1/**
2 * Assemble a generation-only OpenAPI 3.1 document for one provider from
3 * stored endpoints + current schema versions + the provider's connect
4 * profile. Reuses `schema_versions` rows (no second derivation); overlays
5 * the live or pinned `model` enum, and moves output onto the sibling GET
6 * when `connect.siblingGet` is set.
7 */
8import { and, eq, isNull } from 'drizzle-orm'
9​
10import type { Db } from '#/db/index.ts'
11import { activities, endpoints, schemaVersions } from '#/db/schema.ts'
12import type { Activity } from '#/db/schema.ts'
13import {
14 getModelDetail,
15 knownProviderIds,
16 listModelsCatalog,
17} from '#/server/catalog.ts'
18import { contentHash } from '#/server/kv.ts'
19import { getProvider } from '#/server/providers/index.ts'
20import { MAX_SPEC_PATHS, resolveSpecGrain } from '#/server/providers/connect.ts'
21import type {
22 ProviderConfig,
23 ProviderConnect,
24} from '#/server/providers/types.ts'
25import { hasAsyncApiFlag } from '#/server/ingest/asyncapi.ts'
26import { providerExists, publicEndpointId } from '#/server/schemas-api.ts'
27​
28export interface AssembleOpenApiQuery {
29 model?: string
30 activity?: string
32​
33export type AssembleOpenApiResult =
34 | { ok: true; document: Record<string, unknown>; etag: string }
35 | { ok: false; status: 400 | 404 | 500; code: string; message: string }
36​
37interface LoadedEndpoint {
38 id: string
39 path: string
40 activity: Activity
41 description: string | null
42 method: string
43 input?: unknown
44 output?: unknown
45 specRevision: string | null
47​
48function isObject(value: unknown): value is Record<string, unknown> {
49 return typeof value === 'object' && value !== null && !Array.isArray(value)
51​
52/** `{name}` path segments → required path parameters. */
53export function pathParamsFromPath(
54 path: string,
55): Array<Record<string, unknown>> {
56 const names = [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1])
57 return names
58 .filter((name): name is string => typeof name === 'string' && name !== '')
59 .map((name) => ({
60 name,
61 in: 'path',
62 required: true,
63 schema: { type: 'string' },
64 }))
66​
67export function headerParams(
68 headers: Record<string, string> | undefined,
69): Array<Record<string, unknown>> {
70 if (!headers) return []
71 return Object.entries(headers).map(([name, value]) => ({
72 name,
73 in: 'header',
74 required: true,
75 schema: { type: 'string', const: value },
76 }))
78​
79/** Pin `properties.model` to a live enum (or a single id). */
80export function applyModelEnum(
81 schema: unknown,
82 modelIds: Array<string>,
83): unknown {
84 if (!isObject(schema) || modelIds.length === 0) return schema
85 const props = schema.properties
86 if (!isObject(props) || !isObject(props.model)) return schema
87 return {
88 ...schema,
89 properties: {
90 ...props,
91 model: { ...props.model, enum: modelIds },
92 },
93 }
95​
96/** Pin common model path params (Gemini `modelsId`). */
97function pinPathParams(
98 parameters: Array<Record<string, unknown>>,
99 modelId: string,
100): Array<Record<string, unknown>> {
101 return parameters.map((parameter) => {
102 const name = parameter.name
103 if (parameter.in !== 'path') return parameter
104 if (name !== 'model' && name !== 'modelsId' && name !== 'model_id') {
105 return parameter
106 }
107 return { ...parameter, schema: { type: 'string', enum: [modelId] } }
108 })
110​
111function media(
112 schema: unknown,
113): { content: { 'application/json': { schema: unknown } } } | undefined {
114 if (schema === undefined) return undefined
115 return { content: { 'application/json': { schema } } }
117​
118function operationId(providerId: string, method: string, path: string): string {
119 const slug = `${providerId}-${method}-${path}`
120 .toLowerCase()
121 .replace(/[^a-z0-9]+/g, '-')
122 .replace(/^-+|-+$/g, '')
123 return slug.length > 0 ? slug : `${providerId}-${method}`
125​
126export function endpointMatchesModel(
127 endpointId: string,
128 path: string,
129 rawId: string,
130): boolean {
131 return endpointId === rawId || path === rawId || path === `/${rawId}`
133​
134function siblingRequestPath(path: string): string {
135 return `${path}/requests/{request_id}`
137​
138function refuseSelector(
139 providerId: string,
140 grain: 'provider' | 'model',
141 count: number,
142 reason: string,
143): AssembleOpenApiResult {
144 const example = `GET /v1/openapi/${providerId}?model=`
145 const schemas = `GET /v1/schemas/${providerId}`
146 const models = `GET /v1/providers/${providerId}/models`
147 return {
148 ok: false,
149 status: 400,
150 code: 'spec_requires_selector',
151 message:
152 grain === 'model'
153 ? `Provider '${providerId}' is model-grained (${String(count)} endpoints) — there is no combined OpenAPI document. Pass ?model={rawId}, e.g. ${example}<rawId>. List models: ${models}.`
154 : `${reason} ?model= pins the live model enum; it does not drop endpoints on provider-grained specs. Narrow with ?activity= (${activities.join(', ')}). List endpoints: ${schemas}. List models: ${models}.`,
155 }
157​
158function applyConnectProfile(
159 config: ProviderConfig | undefined,
160 selected: Array<LoadedEndpoint>,
161): { connect: ProviderConnect | null; selected: Array<LoadedEndpoint> } {
162 if (!config?.connect) return { connect: null, selected }
163 const overrides = config.connectByActivity
164 if (!overrides) return { connect: config.connect, selected }
165​
166 const present = new Set(selected.map((endpoint) => endpoint.activity))
167 if (present.size === 1) {
168 const only = selected[0]?.activity
169 const override = only !== undefined ? overrides[only] : undefined
170 return { connect: override ?? config.connect, selected }
171 }
172 return {
173 connect: config.connect,
174 selected: selected.filter(
175 (endpoint) => overrides[endpoint.activity] === undefined,
176 ),
177 }
179​
180async function loadEndpoints(
181 db: Db,
182 providerId: string,
183 activity: Activity | undefined,
184): Promise<Array<LoadedEndpoint>> {
185 const rows = await db
186 .select({
187 id: endpoints.id,
188 path: endpoints.path,
189 activity: endpoints.activity,
190 description: endpoints.description,
191 method: endpoints.method,
192 kind: schemaVersions.kind,
193 schema: schemaVersions.schema,
194 specRevision: schemaVersions.specRevision,
195 })
196 .from(endpoints)
197 .leftJoin(
198 schemaVersions,
199 and(
200 eq(schemaVersions.endpointId, endpoints.id),
201 isNull(schemaVersions.supersededAt),
202 ),
203 )
204 .where(
205 activity
206 ? and(
207 eq(endpoints.providerId, providerId),
208 eq(endpoints.activity, activity),
209 )
210 : eq(endpoints.providerId, providerId),
211 )
212 .orderBy(endpoints.id)
213​
214 const byId = new Map<string, LoadedEndpoint>()
215 for (const row of rows) {
216 const existing = byId.get(row.id)
217 const parsed =
218 row.schema !== null ? (JSON.parse(row.schema) as unknown) : undefined
219 if (!existing) {
220 byId.set(row.id, {
221 id: publicEndpointId(row.id, providerId),
222 path: row.path,
223 activity: row.activity,
224 description: row.description,
225 method: row.method,
226 specRevision: row.specRevision,
227 ...(row.kind === 'input' ? { input: parsed } : {}),
228 ...(row.kind === 'output' ? { output: parsed } : {}),
229 })
230 continue
231 }
232 if (row.kind === 'input') existing.input = parsed
233 if (row.kind === 'output') existing.output = parsed
234 if (existing.specRevision === null) existing.specRevision = row.specRevision
235 }
236 return [...byId.values()]
238​
239function buildOperation(
240 providerId: string,
241 endpoint: LoadedEndpoint,
242 connect: ProviderConnect,
243 modelIds: Array<string>,
244 pinnedModel: string | undefined,
245): Record<string, unknown> {
246 const input = applyModelEnum(endpoint.input, modelIds)
247 const parameters = [
248 ...pathParamsFromPath(endpoint.path),
249 ...headerParams(connect.requiredHeaders),
250 ]
251 const pinned = pinnedModel
252 ? pinPathParams(parameters, pinnedModel)
253 : parameters
254 const body = media(input)
255 return {
256 operationId: operationId(providerId, 'post', endpoint.path),
257 summary: endpoint.description ?? undefined,
258 'x-modelschemas-activity': endpoint.activity,
259 ...(pinned.length > 0 ? { parameters: pinned } : {}),
260 ...(body ? { requestBody: { required: true, ...body } } : {}),
261 responses: {
262 '200': {
263 description: 'Success',
264 ...(connect.siblingGet ? {} : (media(endpoint.output) ?? {})),
265 },
266 },
267 }
269​
270function buildSiblingGet(
271 providerId: string,
272 endpoint: LoadedEndpoint,
273): Record<string, unknown> {
274 const requestPath = siblingRequestPath(endpoint.path)
275 return {
276 operationId: operationId(providerId, 'get', requestPath),
277 summary: 'Fetch a queued request result',
278 'x-modelschemas-activity': endpoint.activity,
279 parameters: [
280 ...pathParamsFromPath(endpoint.path),
281 {
282 name: 'request_id',
283 in: 'path',
284 required: true,
285 schema: { type: 'string' },
286 },
287 ],
288 responses: {
289 '200': {
290 description: 'Queued result',
291 ...(media(endpoint.output) ?? {}),
292 },
293 },
294 }
296​
297/**
298 * Assemble GET /v1/openapi/{provider}. Refuses combined documents for
299 * model-grained providers and for selections over {@link MAX_SPEC_PATHS}.
300 */
301export async function assembleProviderOpenApi(
302 db: Db,
303 providerId: string,
304 query: AssembleOpenApiQuery = {},
305): Promise<AssembleOpenApiResult> {
306 if (!(await providerExists(db, providerId))) {
307 const valid = (await knownProviderIds(db)).join(', ')
308 return {
309 ok: false,
310 status: 404,
311 code: 'unknown_provider',
312 message: `Unknown provider '${providerId}'. Valid providers: ${valid}.`,
313 }
314 }
315​
316 let activity: Activity | undefined
317 if (query.activity !== undefined) {
318 if (!(activities as ReadonlyArray<string>).includes(query.activity)) {
319 return {
320 ok: false,
321 status: 404,
322 code: 'unknown_activity',
323 message: `Unknown activity '${query.activity}'. Valid activities: ${activities.join(', ')}.`,
324 }
325 }
326 activity = query.activity as Activity
327 }
328​
329 const config = getProvider(providerId)
330 const grain = resolveSpecGrain(config)
331​
332 let pinnedModel: string | undefined
333 if (query.model !== undefined) {
334 const model = await getModelDetail(db, providerId, query.model)
335 if (!model) {
336 return {
337 ok: false,
338 status: 404,
339 code: 'unknown_model',
340 message: `Unknown model '${query.model}' for provider '${providerId}'. Try GET /v1/providers/${providerId}/models for valid ids.`,
341 }
342 }
343 pinnedModel = model.rawId
344 if (activity === undefined && model.activity) {
345 activity = model.activity
346 }
347 if (hasAsyncApiFlag(model.capabilities)) {
348 const schemaHint = model.activity
349 ? `GET /v1/schemas/${providerId}/${model.activity}/${pinnedModel}`
350 : `GET /v1/schemas/${providerId}`
351 return {
352 ok: false,
353 status: 404,
354 code: 'unknown_model',
355 message: `Model '${pinnedModel}' is listed for '${providerId}' but publishes an AsyncAPI contract, not HTTP OpenAPI. Use ${schemaHint} (kind=input|output). Catalog: GET /v1/models/${providerId}/${pinnedModel}.`,
356 }
357 }
358 }
359​
360 const loaded = await loadEndpoints(db, providerId, activity)
361 let selected = loaded
362 if (pinnedModel !== undefined) {
363 const matching = loaded.filter((e) =>
364 endpointMatchesModel(e.id, e.path, pinnedModel),
365 )
366 if (matching.length > 0) selected = matching
367 else if (grain === 'model') {
368 return {
369 ok: false,
370 status: 404,
371 code: 'unknown_model',
372 message: `Model '${pinnedModel}' is listed for '${providerId}' but has no classified generation endpoint (no path matching that raw id). List endpoints: GET /v1/schemas/${providerId}. If the model is new, wait for spec sync or POST /v1/admin/sync/${providerId}. Catalog: GET /v1/providers/${providerId}/models.`,
373 }
374 }
375 }
376​
377 if (grain === 'model' && pinnedModel === undefined) {
378 return refuseSelector(
379 providerId,
380 'model',
381 loaded.length,
382 `Provider '${providerId}' is model-grained.`,
383 )
384 }
385​
386 const profile = applyConnectProfile(config, selected)
387 const connect = profile.connect
388 selected = profile.selected
389​
390 if (selected.length === 0) {
391 const filtered = activity !== undefined || pinnedModel !== undefined
392 return {
393 ok: false,
394 status: filtered ? 400 : 404,
395 code: filtered ? 'spec_requires_selector' : 'no_endpoints',
396 message: filtered
397 ? `No generation endpoints for provider '${providerId}'${activity ? ` activity '${activity}'` : ''}${pinnedModel ? ` model '${pinnedModel}'` : ''}. List endpoints: GET /v1/schemas/${providerId}. Valid activities: ${activities.join(', ')}.`
398 : `Provider '${providerId}' has no synced generation endpoints yet. Check GET /v1/status or POST /v1/admin/sync/${providerId}. Index: GET /v1/schemas/${providerId}.`,
399 }
400 }
401​
402 if (selected.length > MAX_SPEC_PATHS) {
403 return refuseSelector(
404 providerId,
405 grain,
406 selected.length,
407 `Selection matches ${String(selected.length)} endpoints (cap ${String(MAX_SPEC_PATHS)}).`,
408 )
409 }
410​
411 if (!connect || connect.servers.length === 0) {
412 return {
413 ok: false,
414 status: 500,
415 code: 'missing_connect',
416 message: `Provider '${providerId}' has no declared connect profile (servers/auth). GET /v1/openapi/${providerId} is not assembled until ProviderConfig.connect is set. Use GET /v1/schemas/${providerId} and the provider's own docs.`,
417 }
418 }
419​
420 const modelIds = pinnedModel
421 ? [pinnedModel]
422 : (
423 await listModelsCatalog(db, {
424 provider: providerId,
425 activity,
426 })
427 ).models.map((m) => m.rawId)
428 const paths: Record<string, Record<string, unknown>> = {}
429 for (const endpoint of selected) {
430 const item = paths[endpoint.path] ?? {}
431 item.post = buildOperation(
432 providerId,
433 endpoint,
434 connect,
435 modelIds,
436 pinnedModel,
437 )
438 if (connect.siblingGet) {
439 const siblingPath = siblingRequestPath(endpoint.path)
440 paths[siblingPath] = { get: buildSiblingGet(providerId, endpoint) }
441 }
442 paths[endpoint.path] = item
443 }
444​
445 const revision =
446 selected.find((e) => e.specRevision)?.specRevision ?? 'current'
447 const document: Record<string, unknown> = {
448 openapi: '3.1.0',
449 info: {
450 title: `${config?.displayName ?? providerId} (modelschemas)`,
451 version: revision,
452 description: `Generation-only OpenAPI assembled by modelschemas from live endpoint schemas. Call this provider directly with your own key — this is not a proxy.`,
453 },
454 servers: connect.servers,
455 ...(Object.keys(connect.securitySchemes).length > 0
456 ? {
457 security: connect.security,
458 components: { securitySchemes: connect.securitySchemes },
459 }
460 : {}),
461 paths,
462 }
463​
464 return {
465 ok: true,
466 document,
467 etag: await contentHash(document),
468 }