Skip to content

Commit

Permalink
chore(grpc-gateway) import grpc-gateway plugin into kong
Browse files Browse the repository at this point in the history
As a result of an effort to improve external plugins maintainership,
we are importing currently-bundled plugins into Kong's main tree.
This plugin used to live in https://github.com/Kong/kong-plugin-grpc-gateway.
  • Loading branch information
gszr committed Jun 17, 2021
2 parents 9150524 + 762c3f2 commit 644d861
Show file tree
Hide file tree
Showing 8 changed files with 760 additions and 0 deletions.
32 changes: 32 additions & 0 deletions kong/plugins/grpc-gateway/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Table of Contents

- [0.1.3](#013---20210603)
- [0.1.2](#012---20201105)
- [0.1.1](#011---20200526)
- [0.1.0](#010---20200521)

## [0.1.3] - 2021/06/03

- Fix typo from gatewat to gateway (#16)
- Correctly clear URI args in rewrite (#23)
- Map grpc-status to HTTP status code (#25)

## [0.1.2] - 2020/11/05

- Allows `include` directives in protoc files by adding the
main protoc file's directory as base for non-absolute paths
- Clear up output buffer when getting partial response (#12)

## [0.1.1] - 2020/05/26

- Set priority to 998 to avoid clash with other plugins.
- Pin lua-protobuf to 0.3

## [0.1.0] - 2020/05/21

- Initial release of gRPC gateway plugin for Kong.

[0.1.3]: https://github.com/Kong/kong-plugin-grpc-gateway/compare/0.1.2...0.1.3
[0.1.2]: https://github.com/Kong/kong-plugin-grpc-gateway/compare/0.1.1...0.1.2
[0.1.1]: https://github.com/Kong/kong-plugin-grpc-gateway/compare/0.1.0...0.1.1
[0.1.0]
121 changes: 121 additions & 0 deletions kong/plugins/grpc-gateway/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
# Kong gRPC-gateway plugin

A [Kong] plugin to allow access to a gRPC service via HTTP REST requests and translate requests and
responses in a JSON format. Similar to
[gRPC-gateway](https://github.com/grpc-ecosystem/grpc-gateway).

## Description

This plugin translates requests and responses between gRPC and HTTP REST.

## Usage

This plugin is intended to be used in a Kong route between a gRPC service and an HTTP endpoint.

Sample configuration via declarative (YAML):

```yaml
_format_version: "1.1"
services:
- protocol: grpc
host: localhost
port: 9000
routes:
- protocols:
- http
paths:
- /
plugins:
- name: grpc-gateway
config:
proto: path/to/hello.proto
```
Same thing via the administation API:
```bash
$ # add the gRPC service
$ curl -XPOST localhost:8001/services \
--data name=grpc \
--data protocol=grpc \
--data host=localhost \
--data port=9000

$ # add an http route
$ curl -XPOST localhost:8001/services/grpc/routes \
--data protocols=http \
--data name=web-service \
--data paths[]=/

$ # add the plugin to the route
$ curl -XPOST localhost:8001/routes/web-service/plugins \
--data name=grpc-gateway
```

The proto file must contain the
[HTTP REST to gRPC mapping rule](https://github.com/googleapis/googleapis/blob/fc37c47e70b83c1cc5cc1616c9a307c4303fe789/google/api/http.proto).

In the example we use the following mapping (note the `option (google.api.http) = {}` section):

```protobuf
syntax = "proto2";
package hello;
service HelloService {
rpc SayHello(HelloRequest) returns (HelloResponse) {
option (google.api.http) = {
get: "/v1/messages/{greeting}"
additional_bindings {
get: "/v1/messages/legacy/{greeting=**}"
}
post: "/v1/messages/"
body: "*"
}
}
}
// The request message containing the user's name.
message HelloRequest {
string greeting = 1;
}
// The response message containing the greetings
message HelloReply {
string message = 1;
}
```

In this example, we can send following requests to Kong that translates to corresponding gRPC requests:

```shell
# grpc-go/examples/features/reflection/server $ go run main.go &

curl -XGET localhost:8000/v1/messages/Kong2.0
{"message":"Hello Kong2.0"}

curl -XGET localhost:8000/v1/messages/legacy/Kong2.0
{"message":"Hello Kong2.0"}

curl -XGET localhost:8000/v1/messages/legacy/Kong2.0/more/paths
{"message":"Hello Kong2.0\/more\/paths"}

curl -XPOST localhost:8000/v1/messages/Kong2.0 -d '{"greeting":"kong2.0"}'
{"message":"Hello kong2.0"}
```

All syntax defined in [Path template syntax](https://github.com/googleapis/googleapis/blob/fc37c47e70b83c1cc5cc1616c9a307c4303fe789/google/api/http.proto#L225)
is supported.

Currently only unary requests are supported, streaming requests are not supported.

## Dependencies

The gRPC-gateway plugin depends on [lua-protobuf], [lua-cjson] and [lua-pack]

[Kong]: https://konghq.com
[lua-protobuf]: https://github.com/starwing/lua-protobuf
[lua-cjson]: https://github.com/openresty/lua-cjson
[lua-pack]: https://github.com/Kong/lua-pack

Loading

0 comments on commit 644d861

Please sign in to comment.