grpc-web

Lets gRPC-Web browser clients reach a gRPC upstream.

Category TransformationAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin grpc-webPriority 505

What it does

grpc-web lets a web page call a gRPC backend with gRPC-Web, the form of gRPC a browser can send. The route needs an upstream whose scheme is grpc. The plugin answers the browser's preflight itself, and a call is passed on to the backend as gRPC and answered in the form the page sent.

Every web origin may call the route. The answer carries Access-Control-Allow-Origin: * and no credentials flag, so a browser sends an authorization header only when the page sets it, and never a cookie.

When to use it

• The orders dashboard, a web app, reads orders from a gRPC service and has no REST layer in between.
• A web page sends its own bearer token to a gRPC service in the authorization header, added under CORS allowed headers.
• A team writes one gRPC service for its mobile apps and its web app, and the web app calls it through the gateway.

Not for clients that send plain JSON over HTTP — see grpc-transcode (Translates HTTP and JSON requests into gRPC calls and back) or the cross-origin rules of an ordinary HTTP API — see cors (Adds CORS headers so browsers can call the API from other origins).

Set it up

Let browsers call a gRPC service and send an authorization header

Every web origin may call the route. The answer carries `Access-Control-Allow-Origin: *` and no credentials flag, so a browser sends the authorization header only when the page itself sets it, never a cookie.

Set CORS allowed headers to content-type,x-grpc-web,x-user-agent,authorization.

grpc-web · as the console saves it

{
  "cors_allow_headers": "content-type,x-grpc-web,x-user-agent,authorization"
}

Things to know

• CORS allowed headers — The preflight is answered 204 and lists these headers under Access-Control-Allow-Headers. With authorization added, a page may send its own authorization header.
• CORS allowed headers — Sent only in the answer to the OPTIONS preflight. A route that never gets one never reads this.
• A call sent as application/grpc-web-text is answered 200, and the body comes back in the same text form.
• Request body limit — A body above this, and a POST carrying no body at all, are both answered 400 rather than 413.
• AdviceList under CORS allowed headers only the headers your web app sends.

Settings

The fields as the console shows them, section by section.

CORS allowed headerscors_allow_headersstringdefault content-type,x-grpc-web,x-user-agent

The headers a browser may send on a cross-origin call, comma separated, such as content-type,x-grpc-web,x-user-agent.

Request body limitmax_req_body_sizeintegerdefault 67108864

Bytes of the request body held in memory before it is unframed.

at least 1

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.