README ¶
#gRPC-Go
The Go implementation of gRPC: A high performance, open source, general RPC framework that puts mobile and HTTP/2 first. For more information see the gRPC Quick Start guide.
Installation
To install this package, you need to install Go 1.4 or above and setup your Go workspace on your computer. The simplest way to install the library is to run:
$ go get google.golang.org/grpc
Prerequisites
This requires Go 1.4 or above.
Constraints
The grpc package should only depend on standard Go packages and a small number of exceptions. If your contribution introduces new dependencies which are NOT in the list, you need a discussion with gRPC-Go authors and consultants.
Documentation
See API documentation for package and API descriptions and find examples in the examples directory.
Status
Beta release
Documentation ¶
Overview ¶
Package grpc implements an RPC system called gRPC.
See https://github.com/grpc/grpc for more information about gRPC.
Index ¶
- Variables
- func Code(err error) codes.Code
- func ErrorDesc(err error) string
- func Errorf(c codes.Code, format string, a ...interface{}) error
- func Invoke(ctx context.Context, method string, args, reply interface{}, cc *ClientConn, ...) (err error)
- func SendHeader(ctx context.Context, md metadata.MD) error
- func SetTrailer(ctx context.Context, md metadata.MD) error
- type CallOption
- type ClientConn
- type ClientStream
- type Codec
- type Compressor
- type CompressorGenerator
- type Conn
- type ConnectivityState
- type Decompressor
- type DecompressorGenerator
- type DialOption
- func WithBlock() DialOption
- func WithCodec(c Codec) DialOption
- func WithCompressor(f CompressorGenerator) DialOption
- func WithDecompressor(f DecompressorGenerator) DialOption
- func WithDialer(f func(addr string, timeout time.Duration) (net.Conn, error)) DialOption
- func WithInsecure() DialOption
- func WithPerRPCCredentials(creds credentials.Credentials) DialOption
- func WithPicker(p Picker) DialOption
- func WithTimeout(d time.Duration) DialOption
- func WithTransportCredentials(creds credentials.TransportAuthenticator) DialOption
- func WithUserAgent(s string) DialOption
- type MethodDesc
- type Picker
- type Server
- type ServerOption
- type ServerStream
- type ServiceDesc
- type Stream
- type StreamDesc
Constants ¶
This section is empty.
Variables ¶
var ( // ErrUnspecTarget indicates that the target address is unspecified. ErrUnspecTarget = errors.New("grpc: target is unspecified") // ErrNoTransportSecurity indicates that there is no transport security // being set for ClientConn. Users should either set one or explicityly // call WithInsecure DialOption to disable security. ErrNoTransportSecurity = errors.New("grpc: no transport security set (use grpc.WithInsecure() explicitly or set credentials)") // ErrCredentialsMisuse indicates that users want to transmit security infomation // (e.g., oauth2 token) which requires secure connection on an insecure // connection. ErrCredentialsMisuse = errors.New("grpc: the credentials require transport level security (use grpc.WithTransportAuthenticator() to set)") // ErrClientConnClosing indicates that the operation is illegal because // the session is closing. ErrClientConnClosing = errors.New("grpc: the client connection is closing") // ErrClientConnTimeout indicates that the connection could not be // established or re-established within the specified timeout. ErrClientConnTimeout = errors.New("grpc: timed out trying to connect") )
var EnableTracing = true
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 ( // ErrServerStopped indicates that the operation is now illegal because of // the server being stopped. ErrServerStopped = errors.New("grpc: the server has been stopped") )
Functions ¶
func Code ¶
Code returns the error code for err if it was produced by the rpc system. Otherwise, it returns codes.Unknown.
func ErrorDesc ¶
ErrorDesc returns the error description of err if it was produced by the rpc system. Otherwise, it returns err.Error() or empty string when err is nil.
func Errorf ¶
Errorf returns an error containing an error code and a description; Errorf returns nil if c is OK.
func Invoke ¶
func Invoke(ctx context.Context, method string, args, reply interface{}, cc *ClientConn, opts ...CallOption) (err error)
Invoke is called by the generated code. It sends the RPC request on the wire and returns after response is received.
func SendHeader ¶
SendHeader sends header metadata. It may be called at most once from a unary RPC handler. The ctx is the RPC handler's Context or one derived from it.
Types ¶
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 Header ¶
func Header(md *metadata.MD) CallOption
Header returns a CallOptions that retrieves the header metadata for a unary RPC.
func Trailer ¶
func Trailer(md *metadata.MD) CallOption
Trailer returns a CallOptions that retrieves the trailer metadata for a unary RPC.
type ClientConn ¶
type ClientConn struct {
// contains filtered or unexported fields
}
ClientConn represents a client connection to an RPC service.
func Dial ¶
func Dial(target string, opts ...DialOption) (*ClientConn, error)
Dial creates a client connection the given target.
func (*ClientConn) Close ¶
func (cc *ClientConn) Close() error
Close starts to tear down the ClientConn.
func (*ClientConn) State ¶
func (cc *ClientConn) State() (ConnectivityState, error)
State returns the connectivity state of cc. This is EXPERIMENTAL API.
func (*ClientConn) WaitForStateChange ¶
func (cc *ClientConn) WaitForStateChange(ctx context.Context, sourceState ConnectivityState) (ConnectivityState, error)
WaitForStateChange blocks until the state changes to something other than the sourceState. It returns the new state or error. This is EXPERIMENTAL API.
type ClientStream ¶
type ClientStream interface { // Header returns the header metedata 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. It must be called // after stream.Recv() returns non-nil error (including io.EOF) for // bi-directional streaming and server streaming or stream.CloseAndRecv() // returns for client streaming in order to receive trailer metadata if // present. Otherwise, it could returns an empty MD even though trailer // is present. Trailer() metadata.MD // CloseSend closes the send direction of the stream. It closes the stream // when non-nil error is met. CloseSend() error Stream }
ClientStream defines the interface a client stream has to satify.
func NewClientStream ¶
func NewClientStream(ctx context.Context, desc *StreamDesc, cc *ClientConn, method string, opts ...CallOption) (ClientStream, error)
NewClientStream creates a new Stream for the client side. This is called by generated code.
type Codec ¶
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. The returned // string will be used as part of content type in transmission. String() string }
Codec defines the interface gRPC uses to encode and decode messages.
type Compressor ¶
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.
func NewGZIPCompressor ¶
func NewGZIPCompressor() Compressor
NewGZIPCompressor creates a Compressor based on GZIP.
type CompressorGenerator ¶
type CompressorGenerator func() Compressor
CompressorGenerator defines the function generating a Compressor.
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn is a client connection to a single destination.
func (*Conn) Close ¶
Close starts to tear down the Conn. Returns ErrClientConnClosing if it has been closed (mostly due to dial time-out). TODO(zhaoq): Make this synchronous to avoid unbounded memory consumption in some edge cases (e.g., the caller opens and closes many ClientConn's in a tight loop.
func (*Conn) NotifyReset ¶
func (cc *Conn) NotifyReset()
NotifyReset tries to signal the underlying transport needs to be reset due to for example a name resolution change in flight.
func (*Conn) State ¶
func (cc *Conn) State() ConnectivityState
State returns the connectivity state of the Conn
func (*Conn) Wait ¶
Wait blocks until i) the new transport is up or ii) ctx is done or iii) cc is closed.
func (*Conn) WaitForStateChange ¶
func (cc *Conn) WaitForStateChange(ctx context.Context, sourceState ConnectivityState) (ConnectivityState, error)
WaitForStateChange blocks until the state changes to something other than the sourceState.
type ConnectivityState ¶
type ConnectivityState int
ConnectivityState indicates the state of a client connection.
const ( // Idle indicates the ClientConn is idle. Idle ConnectivityState = iota // Connecting indicates the ClienConn is connecting. Connecting // Ready indicates the ClientConn is ready for work. Ready // TransientFailure indicates the ClientConn has seen a failure but expects to recover. TransientFailure // Shutdown indicates the ClientConn has started shutting down. Shutdown )
func (ConnectivityState) String ¶
func (s ConnectivityState) String() string
type Decompressor ¶
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.
func NewGZIPDecompressor ¶
func NewGZIPDecompressor() Decompressor
NewGZIPDecompressor creates a Decompressor based on GZIP.
type DecompressorGenerator ¶
type DecompressorGenerator func() Decompressor
DecompressorGenerator defines the function generating a Decompressor.
type DialOption ¶
type DialOption func(*dialOptions)
DialOption configures how we set up the connection.
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 WithCodec ¶
func WithCodec(c Codec) DialOption
WithCodec returns a DialOption which sets a codec for message marshaling and unmarshaling.
func WithCompressor ¶
func WithCompressor(f CompressorGenerator) DialOption
WithCompressor returns a DialOption which sets a CompressorGenerator for generating message compressor.
func WithDecompressor ¶
func WithDecompressor(f DecompressorGenerator) DialOption
WithDecompressor returns a DialOption which sets a DecompressorGenerator for generating message decompressor.
func WithDialer ¶
WithDialer returns a DialOption that specifies a function to use for dialing network addresses.
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 WithPerRPCCredentials ¶
func WithPerRPCCredentials(creds credentials.Credentials) DialOption
WithPerRPCCredentials returns a DialOption which sets credentials which will place auth state on each outbound RPC.
func WithPicker ¶
func WithPicker(p Picker) DialOption
WithPicker returns a DialOption which sets a picker for connection selection.
func WithTimeout ¶
func WithTimeout(d time.Duration) DialOption
WithTimeout returns a DialOption that configures a timeout for dialing a client connection.
func WithTransportCredentials ¶
func WithTransportCredentials(creds credentials.TransportAuthenticator) DialOption
WithTransportCredentials returns a DialOption which configures a connection level security credentials (e.g., TLS/SSL).
func WithUserAgent ¶
func WithUserAgent(s string) DialOption
WithUserAgent returns a DialOption that specifies a user agent string for all the RPCs.
type MethodDesc ¶
type MethodDesc struct { MethodName string Handler methodHandler }
MethodDesc represents an RPC service's method specification.
type Picker ¶
type Picker interface { // Init does initial processing for the Picker, e.g., initiate some connections. Init(cc *ClientConn) error // Pick blocks until either a transport.ClientTransport is ready for the upcoming RPC // or some error happens. Pick(ctx context.Context) (transport.ClientTransport, error) // PickAddr picks a peer address for connecting. This will be called repeated for // connecting/reconnecting. PickAddr() (string, error) // State returns the connectivity state of the underlying connections. State() (ConnectivityState, error) // WaitForStateChange blocks until the state changes to something other than // the sourceState. It returns the new state or error. WaitForStateChange(ctx context.Context, sourceState ConnectivityState) (ConnectivityState, error) // Close closes all the Conn's owned by this Picker. Close() error }
Picker picks a Conn for RPC requests. This is EXPERIMENTAL and please do not implement your own Picker for now.
func NewUnicastNamingPicker ¶
NewUnicastNamingPicker creates a Picker to pick addresses from a name resolver to connect.
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) RegisterService ¶
func (s *Server) RegisterService(sd *ServiceDesc, ss interface{})
RegisterService register a service and its implementation to the gRPC server. 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 request and then call the registered handlers to reply to them. Service returns when lis.Accept fails.
func (*Server) Stop ¶
func (s *Server) Stop()
Stop stops the gRPC server. Once Stop returns, the server stops accepting connection requests and closes all the connected connections.
func (*Server) TestingCloseConns ¶
func (s *Server) TestingCloseConns()
TestingCloseConns closes all exiting transports but keeps s.lis accepting new connections. This is for test only now.
type ServerOption ¶
type ServerOption func(*options)
A ServerOption sets options.
func CompressON ¶
func CompressON(f CompressorGenerator) ServerOption
func Creds ¶
func Creds(c credentials.Credentials) 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.
func DecompressON ¶
func DecompressON(f DecompressorGenerator) ServerOption
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.
type ServerStream ¶
type ServerStream interface { // SendHeader sends the header metadata. It should not be called // after SendProto. It fails if called multiple times or if // called after SendProto. SendHeader(metadata.MD) error // SetTrailer sets the trailer metadata which will be sent with the // RPC status. SetTrailer(metadata.MD) Stream }
ServerStream defines the interface a server stream has to satisfy.
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 }
ServiceDesc represents an RPC service's specification.
type Stream ¶
type Stream interface { // Context returns the context for this stream. Context() context.Context // SendMsg blocks until it sends m, the stream is done or the stream // breaks. // On error, it aborts the stream and returns an RPC status on client // side. On server side, it simply returns the error to the caller. // SendMsg is called by generated code. SendMsg(m interface{}) error // RecvMsg blocks until it receives a message or the stream is // done. On client side, it returns io.EOF when the stream is done. On // any other error, it aborts the streama nd returns an RPC status. On // server side, it simply returns the error to the caller. RecvMsg(m interface{}) error }
Stream defines the common interface a client or server stream has to satisfy.
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.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
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. |
grpc_testing
Package grpc_testing is a generated protocol buffer package.
|
Package grpc_testing is a generated protocol buffer package. |
Package codes defines the canonical error codes used by gRPC.
|
Package codes defines the canonical error codes used by gRPC. |
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. |
oauth
Package oauth implements gRPC credentials using OAuth.
|
Package oauth implements gRPC credentials using OAuth. |
examples
|
|
helloworld/helloworld
Package helloworld is a generated protocol buffer package.
|
Package helloworld is a generated protocol buffer package. |
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/routeguide
Package routeguide is a generated protocol buffer package.
|
Package routeguide is a generated protocol buffer package. |
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. |
grpc_health_v1alpha
Package grpc_health_v1alpha is a generated protocol buffer package.
|
Package grpc_health_v1alpha is a generated protocol buffer package. |
grpc_testing
Package grpc_testing is a generated protocol buffer package.
|
Package grpc_testing is a generated protocol buffer package. |
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. |
test
|
|
codec_perf
Package codec_perf is a generated protocol buffer package.
|
Package codec_perf is a generated protocol buffer package. |
grpc_testing
Package grpc_testing is a generated protocol buffer package.
|
Package grpc_testing is a generated protocol buffer package. |
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). |