Documentation
¶
Overview ¶
Package plugin provides a shared host runtime for alpamon plugins.
It encapsulates the boilerplate that every plugin previously duplicated: signal handling, pidfile management, config loading, session setup, the initial server-side version handshake, and the websocket lifecycle (graceful shutdown plus in-place restart).
A plugin defines a Plugin value and either calls Plugin.Run directly or embeds it under a Cobra root command via NewRootCmd.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewRootCmd ¶
NewRootCmd returns a Cobra command that runs the plugin and exposes the shared `setup` subcommand. The returned command is suitable for use as the plugin binary's root command. NewRootCmd panics if p is nil or fails validation, so misconfigured plugins fail at process start rather than at first run.
Types ¶
type BuildResult ¶
type BuildResult struct {
// Run is invoked in a goroutine by the SDK. Typically this is the
// plugin client's RunForever method.
Run func(ctx context.Context)
// Cleanup, if non-nil, runs once before the process exits or restarts.
// It is called after the websocket client is closed but before the pool
// and context manager are shut down.
Cleanup func()
}
BuildResult is what Plugin.Build returns to the SDK.
type Host ¶
type Host struct {
Session *scheduler.Session
WSClient *runner.WebsocketClient
}
Host is the bundle of host-managed resources passed to Plugin.Build. The websocket client is fully constructed and ready for the plugin to wire into its domain types. The worker pool and context manager that back the websocket client are owned by the SDK and intentionally not exposed.
type Plugin ¶
type Plugin struct {
// Name is the plugin's binary/service name, e.g. "alpamon-dhcp-plugin".
// Used for the pidfile, logging, and config file lookup.
Name string
// Version is the plugin's version string (sent in the initial handshake).
Version string
// WSPath is the websocket route used for the main backhaul connection,
// e.g. "/ws/dhcp/backhaul/".
WSPath string
// ControlWSPath is the optional control-channel websocket route.
// Most plugins leave this empty.
ControlWSPath string
// CheckServerURL is the HTTP path PATCHed during the version handshake
// before opening the websocket, e.g. "/api/dhcp/-/".
CheckServerURL string
// InitLogger is called once at startup, before any other initialization,
// to configure the plugin's logger. Each plugin owns its own logger
// package, so the SDK delegates this step.
InitLogger func()
// PreConfigInit, if set, runs after config files are resolved but before
// LoadConfig. Used by plugins that need to validate or fix-up paths
// referenced in their INI files (e.g. storage paths).
PreConfigInit func(configFiles []string)
// Build is called after the session, worker pool, context manager and
// websocket client have all been initialized. It receives the host
// resources and returns the Run function that the SDK will spawn in a
// goroutine, plus an optional Cleanup that runs before exit/restart.
//
// The websocket client's lifecycle (Close, ShutDownChan, RestartChan)
// is owned by the SDK; plugins should not call Close on it themselves.
//
// The provided ctx is the plugin's lifecycle context: it is cancelled on
// shutdown or restart. Long-running goroutines started by Build should
// honor it.
Build func(ctx context.Context, host Host) (*BuildResult, error)
}
Plugin describes a plugin agent. Name, Version, WSPath, CheckServerURL and Build are required; the rest are optional.
func (*Plugin) Run ¶
func (p *Plugin) Run()
Run executes the plugin's full lifecycle: signal setup, logger / pidfile / config / session initialization, the version handshake, websocket startup, and graceful shutdown or in-place restart on the corresponding signals.
Run blocks until the agent stops. On a Restart signal it execs the current binary in place and does not return.
Source Files