webspresso 0.0.104 → 0.0.106

package/src/services/discovery.js

@@ -8,21 +8,10 @@ const fs = require('fs');
 const path = require('path');
 const { trimUrlPathSlashes } = require('../../core/url-path-normalize');
 
-const VALID_EXTENSIONS = new Set(['.js', '.mjs', '.cjs']);
+const { walkDirectoryDetailed } = require('../../core/utils/fs');
+const { toCamelCase } = require('../../core/utils/string');
 
-/**
- * Convert kebab-case or snake_case segment to camelCase
- * @param {string} str
- * @returns {string}
- */
-function toCamelCase(str) {
-  if (!str) return '';
-  const parts = str.split(/[-_]+/);
-  return parts.map((part, index) => {
-    if (!part) return '';
-    return index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1);
-  }).join('');
-}
+const VALID_EXTENSIONS = new Set(['.js', '.mjs', '.cjs']);
 
 /**
  * Check if a file should be included as a service
@@ -105,36 +94,26 @@ function discoverServices(servicesDir) {
     return [];
   }
 
-  const results = [];
+  const items = walkDirectoryDetailed(servicesDir, {
+    extensions: VALID_EXTENSIONS,
+    ignorePrefixes: ['.', '_'],
+    ignoreNames: ['node_modules'],
+    ignoreTests: true,
+  });
 
-  function scan(currentDir, relativePrefix = '') {
-    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
-
-    for (const entry of entries) {
-      if (entry.name.startsWith('.') || entry.name.startsWith('_') || entry.name === 'node_modules') {
-        continue;
-      }
-
-      const fullPath = path.join(currentDir, entry.name);
-      const relPath = relativePrefix ? path.join(relativePrefix, entry.name) : entry.name;
-
-      if (entry.isDirectory()) {
-        scan(fullPath, relPath);
-      } else if (entry.isFile() && isValidServiceFile(entry.name)) {
-        const { name, aliases } = filePathToServiceName(relPath);
-        if (name) {
-          results.push({
-            name,
-            aliases,
-            filePath: fullPath,
-            relativePath: relPath.replace(/\\/g, '/'),
-          });
-        }
-      }
+  const results = [];
+  for (const item of items) {
+    const { name, aliases } = filePathToServiceName(item.relativePath);
+    if (name) {
+      results.push({
+        name,
+        aliases,
+        filePath: item.absolutePath,
+        relativePath: item.relativePath,
+      });
     }
   }
 
-  scan(path.resolve(servicesDir));
   return results;
 }
 

package/src/services/executor.js

@@ -17,6 +17,12 @@ const {
   runWithAmbientTransaction,
   hasAmbientTransaction,
 } = require('../../core/orm/transaction');
+const { ensureArray } = require('../../core/utils/object');
+const {
+  CircuitBreaker,
+  circuitBreakerRegistry,
+  retry,
+} = require('../../core/resilience');
 
 const SERVICE_CALL_STACK_SYMBOL = Symbol.for('webspresso.service.call_stack');
 
@@ -93,7 +99,7 @@ async function checkServiceAuth(serviceDef, ctx, options = {}) {
     if (!user) {
       throw new UnauthorizedError(`Authentication required to execute service '${serviceDef.name}'`);
     }
-    const roles = Array.isArray(user.roles) ? user.roles : (user.role ? [user.role] : []);
+    const roles = ensureArray(user.roles || user.role);
     if (!roles.includes(authRequirement)) {
       throw new ForbiddenError(
         `Insufficient permissions to execute service '${serviceDef.name}' (required role: '${authRequirement}')`
@@ -107,7 +113,7 @@ async function checkServiceAuth(serviceDef, ctx, options = {}) {
     if (!user) {
       throw new UnauthorizedError(`Authentication required to execute service '${serviceDef.name}'`);
     }
-    const roles = Array.isArray(user.roles) ? user.roles : (user.role ? [user.role] : []);
+    const roles = ensureArray(user.roles || user.role);
     const hasAny = authRequirement.some(r => roles.includes(r));
     if (!hasAny) {
       throw new ForbiddenError(
@@ -185,15 +191,71 @@ async function executeService(registry, name, input = {}, ctx = {}, options = {}
     registry.invalidate(subName, subInput, subCtx || executionContext);
   executionContext.service.clearCache = (subName) =>
     registry.clearCache(subName);
+  executionContext.breaker = (bName, bOpts) =>
+    circuitBreakerRegistry.getBreaker(bName, bOpts);
+  executionContext.retry = retry;
 
   // Validate input
   const validatedInput = await validateServiceInput(serviceDef.schema, input, name);
+  if (validatedInput && typeof validatedInput === 'object' && !('input' in validatedInput)) {
+    try {
+      Object.defineProperty(validatedInput, 'input', {
+        value: validatedInput,
+        enumerable: false,
+        configurable: true,
+      });
+    } catch (_) {}
+  }
 
   const startTime = Date.now();
   const logger = executionContext.logger || registry.logger || null;
 
-  const timeoutConfig = options.timeout ?? serviceDef.timeout;
-  const timeoutMs = timeoutConfig ? parseTtlMs(timeoutConfig) : null;
+  const timeoutConfig = options.timeout ?? serviceDef.timeout ?? executionContext?.timeouts?.service ?? registry?.timeouts?.service ?? registry?.timeout;
+  const timeoutMs = (timeoutConfig !== undefined && timeoutConfig !== null && timeoutConfig !== false)
+    ? parseTtlMs(timeoutConfig)
+    : null;
+
+  // Resolve circuit breaker configuration
+  let breaker = null;
+  const cbConfig = options.skipCircuitBreaker === true
+    ? null
+    : (options.circuitBreaker !== undefined ? options.circuitBreaker : serviceDef.circuitBreaker);
+
+  if (cbConfig) {
+    if (cbConfig instanceof CircuitBreaker) {
+      breaker = cbConfig;
+    } else if (typeof cbConfig === 'string') {
+      breaker = circuitBreakerRegistry.getBreaker(cbConfig);
+    } else if (typeof cbConfig === 'object' && cbConfig !== null) {
+      const breakerName = cbConfig.name || name;
+      breaker = circuitBreakerRegistry.getBreaker(breakerName, cbConfig);
+    } else if (cbConfig === true) {
+      breaker = circuitBreakerRegistry.getBreaker(name);
+    }
+  }
+
+  // Resolve retry configuration
+  const retryConfig = options.skipRetry === true
+    ? null
+    : (options.retry !== undefined ? options.retry : serviceDef.retry);
+
+  const runWithRetry = async (fn) => {
+    if (!retryConfig) {
+      return await fn();
+    }
+    const retryOpts = typeof retryConfig === 'number'
+      ? { retries: retryConfig }
+      : (typeof retryConfig === 'object' && retryConfig !== null ? retryConfig : { retries: 3 });
+
+    return await retry((attempt) => fn(attempt), retryOpts);
+  };
+
+  const runWithBreaker = async (fn) => {
+    if (!breaker) {
+      return await fn(validatedInput, executionContext);
+    }
+    return await breaker.execute(fn, validatedInput, executionContext);
+  };
 
   // Helper to execute handler with optional database transaction
   const executeHandler = async (activeCtx) => {
@@ -227,6 +289,9 @@ async function executeService(registry, name, input = {}, ctx = {}, options = {}
             registry.invalidate(subName, subInput, subCtx || txCtx);
           txCtx.service.clearCache = (subName) =>
             registry.clearCache(subName);
+          txCtx.breaker = (bName, bOpts) =>
+            circuitBreakerRegistry.getBreaker(bName, bOpts);
+          txCtx.retry = retry;
           return await serviceDef.handler(validatedInput, txCtx);
         });
       });
@@ -236,31 +301,36 @@ async function executeService(registry, name, input = {}, ctx = {}, options = {}
   };
 
   try {
-    let result;
-
-    if (timeoutMs && timeoutMs > 0) {
-      let timerId;
-      const timeoutPromise = new Promise((_, reject) => {
-        timerId = setTimeout(() => {
-          const timeoutErr = new WebspressoError(`Service '${name}' timed out after ${timeoutMs}ms`);
-          timeoutErr.code = 'SERVICE_TIMEOUT';
-          timeoutErr.statusCode = 504;
-          timeoutErr.service = name;
-          reject(timeoutErr);
-        }, timeoutMs);
-      });
+    const invokeOperation = () => {
+      if (timeoutMs && timeoutMs > 0) {
+        let timerId;
+        const timeoutPromise = new Promise((_, reject) => {
+          timerId = setTimeout(() => {
+            const timeoutErr = new WebspressoError(`Service '${name}' timed out after ${timeoutMs}ms`);
+            timeoutErr.code = 'SERVICE_TIMEOUT';
+            timeoutErr.statusCode = 504;
+            timeoutErr.service = name;
+            reject(timeoutErr);
+          }, timeoutMs);
+          if (timerId && typeof timerId.unref === 'function') {
+            timerId.unref();
+          }
+        });
 
-      try {
-        result = await Promise.race([
+        return Promise.race([
           executeHandler(executionContext),
           timeoutPromise,
-        ]);
-      } finally {
-        clearTimeout(timerId);
+        ]).finally(() => {
+          if (timerId) {
+            clearTimeout(timerId);
+          }
+        });
       }
-    } else {
-      result = await executeHandler(executionContext);
-    }
+
+      return executeHandler(executionContext);
+    };
+
+    const result = await runWithBreaker(() => runWithRetry(invokeOperation));
 
     const duration = Date.now() - startTime;
     if (logger && typeof logger.debug === 'function') {

package/src/services/memoize.js

@@ -4,36 +4,14 @@
  * @module src/services/memoize
  */
 
+const { parseDurationMs } = require('../../core/utils/time');
+
 /**
  * Parse TTL duration into milliseconds
  * @param {string|number|boolean} ttl - Duration string ('5s', '1m', '5m', '1h', '1d'), ms number, or boolean
  * @returns {number} Milliseconds
  */
-function parseTtlMs(ttl) {
-  if (typeof ttl === 'number') {
-    return ttl > 0 ? ttl : 60_000;
-  }
-  if (ttl === true || !ttl) {
-    return 60_000; // Default 1 minute
-  }
-  if (typeof ttl === 'string') {
-    const match = ttl.trim().match(/^(\d+)\s*([smhd])?$/i);
-    if (match) {
-      const val = parseInt(match[1], 10);
-      const unit = (match[2] || 's').toLowerCase();
-      switch (unit) {
-        case 's': return val * 1_000;
-        case 'm': return val * 60_000;
-        case 'h': return val * 3_600_000;
-        case 'd': return val * 86_400_000;
-        default: return val * 1_000;
-      }
-    }
-    const num = parseInt(ttl, 10);
-    return !Number.isNaN(num) && num > 0 ? num : 60_000;
-  }
-  return 60_000;
-}
+const parseTtlMs = parseDurationMs;
 
 /**
  * Safely deep clone an object or array to prevent cache mutation

package/src/services/registry.js

@@ -21,6 +21,8 @@ class ServiceRegistry {
     this.servicesDir = options.servicesDir ? path.resolve(options.servicesDir) : null;
     this.isDev = Boolean(options.isDev);
     this.logger = options.logger || null;
+    this.timeouts = options.timeouts || null;
+    this.timeout = options.timeout !== undefined ? options.timeout : null;
 
     /** @type {Map<string, Object>} */
     this.services = new Map();
@@ -107,6 +109,8 @@ class ServiceRegistry {
         cache: definition.cache,
         timeout: definition.timeout,
         transaction: definition.transaction,
+        circuitBreaker: definition.circuitBreaker,
+        retry: definition.retry,
       };
 
       this.services.set(name, serviceDef);
@@ -125,7 +129,15 @@ class ServiceRegistry {
    * @param {Object|Function} definition - Service definition or handler function
    * @returns {ServiceRegistry}
    */
-  register(name, definition, options = {}) {
+  register(nameOrDef, maybeDef, options = {}) {
+    let name = nameOrDef;
+    let definition = maybeDef;
+
+    if (nameOrDef && typeof nameOrDef === 'object' && nameOrDef.name && maybeDef === undefined) {
+      name = nameOrDef.name;
+      definition = nameOrDef;
+    }
+
     if (!name || typeof name !== 'string') {
       throw new WebspressoError('Service name must be a non-empty string');
     }
@@ -164,6 +176,8 @@ class ServiceRegistry {
       cache: def.cache,
       timeout: def.timeout,
       transaction: def.transaction,
+      circuitBreaker: def.circuitBreaker,
+      retry: def.retry,
     };
 
     this.services.set(name, serviceDef);

package/src/services/validator.js

@@ -72,6 +72,26 @@ function descriptorToZod(typeName) {
   return finalSchema;
 }
 
+function shapeFromDescriptor(descriptorObj) {
+  const shape = {};
+  for (const [key, val] of Object.entries(descriptorObj)) {
+    if (typeof val === 'string') {
+      shape[key] = descriptorToZod(val);
+    } else if (val instanceof z.ZodType || (val && typeof val.safeParse === 'function')) {
+      shape[key] = val;
+    } else if (typeof val === 'object' && val !== null) {
+      const isOpt = val.optional === true || val.required === false;
+      let base = val.type ? descriptorToZod(String(val.type)) : z.any();
+      shape[key] = isOpt ? base.optional() : base;
+    } else if (typeof val === 'function') {
+      shape[key] = z.custom(val);
+    } else {
+      shape[key] = z.any();
+    }
+  }
+  return z.object(shape);
+}
+
 const compiledSchemaCache = new WeakMap();
 
 /**
@@ -100,6 +120,14 @@ function compileServiceSchema(rawSchema) {
       const res = rawSchema({ z: zForServices });
       if (res && (res instanceof z.ZodType || typeof res.safeParse === 'function')) {
         compiled = res;
+      } else if (res && typeof res === 'object' && !(res instanceof Promise) && typeof res.then !== 'function' && (res.constructor === Object || !res.constructor)) {
+        if (res.input && (res.input instanceof z.ZodType || typeof res.input.safeParse === 'function' || (typeof res.input === 'object' && res.input !== null))) {
+          compiled = (res.input instanceof z.ZodType || typeof res.input.safeParse === 'function')
+            ? res.input
+            : shapeFromDescriptor(res.input);
+        } else {
+          compiled = shapeFromDescriptor(res);
+        }
       }
     } catch (e) {
       // If invoking with { z } throws, treat as a direct validator function
@@ -108,28 +136,18 @@ function compileServiceSchema(rawSchema) {
       compiled = rawSchema;
     }
   } else if (typeof rawSchema === 'object' && rawSchema !== null) {
-    // If object descriptor: { id: 'number', name: 'string', email: 'email' }
-    const keys = Object.keys(rawSchema);
-    if (keys.length === 0) {
-      compiled = null;
+    if (rawSchema.input && (rawSchema.input instanceof z.ZodType || typeof rawSchema.input.safeParse === 'function' || (typeof rawSchema.input === 'object' && rawSchema.input !== null))) {
+      compiled = (rawSchema.input instanceof z.ZodType || typeof rawSchema.input.safeParse === 'function')
+        ? rawSchema.input
+        : shapeFromDescriptor(rawSchema.input);
     } else {
-      const shape = {};
-      for (const [key, val] of Object.entries(rawSchema)) {
-        if (typeof val === 'string') {
-          shape[key] = descriptorToZod(val);
-        } else if (val instanceof z.ZodType || (val && typeof val.safeParse === 'function')) {
-          shape[key] = val;
-        } else if (typeof val === 'object' && val !== null) {
-          const isOpt = val.optional === true || val.required === false;
-          let base = val.type ? descriptorToZod(String(val.type)) : z.any();
-          shape[key] = isOpt ? base.optional() : base;
-        } else if (typeof val === 'function') {
-          shape[key] = z.custom(val);
-        } else {
-          shape[key] = z.any();
-        }
+      // If object descriptor: { id: 'number', name: 'string', email: 'email' }
+      const keys = Object.keys(rawSchema);
+      if (keys.length === 0) {
+        compiled = null;
+      } else {
+        compiled = shapeFromDescriptor(rawSchema);
       }
-      compiled = z.object(shape);
     }
   } else {
     compiled = rawSchema;

package/src/template/precompile.js

@@ -11,6 +11,7 @@ const fs = require('fs');
 const path = require('path');
 const nunjucks = require('nunjucks');
 const { parseNjkFrontmatter, frontmatterToPatches, seedProdRouteCache } = require('../njk-frontmatter');
+const { walkDirectoryDetailed } = require('../../core/utils/fs');
 
 const DEFAULT_PRECOMPILED_REL_PATH = path.join('.webspresso', 'templates.compiled.js');
 
@@ -21,25 +22,13 @@ const DEFAULT_PRECOMPILED_REL_PATH = path.join('.webspresso', 'templates.compile
  * @returns {Array<{ absolutePath: string, relativePath: string }>}
  */
 function scanTemplateDir(dir, baseDir = dir) {
-  if (!fs.existsSync(dir)) return [];
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  const results = [];
-
-  for (const entry of entries) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
-      results.push(...scanTemplateDir(full, baseDir));
-    } else if (entry.isFile()) {
-      const ext = path.extname(entry.name);
-      if (ext === '.njk' || ext === '.html') {
-        const rel = path.relative(baseDir, full).split(path.sep).join('/');
-        results.push({ absolutePath: full, relativePath: rel });
-      }
-    }
-  }
-
-  return results;
+  return walkDirectoryDetailed(dir, {
+    extensions: ['.njk', '.html'],
+    ignorePrefixes: ['.'],
+    ignoreNames: ['node_modules'],
+    ignoreTests: false,
+    baseDir,
+  });
 }
 
 /**