webspresso 0.0.90 → 0.0.91

package/core/realtime/reconnect-manager.js

@@ -0,0 +1,118 @@
+/**
+ * Realtime Reconnection & Exponential Backoff Manager
+ * @module core/realtime/reconnect-manager
+ */
+
+class ReconnectManager {
+  /**
+   * @param {Object} [options]
+   * @param {boolean} [options.enabled=true] - Whether automatic reconnection is enabled
+   * @param {number} [options.maxAttempts=10] - Maximum reconnection attempts before giving up
+   * @param {number} [options.baseDelay=500] - Initial reconnection delay in ms
+   * @param {number} [options.maxDelay=30000] - Maximum reconnection delay in ms
+   * @param {number} [options.factor=2] - Exponential growth factor
+   * @param {boolean} [options.jitter=true] - Whether to apply randomized jitter
+   */
+  constructor(options = {}) {
+    this.enabled = options.enabled !== false;
+    this.maxAttempts = options.maxAttempts ?? 10;
+    this.baseDelay = options.baseDelay ?? 500;
+    this.maxDelay = options.maxDelay ?? 30000;
+    this.factor = options.factor ?? 2;
+    this.jitter = options.jitter !== false;
+
+    this.attempts = 0;
+    /** @type {ReturnType<typeof setTimeout> | null} */
+    this._timer = null;
+    this._isReconnecting = false;
+    this._isAborted = false;
+  }
+
+  calculateDelay(attempt) {
+    const rawDelay = this.baseDelay * Math.pow(this.factor, attempt);
+    const capped = Math.min(rawDelay, this.maxDelay);
+
+    if (!this.jitter) {
+      return Math.round(capped);
+    }
+
+    const randomJitter = capped * 0.2 * (Math.random() * 2 - 1);
+    return Math.max(0, Math.round(capped + randomJitter));
+  }
+
+  canReconnect() {
+    if (!this.enabled || this._isAborted) return false;
+    if (this.maxAttempts > 0 && this.attempts >= this.maxAttempts) {
+      return false;
+    }
+    return true;
+  }
+
+  isReconnecting() {
+    return this._isReconnecting || this._timer !== null;
+  }
+
+  schedule(reconnectFn, onAttempt) {
+    if (!this.canReconnect()) {
+      return false;
+    }
+
+    if (this.isReconnecting()) {
+      return false;
+    }
+
+    const currentAttempt = this.attempts + 1;
+    const delay = this.calculateDelay(this.attempts);
+    this.attempts = currentAttempt;
+
+    if (typeof onAttempt === 'function') {
+      try {
+        onAttempt({ attempt: currentAttempt, delay, maxAttempts: this.maxAttempts });
+      } catch (e) {
+        console.error('[realtime] Error in onAttempt callback:', e);
+      }
+    }
+
+    this._timer = setTimeout(async () => {
+      this._timer = null;
+      if (this._isAborted) return;
+
+      this._isReconnecting = true;
+      try {
+        await reconnectFn();
+        this.reset();
+      } catch (err) {
+        this._isReconnecting = false;
+        if (this._isAborted) return;
+
+        if (this.canReconnect()) {
+          this.schedule(reconnectFn, onAttempt);
+        }
+      } finally {
+        this._isReconnecting = false;
+      }
+    }, delay);
+
+    if (this._timer && typeof this._timer.unref === 'function') {
+      this._timer.unref();
+    }
+
+    return true;
+  }
+
+  reset() {
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+    this.attempts = 0;
+    this._isReconnecting = false;
+  }
+
+  cancel() {
+    this._isAborted = true;
+    this.reset();
+  }
+}
+
+module.exports = { ReconnectManager };

package/core/realtime/registry.js

@@ -0,0 +1,243 @@
+/**
+ * Realtime Subscription Registry & Subscription Handle
+ * @module core/realtime/registry
+ */
+
+const { RealtimeError } = require('./errors');
+
+/**
+ * Generate a deterministic composite key for a subscription from identifier and params
+ * 
+ * @param {string} identifier
+ * @param {Object} [params={}]
+ * @returns {string}
+ */
+function createSubscriptionKey(identifier, params = {}) {
+  if (!identifier || typeof identifier !== 'string') {
+    throw new RealtimeError('INVALID_ARGUMENT', 'Subscription identifier must be a non-empty string');
+  }
+
+  let serializedParams = '';
+  if (params && typeof params === 'object' && Object.keys(params).length > 0) {
+    const sortedKeys = Object.keys(params).sort();
+    const sortedObj = {};
+    for (const key of sortedKeys) {
+      sortedObj[key] = params[key];
+    }
+    serializedParams = JSON.stringify(sortedObj);
+  }
+
+  return `${identifier}::${serializedParams}`;
+}
+
+/**
+ * Realtime Subscription Handle
+ */
+class RealtimeSubscription {
+  /**
+   * @param {Object} options
+   * @param {string} options.key - Unique subscription key
+   * @param {string} options.identifier - Topic/Channel identifier (e.g. "project:123")
+   * @param {Object} [options.params={}] - Parameters passed to subscription
+   * @param {Object} [options.callbacks={}] - Callbacks { connected, disconnected, rejected, received }
+   * @param {Function} options.onUnsubscribe - Internal unsubscribe callback
+   * @param {Function} options.onSend - Internal send handler
+   * @param {Function} options.onPerform - Internal perform handler
+   */
+  constructor({ key, identifier, params = {}, callbacks = {}, onUnsubscribe, onSend, onPerform }) {
+    this.key = key;
+    this.identifier = identifier;
+    this.params = params;
+    this.callbacks = {
+      connected: typeof callbacks.connected === 'function' ? callbacks.connected : null,
+      disconnected: typeof callbacks.disconnected === 'function' ? callbacks.disconnected : null,
+      rejected: typeof callbacks.rejected === 'function' ? callbacks.rejected : null,
+      received: typeof callbacks.received === 'function' ? callbacks.received : null,
+    };
+    this._onUnsubscribe = onUnsubscribe;
+    this._onSend = onSend;
+    this._onPerform = onPerform;
+    this._isUnsubscribed = false;
+    this._adapterSub = null;
+  }
+
+  /**
+   * Send data to this subscription
+   * @param {unknown} data
+   */
+  send(data) {
+    if (this._isUnsubscribed) {
+      throw new RealtimeError('SUBSCRIPTION_REJECTED', 'Cannot send data on an unsubscribed channel');
+    }
+    if (typeof this._onSend === 'function') {
+      this._onSend(this, data);
+    }
+  }
+
+  /**
+   * Perform an action on this subscription
+   * @param {string} action
+   * @param {unknown} [data]
+   */
+  perform(action, data) {
+    if (this._isUnsubscribed) {
+      throw new RealtimeError('SUBSCRIPTION_REJECTED', 'Cannot perform action on an unsubscribed channel');
+    }
+    if (typeof this._onPerform === 'function') {
+      this._onPerform(this, action, data);
+    }
+  }
+
+  /**
+   * Unsubscribe from this channel
+   */
+  unsubscribe() {
+    if (this._isUnsubscribed) return;
+    this._isUnsubscribed = true;
+    if (typeof this._onUnsubscribe === 'function') {
+      this._onUnsubscribe(this);
+    }
+  }
+
+  notifyReceived(data) {
+    if (this._isUnsubscribed) return;
+    if (this.callbacks.received) {
+      try {
+        this.callbacks.received(data);
+      } catch (err) {
+        console.error(`[realtime] Error in received callback for "${this.identifier}":`, err);
+      }
+    }
+  }
+
+  notifyConnected() {
+    if (this._isUnsubscribed) return;
+    if (this.callbacks.connected) {
+      try {
+        this.callbacks.connected();
+      } catch (err) {
+        console.error(`[realtime] Error in connected callback for "${this.identifier}":`, err);
+      }
+    }
+  }
+
+  notifyDisconnected() {
+    if (this._isUnsubscribed) return;
+    if (this.callbacks.disconnected) {
+      try {
+        this.callbacks.disconnected();
+      } catch (err) {
+        console.error(`[realtime] Error in disconnected callback for "${this.identifier}":`, err);
+      }
+    }
+  }
+
+  notifyRejected(error) {
+    if (this._isUnsubscribed) return;
+    if (this.callbacks.rejected) {
+      try {
+        this.callbacks.rejected(error);
+      } catch (err) {
+        console.error(`[realtime] Error in rejected callback for "${this.identifier}":`, err);
+      }
+    }
+  }
+}
+
+/**
+ * Subscription Registry
+ */
+class SubscriptionRegistry {
+  constructor() {
+    /** @type {Map<string, RealtimeSubscription>} */
+    this.subscriptions = new Map();
+  }
+
+  has(key) {
+    return this.subscriptions.has(key);
+  }
+
+  get(key) {
+    return this.subscriptions.get(key);
+  }
+
+  register({ identifier, params = {}, callbacks = {}, onSend, onPerform, onAdapterSubscribe, onAdapterUnsubscribe }) {
+    const key = createSubscriptionKey(identifier, params);
+
+    // If already registered and active, return existing subscription
+    if (this.subscriptions.has(key)) {
+      const existing = this.subscriptions.get(key);
+      if (!existing._isUnsubscribed) {
+        if (callbacks.received) existing.callbacks.received = callbacks.received;
+        if (callbacks.connected) existing.callbacks.connected = callbacks.connected;
+        if (callbacks.disconnected) existing.callbacks.disconnected = callbacks.disconnected;
+        if (callbacks.rejected) existing.callbacks.rejected = callbacks.rejected;
+        return existing;
+      }
+    }
+
+    const subscription = new RealtimeSubscription({
+      key,
+      identifier,
+      params,
+      callbacks,
+      onUnsubscribe: (sub) => {
+        this.subscriptions.delete(key);
+        if (typeof onAdapterUnsubscribe === 'function') {
+          onAdapterUnsubscribe(sub);
+        }
+      },
+      onSend,
+      onPerform,
+    });
+
+    this.subscriptions.set(key, subscription);
+
+    if (typeof onAdapterSubscribe === 'function') {
+      subscription._adapterSub = onAdapterSubscribe(subscription);
+    }
+
+    return subscription;
+  }
+
+  restoreAll(onAdapterSubscribe) {
+    if (typeof onAdapterSubscribe !== 'function') return;
+
+    for (const [key, sub] of this.subscriptions.entries()) {
+      if (!sub._isUnsubscribed) {
+        try {
+          sub._adapterSub = onAdapterSubscribe(sub);
+        } catch (err) {
+          console.error(`[realtime] Failed to restore subscription "${sub.identifier}":`, err);
+        }
+      } else {
+        this.subscriptions.delete(key);
+      }
+    }
+  }
+
+  notifyAllDisconnected() {
+    for (const sub of this.subscriptions.values()) {
+      if (!sub._isUnsubscribed) {
+        sub.notifyDisconnected();
+      }
+    }
+  }
+
+  clear() {
+    for (const sub of this.subscriptions.values()) {
+      sub.unsubscribe();
+    }
+    this.subscriptions.clear();
+  }
+
+  getAll() {
+    return Array.from(this.subscriptions.values()).filter((s) => !s._isUnsubscribed);
+  }
+}
+
+module.exports = {
+  createSubscriptionKey,
+  RealtimeSubscription,
+  SubscriptionRegistry,
+};

package/core/shutdown/http-adapter.js

@@ -0,0 +1,134 @@
+/**
+ * Node.js HTTP Server Adapter
+ * Provides server-level connection tracking, graceful closing, and forced termination
+ * @module core/shutdown/http-adapter
+ */
+
+class NodeHttpAdapter {
+  /**
+   * @param {import('http').Server|import('https').Server} server
+   */
+  constructor(server) {
+    if (!server) {
+      throw new Error('NodeHttpAdapter requires an HTTP server instance');
+    }
+    this.server = server;
+    /** @type {Set<import('net').Socket>} */
+    this.sockets = new Set();
+    this._closed = false;
+
+    this._onConnection = this._onConnection.bind(this);
+    this._onSecureConnection = this._onSecureConnection.bind(this);
+
+    this._attachSocketListeners();
+  }
+
+  _attachSocketListeners() {
+    this.server.on('connection', this._onConnection);
+    this.server.on('secureConnection', this._onSecureConnection);
+  }
+
+  _trackSocket(socket) {
+    if (!socket || this.sockets.has(socket)) return;
+    this.sockets.add(socket);
+
+    const cleanup = () => {
+      this.sockets.delete(socket);
+      socket.removeListener('close', cleanup);
+      socket.removeListener('error', cleanup);
+    };
+
+    socket.once('close', cleanup);
+    socket.once('error', cleanup);
+  }
+
+  _onConnection(socket) {
+    this._trackSocket(socket);
+  }
+
+  _onSecureConnection(socket) {
+    this._trackSocket(socket);
+  }
+
+  /**
+   * Check if the server is currently listening
+   * @returns {boolean}
+   */
+  get isListening() {
+    return Boolean(this.server && this.server.listening);
+  }
+
+  /**
+   * Stop accepting new connections and gracefully close existing connections
+   * @returns {Promise<void>}
+   */
+  close() {
+    return new Promise((resolve) => {
+      if (!this.server || !this.server.listening) {
+        this._closed = true;
+        return resolve();
+      }
+
+      this.closeIdleConnections();
+
+      this.server.close(() => {
+        this._closed = true;
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Close idle keep-alive connections if supported by Node.js
+   */
+  closeIdleConnections() {
+    if (this.server && typeof this.server.closeIdleConnections === 'function') {
+      try {
+        this.server.closeIdleConnections();
+      } catch {
+        // Ignore errors during idle closing
+      }
+    }
+  }
+
+  /**
+   * Immediately terminate all active connections
+   */
+  forceClose() {
+    // 1. Try Node.js native closeAllConnections (Node 18.2+)
+    if (this.server && typeof this.server.closeAllConnections === 'function') {
+      try {
+        this.server.closeAllConnections();
+      } catch {
+        // Fall back to manual socket destruction below
+      }
+    }
+
+    // 2. Destroy all tracked sockets with an explicit error to notify clients
+    for (const socket of this.sockets) {
+      try {
+        if (!socket.destroyed) {
+          socket.destroy(new Error('Connection closed by server shutdown'));
+        }
+      } catch {
+        // Ignore socket destroy errors
+      }
+    }
+    this.sockets.clear();
+  }
+
+  /**
+   * Detach all listeners from the server
+   */
+  destroy() {
+    if (this.server) {
+      this.server.removeListener('connection', this._onConnection);
+      this.server.removeListener('secureConnection', this._onSecureConnection);
+    }
+    this.sockets.clear();
+  }
+}
+
+module.exports = {
+  NodeHttpAdapter,
+};

package/core/shutdown/index.js

@@ -0,0 +1,12 @@
+/**
+ * Webspresso Shutdown & Lifecycle Management
+ * @module core/shutdown
+ */
+
+const { ShutdownManager } = require('./shutdown-manager');
+const { NodeHttpAdapter } = require('./http-adapter');
+
+module.exports = {
+  ShutdownManager,
+  NodeHttpAdapter,
+};