gcb

README

Generic Circuit Breakers

Heavily Inspired by hystrix-go.

Goals

• Golang Circuit Breakers with a clean and simple to use API
• Hierarchial circuits.

Hierarchical Circuits

Currently Theoretical

When calls are made to GCB a name is passed that is used to lookup which circuit to use. Traditionally this lets circuits be configured and triggered on a one by one basis. With a hierarchical setup we can create configurations that where settings are set and triggers are triggered in a cascading manner.

For example we could have the key www.example.com!80, and www.example.com!443. We can then configure it such that www.example.com and all child circuits fail at 90%, but then set the 443 child circuit to fail at 95%. Now if the average of both the 443 and 80 circuits hits 90% both child circuits will trigger.

Future Thoughts

• Use a pool or similar for things like timers to stop memory churn
• API for gathering circuit data and values

TODOs

• Ensure no leaking of threads
• Rework errors so they work with errors.Is

Documentation

Index

• Constants
• Variables
• func Go[T any](ctx context.Context, name string, primary func(context.Context) (T, error), ...) (T, bool, error)
• func SetDefaultSettings(s Settings)
• type Circuit
  • func GetCircuit(name string) *Circuit
  • func NewCircuit(name string) *Circuit
• type Error
  • func (e Error) Error() string
• type ErrorType
• type Settings
  • func GetDefaultSettings() Settings
  • func (s *Settings) Merge(s2 *Settings)
  • func (s Settings) String() string
• type Tree
  • func (n Tree) Circuit() *Circuit
  • func (r *Tree) Get(key string) Settings
  • func (n Tree) GetSettings() Settings
  • func (r *Tree) String() string

Constants

const (
	ErrorTimeout = "timeout"
	ErrorContext = "context"
)

Variables

var Separator = "!"

Separator is used to separate sub-keys for hierarchical settings.

Functions

func Go

func Go[T any](
	ctx context.Context,
	name string,
	primary func(context.Context) (T, error),
	fallback func(context.Context) (T, error),
) (T, bool, error)

Go calls your primary function, and if that fails calls your fallback function if provided.

Returns the output of the primary or fallback, along with true if the result was from the primary function, or false if it was from the fallback function or the library itself.

func SetDefaultSettings

func SetDefaultSettings(s Settings)

Types

type Circuit

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

func GetCircuit

func GetCircuit(name string) *Circuit

func NewCircuit

func NewCircuit(name string) *Circuit

type Error

type Error struct {
	Name    string `json:"name"`
	Type    string `json:"type"`
	Message string `json:"message"`
}

func (Error) Error

func (e Error) Error() string

type ErrorType

type ErrorType string

type Settings

type Settings struct {
	Timeout         *printable.Duration `json:"timeout"`
	PrimaryTimeout  *printable.Duration `json:"primary_timeout"`
	FallbackTimeout *printable.Duration `json:"fallback_timeout"`

	BreakPercent *float32 `json:"break_percent"`
}

Everything is a nil-pointer to allow optional settings.

func GetDefaultSettings

func GetDefaultSettings() Settings

func (*Settings) Merge

func (s *Settings) Merge(s2 *Settings)

func (Settings) String

func (s Settings) String() string

type Tree

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

func (Tree) Circuit

func (n Tree) Circuit() *Circuit

func (*Tree) Get

func (r *Tree) Get(key string) Settings

func (Tree) GetSettings

func (n Tree) GetSettings() Settings

func (*Tree) String

func (r *Tree) String() string