proxy

README

gRPC Proxy

This is an implementation of a gRPC Proxying Server in Golang, based on grpc-go. Features:

• full support for all Streams: Unitary RPCs and Streams: One-Many, Many-One, Many-Many
• pass-through mode: no overhead of encoding/decoding messages
• customizable StreamDirector routing based on context.Context of the Stream, allowing users to return a grpc.ClientConn after dialing the backend of choice based on:
  • inspection of service and method name
  • inspection of user credentials in authorization header
  • inspection of custom user-features
  • inspection of TLS client cert credentials
• integration tests

Example Use

director := func(ctx context.Context) (*grpc.ClientConn, error) {
    if err := CheckBearerToken(ctx); err != nil {
        return nil, grpc.Errorf(codes.PermissionDenied, "unauthorized access: %v", err)
    }
    stream, _ := transport.StreamFromContext(ctx)
    backend, found := PreDialledBackends[stream.Method()];
    if !found {
        return nil, grpc.Errorf(codes.Unimplemented, "the service %v is not implemented", stream.Method)
    }
    return backend, nil
}

proxy := grpcproxy.NewProxy(director)
proxy.Server(boundListener)

Status

This is alpha software, written as a proof of concept. It has been integration-tested, but please expect bugs.

The current implementation depends on a public interface to ClientConn.Picker(), which hopefully will be upstreamed in grpc-go#397.

Contributors

Names in no particular order:

• mwitkow

License

grpc-proxy is released under the Apache 2.0 license. See LICENSE.txt.

Part of the main server loop are lifted from the grpc-go Server, which is copyrighted Google Inc. and licensed under MIT license.

Documentation

Index

• func ProxyStream(director StreamDirector, logger grpclog.Logger, ...)
• type Proxy
  • func NewServer(director StreamDirector, opt ...ProxyOption) *Proxy
  • func (s *Proxy) Serve(lis net.Listener) error
  • func (s *Proxy) Stop()
• type ProxyOption
  • func Creds(c credentials.TransportCredentials) ProxyOption
  • func MaxConcurrentStreams(n uint32) ProxyOption
  • func UsingLogger(logger grpclog.Logger) ProxyOption
• type StreamDirector

Functions

func ProxyStream

func ProxyStream(director StreamDirector, logger grpclog.Logger, frontTrans transport.ServerTransport, frontStream *transport.Stream)

ProxyStream performs a forward of a gRPC frontend stream to a backend.

Types

type Proxy

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

func NewServer

func NewServer(director StreamDirector, opt ...ProxyOption) *Proxy

NewServer creates a gRPC proxy which will use the `StreamDirector` for making routing decisions.

func (*Proxy) Serve

func (s *Proxy) Serve(lis net.Listener) error

Serve handles the serving path of the grpc.

func (*Proxy) Stop

func (s *Proxy) Stop()

Stop stops the gRPC server. Once Stop returns, the server stops accepting connection requests and closes all the connected connections.

type ProxyOption

type ProxyOption func(*options)

A ProxyOption sets options.

func Creds

func Creds(c credentials.TransportCredentials) ProxyOption

Creds returns a ProxyOption that sets credentials for server connections.

func MaxConcurrentStreams

func MaxConcurrentStreams(n uint32) ProxyOption

MaxConcurrentStreams returns a ProxyOption that will apply a limit on the number of concurrent streams to each ServerTransport.

func UsingLogger

func UsingLogger(logger grpclog.Logger) ProxyOption

UsingLogger returns a ProxyOption that makes use of a logger other than the default `grpclogger`.

type StreamDirector

type StreamDirector func(ctx context.Context) (*grpc.ClientConn, error)

StreamDirector returns a gRPC ClientConn for a stream of a given context. The service name, method name, and other `MD` metadata (e.g. authority) can be extracted from Context.