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
- type Constraints
- type Disco
- func (d *Disco) Alias(alias, target svchost.Hostname)
- func (d *Disco) CredentialsForHost(hostname svchost.Hostname) (auth.HostCredentials, error)
- func (d *Disco) CredentialsSource() auth.CredentialsSource
- 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) ForgetAlias(alias svchost.Hostname)
- func (d *Disco) ForgetAll()
- func (d *Disco) SetCredentialsSource(src auth.CredentialsSource)
- func (d *Disco) SetUserAgent(uaString string)
- type ErrNoVersionConstraints
- type ErrServiceDiscoveryNetworkRequest
- type ErrServiceNotProvided
- type ErrVersionNotSupported
- type Host
- type OAuthClient
- type OAuthGrantType
- type OAuthGrantTypeSet
Constants ¶
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") )
const DefaultUserAgent = "terraform-svchost/1.0"
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Constraints ¶
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 NewWithCredentialsSource ¶
func NewWithCredentialsSource(credsSrc auth.CredentialsSource) *Disco
NewWithCredentialsSource returns a new discovery object initialized with the given credentials source.
func (*Disco) Alias ¶ added in v0.1.0
Alias accepts an alias and target Hostname. When service discovery is performed or credentials are requested for the alias hostname, the target will be consulted instead.
func (*Disco) CredentialsForHost ¶
CredentialsForHost returns a non-nil HostCredentials if the embedded source has credentials available for the host, or host alias, and a nil HostCredentials if it does not.
func (*Disco) CredentialsSource ¶
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 ¶
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 ¶
DiscoverServiceURL is a convenience wrapper for discovery on a given hostname and then looking up a particular service in the result.
func (*Disco) ForceHostServices ¶
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 ¶
Forget invalidates any cached record of the given hostname. If the host has no cache entry then this is a no-op.
func (*Disco) ForgetAlias ¶ added in v0.1.0
ForgetAlias removes a previously aliased hostname as well as its cached entry, if any exist. If the alias has no target 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.
func (*Disco) SetUserAgent ¶
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 ErrServiceDiscoveryNetworkRequest ¶
type ErrServiceDiscoveryNetworkRequest struct {
// contains filtered or unexported fields
}
ErrServiceDiscoveryNetworkRequest represents the error that occurs when the service discovery fails for an unknown network problem.
func (ErrServiceDiscoveryNetworkRequest) Error ¶
func (e ErrServiceDiscoveryNetworkRequest) Error() string
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) ServiceOAuthClient ¶
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 ¶
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.
type OAuthClient ¶
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
// Oauth2 does not require scopes for the authorization endpoint, however
// OIDC does. Optional list of scopes to include in auth code and token
// requests.
Scopes []string
}
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
type OAuthGrantTypeSet map[OAuthGrantType]struct{}
OAuthGrantTypeSet represents a set of OAuthGrantType values.
func NewOAuthGrantTypeSet ¶
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 ¶
func (s OAuthGrantTypeSet) GoString() string
GoString implements fmt.GoStringer.
func (OAuthGrantTypeSet) Has ¶
func (s OAuthGrantTypeSet) Has(t OAuthGrantType) bool
Has returns true if the given grant type is in the receiving set.
func (OAuthGrantTypeSet) RequiresAuthorizationEndpoint ¶
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 ¶
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