discovery

package
v0.12.0-alpha1 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2018 License: MPL-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const ErrorNoSuchProvider = Error("no provider exists with the given name")

ErrorNoSuchProvider indicates that no provider exists with a name given

View Source 
const ErrorNoSuitableVersion = Error("no suitable version is available")

ErrorNoSuitableVersion indicates that a suitable version (meeting given constraints) is not available.

View Source 
const ErrorNoVersionCompatible = Error("no available version is compatible with this version of Terraform")

ErrorNoVersionCompatible indicates that all of the available versions that otherwise met constraints are not compatible with the current version of Terraform.

View Source 
const ErrorNoVersionCompatibleWithPlatform = Error("no available version is compatible for the requested platform")

ErrorNoVersionCompatibleWithPlatform indicates that all of the available versions that otherwise met constraints are not compatible with the requested platform

View Source 
const VersionZero = "0.0.0"

Variables

This section is empty.

Functions

func FindPluginPaths 

func FindPluginPaths(kind string, dirs []string) []string

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 added in v0.12.0 

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 Error 

type Error string

Error is a type used to describe situations that the caller must handle since they indicate some form of user error.

The functions and methods that return these specialized errors indicate so in their documentation. The Error type should not itself be used directly, but rather errors should be compared using the == operator with the error constants in this package.

Values of this type are _not_ used when the error being reported is an operational error (server unavailable, etc) or indicative of a bug in this package or its caller.

func (Error) Error 

func (err Error) Error() string

type Installer 

type Installer interface {
	Get(name string, req Constraints) (PluginMeta, error)
	PurgeUnused(used map[string]PluginMeta) (removed PluginMetaSet, err error)
}

An Installer maintains a local cache of plugins by downloading plugins from an online repository.

type PluginCache added in v0.10.7 

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 added in v0.10.7 

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 a 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 ProviderInstaller 

type ProviderInstaller struct {
	Dir string

	// Cache is used to access and update a local cache of plugins if non-nil.
	// Can be nil to disable caching.
	Cache PluginCache

	PluginProtocolVersion uint

	// OS and Arch specify the OS and architecture that should be used when
	// installing plugins. These use the same labels as the runtime.GOOS and
	// runtime.GOARCH variables respectively, and indeed the values of these
	// are used as defaults if either of these is the empty string.
	OS   string
	Arch string

	// Skip checksum and signature verification
	SkipVerify bool

	Ui cli.Ui // Ui for output

	// Services is a required *disco.Disco, which may have services and
	// credentials pre-loaded.
	Services *disco.Disco
	// contains filtered or unexported fields
}

ProviderInstaller is an Installer implementation that knows how to download Terraform providers from the official HashiCorp releases service into a local directory. The files downloaded are compliant with the naming scheme expected by FindPlugins, so the target directory of a provider installer can be used as one of several plugin discovery sources.

func (*ProviderInstaller) Get 

func (i *ProviderInstaller) Get(provider string, req Constraints) (PluginMeta, error)

Get is part of an implementation of type Installer, and attempts to download and install a Terraform provider matching the given constraints.

This method may return one of a number of sentinel errors from this package to indicate issues that are likely to be resolvable via user action: 

ErrorNoSuchProvider: no provider with the given name exists in the repository.
ErrorNoSuitableVersion: the provider exists but no available version matches constraints.
ErrorNoVersionCompatible: a plugin was found within the constraints but it is
                          incompatible with the current Terraform version.

These errors should be recognized and handled as special cases by the caller to present a suitable user-oriented error message.

All other errors indicate an internal problem that is likely _not_ solvable through user action, or at least not within Terraform's scope. Error messages are produced under the assumption that if presented to the user they will be presented alongside context about what is being installed, and thus the error messages do not redundantly include such information.

func (*ProviderInstaller) PurgeUnused 

func (i *ProviderInstaller) PurgeUnused(used map[string]PluginMeta) (PluginMetaSet, error)

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) Equal 

func (v Version) Equal(other Version) bool

func (Version) MinorUpgradeConstraintStr 

func (v Version) MinorUpgradeConstraintStr() ConstraintStr

MinorUpgradeConstraintStr returns a ConstraintStr that would permit minor upgrades relative to the receiving version.

func (Version) NewerThan 

func (v Version) NewerThan(other Version) bool

func (Version) String 

func (v Version) String() string

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.

type Versions 

type Versions []Version

func (Versions) Sort 

func (v Versions) Sort()

Sort sorts version from newest to oldest.

Source Files

View all Source files

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.