Project Reactor — Reactive Streams Library for the JVM

Introduction

Project Reactor is a Reactive Streams implementation for Java, developed by the Spring team at VMware. It provides two core publisher types: Mono (0 or 1 element) and Flux (0 to N elements), enabling composable, non-blocking data pipelines with built-in backpressure. Reactor is the foundation of Spring WebFlux and Spring Data Reactive.

What Project Reactor Does

• Models asynchronous sequences with Flux (many elements) and Mono (single element)
• Provides a rich operator library for transforming, filtering, combining, and error-handling streams
• Implements the Reactive Streams specification with built-in backpressure propagation
• Supports multiple threading strategies via Schedulers (parallel, elastic, single, immediate)
• Integrates with Netty, Spring WebFlux, R2DBC, and other reactive libraries

Architecture Overview

Reactor is built around the Publisher-Subscriber pattern defined by the Reactive Streams specification. Operators are implemented as decorating publishers that form a chain. When a subscriber subscribes, a request signal propagates upstream, activating the data flow with backpressure. Reactor uses Netty's event loop for I/O-bound work and configurable thread pools (Schedulers) for CPU-bound or blocking tasks.

Self-Hosting & Configuration

• Add reactor-core as a Maven or Gradle dependency
• For testing, add reactor-test and use StepVerifier to assert stream behavior
• Use Schedulers.boundedElastic() to wrap blocking calls without starving the event loop
• Enable Reactor's debug mode with Hooks.onOperatorDebug() during development
• For production tracing, use reactor-core-micrometer for metrics and context propagation

Key Features

• Mono and Flux types with 200+ composable operators
• Backpressure-aware with configurable overflow strategies (buffer, drop, error, latest)
• Context propagation for carrying metadata (trace IDs, auth tokens) across async boundaries
• StepVerifier test utility for deterministic verification of reactive sequences
• Built-in retry and timeout operators with exponential backoff support

Comparison with Similar Tools

• RxJava — earlier reactive library for Java; Reactor is lighter and aligned with Spring
• Mutiny (Quarkus) — simpler reactive API with Uni/Multi; Reactor has richer operators
• Kotlin Coroutines Flow — Kotlin-native reactive streams; Reactor targets Java-first
• Java 9 Flow — JDK built-in reactive interfaces; Reactor adds the operator library on top
• Akka Streams — Scala-centric with actor model integration; Reactor is Spring-ecosystem native

FAQ

Q: When should I use Mono vs Flux? A: Use Mono for operations that return zero or one result (database lookups, HTTP calls). Use Flux for streams of multiple items (event feeds, query result sets).

Q: How do I handle blocking code in Reactor? A: Wrap blocking calls with Mono.fromCallable().subscribeOn(Schedulers.boundedElastic()) to offload them from the event loop.

Q: Is Reactor required for Spring WebFlux? A: Yes. Spring WebFlux uses Reactor as its reactive foundation. Controllers return Mono or Flux types.

Q: How do I debug reactive pipelines? A: Enable Hooks.onOperatorDebug() to get assembly-time stack traces, or use checkpoint() operators to add diagnostic markers.

Sources

• https://github.com/reactor/reactor-core
• https://projectreactor.io/docs/core/release/reference/