Provide configuration properties for controlling the size of Tomcat's buffers for binary and text WebSocket messages

[mohan-ganesh]

When using Spring Boot with STOMP over WebSockets, applications can easily encounter a CloseStatus[code=1009] error when a client sends a message that exceeds the default buffer size. This is a common scenario in applications that transmit data like Base64-encoded audio, images, or large JSON payloads.

The root cause is that the embedded Tomcat's default WebSocket message buffer size is set to a very low 8192 bytes (8KB). This default is defined in Tomcat's internal constants and there is no override properties available for user to change this value: https://github.com/apache/tomcat/blob/c4c733a4e2dd65fab42434b81339f6ba13ed7301/java/org/apache/tomcat/websocket/Constants.java#L43

When a message exceeds this limit, the connection is abruptly closed with the following log message, which can be confusing to debug:

o.s.w.s.h.LoggingWebSocketHandlerDecorator : StandardWebSocketSession[...] closed with CloseStatus[code=1009, reason=The decoded text message was too big for the output buffer and the endpoint does not support partial messages]

in a normal circumstances you dont even see this log unless you add the additional properties

logging.level.org.springframework.web.socket=DEBUG
logging.level.org.springframework.messaging.simp=DEBUG 

Why This is a Spring Boot Issue
The developer experience for resolving this is not ideal. A developer's first instinct is to configure Spring's own properties, such as:

# This only configures the STOMP message size, not the underlying transport buffer
spring.websocket.messaging.stomp.message-size-limit=512000

However, this property alone is insufficient because it does not affect the underlying Tomcat transport layer's buffer size. To properly solve this, one must dive deep into container-specific configuration by implementing a WebServerFactoryCustomizer, as shown in the reproduction project. This involves casting to a TomcatServletWebServerFactory and accessing the internal WsServerContainer to override the buffer sizes.

This feels like a leaky abstraction. A common requirement like increasing the WebSocket message size should ideally be managed through straightforward properties provided by Spring Boot, abstracting away the specifics of the underlying servlet container (be it Tomcat, Jetty, or Undertow).

How to Reproduce the Issue
I have created a sample project that demonstrates the problem and includes a workaround that can be toggled on or off.

Repository: https://github.com/mohan-ganesh/tts-services

Steps to Reproduce:

1. Clone the repository: git clone https://github.com/mohan-ganesh/tts-services.git

2. Navigate to the project directory.

3. Open src/main/resources/application.properties and ensure the workaround is disabled by setting the following property to false:

4. Run the Spring Boot application: ./mvnw spring-boot:run

5. Open a web browser and go to http://localhost:8080.

6. Click the "Connect" button to establish a WebSocket connection.

7. Click "Start Recording", speak for 5-10 seconds to generate a sufficiently large audio payload, and then click "Stop and Send".

8. Observe the server logs. The application will log a CloseStatus[code=1009] error, and the client will disconnect.

To see the fix in action, you can change server.tomcat.max-websocket-message-size.override back to true and restart the application. The larger message will then be processed successfully.

Suggested Solution
It would significantly improve the developer experience if Spring Boot provided first-class properties to configure the underlying WebSocket message size limits for embedded servers.

First i wanted to check to see community response on this issue and based on the work around that is being done how that can be implemented in sprint-boot framework.

please let me know if you need additional details on recreating the problem or any additional details that would be required..

[wilkinsona]

This can already be configured using properties. Tomcat's documentation describes the relevant settings:

The default buffer size for binary messages is 8192 bytes. This may be changed for a web application by setting the servlet context initialization parameter org.apache.tomcat.websocket.binaryBufferSize to the desired value in bytes.

The default buffer size for text messages is 8192 bytes. This may be changed for a web application by setting the servlet context initialization parameter org.apache.tomcat.websocket.textBufferSize to the desired value in bytes

In a Spring Boot application, servlet context initialization parameters can be set using server.servlet.context-parameters.* properties. For example:

server.servlet.context-parameters.org.apache.tomcat.websocket.binaryBufferSize = 512000
server.servlet.context-parameters.org.apache.tomcat.websocket.textBufferSize = 512000

The documentation is pretty sparse for configuring servlet context parameters using properties. I've opened #47951 to address that.

We can also consider adding some properties specifically for the binary and text buffer sizes. I'll leave this issue open to do that.

[SeoHyeok2]

I'd like to work on this issue. Could you please assign it to me?

[wilkinsona]

Thanks for the offer, @SeoHyeok2, but we're only considering adding more properties at the moment and are not ready to do so. The first step is to get some feedback from @mohan-ganesh on the servlet context parameter approach. That'll be a factor in us deciding whether or not dedicated properties are worth investing in.

[mohan-ganesh]

Hi @wilkinsona,

Thank you so much for the quick and detailed response! I really appreciate you taking the time to review the issue.

The suggestion to use server.servlet.context-parameters.* is a fantastic find and a much cleaner solution than my custom WebServerFactoryCustomizer. Thank you for pointing that out and also for opening #47951 to improve the documentation—that will surely help others.

I'm glad you've kept this issue open as an enhancement to add dedicated, first-class properties. I agree that this would significantly improve discoverability, type-safe and documented as a first-class feature for this common use case.

If you are open to a community contribution for this enhancement, I would be happy to work on preparing a pull request to implement the new dedicated properties seems to be the spring-boot way.

The Proposed Enhancement

The goal would be ,I would add code to the Spring Boot framework itself to introduce new, simpler properties.

This would involve modifying the spring-boot-autoconfigure module to add the new properties and the logic to apply them.

These are NEW properties (suggestive) you would help create

server.tomcat.websocket.max-binary-message-buffer-size=512KB
server.tomcat.websocket.max-text-message-buffer-size=512K

please let me know what are your thoughts on this.

[mohan-ganesh]

hey @wilkinsona just wanted to check to see how we wanted to procceed?

@SeoHyeok2 if you would like to make the necessary changes to add the dedicated properties, please let me know.

[wilkinsona]

We don't know yet, I'm afraid. This issue is in the general backlog which means that it isn't a priority for the team. We're concentrating on finishing off 4.0 at the moment and we'll then have some time to start looking at what might go into 4.1 and beyond.