var (
// ErrIllegalHeaderWrite indicates that setting header is illegal because of
// the stream's state.
ErrIllegalHeaderWrite = status.Error(codes.Internal, "transport: SendHeader called multiple times")
// ErrHeaderListSizeLimitViolation indicates that the header list size is larger
// than the limit set by peer.
ErrHeaderListSizeLimitViolation = status.Error(codes.Internal, "transport: trying to send header list size larger than the limit set by peer")
)
var (
// ErrConnClosing indicates that the transport is closing.
ErrConnClosing = connectionErrorf(true, nil, "transport is closing")
)
var (
// HTTPStatusConvTab is the HTTP status code to gRPC error code conversion table.
HTTPStatusConvTab = map[int]codes.Code{
http.StatusBadRequest: codes.Internal,
http.StatusUnauthorized: codes.Unauthenticated,
http.StatusForbidden: codes.PermissionDenied,
http.StatusNotFound: codes.Unimplemented,
http.StatusTooManyRequests: codes.Unavailable,
http.StatusBadGateway: codes.Unavailable,
http.StatusServiceUnavailable: codes.Unavailable,
http.StatusGatewayTimeout: codes.Unavailable,
}
)
MaxStreamID is the upper bound for the stream ID before the current transport gracefully closes and new transport is created for subsequent RPCs. This is set to 75% of 2^31-1. Streams are identified with an unsigned 31-bit integer. It's exported so that tests can override it.
var MaxStreamID = uint32(math.MaxInt32 * 3 / 4)
func ContextErr(err error) error
ContextErr converts the error from context package into a status error.
func GetConnection(ctx context.Context) net.Conn
GetConnection gets the connection from the context.
func SetConnection(ctx context.Context, conn net.Conn) context.Context
SetConnection adds the connection to the context to be able to get information about the destination ip and port for an incoming RPC. This also allows any unary or streaming interceptors to see the connection.
CallHdr carries the information of a particular RPC.
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
// 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
PreviousAttempts int // value of grpc-previous-rpc-attempts header to set
DoneFunc func() // called when the stream is finished
}
ClientTransport is the common interface for all gRPC client-side transport implementations.
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(err error)
// GracefulClose starts to tear down the transport: the transport will stop
// accepting new RPCs and NewStream will return error. Once all streams are
// finished, the transport will close.
//
// It does not block.
GracefulClose()
// 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, along
// with a human readable string with debug info.
GetGoAwayReason() (GoAwayReason, string)
// RemoteAddr returns the remote network address.
RemoteAddr() net.Addr
// IncrMsgSent increments the number of message sent through this transport.
IncrMsgSent()
// IncrMsgRecv increments the number of message received through this transport.
IncrMsgRecv()
}
func NewClientTransport(connectCtx, ctx context.Context, addr resolver.Address, opts ConnectOptions, onClose func(GoAwayReason)) (ClientTransport, error)
NewClientTransport establishes the transport with the required ConnectOptions and returns it to the caller.
ConnectOptions covers all relevant options for communicating with the server.
type ConnectOptions struct {
// UserAgent is the application user agent.
UserAgent 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. Only one of TransportCredentials and CredsBundle is non-nil.
TransportCredentials credentials.TransportCredentials
// CredsBundle is the credentials bundle to be used. Only one of
// TransportCredentials and CredsBundle is non-nil.
CredsBundle credentials.Bundle
// KeepaliveParams stores the keepalive parameters.
KeepaliveParams keepalive.ClientParameters
// StatsHandlers stores the handler for stats.
StatsHandlers []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
// SharedWriteBuffer indicates whether connections should reuse write buffer
SharedWriteBuffer bool
// ChannelzParent sets the addrConn id which initiated the creation of this client transport.
ChannelzParent *channelz.SubChannel
// MaxHeaderListSize sets the max (uncompressed) size of header list that is prepared to be received.
MaxHeaderListSize *uint32
// UseProxy specifies if a proxy should be used.
UseProxy bool
}
ConnectionError is an error that results in the termination of the entire connection and the retry of all the active streams.
type ConnectionError struct {
Desc string
// contains filtered or unexported fields
}
func (e ConnectionError) Error() string
func (e ConnectionError) Origin() error
Origin returns the original error of this connection error.
func (e ConnectionError) Temporary() bool
Temporary indicates if this connection error is temporary or fatal.
func (e ConnectionError) Unwrap() error
Unwrap returns the original error of this connection error or nil when the origin is nil.
GoAwayReason contains the reason for the GoAway frame received.
type GoAwayReason uint8
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
)
NewStreamError wraps an error and reports additional information. Typically NewStream errors result in transparent retry, as they mean nothing went onto the wire. However, there are two notable exceptions:
type NewStreamError struct {
Err error
AllowTransparentRetry bool
}
func (e NewStreamError) Error() string
Options provides additional hints and information for message transmission.
type Options struct {
// Last indicates whether this write is the last piece for
// this stream.
Last bool
}
ServerConfig consists of all the configurations to establish a server transport.
type ServerConfig struct {
MaxStreams uint32
ConnectionTimeout time.Duration
Credentials credentials.TransportCredentials
InTapHandle tap.ServerInHandle
StatsHandlers []stats.Handler
KeepaliveParams keepalive.ServerParameters
KeepalivePolicy keepalive.EnforcementPolicy
InitialWindowSize int32
InitialConnWindowSize int32
WriteBufferSize int
ReadBufferSize int
SharedWriteBuffer bool
ChannelzParent *channelz.Server
MaxHeaderListSize *uint32
HeaderTableSize *uint32
}
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.
type ServerTransport interface {
// HandleStreams receives incoming streams using the given handler.
HandleStreams(context.Context, func(*Stream))
// 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(err error)
// Peer returns the peer of the server transport.
Peer() *peer.Peer
// Drain notifies the client this ServerTransport stops accepting new RPCs.
Drain(debugData string)
// IncrMsgSent increments the number of message sent through this transport.
IncrMsgSent()
// IncrMsgRecv increments the number of message received through this transport.
IncrMsgRecv()
}
func NewServerHandlerTransport(w http.ResponseWriter, r *http.Request, stats []stats.Handler) (ServerTransport, error)
NewServerHandlerTransport returns a ServerTransport handling gRPC from inside an http.Handler, or writes an HTTP error to w and returns an error. It requires that the http Server supports HTTP/2.
func NewServerTransport(conn net.Conn, config *ServerConfig) (_ ServerTransport, err error)
NewServerTransport creates a http2 transport with conn and configuration options from config.
It returns a non-nil transport and a nil error on success. On failure, it returns a nil transport and a non-nil error. For a special case where the underlying conn gets closed before the client preface could be read, it returns a nil transport and a nil error.
Stream represents an RPC in the transport layer.
type Stream struct {
// contains filtered or unexported fields
}
func (s *Stream) BytesReceived() bool
BytesReceived indicates whether any bytes have been received on this stream.
func (s *Stream) ClientAdvertisedCompressors() []string
ClientAdvertisedCompressors returns the compressor names advertised by the client via grpc-accept-encoding header.
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 (s *Stream) Context() context.Context
Context returns the context of the stream.
func (s *Stream) Done() <-chan struct{}
Done returns a channel which is closed when it receives the final status from the server.
func (s *Stream) GoString() string
GoString is implemented by Stream so context.String() won't race when printing %#v.
func (s *Stream) Header() (metadata.MD, error)
Header returns the header metadata of the stream.
On client side, it 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.
On server side, it returns the out header after t.WriteHeader is called. It does not block and must not be called until after WriteHeader.
func (s *Stream) HeaderWireLength() int
HeaderWireLength returns the size of the headers of the stream as received from the wire. Valid only on the server.
func (s *Stream) Method() string
Method returns the method for the stream.
func (s *Stream) Read(p []byte) (n int, err error)
Read reads all p bytes from the wire for this stream.
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 (s *Stream) SendCompress() string
SendCompress returns the send compressor name.
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 (s *Stream) SetContext(ctx context.Context)
SetContext sets the context of the stream. This will be deleted once the stats handler callouts all move to gRPC layer.
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 (s *Stream) SetSendCompress(name string) error
SetSendCompress sets the compression algorithm to the stream.
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 (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, after Done() is closed.
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 (s *Stream) TrailersOnly() bool
TrailersOnly blocks until a header or trailers-only frame is received and then returns true if the stream was trailers-only. If the stream ends before headers are received, returns true, nil. Client-side only.
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.
| Name | Synopsis |
|---|---|
| .. | |