regaddr

README

OpenTofu Registry Addresses

This Go library contains types to represent module and provider registry addresses as used in OpenTofu, along with the canonical implementations of parsing and comparing those addresses.

Provider addresses can be found in

• tofu show -json <FILE> (full_name)
• tofu version -json (provider_selections)
• tofu providers schema -json (keys of provider_schemas)
• within required_providers block in OpenTofu modules
• OpenTofu CLI configuration file
• Plugin reattach configurations

Module addresses can be found within source argument of module blocks in OpenTofu modules (*.tf) and parts of the address (namespace and name) in the Module Registry API.

Compatibility

The module aims for compatibility with OpenTofu v1.5 and later.

Usage

Provider

pAddr, err := regaddr.ParseProviderSource("foo/bar")
if err != nil {
	// deal with error
}

// pAddr == regaddr.Provider{
//   Type:      "foo",
//   Namespace: "bar",
//   Hostname:  regaddr.DefaultProviderRegistryHost,
// }

Module

mAddr, err := regaddr.ParseModuleSource("foo/bar/baz//modules/example")
if err != nil {
	// deal with error
}

// mAddr == Module{
//   Package: ModulePackage{
//     Host:         regaddr.DefaultModuleRegistryHost,
//     Namespace:    "foo",
//     Name:         "bar",
//     TargetSystem: "baz",
//   },
//   Subdir: "modules/example",
// },

Other Module Address Formats

OpenTofu supports various other module source address types that are not handled by this library. This library focuses only on the syntax used for OpenTofu module registries.

Documentation

Index

• Constants
• func MustParseProviderPart(given string) string
• func ParseProviderPart(given string) (string, error)
• func ValidateProviderAddress(raw string) error
• type Module
  • func MustParseModuleSource(raw string) Module
  • func ParseModuleSource(raw string) (Module, error)
  • func (s Module) ForDisplay() string
  • func (s Module) String() string
• type ModulePackage
  • func (s ModulePackage) ForDisplay() string
  • func (s ModulePackage) ForRegistryProtocol() string
  • func (s ModulePackage) String() string
• type ParserError
  • func (pe *ParserError) Error() string
• type Provider
  • func MustParseProviderSource(raw string) Provider
  • func NewProvider(hostname svchost.Hostname, namespace, typeName string) Provider
  • func ParseProviderSource(str string) (Provider, error)
  • 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

Examples

• ParseModuleSource
• ParseProviderSource

Constants

const BuiltInProviderHost = svchost.Hostname("opentofu.org")

BuiltInProviderHost is a hostname currently reserved for potential future use to represent built-in providers that are OpenTofu-specific, rather than inherited from OpenTofu's predecessor.

To determine whether a particular provider address should be treated as built-in, prefer to use Provider.IsBuiltIn instead of directly comparing to this value, because TransitionalBuiltInProviderHost is also a valid hostname for certain built-in providers.

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 DefaultModuleRegistryHost = svchost.Hostname("registry.opentofu.org")

DefaultModuleRegistryHost is the hostname used for registry-based module source addresses that do not have an explicit hostname.

const DefaultProviderRegistryHost = svchost.Hostname("registry.opentofu.org")

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 is produced only by historical versions of OpenTofu's predecessor.

const TransitionalBuiltInProviderHost = svchost.Hostname("terraform.io")

TransitionalBuiltInProviderHost is a hostname used for the namespace of "built-in" providers inherited from OpenTofu's predecessor. Built-in provider addresses must also have their namespace set to BuiltInProviderNamespace in order to be considered as built-in.

const TransitionalDefaultModuleRegistryHost = svchost.Hostname("registry.terraform.io")

TransitionalDefaultModuleRegistryHost is the equivalent to DefaultModuleRegistryHost from OpenTofu's predecessor project, which OpenTofu might sometimes need to handle in a special way to support those switching existing configurations to use OpenTofu.

const TransitionalDefaultProviderRegistryHost = svchost.Hostname("registry.terraform.io")

TransitionalDefaultProviderRegistryHost is the default registry hostname used by OpenTofu's predecessor.

Addresses with this hostname are not typically used directly with OpenTofu, but OpenTofu contains some support code to help with automatically migrating certain uses of this hostname to use DefaultProviderRegistryHost instead.

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 OpenTofu itself explicitly, since it is only an internal placeholder.

Functions

func MustParseProviderPart

func MustParseProviderPart(given string) string

MustParseProviderPart is a wrapper around ParseProviderPart that panics if it returns an error.

func ParseProviderPart

func ParseProviderPart(given string) (string, error)

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

func ValidateProviderAddress(raw string) error

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 Module

type Module struct {
	// Package is the registry package that the target module belongs to.
	// The module installer must translate this into a ModuleSourceRemote
	// using the registry API and then take that underlying address's
	// Package in order to find the actual package location.
	Package ModulePackage

	// If Subdir is non-empty then it represents a sub-directory within the
	// remote package that the registry address eventually resolves to.
	// This will ultimately become the suffix of the Subdir of the
	// ModuleSourceRemote that the registry address translates to.
	//
	// Subdir uses a normalized forward-slash-based path syntax within the
	// virtual filesystem represented by the final package. It will never
	// include `../` or `./` sequences.
	Subdir string
}

Module is representing a module listed in an OpenTofu module registry.

func MustParseModuleSource

func MustParseModuleSource(raw string) Module

MustParseModuleSource is a wrapper around ParseModuleSource that panics if it returns an error.

func ParseModuleSource

func ParseModuleSource(raw string) (Module, error)

ParseModuleSource only accepts module registry addresses, and will reject any other address type.

Example

mAddr, err := ParseModuleSource("hashicorp/consul/aws//modules/consul-cluster")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%#v", mAddr)

Output:
regaddr.Module{Package:regaddr.ModulePackage{Host:svchost.Hostname("registry.opentofu.org"), Namespace:"hashicorp", Name:"consul", TargetSystem:"aws"}, Subdir:"modules/consul-cluster"}

func (Module) ForDisplay

func (s Module) ForDisplay() string

ForDisplay is similar to String but instead returns a representation of the idiomatic way to write the address in configuration, omitting components that are commonly just implied in addresses written by users.

We typically use this shorter representation in informational messages, such as the note that we're about to start downloading a package.

func (Module) String

func (s Module) String() string

String returns a full representation of the address, including any additional components that are typically implied by omission in user-written addresses.

We typically use this longer representation in error message, in case the inclusion of normally-omitted components is helpful in debugging unexpected behavior.

type ModulePackage

type ModulePackage struct {
	Host         svchost.Hostname
	Namespace    string
	Name         string
	TargetSystem string
}

ModulePackage represents a module package that can be installed using information from an OpenTofu module registry.

func (ModulePackage) ForDisplay

func (s ModulePackage) ForDisplay() string

func (ModulePackage) ForRegistryProtocol

func (s ModulePackage) ForRegistryProtocol() string

ForRegistryProtocol returns a string representation of just the namespace, name, and target system portions of the address, always omitting the registry hostname and the subdirectory portion, if any.

This is primarily intended for generating addresses to send to the registry in question via the registry protocol, since the protocol skips sending the registry its own hostname as part of identifiers.

func (ModulePackage) String

func (s ModulePackage) String() string

type ParserError

type ParserError struct {
	Summary string
	Detail  string
}

func (*ParserError) Error

func (pe *ParserError) Error() string

type Provider

type Provider struct {
	Type      string
	Namespace string
	Hostname  svchost.Hostname
}

Provider encapsulates a single provider type. In the future this will be extended to include additional fields including Namespace and SourceHost

func MustParseProviderSource

func MustParseProviderSource(raw string) Provider

MustParseProviderSource is a wrapper around ParseProviderSource that panics if it returns an error.

func NewProvider

func NewProvider(hostname svchost.Hostname, namespace, typeName string) Provider

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

func ParseProviderSource(str string) (Provider, error)

ParseProviderSource parses the source attribute and returns a provider.

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

Example

pAddr, err := ParseProviderSource("hashicorp/aws")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%#v", pAddr)

Output:
regaddr.Provider{Type:"aws", Namespace:"hashicorp", Hostname:svchost.Hostname("registry.opentofu.org")}

func (Provider) Equals

func (pt Provider) Equals(other Provider) bool

Equals returns true if the receiver and other provider have the same attributes.

func (Provider) ForDisplay

func (pt Provider) ForDisplay() string

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

func (pt Provider) HasKnownNamespace() bool

HasKnownNamespace returns true if the provider namespace is known (also if it is legacy namespace)

func (Provider) IsBuiltIn

func (pt Provider) IsBuiltIn() bool

IsBuiltIn returns true if the receiver is the address of a "built-in" provider. That is, a provider under that is included as part of the OpenTofu CLI executable itself rather than one to be installed from elsewhere.

These are ignored by the OpenTofu provider installer because they are assumed to already be available without any further installation.

func (Provider) IsLegacy

func (pt Provider) IsLegacy() bool

IsLegacy returns true if the provider is a legacy-style provider

func (Provider) IsZero

func (pt Provider) IsZero() bool

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

func (pt Provider) LegacyString() string

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

func (pt Provider) LessThan(other Provider) bool

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 the future.

func (Provider) String

func (pt Provider) String() string

String returns an FQN string, indended for use in machine-readable output.