Minimize API surface in anticipation of gorelease (grpc-ecosystem#1146)

* Move examples under internal to avoid importing

This is necessary as part of adding gorelease to our CI.
These packages could otherwise be considered part of our public API.
This will break users who are importing these examples in their own
projects.

* Rename imports and regenerate files

* Make generator internals private

This helps remove public API surface

* Move codegenerator package to internal

This reduces our API surface

.circleci/config.yml

@@ -26,7 +26,7 @@ jobs:
       - run: go mod vendor
       - run: >
           . $HOME/.nvm/nvm.sh &&
-          cd examples/browser &&
+          cd examples/internal/browser &&
           npm install gulp-cli &&
           npm install &&
           ./node_modules/.bin/gulp

Makefile

@@ -11,8 +11,8 @@ SWAGGER_PLUGIN=bin/protoc-gen-swagger
 SWAGGER_PLUGIN_SRC= utilities/doc.go \
 		    utilities/pattern.go \
 		    utilities/trie.go \
-		    protoc-gen-swagger/genswagger/generator.go \
-		    protoc-gen-swagger/genswagger/template.go \
+		    protoc-gen-swagger/internal/genswagger/generator.go \
+		    protoc-gen-swagger/internal/genswagger/template.go \
 		    protoc-gen-swagger/main.go
 SWAGGER_PLUGIN_PKG=./protoc-gen-swagger
 GATEWAY_PLUGIN=bin/protoc-gen-grpc-gateway
@@ -21,22 +21,22 @@ GATEWAY_PLUGIN_SRC= utilities/doc.go \
 		    utilities/pattern.go \
 		    utilities/trie.go \
 		    protoc-gen-grpc-gateway \
-		    protoc-gen-grpc-gateway/descriptor \
-		    protoc-gen-grpc-gateway/descriptor/registry.go \
-		    protoc-gen-grpc-gateway/descriptor/services.go \
-		    protoc-gen-grpc-gateway/descriptor/types.go \
-		    protoc-gen-grpc-gateway/descriptor/grpc_api_configuration.go \
-		    protoc-gen-grpc-gateway/descriptor/grpc_api_service.go \
-		    protoc-gen-grpc-gateway/generator \
-		    protoc-gen-grpc-gateway/generator/generator.go \
-		    protoc-gen-grpc-gateway/gengateway \
-		    protoc-gen-grpc-gateway/gengateway/doc.go \
-		    protoc-gen-grpc-gateway/gengateway/generator.go \
-		    protoc-gen-grpc-gateway/gengateway/template.go \
-		    protoc-gen-grpc-gateway/httprule \
-		    protoc-gen-grpc-gateway/httprule/compile.go \
-		    protoc-gen-grpc-gateway/httprule/parse.go \
-		    protoc-gen-grpc-gateway/httprule/types.go \
+		    internal/descriptor \
+		    internal/descriptor/registry.go \
+		    internal/descriptor/services.go \
+		    internal/descriptor/types.go \
+		    internal/descriptor/grpc_api_configuration.go \
+		    internal/descriptor/grpc_api_service.go \
+		    internal/generator \
+		    internal/generator/generator.go \
+		    protoc-gen-grpc-gateway/internal/gengateway \
+		    protoc-gen-grpc-gateway/internal/gengateway/doc.go \
+		    protoc-gen-grpc-gateway/internal/gengateway/generator.go \
+		    protoc-gen-grpc-gateway/internal/gengateway/template.go \
+		    internal/httprule \
+		    internal/httprule/compile.go \
+		    internal/httprule/parse.go \
+		    internal/httprule/types.go \
 		    protoc-gen-grpc-gateway/main.go
 GATEWAY_PLUGIN_FLAGS?=
 SWAGGER_PLUGIN_FLAGS?=
@@ -50,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=github.com/grpc-ecosystem/grpc-gateway/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/internal/proto/sub/message.proto=github.com/grpc-ecosystem/grpc-gateway/examples/internal/proto/sub
 ADDITIONAL_GW_FLAGS=
 ifneq "$(GATEWAY_PLUGIN_FLAGS)" ""
 	ADDITIONAL_GW_FLAGS=,$(GATEWAY_PLUGIN_FLAGS)
@@ -59,39 +59,42 @@ ADDITIONAL_SWG_FLAGS=
 ifneq "$(SWAGGER_PLUGIN_FLAGS)" ""
 	ADDITIONAL_SWG_FLAGS=,$(SWAGGER_PLUGIN_FLAGS)
 endif
-SWAGGER_EXAMPLES=examples/proto/examplepb/echo_service.proto \
-	 examples/proto/examplepb/a_bit_of_everything.proto \
-	 examples/proto/examplepb/wrappers.proto \
-	 examples/proto/examplepb/stream.proto \
-	 examples/proto/examplepb/unannotated_echo_service.proto \
-	 examples/proto/examplepb/use_go_template.proto \
-	 examples/proto/examplepb/response_body_service.proto
-
-EXAMPLES=examples/proto/examplepb/echo_service.proto \
-	 examples/proto/examplepb/a_bit_of_everything.proto \
-	 examples/proto/examplepb/stream.proto \
-	 examples/proto/examplepb/flow_combination.proto \
-	 examples/proto/examplepb/non_standard_names.proto \
-	 examples/proto/examplepb/wrappers.proto \
-	 examples/proto/examplepb/unannotated_echo_service.proto \
-	 examples/proto/examplepb/use_go_template.proto \
-	 examples/proto/examplepb/response_body_service.proto
+SWAGGER_EXAMPLES=examples/internal/proto/examplepb/echo_service.proto \
+	 examples/internal/proto/examplepb/a_bit_of_everything.proto \
+	 examples/internal/proto/examplepb/wrappers.proto \
+	 examples/internal/proto/examplepb/stream.proto \
+	 examples/internal/proto/examplepb/unannotated_echo_service.proto \
+	 examples/internal/proto/examplepb/use_go_template.proto \
+	 examples/internal/proto/examplepb/response_body_service.proto
+
+EXAMPLES=examples/internal/proto/examplepb/echo_service.proto \
+	 examples/internal/proto/examplepb/a_bit_of_everything.proto \
+	 examples/internal/proto/examplepb/stream.proto \
+	 examples/internal/proto/examplepb/flow_combination.proto \
+	 examples/internal/proto/examplepb/non_standard_names.proto \
+	 examples/internal/proto/examplepb/wrappers.proto \
+	 examples/internal/proto/examplepb/unannotated_echo_service.proto \
+	 examples/internal/proto/examplepb/use_go_template.proto \
+	 examples/internal/proto/examplepb/response_body_service.proto
 
 EXAMPLE_SVCSRCS=$(EXAMPLES:.proto=.pb.go)
 EXAMPLE_GWSRCS=$(EXAMPLES:.proto=.pb.gw.go)
 EXAMPLE_SWAGGERSRCS=$(SWAGGER_EXAMPLES:.proto=.swagger.json)
-EXAMPLE_DEPS=examples/proto/pathenum/path_enum.proto examples/proto/sub/message.proto examples/proto/sub2/message.proto
+EXAMPLE_DEPS=examples/internal/proto/pathenum/path_enum.proto examples/internal/proto/sub/message.proto examples/internal/proto/sub2/message.proto
 EXAMPLE_DEPSRCS=$(EXAMPLE_DEPS:.proto=.pb.go)
 
-EXAMPLE_CLIENT_DIR=examples/clients
-ECHO_EXAMPLE_SPEC=examples/proto/examplepb/echo_service.swagger.json
+RUNTIME_TEST_PROTO=runtime/internal/examplepb/example.proto
+RUNTIME_TEST_SRCS=$(RUNTIME_TEST_PROTO:.proto=pb.go)
+
+EXAMPLE_CLIENT_DIR=examples/internal/clients
+ECHO_EXAMPLE_SPEC=examples/internal/proto/examplepb/echo_service.swagger.json
 ECHO_EXAMPLE_SRCS=$(EXAMPLE_CLIENT_DIR)/echo/client.go \
 		  $(EXAMPLE_CLIENT_DIR)/echo/response.go \
 		  $(EXAMPLE_CLIENT_DIR)/echo/configuration.go \
 		  $(EXAMPLE_CLIENT_DIR)/echo/api_echo_service.go \
 		  $(EXAMPLE_CLIENT_DIR)/echo/model_examplepb_simple_message.go \
 		  $(EXAMPLE_CLIENT_DIR)/echo/model_examplepb_embedded.go
-ABE_EXAMPLE_SPEC=examples/proto/examplepb/a_bit_of_everything.swagger.json
+ABE_EXAMPLE_SPEC=examples/internal/proto/examplepb/a_bit_of_everything.swagger.json
 ABE_EXAMPLE_SRCS=$(EXAMPLE_CLIENT_DIR)/abe/model_a_bit_of_everything_nested.go \
 		 $(EXAMPLE_CLIENT_DIR)/abe/api_a_bit_of_everything_service.go \
 		 $(EXAMPLE_CLIENT_DIR)/abe/client.go \
@@ -108,13 +111,13 @@ ABE_EXAMPLE_SRCS=$(EXAMPLE_CLIENT_DIR)/abe/model_a_bit_of_everything_nested.go \
 		 $(EXAMPLE_CLIENT_DIR)/abe/model_pathenum_path_enum.go \
 		 $(EXAMPLE_CLIENT_DIR)/abe/model_protobuf_field_mask.go \
 		 $(EXAMPLE_CLIENT_DIR)/abe/response.go
-UNANNOTATED_ECHO_EXAMPLE_SPEC=examples/proto/examplepb/unannotated_echo_service.swagger.json
+UNANNOTATED_ECHO_EXAMPLE_SPEC=examples/internal/proto/examplepb/unannotated_echo_service.swagger.json
 UNANNOTATED_ECHO_EXAMPLE_SRCS=$(EXAMPLE_CLIENT_DIR)/unannotatedecho/client.go \
 		 $(EXAMPLE_CLIENT_DIR)/unannotatedecho/response.go \
 		 $(EXAMPLE_CLIENT_DIR)/unannotatedecho/configuration.go \
 		 $(EXAMPLE_CLIENT_DIR)/unannotatedecho/model_examplepb_unannotated_simple_message.go \
 		 $(EXAMPLE_CLIENT_DIR)/unannotatedecho/api_unannotated_echo_service.go
-RESPONSE_BODY_EXAMPLE_SPEC=examples/proto/examplepb/response_body_service.swagger.json
+RESPONSE_BODY_EXAMPLE_SPEC=examples/internal/proto/examplepb/response_body_service.swagger.json
 RESPONSE_BODY_EXAMPLE_SRCS=$(EXAMPLE_CLIENT_DIR)/responsebody/client.go \
 		 $(EXAMPLE_CLIENT_DIR)/responsebody/response.go \
 		 $(EXAMPLE_CLIENT_DIR)/responsebody/configuration.go \
@@ -157,39 +160,43 @@ $(EXAMPLE_DEPSRCS): $(GO_PLUGIN) $(EXAMPLE_DEPS)
 	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
+$(RUNTIME_TEST_SRCS): $(GO_PLUGIN) $(RUNTIME_TEST_PROTO)
+	protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(GO_PLUGIN) --go_out=$(PKGMAP),plugins=grpc,paths=source_relative:. $(RUNTIME_TEST_PROTO)
+
+$(EXAMPLE_GWSRCS): ADDITIONAL_GW_FLAGS:=$(ADDITIONAL_GW_FLAGS),grpc_api_configuration=examples/internal/proto/examplepb/unannotated_echo_service.yaml
 $(EXAMPLE_GWSRCS): $(GATEWAY_PLUGIN) $(EXAMPLES)
 	protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(GATEWAY_PLUGIN) --grpc-gateway_out=logtostderr=true,allow_repeated_fields_in_body=true,$(PKGMAP)$(ADDITIONAL_GW_FLAGS):. $(EXAMPLES)
 
-$(EXAMPLE_SWAGGERSRCS): ADDITIONAL_SWG_FLAGS:=$(ADDITIONAL_SWG_FLAGS),grpc_api_configuration=examples/proto/examplepb/unannotated_echo_service.yaml
+$(EXAMPLE_SWAGGERSRCS): ADDITIONAL_SWG_FLAGS:=$(ADDITIONAL_SWG_FLAGS),grpc_api_configuration=examples/internal/proto/examplepb/unannotated_echo_service.yaml
 $(EXAMPLE_SWAGGERSRCS): $(SWAGGER_PLUGIN) $(SWAGGER_EXAMPLES)
 	protoc -I $(PROTOC_INC_PATH) -I. -I$(GOOGLEAPIS_DIR) --plugin=$(SWAGGER_PLUGIN) --swagger_out=logtostderr=true,allow_repeated_fields_in_body=true,use_go_templates=true,$(PKGMAP)$(ADDITIONAL_SWG_FLAGS):. $(SWAGGER_EXAMPLES)
 
 $(ECHO_EXAMPLE_SRCS): $(ECHO_EXAMPLE_SPEC)
 	$(SWAGGER_CODEGEN) generate -i $(ECHO_EXAMPLE_SPEC) \
-	    -l go -o examples/clients/echo --additional-properties packageName=echo
+	    -l go -o examples/internal/clients/echo --additional-properties packageName=echo
 	@rm -f $(EXAMPLE_CLIENT_DIR)/echo/README.md \
 		$(EXAMPLE_CLIENT_DIR)/echo/git_push.sh
 $(ABE_EXAMPLE_SRCS): $(ABE_EXAMPLE_SPEC)
 	$(SWAGGER_CODEGEN) generate -i $(ABE_EXAMPLE_SPEC) \
-	    -l go -o examples/clients/abe --additional-properties packageName=abe
+	    -l go -o examples/internal/clients/abe --additional-properties packageName=abe
 	@rm -f $(EXAMPLE_CLIENT_DIR)/abe/README.md \
 		$(EXAMPLE_CLIENT_DIR)/abe/git_push.sh
 $(UNANNOTATED_ECHO_EXAMPLE_SRCS): $(UNANNOTATED_ECHO_EXAMPLE_SPEC)
 	$(SWAGGER_CODEGEN) generate -i $(UNANNOTATED_ECHO_EXAMPLE_SPEC) \
-	    -l go -o examples/clients/unannotatedecho --additional-properties packageName=unannotatedecho
+	    -l go -o examples/internal/clients/unannotatedecho --additional-properties packageName=unannotatedecho
 	@rm -f $(EXAMPLE_CLIENT_DIR)/unannotatedecho/README.md \
 		$(EXAMPLE_CLIENT_DIR)/unannotatedecho/git_push.sh
 $(RESPONSE_BODY_EXAMPLE_SRCS): $(RESPONSE_BODY_EXAMPLE_SPEC)
 	$(SWAGGER_CODEGEN) generate -i $(RESPONSE_BODY_EXAMPLE_SPEC) \
-	    -l go -o examples/clients/responsebody --additional-properties packageName=responsebody
+	    -l go -o examples/internal/clients/responsebody --additional-properties packageName=responsebody
 	@rm -f $(EXAMPLE_CLIENT_DIR)/responsebody/README.md \
 		$(EXAMPLE_CLIENT_DIR)/responsebody/git_push.sh
 
 examples: $(EXAMPLE_DEPSRCS) $(EXAMPLE_SVCSRCS) $(EXAMPLE_GWSRCS) $(EXAMPLE_SWAGGERSRCS) $(EXAMPLE_CLIENT_SRCS)
-test: examples
+testproto: $(RUNTIME_TEST_SRCS)
+test: examples testproto
 	go test -short -race ./...
-	go test -race ./examples/integration -args -network=unix -endpoint=test.sock
+	go test -race ./examples/internal/integration -args -network=unix -endpoint=test.sock
 changelog:
 	docker run --rm \
 		--interactive \
@@ -224,5 +231,6 @@ realclean: distclean
 	rm -f $(EXAMPLE_SWAGGERSRCS)
 	rm -f $(EXAMPLE_CLIENT_SRCS)
 	rm -f $(OPENAPIV2_GO)
+	rm -f $(RUNTIME_TEST_SRCS)
 
 .PHONY: generate examples test lint clean distclean realclean

README.md

@@ -113,7 +113,7 @@ annotation to your .proto file
     }
    ```
 
-   See [a_bit_of_everything.proto](examples/proto/examplepb/a_bit_of_everything.proto)
+   See [a_bit_of_everything.proto](examples/internal/proto/examplepb/a_bit_of_everything.proto)
    for examples of more annotations you can add to customize gateway behavior
    and generated Swagger output.
 
@@ -261,7 +261,7 @@ 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](protoc-gen-swagger/options/openapiv2.proto) - see
-[a_bit_of_everything.proto](examples/proto/examplepb/a_bit_of_everything.proto)
+[a_bit_of_everything.proto](examples/internal/proto/examplepb/a_bit_of_everything.proto)
 for examples.
 
 ## More Examples

docs/_docs/examples.md

@@ -4,7 +4,7 @@ category: documentation
 
 # Examples
 
-Examples are available under `examples` directory.
+Examples are available under `examples/internal` 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 service
   * `proto/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 service

docs/_docs/faq.md

@@ -17,7 +17,7 @@ See the question above at first.
 Grpc-gateway is intended to cover 80% of use cases without forcing you to write comprehensive but complicated annotations. So grpc-gateway itself does not always cover all the use cases you have by design. In other words, grpc-gateway automates typical boring boilerplate mapping between gRPC and HTTP/1 communication, but it does not do arbitrarily complex custom mappings for you.
 
 On the other hand, you can still add whatever you want as a middleware which wraps [`runtime.ServeMux`](http://godoc.org/github.com/grpc-ecosystem/grpc-gateway/runtime#ServeMux).  Since `runtime.ServeMux` is just a standard [`http.Handler`](http://golang.org/pkg/http#Handler), you can easily write a custom wrapper of `runtime.ServeMux`, leveraged with existing third-party libraries in Go.
-e.g. https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/main.go
+e.g. https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/main.go
 
 ## My gRPC server is written in (Scala|C++|Ruby|Haskell|....). Is there a (Scala|C++|Ruby|Haskell|....) version of grpc-gateway?
 

docs/_docs/patch.md

@@ -7,8 +7,8 @@ The HTTP PATCH method allows a resource to be partially updated.
 
 The idea, If a binding is mapped to patch and the request message has exactly one FieldMask message in it, additional code is rendered for the gateway handler that will populate the FieldMask based on the request body.
 There are two scenarios:
-- The FieldMask is hidden from the REST request as per the [Google API design guide](https://cloud.google.com/apis/design/standard_methods#update) (as in the first additional binding in the [UpdateV2](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/proto/examplepb/a_bit_of_everything.proto#L366) example). In this case, the FieldMask is updated from the request body and set in the gRPC request message.
-- The FieldMask is exposed to the REST request (as in the second additional binding in the [UpdateV2](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/proto/examplepb/a_bit_of_everything.proto#L370) example). For this case, the field mask is left untouched by the gateway.
+- The FieldMask is hidden from the REST request as per the [Google API design guide](https://cloud.google.com/apis/design/standard_methods#update) (as in the first additional binding in the [UpdateV2](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto#L366) example). In this case, the FieldMask is updated from the request body and set in the gRPC request message.
+- The FieldMask is exposed to the REST request (as in the second additional binding in the [UpdateV2](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto#L370) example). For this case, the field mask is left untouched by the gateway.
 
 ## Example Usage
 1. Create PATCH request.

docs/_docs/usage.md

@@ -68,7 +68,7 @@ Make sure that your `$GOPATH/bin` is in your `$PATH`.
     }
    ```
 
-   See [a_bit_of_everything.proto](examples/proto/examplepb/a_bit_of_everything.proto)
+   See [a_bit_of_everything.proto](examples/internal/proto/examplepb/a_bit_of_everything.proto)
    for examples of more annotations you can add to customize gateway behavior
    and generated Swagger output.
 
@@ -202,7 +202,7 @@ 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](protoc-gen-swagger/options/openapiv2.proto) - see
-[a_bit_of_everything.proto](examples/proto/examplepb/a_bit_of_everything.proto)
+[a_bit_of_everything.proto](examples/internal/proto/examplepb/a_bit_of_everything.proto)
 for examples.
 
 # Mapping gRPC to HTTP

docs/_docs/usegotemplates.md

@@ -90,4 +90,4 @@ This is how the swagger file would be rendered in [Postman](https://www.getpostm
 
 ![Screenshot swaggerfile in Postman](../_imgs/gotemplates/postman.png "Postman")
 
-For a more detailed example of a protofile that has Go templates enabled, [click here](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/proto/examplepb/use_go_template.proto "Example protofile with Go template").
+For a more detailed example of a protofile that has Go templates enabled, [click here](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/use_go_template.proto "Example protofile with Go template").

examples/README.md → examples/internal/README.md

@@ -9,7 +9,7 @@ Follow the guides from this [README.md](./browser/README.md) to run the server a
 ```bash
 # Make sure you are in the correct directory: 
 # $GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/examples
-$ cd examples/browser
+$ cd examples/internal/browser
 $ pwd
 
 # Install gulp