stability

README

Go Stability library

A library that allows developers to use the Circuitbreaker- and Retry-pattern on requests.

Project wiki

See: Main.md

Project status

4S maturity level: prototyping.

Prerequisites

You need to have the following software installed

Go (golang) (https://golang.org/) librdkafka (https://github.com/confluentinc/confluent-kafka-go#installing-librdkafka)

Building:

This library does not contain a main package, and therefore cannot be built on its own.

Usage

To use this library, it must be included in a project containing a main-package.

To include this library run the following command in your terminal/shell:

go get "bitbucket.org/4s/go-stability"

After retrieving the library, the library can be included by importing it, in the files in which it is required:

package ...
import (
  ...
  stability "bitbucket.org/4s/go-stability"
)
...
agent := stability.NewAgent("Name")
client := http.Client{}

err := agent.Do(
    func() error {
        // create request
        req, err := http.NewRequest(
            "GET",
            "http://example.org",
            nil,
        )
        if err != nil {
            // handle error
        }
        // execute request and get response
        resp, err := client.Do(req)
        if err != nil {
            // handle error
        }
        defer resp.Body.Close()

        // handle response
        ...
        return nil
    },
)
...

Environment variables

This library uses no environment variables

Test

To run unit tests:

go test

Documentation

Index

• Variables
• func DefaultReadyToTrip(counts Counts) bool
• type Agent
  • func NewAgent(name string) Agent
  • func (agent Agent) Do(req func() error) error
  • func (agent *Agent) SetCircuitBreaker(circuitBreaker *CircuitBreaker)
  • func (agent *Agent) SetRetry(retry *Retry)
• type CircuitBreaker
  • func NewCircuitBreaker(name string) *CircuitBreaker
  • func (cb *CircuitBreaker) Do(req func() error) func() error
  • func (cb *CircuitBreaker) SetInterval(interval time.Duration)
  • func (cb *CircuitBreaker) SetMaxRequests(maxRequests uint32)
  • func (cb *CircuitBreaker) SetOnStateChange(onStateChange func(from State, to State))
  • func (cb *CircuitBreaker) SetReadyToTrip(readyToTrip func(counts Counts) bool)
  • func (cb *CircuitBreaker) SetTimeout(timeout time.Duration)
• type Counts
• type OnRetryFunc
• type Retry
  • func NewRetry(name string) *Retry
  • func (retry *Retry) Do(retryableFunc RetryableFunc) func() error
  • func (retry *Retry) SetAttempts(attempts uint)
  • func (retry *Retry) SetDelay(delay time.Duration)
  • func (retry *Retry) SetOnRetry(onRetry func(n uint, err error))
  • func (retry *Retry) SetRetryIf(retryIf func(error) bool)
• type RetryIfFunc
• type RetryableFunc
• type State
  • func (s State) String() (string, error)

Variables

var (
	// ErrTooManyRequests is returned when the CB state is half open and the requests count is over
	// the cb maxRequests
	ErrTooManyRequests = errors.New("too many requests")
	// ErrOpenState is returned when the CB state is open
	ErrOpenState = errors.New("circuit breaker is open")
)

var (
	// ErrRequestFailed is returned when a request has reached the maximum number of retries, and still fails.
	ErrRequestFailed = errors.New("RequestFailed")
)

Functions

func DefaultReadyToTrip

func DefaultReadyToTrip(counts Counts) bool

DefaultReadyToTrip is the default readyToTrip function, which returns true if the ConsecutiveFailures count is 5 or more, and false otherwise

Types

type Agent

type Agent struct {
	CircuitBreaker *CircuitBreaker
	Retry          *Retry
}

Agent is a struct used to make more resilient requests. It has the possibility to implement both the circuitbreaker and the retry stability pattern

func NewAgent

func NewAgent(name string) Agent

NewAgent functions as a constructor for Agent that returns a new instance of Agent

func (Agent) Do

func (agent Agent) Do(req func() error) error

Do is the main function of Agent and executes the request using the circuit breaker and/or the retry if they exist.

func (*Agent) SetCircuitBreaker

func (agent *Agent) SetCircuitBreaker(circuitBreaker *CircuitBreaker)

SetCircuitBreaker sets the CircuitBreaker of the Agent

func (*Agent) SetRetry

func (agent *Agent) SetRetry(retry *Retry)

SetRetry sets the Retry of the Agent

type CircuitBreaker

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

CircuitBreaker is a state machine to prevent sending requests that are likely to fail.

func NewCircuitBreaker

func NewCircuitBreaker(name string) *CircuitBreaker

NewCircuitBreaker functions as a constructor for CircuitBreaker that returns a new instance of CircuitBreaker

func (*CircuitBreaker) Do

func (cb *CircuitBreaker) Do(req func() error) func() error

Do executes the given request if the CircuitBreaker accepts it. Do returns an error instantly if the CircuitBreaker rejects the request. Otherwise, Do returns the result of the request. If a panic occurs in the request, the CircuitBreaker handles it as a failed request and causes the same panic again.

func (*CircuitBreaker) SetInterval

func (cb *CircuitBreaker) SetInterval(interval time.Duration)

SetInterval sets the cyclic period of the closed state for the CircuitBreaker to clear the internal Counts. If set to zero the internal counts will not be cleared.

func (*CircuitBreaker) SetMaxRequests

func (cb *CircuitBreaker) SetMaxRequests(maxRequests uint32)

SetMaxRequests the maximum amount of requests allowed while the circuitbreaker is in half-open state

func (*CircuitBreaker) SetOnStateChange

func (cb *CircuitBreaker) SetOnStateChange(onStateChange func(from State, to State))

SetOnStateChange sets the function called when the CircuitBreaker changes state

func (*CircuitBreaker) SetReadyToTrip

func (cb *CircuitBreaker) SetReadyToTrip(readyToTrip func(counts Counts) bool)

SetReadyToTrip sets the function for determining whether the circuitbreaker is ready to transition into open state.

func (*CircuitBreaker) SetTimeout

func (cb *CircuitBreaker) SetTimeout(timeout time.Duration)

SetTimeout sets the period of the open state, after which the state of the CircuitBreaker becomes half-open

type Counts

type Counts struct {
	Requests             uint32
	TotalSuccesses       uint32
	TotalFailures        uint32
	ConsecutiveSuccesses uint32
	ConsecutiveFailures  uint32
}

Counts holds the numbers of requests and their successes/failures. CircuitBreaker clears the internal Counts either on the change of the state or at the closed-state intervals. Counts ignores the results of the requests sent before clearing.

type OnRetryFunc

type OnRetryFunc func(n uint, err error)

OnRetryFunc is the function signature of the type of function that can be called on retries.

type Retry

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

Retry is a struct representing the retry functionality.

func NewRetry

func NewRetry(name string) *Retry

NewRetry functions as a constructor for Retry that returns a new instance of Retry

func (*Retry) Do

func (retry *Retry) Do(retryableFunc RetryableFunc) func() error

Do is the main method of Retry and executes and retries the retryable function

func (*Retry) SetAttempts

func (retry *Retry) SetAttempts(attempts uint)

SetAttempts is a method for setting the amount of attempts for Retry. If set to 0, there will be no limit to the amount of retries.

func (*Retry) SetDelay

func (retry *Retry) SetDelay(delay time.Duration)

SetDelay is a method for setting the initial delay in ms of Retry

func (*Retry) SetOnRetry

func (retry *Retry) SetOnRetry(onRetry func(n uint, err error))

SetOnRetry is a method for setting the onRetry function of Retry.

func (*Retry) SetRetryIf

func (retry *Retry) SetRetryIf(retryIf func(error) bool)

SetRetryIf is a method for setting the retryIf function of Retry.

type RetryIfFunc

type RetryIfFunc func(error) bool

RetryIfFunc is the function signature of the type of function that can be used to determine whether or not the retryable function should be retried upon failure.

type RetryableFunc

type RetryableFunc func() error

RetryableFunc is the function signature of a function that is retryable by this library

type State

type State int

State is a type that represents a state of CircuitBreaker.

const (
	StateClosed State = iota
	StateHalfOpen
	StateOpen
)

These constants are states of CircuitBreaker.

func (State) String

func (s State) String() (string, error)

String returns a stringified version of the state