webspresso 0.0.104 → 0.0.106

package/core/resilience/retry.js

@@ -0,0 +1,203 @@
+'use strict';
+
+/**
+ * Webspresso - Zero-Dependency Retry Engine
+ * Exponential backoff with jitter and transient error detection to prevent thundering herd spikes.
+ * @module core/resilience/retry
+ */
+
+const { parseDurationMs } = require('../utils/time');
+
+/**
+ * Standard transient network error codes that benefit from retries
+ */
+const TRANSIENT_NETWORK_CODES = new Set([
+  'ECONNRESET',
+  'ETIMEDOUT',
+  'EAI_AGAIN',
+  'ENOTFOUND',
+  'ECONNREFUSED',
+  'EPIPE',
+  'EHOSTUNREACH',
+]);
+
+/**
+ * Default predicate determining if an error is transient and safe to retry
+ *
+ * @param {Error} error
+ * @returns {boolean}
+ */
+function isTransientError(error) {
+  if (!error) return false;
+
+  // 1. Check network error code
+  if (error.code && TRANSIENT_NETWORK_CODES.has(error.code)) {
+    return true;
+  }
+
+  // 2. Check HTTP status code (if available)
+  const status = error.status || error.statusCode || error.response?.status;
+  if (typeof status === 'number') {
+    // 429 Too Many Requests, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout
+    if (status === 429 || status === 502 || status === 503 || status === 504) {
+      return true;
+    }
+    // Standard 4xx client errors (400, 401, 403, 404, 422) will not succeed on retry
+    if (status >= 400 && status < 500) {
+      return false;
+    }
+    // Internal server errors 500
+    if (status >= 500) {
+      return true;
+    }
+  }
+
+  // 3. Fallback: Check common error message keywords
+  const message = error.message || '';
+  if (/timeout|connection reset|temporarily unavailable|network error/i.test(message)) {
+    return true;
+  }
+
+  return true;
+}
+
+/**
+ * Calculate exponential backoff delay with optional random jitter
+ *
+ * @param {number} attempt - Current retry attempt (1-based)
+ * @param {number} minTimeoutMs - Initial delay in ms
+ * @param {number} maxTimeoutMs - Maximum delay cap in ms
+ * @param {number} factor - Backoff factor (e.g. 2)
+ * @param {boolean} jitter - Whether to apply full jitter
+ * @returns {number} Delay in milliseconds
+ */
+function calculateBackoffDelay(attempt, minTimeoutMs, maxTimeoutMs, factor, jitter) {
+  const exponential = minTimeoutMs * Math.pow(factor, attempt - 1);
+  const capped = Math.min(maxTimeoutMs, exponential);
+
+  if (!jitter) {
+    return Math.floor(capped);
+  }
+
+  // Full jitter: uniformly distributed between 0 and capped delay
+  return Math.floor(Math.random() * capped);
+}
+
+/**
+ * Sleep helper respecting AbortSignal
+ * @private
+ */
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      return reject(signal.reason || new Error('Aborted'));
+    }
+
+    let timer = null;
+    const onAbort = () => {
+      if (timer) clearTimeout(timer);
+      reject(signal.reason || new Error('Aborted'));
+    };
+
+    if (signal) {
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+
+    timer = setTimeout(() => {
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+
+    if (typeof timer?.unref === 'function') {
+      timer.unref();
+    }
+  });
+}
+
+/**
+ * @typedef {Object} RetryOptions
+ * @property {number} [retries=3] - Maximum retry attempts (0 = no retry)
+ * @property {number|string} [delay=100] - Initial delay in ms or duration string
+ * @property {number|string} [minTimeout=100] - Alias for delay
+ * @property {number|string} [maxTimeout=10000] - Max backoff delay cap in ms or duration string
+ * @property {number} [factor=2] - Exponential multiplier
+ * @property {boolean} [jitter=true] - Whether to apply random jitter
+ * @property {function(Error, number): boolean} [shouldRetry] - Error classifier predicate
+ * @property {function({ attempt: number, error: Error, delayMs: number }): void} [onRetry] - Notification callback
+ * @property {AbortSignal} [signal] - Optional abort signal
+ */
+
+/**
+ * Execute an async operation with automatic exponential backoff retries.
+ *
+ * @param {function(number): Promise<*>} asyncFn - Async function to execute (receives attempt index)
+ * @param {RetryOptions} [options]
+ * @returns {Promise<*>}
+ */
+async function retry(asyncFn, options = {}) {
+  const maxRetries = typeof options.retries === 'number' ? Math.max(0, options.retries) : 3;
+  
+  const minTimeoutMs = options.delay !== undefined
+    ? parseDurationMs(options.delay, 100)
+    : (options.minTimeout !== undefined ? parseDurationMs(options.minTimeout, 100) : 100);
+
+  const maxTimeoutMs = options.maxTimeout !== undefined
+    ? parseDurationMs(options.maxTimeout, 10000)
+    : 10000;
+
+  const factor = typeof options.factor === 'number' && options.factor >= 1 ? options.factor : 2;
+  const jitter = options.jitter !== false;
+  const shouldRetry = typeof options.shouldRetry === 'function' ? options.shouldRetry : isTransientError;
+  const onRetry = typeof options.onRetry === 'function' ? options.onRetry : null;
+  const signal = options.signal || null;
+
+  let attempt = 0;
+
+  while (true) {
+    attempt++;
+    if (signal?.aborted) {
+      throw signal.reason || new Error('Aborted');
+    }
+
+    try {
+      return await asyncFn(attempt);
+    } catch (err) {
+      const isLastAttempt = attempt > maxRetries;
+      const canRetry = shouldRetry(err, attempt);
+
+      if (isLastAttempt || !canRetry || signal?.aborted) {
+        throw err;
+      }
+
+      const delayMs = calculateBackoffDelay(attempt, minTimeoutMs, maxTimeoutMs, factor, jitter);
+
+      if (onRetry) {
+        try {
+          onRetry({ attempt, error: err, delayMs });
+        } catch {
+          // Callback must never break retry loop
+        }
+      }
+
+      await sleep(delayMs, signal);
+    }
+  }
+}
+
+/**
+ * Wrap an async function with retry behavior
+ *
+ * @param {Function} asyncFn
+ * @param {RetryOptions} [options]
+ * @returns {Function}
+ */
+function withRetry(asyncFn, options = {}) {
+  return (...args) => retry((attempt) => asyncFn(...args), options);
+}
+
+module.exports = {
+  retry,
+  withRetry,
+  isTransientError,
+  calculateBackoffDelay,
+};

package/core/schema-cache.js

@@ -1,10 +1,17 @@
+'use strict';
+
 /**
  * Schema Cache
- * Caches compiled Zod schemas per file path
+ * Caches compiled Zod schemas per file path using memory-bounded LRU eviction
  * @module core/schema-cache
  */
 
-const cache = new Map();
+const { createLruCache } = require('./cache');
+
+// 2,000 schemas capacity protects against OOM in dynamic routing/JIT compilation
+const cache = createLruCache({
+  maxEntries: 2000,
+});
 
 /**
  * Get cached schema for a file path

package/core/secrets/index.js

@@ -0,0 +1,113 @@
+/**
+ * Webspresso Cloud Secrets Management
+ *
+ * Zero-dependency cloud secrets manager supporting Google Cloud Secret Manager,
+ * AWS Secrets Manager & SSM Parameter Store, in-memory caching with TTL,
+ * JSON bundle unpacking, dot-notation subkeys, and process.env hydration.
+ *
+ * @module core/secrets
+ */
+
+'use strict';
+
+const { SecretManager, SecretNotFoundError, detectCloudProvider } = require('./manager');
+const { EnvSecretProvider } = require('./providers/env');
+const { MemorySecretProvider } = require('./providers/memory');
+const { GcpSecretProvider } = require('./providers/gcp');
+const { AwsSecretProvider } = require('./providers/aws');
+
+// Global singleton instance
+let defaultSecretManager = null;
+
+/**
+ * Factory to create a SecretManager instance
+ * @param {Object} [options]
+ * @returns {SecretManager}
+ */
+function createSecretManager(options = {}) {
+  return new SecretManager(options);
+}
+
+/**
+ * Get or initialize default SecretManager singleton
+ * @param {Object} [options]
+ * @returns {SecretManager}
+ */
+function getDefaultSecretManager(options = {}) {
+  if (!defaultSecretManager || Object.keys(options).length > 0) {
+    defaultSecretManager = new SecretManager(options);
+  }
+  return defaultSecretManager;
+}
+
+/**
+ * Convenience helper to resolve a single secret
+ * @param {string} secretName
+ * @param {Object} [options]
+ * @returns {Promise<any>}
+ */
+async function resolveSecret(secretName, options = {}) {
+  const manager = getDefaultSecretManager(options);
+  return manager.get(secretName, options);
+}
+
+/**
+ * Convenience helper to load secrets and inject them into process.env at bootstrap
+ *
+ * Example:
+ * ```javascript
+ * const { loadSecrets } = require('webspresso/core/secrets');
+ *
+ * await loadSecrets({
+ *   provider: 'cloudrun', // or 'auto'
+ *   secrets: {
+ *     SESSION_SECRET: 'prod-session-secret:latest',
+ *     DATABASE_URL: 'production-db-url',
+ *   }
+ * });
+ * ```
+ *
+ * @param {Object} options
+ * @param {'auto'|'gcp'|'cloudrun'|'aws'|'env'|'memory'} [options.provider='auto']
+ * @param {Record<string, string>|string[]} [options.secrets]
+ * @param {string} [options.bundle] - JSON secret bundle to unpack
+ * @param {boolean} [options.inject=true] - Set into process.env
+ * @param {boolean} [options.override=false] - Override existing process.env
+ * @returns {Promise<Record<string, any>>}
+ */
+async function loadSecrets(options = {}) {
+  const manager = createSecretManager(options);
+  const result = {};
+
+  if (options.secrets) {
+    const loaded = await manager.load(options.secrets, {
+      inject: options.inject !== false,
+      override: options.override === true,
+    });
+    Object.assign(result, loaded);
+  }
+
+  if (options.bundle) {
+    const bundleLoaded = await manager.loadBundle(options.bundle, {
+      inject: options.inject !== false,
+      override: options.override === true,
+    });
+    Object.assign(result, bundleLoaded);
+  }
+
+  return result;
+}
+
+module.exports = {
+  SecretManager,
+  SecretNotFoundError,
+  createSecretManager,
+  getDefaultSecretManager,
+  resolveSecret,
+  loadSecrets,
+  detectCloudProvider,
+  EnvSecretProvider,
+  MemorySecretProvider,
+  GcpSecretProvider,
+  AwsSecretProvider,
+};

package/core/secrets/manager.js

@@ -0,0 +1,308 @@
+/**
+ * Secret Manager Core for Webspresso
+ * Provides multi-cloud secret resolution, in-memory caching with TTL,
+ * JSON bundle unpacking, subkey dot-notation, and process.env hydration.
+ *
+ * @module core/secrets/manager
+ */
+
+'use strict';
+
+const { EnvSecretProvider } = require('./providers/env');
+const { MemorySecretProvider } = require('./providers/memory');
+const { GcpSecretProvider } = require('./providers/gcp');
+const { AwsSecretProvider } = require('./providers/aws');
+
+/**
+ * Parse human TTL string ('5m', '1h', '30s') or number to milliseconds
+ * @param {string|number} ttl
+ * @returns {number}
+ */
+function parseTtlMs(ttl) {
+  if (typeof ttl === 'number' && Number.isFinite(ttl)) {
+    return Math.max(0, ttl);
+  }
+  if (typeof ttl === 'string') {
+    const trimmed = ttl.trim().toLowerCase();
+    const match = trimmed.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)?$/);
+    if (!match) return 300_000;
+    const value = parseFloat(match[1]);
+    const unit = match[2] || 'ms';
+    switch (unit) {
+      case 'ms': return Math.round(value);
+      case 's': return Math.round(value * 1000);
+      case 'm': return Math.round(value * 60_000);
+      case 'h': return Math.round(value * 3_600_000);
+      case 'd': return Math.round(value * 86_400_000);
+      default: return 300_000;
+    }
+  }
+  return 300_000; // 5 minutes default
+}
+
+/**
+ * Detect target cloud provider automatically from environment
+ * @returns {'gcp'|'aws'|'env'}
+ */
+function detectCloudProvider() {
+  if (
+    process.env.K_SERVICE ||
+    process.env.GOOGLE_CLOUD_PROJECT ||
+    process.env.GCP_PROJECT ||
+    process.env.GOOGLE_APPLICATION_CREDENTIALS
+  ) {
+    return 'gcp';
+  }
+
+  if (
+    process.env.AWS_EXECUTION_ENV ||
+    process.env.AWS_LAMBDA_FUNCTION_NAME ||
+    (process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY)
+  ) {
+    return 'aws';
+  }
+
+  return 'env';
+}
+
+class SecretNotFoundError extends Error {
+  constructor(secretName) {
+    super(`Secret "${secretName}" was not found in the configured secret provider.`);
+    this.name = 'SecretNotFoundError';
+    this.secretName = secretName;
+  }
+}
+
+class SecretManager {
+  /**
+   * @param {Object} [options]
+   * @param {'auto'|'gcp'|'cloudrun'|'aws'|'env'|'memory'|Object} [options.provider='auto']
+   * @param {string|number} [options.cacheTtl='5m']
+   * @param {boolean} [options.cache=true]
+   * @param {string} [options.projectId] - For GCP
+   * @param {string} [options.region] - For AWS
+   * @param {Object} [options.client] - Duck-typed official client
+   * @param {Record<string, any>} [options.mockSecrets] - Initial memory secrets
+   * @param {Function} [options.httpTransport]
+   */
+  constructor(options = {}) {
+    this.options = options;
+    this.cacheEnabled = options.cache !== false;
+    this.cacheTtlMs = parseTtlMs(options.cacheTtl ?? '5m');
+    this.cacheStore = new Map(); // key -> { value, expiresAt }
+
+    let providerType = options.provider || 'auto';
+    if (providerType === 'auto') {
+      providerType = detectCloudProvider();
+    }
+
+    if (typeof providerType === 'object' && providerType !== null) {
+      this.provider = providerType;
+    } else if (providerType === 'gcp' || providerType === 'cloudrun') {
+      this.provider = new GcpSecretProvider(options);
+    } else if (providerType === 'aws') {
+      this.provider = new AwsSecretProvider(options);
+    } else if (providerType === 'memory') {
+      this.provider = new MemorySecretProvider({
+        secrets: options.mockSecrets || options.secrets,
+      });
+    } else {
+      this.provider = new EnvSecretProvider(options);
+    }
+  }
+
+  /**
+   * Invalidate cached secret
+   * @param {string} secretName
+   */
+  invalidate(secretName) {
+    if (secretName) {
+      this.cacheStore.delete(secretName);
+    }
+  }
+
+  /**
+   * Clear entire in-memory secrets cache
+   */
+  clearCache() {
+    this.cacheStore.clear();
+  }
+
+  /**
+   * Fetch a secret value
+   * Supports:
+   * - Dot notation for subkeys: e.g. get('my-bundle.DATABASE_URL')
+   * - JSON parsing: get('my-bundle', { parseJson: true })
+   * - Default fallback: get('MISSING', { fallback: 'default' })
+   * - Required validation: get('MISSING', { required: true })
+   *
+   * @param {string} secretName
+   * @param {Object} [options]
+   * @param {any} [options.fallback]
+   * @param {boolean} [options.required=false]
+   * @param {boolean} [options.parseJson=false]
+   * @param {boolean} [options.bypassCache=false]
+   * @returns {Promise<any>}
+   */
+  async get(secretName, options = {}) {
+    if (!secretName || typeof secretName !== 'string') {
+      if (options.required) {
+        throw new SecretNotFoundError(String(secretName));
+      }
+      return options.fallback !== undefined ? options.fallback : null;
+    }
+
+    const { fallback, required = false, parseJson = false, bypassCache = false } = options;
+
+    // Handle dot notation subkey (e.g. "prod/bundle.DB_PASSWORD")
+    if (secretName.includes('.') && !secretName.startsWith('.')) {
+      const dotIndex = secretName.indexOf('.');
+      const bundleName = secretName.substring(0, dotIndex);
+      const subKey = secretName.substring(dotIndex + 1);
+
+      const bundleVal = await this.get(bundleName, { bypassCache });
+      if (bundleVal) {
+        try {
+          const parsed = typeof bundleVal === 'object' ? bundleVal : JSON.parse(bundleVal);
+          if (parsed && Object.prototype.hasOwnProperty.call(parsed, subKey)) {
+            return parsed[subKey];
+          }
+        } catch (_) {}
+      }
+
+      if (required) {
+        throw new SecretNotFoundError(secretName);
+      }
+      return fallback !== undefined ? fallback : null;
+    }
+
+    // Check in-memory cache
+    if (this.cacheEnabled && !bypassCache) {
+      const cached = this.cacheStore.get(secretName);
+      if (cached && Date.now() < cached.expiresAt) {
+        return this._formatResult(cached.value, parseJson);
+      }
+    }
+
+    // Resolve via provider
+    let rawValue = null;
+    if (this.provider && typeof this.provider.get === 'function') {
+      rawValue = await this.provider.get(secretName);
+    }
+
+    if (rawValue === null || rawValue === undefined) {
+      // Fallback to process.env if cloud provider didn't have it
+      if (process.env[secretName] !== undefined) {
+        rawValue = process.env[secretName];
+      }
+    }
+
+    if (rawValue === null || rawValue === undefined) {
+      if (required) {
+        throw new SecretNotFoundError(secretName);
+      }
+      return fallback !== undefined ? fallback : null;
+    }
+
+    // Save to cache
+    if (this.cacheEnabled) {
+      this.cacheStore.set(secretName, {
+        value: rawValue,
+        expiresAt: Date.now() + this.cacheTtlMs,
+      });
+    }
+
+    return this._formatResult(rawValue, parseJson);
+  }
+
+  /**
+   * Internal formatter
+   * @private
+   */
+  _formatResult(val, parseJson) {
+    if (!parseJson) return val;
+    if (typeof val === 'object' && val !== null) return val;
+    try {
+      return JSON.parse(val);
+    } catch (_) {
+      return val;
+    }
+  }
+
+  /**
+   * Load multiple secrets and optionally inject them into process.env
+   * @param {Record<string, string>|string[]} secretsMapOrArray - Map of { ENV_KEY: 'secret-name' } or array of names
+   * @param {Object} [options]
+   * @param {boolean} [options.inject=true] - Set into process.env
+   * @param {boolean} [options.override=false] - Override existing process.env
+   * @returns {Promise<Record<string, string>>}
+   */
+  async load(secretsMapOrArray, options = {}) {
+    const { inject = true, override = false } = options;
+    const result = {};
+
+    let mappings = {};
+    if (Array.isArray(secretsMapOrArray)) {
+      for (const name of secretsMapOrArray) {
+        mappings[name] = name;
+      }
+    } else if (typeof secretsMapOrArray === 'object' && secretsMapOrArray !== null) {
+      mappings = secretsMapOrArray;
+    }
+
+    for (const [envKey, secretName] of Object.entries(mappings)) {
+      let val = await this.get(secretName);
+      if ((val === null || val === undefined) && envKey !== secretName) {
+        val = await this.get(envKey);
+      }
+      if (val !== null && val !== undefined) {
+        const strVal = typeof val === 'object' ? JSON.stringify(val) : String(val);
+        result[envKey] = strVal;
+        if (inject) {
+          if (override || process.env[envKey] === undefined) {
+            process.env[envKey] = strVal;
+          }
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Unpack a JSON secret bundle and inject all key-values into process.env
+   * @param {string} bundleName - Secret name holding JSON object
+   * @param {Object} [options]
+   * @param {boolean} [options.inject=true]
+   * @param {boolean} [options.override=false]
+   * @returns {Promise<Record<string, any>>}
+   */
+  async loadBundle(bundleName, options = {}) {
+    const { inject = true, override = false } = options;
+    const bundleContent = await this.get(bundleName, { parseJson: true });
+
+    if (!bundleContent || typeof bundleContent !== 'object') {
+      return {};
+    }
+
+    const result = {};
+    for (const [key, val] of Object.entries(bundleContent)) {
+      const strVal = typeof val === 'object' ? JSON.stringify(val) : String(val ?? '');
+      result[key] = strVal;
+      if (inject) {
+        if (override || process.env[key] === undefined) {
+          process.env[key] = strVal;
+        }
+      }
+    }
+
+    return result;
+  }
+}
+
+module.exports = {
+  SecretManager,
+  SecretNotFoundError,
+  parseTtlMs,
+  detectCloudProvider,
+};