@djangocfg/centrifugo 2.1.72 → 2.1.73

package/README.md

@@ -34,10 +34,13 @@ src/
 │   │   ├── CentrifugoRPCClient.ts  # Main facade (~165 lines)
 │   │   ├── connection.ts           # Connection lifecycle
 │   │   ├── subscriptions.ts        # Channel subscriptions
-│   │   ├── rpc.ts                  # RPC methods (namedRPC, namedRPCNoWait)
+│   │   ├── rpc.ts                  # RPC methods (namedRPC, namedRPCWithRetry, namedRPCNoWait)
 │   │   ├── version.ts              # API version checking
 │   │   ├── types.ts                # Type definitions
 │   │   └── index.ts                # Exports
+│   ├── errors/              # Error handling with retry logic
+│   │   ├── RPCError.ts      # Typed RPC errors (isRetryable, userMessage)
+│   │   └── RPCRetryHandler.ts # Exponential backoff retry
 │   ├── logger/              # Logging system with circular buffer
 │   │   ├── createLogger.ts  # Logger factory (supports string prefix)
 │   │   └── LogsStore.ts     # In-memory logs accumulation
@@ -598,6 +601,98 @@ client?.namedRPCNoWait('terminal.input', { session_id, data }, {
 | `namedRPC()` | ~800-1800ms | Commands that need response |
 | `namedRPCNoWait()` | ~10-30ms | Real-time input, fire-and-forget |
 
+### namedRPCWithRetry() - RPC with Timeout and Retry
+
+For operations that need both timeout protection and automatic retry on transient failures.
+
+```tsx
+import { useCentrifugo } from '@djangocfg/centrifugo';
+
+function FileList() {
+  const { client } = useCentrifugo();
+
+  const loadFiles = async () => {
+    // Automatically retries on timeout/network errors
+    const files = await client?.namedRPCWithRetry('files.list',
+      { path: '/home' },
+      {
+        timeout: 5000,      // 5 second timeout per attempt
+        maxRetries: 3,      // Up to 3 retries
+        baseDelayMs: 1000,  // Start with 1s delay
+        maxDelayMs: 10000,  // Cap at 10s
+        onRetry: (attempt, error, delay) => {
+          console.log(`Retry ${attempt}: ${error.userMessage}, waiting ${delay}ms`);
+        }
+      }
+    );
+    return files;
+  };
+}
+```
+
+### RPCError - Typed Error Handling
+
+All RPC methods now throw `RPCError` with classification for better error handling:
+
+```tsx
+import { RPCError } from '@djangocfg/centrifugo';
+
+try {
+  await client.namedRPC('files.list', { path: '/' });
+} catch (error) {
+  if (error instanceof RPCError) {
+    // Error classification
+    console.log(error.code);           // 'timeout' | 'network_error' | 'server_error' | ...
+    console.log(error.isRetryable);    // true for transient errors
+    console.log(error.userMessage);    // User-friendly message
+    console.log(error.suggestedRetryDelay); // Recommended delay in ms
+
+    // Show user-friendly message
+    toast.error(error.userMessage);
+
+    // Decide if retry makes sense
+    if (error.isRetryable) {
+      // Schedule retry
+    }
+  }
+}
+```
+
+**Error Codes:**
+
+| Code | Retryable | Description |
+|------|-----------|-------------|
+| `timeout` | ✅ | Request timed out |
+| `network_error` | ✅ | Network connectivity issue |
+| `connection_failed` | ✅ | WebSocket connection failed |
+| `websocket_error` | ✅ | WebSocket protocol error |
+| `server_error` | ✅ (5xx only) | Server returned error |
+| `not_connected` | ❌ | Client not connected |
+| `encoding_error` | ❌ | Failed to encode request |
+| `decoding_error` | ❌ | Failed to decode response |
+| `cancelled` | ❌ | Request was cancelled |
+
+### withRetry() - Generic Retry Utility
+
+For custom retry logic outside of RPC:
+
+```tsx
+import { withRetry, RPCError } from '@djangocfg/centrifugo';
+
+const result = await withRetry(
+  () => fetchSomething(),
+  {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 10000,
+    jitterFactor: 0.2,  // ±20% randomization
+  },
+  (state, delay) => {
+    console.log(`Retry ${state.attempt}, waiting ${delay}ms`);
+  }
+);
+```
+
 ### checkApiVersion() - API Contract Validation
 
 Validates that the client API version matches the server. Useful for detecting when the frontend needs to refresh after a backend deployment.
@@ -1087,6 +1182,12 @@ import type {
   RPCOptions,
   RetryOptions,
   VersionCheckResult,
+  NamedRPCWithRetryOptions,
+
+  // Errors
+  RPCErrorCode,
+  RetryConfig,
+  RetryState,
 
   // Connection
   ConnectionState,
@@ -1121,6 +1222,9 @@ import type {
   SubscriptionsListProps,
   CentrifugoMonitorProps,
 } from '@djangocfg/centrifugo';
+
+// Error classes
+import { RPCError, withRetry, createRetryHandler } from '@djangocfg/centrifugo';
 ```
 
 ## Unified Event System

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/centrifugo",
-  "version": "2.1.72",
+  "version": "2.1.73",
   "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.72",
-    "@djangocfg/ui-nextjs": "^2.1.72",
-    "@djangocfg/layouts": "^2.1.72",
+    "@djangocfg/api": "^2.1.73",
+    "@djangocfg/ui-nextjs": "^2.1.73",
+    "@djangocfg/layouts": "^2.1.73",
     "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.72",
+    "@djangocfg/typescript-config": "^2.1.73",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "moment": "^2.30.1",

package/src/core/client/CentrifugoRPCClient.ts

@@ -47,7 +47,9 @@ import {
   rpc as legacyRpc,
   namedRPC as nativeNamedRPC,
   namedRPCNoWait as nativeNamedRPCNoWait,
+  namedRPCWithRetry as nativeNamedRPCWithRetry,
   type RPCManager,
+  type NamedRPCWithRetryOptions,
 } from './rpc';
 
 import { checkApiVersion as checkVersion } from './version';
@@ -158,6 +160,14 @@ export class CentrifugoRPCClient {
     nativeNamedRPCNoWait(this.rpcManager, method, data, options);
   }
 
+  async namedRPCWithRetry<TRequest = any, TResponse = any>(
+    method: string,
+    data: TRequest,
+    options?: NamedRPCWithRetryOptions
+  ): Promise<TResponse> {
+    return nativeNamedRPCWithRetry(this.rpcManager, method, data, options);
+  }
+
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   // API Version Checking
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━