bro-framework 2.3.1 → 2.4.1

package/README.md

@@ -27,8 +27,11 @@
 ## Table of Contents
 
 - [Getting Started](#getting-started)
+- [Configuration](#configuration)
 - [The Core Experience](#the-core-experience)
 - [Deep-Dive Features](#deep-dive-features)
+- [Route Reference](#route-reference)
+- [Context Reference](#context-reference)
 - [Architecture & Request Lifecycle](#architecture--request-lifecycle)
 - [Tech Stack Breakdown](#tech-stack-breakdown)
 - [CLI Reference](#cli-reference)
@@ -48,6 +51,38 @@ npm run dev
 
 That's it! Your zero-boilerplate backend is now running with hot-reloading enabled.
 
+## Configuration
+
+Configuration lives in `bro.config.js`:
+
+```javascript
+import { defineConfig } from 'bro-framework';
+
+export default defineConfig({
+  server: { port: 5000, cors: true, helmet: true },
+  auth: {
+    jwtSecret: process.env.JWT_SECRET,
+    expiresIn: '7d',
+    apiKey: process.env.API_KEY
+  },
+  locale: { directory: './locale', defaultLocale: 'en' },
+  rateLimit: { windowMs: 15 * 60 * 1000, max: 100 },
+  docs: process.env.NODE_ENV !== 'production',
+  redisUrl: process.env.REDIS_URL,
+  db: async () => {
+    // Initialize database connection here
+  },
+  sockets: async (io, db) => {
+    // Setup Socket.IO event listeners here
+  },
+  onShutdown: async (db) => {
+    // Close application-owned database resources here.
+  }
+});
+```
+
+`cors: false` disables HTTP CORS middleware. Helmet is enabled by default and can be disabled with `helmet: false`. Redis is optional; when configured it powers distributed rate limiting, route caching, and Socket.IO scaling. In `NODE_ENV=test`, bro.js can inject `ioredis-mock`; install it in the consuming project's development dependencies.
+
 ---
 
 ## The Core Experience
@@ -68,6 +103,13 @@ export default defineRoute({
     title: z.string().min(5),
     content: z.string()
   }),
+  query: z.object({
+    draft: z.coerce.boolean().default(false)
+  }),
+  response: z.object({
+    success: z.boolean(),
+    updated: z.number()
+  }),
   handler: async ({ body, params, user, db, io }) => {
     // 1. Data is already validated. user is already authenticated.
     
@@ -89,6 +131,8 @@ export default defineRoute({
 });
 ```
 
+Validation schemas are flat and must be declared directly as `body`, `params`, and `query`. The deprecated nested `schema: { body, params, query }` form is rejected during route loading. The optional `response` schema documents the successful JSON response in OpenAPI; it does not runtime-validate handler output.
+
 ---
 
 ## Deep-Dive Features
@@ -99,23 +143,49 @@ Create a `.js` file in the `routes/` directory, and it automatically becomes an
 ### Bouncer-Grade Validation
 Powered by Zod. Attach a schema to `body`, `query`, or `params` directly in your route definition. If the client sends malformed data, `bro.js` automatically rejects the request with a structured `400 Bad Request` JSON payload *before* your handler ever executes. You never have to manually validate inputs again. You can also define a `response` schema to strongly type your OpenAPI documentation (strictly opt-in; arbitrary 200s work out of the box).
 
-### Zero-Config JWTs
+### Zero-Config Auth (JWTs, RBAC, API Keys)
 Add `auth: true` to your route config. `bro.js` will intercept the request, extract the `Authorization: Bearer <token>` header, verify the signature using your `jwtSecret`, and inject the decoded payload directly into `ctx.user`.
+You can also use Role-Based Access Control by passing an array of roles (e.g. `auth: ['admin']`) or enforce service-to-service communication with `auth: 'api-key'`. API keys are read from `auth.apiKey` or `API_KEY` and support zero-downtime rotation with an array:
+
+```javascript
+auth: {
+  apiKey: ['current-key', 'next-key']
+}
+```
+
+Clients send the selected key in the `x-api-key` header. API-key routes are represented as `apiKeyAuth` operations in OpenAPI.
 
 ### Context Injection
 Stop importing singleton database connections and socket instances into every file. Define your `db` and `sockets` setup once in `bro.config.js`. `bro.js` orchestrates the initialization and injects both instances directly into the `ctx` object for every request handler.
 
+### Redis Caching and Lifecycle
+Set `redisUrl` to enable distributed rate limiting, route caching, and Socket.IO pub/sub scaling. Add `cache: 60` to a route to cache its JSON response for 60 seconds. Cache keys include the request URL, resolved locale, and authorization/API-key identity; do not cache responses with dimensions that are not represented in the key.
+
+The programmatic `createServer()` API returns `shutdown()`. It stops scheduled tasks, closes Socket.IO, closes Redis clients, runs the optional `onShutdown(db)` hook, and closes the HTTP server. The CLI calls it automatically on `SIGINT` and `SIGTERM`.
+
 ### Zero-YAML Live Documentation
 If you've ever hand-written OpenAPI YAML, you know the pain. `bro.js` parses your Zod schemas and automatically serves a stunning, interactive [Scalar](https://scalar.com/) API playground at `/docs`. It's highly secure: by default, these internal docs are disabled in production mode.
 
 ### The Frontend SDK Generator
-Tired of writing frontend `fetch` wrappers? Run `bro sdk`. The CLI will parse your backend routes and compile a `bro-sdk.js` file for your frontend. It features built-in token management, request stringification, and type-safe deep tree traversal (e.g., `api.users.id("123").post(data)`).
+Tired of writing frontend `fetch` wrappers? Run `bro sdk`. The CLI parses your backend routes and compiles a JavaScript `bro-sdk.js` file. It includes token and locale headers, query serialization, URL-encoded dynamic parameters, and deep tree traversal (e.g., `api.users.id("123").get()`). Configure it with `setBaseURL()`, `setTokenKey()`, and `setLocale()`.
 
 ### Background Task Scheduler
 Don't spin up a separate worker server. Drop a JavaScript file anywhere in the `tasks/` folder, export a cron string (e.g., `"0 0 * * *"`), and an async handler. `bro.js` natively schedules it as a background worker with full access to your injected database and WebSocket contexts.
 
 ### Zero-Boilerplate File Uploads
-Add `upload: true` to a route. `bro.js` automatically hooks into `multer`, parses the `multipart/form-data` payload in memory, and injects the files directly into `ctx.files`. It also natively supports granular file limits, restricting max sizes, parts, and fielding counts instantly to protect your RAM. (Note: Use the `storage` configuration for heavy production disk writing to prevent memory exhaustion).
+Add `upload: true` to a route. bro.js uses Multer to parse `multipart/form-data` and inject files into the context. Use `single`, `array`, or `fields` for explicit field handling:
+
+```javascript
+export default defineRoute({
+  upload: {
+    single: 'avatar',
+    limits: { fileSize: 5 * 1024 * 1024 }
+  },
+  handler: ({ file }) => ({ name: file?.originalname })
+});
+```
+
+`ctx.file` is used by `single()`. `ctx.files` is an array for `array()` or a field-to-array object for `fields()`. Defaults include limits for file size, file count, fields, parts, and field size. Use `storage` for production disk/object-storage integration instead of retaining large buffers in memory.
 
 ### File-Based Locale
 Create a `locale/` folder with one translation file per locale, such as `locale/en.js` and `locale/fr.js`. Export a plain object from each file, then use `t()` in any route:
@@ -132,6 +202,46 @@ export default defineRoute({
 
 The locale is negotiated dynamically using RFC 9110 `Accept-Language` headers, supporting full region fallback and custom defaults, and the generated SDK can securely set it via `setLocale('fr')`.
 
+## Route Reference
+
+| Option | Type | Purpose |
+| :--- | :--- | :--- |
+| `auth` | `boolean \| string[] \| 'api-key'` | JWT, role, or API-key protection. |
+| `body` | Zod schema | Validates JSON request bodies. |
+| `params` | Zod schema | Validates URL parameters. |
+| `query` | Zod schema | Validates query-string values. |
+| `response` | Zod schema | Documents successful JSON output in OpenAPI. |
+| `cache` | number | Redis response-cache duration in seconds. |
+| `rateLimit` | `{ windowMs, max }` | Route-specific request limiting. |
+| `upload` | boolean or options | Enables Multer parsing and limits. |
+| `summary` | string | OpenAPI operation summary. |
+
+Dynamic route files use bracket parameters such as `routes/users/[id].get.js`. Nested dynamic directories are supported. HTTP method suffixes are `get`, `post`, `put`, `delete`, `patch`, `options`, and `head`.
+
+## Context Reference
+
+Handlers receive:
+
+| Property | Description |
+| :--- | :--- |
+| `body` | Validated body data. |
+| `params` | Validated path parameters. |
+| `query` | Validated query data. |
+| `user` | Decoded JWT payload when JWT auth is used. |
+| `db` | Value returned by `config.db`. |
+| `io` | Socket.IO server instance. |
+| `redis` | Redis client when Redis is enabled or test mode is active. |
+| `file` | Single uploaded file from `upload.single()`. |
+| `files` | Array or field map from `array()`/`fields()`. |
+| `locale` | Resolved request locale. |
+| `t` | Translation function, `t(key, values)`. |
+| `jwt` | Configured JWT signing helper. |
+| `env` | Parsed environment data when configured, otherwise `process.env`. |
+
+## Testing
+
+For Redis-backed integration tests without an external Redis server, install `ioredis-mock` in the consuming project and run with `NODE_ENV=test`. bro.js injects a mock Redis client and exercises cache, rate-limit, Socket.IO adapter, and shutdown paths.
+
 ---
 
 ## Architecture & Request Lifecycle
@@ -185,6 +295,8 @@ The locale is negotiated dynamically using RFC 9110 `Accept-Language` headers, s
 | **API Reference** | Scalar | Auto-generated, interactive Swagger/OpenAPI documentation. |
 | **Task Scheduler** | node-cron | Reliable internal background task orchestration. |
 | **File Parsing** | multer | Zero-boilerplate `multipart/form-data` file extraction. |
+| **Caching & Scaling** | Redis | Optional zero-config route caching, distributed rate-limiting, and WebSocket scaling. |
+| **Security** | Helmet | Auto-configured industry-standard HTTP security headers. |
 
 ---
 

package/bin/bro.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import path from 'path';
 import fs from 'fs';
@@ -29,13 +29,15 @@ export default defineConfig({
   // Server Settings
   server: {
     port: 5000,
-    cors: true // Set to true to allow all, or pass a CORS options object
+    cors: true, // Set to true to allow all, or pass a CORS options object
+    helmet: true // Enable security headers
   },
 
   // Authentication Settings
   auth: {
     jwtSecret: 'dev_secret_please_change',
-    expiresIn: '7d'
+    expiresIn: '7d',
+    apiKey: process.env.API_KEY || ['dev_key_1', 'dev_key_2'] // Supports array for zero-downtime rotation
   },
 
   // Optional file-based API translations
@@ -53,6 +55,9 @@ export default defineConfig({
     max: 100 // limit each IP to 100 requests per windowMs
   },
 
+  // Redis Configuration (Auto-scales WebSockets, distributed caches & rate-limiting)
+  redisUrl: process.env.REDIS_URL, // e.g., 'redis://localhost:6379'
+
   // WebSockets Setup
   sockets: async (io, db) => {
     io.on('connection', (socket) => {
@@ -79,6 +84,11 @@ export default defineConfig({
     // return mongoose.connection; 
     // --------------------------
     return null;
+  },
+
+  // Graceful Teardown Hook
+  onShutdown: async (db) => {
+    // Close application-owned database resources gracefully here
   }
 });
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bro-framework",
-  "version": "2.3.1",
+  "version": "2.4.1",
   "description": "The No-BS Backend Framework for Node.js",
   "repository": {
     "type": "git",
@@ -27,14 +27,17 @@
   ],
   "dependencies": {
     "@scalar/express-api-reference": "^0.10.18",
+    "@socket.io/redis-adapter": "^8.3.0",
     "chokidar": "^5.0.0",
     "cors": "^2.8.6",
     "dotenv": "^16.4.5",
     "express": "^4.21.1",
     "express-rate-limit": "^8.7.0",
+    "helmet": "^8.3.0",
     "jsonwebtoken": "^9.0.2",
     "multer": "^2.3.0",
     "node-cron": "^4.6.0",
+    "redis": "^6.2.1",
     "socket.io": "^4.8.3",
     "tsx": "^4.23.13",
     "zod": "^3.23.8",
@@ -43,6 +46,7 @@
   "keywords": [
     "bro",
     "brojs",
+    "bro.js",
     "bro-framework",
     "framework",
     "backend",
@@ -84,5 +88,8 @@
     "ai-friendly",
     "developer-experience",
     "dx"
-  ]
+  ],
+  "devDependencies": {
+    "ioredis-mock": "^8.13.1"
+  }
 }

package/src/index.d.ts

@@ -2,6 +2,18 @@ import { z, ZodTypeAny } from 'zod';
 
 type InferZod<T> = T extends ZodTypeAny ? z.infer<T> : any;
 
+export interface UploadedFile {
+  fieldname: string;
+  originalname: string;
+  encoding: string;
+  mimetype: string;
+  size: number;
+  destination?: string;
+  filename?: string;
+  path?: string;
+  buffer?: Buffer;
+}
+
 export interface BroContext<Body = any, Params = any, Query = any> {
   env?: any;
   jwt?: { sign: (payload: any, options?: any) => string };
@@ -11,19 +23,22 @@ export interface BroContext<Body = any, Params = any, Query = any> {
   user?: any;
   db?: any;
   io?: any;
-  files?: any[];
+  file?: UploadedFile;
+  files?: UploadedFile[] | Record<string, UploadedFile[]>;
   locale: string;
   t: (key: string, values?: Record<string, unknown>) => string;
   error?: any;
+  redis?: any;
 }
 
 export interface RouteConfig<Body = any, Params = any, Query = any> {
-  auth?: boolean;
+  auth?: boolean | string[] | 'api-key';
   upload?: boolean | { limits?: any, fields?: { name: string, maxCount?: number }[], single?: string, array?: string, fileFilter?: any, storage?: any };
   body?: Body;
   params?: Params;
   query?: Query;
   response?: ZodTypeAny;
+  cache?: number;
   rateLimit?: {
     windowMs: number;
     max: number;
@@ -48,6 +63,7 @@ export interface BroConfig {
   server?: {
     port?: number;
     cors?: boolean | object;
+    helmet?: boolean | object;
   };
   locale?: {
     directory?: string;
@@ -56,6 +72,7 @@ export interface BroConfig {
   auth?: {
     jwtSecret?: string;
     expiresIn?: string | number;
+    apiKey?: string | string[];
   };
   docs?: boolean | { auth?: { user: string; pass: string } };
   rateLimit?: {
@@ -73,6 +90,7 @@ export interface BroConfig {
   db?: () => Promise<any> | any;
   sockets?: (io: any, db: any) => Promise<void> | void;
   onShutdown?: (db: any) => Promise<void> | void;
+  redisUrl?: string;
 }
 
 export function defineConfig(config: BroConfig): BroConfig;

package/src/router.js

@@ -158,7 +158,9 @@ export async function loadRoutes(app, routesDir, createHandler, openApiSpec) {
       }
       
       // Auto-inject security definition if auth is true
-      if (config.auth) {
+      if (config.auth === 'api-key') {
+        operation.security = [{ apiKeyAuth: [] }];
+      } else if (config.auth) {
         operation.security = [{ bearerAuth: [] }];
       }
       

package/src/server.js

@@ -2,9 +2,13 @@ import express from 'express';
 import cors from 'cors';
 import http from 'node:http';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { Server } from 'socket.io';
 import rateLimit from 'express-rate-limit';
 import multer from 'multer';
+import helmet from 'helmet';
+import { createClient } from 'redis';
+import { createAdapter } from '@socket.io/redis-adapter';
 import { apiReference } from '@scalar/express-api-reference';
 import { verifyJwt, signJwt } from './auth.js';
 import { loadLocale } from './locale.js';
@@ -28,6 +32,21 @@ export async function createServer(globalConfig, routesDir, db) {
   const localeDirectory = globalConfig.locale?.directory || path.join(process.cwd(), 'locale');
   let locale = await loadLocale(localeDirectory, globalConfig.locale);
   
+  const helmetConfig = globalConfig.server?.helmet !== undefined ? globalConfig.server.helmet : true;
+  if (helmetConfig !== false) {
+    const userConfig = typeof helmetConfig === 'object' ? helmetConfig : {};
+    app.use(helmet({
+      ...userConfig,
+      contentSecurityPolicy: userConfig.contentSecurityPolicy ?? {
+        directives: {
+          ...helmet.contentSecurityPolicy.getDefaultDirectives(),
+          "script-src": ["'self'", "'unsafe-inline'"],
+          "style-src": ["'self'", "'unsafe-inline'"],
+        },
+      }
+    }));
+  }
+
   const corsConfig = globalConfig.server?.cors !== undefined ? globalConfig.server.cors : true;
   
   if (corsConfig !== false) {
@@ -36,12 +55,84 @@ export async function createServer(globalConfig, routesDir, db) {
   
   app.use(express.json());
   
+  const safeConnect = async (client) => {
+    if (typeof client.connect !== 'function') return;
+    if (client.status && client.status !== 'wait') return;
+    try {
+      await client.connect();
+    } catch (err) {
+      if (!err.message.includes('already connecting') && !err.message.includes('already connected')) {
+        throw err;
+      }
+    }
+  };
+
+  let redisClient = null;
+  let pubClient = null;
+  let subClient = null;
+  
+  try {
+    if (globalConfig.redisUrl) {
+      redisClient = createClient({ url: globalConfig.redisUrl });
+      redisClient.on('error', (err) => console.error('[bro.js] Redis Error:', err));
+      await safeConnect(redisClient);
+    } else if (process.env.NODE_ENV === 'test') {
+      try {
+        const IORedisMock = (await import('ioredis-mock')).default;
+        redisClient = new IORedisMock();
+        redisClient.connect = async () => {};
+        redisClient.setEx = redisClient.setex.bind(redisClient);
+      } catch (err) {
+        throw new Error("ioredis-mock is required for test mode. Please install it as a devDependency to use NODE_ENV=test.");
+      }
+    }
+  } catch (err) {
+    if (redisClient) await redisClient.quit().catch(() => {});
+    throw err;
+  }
+
   if (globalConfig.rateLimit) {
-    app.use(rateLimit(globalConfig.rateLimit));
+    if (redisClient) {
+      const fallbackLimiter = rateLimit(globalConfig.rateLimit);
+      app.use(async (req, res, next) => {
+        try {
+          const key = `rate_limit:global:${req.ip}`;
+          const current = await redisClient.incr(key);
+          if (current === 1) {
+            await redisClient.expire(key, Math.floor(globalConfig.rateLimit.windowMs / 1000));
+          }
+          if (current > globalConfig.rateLimit.max) {
+            return res.status(429).json({ error: 'Too Many Requests' });
+          }
+          next();
+        } catch (err) {
+          console.error('[bro.js] Redis Global Rate Limit Error:', err);
+          fallbackLimiter(req, res, next);
+        }
+      });
+    } else {
+      app.use(rateLimit(globalConfig.rateLimit));
+    }
   }
   
   const io = new Server(server, { cors: typeof corsConfig === 'object' ? corsConfig : undefined });
   
+  try {
+    if (redisClient) {
+      pubClient = redisClient.duplicate();
+      subClient = redisClient.duplicate();
+      await Promise.all([safeConnect(pubClient), safeConnect(subClient)]);
+      io.adapter(createAdapter(pubClient, subClient));
+    }
+  } catch (err) {
+    await Promise.allSettled([
+      redisClient?.quit(),
+      pubClient?.quit(),
+      subClient?.quit()
+    ].filter(Boolean));
+    throw err;
+  }
+  
   if (globalConfig.sockets) {
     await globalConfig.sockets(io, db);
   }
@@ -55,7 +146,27 @@ export async function createServer(globalConfig, routesDir, db) {
     const querySchema = routeConfig.query;
     
     if (routeConfig.rateLimit) {
-      middlewares.push(rateLimit(routeConfig.rateLimit));
+      if (redisClient) {
+        const fallbackLimiter = rateLimit(routeConfig.rateLimit);
+        middlewares.push(async (req, res, next) => {
+          try {
+            const key = `rate_limit:${req.ip}:${req.originalUrl}`;
+            const current = await redisClient.incr(key);
+            if (current === 1) {
+              await redisClient.expire(key, Math.floor(routeConfig.rateLimit.windowMs / 1000));
+            }
+            if (current > routeConfig.rateLimit.max) {
+              return res.status(429).json({ error: 'Too Many Requests' });
+            }
+            next();
+          } catch (err) {
+            console.error('[bro.js] Redis Route Rate Limit Error:', err);
+            fallbackLimiter(req, res, next);
+          }
+        });
+      } else {
+        middlewares.push(rateLimit(routeConfig.rateLimit));
+      }
     }
     
     if (routeConfig.upload) {
@@ -91,6 +202,7 @@ export async function createServer(globalConfig, routesDir, db) {
           env: globalConfig.envData || process.env,
           db,
           io,
+          redis: redisClient,
           body: req.body,
           params: req.params,
           query: req.query,
@@ -106,18 +218,40 @@ export async function createServer(globalConfig, routesDir, db) {
           }
         };
 
-        const authHeader = req.headers.authorization;
-        if ((!authHeader || !authHeader.startsWith('Bearer ')) && routeConfig.auth) {
-          return res.status(401).json({ error: 'Unauthorized', details: 'Missing or invalid Bearer token' });
-        }
-        
-        const token = authHeader?.split(' ')[1] ?? '';
-        const authResult = verifyJwt(token, globalConfig.jwtSecret);
-        
-        if (!authResult.valid && routeConfig.auth) {
-          return res.status(401).json({ error: 'Unauthorized', details: authResult.error });
+        if (routeConfig.auth === 'api-key') {
+          const apiKey = req.headers['x-api-key'];
+          const validKey = globalConfig.auth?.apiKey || process.env.API_KEY;
+          
+          let isValid = false;
+          if (Array.isArray(validKey)) {
+            isValid = validKey.includes(apiKey);
+          } else {
+            isValid = apiKey && apiKey === validKey;
+          }
+          
+          if (!isValid) {
+            return res.status(401).json({ error: 'Unauthorized', details: 'Missing or invalid API key' });
+          }
+        } else if (routeConfig.auth) {
+          const authHeader = req.headers.authorization;
+          if (!authHeader || !authHeader.startsWith('Bearer ')) {
+            return res.status(401).json({ error: 'Unauthorized', details: 'Missing or invalid Bearer token' });
+          }
+          
+          const token = authHeader?.split(' ')[1] ?? '';
+          const authResult = verifyJwt(token, globalConfig.jwtSecret);
+          
+          if (!authResult.valid) {
+            return res.status(401).json({ error: 'Unauthorized', details: authResult.error });
+          }
+          ctx.user = authResult.payload ?? null;
+          
+          if (Array.isArray(routeConfig.auth)) {
+             if (!ctx.user || !ctx.user.role || !routeConfig.auth.includes(ctx.user.role)) {
+                return res.status(403).json({ error: 'Forbidden', details: 'Insufficient role permissions' });
+             }
+          }
         }
-        ctx.user = authResult?.payload ?? null;
 
         if (paramsSchema) {
           const result = paramsSchema.safeParse(req.params);
@@ -147,9 +281,29 @@ export async function createServer(globalConfig, routesDir, db) {
            throw new Error('Route "handler" is missing or is not a function');
         }
 
+        let cacheKey = null;
+        if (routeConfig.cache && redisClient) {
+          const authIdentity = crypto.createHash('sha256').update(req.headers.authorization || req.headers['x-api-key'] || 'anonymous').digest('hex');
+          cacheKey = `bro:cache:${req.method}:${req.originalUrl}:${requestLocale}:${authIdentity}`;
+          try {
+            const cached = await redisClient.get(cacheKey);
+            if (cached) {
+              const parsed = JSON.parse(cached);
+              if (!res.headersSent) res.status(200).json(parsed);
+              return;
+            }
+          } catch (err) {
+            console.error('[bro.js] Cache parsing failed, deleting key:', cacheKey);
+            await redisClient.del(cacheKey).catch(() => {});
+          }
+        }
+
         const responseData = await routeConfig.handler(ctx);
         
         if (!res.headersSent) {
+           if (cacheKey && routeConfig.cache) {
+             await redisClient.setEx(cacheKey, routeConfig.cache, JSON.stringify(responseData));
+           }
            res.status(200).json(responseData);
         }
 
@@ -183,6 +337,11 @@ export async function createServer(globalConfig, routesDir, db) {
           type: 'http',
           scheme: 'bearer',
           bearerFormat: 'JWT'
+        },
+        apiKeyAuth: {
+          type: 'apiKey',
+          in: 'header',
+          name: 'x-api-key'
         }
       },
       responses: {
@@ -256,6 +415,11 @@ export async function createServer(globalConfig, routesDir, db) {
     isShuttingDown = true;
     if (taskManager) taskManager.stopAll();
     if (io) io.close();
+    await Promise.allSettled([
+      redisClient?.quit(),
+      pubClient?.quit(),
+      subClient?.quit()
+    ].filter(Boolean));
     
     if (typeof globalConfig.onShutdown === 'function') {
       try {