@djangocfg/centrifugo 2.1.18 → 2.1.19

package/package.json

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

package/src/core/utils/channelValidator.ts

@@ -0,0 +1,118 @@
+/**
+ * Channel name validation utilities for Centrifugo
+ *
+ * Helps detect common mistakes with channel naming that can lead to permission errors.
+ */
+
+export interface ChannelValidationResult {
+  valid: boolean;
+  warning?: string;
+  suggestion?: string;
+}
+
+/**
+ * Validates Centrifugo channel name and detects potential issues.
+ *
+ * Common issues:
+ * - Using `#` for namespace separator (should use `:`)
+ * - User-limited channels without proper JWT token setup
+ *
+ * @param channel - Channel name to validate
+ * @returns Validation result with warnings and suggestions
+ *
+ * @example
+ * ```ts
+ * // ❌ Bad: might be interpreted as user-limited channel
+ * validateChannelName('terminal#session#abc123')
+ * // Returns: { valid: false, warning: "...", suggestion: "Use terminal:session:abc123" }
+ *
+ * // ✅ Good: proper namespace separator
+ * validateChannelName('terminal:session:abc123')
+ * // Returns: { valid: true }
+ * ```
+ */
+export function validateChannelName(channel: string): ChannelValidationResult {
+  // Check for multiple # symbols (potential user-limited channel misuse)
+  const hashCount = (channel.match(/#/g) || []).length;
+
+  if (hashCount >= 2) {
+    // Pattern: namespace#something#something
+    // This might be interpreted as user-limited channel: namespace#user_id#channel
+    const parts = channel.split('#');
+    const [namespace, possibleUserId, ...rest] = parts;
+
+    // Check if second part looks like a user ID (numeric)
+    const isNumericUserId = /^\d+$/.test(possibleUserId);
+
+    if (!isNumericUserId && possibleUserId) {
+      // Non-numeric second part after # - likely a mistake
+      const suggestion = channel.replace(/#/g, ':');
+
+      return {
+        valid: false,
+        warning: `Channel "${channel}" uses '#' separator which Centrifugo interprets as user-limited channel boundary. ` +
+                 `The part "${possibleUserId}" will be treated as user_id, which may cause permission errors if not in JWT token.`,
+        suggestion: `Use ':' for namespace separation: "${suggestion}"`
+      };
+    }
+
+    if (isNumericUserId) {
+      return {
+        valid: true,
+        warning: `Channel "${channel}" appears to be a user-limited channel (user_id: ${possibleUserId}). ` +
+                 `Make sure your JWT token's "sub" field matches "${possibleUserId}".`,
+      };
+    }
+  }
+
+  // Single # is okay for user-limited channels like "user#123"
+  if (hashCount === 1) {
+    const [namespace, userId] = channel.split('#');
+    if (userId && !/^\d+$/.test(userId) && userId !== '*') {
+      // Non-numeric user_id (not a wildcard) - might be a mistake
+      const suggestion = channel.replace('#', ':');
+      return {
+        valid: false,
+        warning: `Channel "${channel}" uses '#' but "${userId}" doesn't look like a user_id. ` +
+                 `This might cause permission issues.`,
+        suggestion: `Consider using ':' instead: "${suggestion}"`
+      };
+    }
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Log channel validation warnings to console (development only).
+ *
+ * @param channel - Channel name to validate
+ * @param logger - Logger instance (optional)
+ */
+export function logChannelWarnings(
+  channel: string,
+  logger?: { warning: (msg: string) => void }
+): void {
+  if (process.env.NODE_ENV === 'production') {
+    return; // Skip in production
+  }
+
+  const result = validateChannelName(channel);
+
+  if (!result.valid && result.warning) {
+    const message = `[Centrifugo Channel Warning]\n${result.warning}${
+      result.suggestion ? `\n💡 Suggestion: ${result.suggestion}` : ''
+    }`;
+
+    if (logger?.warning) {
+      logger.warning(message);
+    } else {
+      console.warn(message);
+    }
+  } else if (result.warning) {
+    // Valid but has informational warning
+    if (logger?.warning) {
+      logger.warning(`[Centrifugo] ${result.warning}`);
+    }
+  }
+}

package/src/hooks/useSubscription.ts

@@ -15,6 +15,7 @@
 import { useEffect, useCallback, useRef, useState } from 'react';
 import { useCentrifugo } from '../providers/CentrifugoProvider';
 import { createLogger } from '../core/logger';
+import { logChannelWarnings } from '../core/utils/channelValidator';
 
 export interface UseSubscriptionOptions<T = any> {
   channel: string;
@@ -76,6 +77,9 @@ export function useSubscription<T = any>(
       return;
     }
 
+    // Validate channel name and log warnings (dev only)
+    logChannelWarnings(channel, logger);
+
     logger.info(`Subscribing to channel: ${channel}`);
 
     try {