@djangocfg/centrifugo 2.1.54 → 2.1.56

package/src/core/client/subscriptions.ts

@@ -0,0 +1,176 @@
+/**
+ * Subscription Management Module
+ *
+ * Handles Centrifugo channel subscriptions (pub/sub pattern).
+ */
+
+import type { Centrifuge, Subscription } from 'centrifuge';
+import type { Logger } from '../logger';
+
+export interface SubscriptionManager {
+  channelSubscriptions: Map<string, Subscription>;
+  centrifuge: Centrifuge;
+  logger: Logger;
+}
+
+/**
+ * Subscribe to a Centrifugo channel for real-time events.
+ *
+ * @param manager - Subscription manager state
+ * @param channel - Channel name (e.g., 'bot#bot-123#heartbeat')
+ * @param callback - Callback for received messages
+ * @returns Unsubscribe function
+ *
+ * @example
+ * const unsubscribe = subscribe(manager, 'bot#bot-123#heartbeat', (data) => {
+ *   console.log('Heartbeat:', data);
+ * });
+ *
+ * // Later: unsubscribe when done
+ * unsubscribe();
+ */
+export function subscribe(
+  manager: SubscriptionManager,
+  channel: string,
+  callback: (data: any) => void
+): () => void {
+  const { channelSubscriptions, centrifuge, logger } = manager;
+
+  // Check if already subscribed - reuse existing subscription
+  const existingSub = channelSubscriptions.get(channel);
+  if (existingSub) {
+    logger.warning(`Already subscribed to ${channel}, reusing existing subscription`);
+
+    // Add new callback handler to existing subscription
+    const handler = (ctx: any) => {
+      try {
+        callback(ctx.data);
+      } catch (error) {
+        logger.error(`Error in subscription callback for ${channel}`, error);
+      }
+    };
+
+    existingSub.on('publication', handler);
+
+    // Return unsubscribe that only removes this specific handler
+    return () => {
+      existingSub.off('publication', handler);
+    };
+  }
+
+  // Create new subscription using Centrifuge's getSubscription or newSubscription
+  let sub = centrifuge.getSubscription(channel);
+  if (!sub) {
+    sub = centrifuge.newSubscription(channel);
+  }
+
+  // Handle publications with error handling
+  const publicationHandler = (ctx: any) => {
+    try {
+      callback(ctx.data);
+    } catch (error) {
+      logger.error(`Error in subscription callback for ${channel}`, error);
+    }
+  };
+
+  sub.on('publication', publicationHandler);
+
+  // Handle subscription lifecycle
+  sub.on('subscribed', () => {
+    logger.success(`Subscribed to ${channel}`);
+  });
+
+  sub.on('error', (ctx: any) => {
+    logger.error(`Subscription error for ${channel}`, ctx.error);
+  });
+
+  // Start subscription
+  sub.subscribe();
+
+  // Store subscription
+  channelSubscriptions.set(channel, sub);
+
+  // Return unsubscribe function
+  return () => unsubscribe(manager, channel);
+}
+
+/**
+ * Unsubscribe from a channel.
+ * Properly removes subscription from both internal map and Centrifuge client.
+ */
+export function unsubscribe(manager: SubscriptionManager, channel: string): void {
+  const { channelSubscriptions, centrifuge, logger } = manager;
+  const sub = channelSubscriptions.get(channel);
+
+  if (!sub) {
+    return;
+  }
+
+  try {
+    sub.unsubscribe();
+    centrifuge.removeSubscription(sub);
+    channelSubscriptions.delete(channel);
+    logger.info(`Unsubscribed from ${channel}`);
+  } catch (error) {
+    logger.error(`Error unsubscribing from ${channel}`, error);
+    channelSubscriptions.delete(channel);
+  }
+}
+
+/**
+ * Unsubscribe from all channels.
+ */
+export function unsubscribeAll(manager: SubscriptionManager): void {
+  const { channelSubscriptions, centrifuge, logger } = manager;
+
+  if (channelSubscriptions.size === 0) {
+    return;
+  }
+
+  channelSubscriptions.forEach((sub, channel) => {
+    try {
+      sub.unsubscribe();
+      centrifuge.removeSubscription(sub);
+    } catch (error) {
+      logger.error(`Error unsubscribing from ${channel}`, error);
+    }
+  });
+
+  channelSubscriptions.clear();
+  logger.info('Unsubscribed from all channels');
+}
+
+/**
+ * Get list of active client-side subscriptions.
+ */
+export function getActiveSubscriptions(manager: SubscriptionManager): string[] {
+  return Array.from(manager.channelSubscriptions.keys());
+}
+
+/**
+ * Get list of server-side subscriptions (from JWT token).
+ *
+ * These are channels automatically subscribed by Centrifugo server
+ * based on the 'channels' claim in the JWT token.
+ */
+export function getServerSideSubscriptions(manager: SubscriptionManager): string[] {
+  try {
+    // Access Centrifuge.js internal state for server-side subs
+    // @ts-ignore - accessing internal property
+    const serverSubs = manager.centrifuge._serverSubs || {};
+    return Object.keys(serverSubs);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get all active subscriptions (both client-side and server-side).
+ */
+export function getAllSubscriptions(manager: SubscriptionManager): string[] {
+  const clientSubs = getActiveSubscriptions(manager);
+  const serverSubs = getServerSideSubscriptions(manager);
+
+  // Combine and deduplicate
+  return Array.from(new Set([...clientSubs, ...serverSubs]));
+}

package/src/core/client/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Centrifugo Client Types
+ */
+
+import type { Logger } from '../logger';
+
+export interface CentrifugoClientOptions {
+  url: string;
+  token: string;
+  userId: string;
+  timeout?: number;
+  logger?: Logger;
+  /**
+   * Callback to get fresh token when current token expires.
+   * Centrifuge-js calls this automatically on token expiration.
+   */
+  getToken?: () => Promise<string>;
+}
+
+export interface RPCOptions {
+  timeout?: number;
+  replyChannel?: string;
+}
+
+export interface RetryOptions {
+  /** Max retry attempts (default: 3) */
+  maxRetries?: number;
+  /** Base delay in ms for exponential backoff (default: 100) */
+  baseDelayMs?: number;
+  /** Max delay cap in ms (default: 2000) */
+  maxDelayMs?: number;
+}
+
+export interface VersionCheckResult {
+  compatible: boolean;
+  clientVersion: string;
+  serverVersion: string;
+  message: string;
+}
+
+export interface PendingRequest {
+  resolve: (result: any) => void;
+  reject: (error: Error) => void;
+}

package/src/core/client/version.ts

@@ -0,0 +1,92 @@
+/**
+ * API Version Checking Module
+ *
+ * Validates that client and server API versions are compatible.
+ */
+
+import { dispatchVersionMismatch } from '../../events';
+
+import type { Logger } from '../logger';
+import type { VersionCheckResult } from './types';
+
+export interface VersionChecker {
+  namedRPC: <TRequest, TResponse>(method: string, data: TRequest) => Promise<TResponse>;
+  logger: Logger;
+}
+
+interface CheckVersionResponse {
+  compatible: boolean;
+  client_version: string;
+  server_version: string;
+  message: string;
+}
+
+/**
+ * Check if client API version matches server version.
+ *
+ * Calls system.check_version RPC and dispatches a CustomEvent
+ * if versions don't match. Listen to 'centrifugo' event to handle globally.
+ *
+ * @example
+ * ```ts
+ * import { API_VERSION } from '@/_ws';
+ *
+ * // Check version after connect
+ * const result = await checkApiVersion(checker, API_VERSION);
+ * if (!result.compatible) {
+ *   // Event already dispatched, but you can handle here too
+ *   console.warn('Please refresh the page');
+ * }
+ *
+ * // Listen to event globally
+ * window.addEventListener('centrifugo', (e) => {
+ *   if (e.detail.type === 'version_mismatch') {
+ *     toast.warning('New version available. Please refresh.');
+ *   }
+ * });
+ * ```
+ */
+export async function checkApiVersion(
+  checker: VersionChecker,
+  clientVersion: string
+): Promise<VersionCheckResult> {
+  const { namedRPC, logger } = checker;
+
+  try {
+    const result = await namedRPC<{ client_version: string }, CheckVersionResponse>(
+      'system.check_version',
+      { client_version: clientVersion }
+    );
+
+    if (!result.compatible) {
+      logger.warning(
+        `API version mismatch: client=${clientVersion}, server=${result.server_version}`
+      );
+
+      // Dispatch event for global handling
+      dispatchVersionMismatch({
+        clientVersion,
+        serverVersion: result.server_version,
+        message: result.message || 'API version mismatch. Please refresh the page.',
+      });
+    } else {
+      logger.success(`API version check passed: ${clientVersion}`);
+    }
+
+    return {
+      compatible: result.compatible,
+      clientVersion,
+      serverVersion: result.server_version,
+      message: result.message,
+    };
+  } catch (error) {
+    // If endpoint doesn't exist (old server), assume compatible
+    logger.warning('API version check endpoint not available');
+    return {
+      compatible: true,
+      clientVersion,
+      serverVersion: 'unknown',
+      message: 'Version check endpoint not available',
+    };
+  }
+}

package/src/events.ts

@@ -1,40 +1,50 @@
 /**
  * Centrifugo Package Events
  *
- * Event-driven communication for Centrifugo monitor dialog
- * and error tracking via CustomEvents
+ * Unified event system for Centrifugo client.
+ * All events use single 'centrifugo' CustomEvent with type discriminator.
  */
 
 import { events } from '@djangocfg/ui-nextjs';
 
 // ─────────────────────────────────────────────────────────────────────────
-// Event Types
+// Event Constants
 // ─────────────────────────────────────────────────────────────────────────
 
+/**
+ * Single event name for all Centrifugo events.
+ * Use `type` field in payload to distinguish event types.
+ */
+export const CENTRIFUGO_EVENT = 'centrifugo' as const;
+
+/**
+ * Internal events for UI components (via events.publish)
+ */
 export const CENTRIFUGO_MONITOR_EVENTS = {
   OPEN_MONITOR_DIALOG: 'CENTRIFUGO_OPEN_MONITOR_DIALOG',
   CLOSE_MONITOR_DIALOG: 'CENTRIFUGO_CLOSE_MONITOR_DIALOG',
 } as const;
 
-/**
- * Error event name for ErrorsTracker integration
- */
-export const CENTRIFUGO_ERROR_EVENT = 'centrifugo-error' as const;
+// Legacy exports for backwards compatibility
+export const CENTRIFUGO_ERROR_EVENT = CENTRIFUGO_EVENT;
+export const CENTRIFUGO_VERSION_MISMATCH_EVENT = CENTRIFUGO_EVENT;
 
 // ─────────────────────────────────────────────────────────────────────────
-// Event Payload Types
+// Event Types
 // ─────────────────────────────────────────────────────────────────────────
 
-export interface OpenMonitorDialogPayload {
-  variant?: 'compact' | 'full' | 'minimal';
-  defaultTab?: 'connection' | 'messages' | 'subscriptions';
-}
+export type CentrifugoEventType =
+  | 'error'
+  | 'version_mismatch'
+  | 'connected'
+  | 'disconnected'
+  | 'reconnecting';
 
-/**
- * Payload for centrifugo-error CustomEvent
- * Compatible with ErrorsTracker CentrifugoErrorDetail
- */
-export interface CentrifugoErrorPayload {
+// ─────────────────────────────────────────────────────────────────────────
+// Event Payloads
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface CentrifugoErrorData {
   /** RPC method that failed */
   method: string;
   /** Error message */
@@ -45,60 +55,163 @@ export interface CentrifugoErrorPayload {
   data?: any;
 }
 
+export interface CentrifugoVersionMismatchData {
+  /** Client API version hash */
+  clientVersion: string;
+  /** Server API version hash */
+  serverVersion: string;
+  /** Human-readable message */
+  message: string;
+}
+
+export interface CentrifugoConnectionData {
+  /** User ID */
+  userId?: string;
+  /** Reconnect attempt number (for reconnecting) */
+  attempt?: number;
+  /** Reason for disconnect */
+  reason?: string;
+}
+
+/**
+ * Unified Centrifugo event payload
+ */
+export type CentrifugoEventPayload =
+  | { type: 'error'; data: CentrifugoErrorData }
+  | { type: 'version_mismatch'; data: CentrifugoVersionMismatchData }
+  | { type: 'connected'; data: CentrifugoConnectionData }
+  | { type: 'disconnected'; data: CentrifugoConnectionData }
+  | { type: 'reconnecting'; data: CentrifugoConnectionData };
+
+/**
+ * Full event detail (includes timestamp)
+ */
+export type CentrifugoEventDetail = CentrifugoEventPayload & {
+  timestamp: Date;
+};
+
 // ─────────────────────────────────────────────────────────────────────────
-// Event Emitters
+// Monitor Dialog Payloads (internal events)
 // ─────────────────────────────────────────────────────────────────────────
 
-export const emitOpenMonitorDialog = (payload?: OpenMonitorDialogPayload) => {
-  events.publish({
-    type: CENTRIFUGO_MONITOR_EVENTS.OPEN_MONITOR_DIALOG,
-    payload: payload || {},
-  });
-};
+export interface OpenMonitorDialogPayload {
+  variant?: 'compact' | 'full' | 'minimal';
+  defaultTab?: 'connection' | 'messages' | 'subscriptions';
+}
 
-export const emitCloseMonitorDialog = () => {
-  events.publish({
-    type: CENTRIFUGO_MONITOR_EVENTS.CLOSE_MONITOR_DIALOG,
-    payload: {},
-  });
-};
+// ─────────────────────────────────────────────────────────────────────────
+// Legacy Types (for backwards compatibility)
+// ─────────────────────────────────────────────────────────────────────────
+
+/** @deprecated Use CentrifugoErrorData */
+export type CentrifugoErrorPayload = CentrifugoErrorData;
+
+/** @deprecated Use CentrifugoVersionMismatchData */
+export type VersionMismatchPayload = CentrifugoVersionMismatchData;
 
 // ─────────────────────────────────────────────────────────────────────────
-// Error Event Dispatcher (CustomEvent for ErrorsTracker)
+// Event Dispatcher
 // ─────────────────────────────────────────────────────────────────────────
 
 /**
- * Dispatch Centrifugo error event for ErrorsTracker
- *
- * Uses window.dispatchEvent with CustomEvent to integrate with
- * ErrorsTracker from @djangocfg/layouts package.
+ * Dispatch unified Centrifugo event
  *
  * @example
  * ```ts
- * dispatchCentrifugoError({
- *   method: 'terminal.input',
- *   error: 'timeout',
- *   code: 1,
- *   data: { session_id: 'abc-123' },
+ * // Dispatch error
+ * dispatchCentrifugoEvent({
+ *   type: 'error',
+ *   data: { method: 'terminal.input', error: 'timeout' }
+ * });
+ *
+ * // Listen to all Centrifugo events
+ * window.addEventListener('centrifugo', (e) => {
+ *   const { type, data, timestamp } = e.detail;
+ *   switch (type) {
+ *     case 'error':
+ *       console.error('RPC error:', data.method, data.error);
+ *       break;
+ *     case 'version_mismatch':
+ *       toast.warning('Please refresh the page');
+ *       break;
+ *   }
  * });
  * ```
  */
-export const dispatchCentrifugoError = (payload: CentrifugoErrorPayload): void => {
+export const dispatchCentrifugoEvent = (payload: CentrifugoEventPayload): void => {
   if (typeof window === 'undefined') {
     return;
   }
 
   try {
-    window.dispatchEvent(new CustomEvent(CENTRIFUGO_ERROR_EVENT, {
-      detail: {
-        ...payload,
-        timestamp: new Date(),
-      },
+    const detail: CentrifugoEventDetail = {
+      ...payload,
+      timestamp: new Date(),
+    };
+
+    window.dispatchEvent(new CustomEvent(CENTRIFUGO_EVENT, {
+      detail,
       bubbles: true,
       cancelable: false,
     }));
-  } catch (eventError) {
+  } catch (error) {
     // Silently fail - event dispatch should never crash the app
   }
 };
 
+// ─────────────────────────────────────────────────────────────────────────
+// Convenience Dispatchers
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Dispatch error event
+ */
+export const dispatchCentrifugoError = (data: CentrifugoErrorData): void => {
+  dispatchCentrifugoEvent({ type: 'error', data });
+};
+
+/**
+ * Dispatch version mismatch event
+ */
+export const dispatchVersionMismatch = (data: CentrifugoVersionMismatchData): void => {
+  dispatchCentrifugoEvent({ type: 'version_mismatch', data });
+};
+
+/**
+ * Dispatch connected event
+ */
+export const dispatchConnected = (data: CentrifugoConnectionData = {}): void => {
+  dispatchCentrifugoEvent({ type: 'connected', data });
+};
+
+/**
+ * Dispatch disconnected event
+ */
+export const dispatchDisconnected = (data: CentrifugoConnectionData = {}): void => {
+  dispatchCentrifugoEvent({ type: 'disconnected', data });
+};
+
+/**
+ * Dispatch reconnecting event
+ */
+export const dispatchReconnecting = (data: CentrifugoConnectionData = {}): void => {
+  dispatchCentrifugoEvent({ type: 'reconnecting', data });
+};
+
+// ─────────────────────────────────────────────────────────────────────────
+// Monitor Dialog Emitters (internal, uses events.publish)
+// ─────────────────────────────────────────────────────────────────────────
+
+export const emitOpenMonitorDialog = (payload?: OpenMonitorDialogPayload) => {
+  events.publish({
+    type: CENTRIFUGO_MONITOR_EVENTS.OPEN_MONITOR_DIALOG,
+    payload: payload || {},
+  });
+};
+
+export const emitCloseMonitorDialog = () => {
+  events.publish({
+    type: CENTRIFUGO_MONITOR_EVENTS.CLOSE_MONITOR_DIALOG,
+    payload: {},
+  });
+};