resolver

Documentation

Overview

Package resolver defines APIs for name resolution in gRPC. All APIs in this package are experimental.

Index

• func GetDefaultScheme() string
• func Register(b Builder)
• func SetDefaultScheme(scheme string)
• func UnregisterForTesting(scheme string)
• type Address
• type AddressType
• type BuildOptions
• type Builder
  • func Get(scheme string) Builder
• type ClientConn
• type ResolveNowOptions
• type Resolver
• type State
• type Target

Functions

func GetDefaultScheme

func GetDefaultScheme() string

GetDefaultScheme gets the default scheme that will be used.

func Register

func Register(b Builder)

Register registers the resolver builder to the resolver map. b.Scheme will be used as the scheme registered with this builder.

NOTE: this function must only be called during initialization time (i.e. in an init() function), and is not thread-safe. If multiple Resolvers are registered with the same name, the one registered last will take effect.

func SetDefaultScheme

func SetDefaultScheme(scheme string)

SetDefaultScheme sets the default scheme that will be used. The default default scheme is "passthrough".

NOTE: this function must only be called during initialization time (i.e. in an init() function), and is not thread-safe. The scheme set last overrides previously set values.

func UnregisterForTesting

func UnregisterForTesting(scheme string)

UnregisterForTesting removes the resolver builder with the given scheme from the resolver map. This function is for testing only.

Types

type Address

type Address struct {
	// Addr is the server address on which a connection will be established.
	Addr string

	// ServerName is the name of this address.
	// If non-empty, the ServerName is used as the transport certification authority for
	// the address, instead of the hostname from the Dial target string. In most cases,
	// this should not be set.
	//
	// If Type is GRPCLB, ServerName should be the name of the remote load
	// balancer, not the name of the backend.
	//
	// WARNING: ServerName must only be populated with trusted values. It
	// is insecure to populate it with data from untrusted inputs since untrusted
	// values could be used to bypass the authority checks performed by TLS.
	ServerName string

	// Attributes contains arbitrary data about this address intended for
	// consumption by the load balancing policy.
	Attributes *attributes.Attributes

	// Type is the type of this address.
	//
	// Deprecated: use Attributes instead.
	Type AddressType

	// Metadata is the information associated with Addr, which may be used
	// to make load balancing decision.
	//
	// Deprecated: use Attributes instead.
	Metadata interface{}
}

Address represents a server the client connects to.

Experimental

Notice: This type is EXPERIMENTAL and may be changed or removed in a later release.

type AddressType

type AddressType uint8

AddressType indicates the address type returned by name resolution.

Deprecated: use Attributes in Address instead.

const (
	// Backend indicates the address is for a backend server.
	//
	// Deprecated: use Attributes in Address instead.
	Backend AddressType = iota
	// GRPCLB indicates the address is for a grpclb load balancer.
	//
	// Deprecated: to select the GRPCLB load balancing policy, use a service
	// config with a corresponding loadBalancingConfig.  To supply balancer
	// addresses to the GRPCLB load balancing policy, set State.Attributes
	// using balancer/grpclb/state.Set.
	GRPCLB
)

type BuildOptions

type BuildOptions struct {
	// DisableServiceConfig indicates whether a resolver implementation should
	// fetch service config data.
	DisableServiceConfig bool
	// DialCreds is the transport credentials used by the ClientConn for
	// communicating with the target gRPC service (set via
	// WithTransportCredentials). In cases where a name resolution service
	// requires the same credentials, the resolver may use this field. In most
	// cases though, it is not appropriate, and this field may be ignored.
	DialCreds credentials.TransportCredentials
	// CredsBundle is the credentials bundle used by the ClientConn for
	// communicating with the target gRPC service (set via
	// WithCredentialsBundle). In cases where a name resolution service
	// requires the same credentials, the resolver may use this field. In most
	// cases though, it is not appropriate, and this field may be ignored.
	CredsBundle credentials.Bundle
	// Dialer is the custom dialer used by the ClientConn for dialling the
	// target gRPC service (set via WithDialer). In cases where a name
	// resolution service requires the same dialer, the resolver may use this
	// field. In most cases though, it is not appropriate, and this field may
	// be ignored.
	Dialer func(context.Context, string) (net.Conn, error)
}

BuildOptions includes additional information for the builder to create the resolver.

type Builder

type Builder interface {
	// Build creates a new resolver for the given target.
	//
	// gRPC dial calls Build synchronously, and fails if the returned error is
	// not nil.
	Build(target Target, cc ClientConn, opts BuildOptions) (Resolver, error)
	// Scheme returns the scheme supported by this resolver.
	// Scheme is defined at https://github.com/grpc/grpc/blob/master/doc/naming.md.
	Scheme() string
}

Builder creates a resolver that will be used to watch name resolution updates.

func Get

func Get(scheme string) Builder

Get returns the resolver builder registered with the given scheme.

If no builder is register with the scheme, nil will be returned.

type ClientConn

type ClientConn interface {
	// UpdateState updates the state of the ClientConn appropriately.
	UpdateState(State) error
	// ReportError notifies the ClientConn that the Resolver encountered an
	// error.  The ClientConn will notify the load balancer and begin calling
	// ResolveNow on the Resolver with exponential backoff.
	ReportError(error)
	// NewAddress is called by resolver to notify ClientConn a new list
	// of resolved addresses.
	// The address list should be the complete list of resolved addresses.
	//
	// Deprecated: Use UpdateState instead.
	NewAddress(addresses []Address)
	// NewServiceConfig is called by resolver to notify ClientConn a new
	// service config. The service config should be provided as a json string.
	//
	// Deprecated: Use UpdateState instead.
	NewServiceConfig(serviceConfig string)
	// ParseServiceConfig parses the provided service config and returns an
	// object that provides the parsed config.
	ParseServiceConfig(serviceConfigJSON string) *serviceconfig.ParseResult
}

ClientConn contains the callbacks for resolver to notify any updates to the gRPC ClientConn.

This interface is to be implemented by gRPC. Users should not need a brand new implementation of this interface. For the situations like testing, the new implementation should embed this interface. This allows gRPC to add new methods to this interface.

type ResolveNowOptions

type ResolveNowOptions struct{}

ResolveNowOptions includes additional information for ResolveNow.

type Resolver

type Resolver interface {
	// ResolveNow will be called by gRPC to try to resolve the target name
	// again. It's just a hint, resolver can ignore this if it's not necessary.
	//
	// It could be called multiple times concurrently.
	ResolveNow(ResolveNowOptions)
	// Close closes the resolver.
	Close()
}

Resolver watches for the updates on the specified target. Updates include address updates and service config updates.

type State

type State struct {
	// Addresses is the latest set of resolved addresses for the target.
	Addresses []Address

	// ServiceConfig contains the result from parsing the latest service
	// config.  If it is nil, it indicates no service config is present or the
	// resolver does not provide service configs.
	ServiceConfig *serviceconfig.ParseResult

	// Attributes contains arbitrary data about the resolver intended for
	// consumption by the load balancing policy.
	Attributes *attributes.Attributes
}

State contains the current Resolver state relevant to the ClientConn.

type Target

type Target struct {
	Scheme    string
	Authority string
	Endpoint  string
}

Target represents a target for gRPC, as specified in: https://github.com/grpc/grpc/blob/master/doc/naming.md. It is parsed from the target string that gets passed into Dial or DialContext by the user. And grpc passes it to the resolver and the balancer.

If the target follows the naming spec, and the parsed scheme is registered with grpc, we will parse the target string according to the spec. e.g. "dns://some_authority/foo.bar" will be parsed into &Target{Scheme: "dns", Authority: "some_authority", Endpoint: "foo.bar"}

If the target does not contain a scheme, we will apply the default scheme, and set the Target to be the full target string. e.g. "foo.bar" will be parsed into &Target{Scheme: resolver.GetDefaultScheme(), Endpoint: "foo.bar"}.

If the parsed scheme is not registered (i.e. no corresponding resolver available to resolve the endpoint), we set the Scheme to be the default scheme, and set the Endpoint to be the full target string. e.g. target string "unknown_scheme://authority/endpoint" will be parsed into &Target{Scheme: resolver.GetDefaultScheme(), Endpoint: "unknown_scheme://authority/endpoint"}.