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 any, reply any, ...) error
  • func (p *Conn) InvokeOneMany(ctx context.Context, method string, args any, 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
• type StreamInterceptor
• type Streamer
• type UnaryInterceptor
• type UnaryInvoker

Types

type Conn

type Conn struct {
	// The targets we're proxying for currently.
	Targets []string

	// UnaryInterceptors allow intercepting Invoke and InvokeOneMany calls
	// that go through a proxy.
	// It is unsafe to modify Intercepters while calls are in progress.
	UnaryInterceptors []UnaryInterceptor

	// StreamInterceptors allow intercepting NewStream calls that go through a proxy.
	// It is unsafe to modify Intercepters while calls are in progress.
	StreamInterceptors []StreamInterceptor
	// 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 any, reply any, opts ...grpc.CallOption) error

Invoke - see grpc.ClientConnInterface

func (*Conn) InvokeOneMany

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

InvokeOneMany is used in proto generated code to implement 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.

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

type StreamInterceptor

type StreamInterceptor func(ctx context.Context, desc *grpc.StreamDesc, cc *Conn, method string, streamer Streamer, opts ...grpc.CallOption) (grpc.ClientStream, error)

StreamInterceptor intercepts the execution of an RPC through the proxy. Interceptors can be added to a Conn by modifying its Interceptors field. When an interceptor is set on a ClientConn, all proxy RPC invocations are delegated to the interceptor, and it is the responsibility of the interceptor to call invoker to complete the processing of the RPC.

type Streamer

type Streamer func(ctx context.Context, desc *grpc.StreamDesc, method string, opts ...grpc.CallOption) (grpc.ClientStream, error)

Streamer is called by StreamInterceptor to complete RPCs.

type UnaryInterceptor

type UnaryInterceptor func(ctx context.Context, conn *Conn, method string, args any, invoker UnaryInvoker, opts ...grpc.CallOption) (<-chan *Ret, error)

UnaryInterceptor intercepts the execution of an RPC through the proxy. Interceptors can be added to a Conn by modifying its Interceptors field. When an interceptor is set on a ClientConn, all proxy RPC invocations are delegated to the interceptor, and it is the responsibility of the interceptor to call invoker to complete the processing of the RPC.

type UnaryInvoker

type UnaryInvoker func(ctx context.Context, method string, args any, opts ...grpc.CallOption) (<-chan *Ret, error)

UnaryInvoker is called by UnaryInterceptor to complete RPCs.