<commit_before># Overcurrent

[![GoDoc](https://godoc.org/github.com/efritz/overcurrent?status.svg)](https://godoc.org/github.com/efritz/overcurrent)
[![Build Status](https://secure.travis-ci.org/efritz/overcurrent.png)](http://travis-ci.org/efritz/overcurrent)
[![codecov.io](http://codecov.io/github/efritz/overcurrent/coverage.svg?branch=master)](http://codecov.io/github/efritz/overcurrent?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/efritz/overcurrent)](https://goreportcard.com/report/github.com/efritz/overcurrent)

Go library for protecting function calls via circuit breaker pattern.

The circuit breaker pattern can prevent an application from repeatedly trying to
execute an operation that is likely to fail. If the problem appears to have been
rectified, the application can attempt to invoke the operation. This is useful
in a distributed environment where an application accesses remote resources and
services. It is possible (and likely at scale) for these operations to fail due
to transient faults such as:

- timeouts
- slow network connections
- resource or service being overcommitted
- resource or service being temporarily unavailable

These faults typically correct themselves after a short period of time. You can
read more about the pattern
[here](https://msdn.microsoft.com/en-us/library/dn589784.aspx) and
[here](http://martinfowler.com/bliki/CircuitBreaker.html).

This library depends on the [backoff](https://github.com/efritz/backoff) library,
which defines structures for creating backoff interval generator.

## Example

First, create an instance of a `Breaker` with the following customizable config
parameters. The `InvocationTimeout` specifies how long a protected function can
run for before returning an error (zero allows for unbounded runtime).

The `ResetBackoff` specifies how long the circuit breaker stays in the open state
until transitioning to the half-closed state. If a failure occurs while in the
half-closed state, the circuit breaker will transition back to the open state, and
the time spent before transitioning to the half-closed state may increase, depending
on the implementation of the backoff interface.

The `HalfClosedRetryProbability` specifies the probability that a request in the
half-closed state will attempt to retry instead of immediately returning a
`CircuitOpenError`.

```go
breaker := NewCircuitBreaker(&CircuitBreakerConfig {
	InvocationTimeout:          50 * time.Milliecond,
	ResetBackoff:               backoff.NewConstantBackoff(1 * time.Second),
	HalfClosedRetryProbability: 0.1,
	FailureInterpreter:         NewAnyErrorFailureInterpreter(),
	TripCondition:              NewConsecutiveFailureTripCondition(5),
})
```

The `FailureInterpreter` determines which errors returned from the protected
function should count as a failure with respect to the circuit breaker. As an
example, the following failure interpreter will only count HTTP 500 errors as
a circuit error (given an omitted definition of the type ProtocolError).

```go
type ServerErrorFailureInterpreter struct{}

func (fi *ServerErrorFailureInterpreter) ShouldTrip(err error) bool {
	if perr, ok := err.(ProtocolError); ok {
		return perr.StatusCode >= 500
	}

	return false
}<commit_msg>Update README.<commit_after># Overcurrent

[![GoDoc](https://godoc.org/github.com/efritz/overcurrent?status.svg)](https://godoc.org/github.com/efritz/overcurrent)
[![Build Status](https://secure.travis-ci.org/efritz/overcurrent.png)](http://travis-ci.org/efritz/overcurrent)
[![codecov.io](http://codecov.io/github/efritz/overcurrent/coverage.svg?branch=master)](http://codecov.io/github/efritz/overcurrent?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/efritz/overcurrent)](https://goreportcard.com/report/github.com/efritz/overcurrent)

Go library for protecting function calls via circuit breaker pattern.

The circuit breaker pattern can prevent an application from repeatedly trying to
execute an operation that is likely to fail. If the problem appears to have been
rectified, the application can attempt to invoke the operation. This is useful
in a distributed environment where an application accesses remote resources and
services. It is possible (and likely at scale) for these operations to fail due
to transient faults such as:

- timeouts
- slow network connections
- resource or service being overcommitted
- resource or service being temporarily unavailable

These faults typically correct themselves after a short period of time. You can
read more about the pattern
[here](https://msdn.microsoft.com/en-us/library/dn589784.aspx) and
[here](http://martinfowler.com/bliki/CircuitBreaker.html).

This library depends on the [backoff](https://github.com/efritz/backoff) library,
which defines structures for creating backoff interval generator.

## Example

First, create an instance of a `Breaker` with any of the following configuration
functions supplied. A circuit breaker can be created with all default parameters.

The `InvocationTimeout` specifies how long a protected function can
run for before returning an error (zero allows for unbounded runtime).

The `ResetBackoff` specifies how long the circuit breaker stays in the open state
until transitioning to the half-closed state. If a failure occurs while in the
half-closed state, the circuit breaker will transition back to the open state, and
the time spent before transitioning to the half-closed state may increase, depending
on the implementation of the backoff interface.

The `HalfClosedRetryProbability` specifies the probability that a request in the
half-closed state will attempt to retry instead of immediately returning a
`CircuitOpenError`.

```go
breaker := NewCircuitBreaker(
	WithInvocationTimeout(50 * time.Millisecond),
	WithResetBackoff(backoff.NewConstantBackoff(1 * time.Second)),
	WithHalfClosedRetryProbability(0.1),
	WithFailureInterpreter(NewAnyErrorFailureInterpreter()),
	WithTripCondition(NewConsecutiveFailureTripCondition(5)),
)
```

The `FailureInterpreter` determines which errors returned from the protected
function should count as a failure with respect to the circuit breaker. As an
example, the following failure interpreter will only count HTTP 500 errors as
a circuit error (given an omitted definition of the type ProtocolError).

```go
type ServerErrorFailureInterpreter struct{}

func (fi *ServerErrorFailureInterpreter) ShouldTrip(err error) bool {
	if perr, ok := err.(ProtocolError); ok {
		return perr.StatusCode >= 500
	}

	return false
}
{'fraction_non_alphanumeric': 0.07908396946564886, 'fraction_numerical': 0.00549618320610687, 'mean_word_length': 5.416258570029383, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1904318', 'n_tokens_mistral': 1778, 'n_tokens_neox': 1708, 'n_words': 676}