@djangocfg/centrifugo 1.0.1 → 1.0.2

package/src/core/client/CentrifugoRPCClient.ts

@@ -0,0 +1,281 @@
+/**
+ * Base Centrifugo RPC Client
+ *
+ * Handles WebSocket connection and RPC call correlation.
+ * Provides both RPC (request/response) and Subscription (pub/sub) patterns.
+ */
+
+import { Centrifuge } from 'centrifuge';
+import type { Logger } from '../logger';
+import { createLogger } from '../logger';
+
+export class CentrifugoRPCClient {
+  private centrifuge: Centrifuge;
+  private subscription: any;
+  private channelSubscriptions: Map<string, any> = new Map();
+  private pendingRequests: Map<string, { resolve: Function; reject: Function }> = new Map();
+  private readonly replyChannel: string;
+  private readonly timeout: number;
+  private readonly logger: Logger;
+
+  constructor(
+    url: string,
+    token: string,
+    userId: string,
+    timeout: number = 30000,
+    logger?: Logger
+  ) {
+    this.replyChannel = `user#${userId}`;
+    this.timeout = timeout;
+    this.logger = logger || createLogger({ source: 'client' });
+
+    this.centrifuge = new Centrifuge(url, {
+      token,
+    });
+
+    this.centrifuge.on('disconnected', (ctx) => {
+      // Reject all pending requests
+      this.pendingRequests.forEach(({ reject }) => {
+        reject(new Error('Disconnected from Centrifugo'));
+      });
+      this.pendingRequests.clear();
+    });
+  }
+
+  async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      let resolved = false;
+
+      // Listen to Centrifuge connection events
+      const onConnected = () => {
+        if (!resolved) {
+          resolved = true;
+          resolve();
+        }
+      };
+
+      const onError = (ctx: any) => {
+        if (!resolved) {
+          resolved = true;
+          reject(new Error(ctx.message || 'Connection error'));
+        }
+      };
+
+      this.centrifuge.on('connected', onConnected);
+      this.centrifuge.on('error', onError);
+
+      // Start connection
+      this.centrifuge.connect();
+
+      // Subscribe to reply channel
+      this.subscription = this.centrifuge.newSubscription(this.replyChannel);
+
+      this.subscription.on('publication', (ctx: any) => {
+        this.handleResponse(ctx.data);
+      });
+
+      this.subscription.on('subscribed', () => {
+        // Subscription successful (optional, we already resolved on 'connected')
+      });
+
+      this.subscription.on('error', (ctx: any) => {
+        // Error code 105 = "already subscribed" (server-side subscription from JWT)
+        // This is not an error - the channel is already active via server-side subscription
+        if (ctx.error?.code === 105) {
+          // This is fine, server-side subscription exists
+        } else {
+          this.logger.error(`Subscription error for ${this.replyChannel}:`, ctx.error);
+        }
+      });
+
+      this.subscription.subscribe();
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    // Unsubscribe from all event channels
+    this.unsubscribeAll();
+
+    // Unsubscribe from RPC reply channel
+    if (this.subscription) {
+      this.subscription.unsubscribe();
+    }
+
+    this.centrifuge.disconnect();
+  }
+
+  async call<T = any>(method: string, params: any): Promise<T> {
+    const correlationId = this.generateCorrelationId();
+
+    const message = {
+      method,
+      params,
+      correlation_id: correlationId,
+      reply_to: this.replyChannel,
+    };
+
+    // Create promise for response
+    const promise = new Promise<T>((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        this.pendingRequests.delete(correlationId);
+        reject(new Error(`RPC timeout: ${method}`));
+      }, this.timeout);
+
+      this.pendingRequests.set(correlationId, {
+        resolve: (result: T) => {
+          clearTimeout(timeoutId);
+          resolve(result);
+        },
+        reject: (error: Error) => {
+          clearTimeout(timeoutId);
+          reject(error);
+        },
+      });
+    });
+
+    // Publish request
+    await this.centrifuge.publish('rpc.requests', message);
+
+    return promise;
+  }
+
+  private handleResponse(data: any): void {
+    const correlationId = data.correlation_id;
+    if (!correlationId) {
+      return;
+    }
+
+    const pending = this.pendingRequests.get(correlationId);
+    if (!pending) {
+      return;
+    }
+
+    this.pendingRequests.delete(correlationId);
+
+    if (data.error) {
+      pending.reject(new Error(data.error.message || 'RPC error'));
+    } else {
+      pending.resolve(data.result);
+    }
+  }
+
+  private generateCorrelationId(): string {
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+  }
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Channel Subscription API (for gRPC events)
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  /**
+   * Subscribe to a Centrifugo channel for real-time events.
+   *
+   * @param channel - Channel name (e.g., 'bot#bot-123#heartbeat')
+   * @param callback - Callback for received messages
+   * @returns Unsubscribe function
+   *
+   * @example
+   * const unsubscribe = client.subscribe('bot#bot-123#heartbeat', (data) => {
+   *   console.log('Heartbeat:', data);
+   * });
+   *
+   * // Later: unsubscribe when done
+   * unsubscribe();
+   */
+  subscribe(channel: string, callback: (data: any) => void): () => void {
+    // Check if already subscribed
+    if (this.channelSubscriptions.has(channel)) {
+      return () => {}; // Return no-op unsubscribe
+    }
+
+    // Create new subscription
+    const sub = this.centrifuge.newSubscription(channel);
+
+    // Handle publications
+    sub.on('publication', (ctx: any) => {
+      callback(ctx.data);
+    });
+
+    // Handle subscription lifecycle
+    sub.on('subscribed', () => {
+      // Subscription successful
+    });
+
+    sub.on('error', (ctx: any) => {
+      this.logger.error(`Subscription error for ${channel}:`, ctx.error);
+    });
+
+    // Start subscription
+    sub.subscribe();
+
+    // Store subscription
+    this.channelSubscriptions.set(channel, sub);
+
+    // Return unsubscribe function
+    return () => this.unsubscribe(channel);
+  }
+
+  /**
+   * Unsubscribe from a channel.
+   *
+   * @param channel - Channel name
+   */
+  unsubscribe(channel: string): void {
+    const sub = this.channelSubscriptions.get(channel);
+    if (!sub) {
+      return;
+    }
+
+    sub.unsubscribe();
+    this.channelSubscriptions.delete(channel);
+  }
+
+  /**
+   * Unsubscribe from all channels.
+   */
+  unsubscribeAll(): void {
+    if (this.channelSubscriptions.size === 0) {
+      return;
+    }
+
+    this.channelSubscriptions.forEach((sub, channel) => {
+      sub.unsubscribe();
+    });
+    this.channelSubscriptions.clear();
+  }
+
+  /**
+   * Get list of active client-side subscriptions.
+   */
+  getActiveSubscriptions(): string[] {
+    return Array.from(this.channelSubscriptions.keys());
+  }
+
+  /**
+   * Get list of server-side subscriptions (from JWT token).
+   *
+   * These are channels automatically subscribed by Centrifugo server
+   * based on the 'channels' claim in the JWT token.
+   */
+  getServerSideSubscriptions(): string[] {
+    try {
+      // Access Centrifuge.js internal state for server-side subs
+      // @ts-ignore - accessing internal property
+      const serverSubs = this.centrifuge._serverSubs || {};
+      return Object.keys(serverSubs);
+    } catch (error) {
+      return [];
+    }
+  }
+
+  /**
+   * Get all active subscriptions (both client-side and server-side).
+   */
+  getAllSubscriptions(): string[] {
+    const clientSubs = this.getActiveSubscriptions();
+    const serverSubs = this.getServerSideSubscriptions();
+
+    // Combine and deduplicate
+    return Array.from(new Set([...clientSubs, ...serverSubs]));
+  }
+}

package/src/core/client/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Client Module
+ */
+
+export { CentrifugoRPCClient } from './CentrifugoRPCClient';

package/src/core/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Core Module
+ *
+ * Platform-agnostic core functionality (no React)
+ */
+
+// Client
+export { CentrifugoRPCClient } from './client';
+
+// Logger
+export { createLogger, LogsStore, getGlobalLogsStore } from './logger';
+export type { Logger, LoggerConfig } from './logger';
+
+// Types
+export type * from './types';

package/src/core/logger/LogsStore.ts

@@ -0,0 +1,101 @@
+/**
+ * Logs Store
+ *
+ * In-memory store for accumulated logs with circular buffer.
+ * Thread-safe, max capacity, auto-cleanup.
+ */
+
+import type { LogEntry, LogLevel } from '../types';
+
+export class LogsStore {
+  private logs: LogEntry[] = [];
+  private listeners: Set<(logs: LogEntry[]) => void> = new Set();
+  private maxLogs: number;
+
+  constructor(maxLogs: number = 500) {
+    this.maxLogs = maxLogs;
+  }
+
+  /**
+   * Add log entry
+   */
+  add(entry: Omit<LogEntry, 'id' | 'timestamp'>): void {
+    const logEntry: LogEntry = {
+      ...entry,
+      id: `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+      timestamp: new Date(),
+    };
+
+    this.logs.push(logEntry);
+
+    // Keep only last N logs (circular buffer)
+    if (this.logs.length > this.maxLogs) {
+      this.logs = this.logs.slice(-this.maxLogs);
+    }
+
+    // Notify listeners
+    this.notify();
+  }
+
+  /**
+   * Get all logs
+   */
+  getAll(): LogEntry[] {
+    return [...this.logs];
+  }
+
+  /**
+   * Get logs by level
+   */
+  getByLevel(level: LogLevel): LogEntry[] {
+    return this.logs.filter((log) => log.level === level);
+  }
+
+  /**
+   * Get logs by source
+   */
+  getBySource(source: LogEntry['source']): LogEntry[] {
+    return this.logs.filter((log) => log.source === source);
+  }
+
+  /**
+   * Clear all logs
+   */
+  clear(): void {
+    this.logs = [];
+    this.notify();
+  }
+
+  /**
+   * Subscribe to log changes
+   */
+  subscribe(listener: (logs: LogEntry[]) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /**
+   * Notify all listeners
+   */
+  private notify(): void {
+    const logs = this.getAll();
+    this.listeners.forEach((listener) => listener(logs));
+  }
+
+  /**
+   * Get logs count
+   */
+  get count(): number {
+    return this.logs.length;
+  }
+}
+
+// Singleton instance
+let globalStore: LogsStore | null = null;
+
+export function getGlobalLogsStore(): LogsStore {
+  if (!globalStore) {
+    globalStore = new LogsStore();
+  }
+  return globalStore;
+}

package/src/core/logger/createLogger.ts

@@ -0,0 +1,79 @@
+/**
+ * Create Logger
+ *
+ * Creates logger that writes to both console (consola) and LogsStore.
+ * Dual output: developer console + UI logs viewer.
+ */
+
+import { createConsola } from 'consola';
+import type { LogEntry, LogLevel } from '../types';
+import { getGlobalLogsStore } from './LogsStore';
+
+export interface Logger {
+  debug: (message: string, data?: unknown) => void;
+  info: (message: string, data?: unknown) => void;
+  success: (message: string, data?: unknown) => void;
+  warning: (message: string, data?: unknown) => void;
+  error: (message: string, error?: Error | unknown) => void;
+}
+
+export interface LoggerConfig {
+  source: LogEntry['source'];
+  isDevelopment?: boolean;
+  tag?: string;
+}
+
+export function createLogger(config: LoggerConfig): Logger {
+  const { source, isDevelopment = process.env.NODE_ENV === 'development', tag = 'Centrifugo' } = config;
+
+  const logsStore = getGlobalLogsStore();
+
+  // Console logger (consola)
+  const consola = createConsola({
+    level: isDevelopment ? 4 : 3,
+    formatOptions: {
+      colors: true,
+      date: false,
+      compact: !isDevelopment,
+    },
+  }).withTag(tag);
+
+  const log = (level: LogLevel, message: string, data?: unknown) => {
+    // Add to LogsStore (always)
+    logsStore.add({
+      level,
+      source,
+      message,
+      data,
+    });
+
+    // Write to console (only in development)
+    if (!isDevelopment) return;
+
+    switch (level) {
+      case 'debug':
+        consola.debug(message, data || '');
+        break;
+      case 'info':
+        consola.info(message, data || '');
+        break;
+      case 'success':
+        consola.success(message, data || '');
+        break;
+      case 'warning':
+        consola.warn(message, data || '');
+        break;
+      case 'error':
+        consola.error(message, data || '');
+        break;
+    }
+  };
+
+  return {
+    debug: (message, data) => log('debug', message, data),
+    info: (message, data) => log('info', message, data),
+    success: (message, data) => log('success', message, data),
+    warning: (message, data) => log('warning', message, data),
+    error: (message, error) => log('error', message, error),
+  };
+}

package/src/core/logger/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Logger Module
+ *
+ * Exports logger utilities
+ */
+
+export { createLogger } from './createLogger';
+export type { Logger, LoggerConfig } from './createLogger';
+export { LogsStore, getGlobalLogsStore } from './LogsStore';

package/src/core/types/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Core Types for Centrifugo Package
+ *
+ * Type-only exports, no runtime dependencies
+ */
+
+// ─────────────────────────────────────────────────────────────────────────
+// Log Types
+// ─────────────────────────────────────────────────────────────────────────
+
+export type LogLevel = 'debug' | 'info' | 'success' | 'warning' | 'error';
+
+export interface LogEntry {
+  id: string;
+  timestamp: Date;
+  level: LogLevel;
+  source: 'client' | 'provider' | 'subscription' | 'system';
+  message: string;
+  data?: unknown;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Connection Types
+// ─────────────────────────────────────────────────────────────────────────
+
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
+
+export interface CentrifugoToken {
+  token: string;
+  centrifugo_url: string;
+  channels: string[];
+  expires_at: string;
+}
+
+export interface User {
+  id: number;
+  centrifugo?: CentrifugoToken;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Subscription Types
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ActiveSubscription {
+  channel: string;
+  type: 'client' | 'server';
+  subscribedAt: number; // timestamp
+  data?: unknown;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Client Types
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface CentrifugoClientConfig {
+  url: string;
+  token: string;
+  userId: string;
+  timeout?: number;
+  onLog?: (entry: Omit<LogEntry, 'id' | 'timestamp'>) => void;
+}
+
+export interface CentrifugoClientState {
+  isConnected: boolean;
+  isConnecting: boolean;
+  error: Error | null;
+  connectionState: ConnectionState;
+}