webspresso 0.0.90 → 0.0.91

package/core/realtime/core.js

@@ -0,0 +1,359 @@
+/**
+ * Realtime Core Client
+ * @module core/realtime/core
+ */
+
+const { EventEmitter } = require('./emitter');
+const { AuthManager } = require('./auth-manager');
+const { SubscriptionRegistry } = require('./registry');
+const { ReconnectManager } = require('./reconnect-manager');
+const { RealtimeError, normalizeRealtimeError } = require('./errors');
+
+const DEFAULT_CAPABILITIES = Object.freeze({
+  send: true,
+  perform: true,
+  multiplexing: true,
+  serverEvents: true,
+  binary: false,
+});
+
+/**
+ * Check whether the current execution context is in a browser environment
+ * @returns {boolean}
+ */
+function isBrowserEnvironment() {
+  return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+
+class RealtimeClient {
+  /**
+   * @param {Object} options
+   * @param {Object} options.adapter - Realtime transport adapter (e.g. websocket, sse, socketIo)
+   * @param {Object|boolean} [options.auth=false] - Auth strategy configuration
+   * @param {boolean} [options.autoConnect=true] - Auto-connect when browser is ready
+   * @param {Object} [options.reconnect] - Reconnection options
+   * @param {boolean} [options.isBrowser] - Force browser environment flag for testing
+   */
+  constructor(options = {}) {
+    if (!options.adapter || typeof options.adapter !== 'object') {
+      throw new RealtimeError('INVALID_ARGUMENT', 'RealtimeClient requires a valid adapter');
+    }
+
+    this.options = options;
+    this.adapter = options.adapter;
+    this.auth = new AuthManager(options.auth);
+    this.registry = new SubscriptionRegistry();
+    this.reconnectManager = new ReconnectManager(options.reconnect);
+    this.emitter = new EventEmitter();
+
+    this._autoConnect = options.autoConnect !== false;
+    this._isBrowserOverride = typeof options.isBrowser === 'boolean' ? options.isBrowser : null;
+    this._isConnecting = false;
+    this._isDestroyed = false;
+    this._hasConnectedBefore = false;
+
+    // Wire up adapter low-level events
+    this._wireAdapterEvents();
+
+    // Auto-connect if in browser environment
+    if (this._autoConnect && this.isBrowser()) {
+      Promise.resolve().then(() => {
+        if (!this._isDestroyed && !this.isConnected()) {
+          this.connect().catch(() => {});
+        }
+      });
+    }
+  }
+
+  isBrowser() {
+    if (this._isBrowserOverride !== null) {
+      return this._isBrowserOverride;
+    }
+    return isBrowserEnvironment();
+  }
+
+  get capabilities() {
+    if (this.adapter && this.adapter.capabilities && typeof this.adapter.capabilities === 'object') {
+      return { ...DEFAULT_CAPABILITIES, ...this.adapter.capabilities };
+    }
+    return { ...DEFAULT_CAPABILITIES };
+  }
+
+  isConnected() {
+    if (this._isDestroyed) return false;
+    if (this.adapter && typeof this.adapter.isConnected === 'function') {
+      return this.adapter.isConnected();
+    }
+    return false;
+  }
+
+  on(event, handler) {
+    return this.emitter.on(event, handler);
+  }
+
+  once(event, handler) {
+    return this.emitter.once(event, handler);
+  }
+
+  off(event, handler) {
+    this.emitter.off(event, handler);
+  }
+
+  async connect(overrideAuth = null) {
+    if (this._isDestroyed) {
+      throw new RealtimeError('DESTROYED', 'Cannot connect on a destroyed Realtime instance');
+    }
+
+    // SSR Guard: Never open network connections during server-side rendering
+    if (!this.isBrowser()) {
+      return;
+    }
+
+    if (this.isConnected() || this._isConnecting) {
+      return;
+    }
+
+    this._isConnecting = true;
+
+    try {
+      let authMetadata = overrideAuth;
+      if (!authMetadata) {
+        authMetadata = await this.auth.resolveAuthMetadata();
+      }
+
+      const connectionContext = {
+        auth: authMetadata,
+        client: this,
+      };
+
+      await this.adapter.connect(connectionContext);
+
+      this._isConnecting = false;
+      const isReconnection = this._hasConnectedBefore;
+      this._hasConnectedBefore = true;
+
+      this.reconnectManager.reset();
+
+      this.registry.restoreAll((sub) => {
+        return this._adapterSubscribe(sub);
+      });
+
+      if (isReconnection) {
+        this.emitter.emit('reconnected');
+      }
+      this.emitter.emit('connected');
+    } catch (err) {
+      this._isConnecting = false;
+      const error = normalizeRealtimeError(err, 'CONNECTION_FAILED', 'Realtime connection failed');
+
+      if (error.code === 'UNAUTHORIZED') {
+        this.auth.handleUnauthorized(error);
+        this.emitter.emit('unauthorized', error);
+      }
+
+      this.emitter.emit('error', error);
+      throw error;
+    }
+  }
+
+  disconnect() {
+    if (this._isDestroyed) return;
+
+    this.reconnectManager.reset();
+
+    if (this.adapter && typeof this.adapter.disconnect === 'function') {
+      try {
+        this.adapter.disconnect();
+      } catch (err) {
+        console.error('[realtime] Error during adapter disconnect:', err);
+      }
+    }
+
+    this.registry.notifyAllDisconnected();
+    this.emitter.emit('disconnected');
+  }
+
+  async reconnect() {
+    if (this._isDestroyed) {
+      throw new RealtimeError('DESTROYED', 'Cannot reconnect on a destroyed Realtime instance');
+    }
+
+    this.disconnect();
+    return this.connect();
+  }
+
+  async reauthenticate() {
+    if (this._isDestroyed) {
+      throw new RealtimeError('DESTROYED', 'Cannot reauthenticate on a destroyed Realtime instance');
+    }
+
+    if (!this.isBrowser()) return;
+
+    try {
+      this.disconnect();
+      const newAuth = await this.auth.refreshToken();
+      await this.connect(newAuth);
+    } catch (err) {
+      const error = normalizeRealtimeError(err, 'TOKEN_REFRESH_FAILED', 'Reauthentication failed');
+      this.emitter.emit('error', error);
+      throw error;
+    }
+  }
+
+  subscribe(identifier, params = {}, callbacks = {}) {
+    if (this._isDestroyed) {
+      throw new RealtimeError('DESTROYED', 'Cannot subscribe on a destroyed Realtime instance');
+    }
+
+    return this.registry.register({
+      identifier,
+      params,
+      callbacks,
+      onSend: (sub, data) => this._handleSubscriptionSend(sub, data),
+      onPerform: (sub, action, data) => this._handleSubscriptionPerform(sub, action, data),
+      onAdapterSubscribe: (sub) => {
+        if (this.isConnected()) {
+          return this._adapterSubscribe(sub);
+        }
+        return null;
+      },
+      onAdapterUnsubscribe: (sub) => {
+        if (this.adapter && typeof this.adapter.unsubscribe === 'function') {
+          try {
+            this.adapter.unsubscribe(sub.identifier, sub.params, sub);
+          } catch (err) {
+            console.error(`[realtime] Error unsubscribing "${sub.identifier}":`, err);
+          }
+        }
+      },
+    });
+  }
+
+  _adapterSubscribe(sub) {
+    if (!this.adapter || typeof this.adapter.subscribe !== 'function') {
+      return null;
+    }
+
+    const adapterCallbacks = {
+      connected: () => sub.notifyConnected(),
+      disconnected: () => sub.notifyDisconnected(),
+      rejected: (err) => {
+        const error = normalizeRealtimeError(err, 'SUBSCRIPTION_REJECTED', `Subscription "${sub.identifier}" rejected`);
+        sub.notifyRejected(error);
+        this.emitter.emit('error', error);
+      },
+      received: (data) => sub.notifyReceived(data),
+    };
+
+    try {
+      return this.adapter.subscribe(sub.identifier, sub.params, adapterCallbacks);
+    } catch (err) {
+      const error = normalizeRealtimeError(err, 'SUBSCRIPTION_REJECTED', `Failed to subscribe to "${sub.identifier}"`);
+      sub.notifyRejected(error);
+      this.emitter.emit('error', error);
+      return null;
+    }
+  }
+
+  _handleSubscriptionSend(sub, data) {
+    if (!this.capabilities.send) {
+      throw new RealtimeError('UNSUPPORTED_CAPABILITY', 'Active realtime adapter does not support send()');
+    }
+
+    if (this.adapter && typeof this.adapter.send === 'function') {
+      this.adapter.send(sub.identifier, data, sub);
+    } else if (sub._adapterSub && typeof sub._adapterSub.send === 'function') {
+      sub._adapterSub.send(data);
+    } else {
+      throw new RealtimeError('UNSUPPORTED_CAPABILITY', 'Adapter does not implement send');
+    }
+  }
+
+  _handleSubscriptionPerform(sub, action, data) {
+    if (this.capabilities.perform) {
+      if (this.adapter && typeof this.adapter.perform === 'function') {
+        this.adapter.perform(sub.identifier, action, data, sub);
+        return;
+      }
+
+      if (sub._adapterSub && typeof sub._adapterSub.perform === 'function') {
+        sub._adapterSub.perform(action, data);
+        return;
+      }
+    }
+
+    // If perform is unsupported but send is available, map to generic action command
+    if (this.capabilities.send) {
+      this._handleSubscriptionSend(sub, { action, data });
+      return;
+    }
+
+    throw new RealtimeError('UNSUPPORTED_CAPABILITY', 'Active realtime adapter does not support perform() or send()');
+  }
+
+  _wireAdapterEvents() {
+    if (!this.adapter || typeof this.adapter.on !== 'function') return;
+
+    this.adapter.on('disconnected', (reason) => {
+      this.registry.notifyAllDisconnected();
+      this.emitter.emit('disconnected', reason);
+
+      if (!this._isDestroyed && this.reconnectManager.canReconnect()) {
+        this.reconnectManager.schedule(
+          async () => {
+            await this.connect();
+          },
+          ({ attempt, delay, maxAttempts }) => {
+            this.emitter.emit('reconnecting', { attempt, delay, maxAttempts });
+          }
+        );
+      }
+    });
+
+    this.adapter.on('unauthorized', (err) => {
+      const error = normalizeRealtimeError(err, 'UNAUTHORIZED', 'Realtime connection unauthorized');
+      this.auth.handleUnauthorized(error);
+      this.emitter.emit('unauthorized', error);
+    });
+
+    this.adapter.on('error', (err) => {
+      const error = normalizeRealtimeError(err, 'CONNECTION_FAILED', 'Adapter error');
+      this.emitter.emit('error', error);
+    });
+  }
+
+  browserReady() {
+    if (this._isDestroyed) return;
+    if (this._autoConnect && !this.isConnected() && !this._isConnecting) {
+      this.connect().catch(() => {});
+    }
+  }
+
+  destroy() {
+    if (this._isDestroyed) return;
+    this._isDestroyed = true;
+
+    this.reconnectManager.cancel();
+    this.registry.clear();
+
+    if (this.adapter) {
+      try {
+        if (typeof this.adapter.disconnect === 'function') {
+          this.adapter.disconnect();
+        }
+        if (typeof this.adapter.destroy === 'function') {
+          this.adapter.destroy();
+        }
+      } catch (err) {
+        console.error('[realtime] Error destroying adapter:', err);
+      }
+    }
+
+    this.emitter.clear();
+  }
+}
+
+module.exports = {
+  RealtimeClient,
+  DEFAULT_CAPABILITIES,
+};

package/core/realtime/emitter.js

@@ -0,0 +1,98 @@
+/**
+ * Lightweight, zero-dependency Event Emitter
+ * @module core/realtime/emitter
+ */
+
+class EventEmitter {
+  constructor() {
+    /** @type {Map<string, Set<Function>>} */
+    this._listeners = new Map();
+  }
+
+  /**
+   * Subscribe to an event
+   * 
+   * @param {string} event
+   * @param {Function} handler
+   * @returns {() => void} Unsubscribe function
+   */
+  on(event, handler) {
+    if (typeof handler !== 'function') {
+      throw new TypeError(`Event handler for "${event}" must be a function`);
+    }
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, new Set());
+    }
+    this._listeners.get(event).add(handler);
+
+    return () => this.off(event, handler);
+  }
+
+  /**
+   * Subscribe to an event once
+   * 
+   * @param {string} event
+   * @param {Function} handler
+   * @returns {() => void} Unsubscribe function
+   */
+  once(event, handler) {
+    if (typeof handler !== 'function') {
+      throw new TypeError(`Event handler for "${event}" must be a function`);
+    }
+    const wrapper = (...args) => {
+      this.off(event, wrapper);
+      handler(...args);
+    };
+    return this.on(event, wrapper);
+  }
+
+  /**
+   * Unsubscribe from an event
+   * 
+   * @param {string} event
+   * @param {Function} handler
+   */
+  off(event, handler) {
+    const set = this._listeners.get(event);
+    if (set) {
+      set.delete(handler);
+      if (set.size === 0) {
+        this._listeners.delete(event);
+      }
+    }
+  }
+
+  /**
+   * Emit an event to all subscribers
+   * 
+   * @param {string} event
+   * @param  {...any} args
+   */
+  emit(event, ...args) {
+    const set = this._listeners.get(event);
+    if (!set || set.size === 0) return;
+
+    // Iterate over shallow copy to allow listeners to modify set during execution
+    const handlers = Array.from(set);
+    for (const handler of handlers) {
+      try {
+        handler(...args);
+      } catch (err) {
+        if (event !== 'error' && this._listeners.has('error')) {
+          this.emit('error', err);
+        } else {
+          console.error(`[realtime] Error in event listener for "${event}":`, err);
+        }
+      }
+    }
+  }
+
+  /**
+   * Clear all registered listeners
+   */
+  clear() {
+    this._listeners.clear();
+  }
+}
+
+module.exports = { EventEmitter };

package/core/realtime/errors.js

@@ -0,0 +1,71 @@
+/**
+ * Realtime error classes & normalization utilities
+ * @module core/realtime/errors
+ */
+
+/**
+ * Strips tokens, secrets, and sensitive query parameters from strings/URLs
+ * 
+ * @param {string} input
+ * @returns {string}
+ */
+function sanitizeErrorMessage(input) {
+  if (typeof input !== 'string') return '';
+  return input
+    .replace(/([?&](?:token|access_token|secret|key|auth|password|apiKey)=)[^&#\s]+/gi, '$1***')
+    .replace(/(Bearer\s+)[A-Za-z0-9-_=.]+/gi, '$1***')
+    .replace(/(Basic\s+)[A-Za-z0-9-_=.]+/gi, '$1***');
+}
+
+/**
+ * Standard Realtime Error
+ */
+class RealtimeError extends Error {
+  /**
+   * @param {string} code - Standardized error code
+   * @param {string} message - Human-readable error description (sanitized)
+   * @param {Error|unknown} [cause] - Original root cause error
+   */
+  constructor(code, message, cause = null) {
+    const sanitizedMsg = sanitizeErrorMessage(message);
+    super(sanitizedMsg);
+    this.name = 'RealtimeError';
+    this.code = code;
+    if (cause) {
+      this.cause = cause instanceof Error ? cause : new Error(sanitizeErrorMessage(String(cause)));
+    }
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      cause: this.cause ? this.cause.message || String(this.cause) : null,
+    };
+  }
+}
+
+/**
+ * Normalize any error into a standard RealtimeError
+ * 
+ * @param {unknown} err
+ * @param {string} [defaultCode='REALTIME_ERROR']
+ * @param {string} [defaultMessage='An unexpected realtime error occurred']
+ * @returns {RealtimeError}
+ */
+function normalizeRealtimeError(err, defaultCode = 'REALTIME_ERROR', defaultMessage = 'An unexpected realtime error occurred') {
+  if (err instanceof RealtimeError) {
+    return err;
+  }
+  if (err instanceof Error) {
+    const code = err.code && typeof err.code === 'string' ? err.code : defaultCode;
+    return new RealtimeError(code, err.message || defaultMessage, err);
+  }
+  return new RealtimeError(defaultCode, typeof err === 'string' ? err : defaultMessage, err);
+}
+
+module.exports = {
+  RealtimeError,
+  normalizeRealtimeError,
+  sanitizeErrorMessage,
+};

package/core/realtime/index.js

@@ -0,0 +1,79 @@
+/**
+ * Webspresso Realtime Core
+ * @module core/realtime
+ */
+
+const { RealtimeClient, DEFAULT_CAPABILITIES } = require('./core');
+const { RealtimeSubscription, SubscriptionRegistry, createSubscriptionKey } = require('./registry');
+const { AuthManager } = require('./auth-manager');
+const { ReconnectManager } = require('./reconnect-manager');
+const { RealtimeError, normalizeRealtimeError, sanitizeErrorMessage } = require('./errors');
+const { EventEmitter } = require('./emitter');
+
+// Adapters
+const { createWebSocketAdapter, websocket, WebSocketAdapter, resolveWebSocketUrl } = require('./adapters/websocket');
+const { createSseAdapter, sse, SseAdapter, resolveSseUrl } = require('./adapters/sse');
+const { createSocketIoAdapter, socketIo, SocketIoAdapter } = require('./adapters/socket-io');
+const { createRedisAdapter, redis, RedisAdapter, InMemoryDistributedBus } = require('./adapters/redis');
+
+/**
+ * Factory to create a RealtimeClient instance
+ * 
+ * @param {Object} options
+ * @param {Object} options.adapter - Transport adapter (e.g. websocket, sse, socketIo, redis)
+ * @param {Object|boolean} [options.auth=false] - Auth strategy configuration
+ * @param {boolean} [options.autoConnect=true] - Auto-connect when browser is ready
+ * @param {Object} [options.reconnect] - Reconnection options
+ * @returns {RealtimeClient}
+ */
+function createRealtime(options = {}) {
+  return new RealtimeClient(options);
+}
+
+/**
+ * Universal realtime helper
+ * 
+ * @param {Object} options
+ * @returns {RealtimeClient}
+ */
+function realtime(options = {}) {
+  const client = createRealtime(options);
+  return client;
+}
+
+module.exports = {
+  createRealtime,
+  realtime,
+  RealtimeClient,
+  RealtimeSubscription,
+  SubscriptionRegistry,
+  createSubscriptionKey,
+  AuthManager,
+  ReconnectManager,
+  RealtimeError,
+  normalizeRealtimeError,
+  sanitizeErrorMessage,
+  EventEmitter,
+  DEFAULT_CAPABILITIES,
+
+  // Adapters
+  websocket,
+  createWebSocketAdapter,
+  WebSocketAdapter,
+  resolveWebSocketUrl,
+
+  sse,
+  createSseAdapter,
+  SseAdapter,
+  resolveSseUrl,
+
+  socketIo,
+  createSocketIoAdapter,
+  SocketIoAdapter,
+
+  redis,
+  createRedisAdapter,
+  RedisAdapter,
+  InMemoryDistributedBus,
+};
+