grpc

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 23, 2016 License: BSD-3-Clause, Apache-2.0 Imports: 29 Imported by: 0

README

#gRPC-Go

Build Status GoDoc

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 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.5 or later .

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 www.grpc.io for more information about gRPC.

Index

Constants

View Source 
const SupportPackageIsVersion1 = true

SupportPackageIsVersion1 is referenced from generated protocol buffer files to assert that that code is compatible with this version of the grpc package.

This constant may be renamed in the future if a change in the generated code requires a synchronised update of grpc-go and protoc-gen-go. This constant should not be referenced from any other code.

Variables

View Source 
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 explicitly
	// 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 information
	// (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")
)
View Source 
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.

View Source 
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 

func Code(err error) codes.Code

Code returns the error code for err if it was produced by the rpc system. Otherwise, it returns codes.Unknown.

func ErrorDesc added in v0.4.0 

func ErrorDesc(err error) string

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 

func Errorf(c codes.Code, format string, a ...interface{}) error

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 sends the RPC request on the wire and returns after response is received. Invoke is called by generated code. Also users can call Invoke directly when it is really needed in their use cases.

func SendHeader 

func SendHeader(ctx context.Context, md metadata.MD) error

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.

func SetTrailer 

func SetTrailer(ctx context.Context, md metadata.MD) error

SetTrailer sets the trailer metadata that will be sent when an RPC returns. 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(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 added in v0.4.0 

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 added in v0.4.0 

func NewGZIPCompressor() Compressor

NewGZIPCompressor creates a Compressor based on GZIP.

type Conn added in v0.4.0 

type Conn struct {
	// contains filtered or unexported fields
}

Conn is a client connection to a single destination.

func NewConn added in v0.4.0 

func NewConn(cc *ClientConn) (*Conn, error)

NewConn creates a Conn.

func (*Conn) Close added in v0.4.0 

func (cc *Conn) Close() error

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 added in v0.4.0 

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 added in v0.4.0 

func (cc *Conn) State() ConnectivityState

State returns the connectivity state of the Conn

func (*Conn) Wait added in v0.4.0 

func (cc *Conn) Wait(ctx context.Context) (transport.ClientTransport, error)

Wait blocks until i) the new transport is up or ii) ctx is done or iii) cc is closed.

func (*Conn) WaitForStateChange added in v0.4.0 

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 added in v0.4.0 

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 added in v0.4.0 

func NewGZIPDecompressor() Decompressor

NewGZIPDecompressor creates a Decompressor based on GZIP.

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 added in v0.4.0 

func WithCompressor(cp Compressor) DialOption

WithCompressor returns a DialOption which sets a CompressorGenerator for generating message compressor.

func WithDecompressor added in v0.4.0 

func WithDecompressor(dc Decompressor) DialOption

WithDecompressor returns a DialOption which sets a DecompressorGenerator for generating message decompressor.

func WithDialer 

func WithDialer(f func(addr string, timeout time.Duration) (net.Conn, error)) DialOption

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 added in v0.4.0 

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 added in v0.4.0 

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 added in v0.4.0 

func NewUnicastNamingPicker(r naming.Resolver) Picker

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 

func (s *Server) Serve(lis net.Listener) error

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. Service returns when lis.Accept fails.

func (*Server) ServeHTTP added in v0.4.0 

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Server) Stop 

func (s *Server) Stop()

Stop stops the gRPC server. It immediately closes all open connections and listeners. It cancels all active RPCs on the server side and the corresponding pending RPCs on the client side will get notified by connection errors.

type ServerOption 

type ServerOption func(*options)

A ServerOption sets options.

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 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 RPCCompressor added in v0.4.0 

func RPCCompressor(cp Compressor) ServerOption

func RPCDecompressor added in v0.4.0 

func RPCDecompressor(dc Decompressor) ServerOption

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. Also Users can call SendMsg
	// directly when it is really needed in their use cases.
	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 stream and 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

View all 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.
client
grpc_testing
Package grpc_testing is a generated protocol buffer package.
 Package grpc_testing is a generated protocol buffer package.
server
stats
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/greeter_client
helloworld/greeter_server
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_v1
Package grpc_health_v1 is a generated protocol buffer package.
 Package grpc_health_v1 is a generated protocol buffer package.
Package internal contains gRPC-internal code for testing, to avoid polluting the godoc of the top-level grpc package.
 Package internal contains gRPC-internal code for testing, to avoid polluting the godoc of the top-level grpc package.
client
grpc_testing
Package grpc_testing is a generated protocol buffer package.
 Package grpc_testing is a generated protocol buffer package.
server
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).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.