Documentation
¶
Overview ¶
Package pluginload opens plugin shared objects (.so) built against the pluginapi contract.
A shared object is trusted code: opening one is equivalent to changing the binary. The loader therefore refuses relative paths that escape the configured search paths, verifies optional SHA-256 pins, and turns every failure into a startup error that names the file. It never loads anything unless plugins.load is configured.
Go's plugin package requires the host and the plugin to be built with the same toolchain and the same build flags (notably -trimpath and -race) from identical sources of every shared package. HostBuildInfo and HostBuildFlags expose what this binary was built with so tooling can reproduce it.
Index ¶
Constants ¶
const ( // PluginSymbol is required: `func GoModelPlugin() pluginapi.Plugin` // (preferred, one file can back several instances) or // `var GoModelPlugin pluginapi.Plugin` (single instance). PluginSymbol = "GoModelPlugin" // BuildInfoSymbol is optional: `var GoModelBuildInfo pluginapi.BuildInfo`, // stamped by `gomodel plugin build`. BuildInfoSymbol = "GoModelBuildInfo" )
Symbol names a shared object exports for GoModel.
const Supported = true
Supported reports whether this platform can open shared objects. Go's plugin package works on Linux, macOS, and FreeBSD only, and only in cgo-enabled binaries; the latter is detected at open time.
Variables ¶
var HostBuildInfo = pluginapi.BuildInfo{ GoVersion: runtime.Version(), PluginAPIVersion: pluginapi.Version, }
HostBuildInfo describes the toolchain this binary was built with. Plugins must be built with the same Go version against the same pluginapi sources.
Functions ¶
func FileSHA256 ¶
FileSHA256 returns the lowercase hex SHA-256 digest of the file.
func Resolve ¶
Resolve turns a configured plugin file into an absolute path. Absolute files are used as-is. Relative files are looked up in searchPaths in order and must stay inside the directory they are found in, symlinks included.
func VerifySHA256 ¶
VerifySHA256 checks the file against a hex digest. An empty digest skips the check.
Types ¶
type BuildFlags ¶
BuildFlags are the go build flags that change compiled package hashes and therefore must match between a host and its plugins.
func HostBuildFlags ¶
func HostBuildFlags() BuildFlags
HostBuildFlags returns the flags this binary was built with, read from its embedded build info. Plugins must be built with the same flags.
func (BuildFlags) Args ¶
func (f BuildFlags) Args() []string
Args returns the flags as go build arguments.
func (BuildFlags) String ¶
func (f BuildFlags) String() string
String renders the flags for diagnostics; "(none)" when empty.
type Loaded ¶
type Loaded struct {
// Path is the resolved absolute path of the shared object.
Path string
// Factory returns a plugin instance. For a constructor symbol every call
// returns a fresh instance; for a variable symbol every call returns the
// same value (see SingleInstance).
Factory func() pluginapi.Plugin
// Manifest is the manifest reported by a probe instance, with BuiltWith
// filled from BuildInfo when the plugin left it empty.
Manifest pluginapi.Manifest
// BuildInfo is the GoModelBuildInfo symbol stamped by `gomodel plugin
// build`, or the zero value when the plugin does not export one.
BuildInfo pluginapi.BuildInfo
// SingleInstance reports that GoModelPlugin is a variable rather than a
// constructor, so the shared object can back only one configured
// instance.
SingleInstance bool
}
Loaded is one opened shared object.
Source Files