Circuit

Circuit is an efficient Go implementation of the circuit breaker pattern, similar to Netflix's Hystrix. It protects your service from downstream failures by:

• Preventing hangs: Detects downstream failures quickly and returns errors immediately instead of waiting for timeouts.
• Providing monitoring boundaries: Creates common metric names for downstream failure types and supports SLO tracking.
• Handling fallbacks: Provides a centralized place for fallback logic when a circuit is open or a call fails.
• Preventing overload: Allows downstream services to recover by limiting traffic during degraded states.
• Protecting dependencies: Shields dependencies from abnormal traffic rushes.

In v4, all metric and circuit interfaces have been updated to accept a context.Context as the first parameter. If you are using or implementing custom metric interfaces, you must update your method signatures to include ctx context.Context.

Example changes:

• Success(now time.Time, duration time.Duration) $\rightarrow$ Success(ctx context.Context, now time.Time, duration time.Duration)
• Closed(now time.Time) $\rightarrow$ Closed(ctx context.Context, now time.Time)

When upgrading from version 3 to version 4, several breaking changes and architectural shifts must be addressed:

• Dependency Management: Gopkg.toml and dep support have been removed. Use go.mod for dependency management.
• Directory Structure: The /v3 root directory has been removed; all core logic is now in the root directory.
• Statsd Metrics: The built-in statsd implementation has been moved to a separate repository. If you require statsd metrics, use cep21/circuit-statsd.
• Atomics: The library now uses Go 1.19's built-in atomic package instead of a manual implementation.
• Benchmarks: Benchmarks are no longer part of this repository and have moved to cep21/circuit-benchmarks.

The project uses a Makefile for common development tasks:

• make: Fast development loop (build, test, and lint).
• make ci: Runs the full CI suite locally (build, go test -race -count 10, and golangci-lint run).
• make fuzz: Runs active fuzzing.
• make help: Displays the full target list.

To see the circuits in action, including the Hystrix stream and expvar metrics, run the example main file located in the example/ directory.

go run example/main.go

If you need to send metrics to multiple collectors simultaneously, use RunMetricsCollection. It implements the RunMetrics interface by broadcasting every call to all underlying collectors.

It also implements the expvar.Var interface via the Var() method, allowing you to expose the aggregated metrics of all collectors through Go's expvar package.

// Example of creating a collection
collection := RunMetricsCollection{
    &MyCustomRunMetrics{},
    &AnotherRunMetrics{},
}

// The collection can be used directly where RunMetrics is expected
collection.Success(ctx, time.Now(), duration)

Use MetricsCollection to broadcast circuit state change events (Opened and Closed) to multiple Metrics implementations simultaneously.

collection := MetricsCollection{
    &MyStateMetrics{},
}

collection.Opened(ctx, time.Now())

The Manager.DefaultCircuitProperties field accepts a slice of CommandPropertiesConstructor functions. These functions are used to apply global configuration defaults to every circuit created by the manager.

When CreateCircuit is called, these constructors are executed in reverse order. This allows you to define a base configuration and then append constructors that override specific parts of that base for all circuits.

type CommandPropertiesConstructor func(circuitName string) Config

Similar to RunMetricsCollection, FallbackMetricsCollection allows you to broadcast fallback telemetry to multiple collectors. It also implements expvar.Var to expose the metrics of all collectors in the collection via expvar.

collection := FallbackMetricsCollection{
    &MyCustomFallbackMetrics{},
}

collection.ErrFailure(ctx, time.Now(), duration)