pluginhost

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2026 License: Apache-2.0 Imports: 31 Imported by: 0

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

View Source
const BinaryPrefix = "stampede-plugin-"

BinaryPrefix starts every plugin executable's name.

View Source
const DefaultRepo = "https://github.com/Ivan825/Stampede"

DefaultRepo is cloned to build first-party plugins without a checkout.

View Source
const DirEnv = "STAMPEDE_PLUGIN_DIR"

DirEnv overrides the plugin directory.

View Source
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.

View Source
const RepoEnv = "STAMPEDE_PLUGIN_REPO"

RepoEnv overrides the repository cloned when no checkout is found.

View Source
const SourceEnv = "STAMPEDE_SOURCE"

SourceEnv points at a Stampede source checkout for first-party installs.

Variables

View Source
var ErrCrashed = errors.New("plugin process exited")

ErrCrashed fails calls to a plugin process that has exited.

View Source
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

func BinaryName(name string) string

BinaryName is the executable name for a plugin.

func CheckProgram

func CheckProgram(prog *scenario.Program, set Set) error

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

func Dir() (string, error)

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 Find

func Find(dir, name string) (string, error)

Find locates a plugin's executable: first in dir (Dir() when empty), then on PATH.

func Remove

func Remove(dir, name string) (string, error)

Remove deletes an installed plugin from the plugin directory.

func TargetHosts

func TargetHosts(v any) ([]string, error)

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.

func List

func List(dir string) ([]Installed, error)

List returns the installed plugins, those in dir (Dir() when empty) first; a plugin in dir hides one of the same name on PATH.

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

func Install(ctx context.Context, spec string, o InstallOptions) (*Plugin, string, error)

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

func Start(ctx context.Context, path string, log *slog.Logger) (*Plugin, error)

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.

func (*Plugin) Kill

func (p *Plugin) Kill()

Kill stops the plugin process.

func (*Plugin) Open

func (p *Plugin) Open(ctx context.Context, vu int64, runID string) (*Session, error)

Open starts a session for a virtual user.

func (*Plugin) StepNames

func (p *Plugin) StepNames() []string

StepNames lists the plugin's steps, sorted.

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session is one virtual user's session in a plugin process.

func (*Session) Close

func (s *Session) Close(ctx context.Context)

Close ends the session; errors are ignored, as the user is gone.

func (*Session) Execute

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.

func (*Session) Stale

func (s *Session) Stale() bool

Stale reports whether the session's process has exited.

type Set

type Set map[string]*Plugin

Set is the plugins a run uses, by name.

func Load

func Load(ctx context.Context, dir string, names []string, log *slog.Logger) (Set, error)

Load finds and starts the named plugins. dir is the plugin directory (Dir() when empty). A plugin that is missing or fails to start fails the whole load, naming it.

func (Set) Kill

func (s Set) Kill()

Kill stops every plugin in the set.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL