proxy

Documentation

Overview

Package proxy provides the client side API for working with a proxy server.

If called without a proxy simply acts as a pass though and normal ClientConnInterface.

Index

• type Conn
  • func Dial(proxy string, targets []string, opts ...grpc.DialOption) (*Conn, error)
  • func DialContext(ctx context.Context, proxy string, targets []string, opts ...grpc.DialOption) (*Conn, error)
  • func (p *Conn) Close() error
  • func (p *Conn) Direct() bool
  • func (p *Conn) Invoke(ctx context.Context, method string, args interface{}, reply interface{}, ...) error
  • func (p *Conn) InvokeOneMany(ctx context.Context, method string, args interface{}, opts ...grpc.CallOption) (<-chan *Ret, error)
  • func (p *Conn) NewStream(ctx context.Context, desc *grpc.StreamDesc, method string, ...) (grpc.ClientStream, error)
  • func (p *Conn) Proxy() *grpc.ClientConn
• type Ret

Types

type Conn

type Conn struct {
	// The targets we're proxying for currently.
	Targets []string
	// contains filtered or unexported fields
}

Conn is a grpc.ClientConnInterface which is connected to the proxy converting calls into RPC the proxy understands.

func Dial

func Dial(proxy string, targets []string, opts ...grpc.DialOption) (*Conn, error)

Dial will connect to the given proxy and setup to send RPCs to the listed targets. If proxy is blank and there is only one target this will return a normal grpc connection object (*grpc.ClientConn). Otherwise this will return a *ProxyConn setup to act with the proxy. Targets is a list of normal gRPC style endpoint addresses with an optional dial timeout appended with a semi-colon in time.Duration format. i.e. host[:port][;Ns] for instance to set the dial timeout to N seconds. The proxy value can also specify a dial timeout in the same fashion.

func DialContext

func DialContext(ctx context.Context, proxy string, targets []string, opts ...grpc.DialOption) (*Conn, error)

DialContext is the same as Dial except the context provided can be used to cancel or expire the pending connection. By default dial operations are non-blocking. See grpc.Dial for a complete explanation.

func (*Conn) Close

func (p *Conn) Close() error

Close tears down the ProxyConn and closes all connections to it.

func (*Conn) Direct

func (p *Conn) Direct() bool

Direct indicates whether the proxy is in use or a direct connection is being made.

func (*Conn) Invoke

func (p *Conn) Invoke(ctx context.Context, method string, args interface{}, reply interface{}, opts ...grpc.CallOption) error

Invoke - see grpc.ClientConnInterface

func (*Conn) InvokeOneMany

func (p *Conn) InvokeOneMany(ctx context.Context, method string, args interface{}, opts ...grpc.CallOption) (<-chan *Ret, error)

InvokeOneMany is used in proto generated code to implemened unary OneMany methods doing 1:N calls to the proxy. This returns ProxyRet objects from the channel which contain anypb.Any so the caller (generally generated code) will need to convert those to the proper expected specific types.

As we're attempting to invoke N RPC's together we do have an implicit blocking timeout for the remote server to get connections (or not) to the N targets. This is done in parallel but does mean there's a bound where the RPC may take up to a Dial timeout (usually 20s) if any target is unavailable. Therefore it's suggested this never be invoked with a context timeout lower than the remote server Dial timeout.

NOTE: The returned channel must be read until it closes in order to avoid leaking goroutines.

TODO(jchacon): Should add the ability to specify remote dial timeout in the connection to the proxy.

func (*Conn) NewStream

func (p *Conn) NewStream(ctx context.Context, desc *grpc.StreamDesc, method string, opts ...grpc.CallOption) (grpc.ClientStream, error)

NewStream - see grpc.ClientConnInterface

func (*Conn) Proxy

func (p *Conn) Proxy() *grpc.ClientConn

Proxy will return the ClientConn which connects directly to the proxy rather than wrapped as proxy.Conn normally does. This allows callers to invoke direct RPCs against the proxy as needed (such as services/logging).

type Ret

type Ret struct {
	Target string
	// As targets can be duplicated this is the index into the slice passed to ProxyConn.
	Index int
	Resp  *anypb.Any
	Error error
}

Ret defines the internal API for getting responses from the proxy. Callers will need to convert the anypb.Any into their final type (generally via generated code).