micro/client/client.go

151 lines
4.6 KiB
Go
Raw Normal View History

2016-12-14 18:41:48 +03:00
// Package client is an interface for an RPC client
2015-01-14 02:31:27 +03:00
package client
2015-05-21 21:24:57 +03:00
import (
2018-03-03 14:53:52 +03:00
"context"
2016-01-04 00:14:33 +03:00
"time"
2019-01-10 14:39:39 +03:00
"github.com/micro/go-micro/codec"
2015-05-21 21:24:57 +03:00
)
2016-01-31 00:15:08 +03:00
// Client is the interface used to make requests to services.
// It supports Request/Response via Transport and Publishing via the Broker.
2019-07-22 10:41:14 +03:00
// It also supports bidirectional streaming of requests.
2015-01-14 02:31:27 +03:00
type Client interface {
2016-01-02 22:12:17 +03:00
Init(...Option) error
Options() Options
2018-05-10 19:33:54 +03:00
NewMessage(topic string, msg interface{}, opts ...MessageOption) Message
2019-01-11 00:25:31 +03:00
NewRequest(service, endpoint string, req interface{}, reqOpts ...RequestOption) Request
2015-12-08 22:25:42 +03:00
Call(ctx context.Context, req Request, rsp interface{}, opts ...CallOption) error
2018-04-14 20:15:09 +03:00
Stream(ctx context.Context, req Request, opts ...CallOption) (Stream, error)
2018-04-14 20:06:52 +03:00
Publish(ctx context.Context, msg Message, opts ...PublishOption) error
2015-12-20 00:56:14 +03:00
String() string
}
2019-01-10 14:39:39 +03:00
// Router manages request routing
type Router interface {
SendRequest(context.Context, Request) (Response, error)
}
2018-04-14 20:06:52 +03:00
// Message is the interface for publishing asynchronously
type Message interface {
Topic() string
2018-04-14 20:06:52 +03:00
Payload() interface{}
ContentType() string
}
2016-04-06 19:53:16 +03:00
// Request is the interface for a synchronous request used by Call or Stream
type Request interface {
2019-01-10 14:39:39 +03:00
// The service to call
Service() string
2019-01-18 13:12:57 +03:00
// The action to take
Method() string
// The endpoint to invoke
2019-01-11 00:25:31 +03:00
Endpoint() string
2019-01-10 14:39:39 +03:00
// The content type
ContentType() string
2019-01-10 14:39:39 +03:00
// The unencoded request body
Body() interface{}
// Write to the encoded request writer. This is nil before a call is made
Codec() codec.Writer
2015-12-17 23:37:35 +03:00
// indicates whether the request will be a streaming one rather than unary
Stream() bool
}
2019-01-10 14:39:39 +03:00
// Response is the response received from a service
type Response interface {
// Read the response
Codec() codec.Reader
// read the header
Header() map[string]string
// Read the undecoded response
Read() ([]byte, error)
}
2018-04-14 20:15:09 +03:00
// Stream is the inteface for a bidirectional synchronous stream
type Stream interface {
2019-01-15 00:30:43 +03:00
// Context for the stream
2015-12-17 23:37:35 +03:00
Context() context.Context
2019-01-15 00:30:43 +03:00
// The request made
Request() Request
2019-01-15 00:30:43 +03:00
// The response read
Response() Response
// Send will encode and send a request
2015-12-17 23:37:35 +03:00
Send(interface{}) error
2019-01-15 00:30:43 +03:00
// Recv will decode and read a response
2015-12-17 23:37:35 +03:00
Recv(interface{}) error
2019-01-15 00:30:43 +03:00
// Error returns the stream error
Error() error
2019-01-15 00:30:43 +03:00
// Close closes the stream
Close() error
2015-01-14 02:31:27 +03:00
}
2016-04-06 19:53:16 +03:00
// Option used by the Client
type Option func(*Options)
2016-04-06 19:53:16 +03:00
// CallOption used by Call or Stream
type CallOption func(*CallOptions)
2016-04-06 19:53:16 +03:00
// PublishOption used by Publish
type PublishOption func(*PublishOptions)
2016-04-06 19:53:16 +03:00
2018-05-10 19:33:54 +03:00
// MessageOption used by NewMessage
type MessageOption func(*MessageOptions)
2016-04-06 19:53:16 +03:00
// RequestOption used by NewRequest
type RequestOption func(*RequestOptions)
2015-05-21 21:24:57 +03:00
2015-01-14 02:31:27 +03:00
var (
2016-04-06 19:53:16 +03:00
// DefaultClient is a default client to use out of the box
2015-05-23 19:40:53 +03:00
DefaultClient Client = newRpcClient()
2016-04-06 19:53:16 +03:00
// DefaultBackoff is the default backoff function for retries
DefaultBackoff = exponentialBackoff
2016-11-07 11:40:11 +03:00
// DefaultRetry is the default check-for-retry function for retries
DefaultRetry = RetryOnError
2016-04-06 19:53:16 +03:00
// DefaultRetries is the default number of times a request is tried
DefaultRetries = 1
// DefaultRequestTimeout is the default request timeout
2016-01-04 00:14:33 +03:00
DefaultRequestTimeout = time.Second * 5
2016-06-07 02:46:14 +03:00
// DefaultPoolSize sets the connection pool size
2019-01-16 21:54:32 +03:00
DefaultPoolSize = 100
2016-06-07 02:46:14 +03:00
// DefaultPoolTTL sets the connection pool ttl
DefaultPoolTTL = time.Minute
2015-01-14 02:31:27 +03:00
)
2018-04-17 13:00:22 +03:00
// Makes a synchronous call to a service using the default client
func Call(ctx context.Context, request Request, response interface{}, opts ...CallOption) error {
return DefaultClient.Call(ctx, request, response, opts...)
}
// Publishes a publication using the default client. Using the underlying broker
// set within the options.
2018-05-10 19:33:54 +03:00
func Publish(ctx context.Context, msg Message, opts ...PublishOption) error {
return DefaultClient.Publish(ctx, msg, opts...)
2018-04-17 13:00:22 +03:00
}
// Creates a new message using the default client
2018-05-10 19:33:54 +03:00
func NewMessage(topic string, payload interface{}, opts ...MessageOption) Message {
return DefaultClient.NewMessage(topic, payload, opts...)
2018-04-17 13:00:22 +03:00
}
2015-11-26 15:21:00 +03:00
// Creates a new client with the options passed in
func NewClient(opt ...Option) Client {
2015-05-23 19:40:53 +03:00
return newRpcClient(opt...)
}
2018-04-17 13:00:22 +03:00
// Creates a new request using the default client. Content Type will
// be set to the default within options and use the appropriate codec
2019-01-11 00:25:31 +03:00
func NewRequest(service, endpoint string, request interface{}, reqOpts ...RequestOption) Request {
return DefaultClient.NewRequest(service, endpoint, request, reqOpts...)
2018-04-17 13:00:22 +03:00
}
// Creates a streaming connection with a service and returns responses on the
// channel passed in. It's up to the user to close the streamer.
func NewStream(ctx context.Context, request Request, opts ...CallOption) (Stream, error) {
return DefaultClient.Stream(ctx, request, opts...)
}
func String() string {
return DefaultClient.String()
}