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.