webspresso 0.0.104 → 0.0.105

package/core/cache/tagged-lru.js

@@ -0,0 +1,346 @@
+'use strict';
+
+/**
+ * Webspresso - Tagged LRU Cache
+ * Combines zero-allocation O(1) LRU eviction, byte budget constraints, and
+ * bidirectional tag-based invalidation for ORM query caching and full-app caching.
+ * Guaranteed zero dangling Set memory leaks on LRU evictions.
+ * @module core/cache/tagged-lru
+ */
+
+const { LruCache } = require('./lru');
+
+/**
+ * Normalizes input tags into clean string array
+ * @param {string|string[]|Set<string>} tags
+ * @returns {string[]}
+ */
+function normalizeTags(tags) {
+  if (!tags) return [];
+  if (typeof tags === 'string') return [tags.trim()];
+  if (tags instanceof Set) return Array.from(tags).map(String);
+  if (Array.isArray(tags)) return tags.map(String).filter(Boolean);
+  return [];
+}
+
+class TaggedLruCache {
+  /**
+   * @param {import('./lru').LruCacheOptions} [options]
+   */
+  constructor(options = {}) {
+    /** @type {Map<string, Set<string>>} */
+    this.tagToKeys = new Map();
+
+    /** @type {Map<string, Set<string>>} */
+    this.keyToTags = new Map();
+
+    const userOnEvict = options.onEvict;
+
+    // Connect internal LRU eviction directly to tag cleanup
+    this.lru = new LruCache({
+      ...options,
+      onEvict: (key, value, reason) => {
+        this._removeKeyFromTags(key);
+        if (typeof userOnEvict === 'function') {
+          userOnEvict(key, value, reason);
+        }
+      },
+    });
+  }
+
+  get size() {
+    return this.lru.size;
+  }
+
+  get currentBytes() {
+    return this.lru.currentBytes;
+  }
+
+  get maxBytes() {
+    return this.lru.maxBytes;
+  }
+
+  get maxEntries() {
+    return this.lru.maxEntries;
+  }
+
+  get hits() {
+    return this.lru.hits;
+  }
+
+  get misses() {
+    return this.lru.misses;
+  }
+
+  get hitRate() {
+    return this.lru.hitRate;
+  }
+
+  get evictions() {
+    return this.lru.evictions;
+  }
+
+  get expirations() {
+    return this.lru.expirations;
+  }
+
+  /**
+   * Clean up all tag mappings for a key (called on eviction, deletion, or tag rewrite)
+   * @private
+   */
+  _removeKeyFromTags(key) {
+    const tags = this.keyToTags.get(key);
+    if (!tags) return;
+
+    for (const tag of tags) {
+      const set = this.tagToKeys.get(tag);
+      if (set) {
+        set.delete(key);
+        if (set.size === 0) {
+          this.tagToKeys.delete(tag);
+        }
+      }
+    }
+
+    this.keyToTags.delete(key);
+  }
+
+  /**
+   * Associate tags with a key
+   * @private
+   */
+  _addKeyToTags(key, tags) {
+    if (!tags || tags.length === 0) return;
+
+    const tagSet = new Set(tags);
+    this.keyToTags.set(key, tagSet);
+
+    for (const tag of tagSet) {
+      let keySet = this.tagToKeys.get(tag);
+      if (!keySet) {
+        keySet = new Set();
+        this.tagToKeys.set(tag, keySet);
+      }
+      keySet.add(key);
+    }
+  }
+
+  /**
+   * Retrieve item by key
+   */
+  get(key) {
+    return this.lru.get(key);
+  }
+
+  /**
+   * Peek item without updating LRU order
+   */
+  peek(key) {
+    return this.lru.peek(key);
+  }
+
+  /**
+   * Check existence
+   */
+  has(key) {
+    return this.lru.has(key);
+  }
+
+  /**
+   * Store item with optional tags, TTL, and size
+   *
+   * @param {string} key
+   * @param {*} value
+   * @param {Object} [options]
+   * @param {string|string[]} [options.tags]
+   * @param {string|number} [options.ttl]
+   * @param {number} [options.ttlMs]
+   * @param {number} [options.size]
+   * @returns {this}
+   */
+  set(key, value, options = {}) {
+    const tags = normalizeTags(options.tags);
+
+    // If key already had tags, clean them up first before assigning new tags
+    if (this.keyToTags.has(key)) {
+      this._removeKeyFromTags(key);
+    }
+
+    this._addKeyToTags(key, tags);
+    this.lru.set(key, value, options);
+
+    return this;
+  }
+
+  /**
+   * Delete single key
+   */
+  delete(key) {
+    this._removeKeyFromTags(key);
+    return this.lru.delete(key);
+  }
+
+  /**
+   * Alias for delete
+   */
+  del(key) {
+    return this.delete(key);
+  }
+
+  /**
+   * Invalidate all keys matching a specific tag
+   *
+   * @param {string} tag
+   * @returns {number} Count of invalidated keys
+   */
+  invalidateTag(tag) {
+    const keySet = this.tagToKeys.get(String(tag));
+    if (!keySet || keySet.size === 0) return 0;
+
+    // Copy keys to array to avoid mutating set during iteration
+    const keys = Array.from(keySet);
+    for (const key of keys) {
+      this.lru.delete(key);
+    }
+
+    this.tagToKeys.delete(String(tag));
+    return keys.length;
+  }
+
+  /**
+   * Invalidate multiple tags in a single operation
+   *
+   * @param {string[]|string} tags
+   * @returns {number} Total count of invalidated keys
+   */
+  invalidateTags(tags) {
+    const normalized = normalizeTags(tags);
+    if (normalized.length === 0) return 0;
+
+    const toDelete = new Set();
+    for (const t of normalized) {
+      const keys = this.tagToKeys.get(t);
+      if (keys) {
+        for (const k of keys) {
+          toDelete.add(k);
+        }
+      }
+    }
+
+    for (const k of toDelete) {
+      this.lru.delete(k);
+    }
+
+    return toDelete.size;
+  }
+
+  /**
+   * Check if a tag exists and has active keys
+   * @param {string} tag
+   * @returns {boolean}
+   */
+  hasTag(tag) {
+    const keys = this.tagToKeys.get(String(tag));
+    return Boolean(keys && keys.size > 0);
+  }
+
+  /**
+   * Get all active keys for a tag
+   * @param {string} tag
+   * @returns {string[]}
+   */
+  getKeysForTag(tag) {
+    const keys = this.tagToKeys.get(String(tag));
+    return keys ? Array.from(keys) : [];
+  }
+
+  /**
+   * Purge everything
+   */
+  clear() {
+    this.tagToKeys.clear();
+    this.keyToTags.clear();
+    this.lru.clear();
+    return this;
+  }
+
+  /**
+   * Actively prune expired entries
+   */
+  pruneExpired() {
+    return this.lru.pruneExpired();
+  }
+
+  /**
+   * Thundering herd stampede protection with tagging support
+   */
+  async getOrSet(key, asyncFactory, options = {}) {
+    const cached = this.get(key);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    return this.lru.getOrSet(key, asyncFactory, options);
+  }
+
+  /**
+   * Returns stats compatible with both LruCache and ORM CacheProvider
+   */
+  getSizeStats() {
+    return {
+      entries: this.lru.size,
+      tags: this.tagToKeys.size,
+      currentBytes: this.lru.currentBytes,
+      maxBytes: this.lru.maxBytes,
+      maxEntries: this.lru.maxEntries,
+      hits: this.lru.hits,
+      misses: this.lru.misses,
+      hitRate: this.lru.hitRate,
+      evictions: this.lru.evictions,
+      expirations: this.lru.expirations,
+    };
+  }
+
+  getStats() {
+    return this.getSizeStats();
+  }
+
+  resetStats() {
+    this.lru.resetStats();
+  }
+
+  keys() {
+    return this.lru.keys();
+  }
+
+  values() {
+    return this.lru.values();
+  }
+
+  entries() {
+    return this.lru.entries();
+  }
+
+  [Symbol.iterator]() {
+    return this.lru.entries();
+  }
+
+  forEach(callback, thisArg) {
+    this.lru.forEach(callback, thisArg);
+  }
+}
+
+/**
+ * Factory helper
+ * @param {import('./lru').LruCacheOptions} [options]
+ * @returns {TaggedLruCache}
+ */
+function createTaggedLruCache(options) {
+  return new TaggedLruCache(options);
+}
+
+module.exports = {
+  TaggedLruCache,
+  createTaggedLruCache,
+  normalizeTags,
+};

package/core/commands/registry.js

@@ -9,6 +9,7 @@
 const fs = require('fs');
 const path = require('path');
 const { defineCommand } = require('./define-command');
+const { walkDirectory } = require('../utils/fs');
 
 /**
  * Recursively find command files in directory
@@ -16,26 +17,11 @@ const { defineCommand } = require('./define-command');
  * @returns {string[]}
  */
 function findCommandFiles(dir) {
-  if (!fs.existsSync(dir)) return [];
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  const files = [];
-
-  for (const entry of entries) {
-    const fullPath = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...findCommandFiles(fullPath));
-    } else if (
-      entry.isFile() &&
-      entry.name.endsWith('.js') &&
-      !entry.name.startsWith('_') &&
-      !entry.name.endsWith('.test.js') &&
-      !entry.name.endsWith('.spec.js')
-    ) {
-      files.push(fullPath);
-    }
-  }
-
-  return files;
+  return walkDirectory(dir, {
+    extensions: ['.js'],
+    ignorePrefixes: ['_', '.'],
+    ignoreTests: true,
+  });
 }
 
 /**

package/core/early-hints/index.js

@@ -0,0 +1,267 @@
+'use strict';
+
+/**
+ * Webspresso HTTP 103 Early Hints Module
+ * Zero-dependency RFC 8288 / RFC 8297 compliant Early Hints dispatcher.
+ * Preloads critical assets (CSS, JS, Fonts) before SSR rendering finishes to optimize TTFB, FCP and LCP.
+ *
+ * @module core/early-hints
+ */
+
+const EXTENSION_AS_MAP = {
+  '.css': 'style',
+  '.js': 'script',
+  '.mjs': 'script',
+  '.cjs': 'script',
+  '.woff2': 'font',
+  '.woff': 'font',
+  '.ttf': 'font',
+  '.otf': 'font',
+  '.png': 'image',
+  '.jpg': 'image',
+  '.jpeg': 'image',
+  '.webp': 'image',
+  '.avif': 'image',
+  '.svg': 'image',
+  '.gif': 'image',
+  '.ico': 'image',
+  '.json': 'fetch',
+  '.mp4': 'video',
+  '.webm': 'video',
+  '.mp3': 'audio',
+  '.wav': 'audio',
+  '.ogg': 'audio',
+};
+
+/**
+ * Infers the resource `as` type based on file extension
+ * @param {string} url - Resource URL or path
+ * @returns {string|null}
+ */
+function inferAsType(url) {
+  if (typeof url !== 'string' || !url) return null;
+  const cleanUrl = url.split('?')[0].split('#')[0];
+  const lastDot = cleanUrl.lastIndexOf('.');
+  if (lastDot === -1) return null;
+  const ext = cleanUrl.slice(lastDot).toLowerCase();
+  return EXTENSION_AS_MAP[ext] || null;
+}
+
+/**
+ * Formats a single link candidate into an RFC 8288 Link header string
+ * @param {string|Object} item - URL string or link options object
+ * @returns {string|null}
+ */
+function formatLink(item) {
+  if (!item) return null;
+
+  // Already a serialized RFC 8288 Link header
+  if (typeof item === 'string') {
+    const trimmed = item.trim();
+    if (!trimmed) return null;
+    if (trimmed.startsWith('<') && trimmed.includes('>')) {
+      return trimmed;
+    }
+    const deducedAs = inferAsType(trimmed);
+    const parts = [`<${trimmed}>`, 'rel=preload'];
+    if (deducedAs) {
+      parts.push(`as=${deducedAs}`);
+      if (deducedAs === 'font') {
+        parts.push('crossorigin');
+      }
+    }
+    return parts.join('; ');
+  }
+
+  if (typeof item === 'object') {
+    const rawUrl = item.url || item.href;
+    if (!rawUrl || typeof rawUrl !== 'string') return null;
+    const url = rawUrl.trim();
+    if (!url) return null;
+
+    const rel = item.rel || 'preload';
+    const parts = [`<${url}>`, `rel=${rel}`];
+
+    const asType = item.as || (rel === 'preload' ? inferAsType(url) : null);
+    if (asType) {
+      parts.push(`as=${asType}`);
+    }
+
+    const co = item.crossOrigin !== undefined ? item.crossOrigin : item.crossorigin;
+    if (co === true || co === '' || co === 'anonymous') {
+      parts.push('crossorigin');
+    } else if (co === 'use-credentials') {
+      parts.push('crossorigin=use-credentials');
+    } else if (asType === 'font' && rel === 'preload' && co === undefined) {
+      // Browsers require CORS for font preloads regardless of origin
+      parts.push('crossorigin');
+    }
+
+    if (item.type) {
+      parts.push(`type="${item.type}"`);
+    }
+
+    if (item.media) {
+      parts.push(`media="${item.media}"`);
+    }
+
+    const fetchPriority = item.fetchPriority || item.fetchpriority;
+    if (fetchPriority) {
+      parts.push(`fetchpriority=${fetchPriority}`);
+    }
+
+    const noPush = item.noPush !== undefined ? item.noPush : item.nopush;
+    if (noPush) {
+      parts.push('nopush');
+    }
+
+    return parts.join('; ');
+  }
+
+  return null;
+}
+
+/**
+ * Normalizes one or more link items into an array of RFC 8288 Link header strings
+ * @param {string|Object|Array<string|Object>} links
+ * @returns {string[]}
+ */
+function formatLinkHeader(links) {
+  if (!links) return [];
+  const list = Array.isArray(links) ? links : [links];
+  const out = [];
+
+  for (const item of list) {
+    if (!item) continue;
+    if (typeof item === 'string' && item.includes(',') && !item.startsWith('<')) {
+      // Comma-separated list of simple URLs
+      const splitUrls = item.split(',').map((s) => s.trim()).filter(Boolean);
+      for (const u of splitUrls) {
+        const formatted = formatLink(u);
+        if (formatted) out.push(formatted);
+      }
+      continue;
+    }
+    const formatted = formatLink(item);
+    if (formatted) {
+      out.push(formatted);
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Safely sends HTTP 103 Early Hints before the final response is generated.
+ * Handles Node.js runtime variations, headersSent state, and socket closure gracefully.
+ *
+ * @param {import('http').ServerResponse} res - Node HTTP ServerResponse
+ * @param {string|Object|Array<string|Object>} hints - Links or hints map
+ * @param {Function} [callback] - Optional completion callback
+ * @returns {boolean} Whether Early Hints were dispatched
+ */
+function sendEarlyHints(res, hints, callback) {
+  const cb = typeof callback === 'function' ? callback : null;
+
+  if (!res || typeof res.writeEarlyHints !== 'function') {
+    if (cb) process.nextTick(cb);
+    return false;
+  }
+
+  if (res.headersSent || res.writableEnded || res.destroyed) {
+    if (cb) process.nextTick(cb);
+    return false;
+  }
+
+  let payload = null;
+
+  if (Array.isArray(hints) || typeof hints === 'string') {
+    const formattedLinks = formatLinkHeader(hints);
+    if (formattedLinks.length === 0) {
+      if (cb) process.nextTick(cb);
+      return false;
+    }
+    payload = { link: formattedLinks };
+  } else if (typeof hints === 'object' && hints !== null) {
+    if (hints.url || hints.href) {
+      const formatted = formatLink(hints);
+      if (!formatted) {
+        if (cb) process.nextTick(cb);
+        return false;
+      }
+      payload = { link: [formatted] };
+    } else {
+      payload = { ...hints };
+      const rawLink = payload.link || payload.Link;
+      if (rawLink) {
+        const formatted = formatLinkHeader(rawLink);
+        if (formatted.length > 0) {
+          payload.link = formatted;
+          if (payload.Link) delete payload.Link;
+        }
+      }
+    }
+  } else {
+    if (cb) process.nextTick(cb);
+    return false;
+  }
+
+  try {
+    res.writeEarlyHints(payload, (err) => {
+      if (cb) cb(err || null);
+    });
+    return true;
+  } catch (err) {
+    if (cb) cb(err);
+    return false;
+  }
+}
+
+/**
+ * Creates an Express middleware for HTTP 103 Early Hints
+ * Attaches `res.earlyHints(links, cb)` to every response and optionally sends default hints on GET/HEAD requests.
+ *
+ * @param {boolean|Object} [options={}] - Early hints configuration
+ * @param {boolean} [options.enabled=true] - Whether early hints are enabled
+ * @param {string[]|Function} [options.links] - Default preload links for all GET/HEAD requests
+ * @returns {Function} Express middleware
+ */
+function createEarlyHintsMiddleware(options = {}) {
+  const opts = typeof options === 'boolean' ? { enabled: options } : (options || {});
+  const enabled = opts.enabled !== false;
+  const defaultLinks = opts.links || null;
+
+  return function earlyHintsMiddleware(req, res, next) {
+    // Attach res.earlyHints helper (available regardless of whether global auto hints are active)
+    if (!res.earlyHints) {
+      res.earlyHints = function earlyHintsHelper(links, cb) {
+        return sendEarlyHints(res, links, cb);
+      };
+    }
+
+    if (enabled && defaultLinks && (req.method === 'GET' || req.method === 'HEAD')) {
+      try {
+        const linksToSend = typeof defaultLinks === 'function' ? defaultLinks(req) : defaultLinks;
+        if (linksToSend) {
+          sendEarlyHints(res, linksToSend);
+        }
+      } catch (err) {
+        // Early hints must never break normal request flow
+        if (process.env.NODE_ENV === 'development') {
+          console.warn('[EarlyHints] Failed to evaluate default links:', err.message);
+        }
+      }
+    }
+
+    next();
+  };
+}
+
+module.exports = {
+  EXTENSION_AS_MAP,
+  inferAsType,
+  formatLink,
+  formatLinkHeader,
+  sendEarlyHints,
+  createEarlyHintsMiddleware,
+};

package/core/errors/domain.js

@@ -180,6 +180,51 @@ class RouteGenerationError extends RouterError {
   }
 }
 
+/**
+ * Circuit Breaker Open Error
+ * Thrown when an invocation is rejected because the circuit is in the OPEN state.
+ * Maps to HTTP 503 Service Unavailable.
+ */
+class CircuitBreakerOpenError extends HttpError {
+  /**
+   * @param {string} [breakerName='default']
+   * @param {number} [resetTimeoutMs=0]
+   * @param {Object} [options]
+   */
+  constructor(breakerName = 'default', resetTimeoutMs = 0, options = {}) {
+    super(503, `Circuit breaker '${breakerName}' is OPEN and failing fast`, {
+      code: 'CIRCUIT_BREAKER_OPEN',
+      expose: true,
+      ...options,
+    });
+    this.breakerName = breakerName;
+    this.resetTimeoutMs = resetTimeoutMs;
+    this.state = 'OPEN';
+  }
+}
+
+/**
+ * Circuit Breaker Timeout Error
+ * Thrown when execution inside a circuit breaker exceeds timeout.
+ * Maps to HTTP 504 Gateway Timeout.
+ */
+class CircuitBreakerTimeoutError extends HttpError {
+  /**
+   * @param {string} [breakerName='default']
+   * @param {number} [timeoutMs=0]
+   * @param {Object} [options]
+   */
+  constructor(breakerName = 'default', timeoutMs = 0, options = {}) {
+    super(504, `Execution in circuit breaker '${breakerName}' timed out after ${timeoutMs}ms`, {
+      code: 'CIRCUIT_BREAKER_TIMEOUT',
+      expose: true,
+      ...options,
+    });
+    this.breakerName = breakerName;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
 module.exports = {
   ValidationError,
   ConfigurationError,
@@ -190,4 +235,7 @@ module.exports = {
   RouterError,
   RouteNotFoundError,
   RouteGenerationError,
+  CircuitBreakerOpenError,
+  CircuitBreakerTimeoutError,
 };
+