Mastering Backpressure in Spring WebFlux: Strategies and Code Examples

Introduction

In modern web development reactive programming is popular, and backpressure is a key concept for controlling data flow between producers and consumers.

This article explains what backpressure is, how it works in Spring WebFlux, and which strategies can be used.

What is Backpressure?

Backpressure occurs when the data production rate exceeds the consumption rate. It is a flow‑control mechanism that tells the producer how much data the consumer is ready to handle.

Think of a pipe: excessive pressure can cause a rupture, while a valve reduces pressure to keep the flow safe and efficient.

Backpressure Strategies

Buffer : store data in a buffer until the consumer is ready.

Drop : discard excess data when the consumer cannot keep up.

Latest : keep only the most recent item, dropping earlier unprocessed items.

Error : emit an error when the system is overloaded.

Backpressure in Network Protocols

Understanding backpressure in Spring WebFlux starts with TCP’s flow‑control mechanisms.

TCP Flow Control

TCP guarantees reliable, ordered delivery and uses flow control to prevent the sender from overwhelming the receiver.

Main features:

Receive window : tells the sender how much data the receiver can accept.

Transmission rate control : sender adjusts speed based on the window size.

Feedback : when the receiver’s buffer is full, the window shrinks, signaling the sender to slow down.

This is the byte‑level form of backpressure.

Backpressure in WebFlux

Spring WebFlux runs on Netty, which uses TCP. TCP works with bytes, while the application works with logical objects or messages.

Main characteristics of WebFlux backpressure:

Event‑to‑byte conversion : WebFlux translates high‑level events into bytes.

Event queuing : events accumulate when the consumer has not requested more items.

Lack of object‑level control : TCP only sees bytes, not application‑level boundaries.

Slow consumer problem : a fast producer can overflow the queue, increasing latency and resource usage.

Visualizing the Backpressure Process

The following steps illustrate how backpressure works between a client and a server.

Process Steps

1. Client sends request : The client initiates an HTTP request for a data stream.

2. Server responds : The server starts sending data as a byte stream over TCP.

3. Decode and add to Flux : The client receives bytes, converts them to logical objects, and queues them in a Flux.

4. Consumer pulls items : The consumer subscribes to the Flux and pulls items for processing.

5. Slow consumer fills queue : If processing is slow, the queue fills up.

6. Buffer‑overflow signal : When the Flux buffer is full, a signal propagates to TCP, indicating overload.

7. Server stops sending : The server halts transmission until the client frees buffer space.

8. Consumer releases space : As items are processed, space in the Flux queue becomes available.

9. Transmission resumes : The server resumes sending data at a rate matching the consumer’s capacity.

Using Backpressure in Spring WebFlux

Below is a simple service that retrieves a data stream with WebClient.

Project Setup

Assume a service that must handle real‑time data from an external API.

Fetching Data with WebClient

@Service
public class DataService {
    private static final Logger log = LoggerFactory.getLogger(DataService.class);
    private final WebClient webClient;

    public DataService(WebClient.Builder webClientBuilder) {
        this.webClient = webClientBuilder.baseUrl("https://external-api.com").build();
    }

    public Flux<Data> getData() {
        var dataFlux = webClient.get()
                .uri("/data-stream")
                .retrieve()
                .bodyToFlux(Data.class);
        return dataFlux;
    }
}

Flux<Data>

: a reactive stream of data objects. /data-stream: endpoint that returns a data stream.

Handling Backpressure

By default, a Flux buffers up to 256 elements before applying a backpressure strategy.

onBackpressure* Operators

Spring WebFlux provides several operators to define behavior when backpressure occurs.

onBackpressureBuffer

Accumulates data in a buffer and handles overflow.

public Flux<Data> getDataBuffer() {
    var dataFlux = webClient.get()
            .uri("/data-stream")
            .retrieve()
            .bodyToFlux(Data.class)
            .onBackpressureBuffer(100, data -> {
                // overflow handling
                log.error("Buffer overflow, data lost: {}", data);
            });
    return dataFlux;
}

onBackpressureDrop

Drops items when the consumer cannot keep up.

public Flux<Data> getDataDrop() {
    var dataFlux = webClient.get()
            .uri("/data-stream")
            .retrieve()
            .bodyToFlux(Data.class)
            .onBackpressureDrop(data -> {
                // handle dropped data
                log.warn("Data dropped due to overflow: {}", data);
            });
    return dataFlux;
}

onBackpressureLatest

Keeps only the latest element, discarding earlier unprocessed ones.

public Flux<Data> getDataLatest() {
    var dataFlux = webClient.get()
            .uri("/data-stream")
            .retrieve()
            .bodyToFlux(Data.class)
            .onBackpressureLatest();
    return dataFlux;
}

onBackpressureError

Emits an OverflowException when the buffer overflows.

public Flux<Data> getDataError() {
    var dataFlux = webClient.get()
            .uri("/data-stream")
            .retrieve()
            .bodyToFlux(Data.class)
            .onBackpressureError();
    return dataFlux;
}

Conclusion

We discussed what backpressure is, how it enables efficient data‑flow management between producers and consumers, and how to use Spring WebFlux operators to prevent buffer overflows and keep systems stable under high load. Apply these techniques to achieve optimal performance in your reactive applications.