WebSocket Load Balancing Across Microservices Using a Single Annotation

Background

WebSocket works well in a monolithic application, but in a micro‑service architecture a client connected to one instance may miss messages sent by another instance because load‑balancing routes the client to a single server.

For example, service A has two instances A1 and A2. The client connects to A1 via the gateway; when A2 wants to broadcast a message, the client does not receive it.

The simplest fix is to forward messages from A2 to A1, which then pushes them to the client.

Solution Overview

A small library is provided that encapsulates this forwarding logic behind a single configuration annotation, eliminating manual forwarding code.

Usage

1. Add the annotation to the Spring Boot entry class:

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

2. Inject WebSocketLoadBalanceConcept where a message needs to be sent:

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

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

This makes cross‑instance message sending as easy as calling a method.

Abstract Design

The library abstracts long‑connection handling into a top‑level Connection interface. Implementations such as WebSocketConnection or TCPConnection provide protocol‑specific behavior.

To manage connections, the following components are defined: ConnectionSubscriber: each instance subscribes to messages from other instances. ConnectionServerManager: discovers other service instances (via Spring Cloud DiscoveryClient, Eureka, Nacos, etc.). ConnectionFactory: adapts any Connection into a unified object. MessageEncoder / MessageDecoder: handle protocol‑specific encoding. MessageCodecAdapter: bridges different codecs.

Heart‑beat detection and automatic reconnection are built in; if a heartbeat is missed, the connection is closed and re‑established after re‑discovering instances.

Message Routing

Messages are routed through a ConnectionSelector. Custom selectors can filter connections based on metadata or message headers.

Examples:

User‑specific delivery : store userId in Connection.metadata and add the same userId as a header in the message. UserSelector matches connections with the same userId.

Topic/path based delivery : use a path string as a topic; PathSelector matches connections whose path matches the message header.

Both selectors are configurable and can be enabled via properties.

Implementation Highlights

The library provides concrete classes such as: DiscoveryConnectionServerManager – uses Spring Cloud service discovery to obtain instance lists. ReactiveWebSocketConnection – a reactive WebSocket implementation. ConnectionLoadBalanceConcept – the core component that exposes the send method.

All components work together to automatically establish inter‑instance connections, forward messages, and allow fine‑grained targeting without additional middleware.

Conclusion

By abstracting long‑connection handling into a set of interfaces and providing a simple annotation, the library turns a complex cross‑instance WebSocket broadcasting problem into a plug‑and‑play solution, while remaining extensible for other protocols such as TCP, HTTP, or MQ.