websocket-development

mindrally

•

6155 months ago

Source Raw

Best practices and guidelines for building real-time applications with WebSocket communication

Quick Install

npxskills add mindrally/skills--skill websocket-development

Instructions

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

Loading…

Related Skills

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,360