netty-websocket-spring-boot-starter for Spring Boot 4

Why netty-websocket-spring-boot-starter Runs WebSockets Separately

netty-websocket-spring-boot-starter addresses Java applications that need WebSocket server endpoints without building the Netty server lifecycle by hand. Its intended users are Spring Boot developers who prefer annotations such as @ServerEndpoint and @OnMessage to imperative listener registration. The starter is aimed at servers, chat systems and other applications that receive WebSocket messages on a Netty listener and invoke application code through annotated methods.

The important architectural detail is that WebSocket does not automatically join the application's main HTTP server. The README states that WebSocket uses its own Netty listener and that server.port does not configure it. This separates connection handling and deployment decisions from the Spring Boot web port, but it also means an application can accidentally expose endpoints on a port that differs from the one used by its controllers. The quick-start example assigns /ws to port expression ${ws.port:8081}, making 8081 the effective default there while preserving port 80 as the annotation default for compatibility.

That design is useful when a service wants a dedicated WebSocket entry point or when another service already occupies its normal HTTP port. It is less convenient when infrastructure assumes that every application endpoint is reachable through one port. Separate listeners also need separate deployment, health, firewall and TLS decisions. The README does not describe how the standalone listener is shut down or how multiple server instances coordinate, so those details would need confirmation before adoption.

Annotation Callbacks and Netty Message Flow

The starter scans Spring-managed code for classes annotated with @ServerEndpoint and registers each one as a WebSocket endpoint. Configuration lives on that annotation rather than in a separate configuration class. A client handshake establishes the connection, Netty emits channel events, and the starter dispatches those events to methods annotated with lifecycle and message callbacks.

Text frames can reach a method annotated with @OnMessage, with Session and String among the documented injectable arguments. Binary data follows a separate @OnBinary path with Session and byte[]. Lower-level Netty events can be handled through @OnEvent with Session and Object. The lifecycle annotations are @BeforeHandshake, @OnOpen, @OnClose and @OnError. The documented injection types are limited by callback type: handshake and open handlers receive Session and HttpHeaders, close handlers receive Session, and error handlers receive Session and Throwable.

This callback structure maps application concerns to protocol stages without requiring a handler object to be exposed in Spring configuration. By default, useEventExecutorGroup is true and eventExecutorGroupThreads is 16. Message, close and event callbacks move to a business executor, while handshake and open callbacks remain on the Netty I/O thread. Applications must account for that division. Work placed in an open callback still runs on the I/O thread.

The pipeline also includes explicit resource controls. maxFramePayloadLength defaults to 65536, and maxMessagePayloadLength defaults to 1048576, or 1 MiB. The latter counts all fragments in a decoded message and also bounds decompression workspace when compression is enabled. A message that requires a larger decoded size will not fit the default and must be evaluated against explicit application limits rather than handled by raising a browser-side frame size.

Adding the 1.0.0 Starter and First Text Echo

Version 1.0.0 is intended for JDK 17 or later and Spring Boot 4 with Spring Framework 7. Add the dependency to the existing Spring Boot project. The dependency transitively includes Spring Boot basics, and the README says no extra @Component or manual exporter registration is required.

<dependency>
    <groupId>org.yeauty</groupId>
    <artifactId>netty-websocket-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Place the endpoint inside the main application's package or a subpackage. This first handler accepts text messages and sends the same value back to the client:

@ServerEndpoint(path = "/ws", port = "${ws.port:8081}")
public class MyWebSocket {
    @OnMessage
    public void onMessage(Session session, String message) {
        session.sendText(message);
    }
}

After starting the existing @SpringBootApplication, connect to ws://127.0.0.1:8081/ws. Sending hello should produce a hello response:

const ws = new WebSocket("ws://127.0.0.1:8081/ws");
ws.onopen = () => ws.send("hello");
ws.onmessage = event => console.log(event.data);

The console entry documented by the README is hello. If no connection appears, first verify ws.port or the annotation's explicit port. The endpoint is not expected on server.port merely because it belongs to the same Spring Boot application.

Package Scanning, Listener Configuration and Port Boundaries

Endpoint discovery follows normal package placement. Classes under the application's main package or a subpackage can be found without extra configuration. For an endpoint located outside that hierarchy, the README directs developers to add @EnableWebSocket with scanBasePackages set to the package containing the endpoints.

Each @ServerEndpoint can define path, host and port along with Netty client and child-channel options. The default host is 0.0.0.0, which listens on all local addresses. The default port is 80, unless the endpoint or application property selects another value. Setting port to 0 requests a random available port, but the README only explains obtaining that assigned value through its multi-endpoint discussion. No complete property or API example for reading the assigned port is present in the README.

The listener settings expose practical controls such as bossLoopGroupThreads, workerLoopGroupThreads, useCompressionHandler and TCP buffer options. Idle handlers are added only when readerIdleTimeSeconds, writerIdleTimeSeconds or allIdleTimeSeconds is nonzero. The write water-mark table also contains a documented naming mismatch: both high and low entries refer to ChannelOption.WRITE_BUFFER_WATER_MARK in practice. That is an adoption concern for operators because Netty's actual option choice determines the behavior, not the friendly configuration label alone.

TLS-related annotation properties mirror Spring Boot key-store, trust-store and password configuration keys. The README table ends after sslTrustStore, so it does not establish the complete set of supported SSL modes or client-authentication behavior. Teams requiring TLS should inspect the remaining documentation and configuration implementation before deployment.

Version Boundaries, Maintenance and License

The release line changed substantially with v1.0.0. That release targets Spring Boot 4 and Spring Framework 7, requires JDK 17 or later, and lists Spring Boot 4.1.1 as its tested baseline. CI covers JDK 17 and 21. Spring Boot 3 users are explicitly directed to remain on 0.13.x and read the migration notes before upgrading, so selecting the newest artifact without checking the application's framework generation would be a mistake.

Netty is also part of the compatibility surface. The starter defaults to Netty 4.2.18.Final, while Netty 4.2.17.Final as managed by Boot 4.1.1 is also described as tested. The README does not claim that every Netty patch or Boot patch has been tested and asks users to validate other combinations. Dependency management can therefore override the starter's expected Netty version. This is a specific upgrade check, not a generic caution about library compatibility.

The repository is not archived, and its last push was on 2026-09-25. Version 1.0.0 was released on the same date. That supports treating the release as recent, but it does not remove the cost of validating a new major compatibility line. The project is licensed under Apache-2.0. The repository includes a LICENSE file, which is the appropriate text to review for redistribution, notice and modification obligations when integrating the starter into a distributed product.

Upgrade work will likely include checking the framework generation, JDK, Netty resolution and changed callback behavior. The 0.13.x line should not be replaced blindly with a Spring Boot 4 release.

Spring WebSocket as the Native-Stack Alternative

The direct alternative is Spring's own WebSocket support, which the starter's documentation compares with in its description of annotation-like development. The documented difference in operation is that this starter creates its own Netty WebSocket listener and configures that listener through @ServerEndpoint. Spring's native WebSocket facilities are not documented in this repository, so a precise comparison of their handler APIs, container deployment or message-size defaults would go beyond what the README establishes.

That comparison matters when an application is already designed around a single Spring-managed server. Choosing the starter means accepting an independently configured port and Netty channel options. Choosing the native Spring model would avoid relying on this starter's separate listener, although the README does not specify its configuration details.

It is the wrong choice for Spring Boot 3 applications that have not scheduled a framework upgrade, systems that require messages larger than the 1 MiB decoded-message default without adjusting configuration, or deployments where every endpoint must remain on the main server port. It is more relevant to teams already targeting the documented Spring Boot 4 baseline and comfortable with Netty-specific listener settings.

Editorial conclusion

Application teams that already use JDK 17 or later with Spring Boot 4 and prefer annotation-driven handlers over Spring's native WebSocket model should consider this starter. Teams on Spring Boot 3 should remain on 0.13.x, while projects that require one shared HTTP port or messages above 1 MiB need a different design or explicit configuration changes. Verify the exact JDK, Spring Boot, Spring Framework and Netty combination first, then confirm whether the separate listener and default payload ceiling match the application architecture.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. YeautyYE/netty-websocket-spring-boot-starter on GitHub