[Awesome Go, Iris] Use Iris as the gRPC-Gateway which translates a RESTful HTTP API into gRPC

Iris as gRPC-Gateway

gRPC is a modern open source high performance Remote Procedure Call framework that can run in any environment. It can efficiently connect services in and across data centers with pluggable support for load balancing, tracing, health checking and authentication. It is also applicable in last mile of distributed computing to connect devices, mobile applications and browsers to backend services.

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 article describe how Iris and gRPC integration as a gRPC-Gateway lives inside the mvc package.

Have you ever have difficulties converting your app or parts of it from HTTP to gGRPC or did you ever wish you had decent HTTP framework support as well for your gRPC services?

Now, with Iris you have the best of two worlds. Without change a bit of your existing gRPC services code, you can register them as Iris HTTP routes through a Controller (your service struct value).

Prerequisites

Step by step

We will follow the official helloworld gRPC example - https://github.com/grpc/grpc-go/tree/master/examples/helloworld. If you had already work with gRPC services you can skip 1-5.

  1. Let’s write our proto schema for request and response.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
syntax = "proto3";

package helloworld;

// The greeting service definition.
service Greeter {
// Sends a greeting
rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
string name = 1;
}

// The response message containing the greetings
message HelloReply {
string message = 1;
}
  1. Install the protoc Go plugin
1
2
$ go get -u google.golang.org/protobuf/cmd/protoc-gen-go \
google.golang.org/grpc/cmd/protoc-gen-go-grpc
  1. Generate Go file from the helloworld.proto file above

Before you can use the new service method, you need to recompile the updated .proto file.

While still in the examples/helloworld directory, run the following command:

1
2
3
$ protoc --go_out=. --go_opt=paths=source_relative \
--go-grpc_out=. --go-grpc_opt=paths=source_relative \
helloworld/helloworld.proto

This will regenerate the helloworld/helloworld.pb.go and helloworld/helloworld_grpc.pb.go files, which contain:

  • Code for populating, serializing, and retrieving HelloRequest and HelloReply message types.

  • Generated client and server code.

  1. Implement a gRPC service as usually, with or without Iris
1
2
3
4
5
6
7
8
9
10
11
import (
// [...]
pb "myapp/helloworld"
"context"
)
type Greeter struct { }

// SayHello implements helloworld.GreeterServer.
func (c *Greeter) SayHello(ctx context.Context, in *pb.HelloRequest) (*pb.HelloReply, error) {
return &pb.HelloReply{Message: "Hello " + in.GetName()}, nil
}

Iris automatically binds the standard “context” context.Context to iris.Context.Request().Context() and any other structure that is not mapping to a registered dependency as a payload (depending on the request), e.g XML, YAML, Query, Form, JSON, Protobuf.

  1. Register your service to the gRPC server
1
2
3
4
5
6
7
8
9
import (
// [...]
pb "myapp/helloworld"
"google.golang.org/grpc"
)
grpcServer := grpc.NewServer()

myService := &Greeter{}
pb.RegisterGreeterServer(grpcServer, myService)
  1. Register this myService to Iris

The mvc.New(party).Handle(ctrl, mvc.GRPC{...}) option allows to register gRPC services per-party (without the requirement of a full wrapper) and optionally strict access to gRPC-only clients.

Register MVC application controller for gRPC services. You can bind as many mvc gRpc services in the same Party or app, as the ServiceName differs.

1
2
3
4
5
6
7
8
9
10
11
12
13
import (
// [...]
"github.com/kataras/iris/v12"
"github.com/kataras/iris/v12/mvc"
)
app := iris.New()

rootApp := mvc.New(app)
rootApp.Handle(myService, mvc.GRPC{
Server: grpcServer, // Required.
ServiceName: "helloworld.Greeter", // Required.
Strict: false,
})
  1. Generate TLS Keys

The Iris server should ran under TLS (it’s a gRPC requirement).

1
2
$ openssl genrsa -out server.key 2048
$ openssl req -new -x509 -sha256 -key server.key -out server.crt -days 3650
  1. Listen and Serve
1
app.Run(iris.TLS(":443", "server.crt", "server.key"))

Then, POST: https://localhost:443/helloworld.Greeter/SayHello with request data: {“name”: “John”} xpected output: {“message”: “Hello John”}.

Both HTTP Client and gRPC client will be able to communicate with our Iris+gRPC service.

Exercise files

Full Server, Clients and Testing Code can be found at: https://github.com/kataras/iris/tree/master/_examples/mvc/grpc-compatible.

References

[1] gRPC - Iris - https://docs.iris-go.com/iris/mvc/mvc-grpc

[2] Grpc · kataras/iris Wiki · GitHub - https://github.com/kataras/iris/wiki/Grpc

[3] grpc-go/examples/helloworld at master · grpc/grpc-go · GitHub - https://github.com/grpc/grpc-go/tree/master/examples/helloworld

[4] iris/_examples/mvc/grpc-compatible at master · kataras/iris · GitHub - https://github.com/kataras/iris/tree/master/_examples/mvc/grpc-compatible

[5] Quick start | Go | gRPC - https://grpc.io/docs/languages/go/quickstart/

[6] Protocol buffer - https://developers.google.com/protocol-buffers compiler, protoc, version 3 - https://developers.google.com/protocol-buffers/docs/proto3.

[7] The Go Programming Language - https://golang.org/

[8] Iris - https://www.iris-go.com/

[9] GitHub - grpc-ecosystem/grpc-gateway: gRPC to JSON proxy generator following the gRPC HTTP spec - https://github.com/grpc-ecosystem/grpc-gateway

[10] /index.html - https://www.openssl.org/

[11] Homebrew - https://brew.sh/