sidechannel

Documentation

Index

• Variables
• func NewClientHandshaker(logger *logrus.Entry, registry *Registry) client.Handshaker
• func NewStreamProxy(registry *Registry) grpc.StreamClientInterceptor
• func NewUnaryProxy(registry *Registry) grpc.UnaryClientInterceptor
• type ClientConn
  • func (cc *ClientConn) CloseWrite() error
  • func (cc *ClientConn) Read(b []byte) (n int, err error)
  • func (cc *ClientConn) Write(p []byte) (int, error)
• type Registry
  • func NewRegistry() *Registry
  • func (s *Registry) Register(callback func(*ClientConn) error) *Waiter
• type ServerConn
  • func OpenSidechannel(ctx context.Context) (_ *ServerConn, err error)
  • func (cc *ServerConn) Close() error
  • func (cc *ServerConn) Read(p []byte) (n int, err error)
  • func (cc *ServerConn) Write(b []byte) (n int, err error)
• type ServerHandshaker
  • func NewServerHandshaker(registry *Registry) *ServerHandshaker
  • func (s *ServerHandshaker) Handshake(conn net.Conn, authInfo credentials.AuthInfo) (net.Conn, credentials.AuthInfo, error)
  • func (s *ServerHandshaker) Magic() string
• type Waiter
  • func RegisterSidechannel(ctx context.Context, registry *Registry, callback func(*ClientConn) error) (context.Context, *Waiter)
  • func (w *Waiter) Close() error

Variables

var ErrCallbackDidNotRun = errors.New("sidechannel: callback de-registered without having run")

ErrCallbackDidNotRun indicates that a sidechannel callback was de-registered without having run. This can happen if the server chose not to use the sidechannel.

Functions

func NewClientHandshaker

func NewClientHandshaker(logger *logrus.Entry, registry *Registry) client.Handshaker

NewClientHandshaker is used to enable sidechannel support on outbound gRPC connections.

func NewStreamProxy

func NewStreamProxy(registry *Registry) grpc.StreamClientInterceptor

NewStreamProxy creates a gRPC client middleware that proxies sidechannels.

func NewUnaryProxy

func NewUnaryProxy(registry *Registry) grpc.UnaryClientInterceptor

NewUnaryProxy creates a gRPC client middleware that proxies sidechannels.

Types

type ClientConn

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

ClientConn is a wrapper around net.Conn with the support of half-closed capacity for sidechannel. This struct is expected to use by sidechannel's client only.

func (*ClientConn) CloseWrite

func (cc *ClientConn) CloseWrite() error

CloseWrite shuts down the writing side of the connection. After this call, any read operations from the server return EOF. The reading side is still functional so that the server is still able to write back to the client. Any attempt to write into a half-closed connection returns an error.

func (*ClientConn) Read

func (cc *ClientConn) Read(b []byte) (n int, err error)

Read reads data from the connection. This method fallbacks to underlying connection without any modificiation.

func (*ClientConn) Write

func (cc *ClientConn) Write(p []byte) (int, error)

Write writes len(p) bytes from p to the underlying data stream. It returns the number of bytes written from p and any error encountered that caused the write to stop early. This method overrides Write() to wrap the writing data into a frame. The frame is then extracted and read by ServerConn.Read().

type Registry

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

Registry manages sidechannel connections. It allows the RPC handlers to wait for the secondary incoming connection made by the client.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns a new Registry instance

func (*Registry) Register

func (s *Registry) Register(callback func(*ClientConn) error) *Waiter

Register registers the caller into the waiting list. The caller must provide a callback function. The caller receives a waiter instance. After the connection arrives, the callback function is executed with arrived connection in a new goroutine. The caller receives execution result via waiter.Wait().

type ServerConn

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

ServerConn is a wrapper around net.Conn with the support of half-closed capacity for sidechannel. This struct is expected to be used by sidechannel's server only.

func OpenSidechannel

func OpenSidechannel(ctx context.Context) (_ *ServerConn, err error)

OpenSidechannel opens a sidechannel connection from the stream opener extracted from the current peer connection.

func (*ServerConn) Close

func (cc *ServerConn) Close() error

Close closes the connection. This method fallbacks to underlying connection without any modificiation.

func (*ServerConn) Read

func (cc *ServerConn) Read(p []byte) (n int, err error)

Read reads up to len(p) bytes into p. It returns the number of bytes read or any error encountered. This struct overrides Read() to extract the data wrapped in a frame generated by ClientConn.Write().

func (*ServerConn) Write

func (cc *ServerConn) Write(b []byte) (n int, err error)

Write writes data to the connection. This method fallbacks to underlying connection without any modificiation.

type ServerHandshaker

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

ServerHandshaker implements the server-side sidechannel handshake.

func NewServerHandshaker

func NewServerHandshaker(registry *Registry) *ServerHandshaker

NewServerHandshaker creates a new handshaker for sidechannel to embed into listenmux.

func (*ServerHandshaker) Handshake

func (s *ServerHandshaker) Handshake(conn net.Conn, authInfo credentials.AuthInfo) (net.Conn, credentials.AuthInfo, error)

Handshake implements the handshaking logic for sidechannel so that this handshaker reads the sidechannel ID from the wire, and then delegates the connection to the sidechannel registry

func (*ServerHandshaker) Magic

func (s *ServerHandshaker) Magic() string

Magic returns the magic bytes for sidechannel

type Waiter

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

Waiter lets the caller waits until a connection with matched id is pushed into the registry, then execute the callback

func RegisterSidechannel

func RegisterSidechannel(ctx context.Context, registry *Registry, callback func(*ClientConn) error) (context.Context, *Waiter)

RegisterSidechannel registers the caller into the waiting list of the sidechannel registry and injects the sidechannel ID into outgoing metadata. The caller is expected to establish the request with the returned context. The callback is executed automatically when the sidechannel connection arrives. The result is pushed to the error channel of the returned waiter.

func (*Waiter) Close

func (w *Waiter) Close() error

Close de-registers the callback. If the callback got triggered, Close() will return its error return value. If the callback has not started by the time Close() is called, Close() returns ErrCallbackDidNotRun.