Documentation
¶
Overview ¶
Package plugin defines the on-disk contract between the cub CLI and its plugins: the cub-plugin.yaml manifest and the install/upgrade hook protocol.
Plugin authors use HandleHook to make a single binary self-describing — when cub installs or upgrades the plugin it invokes the binary with the hook environment set, and HandleHook writes the manifest (and any other setup the author wants) into the plugin directory. The cub CLI reads the same manifest at startup to learn which commands the plugin contributes.
This package intentionally has no dependency on cobra or any CLI framework so that it stays cheap to import.
Index ¶
Constants ¶
const ( // EnvHook carries the hook phase: HookInstall or HookUpgrade. It is empty // during a normal command invocation. EnvHook = "CUB_PLUGIN_HOOK" // EnvDir is the plugin's own directory, which the hook should write into. EnvDir = "CUB_PLUGIN_DIR" // EnvPreviousVersion is the version of the plugin being replaced, set only // on the upgrade phase, so the hook can run version-aware migrations. EnvPreviousVersion = "CUB_PLUGIN_PREVIOUS_VERSION" )
Hook protocol environment variables. cub sets these when it invokes a plugin binary as an install or upgrade hook (rather than as a normal command).
const ( HookInstall = "install" HookUpgrade = "upgrade" )
Hook phase values for EnvHook.
const ManifestFileName = "cub-plugin.yaml"
ManifestFileName is the name of the manifest file that lives beside a plugin's executable(s) inside the plugin directory.
Variables ¶
This section is empty.
Functions ¶
func HandleHook ¶
HandleHook handles the install/upgrade hook if cub is invoking one. When a hook is in progress it writes m as the plugin's manifest into the hook directory and returns handled=true; the caller should then exit without running its normal command logic. During a normal invocation it returns handled=false and the caller proceeds as usual.
Any Command whose Entrypoint is empty defaults to the basename of the running executable, which is the common single-binary case.
Typical use:
if handled, err := plugin.HandleHook(manifest); handled {
if err != nil { fmt.Fprintln(os.Stderr, err); os.Exit(1) }
return
}
// ... normal command execution ...
Types ¶
type Command ¶
type Command struct {
// Name is the cub command token, e.g. "vmcluster" for "cub vmcluster".
Name string `yaml:"name"`
// Aliases are alternate tokens that route to the same command.
Aliases []string `yaml:"aliases,omitempty"`
// Summary is a one-line description shown in help.
Summary string `yaml:"summary,omitempty"`
// Entrypoint is the executable within the plugin directory to run.
Entrypoint string `yaml:"entrypoint"`
// Args is prepended to the plugin's argv, letting one binary back several
// commands (e.g. Args ["vm"] so "cub vm ..." runs "<binary> vm ...").
Args []string `yaml:"args,omitempty"`
}
Command is a single command a plugin contributes to cub. cub routes the top-level token; the command's deeper subcommand tree is owned and parsed by the plugin itself.
type Manifest ¶
type Manifest struct {
// Name is an optional human-friendly plugin name. It does not affect
// routing; command names do.
Name string `yaml:"name,omitempty"`
// Version is the plugin's own version string. cub records it and passes it
// back as CUB_PLUGIN_PREVIOUS_VERSION on the next upgrade.
Version string `yaml:"version,omitempty"`
// Entrypoint is the legacy single-command form: a directory plugin with no
// Commands resolves to one command named after its directory whose
// executable is Entrypoint. Retained for backward compatibility.
Entrypoint string `yaml:"entrypoint,omitempty"`
// Commands are the commands this plugin contributes.
Commands []Command `yaml:"commands,omitempty"`
}
Manifest is the parsed form of cub-plugin.yaml. It declares the commands a plugin contributes to cub.
Source Files