Documentation
¶
Index ¶
- Constants
- func FindPluginPaths(kind string, dirs []string) []string
- type ConstraintStr
- type Constraints
- type PluginCache
- type PluginConstraints
- type PluginMeta
- type PluginMetaSet
- func (s PluginMetaSet) Add(p PluginMeta)
- func (s PluginMetaSet) ByName() map[string]PluginMetaSet
- func (s PluginMetaSet) ConstrainVersions(reqd PluginRequirements) map[string]PluginMetaSet
- func (s PluginMetaSet) Count() int
- func (s PluginMetaSet) Has(p PluginMeta) bool
- func (s PluginMetaSet) Newest() PluginMeta
- func (s PluginMetaSet) OverridePaths(paths map[string]string) PluginMetaSet
- func (s PluginMetaSet) Remove(p PluginMeta)
- func (s PluginMetaSet) ValidateVersions() (valid, invalid PluginMetaSet)
- func (s PluginMetaSet) WithName(name string) PluginMetaSet
- func (s PluginMetaSet) WithVersion(version Version) PluginMetaSet
- type PluginRequirements
- type Version
- type VersionStr
- type Versions
Constants ¶
const PluginInstallProtocolVersion = 5
PluginInstallProtocolVersion is the protocol version TF-core supports to communicate with servers, and is used to resolve plugin discovery with terraform registry, in addition to any specified plugin version constraints
const VersionZero = "0.0.0"
Variables ¶
This section is empty.
Functions ¶
func FindPluginPaths ¶
FindPluginPaths looks in the given directories for files whose filenames suggest that they are plugins of the given kind (e.g. "provider").
The return value is a list of absolute paths that appear to refer to plugins in the given directories, based only on what can be inferred from the naming scheme. The paths returned are ordered such that files in later dirs appear after files in earlier dirs in the given directory list. Within the same directory plugins are returned in a consistent but undefined order.
Types ¶
type ConstraintStr ¶
type ConstraintStr string
A ConstraintStr is a string containing a possibly-invalid representation of a version constraint provided in configuration. Call Parse on it to obtain a real Constraint object, or discover that it is invalid.
func (ConstraintStr) MustParse ¶
func (s ConstraintStr) MustParse() Constraints
MustParse is like Parse but it panics if the constraint string is invalid.
func (ConstraintStr) Parse ¶
func (s ConstraintStr) Parse() (Constraints, error)
Parse transforms a ConstraintStr into a Constraints if it is syntactically valid. If it isn't then an error is returned instead.
type Constraints ¶
type Constraints struct {
// contains filtered or unexported fields
}
Constraints represents a set of versions which any given Version is either a member of or not.
var AllVersions Constraints
AllVersions is a Constraints containing all versions
func NewConstraints ¶
func NewConstraints(c version.Constraints) Constraints
NewConstraints creates a Constraints based on a version.Constraints.
func (Constraints) Allows ¶
func (s Constraints) Allows(v Version) bool
Allows returns true if the given version permitted by the receiving constraints set.
func (Constraints) Append ¶
func (s Constraints) Append(other Constraints) Constraints
Append combines the receiving set with the given other set to produce a set that is the intersection of both sets, which is to say that resulting constraints contain only the versions that are members of both.
func (Constraints) String ¶
func (s Constraints) String() string
String returns a string representation of the set members as a set of range constraints.
func (Constraints) Unconstrained ¶
func (s Constraints) Unconstrained() bool
Unconstrained returns true if and only if the receiver is an empty constraint set.
type PluginCache ¶
type PluginCache interface {
// CachedPluginPath returns a path where the requested plugin is already
// cached, or an empty string if the requested plugin is not yet cached.
CachedPluginPath(kind string, name string, version Version) string
// InstallDir returns the directory that new plugins should be installed into
// in order to populate the cache. This directory should be used as the
// first argument to getter.Get when downloading plugins with go-getter.
//
// After installing into this directory, use CachedPluginPath to obtain the
// path where the plugin was installed.
InstallDir() string
}
PluginCache is an interface implemented by objects that are able to maintain a cache of plugins.
func NewLocalPluginCache ¶
func NewLocalPluginCache(dir string) PluginCache
NewLocalPluginCache returns a PluginCache that caches plugins in a given local directory.
type PluginConstraints ¶
type PluginConstraints struct {
// Specifies that the plugin's version must be within the given
// constraints.
Versions Constraints
// If non-nil, the hash of the on-disk plugin executable must exactly
// match the SHA256 hash given here.
SHA256 []byte
}
PluginConstraints represents an element of PluginRequirements describing the constraints for a single plugin.
func (*PluginConstraints) AcceptsSHA256 ¶
func (s *PluginConstraints) AcceptsSHA256(digest []byte) bool
AcceptsSHA256 returns true if the given executable SHA256 hash is acceptable, either because it matches the constraint or because there is no such constraint.
func (*PluginConstraints) Allows ¶
func (s *PluginConstraints) Allows(v Version) bool
Allows returns true if the given version is within the receiver's version constraints.
type PluginMeta ¶
type PluginMeta struct {
// Name is the name of the plugin, e.g. as inferred from the plugin
// binary's filename, or by explicit configuration.
Name string
// Version is the semver version of the plugin, expressed as a string
// that might not be semver-valid.
Version VersionStr
// Path is the absolute path of the executable that can be launched
// to provide the RPC server for this plugin.
Path string
}
PluginMeta is metadata about a plugin, useful for launching the plugin and for understanding which plugins are available.
func (PluginMeta) SHA256 ¶
func (m PluginMeta) SHA256() ([]byte, error)
SHA256 returns a SHA256 hash of the content of the referenced executable file, or an error if the file's contents cannot be read.
type PluginMetaSet ¶
type PluginMetaSet map[PluginMeta]struct{}
A PluginMetaSet is a set of PluginMeta objects meeting a certain criteria.
Methods on this type allow filtering of the set to produce subsets that meet more restrictive criteria.
func FindPlugins ¶
func FindPlugins(kind string, dirs []string) PluginMetaSet
FindPlugins looks in the given directories for files whose filenames suggest that they are plugins of the given kind (e.g. "provider") and returns a PluginMetaSet representing the discovered potential-plugins.
Currently this supports two different naming schemes. The current standard naming scheme is a subdirectory called $GOOS-$GOARCH containing files named terraform-$KIND-$NAME-V$VERSION. The legacy naming scheme is files directly in the given directory whose names are like terraform-$KIND-$NAME.
Only one plugin will be returned for each unique plugin (name, version) pair, with preference given to files found in earlier directories.
This is a convenience wrapper around FindPluginPaths and ResolvePluginsPaths.
func ResolvePluginPaths ¶
func ResolvePluginPaths(paths []string) PluginMetaSet
ResolvePluginPaths takes a list of paths to plugin executables (as returned by e.g. FindPluginPaths) and produces a PluginMetaSet describing the referenced plugins.
If the same combination of plugin name and version appears multiple times, the earlier reference will be preferred. Several different versions of the same plugin name may be returned, in which case the methods of PluginMetaSet can be used to filter down.
func (PluginMetaSet) Add ¶
func (s PluginMetaSet) Add(p PluginMeta)
Add inserts the given PluginMeta into the receiving set. This is a no-op if the given meta is already present.
func (PluginMetaSet) ByName ¶
func (s PluginMetaSet) ByName() map[string]PluginMetaSet
ByName groups the metas in the set by their Names, returning a map.
func (PluginMetaSet) ConstrainVersions ¶
func (s PluginMetaSet) ConstrainVersions(reqd PluginRequirements) map[string]PluginMetaSet
ConstrainVersions takes a set of requirements and attempts to return a map from name to a set of metas that have the matching name and an appropriate version.
If any of the given requirements match *no* plugins then its PluginMetaSet in the returned map will be empty.
All viable metas are returned, so the caller can apply any desired filtering to reduce down to a single option. For example, calling Newest() to obtain the highest available version.
If any of the metas in the set have invalid version strings then this function will panic. Use ValidateVersions() first to filter out metas with invalid versions.
func (PluginMetaSet) Count ¶
func (s PluginMetaSet) Count() int
Count returns the number of metas in the set
func (PluginMetaSet) Has ¶
func (s PluginMetaSet) Has(p PluginMeta) bool
Has returns true if the given meta is in the receiving set, or false otherwise.
func (PluginMetaSet) Newest ¶
func (s PluginMetaSet) Newest() PluginMeta
Newest returns the one item from the set that has the newest Version value.
The result is meaningful only if the set is already filtered such that all of the metas have the same Name.
If there isn't at least one meta in the set then this function will panic. Use Count() to ensure that there is at least one value before calling.
If any of the metas have invalid version strings then this function will panic. Use ValidateVersions() first to filter out metas with invalid versions.
If two metas have the same Version then one is arbitrarily chosen. This situation should be avoided by pre-filtering the set.
func (PluginMetaSet) OverridePaths ¶
func (s PluginMetaSet) OverridePaths(paths map[string]string) PluginMetaSet
OverridePaths returns a new set where any existing plugins with the given names are removed and replaced with the single path given in the map.
This is here only to continue to support the legacy way of overriding plugin binaries in the .terraformrc file. It treats all given plugins as pre-versioning (version 0.0.0). This mechanism will eventually be phased out, with vendor directories being the intended replacement.
func (PluginMetaSet) Remove ¶
func (s PluginMetaSet) Remove(p PluginMeta)
Remove removes the given PluginMeta from the receiving set. This is a no-op if the given meta is not already present.
func (PluginMetaSet) ValidateVersions ¶
func (s PluginMetaSet) ValidateVersions() (valid, invalid PluginMetaSet)
ValidateVersions returns two new PluginMetaSets, separating those with versions that have syntax-valid semver versions from those that don't.
Eliminating invalid versions from consideration (and possibly warning about them) is usually the first step of working with a meta set after discovery has completed.
func (PluginMetaSet) WithName ¶
func (s PluginMetaSet) WithName(name string) PluginMetaSet
WithName returns the subset of metas that have the given name.
func (PluginMetaSet) WithVersion ¶
func (s PluginMetaSet) WithVersion(version Version) PluginMetaSet
WithVersion returns the subset of metas that have the given version.
This should be used only with the "valid" result from ValidateVersions; it will ignore any plugin metas that have invalid version strings.
type PluginRequirements ¶
type PluginRequirements map[string]*PluginConstraints
PluginRequirements describes a set of plugins (assumed to be of a consistent kind) that are required to exist and have versions within the given corresponding sets.
func (PluginRequirements) LockExecutables ¶
func (r PluginRequirements) LockExecutables(sha256s map[string][]byte)
LockExecutables applies additional constraints to the receiver that require plugin executables with specific SHA256 digests. This modifies the receiver in-place, since it's intended to be applied after version constraints have been resolved.
The given map must include a key for every plugin that is already required. If not, any missing keys will cause the corresponding plugin to never match, though the direct caller doesn't necessarily need to guarantee this as long as the downstream code _applying_ these constraints is able to deal with the non-match in some way.
func (PluginRequirements) Merge ¶
func (r PluginRequirements) Merge(other PluginRequirements) PluginRequirements
Merge takes the contents of the receiver and the other given requirements object and merges them together into a single requirements structure that satisfies both sets of requirements.
Note that it doesn't make sense to merge two PluginRequirements with differing required plugin SHA256 hashes, since the result will never match any plugin.
type Version ¶
type Version struct {
// contains filtered or unexported fields
}
Version represents a version number that has been parsed from a semver string and known to be valid.
func (Version) IsPrerelease ¶
IsPrerelease determines if version is a prerelease
func (Version) MinorUpgradeConstraintStr ¶
func (v Version) MinorUpgradeConstraintStr() ConstraintStr
MinorUpgradeConstraintStr returns a ConstraintStr that would permit minor upgrades relative to the receiving version.
type VersionStr ¶
type VersionStr string
A VersionStr is a string containing a possibly-invalid representation of a semver version number. Call Parse on it to obtain a real Version object, or discover that it is invalid.
func (VersionStr) MustParse ¶
func (s VersionStr) MustParse() Version
MustParse transforms a VersionStr into a Version if it is syntactically valid. If it isn't then it panics.
func (VersionStr) Parse ¶
func (s VersionStr) Parse() (Version, error)
Parse transforms a VersionStr into a Version if it is syntactically valid. If it isn't then an error is returned instead.
Source Files