webspresso 0.0.90 → 0.0.93

package/core/shutdown/shutdown-manager.js

@@ -0,0 +1,312 @@
+/**
+ * ShutdownManager
+ * Framework-independent lifecycle coordinator for graceful shutdown, forced connection termination,
+ * application shutdown hooks, and plugin cleanup disposers.
+ * @module core/shutdown/shutdown-manager
+ */
+
+class ShutdownManager {
+  /**
+   * @param {Object} [options]
+   * @param {boolean} [options.enabled=true] - Enable shutdown management
+   * @param {'graceful'|'force'} [options.mode='graceful'] - Shutdown mode ('graceful' or 'force')
+   * @param {number} [options.timeout=10000] - Graceful timeout in milliseconds before forcing close
+   * @param {string[]} [options.signals=['SIGINT', 'SIGTERM']] - Process signals to listen for
+   * @param {Object|null} [options.logger=console] - Logger instance (or null to disable logs)
+   * @param {boolean} [options.exitOnSignal=true] - Whether to call process.exit when triggered by a process signal
+   */
+  constructor(options = {}) {
+    this.options = {
+      enabled: options.enabled !== false,
+      mode: options.mode === 'force' ? 'force' : 'graceful',
+      timeout: typeof options.timeout === 'number' && options.timeout >= 0 ? options.timeout : 10_000,
+      signals: Array.isArray(options.signals) ? options.signals : ['SIGINT', 'SIGTERM'],
+      logger: options.logger === null ? null : (options.logger || console),
+      exitOnSignal: options.exitOnSignal !== false,
+    };
+
+    this.isShuttingDown = false;
+    this.isClosed = false;
+
+    /** @type {Array<Function>} */
+    this._hooks = [];
+
+    /** @type {Array<{ name: string, fn: Function }>} */
+    this._disposers = [];
+
+    /** @type {Array<{ close: () => Promise<void>, forceClose?: () => void, closeIdleConnections?: () => void }>} */
+    this._adapters = [];
+
+    /** @type {Promise<void>|null} */
+    this._shutdownPromise = null;
+
+    /** @type {Map<string, Function>} */
+    this._signalListeners = new Map();
+  }
+
+  get mode() {
+    return this.options.mode;
+  }
+
+  set mode(value) {
+    this.options.mode = value === 'force' ? 'force' : 'graceful';
+  }
+
+  get timeout() {
+    return this.options.timeout;
+  }
+
+  set timeout(value) {
+    if (typeof value === 'number' && value >= 0) {
+      this.options.timeout = value;
+    }
+  }
+
+  /**
+   * Safe logger helper
+   * @param {'info'|'warn'|'error'|'debug'} level
+   * @param {string} message
+   * @param {unknown} [extra]
+   */
+  _log(level, message, extra) {
+    const logger = this.options.logger;
+    if (!logger) return;
+
+    const formatted = `[webspresso] ${message}`;
+    if (typeof logger[level] === 'function') {
+      if (extra !== undefined) {
+        logger[level](formatted, extra);
+      } else {
+        logger[level](formatted);
+      }
+    } else if (typeof logger.log === 'function') {
+      if (extra !== undefined) {
+        logger.log(formatted, extra);
+      } else {
+        logger.log(formatted);
+      }
+    }
+  }
+
+  /**
+   * Register an application shutdown hook
+   * @param {Function} fn - Sync or async callback
+   * @returns {this}
+   */
+  onShutdown(fn) {
+    if (typeof fn === 'function') {
+      this._hooks.push(fn);
+    }
+    return this;
+  }
+
+  /**
+   * Register a plugin disposer / cleanup function
+   * @param {string|Function} nameOrFn - Plugin name or disposer function
+   * @param {Function} [maybeFn] - Disposer function if name is provided
+   * @returns {this}
+   */
+  registerDisposer(nameOrFn, maybeFn) {
+    let name = 'plugin';
+    let fn = nameOrFn;
+
+    if (typeof nameOrFn === 'string' && typeof maybeFn === 'function') {
+      name = nameOrFn;
+      fn = maybeFn;
+    }
+
+    if (typeof fn === 'function') {
+      this._disposers.push({ name, fn });
+    }
+    return this;
+  }
+
+  /**
+   * Register a server adapter (e.g. NodeHttpAdapter)
+   * @param {{ close: () => Promise<void>, forceClose?: () => void, closeIdleConnections?: () => void }} adapter
+   * @returns {this}
+   */
+  registerAdapter(adapter) {
+    if (adapter && typeof adapter.close === 'function') {
+      this._adapters.push(adapter);
+    }
+    return this;
+  }
+
+  /**
+   * Attach signal listeners (SIGINT, SIGTERM) to the Node.js process
+   * @returns {this}
+   */
+  enableShutdownHooks() {
+    if (!this.options.enabled || typeof process === 'undefined' || typeof process.on !== 'function') {
+      return this;
+    }
+
+    for (const signal of this.options.signals) {
+      if (!this._signalListeners.has(signal)) {
+        const listener = async () => {
+          this._log('info', `${signal} received`);
+          try {
+            await this.close(signal);
+            if (this.options.exitOnSignal) {
+              process.exit(0);
+            }
+          } catch (err) {
+            this._log('error', `Shutdown failed following ${signal}:`, err);
+            if (this.options.exitOnSignal) {
+              process.exit(1);
+            }
+          }
+        };
+
+        this._signalListeners.set(signal, listener);
+        process.on(signal, listener);
+      }
+    }
+
+    return this;
+  }
+
+  /**
+   * Detach signal listeners from process
+   * @returns {this}
+   */
+  disableShutdownHooks() {
+    if (typeof process === 'undefined' || typeof process.removeListener !== 'function') {
+      return this;
+    }
+
+    for (const [signal, listener] of this._signalListeners.entries()) {
+      process.removeListener(signal, listener);
+    }
+    this._signalListeners.clear();
+    return this;
+  }
+
+  /**
+   * Execute the shutdown lifecycle pipeline.
+   * Idempotent: safe to call multiple times concurrently or sequentially.
+   * Note: manual calls to `close()` never call `process.exit()`.
+   * @param {string} [reason='manual']
+   * @returns {Promise<void>}
+   */
+  async close(reason = 'manual') {
+    if (this.isClosed) {
+      return;
+    }
+
+    if (this._shutdownPromise) {
+      return this._shutdownPromise;
+    }
+
+    this._shutdownPromise = (async () => {
+      this.isShuttingDown = true;
+      const isForce = this.options.mode === 'force';
+      const modeLabel = isForce ? 'force' : 'graceful';
+
+      this._log('info', `Starting ${modeLabel} shutdown (reason: ${reason})`);
+
+      // 1. Close HTTP server adapters
+      if (this._adapters.length > 0) {
+        this._log('info', 'Closing HTTP server');
+
+        for (const adapter of this._adapters) {
+          if (isForce) {
+            // Force mode: immediately close listener & force terminate connections
+            try {
+              if (typeof adapter.forceClose === 'function') {
+                adapter.forceClose();
+              }
+              await adapter.close();
+            } catch (err) {
+              this._log('error', 'Error force closing adapter:', err);
+            }
+          } else {
+            // Graceful mode: close idle connections, close server, and force close on timeout
+            try {
+              if (typeof adapter.closeIdleConnections === 'function') {
+                adapter.closeIdleConnections();
+              }
+            } catch (e) {}
+
+            let timer = null;
+            let timedOut = false;
+
+            const closePromise = adapter.close();
+
+            if (this.options.timeout > 0) {
+              const timeoutPromise = new Promise((resolve) => {
+                timer = setTimeout(() => {
+                  timedOut = true;
+                  this._log('warn', `Graceful shutdown timed out after ${this.options.timeout}ms`);
+                  this._log('info', 'Force closing active connections');
+                  try {
+                    if (typeof adapter.forceClose === 'function') {
+                      adapter.forceClose();
+                    }
+                  } catch (err) {
+                    this._log('error', 'Error force closing connections after timeout:', err);
+                  }
+                  resolve();
+                }, this.options.timeout);
+
+                if (typeof timer.unref === 'function') {
+                  timer.unref();
+                }
+              });
+
+              await Promise.race([closePromise, timeoutPromise]);
+            } else {
+              await closePromise;
+            }
+
+            if (timer) {
+              clearTimeout(timer);
+            }
+
+            // Ensure closePromise has resolved
+            await closePromise.catch(() => {});
+          }
+        }
+      }
+
+      // 2. Run application shutdown hooks (app.onShutdown)
+      if (this._hooks.length > 0) {
+        this._log('info', `Running ${this._hooks.length} shutdown hooks`);
+        for (const hook of this._hooks) {
+          try {
+            await hook();
+          } catch (err) {
+            this._log('error', 'Error in shutdown hook:', err);
+          }
+        }
+      }
+
+      // 3. Run plugin disposers in reverse registration order
+      if (this._disposers.length > 0) {
+        this._log('info', `Disposing ${this._disposers.length} plugins`);
+        // Reverse array to tear down dependencies in reverse order
+        const reverseDisposers = this._disposers.slice().reverse();
+        for (const { name, fn } of reverseDisposers) {
+          try {
+            await fn();
+          } catch (err) {
+            this._log('error', `Error in plugin disposer "${name}":`, err);
+          }
+        }
+      }
+
+      // 4. Detach signal hooks from process
+      this.disableShutdownHooks();
+
+      this.isClosed = true;
+      this._log('info', 'Shutdown completed');
+    })();
+
+    return this._shutdownPromise;
+  }
+}
+
+module.exports = {
+  ShutdownManager,
+};

package/core/ssr/index.js

@@ -0,0 +1,13 @@
+/**
+ * Webspresso SSR Core Module
+ * @module core/ssr
+ */
+
+'use strict';
+
+const { createHtmlStream, renderStream } = require('./stream');
+
+module.exports = {
+  createHtmlStream,
+  renderStream,
+};

package/core/ssr/stream.js

@@ -0,0 +1,174 @@
+/**
+ * Webspresso SSR Streaming & Chunked Transfer Engine
+ * @module core/ssr/stream
+ */
+
+'use strict';
+
+const { Readable } = require('stream');
+
+/**
+ * Creates a readable HTML stream for Nunjucks templates supporting deferred data slots
+ * @param {Object} options
+ * @param {import('nunjucks').Environment} options.env - Nunjucks environment
+ * @param {string} options.templatePath - Template name or path
+ * @param {Object} [options.context={}] - Render context
+ * @param {Object} [options.defer] - Map of deferred promises { [slotName]: Promise<any> | { promise: Promise<any>, template?: string } }
+ * @returns {Readable}
+ */
+function createHtmlStream(options = {}) {
+  const { env, templatePath, context = {}, defer = {} } = options;
+
+  if (!env) {
+    throw new Error('createHtmlStream requires a valid Nunjucks environment in options.env');
+  }
+
+  const stream = new Readable({
+    read() {}, // No-op, data is pushed asynchronously
+  });
+
+  (async () => {
+    try {
+      const deferredKeys = Object.keys(defer);
+
+      if (deferredKeys.length === 0) {
+        // Standard template streaming (render and stream)
+        const html = env.render(templatePath, context);
+        stream.push(html);
+        stream.push(null);
+        return;
+      }
+
+      // Initial shell rendering with deferred slot placeholders
+      const shellContext = {
+        ...context,
+        __streaming: true,
+      };
+
+      for (const key of deferredKeys) {
+        shellContext[key] = null;
+      }
+
+      let shellHtml = env.render(templatePath, shellContext);
+
+      // Check if template contains streaming slot markers, or split at first slot
+      // We push the initial shell chunk immediately to start browser TTFB & CSS download
+      stream.push(shellHtml);
+
+      // Resolve deferred promises in parallel
+      const resolutionPromises = deferredKeys.map(async (key) => {
+        const deferredItem = defer[key];
+        const promise = deferredItem && typeof deferredItem.then === 'function' ? deferredItem : deferredItem.promise;
+        const slotTemplate = deferredItem.template || null;
+
+        try {
+          const resolvedData = await promise;
+          let slotHtml = '';
+          if (slotTemplate) {
+            slotHtml = env.render(slotTemplate, { ...context, [key]: resolvedData });
+          } else {
+            slotHtml = typeof resolvedData === 'string' ? resolvedData : JSON.stringify(resolvedData);
+          }
+
+          // Push an out-of-order streaming chunk with inline replacement script or comment
+          const slotChunk = `
+<template data-stream-slot="${key}">${slotHtml}</template>
+<script>
+(function(){
+  var t = document.querySelector('template[data-stream-slot="${key}"]');
+  var target = document.querySelector('[data-stream-target="${key}"]') || document.getElementById('stream-target-${key}');
+  if (t && target) {
+    target.innerHTML = '';
+    target.appendChild(t.content.cloneNode(true));
+  }
+})();
+</script>`;
+          stream.push(slotChunk);
+        } catch (slotErr) {
+          const errorChunk = `
+<template data-stream-slot="${key}">
+  <!-- Slot Error (${key}): ${slotErr.message} -->
+</template>`;
+          stream.push(errorChunk);
+        }
+      });
+
+      await Promise.all(resolutionPromises);
+      stream.push(null); // End of stream
+    } catch (err) {
+      stream.destroy(err);
+    }
+  })();
+
+  return stream;
+}
+
+/**
+ * Render template directly to Express response as a chunked stream
+ * @param {import('express').Response} res - Express response object
+ * @param {string} templatePath - Template name
+ * @param {Object} [context={}] - Context data
+ * @param {Object} [options] - Additional options
+ * @param {import('nunjucks').Environment} options.env - Nunjucks environment
+ * @param {Object} [options.defer] - Deferred slot promises
+ * @param {number} [options.status=200] - HTTP status code
+ * @param {boolean} [options.flushImmediately=true] - Flush headers immediately
+ * @returns {Promise<void>}
+ */
+function renderStream(res, templatePath, context = {}, options = {}) {
+  return new Promise((resolve, reject) => {
+    const {
+      env,
+      defer = {},
+      status = 200,
+      flushImmediately = true,
+    } = options;
+
+    if (!env) {
+      return reject(new Error('renderStream requires a valid Nunjucks environment in options.env'));
+    }
+
+    if (res.headersSent) {
+      return reject(new Error('Cannot render stream: headers already sent'));
+    }
+
+    res.status(status);
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.setHeader('Transfer-Encoding', 'chunked');
+
+    if (flushImmediately && typeof res.flushHeaders === 'function') {
+      res.flushHeaders();
+    }
+
+    const stream = createHtmlStream({
+      env,
+      templatePath,
+      context,
+      defer,
+    });
+
+    stream.on('data', (chunk) => {
+      res.write(chunk);
+    });
+
+    stream.on('end', () => {
+      res.end();
+      resolve();
+    });
+
+    stream.on('error', (err) => {
+      if (!res.headersSent) {
+        res.status(500).send('Streaming Render Error');
+      } else {
+        res.write(`<!-- Streaming Error: ${err.message} -->`);
+        res.end();
+      }
+      reject(err);
+    });
+  });
+}
+
+module.exports = {
+  createHtmlStream,
+  renderStream,
+};

package/core/validation/index.js

@@ -0,0 +1,70 @@
+/**
+ * Webspresso Unified Validation Core
+ * Centralized Zod extensions, prototype pollution defense, and schema utilities
+ * @module core/validation
+ */
+
+const z = require('zod');
+const { extendZ, generateNanoid, zodNanoid } = require('../orm/utils/nanoid');
+
+/**
+ * Standard Zod instance extended with z.nanoid() for framework-wide validation.
+ */
+const zExtended = extendZ(z);
+
+/**
+ * Check if an object contains dangerous prototype pollution keys
+ * @param {*} obj
+ * @returns {boolean}
+ */
+function hasDangerousKeys(obj) {
+  if (obj === null || typeof obj !== 'object') {
+    return false;
+  }
+  if (Array.isArray(obj)) {
+    return obj.some(item => hasDangerousKeys(item));
+  }
+  for (const key of Object.keys(obj)) {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+      return true;
+    }
+    if (typeof obj[key] === 'object' && obj[key] !== null && hasDangerousKeys(obj[key])) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Sanitize input payload against prototype pollution
+ * @param {*} input
+ * @returns {*} Sanitized input
+ */
+function sanitizeInput(input) {
+  if (input === null || typeof input !== 'object') {
+    return input;
+  }
+  if (!hasDangerousKeys(input)) {
+    return input;
+  }
+  if (Array.isArray(input)) {
+    return input.map(item => sanitizeInput(item));
+  }
+  const clean = {};
+  for (const key of Object.keys(input)) {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+      continue;
+    }
+    clean[key] = sanitizeInput(input[key]);
+  }
+  return clean;
+}
+
+module.exports = {
+  z: zExtended,
+  extendZ,
+  generateNanoid,
+  zodNanoid,
+  hasDangerousKeys,
+  sanitizeInput,
+};