bootstrap

README

Bootstrap

A Go package for managing service lifecycle with graceful startup and shutdown capabilities.

Features

• Flexible Service Management:

  • Ordered service startup and shutdown
  • Parallel service startup for unordered services
  • After-start services that run after main services
  • Graceful shutdown handling

• Health Checks:

  • Readiness checks for service availability
  • Liveness checks for service health
  • Custom error handling for failed health checks

• Resilient Operations:

  • Configurable restart policies using backoff strategies
  • Graceful shutdown with configurable timeouts
  • Context-based cancellation support

• Extensible Logging:

  • Context-aware logging methods
  • Flexible logger implementation

Installation

go get github.com/n-r-w/bootstrap

Usage

See example

Configuration Options

• WithStartTimeout(timeout time.Duration): Sets the timeout for service startup
• WithStopTimeout(timeout time.Duration): Sets the timeout for graceful shutdown
• WithHealthCheck(checker IHealthChecker): Configures health checking
• WithOrdered(services ...IService): Adds services that must start in order
• WithUnordered(services ...IService): Adds services that can start in parallel
• WithAfterStart(services ...IService): Adds services to start after all others
• WithRunFunc(func(context.Context) error): Sets a function to run after services start
• WithLogger(logger ILogger): Configures a custom logger

Service Interface

Services must implement the IService interface:

type IService interface {
    Info() Info
    Start(ctx context.Context) error
    Stop(ctx context.Context) error
}

The Info struct contains:

• Name: Service identifier
• RestartPolicy: Optional backoff configuration for restart attempts

Health Checks

Health checks can be added using the IHealthChecker interface

Executor package

Executor package provides an interface for executing a function at specified time intervals. Supports bootstrap.IService interface.

Documentation

Overview

Package bootstrap is a generated GoMock package.

Index

• type Bootstrap
  • func New(appName string) (*Bootstrap, error)
  • func (b *Bootstrap) Run(ctx context.Context, opts ...Option) error
• type CleanUpFunc
• type IHealthChecher
• type IService
• type Info
• type MockIHealthChecher
  • func NewMockIHealthChecher(ctrl *gomock.Controller) *MockIHealthChecher
  • func (m *MockIHealthChecher) AddCheckErrorHandler(handler func(string, error))
  • func (m *MockIHealthChecher) AddLivenessCheck(name string, check func() error)
  • func (m *MockIHealthChecher) AddReadinessCheck(name string, check func() error)
  • func (m *MockIHealthChecher) EXPECT() *MockIHealthChecherMockRecorder
• type MockIHealthChecherMockRecorder
  • func (mr *MockIHealthChecherMockRecorder) AddCheckErrorHandler(handler any) *gomock.Call
  • func (mr *MockIHealthChecherMockRecorder) AddLivenessCheck(name, check any) *gomock.Call
  • func (mr *MockIHealthChecherMockRecorder) AddReadinessCheck(name, check any) *gomock.Call
• type MockIService
  • func NewMockIService(ctrl *gomock.Controller) *MockIService
  • func (m *MockIService) EXPECT() *MockIServiceMockRecorder
  • func (m *MockIService) Info() Info
  • func (m *MockIService) Start(ctx context.Context) error
  • func (m *MockIService) Stop(ctx context.Context) error
• type MockIServiceMockRecorder
  • func (mr *MockIServiceMockRecorder) Info() *gomock.Call
  • func (mr *MockIServiceMockRecorder) Start(ctx any) *gomock.Call
  • func (mr *MockIServiceMockRecorder) Stop(ctx any) *gomock.Call
• type Option
  • func WithAfterStart(services ...IService) Option
  • func WithCleanUp(cleanUp ...CleanUpFunc) Option
  • func WithHealthCheck(hch IHealthChecher) Option
  • func WithLogger(logger ctxlog.ILogger) Option
  • func WithOrdered(services ...IService) Option
  • func WithRunFunc(runFunc func(context.Context) error) Option
  • func WithStartTimeout(timeout time.Duration) Option
  • func WithStopTimeout(timeout time.Duration) Option
  • func WithUnordered(services ...IService) Option

Types

type Bootstrap

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

Bootstrap - helper for starting services.

func New

func New(appName string) (*Bootstrap, error)

New - creates a new Bootstrap instance.

func (*Bootstrap) Run

func (b *Bootstrap) Run(ctx context.Context, opts ...Option) error

Run - starts all services and waits for stop signal.

type CleanUpFunc

type CleanUpFunc func(ctx context.Context) error

CleanUpFunc - function for cleaning up resources.

type IHealthChecher

type IHealthChecher interface {
	// AddReadinessCheck adds a check indicating that this instance
	// of the application currently cannot serve requests due to an external
	// dependency or some temporary failure. If the readiness check fails, this instance
	// should no longer receive requests, but it should not be restarted or
	// destroyed.
	AddReadinessCheck(name string, check func() error)
	// AddLivenessCheck adds a check indicating that this instance
	// of the application should be destroyed or restarted. A failed liveness
	// check indicates that this instance is not working.
	// Each liveness check is also included as a readiness check.
	AddLivenessCheck(name string, check func() error)
	// AddCheckErrorHandler adds a callback for handling a failed
	// check (for the purpose of logging errors, etc).
	// The function should not block the execution thread for a long time.
	AddCheckErrorHandler(handler func(name string, err error))
}

IHealthChecher interface for health checks.

type IService

type IService interface {
	// Info - returns service information.
	Info() Info
	// Start - starts the service.
	// WARNING:
	// The passed context contains a timeout for starting the service and will be canceled.
	// Therefore, it should not be used to create objects with a long lifecycle.
	Start(ctx context.Context) error
	// Stop - stops the service.
	Stop(ctx context.Context) error
}

IService - interface for a service that can be started and stopped.

type Info

type Info struct {
	// Name - service name.
	Name string
	// RestartPolicy - service restart policy on error. If empty, the service will not be restarted.
	RestartPolicy []backoff.RetryOption
}

Info - service information.

type MockIHealthChecher

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

MockIHealthChecher is a mock of IHealthChecher interface.

func NewMockIHealthChecher

func NewMockIHealthChecher(ctrl *gomock.Controller) *MockIHealthChecher

NewMockIHealthChecher creates a new mock instance.

func (*MockIHealthChecher) AddCheckErrorHandler

func (m *MockIHealthChecher) AddCheckErrorHandler(handler func(string, error))

AddCheckErrorHandler mocks base method.

func (*MockIHealthChecher) AddLivenessCheck

func (m *MockIHealthChecher) AddLivenessCheck(name string, check func() error)

AddLivenessCheck mocks base method.

func (*MockIHealthChecher) AddReadinessCheck

func (m *MockIHealthChecher) AddReadinessCheck(name string, check func() error)

AddReadinessCheck mocks base method.

func (*MockIHealthChecher) EXPECT

func (m *MockIHealthChecher) EXPECT() *MockIHealthChecherMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

type MockIHealthChecherMockRecorder

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

MockIHealthChecherMockRecorder is the mock recorder for MockIHealthChecher.

func (*MockIHealthChecherMockRecorder) AddCheckErrorHandler

func (mr *MockIHealthChecherMockRecorder) AddCheckErrorHandler(handler any) *gomock.Call

AddCheckErrorHandler indicates an expected call of AddCheckErrorHandler.

func (*MockIHealthChecherMockRecorder) AddLivenessCheck

func (mr *MockIHealthChecherMockRecorder) AddLivenessCheck(name, check any) *gomock.Call

AddLivenessCheck indicates an expected call of AddLivenessCheck.

func (*MockIHealthChecherMockRecorder) AddReadinessCheck

func (mr *MockIHealthChecherMockRecorder) AddReadinessCheck(name, check any) *gomock.Call

AddReadinessCheck indicates an expected call of AddReadinessCheck.

type MockIService

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

MockIService is a mock of IService interface.

func NewMockIService

func NewMockIService(ctrl *gomock.Controller) *MockIService

NewMockIService creates a new mock instance.

func (*MockIService) EXPECT

func (m *MockIService) EXPECT() *MockIServiceMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockIService) Info

func (m *MockIService) Info() Info

Info mocks base method.

func (*MockIService) Start

func (m *MockIService) Start(ctx context.Context) error

Start mocks base method.

func (*MockIService) Stop

func (m *MockIService) Stop(ctx context.Context) error

Stop mocks base method.

type MockIServiceMockRecorder

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

MockIServiceMockRecorder is the mock recorder for MockIService.

func (*MockIServiceMockRecorder) Info

func (mr *MockIServiceMockRecorder) Info() *gomock.Call

Info indicates an expected call of Info.

func (*MockIServiceMockRecorder) Start

func (mr *MockIServiceMockRecorder) Start(ctx any) *gomock.Call

Start indicates an expected call of Start.

func (*MockIServiceMockRecorder) Stop

func (mr *MockIServiceMockRecorder) Stop(ctx any) *gomock.Call

Stop indicates an expected call of Stop.

type Option

type Option func(*Bootstrap)

Option - function for configuring Bootstrap.

func WithAfterStart

func WithAfterStart(services ...IService) Option

WithAfterStart - sets services that should be started after all others. Startup happens in order after starting all other services. Shutdown happens in reverse order before stopping all other services.

func WithCleanUp

func WithCleanUp(cleanUp ...CleanUpFunc) Option

WithCleanUp - adds a function to be called during shutdown. Called in reverse order.

func WithHealthCheck

func WithHealthCheck(hch IHealthChecher) Option

WithHealthCheck - sets health.Handler for service readiness check.

func WithLogger

func WithLogger(logger ctxlog.ILogger) Option

WithLogger - sets logger for logging.

func WithOrdered

func WithOrdered(services ...IService) Option

WithOrdered - sets services that must be started in a specific order. Shutdown happens in reverse order after stopping services that don't require ordering.

func WithRunFunc

func WithRunFunc(runFunc func(context.Context) error) Option

WithRunFunc - sets a function to run. If set, the function will be called and then work will be completed.

func WithStartTimeout

func WithStartTimeout(timeout time.Duration) Option

WithStartTimeout - sets the timeout for graceful startup.

func WithStopTimeout

func WithStopTimeout(timeout time.Duration) Option

WithStopTimeout - sets the timeout for graceful shutdown.

func WithUnordered

func WithUnordered(services ...IService) Option

WithUnordered - sets services that can be started in parallel. Shutdown also happens in parallel before stopping services that require ordering.