@open-xchange/fastify-sdk 0.1.0

package/README.md

@@ -0,0 +1,370 @@
+# @open-xchange/fastify-sdk
+
+[![coverage](https://gitlab.com/openxchange/appsuite/web-foundation/fastify-sdk/badges/main/coverage.svg)](https://gitlab.com/openxchange/appsuite/web-foundation/fastify-sdk/-/graphs/main/charts)
+
+Shared foundation package for OX App Suite Node.js services. Extracts common infrastructure — Fastify setup, logging, health checks, plugins, database pools, config loading — so consuming projects consist almost entirely of business logic.
+
+## Install
+
+```bash
+pnpm add @open-xchange/fastify-sdk
+```
+
+## Quick start
+
+```js
+import { createApp } from '@open-xchange/fastify-sdk'
+
+const app = await createApp({
+  dirname: import.meta.dirname,
+  plugins: {
+    jwt: true,
+    swagger: { enabled: process.env.EXPOSE_API_DOCS === 'true' }
+  }
+})
+
+await app.listen({ host: '0.0.0.0', port: 8080 })
+```
+
+That single call replaces ~500 lines of boilerplate (logger, CORS, Helmet, metrics, JWT, Swagger, autoload).
+
+## Exports
+
+| Import path | What it provides |
+|---|---|
+| `@open-xchange/fastify-sdk` | `createApp`, `createMetricsServer`, `createLogger`, `getLogger`, `loadEnv`, `jwtAuthHook`, health check helpers, re-exports of `fastify`, `fp`, `pino`, `promClient`, `createError`, `jose` |
+| `@open-xchange/fastify-sdk/mysql` | `createMySQLPool`, `createMySQLPoolFromEnv`, `getMySQLPools`, `mysqlReadyCheck`, `createUUID` |
+| `@open-xchange/fastify-sdk/postgres` | `createPostgresPool`, `createPostgresPoolFromEnv` |
+| `@open-xchange/fastify-sdk/migrations` | `createMigrationRunner`, `executeMigrations` |
+| `@open-xchange/fastify-sdk/config` | `createConfigRegistry`, `readConfigurationFile`, Joi helpers (`defaultTrue`, `defaultFalse`, `customString`, `customURL`), `Joi` |
+| `@open-xchange/fastify-sdk/redis` | `createRedisClient`, `createRedisClientFromEnv`, `redisReadyCheck` |
+| `@open-xchange/fastify-sdk/testing` | `createTestApp`, `generateTokenForJwks`, `getJwks` |
+| `@open-xchange/fastify-sdk/lint` | ESLint flat config with `@open-xchange/lint` |
+
+## API reference
+
+### `createApp(options)`
+
+Creates a configured Fastify instance with standard OX defaults.
+
+**Options:**
+
+```js
+{
+  dirname: import.meta.dirname,        // For resolving plugins/routes dirs
+  pluginsDir: 'plugins',               // Relative to dirname (auto-loaded)
+  routesDir: 'routes',                 // Relative to dirname (auto-loaded)
+  routes: { prefix, ...autoloadOpts }, // Extra @fastify/autoload options for routes
+  fastify: {},                         // Merged into Fastify constructor options
+  plugins: {
+    cors: true | { origin, methods },  // Default: true
+    helmet: true | { options },        // Default: true
+    logging: true,                     // Default: true (request/response hooks)
+    metrics: true,                     // Default: true (fastify-metrics collectors, no endpoint)
+    jwt: false | true | { key },       // Default: false (see JWT section below)
+    swagger: false | { enabled, openapi }, // Default: false
+    static: false | true | { root, preCompressed, ... }, // Default: false
+  },
+  metricsServer: true,                 // Default: true (separate Fastify on port 9000)
+  database: { mysql: true },           // Auto-manages pool readiness, health checks, shutdown
+  config: {                            // YAML config file watching
+    filename: 'config.yaml',
+    schema,                            // Joi schema for validation
+    optional: true,
+    callback: (data) => { ... }
+  },
+  onReady: async () => {},             // Called in Fastify onReady hook
+  onClose: async () => {},             // Called in Fastify onClose hook
+}
+```
+
+**Defaults applied:**
+- `requestIdLogLabel: 'requestId'`
+- `disableRequestLogging: true`
+- `connectionTimeout: 30000`
+- `genReqId: () => randomUUID()`
+
+### `createLogger(options)`
+
+Returns a Pino logger with the standard OX configuration:
+- Custom level mapping (trace→8, debug→7, info→6, warn→4, error→3, fatal→0)
+- Redaction of `headers.authorization`, `headers.cookie`, `headers.host`, `key`, `password`, `salt`, `hash`
+- Epoch millisecond timestamps
+- No base (omits pid/hostname)
+
+Pass custom options to override defaults (e.g. `createLogger({ level: 'debug' })`).
+
+### `loadEnv()`
+
+Loads environment variables from `.env.defaults` then `.env` using Node's built-in `process.loadEnvFile()`. No external dependency needed.
+
+### Health check helpers
+
+```js
+import { registerReadinessCheck, registerHealthCheck, mysqlHealthCheck } from '@open-xchange/fastify-sdk'
+
+registerReadinessCheck(async () => { await mysqlHealthCheck(pool) })
+registerHealthCheck(async () => { await mysqlHealthCheck(pool) })
+```
+
+Registered checks are run by the metrics server (`GET /ready` and `GET /live` on port 9000). See [Metrics server](#metrics-server-default-enabled) below.
+
+### MySQL
+
+```js
+import { createMySQLPool, createMySQLPoolFromEnv, mysqlReadyCheck, createUUID } from '@open-xchange/fastify-sdk/mysql'
+
+// From explicit options
+const pool = createMySQLPool({ host: 'localhost', database: 'mydb', user: 'root', password: '' })
+
+// From env vars (SQL_HOST, SQL_PORT, SQL_DB, SQL_USER, SQL_PASS, SQL_CONNECTIONS)
+const pool = createMySQLPoolFromEnv()
+
+// Multi-database from env (DB_<NAME>_HOST, DB_<NAME>_PORT, etc.)
+const pools = createMySQLPoolFromEnv({ names: 'users,analytics' })
+
+// Retry-based readiness check
+await mysqlReadyCheck(pool, { retries: 12, delay: 10_000, logger })
+
+// MySQL UUID generation
+const uuid = await createUUID(pool)
+```
+
+### PostgreSQL
+
+```js
+import { createPostgresPool, createPostgresPoolFromEnv } from '@open-xchange/fastify-sdk/postgres'
+
+// From env vars (DATABASE_HOST, DATABASE_PORT, DATABASE_NAME, DATABASE_USER, DATABASE_PASSWORD)
+// Supports SSL via DATABASE_SSL, DATABASE_SSL_CA_PATH, etc.
+const pool = createPostgresPoolFromEnv()
+```
+
+### Migrations (Umzug + MySQL)
+
+```js
+import { createMigrationRunner, executeMigrations } from '@open-xchange/fastify-sdk/migrations'
+
+const runner = createMigrationRunner({
+  pool,
+  migrationsGlob: 'src/migrations/*.mjs',
+  tableName: 'migrations',
+  logger
+})
+
+await executeMigrations(runner)
+```
+
+### Config (YAML + Joi + hot-reload)
+
+```js
+import { createConfigRegistry, Joi, defaultTrue } from '@open-xchange/fastify-sdk/config'
+
+const { registerConfigurationFile, getCurrent } = createConfigRegistry({ logger })
+
+const schema = Joi.object({
+  features: Joi.object({ chat: defaultTrue }).default()
+})
+
+await registerConfigurationFile('config.yaml', { schema, watch: true }, (data) => {
+  Object.assign(config, data)
+})
+
+const current = getCurrent('config.yaml')
+```
+
+### Redis
+
+```js
+import { createRedisClient, redisReadyCheck } from '@open-xchange/fastify-sdk/redis'
+
+// Reads REDIS_HOSTS, REDIS_MODE (standalone|sentinel|cluster), REDIS_PASSWORD, etc.
+const client = createRedisClient()
+await redisReadyCheck(client)
+```
+
+### Testing
+
+```js
+import { createTestApp, generateTokenForJwks, getJwks } from '@open-xchange/fastify-sdk/testing'
+
+// Creates Fastify with CORS/Helmet/Metrics/Logging disabled, metrics server off
+const app = await createTestApp({
+  dirname: import.meta.dirname,
+  routesDir: '../src/routes',
+  plugins: { jwt: true }
+})
+
+const token = await generateTokenForJwks({ userId: '1' }, 'kid', 'issuer.com')
+const jwks = await getJwks('kid')
+```
+
+### Lint
+
+```js
+// eslint.config.js
+import config from '@open-xchange/fastify-sdk/lint'
+
+export default [
+  ...config
+]
+```
+
+### Logging
+
+Foundation configures Pino with syslog-level mapping, redaction, and epoch timestamps. When running in a TTY (e.g. local development), logs are automatically pretty-printed with colors — no `pino-pretty` pipe needed.
+
+Override TTY detection with `LOG_PRETTY`:
+- `LOG_PRETTY=true` — force pretty printing (useful in CI or non-TTY environments)
+- `LOG_PRETTY=false` — force JSON output
+
+### Re-exports
+
+These are re-exported so consuming projects don't need to install them separately:
+
+```js
+import { fastify, fp, pino, promClient, createError, jose } from '@open-xchange/fastify-sdk'
+```
+
+## Plugins
+
+### CORS (default: enabled)
+
+Reads `ORIGINS` env var (comma-separated). Defaults: methods `GET, POST`, maxAge `86400`.
+
+### Helmet (default: enabled)
+
+Standard security headers. `contentSecurityPolicy: false`, `crossOriginEmbedderPolicy: false`, `crossOriginOpenerPolicy: same-origin-allow-popups`.
+
+### Logging (default: enabled)
+
+- `preHandler`: trace-logs request body
+- `onResponse`: debug-logs URL, status, responseTime (includes headers at trace level)
+
+### Metrics server (default: enabled)
+
+A separate Fastify instance on port 9000, serving health probes and Prometheus metrics.
+
+| Endpoint | Purpose | Response |
+|---|---|---|
+| `GET /live` | K8s liveness probe | `200 {"status":"ok"}` or `503 {"status":"error"}` |
+| `GET /ready` | K8s readiness probe | `200 {"status":"ok"}` or `503 {"status":"error"}` |
+| `GET /metrics` | Prometheus scraping | Prometheus text format |
+
+`/live` runs checks registered via `registerHealthCheck()`. `/ready` runs checks registered via `registerReadinessCheck()`. With no checks registered, both return 200.
+
+The metrics server starts automatically in `createApp()`'s `onReady` hook and closes in `onClose`. Disable with `metricsServer: false` (used by `createTestApp()` to avoid port binding in tests).
+
+Port 9000 is hardcoded to match all existing K8s probe and Prometheus configs.
+
+### Metrics plugin (default: enabled)
+
+Registers `fastify-metrics` collectors on the main app (request duration, etc.) but does **not** serve an endpoint — metrics are read from `prom-client`'s registry by the metrics server on port 9000.
+
+### Sensible (always enabled)
+
+Registers `@fastify/sensible`, providing `reply.notFound()`, `reply.badRequest()`, `app.httpErrors`, `request.to()`, and other convenience utilities on every app.
+
+### JWT (default: disabled)
+
+JWKS-based JWT verification using `jose.createRemoteJWKSet`. Verifies tokens against remote JWKS endpoints with OIDC discovery support. Also supports a custom key resolver for project-specific verification (e.g. local X.509 certificates).
+
+**Env vars:**
+- `OIDC_ISSUER` — comma-separated allowed issuers (e.g. `auth.example.com, *.example.org`). Supports wildcard subdomains.
+
+**Modes:**
+
+| `OIDC_ISSUER` | `key` option | Behavior |
+|---|---|---|
+| Set | — | OIDC/JWKS verification via `createRemoteJWKSet` |
+| Not set | Provided | Custom key resolver (e.g. local certificates) |
+| Not set | Not provided | `app.verifyJWT` always returns 401 |
+
+**OIDC mode** (`plugins: { jwt: true }` with `OIDC_ISSUER` set):
+1. Extracts the `iss` claim from the JWT and checks it against the allowlist
+2. On first request per issuer, tries OIDC discovery (`.well-known/openid-configuration`) to find `jwks_uri`
+3. Falls back to `.well-known/jwks.json` if discovery is unavailable
+4. Uses `jose.createRemoteJWKSet` for key resolution — jose handles caching and key rotation internally
+
+**Custom key mode** (`plugins: { jwt: { key: fn } }` without `OIDC_ISSUER`):
+
+For services that verify tokens against project-specific keys (e.g. local X.509 certificates):
+
+```js
+import { getLocalPublicKey } from './modules/jwks.js'
+
+const app = await createApp({
+  plugins: {
+    jwt: { key: (request, token) => getLocalPublicKey(token) }
+  }
+})
+```
+
+The `key` function receives `(request, token)` where `token` has `header` (with `kid`, `alg`) and `payload` (with `iss`, `sub`, etc.). It should return the verification key (SPKI public key string or `{}` to reject).
+
+**Decorators:**
+- `app.verifyJWT` — async function for use as `onRequest` hook. Returns 401 if token is invalid or JWT is not configured.
+- `request.jwtVerify()` — from `@fastify/jwt`, available when `OIDC_ISSUER` is set or `key` is provided.
+
+**`jwtAuthHook`** — ready-made autohook that requires a valid JWT on every request in the encapsulated scope. Use as the default export of an `autohooks.js` file to protect all routes in that directory:
+
+```js
+// src/routes/api/autohooks.js
+export { jwtAuthHook as default } from '@open-xchange/fastify-sdk'
+```
+
+This is equivalent to:
+
+```js
+export default async function (app) {
+  app.addHook('onRequest', app.verifyJWT)
+}
+```
+
+### Static files (default: disabled)
+
+Serves static files using `@fastify/static`. Defaults to `public/` directory with pre-compressed file support.
+
+```js
+plugins: {
+  static: true,                     // Serve from public/ with preCompressed: true
+  static: { root: 'dist', prefix: '/assets' }  // Customize
+}
+```
+
+### Swagger (default: disabled)
+
+Conditional on `enabled` option. Serves Swagger UI at `/api-docs`.
+
+## Running standalone
+
+Foundation runs Fastify standalone. Health endpoints, metrics, and logging are all built in:
+
+```js
+import { createApp } from '@open-xchange/fastify-sdk'
+
+const app = await createApp({ dirname: import.meta.dirname })
+
+try {
+  await app.listen({ host: process.env.BIND_ADDR, port: Number(process.env.PORT) })
+} catch (err) {
+  app.log.error(err)
+  process.exit(1)
+}
+```
+
+This starts:
+- **Port 8080** (app) — your routes (auto-loaded from `routes/`), with CORS, Helmet, logging, JWT
+- **Port 9000** (metrics server) — `GET /live`, `GET /ready`, `GET /metrics`
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm lint
+```
+
+## License
+
+AGPL-3.0-or-later

package/lib/app.js

@@ -0,0 +1,324 @@
+import { randomUUID } from 'node:crypto'
+import { dirname, join } from 'node:path'
+import { existsSync } from 'node:fs'
+import fastify from 'fastify'
+import autoLoad from '@fastify/autoload'
+import ajvErrors from 'ajv-errors'
+import { loadEnv } from './dotenv.js'
+import { getLogger } from './logger.js'
+
+import sensible from '@fastify/sensible'
+import corsPlugin from './plugins/cors.js'
+import helmetPlugin from './plugins/helmet.js'
+import loggingPlugin from './plugins/logging.js'
+import metricsPlugin from './plugins/metrics.js'
+
+/** @typedef {import('fastify').FastifyInstance} FastifyInstance */
+/** @typedef {import('fastify').FastifyServerOptions} FastifyServerOptions */
+/** @typedef {import('@fastify/cors').FastifyCorsOptions} FastifyCorsOptions */
+/** @typedef {import('@fastify/static').FastifyStaticOptions} FastifyStaticOptions */
+
+/**
+ * @typedef {object} PluginsConfig
+ * @property {boolean | FastifyCorsOptions} [cors=true] CORS plugin. Pass `true` for defaults (reads ORIGINS env var), an object to customize, or `false` to disable.
+ * @property {boolean | import('@fastify/helmet').FastifyHelmetOptions} [helmet=true] Helmet security headers. Pass `true` for defaults, an object to customize, or `false` to disable.
+ * @property {boolean} [logging=true] Request/response logging plugin.
+ * @property {boolean} [metrics=true] Prometheus metrics plugin (fastify-metrics).
+ * @property {boolean | JwtConfig} [jwt=true] JWT verification plugin. Pass `true` for OIDC/JWKS via `OIDC_ISSUER` env var, or an object with `{ key }` for a custom key resolver.
+ * @property {boolean | SwaggerConfig} [swagger=true] Swagger/OpenAPI documentation plugin. Enabled when `EXPOSE_API_DOCS=true`.
+ * @property {boolean | StaticConfig} [static=false] Static file serving plugin (@fastify/static). Pass `true` to serve from `public/` with `preCompressed: true`, or an object to customize.
+ */
+
+/**
+ * @typedef {object} SwaggerConfig
+ * @property {boolean} [enabled] Whether to enable Swagger UI. Defaults to `EXPOSE_API_DOCS === 'true'` env var.
+ * @property {object} [openapi] OpenAPI specification object passed to @fastify/swagger.
+ */
+
+/**
+ * @typedef {object} StaticConfig
+ * @property {string} [root='public'] Directory to serve files from. Relative paths are resolved against `dirname`.
+ * @property {boolean} [preCompressed=true] Whether to serve pre-compressed `.gz`/`.br` files when available.
+ * @property {string} [prefix] URL prefix for static files (e.g. `'/assets'`).
+ * @property {string} [logLevel] Fastify log level for static file requests. Defaults to `'warn'` when `LOG_LEVEL` is `debug` or `info` (to reduce noise), otherwise uses `LOG_LEVEL`.
+ * @property {(res: import('http').ServerResponse, path: string, stat: import('fs').Stats) => void} [setHeaders] Function to set custom headers on static file responses.
+ */
+
+/**
+ * @typedef {object} JwtConfig
+ * @property {(request: import('fastify').FastifyRequest, token: object) => Promise<string|object>} [key] Custom key resolver function. Called with `(request, token)` where `token` has `header` and `payload`. Return the verification key (e.g. SPKI public key string). Used as fallback when `OIDC_ISSUER` is not set.
+ */
+
+/**
+ * @typedef {object} ConfigFileRegistration
+ * @property {string} filename Config file name relative to CONFIG_PATH (e.g. `'config.yaml'`).
+ * @property {import('joi').Schema} [schema] Joi schema to validate the parsed YAML against.
+ * @property {boolean} [optional=false] If `true`, skip silently when the file doesn't exist.
+ * @property {boolean} [watch=true] Watch the file for changes and re-read/validate on change.
+ * @property {(data: object) => void} [callback] Called with the validated config data on initial read and on every change.
+ */
+
+/**
+ * @typedef {object} CreateAppOptions
+ * @property {string} [dirname] Absolute path to the application root. Defaults to `dirname(process.argv[1])`.
+ * @property {string | null} [pluginsDir='plugins'] Directory for auto-loaded Fastify plugins (relative to `dirname`). Set to `null` to disable.
+ * @property {string | null} [routesDir='routes'] Directory for auto-loaded route files (relative to `dirname`). Set to `null` to disable.
+ * @property {object} [routes] Options passed to @fastify/autoload for routes.
+ * @property {string} [routes.prefix] URL prefix for all routes (e.g. `'/api'`).
+ * @property {boolean} [routes.routeParams] Enable route parameters from directory names.
+ * @property {FastifyServerOptions} [fastify] Options passed directly to the Fastify constructor.
+ * @property {PluginsConfig} [plugins] Plugin configuration.
+ * @property {boolean} [metricsServer=true] Start a metrics/health server on port 9000 (`/live`, `/ready`, `/metrics`).
+ * @property {{ mysql?: true | Record<string, import('mysql2/promise').Pool> }} [database] Database pools to manage. Pass `{ mysql: true }` to create pools from the `DATABASES` env var, or pass pre-created pools. Foundation waits for readiness, registers health checks, and closes pools on shutdown.
+ * @property {ConfigFileRegistration | ConfigFileRegistration[]} [config] YAML configuration files to watch. Foundation creates the config registry, registers files on ready, and closes the watcher on shutdown.
+ * @property {() => void | Promise<void>} [onReady] Hook called when the Fastify instance is ready.
+ * @property {() => void | Promise<void>} [onClose] Hook called when the Fastify instance is closing (before shutdown).
+ */
+
+/**
+ * @typedef {FastifyInstance & { start: () => Promise<void> }} FoundationApp
+ */
+
+/**
+ * Creates a pre-configured Fastify application with standard OX infrastructure:
+ * env loading, logging, CORS, helmet, metrics, Swagger, static files, auto-loaded
+ * plugins/routes, a metrics server on port 9000, and graceful shutdown handlers.
+ *
+ * @param {CreateAppOptions} options
+ * @returns {Promise<FoundationApp>} A Fastify instance with an added `start()` method.
+ *
+ * @example
+ * const app = await createApp({
+ *   plugins: { cors: { methods: ['GET', 'POST'] }, swagger: { openapi: { info: { title: 'My API', version: '1.0.0' } } } },
+ *   routes: { prefix: '/api' }
+ * })
+ * await app.start()
+ */
+export async function createApp (options = {}) {
+  const {
+    dirname: dir = dirname(process.argv[1]),
+    pluginsDir = 'plugins',
+    routesDir = 'routes',
+    routes: routeOptions = {},
+    fastify: fastifyOptions = {},
+    plugins = {},
+    metricsServer = true,
+    database: databaseOptions,
+    config: configOptions,
+    onReady,
+    onClose
+  } = options
+
+  // Load env vars
+  loadEnv()
+
+  const app = fastify({
+    requestIdLogLabel: 'requestId',
+    disableRequestLogging: true,
+    loggerInstance: getLogger(),
+    connectionTimeout: 30000,
+    genReqId: () => randomUUID(),
+    ajv: {
+      customOptions: { allErrors: true },
+      plugins: [ajvErrors]
+    },
+    ...fastifyOptions
+  })
+
+  // Register universal plugins based on config (defaults: cors, helmet, logging, metrics ON)
+  const {
+    cors = true,
+    helmet = true,
+    logging = true,
+    metrics = true,
+    jwt: jwtConfig = true,
+    swagger: swaggerConfig = true,
+    static: staticConfig = false
+  } = plugins
+
+  await app.register(sensible)
+
+  if (cors) {
+    await app.register(corsPlugin, cors === true ? {} : cors)
+  }
+
+  if (helmet) {
+    await app.register(helmetPlugin, helmet === true ? {} : helmet)
+  }
+
+  if (logging) {
+    await app.register(loggingPlugin)
+  }
+
+  if (metrics) {
+    await app.register(metricsPlugin)
+  }
+
+  // Opt-in plugins
+  if (jwtConfig) {
+    const { default: jwtPlugin } = await import('./plugins/jwt.js')
+    await app.register(jwtPlugin, jwtConfig === true ? {} : jwtConfig)
+  }
+
+  if (swaggerConfig) {
+    const enabled = swaggerConfig.enabled !== undefined ? swaggerConfig.enabled : process.env.EXPOSE_API_DOCS === 'true'
+    if (enabled) {
+      const { default: swaggerPlugin } = await import('./plugins/swagger.js')
+      await app.register(swaggerPlugin, swaggerConfig === true ? {} : swaggerConfig)
+    }
+  }
+
+  if (staticConfig) {
+    const { default: fastifyStatic } = await import('@fastify/static')
+    const logLevelEnv = process.env.LOG_LEVEL
+    const defaultLogLevel = logLevelEnv === 'debug' || logLevelEnv === 'info' ? 'warn' : logLevelEnv
+    const { root = 'public', preCompressed = true, logLevel = defaultLogLevel, ...restStaticConfig } = staticConfig === true ? {} : staticConfig
+    const isAbsolute = root.startsWith('/')
+    await app.register(fastifyStatic, {
+      root: isAbsolute ? root : join(dir, root),
+      preCompressed,
+      logLevel,
+      ...restStaticConfig
+    })
+  }
+
+  // Auto-load project-specific plugins
+  if (dir && pluginsDir) {
+    const pluginsDirPath = join(dir, pluginsDir)
+    if (existsSync(pluginsDirPath)) {
+      app.register(autoLoad, { dir: pluginsDirPath })
+    }
+  }
+
+  // Auto-load routes
+  if (dir && routesDir) {
+    const routesDirPath = join(dir, routesDir)
+    if (existsSync(routesDirPath)) {
+      const { prefix, ...restRouteOptions } = routeOptions
+      const autoLoadOptions = {
+        dir: routesDirPath,
+        autoHooks: true,
+        cascadeHooks: true,
+        ...restRouteOptions
+      }
+      if (prefix) {
+        app.register(async (scoped) => {
+          scoped.register(autoLoad, autoLoadOptions)
+        }, { prefix })
+      } else {
+        app.register(autoLoad, autoLoadOptions)
+      }
+    }
+  }
+
+  // Database lifecycle: readiness checks, health probes, graceful shutdown
+  if (databaseOptions?.mysql) {
+    const { mysqlReadyCheck, getMySQLPools } = await import('./database/mysql.js')
+    const { registerReadinessCheck, mysqlHealthCheck } = await import('./health.js')
+    const pools = databaseOptions.mysql === true ? getMySQLPools() : databaseOptions.mysql
+    const entries = Object.entries(pools)
+
+    // Register health checks for each pool
+    for (const [, pool] of entries) {
+      registerReadinessCheck(() => mysqlHealthCheck(pool))
+    }
+
+    // Wait for all pools to be ready
+    for (const [name, pool] of entries) {
+      await mysqlReadyCheck(pool, { logger: app.log })
+      app.log.info(`Database "${name}" is ready`)
+    }
+
+    // Close all pools on shutdown
+    app.addHook('onClose', async () => {
+      await Promise.all(entries.map(([, pool]) => pool.end()))
+    })
+  }
+
+  // Start metrics server immediately so K8s probes work during initialization
+  if (metricsServer !== false) {
+    const { createMetricsServer } = await import('./metrics-server.js')
+    const server = createMetricsServer()
+    await server.listen({ port: 9000, host: process.env.BIND_ADDR })
+    app.log.info('Metrics server listening on port 9000')
+
+    app.addHook('onClose', async () => {
+      await server.close()
+    })
+  }
+
+  // Configuration file watching
+  if (configOptions) {
+    const { createConfigRegistry } = await import('./config/registry.js')
+    const registry = createConfigRegistry({ logger: app.log })
+    const files = Array.isArray(configOptions) ? configOptions : [configOptions]
+
+    app.addHook('onReady', async () => {
+      for (const { filename, schema, optional, watch, callback } of files) {
+        await registry.registerConfigurationFile(filename, { schema, optional, watch }, callback)
+      }
+    })
+
+    app.addHook('onClose', async () => {
+      await registry.close()
+    })
+  }
+
+  if (onReady) {
+    app.addHook('onReady', onReady)
+  }
+
+  if (onClose) {
+    app.addHook('onClose', onClose)
+  }
+
+  // Register process signal handlers for graceful shutdown
+  async function shutdown () {
+    await app.close()
+  }
+
+  async function onUncaughtException (err) {
+    app.log.fatal({ err }, `Uncaught Exception: ${err.message}`)
+    await shutdown()
+  }
+
+  async function onUnhandledRejection (err) {
+    app.log.fatal({ err }, `Unhandled Rejection: ${err.message}`)
+    await shutdown()
+  }
+
+  async function onSigint () {
+    app.log.info('SIGINT received, initiating graceful shutdown...')
+    await shutdown()
+  }
+
+  process.on('uncaughtException', onUncaughtException)
+  process.on('unhandledRejection', onUnhandledRejection)
+  process.on('SIGINT', onSigint)
+
+  app.addHook('onClose', () => {
+    process.removeListener('uncaughtException', onUncaughtException)
+    process.removeListener('unhandledRejection', onUnhandledRejection)
+    process.removeListener('SIGINT', onSigint)
+  })
+
+  /**
+   * Start the app server. Reads `BIND_ADDR` and `PORT` (default 8080) from
+   * environment variables, logs the listen address, and begins accepting connections.
+   * On failure, logs the error and closes the app.
+   * @returns {Promise<void>}
+   */
+  app.start = async function () {
+    try {
+      const host = process.env.BIND_ADDR
+      const port = Number(process.env.PORT) || 8080
+      app.log.info(`Starting on ${host || '0.0.0.0'}:${port}`)
+      await app.listen({ host, port })
+    } catch (err) {
+      app.log.error({ err }, `Failed to start: ${err.message}`)
+      await app.close()
+    }
+  }
+
+  return app
+}

package/lib/config/index.js

@@ -0,0 +1,4 @@
+export { createConfigRegistry } from './registry.js'
+export { readConfigurationFile, validateAndUpdateConfiguration, fileExists, getConfigPath } from './read.js'
+export { defaultTrue, defaultFalse, customString, optionalCustomString, customURL } from './util.js'
+export { default as Joi } from 'joi'