Documentation
¶
Overview ¶
Package regsrc provides helpers for working with source strings that identify resources within a Terraform registry.
Index ¶
- Constants
- Variables
- func MustParseProviderPart(given string) string
- func ParseProviderPart(given string) (string, error)
- func ValidateProviderAddress(raw string) error
- type FriendlyHost
- type Module
- type ParserError
- type Provider
- func (pt Provider) Equals(other Provider) bool
- func (pt Provider) ForDisplay() string
- func (pt Provider) HasKnownNamespace() bool
- func (pt Provider) IsBuiltIn() bool
- func (pt Provider) IsLegacy() bool
- func (pt Provider) IsZero() bool
- func (pt Provider) LegacyString() string
- func (pt Provider) LessThan(other Provider) bool
- func (pt Provider) String() string
Constants ¶
const BuiltInProviderHost = svchost.Hostname("terraform.io")
BuiltInProviderHost is the pseudo-hostname used for the "built-in" provider namespace. Built-in provider addresses must also have their namespace set to BuiltInProviderNamespace in order to be considered as built-in.
const BuiltInProviderNamespace = "builtin"
BuiltInProviderNamespace is the provider namespace used for "built-in" providers. Built-in provider addresses must also have their hostname set to BuiltInProviderHost in order to be considered as built-in.
The this namespace is literally named "builtin", in the hope that users who see FQNs containing this will be able to infer the way in which they are special, even if they haven't encountered the concept formally yet.
const DefaultProviderRegistryHost = svchost.Hostname("registry.terraform.io")
DefaultProviderRegistryHost is the hostname used for provider addresses that do not have an explicit hostname.
const LegacyProviderNamespace = "-"
LegacyProviderNamespace is the special string used in the Namespace field of type Provider to mark a legacy provider address. This special namespace value would normally be invalid, and can be used only when the hostname is DefaultProviderRegistryHost because that host owns the mapping from legacy name to FQN. This may be produced by Terraform 0.13.
const UnknownProviderNamespace = "?"
UnknownProviderNamespace is the special string used to indicate unknown namespace, e.g. in "aws". This is equivalent to LegacyProviderNamespace for <0.12 style address. This namespace would never be produced by Terraform itself explicitly, it is only an internal placeholder.
Variables ¶
var ( ErrInvalidModuleSource = errors.New("not a valid registry module source") // NameRe is a regular expression defining the format allowed for namespace // or name fields in module registry implementations. NameRe = regexp.MustCompile("^" + nameSubRe + "$") // ProviderRe is a regular expression defining the format allowed for // provider fields in module registry implementations. ProviderRe = regexp.MustCompile("^" + providerSubRe + "$") )
var ErrParseProvider = errors.New("error parsing provider")
var ErrSvcHostComparison = errors.New("error in for comparison of svchost")
var ( // InvalidHostString is a placeholder returned when a raw host can't be // converted by IDNA spec. It will never be returned for any host for which // Valid() is true. InvalidHostString = "<invalid host>" )
var ( // PublicRegistryHost is a FriendlyHost that represents the public registry. PublicRegistryHost = NewFriendlyHost("registry.terraform.io") )
Functions ¶
func MustParseProviderPart ¶ added in v0.4.3
MustParseProviderPart is a wrapper around ParseProviderPart that panics if it returns an error.
func ParseProviderPart ¶ added in v0.4.3
ParseProviderPart processes an addrs.Provider namespace or type string provided by an end-user, producing a normalized version if possible or an error if the string contains invalid characters.
A provider part is processed in the same way as an individual label in a DNS domain name: it is transformed to lowercase per the usual DNS case mapping and normalization rules and may contain only letters, digits, and dashes. Additionally, dashes may not appear at the start or end of the string.
These restrictions are intended to allow these names to appear in fussy contexts such as directory/file names on case-insensitive filesystems, repository names on GitHub, etc. We're using the DNS rules in particular, rather than some similar rules defined locally, because the hostname part of an addrs.Provider is already a hostname and it's ideal to use exactly the same case folding and normalization rules for all of the parts.
In practice a provider type string conventionally does not contain dashes either. Such names are permitted, but providers with such type names will be hard to use because their resource type names will not be able to contain the provider type name and thus each resource will need an explicit provider address specified. (A real-world example of such a provider is the "google-beta" variant of the GCP provider, which has resource types that start with the "google_" prefix instead.)
It's valid to pass the result of this function as the argument to a subsequent call, in which case the result will be identical.
func ValidateProviderAddress ¶ added in v0.4.3
ValidateProviderAddress returns error if the given address is not FQN, that is if it is missing any of the three components from hostname/namespace/name.
Types ¶
type FriendlyHost ¶
type FriendlyHost struct {
Raw string
}
FriendlyHost describes a registry instance identified in source strings by a simple bare hostname like registry.terraform.io.
func NewFriendlyHost ¶
func NewFriendlyHost(host string) *FriendlyHost
func ParseFriendlyHost ¶
func ParseFriendlyHost(source string) (host *FriendlyHost, rest string)
ParseFriendlyHost attempts to parse a valid "friendly host" prefix from the given string. If no valid prefix is found, host will be nil and rest will contain the full source string. The host prefix must terminate at the end of the input or at the first / character. If one or more characters exist after the first /, they will be returned as rest (without the / delimiter). Hostnames containing punycode WILL be parsed successfully since they may have come from an internal normalized source string, however should be considered invalid if the string came from a user directly. This must be checked explicitly for user-input strings by calling Valid() on the returned host.
func (*FriendlyHost) Display ¶
func (h *FriendlyHost) Display() string
Display returns the host formatted for display to the user in CLI or web output.
func (*FriendlyHost) Equal ¶
func (h *FriendlyHost) Equal(other *FriendlyHost) bool
Equal compares the FriendlyHost against another instance taking normalization into account. Invalid hosts cannot be compared and will always return false.
func (*FriendlyHost) Normalized ¶
func (h *FriendlyHost) Normalized() string
Normalized returns the host formatted for internal reference or comparison.
func (*FriendlyHost) String ¶
func (h *FriendlyHost) String() string
String returns the host formatted as the user originally typed it assuming it was parsed from user input.
func (*FriendlyHost) Valid ¶
func (h *FriendlyHost) Valid() bool
Valid returns whether the host prefix is considered valid in any case. Example of invalid prefixes might include ones that don't conform to the host name specifications. Not that IDN prefixes containing punycode are not valid input which we expect to always be in user-input or normalised display form.
type Module ¶
type Module struct {
// RawHost is the friendly host prefix if one was present. It might be nil
// if the original source had no host prefix which implies
// PublicRegistryHost but is distinct from having an actual pointer to
// PublicRegistryHost since it encodes the fact the original string didn't
// include a host prefix at all which is significant for recovering actual
// input not just normalized form. Most callers should access it with Host()
// which will return public registry host instance if it's nil.
RawHost *FriendlyHost
RawNamespace string
RawName string
RawProvider string
RawSubmodule string
}
Module describes a Terraform Registry Module source.
func NewModule ¶
NewModule construct a new module source from separate parts. Pass empty string if host or submodule are not needed.
func ParseModuleSource ¶
ParseModuleSource attempts to parse source as a Terraform registry module source. If the string is not found to be in a valid format, ErrInvalidModuleSource is returned. Note that this can only be used on "input" strings, e.g. either ones supplied by the user or potentially normalised but in Display form (unicode). It will fail to parse a source with a punycoded domain since this is not permitted input from a user. If you have an already normalized string internally, you can compare it without parsing by comparing with the normalized version of the subject with the normal string equality operator.
func (*Module) Display ¶
Display returns the source formatted for display to the user in CLI or web output.
func (*Module) Equal ¶
Equal compares the module source against another instance taking normalization into account.
func (*Module) Host ¶
func (m *Module) Host() *FriendlyHost
Host returns the FriendlyHost object describing which registry this module is in. If the original source string had not host component this will return the PublicRegistryHost.
func (*Module) Module ¶
Module returns just the registry ID of the module, without a hostname or suffix.
func (*Module) Normalized ¶
Normalized returns the source formatted for internal reference or comparison.
func (*Module) String ¶
String returns the source formatted as the user originally typed it assuming it was parsed from user input.
type ParserError ¶ added in v0.4.3
func (*ParserError) Error ¶ added in v0.4.3
func (pe *ParserError) Error() string
type Provider ¶ added in v0.4.3
Provider encapsulates a single provider type. In the future this will be extended to include additional fields including Namespace and SourceHost.
func MustParseProviderSource ¶ added in v0.4.3
MustParseProviderSource is a wrapper around ParseProviderSource that panics if it returns an error.
func NewProvider ¶ added in v0.4.3
NewProvider constructs a provider address from its parts, and normalizes the namespace and type parts to lowercase using unicode case folding rules so that resulting addrs.Provider values can be compared using standard Go equality rules (==).
The hostname is given as a svchost.Hostname, which is required by the contract of that type to have already been normalized for equality testing.
This function will panic if the given namespace or type name are not valid. When accepting namespace or type values from outside the program, use ParseProviderPart first to check that the given value is valid.
func ParseProviderSource ¶ added in v0.4.3
ParseProviderSource parses the source attribute and returns a provider. This is intended primarily to parse the FQN-like strings returned by terraform-config-inspect.
The following are valid source string formats:
name namespace/name hostname/namespace/name
"name"-only format is parsed as -/name (i.e. legacy namespace) requiring further identification of the namespace via Registry API.
func (Provider) Equals ¶ added in v0.4.3
Equals returns true if the receiver and other provider have the same attributes.
func (Provider) ForDisplay ¶ added in v0.4.3
ForDisplay returns a user-friendly FQN string, simplified for readability. If the provider is using the default hostname, the hostname is omitted.
func (Provider) HasKnownNamespace ¶ added in v0.4.3
HasKnownNamespace returns true if the provider namespace is known (also if it is legacy namespace).
func (Provider) IsBuiltIn ¶ added in v0.4.3
IsBuiltIn returns true if the receiver is the address of a "built-in" provider. That is, a provider under terraform.io/builtin/ which is included as part of the Terraform binary itself rather than one to be installed from elsewhere.
These are ignored by the provider installer because they are assumed to already be available without any further installation.
func (Provider) IsLegacy ¶ added in v0.4.3
IsLegacy returns true if the provider is a legacy-style provider.
func (Provider) IsZero ¶ added in v0.4.3
IsZero returns true if the receiver is the zero value of addrs.Provider.
The zero value is not a valid addrs.Provider and calling other methods on such a value is likely to either panic or otherwise misbehave.
func (Provider) LegacyString ¶ added in v0.4.3
LegacyString returns the provider type, which is frequently used interchangeably with provider name. This function can and should be removed when provider type is fully integrated. As a safeguard for future refactoring, this function panics if the Provider is not a legacy provider.
func (Provider) LessThan ¶ added in v0.4.3
LessThan returns true if the receiver should sort before the other given address in an ordered list of provider addresses.
This ordering is an arbitrary one just to allow deterministic results from functions that would otherwise have no natural ordering. It's subject to change in future.
Source Files