Protocols

CDN gRPC-Web Proxy: Binary Protocol Translation at Edge

Q: Why can't browsers call gRPC directly without a proxy?

Browsers lack support for gRPC's required HTTP/2 trailers, binary framing control, and direct access to HTTP/2 streams via fetch/XHR. gRPC-Web and an edge proxy translate browser-friendly HTTP/1.1 or HTTP/2 requests into compliant gRPC frames with trailers.

Q: Does gRPC-Web proxying add significant latency?

A well-tuned edge proxy adds 1-5ms for framing translation. This is offset by avoiding extra origin round-trips, persistent h2 connections to origin, and edge termination that reduces TLS handshake overhead. Keep proxy and origin in the same region or use Argo-style acceleration.

Q: Should I use Envoy, NGINX, or CDN-native gRPC-Web support?

Use CDN-native gRPC-Web if available (Cloudflare, Fastly, AWS CloudFront + ALB) for zero-ops translation. Choose Envoy at the edge for full control over retry, timeout, and streaming. NGINX is sufficient for unary RPCs but has limited streaming and trailer handling.

Q: Can gRPC-Web proxies cache responses?

Unary gRPC responses can be cached at the edge using a custom cache key derived from method + protobuf payload hash, but only for idempotent, safe methods. Streaming responses should not be cached. Set cache-control via grpc-encoding and configure explicit cache rules to avoid caching authenticated streams.

By James Thornton, CDN Solutions ArchitectSep 7, 20269 min read

gRPC is efficient inside your data center, but it breaks at the browser edge. Browsers cannot speak native gRPC. A CDN gRPC-Web proxy solves this by translating between the browser's limited HTTP stack and your origin's binary HTTP/2 gRPC service — without sacrificing streaming, flow control, or protobuf efficiency.

TL;DR: Deploy gRPC-Web translation at the CDN edge to terminate browser HTTP/1.1, re-frame to HTTP/2 gRPC with trailers, and multiplex to origin over persistent connections. This cuts connection overhead by 60-80% and enables streaming to the browser without a dedicated gateway fleet.

Why gRPC Needs Translation at the Edge

Native gRPC relies on HTTP/2 features that the Fetch API and XMLHttpRequest do not expose: trailing headers (trailers), full control over binary framing, and bidirectional streaming. The gRPC-Web protocol is a deliberate adaptation that encodes the same protobuf payloads over HTTP/1.1 or HTTP/2 in a way browsers can handle.

Without an edge proxy, you have two bad options: expose a REST gateway that re-serializes to JSON (losing 30-40% payload efficiency) or run a self-managed Envoy fleet just for translation. A CDN edge proxy eliminates both by handling translation within PoPs, close to users. For background on how PoPs handle protocol termination, see our CDN architecture overview and edge computing guide.

gRPC vs gRPC-Web vs REST at the Edge

Feature	Native gRPC	gRPC-Web (via CDN Proxy)	REST / JSON
Transport	HTTP/2 only, trailers required	HTTP/1.1 or HTTP/2, no trailers needed in browser	HTTP/1.1 or HTTP/2
Payload	Protobuf binary, 5-byte frame header	Same protobuf binary + gRPC-Web framing	JSON text, 2-4x larger
Streaming	Full bidi streaming	Server streaming + unary (bidi via websockets)	Server-sent events / polling
Browser Support	None	All modern browsers	All browsers
CDN Cacheable	No (trailers break cache)	Unary: Yes with custom key	Yes, natively
Edge Overhead	N/A	1-5ms translation	JSON serialization 5-15ms

How Edge Translation Works

The proxy performs three critical translations in the data path:

Performance Comparison: Edge vs Origin Processing
Metric	Edge Processing	Origin Processing	Improvement
Latency (p50)	8–15 ms	120–300 ms	15–20x faster
Cache Hit Ratio	85–95%	N/A	Reduces origin load
TLS Handshake	1–5 ms (nearby PoP)	50–150 ms	10–30x faster
Bandwidth Cost	$0.01–0.04/GB	$0.05–0.12/GB	3–5x cheaper
Availability	99.99% (multi-PoP)	99.9% (single DC)	10x fewer outages

Protocol downgrade/upgrade: Accepts content-type: application/grpc-web+proto over HTTP/1.1 from the browser, then re-emits application/grpc over HTTP/2 to origin.
Framing conversion: Strips the gRPC-Web 1-byte flag + 4-byte length prefix wrapper and re-adds standard gRPC length-prefixed messages, handling grpc-status and grpc-message trailers.
Connection coalescing: Multiplexes thousands of browser HTTP/1.1 connections onto a small pool of warm HTTP/2 connections to origin, reducing TLS and TCP handshake cost.

Figure 1: Edge proxy terminates gRPC-Web over HTTP/1.1 and proxies native gRPC over HTTP/2 with trailer translation and connection pooling.

Binary Framing: What the Proxy Actually Rewrites

Both protocols use the same 5-byte frame: 1 byte compressed flag + 4 bytes big-endian message length + protobuf bytes. The difference is trailer handling.

gRPC-Web text mode base64-encodes frames for proxies that buffer binary. gRPC-Web proto mode sends raw binary and is preferred at the edge for lower CPU. The edge proxy must:

Detect content-type: application/grpc-web-text vs grpc-web+proto and decode if needed.
Buffer until a full frame length is available before forwarding — never forward partial protobuf messages.
Convert the terminal data frame containing grpc-status:0 into a proper HTTP/2 trailer. Browsers read this as a header because trailers are not exposed.

# gRPC-Web frame (browser -> edge) POST /com.example.SearchService/Search HTTP/1.1 content-type: application/grpc-web+proto x-grpc-web: 1 accept: application/grpc-web+proto # 5-byte prefix + protobuf payload 00 00 00 00 0A 0A 07 68 65 6C 6C 6F 2D77 6F 72 6C 64 # Edge -> Origin (translated) POST /com.example.SearchService/Search HTTP/2 content-type: application/grpc te: trailers grpc-encoding: identity # Same frame, but response will use HTTP/2 trailers: grpc-status: 0 grpc-message: OK

Configuring the Edge Proxy

Most teams use Envoy's grpc_web filter at the edge, or a CDN-native toggle. Below are production-ready patterns.

Option 1: Envoy at CDN Edge (Recommended for control)

# envoy.yaml - edge listener with grpc_web filter static_resources: listeners: - name: edge_listener address: { socket_address: { address: 0.0.0.0, port_value: 443 } } filter_chains: - filters: - name: envoy.filters.network.http_connection_manager typed_config: "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager stat_prefix: ingress_http http_filters: - name: envoy.filters.http.grpc_web - name: envoy.filters.http.cors - name: envoy.filters.http.router route_config: virtual_hosts: - name: grpc_service domains: ["api.example.com"] routes: - match: { prefix: "/com.example." } route: cluster: grpc_origin timeout: 30s retry_policy: retry_on: unavailable, reset num_retries: 2 clusters: - name: grpc_origin connect_timeout: 0.25s type: STRICT_DNS typed_extension_protocol_options: envoy.extensions.upstreams.http.v3.HttpProtocolOptions: "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions explicit_http_config: { http2_protocol_options: {} } load_assignment: cluster_name: grpc_origin endpoints: [{lb_endpoints: [{endpoint: {address: {socket_address: {address: origin.internal, port_value: 50051}}}]}]

Option 2: CDN-Native (Cloudflare / Fastly / CloudFront)

Enable gRPC-Web in the dashboard and set origin protocol to h2c or h2. Ensure your origin speaks HTTP/2 without TLS termination mismatch. For CloudFront, put an ALB or NLB with HTTP/2 target group in front of your gRPC servers.

Client Example (grpc-web JS)

// npm install grpc-web google-protobuf import { SearchServiceClient } from './generated/SearchService_grpc_web_pb'; import { SearchRequest } from './generated/search_pb'; const client = new SearchServiceClient('https://api.example.com', null, null); const req = new SearchRequest(); req.setQuery('edge proxy'); req.setPageSize(20); // Unary call - automatically uses application/grpc-web+proto client.search(req, {'x-request-id': crypto.randomUUID()}, (err, res) => { if (err) console.error(err.code, err.message); else console.log(res.getResultsList()); }); // Server streaming - edge proxy translates to chunked HTTP/1.1 const stream = client.streamResults(req); stream.on('data', (chunk) => render(chunk)); stream.on('error', (e) => { if (e.code !== 0) retryWithBackoff(); }); stream.on('end', () => console.log('stream complete'));

Performance Tuning at the Edge

Translation is cheap, but misconfiguration is not. Apply these settings to keep p95 under 30ms:

Keepalive: Set origin HTTP/2 keepalive to 30s with 10s timeout. Edge should hold 10-20 persistent connections per PoP per origin, not per request.
Timeouts: Use per-method timeouts. Unary search: 2-5s. Streaming: 30-60s with idle timeout 15s. Never use Envoy's default 15s for streaming.
Buffer limits: Cap initial_stream_window_size at 1MB and connection_window_size at 4MB to prevent one large message from starving multiplexed streams.
Compression: Prefer grpc-encoding: gzip only for messages >1KB. Small protobufs compress poorly and waste CPU at edge. Disable compression for <512B.
CORS: Handle CORS at the edge, not origin. Add Access-Control-Allow-Headers: x-grpc-web, grpc-timeout, content-type and cache preflight for 86400s.

Measure with CDN performance metrics and correlate with Core Web Vitals — gRPC-Web streaming improves INP by avoiding polling waterfalls, but unoptimized framing can regress LCP if the proxy buffers too aggressively.

Pro tip: Enable access_log with %GRPC_STATUS% and %RESPONSE_CODE_DETAILS% at the edge. A 200 HTTP with grpc-status:14 (unavailable) is invisible to standard CDN dashboards that only track HTTP status.

Security and Reliability

Binary protocols obscure payloads from traditional WAFs. Configure edge security explicitly:

mTLS to origin: Terminate browser TLS at edge with modern ciphers, then use mTLS or private network + X-Origin-Verify to origin. Never forward browser certs as gRPC metadata.
Payload validation: Enforce max_request_bytes: 4MB at edge and validate protobuf field sizes via Envoy's max_request_headers_kb. See CDN security guide for header overflow protections.
DNS and failover: Use health checks that send a real gRPC health probe (grpc.health.v1.Health/Check), not just TCP. Combine with CDN DNS resolution to fail over PoP-to-origin quickly.
Retry safely: Only retry idempotent unary methods. Never auto-retry streaming or methods with side effects. Use x-retry-attempt header to make retries observable.

When Not to Use gRPC-Web at the Edge

Avoid gRPC-Web if you need true bidirectional streaming from the browser (use WebSockets or Connect protocol instead), or if your payloads are already JSON and <500B (REST overhead is negligible). For edge caching of large unary responses, consider Connect's application/proto with GET support, which maps better to CDN cache keys.

Edge Checklist

✓ Origin speaks HTTP/2 with trailers, health-checked via gRPC health protocol
✓ Edge filter order: grpc_web before cors before router
✓ Persistent h2 pool, per-method timeouts, no retry on streams
✓ CORS and compression handled at edge, not origin
✓ Logging includes grpc-status, not just HTTP 200

Frequently Asked Questions

Why can't browsers call gRPC directly without a proxy?

Browsers don't expose HTTP/2 trailers or raw binary frame control through fetch/XHR, both required for gRPC. gRPC-Web encodes the same protobuf payloads over HTTP/1.1 with length-prefixed frames and moves trailer data into headers the browser can read. The edge proxy restores proper HTTP/2 trailers toward origin.

Does gRPC-Web proxying add significant latency?

No — translation is typically 1–5ms per request at the PoP. You gain back more by multiplexing browser connections onto warm HTTP/2 origin connections and terminating TLS at the edge. Keep the proxy and origin peered in the same region and monitor p95 with edge timing headers.

Should I use Envoy, NGINX, or CDN-native gRPC-Web support?

If your CDN offers native gRPC-Web translation, use it to eliminate operational overhead. Choose Envoy when you need fine-grained retry, timeout, and observability per RPC. NGINX works for simple unary workloads but lacks robust streaming and trailer fidelity.

Can gRPC-Web proxies cache responses?

Unary responses can be cached if they are idempotent and safe — create a cache key from the method name plus a hash of the protobuf request body. Set explicit cache-control and vary on authorization headers. Never cache server-streaming responses; buffer them instead.

References & Standards: RFC 7234 · HTTP/2 specification