Spring Cloud Circuit Breaker

Spring Cloud Circuit Breaker provides a common abstraction for circuit breaker patterns, allowing you to switch between different underlying fault tolerance libraries. The project currently supports three main implementations:

• Resilience4J: A comprehensive library supporting circuit breakers, rate limiters, bulkheads, and more. It is compatible with both blocking and reactive applications.
• Spring Retry: Provides declarative retry support with circuit breaker functionality. It is a mature implementation with extensive configuration options.
• Framework Retry: A lightweight implementation built on Spring Framework 7's native retry support. Note that this implementation does not support reactive applications.

To use these features, you interact with the APIs defined in Spring Cloud Commons.

Spring Cloud CircuitBreaker Resilience4j provides two bulkhead implementations:

1. SemaphoreBulkhead: Uses Semaphores to limit concurrency.
2. FixedThreadPoolBulkhead: Uses a bounded queue and a fixed thread pool.

By default, FixedThreadPoolBulkhead is used. To switch the default implementation to SemaphoreBulkhead, set the following property:

spring.cloud.circuitbreaker.resilience4j.enableSemaphoreDefaultBulkhead=true

This implementation adds stateful functionality to the stateless Spring Framework retry support. It follows the CircuitBreakerRetryPolicy pattern:

• Closed State: Requests pass through and are retried based on the RetryPolicy. If an invocation fails after all retries are exhausted, the circuit opens immediately.
• Open State: Requests fail immediately with a fallback response. The circuit stays open for the duration of openTimeout.
• Half-Open State: After openTimeout, a single request is allowed through. Success closes the circuit; failure reopens it.
• Reset Timeout: If no failures occur within the resetTimeout period, the circuit automatically resets to the Closed state.

For reactive programming (using Mono and Flux), use the ReactiveResilience4jBulkheadProvider. This provider decorates reactive streams to ensure bulkhead constraints are applied during operations.

Note: Reactive support only uses SemaphoreBulkhead. If spring.cloud.circuitbreaker.resilience4j.enableSemaphoreDefaultBulkhead is set to false, a warning will be logged, but the provider will still default to SemaphoreBulkhead to ensure functionality.

When multiple configuration sources are present, the following priority order is applied (from highest to lowest):

1. Specific instance configuration: resilience4j.thread-pool-bulkhead.instances.* or resilience4j.bulkhead.instances.*
2. Java Customizer configuration using Resilience4JBulkheadProvider.
3. Shared configuration templates: resilience4j.thread-pool-bulkhead.configs.* or resilience4j.bulkhead.configs.* (applied via baseConfig).

You can configure CircuitBreaker and TimeLimiter settings via your application's configuration properties. Property configuration takes precedence over Java Customizer configuration.

When defining properties, the configuration follows a descending priority order (from highest to lowest):

1. Method (id) config: Applied to a specific method or operation.
2. Service (group) config: Applied to a specific application service or group of operations.
3. Global default config: The fallback configuration used when no specific instance or group is matched.

You can control the ExecutorService used to execute circuit breaker logic by using the configureExecutorService method on the Resilience4JCircuitBreakerFactory. This is useful if you need to provide a specialized executor, such as a context-aware ExecutorService.

@Bean
public Customizer<Resilience4JCircuitBreakerFactory> defaultCustomizer() {
	return factory -> {
		ContextAwareScheduledThreadPoolExecutor executor = ContextAwareScheduledThreadPoolExecutor.newScheduledThreadPool().corePoolSize(5)
			.build();
		factory.configureExecutorService(executor);
	};
}

The project uses Antora to build documentation from Asciidoc sources. To generate the documentation site, use the docs profile with the antora:antora goal.

./mvnw -pl docs -P docs antora:antora

To use the Framework Retry circuit breaker implementation, add the following dependency to your project.

### Maven
```xml
<dependency>
	<groupId>org.springframework.cloud</groupId>
	<artifactId>spring-cloud-starter-circuitbreaker-framework-retry</artifactId>
</dependency>

Gradle

implementation 'spring-cloud-starter-circuitbreaker-framework-retry'

To build the source, ensure you have JDK 17 installed. Spring Cloud uses Maven for build activities. You can use the Maven Wrapper (./mvnw) included in the repository or a local Maven installation (>=3.3.3).

Important Notes:

• If using a local Maven installation, you may need to add the -P spring profile to resolve Spring milestone and snapshot repositories.
• If you encounter memory issues, increase Maven memory by setting the MAVEN_OPTS environment variable (e.g., -Xmx512m -XX:MaxPermSize=128m).
• Projects requiring middleware (like Redis) for testing require Docker to be installed and running.

$ ./mvnw install

To apply a configuration to every circuit breaker created by the factory, define a Customizer<SpringRetryCircuitBreakerFactory> bean. Use the configureDefault method within the customizer to provide a SpringRetryConfigBuilder that defines the retryPolicy (and other settings) for all circuit breakers.

@Bean
public Customizer<SpringRetryCircuitBreakerFactory> defaultCustomizer() {
	return factory -> factory.configureDefault(id -> new SpringRetryConfigBuilder(id)
    	.retryPolicy(new TimeoutRetryPolicy()).build());
}