plugins

package
v0.3.5 Latest Latest
Warning

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

 Go to latest Published: Jun 13, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Overview

Package plugins loads Extism WASM plugins for honey (CUE transforms, custom steps, secret ref backends, and local hooks). Enable via honey config plugins.enabled.

Index

Constants

View Source 
const (
	CapCueTransform = "cue_transform"
	CapCustomStep   = "custom_step"
	CapSecret       = "secret"
	CapStackUnwrap  = "stack_unwrap"
	CapHook         = "hook"
)

Capability names registered in plugin.yaml.

Variables

This section is empty.

Functions

func KVSessionFromContext 

func KVSessionFromContext(ctx context.Context) (*stepkv.Session, bool)

KVSessionFromContext returns the session bound for this plugin call, if any.

func PluginsFromConfig 

func PluginsFromConfig(f *config.File) config.PluginsEffective

PluginsFromConfig builds effective settings from honey config file.

func ResolvePostgresDSN added in v0.3.0 

func ResolvePostgresDSN(ctx context.Context, h *HostRunContext, ref string) (string, error)

ResolvePostgresDSN resolves config.dsn_secret from a secrets map key or direct secure:v1 ref.

func RunKVForTest 

func RunKVForTest(ctx context.Context, in apiv1.KVInput) apiv1.KVOutput

RunKVForTest exposes runKV for unit tests.

func RunPostgresExecForTest added in v0.3.0 

func RunPostgresExecForTest(ctx context.Context, in apiv1.PostgresSQLInput) apiv1.PostgresOutput

RunPostgresExecForTest exposes postgres_exec for unit tests.

func RunPostgresQueryForTest added in v0.3.0 

func RunPostgresQueryForTest(ctx context.Context, in apiv1.PostgresSQLInput) apiv1.PostgresOutput

RunPostgresQueryForTest exposes postgres_query for unit tests.

func RunRemoteExecForTest added in v0.3.0 

func RunRemoteExecForTest(ctx context.Context, in apiv1.RemoteExecInput) apiv1.RemoteExecOutput

RunRemoteExecForTest exposes remote_exec handling for unit tests.

func RunRemoteStatForTest added in v0.3.0 

func RunRemoteStatForTest(ctx context.Context, in apiv1.RemoteStatInput) apiv1.RemoteStatOutput

RunRemoteStatForTest exposes remote_stat handling for unit tests.

func RunRemoteUploadForTest added in v0.3.0 

func RunRemoteUploadForTest(ctx context.Context, in apiv1.RemoteUploadInput) apiv1.RemoteUploadOutput

RunRemoteUploadForTest exposes remote_upload handling for unit tests.

func RunTemplateRenderForTest added in v0.3.0 

func RunTemplateRenderForTest(ctx context.Context, in apiv1.TemplateRenderInput) apiv1.TemplateRenderOutput

RunTemplateRenderForTest exposes template_render handling for unit tests.

func WithHostRunContext added in v0.3.0 

func WithHostRunContext(ctx context.Context, h *HostRunContext) context.Context

WithHostRunContext attaches host execution context for plugin remote host functions.

func WithKVSession 

func WithKVSession(ctx context.Context, sess *stepkv.Session) context.Context

WithKVSession attaches the recipe stepkv session for plugin host functions.

Types

type HostRunContext added in v0.3.0 

type HostRunContext struct {
	SSHUser              string
	Record               hosts.Record
	RecipeDir            string
	Execute              bool
	SecretsDry           bool
	RunAs                string
	Env                  map[string]string
	Bridge               RemoteBridge
	Postgres             PostgresBridge
	TunnelCoord          TunnelCoordinator
	AllowedPaths         map[string]string
	RecipeSecrets        map[string]string
	ResolveSecret        SecretResolveFunc
	PluginID             string
	MaxPostgresTimeoutMS int
}

HostRunContext carries per-host recipe execution state for plugin host functions.

func HostRunContextFromContext added in v0.3.0 

func HostRunContextFromContext(ctx context.Context) (*HostRunContext, bool)

HostRunContextFromContext returns the host run context for this plugin call, if any.

type Info 

type Info struct {
	ID                   string            `json:"id"`
	Version              string            `json:"version"`
	Capabilities         []string          `json:"capabilities"`
	Path                 string            `json:"path"`
	SecretRefPrefixes    []string          `json:"secret_ref_prefixes,omitempty"`
	AllowHostExec        bool              `json:"allow_host_exec,omitempty"`
	AllowRemoteExec      bool              `json:"allow_remote_exec,omitempty"`
	AllowSFTP            bool              `json:"allow_sftp,omitempty"`
	AllowTemplateRender  bool              `json:"allow_template_render,omitempty"`
	AllowPostgres        bool              `json:"allow_postgres,omitempty"`
	AllowKV              bool              `json:"allow_kv,omitempty"`
	AllowedHosts         []string          `json:"allowed_hosts,omitempty"`
	AllowedPaths         map[string]string `json:"allowed_paths,omitempty"`
	AllowedEnv           []string          `json:"allowed_env,omitempty"`
	MaxHTTPResponseBytes int64             `json:"max_http_response_bytes,omitempty"`
}

Info describes a loaded plugin for listing.

type Manager 

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

Manager loads Extism WASM plugins and routes capability calls.

func LoadFromDir 

func LoadFromDir(ctx context.Context, dir string) (*Manager, error)

LoadFromDir is a test helper that loads plugins from a directory without config allowlist.

func NewManager 

func NewManager(ctx context.Context, cfg config.PluginsEffective) (*Manager, error)

NewManager loads plugins from cfg. When plugins are disabled, returns a manager with no plugins.

func Open 

func Open(ctx context.Context, cfg *config.File) (*Manager, error)

Open loads plugins from honey config (returns non-nil manager even when disabled).

func (*Manager) Call 

func (m *Manager) Call(ctx context.Context, pluginID, export string, in, out any) error

Call invokes export on pluginID with JSON input; decodes JSON output or returns plugin error string.

func (*Manager) Close 

func (m *Manager) Close() error

Close releases plugin resources.

func (*Manager) EffectivePaths added in v0.3.0 

func (m *Manager) EffectivePaths(pluginID string) map[string]string

EffectivePaths returns validated allowed_paths for a loaded plugin id.

func (*Manager) Enabled 

func (m *Manager) Enabled() bool

Enabled reports whether plugins are turned on in config.

func (*Manager) ExecuteStep 

func (m *Manager) ExecuteStep(ctx context.Context, pluginID, action string, config json.RawMessage, stepIndex int, hostJSON []byte, env map[string]string, execute, secretsDry bool, kvSession *stepkv.Session) (apiv1.ExecuteStepOutput, error)

ExecuteStep runs the execute_step export for a plugin step on one host. kvSession is optional; when non-nil it is bound for allow_kv plugins via the kv host function.

func (*Manager) List 

func (m *Manager) List() []Info

List returns metadata for loaded plugins.

func (*Manager) OnStepResult 

func (m *Manager) OnStepResult(ctx context.Context, pluginID, action string, config json.RawMessage, in apiv1.OnStepResultInput, kvSession *stepkv.Session) (apiv1.OnStepResultOutput, error)

OnStepResult runs the on_step_result export for a local hook plugin.

func (*Manager) PluginIDsWithCapability 

func (m *Manager) PluginIDsWithCapability(capability string) []string

PluginIDsWithCapability returns plugin IDs that declare the capability.

func (*Manager) SecretRefBackends 

func (m *Manager) SecretRefBackends() []ref.Backend

SecretRefBackends returns ref.Backend adapters for plugins with the secret capability.

func (*Manager) SecretRefPrefixes 

func (m *Manager) SecretRefPrefixes() []string

SecretRefPrefixes returns all registered secret ref prefixes from secret-capable plugins.

func (*Manager) TimeoutMS added in v0.3.0 

func (m *Manager) TimeoutMS() int

TimeoutMS returns configured plugin timeout milliseconds (default 30000).

func (*Manager) TransformCue 

func (m *Manager) TransformCue(ctx context.Context, cueBytes []byte, hostsCount int) ([]byte, error)

TransformCue runs cue_transform plugins in manifest order.

type Manifest 

type Manifest struct {
	ID                   string            `yaml:"id"`
	Version              string            `yaml:"version"`
	Capabilities         []string          `yaml:"capabilities"`
	SecretRefPrefixes    []string          `yaml:"secret_ref_prefixes,omitempty"`
	AllowK8sHTTP         bool              `yaml:"allow_k8s_http,omitempty"`
	AllowHostExec        bool              `yaml:"allow_host_exec,omitempty"`
	AllowRemoteExec      bool              `yaml:"allow_remote_exec,omitempty"`
	AllowSFTP            bool              `yaml:"allow_sftp,omitempty"`
	AllowTemplateRender  bool              `yaml:"allow_template_render,omitempty"`
	AllowPostgres        bool              `yaml:"allow_postgres,omitempty"`
	AllowKV              bool              `yaml:"allow_kv,omitempty"`
	AllowedEnv           []string          `yaml:"allowed_env,omitempty"`
	AllowedHosts         []string          `yaml:"allowed_hosts,omitempty"`
	AllowedPaths         map[string]string `yaml:"allowed_paths,omitempty"`
	MaxHTTPResponseBytes int64             `yaml:"max_http_response_bytes,omitempty"`
	Order                int               `yaml:"order,omitempty"`
}

Manifest describes a plugin bundle (plugin.yaml next to plugin.wasm).

func Install added in v0.3.2 

func Install(ctx context.Context, src, destDir string, force bool) (*Manifest, error)

Install installs a plugin from src (https:// URL, local .tar.gz/.zip, or local directory) into destDir/<plugin-id>/. Returns the installed Manifest. If force is false, returns an error when the plugin id already exists in destDir.

type PostgresBridge added in v0.3.0 

type PostgresBridge interface {
	Query(ctx context.Context, in apiv1.PostgresSQLInput) apiv1.PostgresOutput
	Exec(ctx context.Context, in apiv1.PostgresSQLInput) apiv1.PostgresOutput
	Migrate(ctx context.Context, in apiv1.PostgresMigrateInput) apiv1.PostgresOutput
}

PostgresBridge performs Postgres operations on the operator via pgx.

type RemoteBridge added in v0.3.0 

type RemoteBridge interface {
	RemoteExec(ctx context.Context, in apiv1.RemoteExecInput) apiv1.RemoteExecOutput
	RemoteUpload(ctx context.Context, in apiv1.RemoteUploadInput) apiv1.RemoteUploadOutput
	RemoteDownload(ctx context.Context, in apiv1.RemoteDownloadInput) apiv1.RemoteDownloadOutput
	RemoteStat(ctx context.Context, in apiv1.RemoteStatInput) apiv1.RemoteStatOutput
	TemplateRender(ctx context.Context, in apiv1.TemplateRenderInput) apiv1.TemplateRenderOutput
}

RemoteBridge performs SSH/SFTP operations on behalf of a WASM plugin for one host.

type SecretBackend 

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

SecretBackend resolves secret refs via a WASM plugin prefix.

func (SecretBackend) Handles 

func (b SecretBackend) Handles(ref string) bool

Handles implements ref.Backend.

func (SecretBackend) Name 

func (b SecretBackend) Name() string

Name implements ref.Backend.

func (SecretBackend) Resolve 

func (b SecretBackend) Resolve(ctx context.Context, ref string) (string, error)

Resolve implements ref.Backend.

type SecretResolveFunc added in v0.3.0 

type SecretResolveFunc func(ctx context.Context, ref string) (string, error)

SecretResolveFunc resolves a secure:v1 ref to plaintext (operator-side only).

type TunnelCoordinator added in v0.3.0 

type TunnelCoordinator interface {
	LookupEndpoint(stepID, sshUser string, record hosts.Record) (host string, port int, ok bool)
}

TunnelCoordinator resolves recipe tunnel step endpoints for DSN rewrite.

Source Files

View all Source files

Directories

Path Synopsis
api
v1
Package v1 defines the honey.plugins/v1 JSON contract between the host and WASM plugins.
 Package v1 defines the honey.plugins/v1 JSON contract between the host and WASM plugins.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.