xn--rhta.xyz/grpc-ecosystem/grpc-gateway
The grpc-gateway is a plugin of the Google protocol buffers compiler
protoc.
It reads protobuf service definitions and generates a reverse-proxy server which
'translates a RESTful HTTP API into gRPC. This server is generated according to the
google.api.http
annotations in your service definitions.
This helps you provide your APIs in both gRPC and RESTful style at the same time.
gRPC is great -- it generates API clients and server stubs in many programming languages, it is fast, easy-to-use, bandwidth-efficient and its design is combat-proven by Google. However, you might still want to provide a traditional RESTful JSON API as well. Reasons can range from maintaining backwards-compatibility, supporting languages or clients not well supported by gRPC, to simply maintaining the aesthetics and tooling involved with a RESTful JSON architecture.
This project aims to provide that HTTP+JSON interface to your gRPC service. A small amount of configuration in your service to attach HTTP semantics is all that's needed to generate a reverse-proxy with this library.
The grpc-gateway requires a local installation of the Google protocol buffers
compiler protoc v3.0.0 or above. Please install this via your local package
manager or by downloading one of the releases from the official repository:
https://github.com/protocolbuffers/protobuf/releases
Then use go get -u to download 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
This will place three binaries in your $GOBIN;
protoc-gen-grpc-gatewayprotoc-gen-swaggerprotoc-gen-goMake sure that your $GOBIN is in your $PATH.
Define your gRPC service using protocol buffers
your_service.proto:
syntax = "proto3";
package example;
message StringMessage {
string value = 1;
}
service YourService {
rpc Echo(StringMessage) returns (StringMessage) {}
}
Add a google.api.http
annotation to your .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: "*"
+ };
+ }
}
If you do not want to modify the proto file for use with grpc-gateway you can alternatively use an external gRPC Service Configuration file. Check our documentation for more information.
Generate gRPC stub
The following generates gRPC code for Golang based on 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 \
--go_out=plugins=grpc:. \
path/to/your_service.proto
It will generate a stub file path/to/your_service.pb.go.
Implement your service in gRPC as usual
For example, the following generates gRPC code for Ruby based on 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 \
--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
Generate reverse-proxy using protoc-gen-grpc-gateway
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.
Write an entrypoint for the HTTP reverse-proxy server
package main
import (
"context" // Use "golang.org/x/net/context" for Golang version <= 1.6
"flag"
"net/http"
"github.com/golang/glog"
"github.com/grpc-ecosystem/grpc-gateway/runtime"
"google.golang.org/grpc"
gw "path/to/your_service_package" // Update
)
var (
// command-line options:
// gRPC server endpoint
grpcServerEndpoint = flag.String("grpc-server-endpoint", "localhost:9090", "gRPC server endpoint")
)
func run() error {
ctx := context.Background()
ctx, cancel := context.WithCancel(ctx)
defer cancel()
// Register gRPC server endpoint
// Note: Make sure the gRPC server is running properly and accessible
mux := runtime.NewServeMux()
opts := []grpc.DialOption{grpc.WithInsecure()}
err := gw.RegisterYourServiceHandlerFromEndpoint(ctx, mux, *grpcServerEndpoint, opts)
if err != nil {
return err
}
// Start HTTP server (and proxy calls to gRPC server endpoint)
return http.ListenAndServe(":8081", mux)
}
func main() {
flag.Parse()
defer glog.Flush()
if err := run(); err != nil {
glog.Fatal(err)
}
}
(Optional) Generate swagger definitions using protoc-gen-swagger
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
protoc-gen-grpc-gateway supports custom mapping from Protobuf import to
Golang import paths. They are compatible to
the parameters with same names in protoc-gen-go
(except source_relative).
In addition we also support the request_context parameter in order to use the
http.Request's Context (only for Go 1.7 and above). This parameter can be
useful to pass 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 parameters above. Run
protoc-gen-grpc-gateway --help for more details about the flags.
More examples are available under examples directory.
proto/examplepb/echo_service.proto, proto/examplepb/a_bit_of_everything.proto, proto/examplepb/unannotated_echo_service.proto: service definition
proto/examplepb/echo_service.pb.go, proto/examplepb/a_bit_of_everything.pb.go, proto/examplepb/unannotated_echo_service.pb.go: [generated] stub of the serviceproto/examplepb/echo_service.pb.gw.go, proto/examplepb/a_bit_of_everything.pb.gw.go, proto/examplepb/uannotated_echo_service.pb.gw.go: [generated] reverse proxy for the serviceproto/examplepb/unannotated_echo_service.yaml: gRPC API Configuration for unannotated_echo_service.protoserver/main.go: service implementationmain.go: entrypoint of the generated reverse proxyTo use the same port for custom HTTP handlers (e.g. serving swagger.json),
gRPC-gateway, and a gRPC server, see
this example by CoreOS
(and its accompanying blog post).
Grpc-Metadata- prefix to gRPC metadata (prefixed with grpcgateway-)Grpc-Timeout header.But patch is welcome.
X-Forwarded-For gRPC request header.X-Forwarded-Host gRPC request header.Authorization header is added as authorization gRPC request header.grpcgateway- and added with their values to gRPC request
header.grpcgateway-).OrigName: true.See CONTRIBUTING.md.
grpc-gateway is licensed under the BSD 3-Clause License. See LICENSE.txt for more details.
FAQs
Unknown package
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh discusses the recent npm supply chain attacks on PodRocket, covering novel attack vectors and how developers can protect themselves.
Security News
Maintainers back GitHub’s npm security overhaul but raise concerns about CI/CD workflows, enterprise support, and token management.
Product
Socket Firewall is a free tool that blocks malicious packages at install time, giving developers proactive protection against rising supply chain attacks.