agent

Documentation

Overview

Package agent provides the life-cycle management agent for plugins. It is intended to be used as a base point of an application used in main package.

Here is a common example usage:

func main() {
	plugin := myplugin.NewPlugin()

	a := agent.NewAgent(
		agent.Plugins(plugin),
	)
	if err := a.Run(); err != nil {
		log.Fatal(err)
	}
}

Options

There are various options available to customize agent:

Version(ver, date, id)	- sets version of the program
QuitOnClose(chan)   	- sets signal used to quit the running agent when closed
QuitSignals(signals)	- sets signals used to quit the running agent (default: SIGINT, SIGTERM)
StartTimeout(dur)   	- sets start timeout (default: 15s)
StopTimeout(dur)    	- sets stop timeout (default: 5s)

There are two options for adding plugins to the agent:

Plugins(...)	- adds just single plugins without lookup
AllPlugins(...)	- adds plugin along with all of its plugin deps

Index

• Variables
• type Agent
  • func NewAgent(opts ...Option) Agent
• type Option
  • func AllPlugins(plugins ...infra.Plugin) Option
  • func Context(ctx context.Context) Option
  • func Plugins(plugins ...infra.Plugin) Option
  • func QuitOnClose(ch chan struct{}) Option
  • func QuitSignals(sigs ...os.Signal) Option
  • func StartTimeout(timeout time.Duration) Option
  • func StopTimeout(timeout time.Duration) Option
  • func Version(buildVer, buildDate, commitHash string) Option
• type Options

Variables

var (
	// BuildVersion describes version for the build. It is usually set using `git describe --always --tags --dirty`.
	BuildVersion = "v0.0.0-dev"
	// 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 (
	// DefaultStartTimeout is default timeout for starting agent
	DefaultStartTimeout = time.Second * 15
	// DefaultStopTimeout is default timeout for stopping agent
	DefaultStopTimeout = time.Second * 5

	// DumpStackTraceOnTimeout prints stack trace on timeout or agent start/stop
	DumpStackTraceOnTimeout = os.Getenv("DUMP_STACK_ON_TIMEOUT") != ""
)

Types

type Agent

type Agent interface {
	// Run is a blocking call which starts the agent with all of its plugins,
	// waits for a signal from OS (SIGINT, SIGTERM by default), context cancellation or
	// close of quit channel (can be set via options) and then stops the agent.
	// Returns nil if all the plugins were intialized and closed successfully.
	Run() error
	// Start starts the agent with all the plugins, calling their Init() and optionally AfterInit().
	// Returns nil if all the plugins were initialized successfully.
	Start() error
	// Stop stops the agent with all the plugins, calling their Close().
	// Returns nil if all the plugins were closed successfully.
	Stop() error
	// Options returns all agent's options configured via constructor.
	Options() Options

	// Wait waits until agent is stopped  and returns same error as Stop().
	Wait() error
	// After returns a channel that is closed before the agents is stopped.
	// Note: It is not certain the all plugins are stopped, see Error()..
	After() <-chan struct{}
	// Error returns an error that occurret when the agent was stopped.
	// Note: This essentially just calls Stop()..
	Error() error
}

Agent implements startup & shutdown procedures for plugins.

func NewAgent

func NewAgent(opts ...Option) Agent

NewAgent creates a new agent using given options and registers all flags defined for plugins via config.ForPlugin.

type Option

type Option func(*Options)

Option is a function that operates on an Agent's Option

func AllPlugins

func AllPlugins(plugins ...infra.Plugin) Option

AllPlugins creates an Option that adds all of the nested plugins recursively to the Agent's plugin list.

func Context

func Context(ctx context.Context) Option

Context returns an Option that sets the context for the Agent

func Plugins

func Plugins(plugins ...infra.Plugin) Option

Plugins creates an Option that adds a list of Plugins to the Agent's Plugin list

func QuitOnClose

func QuitOnClose(ch chan struct{}) Option

QuitOnClose returns an Option that will set channel which stops Agent on close

func QuitSignals

func QuitSignals(sigs ...os.Signal) Option

QuitSignals returns an Option that will set signals which stop Agent

func StartTimeout

func StartTimeout(timeout time.Duration) Option

StartTimeout returns an Option that sets timeout for the start of Agent.

func StopTimeout

func StopTimeout(timeout time.Duration) Option

StopTimeout returns an Option that sets timeout for the stop of Agent.

func Version

func Version(buildVer, buildDate, commitHash string) Option

Version returns an Option that sets the version of the Agent to the entered string

type Options

type Options struct {
	StartTimeout time.Duration
	StopTimeout  time.Duration
	QuitSignals  []os.Signal
	QuitChan     chan struct{}
	Context      context.Context
	Plugins      []infra.Plugin
	// contains filtered or unexported fields
}

Options specifies option list for the Agent