A Go framework for building browser-facing RPC services based on Protocol Buffers service definitions, with full streaming support.
Protean is inspired by Twirp but has different goals. Specifically, it is intended to produce RPC services that are easy to use directly in the browser with standard browser APIs. It can also be used for server-to-server communication.
Both Protean and Twirp are alternatives to gRPC.
To use Protean, you will need a working knowledge of Protocol Buffers, Protocol Buffers service definitions and generating Go code from .proto files.
Protean provides a protoc plugin called protoc-gen-go-protean, which is used
in addition to the standard protoc-gen-go plugin. The latest version can be
installed by running:
go install github.com/dogmatiq/protean/cmd/protoc-gen-go-protean@latest
To generate Protean server and client code, pass the --go-protean_out flag to
protoc. An example demonstrating how to implement a server and use an RPC
client is available in example_test.go.
Protean exposes APIs via HTTP/1.1 and HTTP/2 using Go's standard HTTP server.
It has complete support for all method types that can be defined in a Protocol Buffers service:
- unary methods, which accept a single request from the client and return a single response from the server
- client streaming methods, which accept a stream of requests from the client and return a single response from the server
- server streaming methods, which accept a single request from the client and return a stream of responses from the server
- bidirectional streaming methods, which accept a stream of requests from the client and return a stream of responses from the server
Depending on what kind of method is being called and what best suits the application, the caller can choose from any of the transports described below on a per-call basis.
| Tranport | Supported Methods | Suitable Browser API | Implementation |
|---|---|---|---|
| HTTP GET | unary | fetch | ❌ |
| HTTP POST | unary | fetch | ✅ |
| JSON-RPC | unary | fetch | ❌ |
| SSE | server streaming | server-sent events | ❌ |
| WebSocket | all | websocket | 🚧 |
All of the above transports are made available via the same HTTP handler. The client uses content negotiation and other similar mechanisms to choose the desired transport.
Protean supports all of the standard Protocol Buffers serialization formats:
- native binary format
- canonical JSON format
- human-readable text format (undocumented)
As with transports, the encoding is chosen via content negotiation. JSON is the default encoding, allowing simpler use from the browser.
Protean can be used for server-to-server communication by using the client code
generated by protoc-gen-go-protean.
This generated will use the most appropriate transport based on the method type being called, and uses the native binary format encoding format by default.