webspresso 0.0.89 → 0.0.91

package/src/services/executor.js

@@ -0,0 +1,292 @@
+/**
+ * Webspresso Services Executor
+ * Executes services with shared context, auth/role guards, timeout handling, transaction boundaries, sensitive data masking, and branch-safe call stacks
+ * @module src/services/executor
+ */
+
+const {
+  NotFoundError,
+  WebspressoError,
+  ValidationError,
+  UnauthorizedError,
+  ForbiddenError,
+} = require('../../core/errors');
+const { validateServiceInput } = require('./validator');
+const { parseTtlMs } = require('./memoize');
+const {
+  runWithAmbientTransaction,
+  hasAmbientTransaction,
+} = require('../../core/orm/transaction');
+
+const SERVICE_CALL_STACK_SYMBOL = Symbol.for('webspresso.service.call_stack');
+
+const DEFAULT_REDACT_KEYS = new Set([
+  'password',
+  'pass',
+  'token',
+  'secret',
+  'apikey',
+  'api_key',
+  'authorization',
+  'creditcard',
+  'credit_card',
+  'cardnumber',
+  'card_number',
+  'cvv',
+  'ssn',
+]);
+
+/**
+ * Mask sensitive fields in payloads for safe logging
+ * @param {*} data
+ * @param {string[]} [customRedactKeys=[]]
+ * @returns {*} Masked payload
+ */
+function maskSensitiveData(data, customRedactKeys = []) {
+  if (data === null || typeof data !== 'object') {
+    return data;
+  }
+
+  const redactKeys = new Set([...DEFAULT_REDACT_KEYS, ...customRedactKeys.map(k => k.toLowerCase())]);
+
+  if (Array.isArray(data)) {
+    return data.map(item => maskSensitiveData(item, customRedactKeys));
+  }
+
+  const masked = {};
+  for (const [k, v] of Object.entries(data)) {
+    if (redactKeys.has(k.toLowerCase())) {
+      masked[k] = '[REDACTED]';
+    } else if (typeof v === 'object' && v !== null) {
+      masked[k] = maskSensitiveData(v, customRedactKeys);
+    } else {
+      masked[k] = v;
+    }
+  }
+  return masked;
+}
+
+/**
+ * Check service authorization and role permissions
+ * @param {Object} serviceDef - Service definition
+ * @param {Object} ctx - Context object
+ * @param {Object} options - Execution options
+ */
+async function checkServiceAuth(serviceDef, ctx, options = {}) {
+  if (options.skipAuth === true || !serviceDef.auth) {
+    return;
+  }
+
+  const authRequirement = serviceDef.auth;
+  const user = ctx.user || ctx.auth?.user || (ctx.req && (ctx.req.user || ctx.req.session?.user)) || null;
+
+  // 1. Boolean check (must be authenticated)
+  if (authRequirement === true) {
+    if (!user) {
+      throw new UnauthorizedError(`Authentication required to execute service '${serviceDef.name}'`);
+    }
+    return;
+  }
+
+  // 2. Single role string check (e.g. 'admin')
+  if (typeof authRequirement === 'string') {
+    if (!user) {
+      throw new UnauthorizedError(`Authentication required to execute service '${serviceDef.name}'`);
+    }
+    const roles = Array.isArray(user.roles) ? user.roles : (user.role ? [user.role] : []);
+    if (!roles.includes(authRequirement)) {
+      throw new ForbiddenError(
+        `Insufficient permissions to execute service '${serviceDef.name}' (required role: '${authRequirement}')`
+      );
+    }
+    return;
+  }
+
+  // 3. Array of allowed roles check (e.g. ['admin', 'manager'])
+  if (Array.isArray(authRequirement)) {
+    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 hasAny = authRequirement.some(r => roles.includes(r));
+    if (!hasAny) {
+      throw new ForbiddenError(
+        `Insufficient permissions to execute service '${serviceDef.name}' (required one of: '${authRequirement.join(', ')}')`
+      );
+    }
+    return;
+  }
+
+  // 4. Custom predicate function check: (user, ctx) => boolean
+  if (typeof authRequirement === 'function') {
+    let isAuthorized = false;
+    try {
+      isAuthorized = await authRequirement(user, ctx);
+    } catch (authFnErr) {
+      throw new ForbiddenError(
+        `Authorization check failed for service '${serviceDef.name}': ${authFnErr.message}`,
+        { cause: authFnErr }
+      );
+    }
+    if (!isAuthorized) {
+      throw new ForbiddenError(
+        `Access denied to execute service '${serviceDef.name}' by authorization policy`
+      );
+    }
+  }
+}
+
+/**
+ * Execute a service with schema validation, auth checks, and error boundary
+ * @param {ServiceRegistry} registry - Service registry instance
+ * @param {string} name - Service name
+ * @param {unknown} [input] - Raw input payload
+ * @param {Object} [ctx={}] - Context object
+ * @param {Object} [options={}] - Execution options
+ * @returns {Promise<unknown>} Service execution result
+ */
+async function executeService(registry, name, input = {}, ctx = {}, options = {}) {
+  if (!name || typeof name !== 'string') {
+    throw new WebspressoError('Service name must be a non-empty string');
+  }
+
+  const serviceDef = registry.get(name);
+
+  if (!serviceDef) {
+    const notFoundErr = new NotFoundError(`Service not found: ${name}`);
+    notFoundErr.code = 'SERVICE_NOT_FOUND';
+    notFoundErr.service = name;
+    throw notFoundErr;
+  }
+
+  // Check authorization requirements
+  await checkServiceAuth(serviceDef, ctx, options);
+
+  // Check call stack depth for circular service invocations
+  const activeStack = Array.isArray(ctx[SERVICE_CALL_STACK_SYMBOL])
+    ? ctx[SERVICE_CALL_STACK_SYMBOL]
+    : [];
+
+  if (activeStack.includes(name)) {
+    const cycle = [...activeStack, name].join(' -> ');
+    const circularErr = new WebspressoError(`Circular service call detected:\n${cycle}`);
+    circularErr.code = 'CIRCULAR_SERVICE_CALL';
+    circularErr.service = name;
+    circularErr.callStack = [...activeStack, name];
+    throw circularErr;
+  }
+
+  // Configure execution context
+  const executionContext = Object.create(ctx);
+  executionContext[SERVICE_CALL_STACK_SYMBOL] = [...activeStack, name];
+  executionContext.service = (subName, subInput, subOpts) =>
+    executeService(registry, subName, subInput, executionContext, subOpts);
+  executionContext.service.invalidate = (subName, subInput, subCtx) =>
+    registry.invalidate(subName, subInput, subCtx || executionContext);
+  executionContext.service.clearCache = (subName) =>
+    registry.clearCache(subName);
+
+  // Validate input
+  const validatedInput = await validateServiceInput(serviceDef.schema, input, name);
+
+  const startTime = Date.now();
+  const logger = executionContext.logger || registry.logger || null;
+
+  const timeoutConfig = options.timeout ?? serviceDef.timeout;
+  const timeoutMs = timeoutConfig ? parseTtlMs(timeoutConfig) : null;
+
+  // Helper to execute handler with optional database transaction
+  const executeHandler = async (activeCtx) => {
+    const shouldUseTx = (options.transaction === true || serviceDef.transaction === true);
+    const db = activeCtx.db;
+
+    // Check if knex or transaction-capable database is present
+    const knexInstance = db && (db.knex || (typeof db.transaction === 'function' ? db : null));
+    const alreadyInTx = Boolean(activeCtx.trx || hasAmbientTransaction());
+
+    if (shouldUseTx && knexInstance && !alreadyInTx) {
+      return await knexInstance.transaction(async (trx) => {
+        return await runWithAmbientTransaction(trx, async () => {
+          const txCtx = Object.create(activeCtx);
+          txCtx.trx = trx;
+          if (activeCtx.db && typeof activeCtx.db.getRepository === 'function') {
+            const { createRepository } = require('../../core/orm/repository');
+            txCtx.db = Object.assign(Object.create(activeCtx.db), {
+              knex: trx,
+              getRepository: (modelName, scopeCtx) => {
+                const origRepo = activeCtx.db.getRepository(modelName, scopeCtx);
+                return createRepository(origRepo.model, trx, scopeCtx);
+              },
+            });
+          } else {
+            txCtx.db = trx;
+          }
+          txCtx.service = (subName, subInput, subOpts) =>
+            executeService(registry, subName, subInput, txCtx, subOpts);
+          txCtx.service.invalidate = (subName, subInput, subCtx) =>
+            registry.invalidate(subName, subInput, subCtx || txCtx);
+          txCtx.service.clearCache = (subName) =>
+            registry.clearCache(subName);
+          return await serviceDef.handler(validatedInput, txCtx);
+        });
+      });
+    }
+
+    return await serviceDef.handler(validatedInput, activeCtx);
+  };
+
+  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);
+      });
+
+      try {
+        result = await Promise.race([
+          executeHandler(executionContext),
+          timeoutPromise,
+        ]);
+      } finally {
+        clearTimeout(timerId);
+      }
+    } else {
+      result = await executeHandler(executionContext);
+    }
+
+    const duration = Date.now() - startTime;
+    if (logger && typeof logger.debug === 'function') {
+      logger.debug(`[service] ${name} executed successfully (${duration}ms)`);
+    }
+
+    return result;
+  } catch (err) {
+    const duration = Date.now() - startTime;
+
+    if (logger && typeof logger.error === 'function' && !(err instanceof ValidationError)) {
+      logger.error(`[service] ${name} execution failed (${duration}ms): ${err.message}`);
+    }
+
+    // Attach service name to error if not present
+    if (!err.service) {
+      err.service = name;
+    }
+
+    throw err;
+  }
+}
+
+module.exports = {
+  SERVICE_CALL_STACK_SYMBOL,
+  maskSensitiveData,
+  checkServiceAuth,
+  executeService,
+};

package/src/services/index.js

@@ -0,0 +1,70 @@
+/**
+ * Webspresso Services Layer
+ * Lightweight, reusable business logic services with zero dependency sprawl
+ * @module src/services
+ */
+
+const { ServiceRegistry } = require('./registry');
+const { discoverServices, filePathToServiceName, toCamelCase } = require('./discovery');
+const { validateServiceInput, sanitizeInput } = require('./validator');
+const { executeService, SERVICE_CALL_STACK_SYMBOL, maskSensitiveData } = require('./executor');
+
+const { memoize, parseTtlMs, stableCacheKey } = require('./memoize');
+
+/**
+ * Define a service definition with optional schema and metadata
+ * @param {Object|Function} definition - Service definition or handler function
+ * @returns {Object} Normalized service definition
+ */
+function defineService(definition) {
+  if (typeof definition === 'function') {
+    return { handler: definition };
+  }
+  return definition;
+}
+
+/**
+ * Factory function to create and optionally load a ServiceRegistry
+ * @param {Object} [options]
+ * @param {string} [options.servicesDir] - Path to services directory
+ * @param {boolean} [options.isDev=false] - Whether development mode is active
+ * @param {Object} [options.logger] - Optional logger
+ * @param {boolean} [options.autoLoad=true] - Whether to load immediately if servicesDir exists
+ * @returns {ServiceRegistry}
+ */
+function createServiceRegistry(options = {}) {
+  const registry = new ServiceRegistry(options);
+  if (options.autoLoad !== false && options.servicesDir) {
+    registry.load();
+  }
+  return registry;
+}
+
+const { createAuthServices } = require('./builtins/auth');
+const { createMailServices } = require('./builtins/mail');
+const { createMediaServices } = require('./builtins/media');
+const { createSystemServices } = require('./builtins/system');
+const { createExchangeServices } = require('./builtins/exchange');
+
+module.exports = {
+  ServiceRegistry,
+  createServiceRegistry,
+  defineService,
+  service: defineService, // alias
+  createAuthServices,
+  createMailServices,
+  createMediaServices,
+  createSystemServices,
+  createExchangeServices,
+  memoize,
+  parseTtlMs,
+  stableCacheKey,
+  sanitizeInput,
+  maskSensitiveData,
+  toCamelCase,
+  discoverServices,
+  filePathToServiceName,
+  validateServiceInput,
+  executeService,
+  SERVICE_CALL_STACK_SYMBOL,
+};

package/src/services/memoize.js

@@ -0,0 +1,256 @@
+/**
+ * Webspresso Services Memoization & Caching
+ * Lightweight, zero-dependency in-memory cache with stampede protection, LRU eviction, and safe serialization
+ * @module src/services/memoize
+ */
+
+/**
+ * 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;
+}
+
+/**
+ * Safely deep clone an object or array to prevent cache mutation
+ * @param {*} value
+ * @returns {*} Cloned value
+ */
+function safeClone(value) {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  if (typeof structuredClone === 'function') {
+    try {
+      return structuredClone(value);
+    } catch (e) {
+      // Fallback for non-cloneable objects (buffers, functions, etc.)
+    }
+  }
+  if (Array.isArray(value)) {
+    return value.map(item => safeClone(item));
+  }
+  if (value instanceof Date) {
+    return new Date(value.getTime());
+  }
+  const cloned = {};
+  for (const [k, v] of Object.entries(value)) {
+    cloned[k] = safeClone(v);
+  }
+  return cloned;
+}
+
+/**
+ * Safe deterministic cache key serializer
+ * Handles BigInt, Buffer, Date, RegExp, Symbols, and circular references safely
+ * @param {*} input - Input arguments
+ * @param {WeakSet} [seen] - Seen objects for circular reference detection
+ * @returns {string} Serialized cache key
+ */
+function stableCacheKey(input, seen = new WeakSet()) {
+  if (input === undefined) return '__undefined__';
+  if (input === null) return '__null__';
+
+  const type = typeof input;
+
+  if (type === 'string') return JSON.stringify(input);
+  if (type === 'number' || type === 'boolean') return String(input);
+  if (type === 'bigint') return `${input.toString()}n`;
+  if (type === 'symbol') return input.toString();
+  if (type === 'function') return `[Function: ${input.name || 'anonymous'}]`;
+
+  if (type === 'object') {
+    if (seen.has(input)) {
+      return '[Circular]';
+    }
+    seen.add(input);
+
+    if (Buffer.isBuffer(input)) {
+      return `[Buffer:${input.toString('hex')}]`;
+    }
+    if (input instanceof Date) {
+      return `[Date:${input.toISOString()}]`;
+    }
+    if (input instanceof RegExp) {
+      return `[RegExp:${input.toString()}]`;
+    }
+
+    if (Array.isArray(input)) {
+      const items = input.map(item => stableCacheKey(item, seen));
+      return `[${items.join(',')}]`;
+    }
+
+    // Deterministically sort keys
+    const keys = Object.keys(input).sort();
+    const pairs = keys.map(k => `${JSON.stringify(k)}:${stableCacheKey(input[k], seen)}`);
+    return `{${pairs.join(',')}}`;
+  }
+
+  return String(input);
+}
+
+/**
+ * Memoize an async or sync function with:
+ * - Cache stampede / thundering herd protection (in-flight promise deduping)
+ * - LRU cache eviction
+ * - TTL expiration
+ * - Cache mutation protection (safe cloning)
+ * - Safe serialization (BigInt, circular refs, Buffers)
+ * 
+ * @param {Function} fn - Function to memoize
+ * @param {Object} [options]
+ * @param {string|number|boolean} [options.ttl='1m'] - Time to live
+ * @param {number} [options.maxSize=500] - Max cache entries before LRU eviction
+ * @param {boolean} [options.clone=true] - Clone cached results to prevent mutation
+ * @param {Function} [options.key] - Custom cache key generator `(input, ctx) => string`
+ * @returns {Function} Memoized function with .clear(), .invalidate(), .delete(), .has(), .size
+ */
+function memoize(fn, options = {}) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('memoize requires a function as first argument');
+  }
+
+  const ttlMs = parseTtlMs(options.ttl ?? options.cache ?? '1m');
+  const maxSize = Number(options.maxSize) || 500;
+  const shouldClone = options.clone !== false;
+  const customKeyFn = typeof options.key === 'function' ? options.key : null;
+
+  /** @type {Map<string, { value: *, expiresAt: number }>} */
+  const cache = new Map();
+
+  /** @type {Map<string, Promise<*>>} In-flight request deduplication map */
+  const inFlight = new Map();
+
+  function getKey(input, ctx) {
+    if (customKeyFn) {
+      return String(customKeyFn(input, ctx));
+    }
+    return stableCacheKey(input);
+  }
+
+  async function memoized(input, ctx) {
+    const key = getKey(input, ctx);
+    const now = Date.now();
+    const hit = cache.get(key);
+
+    if (hit) {
+      if (hit.expiresAt > now) {
+        // Refresh LRU position
+        cache.delete(key);
+        cache.set(key, hit);
+        return shouldClone ? safeClone(hit.value) : hit.value;
+      }
+      cache.delete(key);
+    }
+
+    // 1. In-flight Promise Deduping (Thundering Herd / Cache Stampede Protection)
+    if (inFlight.has(key)) {
+      const inFlightResult = await inFlight.get(key);
+      return shouldClone ? safeClone(inFlightResult) : inFlightResult;
+    }
+
+    // 2. Execute and track in-flight promise
+    const executionPromise = (async () => {
+      try {
+        return await fn(input, ctx);
+      } finally {
+        inFlight.delete(key);
+      }
+    })();
+
+    inFlight.set(key, executionPromise);
+
+    let result;
+    try {
+      result = await executionPromise;
+    } catch (execErr) {
+      // Do not cache failed executions
+      throw execErr;
+    }
+
+    // 3. LRU Eviction when exceeding maxSize
+    if (cache.size >= maxSize) {
+      const oldestKey = cache.keys().next().value;
+      if (oldestKey !== undefined) {
+        cache.delete(oldestKey);
+      }
+    }
+
+    cache.set(key, {
+      value: shouldClone ? safeClone(result) : result,
+      expiresAt: Date.now() + ttlMs,
+    });
+
+    return shouldClone ? safeClone(result) : result;
+  }
+
+  memoized.invalidate = function invalidate(input, ctx) {
+    const key = getKey(input, ctx);
+    inFlight.delete(key);
+    return cache.delete(key);
+  };
+
+  memoized.delete = memoized.invalidate;
+
+  memoized.clear = function clear() {
+    inFlight.clear();
+    cache.clear();
+  };
+
+  memoized.has = function has(input, ctx) {
+    const key = getKey(input, ctx);
+    const hit = cache.get(key);
+    if (!hit) return false;
+    if (hit.expiresAt <= Date.now()) {
+      cache.delete(key);
+      return false;
+    }
+    return true;
+  };
+
+  Object.defineProperty(memoized, 'size', {
+    get() {
+      // Clean expired entries on size access
+      const now = Date.now();
+      for (const [k, v] of cache.entries()) {
+        if (v.expiresAt <= now) {
+          cache.delete(k);
+        }
+      }
+      return cache.size;
+    },
+  });
+
+  return memoized;
+}
+
+module.exports = {
+  memoize,
+  parseTtlMs,
+  stableCacheKey,
+  safeClone,
+};