grpc

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Jun 22, 2016 License: BSD-3-Clause, Apache-2.0 Imports: 26 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 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

Constants

This section is empty.

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 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")
)
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 

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 is called by the generated code. It sends the RPC request on the wire and returns after response is received.

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 

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 Conn 

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

Conn is a client connection to a single destination.

func NewConn 

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

NewConn creates a Conn.

func (*Conn) Close 

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 

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 

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 

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 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(cp Compressor) DialOption

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

func WithDecompressor 

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 

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 

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

func RPCCompressor(cp Compressor) ServerOption

func RPCDecompressor 

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.
	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

View all Source files

Directories

Path Synopsis
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.
Package grpclog defines logging for grpc.
 Package grpclog defines logging for grpc.
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 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.