disco

Documentation

Overview

Package disco handles Terraform's remote service discovery protocol.

This protocol allows mapping from a service hostname, as produced by the svchost package, to a set of services supported by that host and the endpoint information for each supported service.

Index

• type Disco
  • func New() *Disco
  • func NewWithCredentialsSource(credsSrc auth.CredentialsSource) *Disco
  • func (d *Disco) CredentialsForHost(host svchost.Hostname) (auth.HostCredentials, error)
  • func (d *Disco) Discover(host svchost.Hostname) Host
  • func (d *Disco) DiscoverServiceURL(host svchost.Hostname, serviceID string) *url.URL
  • func (d *Disco) ForceHostServices(host svchost.Hostname, services map[string]interface{})
  • func (d *Disco) Forget(host svchost.Hostname)
  • func (d *Disco) ForgetAll()
  • func (d *Disco) SetCredentialsSource(src auth.CredentialsSource)
• type Host
  • func (h Host) ServiceURL(id string) *url.URL

Types

type Disco

type Disco struct {

	// Transport is a custom http.RoundTripper to use.
	// A package default is used if this is nil.
	Transport http.RoundTripper
	// contains filtered or unexported fields
}

Disco is the main type in this package, which allows discovery on given hostnames and caches the results by hostname to avoid repeated requests for the same information.

func New

func New() *Disco

New returns a new initialized discovery object.

func NewWithCredentialsSource

func NewWithCredentialsSource(credsSrc auth.CredentialsSource) *Disco

NewWithCredentialsSource returns a new discovery object initialized with the given credentials source.

func (*Disco) CredentialsForHost

func (d *Disco) CredentialsForHost(host svchost.Hostname) (auth.HostCredentials, error)

CredentialsForHost returns a non-nil HostCredentials if the embedded source has credentials available for the host, and a nil HostCredentials if it does not.

func (*Disco) Discover

func (d *Disco) Discover(host svchost.Hostname) Host

Discover runs the discovery protocol against the given hostname (which must already have been validated and prepared with svchost.ForComparison) and returns an object describing the services available at that host.

If a given hostname supports no Terraform services at all, a non-nil but empty Host object is returned. When giving feedback to the end user about such situations, we say e.g. "the host <name> doesn't provide a module registry", regardless of whether that is due to that service specifically being absent or due to the host not providing Terraform services at all, since we don't wish to expose the detail of whole-host discovery to an end-user.

func (*Disco) DiscoverServiceURL

func (d *Disco) DiscoverServiceURL(host svchost.Hostname, serviceID string) *url.URL

DiscoverServiceURL is a convenience wrapper for discovery on a given hostname and then looking up a particular service in the result.

func (*Disco) ForceHostServices

func (d *Disco) ForceHostServices(host svchost.Hostname, services map[string]interface{})

ForceHostServices provides a pre-defined set of services for a given host, which prevents the receiver from attempting network-based discovery for the given host. Instead, the given services map will be returned verbatim.

When providing "forced" services, any relative URLs are resolved against the initial discovery URL that would have been used for network-based discovery, yielding the same results as if the given map were published at the host's default discovery URL, though using absolute URLs is strongly recommended to make the configured behavior more explicit.

func (*Disco) Forget

func (d *Disco) Forget(host svchost.Hostname)

Forget invalidates any cached record of the given hostname. If the host has no cache entry then this is a no-op.

func (*Disco) ForgetAll

func (d *Disco) ForgetAll()

ForgetAll is like Forget, but for all of the hostnames that have cache entries.

func (*Disco) SetCredentialsSource

func (d *Disco) SetCredentialsSource(src auth.CredentialsSource)

SetCredentialsSource provides a credentials source that will be used to add credentials to outgoing discovery requests, where available.

If this method is never called, no outgoing discovery requests will have credentials.

type Host

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

func (Host) ServiceURL

func (h Host) ServiceURL(id string) *url.URL

ServiceURL returns the URL associated with the given service identifier, which should be of the form "servicename.vN".

A non-nil result is always an absolute URL with a scheme of either https or http.

If the requested service is not supported by the host, this method returns a nil URL.

If the discovery document entry for the given service is invalid (not a URL), it is treated as absent, also returning a nil URL.