WebSocket Load Balancing Across Microservice Instances Using a Configurable Annotation

WebSocket works well for monolithic applications, but in a micro‑service environment messages may be lost when different instances handle client connections. The author describes a simple solution: forward messages from one instance to another so all clients receive them.

To implement this, a library is created that can be enabled with a single annotation on the Spring Boot entry class:

@EnableWebSocketLoadBalanceConcept
@EnableDiscoveryClient
@SpringBootApplication
public class AServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(AServiceApplication.class, args);
    }
}

In a controller, the WebSocketLoadBalanceConcept bean is injected to send messages across instances:

@RestController
@RequestMapping("/ws")
public class WsController {
    @Autowired
    private WebSocketLoadBalanceConcept concept;

    @RequestMapping("/send")
    public void send(@RequestParam String msg) {
        concept.send(msg);
    }
}

The library abstracts long‑connection clustering by defining a top‑level Connection interface, with implementations such as WebSocketConnection and TCPConnection . A ConnectionSubscriber interface allows services to subscribe to messages from other instances, and can be backed by discovery services, MQ, or HTTP.

Service discovery (e.g., Spring Cloud DiscoveryClient) provides the list of peer instances, and each instance establishes bidirectional connections, sends heartbeat messages, and automatically reconnects when needed. Connections are categorized and managed via a ConnectionFactory and stored in a repository.

Message routing is handled by a ConnectionSelector . The default selector forwards to all connections, but custom selectors (e.g., UserSelector , PathSelector ) enable targeted delivery based on message headers such as user ID or topic path.

Overall, the library offers a plug‑and‑play solution for reliable WebSocket communication in distributed systems, reducing boilerplate code and allowing developers to focus on business logic.