resolver
package
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
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 ValidateEndpoints(endpoints []Endpoint) error
- type Address
- type AddressMapdeprecated
- func NewAddressMap() *AddressMapdeprecated
- type AddressMapV2
- type AuthorityOverrider
- type BuildOptions
- type Builder
- type ClientConn
- type Endpoint
- type EndpointMap
- type ResolveNowOptions
- type Resolver
- type State
- type Target
Constants¶
This section is empty.
Variables¶
This section is empty.
Functions¶
funcGetDefaultScheme¶added inv1.10.1
func GetDefaultScheme()string
GetDefaultScheme gets the default scheme that will be used by grpc.Dial. IfSetDefaultScheme is never called, the default scheme used by grpc.NewClient is "dns" instead.
funcRegister¶
func Register(bBuilder)
Register registers the resolver builder to the resolver map. b.Scheme willbe used as the scheme registered with this builder. The registry is casesensitive, and schemes should not contain any uppercase characters.
NOTE: this function must only be called during initialization time (i.e. inan init() function), and is not thread-safe. If multiple Resolvers areregistered with the same name, the one registered last will take effect.
funcSetDefaultScheme¶
func SetDefaultScheme(schemestring)
SetDefaultScheme sets the default scheme that will be used. The defaultscheme is initially set to "passthrough".
NOTE: this function must only be called during initialization time (i.e. inan init() function), and is not thread-safe. The scheme set last overridespreviously set values.
funcValidateEndpoints¶added inv1.69.0
ValidateEndpoints validates endpoints from a petiole policy's perspective.Petiole policies should call this before calling into their children. See[gRPC A61](https://github.com/grpc/proposal/blob/master/A61-IPv4-IPv6-dualstack-backends.md)for details.
Types¶
typeAddress¶
type Address struct {// Addr is the server address on which a connection will be established.Addrstring// 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.//// 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.ServerNamestring// Attributes contains arbitrary data about this address intended for// consumption by the SubConn.Attributes *attributes.Attributes// BalancerAttributes contains arbitrary data about this address intended// for consumption by the LB policy. These attributes do not affect SubConn// creation, connection establishment, handshaking, etc.//// Deprecated: when an Address is inside an Endpoint, this field should not// be used, and it will eventually be removed entirely.BalancerAttributes *attributes.Attributes// Metadata is the information associated with Addr, which may be used// to make load balancing decision.//// Deprecated: use Attributes instead.Metadataany}Address represents a server the client connects to.
Experimental¶
Notice: This type is EXPERIMENTAL and may be changed or removed in alater release.
func (Address)Equal¶added inv1.42.0
Equal returns whether a and o are identical. Metadata is compared directly,not with any recursive introspection.
This method compares all fields of the address. When used to tell apartaddresses during subchannel creation or connection establishment, it might bemore appropriate for the caller to implement custom equality logic.
typeAddressMapdeprecatedadded inv1.42.0
type AddressMap =AddressMapV2[any]
AddressMap is an AddressMapV2[any]. It will be deleted in an upcomingrelease of grpc-go.
Deprecated: use the generic AddressMapV2 type instead.
funcNewAddressMapdeprecatedadded inv1.42.0
func NewAddressMap() *AddressMap
NewAddressMap creates a new AddressMapV2[any].
Deprecated: use the generic NewAddressMapV2 constructor instead.
typeAddressMapV2¶added inv1.72.0
type AddressMapV2[Tany] struct {// contains filtered or unexported fields}
AddressMapV2 is a map of addresses to arbitrary values taking into accountAttributes. BalancerAttributes are ignored, as are Metadata and Type.Multiple accesses may not be performed concurrently. Must be created viaNewAddressMap; do not construct directly.
funcNewAddressMapV2¶added inv1.72.0
func NewAddressMapV2[Tany]() *AddressMapV2[T]
NewAddressMapV2 creates a new AddressMapV2.
func (*AddressMapV2[T])Delete¶added inv1.72.0
func (a *AddressMapV2[T]) Delete(addrAddress)
Delete removes addr from the map.
func (*AddressMapV2[T])Get¶added inv1.72.0
func (a *AddressMapV2[T]) Get(addrAddress) (value T, okbool)
Get returns the value for the address in the map, if present.
func (*AddressMapV2[T])Keys¶added inv1.72.0
func (a *AddressMapV2[T]) Keys() []Address
Keys returns a slice of all current map keys.
func (*AddressMapV2[T])Len¶added inv1.72.0
func (a *AddressMapV2[T]) Len()int
Len returns the number of entries in the map.
func (*AddressMapV2[T])Set¶added inv1.72.0
func (a *AddressMapV2[T]) Set(addrAddress, value T)
Set updates or adds the value to the address in the map.
func (*AddressMapV2[T])Values¶added inv1.72.0
func (a *AddressMapV2[T]) Values() []T
Values returns a slice of all current map values.
typeAuthorityOverrider¶added inv1.61.0
type AuthorityOverrider interface {// OverrideAuthority returns the authority to use for a ClientConn with the// given target. The implementation must generate it without blocking,// typically in line, and must keep it unchanged.//// The returned string must be a valid ":authority" header value, i.e. be// encoded according to// [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2) as// necessary.OverrideAuthority(Target)string}AuthorityOverrider is implemented by Builders that wish to override thedefault authority for the ClientConn.By default, the authority used is target.Endpoint().
typeBuildOptions¶added inv1.26.0
type BuildOptions struct {// DisableServiceConfig indicates whether a resolver implementation should// fetch service config data.DisableServiceConfigbool// 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.DialCredscredentials.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.CredsBundlecredentials.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)// Authority is the effective authority of the clientconn for which the// resolver is built.Authoritystring// MetricsRecorder is the metrics recorder to do recording.MetricsRecorderstats.MetricsRecorder}BuildOptions includes additional information for the builder to createthe resolver.
typeBuilder¶
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(targetTarget, ccClientConn, optsBuildOptions) (Resolver,error)// Scheme returns the scheme supported by this resolver. Scheme is defined// athttps://github.com/grpc/grpc/blob/master/doc/naming.md. The returned// string should not contain uppercase characters, as they will not match// the parsed target's scheme as defined inRFC 3986.Scheme()string}Builder creates a resolver that will be used to watch name resolution updates.
typeClientConn¶
type ClientConn interface {// UpdateState updates the state of the ClientConn appropriately.//// If an error is returned, the resolver should try to resolve the// target again. The resolver should use a backoff timer to prevent// overloading the server with requests. If a resolver is certain that// reresolving will not change the result, e.g. because it is// a watch-based resolver, returned errors can be ignored.//// If the resolved State is the same as the last reported one, calling// UpdateState can be omitted.UpdateState(State)error// ReportError notifies the ClientConn that the Resolver encountered an// error. The ClientConn then forwards this error to the load balancing// policy.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)// ParseServiceConfig parses the provided service config and returns an// object that provides the parsed config.ParseServiceConfig(serviceConfigJSONstring) *serviceconfig.ParseResult}ClientConn contains the callbacks for resolver to notify any updatesto the gRPC ClientConn.
This interface is to be implemented by gRPC. Users should not need abrand new implementation of this interface. For the situations liketesting, the new implementation should embed this interface. This allowsgRPC to add new methods to this interface.
typeEndpoint¶added inv1.58.0
type Endpoint struct {// Addresses contains a list of addresses used to access this endpoint.Addresses []Address// Attributes contains arbitrary data about this endpoint intended for// consumption by the LB policy.Attributes *attributes.Attributes}An Endpoint is one network endpoint, or server, which may have multipleaddresses with which it can be accessed.
typeEndpointMap¶added inv1.60.0
type EndpointMap[Tany] struct {// contains filtered or unexported fields}
EndpointMap is a map of endpoints to arbitrary values keyed on only theunordered set of address strings within an endpoint. This map is not threadsafe, thus it is unsafe to access concurrently. Must be created viaNewEndpointMap; do not construct directly.
funcNewEndpointMap¶added inv1.60.0
func NewEndpointMap[Tany]() *EndpointMap[T]
NewEndpointMap creates a new EndpointMap.
func (*EndpointMap[T])Delete¶added inv1.60.0
func (em *EndpointMap[T]) Delete(eEndpoint)
Delete removes the specified endpoint from the map.
func (*EndpointMap[T])Get¶added inv1.60.0
func (em *EndpointMap[T]) Get(eEndpoint) (value T, okbool)
Get returns the value for the address in the map, if present.
func (*EndpointMap[T])Keys¶added inv1.60.0
func (em *EndpointMap[T]) Keys() []Endpoint
Keys returns a slice of all current map keys, as endpoints specifying theaddresses present in the endpoint keys, in which uniqueness is determined bythe unordered set of addresses. Thus, endpoint information returned is notthe full endpoint data (drops duplicated addresses and attributes) but can beused for EndpointMap accesses.
func (*EndpointMap[T])Len¶added inv1.60.0
func (em *EndpointMap[T]) Len()int
Len returns the number of entries in the map.
func (*EndpointMap[T])Set¶added inv1.60.0
func (em *EndpointMap[T]) Set(eEndpoint, value T)
Set updates or adds the value to the address in the map.
func (*EndpointMap[T])Values¶added inv1.60.0
func (em *EndpointMap[T]) Values() []T
Values returns a slice of all current map values.
typeResolveNowOptions¶added inv1.26.0
type ResolveNowOptions struct{}ResolveNowOptions includes additional information for ResolveNow.
typeResolver¶
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.
typeState¶added inv1.20.0
type State struct {// Addresses is the latest set of resolved addresses for the target.//// If a resolver sets Addresses but does not set Endpoints, one Endpoint// will be created for each Address before the State is passed to the LB// policy. The BalancerAttributes of each entry in Addresses will be set// in Endpoints.Attributes, and be cleared in the Endpoint's Address's// BalancerAttributes.//// Soon, Addresses will be deprecated and replaced fully by Endpoints.Addresses []Address// Endpoints is the latest set of resolved endpoints for the target.//// If a resolver produces a State containing Endpoints but not Addresses,// it must take care to ensure the LB policies it selects will support// Endpoints.Endpoints []Endpoint// 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.
typeTarget¶
type Target struct {// URL contains the parsed dial target with an optional default scheme added// to it if the original dial target contained no scheme or contained an// unregistered scheme. Any query params specified in the original dial// target can be accessed from here.URLurl.URL}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 DialContextby the user. And gRPC passes it to the resolver and the balancer.
If the target follows the naming spec, and the parsed scheme is registeredwith gRPC, we will parse the target string according to the spec. If thetarget does not contain a scheme or if the parsed scheme is not registered(i.e. no corresponding resolver available to resolve the endpoint), we willapply the default scheme, and will attempt to reparse it.
Source Files
Directories¶
| Path | Synopsis |
|---|---|
Package dns implements a dns resolver to be installed as the default resolver in grpc. | Package dns implements a dns resolver to be installed as the default resolver in grpc. |
Package manual defines a resolver that can be used to manually send resolved addresses to ClientConn. | Package manual defines a resolver that can be used to manually send resolved addresses to ClientConn. |
Package passthrough implements a pass-through resolver. | Package passthrough implements a pass-through resolver. |
Package ringhash implements resolver related functions for the ring_hash load balancing policy. | Package ringhash implements resolver related functions for the ring_hash load balancing policy. |