From 6806a84f43b8f96f4964f1aaee186bd406cfdb56 Mon Sep 17 00:00:00 2001 From: Johan Brandhorst Date: Mon, 18 Feb 2019 22:53:18 +0000 Subject: [PATCH] Switch to go modules --- .circleci/config.yml | 28 +++---- .gitignore | 3 + CONTRIBUTING.md | 4 +- Gopkg.lock | 192 ------------------------------------------- Gopkg.toml | 66 --------------- Makefile | 41 +++++---- README.md | 143 +++++++++++++++++++------------- go.mod | 18 ++++ go.sum | 43 ++++++++++ 9 files changed, 184 insertions(+), 354 deletions(-) delete mode 100644 Gopkg.lock delete mode 100644 Gopkg.toml create mode 100644 go.mod create mode 100644 go.sum diff --git a/.circleci/config.yml b/.circleci/config.yml index 68dd572a8c..cac9aa698e 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -3,29 +3,27 @@ jobs: build: docker: - image: jfbrandhorst/grpc-gateway-build-env - working_directory: /go/src/github.com/grpc-ecosystem/grpc-gateway + working_directory: /src/grpc-gateway steps: - checkout - - run: dep ensure --vendor-only - run: go build ./... test: docker: - image: jfbrandhorst/grpc-gateway-build-env - working_directory: /go/src/github.com/grpc-ecosystem/grpc-gateway + working_directory: /src/grpc-gateway environment: - GLOG_logtostderr: "1" + GLOG_logtostderr: '1' steps: - checkout - - run: dep ensure --vendor-only - run: go test -race -coverprofile=coverage.txt ./... - run: bash <(curl -s https://codecov.io/bash) node_test: docker: - image: jfbrandhorst/grpc-gateway-build-env - working_directory: /go/src/github.com/grpc-ecosystem/grpc-gateway + working_directory: /src/grpc-gateway steps: - checkout - - run: dep ensure --vendor-only + - run: go mod vendor - run: > . $HOME/.nvm/nvm.sh && cd examples/browser && @@ -35,25 +33,25 @@ jobs: generate: docker: - image: jfbrandhorst/grpc-gateway-build-env - working_directory: /go/src/github.com/grpc-ecosystem/grpc-gateway + working_directory: /src/grpc-gateway steps: - checkout - run: make realclean - run: make examples SWAGGER_CODEGEN="${SWAGGER_CODEGEN}" # Set in Docker image + - run: go mod tidy - run: git diff --exit-code lint: docker: - image: jfbrandhorst/grpc-gateway-build-env - working_directory: /go/src/github.com/grpc-ecosystem/grpc-gateway + working_directory: /src/grpc-gateway steps: - checkout - - run: dep ensure --vendor-only - run: go get golang.org/x/lint/golint - run: make lint bazel: docker: - image: l.gcr.io/google/bazel:latest - working_directory: /go/src/github.com/grpc-ecosystem/grpc-gateway + working_directory: /src/grpc-gateway steps: - checkout - run: @@ -67,22 +65,22 @@ jobs: - run: name: Check that Bazel BUILD files are up-to-date command: 'test -z "$(bazel run //:gazelle_diff)" || - (echo "ERROR: Bazel files out-of-date, please run \`bazel run :gazelle_fix\`" >&2; exit 1)' + (echo "ERROR: Bazel files out-of-date, please run \`bazel run :gazelle_fix\`" >&2; exit 1)' - run: name: Run tests with Bazel command: bazel test //... - run: name: Check formatting of Bazel BUILD files command: 'bazel run //:buildifier_check || - (echo "ERROR: Bazel files not formatted, please run \`bazel run :buildifier\`" >&2; exit 1)' + (echo "ERROR: Bazel files not formatted, please run \`bazel run :buildifier\`" >&2; exit 1)' when: always release: docker: - image: jfbrandhorst/grpc-gateway-build-env - working_directory: /go/src/github.com/grpc-ecosystem/grpc-gateway + working_directory: /src/grpc-gateway steps: - checkout - - run: dep ensure --vendor-only + - run: go mod vendor - run: curl -sL https://git.io/goreleaser | bash workflows: version: 2 diff --git a/.gitignore b/.gitignore index 7c349d62a4..2a59512090 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,6 @@ bazel-testlogs # Go vendor directory vendor + +# Generated travis files +.travis.yml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a7d09ce6cb..04fc20639c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,8 +24,8 @@ All submissions, including submissions by project members, require review. Great, it should be as simple as thus (run from the root of the directory): ```bash -docker run -v $(pwd):/go/src/github.com/grpc-ecosystem/grpc-gateway --rm jfbrandhorst/grpc-gateway-build-env \ - /bin/bash -c 'cd /go/src/github.com/grpc-ecosystem/grpc-gateway && \ +docker run -v $(pwd):/src/grpc-gateway --rm jfbrandhorst/grpc-gateway-build-env \ + /bin/bash -c 'cd /src/grpc-gateway && \ make realclean && \ make examples SWAGGER_CODEGEN="${SWAGGER_CODEGEN}"' docker run -itv $(pwd):/grpc-gateway -w /grpc-gateway --entrypoint /bin/bash --rm \ diff --git a/Gopkg.lock b/Gopkg.lock deleted file mode 100644 index 4e9da47990..0000000000 --- a/Gopkg.lock +++ /dev/null @@ -1,192 +0,0 @@ -# This file is autogenerated, do not edit; changes may be undone by the next 'dep ensure'. - - -[[projects]] - digest = "1:2cd7915ab26ede7d95b8749e6b1f933f1c6d5398030684e6505940a10f31cfda" - name = "github.com/ghodss/yaml" - packages = ["."] - pruneopts = "UT" - revision = "0ca9ea5df5451ffdf184b4428c902747c2c11cd7" - -[[projects]] - digest = "1:5cae6c173646d9230aecf8074c171edb4fb9a37f074c5c89ba2fece20b6703b6" - name = "github.com/go-resty/resty" - packages = ["."] - pruneopts = "UT" - revision = "f8815663de1e64d57cdd4ee9e2b2fa96977a030e" - -[[projects]] - digest = "1:1ba1d79f2810270045c328ae5d674321db34e3aae468eb4233883b473c5c0467" - name = "github.com/golang/glog" - packages = ["."] - pruneopts = "UT" - revision = "23def4e6c14b4da8ac2ed8007337bc5eb5007998" - -[[projects]] - digest = "1:329b943e12961fb0c0db5bc18858433e569183178edfd0a8d99033ce032c62cc" - name = "github.com/golang/protobuf" - packages = [ - "descriptor", - "jsonpb", - "proto", - "protoc-gen-go", - "protoc-gen-go/descriptor", - "protoc-gen-go/generator", - "protoc-gen-go/generator/internal/remap", - "protoc-gen-go/grpc", - "protoc-gen-go/plugin", - "ptypes", - "ptypes/any", - "ptypes/duration", - "ptypes/empty", - "ptypes/struct", - "ptypes/timestamp", - "ptypes/wrappers", - ] - pruneopts = "UT" - revision = "aa810b61a9c79d51363740d207bb46cf8e620ed5" - -[[projects]] - digest = "1:d673e95129a1107bfd04e093751a5e1267faabc27d218d824fb013f57ac08f55" - name = "github.com/rogpeppe/fastuuid" - packages = ["."] - pruneopts = "UT" - revision = "6724a57986aff9bff1a1770e9347036def7c89f6" - -[[projects]] - digest = "1:c0b7af9789502fec69b7ab40035a2180e43b9663c32101084ba51c844ea416e9" - name = "golang.org/x/net" - packages = [ - "context", - "http/httpguts", - "http2", - "http2/hpack", - "idna", - "internal/timeseries", - "publicsuffix", - "trace", - ] - pruneopts = "UT" - revision = "4dfa2610cdf3b287375bbba5b8f2a14d3b01d8de" - -[[projects]] - branch = "master" - digest = "1:7ba061af4131fb44b30448572acd0d6fefbf63a61b97b7ef1dea0be5871c2742" - name = "golang.org/x/sys" - packages = ["unix"] - pruneopts = "UT" - revision = "66b7b1311ac80bbafcd2daeef9a5e6e2cd1e2399" - -[[projects]] - digest = "1:a2ab62866c75542dd18d2b069fec854577a20211d7c0ea6ae746072a1dccdd18" - name = "golang.org/x/text" - packages = [ - "collate", - "collate/build", - "internal/colltab", - "internal/gen", - "internal/tag", - "internal/triegen", - "internal/ucd", - "language", - "secure/bidirule", - "transform", - "unicode/bidi", - "unicode/cldr", - "unicode/norm", - "unicode/rangetable", - ] - pruneopts = "UT" - revision = "f21a4dfb5e38f5895301dc265a8def02365cc3d0" - version = "v0.3.0" - -[[projects]] - digest = "1:46be2f6b4d4e4b89f8102668902e68013234da1684fc78da602da95e745f285d" - name = "google.golang.org/genproto" - packages = [ - "googleapis/api/annotations", - "googleapis/rpc/errdetails", - "googleapis/rpc/status", - "protobuf/field_mask", - ] - pruneopts = "UT" - revision = "383e8b2c3b9e36c4076b235b32537292176bae20" - -[[projects]] - digest = "1:c3ad9841823db6da420a5625b367913b4ff54bbe60e8e3c98bd20e243e62e2d2" - name = "google.golang.org/grpc" - packages = [ - ".", - "balancer", - "balancer/base", - "balancer/roundrobin", - "codes", - "connectivity", - "credentials", - "encoding", - "encoding/proto", - "grpclog", - "internal", - "internal/backoff", - "internal/channelz", - "internal/envconfig", - "internal/grpcrand", - "internal/transport", - "keepalive", - "metadata", - "naming", - "peer", - "resolver", - "resolver/dns", - "resolver/passthrough", - "stats", - "status", - "tap", - ] - pruneopts = "UT" - revision = "2e463a05d100327ca47ac218281906921038fd95" - version = "v1.16.0" - -[[projects]] - digest = "1:6570992c02a2137a20be83990a979b6fe892e20ecdc6b756449989b2a7efb8ae" - name = "gopkg.in/yaml.v2" - packages = ["."] - pruneopts = "UT" - revision = "eb3733d160e74a9c7e442f435eb3bea458e1d19f" - -[solve-meta] - analyzer-name = "dep" - analyzer-version = 1 - input-imports = [ - "github.com/ghodss/yaml", - "github.com/go-resty/resty", - "github.com/golang/glog", - "github.com/golang/protobuf/descriptor", - "github.com/golang/protobuf/jsonpb", - "github.com/golang/protobuf/proto", - "github.com/golang/protobuf/protoc-gen-go", - "github.com/golang/protobuf/protoc-gen-go/descriptor", - "github.com/golang/protobuf/protoc-gen-go/generator", - "github.com/golang/protobuf/protoc-gen-go/plugin", - "github.com/golang/protobuf/ptypes", - "github.com/golang/protobuf/ptypes/any", - "github.com/golang/protobuf/ptypes/duration", - "github.com/golang/protobuf/ptypes/empty", - "github.com/golang/protobuf/ptypes/struct", - "github.com/golang/protobuf/ptypes/timestamp", - "github.com/golang/protobuf/ptypes/wrappers", - "github.com/rogpeppe/fastuuid", - "golang.org/x/net/context", - "google.golang.org/genproto/googleapis/api/annotations", - "google.golang.org/genproto/googleapis/rpc/errdetails", - "google.golang.org/genproto/googleapis/rpc/status", - "google.golang.org/genproto/protobuf/field_mask", - "google.golang.org/grpc", - "google.golang.org/grpc/codes", - "google.golang.org/grpc/connectivity", - "google.golang.org/grpc/grpclog", - "google.golang.org/grpc/metadata", - "google.golang.org/grpc/status", - ] - solver-name = "gps-cdcl" - solver-version = 1 diff --git a/Gopkg.toml b/Gopkg.toml deleted file mode 100644 index e4c78e94a9..0000000000 --- a/Gopkg.toml +++ /dev/null @@ -1,66 +0,0 @@ -required = [ - "github.com/golang/protobuf/protoc-gen-go", -] - -[prune] - go-tests = true - unused-packages = true - -# Constrained versions that are defined in WORKSPACE are at the top - -[[constraint]] - # Also defined in WORKSPACE - revision = "0ca9ea5df5451ffdf184b4428c902747c2c11cd7" - name = "github.com/ghodss/yaml" - -[[constraint]] - # Also defined in WORKSPACE - revision = "f8815663de1e64d57cdd4ee9e2b2fa96977a030e" - name = "github.com/go-resty/resty" - -[[constraint]] - # Also defined in WORKSPACE - revision = "6724a57986aff9bff1a1770e9347036def7c89f6" - name = "github.com/rogpeppe/fastuuid" - -[[constraint]] - # Also defined in WORKSPACE - revision = "383e8b2c3b9e36c4076b235b32537292176bae20" - name = "google.golang.org/genproto" - -[[override]] - # Also defined in WORKSPACE - revision = "eb3733d160e74a9c7e442f435eb3bea458e1d19f" - name = "gopkg.in/yaml.v2" - -# These versions are constrained transitively by bazelbuild/rules_go - -[[constraint]] - # Also defined in bazelbuild/rules_go - # https://github.com/bazelbuild/rules_go/blob/109c520465fcb418f2c4be967f3744d959ad66d3/go/private/repositories.bzl#L52 - revision = "aa810b61a9c79d51363740d207bb46cf8e620ed5" - name = "github.com/golang/protobuf" - -[[constraint]] - # Also defined in bazelbuild/rules_go - # https://github.com/bazelbuild/rules_go/blob/109c520465fcb418f2c4be967f3744d959ad66d3/go/private/repositories.bzl#L96 - revision = "4dfa2610cdf3b287375bbba5b8f2a14d3b01d8de" - name = "golang.org/x/net" - -[[constraint]] - # Also defined in bazelbuild/rules_go - # https://github.com/bazelbuild/rules_go/blob/109c520465fcb418f2c4be967f3744d959ad66d3/go/private/repositories.bzl#L123 - version = "1.15.0" - name = "google.golang.org/grpc" - -[[constraint]] - # Also defined in bazelbuild/rules_go - # https://github.com/bazelbuild/rules_go/blob/109c520465fcb418f2c4be967f3744d959ad66d3/go/private/repositories.bzl#L160 - revision = "23def4e6c14b4da8ac2ed8007337bc5eb5007998" - name = "github.com/golang/glog" - -[[override]] - # Also defined in bazelbuild/rules_go - # https://github.com/bazelbuild/rules_go/blob/109c520465fcb418f2c4be967f3744d959ad66d3/go/private/repositories.bzl#L117 - version = "0.3.0" - name = "golang.org/x/text" diff --git a/Makefile b/Makefile index ba923e91f9..b141347681 100644 --- a/Makefile +++ b/Makefile @@ -3,7 +3,6 @@ # You don't have to rebuild these targets by yourself unless you develop # grpc-gateway itself. -PKG=github.com/grpc-ecosystem/grpc-gateway GO_PLUGIN=bin/protoc-gen-go GO_PROTOBUF_REPO=github.com/golang/protobuf GO_PLUGIN_PKG=$(GO_PROTOBUF_REPO)/protoc-gen-go @@ -15,9 +14,9 @@ SWAGGER_PLUGIN_SRC= utilities/doc.go \ protoc-gen-swagger/genswagger/generator.go \ protoc-gen-swagger/genswagger/template.go \ protoc-gen-swagger/main.go -SWAGGER_PLUGIN_PKG=$(PKG)/protoc-gen-swagger +SWAGGER_PLUGIN_PKG=./protoc-gen-swagger GATEWAY_PLUGIN=bin/protoc-gen-grpc-gateway -GATEWAY_PLUGIN_PKG=$(PKG)/protoc-gen-grpc-gateway +GATEWAY_PLUGIN_PKG=./protoc-gen-grpc-gateway GATEWAY_PLUGIN_SRC= utilities/doc.go \ utilities/pattern.go \ utilities/trie.go \ @@ -51,7 +50,7 @@ RUNTIME_GO=$(RUNTIME_PROTO:.proto=.pb.go) OPENAPIV2_PROTO=protoc-gen-swagger/options/openapiv2.proto protoc-gen-swagger/options/annotations.proto OPENAPIV2_GO=$(OPENAPIV2_PROTO:.proto=.pb.go) -PKGMAP=Mgoogle/protobuf/field_mask.proto=google.golang.org/genproto/protobuf/field_mask,Mgoogle/protobuf/descriptor.proto=$(GO_PLUGIN_PKG)/descriptor,Mexamples/proto/sub/message.proto=$(PKG)/examples/proto/sub +PKGMAP=Mgoogle/protobuf/field_mask.proto=google.golang.org/genproto/protobuf/field_mask,Mgoogle/protobuf/descriptor.proto=$(GO_PLUGIN_PKG)/descriptor,Mexamples/proto/sub/message.proto=github.com/grpc-ecosystem/grpc-gateway/examples/proto/sub ADDITIONAL_GW_FLAGS= ifneq "$(GATEWAY_PLUGIN_FLAGS)" "" ADDITIONAL_GW_FLAGS=,$(GATEWAY_PLUGIN_FLAGS) @@ -126,14 +125,14 @@ generate: $(RUNTIME_GO) .SUFFIXES: .go .proto $(GO_PLUGIN): - dep ensure -vendor-only - go build -o $@ ./vendor/$(GO_PLUGIN_PKG) + go build -o $(GO_PLUGIN) $(GO_PLUGIN_PKG) $(RUNTIME_GO): $(RUNTIME_PROTO) $(GO_PLUGIN) - protoc -I $(PROTOC_INC_PATH) --plugin=$(GO_PLUGIN) -I $(GOPATH)/src/$(GO_PTYPES_ANY_PKG) -I. --go_out=$(PKGMAP):. $(RUNTIME_PROTO) + go mod vendor + protoc -I $(PROTOC_INC_PATH) --plugin=$(GO_PLUGIN) -I ./vendor/$(GO_PTYPES_ANY_PKG) -I. --go_out=$(PKGMAP),paths=source_relative:. $(RUNTIME_PROTO) $(OPENAPIV2_GO): $(OPENAPIV2_PROTO) $(GO_PLUGIN) - protoc -I $(PROTOC_INC_PATH) --plugin=$(GO_PLUGIN) -I. --go_out=$(PKGMAP):$(GOPATH)/src $(OPENAPIV2_PROTO) + protoc -I $(PROTOC_INC_PATH) --plugin=$(GO_PLUGIN) -I. --go_out=$(PKGMAP),paths=source_relative:. $(OPENAPIV2_PROTO) $(GATEWAY_PLUGIN): $(RUNTIME_GO) $(GATEWAY_PLUGIN_SRC) go build -o $@ $(GATEWAY_PLUGIN_PKG) @@ -142,11 +141,11 @@ $(SWAGGER_PLUGIN): $(SWAGGER_PLUGIN_SRC) $(OPENAPIV2_GO) go build -o $@ $(SWAGGER_PLUGIN_PKG) $(EXAMPLE_SVCSRCS): $(GO_PLUGIN) $(EXAMPLES) - protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(GO_PLUGIN) --go_out=$(PKGMAP),plugins=grpc:. $(EXAMPLES) + protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(GO_PLUGIN) --go_out=$(PKGMAP),plugins=grpc,paths=source_relative:. $(EXAMPLES) $(EXAMPLE_DEPSRCS): $(GO_PLUGIN) $(EXAMPLE_DEPS) mkdir -p $(OUTPUT_DIR) - protoc -I $(PROTOC_INC_PATH) -I. --plugin=$(GO_PLUGIN) --go_out=$(PKGMAP),plugins=grpc:$(OUTPUT_DIR) $(@:.pb.go=.proto) - cp $(OUTPUT_DIR)/$(PKG)/$@ $@ || cp $(OUTPUT_DIR)/$@ $@ + protoc -I $(PROTOC_INC_PATH) -I. --plugin=$(GO_PLUGIN) --go_out=$(PKGMAP),plugins=grpc,paths=source_relative:$(OUTPUT_DIR) $(@:.pb.go=.proto) + cp $(OUTPUT_DIR)/$@ $@ || cp $(OUTPUT_DIR)/$@ $@ $(EXAMPLE_GWSRCS): ADDITIONAL_GW_FLAGS:=$(ADDITIONAL_GW_FLAGS),grpc_api_configuration=examples/proto/examplepb/unannotated_echo_service.yaml $(EXAMPLE_GWSRCS): $(GATEWAY_PLUGIN) $(EXAMPLES) @@ -179,8 +178,8 @@ $(RESPONSE_BODY_EXAMPLE_SRCS): $(RESPONSE_BODY_EXAMPLE_SPEC) examples: $(EXAMPLE_DEPSRCS) $(EXAMPLE_SVCSRCS) $(EXAMPLE_GWSRCS) $(EXAMPLE_SWAGGERSRCS) $(EXAMPLE_CLIENT_SRCS) test: examples - go test -race $(PKG)/... - go test -race $(PKG)/examples/integration -args -network=unix -endpoint=test.sock + go test -race ... + go test -race examples/integration -args -network=unix -endpoint=test.sock changelog: docker run --rm \ --interactive \ @@ -196,14 +195,14 @@ changelog: --unreleased-label "**Next release**" \ --future-release=v1.7.0 lint: - golint --set_exit_status $(PKG)/runtime - golint --set_exit_status $(PKG)/utilities/... - golint --set_exit_status $(PKG)/protoc-gen-grpc-gateway/... - golint --set_exit_status $(PKG)/protoc-gen-swagger/... - go vet $(PKG)/runtime || true - go vet $(PKG)/utilities/... - go vet $(PKG)/protoc-gen-grpc-gateway/... - go vet $(PKG)/protoc-gen-swagger/... + golint --set_exit_status ./runtime + golint --set_exit_status ./utilities/... + golint --set_exit_status ./protoc-gen-grpc-gateway/... + golint --set_exit_status ./protoc-gen-swagger/... + go vet ./runtime || true + go vet ./utilities/... + go vet ./protoc-gen-grpc-gateway/... + go vet ./protoc-gen-swagger/... clean: rm -f $(GATEWAY_PLUGIN) $(SWAGGER_PLUGIN) diff --git a/README.md b/README.md index a780964be0..d87501ec8f 100644 --- a/README.md +++ b/README.md @@ -2,39 +2,40 @@ [![CircleCI](https://circleci.com/gh/grpc-ecosystem/grpc-gateway.svg?style=svg)](https://circleci.com/gh/grpc-ecosystem/grpc-gateway) -grpc-gateway is a plugin of [protoc](http://github.com/google/protobuf). -It reads [gRPC](http://github.com/grpc/grpc-common) service definition, -and generates a reverse-proxy server which translates a RESTful JSON API into gRPC. -This server is generated according to the +The grpc-gateway is a plugin of the Google protocol buffers compiler +[protoc](https://github.com/protocolbuffers/protobuf). +It reads protobuf service definitions and generates a reverse-proxy server which +translates a RESTful JSON API into gRPC. This server is generated according to the [`google.api.http`](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto#L46) -annotation in your gRPC service definition. +annotations in your service definitions. -It helps you to provide your APIs in both gRPC and RESTful style at the same time. +It helps you provide your APIs in both gRPC and RESTful style at the same time. ![architecture introduction diagram](https://docs.google.com/drawings/d/12hp4CPqrNPFhattL_cIoJptFvlAqm5wLQ0ggqI5mkCg/pub?w=749&h=370) ## Check out our [documentation](https://grpc-ecosystem.github.io/grpc-gateway/)! ## Background -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 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 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. +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. ## Installation -First you need to install ProtocolBuffers 3.0.0 or later. -```sh -mkdir tmp -cd tmp -git clone https://github.com/protocolbuffers/protobuf -cd protobuf -./autogen.sh -./configure -make -make check -sudo make install -``` +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, `go get -u` as usual the following packages: @@ -44,8 +45,15 @@ 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-gateway` +* `protoc-gen-grpc-swagger` +* `protoc-gen-go` + +Make sure that your `$GOBIN` is in your `$PATH`. + ## Usage -Make sure that your `$GOPATH/bin` is in your `$PATH`. 1. Define your service in gRPC @@ -61,7 +69,8 @@ Make sure that your `$GOPATH/bin` is in your `$PATH`. rpc Echo(StringMessage) returns (StringMessage) {} } ``` -2. Add a [`google.api.http`](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto#L46) to your .proto file +2. Add a [`google.api.http`](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto#L46) +annotation to your .proto file your_service.proto: ```diff @@ -85,7 +94,11 @@ Make sure that your `$GOPATH/bin` is in your `$PATH`. } ``` - If you do not want to modify the proto file for use with grpc-gateway you can alternatively use an external [gRPC Service Configuration](https://cloud.google.com/endpoints/docs/grpc/grpc-service-config) file. [Check our documentation](https://grpc-ecosystem.github.io/grpc-gateway/docs/grpcapiconfiguration.html) for more information. + If you do not want to modify the proto file for use with grpc-gateway you can + alternatively use an external + [gRPC Service Configuration](https://cloud.google.com/endpoints/docs/grpc/grpc-service-config) file. + [Check our documentation](https://grpc-ecosystem.github.io/grpc-gateway/docs/grpcapiconfiguration.html) + for more information. 3. Generate gRPC stub @@ -131,8 +144,6 @@ Make sure that your `$GOPATH/bin` is in your `$PATH`. It will generate a reverse proxy `path/to/your_service.pb.gw.go`. - Note: After generating the code for each of the stubs, in order to build the code, you will want to run ```go get .``` from the directory containing the stubs. - 6. Write an entrypoint Now you need to write an entrypoint of the proxy server. @@ -191,13 +202,18 @@ Make sure that your `$GOPATH/bin` is in your `$PATH`. ``` ## Parameters and flags -`protoc-gen-grpc-gateway` supports custom mapping from Protobuf `import` to Golang import path. -They are compatible to [the parameters with same names in `protoc-gen-go`](https://github.com/golang/protobuf#parameters). +`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`](https://github.com/golang/protobuf#parameters) +(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. +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. +`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 More examples are available under `examples` directory. @@ -208,43 +224,54 @@ More examples are available under `examples` directory. * `server/main.go`: service implementation * `main.go`: entrypoint of the generated reverse proxy -To use the same port for custom HTTP handlers (e.g. serving `swagger.json`), gRPC-gateway, and a gRPC server, see [this code example by CoreOS](https://github.com/philips/grpc-gateway-example/blob/master/cmd/serve.go) (and its accompanying [blog post](https://coreos.com/blog/gRPC-protobufs-swagger.html)) +To use the same port for custom HTTP handlers (e.g. serving `swagger.json`), +gRPC-gateway, and a gRPC server, see +[this code example by CoreOS](https://github.com/philips/grpc-gateway-example/blob/master/cmd/serve.go) +(and its accompanying [blog post](https://coreos.com/blog/gRPC-protobufs-swagger.html)). ## Features + ### Supported -* Generating JSON API handlers -* Method parameters in request body -* Method parameters in request path -* Method parameters in query string + +* Generating JSON API handlers. +* Method parameters in request body. +* Method parameters in request path. +* Method parameters in query string. * Enum fields in path parameter (including repeated enum fields). -* Mapping streaming APIs to newline-delimited JSON streams +* Mapping streaming APIs to newline-delimited JSON streams. * Mapping HTTP headers with `Grpc-Metadata-` prefix to gRPC metadata (prefixed with `grpcgateway-`) -* Optionally emitting API definition for [Swagger](http://swagger.io). -* Setting [gRPC timeouts](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests) through inbound HTTP `Grpc-Timeout` header. -* Partial support for [gRPC API Configuration]((https://cloud.google.com/endpoints/docs/grpc/grpc-service-config)) files as an alternative to annotation. - -### Want to support -But not yet. -* Optionally generating the entrypoint. #8 -* `import_path` parameter +* Optionally emitting API definitions for +[OpenAPI (Swagger) v2](https://swagger.io/docs/specification/2-0/basic-structure/). +* Setting [gRPC timeouts](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests) +through inbound HTTP `Grpc-Timeout` header. +* Partial support for [gRPC API Configuration](https://cloud.google.com/endpoints/docs/grpc/grpc-service-config) +files as an alternative to annotation. +* Automatically translating PATCH requests into Field Mask gRPC requests. See +[the docs](https://grpc-ecosystem.github.io/grpc-gateway/docs/patch.html) +for more information. ### No plan to support But patch is welcome. -* Method parameters in HTTP headers -* Handling trailer metadata -* Encoding request/response body in XML -* True bi-directional streaming. (Probably impossible?) +* Method parameters in HTTP headers. +* Handling trailer metadata. +* Encoding request/response body in XML. +* True bi-directional streaming. # Mapping gRPC to HTTP -* [How gRPC error codes map to HTTP status codes in the response](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/runtime/errors.go#L15) -* 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](http://www.iana.org/assignments/message-headers/message-headers.xhtml) 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 (prefixed with `grpcgateway-`) -* While configurable, the default {un,}marshaling uses [jsonpb](https://godoc.org/github.com/golang/protobuf/jsonpb) with `OrigName: true`. - +* [How gRPC error codes map to HTTP status codes in the response](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/runtime/errors.go#L15). +* 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](http://www.iana.org/assignments/message-headers/message-headers.xhtml) +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 +(prefixed with `grpcgateway-`). +* While configurable, the default {un,}marshaling uses +[jsonpb](https://godoc.org/github.com/golang/protobuf/jsonpb) with +`OrigName: true`. # Contribution See [CONTRIBUTING.md](http://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md). diff --git a/go.mod b/go.mod new file mode 100644 index 0000000000..4c1a2ae717 --- /dev/null +++ b/go.mod @@ -0,0 +1,18 @@ +module github.com/grpc-ecosystem/grpc-gateway + +require ( + github.com/ghodss/yaml v1.0.0 + github.com/go-resty/resty v1.9.0 + github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b + github.com/golang/protobuf v1.2.0 + github.com/kr/pretty v0.1.0 // indirect + github.com/rogpeppe/fastuuid v0.0.0-20150106093220-6724a57986af + golang.org/x/net v0.0.0-20181220203305-927f97764cc3 + golang.org/x/sys v0.0.0-20181107165924-66b7b1311ac8 // indirect + google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8 + google.golang.org/grpc v1.16.0 + gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 // indirect + gopkg.in/yaml.v2 v2.0.0-20170812160011-eb3733d160e7 // indirect +) + +replace github.com/go-resty/resty => gopkg.in/resty.v1 v1.9.0 diff --git a/go.sum b/go.sum new file mode 100644 index 0000000000..ceb099f342 --- /dev/null +++ b/go.sum @@ -0,0 +1,43 @@ +cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw= +github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw= +github.com/ghodss/yaml v1.0.0 h1:wQHKEahhL6wmXdzwWG11gIVCkOv05bNOh+Rxn0yngAk= +github.com/ghodss/yaml v1.0.0/go.mod h1:4dBDuWmgqj2HViK6kFavaiC9ZROes6MMH2rRYeMEF04= +github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b h1:VKtxabqXZkF25pY9ekfRL6a582T4P37/31XEstQ5p58= +github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q= +github.com/golang/lint v0.0.0-20180702182130-06c8688daad7/go.mod h1:tluoj9z5200jBnyusfRPU2LqT6J+DAorxEvtC7LHB+E= +github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A= +github.com/golang/protobuf v1.2.0 h1:P3YflyNX/ehuJFLhxviNdFxQPkGK5cDcApsge1SqnvM= +github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U= +github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck= +github.com/kr/pretty v0.1.0 h1:L/CwN0zerZDmRFUapSPitk6f+Q3+0za1rQkzVuMiMFI= +github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo= +github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ= +github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE= +github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI= +github.com/rogpeppe/fastuuid v0.0.0-20150106093220-6724a57986af h1:gu+uRPtBe88sKxUCEXRoeCvVG90TJmwhiqRpvdhQFng= +github.com/rogpeppe/fastuuid v0.0.0-20150106093220-6724a57986af/go.mod h1:XWv6SoW27p1b0cqNHllgS5HIMJraePCO15w5zCzIWYg= +golang.org/x/lint v0.0.0-20180702182130-06c8688daad7/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE= +golang.org/x/net v0.0.0-20180611182652-db08ff08e862/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4= +golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4= +golang.org/x/net v0.0.0-20181220203305-927f97764cc3 h1:eH6Eip3UpmR+yM/qI9Ijluzb1bNv/cAU/n+6l8tRSis= +golang.org/x/net v0.0.0-20181220203305-927f97764cc3/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4= +golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U= +golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f h1:wMNYb4v58l5UBM7MYRLPG6ZhfOqbKu7X5eyFl8ZhKvA= +golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= +golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= +golang.org/x/sys v0.0.0-20181107165924-66b7b1311ac8 h1:YoY1wS6JYVRpIfFngRf2HHo9R9dAne3xbkGOQ5rJXjU= +golang.org/x/sys v0.0.0-20181107165924-66b7b1311ac8/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= +golang.org/x/text v0.3.0 h1:g61tztE5qeGQ89tm6NTjjM9VPIm088od1l6aSorWRWg= +golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= +golang.org/x/tools v0.0.0-20180828015842-6cd1fcedba52/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= +google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9YwlJXL52JkM= +google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8 h1:Nw54tB0rB7hY/N0NQvRW8DG4Yk3Q6T9cu9RcFQDu1tc= +google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc= +google.golang.org/grpc v1.16.0 h1:dz5IJGuC2BB7qXR5AyHNwAUBhZscK2xVez7mznh72sY= +google.golang.org/grpc v1.16.0/go.mod h1:0JHn/cJsOMiMfNA9+DeHDlAU7KAAB5GDlYFpa9MZMio= +gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 h1:qIbj1fsPNlZgppZ+VLlY7N33q108Sa+fhmuc+sWQYwY= +gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/resty.v1 v1.9.0/go.mod h1:vo52Hzryw9PnPHcJfPsBiFW62XhNx5OczbV9y+IMpgc= +gopkg.in/yaml.v2 v2.0.0-20170812160011-eb3733d160e7 h1:+t9dhfO+GNOIGJof6kPOAenx7YgrZMTdRPV+EsnPabk= +gopkg.in/yaml.v2 v2.0.0-20170812160011-eb3733d160e7/go.mod h1:JAlM8MvJe8wmxCU4Bli9HhUf9+ttbYbLASfIpnQbh74= +honnef.co/go/tools v0.0.0-20180728063816-88497007e858/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=