regsrc

Documentation

Overview

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

Index

• Variables
• type FriendlyHost
  • func NewFriendlyHost(host string) *FriendlyHost
  • func ParseFriendlyHost(source string) (host *FriendlyHost, rest string)
  • func (h *FriendlyHost) Display() string
  • func (h *FriendlyHost) Equal(other *FriendlyHost) bool
  • func (h *FriendlyHost) Normalized() string
  • func (h *FriendlyHost) String() string
  • func (h *FriendlyHost) Valid() bool
• type Module
  • func NewModule(host, namespace, name, provider, submodule string) (*Module, error)
  • func ParseModuleSource(source string) (*Module, error)
  • func (m *Module) Display() string
  • func (m *Module) Equal(other *Module) bool
  • func (m *Module) Host() *FriendlyHost
  • func (m *Module) Module() string
  • func (m *Module) Normalized() string
  • func (m *Module) String() string
  • func (m *Module) SvcHost() (svchost.Hostname, error)
• type TerraformProvider
  • func NewTerraformProvider(name, os, arch string) *TerraformProvider
  • func (p *TerraformProvider) SvcHost() (svchost.Hostname, error)
  • func (p *TerraformProvider) TerraformProvider() string

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 (
	// DefaultProviderNamespace represents the namespace for canonical
	// HashiCorp-controlled providers.
	DefaultProviderNamespace = "-"
)

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")
)

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

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.

type TerraformProvider

type TerraformProvider struct {
	RawHost      *FriendlyHost
	RawNamespace string
	RawName      string
	OS           string
	Arch         string
}

TerraformProvider describes a Terraform Registry Provider source.

func NewTerraformProvider

func NewTerraformProvider(name, os, arch string) *TerraformProvider

NewTerraformProvider constructs a new provider source.

func (*TerraformProvider) SvcHost

func (p *TerraformProvider) SvcHost() (svchost.Hostname, error)

SvcHost returns the svchost.Hostname for this provider. The default PublicRegistryHost is returned.

func (*TerraformProvider) TerraformProvider

func (p *TerraformProvider) TerraformProvider() string

Provider returns just the registry ID of the provider