Documentation
¶
Overview ¶
Package breaker provides HTTP client-side circuit breaking for go-service.
It integrates circuit breaking into HTTP clients by wrapping an `http.RoundTripper`.
Breaker scope ¶
Breakers are maintained per request key (method + host), so each upstream is isolated.
Failure accounting vs caller behavior ¶
The wrapped `RoundTripper` classifies outcomes for breaker accounting:
- Transport errors (a non-nil error returned by the underlying `RoundTripper`) are counted as failures.
- HTTP responses with status codes classified as failures (see `WithFailureStatusFunc` / `WithFailureStatuses`) are also counted as failures.
When a response status code is treated as a failure for breaker accounting, the wrapper still returns the original `*http.Response` to the caller with a nil error. This allows application logic to continue to handle HTTP responses normally, while the circuit breaker learns about upstream health.
Start with `NewRoundTripper`.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶ added in v2.260.0
type Option interface {
// contains filtered or unexported methods
}
Option configures the HTTP circuit breaker `RoundTripper` created by `NewRoundTripper`.
Options are applied in the order provided to `NewRoundTripper`. If multiple options configure the same field, the last one wins.
func WithFailureStatusFunc ¶ added in v2.260.0
WithFailureStatusFunc configures the predicate that classifies an HTTP response status code as a failure for breaker accounting.
When the predicate returns true for a response status code, the breaker counts the call as a failure, but the `RoundTripper` still returns the original `*http.Response` to the caller with a nil error. This decouples breaker health tracking from application-level HTTP response handling.
func WithFailureStatuses ¶ added in v2.260.0
WithFailureStatuses configures a fixed set of HTTP status codes that are treated as failures for breaker accounting.
This is a convenience wrapper over `WithFailureStatusFunc`. The provided codes are stored in a set and membership is checked for each response.
Example: treat 502/503/504 as failures:
WithFailureStatuses(502, 503, 504)
func WithSettings ¶ added in v2.260.0
WithSettings configures the circuit breaker settings used for each per-upstream breaker instance.
The settings value is copied into each created breaker, and `NewRoundTripper` will also set:
- `Settings.Name` to the request key ("<METHOD> <HOST>"), and
- `Settings.IsSuccessful` to ensure responses classified as failures by this package's failure-status predicate are counted as failures for breaker accounting.
Note: because settings are copied, if your `Settings` contains function fields that close over mutable state, ensure that state is safe for concurrent use.
type RoundTripper ¶
type RoundTripper struct {
http.RoundTripper
// contains filtered or unexported fields
}
RoundTripper wraps an underlying `http.RoundTripper` and applies circuit breaking.
Breakers are cached per request key (method + host) so each upstream is isolated. Breakers are created lazily on first use and then reused for subsequent requests to the same key.
Use `NewRoundTripper` to construct instances with the desired settings and failure classification behavior.
func NewRoundTripper ¶
func NewRoundTripper(hrt http.RoundTripper, options ...Option) *RoundTripper
NewRoundTripper constructs an HTTP RoundTripper guarded by circuit breakers.
The returned `*RoundTripper` wraps the provided base transport (`hrt`) and executes each request through a circuit breaker keyed by the request destination.
Breaker scope ¶
A separate circuit breaker is maintained per request key: "<METHOD> <HOST>". The host is derived from `req.URL.Host`, falling back to `req.Host` (and finally "unknown"). This isolates failures per upstream.
Failure accounting and error semantics ¶
The breaker executes the underlying transport call and classifies the outcome for breaker accounting:
- Transport errors (i.e., the underlying RoundTripper returns a non-nil error) are counted as failures.
- HTTP responses whose `StatusCode` matches the configured failure-status predicate are also counted as failures.
Important: when a response status code is treated as a failure for breaker accounting, this RoundTripper still returns the response to the caller with a nil error. This means:
- Your application logic continues to be driven by the HTTP response status/body, and
- The breaker still "learns" that the upstream is unhealthy and may open accordingly.
Defaults: HTTP status codes >= 500 or 429 are treated as failures (see `defaultOpts` and `WithFailureStatusFunc`).
func (*RoundTripper) RoundTrip ¶
RoundTrip executes the request guarded by a circuit breaker.
If the breaker is open (or half-open and MaxRequests would be exceeded), the underlying breaker may reject the call and return an error (for example `breaker.ErrOpenState` or `breaker.ErrTooManyRequests`).
Failure accounting:
- Transport errors are counted as failures.
- Responses that match the configured failure-status predicate are counted as failures for breaker accounting, but the response is still returned to the caller with a nil error.
type Settings ¶ added in v2.261.0
Settings is an alias for `github.com/alexfalkowski/go-service/v2/breaker.Settings`.
It is re-exported from this package so callers can configure circuit breaker behavior (trip thresholds, timeouts, half-open probing, etc.) without importing the lower-level breaker package directly.
Source Files