Involved Source Filesmap.go Package resolver defines APIs for name resolution in gRPC.
All APIs in this package are experimental.
Package-Level Type Names (total 17, in which 13 are exported)
/* sort exporteds by: | */
Address represents a server the client connects to.
# Experimental
Notice: This type is EXPERIMENTAL and may be changed or removed in a
later release. Addr is the server address on which a connection will be established. Attributes contains arbitrary data about this address intended for
consumption by the SubConn. 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. Metadata is the information associated with Addr, which may be used
to make load balancing decision.
Deprecated: use Attributes instead. 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. 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 apart
addresses during subchannel creation or connection establishment, it might be
more appropriate for the caller to implement custom equality logic. String returns JSON formatted string representation of the address.
Address : expvar.Var
Address : fmt.Stringer
Address : context.stringer
Address : runtime.stringer
func (*AddressMapV2)[T].Keys() []Address
func google.golang.org/grpc/internal/metadata.Set(addr Address, md metadata.MD) Address
func google.golang.org/grpc/internal/proxyattributes.Set(addr Address, opts proxyattributes.Options) Address
func google.golang.org/grpc/internal/transport/networktype.Set(address Address, networkType string) Address
func toMapKey(addr *Address) Address
func google.golang.org/grpc.copyAddresses(in []Address) []Address
func google.golang.org/grpc/balancer.connectedAddress(scs balancer.SubConnState) Address
func google.golang.org/grpc/balancer/pickfirst/pickfirstleaf.deDupAddresses(addrs []Address) []Address
func google.golang.org/grpc/balancer/pickfirst/pickfirstleaf.interleaveAddresses(addrs []Address) []Address
func Address.Equal(o Address) bool
func (*AddressMapV2)[T].Delete(addr Address)
func (*AddressMapV2)[T].Get(addr Address) (value T, ok bool)
func (*AddressMapV2)[T].Set(addr Address, value T)
func ClientConn.NewAddress(addresses []Address)
func google.golang.org/grpc/balancer.ClientConn.NewSubConn([]Address, balancer.NewSubConnOptions) (balancer.SubConn, error)
func google.golang.org/grpc/balancer.ClientConn.UpdateAddresses(balancer.SubConn, []Address)
func google.golang.org/grpc/balancer.SubConn.UpdateAddresses([]Address)
func google.golang.org/grpc/internal/metadata.Get(addr Address) metadata.MD
func google.golang.org/grpc/internal/metadata.Set(addr Address, md metadata.MD) Address
func google.golang.org/grpc/internal/proxyattributes.Get(addr Address) (proxyattributes.Options, bool)
func google.golang.org/grpc/internal/proxyattributes.Set(addr Address, opts proxyattributes.Options) Address
func google.golang.org/grpc/internal/transport.NewHTTP2Client(connectCtx, ctx context.Context, addr Address, opts transport.ConnectOptions, onClose func(transport.GoAwayReason)) (_ transport.ClientTransport, err error)
func google.golang.org/grpc/internal/transport/networktype.Get(address Address) (string, bool)
func google.golang.org/grpc/internal/transport/networktype.Set(address Address, networkType string) Address
func toMapKey(addr *Address) Address
func google.golang.org/grpc.addressesToEndpoints(addrs []Address) []Endpoint
func google.golang.org/grpc.copyAddresses(in []Address) []Address
func google.golang.org/grpc.equalAddressesIgnoringBalAttributes(a, b []Address) bool
func google.golang.org/grpc.equalAddressIgnoringBalAttributes(a, b *Address) bool
func google.golang.org/grpc.(*ClientConn).getServerName(addr Address) string
func google.golang.org/grpc.(*ClientConn).newAddrConnLocked(addrs []Address, opts balancer.NewSubConnOptions) (*grpc.addrConn, error)
func google.golang.org/grpc/balancer.setConnectedAddress(scs *balancer.SubConnState, addr Address)
func google.golang.org/grpc/balancer/pickfirst/pickfirstleaf.deDupAddresses(addrs []Address) []Address
func google.golang.org/grpc/balancer/pickfirst/pickfirstleaf.equalAddressIgnoringBalAttributes(a, b *Address) bool
func google.golang.org/grpc/balancer/pickfirst/pickfirstleaf.interleaveAddresses(addrs []Address) []Address
func google.golang.org/grpc/internal/resolver/delegatingresolver.skipProxy(address Address) bool
func google.golang.org/grpc/internal/transport.dial(ctx context.Context, fn func(context.Context, string) (net.Conn, error), addr Address, grpcUA string) (net.Conn, error)
func google.golang.org/grpc/internal/transport.proxyDial(ctx context.Context, addr Address, grpcUA string, opts proxyattributes.Options) (net.Conn, error)
AddressMap is an AddressMapV2[any]. It will be deleted in an upcoming
release of grpc-go.
Deprecated: use the generic AddressMapV2 type instead.
Type Parameters:
T: any AddressMapV2 is a map of addresses to arbitrary values taking into account
Attributes. BalancerAttributes are ignored, as are Metadata and Type.
Multiple accesses may not be performed concurrently. Must be created via
NewAddressMap; do not construct directly. The underlying map is keyed by an Address with fields that we don't care
about being set to their zero values. The only fields that we care about
are `Addr`, `ServerName` and `Attributes`. Since we need to be able to
distinguish between addresses with same `Addr` and `ServerName`, but
different `Attributes`, we cannot store the `Attributes` in the map key.
The comparison operation for structs work as follows:
Struct values are comparable if all their fields are comparable. Two
struct values are equal if their corresponding non-blank fields are equal.
The value type of the map contains a slice of addresses which match the key
in their `Addr` and `ServerName` fields and contain the corresponding value
associated with them. Delete removes addr from the map. Get returns the value for the address in the map, if present. Keys returns a slice of all current map keys. Len returns the number of entries in the map. Set updates or adds the value to the address in the map. Values returns a slice of all current map values.
func NewAddressMap() *AddressMap
func NewAddressMapV2[T]() *AddressMapV2[T]
AuthorityOverrider is implemented by Builders that wish to override the
default authority for the ClientConn.
By default, the authority used is target.Endpoint(). 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.
*google.golang.org/grpc/internal/resolver/unix.builder
Builder creates a resolver that will be used to watch name resolution updates. Build creates a new resolver for the given target.
gRPC dial calls Build synchronously, and fails if the returned error is
not nil. Scheme returns the scheme supported by this resolver. Scheme is defined
at https://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 in RFC 3986.
*google.golang.org/grpc/internal/resolver/dns.dnsBuilder
*google.golang.org/grpc/internal/resolver/passthrough.passthroughBuilder
*google.golang.org/grpc/internal/resolver/unix.builder
func Get(scheme string) Builder
func google.golang.org/grpc/resolver/dns.NewBuilder() Builder
func google.golang.org/grpc/internal/resolver/dns.NewBuilder() Builder
func google.golang.org/grpc.(*ClientConn).getResolver(scheme string) Builder
func Register(b Builder)
func google.golang.org/grpc.WithResolvers(rs ...Builder) grpc.DialOption
func google.golang.org/grpc/internal/resolver/delegatingresolver.New(target Target, cc ClientConn, opts BuildOptions, targetResolverBuilder Builder, targetResolutionEnabled bool) (Resolver, error)
BuildOptions includes additional information for the builder to create
the resolver. Authority is the effective authority of the clientconn for which the
resolver is built. 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. 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. 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. DisableServiceConfig indicates whether a resolver implementation should
fetch service config data. MetricsRecorder is the metrics recorder to do recording.
func Builder.Build(target Target, cc ClientConn, opts BuildOptions) (Resolver, error)
func google.golang.org/grpc/internal/resolver/delegatingresolver.New(target Target, cc ClientConn, opts BuildOptions, targetResolverBuilder Builder, targetResolutionEnabled bool) (Resolver, error)
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. 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. ParseServiceConfig parses the provided service config and returns an
object that provides the parsed config. ReportError notifies the ClientConn that the Resolver encountered an
error. The ClientConn then forwards this error to the load balancing
policy. 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.
*google.golang.org/grpc.ccResolverWrapper
*google.golang.org/grpc/internal/resolver/delegatingresolver.wrappingClientConn
func Builder.Build(target Target, cc ClientConn, opts BuildOptions) (Resolver, error)
func google.golang.org/grpc/internal/resolver/delegatingresolver.New(target Target, cc ClientConn, opts BuildOptions, targetResolverBuilder Builder, targetResolutionEnabled bool) (Resolver, error)
An Endpoint is one network endpoint, or server, which may have multiple
addresses with which it can be accessed. Addresses contains a list of addresses used to access this endpoint. Attributes contains arbitrary data about this endpoint intended for
consumption by the LB policy.
func (*EndpointMap)[T].Keys() []Endpoint
func google.golang.org/grpc.addressesToEndpoints(addrs []Address) []Endpoint
func google.golang.org/grpc/balancer/endpointsharding.rotateEndpoints(es []Endpoint) []Endpoint
func ValidateEndpoints(endpoints []Endpoint) error
func (*EndpointMap)[T].Delete(e Endpoint)
func (*EndpointMap)[T].Get(e Endpoint) (value T, ok bool)
func (*EndpointMap)[T].Set(e Endpoint, value T)
func encodeEndpoint(e Endpoint) endpointMapKey
func google.golang.org/grpc/balancer/endpointsharding.rotateEndpoints(es []Endpoint) []Endpoint
Type Parameters:
T: any EndpointMap is a map of endpoints to arbitrary values keyed on only the
unordered set of address strings within an endpoint. This map is not thread
safe, thus it is unsafe to access concurrently. Must be created via
NewEndpointMap; do not construct directly.endpointsmap[endpointMapKey]endpointData[T] Delete removes the specified endpoint from the map. Get returns the value for the address in the map, if present. Keys returns a slice of all current map keys, as endpoints specifying the
addresses present in the endpoint keys, in which uniqueness is determined by
the unordered set of addresses. Thus, endpoint information returned is not
the full endpoint data (drops duplicated addresses and attributes) but can be
used for EndpointMap accesses. Len returns the number of entries in the map. Set updates or adds the value to the address in the map. Values returns a slice of all current map values.
func NewEndpointMap[T]() *EndpointMap[T]
ResolveNowOptions includes additional information for ResolveNow.
func Resolver.ResolveNow(ResolveNowOptions)
func google.golang.org/grpc/balancer.ClientConn.ResolveNow(ResolveNowOptions)
func google.golang.org/grpc.(*ClientConn).resolveNow(o ResolveNowOptions)
func google.golang.org/grpc.(*ClientConn).resolveNowLocked(o ResolveNowOptions)
Resolver watches for the updates on the specified target.
Updates include address updates and service config updates. Close closes the resolver. 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.
*google.golang.org/grpc/internal/balancer/gracefulswitch.balancerWrapper
*google.golang.org/grpc/internal/resolver/delegatingresolver.delegatingResolver
google.golang.org/grpc/internal/resolver/delegatingresolver.nopResolver
google.golang.org/grpc/internal/resolver/dns.deadResolver
*google.golang.org/grpc/internal/resolver/dns.dnsResolver
*google.golang.org/grpc/internal/resolver/passthrough.passthroughResolver
*google.golang.org/grpc/internal/resolver/unix.nopResolver
func Builder.Build(target Target, cc ClientConn, opts BuildOptions) (Resolver, error)
func google.golang.org/grpc/internal/resolver/delegatingresolver.New(target Target, cc ClientConn, opts BuildOptions, targetResolverBuilder Builder, targetResolutionEnabled bool) (Resolver, error)
State contains the current Resolver state relevant to the ClientConn. 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. Attributes contains arbitrary data about the resolver intended for
consumption by the load balancing policy. 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. 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.
func google.golang.org/grpc/balancer/grpclb/state.Set(state State, s *state.State) State
func google.golang.org/grpc/balancer/pickfirst/pickfirstleaf.EnableHealthListener(state State) State
func google.golang.org/grpc/internal/resolver.SetConfigSelector(state State, cs resolver.ConfigSelector) State
func ClientConn.UpdateState(State) error
func google.golang.org/grpc/balancer/grpclb/state.Get(state State) *state.State
func google.golang.org/grpc/balancer/grpclb/state.Set(state State, s *state.State) State
func google.golang.org/grpc/balancer/pickfirst/pickfirstleaf.EnableHealthListener(state State) State
func google.golang.org/grpc/internal/resolver.GetConfigSelector(state State) resolver.ConfigSelector
func google.golang.org/grpc/internal/resolver.SetConfigSelector(state State, cs resolver.ConfigSelector) State
func google.golang.org/grpc.(*ClientConn).updateResolverStateAndUnlock(s State, err error) error
func google.golang.org/grpc/internal/resolver/delegatingresolver.needsProxyResolver(state *State) bool
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. If the
target does not contain a scheme or if the parsed scheme is not registered
(i.e. no corresponding resolver available to resolve the endpoint), we will
apply the default scheme, and will attempt to reparse it. 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. Endpoint retrieves endpoint without leading "/" from either `URL.Path`
or `URL.Opaque`. The latter is used when the former is empty. String returns the canonical string representation of Target.
Target : expvar.Var
Target : fmt.Stringer
Target : context.stringer
Target : runtime.stringer
func google.golang.org/grpc.parseTarget(target string) (Target, error)
func AuthorityOverrider.OverrideAuthority(Target) string
func Builder.Build(target Target, cc ClientConn, opts BuildOptions) (Resolver, error)
func google.golang.org/grpc/internal/resolver/delegatingresolver.New(target Target, cc ClientConn, opts BuildOptions, targetResolverBuilder Builder, targetResolutionEnabled bool) (Resolver, error)
Package-Level Functions (total 10, in which 8 are exported)
Get returns the resolver builder registered with the given scheme.
If no builder is register with the scheme, nil will be returned.
GetDefaultScheme gets the default scheme that will be used by grpc.Dial. If
SetDefaultScheme is never called, the default scheme used by grpc.NewClient is "dns" instead.
NewAddressMap creates a new AddressMapV2[any].
Deprecated: use the generic NewAddressMapV2 constructor instead.
Type Parameters:
T: any NewAddressMapV2 creates a new AddressMapV2.
Type Parameters:
T: any NewEndpointMap creates a new EndpointMap.
Register registers the resolver builder to the resolver map. b.Scheme will
be used as the scheme registered with this builder. The registry is case
sensitive, and schemes should not contain any uppercase characters.
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.
SetDefaultScheme sets the default scheme that will be used. The default
scheme is initially set to "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.
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.
encodeEndpoint returns a string that uniquely identifies the unordered set of
addresses within an endpoint.