WebSocket Load‑Balancing Concept Library for Microservice Architectures

Introduction

WebSocket works well in monolithic applications, but in a microservice environment messages sent from one instance may not reach clients connected to another instance, leading to lost notifications.

Problem & Simple Idea

When service A has two instances (A1, A2) and a client connects through a gateway to A1, a message generated by A2 cannot be delivered to that client because the client is attached to A1.

The simplest fix is to forward A2’s message to A1, which then pushes it to the client.

Solution – Concept Library

A library called Concept‑WebSocket‑LoadBalance provides this functionality with a single configuration annotation.

GitHub repository: https://github.com/Linyuzai/concept/wiki/Concept-WebSocket-LoadBalance

Usage

1. Add the annotation @EnableWebSocketLoadBalanceConcept (together with @EnableDiscoveryClient and @SpringBootApplication) to the main application class:

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

2. Inject WebSocketLoadBalanceConcept into any component that needs to send messages:

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

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

This allows cross‑instance message broadcasting with a single method call.

Abstract Design

The library abstracts a generic Connection interface, with concrete implementations such as WebSocketConnection or TCPConnection. It treats both long‑ and short‑lived connections uniformly.

Forwarding Logic

Each service instance acts as a client to every other instance. When an instance receives a message, it forwards it to its peers, which then deliver it to their own connected clients.

Connection Establishment

Service discovery (Eureka, Nacos, etc.) provides the list of peer instances via DiscoveryClient#getInstances(serviceId). Instances exchange heartbeat messages and automatically reconnect if a peer disappears.

Connection Management

Connections are categorized (real client vs. forwarding client) and stored in a ConnectionRepository. A ConnectionFactory adapts any low‑level connection to the unified Connection model, while MessageEncoder and MessageDecoder handle protocol‑specific serialization.

Message Sending & Selectors

When sending a message, a ConnectionSelector determines which connections should receive it. Built‑in selectors include: UserSelector – delivers to a specific user identified by a header. PathSelector – delivers to connections subscribed to a particular topic/path.

Custom selectors can be implemented by examining message headers and connection metadata.

Conclusion

The library provides a flexible, annotation‑driven way to achieve WebSocket (or any long‑connection) load balancing across microservice instances, with extensible connection types, discovery integration, heartbeat handling, and fine‑grained message routing.