providercache

Documentation

Index

• type CachedProvider
  • func (cp *CachedProvider) ExecutableFile() (string, error)
  • func (cp *CachedProvider) Hash() (getproviders.Hash, error)
  • func (cp *CachedProvider) HashV1() (getproviders.Hash, error)
  • func (cp *CachedProvider) MatchesAnyHash(allowed []getproviders.Hash) (bool, error)
  • func (cp *CachedProvider) MatchesHash(want getproviders.Hash) (bool, error)
  • func (cp *CachedProvider) PackageLocation() getproviders.PackageLocalDir
• type Dir
  • func NewDir(baseDir string) *Dir
  • func NewDirWithPlatform(baseDir string, platform getproviders.Platform) *Dir
  • func (d *Dir) AllAvailablePackages() map[addrs.Provider][]CachedProvider
  • func (d *Dir) BasePath() string
  • func (d *Dir) InstallPackage(ctx context.Context, meta getproviders.PackageMeta, ...) (*getproviders.PackageAuthenticationResult, error)
  • func (d *Dir) LinkFromOtherCache(entry *CachedProvider, allowedHashes []getproviders.Hash) error
  • func (d *Dir) ProviderLatestVersion(provider addrs.Provider) *CachedProvider
  • func (d *Dir) ProviderVersion(provider addrs.Provider, version getproviders.Version) *CachedProvider

Types

type CachedProvider

type CachedProvider struct {
	// Provider and Version together identify the specific provider version
	// this cache entry represents.
	Provider addrs.Provider
	Version  getproviders.Version

	// PackageDir is the local filesystem path to the root directory where
	// the provider's distribution archive was unpacked.
	//
	// The path always uses slashes as path separators, even on Windows, so
	// that the results are consistent between platforms. Windows accepts
	// both slashes and backslashes as long as the separators are consistent
	// within a particular path string.
	PackageDir string
}

CachedProvider represents a provider package in a cache directory.

func (*CachedProvider) ExecutableFile

func (cp *CachedProvider) ExecutableFile() (string, error)

ExecutableFile inspects the cached provider's unpacked package directory for something that looks like it's intended to be the executable file for the plugin.

This is a bit messy and heuristic-y because historically Terraform used the filename itself for local filesystem discovery, allowing some variance in the filenames to capture extra metadata, whereas now we're using the directory structure leading to the executable instead but need to remain compatible with the executable names bundled into existing provider packages.

It will return an error if it can't find a file following the expected convention in the given directory.

If found, the path always uses slashes as path separators, even on Windows, so that the results are consistent between platforms. Windows accepts both slashes and backslashes as long as the separators are consistent within a particular path string.

func (*CachedProvider) Hash

func (cp *CachedProvider) Hash() (getproviders.Hash, error)

Hash computes a hash of the contents of the package directory associated with the receiving cached provider, using whichever hash algorithm is the current default.

If you need a specific version of hash rather than just whichever one is current default, call that version's corresponding method (e.g. HashV1) directly instead.

func (*CachedProvider) HashV1

func (cp *CachedProvider) HashV1() (getproviders.Hash, error)

HashV1 computes a hash of the contents of the package directory associated with the receiving cached provider using hash algorithm 1.

The hash covers the paths to files in the directory and the contents of those files. It does not cover other metadata about the files, such as permissions.

This function is named "HashV1" in anticipation of other hashing algorithms being added (in a backward-compatible way) in future. The result from HashV1 always begins with the prefix "h1:" so that callers can distinguish the results of potentially multiple different hash algorithms in future.

func (*CachedProvider) MatchesAnyHash

func (cp *CachedProvider) MatchesAnyHash(allowed []getproviders.Hash) (bool, error)

MatchesAnyHash returns true if the package on disk matches the given hash, or false otherwise. If it cannot traverse the package directory and read all of the files in it, MatchesAnyHash returns an error.

Unlike the singular MatchesHash, MatchesAnyHash considers unsupported hash formats as successfully non-matching, rather than returning an error.

func (*CachedProvider) MatchesHash

func (cp *CachedProvider) MatchesHash(want getproviders.Hash) (bool, error)

MatchesHash returns true if the package on disk matches the given hash, or false otherwise. If it cannot traverse the package directory and read all of the files in it, or if the hash is in an unsupported format, MatchesHash returns an error.

MatchesHash may accept hashes in a number of different formats. Over time the set of supported formats may grow and shrink.

func (*CachedProvider) PackageLocation

func (cp *CachedProvider) PackageLocation() getproviders.PackageLocalDir

PackageLocation returns the package directory given in the PackageDir field as a getproviders.PackageLocation implementation.

Because cached providers are always in the unpacked structure, the result is always of the concrete type getproviders.PackageLocalDir.

type Dir

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

Dir represents a single local filesystem directory containing cached provider plugin packages that can be both read from (to find providers to use for operations) and written to (during provider installation).

The contents of a cache directory follow the same naming conventions as a getproviders.FilesystemMirrorSource, except that the packages are always kept in the "unpacked" form (a directory containing the contents of the original distribution archive) so that they are ready for direct execution.

A Dir also pays attention only to packages for the current host platform, silently ignoring any cached packages for other platforms.

Various Dir methods return values that are technically mutable due to the restrictions of the Go typesystem, but callers are not permitted to mutate any part of the returned data structures.

func NewDir

func NewDir(baseDir string) *Dir

NewDir creates and returns a new Dir object that will read and write provider plugins in the given filesystem directory.

If two instances of Dir are concurrently operating on a particular base directory, or if a Dir base directory is also used as a filesystem mirror source directory, the behavior is undefined.

func NewDirWithPlatform

func NewDirWithPlatform(baseDir string, platform getproviders.Platform) *Dir

NewDirWithPlatform is a variant of NewDir that allows selecting a specific target platform, rather than taking the current one where this code is running.

This is primarily intended for portable unit testing and not particularly useful in "real" callers.

func (*Dir) AllAvailablePackages

func (d *Dir) AllAvailablePackages() map[addrs.Provider][]CachedProvider

AllAvailablePackages returns a description of all of the packages already present in the directory. The cache entries are grouped by the provider they relate to and then sorted by version precedence, with highest precedence first.

This function will return an empty result both when the directory is empty and when scanning the directory produces an error.

The caller is forbidden from modifying the returned data structure in any way, even though the Go type system permits it.

func (*Dir) BasePath

func (d *Dir) BasePath() string

BasePath returns the filesystem path of the base directory of this cache directory.

func (*Dir) InstallPackage

func (d *Dir) InstallPackage(ctx context.Context, meta getproviders.PackageMeta, allowedHashes []getproviders.Hash) (*getproviders.PackageAuthenticationResult, error)

InstallPackage takes a metadata object describing a package available for installation, retrieves that package, and installs it into the receiving cache directory.

If the allowedHashes set has non-zero length then at least one of the hashes in the set must match the package that "entry" refers to. If none of the hashes match then the returned error message assumes that the hashes came from a lock file.

func (*Dir) LinkFromOtherCache

func (d *Dir) LinkFromOtherCache(entry *CachedProvider, allowedHashes []getproviders.Hash) error

LinkFromOtherCache takes a CachedProvider value produced from another Dir and links it into the cache represented by the receiver Dir.

This is used to implement tiered caching, where new providers are first populated into a system-wide shared cache and then linked from there into a configuration-specific local cache.

It's invalid to link a CachedProvider from a particular Dir into that same Dir, because that would otherwise potentially replace a real package directory with a circular link back to itself.

If the allowedHashes set has non-zero length then at least one of the hashes in the set must match the package that "entry" refers to. If none of the hashes match then the returned error message assumes that the hashes came from a lock file.

func (*Dir) ProviderLatestVersion

func (d *Dir) ProviderLatestVersion(provider addrs.Provider) *CachedProvider

ProviderLatestVersion returns the cache entry for the latest version of the requested provider already available in the cache, or nil if there are no versions of that provider available.

func (*Dir) ProviderVersion

func (d *Dir) ProviderVersion(provider addrs.Provider, version getproviders.Version) *CachedProvider

ProviderVersion returns the cache entry for the requested provider version, or nil if the requested provider version isn't present in the cache.