@djangocfg/centrifugo 2.1.71 → 2.1.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/centrifugo",
-  "version": "2.1.71",
+  "version": "2.1.72",
   "description": "Production-ready Centrifugo WebSocket client for React with real-time subscriptions, RPC patterns, and connection state management",
   "keywords": [
     "centrifugo",
@@ -51,9 +51,9 @@
     "centrifuge": "^5.2.2"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.71",
-    "@djangocfg/ui-nextjs": "^2.1.71",
-    "@djangocfg/layouts": "^2.1.71",
+    "@djangocfg/api": "^2.1.72",
+    "@djangocfg/ui-nextjs": "^2.1.72",
+    "@djangocfg/layouts": "^2.1.72",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -61,7 +61,7 @@
     "react-dom": "^19.1.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.71",
+    "@djangocfg/typescript-config": "^2.1.72",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "moment": "^2.30.1",

package/src/core/client/index.ts

@@ -44,7 +44,9 @@ export {
   rpc,
   namedRPC,
   namedRPCNoWait,
+  namedRPCWithRetry,
   type RPCManager,
+  type NamedRPCWithRetryOptions,
 } from './rpc';
 
 // Version module (for advanced use cases)

package/src/core/client/rpc.ts

@@ -7,11 +7,15 @@
 import type { Centrifuge, Subscription } from 'centrifuge';
 
 import { dispatchCentrifugoError } from '../../events';
+import { RPCError } from '../errors/RPCError';
 
 import type { Logger } from '../logger';
 import type { PendingRequest, RPCOptions, RetryOptions } from './types';
 import { generateCorrelationId } from './connection';
 
+/** Default RPC timeout in milliseconds */
+const DEFAULT_RPC_TIMEOUT = 30000;
+
 export interface RPCManager {
   centrifuge: Centrifuge;
   pendingRequests: Map<string, PendingRequest>;
@@ -194,6 +198,17 @@ export async function rpc<TRequest = any, TResponse = any>(
   });
 }
 
+/**
+ * Create a timeout promise that rejects after specified ms.
+ */
+function createTimeoutPromise(timeoutMs: number, method: string): Promise<never> {
+  return new Promise((_, reject) => {
+    setTimeout(() => {
+      reject(new RPCError('timeout', `RPC timeout after ${timeoutMs}ms: ${method}`, { method }));
+    }, timeoutMs);
+  });
+}
+
 /**
  * Call RPC method via native Centrifugo RPC proxy.
  *
@@ -206,6 +221,11 @@ export async function rpc<TRequest = any, TResponse = any>(
  * 3. Centrifugo proxies to Django: POST /centrifugo/rpc/
  * 4. Django routes to @websocket_rpc handler
  * 5. Response returned to client
+ *
+ * Features:
+ * - Configurable timeout (default: 30s)
+ * - Returns typed RPCError for better error handling
+ * - Dispatches error events for monitoring
  */
 export async function namedRPC<TRequest = any, TResponse = any>(
   manager: RPCManager,
@@ -214,11 +234,16 @@ export async function namedRPC<TRequest = any, TResponse = any>(
   options?: { timeout?: number }
 ): Promise<TResponse> {
   const { centrifuge, logger } = manager;
+  const timeoutMs = options?.timeout ?? DEFAULT_RPC_TIMEOUT;
 
-  logger.info(`Native RPC: ${method}`, { data });
+  logger.info(`Native RPC: ${method}`, { data, timeout: timeoutMs });
 
   try {
-    const result = await centrifuge.rpc(method, data);
+    // Race between RPC call and timeout
+    const result = await Promise.race([
+      centrifuge.rpc(method, data),
+      createTimeoutPromise(timeoutMs, method),
+    ]);
 
     logger.success(`Native RPC success: ${method}`, {
       hasData: !!result.data,
@@ -226,29 +251,24 @@ export async function namedRPC<TRequest = any, TResponse = any>(
 
     return result.data as TResponse;
   } catch (error) {
-    logger.error(`Native RPC failed: ${method}`, error);
+    // Convert to RPCError for consistent error handling
+    const rpcError = RPCError.fromError(error, method);
+
+    logger.error(`Native RPC failed: ${method}`, {
+      code: rpcError.code,
+      isRetryable: rpcError.isRetryable,
+      message: rpcError.message,
+    });
 
     // Dispatch error event for ErrorsTracker
-    // Handle different error formats: Error objects, plain objects with message, or stringify
-    let errorMessage: string;
-    if (error instanceof Error) {
-      errorMessage = error.message;
-    } else if (typeof error === 'object' && error !== null) {
-      // Try to extract message from object, fallback to JSON stringify
-      const errObj = error as Record<string, unknown>;
-      errorMessage = (errObj.message as string) || (errObj.error as string) || JSON.stringify(error);
-    } else {
-      errorMessage = String(error);
-    }
-    const errorCode = (error as any)?.code;
     dispatchCentrifugoError({
       method,
-      error: errorMessage,
-      code: errorCode,
+      error: rpcError.message,
+      code: rpcError.serverCode,
       data,
     });
 
-    throw error;
+    throw rpcError;
   }
 }
 
@@ -275,21 +295,26 @@ export function namedRPCNoWait<TRequest = any>(
 
   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);
+      const rpcError = RPCError.fromError(error, method);
+
+      if (attempt < maxRetries && rpcError.isRetryable) {
+        // Exponential backoff with jitter
+        const baseDelay = rpcError.suggestedRetryDelay || baseDelayMs;
+        const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelayMs);
+        const jitter = delay * 0.2 * (Math.random() * 2 - 1);
+        const finalDelay = Math.max(0, Math.round(delay + jitter));
 
         logger.warning(
-          `Fire-and-forget RPC failed (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms: ${method}`,
-          error
+          `Fire-and-forget RPC failed (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${finalDelay}ms: ${method}`,
+          { code: rpcError.code, isRetryable: rpcError.isRetryable }
         );
 
-        setTimeout(() => attemptSend(attempt + 1), delay);
+        setTimeout(() => attemptSend(attempt + 1), finalDelay);
       } else {
-        // All retries exhausted
+        // All retries exhausted or non-retryable error
         logger.error(
-          `Fire-and-forget RPC failed after ${maxRetries + 1} attempts: ${method}`,
-          error
+          `Fire-and-forget RPC failed after ${attempt + 1} attempts: ${method}`,
+          { code: rpcError.code, message: rpcError.message }
         );
       }
     });
@@ -298,3 +323,83 @@ export function namedRPCNoWait<TRequest = any>(
   // Start first attempt immediately
   attemptSend(0);
 }
+
+export interface NamedRPCWithRetryOptions {
+  timeout?: number;
+  maxRetries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  onRetry?: (attempt: number, error: RPCError, delayMs: number) => void;
+}
+
+/**
+ * Call RPC method with timeout and automatic retry.
+ *
+ * Combines namedRPC timeout with retry logic for robust RPC calls.
+ * Uses RPCError.isRetryable to determine if retry should happen.
+ *
+ * @example
+ * const files = await namedRPCWithRetry(manager, 'files.list', { path: '/' }, {
+ *   timeout: 5000,
+ *   maxRetries: 3,
+ *   onRetry: (attempt, error, delay) => {
+ *     console.log(`Retry ${attempt} after ${delay}ms: ${error.userMessage}`);
+ *   }
+ * });
+ */
+export async function namedRPCWithRetry<TRequest = any, TResponse = any>(
+  manager: RPCManager,
+  method: string,
+  data: TRequest,
+  options?: NamedRPCWithRetryOptions
+): Promise<TResponse> {
+  const { logger } = manager;
+  const maxRetries = options?.maxRetries ?? 3;
+  const baseDelayMs = options?.baseDelayMs ?? 1000;
+  const maxDelayMs = options?.maxDelayMs ?? 10000;
+
+  let lastError: RPCError | null = null;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await namedRPC<TRequest, TResponse>(manager, method, data, {
+        timeout: options?.timeout,
+      });
+    } catch (error) {
+      lastError = error instanceof RPCError ? error : RPCError.fromError(error, method);
+
+      // Don't retry non-retryable errors
+      if (!lastError.isRetryable) {
+        throw lastError;
+      }
+
+      // Check if we have retries left
+      if (attempt >= maxRetries) {
+        throw lastError;
+      }
+
+      // Calculate delay with exponential backoff and jitter
+      const suggestedDelay = lastError.suggestedRetryDelay || baseDelayMs;
+      const exponentialDelay = suggestedDelay * Math.pow(2, attempt);
+      const cappedDelay = Math.min(exponentialDelay, maxDelayMs);
+      const jitter = cappedDelay * 0.2 * (Math.random() * 2 - 1);
+      const delayMs = Math.max(0, Math.round(cappedDelay + jitter));
+
+      logger.warning(
+        `RPC retry (${attempt + 1}/${maxRetries}): ${method} in ${delayMs}ms`,
+        { code: lastError.code, message: lastError.message }
+      );
+
+      // Notify callback if provided
+      if (options?.onRetry) {
+        options.onRetry(attempt + 1, lastError, delayMs);
+      }
+
+      // Wait before retry
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
+  // Should not reach here, but TypeScript needs this
+  throw lastError ?? new RPCError('unknown', 'Retry failed', { method });
+}

package/src/core/errors/RPCError.ts

@@ -0,0 +1,187 @@
+/**
+ * RPC Error with classification for retry logic.
+ *
+ * Mirrors Swift's RPCError implementation with:
+ * - isRetryable: Whether the error should trigger a retry
+ * - suggestedRetryDelay: Recommended delay before retry
+ * - userMessage: User-friendly error message
+ */
+
+export type RPCErrorCode =
+  | 'not_connected'
+  | 'timeout'
+  | 'server_error'
+  | 'encoding_error'
+  | 'decoding_error'
+  | 'websocket_error'
+  | 'connection_failed'
+  | 'cancelled'
+  | 'network_error'
+  | 'unknown';
+
+export class RPCError extends Error {
+  readonly code: RPCErrorCode;
+  readonly serverCode?: number;
+  readonly method?: string;
+  readonly isRetryable: boolean;
+  readonly suggestedRetryDelay: number;
+  readonly userMessage: string;
+
+  constructor(
+    code: RPCErrorCode,
+    message: string,
+    options?: {
+      serverCode?: number;
+      method?: string;
+      cause?: unknown;
+    }
+  ) {
+    super(message, { cause: options?.cause });
+    this.name = 'RPCError';
+    this.code = code;
+    this.serverCode = options?.serverCode;
+    this.method = options?.method;
+    this.isRetryable = this.determineRetryable();
+    this.suggestedRetryDelay = this.determineSuggestedDelay();
+    this.userMessage = this.determineUserMessage();
+  }
+
+  /**
+   * Determine if this error should trigger a retry.
+   * Transient errors (timeout, network) are retryable.
+   * Permanent errors (encoding, 4xx) are not.
+   */
+  private determineRetryable(): boolean {
+    switch (this.code) {
+      // Transient errors - retry
+      case 'timeout':
+      case 'websocket_error':
+      case 'connection_failed':
+      case 'network_error':
+        return true;
+
+      // Server errors - retry only 5xx
+      case 'server_error':
+        return this.serverCode ? this.serverCode >= 500 : false;
+
+      // Permanent errors - don't retry
+      case 'not_connected':
+      case 'encoding_error':
+      case 'decoding_error':
+      case 'cancelled':
+      case 'unknown':
+        return false;
+
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * Suggested delay before retry based on error type.
+   */
+  private determineSuggestedDelay(): number {
+    switch (this.code) {
+      case 'timeout':
+        return 1000;
+      case 'websocket_error':
+        return 2000;
+      case 'server_error':
+        return 3000;
+      case 'connection_failed':
+        return 2000;
+      case 'network_error':
+        return 1500;
+      default:
+        return 1000;
+    }
+  }
+
+  /**
+   * User-friendly message for UI display.
+   */
+  private determineUserMessage(): string {
+    switch (this.code) {
+      case 'not_connected':
+        return 'Not connected. Please check your internet connection.';
+      case 'timeout':
+        return 'Request timed out. Please try again.';
+      case 'server_error':
+        return this.message || 'Server error. Please try again later.';
+      case 'websocket_error':
+        return 'Connection error. Please try again.';
+      case 'connection_failed':
+        return 'Unable to connect. Please check your internet connection.';
+      case 'encoding_error':
+      case 'decoding_error':
+        return 'Data error. Please try again or contact support.';
+      case 'cancelled':
+        return 'Request cancelled.';
+      case 'network_error':
+        return 'Network error. Please check your connection.';
+      default:
+        return 'An unexpected error occurred. Please try again.';
+    }
+  }
+
+  /**
+   * Create RPCError from Centrifugo/unknown error.
+   */
+  static fromError(error: unknown, method?: string): RPCError {
+    if (error instanceof RPCError) {
+      return error;
+    }
+
+    // Handle Centrifugo error object
+    if (typeof error === 'object' && error !== null) {
+      const err = error as Record<string, unknown>;
+      const code = err.code as number | undefined;
+      const message =
+        (err.message as string) || (err.error as string) || 'Unknown error';
+
+      // Timeout detection
+      if (message.includes('timeout') || message.includes('Timeout')) {
+        return new RPCError('timeout', message, { method });
+      }
+
+      // Connection issues
+      if (
+        message.includes('disconnect') ||
+        message.includes('connection') ||
+        message.includes('not connected')
+      ) {
+        return new RPCError('connection_failed', message, { method });
+      }
+
+      // Server error codes
+      if (code !== undefined) {
+        if (code >= 500) {
+          return new RPCError('server_error', message, {
+            serverCode: code,
+            method,
+          });
+        }
+        if (code >= 400) {
+          return new RPCError('server_error', message, {
+            serverCode: code,
+            method,
+          });
+        }
+      }
+
+      return new RPCError('unknown', message, { method, cause: error });
+    }
+
+    // Standard Error
+    if (error instanceof Error) {
+      // Check for abort/cancel
+      if (error.name === 'AbortError') {
+        return new RPCError('cancelled', 'Request cancelled', { method });
+      }
+
+      return new RPCError('unknown', error.message, { method, cause: error });
+    }
+
+    return new RPCError('unknown', String(error), { method });
+  }
+}

package/src/core/errors/RPCRetryHandler.ts

@@ -0,0 +1,154 @@
+/**
+ * RPC Retry Handler with exponential backoff.
+ *
+ * Mirrors Swift's RPCRetryHandler implementation with:
+ * - Configurable max retries and delays
+ * - Exponential backoff with jitter
+ * - Retry decision based on RPCError.isRetryable
+ */
+
+import { RPCError } from './RPCError';
+
+export interface RetryConfig {
+  maxRetries: number;
+  baseDelayMs: number;
+  maxDelayMs: number;
+  jitterFactor: number;
+}
+
+export const DEFAULT_RETRY_CONFIG: RetryConfig = {
+  maxRetries: 3,
+  baseDelayMs: 1000,
+  maxDelayMs: 10000,
+  jitterFactor: 0.2,
+};
+
+export interface RetryState {
+  attempt: number;
+  lastError: RPCError | null;
+  totalDelayMs: number;
+}
+
+/**
+ * Calculate delay with exponential backoff and jitter.
+ */
+export function calculateDelay(
+  attempt: number,
+  config: RetryConfig,
+  error?: RPCError
+): number {
+  // Use error's suggested delay if available
+  const baseDelay = error?.suggestedRetryDelay ?? config.baseDelayMs;
+
+  // Exponential: base * 2^attempt
+  const exponentialDelay = baseDelay * Math.pow(2, attempt);
+
+  // Cap at max
+  const cappedDelay = Math.min(exponentialDelay, config.maxDelayMs);
+
+  // Add jitter: delay * (1 ± jitterFactor * random)
+  const jitter = cappedDelay * config.jitterFactor * (Math.random() * 2 - 1);
+
+  return Math.max(0, Math.round(cappedDelay + jitter));
+}
+
+/**
+ * Sleep for specified milliseconds.
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Execute operation with retry logic.
+ *
+ * @param operation - Async function to execute
+ * @param config - Retry configuration
+ * @param onRetry - Optional callback before each retry
+ * @returns Promise with operation result
+ * @throws RPCError after all retries exhausted
+ */
+export async function withRetry<T>(
+  operation: () => Promise<T>,
+  config: Partial<RetryConfig> = {},
+  onRetry?: (state: RetryState, delayMs: number) => void
+): Promise<T> {
+  const fullConfig: RetryConfig = { ...DEFAULT_RETRY_CONFIG, ...config };
+  const state: RetryState = {
+    attempt: 0,
+    lastError: null,
+    totalDelayMs: 0,
+  };
+
+  while (state.attempt <= fullConfig.maxRetries) {
+    try {
+      return await operation();
+    } catch (error) {
+      const rpcError = RPCError.fromError(error);
+      state.lastError = rpcError;
+
+      // Don't retry non-retryable errors
+      if (!rpcError.isRetryable) {
+        throw rpcError;
+      }
+
+      // Check if we have retries left
+      if (state.attempt >= fullConfig.maxRetries) {
+        throw rpcError;
+      }
+
+      // Calculate delay and wait
+      const delayMs = calculateDelay(state.attempt, fullConfig, rpcError);
+      state.totalDelayMs += delayMs;
+
+      // Notify about retry
+      if (onRetry) {
+        onRetry(state, delayMs);
+      }
+
+      await sleep(delayMs);
+      state.attempt++;
+    }
+  }
+
+  // Should not reach here, but TypeScript needs this
+  throw state.lastError ?? new RPCError('unknown', 'Retry failed');
+}
+
+/**
+ * Create a retry wrapper for RPC calls.
+ */
+export function createRetryHandler(config: Partial<RetryConfig> = {}) {
+  const fullConfig: RetryConfig = { ...DEFAULT_RETRY_CONFIG, ...config };
+
+  return {
+    config: fullConfig,
+
+    /**
+     * Execute with retry.
+     */
+    execute: <T>(
+      operation: () => Promise<T>,
+      onRetry?: (state: RetryState, delayMs: number) => void
+    ) => withRetry(operation, fullConfig, onRetry),
+
+    /**
+     * Check if error should be retried.
+     */
+    shouldRetry: (error: unknown, attempt: number): boolean => {
+      if (attempt >= fullConfig.maxRetries) {
+        return false;
+      }
+      const rpcError = RPCError.fromError(error);
+      return rpcError.isRetryable;
+    },
+
+    /**
+     * Get delay for next retry.
+     */
+    getDelay: (attempt: number, error?: unknown): number => {
+      const rpcError = error ? RPCError.fromError(error) : undefined;
+      return calculateDelay(attempt, fullConfig, rpcError);
+    },
+  };
+}

package/src/core/errors/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Error Types
+ */
+
+export { RPCError, type RPCErrorCode } from './RPCError';
+export {
+  withRetry,
+  createRetryHandler,
+  calculateDelay,
+  sleep,
+  DEFAULT_RETRY_CONFIG,
+  type RetryConfig,
+  type RetryState,
+} from './RPCRetryHandler';

package/src/core/index.ts

@@ -11,5 +11,14 @@ export { CentrifugoRPCClient } from './client';
 export { createLogger, LogsStore, getGlobalLogsStore } from './logger';
 export type { Logger, LoggerConfig } from './logger';
 
+// Errors
+export {
+  RPCError,
+  withRetry,
+  createRetryHandler,
+  DEFAULT_RETRY_CONFIG,
+} from './errors';
+export type { RPCErrorCode, RetryConfig, RetryState } from './errors';
+
 // Types
 export type * from './types';