webspresso 0.0.90 → 0.0.91

package/core/realtime/adapters/sse.js

@@ -0,0 +1,210 @@
+/**
+ * Server-Sent Events (SSE) Adapter for Webspresso Realtime
+ * @module core/realtime/adapters/sse
+ */
+
+/**
+ * Resolve target SSE URL with auth query parameters
+ * 
+ * @param {string|Function} urlOption
+ * @param {Object} context
+ * @param {string} [queryParamName='token']
+ * @returns {Promise<string>}
+ */
+async function resolveSseUrl(urlOption, context, queryParamName = 'token') {
+  let resolved = '';
+  if (typeof urlOption === 'function') {
+    resolved = await urlOption(context);
+  } else if (typeof urlOption === 'string') {
+    resolved = urlOption;
+  } else {
+    throw new Error('SSE adapter requires a valid url string or async resolver function');
+  }
+
+  if (context.auth && context.auth.token) {
+    const separator = resolved.includes('?') ? '&' : '?';
+    const encodedToken = encodeURIComponent(context.auth.token);
+    resolved = `${resolved}${separator}${queryParamName}=${encodedToken}`;
+  }
+
+  return resolved;
+}
+
+class SseAdapter {
+  /**
+   * @param {Object} options
+   * @param {string|Function} options.url - SSE endpoint URL or async resolver
+   * @param {string} [options.queryParamName='token'] - Query parameter name for token
+   * @param {Function} [options.EventSource] - EventSource constructor injection
+   * @param {Object} [options.capabilities] - Custom capabilities override
+   */
+  constructor(options = {}) {
+    this.options = options;
+    this.capabilities = {
+      send: false,
+      perform: false,
+      multiplexing: true,
+      serverEvents: true,
+      binary: false,
+      ...(options.capabilities || {}),
+    };
+
+    this.EventSourceClass = options.EventSource || (typeof EventSource !== 'undefined' ? EventSource : null);
+    this.eventSource = null;
+    this._listeners = new Map();
+    this._subscriptions = new Map();
+    this._isOpen = false;
+  }
+
+  isConnected() {
+    return Boolean(this.eventSource && this._isOpen);
+  }
+
+  on(event, handler) {
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, new Set());
+    }
+    this._listeners.get(event).add(handler);
+    return () => {
+      const set = this._listeners.get(event);
+      if (set) set.delete(handler);
+    };
+  }
+
+  _emit(event, ...args) {
+    const set = this._listeners.get(event);
+    if (!set) return;
+    for (const handler of set) {
+      try {
+        handler(...args);
+      } catch (err) {
+        console.error(`[sse-adapter] Error in event listener for "${event}":`, err);
+      }
+    }
+  }
+
+  async connect(context) {
+    if (!this.EventSourceClass) {
+      throw new Error('EventSource implementation not found. Inject options.EventSource or run in a browser environment.');
+    }
+
+    const queryParamName = this.options.queryParamName || 'token';
+    const url = await resolveSseUrl(this.options.url, context, queryParamName);
+
+    return new Promise((resolve, reject) => {
+      let isSettled = false;
+
+      try {
+        this.eventSource = new this.EventSourceClass(url);
+      } catch (err) {
+        return reject(err);
+      }
+
+      this.eventSource.onopen = () => {
+        this._isOpen = true;
+        if (!isSettled) {
+          isSettled = true;
+          resolve();
+        }
+      };
+
+      this.eventSource.onerror = (err) => {
+        this._isOpen = false;
+        this._emit('disconnected', err);
+        if (!isSettled) {
+          isSettled = true;
+          reject(err || new Error('SSE connection failed'));
+        }
+      };
+
+      this.eventSource.onmessage = (event) => {
+        this._handleMessage(event.data);
+      };
+    });
+  }
+
+  _handleMessage(rawData) {
+    let data = rawData;
+    try {
+      data = JSON.parse(rawData);
+    } catch {
+      // Raw string
+    }
+
+    const identifier = data && typeof data === 'object' ? data.identifier : null;
+
+    if (identifier && this._subscriptions.has(identifier)) {
+      const subs = this._subscriptions.get(identifier);
+      for (const cb of subs) {
+        cb.received?.(data.data !== undefined ? data.data : data);
+      }
+      return;
+    }
+
+    for (const subs of this._subscriptions.values()) {
+      for (const cb of subs) {
+        cb.received?.(data);
+      }
+    }
+  }
+
+  subscribe(identifier, params, callbacks) {
+    if (!this._subscriptions.has(identifier)) {
+      this._subscriptions.set(identifier, new Set());
+    }
+
+    this._subscriptions.get(identifier).add(callbacks);
+    callbacks.connected?.();
+
+    return {
+      send: () => {
+        throw new Error('SSE adapter is unidirectional and does not support send()');
+      },
+      perform: () => {
+        throw new Error('SSE adapter is unidirectional and does not support perform()');
+      },
+      unsubscribe: () => this.unsubscribe(identifier, params, callbacks),
+    };
+  }
+
+  unsubscribe(identifier, params, callbacks) {
+    if (this._subscriptions.has(identifier)) {
+      const subs = this._subscriptions.get(identifier);
+      if (callbacks) {
+        subs.delete(callbacks);
+      }
+      if (subs.size === 0 || !callbacks) {
+        this._subscriptions.delete(identifier);
+      }
+    }
+  }
+
+  disconnect() {
+    this._isOpen = false;
+    if (this.eventSource) {
+      try {
+        this.eventSource.close();
+      } catch (err) {
+        // Closed
+      }
+      this.eventSource = null;
+    }
+  }
+
+  destroy() {
+    this.disconnect();
+    this._subscriptions.clear();
+    this._listeners.clear();
+  }
+}
+
+function createSseAdapter(options = {}) {
+  return new SseAdapter(options);
+}
+
+module.exports = {
+  createSseAdapter,
+  sse: createSseAdapter,
+  SseAdapter,
+  resolveSseUrl,
+};

package/core/realtime/adapters/websocket.js

@@ -0,0 +1,337 @@
+/**
+ * Generic WebSocket Adapter for Webspresso Realtime
+ * @module core/realtime/adapters/websocket
+ */
+
+/**
+ * Resolve target WebSocket URL with optional auth query parameters
+ * 
+ * @param {string|Function} urlOption
+ * @param {Object} context
+ * @param {string} [authTransport='query']
+ * @param {string} [queryParamName='token']
+ * @returns {Promise<string>}
+ */
+async function resolveWebSocketUrl(urlOption, context, authTransport = 'query', queryParamName = 'token') {
+  let resolved = '';
+  if (typeof urlOption === 'function') {
+    resolved = await urlOption(context);
+  } else if (typeof urlOption === 'string') {
+    resolved = urlOption;
+  } else {
+    throw new Error('WebSocket adapter requires a valid url string or async resolver function');
+  }
+
+  // Handle query parameter auth transport if token exists
+  if (authTransport === 'query' && context.auth && context.auth.token) {
+    const separator = resolved.includes('?') ? '&' : '?';
+    const encodedToken = encodeURIComponent(context.auth.token);
+    resolved = `${resolved}${separator}${queryParamName}=${encodedToken}`;
+  }
+
+  return resolved;
+}
+
+/**
+ * Default WebSocket message formatters
+ */
+const DEFAULT_MESSAGE_FORMATTERS = {
+  subscribe: ({ identifier, params }) => ({
+    type: 'subscribe',
+    identifier,
+    params,
+  }),
+  unsubscribe: ({ identifier, params }) => ({
+    type: 'unsubscribe',
+    identifier,
+    params,
+  }),
+  perform: ({ identifier, action, data }) => ({
+    type: 'perform',
+    identifier,
+    action,
+    data,
+  }),
+  send: ({ identifier, data }) => ({
+    type: 'message',
+    identifier,
+    data,
+  }),
+  auth: ({ token, metadata }) => ({
+    type: 'auth',
+    token,
+    ...metadata,
+  }),
+};
+
+class WebSocketAdapter {
+  /**
+   * @param {Object} options
+   * @param {string|Function} options.url - WebSocket URL or async function
+   * @param {string} [options.authTransport='query'] - 'query' | 'header' | 'protocol' | 'message'
+   * @param {string} [options.queryParamName='token'] - Query parameter name for token
+   * @param {string|string[]} [options.protocols] - Subprotocols
+   * @param {Function} [options.WebSocket] - WebSocket constructor injection
+   * @param {Object} [options.messages] - Message formatters
+   * @param {Object} [options.capabilities] - Custom capabilities
+   */
+  constructor(options = {}) {
+    this.options = options;
+    this.capabilities = {
+      send: true,
+      perform: true,
+      multiplexing: true,
+      serverEvents: true,
+      binary: true,
+      ...(options.capabilities || {}),
+    };
+
+    this.messages = {
+      ...DEFAULT_MESSAGE_FORMATTERS,
+      ...(options.messages || {}),
+    };
+
+    this.WebSocketClass = options.WebSocket || (typeof WebSocket !== 'undefined' ? WebSocket : null);
+    this.socket = null;
+    this._listeners = new Map();
+    this._activeSubscriptions = new Map();
+    this._isOpen = false;
+  }
+
+  isConnected() {
+    return Boolean(this.socket && this._isOpen);
+  }
+
+  on(event, handler) {
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, new Set());
+    }
+    this._listeners.get(event).add(handler);
+    return () => {
+      const set = this._listeners.get(event);
+      if (set) set.delete(handler);
+    };
+  }
+
+  _emit(event, ...args) {
+    const set = this._listeners.get(event);
+    if (!set) return;
+    for (const handler of set) {
+      try {
+        handler(...args);
+      } catch (err) {
+        console.error(`[websocket-adapter] Error in event listener for "${event}":`, err);
+      }
+    }
+  }
+
+  async connect(context) {
+    if (!this.WebSocketClass) {
+      throw new Error('WebSocket implementation not found. Inject options.WebSocket or run in a browser environment.');
+    }
+
+    const authTransport = this.options.authTransport || 'query';
+    const queryParamName = this.options.queryParamName || 'token';
+
+    const url = await resolveWebSocketUrl(this.options.url, context, authTransport, queryParamName);
+
+    let protocols = this.options.protocols;
+    if (authTransport === 'protocol' && context.auth && context.auth.token) {
+      const authProtocol = `token.${context.auth.token}`;
+      protocols = Array.isArray(protocols) ? [...protocols, authProtocol] : [authProtocol];
+    }
+
+    return new Promise((resolve, reject) => {
+      let isSettled = false;
+
+      try {
+        this.socket = protocols ? new this.WebSocketClass(url, protocols) : new this.WebSocketClass(url);
+      } catch (err) {
+        return reject(err);
+      }
+
+      this.socket.onopen = () => {
+        this._isOpen = true;
+        isSettled = true;
+
+        if (authTransport === 'message' && context.auth && context.auth.token) {
+          try {
+            const authMsg = this.messages.auth({
+              token: context.auth.token,
+              metadata: context.auth,
+            });
+            this.socket.send(typeof authMsg === 'string' ? authMsg : JSON.stringify(authMsg));
+          } catch (e) {
+            console.error('[websocket-adapter] Failed to send auth message:', e);
+          }
+        }
+
+        resolve();
+      };
+
+      this.socket.onclose = (event) => {
+        this._isOpen = false;
+        const code = event ? event.code : null;
+        const reason = event ? event.reason : '';
+
+        if (code === 4001 || code === 4003 || code === 4401 || (typeof reason === 'string' && reason.toLowerCase().includes('unauthorized'))) {
+          this._emit('unauthorized', new Error(reason || 'Unauthorized'));
+        }
+
+        this._emit('disconnected', { code, reason });
+
+        if (!isSettled) {
+          isSettled = true;
+          reject(new Error(`WebSocket connection closed before opening: ${code} ${reason}`));
+        }
+      };
+
+      this.socket.onerror = (err) => {
+        this._emit('error', err);
+        if (!isSettled) {
+          isSettled = true;
+          reject(err || new Error('WebSocket connection failed'));
+        }
+      };
+
+      this.socket.onmessage = (event) => {
+        this._handleMessage(event.data);
+      };
+    });
+  }
+
+  _handleMessage(rawData) {
+    let message = rawData;
+    if (typeof rawData === 'string') {
+      try {
+        message = JSON.parse(rawData);
+      } catch {
+        // Raw string message
+      }
+    }
+
+    if (!message || typeof message !== 'object') {
+      for (const subs of this._activeSubscriptions.values()) {
+        for (const cb of subs.values()) {
+          cb.received?.(message);
+        }
+      }
+      return;
+    }
+
+    const { identifier, type, data, error } = message;
+
+    if (type === 'unauthorized' || type === 'auth_error') {
+      this._emit('unauthorized', new Error(message.message || 'Unauthorized'));
+      return;
+    }
+
+    if (identifier && this._activeSubscriptions.has(identifier)) {
+      const subs = this._activeSubscriptions.get(identifier);
+      for (const cb of subs.values()) {
+        if (type === 'rejected') {
+          cb.rejected?.(error || new Error(message.message || 'Subscription rejected'));
+        } else if (type === 'subscribed' || type === 'connected') {
+          cb.connected?.();
+        } else {
+          cb.received?.(data !== undefined ? data : message);
+        }
+      }
+      return;
+    }
+
+    for (const subs of this._activeSubscriptions.values()) {
+      for (const cb of subs.values()) {
+        cb.received?.(message);
+      }
+    }
+  }
+
+  subscribe(identifier, params, callbacks) {
+    if (!this._activeSubscriptions.has(identifier)) {
+      this._activeSubscriptions.set(identifier, new Map());
+    }
+
+    const subId = Symbol('sub');
+    this._activeSubscriptions.get(identifier).set(subId, callbacks);
+
+    if (this.isConnected()) {
+      const msg = this.messages.subscribe({ identifier, params });
+      this._sendRaw(msg);
+      callbacks.connected?.();
+    }
+
+    return {
+      send: (data) => this.send(identifier, data),
+      perform: (action, data) => this.perform(identifier, action, data),
+      unsubscribe: () => this.unsubscribe(identifier, params, subId),
+    };
+  }
+
+  unsubscribe(identifier, params, subId) {
+    if (this._activeSubscriptions.has(identifier)) {
+      const subs = this._activeSubscriptions.get(identifier);
+      if (subId) {
+        subs.delete(subId);
+      }
+      if (subs.size === 0 || !subId) {
+        this._activeSubscriptions.delete(identifier);
+        if (this.isConnected()) {
+          const msg = this.messages.unsubscribe({ identifier, params });
+          this._sendRaw(msg);
+        }
+      }
+    }
+  }
+
+  send(identifier, data) {
+    const msg = this.messages.send({ identifier, data });
+    this._sendRaw(msg);
+  }
+
+  perform(identifier, action, data) {
+    const msg = this.messages.perform({ identifier, action, data });
+    this._sendRaw(msg);
+  }
+
+  _sendRaw(msg) {
+    if (!this.isConnected()) {
+      throw new Error('WebSocket is not connected');
+    }
+    const payload = typeof msg === 'string' ? msg : JSON.stringify(msg);
+    this.socket.send(payload);
+  }
+
+  disconnect() {
+    this._isOpen = false;
+    if (this.socket) {
+      try {
+        this.socket.onopen = null;
+        this.socket.onclose = null;
+        this.socket.onerror = null;
+        this.socket.onmessage = null;
+        this.socket.close();
+      } catch (err) {
+        // Socket close
+      }
+      this.socket = null;
+    }
+  }
+
+  destroy() {
+    this.disconnect();
+    this._activeSubscriptions.clear();
+    this._listeners.clear();
+  }
+}
+
+function createWebSocketAdapter(options = {}) {
+  return new WebSocketAdapter(options);
+}
+
+module.exports = {
+  createWebSocketAdapter,
+  websocket: createWebSocketAdapter,
+  WebSocketAdapter,
+  resolveWebSocketUrl,
+};

package/core/realtime/auth-manager.js

@@ -0,0 +1,140 @@
+/**
+ * Realtime Authentication Strategy Manager
+ * @module core/realtime/auth-manager
+ */
+
+const { RealtimeError } = require('./errors');
+
+class AuthManager {
+  /**
+   * @param {Object|boolean} [authConfig=false]
+   */
+  constructor(authConfig = false) {
+    this.config = authConfig;
+  }
+
+  /**
+   * Check if authentication is enabled
+   * @returns {boolean}
+   */
+  isEnabled() {
+    return Boolean(this.config && this.config !== false);
+  }
+
+  /**
+   * Get active auth strategy ('token' | 'cookie' | 'custom' | 'none')
+   * @returns {'token' | 'cookie' | 'custom' | 'none'}
+   */
+  getStrategy() {
+    if (!this.isEnabled()) return 'none';
+    return this.config.strategy || 'token';
+  }
+
+  /**
+   * Resolve framework-agnostic connection auth metadata before establishing connection
+   * 
+   * @returns {Promise<Object>} Metadata to pass to adapter
+   */
+  async resolveAuthMetadata() {
+    if (!this.isEnabled()) {
+      return { type: 'none' };
+    }
+
+    const strategy = this.getStrategy();
+
+    if (strategy === 'cookie') {
+      return { type: 'cookie' };
+    }
+
+    if (strategy === 'token') {
+      if (typeof this.config.getToken !== 'function') {
+        throw new RealtimeError(
+          'UNAUTHORIZED',
+          'Auth strategy "token" requires a getToken() function'
+        );
+      }
+      try {
+        const token = await this.config.getToken();
+        if (!token) {
+          throw new RealtimeError('UNAUTHORIZED', 'No authentication token provided by getToken()');
+        }
+        return {
+          type: 'token',
+          token,
+        };
+      } catch (err) {
+        if (err instanceof RealtimeError) throw err;
+        throw new RealtimeError('UNAUTHORIZED', 'Failed to retrieve authentication token', err);
+      }
+    }
+
+    if (strategy === 'custom') {
+      if (typeof this.config.resolve !== 'function') {
+        throw new RealtimeError(
+          'UNAUTHORIZED',
+          'Auth strategy "custom" requires a resolve() function'
+        );
+      }
+      try {
+        const metadata = await this.config.resolve();
+        return {
+          type: 'custom',
+          ...(metadata && typeof metadata === 'object' ? metadata : {}),
+        };
+      } catch (err) {
+        if (err instanceof RealtimeError) throw err;
+        throw new RealtimeError('UNAUTHORIZED', 'Custom auth resolution failed', err);
+      }
+    }
+
+    throw new RealtimeError('UNAUTHORIZED', `Unsupported auth strategy "${strategy}"`);
+  }
+
+  /**
+   * Handle token refresh or re-authentication
+   * 
+   * @returns {Promise<Object>} New auth metadata
+   */
+  async refreshToken() {
+    if (!this.isEnabled()) {
+      return { type: 'none' };
+    }
+
+    const strategy = this.getStrategy();
+
+    if (strategy === 'token' && typeof this.config.refreshToken === 'function') {
+      try {
+        const token = await this.config.refreshToken();
+        if (!token) {
+          throw new RealtimeError('TOKEN_REFRESH_FAILED', 'refreshToken() returned empty token');
+        }
+        return {
+          type: 'token',
+          token,
+        };
+      } catch (err) {
+        if (err instanceof RealtimeError) throw err;
+        throw new RealtimeError('TOKEN_REFRESH_FAILED', 'Failed to refresh token', err);
+      }
+    }
+
+    // Fallback to standard resolve
+    return this.resolveAuthMetadata();
+  }
+
+  /**
+   * Notify unauthorized handler if configured
+   * @param {RealtimeError} error
+   */
+  handleUnauthorized(error) {
+    if (this.config && typeof this.config.onUnauthorized === 'function') {
+      try {
+        this.config.onUnauthorized(error);
+      } catch (e) {
+        console.error('[realtime] Error in onUnauthorized handler:', e);
+      }
+    }
+  }
+}
+
+module.exports = { AuthManager };