gRPC & ASP.NET Core 3.1: What’s gRPC-web & how to create a gRPC-web service ?

What’s gRPC-web ?

In the summer of 2016, both a team at Google and  Improbable independently started working on implementing something that could be called “gRPC for the browser”. They soon discovered each other’s existence and got together to define a spec for the new protocol.

It is currently impossible to implement the HTTP/2 gRPC spec in the browser, as there is simply no browser API with enough fine-grained control over the requests. For example: there is no way to force the use of HTTP/2, and even if there was, raw HTTP/2 frames are inaccessible in browsers. The gRPC-web spec starts from the point of view of the HTTP/2 spec, and then defines the differences. These notably include:

• Supporting both HTTP/1.1 and HTTP/2.
• Sending of gRPC trailers at the very end of request/response bodies as indicated by a new bit in the gRPC message header.
• A mandatory proxy for translating between gRPC-web requests and gRPC HTTP/2 responses.

Note that gRPC-web is not compatible with client-side and bi-directional streaming but only with unary and server-side streaming.

Source: https://grpc.io/blog/state-of-grpc-web/

Envoy can be used as the mandatory proxy:

Because Improbable implementation supports TypeScript, I chose this library to make the demo in the next article, here is the link of Improbable gRPC-web repository: https://github.com/improbable-eng/grpc-web

gRPC-web & ASP.NET Core 3.1

In january 2020, Microsoft has announced an experimental support for gRPC-web with ASP.NET Core. Compatible with browsers (like Angular, React apps and more SPAs), Blazor WebAssembly and even Xamarin, that implementation brings an important feature: the uselessness of using a proxy such as Envoy.

To learn more about Microsoft announcement you can read this article: https://devblogs.microsoft.com/aspnet/grpc-web-experiment/

Implementation of gRPC-web & ASP.NET Core 3.1

We’ll need to download that preview package in your ASP.NET Core 3 project:

 Install-Package Grpc.AspNetCore.Web -Version 2.28.0-pre2

In our Startup. cs we will add the required config:

Configure CORS policies in ASP.NET Core 3

gRPC-web requires CORS.

• Origins must be set with our known domains (such as localhost and our official domain name on internet)
• Methods allowed must be POST and depending the browser OPTIONS too
• All Request headers must be allowed
• Response headers (exposed headers) must allow Grpc-Status and Grpc-Message

Activate gRPC-web middleware

The middleware app.UseGrpcWeb() must be activated. Its role is to catch requests that ask a gRPC endpoint to answer a non binary answer then text instead in order to be compatible with the browser, there are 2 types of Content-Type:

• application/grpc-web which is compatible with unary services
• application/grpc-web-text which is compatible with unary and server-side streaming services

Apply Cors and enable gRPC-web on services

This is the last step, we need to apply Cors and gRPC-web on services: .MapGrpcService<CountryGrpcService().RequireCors(“MyPolicy”).EnableGrpcWeb();

gRPC-web can be enabled for all services by adding this line in ConfigureServices: services.AddGrpcWeb(o => o.GrpcWebEnabled = true); so you don’t need to add on each service .EnableGrpcWeb();

The Startup.cs file should look like this:

For more information you can go to the Microsoft documentation: https://docs.microsoft.com/en-us/aspnet/core/grpc/browser?view=aspnetcore-3.1

Azure App Service support

Good news! Unlike gRPC, gRPC-web in ASP.NET Core 3 is supported by Azure App Services.

The thing you need to know is that Azure App Services doesn’t support HTTP/2 then you have to deploy your app with HTTP/1 as Kestrel default end points protocol settings in the appsettings.json file.

If you keep HTTP/2 in your settings, it will only work on Windows App Services because this one runs with module named ASPNetCoreModuleV2 that makes sure the app works fine on Windows (turns HTTP/2 to HTTP/1). On Linux App Services the docker behind the scene will fail on start:

Conclusion

We saw how to make gRPC compatible with browsers with a new spec: gRPC-web. The ASP.NET Core implementation of gRPC-web is still in preview, there is no commitment from Microsoft from now on this.

In the next article we will how to consume an gRPC-web service with an Angular 8 app and also with console app using HttpClient.