Twirp: Protobuf RPC over Go's net/http

Why Twirp Sits Between net/http and gRPC

Twirp addresses a narrow engineering problem: service-to-service RPC in Go without requiring a separate server or transport architecture. A team defines services in protobuf, then uses the generated bindings instead of manually coordinating HTTP methods, paths, request decoding, response encoding, and client calls. The target audience is therefore Go developers who want a shared protobuf contract and generated code, but also need their services to remain ordinary net/http applications.

That boundary matters operationally. According to the README, Twirp runs on the standard library's net/http Server. It can operate over HTTP 1.1 and supports JSON serialization for easier debugging. This differs from the usual gRPC deployment model, which brings its own HTTP server and transport implementation. Twirp does not attempt to be gRPC at the wire level. Its simpler transport model is the central trade-off: it fits a standard Go HTTP stack, but it does not inherit gRPC-specific transport behavior merely by using protobuf definitions.

Twirp is most relevant when services are internal, contracts benefit from protobuf, and engineers want typed generation without rebuilding an HTTP RPC layer around each API. It is less suitable when gRPC compatibility is mandatory, when the ecosystem requirement centers on gRPC clients, or when a new application depends on advanced RPC features not documented by this repository.

Generated Routing, Serialization, and Go Bindings

The repository is both a generator and a Go runtime library. Code generation begins with protobuf service definitions and produces routing and serialization logic. The example directory makes that split visible through `service.proto`, the generated `service.pb.go`, and the generated `service.twirp.go`, plus command sources under `example/cmd/`. This indicates a conventional protobuf model for message definitions combined with Twirp-specific generated service code.

For a generated server, the application supplies service behavior and exposes the generated routing through an HTTP handler. For a generated client, the caller invokes a typed method corresponding to the protobuf service method. The generated layer owns the wire-facing details that application code would otherwise repeat, including selecting routes and translating request and response bodies. Serialization can use JSON for easier inspection, while protobuf remains the basis of the service definition and generated bindings.

The Go runtime includes client and server options, interceptors, context-related files, and `errors.go`. Their presence confirms that the repository provides extension points beyond basic code generation. The README does not define the exact hook order or every available option, so those semantics should be taken from the linked documentation and source rather than inferred from filenames alone. The documented error model is also linked separately, which is appropriate because RPC failures need stable status information across client and server boundaries.

Installing Twirp and Reaching the First Generated Service

The README directs new users to the Getting Started documentation at `https://twitchtv.github.io/twirp/docs/intro.html` and the Usage Example at `https://twitchtv.github.io/twirp/docs/example.html`. It does not provide a consumer installation command or document a standalone server binary. Adding an import path, module version, or `go install` command here would therefore invent setup instructions.

The repository's own development workflow is visible in the Makefile. The `setup` target checks the required protobuf compiler version, obtains the pinned tool manager, and builds repository tools. The `generate` target installs `./protoc-gen-twirp` into the repository's `bin` directory and runs Go generation. These commands are contributor and generator workflow steps, not a documented installation guide for an application using Twirp. A first real use should therefore begin at the official Getting Started page, follow its protobuf compiler and module setup, define a service, generate the Twirp files, and attach the generated server handler to the application's existing net/http server.

The repository's example directory is the best local reference for expected output: application commands live under `example/cmd/`, while the protobuf, message, and Twirp bindings sit beside them. The README does not expose a service method, request type, response body, endpoint path, or generated method signature, so this review does not invent one.

Operational Costs of HTTP 1.1, JSON, and Code Generation

Twirp's use of net/http is its clearest operational advantage and a source of constraints. HTTP 1.1 support means the framework does not require every Twirp connection to depend on HTTP/2. That can simplify deployment when the surrounding Go service already uses standard HTTP infrastructure. JSON support also makes request and response inspection easier than a binary-only representation would be, although the README does not document production recommendations, configuration toggles, or the precise content negotiation behavior.

Code generation introduces its own maintenance cost. Developers need a compatible protobuf compiler and the `protoc-gen-twirp` generator, and generated files must remain synchronized with service definitions. The repository contains `check_protoc_version.sh`, `tools.json`, `Gopkg.toml`, and `Gopkg.lock`, while its Makefile sets `GO111MODULE=off` for the repository tool workflow. Those files describe Twirp's own build environment. They should not automatically be copied into a modern consuming application without checking its module and protobuf setup.

Upgrades also require attention. The repository follows semantic versioning through Git tags and directs users to GitHub Releases for release notes and upgrade guides. The newest listed release is `v8.1.3` from 2022-10-24, although the repository's last push was on 2026-10-08. Recent source changes without a listed newer release mean version selection and release-note review are more informative than assuming `main` is the intended deployment target.

Where Twirp Is the Wrong RPC Choice

The clearest wrong-tool case is a system that requires compatibility with existing gRPC clients or servers. Sharing `.proto` files does not make Twirp wire-compatible with gRPC, because the README explicitly contrasts their server and transport models. A team selecting Twirp should verify that every required participant can use a Twirp implementation listed for its language.

The README lists third-party clients, servers, or both for languages including Crystal, Elixir, Java, Python, Ruby, Rust, Scala, PHP, JavaScript, Kotlin, Swift, and TypeScript. Coverage is uneven. Some entries provide only a client or only a server, and the README identifies them as third-party implementations. It does not claim that those projects share the Go implementation's release cadence or behavior. Multilanguage adoption therefore requires checking the exact implementation matrix rather than assuming protobuf compatibility guarantees parity.

The README also does not document Twirp streaming, deadlines, retries, load balancing, service discovery, or production observability. Their absence from the README is not proof that none exist, but it is a documentation boundary. Teams selecting Twirp should not base a requirement on one of these behaviors without checking the protocol and implementation source.

Twirp and gRPC Choose Different Transport Boundaries

gRPC is the relevant alternative because both systems use protobuf service definitions and generate clients and servers. The actual difference is not protobuf itself. Twirp generates routing and serialization but delegates the server foundation to Go's `net/http`. gRPC uses its own HTTP server and transport implementations, as stated by the Twirp README. Consequently, Twirp fits teams that want generated RPC inside a conventional net/http service, while gRPC fits environments organized around its own client stack and transport.

Twirp can also use JSON serialization for easier debugging and works with HTTP 1.1. Those properties make its calls more approachable outside Go, but they do not make Twirp a generic interoperability substitute for gRPC. Its Go implementation is supplied in this repository; other-language support comes from separate projects with different client and server coverage.

The repository is licensed under `Apache-2.0`. That identifier should be reviewed against the actual `LICENSE` and `NOTICE` files when distributing modified code or bundled dependencies. This is a licensing identification point, not legal advice. The repository's `THIRD_PARTY` file and vendored dependency tree also make dependency provenance relevant during adoption and upgrades.

Editorial conclusion

Twirp fits Go services and clients that want generated RPC bindings while retaining net/http and JSON accessibility. It is a poor fit when an application requires gRPC's transport, streaming, or interoperability model. Before adoption, verify that the documented generator workflow matches the local protobuf toolchain, inspect the release notes for the intended version, and confirm that required client or server implementations exist in every language used by the system.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. twitchtv/twirp on GitHub