cell

type AllSettings ¶

type AllSettings map[string]any

type Cell ¶

type Cell interface {
	// Info provides a structural summary of the cell for printing purposes.
	Info(container) Info

	// Apply the cell to the dependency graph container.
	Apply(container) error
}

Cell is the modular building block of the hive.

A cell can be constructed with:

• Module(): Create a named set of cells.
• Provide(): Provide object constructors.
• Invoke(): Invoke a function to instantiate objects.
• Decorate(): Decorate a set of cells to augment an object.
• Config(): Cell providing a configuration struct.

func Config[Cfg Flagger](def Cfg) Cell

func Decorate(dtor any, cells ...Cell) Cell

cell.Decorate(
	func(e Example) Example {
		return e.WithMoreMagic()
	},
	cell.Invoke(func(e Example) {
		// e now has more magic
	},
)

func Group(cells ...Cell) Cell

func Invoke(funcs ...any) Cell

func Module(id, description string, cells ...Cell) Cell

endpoint-manager: Manages and provides access to endpoints
^- id             ^- description

func Provide(ctors ...any) Cell

func() A
func(A, B, C) (D, error).

type params struct {
	cell.In
	Flower *Flower
	Sun *Sun
}

type out struct {
	cell.Out
	Honey *Honey
	Nectar *Nectar
}

func newBee(params) (out, error)

func ProvidePrivate(ctors ...any) Cell

type DecodeHooks ¶

type DecodeHooks []mapstructure.DecodeHookFunc

type DefaultLifecycle ¶

type DefaultLifecycle struct {
	LogThreshold time.Duration
	// 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 (lc *DefaultLifecycle) Append(hook HookInterface)

func (lc *DefaultLifecycle) PrintHooks()

func (lc *DefaultLifecycle) Start(log *slog.Logger, ctx context.Context) error

func (lc *DefaultLifecycle) Stop(log *slog.Logger, ctx context.Context) error

type Flagger ¶

type Flagger interface {
	// Flags registers the configuration options as command-line flags.
	//
	// By convention a flag name matches the field name
	// if they're the same under case-insensitive comparison when dashes are
	// removed. E.g. "my-config-flag" matches field "MyConfigFlag". The
	// correspondence to the flag can be also specified with the mapstructure
	// tag: MyConfigFlag `mapstructure:"my-config-flag"`.
	//
	// Exported fields that are not found from the viper settings will cause
	// hive.Run() to fail. Unexported fields are ignored.
	//
	// See https://pkg.go.dev/github.com/mitchellh/mapstructure for more info.
	Flags(*pflag.FlagSet)
}

Flagger is implemented by configuration structs to provide configuration for a cell.

type FullModuleID ¶

type FullModuleID []string

FullModuleID is the fully qualified module identifier, e.g. the concat of nested module ids, e.g. "agent.controlplane.endpoint-manager". Provided in the module's scope.

func (f FullModuleID) String() string

type Health ¶

type Health interface {
	// OK declares that a Module has achieved a desired state and has not entered
	// any unexpected or incorrect states.
	// Modules should only declare themselves as 'OK' once they have stabilized,
	// rather than during their initial state. This should be left to be reported
	// as the default "unknown" to denote that the module has not reached a "ready"
	// health state.
	OK(status string)

	// Stopped reports that a module has completed, and will no longer report any
	// health status.
	// Implementations should differentiate that a stopped module may also be OK or Degraded.
	// Stopping a reporting should only affect future updates.
	Stopped(reason string)

	// Degraded declares that a module has entered a degraded state.
	// This means that it may have failed to provide it's intended services, or
	// to perform it's desired task.
	Degraded(reason string, err error)

	// NewScope constructs a new scoped health reporter.
	NewScope(name string) Health

	// Close closes this health scope and removes it. This is distinct from
	// 'Stopped' in that after closing the health status will disappear completely.
	Close()
}

Health provides a method of declaring a Modules health status.

The interface is meant to be used with "ModuleDecorator" to inject it into the scope of modules.

Implementation for health reporting is not included with the Hive library.

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 (h Hook) Start(ctx HookContext) error

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(HookContext) error
	Stop(HookContext) error
}

HookInterface wraps the Start and Stop methods that can be appended to an application lifecycle.

type In ¶

type In = dig.In

In when embedded into a struct used as constructor parameter makes the exported values of that struct become dependency injected values. In other words, it allows moving a long list of constructor parameters into a struct.

Struct fields can be annotated with `optional:"true"` to make the dependency optional. If the type is not found in the dependency graph, the value is set to the zero value.

See https://pkg.go.dev/go.uber.org/dig#In for more information.

type Info ¶

type Info interface {
	Print(indent int, w *InfoPrinter)
}

Info provides a simple way of printing cells hierarchically in textual form.

type InfoLeaf ¶

type InfoLeaf string

func (l InfoLeaf) Print(indent int, w *InfoPrinter)

type InfoNode ¶

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

func NewInfoNode(header string) *InfoNode

func (n *InfoNode) Add(child Info)

func (n *InfoNode) AddLeaf(format string, args ...any)

func (n *InfoNode) Print(indent int, w *InfoPrinter)

type InfoPrinter ¶

type InfoPrinter struct {
	io.Writer
	// contains filtered or unexported fields
}

func NewInfoPrinter() *InfoPrinter

type InfoStruct ¶

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

func (n *InfoStruct) Print(indent int, w *InfoPrinter)

type InvokerList ¶

type InvokerList interface {
	AppendInvoke(func(*slog.Logger, time.Duration) error)
}

type Level ¶

type Level string

Level denotes what kind an update is.

const (
	// StatusUnknown is the default status of a Module, prior to it reporting
	// any status.
	// All created
	StatusUnknown Level = "Unknown"

	// StatusStopped is the status of a Module that has completed, further updates
	// will not be processed.
	StatusStopped Level = "Stopped"

	// StatusDegraded is the status of a Module that has entered a degraded state.
	StatusDegraded Level = "Degraded"

	// StatusOK is the status of a Module that has achieved a desired state.
	StatusOK Level = "OK"
)

type Lifecycle ¶

type Lifecycle interface {
	Append(HookInterface)

	Start(*slog.Logger, context.Context) error
	Stop(*slog.Logger, context.Context) error
	PrintHooks()
}

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

type ModuleDecorator ¶

type ModuleDecorator any

ModuleDecorator is the optional decorator function used for each module to provide or replace objects in each module's scope. Supplied with [hive.Options] field 'ModuleDecorators'.

This can be used to provide module-specific instances of objects application wide, similar to how *slog.Logger is provided by default.

type ModuleDecorators ¶

type ModuleDecorators []ModuleDecorator

type ModuleID ¶

type ModuleID string

ModuleID is the module identifier. Provided in the module's scope.

type ModulePrivateProvider ¶

type ModulePrivateProvider any

type ModulePrivateProviders ¶

type ModulePrivateProviders []ModulePrivateProvider

type Out ¶

type Out = dig.Out

Out when embedded into a struct that is returned by a constructor will make the values in the struct become objects in the dependency graph instead of the struct itself.

See https://pkg.go.dev/go.uber.org/dig#Out for more information.

type RootLogger ¶

type RootLogger *slog.Logger

RootLogger is the unscoped logger without any attrs added to it.

type SimpleHealth ¶

type SimpleHealth struct {
	Scope  string
	Level  Level
	Status string
	Error  error
	// contains filtered or unexported fields
}

func (h *SimpleHealth) Close()

func (h *SimpleHealth) Degraded(reason string, err error)

func (h *SimpleHealth) GetChild(fullName string) *SimpleHealth

func (h *SimpleHealth) NewScope(name string) Health

func (h *SimpleHealth) OK(status string)

func (h *SimpleHealth) Stopped(reason string)