transport

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Apr 28, 2017 License: BSD-3-Clause Imports: 29 Imported by: 0

Documentation

Overview

Package transport defines and implements message oriented communication channel to complete various transactions (e.g., an RPC).

Index

Constants

This section is empty.

Variables

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

	// 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{}

	// GetGoAwayReason returns the reason why GoAway frame was received.
	GetGoAwayReason() GoAwayReason
}

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 added in v1.0.2 

func (e ConnectionError) Origin() error

Origin returns the original error of this connection error.

func (ConnectionError) Temporary added in v1.0.2 

func (e ConnectionError) Temporary() bool

Temporary indicates if this connection error is temporary or fatal.

type GoAwayReason added in v1.3.0 

type GoAwayReason uint8

GoAwayReason contains the reason for the GoAway frame received. 

const (
	// Invalid indicates that no GoAway frame is received.
	Invalid GoAwayReason = 0
	// NoReason is the default value when GoAway frame is received.
	NoReason GoAwayReason = 1
	// TooManyPings indicates that a GoAway frame with ErrCodeEnhanceYourCalm
	// was recieved and that the debug data said "too_many_pings".
	TooManyPings 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 added in v1.0.5 

type ServerConfig struct {
	MaxStreams      uint32
	AuthInfo        credentials.AuthInfo
	InTapHandle     tap.ServerInHandle
	StatsHandler    stats.Handler
	KeepaliveParams keepalive.ServerParameters
	KeepalivePolicy keepalive.EnforcementPolicy
}

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, 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()
}

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 

func StreamFromContext(ctx context.Context) (s *Stream, ok bool)

StreamFromContext returns the stream saved in ctx.

func (*Stream) BytesReceived added in v1.3.0 

func (s *Stream) BytesReceived() bool

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

func (*Stream) BytesSent added in v1.3.0 

func (s *Stream) BytesSent() bool

BytesSent indicates whether any bytes have been sent on this stream.

func (*Stream) Context 

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

Context returns the context of the stream.

func (*Stream) Done added in v1.0.2 

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 added in v1.0.2 

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 added in v1.2.1 

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

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

func (s *Stream) ServerTransport() ServerTransport

ServerTransport returns the underlying ServerTransport for the stream. The client side stream always returns nil.

func (*Stream) SetHeader added in v1.0.3 

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

SetHeader sets the header metadata. This can be called multiple times. Server side only.

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.

func (*Stream) Status added in v1.3.0 

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

Status returns the status received from the server.

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.

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 added in v1.0.3 

type TargetInfo struct {
	Addr     string
	Metadata interface{}
}

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

Source Files

View all Source files

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.