/java-resilience

name: java-resilience
description: Use when the user asks to add resilience patterns, handle service failures, implement circuit breaker, retry, rate limiter, bulkhead, or timeout in a Spring Boot project using Resilience4J.
version: 1.0.0
authors: [java-plugins contributors]
tags: [java, spring-boot, resilience4j, circuit-breaker, retry, rate-limiter, bulkhead, timeout]
allowed-tools: [Read, Glob, Grep, Edit, Write]

Resilience4J Skill

Detect the existing setup, then apply the correct pattern.

Step 1 — Detect setup

Check `pom.xml` or `build.gradle`:

• `resilience4j-spring-boot3` → Spring Boot 3.x (use `io.github.resilience4j:resilience4j-spring-boot3`)
• `resilience4j-spring-boot2` → Spring Boot 2.x
• `spring-cloud-starter-circuitbreaker-resilience4j` → Spring Cloud Circuit Breaker abstraction
• None present → offer to add (recommend `resilience4j-spring-boot3` for Boot 3.x)

Check Java version: Java 17+ enables records for fallback DTOs; Java 8+ supported throughout.

---

Mode: `review`

User asks to review existing Resilience4J config. Check for:

• [ ] Circuit breaker thresholds are tuned — `slidingWindowSize`, `failureRateThreshold`, `waitDurationInOpenState` set explicitly (not defaults)
• [ ] `slowCallDurationThreshold` and `slowCallRateThreshold` configured — slow calls should also trip the breaker
• [ ] Fallback methods match the same signature as the guarded method (same return type + `Throwable` param)
• [ ] `@CircuitBreaker` and `@Retry` not stacked without `fallbackMethod` on the outer annotation — will swallow exceptions silently
• [ ] Retry has `ignoreExceptions` for business errors (e.g. `IllegalArgumentException`, `EntityNotFoundException`) — don't retry 4xx errors
• [ ] `RateLimiter` uses `limitForPeriod` appropriate for downstream SLA — not an arbitrary number
• [ ] Bulkhead `maxConcurrentCalls` sized against thread pool or reactive scheduler
• [ ] Actuator endpoints exposed: `management.endpoints.web.exposure.include=health,circuitbreakers,retries,ratelimiters`
• [ ] Circuit breaker state changes logged via `CircuitBreakerEvent` listener — not silent
• [ ] No `@Retry` on `@Transactional` methods — retries after a rolled-back transaction reopen a new transaction

---

Mode: `circuit-breaker`

User asks to add a circuit breaker to protect a downstream call.

1. Add dependency (see `references/patterns.md` → Setup) 2. Configure in `application.yml` — set `sliding-window-size`, `failure-rate-threshold`, `wait-duration-in-open-state` 3. Annotate the method with `@CircuitBreaker(name = "serviceName", fallbackMethod = "fallback")` 4. Write the fallback method — same return type, extra `Throwable` parameter 5. Expose circuit breaker health: `management.health.circuitbreakers.enabled=true` 6. Add event listener to log state transitions (CLOSED→OPEN→HALF_OPEN)

Version note:

• Spring Boot 3.x → `resilience4j-spring-boot3`
• Spring Boot 2.x → `resilience4j-spring-boot2`

---

Mode: `retry`

User asks to add automatic retry for flaky remote calls.

1. Configure retry in `application.yml` — `max-attempts`, `wait-duration`, `exponential-backoff-multiplier` 2. Set `ignore-exceptions` for non-retryable errors (validation errors, 4xx responses) 3. Set `retry-exceptions` explicitly (e.g. `IOException`, `TimeoutException`) 4. Annotate with `@Retry(name = "serviceName", fallbackMethod = "fallback")` 5. For HTTP clients: check response status before retrying — use `retryOnResultPredicate` to retry on 5xx, not 4xx 6. Warn if stacking with `@CircuitBreaker` — retry fires first, circuit breaker wraps it; set `retry.max-attempts` lower than circuit breaker `sliding-window-size`

---

Mode: `rate-limiter`

User asks to limit how often a method can be called (outgoing rate limiting or incoming API protection).

1. Configure `limit-for-period` (requests per window), `limit-refresh-period`, `timeout-duration` 2. Annotate with `@RateLimiter(name = "serviceName", fallbackMethod = "fallback")` 3. For incoming API protection: place on controller method or use a filter 4. For outgoing: place on the service/client method calling the downstream

---

Mode: `bulkhead`

User asks to limit concurrent calls to isolate failures (prevent thread starvation).

Two types — choose based on context:

• **Semaphore bulkhead** (default): limits concurrent calls via a counter — lightweight, same thread pool
• **ThreadPool bulkhead**: executes in a dedicated pool — true isolation, for blocking I/O

Configure `max-concurrent-calls` and `max-wait-duration` (semaphore) or pool size (thread pool). Annotate with `@Bulkhead(name = "serviceName", type = Bulkhead.Type.SEMAPHORE)`.

---

Mode: `timeout`

User asks to add a timeout to a method.

1. Use `@TimeLimiter` for reactive/async methods (returns `CompletableFuture` or `Flux`/`Mono`) 2. For blocking methods: use `@CircuitBreaker` with `slowCallDurationThreshold` instead 3. Configure `timeout-duration` in `application.yml` 4. `@TimeLimiter` requires the method to return `CompletableFuture<T>` — wrap synchronous calls if needed

---

Output format

For **review mode**: list findings as `[CRITICAL] / [HIGH] / [MEDIUM] / [LOW]` with file:line references.

For **implementation modes**: show exact Maven/Gradle snippet, full `application.yml` config block, and complete annotated Java example. State minimum Spring Boot version where relevant.