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 Constraints
• type Disco
  • func New() *Disco
  • func NewWithCredentialsSource(credsSrc auth.CredentialsSource) *Disco
  • func (d *Disco) CredentialsForHost(hostname svchost.Hostname) (auth.HostCredentials, error)
  • func (d *Disco) Discover(hostname svchost.Hostname) (*Host, error)
  • func (d *Disco) DiscoverServiceURL(hostname svchost.Hostname, serviceID string) (*url.URL, error)
  • func (d *Disco) ForceHostServices(hostname svchost.Hostname, services map[string]interface{})
  • func (d *Disco) Forget(hostname svchost.Hostname)
  • func (d *Disco) ForgetAll()
  • func (d *Disco) SetCredentialsSource(src auth.CredentialsSource)
• type ErrNoVersionConstraints
  • func (e *ErrNoVersionConstraints) Error() string
• type ErrServiceNotProvided
  • func (e *ErrServiceNotProvided) Error() string
• type ErrVersionNotSupported
  • func (e *ErrVersionNotSupported) Error() string
• type Host
  • func (h *Host) ServiceURL(id string) (*url.URL, error)
  • func (h *Host) VersionConstraints(id, product string) (*Constraints, error)

Types

type Constraints

type Constraints struct {
	Service   string   `json:"service"`
	Product   string   `json:"product"`
	Minimum   string   `json:"minimum"`
	Excluding []string `json:"excluding"`
	Maximum   string   `json:"maximum"`
}

Constraints represents the version constraints of a service.

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(hostname 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(hostname svchost.Hostname) (*Host, error)

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 "host <name> does not provide a <service> service", 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(hostname svchost.Hostname, serviceID string) (*url.URL, error)

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(hostname 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(hostname 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 ErrNoVersionConstraints

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

ErrNoVersionConstraints is returned when checkpoint was disabled or the endpoint to query for version constraints was unavailable.

func (*ErrNoVersionConstraints) Error

func (e *ErrNoVersionConstraints) Error() string

Error returns a customized error message.

type ErrServiceNotProvided

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

ErrServiceNotProvided is returned when the service is not provided.

func (*ErrServiceNotProvided) Error

func (e *ErrServiceNotProvided) Error() string

Error returns a customized error message.

type ErrVersionNotSupported

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

ErrVersionNotSupported is returned when the version is not supported.

func (*ErrVersionNotSupported) Error

func (e *ErrVersionNotSupported) Error() string

Error returns a customized error message.

type Host

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

Host represents a service discovered host.

func (*Host) ServiceURL

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

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.

func (*Host) VersionConstraints

func (h *Host) VersionConstraints(id, product string) (*Constraints, error)

VersionConstraints returns the contraints for a given service identifier (which should be of the form "servicename.vN") and product.

When an exact (service and version) match is found, the constraints for that service are returned.

When the requested version is not provided but the service is, we will search for all alternative versions. If mutliple alternative versions are found, the contrains of the latest available version are returned.

When a service is not provided at all an error will be returned instead.

When checkpoint is disabled or when a 404 is returned after making the HTTP call, an ErrNoVersionConstraints error will be returned.