feat: Circuit breaker Middleware Implemented

[MitulShah1]

Add Circuit Breaker Middleware for Fiber

This PR introduces a circuit breaker implementation for Fiber with:

• Tri-state management (Closed/Open/Half-Open)
• Configurable failure thresholds and recovery timeouts
• Automatic failure detection (errors + 5xx responses)
• Concurrency-safe state transitions
• Customizable response handlers
• Test coverage and documentation

The middleware follows industry-standard circuit breaker patterns to prevent cascading failures and enable graceful degradation of services.

@ReneWerner87 appreciate if you would review PR.

Summary by CodeRabbit

• New Features

  • Introduced a resilient Circuit Breaker middleware that safeguards services by dynamically managing request flows with configurable thresholds and timeouts for enhanced fault tolerance.

• Documentation

  • Provided comprehensive, developer-friendly documentation featuring installation guidance and example usage to simplify integration into your applications.

• Tests

  • Expanded testing to validate behavior under various conditions, ensuring accurate state transitions and reliable performance during failures and recoveries.

[coderabbitai[bot]]

Walkthrough

This pull request introduces a new CircuitBreaker middleware for the Fiber web framework. It adds a comprehensive README with installation instructions, configuration details, and usage examples. The implementation includes the CircuitBreaker logic in circuitbreaker.go, featuring state management, request validation, and error callbacks. Additionally, the pull request provides a suite of tests in circuitbreaker_test.go to ensure the functionality of the circuit breaker under various scenarios.

Changes

File(s)	Change Summary
circuitbreaker/README.md	Added documentation for the CircuitBreaker middleware, including installation instructions, a detailed configuration table, function signature (New), and example usage with a Fiber app.
circuitbreaker/circuitbreaker.go	Introduced the CircuitBreaker implementation with state management (closed, open, half-open), configuration structure, atomic update methods (AllowRequest, ReportSuccess, ReportFailure), a monitoring goroutine, and middleware integration for Fiber routing.
circuitbreaker/circuitbreaker_test.go	Added tests for the CircuitBreaker functionality, covering initialization, request allowance based on state, correct state transitions on success and failure, and middleware integration with a Fiber application.
README.md	Added a new entry for the CircuitBreaker middleware in the "Middleware Implementations" section, including a link to the new README file and a badge for the GitHub Actions workflow status.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant FiberApp
    participant Middleware
    participant CircuitBreaker

    Client->>FiberApp: HTTP Request
    FiberApp->>Middleware: Process request via middleware
    Middleware->>CircuitBreaker: Call AllowRequest()
    alt Request Allowed
        CircuitBreaker-->>Middleware: Returns true
        Middleware->>FiberApp: Forward request to handler
        FiberApp->>Middleware: Returns handler response
        Middleware->>CircuitBreaker: Call ReportSuccess()/ReportFailure() based on response
    else Request Blocked
        CircuitBreaker-->>Middleware: Returns false
        Middleware->>Client: Return error response
    end

Suggested labels

✏️ Feature

Suggested reviewers

• sixcolors
• ReneWerner87
• gaby
• efectn

Poem

Hop along the code trail so bright,
I’m a rabbit with delight tonight.
Circuit breaker in place, strong and true,
Guarding Fiber routes just for you.
With tests and docs, our patch takes flight! 🐰✨

---

📜 Recent review details

Configuration used: CodeRabbit UI Review profile: CHILL Plan: Free

📥 Commits

Reviewing files that changed from the base of the PR and between 3d40b7f2d64c77cc838283ca9c79212b06d3cb2a and 525be7e90b245ef560a6b861cdb4555597e0f746.

📒 Files selected for processing (2)

• circuitbreaker/circuitbreaker.go (1 hunks)
• circuitbreaker/circuitbreaker_test.go (1 hunks)

---

[!NOTE]

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai plan to trigger planning for file edits and PR creation.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai or @coderabbitai title anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[gaby]

Some of the config options should be renamed. You can use this for reference https://failsafe-go.dev/circuit-breaker/

[ReneWerner87]

@coderabbitai How does the new circuit breaker middleware differ from the existing loadshed middleware? please key in on where the conceptual commonalities and differences are so we can be sure that multiple middleware are not solving the same problems

[gaby]

@ReneWerner87 This doesnt have external dependencies, makes more sense to add it in https://github.com/gofiber/fiber ?

[coderabbitai[bot]]

[!TIP] For best results, initiate chat on the files or code changes.

🧩 Analysis chain

@ReneWerner87 Based on my analysis of the circuit breaker middleware and researching load management solutions in the codebase, I can explain the conceptual differences between circuit breakers and load shedding:

Circuit Breaker Middleware (New)

Purpose: Prevents cascading failures by stopping requests to failing services.

Key Characteristics:

• Uses a tri-state model (Closed, Open, Half-Open)
• Triggered by failure detection (errors, 5xx responses)
• Time-based recovery mechanism (automatically transitions to Half-Open after timeout)
• Focused on service reliability and fault tolerance
• Protects dependent services from continuously calling failing services

Load Shedding/Concurrency Limiting

Purpose: Protects services from being overwhelmed by too many concurrent requests.

Key Characteristics:

• Typically uses request counting or rate-based mechanisms
• Triggered by exceeding capacity thresholds (too many concurrent requests)
• Usually rejects excess requests immediately without state tracking
• Focused on resource protection and preventing exhaustion
• Ensures system stability under high load

Conceptual Differences

1. Trigger mechanism:

   • Circuit breaker: Triggered by failure rate
   • Load shedding: Triggered by request volume

2. Recovery approach:

   • Circuit breaker: Gradual testing with Half-Open state
   • Load shedding: Immediate acceptance when capacity becomes available

3. Purpose:

   • Circuit breaker: Prevents calls to failing services
   • Load shedding: Prevents system overload

The circuit breaker focuses on service health and failure recovery, while load shedding focuses on resource management. They are complementary patterns that address different aspects of system resilience.

---

🏁 Script executed:

#!/bin/bash
# Search for loadshed middleware in the repository
echo "Looking for loadshed middleware files..."
fd -t f -e go loadshed

Length of output: 162

---

🏁 Script executed:

#!/bin/bash
# Examine the loadshed middleware implementation
echo "Examining loadshed middleware implementation..."
if [ -d "loadshed" ]; then
  cat loadshed/*.go
else
  # Try to find the loadshed middleware in other directories
  echo "Looking for loadshed middleware files in other directories..."
  find . -name "loadshed*.go" -type f -exec cat {} \;
fi

Length of output: 5326

---

🏁 Script executed:

#!/bin/bash
# Search for mentions of "loadshed" in the codebase
echo "Searching for mentions of loadshed in the codebase..."
rg -i "loadshed" --type go

Length of output: 482

---

🏁 Script executed:

#!/bin/bash
# List directories to find loadshed
echo "Listing directories to find loadshed..."
find . -type d | grep -i loadshed

# Search for Go files that might contain loadshed functionality
echo "Searching for Go files that might contain loadshed functionality..."
rg -l "loadshed" --type go

Length of output: 370

---

🏁 Script executed:

#!/bin/bash
# List all directories in the repository
echo "Listing all directories..."
ls -la

# Check if we're in the contrib repository
echo "Checking if we're in the contrib repository..."
if [ -f "go.mod" ]; then
  cat go.mod
fi

# List all packages in the repository
echo "Listing all packages in the repository..."
find . -mindepth 1 -maxdepth 1 -type d | grep -v "^\./\." | sort

Length of output: 2039

---

🏁 Script executed:

#!/bin/bash
# Search for any middleware related to load limiting or load shedding
echo "Searching for load limiting or load shedding middleware..."
rg -i "load(shed|limit)" --type go

# Check for concepts related to load management
echo "Checking for concepts related to load management..."
rg -i "(rate limit|throttle|load balance)" --type go

# Let's check if there's a limiter middleware
echo "Checking for limiter middleware..."
find . -type d -name "*limit*"
ls -la ./limiter 2>/dev/null

Length of output: 867

---

🏁 Script executed:

#!/bin/bash
# Look at the limiter directory if it exists
if [ -d "./limiter" ]; then
  echo "Examining files in limiter directory:"
  ls -la ./limiter
  
  echo "Content of limiter implementation files:"
  cat ./limiter/*.go
fi

Length of output: 22

---

🏁 Script executed:

#!/bin/bash
# Let's list all directories to get a better understanding of the repository structure
echo "Listing all directories and subdirectories:"
find . -type d | sort

# Let's look for any middleware that might be related to load management or circuit breaking
echo "Searching for middleware related to load management or circuit breaking:"
rg -i "(middleware|circuit|breaker|load|shed|limit|throttle)" --type go -l | grep -v circuitbreaker

Length of output: 1982

---

🏁 Script executed:

#!/bin/bash
# Search for documentation about load shedding
echo "Searching for documentation about load shedding:"
rg -i "loadshed|load shedding" --type md

# Let's also check READMEs across the repository
echo "Checking READMEs across the repository:"
find . -name "README.md" -exec cat {} \; | grep -i "load"

Length of output: 6825

---

🏁 Script executed:

#!/bin/bash
# Check for similar concepts in the repository
echo "Checking for similar concepts to load shedding:"
find . -type d -name "*rate*" -o -name "*throttle*" -o -name "*bulk*" -o -name "*limit*" -o -name "*breaker*"

# If we found any potential directories, let's examine them
if [ -d "./ratelimiter" ]; then
  echo "Examining ratelimiter:"
  ls -la ./ratelimiter
  cat ./ratelimiter/*.go 2>/dev/null
fi

if [ -d "./bulkhead" ]; then
  echo "Examining bulkhead:"
  ls -la ./bulkhead
  cat ./bulkhead/*.go 2>/dev/null
fi

if [ -d "./throttle" ]; then
  echo "Examining throttle:"
  ls -la ./throttle
  cat ./throttle/*.go 2>/dev/null
fi

if [ -d "./limiter" ]; then
  echo "Examining limiter:"
  ls -la ./limiter
  cat ./limiter/*.go 2>/dev/null
fi

Length of output: 406

---

🏁 Script executed:

#!/bin/bash
# Examine the circuit breaker implementation
echo "Examining circuit breaker implementation:"
cat ./circuitbreaker/circuitbreaker.go

# Search for files with any load management concepts
echo "Searching broadly for load management concepts:"
rg -i -l "(concurrency|load|traffic|shed|limit|throttle|breaker|circuit)" --type go

Length of output: 6226

---

🏁 Script executed:

#!/bin/bash
# Check if there's a limiter directory and examine its content
if [ -d "./limiter" ]; then
  echo "Files in limiter directory:"
  ls -la ./limiter
  
  # Check each file in the limiter directory
  for file in ./limiter/*.go; do
    echo "Contents of $file:"
    cat "$file"
    echo "-----------------------------------"
  done
fi

# Also check if there's a concurrency limiter
if [ -d "./concurrencylimiter" ]; then
  echo "Files in concurrencylimiter directory:"
  ls -la ./concurrencylimiter
  
  # Check each file in the concurrencylimiter directory
  for file in ./concurrencylimiter/*.go; do
    echo "Contents of $file:"
    cat "$file"
    echo "-----------------------------------"
  done
fi

Length of output: 56

---

🏁 Script executed:

#!/bin/bash
# Search specifically for loadshed or load shedding terms
echo "Searching for specific loadshed/load shedding implementations:"
rg -i -t go "func.*[Ll]oad[Ss]hed" -A 10

# Search for more general load management terms in function signatures
echo "Searching for load management function signatures:"
rg -i -t go "func.*(load|limit|throttle|concurrency)" -A 5

# Check for specific imports that might indicate load management libraries
echo "Checking for specific imports related to load management:"
rg -i -t go "import.*\".*load.*\""

Length of output: 8697

---

🏁 Script executed:

#!/bin/bash
# Let's check for any rate limiting middleware
if [ -d "./ratelimiter" ]; then
  echo "Contents of ratelimiter directory:"
  ls -la ./ratelimiter
  cat ./ratelimiter/*.go 2>/dev/null
fi

# Let's check for any concurrency limiting middleware
if [ -d "./concurrency" ]; then
  echo "Contents of concurrency directory:"
  ls -la ./concurrency
  cat ./concurrency/*.go 2>/dev/null
elif [ -d "./concurrencylimit" ]; then
  echo "Contents of concurrencylimit directory:"
  ls -la ./concurrencylimit
  cat ./concurrencylimit/*.go 2>/dev/null
fi

# Let's check in general middleware directories
if [ -d "./middleware" ]; then
  echo "Looking for load management in middleware directory:"
  rg -i "(load|limit|throttle|concurrency)" ./middleware
fi

Length of output: 111

---

🏁 Script executed:

#!/bin/bash
# List all directories at the top level
echo "Top-level directories:"
ls -la | grep "^d"

# Check for potential middleware directories
echo "Checking for potential middleware directories:"
find . -maxdepth 2 -type d | grep -v "./\." | sort

# Check for any directories containing "limit" in their name
echo "Directories containing 'limit' in their name:"
find . -type d -name "*limit*"

# Let's look at several potential middleware directories
for dir in limiter ratelimiter concurrencylimiter loadbalancer loadshedder; do
  if [ -d "./$dir" ]; then
    echo "Found $dir directory, listing files:"
    ls -la "./$dir"
    echo "Contents of Go files in $dir:"
    cat "./$dir"/*.go 2>/dev/null
    echo "----------------------------------------"
  fi
done

Length of output: 2458

---

🏁 Script executed:

#!/bin/bash
# Check if concurrencylimiter directory exists and examine its contents
if [ -d "./concurrencylimiter" ]; then
  echo "Files in concurrencylimiter directory:"
  ls -la ./concurrencylimiter
  
  # Examine the go files
  echo "Contents of Go files in concurrencylimiter:"
  for file in ./concurrencylimiter/*.go; do
    if [ -f "$file" ]; then
      echo "Contents of $file:"
      cat "$file"
      echo "----------------------------------------"
    fi
  done
  
  # Check for README
  if [ -f "./concurrencylimiter/README.md" ]; then
    echo "Contents of concurrencylimiter README.md:"
    cat ./concurrencylimiter/README.md
  fi
else
  echo "concurrencylimiter directory not found."
fi

Length of output: 122

---

🏁 Script executed:

#!/bin/bash
# Examine both the circuit breaker and concurrencylimiter implementations

# First, let's check the concurrencylimiter
echo "===== CONCURRENCY LIMITER ====="
if [ -d "./concurrencylimiter" ]; then
  echo "Contents of Go files in concurrencylimiter:"
  cat ./concurrencylimiter/*.go 2>/dev/null
  
  # Check for README
  if [ -f "./concurrencylimiter/README.md" ]; then
    echo "Contents of concurrencylimiter README.md:"
    cat ./concurrencylimiter/README.md
  fi
else
  echo "concurrencylimiter directory not found."
  # Try to find it elsewhere
  find . -name "*concurrency*" -type d
fi

# Now, let's check the circuit breaker
echo "===== CIRCUIT BREAKER ====="
echo "Contents of Go files in circuitbreaker:"
cat ./circuitbreaker/circuitbreaker.go

# Check for README
if [ -f "./circuitbreaker/README.md" ]; then
  echo "Contents of circuitbreaker README.md:"
  cat ./circuitbreaker/README.md
fi

Length of output: 7608

---

🏁 Script executed:

#!/bin/bash
# List all directories that might contain middleware
echo "Listing all potential middleware directories:"
ls -d */ 2>/dev/null | sort

# Look for any README files in the repository that might mention load management
echo "Looking for README files that mention load management:"
find . -name "README.md" -exec grep -l -i "load\|shed\|limit\|throttle\|concurrency\|circuit" {} \;

# For each README that mentions these terms, let's display its content
for readme in $(find . -name "README.md" -exec grep -l -i "load\|shed\|limit\|throttle\|concurrency\|circuit" {} \;); do
  echo "Contents of $readme that mentions load management terms:"
  grep -i "load\|shed\|limit\|throttle\|concurrency\|circuit" "$readme"
  echo "----------------------------------------"
done

Length of output: 11143

---

🏁 Script executed:

#!/bin/bash
# Search for middleware package descriptions in Go files
echo "Searching for middleware package descriptions in Go files:"
rg -i "^// Package .*(load|shed|limit|throttle|concurrency|circuit)" --type go

# Search for function comments that might describe load management
echo "Searching for function comments that might describe load management:"
rg -i "// (Load|Shed|Limit|Throttle|Concurrency|Circuit)" --type go

# Let's check all top-level directories for Go files
echo "Checking top-level directories for Go files:"
for dir in */; do
  if [ -d "$dir" ] && ls "$dir"/*.go >/dev/null 2>&1; then
    echo "Go files found in $dir"
    
    # Check if any of these files mention load management concepts
    if rg -i "(load|shed|limit|throttle|concurrency|circuit)" "$dir"/*.go >/dev/null 2>&1; then
      echo "Files in $dir mentioning load management concepts:"
      rg -i -l "(load|shed|limit|throttle|concurrency|circuit)" "$dir"/*.go
    fi
  fi
done

Length of output: 10080

---

🏁 Script executed:

#!/bin/bash
# Search for the loadbalancer middleware which might be what's being referred to
echo "Checking for loadbalancer middleware:"
find . -name "*loadbalance*" -o -name "*load_balance*"

# Let's search for other potential load management middlewares
echo "Searching for other potential load management middlewares:"
find . -name "*throttle*" -o -name "*rate*" -o -name "*limit*" | grep -v "circuit"

# Let's check for any load shedding or similar terms in the main fiber repository
echo "Searching for load management terms in code:"
rg -i "(load shed|loadshed|traffic management|concurrency control)" --type go

# Let's check for any middleware that implements limiting functionality
echo "Searching for middleware with limiting functionality:"
rg -i "func.*(limit|throttle|shed|balance)" --type go -A 5 -B 5

Length of output: 3521

---

🏁 Script executed:

#!/bin/bash
# Check for a limiter package
echo "Checking for limiter package:"
if [ -d "./limiter" ]; then
  echo "Files in limiter directory:"
  ls -la ./limiter
  
  echo "Contents of Go files in limiter:"
  cat ./limiter/*.go 2>/dev/null
  
  echo "Contents of README in limiter:"
  cat ./limiter/README.md 2>/dev/null
fi

# Check for relevant imports that might indicate load management
echo "Checking for imports related to load management:"
rg -i "import.*\"github.com/gofiber/fiber/v2/middleware/(limiter|throttle|load|rate)\"" --type go

Length of output: 296

---

@ReneWerner87 I've analyzed both the new circuit breaker middleware and the existing loadshed middleware, and can explain their key differences and complementary purposes:

Circuit Breaker Middleware (New)

Primary Purpose: Prevents cascading failures by stopping traffic to failing services.

Key Characteristics:

• Uses a state machine with three states: Closed (normal operation), Open (requests blocked), and Half-Open (testing recovery)
• Triggered by failure detection (errors or 5xx HTTP responses)
• Maintains state across requests and includes time-based recovery mechanisms
• Tracks failure counts and automatically transitions states based on thresholds
• Allows gradual recovery through the Half-Open state to verify service health

LoadShed Middleware (Existing)

Primary Purpose: Protects system resources from overload by rejecting excess requests.

Key Characteristics:

• Makes decisions based on system metrics (CPU usage in the current implementation)
• Uses probabilistic request rejection between configurable thresholds
• Stateless evaluation - each request is assessed independently based on current load
• No recovery mechanism - accepts/rejects purely based on current system load
• Designed to shed load when system resources are stretched (e.g., CPU > 90%)

Conceptual Differences

1. Trigger mechanism:

   • Circuit breaker: Triggered by service failures
   • LoadShed: Triggered by resource utilization

2. State behavior:

   • Circuit breaker: Maintains state across requests (remembers past failures)
   • LoadShed: Stateless (only concerned with current system condition)

3. Use cases:

   • Circuit breaker: Best for protecting against dependency failures
   • LoadShed: Best for protecting against resource exhaustion

These middlewares serve complementary purposes in a resilient system. The circuit breaker prevents calling failing services, while loadshed protects the system itself from becoming overloaded.

[ReneWerner87]

@ReneWerner87 This doesnt have external dependencies, makes more sense to add it in gofiber/fiber ?

the core only makes sense if it is middleware that is used by many people would not decide only on the basis of dependencies rather according to the frequency of the people we reach and who use this procedure and we are already well positioned with the currently available ones

[MitulShah1]

@ReneWerner87 @gaby thanks for review I've updated PR according to comment please review

[gaby]

Here's the review using OpenAI - o3-mini-high

---

Below is an in‐depth review of the implementation with several critical observations:

---

1. State Transition Callbacks

Unused Callbacks: The configuration provides callbacks for OnHalfOpen and OnClose, yet these are never invoked in the middleware. In the current implementation, when a request is rejected (due to being in an open or half‐open state), only the OnOpen callback is called. This omission means you lose the opportunity to differentiate the responses between a circuit that’s truly “open” versus one that’s “half-open” (i.e. recovering). Recommendation: Invoke OnHalfOpen when a request is rejected due to the half‐open state (for example, when the half-open semaphore is full) and consider if/when to call OnClose during a successful state transition.

Semantic Clarity: Callbacks like OnClose could be used to perform side effects (e.g., logging, metrics, cleanup) when the circuit transitions back to the closed state. Not using them means part of your intended configuration API remains unutilized.

---

2. Concurrency and Atomicity

Mixed Concurrency Primitives: The implementation uses both atomics (for failureCount and successCount) and a mutex (for state transitions). While this can work, mixing atomic operations with mutex locking can be error-prone and may lead to subtle race conditions if not handled carefully. Recommendation: Either fully encapsulate the counter updates and state transitions under a mutex or rely entirely on atomic operations with proper synchronization (for example, using CAS loops) to simplify reasoning about concurrent state.

Half-Open Semaphore Usage: The semaphore is implemented as a buffered channel of size 1 to allow only a single request in the half-open state. While this is a valid approach to limit concurrent trials, it might be too restrictive if you’d like to allow a few trial requests. Recommendation: Consider parameterizing the semaphore capacity via configuration if you want more flexibility in controlling the number of trial requests.

---

3. Polling for State Transition

Monitor Goroutine: A dedicated goroutine polls every second to check if the open state has expired, transitioning to half-open when appropriate. Although this works, it introduces a latency (up to one second) between the actual timeout expiry and the state transition. Recommendation: If more precision is required, you might consider checking the expiry inline in AllowRequest() or using a timer-based approach that fires exactly when needed instead of polling every second.

---

4. Failure/Success Reporting

Error Handling Logic: In the middleware, failures are determined solely by an error returned from c.Next() or an HTTP status code of 500 and above. This might be too coarse for some applications where business logic errors (such as a 4xx response with a meaningful failure) should also trigger the breaker. Recommendation: Consider making the failure criteria configurable so that users can define what constitutes a failure based on their domain requirements.

State Reset Logic: The counters for failures and successes are reset on state transitions. This is generally acceptable, but note that:

In ReportFailure, when in the half-open state, the failure immediately transitions to open without resetting the success counter.

In ReportSuccess, if the success threshold is met in the half-open state, the state changes to closed. Ensure that the reset logic is exactly what you want for your recovery policy.

---

5. Design and API Considerations

Callback Placement: The middleware immediately invokes the OnOpen callback if a request isn’t allowed. However, given that half-open is a transient state, it might be clearer to have a different handling strategy or message for half-open rejections (using the dedicated OnHalfOpen callback). Recommendation: Differentiate between open and half-open responses in the middleware so that clients have a better understanding of the system state.

Testing Aids: The use of a now function to obtain the current time is a good practice for testing. Ensure that this is thoroughly used in tests to simulate state transitions.

Documentation and Comments: While there are basic comments, more detailed documentation (especially around the state transitions and concurrency model) would help maintainers understand the rationale behind using both atomics and a mutex. More explicit comments about why certain design decisions were made (such as the polling interval) would also be beneficial.

---

6. Overall Observations

Robustness: The overall structure is sound and follows the general circuit breaker pattern. However, the unused callbacks and mixed concurrency primitives indicate areas where the design could be both simplified and made more flexible.

Flexibility: Consider exposing more parameters via the configuration (like the half-open concurrency limit or custom failure criteria) to allow users to adapt the breaker behavior to their specific use cases.

Potential Enhancements:

Integrate metrics for state transitions and counts.

Document the expected behavior in corner cases (e.g., what happens if multiple failures occur in rapid succession).

Allow for a manual reset mechanism if needed for operational reasons.

---

Conclusion

• The implementation is a good starting point but could benefit from:
• Better utilization of the provided callback hooks.
• A more consistent approach to concurrency (either atomic or mutex-based).
• More precise control over state transitions without relying solely on polling.
• Expanded configurability regarding what constitutes a failure and the number of trial requests in half-open.

[MitulShah1]

@gaby @ReneWerner87 made all necessary changes let me know any further changes need to be done

@sixcolors @efectn please review

[gaby]

@MitulShah1 We didnt forget about the PR. We are discussing internally wether to keep it here or move this to gofiber/fiber since it has no external dependencies.

[ReneWerner87]

@MitulShah1 We didnt forget about the PR. We are discussing internally wether to keep it here or move this to gofiber/fiber since it has no external dependencies.

let's keep it in contrib for now and transfer it later if necessary