@djangocfg/centrifugo 2.1.3 → 2.1.4

package/README.md

@@ -335,46 +335,114 @@ interface UseRPCResult {
 }
 ```
 
-**Backend Implementation:**
+### useNamedRPC() - Native Centrifugo RPC
 
-The backend should subscribe to `rpc#{method}` channels and publish responses:
+Hook for making **native Centrifugo RPC calls** via RPC proxy.
+
+**This is the recommended approach** for request-response patterns. It uses Centrifugo's built-in RPC mechanism which proxies requests to Django.
+
+**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
+```
+
+**Basic Usage:**
+
+```tsx
+import { useNamedRPC } from '@djangocfg/centrifugo';
+
+function TerminalInput() {
+  const { call, isLoading, error } = useNamedRPC();
+
+  const handleSendInput = async (input: string) => {
+    try {
+      const result = await call('terminal.input', {
+        session_id: 'abc-123',
+        data: btoa(input)  // Base64 encode
+      });
+      console.log('Result:', result);
+    } catch (error) {
+      console.error('RPC failed:', error);
+    }
+  };
+
+  return (
+    <button onClick={() => handleSendInput('ls -la')} disabled={isLoading}>
+      {isLoading ? 'Sending...' : 'Send Command'}
+    </button>
+  );
+}
+```
+
+**With Type Safety:**
+
+```tsx
+interface TerminalInputRequest {
+  session_id: string;
+  data: string;  // Base64 encoded
+}
+
+interface TerminalInputResponse {
+  success: boolean;
+  message?: string;
+}
+
+const { call } = useNamedRPC();
+
+const result = await call<TerminalInputRequest, TerminalInputResponse>(
+  'terminal.input',
+  { session_id: 'abc-123', data: btoa('ls -la') }
+);
+
+console.log(result.success); // Type-safe!
+```
+
+**Backend Handler:**
 
 ```python
-# Django backend example
-from django_cfg.apps.integrations.centrifugo import get_centrifugo_publisher
-
-publisher = get_centrifugo_publisher()
-
-# Listen to RPC requests (via Centrifugo subscription)
-async def handle_rpc_request(data):
-    correlation_id = data['correlation_id']
-    method = data['method']
-    params = data['params']
-    reply_to = data['reply_to']
-    
-    try:
-        # Process request
-        result = await process_task_stats(params['bot_id'])
-        
-        # Send response
-        await publisher.publish(
-            channel=reply_to,
-            data={
-                'correlation_id': correlation_id,
-                'result': result,
-            }
-        )
-    except Exception as e:
-        # Send error response
-        await publisher.publish(
-            channel=reply_to,
-            data={
-                'correlation_id': correlation_id,
-                'error': {'message': str(e)},
-            }
-        )
+# Django backend with @websocket_rpc decorator
+from pydantic import BaseModel, Field
+from django_cfg.apps.integrations.centrifugo.decorators import websocket_rpc
+
+class TerminalInputParams(BaseModel):
+    session_id: str = Field(..., description="Session UUID")
+    data: str = Field(..., description="Base64 encoded input")
+
+class SuccessResult(BaseModel):
+    success: bool
+    message: str = ""
+
+@websocket_rpc("terminal.input")
+async def terminal_input(conn, params: TerminalInputParams) -> SuccessResult:
+    """Handle terminal input from browser."""
+    # Forward to gRPC/Electron terminal
+    await forward_to_terminal(params.session_id, base64.b64decode(params.data))
+    return SuccessResult(success=True, message="Input sent")
+```
+
+**Options:**
+```typescript
+interface UseNamedRPCOptions {
+  onError?: (error: Error) => void;
+}
+
+interface UseNamedRPCResult {
+  call: <TRequest, TResponse>(
+    method: string,
+    data: TRequest
+  ) => Promise<TResponse>;
+  isLoading: boolean;
+  error: Error | null;
+  reset: () => void;
+}
 ```
 
+> **Note:** `useNamedRPC` uses native Centrifugo RPC which requires RPC proxy to be configured in Centrifugo server. See the [Setup Guide](https://djangocfg.com/features/integrations/centrifugo/setup) for configuration details.
+
 ## UI Components
 
 All components are composable and can be used independently or together.

package/package.json

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

package/src/core/client/CentrifugoRPCClient.ts

@@ -475,4 +475,52 @@ export class CentrifugoRPCClient {
   getCentrifuge(): Centrifuge {
     return this.centrifuge;
   }
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Native Centrifugo RPC (via RPC Proxy)
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  /**
+   * 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
+   *
+   * @param method - RPC method name (e.g., 'terminal.input')
+   * @param data - Request data
+   * @returns Promise that resolves with response data
+   *
+   * @example
+   * const result = await client.namedRPC('terminal.input', {
+   *   session_id: 'abc-123',
+   *   data: btoa('ls -la')
+   * });
+   * console.log('Result:', result); // { success: true }
+   */
+  async namedRPC<TRequest = any, TResponse = any>(
+    method: string,
+    data: TRequest
+  ): Promise<TResponse> {
+    this.logger.info(`Native RPC: ${method}`, { data });
+
+    try {
+      const result = await this.centrifuge.rpc(method, data);
+
+      this.logger.success(`Native RPC success: ${method}`, {
+        hasData: !!result.data
+      });
+
+      return result.data as TResponse;
+    } catch (error) {
+      this.logger.error(`Native RPC failed: ${method}`, error);
+      throw error;
+    }
+  }
 }

package/src/hooks/index.ts

@@ -7,3 +7,6 @@ export type { UseSubscriptionOptions, UseSubscriptionResult } from './useSubscri
 
 export { useRPC } from './useRPC';
 export type { UseRPCOptions, UseRPCResult } from './useRPC';
+
+export { useNamedRPC } from './useNamedRPC';
+export type { UseNamedRPCOptions, UseNamedRPCResult } from './useNamedRPC';

package/src/hooks/useNamedRPC.ts

@@ -0,0 +1,118 @@
+/**
+ * useNamedRPC Hook
+ *
+ * React hook for making native Centrifugo RPC calls via RPC proxy.
+ * Uses Centrifugo's built-in RPC mechanism which proxies to Django.
+ *
+ * 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
+ *
+ * @example
+ * const { call, isLoading, error } = useNamedRPC();
+ *
+ * const handleSendInput = async () => {
+ *   const result = await call('terminal.input', {
+ *     session_id: 'abc-123',
+ *     data: btoa('ls -la')
+ *   });
+ *   console.log('Result:', result);
+ * };
+ */
+
+'use client';
+
+import { useState, useCallback, useRef } from 'react';
+import { useCentrifugo } from '../providers/CentrifugoProvider';
+import { createLogger } from '../core/logger';
+
+export interface UseNamedRPCOptions {
+  onError?: (error: Error) => void;
+}
+
+export interface UseNamedRPCResult {
+  call: <TRequest = any, TResponse = any>(
+    method: string,
+    data: TRequest
+  ) => Promise<TResponse>;
+  isLoading: boolean;
+  error: Error | null;
+  reset: () => void;
+}
+
+export function useNamedRPC(
+  defaultOptions: UseNamedRPCOptions = {}
+): UseNamedRPCResult {
+  const { client, isConnected } = useCentrifugo();
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const logger = useRef(createLogger('useNamedRPC')).current;
+
+  const reset = useCallback(() => {
+    setIsLoading(false);
+    setError(null);
+  }, []);
+
+  const call = useCallback(
+    async <TRequest = any, TResponse = any>(
+      method: string,
+      data: TRequest
+    ): Promise<TResponse> => {
+      if (!client) {
+        const error = new Error('Centrifugo client not available');
+        setError(error);
+        throw error;
+      }
+
+      if (!isConnected) {
+        const error = new Error('Not connected to Centrifugo');
+        setError(error);
+        throw error;
+      }
+
+      // Reset previous state
+      setError(null);
+      setIsLoading(true);
+
+      try {
+        logger.info(`Native RPC call: ${method}`, { data });
+
+        const result = await client.namedRPC<TRequest, TResponse>(method, data);
+
+        logger.success(`Native RPC success: ${method}`);
+        setIsLoading(false);
+        return result;
+      } catch (err) {
+        const rpcError =
+          err instanceof Error ? err : new Error('Native RPC call failed');
+
+        setError(rpcError);
+        logger.error(`Native RPC failed: ${method}`, rpcError);
+
+        // Call error callback if provided
+        if (defaultOptions.onError) {
+          try {
+            defaultOptions.onError(rpcError);
+          } catch (callbackError) {
+            logger.error('Error in onError callback', callbackError);
+          }
+        }
+
+        setIsLoading(false);
+        throw rpcError;
+      }
+    },
+    [client, isConnected, defaultOptions, logger]
+  );
+
+  return {
+    call,
+    isLoading,
+    error,
+    reset,
+  };
+}