grpc-proxy

gRPC Proxy

gRPC Go Proxy server

Project Goal

Build a transparent reverse proxy for gRPC targets that will make it easy to expose gRPC services over the Internet.

This includes:

• no needed knowledge of the semantics of requests exchanged in the call (independent rollouts)
• easy declarative definition of backends and their mappings to frontends
• simple round-robin load balancing of inbound requests from a single connection to multiple backends

Proxying Modes

There are two proxying modes supported:

• one to one: in this mode data passed back and forth is transmitted as is without any modifications;
• one to many: one client connection gets mapped into multiple upstream connections, results might be aggregated (for unary calls), errors translated into response messages; this mode requires a special layout of protobuf messages.

Proxy Handler

The package proxy contains a generic gRPC reverse proxy handler that allows a gRPC server not to know about method names and their request/response data types. Please consult the package documentation. Here you can find an example usage.

First, define Backend implementation to identify specific upstream. For one to one proxying, SingleBackend might be used:

backend := &proxy.SingleBackend{
    GetConn: func(ctx context.Context) (context.Context, *grpc.ClientConn, error) {
        md, _ := metadata.FromIncomingContext(ctx)

        // Copy the inbound metadata explicitly.
        outCtx := metadata.NewOutgoingContext(ctx, md.Copy())
        // Make sure we use DialContext so the dialing can be cancelled/time out together with the context.
        conn, err := grpc.DialContext(ctx, "api-service.staging.svc.local", grpc.WithCodec(proxy.Codec())) // nolint: staticcheck

        return outCtx, conn, err
    },
}

Defining a StreamDirector that decides where (if at all) to send the request

director = func(ctx context.Context, fullMethodName string) (context.Context, *grpc.ClientConn, error) {
    // Make sure we never forward internal services.
    if strings.HasPrefix(fullMethodName, "/com.example.internal.") {
        return nil, nil, grpc.Errorf(codes.Unimplemented, "Unknown method")
    }
    md, ok := metadata.FromContext(ctx)
    if ok {
        // Decide on which backend to dial
        if val, exists := md[":authority"]; exists && val[0] == "staging.api.example.com" {
            // Make sure we use DialContext so the dialing can be cancelled/time out together with the context.
            return ctx, backend1, nil
        } else if val, exists := md[":authority"]; exists && val[0] == "api.example.com" {
            return ctx, backend2, nil
        }
    }
    return nil, grpc.Errorf(codes.Unimplemented, "Unknown method")
}

Then you need to register it with a grpc.Server. The server may have other handlers that will be served locally:

server := grpc.NewServer(
    grpc.CustomCodec(proxy.Codec()),
    grpc.UnknownServiceHandler(
        proxy.TransparentHandler(director),
        proxy.WithMode(proxy.One2One),
    ))
pb_test.RegisterTestServiceServer(server, &testImpl{})

One to Many Proxying

In one to many proxying mode, it's critical to identify source of each message proxied back from the upstreams. Also upstream error shouldn't fail whole request and instead return errors as messages back. In order to achieve this goal, protobuf response message should follow the same structure:

1. Every response should be repeated list of response messages so that responses from multiple upstreams might be concatenated to build a combined response from all the upstreams.

2. Response should contain common metadata fields which allow grpc-proxy to inject source information and error information into response.

Talks

• "Transparent gRPC proxy in Go" at GopherCon Russia 2021 slides

History

This is a fork of awesome mwitkow/grpc-proxy package with added support for one to many proxying.

License

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