Documentation
¶
Overview ¶
Package plugin handles discovery, manifest loading, and caching of Restish out-of-process plugins. Plugins are executables named restish-<name> found in the plugin directory.
Index ¶
- Constants
- func CallHook(path string, in, out any) error
- func CallHookContext(ctx context.Context, path string, in, out any) error
- func CallHookWithTimeout(path string, timeout time.Duration, in, out any) error
- func CallHookWithTimeoutContext(ctx context.Context, path string, timeout time.Duration, in, out any) error
- func DefaultManifestCachePath() string
- func DefaultPluginDir() string
- func HookTimeout(m Manifest, hookName string) time.Duration
- func TLSCertificateFromPlugin(path string, params map[string]string) (*tls.Certificate, error)
- type FormatterStream
- type Manifest
- type Plugin
- type PluginSigner
Constants ¶
const CurrentPluginAPIVersion = 2
CurrentPluginAPIVersion is the highest plugin protocol version this build of Restish requires plugins to ask for. The manifest restish_api_version field is a minimum required version, so a plugin built against a future Restish can still load when it only needs features this host supports.
Variables ¶
This section is empty.
Functions ¶
func CallHook ¶
CallHook spawns the plugin at path, writes in as a CBOR message to the plugin's stdin, reads one CBOR reply from stdout, and unmarshals it into out (which must be a pointer).
The plugin must exit 0 for the call to succeed; a non-zero exit is returned as an error along with any text the plugin wrote to stderr. The plugin has 30 seconds to respond before it is killed. Use CallHookWithTimeout to override the deadline.
func CallHookContext ¶
CallHookContext is like CallHook but derives the plugin deadline from ctx.
func CallHookWithTimeout ¶
CallHookWithTimeout is like CallHook but uses the supplied deadline.
func CallHookWithTimeoutContext ¶
func CallHookWithTimeoutContext(ctx context.Context, path string, timeout time.Duration, in, out any) error
CallHookWithTimeoutContext is like CallHookWithTimeout but derives the plugin deadline from ctx.
func DefaultManifestCachePath ¶
func DefaultManifestCachePath() string
DefaultManifestCachePath returns the path to the on-disk plugin manifest cache file. Stored next to the config file to be automatically cleaned up when users wipe their config directory.
func DefaultPluginDir ¶
func DefaultPluginDir() string
DefaultPluginDir returns the default directory for installed plugins.
func HookTimeout ¶
HookTimeout returns the effective timeout for hookName from the manifest, using a default of 5 minutes for "auth" and 30 seconds for all other hooks.
func TLSCertificateFromPlugin ¶
TLSCertificateFromPlugin starts a tls-signer plugin, waits for its ready message, and returns a tls.Certificate whose PrivateKey proxies Sign calls back to the plugin.
Types ¶
type FormatterStream ¶
type FormatterStream struct {
// contains filtered or unexported fields
}
FormatterStream is a long-lived formatter plugin process that receives sequential CBOR requests on stdin and writes formatted bytes directly to the provided stdout writer.
func StartFormatterStream ¶
func StartFormatterStream(ctx context.Context, path string, w io.Writer, in any) (*FormatterStream, error)
StartFormatterStream starts a formatter plugin subprocess, wires its stdout to w, sends the initial request, and returns a handle that can send additional stream messages before Close waits for plugin exit.
func (*FormatterStream) Close ¶
func (s *FormatterStream) Close() error
Close closes plugin stdin and waits up to formatterCloseTimeout for the plugin to exit. If the plugin does not exit in time it is killed.
func (*FormatterStream) Send ¶
func (s *FormatterStream) Send(in any) error
Send writes one additional CBOR message to the formatter plugin.
type Manifest ¶
type Manifest = pluginwire.Manifest
Manifest is an alias for the canonical plugin.Manifest defined in the public plugin package. Using the same type eliminates the dual-maintenance risk that arose when the two structs diverged.
type Plugin ¶
Plugin is a discovered plugin executable together with its manifest.
func Discover ¶
func Discover(pluginDir string, errFn func(path string, err error), manifestCacheFile string, stderr io.Writer) []Plugin
Discover finds all executable restish-* plugins in pluginDir. Errors loading individual plugin manifests are reported via errFn but do not abort discovery. Pass nil for errFn to silently skip broken plugins. manifestCacheFile, when non-empty, enables a CBOR on-disk manifest cache keyed by plugin path + mtime. This avoids subprocess spawns on every invocation when the plugin binary has not changed. When duplicate plugin identities are found, the first plugin in directory order is loaded and later duplicates are reported through errFn.
type PluginSigner ¶
type PluginSigner struct {
// contains filtered or unexported fields
}
PluginSigner implements crypto.Signer by delegating Sign operations to a long-lived tls-signer plugin subprocess.
func (*PluginSigner) Close ¶
func (s *PluginSigner) Close() error
Close gracefully shuts down the signer subprocess.
func (*PluginSigner) Public ¶
func (s *PluginSigner) Public() crypto.PublicKey
func (*PluginSigner) Sign ¶
func (s *PluginSigner) Sign(_ io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)
Source Files