disco

package
v0.12.10 Latest Latest
Warning

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

 Go to latest Published: Oct 7, 2019 License: MPL-2.0 Imports: 19 Imported by: 0

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

Constants

View Source 
const (
	// OAuthAuthzCodeGrant represents an authorization code grant, as
	// defined in IETF RFC 6749 section 4.1.
	OAuthAuthzCodeGrant = OAuthGrantType("authz_code")

	// OAuthOwnerPasswordGrant represents a resource owner password
	// credentials grant, as defined in IETF RFC 6749 section 4.3.
	OAuthOwnerPasswordGrant = OAuthGrantType("password")
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Constraints added in v0.11.11 

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

Constraints represents the version constraints of a service.

type Disco 

type Disco struct {

	// Transport is a custom http.RoundTripper to use.
	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 added in v0.11.8 

func New() *Disco

New returns a new initialized discovery object.

func NewWithCredentialsSource added in v0.11.8 

func NewWithCredentialsSource(credsSrc auth.CredentialsSource) *Disco

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

func (*Disco) CredentialsForHost added in v0.11.8 

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) CredentialsSource added in v0.12.8 

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

CredentialsSource returns the credentials source associated with the receiver, or an empty credentials source if none is associated.

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 added in v0.11.0 

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 added in v0.11.11 

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 added in v0.11.11 

func (e *ErrNoVersionConstraints) Error() string

Error returns a customized error message.

type ErrServiceNotProvided added in v0.11.11 

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

ErrServiceNotProvided is returned when the service is not provided.

func (*ErrServiceNotProvided) Error added in v0.11.11 

func (e *ErrServiceNotProvided) Error() string

Error returns a customized error message.

type ErrVersionNotSupported added in v0.11.11 

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

ErrVersionNotSupported is returned when the version is not supported.

func (*ErrVersionNotSupported) Error added in v0.11.11 

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) ServiceOAuthClient added in v0.12.8 

func (h *Host) ServiceOAuthClient(id string) (*OAuthClient, error)

ServiceOAuthClient returns the OAuth client configuration associated with the given service identifier, which should be of the form "servicename.vN".

This is an alternative to ServiceURL for unusual services that require a full OAuth2 client definition rather than just a URL. Use this only for services whose specification calls for this sort of definition.

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 added in v0.11.11 

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.

type OAuthClient added in v0.12.8 

type OAuthClient struct {
	// ID is the identifier for the client, to be used as "client_id" in
	// OAuth requests.
	ID string

	// Authorization URL is the URL of the authorization endpoint that must
	// be used for this OAuth client, as defined in the OAuth2 specifications.
	//
	// Not all grant types use the authorization endpoint, so it may be omitted
	// if none of the grant types in SupportedGrantTypes require it.
	AuthorizationURL *url.URL

	// Token URL is the URL of the token endpoint that must be used for this
	// OAuth client, as defined in the OAuth2 specifications.
	//
	// Not all grant types use the token endpoint, so it may be omitted
	// if none of the grant types in SupportedGrantTypes require it.
	TokenURL *url.URL

	// MinPort and MaxPort define a range of TCP ports on localhost that this
	// client is able to use as redirect_uri in an authorization request.
	// Terraform will select a port from this range for the temporary HTTP
	// server it creates to receive the authorization response, giving
	// a URL like http://localhost:NNN/ where NNN is the selected port number.
	//
	// Terraform will reject any port numbers in this range less than 1024,
	// to respect the common convention (enforced on some operating systems)
	// that lower port numbers are reserved for "privileged" services.
	MinPort, MaxPort uint16

	// SupportedGrantTypes is a set of the grant types that the client may
	// choose from. This includes an entry for each distinct type advertised
	// by the server, even if a particular keyword is not supported by the
	// current version of Terraform.
	SupportedGrantTypes OAuthGrantTypeSet
}

OAuthClient represents an OAuth client configuration, which is used for unusual services that require an entire OAuth client configuration as part of their service discovery, rather than just a URL.

func (*OAuthClient) Endpoint added in v0.12.8 

func (c *OAuthClient) Endpoint() oauth2.Endpoint

Endpoint returns an oauth2.Endpoint value ready to be used with the oauth2 library, representing the URLs from the receiver.

type OAuthGrantType added in v0.12.8 

type OAuthGrantType string

OAuthGrantType is an enumeration of grant type strings that a host can advertise support for.

Values of this type don't necessarily match with a known constant of the type, because they may represent grant type keywords defined in a later version of Terraform which this version doesn't yet know about.

func (OAuthGrantType) UsesAuthorizationEndpoint added in v0.12.8 

func (t OAuthGrantType) UsesAuthorizationEndpoint() bool

UsesAuthorizationEndpoint returns true if the receiving grant type makes use of the authorization endpoint from the client configuration, and thus if the authorization endpoint ought to be required.

func (OAuthGrantType) UsesTokenEndpoint added in v0.12.8 

func (t OAuthGrantType) UsesTokenEndpoint() bool

UsesTokenEndpoint returns true if the receiving grant type makes use of the token endpoint from the client configuration, and thus if the authorization endpoint ought to be required.

type OAuthGrantTypeSet added in v0.12.8 

type OAuthGrantTypeSet map[OAuthGrantType]struct{}

OAuthGrantTypeSet represents a set of OAuthGrantType values.

func NewOAuthGrantTypeSet added in v0.12.8 

func NewOAuthGrantTypeSet(keywords ...string) OAuthGrantTypeSet

NewOAuthGrantTypeSet constructs a new grant type set from the given list of grant type keyword strings. Any duplicates in the list are ignored.

func (OAuthGrantTypeSet) GoString added in v0.12.8 

func (s OAuthGrantTypeSet) GoString() string

GoString implements fmt.GoStringer.

func (OAuthGrantTypeSet) Has added in v0.12.8 

func (s OAuthGrantTypeSet) Has(t OAuthGrantType) bool

Has returns true if the given grant type is in the receiving set.

func (OAuthGrantTypeSet) RequiresAuthorizationEndpoint added in v0.12.8 

func (s OAuthGrantTypeSet) RequiresAuthorizationEndpoint() bool

RequiresAuthorizationEndpoint returns true if any of the grant types in the set are known to require an authorization endpoint.

func (OAuthGrantTypeSet) RequiresTokenEndpoint added in v0.12.8 

func (s OAuthGrantTypeSet) RequiresTokenEndpoint() bool

RequiresTokenEndpoint returns true if any of the grant types in the set are known to require a token endpoint.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.