@open-xchange/fastify-sdk 0.1.0 → 0.2.1

package/README.md

@@ -32,14 +32,13 @@ That single call replaces ~500 lines of boilerplate (logger, CORS, Helmet, metri
 
 | 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` | `createApp`, `createMetricsServer`, `createLogger`, `logger`, `loadEnv`, `requireEnv`, `jwtAuthHook`, health check helpers, re-exports of `fastify`, `fp`, `pino`, `promClient`, `createError`, `jose` |
+| `@open-xchange/fastify-sdk/mariadb` | `createMariaDBPool`, `createMariaDBPoolFromEnv`, `getMariaDBPools`, `mariadbReadyCheck`, `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
 
@@ -66,7 +65,7 @@ Creates a configured Fastify instance with standard OX defaults.
     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
+  database: { mariadb: true },          // Auto-manages pool readiness, health checks, shutdown
   config: {                            // YAML config file watching
     filename: 'config.yaml',
     schema,                            // Joi schema for validation
@@ -98,35 +97,51 @@ Pass custom options to override defaults (e.g. `createLogger({ level: 'debug' })
 
 Loads environment variables from `.env.defaults` then `.env` using Node's built-in `process.loadEnvFile()`. No external dependency needed.
 
+### `requireEnv(keys)`
+
+Validates that the given environment variables are set and non-empty. Prints a clear error message and exits the process if any are missing. Call after `loadEnv()` and before `createApp()`.
+
+```js
+import { loadEnv, requireEnv } from '@open-xchange/fastify-sdk'
+
+loadEnv()
+
+requireEnv(['PORT', 'ORIGINS', 'REDIS_HOSTS'])
+
+if (process.env.SQL_ENABLED === 'true') {
+  requireEnv(['SQL_HOST', 'SQL_USER', 'SQL_PASS', 'SQL_DB'])
+}
+```
+
 ### Health check helpers
 
 ```js
-import { registerReadinessCheck, registerHealthCheck, mysqlHealthCheck } from '@open-xchange/fastify-sdk'
+import { registerReadinessCheck, registerHealthCheck, mariadbHealthCheck } from '@open-xchange/fastify-sdk'
 
-registerReadinessCheck(async () => { await mysqlHealthCheck(pool) })
-registerHealthCheck(async () => { await mysqlHealthCheck(pool) })
+registerReadinessCheck(async () => { await mariadbHealthCheck(pool) })
+registerHealthCheck(async () => { await mariadbHealthCheck(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
+### MariaDB
 
 ```js
-import { createMySQLPool, createMySQLPoolFromEnv, mysqlReadyCheck, createUUID } from '@open-xchange/fastify-sdk/mysql'
+import { createMariaDBPool, createMariaDBPoolFromEnv, mariadbReadyCheck, createUUID } from '@open-xchange/fastify-sdk/mariadb'
 
 // From explicit options
-const pool = createMySQLPool({ host: 'localhost', database: 'mydb', user: 'root', password: '' })
+const pool = createMariaDBPool({ 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()
+const pool = createMariaDBPoolFromEnv()
 
 // Multi-database from env (DB_<NAME>_HOST, DB_<NAME>_PORT, etc.)
-const pools = createMySQLPoolFromEnv({ names: 'users,analytics' })
+const pools = createMariaDBPoolFromEnv({ names: 'users,analytics' })
 
 // Retry-based readiness check
-await mysqlReadyCheck(pool, { retries: 12, delay: 10_000, logger })
+await mariadbReadyCheck(pool, { retries: 12, delay: 10_000, logger })
 
-// MySQL UUID generation
+// MariaDB UUID generation
 const uuid = await createUUID(pool)
 ```
 
@@ -140,7 +155,7 @@ import { createPostgresPool, createPostgresPoolFromEnv } from '@open-xchange/fas
 const pool = createPostgresPoolFromEnv()
 ```
 
-### Migrations (Umzug + MySQL)
+### Migrations (Umzug + MariaDB)
 
 ```js
 import { createMigrationRunner, executeMigrations } from '@open-xchange/fastify-sdk/migrations'
@@ -201,9 +216,11 @@ const jwks = await getJwks('kid')
 
 ### Lint
 
+Use `@open-xchange/lint` directly as a devDependency:
+
 ```js
 // eslint.config.js
-import config from '@open-xchange/fastify-sdk/lint'
+import config from '@open-xchange/lint'
 
 export default [
   ...config

package/lib/app.js

@@ -5,7 +5,7 @@ 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 { logger } from './logger.js'
 
 import sensible from '@fastify/sensible'
 import corsPlugin from './plugins/cors.js'
@@ -41,7 +41,7 @@ import metricsPlugin from './plugins/metrics.js'
  * @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.
+ * @property {(res: import('http').ServerResponse, path: string, stat: import('fs').Stats) => void} [setHeaders] Function to set custom headers on static file responses. Defaults to setting a `version` header from `CI_COMMIT_SHA` (or `'main'`).
  */
 
 /**
@@ -69,7 +69,7 @@ import metricsPlugin from './plugins/metrics.js'
  * @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 {{ mariadb?: true | Record<string, import('mariadb').Pool> }} [database] Database pools to manage. Pass `{ mariadb: 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).
@@ -106,7 +106,8 @@ export async function createApp (options = {}) {
     database: databaseOptions,
     config: configOptions,
     onReady,
-    onClose
+    onClose,
+    processHandlers = true
   } = options
 
   // Load env vars
@@ -115,7 +116,7 @@ export async function createApp (options = {}) {
   const app = fastify({
     requestIdLogLabel: 'requestId',
     disableRequestLogging: true,
-    loggerInstance: getLogger(),
+    loggerInstance: logger,
     connectionTimeout: 30000,
     genReqId: () => randomUUID(),
     ajv: {
@@ -172,12 +173,16 @@ export async function createApp (options = {}) {
     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 defaultSetHeaders = (res) => {
+      res.setHeader('version', process.env.CI_COMMIT_SHA || 'main')
+    }
+    const { root = 'public', preCompressed = true, logLevel = defaultLogLevel, setHeaders = defaultSetHeaders, ...restStaticConfig } = staticConfig === true ? {} : staticConfig
     const isAbsolute = root.startsWith('/')
     await app.register(fastifyStatic, {
       root: isAbsolute ? root : join(dir, root),
       preCompressed,
       logLevel,
+      setHeaders,
       ...restStaticConfig
     })
   }
@@ -212,20 +217,20 @@ export async function createApp (options = {}) {
   }
 
   // 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
+  if (databaseOptions?.mariadb) {
+    const { mariadbReadyCheck, getMariaDBPools } = await import('./database/mariadb.js')
+    const { registerReadinessCheck, mariadbHealthCheck } = await import('./health.js')
+    const pools = databaseOptions.mariadb === true ? getMariaDBPools() : databaseOptions.mariadb
     const entries = Object.entries(pools)
 
     // Register health checks for each pool
     for (const [, pool] of entries) {
-      registerReadinessCheck(() => mysqlHealthCheck(pool))
+      registerReadinessCheck(() => mariadbHealthCheck(pool))
     }
 
     // Wait for all pools to be ready
     for (const [name, pool] of entries) {
-      await mysqlReadyCheck(pool, { logger: app.log })
+      await mariadbReadyCheck(pool, { logger: app.log })
       app.log.info(`Database "${name}" is ready`)
     }
 
@@ -273,34 +278,36 @@ export async function createApp (options = {}) {
   }
 
   // Register process signal handlers for graceful shutdown
-  async function shutdown () {
-    await app.close()
-  }
+  if (processHandlers) {
+    async function shutdown () {
+      await app.close()
+    }
 
-  async function onUncaughtException (err) {
-    app.log.fatal({ err }, `Uncaught Exception: ${err.message}`)
-    await shutdown()
-  }
+    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 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()
-  }
+    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)
+    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)
-  })
+    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

package/lib/database/{mysql.js → mariadb.js}

@@ -1,20 +1,20 @@
-import mysql from 'mysql2/promise'
+import * as mariadb from 'mariadb'
 
 const defaults = {
   dateStrings: ['DATE', 'DATETIME'],
-  timezone: 'Z',
+  timezone: '+00:00',
   namedPlaceholders: true
 }
 
-export function createMySQLPool (options = {}) {
-  const pool = mysql.createPool({ ...defaults, ...options })
+export function createMariaDBPool (options = {}) {
+  const pool = mariadb.createPool({ ...defaults, ...options })
   pool.on('connection', (connection) => {
     connection.query('SET SESSION time_zone="+00:00"')
   })
   return pool
 }
 
-export function createMySQLPoolFromEnv ({ prefix = 'SQL', names } = {}) {
+export function createMariaDBPoolFromEnv ({ prefix = 'SQL', names } = {}) {
   if (names) {
     const dbNames = typeof names === 'string'
       ? names.split(',').map(n => n.trim().toLowerCase()).filter(Boolean)
@@ -23,7 +23,7 @@ export function createMySQLPoolFromEnv ({ prefix = 'SQL', names } = {}) {
     const pools = {}
     for (const name of dbNames) {
       const envPrefix = `DB_${name.toUpperCase()}`
-      pools[name] = createMySQLPool({
+      pools[name] = createMariaDBPool({
         host: process.env[`${envPrefix}_HOST`],
         port: Number(process.env[`${envPrefix}_PORT`]) || 3306,
         database: process.env[`${envPrefix}_NAME`],
@@ -36,7 +36,7 @@ export function createMySQLPoolFromEnv ({ prefix = 'SQL', names } = {}) {
     return pools
   }
 
-  return createMySQLPool({
+  return createMariaDBPool({
     host: process.env[`${prefix}_HOST`],
     port: Number(process.env[`${prefix}_PORT`]) || 3306,
     database: process.env[`${prefix}_DB`],
@@ -46,7 +46,7 @@ export function createMySQLPoolFromEnv ({ prefix = 'SQL', names } = {}) {
   })
 }
 
-export async function mysqlReadyCheck (pool, { retries = 12, delay = 10_000, logger } = {}) {
+export async function mariadbReadyCheck (pool, { retries = 12, delay = 10_000, logger } = {}) {
   for (let i = 1; i <= retries; i++) {
     try {
       await pool.query('SELECT 1')
@@ -64,13 +64,13 @@ let _pools
 
 /**
  * Returns a singleton pool map created from the `DATABASES` env var.
- * Calls `createMySQLPoolFromEnv({ names: process.env.DATABASES })` on first access.
- * @returns {Record<string, import('mysql2/promise').Pool>}
+ * Calls `createMariaDBPoolFromEnv({ names: process.env.DATABASES })` on first access.
+ * @returns {Record<string, import('mariadb').Pool>}
  */
-export function getMySQLPools () {
+export function getMariaDBPools () {
   if (!_pools) {
     const names = process.env.DATABASES
-    _pools = names ? createMySQLPoolFromEnv({ names }) : {}
+    _pools = names ? createMariaDBPoolFromEnv({ names }) : {}
   }
   return _pools
 }

package/lib/dotenv.js

@@ -4,3 +4,25 @@ export function loadEnv () {
   try { process.loadEnvFile('.env') } catch {}
   try { process.loadEnvFile('.env.defaults') } catch {}
 }
+
+/**
+ * Validates that the given environment variables are set and non-empty.
+ * Throws an error listing all missing variables if any are not set.
+ *
+ * @param {string[]} keys — Environment variable names to check.
+ * @throws {Error} If one or more variables are missing or empty.
+ *
+ * @example
+ * requireEnv(['PORT', 'ORIGINS', 'REDIS_HOSTS'])
+ *
+ * if (process.env.SQL_ENABLED === 'true') {
+ *   requireEnv(['SQL_HOST', 'SQL_USER', 'SQL_PASS', 'SQL_DB'])
+ * }
+ */
+export function requireEnv (keys) {
+  const missing = keys.filter(key => !process.env[key])
+  if (missing.length > 0) {
+    console.error(`Missing required environment variables: ${missing.join(', ')}`)
+    process.exit(1)
+  }
+}

package/lib/health.js

@@ -22,7 +22,7 @@ export function clearChecks () {
   healthChecks.length = 0
 }
 
-export async function mysqlHealthCheck (pool) {
+export async function mariadbHealthCheck (pool) {
   await pool.query('SELECT 1')
 }
 

package/lib/index.js

@@ -1,8 +1,8 @@
 export { createApp } from './app.js'
 export { createMetricsServer } from './metrics-server.js'
-export { createLogger, getLogger, pinoConfig } from './logger.js'
-export { loadEnv } from './dotenv.js'
-export { registerHealthCheck, registerReadinessCheck, clearChecks, mysqlHealthCheck, postgresHealthCheck, redisHealthCheck } from './health.js'
+export { createLogger, logger, pinoConfig } from './logger.js'
+export { loadEnv, requireEnv } from './dotenv.js'
+export { registerHealthCheck, registerReadinessCheck, clearChecks, mariadbHealthCheck, postgresHealthCheck, redisHealthCheck } from './health.js'
 export { default as metricsPlugin } from './plugins/metrics.js'
 
 /**

package/lib/logger.js

@@ -43,18 +43,7 @@ export function createLogger (options = {}) {
   return pino({ ...pinoConfig, ...options })
 }
 
-let _defaultLogger
-
-/**
- * Returns a shared logger singleton. Creates it on first call
- * (calling loadEnv() to ensure env vars like LOG_LEVEL are loaded).
- */
-export function getLogger () {
-  if (!_defaultLogger) {
-    loadEnv()
-    _defaultLogger = createLogger()
-  }
-  return _defaultLogger
-}
+loadEnv()
+export const logger = createLogger()
 
 export { pinoConfig }

package/lib/metrics-server.js

@@ -1,6 +1,7 @@
 import fastify from 'fastify'
 import promClient from 'prom-client'
 import { getReadinessChecks, getHealthChecks } from './health.js'
+import { logger } from './logger.js'
 
 export function createMetricsServer () {
   const app = fastify({ logger: false })
@@ -26,7 +27,8 @@ async function handleChecks (reply, checks) {
   try {
     await Promise.all(checks.map(fn => fn()))
     return { status: 'ok' }
-  } catch {
+  } catch (err) {
+    logger.debug({ err }, 'Health check failed')
     reply.code(503)
     return { status: 'error' }
   }

package/lib/testing/index.js

@@ -22,6 +22,7 @@ export async function createTestApp (options = {}) {
   return createApp({
     pluginsDir: null,
     metricsServer: false,
+    processHandlers: false,
     ...rest,
     plugins: defaultTestPlugins,
     fastify: {

package/package.json

@@ -1,23 +1,17 @@
 {
   "name": "@open-xchange/fastify-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Shared foundation package for OX App Suite Node.js services",
   "private": false,
   "type": "module",
   "exports": {
     ".": "./lib/index.js",
-    "./mysql": "./lib/database/mysql.js",
+    "./mariadb": "./lib/database/mariadb.js",
     "./postgres": "./lib/database/postgres.js",
     "./migrations": "./lib/database/migrations.js",
     "./config": "./lib/config/index.js",
     "./redis": "./lib/redis/index.js",
-    "./testing": "./lib/testing/index.js",
-    "./lint": "./lib/lint/index.js"
-  },
-  "scripts": {
-    "lint": "eslint . --cache --fix",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
+    "./testing": "./lib/testing/index.js"
   },
   "author": "Open-Xchange",
   "license": "AGPL-3.0-or-later",
@@ -45,7 +39,7 @@
   },
   "peerDependencies": {
     "ioredis": "^5.9.0",
-    "mysql2": "^3.16.0",
+    "mariadb": "^3.0.0",
     "pg": "^8.16.0",
     "umzug": "^3.8.2"
   },
@@ -53,7 +47,7 @@
     "ioredis": {
       "optional": true
     },
-    "mysql2": {
+    "mariadb": {
       "optional": true
     },
     "pg": {
@@ -68,7 +62,7 @@
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^9.39.2",
     "ioredis": "^5.9.2",
-    "mysql2": "^3.16.3",
+    "mariadb": "^3.4.1",
     "pg": "^8.18.0",
     "umzug": "^3.8.2",
     "vitest": "^4.0.18"
@@ -76,10 +70,9 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.27.0",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "unrs-resolver"
-    ]
+  "scripts": {
+    "lint": "eslint . --cache --fix",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   }
-}
+}

package/lib/lint/index.js

@@ -1,5 +0,0 @@
-import config from '@open-xchange/lint'
-
-export default [
-  ...config
-]