How do gRPC server streaming and WebSockets work on the wire?
A gRPC server-streaming call is a single RPC. The client sends one request message, and the server replies with a sequence of protobuf messages on one HTTP/2 stream. Each message carries a length prefix. The call ends with trailers containing grpc-status and an optional grpc-message, so every stream terminates with a machine-readable outcome.
A WebSocket starts as an HTTP/1.1 request with an Upgrade: websocket header, answered by 101 Switching Protocols. Where both ends support it, the handshake can instead be an extended CONNECT over HTTP/2. After the handshake the connection is a full-duplex channel of text or binary messages. The protocol defines control frames (ping, pong, close) but nothing about what messages mean. There is no schema, no request/response pairing and no per-message status. Everything above framing is yours to design.
The rest of this article argues that the choice depends mostly on who the client is and what sits between it and the server: browsers, proxies, load balancers and CDNs each constrain what works.
| Aspect | gRPC server streaming | WebSocket |
|---|---|---|
| Framing | Length-prefixed protobuf messages on an HTTP/2 stream | Text or binary frames, plus ping/pong/close |
| Direction | Server to client after one request | Full-duplex |
| Schema | Enforced by .proto contract |
None; application-defined |
| Status and errors | grpc-status code and message in trailers |
Close code and reason; nothing per message |
| Transport | HTTP/2 | HTTP/1.1 Upgrade, or HTTP/2 extended CONNECT |
| Browser support | Not directly; needs grpc-web and a proxy | Native API in all major browsers |
Server-Sent Events (SSE) is a simpler option for one-way push. It streams text/event-stream over an ordinary HTTP response. It comes up again later.
Why does the browser change the answer, and what does grpc-web actually give you?
Native gRPC depends on HTTP/2 features that browser JavaScript cannot reach. A gRPC call ends with HTTP trailers carrying grpc-status and grpc-message, and clients expect fine control over streams and framing. fetch and XMLHttpRequest expose neither: the browser owns the connection, picks the protocol version, and does not reliably surface trailers to page code. A browser cannot speak gRPC directly, even over an HTTP/2 connection.
grpc-web works around this. It keeps the length-prefixed message framing but moves the status trailers into the response body as a final, specially flagged frame. A browser can then read the whole call through an ordinary HTTP response. You need something on the server side that understands this encoding. That can be a proxy that translates grpc-web to native gRPC for your backends, or a server framework that implements grpc-web itself.
The limit is the call types. grpc-web supports unary and server streaming only. Client streaming and bidirectional streaming are not available, because browsers cannot stream a request body and read the response at the same time in a portable way.
Server streaming through grpc-web is also not guaranteed to arrive incrementally. Some client transport modes, proxies, CDNs and compression layers buffer the response until it completes or a buffer fills. Before you rely on it for live push, test the full production path and confirm that each message reaches the browser when it is sent.
grpc-web has two costs:
- Another component to operate. The translating proxy or grpc-web layer needs its own deployment, timeouts and monitoring.
- No upstream path from the browser. Interactive features such as typing indicators, cursors or client acknowledgements need a channel in that direction. These features often push teams back to WebSockets for that part of the product.
How do you implement a typed contract with gRPC versus a hand-built WebSocket protocol?
With gRPC, the contract is the starting point. A minimal subscription is one RPC, Subscribe(SubscribeRequest) returns (stream Update). The request carries a topic and an opaque resume_cursor, and each Update carries a monotonically increasing sequence plus a payload. Running protoc on that file produces typed client and server stubs for every supported language. Adding a field with a new tag number does not break older clients, because they skip fields they don't recognize.
You also get several things without designing them:
- Deadlines propagate from caller to server.
- Status codes such as
UNAVAILABLE,UNAUTHENTICATEDandRESOURCE_EXHAUSTEDgive clients a shared retry vocabulary. - Metadata, sent as headers and trailers, carries auth tokens and trace context outside the payload.
A WebSocket gives you framed bytes and nothing more. To get rough parity, you define an envelope: a type discriminator, an id for correlating requests with responses, a payload, an error object, and a seq or version field. Then you design what gRPC already specifies:
- Correlation: how replies match requests that are multiplexed on one socket.
- Versioning: how a server tells an old client that a message shape changed.
- Error model: which errors are retryable and which are fatal.
- Auth refresh: how to rotate a token on a connection that outlives it, since the handshake headers are sent only once.
This is the main difference in engineering cost. A JSON Schema or TypeScript types shared across repos can narrow the gap, but nothing enforces them on the wire. When a producer renames a field, the compiler doesn't catch it. You find out at runtime, often as a silently undefined value in a client you don't control.
// feed.proto: the contract is the source of truth; protoc generates typed stubs
syntax = "proto3";
package feed.v1;
service FeedService {
// One request in, an unbounded stream of updates out
rpc Subscribe(SubscribeRequest) returns (stream Update);
}
message SubscribeRequest {
string topic = 1; // e.g. "orders.eu-west"
bytes resume_cursor = 2; // opaque; empty means start from now
}
message Update {
uint64 sequence = 1; // monotonically increasing per topic
bytes resume_cursor = 2; // client stores this to resume after reconnect
bytes payload = 3; // new fields get new tags; old clients skip them
}
// ws-envelope.ts: hand-built WebSocket equivalent. Nothing enforces it on the wire.
type Envelope<T = unknown> = {
type: "subscribe" | "update" | "error" | "auth.refresh"; // discriminator
id: string; // correlates a reply to its request on a shared socket
v: number; // schema version, so the server can signal shape changes
seq?: number; // ordering and gap detection for updates
payload?: T;
error?: {
code: string; // you define the vocabulary, e.g. "UNAUTHORIZED"
retryable: boolean; // you define the retry semantics
message: string;
};
};
A minimal server-streaming .proto with a resume cursor and sequence numbers, followed by the WebSocket envelope a team has to define and keep in sync by hand to approximate the same contract.
How do you keep long-lived streams alive, resumable and authenticated?
Liveness
HTTP/2 has PING frames, and gRPC exposes them through keepalive settings: a ping interval, a timeout for the ack, and whether to ping with no active calls. Servers enforce a minimum ping interval and close clients that ping too often with a GOAWAY. Both ends must agree on these values. WebSockets use ping/pong control frames, but browser JavaScript cannot send pings. Only the server can send them.
Load balancers, NAT tables and proxies drop connections they consider idle, often without sending a FIN or RST. The client keeps a dead socket and waits for messages that never arrive. Some intermediaries terminate HTTP/2 or WebSocket connections themselves and answer protocol pings locally, so a successful ping does not prove the backend is reachable. An application-level heartbeat message, sent end to end, does prove it.
Resumption
Both transports deliver each message at most once per connection. Neither replays anything after a reconnect. Build resumption yourself:
- Tag every event with a monotonic sequence number or cursor.
- Have the client send its last-seen cursor, either in the gRPC request message or in the WebSocket subscribe message.
- On resume, the server replays from a bounded buffer or a durable log. If the cursor is older than what the buffer still holds, return an explicit "resync required" so the client does a full snapshot fetch.
- Have clients drop events with a cursor at or below the one they have already applied, so replays are idempotent.
Authentication
The browser WebSocket API cannot set an Authorization header. The common workarounds each carry a risk:
- Cookies expose you to cross-site WebSocket hijacking unless the server validates the
Originheader. - Query-string tokens end up in access logs.
- First-message auth lets unauthenticated sockets hold server resources. Enforce a short deadline for that first message.
Streams that last hours will outlive their tokens. Either accept a refresh message on the open stream, or have the server close the stream when the token expires and let the client reconnect with a new token and its cursor.
type StreamEvent = { seq: number; payload: unknown };
type ResumeResult =
| { kind: "replay"; events: StreamEvent[] }
| { kind: "resync_required"; latestSeq: number }; // client must fetch a full snapshot
// Bounded in-memory replay buffer. A durable log is the source of truth in production;
// this only covers short disconnects.
class ReplayBuffer {
private events: StreamEvent[] = [];
private nextSeq = 1; // monotonic cursor, never reused while this buffer exists
constructor(private readonly capacity: number) {}
append(payload: unknown): StreamEvent {
const ev = { seq: this.nextSeq++, payload };
this.events.push(ev);
if (this.events.length > this.capacity) this.events.shift(); // evict oldest
return ev;
}
// lastSeenSeq arrives in the gRPC request message or the WebSocket subscribe message.
resumeFrom(lastSeenSeq: number): ResumeResult {
const latestSeq = this.nextSeq - 1;
const oldestSeq = this.events.length > 0 ? this.events[0].seq : this.nextSeq;
// Cursor from the future: the server restarted and lost in-memory state.
if (lastSeenSeq > latestSeq) return { kind: "resync_required", latestSeq };
// Gap: events the client never saw have already been evicted.
if (lastSeenSeq + 1 < oldestSeq) return { kind: "resync_required", latestSeq };
return { kind: "replay", events: this.events.filter((e) => e.seq > lastSeenSeq) };
}
}
// Call resumeFrom() and register the live listener in the same synchronous step,
// so no event can be appended between the replay and the start of live delivery.
// Clients still drop any event with seq <= their last applied seq, so a duplicate
// at the replay/live boundary is harmless.
A transport-agnostic sketch of server-side resume logic that replays events after the client's last-seen cursor from a bounded buffer and returns an explicit resync signal when the cursor is too old or comes from before a server restart.
How should you handle backpressure and slow consumers?
gRPC gives you backpressure for free because it sits on HTTP/2 flow control. Each stream and each connection has a receive window. When a client stops reading, the window fills, the server's transport stops sending, and your send call eventually blocks or returns an error. The slow consumer becomes visible in your server code without you building anything.
WebSockets have no equivalent. Most libraries, including the browser API with bufferedAmount, only expose how many bytes are queued locally. If you keep calling send, the buffer grows until memory runs out. You have to check the queue depth before each write and enforce a cap yourself.
Once you know a consumer is behind, apply a policy based on what each message means:
- Drop messages that are independent and safe to lose, such as telemetry samples or typing indicators.
- Coalesce messages that represent state. Keep only the latest value per key, so a reader that falls behind skips intermediate prices or positions and still ends up current. The code example below shows this per-key conflation.
- Disconnect when the queue stays over its limit for longer than a set grace period, or when the stream carries ordered events that cannot be skipped. The client then resumes from its last acknowledged offset.
HTTP/2 multiplexing creates shared-fate risk. One lost TCP packet stalls every stream on the connection (head-of-line blocking). A single stalled stream can also consume the connection-level window and starve its neighbours.
Track these metrics per stream: duration, messages sent, send-queue depth, drops, and reconnect rate.
// Minimal shape shared by the browser WebSocket and the Node "ws" package.
interface Sendable { readonly bufferedAmount: number; send(data: string): void; }
const HIGH_WATER_BYTES = 256 * 1024; // pause writes above this (placeholder value)
const FLUSH_INTERVAL_MS = 50; // retry draining while the consumer is slow
class ConflatingSender {
// One slot per key: a newer value overwrites an unsent older one.
private pending = new Map<string, unknown>();
private timer: ReturnType<typeof setInterval>;
conflated = 0; // metric: updates replaced before they were sent
constructor(private socket: Sendable) {
this.timer = setInterval(() => this.flush(), FLUSH_INTERVAL_MS);
}
get queueDepth(): number { return this.pending.size; } // metric: send-queue depth
publish(key: string, state: unknown): void {
if (this.pending.has(key)) this.conflated++;
this.pending.set(key, state); // keep only the latest state per key
this.flush();
}
private flush(): void {
for (const [key, state] of this.pending) {
// Slow consumer: stop writing; remaining keys stay queued and keep coalescing.
if (this.socket.bufferedAmount > HIGH_WATER_BYTES) return;
this.socket.send(JSON.stringify({ key, state }));
this.pending.delete(key);
}
}
close(): void { clearInterval(this.timer); this.pending.clear(); }
}
A WebSocket sender that checks bufferedAmount before each write and, while the client is behind, keeps only the latest unsent state per key so memory stays bounded by the number of keys, not the number of updates.
How do load balancing, deploys and fan-out architecture work for real-time backends?
Because gRPC multiplexes many streams over one long-lived HTTP/2 connection, an L4 load balancer sees only that TCP connection. It picks a backend once, and every stream the client opens afterward lands on the same server. A fleet that scales out under load can end up with new pods idle while a few old ones carry most of the streams. To fix this, balance per stream: use an L7 proxy that understands HTTP/2, or client-side balancing that resolves all backend addresses and spreads streams across them. WebSockets are sticky by nature. One connection is one session, so balancing happens only at connect time.
Deploys need a graceful drain. An HTTP/2 server sends GOAWAY, which lets in-flight streams finish while the client opens new ones elsewhere. A WebSocket server sends a close frame with code 1001 ("going away"). A cap on connection age forces periodic rebalancing, at the cost of reconnect churn. Clients must reconnect with jittered exponential backoff, or a drained node's clients all return at the same instant and overwhelm the remaining nodes.
producers ──► pub/sub or log ──► gateway nodes (stateless) ──► gRPC clients
│ │
│ └──────────► grpc-web clients
└──────────────────► WebSocket clients
The transport is only the last hop. Gateways hold no state that cannot be rebuilt from the log, so any node can serve a reconnecting client from its resume offset. Some corporate proxies break WebSocket upgrades or end-to-end HTTP/2, so keep an SSE or long-polling fallback on the same gateways for those clients.
┌─────────────┐ ┌─────────────┐
│ producer │ │ producer │
└──────┬──────┘ └──────┬──────┘
▼ ▼
┌─────────────────────────────────────────────┐
│ pub/sub or log (durable, offset-addressed) │
└──────┬───────────────┬───────────────┬──────┘
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ gateway A │ │ gateway B │ │ gateway C │
│ (stateless) │ │ (stateless) │ │ draining: │
│ │ │ │ │ GOAWAY/1001 │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
└───────────────┼───────────────┘
│
┌───────────────┴───────────────┐
│ L7 HTTP/2-aware proxy or │
│ client-side balancing: │
│ per stream (gRPC), at connect │
│ time only (WebSocket, sticky) │
└───────────────┬───────────────┘
- - - - - - - - - - - - │ - - - last hop: transport - - -
┌────────────┬─────┴────────┬───────────────┐
▼ ▼ ▼ ▼
┌────────┐ ┌──────────┐ ┌───────────┐ ┌──────────────┐
│ gRPC │ │ grpc-web │ │ WebSocket │ │ SSE / long- │
│ client │ │ client │ │ client │ │ poll fallback│
└────────┘ └──────────┘ └───────────┘ └──────────────┘
Producers publish to a durable pub/sub or log that feeds stateless gateway nodes behind L7 or client-side balancing. The gateways can be drained with GOAWAY or a 1001 close frame, and gRPC, grpc-web, WebSocket and SSE/long-poll fallback clients differ only in the final transport hop.
When should you use gRPC streaming, WebSockets or an alternative?
The choice depends mostly on who the client is and which direction traffic flows. Payload format matters much less.
| Client type | Traffic pattern | Recommendation | Avoid when |
|---|---|---|---|
| Internal services | Server push, or bidi | gRPC server streaming | Intermediaries between services strip or downgrade HTTP/2 |
| Native mobile or desktop app you ship | Server push | gRPC server streaming | You can't update clients to match schema changes |
| Browser, push only | Notifications, feeds, dashboards | grpc-web streaming if you already run gRPC; otherwise WebSockets or SSE | You'd add a grpc-web proxy only for this one feature |
| Browser, interactive | Chat, collaborative editing, games | WebSockets | You need a typed contract and won't maintain one yourself |
| Mixed estate | Browsers plus internal services | gRPC internally, WebSocket edge gateway | The gateway would just pass through untyped messages |
Don't use gRPC for bidirectional browser traffic. grpc-web supports only unary and server-streaming calls, so client-to-server messages need separate requests and you lose a single ordered channel. Also avoid gRPC where load balancers or proxies terminate HTTP/2 badly, because streams fail in ways that are hard to diagnose.
Don't use WebSockets when many teams or clients consume the same events. Each consumer has to reimplement framing, message types, versioning and reconnect handling, and that work is repeated for every client.
In engineering-time terms:
- gRPC costs you upfront in schema design, code generation in your build, and proxy setup for browsers. In return, every new consumer gets the protocol already defined.
- WebSockets are quick to start. The cost grows over time as each change to the hand-built protocol needs coordinated edits on server and client.
- SSE is the cheapest to build and run, but only covers server-to-client push.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to grpc streaming vs websockets, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a route's URL or method automatically notifies the services that consume it — no hunting through repos for callers.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Consumers learn about a breaking change at review time rather than from production errors.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.