gitee.com/liuxuezhan/go-micro-v1.18.0@v1.0.0/client/client.go (about)

     1  // Package client is an interface for an RPC client
     2  package client
     3  
     4  import (
     5  	"context"
     6  	"time"
     7  
     8  	"gitee.com/liuxuezhan/go-micro-v1.18.0/codec"
     9  )
    10  
    11  // Client is the interface used to make requests to services.
    12  // It supports Request/Response via Transport and Publishing via the Broker.
    13  // It also supports bidirectional streaming of requests.
    14  type Client interface {
    15  	Init(...Option) error
    16  	Options() Options
    17  	NewMessage(topic string, msg interface{}, opts ...MessageOption) Message
    18  	NewRequest(service, endpoint string, req interface{}, reqOpts ...RequestOption) Request
    19  	Call(ctx context.Context, req Request, rsp interface{}, opts ...CallOption) error
    20  	Stream(ctx context.Context, req Request, opts ...CallOption) (Stream, error)
    21  	Publish(ctx context.Context, msg Message, opts ...PublishOption) error
    22  	String() string
    23  }
    24  
    25  // Router manages request routing
    26  type Router interface {
    27  	SendRequest(context.Context, Request) (Response, error)
    28  }
    29  
    30  // Message is the interface for publishing asynchronously
    31  type Message interface {
    32  	Topic() string
    33  	Payload() interface{}
    34  	ContentType() string
    35  }
    36  
    37  // Request is the interface for a synchronous request used by Call or Stream
    38  type Request interface {
    39  	// The service to call
    40  	Service() string
    41  	// The action to take
    42  	Method() string
    43  	// The endpoint to invoke
    44  	Endpoint() string
    45  	// The content type
    46  	ContentType() string
    47  	// The unencoded request body
    48  	Body() interface{}
    49  	// Write to the encoded request writer. This is nil before a call is made
    50  	Codec() codec.Writer
    51  	// indicates whether the request will be a streaming one rather than unary
    52  	Stream() bool
    53  }
    54  
    55  // Response is the response received from a service
    56  type Response interface {
    57  	// Read the response
    58  	Codec() codec.Reader
    59  	// read the header
    60  	Header() map[string]string
    61  	// Read the undecoded response
    62  	Read() ([]byte, error)
    63  }
    64  
    65  // Stream is the inteface for a bidirectional synchronous stream
    66  type Stream interface {
    67  	// Context for the stream
    68  	Context() context.Context
    69  	// The request made
    70  	Request() Request
    71  	// The response read
    72  	Response() Response
    73  	// Send will encode and send a request
    74  	Send(interface{}) error
    75  	// Recv will decode and read a response
    76  	Recv(interface{}) error
    77  	// Error returns the stream error
    78  	Error() error
    79  	// Close closes the stream
    80  	Close() error
    81  }
    82  
    83  // Option used by the Client
    84  type Option func(*Options)
    85  
    86  // CallOption used by Call or Stream
    87  type CallOption func(*CallOptions)
    88  
    89  // PublishOption used by Publish
    90  type PublishOption func(*PublishOptions)
    91  
    92  // MessageOption used by NewMessage
    93  type MessageOption func(*MessageOptions)
    94  
    95  // RequestOption used by NewRequest
    96  type RequestOption func(*RequestOptions)
    97  
    98  var (
    99  	// DefaultClient is a default client to use out of the box
   100  	DefaultClient Client = newRpcClient()
   101  	// DefaultBackoff is the default backoff function for retries
   102  	DefaultBackoff = exponentialBackoff
   103  	// DefaultRetry is the default check-for-retry function for retries
   104  	DefaultRetry = RetryOnError
   105  	// DefaultRetries is the default number of times a request is tried
   106  	DefaultRetries = 1
   107  	// DefaultRequestTimeout is the default request timeout
   108  	DefaultRequestTimeout = time.Second * 5
   109  	// DefaultPoolSize sets the connection pool size
   110  	DefaultPoolSize = 100
   111  	// DefaultPoolTTL sets the connection pool ttl
   112  	DefaultPoolTTL = time.Minute
   113  )
   114  
   115  // Makes a synchronous call to a service using the default client
   116  func Call(ctx context.Context, request Request, response interface{}, opts ...CallOption) error {
   117  	return DefaultClient.Call(ctx, request, response, opts...)
   118  }
   119  
   120  // Publishes a publication using the default client. Using the underlying broker
   121  // set within the options.
   122  func Publish(ctx context.Context, msg Message, opts ...PublishOption) error {
   123  	return DefaultClient.Publish(ctx, msg, opts...)
   124  }
   125  
   126  // Creates a new message using the default client
   127  func NewMessage(topic string, payload interface{}, opts ...MessageOption) Message {
   128  	return DefaultClient.NewMessage(topic, payload, opts...)
   129  }
   130  
   131  // Creates a new client with the options passed in
   132  func NewClient(opt ...Option) Client {
   133  	return newRpcClient(opt...)
   134  }
   135  
   136  // Creates a new request using the default client. Content Type will
   137  // be set to the default within options and use the appropriate codec
   138  func NewRequest(service, endpoint string, request interface{}, reqOpts ...RequestOption) Request {
   139  	return DefaultClient.NewRequest(service, endpoint, request, reqOpts...)
   140  }
   141  
   142  // Creates a streaming connection with a service and returns responses on the
   143  // channel passed in. It's up to the user to close the streamer.
   144  func NewStream(ctx context.Context, request Request, opts ...CallOption) (Stream, error) {
   145  	return DefaultClient.Stream(ctx, request, opts...)
   146  }
   147  
   148  func String() string {
   149  	return DefaultClient.String()
   150  }