circuitbreaker

README

Circuit Breaker

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

---

Русский

Описание

Circuit Breaker — лёгкая и потокобезопасная реализация паттерна Circuit Breaker на Go. В текущей версии API ориентирован на менеджер circuit breakers, который позволяет управлять набором CB для разных сервисов/серверов.

Ключевые возможности

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

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

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

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

1. Создайте менеджер:

// создаёт менеджер circuit breakers
mgr := circuitbreaker.NewCBManager()

1. Инициализируйте набор сервисов:

cfg := circuitbreaker.CircuitBreakerConf{
    FailureThreshold: 5,
    RecoveryTimeout:  10 * time.Second,
    SuccessThreshold: 3,
    HalfOpenPrc:      20,
}
servers := []string{"service1", "service2"}
mgr.InitCircuitBreakers(servers, cfg)

1. Проверка возможности запроса и отчёт о результате:

allowed, state := mgr.AllowRequest("service1")
if allowed {
    // Выполняем запрос...
    // при успехе:
    mgr.ReportSuccess("service1")
    // при ошибке:
    mgr.ReportFailure("service1")
} else {
    // Обработка заблокированного запроса (state содержит состояние)
}

1. Получение статистики и состояния:

stats := mgr.GetCircuitBreakerStats()
stateStr := mgr.GetCircuitBreakerState("service1")

Состояния

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

---

English

Description

Circuit Breaker is a lightweight and thread-safe implementation of the Circuit Breaker pattern in Go. The current version's API is focused on a circuit breakers manager, which allows managing a set of CBs for different services/servers.

Key Features

• Protection from cascading failures.
• Automatic recovery after a timeout.
• Flexible configuration of thresholds and allowed percentage in half-open.
• Thread safety implemented via sync.RWMutex.
• Statistics and textual state representation for each CB.

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

1. Create a manager:

// Creates a circuit breaker manager
mgr := circuitbreaker.NewCBManager()

1. Initialize a set of services:

cfg := circuitbreaker.CircuitBreakerConf{
    FailureThreshold: 5,
    RecoveryTimeout:  10 * time.Second,
    SuccessThreshold: 3,
    HalfOpenPrc:      20,
}
servers := []string{"service1", "service2"}
mgr.InitCircuitBreakers(servers, cfg)

1. Request permission check and result reporting:

allowed, state := mgr.AllowRequest("service1")
if allowed {
    // Execute the request...
    // on success:
    mgr.ReportSuccess("service1")
    // on error:
    mgr.ReportFailure("service1")
} else {
    // Handle blocked request (state contains the current state)
}

1. Retrieve statistics and state:

stats := mgr.GetCircuitBreakerStats()
stateStr := mgr.GetCircuitBreakerState("service1")

States

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

Documentation

Overview

Circuit Breaker паттерн для управления отказами в распределенных системах. Используется для предотвращения повторных неудачных запросов к сервисам, которые могут быть временно недоступны. Позволяет снизить нагрузку на проблемные сервисы. Имеет три состояния:

					closed(замкнутое состояние, когда запросы пропускаются к сервису),
 					open (разомкнутое состо]ние, когда запросы не пропускаются к проблемному сервису)
					half-open(частично разомкнутое состояние, когда часть запросов пропускается для проверки доступности сервиса).

Index

• type CBManager
  • func NewCBManager() *CBManager
  • func (m *CBManager) AllowRequest(serverURL string) (bool, State)
  • func (m *CBManager) GetCircuitBreaker(serverURL string) *circuitBreaker
  • func (m *CBManager) GetCircuitBreakerState(serverURL string) string
  • func (m *CBManager) GetCircuitBreakerStats() map[string]any
  • func (m *CBManager) InitCircuitBreakers(servers []string, cfg CircuitBreakerConf) (cbInitErr []error)
  • func (m *CBManager) ReportFailure(serverURL string)
  • func (m *CBManager) ReportSuccess(serverURL string)
• type CircuitBreakerConf
• type State
  • func (s State) String() string

Types

type CBManager

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

func NewCBManager

func NewCBManager() *CBManager

NewManager создает новый менеджер circuit breakers

func (*CBManager) AllowRequest

func (m *CBManager) AllowRequest(serverURL string) (bool, State)

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

func (*CBManager) GetCircuitBreaker

func (m *CBManager) GetCircuitBreaker(serverURL string) *circuitBreaker

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

func (*CBManager) GetCircuitBreakerState

func (m *CBManager) GetCircuitBreakerState(serverURL string) string

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

func (*CBManager) GetCircuitBreakerStats

func (m *CBManager) GetCircuitBreakerStats() map[string]any

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

func (*CBManager) InitCircuitBreakers

func (m *CBManager) InitCircuitBreakers(servers []string, cfg CircuitBreakerConf) (cbInitErr []error)

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

func (*CBManager) ReportFailure

func (m *CBManager) ReportFailure(serverURL string)

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

func (*CBManager) ReportSuccess

func (m *CBManager) ReportSuccess(serverURL string)

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

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 uint8

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

func (State) String

func (s State) String() string

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