# lerouxrgd/recloser architecture

> Architecture diagram of the GitHub repository lerouxrgd/recloser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lerouxrgd/recloser
- Repository: https://github.com/lerouxrgd/recloser

## Overview

##### Project type and purpose
- This is a Rust library crate (`recloser`) that implements a concurrent circuit-breaker pattern using ring buffers.
- It provides both synchronous (`Recloser`) and asynchronous (`AsyncRecloser`) APIs to wrap arbitrary function or future calls, track failure rates, and open/close the circuit based on configurable thresholds and time windows.

##### File structure
- Top-level files:
- `Cargo.toml` and `README.md` describe crate metadata, dependencies, features.
- `benches/` holds benchmark harnesses comparing `Recloser` vs. `failsafe`.
- `src/` modules:
- `lib.rs` – public entrypoint re-exports types.
- `recloser.rs` – core `Recloser` struct and its state‐machine logic.
- `ring_buffer.rs` – lock-free ring buffer implementation for counting successes/failures.
- `error.rs` – error types (`Error::Inner`, `Error::Rejected`) and `ErrorPredicate` trait.
- `async.rs` – `AsyncRecloser` wrapper that adapts `Recloser` to `Future`-based calls.

##### README for additional insights
- Circuit-breaker has three states: Closed, Open, Half-Open.
- Configurable thresholds: error rate, buffer lengths, open timeout.
- API synopsis: `call(...)`, `call_with(predicate, ...)`, and async `call(future)`.
- Performance focus: single vs. multi-thread benchmarks.

##### Essential detail reminders
- Three states and their transitions.
- How `AsyncRecloser` delegates to `Recloser`.
- Where `ErrorPredicate` intercepts and may filter out errors.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Consumers
    UserApp["User Application"]:::external
    Benchmark["Benchmark Harness"]:::external

    %% API Layer
    subgraph "API Layer"
        RecloserAPI["Recloser API (sync)"]:::api
        AsyncRecloser["AsyncRecloser API (async)"]:::api
    end

    %% Internal Engine
    subgraph "Internal Engine"
        StateMachine["State Machine\n(Closed/Open/Half-Open)"]:::internal
        ErrorPredicate["ErrorPredicate Filter"]:::internal
        RingBuffer["RingBuffer Store\n(success/failure)"]:::store
    end

    %% Protected Function/Future
    Protected["Protected Function / Future"]:::external

    %% Documentation & Config
    subgraph "Project Files"
        Lib["Public Entrypoint & Re-exports"]:::docs
        ErrorFile["Error Types & Filter"]:::docs
        RecloserFile["Recloser & StateMachine"]:::docs
        AsyncFile["AsyncRecloser Adapter"]:::docs
        RingFile["Ring Buffer impl"]:::docs
        BenchFile["Benchmark Harness"]:::docs
        CargoFile["Cargo.toml"]:::docs
        Readme["README.md"]:::docs
        CI["CI Config"]:::docs
    end

    %% Data Flows
    UserApp -->|"call(f)"| RecloserAPI
    UserApp -->|"call(future)"| AsyncRecloser
    Benchmark -->|"bench calls"| RecloserAPI
    AsyncRecloser -->|"delegates"| RecloserAPI
    RecloserAPI -->|"invoke"| StateMachine

    StateMachine -->|"checkState"| ErrorPredicate
    ErrorPredicate -->|"filter"| StateMachine
    StateMachine -->|"recordDecision"| RingBuffer
    RingBuffer -->|"metrics"| StateMachine
    StateMachine -->|"execute if closed/half-open"| Protected
    Protected -->|"result"| RingBuffer

    %% Timeout transition (dashed)
    StateMachine -.->|"timeout reopen"| StateMachine

    %% Click Events
    click RecloserAPI "https://github.com/lerouxrgd/recloser/blob/master/src/recloser.rs"
    click AsyncRecloser "https://github.com/lerouxrgd/recloser/blob/master/src/async.rs"
    click StateMachine "https://github.com/lerouxrgd/recloser/blob/master/src/recloser.rs"
    click RingBuffer "https://github.com/lerouxrgd/recloser/blob/master/src/ring_buffer.rs"
    click ErrorPredicate "https://github.com/lerouxrgd/recloser/blob/master/src/error.rs"
    click Lib "https://github.com/lerouxrgd/recloser/blob/master/src/lib.rs"
    click BenchFile "https://github.com/lerouxrgd/recloser/blob/master/benches/recloser.rs"
    click CargoFile "https://github.com/lerouxrgd/recloser/blob/master/Cargo.toml"
    click Readme "https://github.com/lerouxrgd/recloser/blob/master/README.md"
    click CI "https://github.com/lerouxrgd/recloser/blob/master/.github/workflows/ci.yaml"

    %% Styles
    classDef external fill:#ffe4b5,stroke:#d2691e,color:#000;
    classDef api fill:#add8e6,stroke:#4682b4,color:#000;
    classDef internal fill:#90ee90,stroke:#2e8b57,color:#000;
    classDef store fill:#fffacd,stroke:#bdb76b,color:#000;
    classDef docs fill:#f0f8ff,stroke:#778899,color:#000;
```
