gRPC and gRPC-Web

A gRPC service behind Flexway reads three ways: native gRPC, gRPC-Web from a browser, and REST/JSON at its annotations' routes. It is one operation per method.

Product side: gRPC; operations side: A gRPC upstream.

gRPC

The gateway's traffic port serves gRPC (HTTP/2, in clear inside a mesh or over TLS). Metadata carries the identity:

grpcurl -protoset orders.binpb -H "authorization: Bearer $TOKEN" \
  -d '{"id":"42"}' api.example.com:443 shop.v1.Orders/GetOrder

conn, _ := grpc.NewClient("api.example.com:443", grpc.WithTransportCredentials(credentials.NewTLS(nil)))
ctx := metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer "+token)
order, err := shopv1.NewOrdersClient(conn).GetOrder(ctx, &shopv1.GetOrderRequest{Id: "42"})

REST on the same method

curl -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/shop/orders/42

A server stream arrives as text/event-stream. Client and bidirectional streams are served in gRPC only.

gRPC-Web from a browser

Use a standard gRPC-Web client (grpc-web, Connect in gRPC-Web mode). The operator must allow your origin and expose grpc-status, grpc-message and grpc-status-details-bin: without them, the browser cannot read a refusal.

Errors

You call over	You get
gRPC, gRPC-Web	google.rpc.Status; the problem code in ErrorInfo.reason
REST	RFC 9457; an error of the gRPC upstream becomes upstream_status, its gRPC status in the grpc extension

Gateway code	gRPC status
unauthenticated	UNAUTHENTICATED
forbidden	PERMISSION_DENIED
invalid_request, malformed_request	INVALID_ARGUMENT
rate_limited, quota_exceeded	RESOURCE_EXHAUSTED
upstream_unavailable, overloaded	UNAVAILABLE
upstream_timeout	DEADLINE_EXCEEDED