AgentSkillsCN

websocket-development

构建 WebSocket 通信的实时应用的最佳实践与指南

SKILL.md
--- frontmatter
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