sourceaddrs

Documentation

Overview

Package sourceaddrs deals with the various types of source code address that Terraform can gather into a source bundle via the sibling package "sourcebundle".

NOTE WELL: Everything in this package is currently experimental and subject to breaking changes even in patch releases. We will make stronger commitments to backward-compatibility once we have more experience using this functionality in real contexts.

Index

• func FinalSourceFilename(addr FinalSource) string
• func ParseRegistryPackage(given string) (regaddr.ModulePackage, error)
• func SourceFilename(addr Source) string
• func ValidSubPath(s string) bool
• type FinalSource
  • func ParseFinalSource(given string) (FinalSource, error)
  • func ResolveRelativeFinalSource(a, b FinalSource) (FinalSource, error)
• type LocalSource
  • func ParseLocalSource(given string) (LocalSource, error)
  • func (s LocalSource) RelativePath() string
  • func (s LocalSource) String() string
  • func (s LocalSource) SupportsVersionConstraints() bool
• type RegistrySource
  • func ParseRegistrySource(given string) (RegistrySource, error)
  • func (s RegistrySource) FinalSourceAddr(realSource RemoteSource) RemoteSource
  • func (s RegistrySource) Package() regaddr.ModulePackage
  • func (s RegistrySource) String() string
  • func (s RegistrySource) SubPath() string
  • func (s RegistrySource) SupportsVersionConstraints() bool
  • func (s RegistrySource) Versioned(selectedVersion versions.Version) RegistrySourceFinal
• type RegistrySourceFinal
  • func ParseFinalRegistrySource(given string) (RegistrySourceFinal, error)
  • func (s RegistrySourceFinal) FinalSourceAddr(realSource RemoteSource) RemoteSource
  • func (s RegistrySourceFinal) Package() regaddr.ModulePackage
  • func (s RegistrySourceFinal) SelectedVersion() versions.Version
  • func (s RegistrySourceFinal) String() string
  • func (s RegistrySourceFinal) SubPath() string
  • func (s RegistrySourceFinal) Unversioned() RegistrySource
• type RemotePackage
  • func ParseRemotePackage(given string) (RemotePackage, error)
  • func (p RemotePackage) SourceAddr(subPath string) RemoteSource
  • func (p RemotePackage) SourceType() string
  • func (p RemotePackage) String() string
  • func (p RemotePackage) URL() *url.URL
• type RemoteSource
  • func MakeRemoteSource(sourceType string, u *url.URL, subPath string) (RemoteSource, error)
  • func ParseRemoteSource(given string) (RemoteSource, error)
  • func (s RemoteSource) Package() RemotePackage
  • func (s RemoteSource) String() string
  • func (s RemoteSource) SubPath() string
  • func (s RemoteSource) SupportsVersionConstraints() bool
• type Source
  • func MustParseSource(given string) Source
  • func ParseSource(given string) (Source, error)
  • func ResolveRelativeSource(a, b Source) (Source, error)

Functions

func FinalSourceFilename

func FinalSourceFilename(addr FinalSource) string

FinalSourceFilename returns the base name (in the same sense as path.Base) of the sub-path or local path portion of the given final source address.

This only really makes sense for a source address that refers to an individual file, and is intended for needs such as using the suffix of the filename to decide how to parse a particular file. Passing a source address that refers to a directory will not fail but its result is unlikely to be useful.

func ParseRegistryPackage

func ParseRegistryPackage(given string) (regaddr.ModulePackage, error)

ParseRegistryPackage parses the given string as a registry package address, which is the same syntax as a registry source address with no sub-path portion.

func SourceFilename

func SourceFilename(addr Source) string

SourceFilename returns the base name (in the same sense as path.Base) of the sub-path or local path portion of the given source address.

This only really makes sense for a source address that refers to an individual file, and is intended for needs such as using the suffix of the filename to decide how to parse a particular file. Passing a source address that refers to a directory will not fail but its result is unlikely to be useful.

func ValidSubPath

func ValidSubPath(s string) bool

ValidSubPath returns true if the given string is a valid sub-path string as could be included in either a remote or registry source address.

A sub-path is valid if it's a slash-separated sequence of path segments without a leading or trailing slash and without any "." or ".." segments, since a sub-path can only traverse downwards from the root of a package.

Types

type FinalSource

type FinalSource interface {
	String() string
	// contains filtered or unexported methods
}

FinalSource is a variant of Source that always refers to a single specific package.

Specifically this models the annoying oddity that while LocalSource and RemoteSource fully specify what they refer to, RegistrySource only gives partial information and must be qualified with a selected version number to determine exactly what it refers to.

func ParseFinalSource

func ParseFinalSource(given string) (FinalSource, error)

ParseFinalSource attempts to parse the given string as any one of the three supported final source address types, recognizing which type it belongs to based on the syntax differences between the address forms.

func ResolveRelativeFinalSource

func ResolveRelativeFinalSource(a, b FinalSource) (FinalSource, error)

ResolveRelativeFinalSource is like ResolveRelativeSource but for FinalSource addresses instead of Source addresses.

Aside from the address type difference its meaning and behavior rules are the same.

type LocalSource

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

LocalSource represents a relative traversal to another path within the same source package as whatever source artifact included this path.

LocalSource sources will typically need to be resolved into either RemoteSource or RegistrySource addresses by reference to the address of whatever artifact declared them, because otherwise they cannot be mapped onto any real source location.

func ParseLocalSource

func ParseLocalSource(given string) (LocalSource, error)

ParseLocalSource interprets the given path as a local source address, or returns an error if it cannot be interpreted as such.

func (LocalSource) RelativePath

func (s LocalSource) RelativePath() string

RelativePath returns the effective relative path for this source address, in our platform-agnostic slash-separated canonical syntax.

func (LocalSource) String

func (s LocalSource) String() string

String implements Source

func (LocalSource) SupportsVersionConstraints

func (s LocalSource) SupportsVersionConstraints() bool

SupportsVersionConstraints implements Source

type RegistrySource

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

RegistrySource represents a source address referring to a set of versions published in a Module Registry.

A RegistrySource is an extra indirection over a set of RemoteSource addresses, which Terraform chooses from based on version constraints given alongside the registry source address.

func ParseRegistrySource

func ParseRegistrySource(given string) (RegistrySource, error)

ParseRegistrySource parses the given string as a registry source address, or returns an error if it does not use the correct syntax for interpretation as a registry source address.

func (RegistrySource) FinalSourceAddr

func (s RegistrySource) FinalSourceAddr(realSource RemoteSource) RemoteSource

FinalSourceAddr takes the result of looking up the package portion of the receiver in a module registry and appends the reciever's sub-path to the returned sub-path to produce the final fully-qualified remote source address.

func (RegistrySource) Package

func (s RegistrySource) Package() regaddr.ModulePackage

func (RegistrySource) String

func (s RegistrySource) String() string

func (RegistrySource) SubPath

func (s RegistrySource) SubPath() string

func (RegistrySource) SupportsVersionConstraints

func (s RegistrySource) SupportsVersionConstraints() bool

func (RegistrySource) Versioned

func (s RegistrySource) Versioned(selectedVersion versions.Version) RegistrySourceFinal

Versioned combines the receiver with a specific selected version number to produce a final source address that can be used to resolve to a single source package.

type RegistrySourceFinal

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

RegistrySourceFinal annotates a RegistrySource with a specific version selection, thereby making it sufficient for selecting a single real source package.

Registry sources are weird in comparison to others in that they must be combined with a version constraint to select from possibly many available versions. After completing the version selection process, the result can be represented as a RegistrySourceFinal that carries the selected version number along with the originally-specified source address.

func ParseFinalRegistrySource

func ParseFinalRegistrySource(given string) (RegistrySourceFinal, error)

ParseFinalRegistrySource parses the given string as a final registry source address, or returns an error if it does not use the correct syntax for interpretation as a final registry source address.

func (RegistrySourceFinal) FinalSourceAddr

func (s RegistrySourceFinal) FinalSourceAddr(realSource RemoteSource) RemoteSource

FinalSourceAddr takes the result of looking up the package portion of the receiver in a module registry and appends the reciever's sub-path to the returned sub-path to produce the final fully-qualified remote source address.

func (RegistrySourceFinal) Package

func (s RegistrySourceFinal) Package() regaddr.ModulePackage

func (RegistrySourceFinal) SelectedVersion

func (s RegistrySourceFinal) SelectedVersion() versions.Version

func (RegistrySourceFinal) String

func (s RegistrySourceFinal) String() string

func (RegistrySourceFinal) SubPath

func (s RegistrySourceFinal) SubPath() string

func (RegistrySourceFinal) Unversioned

func (s RegistrySourceFinal) Unversioned() RegistrySource

Unversioned returns the address of the registry package that this final address is a version of.

type RemotePackage

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

func ParseRemotePackage

func ParseRemotePackage(given string) (RemotePackage, error)

ParseRemotePackage parses a standalone remote package address, which is a remote source address without any sub-path portion.

func (RemotePackage) SourceAddr

func (p RemotePackage) SourceAddr(subPath string) RemoteSource

SourceAddr returns a remote source address referring to the given sub-path inside the recieving package.

subPath must be a valid sub-path (as defined by ValidSubPath) or this function will panic. An empty string is a valid sub-path representing the root directory of the package.

func (RemotePackage) SourceType

func (p RemotePackage) SourceType() string

SourceType returns the source type component of the package address.

func (RemotePackage) String

func (p RemotePackage) String() string

func (RemotePackage) URL

func (p RemotePackage) URL() *url.URL

URL returns the URL component of the package address.

Callers MUST NOT mutate anything accessible through the returned pointer, even though the Go type system cannot enforce that.

type RemoteSource

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

func MakeRemoteSource

func MakeRemoteSource(sourceType string, u *url.URL, subPath string) (RemoteSource, error)

MakeRemoteSource constructs a RemoteSource from its component parts.

This is useful for deriving one remote source from another, by disassembling the original address into its component parts, modifying those parts, and then combining the modified parts back together with this function.

func ParseRemoteSource

func ParseRemoteSource(given string) (RemoteSource, error)

ParseRemoteSource parses the given string as a remote source address, or returns an error if it does not use the correct syntax for interpretation as a remote source address.

func (RemoteSource) Package

func (s RemoteSource) Package() RemotePackage

func (RemoteSource) String

func (s RemoteSource) String() string

String implements Source

func (RemoteSource) SubPath

func (s RemoteSource) SubPath() string

func (RemoteSource) SupportsVersionConstraints

func (s RemoteSource) SupportsVersionConstraints() bool

type Source

type Source interface {
	String() string
	SupportsVersionConstraints() bool
	// contains filtered or unexported methods
}

Source acts as a tagged union over the three possible source address types, for situations where all three are acceptable.

Source is used to specify source addresses for installation. Once packages have been resolved and installed we use [SourceFinal] instead to represent those finalized selections, which allows capturing the selected version number for a module registry source address.

Only address types within this package can implement Source.

func MustParseSource

func MustParseSource(given string) Source

MustParseSource is a thin wrapper around ParseSource that panics if it returns an error, or returns its result if not.

func ParseSource

func ParseSource(given string) (Source, error)

ParseSource attempts to parse the given string as any one of the three supported source address types, recognizing which type it belongs to based on the syntax differences between the address forms.

func ResolveRelativeSource

func ResolveRelativeSource(a, b Source) (Source, error)

ResolveRelativeSource calculates a new source address from the combination of two other source addresses.

If "b" is already an absolute source address then the result is "b" verbatim.

If "b" is a relative source then the result is an address of the same type as "a", but with a different path component. If "a" is an absolute address type then the result is guaranteed to also be an absolute address type.

Returns an error if "b" is a relative path that attempts to traverse out of the package of an absolute address given in "a".