Documentation
¶
Overview ¶
Package pluginhost finds, starts and talks to protocol plugins: the executables that implement steps such as mqtt.publish. Each plugin runs as a child process speaking the gRPC contract in proto/stampede/plugin/v1 through hashicorp/go-plugin, so a plugin that crashes fails its own steps and nothing else.
Index ¶
- Constants
- Variables
- func BinaryName(name string) string
- func CheckProgram(prog *scenario.Program, set Set) error
- func Dir() (string, error)
- func Find(dir, name string) (string, error)
- func Remove(dir, name string) (string, error)
- func TargetHosts(v any) ([]string, error)
- type InstallOptions
- type Installed
- type Plugin
- type Session
- type Set
- type StepType
Constants ¶
const BinaryPrefix = "stampede-plugin-"
BinaryPrefix starts every plugin executable's name.
const DefaultRepo = "https://github.com/Ivan825/Stampede"
DefaultRepo is cloned to build first-party plugins without a checkout.
const DirEnv = "STAMPEDE_PLUGIN_DIR"
DirEnv overrides the plugin directory.
const Module = "github.com/Ivan825/Stampede"
Module is Stampede's module path; first-party plugins live under plugins/<name> in it, each a module of its own.
const RepoEnv = "STAMPEDE_PLUGIN_REPO"
RepoEnv overrides the repository cloned when no checkout is found.
const SourceEnv = "STAMPEDE_SOURCE"
SourceEnv points at a Stampede source checkout for first-party installs.
Variables ¶
var ErrCrashed = errors.New("plugin process exited")
ErrCrashed fails calls to a plugin process that has exited.
var ErrNotInstalled = errors.New("plugin is not installed")
ErrNotInstalled is returned by Find for a plugin that is nowhere to be found.
Functions ¶
func BinaryName ¶
BinaryName is the executable name for a plugin.
func CheckProgram ¶
CheckProgram checks every plugin step of prog against the plugins in set: the plugin offers the step and the step's config fits its schema. A string containing ${} is only rendered at run time, so problems with its value (its type, format or range) are left for the plugin to report then; everything else (missing or unknown settings, literal values) is checked now.
func Dir ¶
Dir is where `stampede plugin install` puts plugins: $STAMPEDE_PLUGIN_DIR, or plugins/ under the user config directory (~/.config/stampede/plugins on Linux, ~/Library/Application Support/stampede/plugins on macOS).
func TargetHosts ¶
TargetHosts returns the hosts a config's target value names. It understands URLs (mqtt://host:1883, postgres://u@h1,h2/db), host:port lists, PostgreSQL key=value DSNs (host=db port=5432) and MySQL DSNs (user:pw@tcp(db:3306)/app). Unix sockets and SQLite file: URIs count as localhost. An address it cannot read is an error, so the policy fails closed.
Types ¶
type InstallOptions ¶
type InstallOptions struct {
// Dir is where the plugin is installed (Dir() when empty).
Dir string
// Source is a Stampede checkout to build first-party plugins from.
// Empty means $STAMPEDE_SOURCE, then the checkout containing the
// current directory, then a fresh clone of the repository.
Source string
// Ref is the branch or tag cloned when there is no checkout (default:
// the repository's default branch).
Ref string
// Output receives the build tools' output.
Output io.Writer
Log *slog.Logger
}
InstallOptions configures Install.
type Installed ¶
type Installed struct {
Name string
Path string
// InDir is true for plugins in the plugin directory, false for ones
// found on PATH.
InDir bool
}
Installed is a plugin executable found on this machine.
type Plugin ¶
type Plugin struct {
Name, Version, Description string
Path string
Steps map[string]*StepType
// contains filtered or unexported fields
}
Plugin is a running plugin. A crashed process is restarted on the next call (at most once a second); sessions opened in the old process fail with ErrCrashed and must be opened again.
func Install ¶
Install builds or copies a plugin and installs it into the plugin directory as stampede-plugin-<name>, where name is what the plugin calls itself. spec is
- the name of a first-party plugin (mqtt, kafka, redis, sql, udp), built from plugins/<name> of a Stampede checkout;
- a directory holding a plugin's main package, built with go build;
- an executable plugin file, copied;
- a Go package path, optionally with @version, built with go install.
The result is started and must describe itself validly before it is installed.
func Start ¶
Start launches the plugin executable at path and asks it to describe itself. The description is validated: a plugin with an invalid name or a schema that does not compile is refused.
func (*Plugin) Describe ¶
func (p *Plugin) Describe() *pluginv1.DescribeResponse
Describe returns the plugin's description as it sent it.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is one virtual user's session in a plugin process.
func (*Session) Execute ¶
func (s *Session) Execute(ctx context.Context, req *pluginv1.ExecuteRequest) (*pluginv1.ExecuteResponse, error)
Execute runs one step. An error means the plugin could not run it at all (ErrCrashed when its process is gone); a step that ran and failed is a response with Ok false.
type Set ¶
Set is the plugins a run uses, by name.
type StepType ¶
type StepType struct {
Name string
Description string
// Schema is the step's config schema as the plugin sent it.
Schema []byte
Compiled *jsonschema.Schema
// Targets are the top-level config properties that name the host the
// step connects to ("x-stampede-target": true).
Targets []string
}
StepType is a step a plugin offers, with its compiled config schema.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package plugintest builds Stampede's test plugin for other packages' tests.
|
Package plugintest builds Stampede's test plugin for other packages' tests. |
|
echo
command
Command echo is a plugin for Stampede's own tests.
|
Command echo is a plugin for Stampede's own tests. |
|
runtest
Package runtest runs a scenario file on an in-process engine, for end-to-end tests of plugins and their example scenarios.
|
Package runtest runs a scenario file on an in-process engine, for end-to-end tests of plugins and their example scenarios. |