core

README

CN-Infra Core

The core package contains the CN-Infra Core that manages the startup and graceful shutdown of CN-Infra based applications. The startup & shutdown lifecycle is depicted in the sequence diagram below. The startup and shutdown behavior is described in comments for the Start() and Stop() functions in agent_core.go, and for the EventLoopWithInterrupt()function in event_loop.go.

The core package also defines the CN-Infra Core's SPI that must be implemented by each plugin (see Guidelines). The SPI is used by the Core to Init(), AfterInit() and Close() each plugin.

Documentation

Overview

Package core manages the lifecycle of all plugins (start, graceful shutdown) and defines the core lifecycle SPI. The core lifecycle SPI must be implemented by each plugin.

Index

• Variables
• func EventLoopWithInterrupt(agent *Agent, closeChan chan struct{}) error
• type Agent
  • func NewAgent(flavor Flavor, opts ...Option) *Agent
  • func NewAgentDeprecated(logger logging.Logger, maxStartup time.Duration, plugins ...*NamedPlugin) *Agent
  • func (agent *Agent) Start() error
  • func (agent *Agent) Stop() error
• type Flavor
  • func Inject(fs ...Flavor) Flavor
• type Injector
• type NamedPlugin
  • func ListPluginsInFlavor(flavor Flavor) (plugins []*NamedPlugin)
  • func (np *NamedPlugin) String() string
• type Option
• type Plugin
• type PluginName
• type PostInit
• type Timer
• type WithLoggerOpt
  • func WithLogger(logger logging.Logger) *WithLoggerOpt
  • func (marker *WithLoggerOpt) OptionMarkerCore()
• type WithPluginsOpt
  • func WithPlugin(pluginName string, plugin Plugin) WithPluginsOpt
• type WithTimeoutOpt
  • func WithTimeout(timeout time.Duration) *WithTimeoutOpt
  • func (marker *WithTimeoutOpt) OptionMarkerCore()

Variables

var (
	// BuildVersion describes version for the build. It is usually set using `git describe --always --tags --dirty`.
	BuildVersion string
	// BuildDate describes time of the build.
	BuildDate string
	// CommitHash describes commit hash for the build.
	CommitHash string
)

Variables set by the compiler using ldflags

var (
	// DefaultMaxStartupTime defines maximal duration of start for agent.
	DefaultMaxStartupTime = 15 * time.Second
)

Functions

func EventLoopWithInterrupt

func EventLoopWithInterrupt(agent *Agent, closeChan chan struct{}) error

EventLoopWithInterrupt starts an instance of the agent created with NewAgent(). Agent is stopped when <closeChan> is closed, a user interrupt (SIGINT), or a terminate signal (SIGTERM) is received.

Types

type Agent

type Agent struct {
	logging.Logger
	// contains filtered or unexported fields
}

Agent implements startup & shutdown procedures.

func NewAgent

func NewAgent(flavor Flavor, opts ...Option) *Agent

NewAgent returns a new instance of the Agent with plugins. Use options if needed: <WithLogger() option> will be used to log messages related to the agent life-cycle, but not for the plugins themselves. <WithTimeout() option> puts a time limit on initialization of all provided plugins. Agent.Start() returns ErrPluginsInitTimeout error if one or more plugins fail to initialize inside the specified time limit. <WithPlugins() option> is a variable list of plugins to load. ListPluginsInFlavor() helper method can be used to obtain the list from a given flavor.

Example 1 (existing flavor - or use alias rpc.NewAgent()):

   core.NewAgent(&FlavorRPC{}, core.WithTimeout(5 * time.Second), rpc.WithPlugins(func(flavor *FlavorRPC) []*core.NamedPlugins {
		return []*core.NamedPlugins{{"customization": &CustomPlugin{DependencyXY: &flavor.GRPC}}}
   })

Example 2 (custom flavor):

   core.NewAgent(&MyFlavor{}, core.WithTimeout(5 * time.Second), my.WithPlugins(func(flavor *MyFlavor) []*core.NamedPlugins {
		return []*core.NamedPlugins{{"customization": &CustomPlugin{DependencyXY: &flavor.XY}}}
   })

func NewAgentDeprecated

func NewAgentDeprecated(logger logging.Logger, maxStartup time.Duration, plugins ...*NamedPlugin) *Agent

NewAgentDeprecated older & deprecated version of a constructor Function returns a new instance of the Agent with plugins. <logger> will be used to log messages related to the agent life-cycle, but not for the plugins themselves. <maxStartup> sets a time limit for initialization of all provided plugins. Agent.Start() returns ErrPluginsInitTimeout error if one or more plugins fail to initialize in the specified time limit. <plugins> is a variable that holds a list of plugins to load. ListPluginsInFlavor() helper method can be used to obtain the list from a given flavor.

func (*Agent) Start

func (agent *Agent) Start() error

Start starts/initializes all selected plugins. The first iteration tries to run Init() method on every plugin from the list. If any of the plugins fails to initialize (Init() returns non-nil error), the initialization is cancelled by calling Close() method for already initialized plugins in the reverse order. The encountered error is returned by this function as-is. The second iteration does the same for the AfterInit() method. The difference is that AfterInit() is an optional method (not required by the Plugin interface, only suggested by PostInit interface) and therefore not necessarily called on every plugin. The startup/initialization must take no longer than maxStartup time limit, otherwise ErrPluginsInitTimeout error is returned.

func (*Agent) Stop

func (agent *Agent) Stop() error

Stop gracefully shuts down the Agent. It is called usually when the user interrupts the Agent from the EventLoopWithInterrupt().

This implementation tries to call Close() method on every plugin on the list in the reverse order. It continues even if some error occurred.

type Flavor

type Flavor interface {
	// Plugins returns a list of plugins.
	// Name of the plugin is supposed to be related to field name of Flavor struct.
	Plugins() []*NamedPlugin

	// Inject method is supposed to be implemented by each Flavor
	// to inject dependencies between the plugins.
	Injector

	// LogRegistry is a getter for accessing log registry (that allows to create new loggers)
	LogRegistry() logging.Registry
}

Flavor is a structure that contains a particular combination of plugins (fields of plugins).

func Inject

func Inject(fs ...Flavor) Flavor

Inject is a utility if you need to combine multiple flavorAggregator for in first parameter of NewAgent() It calls Inject() on every plugin.

Example:

NewAgent(Inject(&Flavor1{}, &Flavor2{}))

type Injector

type Injector interface {
	// When this method is called for the first time it returns true
	// (meaning the dependency injection ran at the first time).
	// It is possible to call this method repeatedly (then it will return false).
	Inject() (firstRun bool)
}

Injector is simple interface reused at least on two places: - Flavor - NewAgent constructor WithPlugins() option

type NamedPlugin

type NamedPlugin struct {
	PluginName
	Plugin
}

NamedPlugin represents a Plugin with a name.

func ListPluginsInFlavor

func ListPluginsInFlavor(flavor Flavor) (plugins []*NamedPlugin)

ListPluginsInFlavor lists plugins in a Flavor. It extracts all plugins and returns them as a slice of NamedPlugins.

func (*NamedPlugin) String

func (np *NamedPlugin) String() string

String returns the PluginName.

type Option

type Option interface {
	//OptionMarkerCore is just for marking implementation that implements this interface.
	OptionMarkerCore()
}

Option defines the maximum time for which the notification delivery is attempted.

type Plugin

type Plugin interface {
	// Init is called in the agent`s startup phase.
	Init() error
	// Close is called in the agent`s cleanup phase.
	Close() error
}

Plugin interface defines plugin's basic life-cycle methods.

type PluginName

type PluginName string

PluginName is a part of the plugin's API and it is supposed to be defined as a publicly accessible string constant. It is used to obtain the appropriate instance of the registry (there are multiple instances).

type PostInit

type PostInit interface {
	// AfterInit is called once Init() of all plugins have returned without error.
	AfterInit() error
}

PostInit interface defines an optional method for plugins with complex initialization.

type Timer

type Timer struct {
	// The startup/initialization must take no longer that maxStartup.
	MaxStartupTime time.Duration
	// contains filtered or unexported fields
}

Timer holds all startup times.

type WithLoggerOpt

type WithLoggerOpt struct {
	Logger logging.Logger
}

WithLoggerOpt defines a logger that logs if notification delivery is unsuccessful.

func WithLogger

func WithLogger(logger logging.Logger) *WithLoggerOpt

WithLogger creates an option for ToChan function that specifies a logger to be used.

func (*WithLoggerOpt) OptionMarkerCore

func (marker *WithLoggerOpt) OptionMarkerCore()

OptionMarkerCore is just for marking implementation that implements this interface.

type WithPluginsOpt

type WithPluginsOpt interface {
	Option

	// return list named plugins with injected dependencies
	// the order in list impacts the order of Init(), AfterInit(), Close() sequence
	Plugins(...Flavor) []*NamedPlugin
}

WithPluginsOpt is used in NewAgent()

func WithPlugin

func WithPlugin(pluginName string, plugin Plugin) WithPluginsOpt

WithPlugin for adding a custom plugins to the Agent

Example:

   flavor := &MyFlavor{}
	  flavor.Inject()
   NewAgent(myFlavor, WithPlugin("my-plugin", &MyPlugin{DependencyXY: &flavor.ETCD}))
   }))

type WithTimeoutOpt

type WithTimeoutOpt struct {
	Timeout time.Duration
}

WithTimeoutOpt defines the maximum time for which the notification delivery is attempted.

func WithTimeout

func WithTimeout(timeout time.Duration) *WithTimeoutOpt

WithTimeout creates an option for ToChan function that defines a notification delivery timeout.

func (*WithTimeoutOpt) OptionMarkerCore

func (marker *WithTimeoutOpt) OptionMarkerCore()

OptionMarkerCore is only for marking implementation that implements this interface.