The Connect protocol
Why special-case unary RPCs?
The Connect protocol is effectively two protocols, one for unary RPC and one for streaming. This isn't intellectually satisfying — it would be purer to treat unary RPCs as a bidirectional stream with exactly one message sent in each direction. In practice, we've found the loss of purity well worth it. By using standard HTTP compression negotiation and eliminating binary framing from the body, the Connect protocol lets us make unary RPCs with web browsers, cURL, or any other HTTP client.
Why not use HTTP status codes?
Every taxonomy of errors is flawed, but at least HTTP status codes are time-tested and widely understood. In a perfect world, we'd have used HTTP status codes as-is for the Connect protocol. Unfortunately, we want Connect handlers and clients to support the gRPC wire protocols without code changes. Since the mapping between gRPC and HTTP status codes is lossy, we can't provide an acceptable gRPC experience without adopting the same set of codes. C'est la vie.
Why not use the Twirp protocol?
We really like Twirp's protocol! It's simple, doesn't rely on any HTTP/2-specific framing, and works nicely with general-purpose HTTP tools. Unfortunately, it didn't fit our needs:
- It doesn't support streaming RPCs. Even if most RPCs are unary, many organizations have a handful of APIs that do benefit from streaming.
- It's semantically incompatible with gRPC. Because Twirp doesn't specify how to encode timeouts and uses a very different error model, swapping protocols requires significant code changes.
In the end, we prioritized gRPC and gRPC-Web compatibility over Twirp support. We hope that Connect's unary protocol captures most of Twirp's magic while still allowing your code to interoperate with the larger gRPC ecosystem.
Serialization & compression
Why are numbers serialized as strings in JSON?
Number is an IEEE 754 double-precision float: even though it
occupies 64 bits of memory, some of the space is reserved for the fractional
portion of the number. There's just not enough space left to represent 64-bit
integers! To make absolutely sure that integers are handled correctly, the
Protobuf JSON mapping represents the
uint64 types as
This only affects calls made with cURL, the browser's
fetch API, or other
plain HTTP tools. Connect clients automatically convert numeric values to and
Why are unknown JSON fields ignored?
Following the proto3 language guide, a JSON parser should reject unknown fields by default. However, we found the behavior to be impractical for RPC because it means that the schema cannot evolve without breaking existing clients: simply adding a field to a response will break old clients. Therefore, Connect clients and servers will ignore unknown fields, provided that the underlying implementation allows us to do so.
Why use generics?
Generic code is inherently more complex than non-generic code. Still, introducing
connect-go eliminated two significant sources of complexity:
- Generics let us generate less code, especially for streaming RPCs — if
you're willing to write out some long URLs, it's now just as easy to use
protoc-gen-connect-go. The generic stream types, like
BidirectionalStream, are much clearer than the equivalent code generation templates.
- We don't need to attach any values to the context, because Connect's generic
Responsestructs can carry headers and trailers explicitly. This makes data flow obvious and avoids any confusion about inbound and outbound metadata.
On balance, we find
connect-go simpler with generics.
Why generate Connect-specific packages?
If you're familiar with Protobuf, you may have noticed that
protoc-gen-connect-go behaves a little differently from many other plugins:
rather than adding code alongside the basic message types, it creates a
separate, Connect-specific Go package and imports the base types.
This serves a few purposes:
- It keeps the base types lightweight, so every package that works with Protobuf messages doesn't drag along an RPC framework.
- It avoids name collisions. Many Protobuf plugins — including
protoc-gen-go-grpc— generate code alongside the base types, so the package namespace becomes very crowded.
- It keeps the contents of the base types package constant. This isn't critical when generating code locally, but it's critical to making remote packages and remote plugins work.
Why do I need a proxy to call gRPC backends?
The HTTP protocol specification has included trailers for decades. In practice, they were rarely used. Many HTTP implementations — including web browsers — still don't support trailers.
Unfortunately, gRPC makes extensive use of HTTP trailers. Because browsers don't support trailers, no code running in a browser can speak the gRPC protocol. To work around this, the gRPC team introduced the gRPC-Web protocol, which encodes trailers at the end of the response body.
Some gRPC servers (including those built with
connect-go) support the
gRPC-Web protocol natively, so browsers can communicate directly with your
backend. Most of Google's gRPC implementations don't support gRPC-Web, so you
must run a proxy like Envoy to translate to and from the standard gRPC
Is streaming supported?
While the Connect protocol supports all types of streaming RPCs, web browsers do not support streaming from the client-side across the board. The fetch API does specify streaming request bodies, but unfortunately, browser vendors have not come to an agreement to support streams from the client – see this WHATWG issue on GitHub. This means you can use streaming from the browser, but only server-streaming.
Does generated code affect bundle size?
Yes, generated code does affect bundle size, but the browser implementation is a slim library using standard Web APIs, and deliberately generates very little code. For an ELIZA client, the compressed bundle size is just around 13KiB.
How does Connect compare to gRPC-web?
With Connect, you don't need a proxy to provide your gRPC service as gRPC-web, and TypeScript is supported out of the box. Requests are easy to inspect in the browser, because the JSON format is used by default, where gRPC-web only supports the binary format.
That said, Connect ships with support for the gRPC-web protocol and is fully compatible with existing gRPC-web backends. See Choosing a protocol.
What Protobuf runtime does Connect use for TypeScript?
Connect uses the Protobuf runtime provided by Protobuf-ES. Additionally, the code generator plugin used by Connect-ES is based on the plugin framework also provided by Protobuf-ES. For any questions you may have about this library, visit the Protobuf-ES FAQ page.
How do I provide a type registry for sending or receiving Any?
If a RPC in your schema uses
google.protobuf.Any in a request or response
message, you can provide a type registry so that they can be parsed from or
serialized to JSON. See this GitHub discussion
for a detailed explanation and an example.
Missing trailers with Ambassador
If you're using Ambassador for Kubernetes ingress and seeing "server closed the
stream without sending trailers" errors, you may have overlapping gRPC and HTTP
mappings for your backend services. You can work around this problem using the
cluster_tag property, as described in