suturesrv

Documentation

Index

• Variables
• func AllReady(ctx context.Context, srvs ...Service) chan error
• func WaitForAllReady(ctx context.Context, srvs ...Service) error
• type BaseService
  • func NewBaseService(runFn RunFunc, logger log.StandardLogger) (*BaseService, error)
  • func (s *BaseService) Ready() ReadyChan
  • func (s *BaseService) Serve(ctx context.Context) error
  • func (s *BaseService) Start(ctx context.Context) (ReadyChan, chan error)
  • func (s *BaseService) Status() Status
  • func (s *BaseService) Stop() (chan struct{}, error)
• type BaseSupervisor
  • func NewBaseSupervisor(logger log.StandardLogger) (*BaseSupervisor, error)
  • func (s *BaseSupervisor) Serve(ctx context.Context) error
  • func (s *BaseSupervisor) ServeBackground(ctx context.Context) <-chan error
• type ReadyChan
• type RunFunc
• type Service
• type Status

Variables

var (
	ErrRunFnMustBeSpecified = errors.New("runFn must be specified")
	ErrAlreadyRunning       = errors.New("already running")
	ErrNotRunning           = errors.New("not running")
)

var (
	ErrStoppedBeforeReady = errors.New("stopped before ready")
)

Functions

func AllReady

func AllReady(ctx context.Context, srvs ...Service) chan error

AllReady return an error channel which can be waited on for all passed services to be ready and get the error if any of the service fails to be ready or the context is done.

func WaitForAllReady

func WaitForAllReady(ctx context.Context, srvs ...Service) error

WaitForAllReady will block and repeatedly try to wait for all passed services to be ready, it will only return `nil` when all services are ready or return an error when `ctx is done.

Types

type BaseService

type BaseService struct {
	Logger log.StandardLogger
	// contains filtered or unexported fields
}

BaseService is the base implementation of a Service which can be embedded in actual services.

func NewBaseService

func NewBaseService(runFn RunFunc, logger log.StandardLogger,
) (*BaseService, error)

NewBaseService creates a new BaseService.

func (*BaseService) Ready

func (s *BaseService) Ready() ReadyChan

func (*BaseService) Serve

func (s *BaseService) Serve(ctx context.Context) error

func (*BaseService) Start

func (s *BaseService) Start(ctx context.Context) (ReadyChan, chan error)

func (*BaseService) Status

func (s *BaseService) Status() Status

func (*BaseService) Stop

func (s *BaseService) Stop() (chan struct{}, error)

type BaseSupervisor

type BaseSupervisor struct {
	*suture.Supervisor

	Logger log.StandardLogger
	// contains filtered or unexported fields
}

BaseSupervisor is the base implementation of a Suture Supervisor which can be embedded in actual supervisors.

func NewBaseSupervisor

func NewBaseSupervisor(logger log.StandardLogger,
) (*BaseSupervisor, error)

NewBaseSupervisor creates a new BaseSupervisor.

func (*BaseSupervisor) Serve

func (s *BaseSupervisor) Serve(ctx context.Context) error

Serve starts the supervisor. You should call this on the top-level supervisor, but nothing else.

func (*BaseSupervisor) ServeBackground

func (s *BaseSupervisor) ServeBackground(ctx context.Context) <-chan error

ServeBackground starts running a supervisor in its own goroutine. When this method returns, the supervisor is guaranteed to be in a running state. The returned one-buffered channel receives the error returned by Serve.

type ReadyChan

type ReadyChan chan error

ReadyChan notifies that the Service is ready or failed to start and the error occurred. If the Service stops before `ready` is called, ReadyChan will send ErrStoppedBeforeReady.

type RunFunc

type RunFunc = func(ctx context.Context, ready func(err error)) error

RunFunc is called when Service.Serve is called either by a suture.Supervisor or manually.

A RunFunc should call `ready` with nil when the Service is ready or failed to start with the error occurred. If the Service stops before `ready` is called, Service.Ready will return a channel that sends ErrStoppedBeforeReady.

The Service should execute within the goroutine that this is called in, that is, it should not spawn a "worker" goroutine. If this function either returns error or panics, the Supervisor will call it again. `ready` should be called when the Service is ready to serve.

type Service

type Service interface {
	suture.Service

	// Status returns the status of the Service.
	Status() Status

	// Ready returns a ReadyChan to notify that the Service is ready or failed to start and the error occurred.
	// If the Service stops before `ready` is called, ReadyChan will send ErrStoppedBeforeReady.
	Ready() ReadyChan

	// Start can conveniently start the Service in a new goroutine without using a suture.Supervisor.
	// Return a ReadyChan the same as Ready, and a channel that sends the result of `Service.Serve`.
	//
	// Useful for writing tests for Service for example:
	// “`go
	// readyCh, resultCh := s.Start(context.Background())
	// require.NoError(t, <-readyCh)
	// defer require.NoError(t, <-resultCh)
	// “`
	Start(ctx context.Context) (ReadyChan, chan error)

	// Stop the Service manually if it's running by cancelling it's context , you can wait on the
	// returned channel for stopping to finish. Returns ErrNotRunning if it's not running.
	Stop() (chan struct{}, error)
}

Service is a Suture-based service interface.

Service's lifecycle graph:

                Serve()
StatusStopped ─────────► StatusStarted
 │                                │ │

runFn() returned │ ┌──────────────────────────────┘ │ ready() called in runFn()

 │ ▼  Stop() or context canceled    ▼
StatusStopping ◄───────- StatusReady/StatusFailed

type Status

type Status uint8

Status of a Service

const (
	// Not started or stopped
	StatusStopped Status = iota
	// Started but not yet ready to serve
	StatusStarted
	// Started and ready to serve
	StatusReady
	// Failed to start
	StatusFailed
	// Stopping
	StatusStopping
)