Resilience4cata – retries and circuit breakers written at compile time

Annotation-driven resilience for plain Java 21+: retry, hedging, circuit breaker, rate limiter, adaptive concurrency limit, timeout, bulkhead and fallback, declared with annotations that work without Spring, CDI, AspectJ or agents. A compile-time annotation processor turns them into plain, straight-line Java that calls an allocation-free policy protocol, so the overhead stays in the low nanoseconds and the success path allocates nothing.

Sync and async (CompletionStage), interfaces and annotated classes, composed annotations, named configurations with external overrides, typed events and snapshots, a programmatic Pipeline for code you cannot annotate, and a testkit with a manual clock.

Documentation: resilience4cata.dev (English and Spanish). Status: 0.8.0 on Maven Central; names can still change before 1.0.

Java 21 or newer. Two lines: resilience4cata-all (core, the annotations and external configuration) and the annotation processor, which is mandatory and goes only on the annotation processor path.

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

Maven:

<dependency> <groupId>dev.resilience4cata</groupId> <artifactId>resilience4cata-all</artifactId> <version>0.8.0</version> </dependency> <!-- in the maven-compiler-plugin <configuration> --> <annotationProcessorPaths> <path> <groupId>dev.resilience4cata</groupId> <artifactId>resilience4cata-processor</artifactId> <version>0.8.0</version> </path> </annotationProcessorPaths>

The Gradle Kotlin DSL, the BOM and the individual modules (to keep the annotations compile-only), testkit, IDEs, JPMS and other annotation processors (Lombok, MapStruct) are covered in installation. For Spring Boot 4.1+, resilience4cata-spring configures the registry from application.yml and protects annotated beans without AOP (Spring Boot guide). For Micronaut 5.2+ (Java 25), resilience4cata-micronaut does the same (Micronaut guide).

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; } }

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

BigDecimal price = prices.price("sku-1"); // retried, timed out after 2 s, guarded by the "prices" breaker

The processor generates PriceClient$Resilient at compile time; a wrong attribute or fallback signature is a compile error. Non-final classes can be annotated too (Resilient.create(...)), and then calls the object makes to itself are protected as well. The quickstart runs this example end to end in five minutes.

Measured with JMH against Resilience4j 2.4.0 under equivalent configuration, on AWS c7g.xlarge (4 Graviton3 cores, Amazon Corretto 21), time and allocation per call:

Not every case is a win (the free bulkhead is a tie), and most real calls take milliseconds, so the point is near-zero overhead that keeps scaling with threads. The sync timeout measured 23.7 ns in a later run, a difference still under investigation. Methods, every result (also on an Apple M1), regressions and fairness adjustments are in benchmarks. An allocation gate (./gradlew :benchmark:allocationCheck, run in CI on every pull request) fails the build if a sync success or rejection path starts allocating.

The site at resilience4cata.dev is the Markdown in docs/ (a Docsify site, pre-rendered for search engines by the site module; preview it with ./gradlew :site:serve). Good places to start:

The documentation is bilingual. English is the source of truth; the Spanish version has the same pages: documentación en español (inicio rápido).

./gradlew build compiles, tests and builds the Javadoc of every module (the build runs on JDK 17 or newer and compiles with a Java 21 toolchain). ./gradlew publishToMavenLocal installs the artifacts in your local Maven repository.