name: websocket-development
description: Best practices and guidelines for building real-time applications with WebSocket communication

WebSocket Development

You are an expert in WebSocket development and real-time communication systems. Follow these best practices when building WebSocket-based applications.

Core Principles

• Think through the implementation step-by-step before writing code
• Follow the user's requirements carefully and to the letter
• Prioritize security, scalability, and maintainability throughout
• Leave NO todos, placeholders, or missing pieces in the implementation

Connection Management

Establishing Connections

• Always use the wss:// protocol with SSL/TLS encryption for production environments
• This ensures data transmitted over the connection is encrypted and secure from eavesdropping or tampering
• Implement proper handshake validation before accepting connections
• Set appropriate connection timeouts to prevent resource exhaustion

Connection Lifecycle

• Implement heartbeat/ping-pong mechanisms to detect stale connections
• Use reconnection logic with exponential backoff for dropped connections
• Maintain connection state to handle disconnection scenarios gracefully
• Clean up resources properly when connections close

Message Handling

Message Design

• Use structured message formats (JSON with type/payload pattern)
• Include message IDs for request-response correlation
• Implement message versioning for backward compatibility
• Keep message payloads small to reduce latency

Error Handling

• Always include error handling logic for WebSocket connections
• Manage potential disconnections or message failures gracefully
• Implement dead letter handling for unprocessable messages
• Log errors with sufficient context for debugging

Scalability Patterns

Horizontal Scaling

• Use a message broker (Redis Pub/Sub, RabbitMQ) for cross-server communication
• Implement sticky sessions or connection affinity when needed
• Design stateless handlers where possible
• Consider using a dedicated WebSocket gateway service

Performance Optimization

• Buffer messages during brief disconnections
• Implement message batching for high-frequency updates
• Use binary protocols (MessagePack, Protocol Buffers) for bandwidth-sensitive applications
• Monitor connection counts and message throughput

Security Best Practices

Authentication

• Authenticate connections during the handshake phase
• Use token-based authentication (JWT) with proper expiration
• Validate tokens on both connection and periodic intervals
• Implement rate limiting per connection and per user

Authorization

• Validate permissions for each message type/channel
• Implement channel-based access control for pub/sub patterns
• Never trust client-provided data without validation
• Sanitize all incoming message payloads

Framework-Specific Guidelines

Node.js Native WebSocket (v21+)

• Utilize Node.js's built-in WebSocket client for real-time communication to reduce dependencies
• The built-in client simplifies real-time communication and ensures better interoperability
• For servers, use established libraries like ws or framework-specific solutions

Bun Runtime

• Prefer Bun's native capabilities over third-party alternatives
• Use Bun.serve() with WebSocket support instead of separate WebSocket libraries
• Leverage Bun's built-in stream handling and fetch implementation

Browser Clients

• Implement graceful degradation for older browsers
• Use the standard WebSocket API for broad compatibility
• Handle visibility changes to manage connection state
• Implement offline detection and queuing

Testing Strategies

Unit Testing

• Mock WebSocket connections for isolated testing
• Test message serialization/deserialization independently
• Verify error handling paths

Integration Testing

• Test full connection lifecycle scenarios
• Verify reconnection behavior under various failure modes
• Load test with realistic connection counts and message rates

Monitoring and Observability

• Track connection count metrics
• Monitor message latency and throughput
• Alert on connection error rates
• Log connection lifecycle events for debugging

Common Patterns

Pub/Sub Pattern

• Implement channel subscription management
• Use efficient data structures for subscriber lookup
• Handle subscription cleanup on disconnect

Request/Response Pattern

• Correlate requests and responses with unique IDs
• Implement timeout handling for pending requests
• Consider using acknowledgment messages for reliability

Broadcast Pattern

• Optimize for one-to-many message delivery
• Consider message deduplication strategies
• Implement backpressure for slow consumers