spb/cancerindex

1import { randomUUID } from 'node:crypto';2import Fastify, { type FastifyInstance } from 'fastify';3import cors from '@fastify/cors';4import compress from '@fastify/compress';5import etag from '@fastify/etag';6import rateLimit from '@fastify/rate-limit';7import swagger from '@fastify/swagger';8import swaggerUi from '@fastify/swagger-ui';9import { sql } from 'drizzle-orm';10import { hasZodFastifySchemaValidationErrors, isResponseSerializationError, jsonSchemaTransform, serializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';11import { getDb, type Database } from '@cancerindex/database';12import { HttpError } from './lib/errors.js';13import { rateLimitKey, rateLimitMax, registerApiKeyAuth } from './plugins/auth.js';14import { closeBoss } from './lib/queue.js';15import './types.js';16import { healthRoutes } from './routes/health.js';17import { cancerRoutes } from './routes/cancers.js';18import { geneRoutes } from './routes/genes.js';19import { variantRoutes } from './routes/variants.js';20import { drugRoutes } from './routes/drugs.js';21import { trialRoutes } from './routes/trials.js';22import { publicationRoutes } from './routes/publications.js';23import { rankingRoutes } from './routes/rankings.js';24import { searchRoutes } from './routes/search.js';25import { sourceRoutes } from './routes/sources.js';26import { statsRoutes } from './routes/stats.js';27import { changeRoutes } from './routes/changes.js';28import { adminRoutes } from './routes/admin.js';29import { graphRoutes } from './routes/graph.js';30import { epidemiologyRoutes } from './routes/epidemiology.js';31import { approvalRoutes } from './routes/approvals.js';32import { intelligenceRoutes } from './routes/intelligence.js';33import { researchGapRoutes } from './routes/research-gap.js';34import { trialSiteRoutes } from './routes/trial-sites.js';3536export interface BuildOptions {37  db?: Database;38  logger?: boolean;39  logLevel?: string;40}4142/** Build the Fastify app (used by server.ts and by tests via app.inject). */43export async function buildApp(opts: BuildOptions = {}): Promise<FastifyInstance> {44  const app = Fastify({45    logger: opts.logger === false ? false : { level: opts.logLevel ?? process.env.LOG_LEVEL ?? 'info', base: { service: process.env.CI_SERVICE ?? 'api' } },46    // Correlation id on every request (CLAUDE.md §175): honour an incoming x-request-id, else mint one.47    requestIdHeader: 'x-request-id',48    genReqId: () => randomUUID(),49    trustProxy: true,50    ajv: { customOptions: { coerceTypes: true } },51  });5253  app.setValidatorCompiler(validatorCompiler);54  app.setSerializerCompiler(serializerCompiler);5556  const db = opts.db ?? getDb();57  app.decorate('db', db);58  app.decorate('dbHealthy', async () => {59    try {60      await db.execute(sql`SELECT 1`);61      return true;62    } catch {63      return false;64    }65  });6667  app.addHook('onRequest', async (req, reply) => {68    reply.header('x-request-id', req.id);69  });7071  await app.register(cors, { origin: true, methods: ['GET', 'POST', 'OPTIONS'], exposedHeaders: ['x-request-id', 'x-ratelimit-limit', 'x-ratelimit-remaining', 'x-ratelimit-reset', 'retry-after'] });72  await app.register(compress, { global: true, encodings: ['gzip', 'br', 'deflate'], threshold: 1024 });73  await app.register(etag, { weak: true });7475  registerApiKeyAuth(app);76  await app.register(rateLimit, {77    global: true,78    hook: 'preValidation', // runs after the onRequest auth hook so per-key limits apply79    timeWindow: '1 minute',80    max: (req) => rateLimitMax(req),81    keyGenerator: (req) => rateLimitKey(req),82    allowList: (req) => req.url === '/healthz' || req.url.startsWith('/v1/docs') || req.url === '/v1/openapi.json',83    addHeaders: { 'x-ratelimit-limit': true, 'x-ratelimit-remaining': true, 'x-ratelimit-reset': true, 'retry-after': true },84    addHeadersOnExceeding: { 'x-ratelimit-limit': true, 'x-ratelimit-remaining': true, 'x-ratelimit-reset': true },85    errorResponseBuilder: (req, ctx) => ({ error: { code: 'rate_limited', message: `Rate limit exceeded (${ctx.max} requests per ${ctx.after}). Use an API key for higher limits.` }, requestId: req.id }),86  });8788  await app.register(swagger, {89    openapi: {90      openapi: '3.1.0',91      info: {92        title: 'CancerIndex API',93        version: '1.0.0',94        description:95          'Public read-only API of CancerIndex.io — the global index of cancer. Every response is wrapped in `{ data, sources, dataRelease, generatedAt }`; `sources` lists the upstream sources (with license and attribution) behind the returned data. Numbers are never invented: absent data is absent, not zero. Rankings carry scope, formula version and inputs hash. Not medical advice.',96        contact: { name: 'CancerIndex', url: 'https://www.cancerindex.io' },97        license: { name: 'Data licensed per source; see /v1/sources' },98      },99      servers: [{ url: '/', description: 'This host' }],100      tags: [101        { name: 'cancers', description: 'Canonical cancer entities, hierarchy, statistics, evidence' },102        { name: 'genes' },103        { name: 'variants' },104        { name: 'drugs' },105        { name: 'trials' },106        { name: 'publications' },107        { name: 'rankings', description: 'Ranking snapshots with scope, formula version and lineage' },108        { name: 'search' },109        { name: 'sources', description: 'Source registry, licenses, connector health' },110        { name: 'stats' },111        { name: 'changes' },112        { name: 'epidemiology', description: 'Time-aware incidence/mortality/prevalence observations with provenance (Data Explorer)' },113        { name: 'approvals', description: 'Jurisdiction-aware regulatory approvals and the drug development pipeline' },114        { name: 'graph', description: 'Cancer–gene–variant–drug–trial knowledge graph (contextual neighbourhoods)' },115        { name: 'intelligence', description: 'Derived clinical-trial intelligence and research-gap components (computed metrics with formula versions)' },116        { name: 'admin', description: 'Operator endpoints (x-admin-token)' },117        { name: 'system' },118      ],119      components: {120        securitySchemes: {121          apiKey: { type: 'http', scheme: 'bearer', description: 'Optional. Raises the per-minute rate limit.' },122          adminToken: { type: 'apiKey', in: 'header', name: 'x-admin-token' },123        },124      },125    },126    transform: jsonSchemaTransform,127  });128  await app.register(swaggerUi, { routePrefix: '/v1/docs', uiConfig: { docExpansion: 'list', deepLinking: true } });129130  app.setErrorHandler((err, req, reply) => {131    if (err instanceof HttpError) {132      return reply.code(err.statusCode).send({ error: { code: err.code, message: err.message, details: err.details }, requestId: req.id });133    }134    if (hasZodFastifySchemaValidationErrors(err)) {135      return reply.code(400).send({ error: { code: 'bad_request', message: 'request does not match the schema', details: err.validation }, requestId: req.id });136    }137    if (isResponseSerializationError(err)) {138      req.log.error({ err, issues: err.cause.issues }, 'response serialization error');139      return reply.code(500).send({ error: { code: 'internal', message: 'response does not match the schema' }, requestId: req.id });140    }141    const e = err as { statusCode?: number; message?: string };142    const status = e.statusCode ?? 500;143    if (status >= 500) req.log.error({ err }, 'unhandled error');144    return reply.code(status).send({ error: { code: status === 429 ? 'rate_limited' : status >= 500 ? 'internal' : 'error', message: status >= 500 ? 'internal server error' : (e.message ?? 'error') }, requestId: req.id });145  });146  app.setNotFoundHandler((req, reply) => {147    reply.code(404).send({ error: { code: 'not_found', message: `route ${req.method} ${req.url} not found` }, requestId: req.id });148  });149150  await app.register(healthRoutes);151  await app.register(152    async (v1) => {153      v1.get('/openapi.json', { schema: { hide: true } }, async () => app.swagger());154      await v1.register(cancerRoutes);155      await v1.register(geneRoutes);156      await v1.register(variantRoutes);157      await v1.register(drugRoutes);158      await v1.register(trialRoutes);159      await v1.register(publicationRoutes);160      await v1.register(rankingRoutes);161      await v1.register(searchRoutes);162      await v1.register(sourceRoutes);163      await v1.register(statsRoutes);164      await v1.register(changeRoutes);165      await v1.register(epidemiologyRoutes);166      await v1.register(approvalRoutes);167      await v1.register(graphRoutes);168      await v1.register(intelligenceRoutes);169      await v1.register(researchGapRoutes);170      await v1.register(trialSiteRoutes);171      await v1.register(adminRoutes, { prefix: '/admin' });172    },173    { prefix: '/v1' },174  );175176  app.addHook('onClose', async () => {177    await closeBoss().catch(() => {});178  });179180  return app;181}182