@djangocfg/centrifugo 1.0.1 → 1.0.3

package/src/hooks/useSubscription.ts

@@ -1,86 +1,87 @@
 /**
- * React hook for subscribing to Centrifugo channels.
+ * useSubscription Hook
  *
- * Automatically handles subscription lifecycle (mount/unmount).
- *
- * @example
- * // Subscribe to bot heartbeat
- * useSubscription('bot#bot-123#heartbeat', (data) => {
- *   console.log('Heartbeat:', data);
- *   updateMetrics(data);
- * });
- *
- * @example
- * // Conditional subscription
- * useSubscription(
- *   'bot#bot-123#status',
- *   (data) => console.log('Status:', data),
- *   { enabled: isMonitoring }
- * );
+ * Subscribe to Centrifugo channel with auto-cleanup.
  */
 
-import { useEffect, useRef } from 'react';
-import { useCentrifugo } from '../context';
+'use client';
+
+import { useEffect, useCallback, useRef, useState } from 'react';
+import { useCentrifugo } from '../providers/CentrifugoProvider';
+import { createLogger } from '../core/logger';
 
-export interface useSubscriptionOptions {
-  /**
-   * Enable/disable subscription.
-   * Defaults to true.
-   */
+export interface UseSubscriptionOptions<T = any> {
+  channel: string;
   enabled?: boolean;
+  onPublication?: (data: T) => void;
+  onError?: (error: Error) => void;
+}
+
+export interface UseSubscriptionResult<T = any> {
+  data: T | null;
+  error: Error | null;
+  isSubscribed: boolean;
+  unsubscribe: () => void;
 }
 
-/**
- * Hook for subscribing to a Centrifugo channel.
- *
- * @param channel - Channel name (e.g., 'bot#bot-123#heartbeat'). Set to null to disable.
- * @param callback - Callback function for received messages
- * @param options - Subscription options
- *
- * @example
- * ```tsx
- * function BotMonitor({ botId }: { botId: string }) {
- *   const [heartbeat, setHeartbeat] = useState(null);
- *
- *   useSubscription(`bot#${botId}#heartbeat`, (data) => {
- *     setHeartbeat(data);
- *   });
- *
- *   return <div>CPU: {heartbeat?.cpu_usage}%</div>;
- * }
- * ```
- */
 export function useSubscription<T = any>(
-  channel: string | null,
-  callback: (data: T) => void,
-  options: useSubscriptionOptions = {}
-) {
-  const { baseClient, isConnected } = useCentrifugo();
-  const callbackRef = useRef(callback);
-  const { enabled = true } = options;
+  options: UseSubscriptionOptions<T>
+): UseSubscriptionResult<T> {
+  const { client, isConnected } = useCentrifugo();
+  const { channel, enabled = true, onPublication, onError } = options;
 
-  // Keep callback ref updated (avoid stale closures)
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
+  const [data, setData] = useState<T | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const [isSubscribed, setIsSubscribed] = useState(false);
 
+  const unsubscribeRef = useRef<(() => void) | null>(null);
+  const logger = useRef(createLogger({ source: 'subscription' })).current;
+
+  // Unsubscribe function
+  const unsubscribe = useCallback(() => {
+    if (unsubscribeRef.current) {
+      unsubscribeRef.current();
+      unsubscribeRef.current = null;
+      setIsSubscribed(false);
+      logger.info(`Unsubscribed from channel: ${channel}`);
+    }
+  }, [channel, logger]);
+
+  // Subscribe effect
   useEffect(() => {
-    // Don't subscribe if disabled, not connected, or no channel
-    if (!enabled || !isConnected || !baseClient || !channel) {
+    if (!client || !isConnected || !enabled) {
       return;
     }
 
-    console.log(`🎣 useSubscription: Subscribing to ${channel}`);
+    logger.info(`Subscribing to channel: ${channel}`);
+
+    try {
+      const unsub = client.subscribe(channel, (receivedData: T) => {
+        setData(receivedData);
+        setError(null);
+        onPublication?.(receivedData);
+      });
 
-    // Subscribe with stable callback wrapper
-    const unsubscribe = baseClient.subscribe(channel, (data) => {
-      callbackRef.current(data);
-    });
+      unsubscribeRef.current = unsub;
+      setIsSubscribed(true);
+      logger.success(`Subscribed to channel: ${channel}`);
+    } catch (err) {
+      const subscriptionError = err instanceof Error ? err : new Error('Subscription failed');
+      setError(subscriptionError);
+      onError?.(subscriptionError);
+      logger.error(`Subscription failed: ${channel}`, subscriptionError);
+    }
 
-    // Cleanup on unmount or channel change
+    // Cleanup on unmount or deps change
     return () => {
-      console.log(`🎣 useSubscription: Unsubscribing from ${channel}`);
       unsubscribe();
     };
-  }, [channel, enabled, isConnected, baseClient]);
+  }, [client, isConnected, enabled, channel, onPublication, onError, unsubscribe, logger]);
+
+  return {
+    data,
+    error,
+    isSubscribed,
+    unsubscribe,
+  };
 }

package/src/index.ts

@@ -1,27 +1,108 @@
 /**
  * @djangocfg/centrifugo
  *
- * WebSocket client for Django-CFG + Centrifugo integration
+ * Professional Centrifugo WebSocket client with React integration.
+ *
+ * ## Architecture
+ *
+ * - **Core**: Platform-agnostic client, logger, and types
+ * - **Providers**: React Context for connection and logs management
+ * - **Hooks**: React hooks for subscriptions
+ * - **Debug**: Development-only debug UI (lazy loaded)
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * import { CentrifugoProvider, useCentrifugo, useSubscription, DebugPanel } from '@djangocfg/centrifugo';
+ *
+ * function App() {
+ *   return (
+ *     <CentrifugoProvider
+ *       url="ws://localhost:8000/ws"
+ *       getToken={async () => ({ token: 'xxx', user: 'user123' })}
+ *     >
+ *       <YourApp />
+ *       <DebugPanel />
+ *     </CentrifugoProvider>
+ *   );
+ * }
+ *
+ * function YourComponent() {
+ *   const { isConnected, client } = useCentrifugo();
+ *
+ *   useSubscription({
+ *     channel: 'notifications',
+ *     onPublication: (data) => console.log(data),
+ *   });
+ *
+ *   return <div>Connected: {isConnected ? 'Yes' : 'No'}</div>;
+ * }
+ * ```
  */
 
-// Context & Provider
-export { CentrifugoProvider, useCentrifugo } from './context';
+// ─────────────────────────────────────────────────────────────────────────
+// Re-export Centrifuge for advanced usage
+// ─────────────────────────────────────────────────────────────────────────
 
-// Hooks
-export { useCentrifugoLogger, useRPCLogger, useSubscription } from './hooks';
-export type { CentrifugoLogger, RPCLogger } from './hooks';
-export type { useSubscriptionOptions } from './hooks';
+export { Centrifuge } from 'centrifuge';
+export type { Subscription } from 'centrifuge';
 
-// Components
-export { CentrifugoDebug, WSRPCDebug } from './components';
+// ─────────────────────────────────────────────────────────────────────────
+// Core (Platform-agnostic)
+// ─────────────────────────────────────────────────────────────────────────
 
-// Types
+export { CentrifugoRPCClient } from './core/client/CentrifugoRPCClient';
+export { createLogger, getGlobalLogsStore } from './core/logger';
 export type {
+  // Connection
+  ConnectionState,
   CentrifugoToken,
   User,
+
+  // Logs
+  LogLevel,
+  LogEntry,
+
+  // Subscriptions
+  ActiveSubscription,
+
+  // Client
+  CentrifugoClientConfig,
+  CentrifugoClientState,
+} from './core/types';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Providers (React Context)
+// ─────────────────────────────────────────────────────────────────────────
+
+export { CentrifugoProvider, useCentrifugo } from './providers/CentrifugoProvider';
+export { LogsProvider, useLogs } from './providers/LogsProvider';
+export type {
   CentrifugoProviderProps,
   CentrifugoContextValue,
-} from './types';
+} from './providers/CentrifugoProvider';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Hooks
+// ─────────────────────────────────────────────────────────────────────────
+
+export { useSubscription } from './hooks/useSubscription';
+export type {
+  UseSubscriptionOptions,
+  UseSubscriptionResult,
+} from './hooks/useSubscription';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Configuration
+// ─────────────────────────────────────────────────────────────────────────
+
+export { centrifugoConfig, isDevelopment, isProduction, isStaticBuild } from './config';
+export type { CentrifugoConfig } from './config';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Debug UI (Embedded in Provider, not for direct use)
+// ─────────────────────────────────────────────────────────────────────────
 
-// Config
-export { isDevelopment, isProduction, isStaticBuild, centrifugoConfig } from './config';
+// Note: DebugPanel is now automatically embedded in CentrifugoProvider
+// It shows automatically in development or for admin users
+// No need to manually add <DebugPanel /> to your app

package/src/providers/CentrifugoProvider/CentrifugoProvider.tsx

@@ -0,0 +1,380 @@
+/**
+ * Centrifugo Provider
+ *
+ * Main provider that manages WebSocket connection.
+ * Wraps LogsProvider to provide logs accumulation.
+ */
+
+'use client';
+
+import { createContext, useContext, useState, useEffect, useCallback, useRef, useMemo, lazy, Suspense, type ReactNode } from 'react';
+import { useAuth } from '@djangocfg/layouts';
+import { CentrifugoRPCClient } from '../../core/client';
+import { createLogger } from '../../core/logger';
+import type { ConnectionState, CentrifugoToken } from '../../core/types';
+import { LogsProvider } from '../LogsProvider';
+import { isDevelopment, isStaticBuild } from '../../config';
+
+// Lazy load DebugPanel to reduce bundle size
+const DebugPanel = lazy(() =>
+  import('../../debug/DebugPanel').then((m) => ({ default: m.DebugPanel }))
+);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Context
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface CentrifugoContextValue {
+  // Client
+  client: CentrifugoRPCClient | null;
+
+  // Connection State
+  isConnected: boolean;
+  isConnecting: boolean;
+  error: Error | null;
+  connectionState: ConnectionState;
+
+  // Connection Info
+  uptime: number; // seconds
+  subscriptions: string[];
+  activeSubscriptions: import('../../core/types').ActiveSubscription[];
+
+  // Controls
+  connect: () => Promise<void>;
+  disconnect: () => void;
+  reconnect: () => Promise<void>;
+  unsubscribe: (channel: string) => void;
+
+  // Config
+  enabled: boolean;
+}
+
+const CentrifugoContext = createContext<CentrifugoContextValue | undefined>(undefined);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Provider Props
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface CentrifugoProviderProps {
+  children: ReactNode;
+  enabled?: boolean;
+  url?: string;
+  autoConnect?: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Inner Provider (has access to LogsProvider)
+// ─────────────────────────────────────────────────────────────────────────
+
+function CentrifugoProviderInner({
+  children,
+  enabled = false,
+  url,
+  autoConnect: autoConnectProp = true,
+}: CentrifugoProviderProps) {
+  const { isAuthenticated, isLoading, user, isAdminUser } = useAuth();
+
+  const [client, setClient] = useState<CentrifugoRPCClient | null>(null);
+  const [isConnected, setIsConnected] = useState(false);
+  const [isConnecting, setIsConnecting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [connectionTime, setConnectionTime] = useState<Date | null>(null);
+  const [uptime, setUptime] = useState<number>(0);
+  const [subscriptions, setSubscriptions] = useState<string[]>([]);
+  const [activeSubscriptions, setActiveSubscriptions] = useState<import('../../core/types').ActiveSubscription[]>([]);
+
+  const logger = useMemo(() => createLogger({ source: 'provider' }), []);
+
+  const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const hasConnectedRef = useRef(false);
+  const isConnectingRef = useRef(false);
+  const isMountedRef = useRef(true);
+
+  const centrifugoToken: CentrifugoToken | undefined = user?.centrifugo;
+  const hasCentrifugoToken = !!centrifugoToken?.token;
+
+  const wsUrl = useMemo(() => {
+    if (url) return url;
+    if (centrifugoToken?.centrifugo_url) return centrifugoToken.centrifugo_url;
+    return '';
+  }, [url, centrifugoToken?.centrifugo_url]);
+
+  const autoConnect = autoConnectProp &&
+                      (isAuthenticated && !isLoading) &&
+                      enabled &&
+                      hasCentrifugoToken;
+
+  // Log connection decision
+  useEffect(() => {
+    if (!isLoading) {
+      logger.info(`Auto-connect: ${autoConnect ? 'YES' : 'NO'}`, {
+        authenticated: isAuthenticated,
+        loading: isLoading,
+        enabled,
+        hasToken: hasCentrifugoToken,
+        url: wsUrl,
+      });
+    }
+  }, [autoConnect, isAuthenticated, isLoading, enabled, hasCentrifugoToken, logger, wsUrl]);
+
+  // Update uptime every second
+  useEffect(() => {
+    if (!isConnected || !connectionTime) {
+      setUptime(0);
+      return;
+    }
+
+    const updateUptime = () => {
+      const now = new Date();
+      const diff = Math.floor((now.getTime() - connectionTime.getTime()) / 1000);
+      setUptime(diff);
+    };
+
+    updateUptime();
+    const interval = setInterval(updateUptime, 1000);
+
+    return () => clearInterval(interval);
+  }, [isConnected, connectionTime]);
+
+  // Update subscriptions periodically
+  useEffect(() => {
+    if (!client || !isConnected) {
+      setSubscriptions([]);
+      setActiveSubscriptions([]);
+      return;
+    }
+
+    const updateSubs = () => {
+      try {
+        const subs = client.getAllSubscriptions?.() || [];
+        setSubscriptions(subs);
+
+        // Convert to ActiveSubscription format
+        const activeSubs: import('../../core/types').ActiveSubscription[] = subs.map((channel) => ({
+          channel,
+          type: 'client' as const,
+          subscribedAt: Date.now(),
+        }));
+        setActiveSubscriptions(activeSubs);
+      } catch (error) {
+        logger.error('Failed to get subscriptions', error);
+      }
+    };
+
+    updateSubs();
+    const interval = setInterval(updateSubs, 2000);
+
+    return () => clearInterval(interval);
+  }, [client, isConnected, logger]);
+
+  // Connect function
+  const connect = useCallback(async () => {
+    if (hasConnectedRef.current || isConnectingRef.current) return;
+    if (isConnecting || isConnected) return;
+
+    isConnectingRef.current = true;
+    setIsConnecting(true);
+    setError(null);
+
+    try {
+      logger.info('Connecting to WebSocket server...');
+
+      if (!centrifugoToken?.token) {
+        throw new Error('No Centrifugo token available');
+      }
+
+      const token = centrifugoToken.token;
+      let userId = user?.id?.toString() || '1';
+
+      if (!user?.id) {
+        try {
+          const tokenPayload = JSON.parse(atob(token.split('.')[1]));
+          userId = tokenPayload.user_id?.toString() || tokenPayload.sub?.toString() || '1';
+        } catch (err) {
+          // Fallback
+        }
+      }
+
+      const rpcClient = new CentrifugoRPCClient(wsUrl, token, userId, 30000, logger);
+      await rpcClient.connect();
+
+      if (!isMountedRef.current) {
+        rpcClient.disconnect();
+        isConnectingRef.current = false;
+        return;
+      }
+
+      hasConnectedRef.current = true;
+      isConnectingRef.current = false;
+
+      setClient(rpcClient);
+      setIsConnected(true);
+      setConnectionTime(new Date());
+      setError(null);
+
+      logger.success('WebSocket connected');
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error('Connection failed');
+      setError(error);
+      setClient(null);
+      setIsConnected(false);
+      setConnectionTime(null);
+      hasConnectedRef.current = false;
+      isConnectingRef.current = false;
+
+      const isAuthError = error.message.includes('token') ||
+                          error.message.includes('auth') ||
+                          error.message.includes('expired');
+
+      if (isAuthError) {
+        logger.error('Authentication failed', error);
+      } else {
+        logger.error('Connection failed', error);
+        reconnectTimeoutRef.current = setTimeout(() => {
+          logger.info('Attempting to reconnect...');
+          connect();
+        }, 5000);
+      }
+    } finally {
+      setIsConnecting(false);
+    }
+  }, [wsUrl, centrifugoToken, user, logger, isConnecting, isConnected]);
+
+  // Disconnect function
+  const disconnect = useCallback(() => {
+    if (isConnectingRef.current) return;
+
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current);
+      reconnectTimeoutRef.current = null;
+    }
+
+    if (client) {
+      logger.info('Disconnecting from WebSocket server...');
+      client.disconnect();
+      setClient(null);
+      setIsConnected(false);
+      setConnectionTime(null);
+      setError(null);
+      setSubscriptions([]);
+    }
+
+    hasConnectedRef.current = false;
+    isConnectingRef.current = false;
+  }, [client, logger]);
+
+  // Reconnect function
+  const reconnect = useCallback(async () => {
+    disconnect();
+    await connect();
+  }, [connect, disconnect]);
+
+  // Unsubscribe function
+  const unsubscribe = useCallback((channel: string) => {
+    if (!client) {
+      logger.warning('Cannot unsubscribe: client not connected');
+      return;
+    }
+
+    try {
+      client.unsubscribe?.(channel);
+      logger.info(`Unsubscribed from channel: ${channel}`);
+
+      // Update state immediately
+      setSubscriptions((prev) => prev.filter((ch) => ch !== channel));
+      setActiveSubscriptions((prev) => prev.filter((sub) => sub.channel !== channel));
+    } catch (error) {
+      logger.error(`Failed to unsubscribe from ${channel}`, error);
+    }
+  }, [client, logger]);
+
+  // Auto-connect on mount
+  useEffect(() => {
+    isMountedRef.current = true;
+
+    if (autoConnect && !hasConnectedRef.current) {
+      connect();
+    }
+
+    return () => {
+      if (isConnectingRef.current && !hasConnectedRef.current) {
+        return;
+      }
+
+      if (!hasConnectedRef.current) {
+        return;
+      }
+
+      isMountedRef.current = false;
+      disconnect();
+    };
+  }, [autoConnect, connect, disconnect]);
+
+  const connectionState: ConnectionState = isConnected
+    ? 'connected'
+    : isConnecting
+    ? 'connecting'
+    : error
+    ? 'error'
+    : 'disconnected';
+
+  const value: CentrifugoContextValue = {
+    client,
+    isConnected,
+    isConnecting,
+    error,
+    connectionState,
+    uptime,
+    subscriptions,
+    activeSubscriptions,
+    connect,
+    disconnect,
+    reconnect,
+    unsubscribe,
+    enabled,
+  };
+
+  // Smart DebugPanel visibility:
+  // - Show in development mode
+  // - Show for admin users
+  const showDebugPanel = useMemo(() => {
+    return isDevelopment || isAdminUser;
+  }, [isAdminUser]);
+
+  return (
+    <CentrifugoContext.Provider value={value}>
+      {children}
+      {showDebugPanel && (
+        <Suspense fallback={null}>
+          <DebugPanel />
+        </Suspense>
+      )}
+    </CentrifugoContext.Provider>
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Main Provider (wraps LogsProvider)
+// ─────────────────────────────────────────────────────────────────────────
+
+export function CentrifugoProvider(props: CentrifugoProviderProps) {
+  return (
+    <LogsProvider>
+      <CentrifugoProviderInner {...props} />
+    </LogsProvider>
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────
+
+export function useCentrifugo(): CentrifugoContextValue {
+  const context = useContext(CentrifugoContext);
+
+  if (context === undefined) {
+    throw new Error('useCentrifugo must be used within a CentrifugoProvider');
+  }
+
+  return context;
+}

package/src/providers/CentrifugoProvider/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Centrifugo Provider
+ */
+
+export { CentrifugoProvider, useCentrifugo } from './CentrifugoProvider';
+export type { CentrifugoContextValue, CentrifugoProviderProps } from './CentrifugoProvider';