Home

Fuse Reference Documentation

Fuse is an ultra-lightweight, zero-dependency Circuit Breaker library implemented in modern Java (Java 17+). It provides robust fault tolerance and cascading failure prevention for distributed systems and microservices without introducing third-party transitive dependencies.

---

Architectural Philosophy

In distributed cloud architectures, downstream services (REST APIs, gRPC services, relational databases, cache clusters) inevitably experience degradation, timeouts, and network partitions. When callers continue hammering an unresponsive downstream, threads become blocked, thread pools saturate, and failures cascade upstream until the entire cluster exhausts its resources.

Traditional fault-tolerance libraries (e.g., Netflix Hystrix, Resilience4j) address this issue but often introduce substantial architectural footprint:

• Complex Dependency Graphs: Requiring RxJava, Vavr, or dozens of transitive utility JARs that risk version collisions.
• Heap and Classpath Bloat: Large footprint and reflection overhead unsuitable for lightweight CLI tools, Lambda/Serverless functions, or modular microservices.
• Steep Operational Overhead: Extensive configuration models and steep learning curves when an application strictly requires circuit breaking.

Fuse was designed to solve one problem cleanly: provide a thread-safe, lock-free Circuit Breaker built exclusively on top of standard Java Virtual Machine primitives (java.util.concurrent.atomic).

---

State Machine Architecture

Fuse enforces the classic three-state Circuit Breaker pattern with automatic probe recovery:

stateDiagram-v2
    [*] --> CLOSED
    
    CLOSED --> OPEN : Consecutive Failures >= failureThreshold
    note right of CLOSED
        Normal operation.
        All requests executed.
        Failures increment counter.
    end note

    OPEN --> HALF_OPEN : Duration >= timeout
    note right of OPEN
        Short-circuit active.
        Requests rejected immediately
        with CircuitBreakerOpenException.
    end note

    HALF_OPEN --> CLOSED : Consecutive Successes >= successThreshold
    HALF_OPEN --> OPEN : Single Probe Failure
    note right of HALF_OPEN
        Recovery probing.
        Limited trial calls allowed.
    end note

Loading

• CLOSED: Requests proceed directly to the downstream resource. When consecutive recorded failures reach failureThreshold, the breaker trips to OPEN.
• OPEN: Calls are rejected immediately by throwing CircuitBreakerOpenException. No network I/O or downstream connection attempts occur.
• HALF_OPEN: Once the configured timeout elapses, trial probe requests are admitted. If successThreshold consecutive calls succeed, the circuit resets to CLOSED. If any probe fails, the circuit reverts immediately to OPEN for another timeout duration.

---

Technical Comparison

Characteristic	Fuse	Resilience4j CircuitBreaker	Netflix Hystrix (Deprecated)
Runtime Dependencies	0 (Pure JDK)	~5 transitive (Vavr, Slf4j)	~15 transitive (RxJava, Archaius)
JAR Size	< 20 KB	~200 KB (module only)	~1.5 MB
Java Baseline	Java 17+	Java 8+ / 17+	Java 6+ (Maintenance mode)
Concurrency Model	Lock-free CAS	Concurrent atomic rings	Dedicated thread pools / semaphores
Learning Curve	5 minutes	Intermediate	High

---

Installation

Maven

<dependency>
    <groupId>io.github.frodygr</groupId>
    <artifactId>fuse</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle (Kotlin DSL)

implementation("io.github.frodygr:fuse:1.0.0")

---

Quickstart

import io.github.frodygr.circuitbreaker.CircuitBreaker;
import io.github.frodygr.circuitbreaker.CircuitBreakerConfig;
import io.github.frodygr.circuitbreaker.CircuitBreakerOpenException;
import io.github.frodygr.circuitbreaker.DefaultCircuitBreaker;
import java.time.Duration;

// 1. Configure the thresholds
CircuitBreakerConfig config = CircuitBreakerConfig.builder()
        .failureThreshold(5)             // 5 consecutive failures trips circuit to OPEN
        .successThreshold(3)             // 3 consecutive successes in HALF_OPEN resets to CLOSED
        .timeout(Duration.ofSeconds(30)) // Stay in OPEN for 30s before testing recovery
        .build();

// 2. Instantiate the circuit breaker
CircuitBreaker circuitBreaker = new DefaultCircuitBreaker("payment-gateway", config);

// 3. Execute downstream calls within protection
try {
    PaymentResult result = circuitBreaker.execute(() -> remotePaymentClient.charge(order));
    return result;
} catch (CircuitBreakerOpenException ex) {
    // Fast fallback: downstream service is down, avoid queuing or waiting
    return PaymentResult.degraded("Payment queued for background processing");
}

---

Documentation Sections

• Getting Started: Installation, checked vs unchecked execution, and fallback strategies.
• State Machine & Transitions: Deep dive into lock-free CAS transitions and reset semantics.
• Configuration Reference: Detailed analysis of all builder options, predicates, and thresholds.
• State Listeners & Observability: Subscribing to transition events, SLF4J logging, and Micrometer export.
• Thread Safety & Concurrency: Internals, virtual thread compatibility, and latency overhead benchmarks.
• Production Patterns: Recipes for HTTP clients, Spring Boot beans, and cascading resilience.