gitee.com/sasukebo/go-micro/v4@v4.7.1/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/sasukebo/go-micro/v4/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  	Closer
    68  	// Context for the stream
    69  	Context() context.Context
    70  	// The request made
    71  	Request() Request
    72  	// The response read
    73  	Response() Response
    74  	// Send will encode and send a request
    75  	Send(interface{}) error
    76  	// Recv will decode and read a response
    77  	Recv(interface{}) error
    78  	// Error returns the stream error
    79  	Error() error
    80  	// Close closes the stream
    81  	Close() error
    82  }
    83  
    84  // Closer handle client close
    85  type Closer interface {
    86  	// CloseSend closes the send direction of the stream.
    87  	CloseSend() error
    88  }
    89  
    90  // Option used by the Client
    91  type Option func(*Options)
    92  
    93  // CallOption used by Call or Stream
    94  type CallOption func(*CallOptions)
    95  
    96  // PublishOption used by Publish
    97  type PublishOption func(*PublishOptions)
    98  
    99  // MessageOption used by NewMessage
   100  type MessageOption func(*MessageOptions)
   101  
   102  // RequestOption used by NewRequest
   103  type RequestOption func(*RequestOptions)
   104  
   105  var (
   106  	// DefaultClient is a default client to use out of the box
   107  	DefaultClient Client = newRpcClient()
   108  	// DefaultBackoff is the default backoff function for retries
   109  	DefaultBackoff = exponentialBackoff
   110  	// DefaultRetry is the default check-for-retry function for retries
   111  	DefaultRetry = RetryOnError
   112  	// DefaultRetries is the default number of times a request is tried
   113  	DefaultRetries = 1
   114  	// DefaultRequestTimeout is the default request timeout
   115  	DefaultRequestTimeout = time.Second * 5
   116  	// DefaultPoolSize sets the connection pool size
   117  	DefaultPoolSize = 100
   118  	// DefaultPoolTTL sets the connection pool ttl
   119  	DefaultPoolTTL = time.Minute
   120  
   121  	// NewClient returns a new client
   122  	NewClient func(...Option) Client = newRpcClient
   123  )
   124  
   125  // Makes a synchronous call to a service using the default client
   126  func Call(ctx context.Context, request Request, response interface{}, opts ...CallOption) error {
   127  	return DefaultClient.Call(ctx, request, response, opts...)
   128  }
   129  
   130  // Publishes a publication using the default client. Using the underlying broker
   131  // set within the options.
   132  func Publish(ctx context.Context, msg Message, opts ...PublishOption) error {
   133  	return DefaultClient.Publish(ctx, msg, opts...)
   134  }
   135  
   136  // Creates a new message using the default client
   137  func NewMessage(topic string, payload interface{}, opts ...MessageOption) Message {
   138  	return DefaultClient.NewMessage(topic, payload, opts...)
   139  }
   140  
   141  // Creates a new request using the default client. Content Type will
   142  // be set to the default within options and use the appropriate codec
   143  func NewRequest(service, endpoint string, request interface{}, reqOpts ...RequestOption) Request {
   144  	return DefaultClient.NewRequest(service, endpoint, request, reqOpts...)
   145  }
   146  
   147  // Creates a streaming connection with a service and returns responses on the
   148  // channel passed in. It's up to the user to close the streamer.
   149  func NewStream(ctx context.Context, request Request, opts ...CallOption) (Stream, error) {
   150  	return DefaultClient.Stream(ctx, request, opts...)
   151  }
   152  
   153  func String() string {
   154  	return DefaultClient.String()
   155  }