Documentation

Overview

    Package transport defines and implements message oriented communication channel to complete various transactions (e.g., an RPC). It is meant for grpc-internal usage and is not intended to be imported directly by users.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var (
    	// ErrConnClosing indicates that the transport is closing.
    	ErrConnClosing = connectionErrorf(true, nil, "transport is closing")
    )
    View Source
    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
      
      	// SendCompress specifies the compression algorithm applied on
      	// outbound message.
      	SendCompress string
      
      	// Creds specifies credentials.PerRPCCredentials for a call.
      	Creds credentials.PerRPCCredentials
      
      	// Flush indicates whether a new stream command should be sent
      	// to the peer without waiting for the first data. This is
      	// only a hint.
      	// If it's true, the transport may modify the flush decision
      	// for performance purposes.
      	// If it's false, new stream will never be flushed.
      	Flush bool
      
      	// ContentSubtype specifies the content-subtype for a request. For example, a
      	// content-subtype of "proto" will result in a content-type of
      	// "application/grpc+proto". The value of ContentSubtype must be all
      	// lowercase, otherwise the behavior is undefined. See
      	// https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests
      	// for more details.
      	ContentSubtype string
      }

        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, hdr []byte, 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 ClientTransport
        	// receives the draining signal from the server (e.g., GOAWAY frame in
        	// HTTP/2).
        	GoAway() <-chan struct{}
        
        	// GetGoAwayReason returns the reason why GoAway frame was received.
        	GetGoAwayReason() GoAwayReason
        
        	// IncrMsgSent increments the number of message sent through this transport.
        	IncrMsgSent()
        
        	// IncrMsgRecv increments the number of message received through this transport.
        	IncrMsgRecv()
        }

          ClientTransport is the common interface for all gRPC client-side transport implementations.

          func NewClientTransport

          func NewClientTransport(connectCtx, ctx context.Context, target TargetInfo, opts ConnectOptions, onSuccess func()) (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
            	// InitialWindowSize sets the initial window size for a stream.
            	InitialWindowSize int32
            	// InitialConnWindowSize sets the initial window size for a connection.
            	InitialConnWindowSize int32
            	// WriteBufferSize sets the size of write buffer which in turn determines how much data can be batched before it's written on the wire.
            	WriteBufferSize int
            	// ReadBufferSize sets the size of read buffer, which in turn determines how much data can be read at most for one read syscall.
            	ReadBufferSize int
            	// ChannelzParentID sets the addrConn id which initiate the creation of this client transport.
            	ChannelzParentID int64
            }

              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 GoAwayReason

                    type GoAwayReason uint8

                      GoAwayReason contains the reason for the GoAway frame received.

                      const (
                      	// GoAwayInvalid indicates that no GoAway frame is received.
                      	GoAwayInvalid GoAwayReason = 0
                      	// GoAwayNoReason is the default value when GoAway frame is received.
                      	GoAwayNoReason GoAwayReason = 1
                      	// GoAwayTooManyPings indicates that a GoAway frame with
                      	// ErrCodeEnhanceYourCalm was received and that the debug data said
                      	// "too_many_pings".
                      	GoAwayTooManyPings GoAwayReason = 2
                      )

                      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
                        	KeepaliveParams       keepalive.ServerParameters
                        	KeepalivePolicy       keepalive.EnforcementPolicy
                        	InitialWindowSize     int32
                        	InitialConnWindowSize int32
                        	WriteBufferSize       int
                        	ReadBufferSize        int
                        	ChannelzParentID      int64
                        }

                          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, hdr []byte, 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, st *status.Status) 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()
                          
                          	// IncrMsgSent increments the number of message sent through this transport.
                          	IncrMsgSent()
                          
                          	// IncrMsgRecv increments the number of message received through this transport.
                          	IncrMsgRecv()
                          }

                            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, stats stats.Handler) (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 (*Stream) BytesReceived

                                  func (s *Stream) BytesReceived() bool

                                    BytesReceived indicates whether any bytes have been received on this stream.

                                    func (*Stream) ContentSubtype

                                    func (s *Stream) ContentSubtype() string

                                      ContentSubtype returns the content-subtype for a request. For example, a content-subtype of "proto" will result in a content-type of "application/grpc+proto". This will always be lowercase. See https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests for more details.

                                      func (*Stream) Context

                                      func (s *Stream) Context() context.Context

                                        Context returns the context of the stream.

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

                                          func (s *Stream) GoString() string

                                            GoString is implemented by Stream so context.String() won't race when printing %#v.

                                            func (*Stream) Header

                                            func (s *Stream) Header() (metadata.MD, error)

                                              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 canceled/expired.

                                              func (*Stream) Method

                                              func (s *Stream) Method() string

                                                Method returns the method for the stream.

                                                func (*Stream) Read

                                                func (s *Stream) Read(p []byte) (n int, err error)

                                                  Read reads all p bytes from the wire for this stream.

                                                  func (*Stream) RecvCompress

                                                  func (s *Stream) RecvCompress() string

                                                    RecvCompress returns the compression algorithm applied to the inbound message. It is empty string if there is no compression applied.

                                                    func (*Stream) SendHeader

                                                    func (s *Stream) SendHeader(md metadata.MD) error

                                                      SendHeader sends the given header metadata. The given metadata is combined with any metadata set by previous calls to SetHeader and then written to the transport stream.

                                                      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

                                                        func (s *Stream) SetHeader(md metadata.MD) error

                                                          SetHeader sets the header metadata. This can be called multiple times. Server side only. This should not be called in parallel to other data writes.

                                                          func (*Stream) SetSendCompress

                                                          func (s *Stream) SetSendCompress(str string)

                                                            SetSendCompress sets the compression algorithm to the stream.

                                                            func (*Stream) SetTrailer

                                                            func (s *Stream) SetTrailer(md metadata.MD) error

                                                              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. This should not be called parallel to other data writes.

                                                              func (*Stream) Status

                                                              func (s *Stream) Status() *status.Status

                                                                Status returns the status received from the server. Status can be read safely only after the stream has ended, that is, read or write has returned io.EOF.

                                                                func (*Stream) Trailer

                                                                func (s *Stream) Trailer() metadata.MD

                                                                  Trailer returns the cached trailer metedata. Note that if it is not called after the entire stream is done, it could return an empty MD. Client side only. It can be safely read only after stream has ended that is either read or write have returned io.EOF.

                                                                  func (*Stream) Unprocessed

                                                                  func (s *Stream) Unprocessed() bool

                                                                    Unprocessed indicates whether the server did not process this stream -- i.e. it sent a refused stream or GOAWAY including this stream ID.

                                                                    type StreamError

                                                                    type StreamError struct {
                                                                    	Code codes.Code
                                                                    	Desc string
                                                                    }

                                                                      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{}
                                                                        	Authority string
                                                                        }

                                                                          TargetInfo contains the information of the target such as network address and metadata.