go-micro.dev/v5@v5.12.0/client/client.go (about)

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