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 ¶
Constants ¶
This section is empty.
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 ¶
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 ¶
Agent implements startup & shutdown procedures.
func NewAgent ¶
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 ¶ added in v1.0.7
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 ¶
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.
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).
type Injector ¶ added in v1.0.7
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.
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 ¶ added in v1.0.5
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 ¶
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 ¶ added in v1.0.4
func (marker *WithLoggerOpt) OptionMarkerCore()
OptionMarkerCore is just for marking implementation that implements this interface.
type WithPluginsOpt ¶ added in v1.0.7
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 ¶ added in v1.0.7
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 ¶
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 ¶ added in v1.0.4
func (marker *WithTimeoutOpt) OptionMarkerCore()
OptionMarkerCore is only for marking implementation that implements this interface.
Source Files