grpcadapter

Documentation

Index

• Variables
• type AdaptedClientConn
  • func AdaptClient(conn *grpc.ClientConn) *AdaptedClientConn
  • func (cc *AdaptedClientConn) Close()
  • func (cc *AdaptedClientConn) Stream(ctx context.Context, method string) (ClientStream, error)
• type AdaptedClientPool
  • func NewAdaptedClientPool(opts AdaptedClientPoolOpts) *AdaptedClientPool
  • func (p *AdaptedClientPool) Get(target string) (ClientConn, bool)
  • func (p *AdaptedClientPool) New(targetName, dialTarget string, opts ...grpc.DialOption) (*AdaptedClientPoolController, error)
• type AdaptedClientPoolController
  • func (pw *AdaptedClientPoolController) Close()
• type AdaptedClientPoolOpts
• type AdaptedClientStream
  • func (s *AdaptedClientStream) Close()
  • func (s *AdaptedClientStream) CloseSend()
  • func (s *AdaptedClientStream) Header() metadata.MD
  • func (s *AdaptedClientStream) Recv(ctx context.Context, msg proto.Message) error
  • func (s *AdaptedClientStream) Send(ctx context.Context, msg proto.Message) error
  • func (s *AdaptedClientStream) Trailer() metadata.MD
• type ClientConn
• type ClientPool
• type ClientStream
• type ForwardParams
• type Forwarder
• type MetadataFilter
• type ProxyForwarder
  • func NewProxyForwarder(opts ProxyForwarderOpts) *ProxyForwarder
  • func (pf *ProxyForwarder) Forward(ctx context.Context, params ForwardParams) error
• type ProxyForwarderOpts
• type ProxyMDFilter
  • func NewProxyMDFilter(opts ProxyMDFilterOpts) *ProxyMDFilter
  • func (pd *ProxyMDFilter) FilterRequestMD(md metadata.MD) metadata.MD
  • func (pd *ProxyMDFilter) FilterResponseMD(md metadata.MD) metadata.MD
  • func (pd *ProxyMDFilter) FilterTrailerMD(md metadata.MD) metadata.MD
• type ProxyMDFilterOpts
• type ServerStream

Variables

var ErrAlreadyDialed = errors.New("connection already dialed")

Types

type AdaptedClientConn

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

func AdaptClient

func AdaptClient(conn *grpc.ClientConn) *AdaptedClientConn

AdaptClient wraps an existing gRPC client with an adapter implementing ClientConn. The returned client is instantly ready to be used, and will be valid until *AdaptedClientConn.Close is called, after which any stream initiations via the client will return an error and the underlying gRPC client will be closed, too.

func (*AdaptedClientConn) Close

func (cc *AdaptedClientConn) Close()

Close marks this connection as closed and closes the underlying gRPC client. Calling Close concurrently won't cause issues, but why would you want to even do it...

func (*AdaptedClientConn) Stream

func (cc *AdaptedClientConn) Stream(ctx context.Context, method string) (ClientStream, error)

type AdaptedClientPool

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

func NewAdaptedClientPool

func NewAdaptedClientPool(opts AdaptedClientPoolOpts) *AdaptedClientPool

func (*AdaptedClientPool) Get

func (p *AdaptedClientPool) Get(target string) (ClientConn, bool)

func (*AdaptedClientPool) New

func (p *AdaptedClientPool) New(targetName, dialTarget string, opts ...grpc.DialOption) (*AdaptedClientPoolController, error)

New creates a new *AdaptedClientConn using grpc.NewClient or the NewClientFunc specified in AdaptedClientPoolOpts using the merged set of default options and the options passed to New. It returns a *AdaptedClientPoolController which can be used to close the connection and remove it from the pool.

It is an error to call New() with the same targetName multiple times on a single DialedPool instance, the previous *AdaptedClientPoolController must be explicitly used to close the connection before dialing a new one. Instead of trying to synchronize such procedures, however, it's better to have a properly defined lifecycle for each possible target, with clear logic about when it gets added or removed to/from all the components of a bridge.

type AdaptedClientPoolController

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

AdaptedClientPoolController wraps an AdaptedClientConn created using a DialedPool, providing methods to control the AdaptedClientConn's own and pool lifecycle.

func (*AdaptedClientPoolController) Close

func (pw *AdaptedClientPoolController) Close()

Close removes this connection from the pool and closes it. Calling close multiple times or concurrently will intentionally result in a panic to avoid bugs. TODO(renbou): implement graceful connection closure.

type AdaptedClientPoolOpts

type AdaptedClientPoolOpts struct {
	// NewClientFunc can be used to specify an alternative connection constructor to be used instead of [grpc.NewClient].
	NewClientFunc func(target string, opts ...grpc.DialOption) (*grpc.ClientConn, error)

	// DefaultOpts specify the default options to be used when creating a new client, by default no opts are used.
	DefaultOpts []grpc.DialOption
}

type AdaptedClientStream

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

func (*AdaptedClientStream) Close

func (s *AdaptedClientStream) Close()

func (*AdaptedClientStream) CloseSend

func (s *AdaptedClientStream) CloseSend()

func (*AdaptedClientStream) Header

func (s *AdaptedClientStream) Header() metadata.MD

func (*AdaptedClientStream) Recv

func (s *AdaptedClientStream) Recv(ctx context.Context, msg proto.Message) error

func (*AdaptedClientStream) Send

func (s *AdaptedClientStream) Send(ctx context.Context, msg proto.Message) error

func (*AdaptedClientStream) Trailer

func (s *AdaptedClientStream) Trailer() metadata.MD

type ClientConn

type ClientConn interface {
	Stream(ctx context.Context, method string) (ClientStream, error)
	Close()
}

type ClientPool

type ClientPool interface {
	Get(target string) (ClientConn, bool)
}

type ClientStream

type ClientStream interface {
	Send(context.Context, proto.Message) error
	Recv(context.Context, proto.Message) error
	Header() metadata.MD
	Trailer() metadata.MD
	CloseSend()
	Close()
}

type ForwardParams

type ForwardParams struct {
	Target  *bridgedesc.Target
	Service *bridgedesc.Service
	Method  *bridgedesc.Method

	Incoming ServerStream
	Outgoing ClientConn
}

type Forwarder

type Forwarder interface {
	Forward(context.Context, ForwardParams) error
}

type MetadataFilter

type MetadataFilter interface {
	FilterRequestMD(metadata.MD) metadata.MD
	FilterResponseMD(metadata.MD) metadata.MD
	FilterTrailerMD(metadata.MD) metadata.MD
}

type ProxyForwarder

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

ProxyForwarder is the default implementation of Forwarder used by grpcbridge, suitable for use in a proxy scenario where request/response metadata must be filtered and various timeouts must be set to ensure the proxy continues working with misbehaving clients.

It doesn't modify the messages received from the incoming and outgoing streams, proxying them as-is. Metadata, on the other hand, is filtered using the specified MetadataFilter. If the filtered metadata returned by the filter's FilterRequestMD method contains a "grpc-timeout" field, ProxyForwarder attempts to parse it as specified in gRPC's PROTOCOL-HTTP2 spec and use it as an additional timeout for the whole streaming call.

func NewProxyForwarder

func NewProxyForwarder(opts ProxyForwarderOpts) *ProxyForwarder

NewProxyForwarder creates a new ProxyForwarder using the specified options.

func (*ProxyForwarder) Forward

func (pf *ProxyForwarder) Forward(ctx context.Context, params ForwardParams) error

Forward forwards an incoming ServerStream to an outgoing ClientConn after initiating a ClientStream using the specified params. Metadata is retrieved using metadata.FromIncomingContext and filtered using the MetadataFilter using which this forwarder was configured. It either returns an error when the forwarding process fails, or nil when the outgoing stream returns an io.EOF on Recv.

Forward waits for its forwarding goroutines to exit, which means that both the ServerStream and the created ClientStream MUST support context for their Recv/Send operations, otherwise there exist execution flows which might never end if a Send/Recv on the incoming or outgoing stream don't return properly. Due to such cases existing where Forward will block indefinitely, it waits for its goroutines to exit in ALL cases.

type ProxyForwarderOpts

type ProxyForwarderOpts struct {
	// Filter specifies the metadata filter to be used for all operations.
	// If not set, the default [ProxyMDFilter] is created via [NewProxyMDFilter] and used.
	Filter MetadataFilter
}

ProxyForwarderOpts define all the optional settings which can be set for ProxyForwarder.

type ProxyMDFilter

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

ProxyMDFilter is the default implementation of MetadataFilter used by grpcbridge, suitable for use with various untrusted incoming requests. By default, no client or server metadata is forwarded, since both might contain sensitive fields: a client might send an X-Internal header that will be blindly trusted by a server, while a server might return an X-Internal header leaking some sensitive data.

To enable metadata forwarding in one or the other direction, the field name must be specified in the appropriate allowlist in ProxyMDFilterOpts. Additionally, ProxyMDFilter.FilterRequestMD supports forwarding of the grpc-timeout value, since it will be terminated in grpcbridge by a Forwarder, and as such is guaranteed to not affect the server in any way.

For backwards compatibility with gRPC-Gateway, ProxyMDFilter supports setting custom prefix values which will be used to prefix the appropriate metadata keys, i.e. IncomingPrefix and OutgoingPrefix can be set to "grpcgateway-" and "Grpc-Metadata-" for allowed fields to be proxied just like they would be with gRPC-Gateway. Prefixing incoming metadata with "Grpc-Metadata-" for it the prefix to be stripped is also supported, but such fields must also be explicitly allowed. For example, gRPC-Gateway would blindly forward Grpc-Metadata-Foo as Foo, but ProxyMDFilter would require "Grpc-Metadata-Foo" to be specified in AllowIncoming for that to happen.

Binary metadata fields (fields whose keys are suffixed with "-bin") are decoded by ProxyMDFilter.FilterRequestMD for later encoding by the forwarding gRPC client.

func NewProxyMDFilter

func NewProxyMDFilter(opts ProxyMDFilterOpts) *ProxyMDFilter

NewProxyMDFilter creates a new ProxyMDFilter with the given options. See ProxyMDFilter and ProxyMDFilterOpts for more context.

func (*ProxyMDFilter) FilterRequestMD

func (pd *ProxyMDFilter) FilterRequestMD(md metadata.MD) metadata.MD

FilterRequestMD transforms incoming metadata according to the ProxyMDFilter configuration. If the metadata contains "grpc-timeout" fields, they will additionally be forwarded as-is.

func (*ProxyMDFilter) FilterResponseMD

func (pd *ProxyMDFilter) FilterResponseMD(md metadata.MD) metadata.MD

FilterResponseMD transforms outgoing metadata according to the ProxyMDFilter configuration. Outgoing fields are not modified in any way like they are in ProxyMDFilter.FilterRequestMD, since they are intended to be read by a client as-is.

func (*ProxyMDFilter) FilterTrailerMD

func (pd *ProxyMDFilter) FilterTrailerMD(md metadata.MD) metadata.MD

FilterTrailerMD transforms outgoing trailers according to the ProxyMDFilter configuration. It functions exactly like ProxyMDFilter.FilterResponseMD, but uses the configuration for outgoing trailers.

type ProxyMDFilterOpts

type ProxyMDFilterOpts struct {
	// AllowRequestMD is the allowlist for request metadata.
	AllowRequestMD []string
	// If PrefixRequestMD is specified, request metadata fields are prefixed with this value.
	PrefixRequestMD string
	// AllowResponseMD is the allowlist for response metadata.
	AllowResponseMD []string
	// If PrefixResponseMD is specified, response metadata fields are prefixed with this value.
	PrefixResponseMD string
	// AllowTrailerMD is the allowlist for response trailer metadata.
	AllowTrailerMD []string
	// If PrefixTrailerMD is specified, response trailer metadata fields are prefixed with this value.
	PrefixTrailerMD string
}

ProxyMDFilterOpts specify the metadata fields to be forwarded in incoming headers (from a client) and outgoing headers/trailers (from a server). Additionally, prefix values can be specified for the appropriate forwarded fields to be prefixed with. For more context, see ProxyMDFilter.

type ServerStream

type ServerStream interface {
	Send(context.Context, proto.Message) error
	Recv(context.Context, proto.Message) error
	SetHeader(metadata.MD)
	SetTrailer(metadata.MD)
}