Documentation
¶
Overview ¶
Package getmodules contains the low-level functionality for fetching remote module packages. It's essentially just a thin wrapper around go-getter.
This package is only for remote module source addresses, not for local or registry source addresses. The other address types are handled elsewhere.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExpandSubdirGlobs ¶
ExpandSubdirGlobs handles a subdir string that might contain glob syntax, turning it into a concrete subdirectory path by referring to the actual files on disk in the given directory which we assume contains the content of whichever package this is a subdirectory glob for.
Subdir globs are used, for example, when a module registry wants to specify to select the contents of the single directory at the root of a conventional tar archive but it doesn't actually know the exact name of that directory. In that case it might specify a subdir of just "*", which this function will then expand into the single subdirectory found inside instDir, or return an error if the result would be ambiguous.
func NormalizePackageAddress ¶
NormalizePackageAddress uses the go-getter "detector" functionality in order to turn a user-supplied source address into a normalized address which always includes a prefix naming a protocol to fetch with and may also include a transformed/normalized version of the protocol-specific source address included afterward.
This is part of the implementation of addrs.ParseModulePackage and of addrs.ParseModuleSource, so for most callers it'd be better to call one of those other functions instead. The addrs package can potentially perform other processing in addition to just the go-getter detection.
Note that this function expects to recieve only a package address, not a full source address that might also include a subdirectory portion. The caller must trim off any subdirectory portion using getmodules.SplitPackageSubdir before calling this function, passing in just the packageAddr return value, or the result will be incorrect.
The detectors in go-getter can potentially introduce their own package subdirectory portions. If that happens then this function will return the subdirectory portion as a non-empty subDir return value, which the caller must then use as a prefix for any subDir it already extracted from the user's given package address.
Some of go-getter's detectors make outgoing HTTP requests, and so the behavior of this function may depend on the network connectivity of the system where Terraform is running. However, most of the getters we use are local-only, and so HTTP requests are only for some ambiguous edge-cases, such as the BitBucket detector which has a mechanism to detect whether to use Git or Mercurial, because earlier versions of BitBucket used to support both.
func SplitPackageSubdir ¶
SplitPackageSubdir detects whether the given address string has a subdirectory portion, and if so returns a non-empty subDir string along with the trimmed package address.
If the given string doesn't have a subdirectory portion then it'll just be returned verbatim in packageAddr, with an empty subDir value.
Although the rest of this package is focused only on direct remote module packages, this particular function and its companion ExpandSubdirGlobs are both also relevant for registry-based module addresses, because a registry translates such an address into a remote module package address and thus can contribute its own additions to the final subdirectory selection.
Types ¶
type MaybeRelativePathErr ¶
type MaybeRelativePathErr struct {
Addr string
}
MaybeRelativePathErr is the error type returned by NormalizePackageAddress if the source address looks like it might be intended to be a relative filesystem path but without the required "./" or "../" prefix.
Specifically, NormalizePackageAddress will return a pointer to this type, so the error type will be *MaybeRelativePathErr.
It has a name starting with "Maybe" because in practice we can get here with any string that isn't recognized as one of the supported schemes: treating the address as a local filesystem path is our fallback for when everything else fails, but it could just as easily be a typo in an attempt to use one of the other schemes and thus not a filesystem path at all.
func (*MaybeRelativePathErr) Error ¶
func (e *MaybeRelativePathErr) Error() string
type PackageFetcher ¶
type PackageFetcher struct {
// contains filtered or unexported fields
}
PackageFetcher is a low-level utility for fetching remote module packages into local filesystem directories in preparation for use by higher-level module installer functionality implemented elsewhere.
A PackageFetcher works only with entire module packages and never with the individual modules within a package.
A particular PackageFetcher instance remembers the target directory of any successfully-installed package so that it can optimize future calls that have the same package address by copying the local directory tree, rather than fetching the package from its origin repeatedly. There is no way to reset this cache, so a particular PackageFetcher instance should live only for the duration of a single initialization process.
func NewPackageFetcher ¶
func NewPackageFetcher() *PackageFetcher
func (*PackageFetcher) FetchPackage ¶
func (f *PackageFetcher) FetchPackage(ctx context.Context, instDir string, packageAddr string) error
FetchPackage downloads or otherwise retrieves the filesystem inside the package at the given address into the given local installation directory.
packageAddr must be formatted as if it were the result of an addrs.ModulePackage.String() call. It's only defined as a raw string here because the getmodules package can't import the addrs package due to that creating a package dependency cycle.
PackageFetcher only works with entire packages. If the caller is processing a module source address which includes a subdirectory portion then the caller must resolve that itself, possibly with the help of the getmodules.SplitPackageSubdir and getmodules.ExpandSubdirGlobs functions.
Source Files