grpc-gateway

gRPC to JSON proxy generator following the gRPC HTTP spec

View project on GitHub

How do I use this?

Installation

First, you need to install ProtocolBuffers 3.0.0-beta-3 or later.

mkdir tmp
cd tmp
git clone https://github.com/google/protobuf
cd protobuf
./autogen.sh
./configure
make
make check
sudo make install

Then, go get -u as usual the following packages:

go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway
go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger
go get -u github.com/golang/protobuf/protoc-gen-go

Usage

Make sure that your $GOPATH/bin is in your $PATH.

  1. Define your service in gRPC

    your_service.proto:

    syntax = "proto3";
    package example;
    message StringMessage {
      string value = 1;
    }
       
    service YourService {
      rpc Echo(StringMessage) returns (StringMessage) {}
    }
    
  2. Add a custom option to the .proto file

    your_service.proto:

     syntax = "proto3";
     package example;
    +
    +import "google/api/annotations.proto";
    +
     message StringMessage {
       string value = 1;
     }
        
     service YourService {
    -  rpc Echo(StringMessage) returns (StringMessage) {}
    +  rpc Echo(StringMessage) returns (StringMessage) {
    +    option (google.api.http) = {
    +      post: "/v1/example/echo"
    +      body: "*"
    +    };
    +  }
     }
    

    See a_bit_of_everything.proto for examples of more annotations you can add to customize gateway behavior and generated Swagger output.

    If you do not want to modify the proto file for use with grpc-gateway you can alternatively use an external gRPC API Configuration file. Check our documentation for more information.

  3. Generate gRPC stub

    protoc -I/usr/local/include -I. \
      -I$GOPATH/src \
      -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
      --go_out=plugins=grpc:. \
      path/to/your_service.proto
    

    It will generate a stub file path/to/your_service.pb.go.

  4. Implement your service in gRPC as usual
    1. (Optional) Generate gRPC stub in the language you want.

    e.g.

      protoc -I/usr/local/include -I. \
        -I$GOPATH/src \
        -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
        --ruby_out=. \
        path/to/your/service_proto
         
      protoc -I/usr/local/include -I. \
        -I$GOPATH/src \
        -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
        --plugin=protoc-gen-grpc=grpc_ruby_plugin \
        --grpc-ruby_out=. \
        path/to/your/service.proto
    
    1. Add the googleapis-common-protos gem (or your language equivalent) as a dependency to your project.
    2. Implement your service
  5. Generate reverse-proxy

    protoc -I/usr/local/include -I. \
      -I$GOPATH/src \
      -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
      --grpc-gateway_out=logtostderr=true:. \
      path/to/your_service.proto
    

    It will generate a reverse proxy path/to/your_service.pb.gw.go.

    Note: After generating the code for each of the stubs, to build the code, you will want to run go get . from the directory containing the stubs.

  6. Write an entry point

    Now you need to write an entry point of the proxy server.

    package main
    
    import (
      "flag"
      "net/http"
       
      "github.com/golang/glog"
      "golang.org/x/net/context"
      "github.com/grpc-ecosystem/grpc-gateway/runtime"
      "google.golang.org/grpc"
       	
      gw "path/to/your_service_package"
    )
       
    var (
      echoEndpoint = flag.String("echo_endpoint", "localhost:9090", "endpoint of YourService")
    )
       
    func run() error {
      ctx := context.Background()
      ctx, cancel := context.WithCancel(ctx)
      defer cancel()
       
      mux := runtime.NewServeMux()
      opts := []grpc.DialOption{grpc.WithInsecure()}
      err := gw.RegisterYourServiceHandlerFromEndpoint(ctx, mux, *echoEndpoint, opts)
      if err != nil {
        return err
      }
       
      return http.ListenAndServe(":8080", mux)
    }
       
    func main() {
      flag.Parse()
      defer glog.Flush()
       
      if err := run(); err != nil {
        glog.Fatal(err)
      }
    }
    
  7. (Optional) Generate swagger definitions

    protoc -I/usr/local/include -I. \
      -I$GOPATH/src \
      -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
      --swagger_out=logtostderr=true:. \
      path/to/your_service.proto
    

Parameters and flags

During code generation with protoc, flags to grpc-gateway tools must be passed through protoc using the --<tool_suffix>_out=<flags>:<path> pattern, for example:

--grpc-gateway_out=logtostderr=true,repeated_path_param_separator=ssv:.
--swagger_out=logtostderr=true,repeated_path_param_separator=ssv:.

protoc-gen-grpc-gateway supports custom mapping from Protobuf import to Golang import path. They are compatible with the parameters with the same names in protoc-gen-go.

Besides we also support the request_context parameter to use the http.Request’s Context (only for Go 1.7 and above). This parameter can be useful to pass the request-scoped context between the gateway and the gRPC service.

protoc-gen-grpc-gateway also supports some more command line flags to control logging. You can give these flags together with the parameters above. Run protoc-gen-grpc-gateway --help for more details about the flags.

Similarly, protoc-gen-swagger supports command-line flags to control Swagger output (for example, json_names_for_fields to output JSON names for fields instead of protobuf names). Run protoc-gen-swagger --help for more flag details. Further Swagger customization is possible by annotating your .proto files with options from openapiv2.proto - see a_bit_of_everything.proto for examples.

Mapping gRPC to HTTP

  • How gRPC error codes map to HTTP status codes in the response
  • HTTP request source IP is added as X-Forwarded-For gRPC request header
  • HTTP request-host is added as X-Forwarded-Host gRPC request header
  • HTTP Authorization header is added as authorization gRPC request header
  • Remaining Permanent HTTP header keys (as specified by the IANA here are prefixed with grpcgateway- and added with their values to gRPC request header
  • HTTP headers that start with ‘Grpc-Metadata-‘ are mapped to gRPC metadata (after removing prefix ‘Grpc-Metadata-‘)
  • While configurable, the default {un,}marshaling uses jsonpb with OrigName: true.