regsrc

package
v1.4.0 Latest Latest
Warning

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

Go to latest
Published: Mar 8, 2023 License: MPL-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package regsrc provides helpers for working with source strings that identify resources within a Terraform registry.

Index

Constants

This section is empty.

Variables

View Source
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 + "$")
)
View Source
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>"
)
View Source
var (
	// PublicRegistryHost is a FriendlyHost that represents the public registry.
	PublicRegistryHost = NewFriendlyHost("registry.terraform.io")
)

Functions

This section is empty.

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 ModuleFromModuleSourceAddr added in v1.1.0

func ModuleFromModuleSourceAddr(addr addrs.ModuleSourceRegistry) *Module

ModuleFromModuleSourceAddr is an adapter to automatically transform the modern representation of registry module addresses, addrs.ModuleSourceRegistry, into the legacy representation regsrc.Module.

Note that the new-style model always does normalization during parsing and does not preserve the raw user input at all, and so although the fields of regsrc.Module are all called "Raw...", initializing a Module indirectly through an addrs.ModuleSourceRegistry will cause those values to be the normalized ones, not the raw user input.

Use this only for temporary shims to call into existing code that still uses regsrc.Module. Eventually all other subsystems should be updated to use addrs.ModuleSourceRegistry instead, and then package regsrc can be removed altogether.

func ModuleFromRegistryPackageAddr added in v1.1.0

func ModuleFromRegistryPackageAddr(addr addrs.ModuleRegistryPackage) *Module

ModuleFromRegistryPackageAddr is similar to ModuleFromModuleSourceAddr, but it works with just the isolated registry package address, and not the full source address.

The practical implication of that is that RawSubmodule will always be the empty string in results from this function, because "Submodule" maps to "Subdir" and that's a module source address concept, not a module package concept. In practice this typically doesn't matter because the registry client ignores the RawSubmodule field anyway; that's a concern for the higher-level module installer to deal with.

func NewModule

func NewModule(host, namespace, name, provider, submodule string) (*Module, error)

NewModule construct a new module source from separate parts. Pass empty string if host or submodule are not needed.

func ParseModuleSource

func ParseModuleSource(source string) (*Module, error)

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

func (m *Module) Display() string

Display returns the source formatted for display to the user in CLI or web output.

func (*Module) Equal

func (m *Module) Equal(other *Module) bool

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

func (m *Module) Module() string

Module returns just the registry ID of the module, without a hostname or suffix.

func (*Module) Normalized

func (m *Module) Normalized() string

Normalized returns the source formatted for internal reference or comparison.

func (*Module) String

func (m *Module) String() string

String returns the source formatted as the user originally typed it assuming it was parsed from user input.

func (*Module) SvcHost

func (m *Module) SvcHost() (svchost.Hostname, error)

SvcHost returns the svchost.Hostname for this module. Since FriendlyHost may contain an invalid hostname, this also returns an error indicating if it could be converted to a svchost.Hostname. If no host is specified, the default PublicRegistryHost is returned.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL