bro-framework 2.4.5 → 3.0.1

package/src/engine.js

@@ -0,0 +1,251 @@
+
+export function resolveIdentity(req, config = {}) {
+  const headers = req.headers || {};
+  let ip = req.ip || (req.socket && req.socket.remoteAddress) || 'anonymous';
+
+  const getHeader = (k) => {
+    if (typeof headers.get === 'function') return headers.get(k);
+    if (typeof headers[k] === 'string') return headers[k];
+    if (Array.isArray(headers[k])) return headers[k][0];
+    return null;
+  };
+
+  if (config.trustProxy) {
+    const xff = getHeader('x-forwarded-for');
+    if (xff) {
+      const ips = xff.split(',').map(s => s.trim()).filter(Boolean);
+      if (ips.length > 0) {
+         ip = ips[0];
+      }
+    }
+  }
+
+  const auth = getHeader('authorization');
+  return getHeader('x-api-key') || (auth && auth.startsWith('Bearer ') ? auth.split(' ')[1] : null) || ip;
+}
+
+
+
+
+
+export class RouteRegistry {
+  constructor() {
+    this.routes = [];
+  }
+  register(routeInfo) {
+    this.routes.push(routeInfo);
+  }
+  getRoutes() {
+    return this.routes;
+  }
+  reset() {
+    this.routes = [];
+  }
+  clear() {
+    this.routes = [];
+  }
+}
+
+/**
+ * Validates Zod errors into RFC 7807 problem details
+ */
+export function formatZodError(zodError) {
+  const details = {};
+  for (const err of zodError.errors) {
+    details[err.path.join('.')] = err.message;
+  }
+  return details;
+}
+
+export function formatErrorEnvelope(status, title, details, reqId, instanceUrl = 'about:blank') {
+  const codeMap = { 400: 'BAD_REQUEST', 401: 'UNAUTHORIZED', 403: 'FORBIDDEN', 404: 'NOT_FOUND', 429: 'TOO_MANY_REQUESTS' };
+  const code = codeMap[status] || (status >= 500 ? 'INTERNAL_ERROR' : 'ERROR');
+
+  const payload = {
+    type: `https://brojs.dev/errors/${code.toLowerCase()}`,
+    title,
+    status,
+    instance: instanceUrl,
+    requestId: reqId
+  };
+  
+  if (details) {
+    if (typeof details === 'string') payload.detail = details;
+    else payload.errors = details;
+  }
+  
+  return payload;
+}
+
+/**
+ * The transport-agnostic execution pipeline.
+ * @param {Object} routeConfig - The exported configuration from defineRoute.
+ * @param {Object} requestData - Standardized request object: { method, originalUrl, headers, body, query, params, ip, files }
+ * @param {Object} globalConfig - The global framework configuration.
+ * @param {Object} ctxExtras - Additional context properties (e.g. db, redis, io, pluginManager).
+ * @returns {Promise<{ status: number, body: any, headers: Record<string, string>, error?: Error }>}
+ */
+export async function executeRequest(routeConfig, requestData, globalConfig, ctxExtras) {
+  const reqId = requestData.headers['x-request-id'] || (ctxExtras.generateId ? ctxExtras.generateId() : Date.now().toString());
+  let responseHeaders = { 'X-Request-Id': reqId };
+  let errorHeaders = { 'X-Request-Id': reqId, 'Content-Type': 'application/problem+json' };
+
+  try {
+    const ctx = {
+      req: requestData.originalUrl,
+      method: requestData.method,
+      ip: requestData.ip,
+      headers: requestData.headers,
+      locale: requestData.locale,
+      requestId: reqId,
+      ...ctxExtras,
+      env: globalConfig.envData || process.env,
+      body: requestData.body,
+      query: requestData.query,
+      params: requestData.params,
+      files: requestData.files,
+      user: null
+    };
+
+    if (ctxExtras.pluginManager) {
+      await ctxExtras.pluginManager.runOnContext(ctx);
+    }
+
+    // Rate Limiting Evaluation
+    const activeRateLimit = routeConfig.rateLimit === false ? null : (routeConfig.rateLimit || globalConfig.rateLimit);
+    const redisClient = ctxExtras.redis;
+
+    if (activeRateLimit && redisClient) {
+      const rlKey = generateRateLimitKey ? await generateRateLimitKey(requestData, globalConfig) : `bro:rl:${requestData.originalUrl}:${requestData.ip}`;
+      try {
+        const current = await redisClient.incr(rlKey);
+        const windowSeconds = Math.floor(activeRateLimit.windowMs / 1000);
+        if (current === 1) {
+          await redisClient.expire(rlKey, windowSeconds);
+        }
+        if (current > activeRateLimit.max) {
+          responseHeaders['Retry-After'] = windowSeconds.toString();
+          return { status: 429, headers: responseHeaders, body: formatErrorEnvelope(429, 'Too Many Requests', null, reqId) };
+        }
+      } catch (err) {
+        console.error('[bro.js] Rate Limit Error:', err);
+      }
+    }
+
+    // Auth verification
+    if (routeConfig.auth === 'api-key') {
+      const apiKey = requestData.headers['x-api-key'] || (requestData.headers['authorization'] || '').replace('Bearer ', '');
+      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 { status: 401, headers: errorHeaders, body: formatErrorEnvelope(401, 'Unauthorized', 'Missing or invalid API key', reqId, requestData.originalUrl) };
+      }
+    } else if (routeConfig.auth) {
+      const authHeader = requestData.headers['authorization'];
+      if (!authHeader || !authHeader.startsWith('Bearer ')) {
+        return { status: 401, headers: errorHeaders, body: formatErrorEnvelope(401, 'Unauthorized', 'Missing or invalid Bearer token', reqId, requestData.originalUrl) };
+      }
+      
+      const token = authHeader.split(' ')[1] ?? '';
+      const authResult = verifyJwt(token, globalConfig.jwtSecret);
+      
+      if (!authResult.valid) {
+        return { status: 401, headers: errorHeaders, body: formatErrorEnvelope(401, 'Unauthorized', authResult.error, reqId, requestData.originalUrl) };
+      }
+      ctx.user = authResult.payload ?? null;
+      
+      if (Array.isArray(routeConfig.auth) && routeConfig.auth.length > 0) {
+         if (!ctx.user || !ctx.user.role || !routeConfig.auth.includes(ctx.user.role)) {
+            return { status: 403, headers: errorHeaders, body: formatErrorEnvelope(403, 'Forbidden', 'Insufficient role permissions', reqId, requestData.originalUrl) };
+         }
+      }
+    }
+
+    // Zod validation
+    if (routeConfig.params) {
+      const result = await routeConfig.params.safeParseAsync(requestData.params || {});
+      if (!result.success) {
+        return { status: 400, headers: errorHeaders, body: formatErrorEnvelope(400, 'Invalid URL Parameters', formatZodError(result.error), reqId, requestData.originalUrl) };
+      }
+      ctx.params = result.data;
+    }
+    
+    if (routeConfig.body) {
+      const result = await routeConfig.body.safeParseAsync(requestData.body || {});
+      if (!result.success) {
+        return { status: 400, headers: errorHeaders, body: formatErrorEnvelope(400, 'Invalid Request Body', formatZodError(result.error), reqId, requestData.originalUrl) };
+      }
+      ctx.body = result.data;
+    }
+
+    if (routeConfig.query) {
+       const result = await routeConfig.query.safeParseAsync(requestData.query || {});
+       if (!result.success) {
+         return { status: 400, headers: errorHeaders, body: formatErrorEnvelope(400, 'Invalid Query Parameters', formatZodError(result.error), reqId, requestData.originalUrl) };
+       }
+       ctx.query = result.data;
+    }
+
+    if (typeof routeConfig.handler !== 'function') {
+       throw new Error('Route "handler" is missing or is not a function');
+    }
+
+    // Cache evaluation
+    let cacheKey = null;
+    
+    if (routeConfig.cache && redisClient && requestData.method === 'GET') {
+      const authIdentity = crypto.createHash('sha256').update(String(requestData.headers['authorization'] || requestData.headers['x-api-key'] || requestData.ip || 'anonymous')).digest('hex');
+      const locale = requestData.locale || 'en';
+      // URL has query parameters, so use originalUrl completely
+      cacheKey = `bro:cache:${requestData.method}:${requestData.originalUrl}:${locale}:${authIdentity}`;
+      
+      try {
+        const cached = await redisClient.get(cacheKey);
+        if (cached) {
+          return { status: 200, headers: responseHeaders, body: JSON.parse(cached) };
+        }
+      } catch (err) {
+        console.error('[bro.js] Cache parsing failed, deleting key:', cacheKey);
+        await redisClient.del(cacheKey).catch(() => {});
+      }
+    }
+
+    // Execute User Handler
+    let responseData = await routeConfig.handler(ctx);
+    
+    // Runtime Response Validation
+    if (routeConfig.response && globalConfig.validateResponse !== false) {
+       const result = await routeConfig.response.safeParseAsync(responseData);
+       if (!result.success) {
+          console.error('[bro.js] ⚠️ Response Validation Failed:', formatZodError(result.error));
+          if (process.env.NODE_ENV === 'production' && globalConfig.validateResponse === 'strict') {
+             throw new Error('Response Validation Failed');
+          } else if (globalConfig.validateResponse !== 'warn') {
+             // Strip invalid data, throw 500
+             throw new Error('Response Validation Failed');
+          }
+       } else {
+          responseData = result.data;
+       }
+    }
+    
+    if (cacheKey && routeConfig.cache) {
+      await redisClient.setEx(cacheKey, routeConfig.cache, JSON.stringify(responseData));
+    }
+    
+    return { status: 200, headers: responseHeaders, body: responseData };
+
+  } catch (err) {
+    const status = err.status || 500;
+    const title = status === 500 ? 'Internal Server Error' : err.message;
+    const isProd = process.env.NODE_ENV === 'production';
+    return { status, headers: errorHeaders, body: formatErrorEnvelope(status, isProd && status >= 500 ? 'Internal Server Error' : title, isProd && status >= 500 ? null : err.details, reqId, requestData.originalUrl), error: status >= 500 ? err : undefined };
+  }
+}

package/src/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import { z, ZodTypeAny } from 'zod';
 
 type InferZod<T> = T extends ZodTypeAny ? z.infer<T> : any;
@@ -14,14 +15,20 @@ export interface UploadedFile {
   buffer?: Buffer;
 }
 
-export interface BroContext<Body = any, Params = any, Query = any> {
-  env?: any;
+export interface AppContext<Env = any, Db = any, User = any> {
+  env: Env;
+  db: Db;
+  user: User;
+}
+
+export interface BroContext<Body = any, Params = any, Query = any, App extends AppContext = AppContext> {
+  env?: App['env'];
   jwt?: { sign: (payload: any, options?: any) => string };
   body: InferZod<Body>;
   params: InferZod<Params>;
   query: InferZod<Query>;
-  user?: any;
-  db?: any;
+  user?: App['user'];
+  db?: App['db'];
   io?: any;
   file?: UploadedFile;
   files?: UploadedFile[] | Record<string, UploadedFile[]>;
@@ -29,10 +36,12 @@ export interface BroContext<Body = any, Params = any, Query = any> {
   t: (key: string, values?: Record<string, unknown>) => string;
   error?: any;
   redis?: any;
+  requestId?: string;
 }
 
-export interface RouteConfig<Body = any, Params = any, Query = any> {
+export interface RouteConfig<Body = any, Params = any, Query = any, Response = any, App extends AppContext = AppContext> {
   auth?: boolean | string[] | 'api-key';
+    operationId?: string;
   upload?: boolean | { limits?: any, fields?: { name: string, maxCount?: number }[], single?: string, array?: string, fileFilter?: any, storage?: any };
   body?: Body;
   params?: Params;
@@ -44,12 +53,12 @@ export interface RouteConfig<Body = any, Params = any, Query = any> {
     max: number;
   };
   summary?: string;
-  handler: (ctx: BroContext<Body, Params, Query>) => Promise<any> | any;
+  handler: (ctx: BroContext<Body, Params, Query, App>) => Promise<Response extends import('zod').ZodTypeAny ? import('zod').infer<Response> : any> | (Response extends import('zod').ZodTypeAny ? import('zod').infer<Response> : any);
 }
 
-export function defineRoute<Body = any, Params = any, Query = any>(
-  config: RouteConfig<Body, Params, Query>
-): RouteConfig<Body, Params, Query>;
+export function defineRoute<Body = any, Params = any, Query = any, Response = any, App extends AppContext = AppContext>(
+  config: RouteConfig<Body, Params, Query, Response, App>
+): RouteConfig<Body, Params, Query, Response, App>;
 
 export function loadLocale(directory: string, options?: { defaultLocale?: string }): Promise<{
   locales: string[];
@@ -58,12 +67,40 @@ export function loadLocale(directory: string, options?: { defaultLocale?: string
   translate: (locale: string, key: string, values?: Record<string, unknown>) => string;
 }>;
 
+
+export interface BroPlugin {
+  name: string;
+  version: string;
+  order?: number;
+  onInit?: (globalConfig: BroConfig, app: any) => void | Promise<void>;
+  onContext?: (ctx: BroContext) => any | Promise<any>;
+  onRequest?: (req: any, res: any) => void | Promise<void>;
+  onError?: (err: any, req: any, res: any) => void | Promise<void>;
+  onShutdown?: () => void | Promise<void>;
+}
 export interface BroConfig {
+  routesDir?: string;
+  tasksDir?: string;
+  logger?: { level?: string; [key: string]: any };
+  plugins?: BroPlugin[];
+  fixtures?: Record<string, any>;
+  stores?: Record<string, any>;
+  health?: boolean | { dbCheck?: (db: any) => Promise<any> };
+  locales?: Record<string, any>;
+  defaultLocale?: string;
+  envData?: any;
+  redis?: any;
+  port?: number;
+  jwtSecret?: string;
+  trustProxy?: boolean;
+  validateResponse?: boolean | 'strict' | 'warn';
   env?: ZodTypeAny;
   server?: {
     port?: number;
     cors?: boolean | object;
     helmet?: boolean | object;
+    timeoutMs?: number;
+    headersTimeoutMs?: number;
   };
   locale?: {
     directory?: string;

package/src/index.js

@@ -27,3 +27,13 @@ export function defineConfig(config) {
 
 export { z };
 export { loadLocale } from './locale.js';
+export { createServer } from './server.js';
+export { createTestHarness as test } from './testing.js';
+export { PluginManager, ObservabilityPlugin, SecurityPlugin } from './plugins.js';
+export { createPinoAdapter, setupOpenTelemetry, createDashboardEventBus } from './observability.js';
+export { BaseDatabaseAdapter, PostgresAdapter } from './database.js';
+export { SecureUploadPipeline, LocalStorageAdapter, S3StorageAdapter } from './uploads.js';
+export { TaskManager } from './task-engine.js';
+export { OidcProvider, PolicyEvaluator, ApiKeyManager, tenantContextPlugin } from './policy-auth.js';
+
+export { RouteRegistry } from './engine.js';

package/src/logger.js

@@ -77,3 +77,50 @@ export function printHotReload(fileName, event, reloadTimeMs, resourceType = 'Ro
   console.log(`\n  ${colors.cyan}${resourceType} updated:${colors.reset} ${colors.bold}${fileName}${colors.reset} ${colors.dim}(${event})${colors.reset}`);
   console.log(`  ${colors.dim}Remapped in ${time}ms${colors.reset}\n`);
 }
+
+export function createLogger(config = {}) {
+  const isJson = config.format === 'json';
+  const levelPriority = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
+  const currentLevel = levelPriority[config.level] ?? levelPriority.info;
+
+  const redactKeys = config.redact || ['password', 'token', 'secret', 'authorization'];
+  
+  const redact = (obj) => {
+    if (typeof obj !== 'object' || obj === null) return obj;
+    if (Array.isArray(obj)) return obj.map(redact);
+    const newObj = { ...obj };
+    for (const key of Object.keys(newObj)) {
+      if (redactKeys.some(r => key.toLowerCase().includes(r))) {
+        newObj[key] = '[REDACTED]';
+      } else if (typeof newObj[key] === 'object') {
+        newObj[key] = redact(newObj[key]);
+      }
+    }
+    return newObj;
+  };
+
+  const log = (level, message, meta = {}) => {
+    if (levelPriority[level] < currentLevel) return;
+    const timestamp = new Date().toISOString();
+    
+    if (isJson) {
+      console[level === 'debug' ? 'log' : level](JSON.stringify({ level, timestamp, message, ...redact(meta) }));
+    } else {
+      const colorMap = { debug: colors.dim, info: colors.cyan, warn: colors.yellow, error: colors.red };
+      const c = colorMap[level] || colors.reset;
+      let metaStr = Object.keys(meta).length ? ` ${colors.dim}${JSON.stringify(redact(meta))}${colors.reset}` : '';
+      console[level === 'debug' ? 'log' : level](`${colors.dim}[${timestamp}]${colors.reset} ${c}[${level.toUpperCase()}]${colors.reset} ${message}${metaStr}`);
+    }
+  };
+
+  return {
+    debug: (msg, meta) => log('debug', msg, meta),
+    info: (msg, meta) => log('info', msg, meta),
+    warn: (msg, meta) => log('warn', msg, meta),
+    error: (msg, meta) => log('error', msg, meta),
+    time: (label) => {
+      const start = performance.now();
+      return (msg, meta) => log('info', msg || `${label} completed`, { ...meta, durationMs: performance.now() - start });
+    }
+  };
+}

package/src/next.d.ts

@@ -11,10 +11,34 @@ export interface UploadedFile {
   text: () => Promise<string>;
 }
 
-export interface NextBroGlobalConfig<TDb = any> {
-  env?: ZodTypeAny;
+export interface NextBroGlobalConfig<TEnv = any, TDb = any, TUser = any> {
+  routesDir?: string;
+  tasksDir?: string;
+  logger?: { level?: string; [key: string]: any };
+  plugins?: any[];
+  fixtures?: Record<string, any>;
+  stores?: Record<string, any>;
+  health?: boolean | { dbCheck?: (db: any) => Promise<any> };
   locales?: Record<string, any>;
   defaultLocale?: string;
+  envData?: any;
+  redis?: any;
+  port?: number;
+  jwtSecret?: string;
+  trustProxy?: boolean;
+  validateResponse?: boolean | 'strict' | 'warn';
+  env?: ZodTypeAny;
+  server?: {
+    port?: number;
+    cors?: boolean | object;
+    helmet?: boolean | object;
+    timeoutMs?: number;
+    headersTimeoutMs?: number;
+  };
+  locale?: {
+    directory?: string;
+    defaultLocale?: string;
+  };
   redisUrl?: string;
   rateLimit?: { windowMs: number; max: number; };
   auth?: {
@@ -22,12 +46,23 @@ export interface NextBroGlobalConfig<TDb = any> {
     apiKey?: string | string[];
     expiresIn?: string | number;
   };
+  docs?: boolean | { auth?: { user: string; pass: string } };
+  upload?: {
+    limits?: {
+      fileSize?: number;
+      files?: number;
+      fields?: number;
+      [key: string]: any;
+    };
+  };
   db?: TDb | Promise<TDb> | (() => TDb | Promise<TDb>) | { init: () => TDb | Promise<TDb> };
+  sockets?: (io: any, db: any) => Promise<void> | void;
+  onShutdown?: (db: any) => Promise<void> | void;
 }
 
-export interface NextRouteContext<TBody = any, TQuery = any, TParams = any, TDb = any> {
+export interface NextRouteContext<TBody = any, TQuery = any, TParams = any, TEnv = any, TDb = any, TUser = any> {
   req: Request;
-  env: Record<string, string | undefined>;
+  env: TEnv;
   db: TDb;
   redis: any;
   io: { emit: (event: string, data: any) => void };
@@ -37,13 +72,18 @@ export interface NextRouteContext<TBody = any, TQuery = any, TParams = any, TDb
   file?: UploadedFile;
   files?: Record<string, UploadedFile[]>;
   locale: string;
+  method: string;
+  ip: string;
+  headers: Record<string, string>;
+  requestId: string;
+  logger: any;
   t: (key: string, values?: any) => string;
-  user?: any;
+  user?: TUser;
   jwt: { sign: (payload: any, opts?: any) => string };
   error: (status: number, message: string) => never;
 }
 
-export interface NextRouteConfig<TBody = any, TQuery = any, TParams = any, TDb = any> {
+export interface NextRouteConfig<TBody = any, TQuery = any, TParams = any, TEnv = any, TDb = any, TUser = any> {
   auth?: boolean | string[] | 'api-key' | string;
   body?: TBody;
   query?: TQuery;
@@ -52,19 +92,20 @@ export interface NextRouteConfig<TBody = any, TQuery = any, TParams = any, TDb =
   rateLimit?: { windowMs: number; max: number; } | false;
   response?: ZodTypeAny;
   summary?: string;
+  operationId?: string;
   upload?: any;
-  handler: (ctx: NextRouteContext<TBody, TQuery, TParams, TDb>) => Promise<any> | any;
+  handler: (ctx: NextRouteContext<TBody, TQuery, TParams, TEnv, TDb, TUser>) => Promise<any> | any;
 }
 
-export interface BroNextInstance<TDb = any> {
+export interface BroNextInstance<TEnv = any, TDb = any, TUser = any> {
   z: typeof z;
   defineRoute: <
     TBody extends ZodTypeAny = any,
     TQuery extends ZodTypeAny = any,
     TParams extends ZodTypeAny = any
   >(
-    config: NextRouteConfig<TBody, TQuery, TParams, TDb>
+    config: NextRouteConfig<TBody, TQuery, TParams, TEnv, TDb, TUser>
   ) => (req: Request | any, context: any) => Promise<any>;
 }
 
-export declare function createBro<TDb = any>(config?: NextBroGlobalConfig<TDb>): BroNextInstance<TDb>;
+export declare function createBro<TEnv = any, TDb = any, TUser = any>(config?: NextBroGlobalConfig<TEnv, TDb, TUser>): BroNextInstance<TEnv, TDb, TUser>;