DEV Community: Fabián Guamán Flores

resilience4cata 1.0.0-RC2: resilience annotations for Java, generated at compile time

Fabián Guamán Flores — Thu, 05 Nov 2026 11:32:08 +0000

resilience4cata 1.0.0-RC2 is on Maven Central, and its API is frozen. Unless feedback shows that something has to change, 1.0.0 will ship with this same API. After that, compatibility is a promise for the whole major version. So this is the moment when your opinion can still change things.

What it is

resilience4cata is a resilience library for Java 21+:

retry, circuit breaker, rate limiter, timeout, bulkhead and fallback;
plus hedging and an adaptive concurrency limit.

You annotate an interface or a class:

public interface PriceClient {

    @Retry(maxAttempts = 3, delay = "100ms")
    @CircuitBreaker(name = "prices")
    @Timeout("2s")
    @Fallback(method = "unknownPrice")
    BigDecimal price(String sku) throws IOException;

    default BigDecimal unknownPrice(String sku, Exception failure) {
        return BigDecimal.ZERO;
    }
}

At compile time, an annotation processor writes a plain Java class next to it, PriceClient$Resilient, that calls each policy directly. It needs no proxy, aspect or agent. Mistakes such as an invalid duration or a fallback with the wrong signature are compile errors, each with a documented error code.

Without a framework, you wrap any implementation:

ResilienceRegistry registry = ResilienceRegistry.builder().build();
PriceClient prices = Resilient.of(PriceClient.class, new HttpPriceClient(), registry);

In Spring Boot, Micronaut or Quarkus, the integration makes the generated class the bean. Each integration also reads the configuration from application.yml or application.properties and adds health checks and metrics, plus a management endpoint in Spring Boot and Micronaut.

Why compile time

Decorators and interceptors cost something on every call, the successful ones included. Generated code calls the policies directly, and a successful call allocates nothing. Measured on the release candidate, on AWS Graviton3 with one thread, against Resilience4j 2.4.0 configured the same way:

Call	resilience4cata	Resilience4j 2.4.0
Retry, first attempt succeeds	1.4 ns, 0 B	22.9 ns, 0 B
Circuit breaker, every call succeeds	1.9 ns, 0 B	89.9 ns, 0 B
Sync timeout	23.6 ns, 0 B	8907.6 ns, 183 B
Bulkhead, slots free	17.3 ns, 0 B	20.1 ns, 0 B

With four threads, the circuit breaker stays at 1.9 ns, and Resilience4j's goes to 849.5 ns. The benchmark notes cover the setup, the fairness adjustments and the cases that are close.

What changed on the way to 1.0

The last API changes. Two small incompatible ones, and nullable result types, which help Kotlin and NullAway users.
A written compatibility promise. It covers what stays compatible within a major version: the Java API, code generated by an older processor, configuration keys, metric names, endpoint JSON and error codes.
Four concurrency races fixed. They were in the bulkhead, the adaptive limit, the rate limiter and the timeout. The concurrency stress tests (jcstress) now also pass on ARM.
New in RC2: a missing annotation processor is an error. Before, beans silently ran unprotected. Now Spring Boot and Micronaut fail at startup, Quarkus fails at build time, and the message names the dependency to add.

Try it

dependencies {
    implementation 'dev.resilience4cata:resilience4cata-all:1.0.0-RC2'
    annotationProcessor 'dev.resilience4cata:resilience4cata-processor:1.0.0-RC2'
}

For Maven, the installation page has the setup; write 1.0.0-RC2 where it shows 0.13.0. Then:

the quickstart takes about five minutes;
there are guides for Spring Boot, Micronaut and Quarkus;
if you use Resilience4j today, start with the migration guide.

Feedback wanted

The most useful feedback is what you would want changed after 1.0 but could not change, because it would break compatibility:

a name, default or annotation attribute that surprised you;
an error message that didn't tell you what to do;
a framework setup that didn't work as documented;
something you had to work around.

Please open an issue or a discussion. "I tried it and it just worked" helps too.

The code is Apache-2.0 on GitHub.

A 1.9 ns circuit breaker: resilience generated at compile time

Fabián Guamán Flores — Tue, 27 Oct 2026 16:40:45 +0000

Most Java resilience libraries wrap each call in decorators at runtime; resilience4cata writes the wrapping code at compile time instead, and a healthy circuit breaker ends up costing about two nanoseconds.

Originally published on resilience4cata.dev.

The problem with decorators

Retries, circuit breakers, timeouts and bulkheads usually sit on the call path as runtime decorators. You wrap a Supplier or a Callable in one function per policy, or let a framework put a proxy in front of your bean that does it for you. It works, it is flexible, and it is how Resilience4j, the library many Java teams use, is built.

It also costs something on every call, including the ones that succeed, which are almost all of them. Each layer is another call through a functional interface, and the policy state behind it is shared by every thread. In a benchmark with one decorated method the JIT sees a single type at each call site and can inline much of it, which is the best case. A real service decorates dozens of methods, and those shared call sites stop being monomorphic.

I wanted to know how cheap the same guarantees could be if the code were written for one method at a time, the way you would write it by hand if you had the patience.

Let the compiler write it

resilience4cata is a set of annotations plus an annotation processor. You annotate an interface:

public interface StockClient {

    @Retry(maxAttempts = 3)
    @CircuitBreaker
    int stock(String sku, int warehouse);
}

At compile time the processor writes StockClient$Resilient, a plain class that implements the interface. This is what it generates (abridged, package names shortened):

@Override
public int stock(String p0, int p1) {
    final RetryPolicy r4c$retry = this.retry0;
    final long r4c$start = r4c$retry.start();
    int r4c$attempts = 0;
    while (true) {
        try {
            return this.r4c$circuitBreaker0(p0, p1);
        } catch (Throwable r4c$e) {
            final long r4c$delay = r4c$retry.onFailure(++r4c$attempts, r4c$e, r4c$start);
            if (r4c$delay < 0 || !r4c$retry.pause(r4c$delay)) {
                throw r4c$e;
            }
        }
    }
}

private int r4c$circuitBreaker0(String p0, int p1) {
    final CircuitBreakerPolicy r4c$cb = this.circuitBreaker0;
    final long r4c$token = r4c$cb.acquire();
    if (r4c$token < 0) {
        throw r4c$cb.rejection();
    }
    final long r4c$started = r4c$cb.startTimer();
    try {
        final int r4c$result = this.delegate.stock(p0, p1);
        r4c$cb.onSuccess(r4c$token, r4c$started);
        return r4c$result;
    } catch (Throwable r4c$e) {
        r4c$cb.onFailure(r4c$token, r4c$started, r4c$e);
        throw r4c$e;
    }
}

Each protected method becomes straight-line code: a loop for the retry, a try block for the breaker, one final field per policy. There are no lambdas, no proxies and no reflection on the call path, and every call site is monomorphic because every method has its own. At runtime you wrap your implementation once:

StockClient client = Resilient.of(StockClient.class, new HttpStockClient(), registry);

The policies behind those fields follow a small protocol (acquire, onSuccess, onFailure) designed so that the success path does as little as possible:

No allocation. Rejections throw one preallocated, stackless exception per policy, and events are only created when someone listens.
No clock read unless a feature needs it. The breaker only times calls when you configure a slow-call threshold.
No shared write when nothing changes. While a breaker is closed and has only seen fast successes, a call reads one field and writes nothing.

That last rule did the most. Under contention, writing a cache line that other cores are reading costs far more than any lock-free trick saves. On an Apple M1 with four threads, the breaker's first version cost 244 ns per successful call; skipping writes while the window holds only fast successes brought it to 10 ns, and reading a single field while healthy to about 3 ns (the full history is on the benchmarks page, section "Circuit breaker, 1 and 4 threads").

The numbers

Every comparison uses equivalent configuration in both libraries, and each adjustment made for fairness is written in the benchmark's Javadoc.

Measured: AWS c7g.xlarge (Graviton3), JDK 21, resilience4cata 0.1.0 vs Resilience4j 2.4.0, time and bytes allocated per call. Raw results: benchmarks page, section "MVP completion (2026-10-24, AWS Graviton3)".

Scenario	Threads	resilience4cata	Resilience4j 2.4.0
Retry, first attempt succeeds	1	1.2 ns, 0 B	22.9 ns, 0 B
Retry, fails once then succeeds	1	6.5 ns, 0 B	61.6 ns, 16 B
Circuit breaker, every call succeeds	1	1.9 ns, 0 B	89.2 ns, 0 B
Circuit breaker, every call succeeds	4	1.9 ns, 0 B	832 ns, 2 B
Bulkhead, full (every call rejected)	1	2.3 ns, 0 B	139 ns, 416 B
Bulkhead, slots free	1	20.5 ns, 0 B	20.4 ns, 0 B
Retry + circuit breaker	1	2.3 ns, 0 B	175 ns, 288 B

The table also shows where the approach does not help:

Some cases are a tie. A bulkhead with free slots takes and gives back a permit with one atomic operation in both libraries: 20.5 ns against 20.4 ns.
Contention still costs hundreds of nanoseconds. With four threads and one call in ten failing, the breaker costs 274 ns (Resilience4j: 910 ns), because every call advances one shared window cursor. Shared counters cost the bulkhead and the rate limiter in the same way.
Async calls allocate. Every async layer returns a new future in both libraries; only the sync paths are allocation-free.
Some rows are not like for like. Resilience4j's retry calls Thread.sleep(0) between attempts, so its row uses a variant without it (its best case). Its TimeLimiter needs a Future, so a synchronous timeout means another thread; that comparison is on the performance page, with that caveat.

Does a nanosecond matter for a call that goes over the network? Rarely on its own. It matters when resilience wraps calls that are usually cheap (a cache, a local service, an in-memory queue), when the same code runs millions of times per second, or when you would rather not think about whether a policy is too expensive to add.

What it costs you

Compile-time generation has trade-offs, and they are deliberate:

The annotation processor is mandatory. There is no reflection fallback: if the generated class is missing, Resilient.of fails at once and names the dependency to add.
Mistakes are compile errors. An invalid duration, an unknown attribute or a fallback with the wrong signature fails the build with a code such as R4C-ATR-001, documented in the error reference.
Configuration is resolved once. Values can come from annotations, properties files, environment variables or Spring, Micronaut and Quarkus configuration, but they are fixed when the registry is built: there is no hot reload, by design.
It is young. The current version is 0.8; until 1.0 the API can still change.

Try it

Two lines in Gradle:

implementation 'dev.resilience4cata:resilience4cata-all:0.10.0'
annotationProcessor 'dev.resilience4cata:resilience4cata-processor:0.10.0'

Then the quickstart protects a flaky call in about five minutes. There are integrations for Spring Boot, Micronaut and Quarkus, a testkit with a manual clock, and a guide for migrating from Resilience4j. The code is Apache-2.0 licensed on GitHub; issues and discussions are welcome.