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';35import { biomarkerRoutes } from './routes/biomarkers.js';3637export interface BuildOptions {38  db?: Database;39  logger?: boolean;40  logLevel?: string;41}4243/** Build the Fastify app (used by server.ts and by tests via app.inject). */44export async function buildApp(opts: BuildOptions = {}): Promise<FastifyInstance> {45  const app = Fastify({46    logger: opts.logger === false ? false : { level: opts.logLevel ?? process.env.LOG_LEVEL ?? 'info', base: { service: process.env.CI_SERVICE ?? 'api' } },47    // Correlation id on every request (CLAUDE.md §175): honour an incoming x-request-id, else mint one.48    requestIdHeader: 'x-request-id',49    genReqId: () => randomUUID(),50    trustProxy: true,51    ajv: { customOptions: { coerceTypes: true } },52  });5354  app.setValidatorCompiler(validatorCompiler);55  app.setSerializerCompiler(serializerCompiler);5657  const db = opts.db ?? getDb();58  app.decorate('db', db);59  app.decorate('dbHealthy', async () => {60    try {61      await db.execute(sql`SELECT 1`);62      return true;63    } catch {64      return false;65    }66  });6768  app.addHook('onRequest', async (req, reply) => {69    reply.header('x-request-id', req.id);70  });7172  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'] });73  await app.register(compress, { global: true, encodings: ['gzip', 'br', 'deflate'], threshold: 1024 });74  await app.register(etag, { weak: true });7576  registerApiKeyAuth(app);77  await app.register(rateLimit, {78    global: true,79    hook: 'preValidation', // runs after the onRequest auth hook so per-key limits apply80    timeWindow: '1 minute',81    max: (req) => rateLimitMax(req),82    keyGenerator: (req) => rateLimitKey(req),83    allowList: (req) => req.url === '/healthz' || req.url.startsWith('/v1/docs') || req.url === '/v1/openapi.json',84    addHeaders: { 'x-ratelimit-limit': true, 'x-ratelimit-remaining': true, 'x-ratelimit-reset': true, 'retry-after': true },85    addHeadersOnExceeding: { 'x-ratelimit-limit': true, 'x-ratelimit-remaining': true, 'x-ratelimit-reset': true },86    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 }),87  });8889  await app.register(swagger, {90    openapi: {91      openapi: '3.1.0',92      info: {93        title: 'CancerIndex API',94        version: '1.0.0',95        description:96          '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.',97        contact: { name: 'Simon-Pierre Boucher — CancerIndex', url: 'https://www.cancerindex.io/about', email: 'contact@spboucher.ai' },98        license: { name: 'Data licensed per source; see /v1/sources' },99      },100      servers: [{ url: '/', description: 'This host' }],101      tags: [102        { name: 'cancers', description: 'Canonical cancer entities, hierarchy, statistics, evidence' },103        { name: 'genes' },104        { name: 'variants' },105        { name: 'drugs' },106        { name: 'trials' },107        { name: 'publications' },108        { name: 'rankings', description: 'Ranking snapshots with scope, formula version and lineage' },109        { name: 'search' },110        { name: 'sources', description: 'Source registry, licenses, connector health' },111        { name: 'stats' },112        { name: 'changes' },113        { name: 'epidemiology', description: 'Time-aware incidence/mortality/prevalence observations with provenance (Data Explorer)' },114        { name: 'approvals', description: 'Jurisdiction-aware regulatory approvals and the drug development pipeline' },115        { name: 'biomarkers', description: 'Curated canonical biomarkers (NCIt-verified) with derived links to cancers, drugs, approvals and trials' },116        { name: 'graph', description: 'Cancer–gene–variant–drug–trial knowledge graph (contextual neighbourhoods)' },117        { name: 'intelligence', description: 'Derived clinical-trial intelligence and research-gap components (computed metrics with formula versions)' },118        { name: 'admin', description: 'Operator endpoints (x-admin-token)' },119        { name: 'system' },120      ],121      components: {122        securitySchemes: {123          apiKey: { type: 'http', scheme: 'bearer', description: 'Optional. Raises the per-minute rate limit.' },124          adminToken: { type: 'apiKey', in: 'header', name: 'x-admin-token' },125        },126      },127    },128    transform: jsonSchemaTransform,129  });130  await app.register(swaggerUi, { routePrefix: '/v1/docs', uiConfig: { docExpansion: 'list', deepLinking: true } });131132  app.setErrorHandler((err, req, reply) => {133    if (err instanceof HttpError) {134      return reply.code(err.statusCode).send({ error: { code: err.code, message: err.message, details: err.details }, requestId: req.id });135    }136    if (hasZodFastifySchemaValidationErrors(err)) {137      return reply.code(400).send({ error: { code: 'bad_request', message: 'request does not match the schema', details: err.validation }, requestId: req.id });138    }139    if (isResponseSerializationError(err)) {140      req.log.error({ err, issues: err.cause.issues }, 'response serialization error');141      return reply.code(500).send({ error: { code: 'internal', message: 'response does not match the schema' }, requestId: req.id });142    }143    const e = err as { statusCode?: number; message?: string };144    const status = e.statusCode ?? 500;145    if (status >= 500) req.log.error({ err }, 'unhandled error');146    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 });147  });148  app.setNotFoundHandler((req, reply) => {149    reply.code(404).send({ error: { code: 'not_found', message: `route ${req.method} ${req.url} not found` }, requestId: req.id });150  });151152  await app.register(healthRoutes);153  await app.register(154    async (v1) => {155      v1.get('/openapi.json', { schema: { hide: true } }, async () => app.swagger());156      await v1.register(cancerRoutes);157      await v1.register(geneRoutes);158      await v1.register(variantRoutes);159      await v1.register(drugRoutes);160      await v1.register(trialRoutes);161      await v1.register(publicationRoutes);162      await v1.register(rankingRoutes);163      await v1.register(searchRoutes);164      await v1.register(sourceRoutes);165      await v1.register(statsRoutes);166      await v1.register(changeRoutes);167      await v1.register(epidemiologyRoutes);168      await v1.register(approvalRoutes);169      await v1.register(graphRoutes);170      await v1.register(intelligenceRoutes);171      await v1.register(researchGapRoutes);172      await v1.register(trialSiteRoutes);173      await v1.register(biomarkerRoutes);174      await v1.register(adminRoutes, { prefix: '/admin' });175    },176    { prefix: '/v1' },177  );178179  app.addHook('onClose', async () => {180    await closeBoss().catch(() => {});181  });182183  return app;184}185