# Twirp — Simple Protobuf RPC Framework by Twitch

> A lightweight RPC framework that generates Go servers and clients from Protobuf definitions, using plain HTTP/1.1 with JSON or Protobuf encoding.

## Install

Save in your project root:

# Twirp — Simple Protobuf RPC Framework by Twitch

## Quick Use
```bash
go install github.com/twitchtv/twirp/protoc-gen-twirp@latest
# Generate server and client from a .proto file
protoc --go_out=. --twirp_out=. service.proto
```

## Introduction
Twirp is an RPC framework created by Twitch that generates Go servers and clients from Protobuf service definitions. Unlike gRPC, Twirp uses standard HTTP/1.1 and works with any HTTP infrastructure without requiring HTTP/2 or special proxies. It supports both Protobuf binary and JSON encoding on the same endpoints.

## What Twirp Does
- Generates type-safe Go server interfaces and client implementations from .proto files
- Serves RPCs over standard HTTP/1.1 POST requests with routing based on URL paths
- Supports both Protobuf binary and JSON content types on every endpoint automatically
- Provides hooks and interceptors for middleware like logging, auth, and metrics
- Works with any HTTP reverse proxy, load balancer, or CDN without special configuration

## Architecture Overview
Twirp generates a Go interface matching each Protobuf service. The server implementation wraps this interface in an http.Handler that routes requests by URL path (/twirp/package.Service/Method). Content negotiation selects Protobuf or JSON based on the Content-Type header. The client is a simple HTTP client that serializes requests and deserializes responses. Errors use a structured format with codes that map to HTTP status codes.

## Self-Hosting & Configuration
- Install the protoc-gen-twirp plugin and use it alongside protoc and protoc-gen-go
- Implement the generated interface and mount the handler on your HTTP server or mux
- Configure interceptors for cross-cutting concerns like authentication and request logging
- Use the generated client with any http.Client, including custom transports for retries or tracing
- Deploy behind standard load balancers like Nginx, HAProxy, or cloud ALBs without changes

## Key Features
- No HTTP/2 or gRPC proxy dependency, working with plain HTTP/1.1 infrastructure
- Dual Protobuf and JSON support on every endpoint makes debugging easy with curl
- Structured error model with typed error codes, metadata, and HTTP status mapping
- Minimal code generation with no runtime reflection or service registration boilerplate
- Small library footprint with no external dependencies beyond the Go standard library

## Comparison with Similar Tools
- **gRPC-Go** — full-featured RPC with streaming and HTTP/2, but requires HTTP/2-aware infrastructure
- **ConnectRPC** — modern gRPC-compatible framework that also supports HTTP/1.1, with broader language support
- **net/http + JSON** — no code generation overhead, but loses type safety and requires manual serialization
- **Buf Connect** — similar goals to Twirp with additional features like streaming and browser support

## FAQ
**Q: Does Twirp support streaming RPCs?**
A: No. Twirp only supports unary request-response RPCs. If you need streaming, consider gRPC or ConnectRPC.

**Q: Can I use Twirp with languages other than Go?**
A: The official generator targets Go, but community generators exist for Python, Ruby, TypeScript, and others.

**Q: Why choose Twirp over gRPC?**
A: Twirp is simpler to deploy because it uses HTTP/1.1 and works with any existing HTTP infrastructure. It is a good choice when you do not need streaming or bidirectional communication.

**Q: How does error handling work?**
A: Twirp defines a set of error codes (not_found, internal, permission_denied, etc.) that map to HTTP status codes. Errors include a code, message, and optional metadata map.

## Sources
- https://github.com/twitchtv/twirp
- https://twitchtv.github.io/twirp/

---
Source: https://tokrepo.com/en/workflows/asset-69cad459
Author: AI Open Source