hystrimp

Documentation

Overview

Package hystrimp contains a Go implementation of Netflix's Hystrix project.

Index

• Constants
• Variables
• func SetLogLevel(level LogLevel) error
• type Command
• type CommandCircuitBreakerOpenError
  • func (err *CommandCircuitBreakerOpenError) Error() string
• type CommandConfiguration
  • func NewCommandConfiguration(name string) *CommandConfiguration
• type CommonConfiguration
  • func NewCommonConfiguration(name string) *CommonConfiguration
• type ErrorHandler
• type ErrorHandlers
• type HandlerError
  • func (err *HandlerError) Error() string
• type LocalError
  • func (err *LocalError) Error() string
• type LogLevel
• type MockService
  • func (m *MockService) RegisterCommand(config *CommandConfiguration)
  • func (m *MockService) Run(name string, command Command, ...) error
  • func (m *MockService) RunAsync(name string, command Command, ...) chan<- error
• type RemoteError
  • func (err *RemoteError) Error() string
• type RetryWaitStrategy
• type Service
  • func NewService(config *ServiceConfiguration) Service
• type ServiceCircuitBreakerOpenError
  • func (err *ServiceCircuitBreakerOpenError) Error() string
• type ServiceConfiguration
• type TimeoutError
  • func (err *TimeoutError) Error() string

Constants

const (
	// RetryStrategyImmediate retries immediately.
	RetryStrategyImmediate RetryWaitStrategy = iota
	// RetryStrategyFixedDelay retries after a fixed delay.
	RetryStrategyFixedDelay
	// RetryStrategyExponentialBackoff retries after an exponentially-growing backoff.
	RetryStrategyExponentialBackoff

	// LevelDebug logs debug events and above.
	LevelDebug LogLevel = iota
	// LevelInfo logs only info events and above.
	LevelInfo
	// LevelWarn logs only warning events and above.
	LevelWarn
	// LevelError logs only error events and above.
	LevelError
	// LevelFatal logs only fatal events and above.
	LevelFatal
	// LevelPanic logs only panic events.
	LevelPanic
)

Variables

var (
	// WarnHandler "handles" errors by logging them as warnings and returning them (doesn't really handle them).
	WarnHandler = func(err error) (handled bool, handlerError error) {
		log.Warnln(err)
		return false, nil
	}

	// WarnHandlers is a set of error handlers which log warnings for each kind of error.
	WarnHandlers = &ErrorHandlers{
		Local:     WarnHandler,
		Timeout:   WarnHandler,
		Remote:    WarnHandler,
		ServiceCB: WarnHandler,
		CommandCB: WarnHandler,
	}
)

Functions

func SetLogLevel

func SetLogLevel(level LogLevel) error

SetLogLevel configures the verbosity of logging to the given level.

Types

type Command

type Command func() (localError, remoteError error)

Command is a wrapped operation of a remote service. Errors that are encountered locally are returned as localError. Errors that are caused remotely are returned through remoteError.

type CommandCircuitBreakerOpenError

type CommandCircuitBreakerOpenError struct {
	// Name is the name of the command whose circuit breaker is open.
	Name string
}

CommandCircuitBreakerOpenError arises when the command's circuit breaker is open at the time of running a command.

func (*CommandCircuitBreakerOpenError) Error

func (err *CommandCircuitBreakerOpenError) Error() string

type CommandConfiguration

type CommandConfiguration struct {
	// CommonConfiguration defines options common to both commands and services.
	CommonConfiguration

	// Timeout defines how long to wait for the command to finish before raising a TimeoutError.
	Timeout time.Duration

	// Retries defines the maximum number of retries when an unhandled TimeoutError or RemoteError is encountered.
	Retries int

	// RetryStrategy defines how to wait between retries.
	RetryStrategy RetryWaitStrategy

	// RetryInitialWait defines the initial wait between retries.
	RetryInitialWait time.Duration

	// RetryBackoffCeiling defines the maximum amount of time between retries, even with exponential backoff.
	RetryBackoffCeiling time.Duration
}

CommandConfiguration defines options with which commands should be run.

func NewCommandConfiguration

func NewCommandConfiguration(name string) *CommandConfiguration

NewCommandConfiguration constructs a new CommandConfiguration with some reasonable default values.

type CommonConfiguration

type CommonConfiguration struct {
	// Name is the name of the command or service.
	Name string

	// MaxConcurrentCommands bounds the number of parallel instances of the command that may run at once.
	MaxConcurrentCommands int

	// CBSleepWindow defines how long to wait after a circuit breaker opens before testing for recovery.
	CBSleepWindow time.Duration

	// CBRequestVolumeThreshold defines the minimum number of requests needed before a circuit can be tripped.
	CBRequestVolumeThreshold int

	// CBErrorPercentThreshold defines a failure percentage for requests that will cause the circuit breaker to be tripped.
	CBErrorPercentThreshold int
}

CommonConfiguration defines options that apply to both commands and services.

func NewCommonConfiguration

func NewCommonConfiguration(name string) *CommonConfiguration

NewCommonConfiguration constructs a new CommonConfiguration with some reasonable default values.

type ErrorHandler

type ErrorHandler func(err error) (handled bool, handlerError error)

ErrorHandler handles an error that was encountered while attempting to run a Command. Returns nil if the handler was able to handle the error. May return new errors that occur within the handler.

type ErrorHandlers

type ErrorHandlers struct {
	// Local handles errors that occur locally within the command.
	Local ErrorHandler
	// Timeout handles the command timing out.
	Timeout ErrorHandler
	// Remote handles errors for which the remote service is responsible.
	Remote ErrorHandler
	// CommandCB handles the command circuit breaker being open.
	CommandCB ErrorHandler
	// ServiceCB handles the service circuit breaker being open.
	ServiceCB ErrorHandler
}

ErrorHandlers defines a set of error handlers for use while attempting to run a command.

type HandlerError

type HandlerError struct {
	// Input is the error that the handler attempted to handle.
	Input error
	// Wrapped is the underlying error that the handler returned.
	Wrapped error
}

HandlerError arises when a handler attempts unsuccessfully to handle an error.

func (*HandlerError) Error

func (err *HandlerError) Error() string

type LocalError

type LocalError struct {
	// Wrapped is the underlying local error.
	Wrapped error
}

LocalError arises when the command encounters a local error that was not returned by the remote system.

func (*LocalError) Error

func (err *LocalError) Error() string

type LogLevel

type LogLevel uint8

LogLevel defines the verbosity of logging.

type MockService

type MockService struct {
	mock.Mock
}

func (*MockService) RegisterCommand

func (m *MockService) RegisterCommand(config *CommandConfiguration)

func (*MockService) Run

func (m *MockService) Run(name string, command Command, localHandler, timeoutHandler, remoteHandler, serviceCircuitBreakerOpenHandler,
	commandCircuitBreakerOpenHandler ErrorHandler) error

func (*MockService) RunAsync

func (m *MockService) RunAsync(name string, command Command, localHandler, timeoutHandler, remoteHandler, serviceCircuitBreakerOpenHandler,
	commandCircuitBreakerOpenHandler ErrorHandler) chan<- error

type RemoteError

type RemoteError struct {
	// Wrapped is the underlying remote error.
	Wrapped error
}

RemoteError arises when the command encounters an error that was returned by the remote system.

func (*RemoteError) Error

func (err *RemoteError) Error() string

type RetryWaitStrategy

type RetryWaitStrategy uint8

RetryWaitStrategy is a method of waiting between retrying commands after remote failures.

type Service

type Service interface {
	// RegisterCommand registers a command so that it can be run.
	RegisterCommand(config *CommandConfiguration)

	// Run executes the given registered command synchronously.
	// If error handlers are provided, invokes the appropriate error handler.
	// Returns any unhandled error (one of the error types below), else nil
	Run(name string, command Command, handlers *ErrorHandlers) error

	// RunAsync executes the given registered command asynchronously.
	// If error handlers are provided, invoke the appropriate error handler when errors are encountered.
	// Returns any unhandled error (one of the error types below), else nil
	RunAsync(name string, command Command, handlers *ErrorHandlers) chan<- error
}

Service sends commands to a wrapped remote service.

func NewService

func NewService(config *ServiceConfiguration) Service

NewService constructs a new Service with the provided configuration.

type ServiceCircuitBreakerOpenError

type ServiceCircuitBreakerOpenError struct {
	// Name is the name of the service whose circuit breaker is open.
	Name string
}

ServiceCircuitBreakerOpenError arises when the service's circuit breaker is open at the time of running a command.

func (*ServiceCircuitBreakerOpenError) Error

func (err *ServiceCircuitBreakerOpenError) Error() string

type ServiceConfiguration

type ServiceConfiguration struct {
	// CommonConfiguration defines options common to both commands and services.
	CommonConfiguration

	// CommandPreregistrations is a convenience for pre-registering commands at the time of service creation.
	CommandPreregistrations []*CommandConfiguration
}

ServiceConfiguration defines options to configure a service.

type TimeoutError

type TimeoutError struct {
	// Elapsed is the amount of time after which this timeout error was raised.
	Elapsed time.Duration
}

TimeoutError arises when command execution times out.

func (*TimeoutError) Error

func (err *TimeoutError) Error() string