gRPC Web Tester

01 Canonical Status Codes (0-16)

02 Unary RPC Execution Pipeline

03 gRPC-Web vs gRPC-Native

Native gRPC rides on HTTP/2 and exploits low-level features like trailing headers, binary framing, and flow control that the browser fetch API simply does not expose. gRPC-Web is the bridge: a wire-compatible variant that re-encodes those primitives so a JavaScript client can speak to a gRPC backend through an Envoy or grpcwebproxy hop. Functionally the two share a .proto contract and a generated client surface, but the transport guarantees diverge in ways that matter when you choose a stack.

If you control both ends and neither is a browser, native gRPC is almost always the right answer, fewer hops, full streaming, smaller payloads. The moment a browser enters the picture you need the gRPC-Web shape. This tester targets the gRPC-Web path because that is what front-end engineers and full-stack developers actually need to debug from a webpage; the binary frames it sends are exactly what your production browser client will send.

04 Common Use Cases

05 A Worked Example: From .proto to Response

The fastest way to understand the tester is to follow one call end to end. Suppose your backend exposes a simple user-lookup service. You paste this .proto into the schema panel:

syntax = "proto3";
package users.v1;
service UserService {
  rpc GetUser (GetUserRequest) returns (GetUserResponse);
}
message GetUserRequest { string user_id = 1; }
message GetUserResponse {
  string user_id = 1;
  string display_name = 2;
  bool   is_active = 3;
}

The tester reads the descriptor, lists GetUser as the only callable method, and infers that the request needs a single user_id string. You supply the request as JSON, far easier to author than a hand-packed binary buffer:

{ "user_id": "u_8a31f0" }

On send, that JSON is serialized to a Protobuf message (field user_id → tag 1, wire type 2), prefixed with the gRPC-Web frame header, a one-byte flag plus a four-byte big-endian length, and POSTed to your endpoint with Content-Type: application/grpc-web+proto. A healthy response comes back as another length-prefixed frame followed by a trailer frame, which the tester decodes and renders as:

{ "user_id": "u_8a31f0", "display_name": "Ada Lovelace", "is_active": true }
grpc-status: 0
grpc-message: ""

Because the field numbers in the .proto drive serialization, renaming a field is harmless but renumbering one is a breaking change, the server would read user_id off the wrong tag and likely answer with INVALID_ARGUMENT (3). Seeing the request and response side by side in JSON makes that class of contract drift obvious before it reaches production.

06 How Status Travels in the gRPC-Web Frame

A detail that trips up nearly everyone new to gRPC-Web: the call status does not live in the HTTP status code. A request can return HTTP 200 and still represent a failed RPC. The real outcome is carried in the grpc-status trailer, and in gRPC-Web that trailer is not a true HTTP trailer at all, because browsers cannot read those. Instead the proxy encodes it as a final frame inside the response body, flagged in the frame header so the client knows it is metadata rather than a message.

This has two practical consequences. First, any intermediary that buffers or rewrites the response body, an aggressive CDN, a compression layer, a misconfigured load balancer, can corrupt or drop that trailer frame, leaving the client to report an opaque error even though the service answered correctly. Second, you must check grpc-status, not the HTTP code, to know whether a call truly succeeded. A 200 with grpc-status: 5 is a NOT_FOUND, not a success.

The tester surfaces both layers so you are never guessing: it shows the HTTP status of the transport hop and, separately, the decoded grpc-status and grpc-message extracted from the trailer frame. When the two disagree, that gap is usually your proxy configuration talking, and seeing it explicitly is half the battle when debugging an Envoy or gateway setup.

07 Troubleshooting Tips

Most gRPC-Web failures look identical at first glance, an opaque UNAVAILABLE in the console, but they cluster into a handful of root causes. When a request fails, work down this list in order before assuming the backend is broken.

• CORS preflight rejected. Open the browser network tab and look for an OPTIONS request returning anything other than 200/204. Your proxy needs Access-Control-Allow-Headers to include x-grpc-web, x-user-agent, and grpc-timeout.
• Wrong Content-Type. The server expects application/grpc-web+proto or application/grpc-web-text. A 415 means the proxy was not configured to accept that framing.
• Trailers stripped. If you get a 200 response but no grpc-status, an upstream proxy (often a CDN or load balancer) is dropping trailers. Move the gRPC-Web filter closer to the service.
• Token in the wrong header. Some gateways read Authorization; others expect a custom header forwarded as metadata. Try both and watch for code 16 vs 7.
• .proto drift. Adding a non-optional field on the server without redeploying the client schema yields INVALID_ARGUMENT (3). Re-paste the latest .proto into the tester.