github.com/searKing/golang/go@v1.2.117/net/resolver/resolver.go (about)

     1  // Copyright 2021 The searKing Author. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package resolver
     6  
     7  import (
     8  	"context"
     9  	"errors"
    10  	"time"
    11  )
    12  
    13  // ErrBadResolverState may be returned by UpdateState to indicate a
    14  // problem with the provided name resolver data.
    15  var ErrBadResolverState = errors.New("bad resolver state")
    16  
    17  // Build includes additional information for the builder to create
    18  // the resolver.
    19  //
    20  //go:generate go-option -type "Build"
    21  type Build struct {
    22  	ClientConn ClientConn
    23  }
    24  
    25  // Builder is the interface that must be implemented by a database
    26  // driver.
    27  //
    28  // Database drivers may implement DriverContext for access
    29  // to contexts and to parse the name only once for a pool of connections,
    30  // instead of once per connection.
    31  type Builder interface {
    32  	// Build creates a new resolver for the given target.
    33  	//
    34  	// gRPC dial calls Build synchronously, and fails if the returned error is
    35  	// not nil.
    36  	Build(ctx context.Context, target Target, opts ...BuildOption) (Resolver, error)
    37  
    38  	// Scheme returns the scheme supported by this resolver.
    39  	// Scheme is defined at https://github.com/grpc/grpc/blob/master/doc/naming.md.
    40  	Scheme() string
    41  }
    42  
    43  // resolveOneAddr includes additional information for ResolveOneAddr.
    44  //
    45  //go:generate go-option -type "resolveOneAddr"
    46  type resolveOneAddr struct {
    47  	Picker []PickOption
    48  }
    49  
    50  // resolveAddr includes additional information for ResolveAddr.
    51  //
    52  //go:generate go-option -type "resolveAddr"
    53  type resolveAddr struct{}
    54  
    55  // resolveNow includes additional information for ResolveNow.
    56  //
    57  //go:generate go-option -type "resolveNow"
    58  type resolveNow struct{}
    59  
    60  // resolveDone includes additional information for ResolveDone.
    61  //
    62  //go:generate go-option -type "resolveDone"
    63  type resolveDone struct{}
    64  
    65  // Resolver watches for the updates on the specified target.
    66  // Updates include address updates and service config updates.
    67  type Resolver interface {
    68  	// ResolveOneAddr will be called to try to resolve the target name directly.
    69  	// resolver can not ignore this if it's not necessary.
    70  	// ResolveOneAddr may trigger and wait for ResolveNow if no addr in resolver cache
    71  	ResolveOneAddr(ctx context.Context, opts ...ResolveOneAddrOption) (Address, error)
    72  	// ResolveAddr will be called to try to resolve the target name directly.
    73  	// resolver can not ignore this if it's not necessary.
    74  	// ResolveAddr may trigger and wait for ResolveNow if no addr in resolver cache
    75  	ResolveAddr(ctx context.Context, opts ...ResolveAddrOption) ([]Address, error)
    76  	// ResolveNow will be called to try to resolve the target name
    77  	// again. It's just a hint, resolver can ignore this if it's not necessary.
    78  	//
    79  	// It could be called multiple times concurrently.
    80  	// It may trigger ClientConn to UpdateState or ReportError if failed.
    81  	// It may update cache used by ResolveOneAddr or ResolveAddr.
    82  	ResolveNow(ctx context.Context, opts ...ResolveNowOption)
    83  	// Close closes the resolver.
    84  	Close()
    85  }
    86  
    87  // ResolveDoneResolver extends Resolver with ResolveDone
    88  type ResolveDoneResolver interface {
    89  	Resolver
    90  	// ResolveDone will be called after the RPC finished.
    91  	// resolver can ignore this if it's not necessary.
    92  	ResolveDone(ctx context.Context, doneInfo DoneInfo, opts ...ResolveDoneOption)
    93  }
    94  
    95  // State contains the current Resolver state relevant to the ClientConn.
    96  type State struct {
    97  	// Addresses is the latest set of resolved addresses for the target.
    98  	Addresses []Address
    99  }
   100  
   101  // ClientConn contains the callbacks for resolver to notify any updates
   102  // to the gRPC ClientConn.
   103  //
   104  // This interface is to be implemented by gRPC. Users should not need a
   105  // brand new implementation of this interface. For the situations like
   106  // testing, the new implementation should embed this interface. This allows
   107  // gRPC to add new methods to this interface.
   108  type ClientConn interface {
   109  	// UpdateState updates the state of the ClientConn appropriately.
   110  	UpdateState(State) error
   111  	// ReportError notifies the ClientConn that the Resolver encountered an
   112  	// error.  The ClientConn will notify the load balancer and begin calling
   113  	// ResolveNow on the Resolver with exponential backoff.
   114  	ReportError(error)
   115  }
   116  
   117  // Address represents a server the client connects to.
   118  type Address struct {
   119  	// Addr is the server address on which a connection will be established.
   120  	Addr string
   121  
   122  	// ResolveLoad is the load received from resolver.
   123  	ResolveLoad any
   124  }
   125  
   126  // DoneInfo contains additional information for done.
   127  type DoneInfo struct {
   128  	// Err is the rpc error the RPC finished with. It could be nil.
   129  	// usually io.EOF represents server addr is resolved but unacceptable.
   130  	Err error
   131  
   132  	// Addr represents a server the client connects to.
   133  	Addr Address
   134  
   135  	Duration time.Duration
   136  }