hive

Documentation

Overview

Package hive provides the infrastructure for building Cilium applications from modular components (cells).

Hive is implemented using the uber/dig library, which provides the dependency injection for objects in the hive. It is similar to uber/fx, but adds an opinionated approach to configuration.

The configuration for cells is extracted from Viper. By default the field names are assumed to correspond to flag names, e.g. field 'MyOption' corresponds to '--my-option' flag.

The hive constructor, New(), takes the viper instance and the pflag FlagSet as parameters and registers the flags from all cells and binds them to viper variables. Once the FlagSet and viper configuration has been parsed one can call Populate() to pull the values from viper and construct the application. The hive can then be Run().

Example

For a runnable example see pkg/hive/example.

Try running:

example$ go run .
(ctrl-c stops)

example$ go run . --dot-graph | dot -Tx11

Try also commenting out cell.Provide lines and seeing what the dependency errors look like.

Index

• type DefaultLifecycle
  • func (lc *DefaultLifecycle) Append(hook HookInterface)
  • func (lc *DefaultLifecycle) PrintHooks()
  • func (lc *DefaultLifecycle) Start(ctx context.Context) error
  • func (lc *DefaultLifecycle) Stop(ctx context.Context) error
• type Hive
  • func New(cells ...cell.Cell) *Hive
  • func (h *Hive) AppendInvoke(invoke func() error)
  • func (h *Hive) Command() *cobra.Command
  • func (h *Hive) Populate() error
  • func (h *Hive) PrintDotGraph()
  • func (h *Hive) PrintObjects()
  • func (h *Hive) RegisterFlags(flags *pflag.FlagSet)
  • func (h *Hive) Run() error
  • func (h *Hive) SetEnvPrefix(prefix string)
  • func (h *Hive) SetTimeouts(start, stop time.Duration)
  • func (h *Hive) Shutdown(opts ...ShutdownOption)
  • func (h *Hive) Start(ctx context.Context) error
  • func (h *Hive) Stop(ctx context.Context) error
  • func (h *Hive) Viper() *viper.Viper
• type Hook
  • func (h Hook) Start(ctx HookContext) error
  • func (h Hook) Stop(ctx HookContext) error
• type HookContext
• type HookInterface
• type Lifecycle
• type ShutdownOption
  • func ShutdownWithError(err error) ShutdownOption
• type Shutdowner

Types

type DefaultLifecycle

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

DefaultLifecycle lifecycle implements a simple lifecycle management that conforms to Lifecycle. It is exported for use in applications that have nested lifecycles (e.g. operator).

func (*DefaultLifecycle) Append

func (lc *DefaultLifecycle) Append(hook HookInterface)

func (*DefaultLifecycle) PrintHooks

func (lc *DefaultLifecycle) PrintHooks()

func (*DefaultLifecycle) Start

func (lc *DefaultLifecycle) Start(ctx context.Context) error

func (*DefaultLifecycle) Stop

func (lc *DefaultLifecycle) Stop(ctx context.Context) error

type Hive

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

Hive is a framework building modular applications.

It implements dependency injection using the dig library.

See pkg/hive/example for a runnable example application.

func New

func New(cells ...cell.Cell) *Hive

New returns a new hive that can be run, or inspected. The command-line flags from the cells are registered as part of this.

The object graph is not constructed until methods of the hive are invoked.

Applications should call RegisterFlags() to register the hive's command-line flags. Likewise if configuration settings come from configuration files, then the Viper() method can be used to populate the hive's viper instance.

func (*Hive) AppendInvoke

func (h *Hive) AppendInvoke(invoke func() error)

func (*Hive) Command

func (h *Hive) Command() *cobra.Command

Command constructs the cobra command for hive. The hive command can be used to inspect the dependency graph.

func (*Hive) Populate

func (h *Hive) Populate() error

Populate instantiates the hive. Use for testing that the hive can be instantiated.

func (*Hive) PrintDotGraph

func (h *Hive) PrintDotGraph()

func (*Hive) PrintObjects

func (h *Hive) PrintObjects()

func (*Hive) RegisterFlags

func (h *Hive) RegisterFlags(flags *pflag.FlagSet)

RegisterFlags adds all flags in the hive to the given flag set. Fatals if a flag already exists in the given flag set. Use with e.g. cobra.Command:

cmd := &cobra.Command{...}
h.RegisterFlags(cmd.Flags())

func (*Hive) Run

func (h *Hive) Run() error

Run populates the cell configurations and runs the hive cells. Interrupt signal or call to Shutdowner.Shutdown() will cause the hive to stop.

func (*Hive) SetEnvPrefix

func (h *Hive) SetEnvPrefix(prefix string)

func (*Hive) SetTimeouts

func (h *Hive) SetTimeouts(start, stop time.Duration)

func (*Hive) Shutdown

func (h *Hive) Shutdown(opts ...ShutdownOption)

Shutdown implements the Shutdowner interface and is provided for the cells to use for triggering a early shutdown.

func (*Hive) Start

func (h *Hive) Start(ctx context.Context) error

Start starts the hive. The context allows cancelling the start. If context is cancelled and the start hooks do not respect the cancellation then after 5 more seconds the process will be terminated forcefully.

func (*Hive) Stop

func (h *Hive) Stop(ctx context.Context) error

Stop stops the hive. The context allows cancelling the stop. If context is cancelled and the stop hooks do not respect the cancellation then after 5 more seconds the process will be terminated forcefully.

func (*Hive) Viper

func (h *Hive) Viper() *viper.Viper

Viper returns the hive's viper instance.

type Hook

type Hook struct {
	OnStart func(HookContext) error
	OnStop  func(HookContext) error
}

Hook is a pair of start and stop callbacks. Both are optional. They're paired up to make sure that on failed start all corresponding stop hooks are executed.

func (Hook) Start

func (h Hook) Start(ctx HookContext) error

func (Hook) Stop

func (h Hook) Stop(ctx HookContext) error

type HookContext

type HookContext context.Context

HookContext is a context passed to a lifecycle hook that is cancelled in case of timeout. Hooks that perform long blocking operations directly in the start or stop function (e.g. connecting to external services to initialize) must abort any such operation if this context is cancelled.

type HookInterface

type HookInterface interface {
	// Start hook is called when the hive is started.
	// Returning a non-nil error causes the start to abort and
	// the stop hooks for already started cells to be called.
	//
	// The context is valid only for the duration of the start
	// and is used to allow aborting of start hook on timeout.
	Start(HookContext) error

	// Stop hook is called when the hive is stopped or start aborted.
	// Returning a non-nil error does not abort stopping. The error
	// is recorded and rest of the stop hooks are executed.
	Stop(HookContext) error
}

type Lifecycle

type Lifecycle interface {
	Append(HookInterface)
}

Lifecycle enables cells to register start and stop hooks, either from a constructor or an invoke function.

type ShutdownOption

type ShutdownOption interface {
	// contains filtered or unexported methods
}

func ShutdownWithError

func ShutdownWithError(err error) ShutdownOption

ShutdownWithError shuts down with an error.

type Shutdowner

type Shutdowner interface {
	Shutdown(...ShutdownOption)
}

Shutdowner provides Shutdown(), which is a way to trigger stop for hive.

To shut down with an error, call Shutdown with ShutdownWithError(err). This error will be returned from Run().