Cloud Native Computing Foundation gRPC Conf 2020, 5 Aug 2020

Previous Meeting

⏯

youtube image

►

From YouTube: Writing REST Services for the gRPC-curious - Johan Brandhorst, Buf

Description

Writing REST Services for the gRPC-curious - Johan Brandhorst, Buf

Introducing the gRPC-Gateway, which makes it possible to expose a JSON/REST interface while maintaining many of the benefits of using gRPC.

The first 10 or so minutes will be spent laying the technical ground for the talk by talking about JSON/REST, giving a quick intro into gRPC and [protocol buffers](https://developers.google.com/protocol-buffers/), then introducing the gRPC-Gateway as a way to integrate gRPC into existing architectures with strict JSON/REST interface requirements.

There will then be a live demo showing the power of this workflow by iterating on a simple design. The audience will be able to follow along on their own by cloning the [boilerplate repository](https://github.com/johanbrandhorst/grpc-gateway-boilerplate).

Gradually more complicated topics like PATCH requests, middleware, authentication, working with browser clients, cookies, WebSockets and more will be introduced.

A

Hi everyone, I'm johan, I'm a maintainer of various open source projects, including the grpc gateway and improbable grpc web I've contributed to go, and I run a blog writing mainly about go and grpc.

A

This is my first grpc conf and it's great to be part of it.

A

I work at buff where we are working on api management tooling, for protobuf users through schema-driven development. We already support linting of protofiles and breaking change detection and we've got some really exciting products in the works, including the buff schema registry and automated protobuf file generation and dependency management check out our website for more information.

A

Let's dive into the talk today, we're going to look at what we mean by http json, what it's used for and explore some problems associated with it. We're then going to learn about how we can get the best of both worlds, but best of both grpc and http json with the grpc gateway.

A

We'll then have some dem live demo of it in action.

A

What do we mean when we say http json?

A

We mean a restful interface, making use of the http verbs, get post, put patch delete and using json as the payload content type. This is the de facto standard for most public apis. Today, sometimes it's not entirely restful, but it's almost always using json.

A

It's easy for humans to read and write. It's got native javascript support. All is well right is everything well, as anyone who's ever had to quickly push a configuration fix to your json configured service notes, trailing commas are forbidden in json.

A

I wish I was joking in saying that this is a big problem, but entirely new formats have been developed to deal with this problem. There's also no support for comments. It's unnecessarily verbose on the wire, but compression can help mitigate this in large deployments. The marshalling and unmarshaling of json is a constant strain on response. Latency.

A

Most importantly, it's not well typed enough and there's no single way to define the interface types open. Api is an option, but it's not globally adopted. Most of these problems stem from the fact that json was designed to be human readable, but also effective for a machine to use. These two properties are unfortunately, incompatible.

A

Protocol buffers ngrpc, provides all the benefits we care about over http json, such as speed type safety, a single source of truth code generation and much more. We know this, which is why we're using grpc, but why hasn't the whole world switched to protobuf and grpc?

A

Unfortunately, it's not always so easy to switch entire application stacks to new frameworks.

A

Often there are a number of reasons why we keep using old standards when new, better alternatives are available, such as compatibility with existing systems, management pressure and, in this case the still prevalent expectation that a public asia api should be using http json.

A

What can we do when we want to use grpc but are forced to use http json, the grpc gateway project allows you to design grpc and http json services. At the same time, it uses a custom protobuf generator that generates a simple reverse proxy that translates on the fly from json to protobuf and back again it allows you to define a url path and http verb to grpc service method mapping with a simple annotation scheme in the profiles.

A

As you can see here, it also provides a swagger open api generator, in which, in case, you have some generator in case you have some generator. You want to use that requires the open api format, I've added the http json annotations to the previously defined service methods. Above as you can see, the http verb and url path. Mappings are defined within the rpc definitions.

A

So how does it work? This image shows the basic building blocks of the gateway. You generate a jrpc service as usual, with product django or producee, and then you use our custom generator prorock, gen grpc gateway to generate a gateway handler file which registers the mapped, http, verbs and url paths to a central max, which is then used to serve the external http json interface, it's common to serve the grc gateway and the grc server on different ports of the same server to allow both http json clients and jfc clients. But this is not mandatory.

A

The gateway can also be used with non-go grpc services. You simply connect to an external grpc service. In the setup you can even serve the gateway and grpc server. On the same port and split traffic using http headers, if you want to get fancy.

A

Okay, now we're going to go into a little bit of a live demo of the jrz gateway in action and you'll get a few seconds here to copy down the url for my open source, boilerplate repo and then I'm going to switch the repo and we're going to do some live coding.

A

Together, okay, let me change the presentation.

A

Okay, now we've switched to the boilerplate repo and the first thing we're going to look at is the profile so you're all probably familiar with how profiles look. So this is not going to be strange and, as you can see, we've just got some a package declaration, a syntax declaration and some imports.

A

We're then defining the go package which is naturally part of using a go grpc server.

A

Then we've got some extra annotations here which are used for generating the open api aka swagger file that comes together with the rest api.

A

So if we continue down the file here, we've got a normal service definition as anyone who's familiar with protobuff and jfc will know. This is what maps to a grpc service, and then it gets a little bit interesting here because under the add user, we can see that we've got some extra annotations here and, as you can see here, we can declare that we want to map a certain url path to the add user grpc service method.

A

So we say that a post request to the api, v1 users url path- should map to the add user request on the grpc service. This is how we say how we do the mapping between gfc http paths and gpc backend, and we can also declare that we want the entire json body to map to the add user request.

A

So this simply says that the add user request, json representation- is what we expect to be provided on the http url and then we've got some more open api annotations here just to make the swagger file look a little bit nicer and then we've got another user here. Another method here called list users which, in the same fashion, contains a url mapping in this case to a get verb on api v1 users, and this is of course, the standard path for something that will list users, so that makes sense to map to the list.

A

Users method and again, we've got some open api mappings down here, annotations down here to add some extra tags and stuff, and then we've got the message: definitions as you can see. There's nothing particularly interesting about these. In fact, there's it's a very minimal interface and then, if we dive quickly into the main go file, if you're not familiar with go, this is going to be a little bit unfamiliar, but just giving you an overview of what's happening here. We start a http, oh a tcp listener on port 1000 on the local that network.

A

We then start serving a code jbc server with uh our own um certificates. Here you would obviously replace these with your own certificates when you're working on your own server and then we register the generated server to the grpc server, and then we start that in the gu routine and then here, if we jump into the gateway package, this is where it gets a little bit interesting, because this is the grc gateway setup. So this is where we perform a grpc client connection, dial to the grpc server that we just started.

A

As you can see, we've got the dial adder on on the um function as a function, parameter setting up the gmc logger and uh we're using the same transport credentials that we were using the way we created the server so we're using tls between the gfc gateway, grc client and the grc server.

A

And then we use this method that was generated by our product, gen, grpc gateway generator to register the server handler to this gpc client connection, which means that now the gmc server, uh the gpc gateway server can map all of the http methods properly down to the grc client that we declared up here. So, if you're, using a java server or a c plus plus server again, this part, you can do exactly the same because you're just doing a gfc client connection dialing here.

A

So you just need to use a different dial address and then we're serving the http, the the jeffsy gateway mux, but we're also adding a little bit extra flair in this example, which is that we want to serve the generated open api ui together with it. So in port 11000 we serve both the grpc gateway and the open api handler and enough theory, let's, let's just take a quick look at what that looks like.

A

So if I do that, I'm gonna open my browser.

A

Okay, so here you go I've loaded, the uh open api server. On my in my browser, the first thing we notice is that we get a security warning, of course, because we're using a self's sign certificate in this case, because I'm serving this on localhost I'm going to go ahead and accept the risk and continue because I am hopefully not being intercepted on the way from my computer to my computer and as you can see here, we have the open api. Ui that's been generated from I'm going to enlarge this a little bit.

A

It's been generated together with the definitions that we had in the profile. So, as you can see, this completely maps to the url paths that we had listed in the profile and this this totally works as well. You can list users obviously now this actually gave a content length of zero response, because we have no users, but if we go ahead and add a user now, this doesn't take your parameters, so I'm just going to send it an empty json document that responds with okay. We've got an id of a user here.

A

I think we added the user, and if we execute this, then you can see now we get back um a user. So this is uh interactive. You can use this for testing. You can even use it for uh as a product in front of your own api or something like that.

A

But let's uh take another step back and see what happens if we want to make some changes to the code and just how quickly we can iterate on the code and regenerate everything and everything just works. You know that the kind of powerful.

A

Development workflow that we're used to with protobuf. So I'm going to switch back to my boilerplate.

A

A

I'm gonna turn off the server now. Let's say we want to add a parameter to the user. Let's call say we want the user to have a name see. This is what we do here. We'll then need to add a user, um a name to the user and user request.

A

Name here we go, then this is all we need now we can make generate, which is um we created, makefile command that will run privacy with all the generators that we have here and just recreate everything for us now, if we run go, run main go again and jump back to the browser.

A

Window, let's just make sure that we're disabling the cache memory of the window, because we're downloading a new swagger file.

A

Now, if we want to add a user all of a sudden, we have a name parameter here. So let's do that.

A

There you can see the card request that was made here.

A

We forgot to update the uh the back end, let's jump back quickly to the application.

A

At the backend server, okay, so here we have the go back in server which is implementing all this we'll take the request, and now that we've regenerated this, we have a name here. So let's do rename when we're adding the user and as you can see here, this is a just a mutex protected array, that's being stored in memory and list users. Just reads back from that array. So now we've updated the server as well run that and let's jump back to the browser window.

A

We don't even have to reload this pagerank if I try and execute it now. Yes, okay, we got the name back and if we try to do list users here, yes, we got that user back and the name has been stored.

A

So, as you can see this, the powerful protobuf workflow that we're used to where we just change the prototype files and regenerate and everything just works is completely unlocked by the jrc gateway as well. You just have to use the product file as usual. Regenerate it and your rest. Api is updated automatically, including the documentation, as you can see.

A

So, let's jump back into the.

A

A

A

So, let's talk a little bit more about specific product features that are supported by the grc gateway.

A

We start by the rich type support for the the problem of well known types. These types are part of what you might call a protobuf standard library and they're, always included with a proto-c compiler, meaning that you don't have to manually manage their downloading and generation. They use a special namespace google.protobuff, which makes them easy to recognize.

A

These types are predefined messages and include messages for handling timestamps, durations, wrappers of primitive types and others. All of these types have special cases built into them for the gateway. So whenever, for example, you need a timestamp make use of the well-known type, as you can see, I've added some examples here, the timestamp time marshalls to and from an rfc 3339 timestamp string, the uin32 value can be used to have nullable uin32s and the struct type can be used to store arbitrary json structures.

A

Please use the last one carefully as the protobuf representation is a mess to work with and should only be a last resort.

A

There's another well-known type that has good support in the geopsy gateway.

A

Most protobuf primitive fields such as strings and integers are non-nullable. So in order to do partial updates, the best practice is the use of a special message. Type called a field mask exposing this implementation. Detail to your users, however, is pretty nasty, so the grc gateway supports, translating json fields to a field mask and resource type fields that are found in the input json are used to populate the resource and field mask automatically.

A

This code shows an example structure with the server submitted. The output only comment indicates that the field is not mutable via partial updates, which is in line with the google api design, docs recommendations.

A

This support was entirely the result of an open source contribution from roman azami and daniel mcdonald.

A

When working with grpc, we use this status type for errors, which includes a message and a code. The geopsy gateway automatically translates the codes into appropriate http status codes. According to the google.rpc.code definitions.

A

Here we can see a sample of the error codes and their respective mappings. If you have more specific needs for your error handling such as a custom error, struct format, you can create your own error, handling function and configure the runtime mux with it on startup.

A

Here we have an example of an error handler that sets the response code to one that is mapped from the grpc status and the response body. To simply be the error message itself note that using custom errors like this will break the default open api generator definitions.

A

And wrapping it all up, what have we done today? We've created a http json service, but used grpc and protobuf under the hood. This allows us to get all the benefits of the protobuf idl, while still exposing a json interface externally.

A

We've also managed to sneak a gpc service into our stack and now it's much easier to argue that upc might be something worth trying. New clients can use. Grbc and old clients can keep using the json interface.

A

Most importantly, we found an easy, robust way to write restful services and we've only explored a snapshot of all that the geopsy gateway has to offer other features include the ability to set cookies perform header-based authentication in interceptors and much more. I hope you will, as I do, use the geopsy gateway for your next http json service.

A