bro-framework 2.4.4 → 3.0.0

package/src/server.js

@@ -12,7 +12,14 @@ 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';
-import { loadRoutes } from './router.js';
+import { loadRoutes } from './router.js';
+import { executeRequest, resolveIdentity, RouteRegistry } from './engine.js';
+
+export function hashIdentity(identity) { return crypto.createHash('sha256').update(String(identity)).digest('hex'); }
+export function generateRateLimitKey(req, config, prefix = 'route') { const identity = resolveIdentity(req, config); return `bro:rate_limit:${prefix}:${originalUrl}:${hashIdentity(identity)}`; }
+export function generateCacheKey(req, config, locale) { const identity = resolveIdentity(req, config); return `bro:cache:${method}:${originalUrl}:${locale}:${hashIdentity(identity)}`; }
+import { createLogger } from './logger.js';
+import { PluginManager } from './plugins.js';
 import { scanTasks } from './tasks.js';
 
 /**
@@ -22,13 +29,34 @@ import { scanTasks } from './tasks.js';
  * @param {any} db - Initialized database instance.
  * @returns {Promise<{ app: import('express').Application, server: http.Server, routes: Array, reload: Function, reloadLocale: Function, io: import('socket.io').Server, shutdown: Function }>}
  */
-export async function createServer(globalConfig, routesDir, db) {
-  if (process.env.NODE_ENV === 'production' && ['dev_secret_please_change', 'bro_default_secret_key'].includes(globalConfig.jwtSecret)) {
-    throw new Error('CRITICAL SECURITY ERROR: You are running in production with a default JWT secret! Please set auth.jwtSecret in bro.config.js or via JWT_SECRET environment variable.');
+export async function createServer(globalConfig, routesDir, db) {
+  if (db && typeof db.isReady !== 'function') {
+     throw new Error('[bro.js] CRITICAL: In v3.0.0, the \'db\' passed to createServer MUST extend BaseDatabaseAdapter and implement isReady(), transaction(), healthCheck(), and shutdown().');
+  }
+  const globalLogger = createLogger(globalConfig.logger || { level: process.env.NODE_ENV === 'production' ? 'info' : 'debug' });
+
+  if (process.env.NODE_ENV === 'production' && (!globalConfig.jwtSecret || globalConfig.jwtSecret.length < 32 || ['dev_secret_please_change', 'bro_default_secret_key', 'your_jwt_secret_here'].includes(globalConfig.jwtSecret))) {
+    throw new Error('CRITICAL SECURITY ERROR: You are running in production without a secure JWT secret! Provide a secret of at least 32 characters.');
   }
 
-  const app = express();
-  const server = http.createServer(app);
+    const routeRegistry = new RouteRegistry();
+    const pluginManager = new PluginManager();
+  if (Array.isArray(globalConfig.plugins)) {
+    for (const plugin of globalConfig.plugins) {
+      pluginManager.register(plugin);
+    }
+  }
+
+  const app = express();
+  await pluginManager.runOnInit(globalConfig, app);
+  if (db) {
+    if (!await db.isReady()) {
+      throw new Error('[bro.js] Database adapter failed readiness check during boot.');
+    }
+  }
+  const server = http.createServer(app);
+  server.requestTimeout = globalConfig.server?.timeoutMs || 30000;
+  server.headersTimeout = globalConfig.server?.headersTimeoutMs || 35000;
   const localeDirectory = globalConfig.locale?.directory || path.join(process.cwd(), 'locale');
   let locale = await loadLocale(localeDirectory, globalConfig.locale);
   
@@ -47,12 +75,52 @@ export async function createServer(globalConfig, routesDir, db) {
     }));
   }
 
-  const corsConfig = globalConfig.server?.cors !== undefined ? globalConfig.server.cors : true;
-  
-  if (corsConfig !== false) {
-    app.use(cors(typeof corsConfig === 'object' ? corsConfig : {}));
+  const corsConfig = globalConfig.server?.cors !== undefined ? globalConfig.server.cors : false;
+  if (corsConfig === true) {
+    if (process.env.NODE_ENV === 'production') {
+      throw new Error('CRITICAL SECURITY ERROR: Permissive CORS (cors: true) is forbidden in production in v3.0.0. Provide an explicit origin allowlist.');
+    }
+    app.use(cors());
+  } else if (corsConfig) {
+    app.use(cors(corsConfig));
   }
   
+  app.use((req, res, next) => {
+    req.id = req.headers['x-request-id'] || crypto.randomUUID();
+    res.setHeader('X-Request-Id', req.id);
+    next();
+  });
+
+  const sendError = (res, status, message, details = null, req) => {
+    let finalMessage = message;
+    let finalDetails = details;
+    if (status >= 500 && process.env.NODE_ENV === 'production') {
+      finalMessage = 'Internal Server Error';
+      finalDetails = null;
+    }
+    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');
+
+    // v3.0.0 ALWAYS uses RFC 9457 Problem Details
+    const payload = {
+      type: `https://brojs.dev/errors/${code.toLowerCase()}`,
+      title: finalMessage,
+      status,
+      instance: req.originalUrl || req.url,
+      requestId: req.id
+    };
+    if (finalDetails) {
+      if (typeof finalDetails === 'string') payload.detail = finalDetails;
+      else payload.errors = finalDetails;
+    }
+    return res.status(status).type('application/problem+json').json(payload);
+  };
+
+  const formatZodError = (error) => error.issues.map(i => ({ path: i.path.join('.'), message: i.message, code: i.code }));
+
+  
+
+  app.use(pluginManager.getRequestMiddleware());
   app.use(express.json());
   
   const safeConnect = async (client) => {
@@ -96,13 +164,13 @@ export async function createServer(globalConfig, routesDir, db) {
       const fallbackLimiter = rateLimit(globalConfig.rateLimit);
       app.use(async (req, res, next) => {
         try {
-          const key = `rate_limit:global:${req.ip}`;
+          const key = generateRateLimitKey(req, globalConfig, 'global');
           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' });
+            return sendError(res, 429, 'Too Many Requests', null, req);
           }
           next();
         } catch (err) {
@@ -145,30 +213,6 @@ export async function createServer(globalConfig, routesDir, db) {
     const paramsSchema = routeConfig.params;
     const querySchema = routeConfig.query;
     
-    if (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) {
       const defaultLimits = { fileSize: 10 * 1024 * 1024, files: 5, fields: 20, parts: 25, fieldSize: 1024 * 1024 };
       const routeMulterConfig = {
@@ -195,136 +239,55 @@ export async function createServer(globalConfig, routesDir, db) {
       }
     }
     
-    middlewares.push(async (req, res) => {
-      try {
-        const requestLocale = locale.resolveLocale(req);
-        const ctx = {
-          env: globalConfig.envData || process.env,
-          db,
-          io,
-          redis: redisClient,
-          body: req.body,
-          params: req.params,
-          query: req.query,
-          files: req.files || req.file,
-          locale: requestLocale,
-          t: (key, values) => locale.translate(requestLocale, key, values),
-          user: null,
-          jwt: { sign: (payload, opts) => signJwt(payload, globalConfig.jwtSecret, opts || { expiresIn: globalConfig.auth?.expiresIn || '1d' }) },
-          error: (status, message) => {
-             const err = new Error(message);
-             err.status = status;
-             throw err;
-          }
-        };
-
-        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' });
-             }
-          }
-        }
-
-        if (paramsSchema) {
-          const result = paramsSchema.safeParse(req.params);
-          if (!result.success) {
-            return res.status(400).json({ error: 'Invalid URL Parameters', details: result.error.flatten() });
-          }
-          ctx.params = result.data;
-        }
-        
-        if (bodySchema) {
-          const result = bodySchema.safeParse(req.body);
-          if (!result.success) {
-            return res.status(400).json({ error: 'Invalid Request Body', details: result.error.flatten() });
-          }
-          ctx.body = result.data;
-        }
-
-        if (querySchema) {
-           const result = querySchema.safeParse(req.query);
-           if (!result.success) {
-             return res.status(400).json({ error: 'Invalid Query Parameters', details: result.error.flatten() });
-           }
-           ctx.query = result.data;
-        }
-
-        if (typeof routeConfig.handler !== 'function') {
-           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);
-        }
-
-      } catch (err) {
-        const status = err.status || 500;
-        const message = status === 500 ? 'Internal Server Error' : err.message;
-        
-        if (status === 500) {
-          console.error(`[bro.js] Execution Error in route:`);
-          console.error(err.stack);
-        }
-        
-        if (!res.headersSent) {
-          res.status(status).json({ 
-            error: message, 
-            ...(status !== 500 && err.details ? { details: err.details } : {}) 
-          });
-        }
-      }
-    });
-    
+    middlewares.push(async (req, res) => {
+      const requestData = {
+        method: req.method,
+        originalUrl: req.originalUrl,
+        headers: req.headers,
+        body: req.body,
+        query: req.query,
+        params: req.params,
+        files: req.files || req.file,
+        ip: req.ip,
+        locale: locale.resolveLocale(req)
+      };
+      
+      const ctxExtras = {
+      verifyJwt,
+      generateRateLimitKey,
+      generateCacheKey,
+      generateId: () => crypto.randomUUID(),
+        req,
+        res,
+        db,
+        redis: redisClient,
+        io,
+        pluginManager,
+        t: (key, values) => locale.translate(requestData.locale, key, values),
+        logger: globalLogger,
+        jwt: { sign: (payload, opts) => signJwt(payload, globalConfig.jwtSecret, opts || { expiresIn: globalConfig.auth?.expiresIn || '1d' }) },
+        error: (status, message) => {
+          const err = new Error(message);
+          err.status = status;
+          throw err;
+        },
+        fixtures: globalConfig.fixtures || {},
+        stores: globalConfig.stores || {}
+      };
+
+      const response = await executeRequest(routeConfig, requestData, globalConfig, ctxExtras);
+
+      if (response.headers && !res.headersSent) {
+        for (const [k, v] of Object.entries(response.headers)) {
+          res.setHeader(k, v);
+        }
+      }
+
+      if (!res.headersSent) {
+        res.status(response.status).json(response.body);
+      }
+    });
+
     return middlewares;
   };
 
@@ -376,6 +339,52 @@ export async function createServer(globalConfig, routesDir, db) {
     app.use('/docs', docsAuthMiddleware, apiReference({ spec: { url: '/docs/json' } }));
   }
 
+  if (globalConfig.health) {
+    app.get('/health/live', (req, res) => {
+      res.status(200).json({ status: 'ok', timestamp: new Date().toISOString() });
+    });
+    
+    app.get('/health/ready', async (req, res) => {
+      let isReady = true;
+      const checks = {};
+      
+      const timeoutPromise = (ms, promise) => {
+        return new Promise((resolve, reject) => {
+          const timer = setTimeout(() => reject(new Error('timeout')), ms);
+          promise.then(val => { clearTimeout(timer); resolve(val); }).catch(err => { clearTimeout(timer); reject(err); });
+        });
+      };
+
+      if (redisClient) {
+        try {
+          await timeoutPromise(2000, redisClient.ping());
+          checks.redis = 'up';
+        } catch (err) {
+          checks.redis = 'down';
+          isReady = false;
+        }
+      }
+      
+      if (globalConfig.health === true || typeof globalConfig.health.dbCheck !== 'function') {
+         if (db) checks.db = 'unknown (provide health.dbCheck)';
+      } else if (db) {
+        try {
+          await timeoutPromise(2000, globalConfig.health.dbCheck(db));
+          checks.db = 'up';
+        } catch (err) {
+          checks.db = 'down';
+          isReady = false;
+        }
+      }
+
+      res.status(isReady ? 200 : 503).json({
+        status: isReady ? 'ready' : 'unavailable',
+        checks,
+        timestamp: new Date().toISOString()
+      });
+    });
+  }
+
   let routeStack = express.Router();
   
   app.use((req, res, next) => {
@@ -383,18 +392,19 @@ export async function createServer(globalConfig, routesDir, db) {
   });
 
   app.use((req, res) => {
-    res.status(404).json({ error: 'Not Found' });
+    sendError(res, 404, 'Not Found', null, req);
   });
 
+  app.use(pluginManager.getErrorMiddleware());
   app.use((err, req, res, next) => {
     console.error(`[bro.js] Uncaught Error:`, err);
-    res.status(err.status || 500).json({ error: err.message || 'Internal Server Error' });
+    sendError(res, err.status || 500, err.message || 'Internal Server Error', null, req);
   });
 
   const reload = async () => {
     const newRouter = express.Router();
     const tempSpec = { paths: {} };
-    const routes = await loadRoutes(newRouter, routesDir, createHandler, tempSpec);
+    const routes = await loadRoutes(newRouter, routesDir, createHandler, tempSpec, routeRegistry);
     openApiSpec.paths = tempSpec.paths;
     routeStack = newRouter;
     return routes;
@@ -410,7 +420,8 @@ export async function createServer(globalConfig, routesDir, db) {
   let taskManager = await scanTasks({ db, io });
 
   const reloadTasks = async () => {
-    if (taskManager) taskManager.stopAll();
+    if (taskManager) taskManager.stopAll();
+    await pluginManager.runOnShutdown();
     taskManager = await scanTasks({ db, io });
   };
 

package/src/studio.js

@@ -0,0 +1,162 @@
+import fs from 'fs';
+import path from 'path';
+import { generateSDK } from './sdk.js';
+import { scanDir, parseRouteFile } from './router.js';
+import { pathToFileURL } from 'url';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+/**
+ * Contract Studio Engine
+ * Generates TS Client, OpenAPI Spec, MSW Mocks, React Query Hooks, and Error Types
+ */
+export class ContractStudio {
+  constructor(routesDir, routeRegistry) {
+    this.routeRegistry = routeRegistry;
+    this.routesDir = routesDir || path.join(process.cwd(), 'routes');
+    this.outputDir = path.join(process.cwd(), '.bro-studio');
+  }
+
+  async buildAll() {
+    if (!fs.existsSync(this.outputDir)) {
+      fs.mkdirSync(this.outputDir, { recursive: true });
+    }
+
+    // 1. TypeScript Client (reuse existing SDK generator)
+    await generateSDK();
+    
+    // 2. Scan endpoints for other generators
+    const endpoints = await this._scanEndpoints();
+
+    // 3. Generate OpenAPI
+    await this.generateOpenAPI(endpoints);
+
+    // 4. Generate MSW Mocks
+    await this.generateMswMocks(endpoints);
+
+    // 5. Generate React Query Hooks
+    await this.generateReactQuery(endpoints);
+    
+    console.log('[bro.js] Contract Studio generation complete.');
+  }
+
+  async _scanEndpoints() {
+    const files = scanDir(this.routesDir);
+    const endpoints = [];
+    let routeCounter = 0;
+    
+    for (const file of files) {
+      const routeInfo = parseRouteFile(file, this.routesDir);
+      if (routeInfo) {
+        const mod = await import(pathToFileURL(file).href + '?t=' + Date.now());
+        endpoints.push({
+          ...routeInfo,
+          file,
+          config: mod.default,
+          moduleName: `Route${routeCounter++}`
+        });
+      }
+    }
+    return endpoints;
+  }
+
+  async generateOpenAPI(endpoints) {
+    const spec = {
+      openapi: '3.0.0',
+      info: { title: 'bro.js API', version: '1.0.0' },
+      paths: {}
+    };
+
+    for (const ep of endpoints) {
+      const pathKey = ep.routePath.replace(/:([a-zA-Z0-9_]+)/g, '{$1}');
+      if (!spec.paths[pathKey]) spec.paths[pathKey] = {};
+      
+      
+      // Stable Naming
+      let stableName = ep.config.operationId;
+      if (!stableName) {
+        const cleanPath = ep.routePath.replace(/[^a-zA-Z0-9]/g, ' ').trim().split(/\s+/).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+        stableName = ep.method.toLowerCase() + cleanPath;
+      }
+      
+      const routeOp = {
+        operationId: stableName,
+        summary: ep.config.summary || `${ep.method.toUpperCase()} ${ep.routePath}`,
+        responses: {
+          '200': { description: 'Successful response' },
+          '400': { description: 'Validation error' },
+          '401': { description: 'Unauthorized' }
+        }
+      };
+
+      if (ep.config.response) {
+         routeOp.responses['200'].content = {
+           'application/json': {
+             schema: zodToJsonSchema(ep.config.response, { target: 'openApi3' })
+           }
+         };
+      }
+      
+      spec.paths[pathKey][ep.method.toLowerCase()] = routeOp;
+    }
+    
+    fs.writeFileSync(
+      path.join(this.outputDir, 'openapi.json'),
+      JSON.stringify(spec, null, 2)
+    );
+  }
+
+    async generateMswMocks(endpoints) {
+    let mswCode = `import { http, HttpResponse } from 'msw';\n\nexport const handlers = [\n`;
+    for (const ep of endpoints) {
+      const mswPath = ep.routePath.replace(/:([a-zA-Z0-9_]+)/g, ':$1');
+      mswCode += `  http.${ep.method.toLowerCase()}('*${mswPath}', ({ request, params, cookies }) => {\n`;
+      
+      let mockData = '{ mock: true }';
+      if (ep.config && ep.config.response) {
+        const schema = zodToJsonSchema(ep.config.response);
+        if (schema.type === 'object' && schema.properties) {
+          const mockObj = {};
+          for (const key of Object.keys(schema.properties)) {
+            mockObj[key] = schema.properties[key].type === 'string' ? 'mock_string' : schema.properties[key].type === 'number' ? 123 : schema.properties[key].type === 'boolean' ? true : null;
+          }
+          mockData = JSON.stringify(mockObj);
+        }
+      }
+      
+      mswCode += `    return HttpResponse.json(${mockData});\n`;
+      mswCode += `  }),\n`;
+    }
+    mswCode += `];\n`;
+    fs.writeFileSync(path.join(this.outputDir, 'msw.js'), mswCode);
+  }
+
+    async generateReactQuery(endpoints) {
+    let rqCode = `import { useQuery, useMutation } from '@tanstack/react-query';\nimport { api } from './bro-sdk';\n\n`;
+    for (const ep of endpoints) {
+      const hookName = `use${ep.moduleName}`;
+      const fnName = ep.moduleName.charAt(0).toLowerCase() + ep.moduleName.slice(1);
+      if (ep.method.toLowerCase() === 'get') {
+        rqCode += `export function ${hookName}(query, options) {\n  return useQuery({\n    queryKey: ['${ep.routePath}', query],\n    queryFn: () => api.${fnName}(query),\n    ...options\n  });\n}\n\n`;
+      } else {
+        rqCode += `export function ${hookName}(options) {\n  return useMutation({\n    mutationFn: (data) => api.${fnName}(data),\n    ...options\n  });\n}\n\n`;
+      }
+    }
+    fs.writeFileSync(path.join(this.outputDir, 'react-query.js'), rqCode);
+  }
+
+  async watch() {
+    console.log('[bro.js] Contract Studio watching for route changes...');
+    const chokidar = await import('chokidar');
+    chokidar.watch(this.routesDir).on('change', async (path) => {
+      console.log(`[bro.js] Route ${path} changed, rebuilding contracts...`);
+      await this.buildAll();
+    });
+  }
+}
+
+export async function startStudio(cwd) {
+  console.log('[bro.js] Starting Contract Studio generation...');
+  const studio = new ContractStudio(path.join(cwd, 'api'));
+  await studio.buildAll();
+  console.log('[bro.js] Studio generation complete.');
+}

package/src/task-engine.js

@@ -0,0 +1,88 @@
+import cron from 'node-cron';
+
+/**
+ * Upgraded Task/Worker Model
+ * Supports concurrency, retries, leases, and dead-letter queues.
+ */
+export class TaskManager {
+  constructor(config = {}) {
+    this.tasks = new Map();
+    this.redisClient = config.redisClient || null;
+    this.logger = config.logger || console;
+  }
+
+  register(name, schedule, handler, options = {}) {
+    const defaultOptions = { retries: 3, concurrency: 1, deadLetter: true, timeoutMs: 30000 };
+    const taskDef = { name, schedule, handler, options: { ...defaultOptions, ...options } };
+    
+    let taskJob;
+    if (schedule) {
+      taskJob = cron.schedule(schedule, async () => {
+         await this.execute(name);
+      }, { scheduled: false });
+    }
+    
+    this.tasks.set(name, { ...taskDef, job: taskJob });
+  }
+
+  startAll() {
+    for (const [name, task] of this.tasks.entries()) {
+      if (task.job) {
+        task.job.start();
+        this.logger.info(`[bro.js/tasks] Task '${name}' scheduled (${task.schedule})`);
+      }
+    }
+  }
+
+  stopAll() {
+    for (const task of this.tasks.values()) {
+      if (task.job) task.job.stop();
+    }
+  }
+
+  async execute(name) {
+    const task = this.tasks.get(name);
+    if (!task) throw new Error(`Task '${name}' not found`);
+
+    const leaseKey = `bro:task_lease:${name}`;
+    if (this.redisClient) {
+       const acquired = await this.redisClient.set(leaseKey, 'locked', { NX: true, PX: task.options.timeoutMs });
+       if (!acquired) {
+         this.logger.debug(`[bro.js/tasks] Task '${name}' skipped (locked)`);
+         return;
+       }
+    }
+
+    let attempt = 0;
+    while (attempt < task.options.retries) {
+      try {
+        await Promise.race([
+          task.handler(),
+          new Promise((_, rej) => setTimeout(() => rej(new Error('Task Timeout')), task.options.timeoutMs))
+        ]);
+        break; // Success
+      } catch (err) {
+        attempt++;
+        this.logger.error(`[bro.js/tasks] Task '${name}' attempt ${attempt} failed: ${err.message}`);
+        if (attempt >= task.options.retries) {
+          if (task.options.deadLetter && this.redisClient) {
+            await this.redisClient.rPush('bro:dead_letter_queue', JSON.stringify({ name, error: err.message, time: Date.now() }));
+          }
+        } else {
+          await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000)); // Exponential backoff
+        }
+      }
+    }
+    if (this.redisClient) await this.redisClient.del(leaseKey);
+  }
+
+  async _handleDeadLetter(name, error) {
+    if (!this.redisClient) return;
+    const dlqKey = `bro:dlq:${name}`;
+    try {
+      await this.redisClient.lPush(dlqKey, JSON.stringify({ error: error.message, time: new Date().toISOString() }));
+    } catch (e) {
+      this.logger.error(`[bro.js/tasks] Failed to push dead letter for '${name}':`, e);
+    }
+  }
+}