circuitbreaker

README

Circuit Breaker

🇷🇺 Русский | 🇬🇧 English

---

Русский

Описание

Circuit Breaker — простая и эффективная реализация паттерна Circuit Breaker на Go. Этот паттерн помогает защищать сервисы от лавинообразных сбоев, ограничивая количество запросов к нестабильным или недоступным внешним системам.

Преимущества использования

• Защита от лавинообразных сбоев: предотвращает перегрузку зависимых сервисов.
• Автоматическое восстановление: после таймаута Circuit Breaker пробует восстановить соединение.
• Гибкая настройка: можно задать пороги ошибок, таймауты и процент пропускаемых запросов в half-open состоянии.
• Потокобезопасность: реализовано с использованием sync.RWMutex.

Диаграмма переходов состояний

stateDiagram-v2
    [*] --> Closed
    Closed --> Open: Ошибок >= порога
    Open --> HalfOpen: Таймаут восстановления
    HalfOpen --> Closed: Успехов >= порога
    HalfOpen --> Open: Любая ошибка
    Open --> Open: До истечения таймаута
    Closed --> Closed: Успех или ошибка < порога

Быстрый старт

import "github.com/yourname/circuitbreaker"

cb := circuitbreaker.New("my-service", circuitbreaker.CircuitBreakerConf{
    FailureThreshold: 5,
    RecoveryTimeout:  10 * time.Second,
    SuccessThreshold: 3,
    HalfOpenPrc:      20,
})

if cb.Allow() {
    // Выполнить запрос
    // ...
    cb.Success() // если успешно
    // cb.Failure() // если ошибка
}

Состояния

• Closed — все запросы разрешены.
• Open — все запросы блокируются.
• Half-Open — часть запросов разрешена для проверки восстановления.

---

English

Description

Circuit Breaker is a simple and effective implementation of the Circuit Breaker pattern in Go. This pattern helps protect services from cascading failures by limiting requests to unstable or unavailable external systems.

Advantages

• Prevents cascading failures: protects dependent services from overload.
• Automatic recovery: after a timeout, the circuit breaker tries to restore the connection.
• Flexible configuration: set error thresholds, timeouts, and allowed request percentage in half-open state.
• Thread-safe: implemented using sync.RWMutex.

State Transition Diagram

stateDiagram-v2
    [*] --> Closed
    Closed --> Open: Errors >= threshold
    Open --> HalfOpen: Recovery timeout
    HalfOpen --> Closed: Successes >= threshold
    HalfOpen --> Open: Any error
    Open --> Open: Before timeout
    Closed --> Closed: Success or errors < threshold

Quick Start

import "github.com/yourname/circuitbreaker"

cb := circuitbreaker.New("my-service", circuitbreaker.CircuitBreakerConf{
    FailureThreshold: 5,
    RecoveryTimeout:  10 * time.Second,
    SuccessThreshold: 3,
    HalfOpenPrc:      20,
})

if cb.Allow() {
    // Perform request
    // ...
    cb.Success() // on success
    // cb.Failure() // on failure
}

States

• Closed — all requests are allowed.
• Open — all requests are blocked.
• Half-Open — some requests are allowed to test recovery.

---

Переключайте язык с помощью ссылок в

Documentation

Index

• Constants
• Variables
• func AllowRequest(serverURL string) bool
• func GetCircuitBreakerState(serverURL string) string
• func GetCircuitBreakerStats() map[string]any
• func InitCircuitBreakers(servers []string, cfg CircuitBreakerConf)
• func ReportFailure(serverURL string)
• func ReportSuccess(serverURL string)
• type CircuitBreaker
  • func GetCircuitBreaker(serverURL string) *CircuitBreaker
  • func New(name string, config CircuitBreakerConf) *CircuitBreaker
  • func (cb *CircuitBreaker) Allow() bool
  • func (cb *CircuitBreaker) Failure()
  • func (cb *CircuitBreaker) State() State
  • func (cb *CircuitBreaker) Stats() map[string]any
  • func (cb *CircuitBreaker) Success()
• type CircuitBreakerConf
• type State
  • func (s State) String() string

Constants

const Version = "0.1.0"

Variables

var (
	CircuitBreakers map[string]*CircuitBreaker
)

Functions

func AllowRequest

func AllowRequest(serverURL string) bool

AllowRequest проверяет, разрешен ли запрос к серверу

func GetCircuitBreakerState

func GetCircuitBreakerState(serverURL string) string

GetCircuitBreakerstate возвращает текстовое состояние Circuit Breaker

func GetCircuitBreakerStats

func GetCircuitBreakerStats() map[string]any

GetCircuitBreakerStats возвращает статистику всех Circuit Breakers

func InitCircuitBreakers

func InitCircuitBreakers(servers []string, cfg CircuitBreakerConf)

InitCircuitBreakers инициализирует Circuit Breakers для серверов

func ReportFailure

func ReportFailure(serverURL string)

ReportFailure отмечает неудачный запрос

func ReportSuccess

func ReportSuccess(serverURL string)

ReportSuccess отмечает успешный запрос

Types

type CircuitBreaker

type CircuitBreaker struct {
	// contains filtered or unexported fields
}

CircuitBreaker реализует паттерн Circuit Breaker

func GetCircuitBreaker

func GetCircuitBreaker(serverURL string) *CircuitBreaker

GetCircuitBreaker возвращает Circuit Breaker для сервера

func New

func New(name string, config CircuitBreakerConf) *CircuitBreaker

New создает новый Circuit Breaker

func (*CircuitBreaker) Allow

func (cb *CircuitBreaker) Allow() bool

Allow проверяет, разрешено ли выполнение запроса

func (*CircuitBreaker) Failure

func (cb *CircuitBreaker) Failure()

Failure отмечает неудачное выполнение запроса

func (*CircuitBreaker) State

func (cb *CircuitBreaker) State() State

State возвращает текущее состояние

func (*CircuitBreaker) Stats

func (cb *CircuitBreaker) Stats() map[string]any

Stats возвращает статистику

func (*CircuitBreaker) Success

func (cb *CircuitBreaker) Success()

Success отмечает успешное выполнение запроса

type CircuitBreakerConf

type CircuitBreakerConf struct {
	FailureThreshold int           `yaml:"failure_threshold"`
	RecoveryTimeout  time.Duration `yaml:"recovery_timeout"`
	SuccessThreshold int           `yaml:"success_threshold"`
	HalfOpenPrc      int           `yaml:"half_open_prc"` // Процент пропускаемых запросов
}

Структура для конфигурации Circuit Breaker

type State

type State int

State представляет состояние Circuit Breaker

const (
	StateClosed State = iota
	StateOpen
	StateHalfOpen
)

Возможные состояния

func (State) String

func (s State) String() string

String возвращает текстовое представление состояния