Documentation ¶
Overview ¶
Package transport defines and implements message oriented communication channel to complete various transactions (e.g., an RPC).
Index ¶
- Variables
- type CallHdr
- type ClientTransport
- type ConnectOptions
- type ConnectionError
- type Options
- type ServerConfig
- type ServerTransport
- type Stream
- func (s *Stream) Context() context.Context
- func (s *Stream) Done() <-chan struct{}
- func (s *Stream) GoAway() <-chan struct{}
- func (s *Stream) GoString() string
- func (s *Stream) Header() (metadata.MD, error)
- func (s *Stream) Method() string
- func (s *Stream) Read(p []byte) (n int, err error)
- func (s *Stream) RecvCompress() string
- func (s *Stream) ServerTransport() ServerTransport
- func (s *Stream) SetHeader(md metadata.MD) error
- func (s *Stream) SetSendCompress(str string)
- func (s *Stream) SetTrailer(md metadata.MD) error
- func (s *Stream) StatusCode() codes.Code
- func (s *Stream) StatusDesc() string
- func (s *Stream) Trailer() metadata.MD
- type StreamError
- type TargetInfo
Constants ¶
This section is empty.
Variables ¶
var ( // ErrConnClosing indicates that the transport is closing. ErrConnClosing = connectionErrorf(true, nil, "transport is closing") // ErrStreamDrain indicates that the stream is rejected by the server because // the server stops accepting new RPCs. ErrStreamDrain = streamErrorf(codes.Unavailable, "the server stops accepting new RPCs") )
var ErrIllegalHeaderWrite = errors.New("transport: the stream is done or WriteHeader was already called")
ErrIllegalHeaderWrite indicates that setting header is illegal because of the stream's state.
Functions ¶
This section is empty.
Types ¶
type CallHdr ¶
type CallHdr struct { // Host specifies the peer's host. Host string // Method specifies the operation to perform. Method string // RecvCompress specifies the compression algorithm applied on // inbound messages. RecvCompress string // SendCompress specifies the compression algorithm applied on // outbound message. SendCompress string // Flush indicates whether a new stream command should be sent // to the peer without waiting for the first data. This is // only a hint. The transport may modify the flush decision // for performance purposes. Flush bool }
CallHdr carries the information of a particular RPC.
type ClientTransport ¶
type ClientTransport interface { // Close tears down this transport. Once it returns, the transport // should not be accessed any more. The caller must make sure this // is called only once. Close() error // GracefulClose starts to tear down the transport. It stops accepting // new RPCs and wait the completion of the pending RPCs. GracefulClose() error // Write sends the data for the given stream. A nil stream indicates // the write is to be performed on the transport as a whole. Write(s *Stream, data []byte, opts *Options) error // NewStream creates a Stream for an RPC. NewStream(ctx context.Context, callHdr *CallHdr) (*Stream, error) // CloseStream clears the footprint of a stream when the stream is // not needed any more. The err indicates the error incurred when // CloseStream is called. Must be called when a stream is finished // unless the associated transport is closing. CloseStream(stream *Stream, err error) // Error returns a channel that is closed when some I/O error // happens. Typically the caller should have a goroutine to monitor // this in order to take action (e.g., close the current transport // and create a new one) in error case. It should not return nil // once the transport is initiated. Error() <-chan struct{} // GoAway returns a channel that is closed when ClientTranspor // receives the draining signal from the server (e.g., GOAWAY frame in // HTTP/2). GoAway() <-chan struct{} }
ClientTransport is the common interface for all gRPC client-side transport implementations.
func NewClientTransport ¶
func NewClientTransport(ctx context.Context, target TargetInfo, opts ConnectOptions) (ClientTransport, error)
NewClientTransport establishes the transport with the required ConnectOptions and returns it to the caller.
type ConnectOptions ¶
type ConnectOptions struct { // UserAgent is the application user agent. UserAgent string // Authority is the :authority pseudo-header to use. This field has no effect if // TransportCredentials is set. Authority string // Dialer specifies how to dial a network address. Dialer func(context.Context, string) (net.Conn, error) // FailOnNonTempDialError specifies if gRPC fails on non-temporary dial errors. FailOnNonTempDialError bool // PerRPCCredentials stores the PerRPCCredentials required to issue RPCs. PerRPCCredentials []credentials.PerRPCCredentials // TransportCredentials stores the Authenticator required to setup a client connection. TransportCredentials credentials.TransportCredentials // KeepaliveParams stores the keepalive parameters. KeepaliveParams keepalive.ClientParameters // StatsHandler stores the handler for stats. StatsHandler stats.Handler }
ConnectOptions covers all relevant options for communicating with the server.
type ConnectionError ¶
type ConnectionError struct { Desc string // contains filtered or unexported fields }
ConnectionError is an error that results in the termination of the entire connection and the retry of all the active streams.
func (ConnectionError) Error ¶
func (e ConnectionError) Error() string
func (ConnectionError) Origin ¶
func (e ConnectionError) Origin() error
Origin returns the original error of this connection error.
func (ConnectionError) Temporary ¶
func (e ConnectionError) Temporary() bool
Temporary indicates if this connection error is temporary or fatal.
type Options ¶
type Options struct { // Last indicates whether this write is the last piece for // this stream. Last bool // Delay is a hint to the transport implementation for whether // the data could be buffered for a batching write. The // Transport implementation may ignore the hint. Delay bool }
Options provides additional hints and information for message transmission.
type ServerConfig ¶
type ServerConfig struct { MaxStreams uint32 AuthInfo credentials.AuthInfo InTapHandle tap.ServerInHandle StatsHandler stats.Handler }
ServerConfig consists of all the configurations to establish a server transport.
type ServerTransport ¶
type ServerTransport interface { // HandleStreams receives incoming streams using the given handler. HandleStreams(func(*Stream), func(context.Context, string) context.Context) // WriteHeader sends the header metadata for the given stream. // WriteHeader may not be called on all streams. WriteHeader(s *Stream, md metadata.MD) error // Write sends the data for the given stream. // Write may not be called on all streams. Write(s *Stream, data []byte, opts *Options) error // WriteStatus sends the status of a stream to the client. // WriteStatus is the final call made on a stream and always // occurs. WriteStatus(s *Stream, statusCode codes.Code, statusDesc string) error // Close tears down the transport. Once it is called, the transport // should not be accessed any more. All the pending streams and their // handlers will be terminated asynchronously. Close() error // RemoteAddr returns the remote network address. RemoteAddr() net.Addr // Drain notifies the client this ServerTransport stops accepting new RPCs. Drain() }
ServerTransport is the common interface for all gRPC server-side transport implementations.
Methods may be called concurrently from multiple goroutines, but Write methods for a given Stream will be called serially.
func NewServerHandlerTransport ¶
func NewServerHandlerTransport(w http.ResponseWriter, r *http.Request) (ServerTransport, error)
NewServerHandlerTransport returns a ServerTransport handling gRPC from inside an http.Handler. It requires that the http Server supports HTTP/2.
func NewServerTransport ¶
func NewServerTransport(protocol string, conn net.Conn, config *ServerConfig) (ServerTransport, error)
NewServerTransport creates a ServerTransport with conn or non-nil error if it fails.
type Stream ¶
type Stream struct {
// contains filtered or unexported fields
}
Stream represents an RPC in the transport layer.
func StreamFromContext ¶
StreamFromContext returns the stream saved in ctx.
func (*Stream) Done ¶
func (s *Stream) Done() <-chan struct{}
Done returns a chanel which is closed when it receives the final status from the server.
func (*Stream) GoAway ¶
func (s *Stream) GoAway() <-chan struct{}
GoAway returns a channel which is closed when the server sent GoAways signal before this stream was initiated.
func (*Stream) GoString ¶
GoString is implemented by Stream so context.String() won't race when printing %#v.
func (*Stream) Header ¶
Header acquires the key-value pairs of header metadata once it is available. It blocks until i) the metadata is ready or ii) there is no header metadata or iii) the stream is cancelled/expired.
func (*Stream) Read ¶
Read reads all the data available for this Stream from the transport and passes them into the decoder, which converts them into a gRPC message stream. The error is io.EOF when the stream is done or another non-nil error if the stream broke.
func (*Stream) RecvCompress ¶
RecvCompress returns the compression algorithm applied to the inbound message. It is empty string if there is no compression applied.
func (*Stream) ServerTransport ¶
func (s *Stream) ServerTransport() ServerTransport
ServerTransport returns the underlying ServerTransport for the stream. The client side stream always returns nil.
func (*Stream) SetHeader ¶
SetHeader sets the header metadata. This can be called multiple times. Server side only.
func (*Stream) SetSendCompress ¶
SetSendCompress sets the compression algorithm to the stream.
func (*Stream) SetTrailer ¶
SetTrailer sets the trailer metadata which will be sent with the RPC status by the server. This can be called multiple times. Server side only.
func (*Stream) StatusCode ¶
StatusCode returns statusCode received from the server.
func (*Stream) StatusDesc ¶
StatusDesc returns statusDesc received from the server.
type StreamError ¶
StreamError is an error that only affects one stream within a connection.
func ContextErr ¶
func ContextErr(err error) StreamError
ContextErr converts the error from context package into a StreamError.
func (StreamError) Error ¶
func (e StreamError) Error() string
type TargetInfo ¶
type TargetInfo struct { Addr string Metadata interface{} }
TargetInfo contains the information of the target such as network address and metadata.