Reactive, Kotlin & RxJava

Each style has its own artifact. They contain no Spring code, so they work in any application; the Spring annotations are handled by aspect extensions that live in resilience4j-spring6 and switch on when the matching module is on the classpath.

All four reactive and Kotlin artifacts are in the Resilience4j BOM (the BOM lists resilience4j-reactor, -rxjava2, -rxjava3 and -kotlin), so with the BOM imported they need no version. The starter itself is not in the BOM at 2.4.0 and keeps its explicit version, as on Getting Started. The 2.4.0 artifacts were built against old libraries: the POM of resilience4j-reactor declares reactor-core 3.4.24, resilience4j-rxjava3 declares RxJava 3.0.0, resilience4j-rxjava2 declares RxJava 2.2.8, and resilience4j-kotlin declares Kotlin 1.9.25 and coroutines 1.6.4. In an application, Maven’s mediation and Boot’s dependency management pick the versions that the Boot line manages, and the examples below ran on them:

The dependencies for a Boot 4 service that uses all three styles (keep only the ones you need):

Source: Resilience4j: resilience4j-reactor, resilience4j-rxjava2/3, resilience4j-kotlin and the Resilience4j BOM at v2.4.0. Resolved with mvn dependency:tree on Boot 4.1.1 and 3.5.16. On Boot 3 replace the starter with resilience4j-spring-boot3 and spring-boot-starter-aspectj with spring-boot-starter-aop, and drop spring-boot-starter-webclient, which does not exist there. The Maven setup that compiles Kotlin next to Java is in Concurrency Alternatives.

The readme.io pages for these modules say the reactive library is "not a transitive dependency", and show compile configurations resolved from jCenter(), which was shut down. In the 2.4.0 POMs reactor-core, rxjava (both majors) are compile-scope dependencies, and the Boot-managed version replaces the one in the POM. The Kotlin module lists the Kotlin standard library and coroutines at runtime scope.

The scenario is one WebClient call that returns a Flux<Review>. The configuration is the same for every style on this page, so it is shown once. It is a shared default plus one instance named reviews for each of the five patterns; a 404 for an unknown book is a normal answer, so it is ignored by the breaker and never retried.

Source: Resilience4j: Spring Boot 2 & 3 and the property classes in resilience4j-framework-common at v2.4.0. The YAML is the test configuration of the runs reported below. Every property is described on the page of its module, for example Retry and TimeLimiter. The time limiter’s 400ms and the bulkhead’s maxWaitDuration: 0 are deliberate and are explained in the sections on the operators.

The five annotations work on methods whose return type is Mono or Flux, once resilience4j-reactor is on the classpath. Nothing else changes in the setup of Getting Started: the aspects exist already, and the reactor aspect extensions (for example ReactorCircuitBreakerAspectExt) are registered when reactor.core.publisher.Flux and io.github.resilience4j.reactor.AbstractSubscriber are both on the classpath. The aspect lets the method run, takes the Mono or Flux it returned and applies the matching operator to it with transformDeferred.

Source: Resilience4j: Spring Boot 2 & 3 and the ReactorCircuitBreakerAspectExt source at v2.4.0. This class and ReviewsOperators gave identical results in all four scenarios. The @TimeLimiter, @RateLimiter and @Bulkhead here use the instances of the same name (reviews), which is why the three share one name with the breaker and the retry in the YAML above.

Four details of this example decide whether it works.

transformDeferred wraps what it receives, so the last call is the outermost decorator and the first one to see a subscriber. The order of the aspects is the same idea expressed as numbers: a lower order value is the outer aspect. The defaults make the annotations nest as Retry(CircuitBreaker(RateLimiter(TimeLimiter(Bulkhead(function))))) (see Annotations and aspect order), and the operator chain in ReviewsOperators above is written to give the same nesting.

The order is a decision, not a detail. Two runs show what it changes.

Source: Resilience4j: Spring Boot 2 & 3 and the CircuitBreakerSubscriber source at v2.4.0. Runs on Reactor 3.8.7 with a source that fails with IllegalStateException and, for the last two rows, delays its item by 300 ms against a 50 ms limit.

The last row is the reason the default puts the time limiter inside the breaker: a timeout is exactly the failure a circuit breaker exists to count. Put the time limiter outside only when you want slow calls to be invisible to the breaker. Retrying outside the breaker and the order of the annotations are discussed in depth in Fallbacks & Composition.

The RxJava modules follow the same model: the operators implement RxJava’s FlowableTransformer, SingleTransformer, MaybeTransformer, CompletableTransformer and ObservableTransformer, and you apply them with compose. The five patterns have operators for all five reactive types; the time limiter is a TimeLimiterTransformer and the retry a RetryTransformer, the other three are called …​Operator. Their packages differ between the two majors.

Source: Resilience4j: resilience4j-rxjava examples and the resilience4j-rxjava3 and resilience4j-rxjava2 sources at v2.4.0. The RxJava 2 package names have no rxjava2 segment, which is easy to miss; the RxJava 2 operators were run with CircuitBreakerOperator and RetryTransformer (same outcome as the RxJava 3 run below).

resilience4j-kotlin is a set of extension functions, not an integration: there are no aspects for it and nothing to configure in Spring. You inject the registries as usual and call the extensions.

For each of CircuitBreaker, Retry, RateLimiter, TimeLimiter and the semaphore Bulkhead there are two functions, executeSuspendFunction { } and decorateSuspendFunction { } (which returns a suspend lambda), and a Flow operator named after the pattern: circuitBreaker(…​), retry(…​), rateLimiter(…​), timeLimiter(…​) and bulkhead(…​). There is a Micrometer Timer extension as well. Blocking convenience wrappers (executeFunction, decorateFunction) exist for the same classes. The same client as before:

Source: Resilience4j: resilience4j-kotlin, Kotlin: Asynchronous Flow and the CircuitBreaker.kt source at v2.4.0. The imports are the executeSuspendFunction and the Flow operators from the matching io.github.resilience4j.kotlin.<pattern> packages, plus asFlow from kotlinx.coroutines.reactive and awaitSingle from kotlinx.coroutines.reactor, which is why the Maven snippet has kotlinx-coroutines-reactor. Compiled with the Kotlin Maven plugin of Boot’s parent (Kotlin 2.3.21) and run on Boot 4.1.1 and 3.5.16. The same four scenarios as the Java styles gave the same results for the cases that were run (see the table below).

The nesting rules are the ones you already know. In executeSuspendFunction the outermost block is the outermost pattern; in the Flow chain the last operator is the outermost one, which is the reverse of how it reads. The readme.io page makes the same point: in flowOf(1).retry(…​).timeLimiter(…​) all the retry attempts must fit in the time limiter’s duration.

Everything above exists because blocking a thread used to be expensive. On Java 21 a blocked virtual thread costs almost nothing, and the question becomes whether you need a reactive pipeline for resilience at all. For the Bookshelf the honest answer is often no: the plain annotated methods of the earlier pages, called from virtual threads, give the same protection with code that reads top to bottom. The three concurrency models, their transaction stories and the trade-offs are on Concurrency Alternatives; the JDK mechanics are on Java virtual threads; and the bulkhead specifics, including the measured numbers, are in the Bulkhead: virtual threads section.

The Bookshelf version of the call, on virtual threads (spring.threads.virtual.enabled: true), is the annotation style of the synchronous pages, with the semaphore bulkhead doing the limiting:

Source: Spring Boot: Task execution and scheduling and JEP 444: Virtual Threads. Run with a vt bulkhead of maxConcurrentCalls: 5 and maxWaitDuration: 10s: 50 virtual threads called the method, all 50 completed, the peak concurrency inside it was 5 and the batch took 1.05 s (ten waves of five); every call ran on a virtual thread, and a @Bulkhead(type = THREADPOOL) method reported that its body did not.

Pick the style by what the code already is, not by the pattern.

Mixing is fine at a boundary, and wrong in the middle of a call. A WebFlux controller that calls a blocking, annotated method blocks an event-loop thread; a blocking service that calls block() on a decorated Mono gives up the point of using one.

The same four scenarios were run against WireMock for the Reactor operators, the annotations and the Kotlin extensions. The reviews configuration is the YAML above, in particular maxAttempts: 3, a 6-call window and a 400 ms limit.

Source: the output of the examples above on Boot 4.1.1; every row was identical on Boot 3.5.16. The Kotlin client has no fallback, so the failures reach the caller; add catch or onCompletion to degrade. The delayed-body row shows that a retry outside the time limiter spends the whole budget on every attempt: three attempts of 400 ms cost 1.2 s, so a deadline that the caller sees has to be set around the whole call, see TimeLimiter: a time budget across retries. The last row follows from the 6-call window: two logical calls of three attempts each fill it, the breaker opens, and every later attempt is rejected by the breaker without an HTTP call (the retry still retries a CallNotPermittedException, which is its default, see Retry).

The Java rows show that annotations and operators are equivalent for Mono and Flux, so the choice is style: annotations when the methods are Spring beans and the pattern is the same for every call, operators when the decoration depends on the call, when the code is not a Spring bean, or when the aspect cannot reach it (self-invocation, private methods, see Annotations and aspect order).