Skip to content

feat(utils): implement circuit breaker pattern for resilient network clients#420

Merged
kcenon merged 6 commits into
mainfrom
feature/403-circuit-breaker
Jan 11, 2026
Merged

feat(utils): implement circuit breaker pattern for resilient network clients#420
kcenon merged 6 commits into
mainfrom
feature/403-circuit-breaker

Conversation

@kcenon

@kcenon kcenon commented Jan 11, 2026

Copy link
Copy Markdown
Owner

Summary

  • Implement Circuit Breaker pattern for fault-tolerant network communication
  • Add circuit_breaker class with three-state pattern (closed → open → half_open)
  • Integrate circuit breaker with resilient_client for automatic failure management

Closes #403

Changes

New Files

  • include/kcenon/network/utils/circuit_breaker.h - Circuit breaker header with state machine interface
  • src/utils/circuit_breaker.cpp - Thread-safe circuit breaker implementation
  • tests/unit/test_circuit_breaker.cpp - 18 comprehensive unit tests

Modified Files

  • include/kcenon/network/utils/resilient_client.h - Add circuit breaker integration API
  • src/utils/resilient_client.cpp - Integrate circuit breaker with send/retry logic
  • include/kcenon/network/utils/result_types.h - Add circuit_open error code
  • CMakeLists.txt - Add circuit_breaker.cpp to library sources
  • tests/CMakeLists.txt - Add circuit breaker test target
  • CHANGELOG.md / CHANGELOG_KO.md - Document new feature

Features

  • Three-state pattern: closed (normal), open (fail-fast), half_open (testing recovery)
  • Configurable parameters:
    • failure_threshold - failures before opening circuit
    • open_duration - time before attempting half-open
    • half_open_successes - successes needed to close
    • half_open_max_calls - max calls during half-open
  • State change callbacks: Monitor circuit state transitions
  • Thread-safe: Atomic operations and mutex protection
  • Reset API: Manual circuit reset capability

Test plan

  • All 18 unit tests pass (state transitions, callbacks, reset, thread safety)
  • Build succeeds with circuit breaker integration
  • Existing functionality not broken
  • CI/CD pipeline verification

Add circuit_breaker class with three-state machine (closed, open, half-open)
to prevent cascade failures and provide fast-fail behavior when backend
services are unavailable.

Key features:
- Configurable failure threshold, open duration, and half-open parameters
- Thread-safe state transitions with atomic operations
- State change callbacks for monitoring/metrics integration
- Automatic transition from open to half-open after timeout

Refs: #403
- Add circuit_breaker parameter to resilient_client constructor
- Check circuit breaker before attempting send operations
- Record success/failure to circuit breaker after operations
- Add circuit_state(), reset_circuit(), set_circuit_state_callback() methods
- Add circuit_open error code for fast-fail scenarios
- Move circuit_breaker_config struct outside class to fix default initializer issue

Refs: #403
Add 18 unit tests covering:
- Basic state (closed, open, half-open)
- State transitions and thresholds
- Timeout-based transitions
- State change callbacks
- Reset functionality
- Thread safety with concurrent operations
- State to string conversion
- Next attempt time validation

Refs: #403
Add changelog entries for Circuit Breaker pattern implementation (#403):
- English and Korean versions updated
- Describes circuit_breaker class with three-state pattern
- Lists all configuration parameters and API additions
- Mentions resilient_client integration and test coverage
@github-actions

Copy link
Copy Markdown
Contributor

Performance Comparison

Base Branch Results

No base results

PR Branch Results

No PR results

Add error_codes_ext namespace with circuit_open error code to the
fallback block (when KCENON_WITH_COMMON_SYSTEM is not defined) in
result_types.h for API compatibility.

This fixes build failures when building without common_system
dependency, where resilient_client.cpp references error_codes_ext
which was only defined in the KCENON_WITH_COMMON_SYSTEM path.
Document the fix for error_codes_ext namespace missing in fallback
build path. This fix ensures builds without common_system dependency
compile correctly.
@github-actions

Copy link
Copy Markdown
Contributor

Performance Comparison

Base Branch Results

No base results

PR Branch Results

No PR results

@codecov

codecov Bot commented Jan 11, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 33.19%. Comparing base (a4d8129) to head (4720759).
⚠️ Report is 7 commits behind head on main.

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main     #420      +/-   ##
==========================================
+ Coverage   32.94%   33.19%   +0.24%     
==========================================
  Files          39       39              
  Lines        2841     2841              
==========================================
+ Hits          936      943       +7     
+ Misses       1905     1898       -7     
Flag Coverage Δ
unittests 33.19% <ø> (+0.24%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
include/kcenon/network/utils/result_types.h 90.90% <ø> (ø)

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@kcenon kcenon merged commit 7d9f9f5 into main Jan 11, 2026
46 checks passed
@kcenon kcenon deleted the feature/403-circuit-breaker branch January 11, 2026 23:05
kcenon added a commit that referenced this pull request Apr 13, 2026
…clients (#420)

* feat(utils): implement circuit breaker pattern for fault tolerance

Add circuit_breaker class with three-state machine (closed, open, half-open)
to prevent cascade failures and provide fast-fail behavior when backend
services are unavailable.

Key features:
- Configurable failure threshold, open duration, and half-open parameters
- Thread-safe state transitions with atomic operations
- State change callbacks for monitoring/metrics integration
- Automatic transition from open to half-open after timeout

Refs: #403

* feat(utils): integrate circuit breaker with resilient_client

- Add circuit_breaker parameter to resilient_client constructor
- Check circuit breaker before attempting send operations
- Record success/failure to circuit breaker after operations
- Add circuit_state(), reset_circuit(), set_circuit_state_callback() methods
- Add circuit_open error code for fast-fail scenarios
- Move circuit_breaker_config struct outside class to fix default initializer issue

Refs: #403

* test(utils): add comprehensive circuit breaker unit tests

Add 18 unit tests covering:
- Basic state (closed, open, half-open)
- State transitions and thresholds
- Timeout-based transitions
- State change callbacks
- Reset functionality
- Thread safety with concurrent operations
- State to string conversion
- Next attempt time validation

Refs: #403

* docs(changelog): add circuit breaker implementation entry

Add changelog entries for Circuit Breaker pattern implementation (#403):
- English and Korean versions updated
- Describes circuit_breaker class with three-state pattern
- Lists all configuration parameters and API additions
- Mentions resilient_client integration and test coverage

* fix(utils): add error_codes_ext namespace to fallback build path

Add error_codes_ext namespace with circuit_open error code to the
fallback block (when KCENON_WITH_COMMON_SYSTEM is not defined) in
result_types.h for API compatibility.

This fixes build failures when building without common_system
dependency, where resilient_client.cpp references error_codes_ext
which was only defined in the KCENON_WITH_COMMON_SYSTEM path.

* docs(changelog): add circuit breaker build fix entry

Document the fix for error_codes_ext namespace missing in fallback
build path. This fix ensures builds without common_system dependency
compile correctly.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[RESILIENCE] Implement Circuit Breaker pattern for network clients

1 participant