websocket-hub-patterns

What This Skill Does

The websocket-hub-patterns skill provides a robust architectural template for implementing horizontally-scalable WebSocket servers using a Go-based hub pattern. It solves the classic problem of WebSocket isolation, where users connected to different server instances cannot communicate directly. By leveraging Redis Pub/Sub, the skill acts as a message broker between instances. A key feature is the 'Lazy Redis Subscription' mechanism, which optimizes resource consumption by only initiating a Redis subscription channel when the first local client subscribes to a specific topic. This prevents the server from overwhelming Redis with thousands of idle connections. The skill also includes a centralized connection registry, enabling developers to track which user is connected to which specific instance, facilitating targeted messaging and graceful handling of server shutdowns.

Installation

To integrate this pattern into your project, use the OpenClaw command-line interface:

npx clawhub@latest install websocket-hub-patterns

This will provision the boilerplate hub structure, including the necessary channel orchestration and Redis lifecycle management logic.

Use Cases

• Real-time Collaboration: Ideal for document editing tools (like Google Docs clones) where updates need to be broadcast across multiple server nodes.
• Chat Applications: High-concurrency chat systems that require room-based messaging spanning multiple gateway instances.
• Live Operational Dashboards: Monitoring systems where data updates are pushed to clients in real-time, regardless of which instance they are connected to.
• Multi-tenant Gaming Servers: Managing game state updates across distributed clusters.

Example Prompts

1. "OpenClaw, setup a new hub structure for my game server that supports horizontal scaling using the websocket-hub-patterns skill."
2. "Can you show me how to trigger a graceful shutdown of the WebSocket hub to ensure no client messages are dropped during a deployment?"
3. "Refactor my current local-only WebSocket implementation to use the lazy Redis subscription logic provided by the hub patterns skill."

Tips & Limitations

• Scalability Note: While Redis handles the pub/sub effectively, ensure your Redis cluster is sized correctly to handle the volume of message traffic.
• Consistency: The connection registry relies on external state (Redis). Always handle network partitioning scenarios where the registry might be out-of-sync with actual connections.
• Cleanup: Always ensure that when a local subscriber disconnects, the unsubscribe logic successfully closes the Redis channel to avoid memory leaks. The provided pattern handles this, but custom logic extensions should be audited for potential leaks.