@djangocfg/centrifugo 2.1.54 → 2.1.56

package/src/core/client/connection.ts

@@ -0,0 +1,229 @@
+/**
+ * Connection Management Module
+ *
+ * Handles Centrifuge WebSocket connection lifecycle.
+ */
+
+import { Centrifuge, type Subscription } from 'centrifuge';
+
+import { dispatchConnected, dispatchDisconnected, dispatchReconnecting } from '../../events';
+import { getConsolaLogger } from '../logger/consolaLogger';
+
+import type { Logger } from '../logger';
+import type { CentrifugoClientOptions, PendingRequest } from './types';
+
+export interface ConnectionState {
+  centrifuge: Centrifuge;
+  replySubscription: Subscription | null;
+  pendingRequests: Map<string, PendingRequest>;
+  channelSubscriptions: Map<string, Subscription>;
+  userId: string;
+  replyChannel: string;
+  timeout: number;
+  logger: Logger;
+}
+
+/**
+ * Create connection state from options.
+ * Handles both old positional args and new options-based API.
+ */
+export function createConnectionState(
+  urlOrOptions: string | CentrifugoClientOptions,
+  token?: string,
+  userId?: string,
+  timeout: number = 30000,
+  logger?: Logger
+): ConnectionState {
+  // Parse arguments
+  let url: string;
+  let actualToken: string;
+  let actualUserId: string;
+  let actualTimeout: number;
+  let actualLogger: Logger | undefined;
+  let getToken: (() => Promise<string>) | undefined;
+
+  if (typeof urlOrOptions === 'object') {
+    url = urlOrOptions.url;
+    actualToken = urlOrOptions.token;
+    actualUserId = urlOrOptions.userId;
+    actualTimeout = urlOrOptions.timeout ?? 30000;
+    actualLogger = urlOrOptions.logger;
+    getToken = urlOrOptions.getToken;
+  } else {
+    url = urlOrOptions;
+    actualToken = token!;
+    actualUserId = userId!;
+    actualTimeout = timeout;
+    actualLogger = logger;
+  }
+
+  const log = actualLogger || getConsolaLogger('client');
+  const replyChannel = `user#${actualUserId}`;
+
+  // Build Centrifuge options
+  const centrifugeOptions: any = {
+    token: actualToken,
+  };
+
+  // Add getToken callback for automatic token refresh
+  if (getToken) {
+    centrifugeOptions.getToken = async () => {
+      log.info('Token expired, refreshing...');
+      try {
+        const newToken = await getToken();
+        log.success('Token refreshed successfully');
+        return newToken;
+      } catch (error) {
+        log.error('Failed to refresh token', error);
+        throw error;
+      }
+    };
+  }
+
+  const centrifuge = new Centrifuge(url, centrifugeOptions);
+
+  return {
+    centrifuge,
+    replySubscription: null,
+    pendingRequests: new Map(),
+    channelSubscriptions: new Map(),
+    userId: actualUserId,
+    replyChannel,
+    timeout: actualTimeout,
+    logger: log,
+  };
+}
+
+/**
+ * Setup connection event handlers.
+ */
+export function setupConnectionHandlers(
+  state: ConnectionState,
+  onResponse: (data: any) => void
+): void {
+  const { centrifuge, pendingRequests, logger, userId } = state;
+
+  // Handle disconnection - reject all pending requests
+  centrifuge.on('disconnected', (ctx) => {
+    pendingRequests.forEach(({ reject }) => {
+      reject(new Error('Disconnected from Centrifugo'));
+    });
+    pendingRequests.clear();
+
+    dispatchDisconnected({
+      userId,
+      reason: ctx.reason,
+    });
+
+    logger.info('Disconnected from Centrifugo', { reason: ctx.reason });
+  });
+
+  // Handle successful connection
+  centrifuge.on('connected', () => {
+    dispatchConnected({ userId });
+    logger.success('Connected to Centrifugo');
+  });
+
+  // Handle reconnecting state
+  centrifuge.on('connecting', (ctx) => {
+    if (ctx.reason === 'transport closed') {
+      dispatchReconnecting({
+        userId,
+        attempt: 1,
+        reason: ctx.reason,
+      });
+      logger.info('Reconnecting to Centrifugo...', { reason: ctx.reason });
+    }
+  });
+}
+
+/**
+ * Connect to Centrifugo server.
+ */
+export async function connect(
+  state: ConnectionState,
+  onResponse: (data: any) => void
+): Promise<void> {
+  const { centrifuge, replyChannel, logger } = state;
+
+  return new Promise((resolve, reject) => {
+    let resolved = false;
+
+    const onConnected = () => {
+      if (!resolved) {
+        resolved = true;
+        resolve();
+      }
+    };
+
+    const onError = (ctx: any) => {
+      if (!resolved) {
+        resolved = true;
+        reject(new Error(ctx.message || 'Connection error'));
+      }
+    };
+
+    centrifuge.on('connected', onConnected);
+    centrifuge.on('error', onError);
+
+    // Start connection
+    centrifuge.connect();
+
+    // Subscribe to reply channel for RPC responses
+    const subscription = centrifuge.newSubscription(replyChannel);
+    state.replySubscription = subscription;
+
+    subscription.on('publication', (ctx: any) => {
+      onResponse(ctx.data);
+    });
+
+    subscription.on('subscribed', () => {
+      logger.success(`Subscribed to reply channel: ${replyChannel}`);
+    });
+
+    subscription.on('error', (ctx: any) => {
+      // Error code 105 = "already subscribed" (server-side subscription from JWT)
+      if (ctx.error?.code === 105) {
+        // This is fine, server-side subscription exists
+      } else {
+        logger.error(`Subscription error for ${replyChannel}:`, ctx.error);
+      }
+    });
+
+    subscription.subscribe();
+  });
+}
+
+/**
+ * Disconnect from Centrifugo server.
+ */
+export function disconnect(state: ConnectionState): void {
+  const { centrifuge, replySubscription, channelSubscriptions, logger } = state;
+
+  // Unsubscribe from all event channels
+  channelSubscriptions.forEach((sub, channel) => {
+    try {
+      sub.unsubscribe();
+      centrifuge.removeSubscription(sub);
+    } catch (error) {
+      logger.error(`Error unsubscribing from ${channel}`, error);
+    }
+  });
+  channelSubscriptions.clear();
+
+  // Unsubscribe from RPC reply channel
+  if (replySubscription) {
+    replySubscription.unsubscribe();
+    state.replySubscription = null;
+  }
+
+  centrifuge.disconnect();
+  logger.info('Disconnected from Centrifugo');
+}
+
+/**
+ * Generate unique correlation ID for RPC requests.
+ */
+export function generateCorrelationId(): string {
+  return `rpc-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}

package/src/core/client/index.ts

@@ -1,6 +1,51 @@
 /**
- * Client Module
+ * Centrifugo Client Module
+ *
+ * Exports the main client and its supporting modules.
  */
 
+// Main client (facade)
 export { CentrifugoRPCClient } from './CentrifugoRPCClient';
-export type { CentrifugoClientOptions } from './CentrifugoRPCClient';
+
+// Types
+export type {
+  CentrifugoClientOptions,
+  RPCOptions,
+  RetryOptions,
+  VersionCheckResult,
+  PendingRequest,
+} from './types';
+
+// Connection module (for advanced use cases)
+export {
+  createConnectionState,
+  setupConnectionHandlers,
+  connect,
+  disconnect,
+  generateCorrelationId,
+  type ConnectionState,
+} from './connection';
+
+// Subscription module (for advanced use cases)
+export {
+  subscribe,
+  unsubscribe,
+  unsubscribeAll,
+  getActiveSubscriptions,
+  getServerSideSubscriptions,
+  getAllSubscriptions,
+  type SubscriptionManager,
+} from './subscriptions';
+
+// RPC module (for advanced use cases)
+export {
+  handleResponse,
+  call,
+  rpc,
+  namedRPC,
+  namedRPCNoWait,
+  type RPCManager,
+} from './rpc';
+
+// Version module (for advanced use cases)
+export { checkApiVersion, type VersionChecker } from './version';

package/src/core/client/rpc.ts

@@ -0,0 +1,290 @@
+/**
+ * RPC Module
+ *
+ * Handles Centrifugo RPC patterns (request-response and fire-and-forget).
+ */
+
+import type { Centrifuge, Subscription } from 'centrifuge';
+
+import { dispatchCentrifugoError } from '../../events';
+
+import type { Logger } from '../logger';
+import type { PendingRequest, RPCOptions, RetryOptions } from './types';
+import { generateCorrelationId } from './connection';
+
+export interface RPCManager {
+  centrifuge: Centrifuge;
+  pendingRequests: Map<string, PendingRequest>;
+  channelSubscriptions: Map<string, Subscription>;
+  userId: string;
+  timeout: number;
+  logger: Logger;
+  subscribe: (channel: string, callback: (data: any) => void) => () => void;
+}
+
+/**
+ * Handle RPC response from reply channel.
+ */
+export function handleResponse(
+  pendingRequests: Map<string, PendingRequest>,
+  data: any
+): void {
+  const correlationId = data.correlation_id;
+  if (!correlationId) {
+    return;
+  }
+
+  const pending = pendingRequests.get(correlationId);
+  if (!pending) {
+    return;
+  }
+
+  pendingRequests.delete(correlationId);
+
+  if (data.error) {
+    pending.reject(new Error(data.error.message || 'RPC error'));
+  } else {
+    pending.resolve(data.result);
+  }
+}
+
+/**
+ * Legacy RPC call via publish/subscribe pattern.
+ *
+ * @deprecated Use namedRPC for Centrifugo RPC Proxy
+ */
+export async function call<T = any>(
+  manager: RPCManager,
+  method: string,
+  params: any,
+  replyChannel: string
+): Promise<T> {
+  const { centrifuge, pendingRequests, timeout, logger } = manager;
+  const correlationId = generateCorrelationId();
+
+  const message = {
+    method,
+    params,
+    correlation_id: correlationId,
+    reply_to: replyChannel,
+  };
+
+  const promise = new Promise<T>((resolve, reject) => {
+    const timeoutId = setTimeout(() => {
+      pendingRequests.delete(correlationId);
+      reject(new Error(`RPC timeout: ${method}`));
+    }, timeout);
+
+    pendingRequests.set(correlationId, {
+      resolve: (result: T) => {
+        clearTimeout(timeoutId);
+        resolve(result);
+      },
+      reject: (error: Error) => {
+        clearTimeout(timeoutId);
+        reject(error);
+      },
+    });
+  });
+
+  await centrifuge.publish('rpc.requests', message);
+
+  return promise;
+}
+
+/**
+ * RPC Pattern API (Request-Response via Correlation ID).
+ *
+ * @deprecated Use namedRPC for Centrifugo RPC Proxy
+ */
+export async function rpc<TRequest = any, TResponse = any>(
+  manager: RPCManager,
+  method: string,
+  params: TRequest,
+  options: RPCOptions = {}
+): Promise<TResponse> {
+  const { centrifuge, logger, subscribe, userId } = manager;
+  const { timeout = 10000, replyChannel = `user#${userId}` } = options;
+
+  const correlationId = generateCorrelationId();
+
+  logger.info(`RPC request: ${method}`, { correlationId, params });
+
+  return new Promise<TResponse>((resolve, reject) => {
+    let timeoutId: NodeJS.Timeout | null = null;
+    let unsubscribe: (() => void) | null = null;
+
+    const cleanup = () => {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+      if (unsubscribe) {
+        unsubscribe();
+        unsubscribe = null;
+      }
+    };
+
+    timeoutId = setTimeout(() => {
+      cleanup();
+      const error = new Error(`RPC timeout: ${method} (${timeout}ms)`);
+      logger.error(`RPC timeout: ${method}`, { correlationId, timeout });
+      reject(error);
+    }, timeout);
+
+    try {
+      unsubscribe = subscribe(replyChannel, (data: any) => {
+        try {
+          if (data.correlation_id === correlationId) {
+            cleanup();
+
+            if (data.error) {
+              logger.error(`RPC error: ${method}`, {
+                correlationId,
+                error: data.error,
+              });
+              reject(new Error(data.error.message || 'RPC error'));
+              return;
+            }
+
+            logger.success(`RPC response: ${method}`, {
+              correlationId,
+              hasResult: !!data.result,
+            });
+            resolve(data.result as TResponse);
+          }
+        } catch (error) {
+          cleanup();
+          logger.error(`Error processing RPC response: ${method}`, error);
+          reject(error);
+        }
+      });
+
+      const rpcChannel = `rpc#${method}`;
+      const sub = centrifuge.getSubscription(rpcChannel);
+
+      if (sub) {
+        sub
+          .publish({
+            correlation_id: correlationId,
+            method,
+            params,
+            reply_to: replyChannel,
+            timestamp: Date.now(),
+          })
+          .catch((error: any) => {
+            cleanup();
+            logger.error(`Failed to publish RPC request: ${method}`, error);
+            reject(error);
+          });
+      } else {
+        cleanup();
+        reject(
+          new Error(
+            `Cannot publish RPC request: no subscription to ${rpcChannel}. ` +
+              `Backend should provide a publish endpoint or use server-side subscriptions.`
+          )
+        );
+      }
+    } catch (error) {
+      cleanup();
+      logger.error(`Failed to setup RPC: ${method}`, error);
+      reject(error);
+    }
+  });
+}
+
+/**
+ * Call RPC method via native Centrifugo RPC proxy.
+ *
+ * This uses Centrifugo's built-in RPC mechanism which proxies
+ * requests to the backend (Django) via HTTP.
+ *
+ * Flow:
+ * 1. Client calls namedRPC('terminal.input', data)
+ * 2. Centrifuge.js sends RPC over WebSocket
+ * 3. Centrifugo proxies to Django: POST /centrifugo/rpc/
+ * 4. Django routes to @websocket_rpc handler
+ * 5. Response returned to client
+ */
+export async function namedRPC<TRequest = any, TResponse = any>(
+  manager: RPCManager,
+  method: string,
+  data: TRequest,
+  options?: { timeout?: number }
+): Promise<TResponse> {
+  const { centrifuge, logger } = manager;
+
+  logger.info(`Native RPC: ${method}`, { data });
+
+  try {
+    const result = await centrifuge.rpc(method, data);
+
+    logger.success(`Native RPC success: ${method}`, {
+      hasData: !!result.data,
+    });
+
+    return result.data as TResponse;
+  } catch (error) {
+    logger.error(`Native RPC failed: ${method}`, error);
+
+    // Dispatch error event for ErrorsTracker
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const errorCode = (error as any)?.code;
+    dispatchCentrifugoError({
+      method,
+      error: errorMessage,
+      code: errorCode,
+      data,
+    });
+
+    throw error;
+  }
+}
+
+/**
+ * Fire-and-forget RPC call - sends without waiting for response.
+ * Use for latency-sensitive operations like terminal input.
+ *
+ * Features:
+ * - Returns immediately (non-blocking)
+ * - Automatic retry with exponential backoff on failure
+ * - Configurable max retries and delays
+ */
+export function namedRPCNoWait<TRequest = any>(
+  manager: RPCManager,
+  method: string,
+  data: TRequest,
+  options?: RetryOptions
+): void {
+  const { centrifuge, logger } = manager;
+
+  const maxRetries = options?.maxRetries ?? 3;
+  const baseDelayMs = options?.baseDelayMs ?? 100;
+  const maxDelayMs = options?.maxDelayMs ?? 2000;
+
+  const attemptSend = (attempt: number): void => {
+    centrifuge.rpc(method, data).catch((error) => {
+      if (attempt < maxRetries) {
+        // Exponential backoff: 100ms, 200ms, 400ms... capped at maxDelayMs
+        const delay = Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
+
+        logger.warning(
+          `Fire-and-forget RPC failed (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms: ${method}`,
+          error
+        );
+
+        setTimeout(() => attemptSend(attempt + 1), delay);
+      } else {
+        // All retries exhausted
+        logger.error(
+          `Fire-and-forget RPC failed after ${maxRetries + 1} attempts: ${method}`,
+          error
+        );
+      }
+    });
+  };
+
+  // Start first attempt immediately
+  attemptSend(0);
+}