resilience4cata 1.0.0 is on Maven Central. After four release candidates, it is the first stable release, and from now on compatibility is a written promise for the whole 1.x line.
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 synchronous call allocates nothing: an allocation gate in CI fails the build otherwise. Measured on the release candidate's code, 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 1.0 includes
- Every call shape: synchronous methods,
CompletableFuture/CompletionStage, and ReactorMonoandFlux. - Frameworks: Spring Boot 4.1, Micronaut 5.2 and Quarkus 3.40, also tested inside GraalVM native images.
- Observability: Micrometer and OpenTelemetry metrics with the same names, events, and snapshots of every instance.
- Testing: a testkit with a manual clock and a JUnit extension, so tests of retries, breakers and timeouts never sleep.
- Configuration: named configs and per-instance overrides from properties, environment variables or system properties, resolved once at startup.
How it got here
- Four release candidates and several review rounds, which brought the last API changes, a breaker that records
Errors as failures, and a compile error for annotations that protect nothing. - A missing annotation processor is an error. Spring Boot and Micronaut fail at startup, Quarkus fails at build time, and the message names the dependency to add, instead of beans silently running unprotected.
- Concurrency: races fixed in the bulkhead, the adaptive limit, the rate limiter and the timeout; the jcstress tests run on x86 and ARM.
- A pilot: Spring Boot, Micronaut and Quarkus services on the release from Maven Central, under k6 load with the backend down and then slow. It found that a burst filling a method's own bulkhead could open its breaker; since 1.0.0-RC4 the breaker never records a local limit's rejection.
The compatibility promise
Within 1.x, the compatibility page promises that these stay compatible: the Java API (binary and source), code generated by an older processor running on a newer runtime, the annotations, configuration keys, integration properties, metric names and tags, the snapshot JSON and the error codes. CI checks them on every change: japicmp and the generated code against the last release, and contract files for the rest.
Try it
dependencies { implementation 'dev.resilience4cata:resilience4cata-all:1.0.0' annotationProcessor 'dev.resilience4cata:resilience4cata-processor:1.0.0' } For Maven and the BOM, see the installation page. 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.
The documentation is in English, Spanish, Portuguese and Chinese.
Feedback wanted
Please open an issue for anything that surprised you, an error message that didn't tell you what to do, or a framework setup that didn't work as documented. "I tried it and it just worked" helps too.
The code is Apache-2.0 on GitHub.
