Documentation ¶
Overview ¶
Package grpc implements an RPC system called gRPC.
See grpc.io for more information about gRPC.
Index ¶
- Constants
- Variables
- func Code(err error) codes.Codedeprecated
- func ErrorDesc(err error) stringdeprecated
- func Errorf(c codes.Code, format string, a ...interface{}) errordeprecated
- func Invoke(ctx context.Context, method string, args, reply interface{}, cc *ClientConn, ...) error
- func Method(ctx context.Context) (string, bool)
- func MethodFromServerStream(stream ServerStream) (string, bool)
- func NewContextWithServerTransportStream(ctx context.Context, stream ServerTransportStream) context.Context
- func RegisterChannelz()
- func SendHeader(ctx context.Context, md metadata.MD) error
- func SetHeader(ctx context.Context, md metadata.MD) error
- func SetTrailer(ctx context.Context, md metadata.MD) error
- type Addressdeprecated
- type BackoffConfig
- type Balancerdeprecated
- type BalancerConfigdeprecated
- type BalancerGetOptionsdeprecated
- type CallOption
- func CallContentSubtype(contentSubtype string) CallOption
- func CallCustomCodec(codec Codec) CallOption
- func FailFast(failFast bool) CallOption
- func Header(md *metadata.MD) CallOption
- func MaxCallRecvMsgSize(s int) CallOption
- func MaxCallSendMsgSize(s int) CallOption
- func MaxRetryRPCBufferSize(bytes int) CallOption
- func Peer(p *peer.Peer) CallOption
- func PerRPCCredentials(creds credentials.PerRPCCredentials) CallOption
- func Trailer(md *metadata.MD) CallOption
- func UseCompressor(name string) CallOption
- type ClientConn
- func (cc *ClientConn) ChannelzMetric() *channelz.ChannelInternalMetric
- func (cc *ClientConn) Close() error
- func (cc *ClientConn) GetMethodConfig(method string) MethodConfig
- func (cc *ClientConn) GetState() connectivity.State
- func (cc *ClientConn) Invoke(ctx context.Context, method string, args, reply interface{}, ...) error
- func (cc *ClientConn) NewStream(ctx context.Context, desc *StreamDesc, method string, opts ...CallOption) (ClientStream, error)
- func (cc *ClientConn) Target() string
- func (cc *ClientConn) WaitForStateChange(ctx context.Context, sourceState connectivity.State) bool
- type ClientStream
- type Codecdeprecated
- type Compressordeprecated
- type CompressorCallOption
- type ContentSubtypeCallOption
- type CustomCodecCallOption
- type Decompressordeprecated
- func NewGZIPDecompressor() Decompressordeprecated
- type DialOption
- func FailOnNonTempDialError(f bool) DialOption
- func WithAuthority(a string) DialOption
- func WithBackoffConfig(b BackoffConfig) DialOption
- func WithBackoffMaxDelay(md time.Duration) DialOption
- func WithBalancer(b Balancer) DialOptiondeprecated
- func WithBalancerName(balancerName string) DialOption
- func WithBlock() DialOption
- func WithChannelzParentID(id int64) DialOption
- func WithCodec(c Codec) DialOptiondeprecated
- func WithCompressor(cp Compressor) DialOptiondeprecated
- func WithDecompressor(dc Decompressor) DialOptiondeprecated
- func WithDefaultCallOptions(cos ...CallOption) DialOption
- func WithDialer(f func(string, time.Duration) (net.Conn, error)) DialOption
- func WithDisableRetry() DialOption
- func WithDisableServiceConfig() DialOption
- func WithInitialConnWindowSize(s int32) DialOption
- func WithInitialWindowSize(s int32) DialOption
- func WithInsecure() DialOption
- func WithKeepaliveParams(kp keepalive.ClientParameters) DialOption
- func WithMaxHeaderListSize(s uint32) DialOption
- func WithMaxMsgSize(s int) DialOptiondeprecated
- func WithPerRPCCredentials(creds credentials.PerRPCCredentials) DialOption
- func WithReadBufferSize(s int) DialOption
- func WithServiceConfig(c <-chan ServiceConfig) DialOptiondeprecated
- func WithStatsHandler(h stats.Handler) DialOption
- func WithStreamInterceptor(f StreamClientInterceptor) DialOption
- func WithTimeout(d time.Duration) DialOptiondeprecated
- func WithTransportCredentials(creds credentials.TransportCredentials) DialOption
- func WithUnaryInterceptor(f UnaryClientInterceptor) DialOption
- func WithUserAgent(s string) DialOption
- func WithWaitForHandshake() DialOption
- func WithWriteBufferSize(s int) DialOption
- type EmptyCallOption
- type EmptyDialOption
- type FailFastCallOption
- type HeaderCallOption
- type MaxRecvMsgSizeCallOption
- type MaxRetryRPCBufferSizeCallOption
- type MaxSendMsgSizeCallOption
- type MethodConfigdeprecated
- type MethodDesc
- type MethodInfo
- type PeerCallOption
- type PerRPCCredsCallOption
- type Server
- func (s *Server) ChannelzMetric() *channelz.ServerInternalMetric
- func (s *Server) GetServiceInfo() map[string]ServiceInfo
- func (s *Server) GracefulStop()
- func (s *Server) RegisterService(sd *ServiceDesc, ss interface{})
- func (s *Server) Serve(lis net.Listener) error
- func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (s *Server) Stop()
- type ServerOption
- func ConnectionTimeout(d time.Duration) ServerOption
- func Creds(c credentials.TransportCredentials) ServerOption
- func CustomCodec(codec Codec) ServerOption
- func InTapHandle(h tap.ServerInHandle) ServerOption
- func InitialConnWindowSize(s int32) ServerOption
- func InitialWindowSize(s int32) ServerOption
- func KeepaliveEnforcementPolicy(kep keepalive.EnforcementPolicy) ServerOption
- func KeepaliveParams(kp keepalive.ServerParameters) ServerOption
- func MaxConcurrentStreams(n uint32) ServerOption
- func MaxHeaderListSize(s uint32) ServerOption
- func MaxMsgSize(m int) ServerOptiondeprecated
- func MaxRecvMsgSize(m int) ServerOption
- func MaxSendMsgSize(m int) ServerOption
- func RPCCompressor(cp Compressor) ServerOptiondeprecated
- func RPCDecompressor(dc Decompressor) ServerOptiondeprecated
- func ReadBufferSize(s int) ServerOption
- func StatsHandler(h stats.Handler) ServerOption
- func StreamInterceptor(i StreamServerInterceptor) ServerOption
- func UnaryInterceptor(i UnaryServerInterceptor) ServerOption
- func UnknownServiceHandler(streamHandler StreamHandler) ServerOption
- func WriteBufferSize(s int) ServerOption
- type ServerStream
- type ServerTransportStream
- type ServiceConfigdeprecated
- type ServiceDesc
- type ServiceInfo
- type Streamdeprecated
- type StreamClientInterceptor
- type StreamDesc
- type StreamHandler
- type StreamServerInfo
- type StreamServerInterceptor
- type Streamer
- type TrailerCallOption
- type UnaryClientInterceptor
- type UnaryHandler
- type UnaryInvoker
- type UnaryServerInfo
- type UnaryServerInterceptor
Constants ¶
const ( SupportPackageIsVersion3 = true SupportPackageIsVersion4 = true SupportPackageIsVersion5 = true )
The SupportPackageIsVersion variables are referenced from generated protocol buffer files to ensure compatibility with the gRPC version used. The latest support package version is 5.
Older versions are kept for compatibility. They may be removed if compatibility cannot be maintained.
These constants should not be referenced from any other code.
const PickFirstBalancerName = "pick_first"
PickFirstBalancerName is the name of the pick_first balancer.
const Version = "1.14.0"
Version is the current grpc version.
Variables ¶
var DefaultBackoffConfig = BackoffConfig{ MaxDelay: 120 * time.Second, }
DefaultBackoffConfig uses values specified for backoff in https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md.
var EnableTracing bool
EnableTracing controls whether to trace RPCs using the golang.org/x/net/trace package. This should only be set before any RPCs are sent or received by this program.
var ( // ErrClientConnClosing indicates that the operation is illegal because // the ClientConn is closing. // // Deprecated: this error should not be relied upon by users; use the status // code of Canceled instead. ErrClientConnClosing = status.Error(codes.Canceled, "grpc: the client connection is closing") )
var ErrClientConnTimeout = errors.New("grpc: timed out when dialing")
ErrClientConnTimeout indicates that the ClientConn cannot establish the underlying connections within the specified timeout.
Deprecated: This error is never returned by grpc and should not be referenced by users.
var ErrServerStopped = errors.New("grpc: the server has been stopped")
ErrServerStopped indicates that the operation is now illegal because of the server being stopped.
Functions ¶
func Invoke ¶
func Invoke(ctx context.Context, method string, args, reply interface{}, cc *ClientConn, opts ...CallOption) error
Invoke sends the RPC request on the wire and returns after response is received. This is typically called by generated code.
DEPRECATED: Use ClientConn.Invoke instead.
func Method ¶ added in v1.11.2
Method returns the method string for the server context. The returned string is in the format of "/service/method".
func MethodFromServerStream ¶ added in v1.8.0
func MethodFromServerStream(stream ServerStream) (string, bool)
MethodFromServerStream returns the method string for the input stream. The returned string is in the format of "/service/method".
func NewContextWithServerTransportStream ¶ added in v1.11.0
func NewContextWithServerTransportStream(ctx context.Context, stream ServerTransportStream) context.Context
NewContextWithServerTransportStream creates a new context from ctx and attaches stream to it.
This API is EXPERIMENTAL.
func RegisterChannelz ¶ added in v1.12.0
func RegisterChannelz()
RegisterChannelz turns on channelz service. This is an EXPERIMENTAL API.
func SendHeader ¶
SendHeader sends header metadata. It may be called at most once. The provided md and headers set by SetHeader() will be sent.
func SetHeader ¶ added in v1.0.3
SetHeader sets the header metadata. When called multiple times, all the provided metadata will be merged. All the metadata will be sent out when one of the following happens:
- grpc.SendHeader() is called;
- The first response is sent out;
- An RPC status is sent out (error or success).
Types ¶
type Address
deprecated
type Address struct { // Addr is the server address on which a connection will be established. Addr string // Metadata is the information associated with Addr, which may be used // to make load balancing decision. Metadata interface{} }
Address represents a server the client connects to.
Deprecated: please use package balancer.
type BackoffConfig ¶
type BackoffConfig struct { // MaxDelay is the upper bound of backoff delay. MaxDelay time.Duration }
BackoffConfig defines the parameters for the default gRPC backoff strategy.
type Balancer
deprecated
type Balancer interface { // Start does the initialization work to bootstrap a Balancer. For example, // this function may start the name resolution and watch the updates. It will // be called when dialing. Start(target string, config BalancerConfig) error // Up informs the Balancer that gRPC has a connection to the server at // addr. It returns down which is called once the connection to addr gets // lost or closed. // TODO: It is not clear how to construct and take advantage of the meaningful error // parameter for down. Need realistic demands to guide. Up(addr Address) (down func(error)) // Get gets the address of a server for the RPC corresponding to ctx. // i) If it returns a connected address, gRPC internals issues the RPC on the // connection to this address; // ii) If it returns an address on which the connection is under construction // (initiated by Notify(...)) but not connected, gRPC internals // * fails RPC if the RPC is fail-fast and connection is in the TransientFailure or // Shutdown state; // or // * issues RPC on the connection otherwise. // iii) If it returns an address on which the connection does not exist, gRPC // internals treats it as an error and will fail the corresponding RPC. // // Therefore, the following is the recommended rule when writing a custom Balancer. // If opts.BlockingWait is true, it should return a connected address or // block if there is no connected address. It should respect the timeout or // cancellation of ctx when blocking. If opts.BlockingWait is false (for fail-fast // RPCs), it should return an address it has notified via Notify(...) immediately // instead of blocking. // // The function returns put which is called once the rpc has completed or failed. // put can collect and report RPC stats to a remote load balancer. // // This function should only return the errors Balancer cannot recover by itself. // gRPC internals will fail the RPC if an error is returned. Get(ctx context.Context, opts BalancerGetOptions) (addr Address, put func(), err error) // Notify returns a channel that is used by gRPC internals to watch the addresses // gRPC needs to connect. The addresses might be from a name resolver or remote // load balancer. gRPC internals will compare it with the existing connected // addresses. If the address Balancer notified is not in the existing connected // addresses, gRPC starts to connect the address. If an address in the existing // connected addresses is not in the notification list, the corresponding connection // is shutdown gracefully. Otherwise, there are no operations to take. Note that // the Address slice must be the full list of the Addresses which should be connected. // It is NOT delta. Notify() <-chan []Address // Close shuts down the balancer. Close() error }
Balancer chooses network addresses for RPCs.
Deprecated: please use package balancer.
func RoundRobin
deprecated
type BalancerConfig
deprecated
added in
v1.0.2
type BalancerConfig struct { // DialCreds is the transport credential the Balancer implementation can // use to dial to a remote load balancer server. The Balancer implementations // can ignore this if it does not need to talk to another party securely. DialCreds credentials.TransportCredentials // Dialer is the custom dialer the Balancer implementation can use to dial // to a remote load balancer server. The Balancer implementations // can ignore this if it doesn't need to talk to remote balancer. Dialer func(context.Context, string) (net.Conn, error) }
BalancerConfig specifies the configurations for Balancer.
Deprecated: please use package balancer.
type BalancerGetOptions
deprecated
type BalancerGetOptions struct { // BlockingWait specifies whether Get should block when there is no // connected address. BlockingWait bool }
BalancerGetOptions configures a Get call.
Deprecated: please use package balancer.
type CallOption ¶
type CallOption interface {
// contains filtered or unexported methods
}
CallOption configures a Call before it starts or extracts information from a Call after it completes.
func CallContentSubtype ¶ added in v1.10.0
func CallContentSubtype(contentSubtype string) CallOption
CallContentSubtype returns a CallOption that will set the content-subtype for a call. For example, if content-subtype is "json", the Content-Type over the wire will be "application/grpc+json". The content-subtype is converted to lowercase before being included in Content-Type. See Content-Type on https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests for more details.
If CallCustomCodec is not also used, the content-subtype will be used to look up the Codec to use in the registry controlled by RegisterCodec. See the documentation on RegisterCodec for details on registration. The lookup of content-subtype is case-insensitive. If no such Codec is found, the call will result in an error with code codes.Internal.
If CallCustomCodec is also used, that Codec will be used for all request and response messages, with the content-subtype set to the given contentSubtype here for requests.
func CallCustomCodec ¶ added in v1.10.0
func CallCustomCodec(codec Codec) CallOption
CallCustomCodec returns a CallOption that will set the given Codec to be used for all request and response messages for a call. The result of calling String() will be used as the content-subtype in a case-insensitive manner.
See Content-Type on https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests for more details. Also see the documentation on RegisterCodec and CallContentSubtype for more details on the interaction between Codec and content-subtype.
This function is provided for advanced users; prefer to use only CallContentSubtype to select a registered codec instead.
func FailFast ¶
func FailFast(failFast bool) CallOption
FailFast configures the action to take when an RPC is attempted on broken connections or unreachable servers. If failFast is true, the RPC will fail immediately. Otherwise, the RPC client will block the call until a connection is available (or the call is canceled or times out) and will retry the call if it fails due to a transient error. gRPC will not retry if data was written to the wire unless the server indicates it did not process the data. Please refer to https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md.
By default, RPCs are "Fail Fast".
func Header ¶
func Header(md *metadata.MD) CallOption
Header returns a CallOptions that retrieves the header metadata for a unary RPC.
func MaxCallRecvMsgSize ¶ added in v1.4.0
func MaxCallRecvMsgSize(s int) CallOption
MaxCallRecvMsgSize returns a CallOption which sets the maximum message size the client can receive.
func MaxCallSendMsgSize ¶ added in v1.4.0
func MaxCallSendMsgSize(s int) CallOption
MaxCallSendMsgSize returns a CallOption which sets the maximum message size the client can send.
func MaxRetryRPCBufferSize ¶ added in v1.14.0
func MaxRetryRPCBufferSize(bytes int) CallOption
MaxRetryRPCBufferSize returns a CallOption that limits the amount of memory used for buffering this RPC's requests for retry purposes.
This API is EXPERIMENTAL.
func Peer ¶ added in v1.2.0
func Peer(p *peer.Peer) CallOption
Peer returns a CallOption that retrieves peer information for a unary RPC. The peer field will be populated *after* the RPC completes.
func PerRPCCredentials ¶ added in v1.4.0
func PerRPCCredentials(creds credentials.PerRPCCredentials) CallOption
PerRPCCredentials returns a CallOption that sets credentials.PerRPCCredentials for a call.
func Trailer ¶
func Trailer(md *metadata.MD) CallOption
Trailer returns a CallOptions that retrieves the trailer metadata for a unary RPC.
func UseCompressor ¶ added in v1.8.0
func UseCompressor(name string) CallOption
UseCompressor returns a CallOption which sets the compressor used when sending the request. If WithCompressor is also set, UseCompressor has higher priority.
This API is EXPERIMENTAL.
type ClientConn ¶
type ClientConn struct {
// contains filtered or unexported fields
}
ClientConn represents a client connection to an RPC server.
func Dial ¶
func Dial(target string, opts ...DialOption) (*ClientConn, error)
Dial creates a client connection to the given target.
func DialContext ¶ added in v1.0.2
func DialContext(ctx context.Context, target string, opts ...DialOption) (conn *ClientConn, err error)
DialContext creates a client connection to the given target. By default, it's a non-blocking dial (the function won't wait for connections to be established, and connecting happens in the background). To make it a blocking dial, use WithBlock() dial option.
In the non-blocking case, the ctx does not act against the connection. It only controls the setup steps.
In the blocking case, ctx can be used to cancel or expire the pending connection. Once this function returns, the cancellation and expiration of ctx will be noop. Users should call ClientConn.Close to terminate all the pending operations after this function returns.
The target name syntax is defined in https://github.com/grpc/grpc/blob/master/doc/naming.md. e.g. to use dns resolver, a "dns:///" prefix should be applied to the target.
func (*ClientConn) ChannelzMetric ¶ added in v1.12.0
func (cc *ClientConn) ChannelzMetric() *channelz.ChannelInternalMetric
ChannelzMetric returns ChannelInternalMetric of current ClientConn. This is an EXPERIMENTAL API.
func (*ClientConn) Close ¶
func (cc *ClientConn) Close() error
Close tears down the ClientConn and all underlying connections.
func (*ClientConn) GetMethodConfig ¶ added in v1.4.0
func (cc *ClientConn) GetMethodConfig(method string) MethodConfig
GetMethodConfig gets the method config of the input method. If there's an exact match for input method (i.e. /service/method), we return the corresponding MethodConfig. If there isn't an exact match for the input method, we look for the default config under the service (i.e /service/). If there is a default MethodConfig for the service, we return it. Otherwise, we return an empty MethodConfig.
func (*ClientConn) GetState ¶ added in v1.5.2
func (cc *ClientConn) GetState() connectivity.State
GetState returns the connectivity.State of ClientConn. This is an EXPERIMENTAL API.
func (*ClientConn) Invoke ¶ added in v1.8.0
func (cc *ClientConn) Invoke(ctx context.Context, method string, args, reply interface{}, opts ...CallOption) error
Invoke sends the RPC request on the wire and returns after response is received. This is typically called by generated code.
All errors returned by Invoke are compatible with the status package.
func (*ClientConn) NewStream ¶ added in v1.8.0
func (cc *ClientConn) NewStream(ctx context.Context, desc *StreamDesc, method string, opts ...CallOption) (ClientStream, error)
NewStream creates a new Stream for the client side. This is typically called by generated code. ctx is used for the lifetime of the stream.
To ensure resources are not leaked due to the stream returned, one of the following actions must be performed:
- Call Close on the ClientConn.
- Cancel the context provided.
- Call RecvMsg until a non-nil error is returned. A protobuf-generated client-streaming RPC, for instance, might use the helper function CloseAndRecv (note that CloseSend does not Recv, therefore is not guaranteed to release all resources).
- Receive a non-nil, non-io.EOF error from Header or SendMsg.
If none of the above happen, a goroutine and a context will be leaked, and grpc will not call the optionally-configured stats handler with a stats.End message.
func (*ClientConn) Target ¶ added in v1.14.0
func (cc *ClientConn) Target() string
Target returns the target string of the ClientConn. This is an EXPERIMENTAL API.
func (*ClientConn) WaitForStateChange ¶ added in v1.5.2
func (cc *ClientConn) WaitForStateChange(ctx context.Context, sourceState connectivity.State) bool
WaitForStateChange waits until the connectivity.State of ClientConn changes from sourceState or ctx expires. A true value is returned in former case and false in latter. This is an EXPERIMENTAL API.
type ClientStream ¶
type ClientStream interface { // Header returns the header metadata received from the server if there // is any. It blocks if the metadata is not ready to read. Header() (metadata.MD, error) // Trailer returns the trailer metadata from the server, if there is any. // It must only be called after stream.CloseAndRecv has returned, or // stream.Recv has returned a non-nil error (including io.EOF). Trailer() metadata.MD // CloseSend closes the send direction of the stream. It closes the stream // when non-nil error is met. CloseSend() error // Context returns the context for this stream. // // It should not be called until after Header or RecvMsg has returned. Once // called, subsequent client-side retries are disabled. Context() context.Context // SendMsg is generally called by generated code. On error, SendMsg aborts // the stream. If the error was generated by the client, the status is // returned directly; otherwise, io.EOF is returned and the status of // the stream may be discovered using RecvMsg. // // SendMsg blocks until: // - There is sufficient flow control to schedule m with the transport, or // - The stream is done, or // - The stream breaks. // // SendMsg does not wait until the message is received by the server. An // untimely stream closure may result in lost messages. To ensure delivery, // users should ensure the RPC completed successfully using RecvMsg. // // It is safe to have a goroutine calling SendMsg and another goroutine // calling RecvMsg on the same stream at the same time, but it is not safe // to call SendMsg on the same stream in different goroutines. SendMsg(m interface{}) error // RecvMsg blocks until it receives a message into m or the stream is // done. It returns io.EOF when the stream completes successfully. On // any other error, the stream is aborted and the error contains the RPC // status. // // It is safe to have a goroutine calling SendMsg and another goroutine // calling RecvMsg on the same stream at the same time, but it is not // safe to call RecvMsg on the same stream in different goroutines. RecvMsg(m interface{}) error }
ClientStream defines the client-side behavior of a streaming RPC.
All errors returned from ClientStream methods are compatible with the status package.
func NewClientStream ¶
func NewClientStream(ctx context.Context, desc *StreamDesc, cc *ClientConn, method string, opts ...CallOption) (ClientStream, error)
NewClientStream is a wrapper for ClientConn.NewStream.
type Codec
deprecated
type Codec interface { // Marshal returns the wire format of v. Marshal(v interface{}) ([]byte, error) // Unmarshal parses the wire format into v. Unmarshal(data []byte, v interface{}) error // String returns the name of the Codec implementation. This is unused by // gRPC. String() string }
Codec defines the interface gRPC uses to encode and decode messages. Note that implementations of this interface must be thread safe; a Codec's methods can be called from concurrent goroutines.
Deprecated: use encoding.Codec instead.
type Compressor
deprecated
type Compressor interface { // Do compresses p into w. Do(w io.Writer, p []byte) error // Type returns the compression algorithm the Compressor uses. Type() string }
Compressor defines the interface gRPC uses to compress a message.
Deprecated: use package encoding.
func NewGZIPCompressor
deprecated
func NewGZIPCompressor() Compressor
NewGZIPCompressor creates a Compressor based on GZIP.
Deprecated: use package encoding/gzip.
func NewGZIPCompressorWithLevel
deprecated
added in
v1.11.0
func NewGZIPCompressorWithLevel(level int) (Compressor, error)
NewGZIPCompressorWithLevel is like NewGZIPCompressor but specifies the gzip compression level instead of assuming DefaultCompression.
The error returned will be nil if the level is valid.
Deprecated: use package encoding/gzip.
type CompressorCallOption ¶ added in v1.11.0
type CompressorCallOption struct {
CompressorType string
}
CompressorCallOption is a CallOption that indicates the compressor to use. This is an EXPERIMENTAL API.
type ContentSubtypeCallOption ¶ added in v1.11.0
type ContentSubtypeCallOption struct {
ContentSubtype string
}
ContentSubtypeCallOption is a CallOption that indicates the content-subtype used for marshaling messages. This is an EXPERIMENTAL API.
type CustomCodecCallOption ¶ added in v1.11.0
type CustomCodecCallOption struct {
Codec Codec
}
CustomCodecCallOption is a CallOption that indicates the codec used for marshaling messages. This is an EXPERIMENTAL API.
type Decompressor
deprecated
type Decompressor interface { // Do reads the data from r and uncompress them. Do(r io.Reader) ([]byte, error) // Type returns the compression algorithm the Decompressor uses. Type() string }
Decompressor defines the interface gRPC uses to decompress a message.
Deprecated: use package encoding.
func NewGZIPDecompressor
deprecated
func NewGZIPDecompressor() Decompressor
NewGZIPDecompressor creates a Decompressor based on GZIP.
Deprecated: use package encoding/gzip.
type DialOption ¶
type DialOption interface {
// contains filtered or unexported methods
}
DialOption configures how we set up the connection.
func FailOnNonTempDialError ¶ added in v1.0.5
func FailOnNonTempDialError(f bool) DialOption
FailOnNonTempDialError returns a DialOption that specifies if gRPC fails on non-temporary dial errors. If f is true, and dialer returns a non-temporary error, gRPC will fail the connection to the network address and won't try to reconnect. The default value of FailOnNonTempDialError is false.
This is an EXPERIMENTAL API.
func WithAuthority ¶ added in v1.2.0
func WithAuthority(a string) DialOption
WithAuthority returns a DialOption that specifies the value to be used as the :authority pseudo-header. This value only works with WithInsecure and has no effect if TransportCredentials are present.
func WithBackoffConfig ¶
func WithBackoffConfig(b BackoffConfig) DialOption
WithBackoffConfig configures the dialer to use the provided backoff parameters after connection failures.
Use WithBackoffMaxDelay until more parameters on BackoffConfig are opened up for use.
func WithBackoffMaxDelay ¶
func WithBackoffMaxDelay(md time.Duration) DialOption
WithBackoffMaxDelay configures the dialer to use the provided maximum delay when backing off after failed connection attempts.
func WithBalancer
deprecated
func WithBalancer(b Balancer) DialOption
WithBalancer returns a DialOption which sets a load balancer with the v1 API. Name resolver will be ignored if this DialOption is specified.
Deprecated: use the new balancer APIs in balancer package and WithBalancerName.
func WithBalancerName ¶ added in v1.9.0
func WithBalancerName(balancerName string) DialOption
WithBalancerName sets the balancer that the ClientConn will be initialized with. Balancer registered with balancerName will be used. This function panics if no balancer was registered by balancerName.
The balancer cannot be overridden by balancer option specified by service config.
This is an EXPERIMENTAL API.
func WithBlock ¶
func WithBlock() DialOption
WithBlock returns a DialOption which makes caller of Dial blocks until the underlying connection is up. Without this, Dial returns immediately and connecting the server happens in background.
func WithChannelzParentID ¶ added in v1.12.0
func WithChannelzParentID(id int64) DialOption
WithChannelzParentID returns a DialOption that specifies the channelz ID of current ClientConn's parent. This function is used in nested channel creation (e.g. grpclb dial).
func WithCodec
deprecated
func WithCodec(c Codec) DialOption
WithCodec returns a DialOption which sets a codec for message marshaling and unmarshaling.
Deprecated: use WithDefaultCallOptions(CallCustomCodec(c)) instead.
func WithCompressor
deprecated
func WithCompressor(cp Compressor) DialOption
WithCompressor returns a DialOption which sets a Compressor to use for message compression. It has lower priority than the compressor set by the UseCompressor CallOption.
Deprecated: use UseCompressor instead.
func WithDecompressor
deprecated
func WithDecompressor(dc Decompressor) DialOption
WithDecompressor returns a DialOption which sets a Decompressor to use for incoming message decompression. If incoming response messages are encoded using the decompressor's Type(), it will be used. Otherwise, the message encoding will be used to look up the compressor registered via encoding.RegisterCompressor, which will then be used to decompress the message. If no compressor is registered for the encoding, an Unimplemented status error will be returned.
Deprecated: use encoding.RegisterCompressor instead.
func WithDefaultCallOptions ¶ added in v1.4.0
func WithDefaultCallOptions(cos ...CallOption) DialOption
WithDefaultCallOptions returns a DialOption which sets the default CallOptions for calls over the connection.
func WithDialer ¶
WithDialer returns a DialOption that specifies a function to use for dialing network addresses. If FailOnNonTempDialError() is set to true, and an error is returned by f, gRPC checks the error's Temporary() method to decide if it should try to reconnect to the network address.
func WithDisableRetry ¶ added in v1.14.0
func WithDisableRetry() DialOption
WithDisableRetry returns a DialOption that disables retries, even if the service config enables them. This does not impact transparent retries, which will happen automatically if no data is written to the wire or if the RPC is unprocessed by the remote server.
Retry support is currently disabled by default, but will be enabled by default in the future. Until then, it may be enabled by setting the environment variable "GRPC_GO_RETRY" to "on".
This API is EXPERIMENTAL.
func WithDisableServiceConfig ¶ added in v1.12.0
func WithDisableServiceConfig() DialOption
WithDisableServiceConfig returns a DialOption that causes grpc to ignore any service config provided by the resolver and provides a hint to the resolver to not fetch service configs.
func WithInitialConnWindowSize ¶ added in v1.4.0
func WithInitialConnWindowSize(s int32) DialOption
WithInitialConnWindowSize returns a DialOption which sets the value for initial window size on a connection. The lower bound for window size is 64K and any value smaller than that will be ignored.
func WithInitialWindowSize ¶ added in v1.4.0
func WithInitialWindowSize(s int32) DialOption
WithInitialWindowSize returns a DialOption which sets the value for initial window size on a stream. The lower bound for window size is 64K and any value smaller than that will be ignored.
func WithInsecure ¶
func WithInsecure() DialOption
WithInsecure returns a DialOption which disables transport security for this ClientConn. Note that transport security is required unless WithInsecure is set.
func WithKeepaliveParams ¶ added in v1.2.0
func WithKeepaliveParams(kp keepalive.ClientParameters) DialOption
WithKeepaliveParams returns a DialOption that specifies keepalive parameters for the client transport.
func WithMaxHeaderListSize ¶ added in v1.14.0
func WithMaxHeaderListSize(s uint32) DialOption
WithMaxHeaderListSize returns a DialOption that specifies the maximum (uncompressed) size of header list that the client is prepared to accept.
func WithMaxMsgSize
deprecated
added in
v1.2.0
func WithMaxMsgSize(s int) DialOption
WithMaxMsgSize returns a DialOption which sets the maximum message size the client can receive.
Deprecated: use WithDefaultCallOptions(MaxCallRecvMsgSize(s)) instead.
func WithPerRPCCredentials ¶
func WithPerRPCCredentials(creds credentials.PerRPCCredentials) DialOption
WithPerRPCCredentials returns a DialOption which sets credentials and places auth state on each outbound RPC.
func WithReadBufferSize ¶ added in v1.7.0
func WithReadBufferSize(s int) DialOption
WithReadBufferSize lets you set the size of read buffer, this determines how much data can be read at most for each read syscall.
The default value for this buffer is 32KB. Zero will disable read buffer for a connection so data framer can access the underlying conn directly.
func WithServiceConfig
deprecated
added in
v1.2.0
func WithServiceConfig(c <-chan ServiceConfig) DialOption
WithServiceConfig returns a DialOption which has a channel to read the service configuration.
Deprecated: service config should be received through name resolver, as specified here. https://github.com/grpc/grpc/blob/master/doc/service_config.md
func WithStatsHandler ¶ added in v1.2.0
func WithStatsHandler(h stats.Handler) DialOption
WithStatsHandler returns a DialOption that specifies the stats handler for all the RPCs and underlying network connections in this ClientConn.
func WithStreamInterceptor ¶ added in v1.0.2
func WithStreamInterceptor(f StreamClientInterceptor) DialOption
WithStreamInterceptor returns a DialOption that specifies the interceptor for streaming RPCs.
func WithTimeout
deprecated
func WithTimeout(d time.Duration) DialOption
WithTimeout returns a DialOption that configures a timeout for dialing a ClientConn initially. This is valid if and only if WithBlock() is present.
Deprecated: use DialContext and context.WithTimeout instead.
func WithTransportCredentials ¶
func WithTransportCredentials(creds credentials.TransportCredentials) DialOption
WithTransportCredentials returns a DialOption which configures a connection level security credentials (e.g., TLS/SSL).
func WithUnaryInterceptor ¶ added in v1.0.2
func WithUnaryInterceptor(f UnaryClientInterceptor) DialOption
WithUnaryInterceptor returns a DialOption that specifies the interceptor for unary RPCs.
func WithUserAgent ¶
func WithUserAgent(s string) DialOption
WithUserAgent returns a DialOption that specifies a user agent string for all the RPCs.
func WithWaitForHandshake ¶ added in v1.9.0
func WithWaitForHandshake() DialOption
WithWaitForHandshake blocks until the initial settings frame is received from the server before assigning RPCs to the connection. Experimental API.
func WithWriteBufferSize ¶ added in v1.7.0
func WithWriteBufferSize(s int) DialOption
WithWriteBufferSize determines how much data can be batched before doing a write on the wire. The corresponding memory allocation for this buffer will be twice the size to keep syscalls low. The default value for this buffer is 32KB.
Zero will disable the write buffer such that each write will be on underlying connection. Note: A Send call may not directly translate to a write.
type EmptyCallOption ¶ added in v1.4.0
type EmptyCallOption struct{}
EmptyCallOption does not alter the Call configuration. It can be embedded in another structure to carry satellite data for use by interceptors.
type EmptyDialOption ¶ added in v1.14.0
type EmptyDialOption struct{}
EmptyDialOption does not alter the dial configuration. It can be embedded in another structure to build custom dial options.
This API is EXPERIMENTAL.
type FailFastCallOption ¶ added in v1.11.0
type FailFastCallOption struct {
FailFast bool
}
FailFastCallOption is a CallOption for indicating whether an RPC should fail fast or not. This is an EXPERIMENTAL API.
type HeaderCallOption ¶ added in v1.11.0
HeaderCallOption is a CallOption for collecting response header metadata. The metadata field will be populated *after* the RPC completes. This is an EXPERIMENTAL API.
type MaxRecvMsgSizeCallOption ¶ added in v1.11.0
type MaxRecvMsgSizeCallOption struct {
MaxRecvMsgSize int
}
MaxRecvMsgSizeCallOption is a CallOption that indicates the maximum message size the client can receive. This is an EXPERIMENTAL API.
type MaxRetryRPCBufferSizeCallOption ¶ added in v1.14.0
type MaxRetryRPCBufferSizeCallOption struct {
MaxRetryRPCBufferSize int
}
MaxRetryRPCBufferSizeCallOption is a CallOption indicating the amount of memory to be used for caching this RPC for retry purposes. This is an EXPERIMENTAL API.
type MaxSendMsgSizeCallOption ¶ added in v1.11.0
type MaxSendMsgSizeCallOption struct {
MaxSendMsgSize int
}
MaxSendMsgSizeCallOption is a CallOption that indicates the maximum message size the client can send. This is an EXPERIMENTAL API.
type MethodConfig
deprecated
added in
v1.2.0
type MethodConfig struct { // WaitForReady indicates whether RPCs sent to this method should wait until // the connection is ready by default (!failfast). The value specified via the // gRPC client API will override the value set here. WaitForReady *bool // Timeout is the default timeout for RPCs sent to this method. The actual // deadline used will be the minimum of the value specified here and the value // set by the application via the gRPC client API. If either one is not set, // then the other will be used. If neither is set, then the RPC has no deadline. Timeout *time.Duration // MaxReqSize is the maximum allowed payload size for an individual request in a // stream (client->server) in bytes. The size which is measured is the serialized // payload after per-message compression (but before stream compression) in bytes. // The actual value used is the minimum of the value specified here and the value set // by the application via the gRPC client API. If either one is not set, then the other // will be used. If neither is set, then the built-in default is used. MaxReqSize *int // MaxRespSize is the maximum allowed payload size for an individual response in a // stream (server->client) in bytes. MaxRespSize *int // contains filtered or unexported fields }
MethodConfig defines the configuration recommended by the service providers for a particular method.
Deprecated: Users should not use this struct. Service config should be received through name resolver, as specified here https://github.com/grpc/grpc/blob/master/doc/service_config.md
type MethodDesc ¶
type MethodDesc struct { MethodName string Handler methodHandler }
MethodDesc represents an RPC service's method specification.
type MethodInfo ¶
type MethodInfo struct { // Name is the method name only, without the service name or package name. Name string // IsClientStream indicates whether the RPC is a client streaming RPC. IsClientStream bool // IsServerStream indicates whether the RPC is a server streaming RPC. IsServerStream bool }
MethodInfo contains the information of an RPC including its method name and type.
type PeerCallOption ¶ added in v1.11.0
PeerCallOption is a CallOption for collecting the identity of the remote peer. The peer field will be populated *after* the RPC completes. This is an EXPERIMENTAL API.
type PerRPCCredsCallOption ¶ added in v1.11.0
type PerRPCCredsCallOption struct {
Creds credentials.PerRPCCredentials
}
PerRPCCredsCallOption is a CallOption that indicates the per-RPC credentials to use for the call. This is an EXPERIMENTAL API.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a gRPC server to serve RPC requests.
func NewServer ¶
func NewServer(opt ...ServerOption) *Server
NewServer creates a gRPC server which has no service registered and has not started to accept requests yet.
func (*Server) ChannelzMetric ¶ added in v1.12.0
func (s *Server) ChannelzMetric() *channelz.ServerInternalMetric
ChannelzMetric returns ServerInternalMetric of current server. This is an EXPERIMENTAL API.
func (*Server) GetServiceInfo ¶
func (s *Server) GetServiceInfo() map[string]ServiceInfo
GetServiceInfo returns a map from service names to ServiceInfo. Service names include the package names, in the form of <package>.<service>.
func (*Server) GracefulStop ¶ added in v1.0.2
func (s *Server) GracefulStop()
GracefulStop stops the gRPC server gracefully. It stops the server from accepting new connections and RPCs and blocks until all the pending RPCs are finished.
func (*Server) RegisterService ¶
func (s *Server) RegisterService(sd *ServiceDesc, ss interface{})
RegisterService registers a service and its implementation to the gRPC server. It is called from the IDL generated code. This must be called before invoking Serve.
func (*Server) Serve ¶
Serve accepts incoming connections on the listener lis, creating a new ServerTransport and service goroutine for each. The service goroutines read gRPC requests and then call the registered handlers to reply to them. Serve returns when lis.Accept fails with fatal errors. lis will be closed when this method returns. Serve will return a non-nil error unless Stop or GracefulStop is called.
func (*Server) ServeHTTP ¶
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements the Go standard library's http.Handler interface by responding to the gRPC request r, by looking up the requested gRPC method in the gRPC server s.
The provided HTTP request must have arrived on an HTTP/2 connection. When using the Go standard library's server, practically this means that the Request must also have arrived over TLS.
To share one port (such as 443 for https) between gRPC and an existing http.Handler, use a root http.Handler such as:
if r.ProtoMajor == 2 && strings.HasPrefix( r.Header.Get("Content-Type"), "application/grpc") { grpcServer.ServeHTTP(w, r) } else { yourMux.ServeHTTP(w, r) }
Note that ServeHTTP uses Go's HTTP/2 server implementation which is totally separate from grpc-go's HTTP/2 server. Performance and features may vary between the two paths. ServeHTTP does not support some gRPC features available through grpc-go's HTTP/2 server, and it is currently EXPERIMENTAL and subject to change.
type ServerOption ¶
type ServerOption func(*options)
A ServerOption sets options such as credentials, codec and keepalive parameters, etc.
func ConnectionTimeout ¶ added in v1.7.3
func ConnectionTimeout(d time.Duration) ServerOption
ConnectionTimeout returns a ServerOption that sets the timeout for connection establishment (up to and including HTTP/2 handshaking) for all new connections. If this is not set, the default is 120 seconds. A zero or negative value will result in an immediate timeout.
This API is EXPERIMENTAL.
func Creds ¶
func Creds(c credentials.TransportCredentials) ServerOption
Creds returns a ServerOption that sets credentials for server connections.
func CustomCodec ¶
func CustomCodec(codec Codec) ServerOption
CustomCodec returns a ServerOption that sets a codec for message marshaling and unmarshaling.
This will override any lookups by content-subtype for Codecs registered with RegisterCodec.
func InTapHandle ¶ added in v1.0.5
func InTapHandle(h tap.ServerInHandle) ServerOption
InTapHandle returns a ServerOption that sets the tap handle for all the server transport to be created. Only one can be installed.
func InitialConnWindowSize ¶ added in v1.4.0
func InitialConnWindowSize(s int32) ServerOption
InitialConnWindowSize returns a ServerOption that sets window size for a connection. The lower bound for window size is 64K and any value smaller than that will be ignored.
func InitialWindowSize ¶ added in v1.4.0
func InitialWindowSize(s int32) ServerOption
InitialWindowSize returns a ServerOption that sets window size for stream. The lower bound for window size is 64K and any value smaller than that will be ignored.
func KeepaliveEnforcementPolicy ¶ added in v1.3.0
func KeepaliveEnforcementPolicy(kep keepalive.EnforcementPolicy) ServerOption
KeepaliveEnforcementPolicy returns a ServerOption that sets keepalive enforcement policy for the server.
func KeepaliveParams ¶ added in v1.3.0
func KeepaliveParams(kp keepalive.ServerParameters) ServerOption
KeepaliveParams returns a ServerOption that sets keepalive and max-age parameters for the server.
func MaxConcurrentStreams ¶
func MaxConcurrentStreams(n uint32) ServerOption
MaxConcurrentStreams returns a ServerOption that will apply a limit on the number of concurrent streams to each ServerTransport.
func MaxHeaderListSize ¶ added in v1.14.0
func MaxHeaderListSize(s uint32) ServerOption
MaxHeaderListSize returns a ServerOption that sets the max (uncompressed) size of header list that the server is prepared to accept.
func MaxMsgSize
deprecated
added in
v1.0.2
func MaxMsgSize(m int) ServerOption
MaxMsgSize returns a ServerOption to set the max message size in bytes the server can receive. If this is not set, gRPC uses the default limit.
Deprecated: use MaxRecvMsgSize instead.
func MaxRecvMsgSize ¶ added in v1.4.0
func MaxRecvMsgSize(m int) ServerOption
MaxRecvMsgSize returns a ServerOption to set the max message size in bytes the server can receive. If this is not set, gRPC uses the default 4MB.
func MaxSendMsgSize ¶ added in v1.4.0
func MaxSendMsgSize(m int) ServerOption
MaxSendMsgSize returns a ServerOption to set the max message size in bytes the server can send. If this is not set, gRPC uses the default 4MB.
func RPCCompressor
deprecated
func RPCCompressor(cp Compressor) ServerOption
RPCCompressor returns a ServerOption that sets a compressor for outbound messages. For backward compatibility, all outbound messages will be sent using this compressor, regardless of incoming message compression. By default, server messages will be sent using the same compressor with which request messages were sent.
Deprecated: use encoding.RegisterCompressor instead.
func RPCDecompressor
deprecated
func RPCDecompressor(dc Decompressor) ServerOption
RPCDecompressor returns a ServerOption that sets a decompressor for inbound messages. It has higher priority than decompressors registered via encoding.RegisterCompressor.
Deprecated: use encoding.RegisterCompressor instead.
func ReadBufferSize ¶ added in v1.7.0
func ReadBufferSize(s int) ServerOption
ReadBufferSize lets you set the size of read buffer, this determines how much data can be read at most for one read syscall. The default value for this buffer is 32KB. Zero will disable read buffer for a connection so data framer can access the underlying conn directly.
func StatsHandler ¶ added in v1.2.0
func StatsHandler(h stats.Handler) ServerOption
StatsHandler returns a ServerOption that sets the stats handler for the server.
func StreamInterceptor ¶
func StreamInterceptor(i StreamServerInterceptor) ServerOption
StreamInterceptor returns a ServerOption that sets the StreamServerInterceptor for the server. Only one stream interceptor can be installed.
func UnaryInterceptor ¶
func UnaryInterceptor(i UnaryServerInterceptor) ServerOption
UnaryInterceptor returns a ServerOption that sets the UnaryServerInterceptor for the server. Only one unary interceptor can be installed. The construction of multiple interceptors (e.g., chaining) can be implemented at the caller.
func UnknownServiceHandler ¶ added in v1.2.0
func UnknownServiceHandler(streamHandler StreamHandler) ServerOption
UnknownServiceHandler returns a ServerOption that allows for adding a custom unknown service handler. The provided method is a bidi-streaming RPC service handler that will be invoked instead of returning the "unimplemented" gRPC error whenever a request is received for an unregistered service or method. The handling function has full access to the Context of the request and the stream, and the invocation bypasses interceptors.
func WriteBufferSize ¶ added in v1.7.0
func WriteBufferSize(s int) ServerOption
WriteBufferSize determines how much data can be batched before doing a write on the wire. The corresponding memory allocation for this buffer will be twice the size to keep syscalls low. The default value for this buffer is 32KB. Zero will disable the write buffer such that each write will be on underlying connection. Note: A Send call may not directly translate to a write.
type ServerStream ¶
type ServerStream interface { // SetHeader sets the header metadata. It may be called multiple times. // When call multiple times, all the provided metadata will be merged. // All the metadata will be sent out when one of the following happens: // - ServerStream.SendHeader() is called; // - The first response is sent out; // - An RPC status is sent out (error or success). SetHeader(metadata.MD) error // SendHeader sends the header metadata. // The provided md and headers set by SetHeader() will be sent. // It fails if called multiple times. SendHeader(metadata.MD) error // SetTrailer sets the trailer metadata which will be sent with the RPC status. // When called more than once, all the provided metadata will be merged. SetTrailer(metadata.MD) // Context returns the context for this stream. Context() context.Context // SendMsg sends a message. On error, SendMsg aborts the stream and the // error is returned directly. // // SendMsg blocks until: // - There is sufficient flow control to schedule m with the transport, or // - The stream is done, or // - The stream breaks. // // SendMsg does not wait until the message is received by the client. An // untimely stream closure may result in lost messages. // // It is safe to have a goroutine calling SendMsg and another goroutine // calling RecvMsg on the same stream at the same time, but it is not safe // to call SendMsg on the same stream in different goroutines. SendMsg(m interface{}) error // RecvMsg blocks until it receives a message into m or the stream is // done. It returns io.EOF when the client has performed a CloseSend. On // any non-EOF error, the stream is aborted and the error contains the // RPC status. // // It is safe to have a goroutine calling SendMsg and another goroutine // calling RecvMsg on the same stream at the same time, but it is not // safe to call RecvMsg on the same stream in different goroutines. RecvMsg(m interface{}) error }
ServerStream defines the server-side behavior of a streaming RPC.
All errors returned from ServerStream methods are compatible with the status package.
type ServerTransportStream ¶ added in v1.11.0
type ServerTransportStream interface { Method() string SetHeader(md metadata.MD) error SendHeader(md metadata.MD) error SetTrailer(md metadata.MD) error }
ServerTransportStream is a minimal interface that a transport stream must implement. This can be used to mock an actual transport stream for tests of handler code that use, for example, grpc.SetHeader (which requires some stream to be in context).
See also NewContextWithServerTransportStream.
This API is EXPERIMENTAL.
func ServerTransportStreamFromContext ¶ added in v1.12.0
func ServerTransportStreamFromContext(ctx context.Context) ServerTransportStream
ServerTransportStreamFromContext returns the ServerTransportStream saved in ctx. Returns nil if the given context has no stream associated with it (which implies it is not an RPC invocation context).
This API is EXPERIMENTAL.
type ServiceConfig
deprecated
added in
v1.2.0
type ServiceConfig struct { // LB is the load balancer the service providers recommends. The balancer specified // via grpc.WithBalancer will override this. LB *string // Methods contains a map for the methods in this service. If there is an // exact match for a method (i.e. /service/method) in the map, use the // corresponding MethodConfig. If there's no exact match, look for the // default config for the service (/service/) and use the corresponding // MethodConfig if it exists. Otherwise, the method has no MethodConfig to // use. Methods map[string]MethodConfig // contains filtered or unexported fields }
ServiceConfig is provided by the service provider and contains parameters for how clients that connect to the service should behave.
Deprecated: Users should not use this struct. Service config should be received through name resolver, as specified here https://github.com/grpc/grpc/blob/master/doc/service_config.md
type ServiceDesc ¶
type ServiceDesc struct { ServiceName string // The pointer to the service interface. Used to check whether the user // provided implementation satisfies the interface requirements. HandlerType interface{} Methods []MethodDesc Streams []StreamDesc Metadata interface{} }
ServiceDesc represents an RPC service's specification.
type ServiceInfo ¶
type ServiceInfo struct { Methods []MethodInfo // Metadata is the metadata specified in ServiceDesc when registering service. Metadata interface{} }
ServiceInfo contains unary RPC method info, streaming RPC method info and metadata for a service.
type Stream
deprecated
type Stream interface { // Deprecated: See ClientStream and ServerStream documentation instead. Context() context.Context // Deprecated: See ClientStream and ServerStream documentation instead. SendMsg(m interface{}) error // Deprecated: See ClientStream and ServerStream documentation instead. RecvMsg(m interface{}) error }
Stream defines the common interface a client or server stream has to satisfy.
Deprecated: See ClientStream and ServerStream documentation instead.
type StreamClientInterceptor ¶ added in v1.0.2
type StreamClientInterceptor func(ctx context.Context, desc *StreamDesc, cc *ClientConn, method string, streamer Streamer, opts ...CallOption) (ClientStream, error)
StreamClientInterceptor intercepts the creation of ClientStream. It may return a custom ClientStream to intercept all I/O operations. streamer is the handler to create a ClientStream and it is the responsibility of the interceptor to call it. This is an EXPERIMENTAL API.
type StreamDesc ¶
type StreamDesc struct { StreamName string Handler StreamHandler // At least one of these is true. ServerStreams bool ClientStreams bool }
StreamDesc represents a streaming RPC service's method specification.
type StreamHandler ¶
type StreamHandler func(srv interface{}, stream ServerStream) error
StreamHandler defines the handler called by gRPC server to complete the execution of a streaming RPC. If a StreamHandler returns an error, it should be produced by the status package, or else gRPC will use codes.Unknown as the status code and err.Error() as the status message of the RPC.
type StreamServerInfo ¶
type StreamServerInfo struct { // FullMethod is the full RPC method string, i.e., /package.service/method. FullMethod string // IsClientStream indicates whether the RPC is a client streaming RPC. IsClientStream bool // IsServerStream indicates whether the RPC is a server streaming RPC. IsServerStream bool }
StreamServerInfo consists of various information about a streaming RPC on server side. All per-rpc information may be mutated by the interceptor.
type StreamServerInterceptor ¶
type StreamServerInterceptor func(srv interface{}, ss ServerStream, info *StreamServerInfo, handler StreamHandler) error
StreamServerInterceptor provides a hook to intercept the execution of a streaming RPC on the server. info contains all the information of this RPC the interceptor can operate on. And handler is the service method implementation. It is the responsibility of the interceptor to invoke handler to complete the RPC.
type Streamer ¶ added in v1.0.2
type Streamer func(ctx context.Context, desc *StreamDesc, cc *ClientConn, method string, opts ...CallOption) (ClientStream, error)
Streamer is called by StreamClientInterceptor to create a ClientStream.
type TrailerCallOption ¶ added in v1.11.0
TrailerCallOption is a CallOption for collecting response trailer metadata. The metadata field will be populated *after* the RPC completes. This is an EXPERIMENTAL API.
type UnaryClientInterceptor ¶ added in v1.0.2
type UnaryClientInterceptor func(ctx context.Context, method string, req, reply interface{}, cc *ClientConn, invoker UnaryInvoker, opts ...CallOption) error
UnaryClientInterceptor intercepts the execution of a unary RPC on the client. invoker is the handler to complete the RPC and it is the responsibility of the interceptor to call it. This is an EXPERIMENTAL API.
type UnaryHandler ¶
UnaryHandler defines the handler invoked by UnaryServerInterceptor to complete the normal execution of a unary RPC. If a UnaryHandler returns an error, it should be produced by the status package, or else gRPC will use codes.Unknown as the status code and err.Error() as the status message of the RPC.
type UnaryInvoker ¶ added in v1.0.2
type UnaryInvoker func(ctx context.Context, method string, req, reply interface{}, cc *ClientConn, opts ...CallOption) error
UnaryInvoker is called by UnaryClientInterceptor to complete RPCs.
type UnaryServerInfo ¶
type UnaryServerInfo struct { // Server is the service implementation the user provides. This is read-only. Server interface{} // FullMethod is the full RPC method string, i.e., /package.service/method. FullMethod string }
UnaryServerInfo consists of various information about a unary RPC on server side. All per-rpc information may be mutated by the interceptor.
type UnaryServerInterceptor ¶
type UnaryServerInterceptor func(ctx context.Context, req interface{}, info *UnaryServerInfo, handler UnaryHandler) (resp interface{}, err error)
UnaryServerInterceptor provides a hook to intercept the execution of a unary RPC on the server. info contains all the information of this RPC the interceptor can operate on. And handler is the wrapper of the service method implementation. It is the responsibility of the interceptor to invoke handler to complete the RPC.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package balancer defines APIs for load balancing in gRPC.
|
Package balancer defines APIs for load balancing in gRPC. |
base
Package base defines a balancer base that can be used to build balancers with different picking algorithms.
|
Package base defines a balancer base that can be used to build balancers with different picking algorithms. |
grpclb
Package grpclb defines a grpclb balancer.
|
Package grpclb defines a grpclb balancer. |
roundrobin
Package roundrobin defines a roundrobin balancer.
|
Package roundrobin defines a roundrobin balancer. |
Package benchmark implements the building blocks to setup end-to-end gRPC benchmarks.
|
Package benchmark implements the building blocks to setup end-to-end gRPC benchmarks. |
benchmain
Package main provides benchmark with setting flags.
|
Package main provides benchmark with setting flags. |
benchresult
To format the benchmark result: go run benchmark/benchresult/main.go resultfile To see the performance change based on a old result: go run benchmark/benchresult/main.go resultfile_old resultfile It will print the comparison result of intersection benchmarks between two files.
|
To format the benchmark result: go run benchmark/benchresult/main.go resultfile To see the performance change based on a old result: go run benchmark/benchresult/main.go resultfile_old resultfile It will print the comparison result of intersection benchmarks between two files. |
latency
Package latency provides wrappers for net.Conn, net.Listener, and net.Dialers, designed to interoperate to inject real-world latency into network connections.
|
Package latency provides wrappers for net.Conn, net.Listener, and net.Dialers, designed to interoperate to inject real-world latency into network connections. |
channelz
|
|
service
Package service provides an implementation for channelz service server.
|
Package service provides an implementation for channelz service server. |
Package codes defines the canonical error codes used by gRPC.
|
Package codes defines the canonical error codes used by gRPC. |
Package connectivity defines connectivity semantics.
|
Package connectivity defines connectivity semantics. |
Package credentials implements various credentials supported by gRPC library, which encapsulate all the state needed by a client to authenticate with a server and make various assertions, e.g., about the client's identity, role, or whether it is authorized to make a particular call.
|
Package credentials implements various credentials supported by gRPC library, which encapsulate all the state needed by a client to authenticate with a server and make various assertions, e.g., about the client's identity, role, or whether it is authorized to make a particular call. |
alts
Package alts implements the ALTS credential support by gRPC library, which encapsulates all the state needed by a client to authenticate with a server using ALTS and make various assertions, e.g., about the client's identity, role, or whether it is authorized to make a particular call.
|
Package alts implements the ALTS credential support by gRPC library, which encapsulates all the state needed by a client to authenticate with a server using ALTS and make various assertions, e.g., about the client's identity, role, or whether it is authorized to make a particular call. |
alts/core
Package core contains common core functionality for ALTS.
|
Package core contains common core functionality for ALTS. |
alts/core/authinfo
Package authinfo provide authentication information returned by handshakers.
|
Package authinfo provide authentication information returned by handshakers. |
alts/core/conn
Package conn contains an implementation of a secure channel created by gRPC handshakers.
|
Package conn contains an implementation of a secure channel created by gRPC handshakers. |
alts/core/handshaker
Package handshaker provides ALTS handshaking functionality for GCP.
|
Package handshaker provides ALTS handshaking functionality for GCP. |
alts/core/handshaker/service
Package service manages connections between the VM application and the ALTS handshaker service.
|
Package service manages connections between the VM application and the ALTS handshaker service. |
alts/core/testutil
Package testutil include useful test utilities for the handshaker.
|
Package testutil include useful test utilities for the handshaker. |
oauth
Package oauth implements gRPC credentials using OAuth.
|
Package oauth implements gRPC credentials using OAuth. |
Package encoding defines the interface for the compressor and codec, and functions to register and retrieve compressors and codecs.
|
Package encoding defines the interface for the compressor and codec, and functions to register and retrieve compressors and codecs. |
gzip
Package gzip implements and registers the gzip compressor during the initialization.
|
Package gzip implements and registers the gzip compressor during the initialization. |
proto
Package proto defines the protobuf codec.
|
Package proto defines the protobuf codec. |
examples
|
|
oauth/client
The client demonstrates how to supply an OAuth2 token for every RPC.
|
The client demonstrates how to supply an OAuth2 token for every RPC. |
oauth/server
The server demonstrates how to consume and validate OAuth2 tokens provided by clients for each RPC.
|
The server demonstrates how to consume and validate OAuth2 tokens provided by clients for each RPC. |
route_guide/client
Package main implements a simple gRPC client that demonstrates how to use gRPC-Go libraries to perform unary, client streaming, server streaming and full duplex RPCs.
|
Package main implements a simple gRPC client that demonstrates how to use gRPC-Go libraries to perform unary, client streaming, server streaming and full duplex RPCs. |
route_guide/server
Package main implements a simple gRPC server that demonstrates how to use gRPC-Go libraries to perform unary, client streaming, server streaming and full duplex RPCs.
|
Package main implements a simple gRPC server that demonstrates how to use gRPC-Go libraries to perform unary, client streaming, server streaming and full duplex RPCs. |
Package grpclog defines logging for grpc.
|
Package grpclog defines logging for grpc. |
glogger
Package glogger defines glog-based logging for grpc.
|
Package glogger defines glog-based logging for grpc. |
Package health provides some utility functions to health-check a server.
|
Package health provides some utility functions to health-check a server. |
Package internal contains gRPC-internal code, to avoid polluting the godoc of the top-level grpc package.
|
Package internal contains gRPC-internal code, to avoid polluting the godoc of the top-level grpc package. |
backoff
Package backoff implement the backoff strategy for gRPC.
|
Package backoff implement the backoff strategy for gRPC. |
channelz
Package channelz defines APIs for enabling channelz service, entry registration/deletion, and accessing channelz data.
|
Package channelz defines APIs for enabling channelz service, entry registration/deletion, and accessing channelz data. |
envconfig
Package envconfig contains grpc settings configured by environment variables.
|
Package envconfig contains grpc settings configured by environment variables. |
grpcrand
Package grpcrand implements math/rand functions in a concurrent-safe way with a global random source, independent of math/rand's global source.
|
Package grpcrand implements math/rand functions in a concurrent-safe way with a global random source, independent of math/rand's global source. |
grpcsync
Package grpcsync implements additional synchronization primitives built upon the sync package.
|
Package grpcsync implements additional synchronization primitives built upon the sync package. |
leakcheck
Package leakcheck contains functions to check leaked goroutines.
|
Package leakcheck contains functions to check leaked goroutines. |
syscall
Package syscall provides functionalities that grpc uses to get low-level operating system stats/info.
|
Package syscall provides functionalities that grpc uses to get low-level operating system stats/info. |
transport
Package transport defines and implements message oriented communication channel to complete various transactions (e.g., an RPC).
|
Package transport defines and implements message oriented communication channel to complete various transactions (e.g., an RPC). |
alts/client
This binary can only run on Google Cloud Platform (GCP).
|
This binary can only run on Google Cloud Platform (GCP). |
alts/server
This binary can only run on Google Cloud Platform (GCP).
|
This binary can only run on Google Cloud Platform (GCP). |
Package keepalive defines configurable parameters for point-to-point healthcheck.
|
Package keepalive defines configurable parameters for point-to-point healthcheck. |
Package metadata define the structure of the metadata supported by gRPC library.
|
Package metadata define the structure of the metadata supported by gRPC library. |
Package naming defines the naming API and related data structures for gRPC.
|
Package naming defines the naming API and related data structures for gRPC. |
Package peer defines various peer information associated with RPCs and corresponding utils.
|
Package peer defines various peer information associated with RPCs and corresponding utils. |
Package reflection implements server reflection service.
|
Package reflection implements server reflection service. |
grpc_testingv3
Package grpc_testingv3 is a generated protocol buffer package.
|
Package grpc_testingv3 is a generated protocol buffer package. |
Package resolver defines APIs for name resolution in gRPC.
|
Package resolver defines APIs for name resolution in gRPC. |
dns
Package dns implements a dns resolver to be installed as the default resolver in grpc.
|
Package dns implements a dns resolver to be installed as the default resolver in grpc. |
manual
Package manual defines a resolver that can be used to manually send resolved addresses to ClientConn.
|
Package manual defines a resolver that can be used to manually send resolved addresses to ClientConn. |
passthrough
Package passthrough implements a pass-through resolver.
|
Package passthrough implements a pass-through resolver. |
Package stats is for collecting and reporting various network and RPC stats.
|
Package stats is for collecting and reporting various network and RPC stats. |
Package status implements errors returned by gRPC.
|
Package status implements errors returned by gRPC. |
stress
|
|
client
client starts an interop client to do stress test and a metrics server to report qps.
|
client starts an interop client to do stress test and a metrics server to report qps. |
Package tap defines the function handles which are executed on the transport layer of gRPC-Go and related information.
|
Package tap defines the function handles which are executed on the transport layer of gRPC-Go and related information. |
bufconn
Package bufconn provides a net.Conn implemented by a buffer and related dialing and listening functionality.
|
Package bufconn provides a net.Conn implemented by a buffer and related dialing and listening functionality. |