# connect-rust First 30 Minutes Wiki
> connect-rust is a tower-based ConnectRPC runtime for Rust that lets you build and consume gRPC, gRPC-Web, and Connect-protocol services using generated Rust code from .proto files. It ships three crates — a runtime library, a code-generation library, and a build.rs integration — wired together through a Tower service model.
## Context Links
- [Agent index](https://grok-wiki.com/public/wiki/anthropics-connect-rust-abe117693c52/llms.txt)
- [Human interactive wiki](https://grok-wiki.com/public/wiki/anthropics-connect-rust-abe117693c52)
- [GitHub repository](https://github.com/anthropics/connect-rust)
## Repository Metadata
- Repository: anthropics/connect-rust
- Generated: 2026-05-21T02:35:35.889Z
- Updated: 2026-05-21T21:34:43.297Z
- Runtime: Claude Code
- Format: First 30 Minutes
- Pages: 6
## Page Index
- 01. [Start Here: What This Repo Is & Where to Begin](https://grok-wiki.com/public/wiki/anthropics-connect-rust-abe117693c52/pages/01-start-here-what-this-repo-is-where-to-begin.md) - What connect-rust is, the three-crate layout (connectrpc / connectrpc-codegen / connectrpc-build), the fastest read order for a new contributor, key vocabulary (ConnectRPC, buffa, Tower service, Spec, StreamType), and which files to open first.
- 02. [Build Setup & Code Generation Pipeline](https://grok-wiki.com/public/wiki/anthropics-connect-rust-abe117693c52/pages/02-build-setup-code-generation-pipeline.md) - How .proto files become Rust service traits: connectrpc-build in build.rs, the protoc-gen-connect-rust buf plugin, the two generation modes (unified vs. service-stubs-only), checked-in generated directories, and the task generate:all workflow.
- 03. [Handlers, Router & ConnectRpcService](https://grok-wiki.com/public/wiki/anthropics-connect-rust-abe117693c52/pages/03-handlers-router-connectrpcservice.md) - The server-side dispatch path: implementing the generated FooService handler trait, registering methods on Router, wrapping the router in ConnectRpcService (the Tower service), and mounting it with Axum or raw Hyper. Covers unary and streaming handler shapes.
- 04. [Interceptors & Spec Metadata](https://grok-wiki.com/public/wiki/anthropics-connect-rust-abe117693c52/pages/04-interceptors-spec-metadata.md) - RPC-level interceptors as a typed alternative to Tower middleware: Interceptor trait, Next/NextStream continuations, unary vs. streaming intercept surfaces, registration order, and zero-cost opt-out. Also covers Spec (per-method static metadata) and StreamType, which interceptors use to label spans and gate behaviour without re-parsing URLs.
- 05. [Protocol, Codec & Client Transport](https://grok-wiki.com/public/wiki/anthropics-connect-rust-abe117693c52/pages/05-protocol-codec-client-transport.md) - How the three wire protocols (Connect, gRPC, gRPC-Web) are detected and demultiplexed; envelope framing (5-byte header); codec format selection (proto vs. JSON); compression (gzip, zstd); and the client-side Tower HTTP transport in connectrpc/src/client/. Covers where to look when adding a new codec or compression algorithm.
- 06. [After 30 Minutes: What to Try Next](https://grok-wiki.com/public/wiki/anthropics-connect-rust-abe117693c52/pages/06-after-30-minutes-what-to-try-next.md) - Synthesis of what you now understand — the codegen pipeline, Tower dispatch, interceptor chain, and protocol demux — plus concrete next actions: run the conformance suite, walk the examples (eliza, multiservice, streaming-tour, wasm-client), read docs/guide.md sections on TLS and streaming, and understand how task ci gates every PR.
## Source File Index
- `Cargo.toml`
- `CHANGELOG.md`
- `conformance/buf.gen.yaml`
- `conformance/Cargo.toml`
- `connectrpc-build/src/lib.rs`
- `connectrpc-codegen/src/codegen.rs`
- `connectrpc-codegen/src/lib.rs`
- `connectrpc-codegen/src/plugin.rs`
- `connectrpc/src/axum.rs`
- `connectrpc/src/client/http2.rs`
- `connectrpc/src/client/mod.rs`
- `connectrpc/src/codec.rs`
- `connectrpc/src/compression.rs`
- `connectrpc/src/dispatcher.rs`
- `connectrpc/src/envelope.rs`
- `connectrpc/src/error.rs`
- `connectrpc/src/grpc_status.rs`
- `connectrpc/src/handler.rs`
- `connectrpc/src/interceptor.rs`
- `connectrpc/src/lib.rs`
- `connectrpc/src/payload.rs`
- `connectrpc/src/protocol.rs`
- `connectrpc/src/response.rs`
- `connectrpc/src/router.rs`
- `connectrpc/src/service.rs`
- `connectrpc/src/spec.rs`
- `CONTRIBUTING.md`
- `docs/guide.md`
- `examples/eliza/src`
- `examples/eliza/src/generated`
- `examples/multiservice/src`
- `examples/streaming-tour/src`
- `examples/wasm-client/src`
- `README.md`
- `Taskfile.yaml`
---
## 01. Start Here: What This Repo Is & Where to Begin
> What connect-rust is, the three-crate layout (connectrpc / connectrpc-codegen / connectrpc-build), the fastest read order for a new contributor, key vocabulary (ConnectRPC, buffa, Tower service, Spec, StreamType), and which files to open first.
- Page Markdown: https://grok-wiki.com/public/wiki/anthropics-connect-rust-abe117693c52/pages/01-start-here-what-this-repo-is-where-to-begin.md
- Generated: 2026-05-21T02:33:11.650Z
### Source Files
- `README.md`
- `Cargo.toml`
- `connectrpc/src/lib.rs`
- `docs/guide.md`
- `CONTRIBUTING.md`
Relevant source files
The following files were used as context for generating this wiki page:
- [README.md](README.md)
- [Cargo.toml](Cargo.toml)
- [connectrpc/src/lib.rs](connectrpc/src/lib.rs)
- [connectrpc/src/spec.rs](connectrpc/src/spec.rs)
- [connectrpc/src/interceptor.rs](connectrpc/src/interceptor.rs)
- [connectrpc/src/payload.rs](connectrpc/src/payload.rs)
- [connectrpc-codegen/src/lib.rs](connectrpc-codegen/src/lib.rs)
- [connectrpc-build/src/lib.rs](connectrpc-build/src/lib.rs)
- [docs/guide.md](docs/guide.md)
- [CONTRIBUTING.md](CONTRIBUTING.md)
# Start Here: What This Repo Is & Where to Begin
`connect-rust` is a [Tower](https://docs.rs/tower/latest/tower/)-based Rust implementation of the [ConnectRPC](https://connectrpc.com/) protocol. It lets you build servers and clients that speak Connect, gRPC, and gRPC-Web over HTTP — using the same transport-agnostic `tower::Service` abstraction the broader Rust web ecosystem relies on. The library passes 3,600 server and 6,872 client conformance tests across all three protocols and is production-quality even at its pre-1.0 version.
This page orients you to the repository's structure, key terms, and the fastest reading path before you touch code. It answers the question every new contributor has: *where do I start?*
---
## The Three-Crate Layout
The workspace (`Cargo.toml`) publishes three crates that work together:
```text
connect-rust/
├── connectrpc/ ← runtime library (Tower service, codecs, compression, interceptors)
├── connectrpc-codegen/ ← code generation library + protoc-gen-connect-rust binary
└── connectrpc-build/ ← build.rs integration (wraps codegen for use at build time)
```
Sources: [Cargo.toml:1-11](), [docs/guide.md:27-33]()
### `connectrpc` — The Runtime
This is the crate your application code depends on at runtime. It provides:
- **`ConnectRpcService`** — the core `tower::Service` that receives HTTP requests and dispatches them to registered handlers.
- **`Router`** — collects RPC handler registrations; call `.register()` on your service impl to populate it.
- **`Handler` / `ViewHandler` / streaming variants** — async handler traits your service structs implement. The `View`-prefixed variants return zero-copy `buffa` view types directly from the request buffer.
- **`Interceptor` / `Next` / `NextStream`** — typed RPC middleware: runs after envelope decoding but before handler invocation; has access to `Spec`, headers, deadline, and a lazily decoded `Payload`.
- **`Spec` / `StreamType`** — static per-method metadata (see [Key Vocabulary](#key-vocabulary) below).
- **`Payload` / `AnyMessage`** — type-erased, lazily-decoded message bodies used by interceptors.
- **`client` module** — `HttpClient` and `Http2Connection` transports for generated clients (enabled by the `client` feature flag).
- **`Server`** — a built-in standalone hyper server (enabled by the `server` feature).
Sources: [connectrpc/src/lib.rs:1-200](), [connectrpc/src/lib.rs:220-315]()
### `connectrpc-codegen` — Code Generation Library and Plugin
This crate lives in two roles simultaneously:
1. **Library** (`codegen::generate_files` / `codegen::generate_services`): drives code generation from compiled proto descriptors. Used internally by `connectrpc-build` and the plugin binary.
2. **Binary** (`protoc-gen-connect-rust`): a `protoc` / `buf` plugin that generates service traits, client structs, and `Spec` constants from `.proto` files. Install it with `cargo install --locked connectrpc-codegen` or download a release binary.
Two generation modes exist:
- **Unified** (`generate_files`): message types + service stubs in one file per proto, with `super::`-relative paths. Used by `connectrpc-build`.
- **Service-stubs only** (`generate_services`): references message types via configurable absolute paths (e.g. `crate::proto::greet::v1::GreetRequest`). Used by the `protoc-gen-connect-rust` plugin when paired with `buf generate`.
Sources: [connectrpc-codegen/src/lib.rs:1-43]()
### `connectrpc-build` — Build-time Integration
A `build.rs` helper that shells out to `protoc` (or `buf`, or reads a pre-compiled `FileDescriptorSet`) to obtain descriptors, then calls `connectrpc-codegen` to write Rust code into `$OUT_DIR`. After adding this as a build-dependency, you reference the output with `connectrpc::include_generated!()`.
```rust
// build.rs
fn main() {
connectrpc_build::Config::new()
.files(&["proto/greet.proto"])
.includes(&["proto/"])
.include_file("_connectrpc.rs")
.compile()
.unwrap();
}
```
Sources: [connectrpc-build/src/lib.rs:1-54]()
---
## Key Vocabulary
New contributors encounter a handful of terms that don't resolve obviously from the crate names alone.
| Term | What it means |
|---|---|
| **ConnectRPC** | The [protocol specification](https://connectrpc.com/docs/protocol/) that defines how unary and streaming RPC calls are framed over HTTP/1.1 and HTTP/2. Connect is one of three protocols this library speaks; the other two are gRPC and gRPC-Web. |
| **buffa** | The companion protobuf runtime from `github.com/anthropics/buffa`. Replaces prost. Its key feature is *view types*: zero-copy structs that borrow string and bytes fields directly from the incoming request buffer, avoiding per-field allocations. `buffa = { version = "0.6" }` is a workspace dependency. |
| **Tower service** | `tower::Service`. `ConnectRpcService` implements this trait, making it composable with any Tower-compatible HTTP framework (Axum, Hyper) or middleware stack. |
| **`Spec`** | A `Copy`, `'static` struct emitted as a `const` by codegen for each RPC method. Carries the fully-qualified procedure path (`"/pkg.Service/Method"`), its `StreamType`, its idempotency level, and whether it lives on the client or server side (`SpecOrigin`). Interceptors read `Spec` to label tracing spans or route behavior without re-parsing the URL. |
| **`StreamType`** | An enum with four variants: `Unary`, `ClientStream`, `ServerStream`, `BidiStream`. Records how many messages flow in each direction on a given RPC. The connect-go naming is used so cross-runtime interceptor logic ports cleanly. |
| **`Payload`** | A type-erased, lazily-decoded request/response body. Holds wire bytes as a reference-counted `Bytes` and decodes to the typed message on first access. Interceptors that never inspect message content pay zero decode cost. |
| **`Interceptor`** | A typed RPC middleware trait. Unlike a raw Tower layer, an interceptor runs *after* envelope decoding and header parsing — it sees the already-understood `Spec` and `Payload`, not raw bytes. Registered via `ConnectRpcService::with_interceptor`. |
| **`MethodKind` / `MethodDescriptor`** | Internal routing-table equivalents of `StreamType`; used by `Router` when registering handlers. `StreamType` is the interceptor-facing version; prefer it in interceptor code. |
Sources: [connectrpc/src/spec.rs:1-60](), [connectrpc/src/interceptor.rs:1-42](), [connectrpc/src/payload.rs:1-15]()
---
## How the Three Pieces Fit Together
```text
.proto files
│
▼
┌─────────────────────────────────────┐
│ Code Generation (pick one path) │
│ │
│ Option A: buf generate │
│ protoc-gen-buffa → message types (src/generated/buffa/)
│ protoc-gen-connect-rust → service stubs (src/generated/connect/)
│ │
│ Option B: build.rs │
│ connectrpc-build::Config::compile()
│ → unified .rs into $OUT_DIR/ │
└─────────────────────────────────────┘
│
▼ (generated output)
FooServiceServer FooServiceClient const SPEC_FOO: Spec
│ │
▼ ▼
┌──────────────┐ ┌──────────────────────┐
│ connectrpc │ │ connectrpc client │
│ Router │ │ HttpClient / │
│ Dispatcher │ │ Http2Connection │
│ ConnectRpc │ └──────────────────────┘
│ Service │
│ (tower:: │
│ Service) │
└──────────────┘
│
▼
Axum / Hyper / standalone Server
```
Sources: [README.md:23-30](), [connectrpc/src/lib.rs:62-73]()
---
## The Two Codegen Workflows
### Option A — `buf generate` (checked-in code)
Run `buf generate` with two plugins: `protoc-gen-buffa` (message types) and `protoc-gen-connect-rust` (service stubs). Each produces its own output directory. The `buffa_module=crate::proto` option tells the service-stub generator where the buffa output is mounted in your crate, so it emits absolute paths like `crate::proto::greet::v1::GreetRequest`.
Use this when you want generated code checked into source control and reviewed in PRs.
### Option B — `connectrpc-build` (build-time generation)
Add `connectrpc-build` as a build dependency and call it from `build.rs`. Message types and service stubs appear in one file per proto under `$OUT_DIR`, referenced via `connectrpc::include_generated!()`. No plugin binaries on `PATH` at build time (only `protoc` or `buf`).
Use this for simpler projects or when you don't want generated code in git.
Sources: [README.md:57-179](), [connectrpc-build/src/lib.rs:1-33]()
---
## Feature Flags
The runtime is gated so you only pay for what you use. Defaults include compression; networking is opt-in.
| Feature | Default | What it adds |
|---|---|---|
| `gzip` | yes | Gzip compression (flate2) |
| `zstd` | yes | Zstandard compression |
| `streaming` | yes | Streaming compression (async-compression) |
| `client` | **no** | HTTP client transports (plaintext) |
| `client-tls` | **no** | TLS for client transports |
| `server` | **no** | Built-in hyper `Server` |
| `server-tls` | **no** | TLS for the built-in server |
| `tls` | **no** | Convenience alias: both server-tls + client-tls |
| `axum` | **no** | Axum integration (`into_axum_service`) |
The core crate also compiles for `wasm32-unknown-unknown`. Client transports, server, TLS, and `zstd` require native targets and are excluded on wasm.
Sources: [connectrpc/src/lib.rs:139-152](), [README.md:307-340]()
---
## Fastest Read Order for a New Contributor
Work through these in order. Each step builds on the previous and should take 5–15 minutes.
### Step 1 — Orient yourself (15 min)
| File | What to notice |
|---|---|
| [`README.md`](README.md) | The quick-start shows the full unary server + Axum loop. Read the feature-flag table and the protocol support matrix. |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Prerequisites (Rust 1.88, protoc v27+, buf, task), change-size limit (≤250 net lines), test-coverage expectations, and the `task` command inventory. |
| [`Cargo.toml`](Cargo.toml) | The workspace member list, the `buffa` dependency version floor, and the compression / TLS / framework dependency choices. |
### Step 2 — The runtime entry point (20 min)
| File | What to notice |
|---|---|
| [`connectrpc/src/lib.rs`](connectrpc/src/lib.rs) | Module inventory and the full re-export surface. Every public symbol the library exposes is listed here. The `__codegen` hidden module is what generated code calls. |
| [`connectrpc/src/spec.rs`](connectrpc/src/spec.rs) | `Spec`, `StreamType`, `IdempotencyLevel`, `SpecOrigin`. These four types are the lingua franca of interceptors and generated code; understanding them unlocks the rest. |
### Step 3 — Interceptors and Payload (15 min)
| File | What to notice |
|---|---|
| [`connectrpc/src/interceptor.rs`](connectrpc/src/interceptor.rs) | The `Interceptor` trait and how unary vs streaming interceptors differ. Notice the ASCII diagram of interception order. |
| [`connectrpc/src/payload.rs`](connectrpc/src/payload.rs) | Why `Payload` is lazily decoded: most interceptors never look inside the message. |
### Step 4 — Code generation (15 min)
| File | What to notice |
|---|---|
| [`connectrpc-codegen/src/lib.rs`](connectrpc-codegen/src/lib.rs) | The two generation modes (`generate_files` vs `generate_services`) and when each is used. |
| [`connectrpc-build/src/lib.rs`](connectrpc-build/src/lib.rs) | The `Config` builder: how `DescriptorSource` (protoc / buf / precompiled) is selected at build time. |
### Step 5 — The user guide and examples (30 min)
| File | What to notice |
|---|---|
| [`docs/guide.md`](docs/guide.md) | Long-form coverage of every topic: installation, codegen, streaming, interceptors, Tower middleware, TLS, errors, compression. Read the sections that match your task. |
| [`examples/`](examples/) | Runnable examples: `eliza` (TLS), `middleware` (Tower auth layer), `streaming-tour` (all four RPC types side by side), `wasm-client` (Fetch transport), `multiservice` (multi-service router). |
---
## Files to Open First
If you are fixing a bug or adding a feature, these files are most likely to be involved:
```text
connectrpc/src/
├── lib.rs ← re-export surface; start here to find any symbol
├── spec.rs ← Spec, StreamType — shared by codegen and runtime
├── interceptor.rs ← Interceptor trait; the RPC middleware API
├── handler.rs ← Handler traits your service structs implement
├── router.rs ← MethodKind, Router — the routing table
├── service.rs ← ConnectRpcService — the tower::Service impl
├── payload.rs ← Payload, AnyMessage — lazy decode
├── codec.rs ← ProtoCodec, JsonCodec — encode/decode
├── compression.rs ← CompressionProvider, CompressionRegistry
└── client/ ← HttpClient, Http2Connection, CallOptions
connectrpc-codegen/src/
├── lib.rs ← two generation entry points
└── codegen/ ← quote!-based code emitters
connectrpc-build/src/
└── lib.rs ← Config builder; DescriptorSource variants
```
---
## What the Workspace Also Contains
Beyond the three published crates, the workspace includes:
| Path | Purpose |
|---|---|
| `conformance/` | Conformance test runner binaries (server and client) that talk to the upstream ConnectRPC conformance suite |
| `examples/eliza/`, `examples/streaming-tour/`, etc. | Runnable end-to-end examples; see `docs/guide.md` for a tour |
| `tests/streaming` | In-workspace integration consumer of `connectrpc-build` — the canonical test of the build-time codegen path |
| `benches/rpc/` | Criterion benchmarks; `task bench:cross:quick` runs them |
| `docs/specs/` | Local copies of the Connect, gRPC, and gRPC-Web protocol specs; fetch with `task specs:fetch` |
Sources: [Cargo.toml:2](), [CONTRIBUTING.md:1-120]()
---
## Summary
`connect-rust` is a three-crate workspace: `connectrpc` (the Tower-based runtime), `connectrpc-codegen` (the `protoc-gen-connect-rust` plugin library and binary), and `connectrpc-build` (the `build.rs` wrapper). The vocabulary that glues them together is small: `Spec` describes a method statically, `StreamType` describes its message shape, `Payload` defers decode cost to interceptors that actually need it, and `buffa` provides the zero-copy protobuf message types. Start with `connectrpc/src/lib.rs` to see every public symbol in one place, then read `connectrpc/src/spec.rs` and `docs/guide.md` before touching anything else.
Sources: [connectrpc/src/lib.rs:1-75](), [connectrpc/src/spec.rs:1-40]()
---
## 02. Build Setup & Code Generation Pipeline
> How .proto files become Rust service traits: connectrpc-build in build.rs, the protoc-gen-connect-rust buf plugin, the two generation modes (unified vs. service-stubs-only), checked-in generated directories, and the task generate:all workflow.
- Page Markdown: https://grok-wiki.com/public/wiki/anthropics-connect-rust-abe117693c52/pages/02-build-setup-code-generation-pipeline.md
- Generated: 2026-05-21T02:33:34.472Z
### Source Files
- `connectrpc-build/src/lib.rs`
- `connectrpc-codegen/src/lib.rs`
- `connectrpc-codegen/src/codegen.rs`
- `connectrpc-codegen/src/plugin.rs`
- `Taskfile.yaml`
- `conformance/buf.gen.yaml`
- `examples/eliza/src/generated`
Relevant source files
The following files were used as context for generating this wiki page:
- [connectrpc-build/src/lib.rs](connectrpc-build/src/lib.rs)
- [connectrpc-codegen/src/lib.rs](connectrpc-codegen/src/lib.rs)
- [connectrpc-codegen/src/codegen.rs](connectrpc-codegen/src/codegen.rs)
- [connectrpc-codegen/src/plugin.rs](connectrpc-codegen/src/plugin.rs)
- [Taskfile.yaml](Taskfile.yaml)
- [conformance/buf.gen.yaml](conformance/buf.gen.yaml)
- [examples/eliza/buf.gen.yaml](examples/eliza/buf.gen.yaml)
- [examples/eliza/src/generated/connect/connectrpc.eliza.v1.eliza.__connect.rs](examples/eliza/src/generated/connect/connectrpc.eliza.v1.eliza.__connect.rs)
# Build Setup & Code Generation Pipeline
This page explains how `.proto` service definitions become Rust service traits and client structs in connect-rust. The pipeline has two distinct entry points — a `build.rs` integration crate (`connectrpc-build`) and a `protoc`/`buf` plugin binary (`protoc-gen-connect-rust`) — each suited to a different workflow. Understanding the difference between unified and split generation, and knowing which checked-in directories exist, will save you from mysterious compile errors and regeneration confusion.
The core library (`connectrpc-codegen`) sits underneath both entry points. It owns all `quote!`-based Rust emission logic and exposes two public functions: `generate_files` (unified, used by `connectrpc-build`) and `generate_services` (service-stubs-only, used by the plugin). Both are built on `buffa-codegen` for protobuf message types; connect-rust adds only the service traits, clients, and `Encodable` impls.
---
## Prerequisites
| Tool | Minimum | Purpose |
|---|---|---|
| Rust | 1.88 (MSRV) | Compiles the workspace; requires let-chains |
| `protoc` | v27+ | Default descriptor source (editions syntax) |
| `buf` | any current | BSR module resolution, checked-in regeneration |
| `task` (go-task) | any | Command runner — `task --list` shows all targets |
`protoc` can be overridden with the `PROTOC` environment variable. When using `buf` mode, `protoc` is not needed at all. Sources: [connectrpc-build/src/lib.rs:377](), [conformance/buf.gen.yaml:1-33]()
---
## Two Entry Points, Two Generation Modes
```text
.proto files
│
├─── connectrpc-build (build.rs) ──► generate_files() ─► $OUT_DIR/
│ Unified: messages + stubs (buffa types + service traits
│ in one module tree) in one $OUT_DIR tree)
│
└─── protoc-gen-connect-rust ────► generate_services() ─► out/connect/
(buf plugin, checked-in code) Service stubs only; message types
referenced via extern_paths
```
### Unified mode (`connectrpc-build` / `generate_files`)
Used in `build.rs`. Emits buffa message types **and** ConnectRPC service stubs together into `$OUT_DIR`. Service stubs reference message types with `super::`-relative paths, so both must live in the same module tree. This is the simplest workflow for projects that don't check in generated code.
```rust
// build.rs
fn main() {
connectrpc_build::Config::new()
.files(&["proto/my_service.proto"])
.includes(&["proto/"])
.include_file("_connectrpc.rs")
.compile()
.unwrap();
}
// lib.rs
connectrpc::include_generated!();
```
Sources: [connectrpc-build/src/lib.rs:1-27](), [connectrpc-codegen/src/lib.rs:16-20]()
### Split mode (`protoc-gen-connect-rust` / `generate_services`)
Used as a `buf` plugin to regenerate checked-in code. Emits **service stubs only** (`.__connect.rs` files) into a separate output directory. Message types are referenced via absolute Rust paths configured with `buffa_module=`. This is the workflow for checked-in generated code and BSR cargo SDKs.
Sources: [connectrpc-codegen/src/lib.rs:22-27](), [connectrpc-codegen/src/codegen.rs:274-285]()
---
## `connectrpc-build`: The `build.rs` Integration
`connectrpc-build` is a builder-pattern crate you add to `build-dependencies`. Its `Config` struct collects options and then drives the full pipeline on `compile()`.
### Descriptor acquisition
`Config` supports three ways to get a `FileDescriptorSet`:
| Mode | Trigger | Tool required |
|---|---|---|
| `Protoc` (default) | — | `protoc` on `PATH` or `$PROTOC` |
| `Buf` | `.use_buf()` | `buf` on `PATH` |
| `Precompiled` | `.descriptor_set("path.bin")` | none at build time |
Under `Protoc` mode, includes are sorted longest-first before stripping so that nested prefix directories (`proto/vendor/`) beat shallower ones (`proto/`). Under `Buf` and `Precompiled` modes, `.files()` takes proto-relative names (e.g. `"my/service.proto"`) not filesystem paths — the include stripping does not apply. Sources: [connectrpc-build/src/lib.rs:44-54](), [connectrpc-build/src/lib.rs:270-294]()
### The `compile()` pipeline
```
1. Acquire FileDescriptorSet bytes
(run_protoc / run_buf / read precompiled file)
2. Decode FileDescriptorSet via buffa
3. codegen::generate_files(fds, files_to_generate, options)
4. Write per-file .rs outputs (write_if_changed)
5. Optionally emit include file (_connectrpc.rs)
6. Emit cargo:rerun-if-changed directives
```
`write_if_changed` skips writing identical content to avoid bumping mtimes and forcing downstream recompilation on every proto touch. Sources: [connectrpc-build/src/lib.rs:249-353](), [connectrpc-build/src/lib.rs:366-373]()
### Key builder methods
| Method | Default | Effect |
|---|---|---|
| `.files(&[...])` | required | Proto files to compile |
| `.includes(&[...])` | `[]` | Import search dirs (protoc only) |
| `.use_buf()` | — | Use `buf build` instead of `protoc` |
| `.descriptor_set("x.bin")` | — | Read precompiled FDS |
| `.include_file("_inc.rs")` | none | Emit module-tree include file |
| `.file_per_package(true)` | `false` | Emit one `.rs` per package (unified layout) |
| `.generate_json(false)` | `true` | Disable serde derives |
| `.emit_rerun_directives(false)` | `true` | For non-Cargo build systems |
| `.buffa_config(cfg)` | — | Replace buffa CodeGenConfig wholesale |
Sources: [connectrpc-build/src/lib.rs:83-190]()
---
## `protoc-gen-connect-rust`: The buf Plugin
The plugin binary lives in `connectrpc-codegen/src/main.rs` (installed via `cargo install --path connectrpc-codegen`). It implements the protoc plugin protocol: reads a `CodeGeneratorRequest` from stdin, calls `codegen::generate()`, and writes a `CodeGeneratorResponse` to stdout.
`generate()` parses comma-separated plugin `opt` parameters then delegates to `generate_services`. Sources: [connectrpc-codegen/src/codegen.rs:426-483]()
### Plugin options
| Option | Effect |
|---|---|
| `buffa_module=crate::proto` | Set the catch-all extern path (most common) |
| `extern_path=.pkg=::rust::path` | Map a specific proto package prefix (repeatable) |
| `file_per_package` | Emit one `.rs` per package (no stitchers) |
| `strict_utf8_mapping` | Emit `Vec` for non-utf8 string fields |
| `no_json` | Accepted for compatibility; ignored (no messages emitted) |
| `no_register_fn` | Accepted for compatibility; ignored |
At least one catch-all extern path (`buffa_module` or `extern_path=.=...`) is required so every message type resolves. Sources: [connectrpc-codegen/src/codegen.rs:398-476]()
---
## Output File Layout
### Per-proto split (default)
For each `.proto` with at least one `service`, both modes emit:
```text
out/
├── .rs # buffa message types (unified only)
├── .__view.rs # buffa view types (unified only)
├── .__connect.rs # ConnectRPC service traits + clients
└── .mod.rs # Package stitcher (include!s siblings)
```
The `.__connect.rs` suffix is intentional — it avoids colliding with buffa's own per-proto filenames (`.rs`, `.__view.rs`, etc.). The package stitcher (`.mod.rs`) is wired by `apply_companions` in the unified path, or emitted directly by `generate_services` in the split path. Sources: [connectrpc-codegen/src/codegen.rs:109-125](), [connectrpc-codegen/src/codegen.rs:182-184]()
### `file_per_package` layout
When `file_per_package` is enabled, everything collapses to one file per proto package:
```text
out/
└── .rs # messages + service stubs inlined (no companion files, no stitcher)
```
This mirrors the BSR/tonic filename convention. No `__connect.rs` siblings exist; no `protoc-gen-buffa-packaging` invocations are needed. Sources: [connectrpc-codegen/src/codegen.rs:168-178](), [connectrpc-build/src/lib.rs:151-174]()
### The include file
When `.include_file("_inc.rs")` is set, `connectrpc-build` emits a module-tree include file with nested `pub mod` blocks matching the proto package hierarchy. Include paths use either `env!("OUT_DIR")` (default `$OUT_DIR` workflow) or sibling-relative strings (when `out_dir()` is set explicitly).
```rust
// Generated _inc.rs (env!("OUT_DIR") form)
#[allow(impl_trait_redundant_captures, ...)]
pub mod connectrpc {
use super::*;
pub mod eliza {
use super::*;
pub mod v1 {
use super::*;
include!(concat!(env!("OUT_DIR"), "/connectrpc.eliza.v1.mod.rs"));
}
}
}
```
Sources: [connectrpc-build/src/lib.rs:463-545]()
---
## Checked-In Generated Directories
Four directories contain `buf generate` output that must be regenerated whenever `connectrpc-codegen` changes or the `buffa` dependency is bumped:
| Directory | Proto source | Notes |
|---|---|---|
| `conformance/src/generated/` | `buf.build/connectrpc/conformance` (BSR) | Separate `buffa/` and `connect/` subdirs |
| `examples/eliza/src/generated/` | local `proto/` | Same split layout |
| `examples/multiservice/src/generated/` | local `proto/` | Same split layout |
| `benches/rpc/src/generated/` | local `proto/` | Same split layout |
All four use the split layout: `protoc-gen-buffa` into `src/generated/buffa/`, `protoc-gen-connect-rust` into `src/generated/connect/`. Each directory has its own `buf.gen.yaml`.
### Example: eliza `buf.gen.yaml`
```yaml
# examples/eliza/buf.gen.yaml
version: v2
plugins:
- local: ../../../buffa/target/release/protoc-gen-buffa
out: src/generated/buffa
opt: [views=true, json=true]
- local: ../../../buffa/target/release/protoc-gen-buffa-packaging
out: src/generated/buffa
strategy: all
- local: ../../target/release/protoc-gen-connect-rust
out: src/generated/connect
opt: [buffa_module=crate::proto]
- local: ../../../buffa/target/release/protoc-gen-buffa-packaging
out: src/generated/connect
strategy: all
opt: [filter=services]
```
The second `protoc-gen-buffa-packaging` invocation with `filter=services` emits the `.mod.rs` stitcher for the connect output tree, covering only packages with service-declaring protos. Sources: [examples/eliza/buf.gen.yaml:1-16](), [conformance/buf.gen.yaml:1-33]()
### What the generated connect file looks like
The `.__connect.rs` files use fully-qualified paths (`::connectrpc::`, `::buffa::`) throughout — no top-level `use` statements — so multiple generated files can be `include!`d into the same module without E0252 collisions. Message types are referenced through the `buffa_module` path (e.g. `crate::proto::connectrpc::eliza::v1::SayResponse`). Sources: [examples/eliza/src/generated/connect/connectrpc.eliza.v1.eliza.__connect.rs:1-60]()
---
## The `task generate:all` Workflow
`task generate:all` is the single command to regenerate all four checked-in directories:
```bash
task generate:all
```
It runs the following steps in order:
```
1. cargo build --release -p connectrpc-codegen --bin protoc-gen-connect-rust
(build the plugin from the current source)
2. cargo build --release --manifest-path ../buffa/Cargo.toml \
-p protoc-gen-buffa -p protoc-gen-buffa-packaging
(build sibling buffa plugins)
3. task example:eliza:generate → cd examples/eliza && buf generate
4. task example:multiservice:generate → cd examples/multiservice && buf generate
5. task conformance:generate → cd conformance && BUF_TOKEN="" buf generate
6. task bench:generate → cd benches/rpc && buf generate
```
The build steps use release mode because `buf.gen.yaml` references the plugin binaries at `../../target/release/protoc-gen-connect-rust`. If you're iterating on codegen, run `task generate:all` after every change. CI detects stale generated code as compile errors in the `Check`/`Test` jobs, not as a dedicated stale-check. Sources: [Taskfile.yaml:368-376](), [Taskfile.yaml:119-123]()
### Local buffa override
When testing combined speculative changes across both repos:
```bash
task buffa:link # writes .cargo/config.toml with path overrides to ../buffa
task buffa:unlink # removes the override
```
The `.cargo/config.toml` override is gitignored. Sources: [Taskfile.yaml:98-109]()
---
## Sequence: How a `.proto` Becomes a Rust Trait
```mermaid
sequenceDiagram
participant BR as build.rs / buf generate
participant CB as connectrpc-build Config
participant PC as protoc / buf
participant CG as codegen::generate_files
participant BC as buffa-codegen
participant FS as $OUT_DIR / src/generated/
BR->>CB: Config::new().files(...).compile()
CB->>PC: run_protoc() / run_buf()
PC-->>CB: FileDescriptorSet bytes
CB->>CG: generate_files(fds, files, options)
CG->>BC: buffa_codegen::generate(...)
BC-->>CG: per-proto GeneratedFiles (Owned, View, Oneof, PackageMod)
CG->>CG: emit_service_files() → __connect.rs Companion files
CG->>CG: apply_companions() wires companions into PackageMod stitchers
CG-->>CB: Vec
CB->>FS: write_if_changed() for each file
CB->>FS: generate_include_file() → _inc.rs (if configured)
CB->>BR: cargo:rerun-if-changed directives
```
The key invariant enforced in debug builds: every `Companion` (`.__connect.rs`) file must be referenced by an `include!` inside a matching `PackageMod` stitcher. If `apply_companions` orphans a companion, the service trait silently vanishes at use-site. Sources: [connectrpc-codegen/src/codegen.rs:155-200]()
---
## Summary
The connect-rust build pipeline revolves around two modes sharing one codegen core. The `connectrpc-build` crate handles the `build.rs` path end-to-end: it shells out to `protoc` or `buf`, decodes the descriptor set, calls `generate_files` for unified output, and writes everything to `$OUT_DIR`. The `protoc-gen-connect-rust` plugin handles checked-in regeneration via `buf generate`: it emits service stubs only (`__connect.rs` files) into a separate directory alongside buffa's message output, using `buffa_module=crate::proto` to resolve all type paths. The single `task generate:all` command rebuilds all plugin binaries from source and reruns `buf generate` in all four checked-in directories, ensuring the generated code stays synchronized with the codegen logic. Sources: [connectrpc-codegen/src/lib.rs:1-43]()
---
## 03. Handlers, Router & ConnectRpcService
> The server-side dispatch path: implementing the generated FooService handler trait, registering methods on Router, wrapping the router in ConnectRpcService (the Tower service), and mounting it with Axum or raw Hyper. Covers unary and streaming handler shapes.
- Page Markdown: https://grok-wiki.com/public/wiki/anthropics-connect-rust-abe117693c52/pages/03-handlers-router-connectrpcservice.md
- Generated: 2026-05-21T02:35:35.867Z
### Source Files
- `connectrpc/src/handler.rs`
- `connectrpc/src/router.rs`
- `connectrpc/src/service.rs`
- `connectrpc/src/dispatcher.rs`
- `connectrpc/src/axum.rs`
- `connectrpc/src/response.rs`
- `examples/eliza/src`
Relevant source files
The following files were used as context for generating this wiki page:
- [connectrpc/src/handler.rs](connectrpc/src/handler.rs)
- [connectrpc/src/router.rs](connectrpc/src/router.rs)
- [connectrpc/src/service.rs](connectrpc/src/service.rs)
- [connectrpc/src/dispatcher.rs](connectrpc/src/dispatcher.rs)
- [connectrpc/src/axum.rs](connectrpc/src/axum.rs)
- [connectrpc/src/response.rs](connectrpc/src/response.rs)
- [examples/eliza/src/main.rs](examples/eliza/src/main.rs)
- [examples/eliza/src/generated/connect/connectrpc.eliza.v1.eliza.__connect.rs](examples/eliza/src/generated/connect/connectrpc.eliza.v1.eliza.__connect.rs)
# Handlers, Router & ConnectRpcService
This page covers the server-side dispatch path: from implementing a generated `FooService` trait to mounting the router as a Tower service inside an Axum or Hyper application. It walks through the three conceptual layers — **handler traits**, **Router registration**, and **ConnectRpcService** (the Tower service) — and shows where the generated codegen glue and the hand-written path differ.
Understanding this path matters because the architecture makes a deliberate split: the *type-aware* layer (handler traits, request decode, response encode) is handled at compile time, while the *dispatch* layer (method-path lookup, protocol negotiation, envelope framing, interceptors, limits) happens uniformly inside `ConnectRpcService`. The two paths interact through the `Dispatcher` trait.
---
## Architecture Overview
```text
HTTP request
│
▼
┌─────────────────────────────┐
│ ConnectRpcService │ Tower Service — protocol decode, limits,
│ (service.rs:1098) │ compression, interceptors, deadline, tracing
└──────────┬──────────────────┘
│ Dispatcher::lookup(path) → MethodDescriptor (kind, idempotent, Spec)
│ Dispatcher::call_*(...)
▼
┌──────────────────────────────────────┐
│ D: Dispatcher │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Router │ │ FooServiceServer│ │
│ │ (HashMap) │ │ (monomorphic)│ │
│ └──────┬───────┘ └──────┬───────┘ │
└─────────┼─────────────────┼──────────┘
│ │
▼ ErasedHandler ▼ direct match
Handler FooService trait impl
(handler.rs) (user code / Arc)
```
Sources: [connectrpc/src/dispatcher.rs:1-19](), [connectrpc/src/service.rs:1098-1109]()
---
## Handler Traits
### The public surface
The library defines four handler *kinds*, mirroring the four RPC streaming shapes:
| Kind | Trait | Signature |
|---|---|---|
| Unary | `Handler` | `fn call(&self, ctx, Req) -> BoxFuture>` |
| Server streaming | `StreamingHandler` | `fn call(&self, ctx, Req) -> BoxFuture>>` |
| Client streaming | `ClientStreamingHandler` | `fn call(&self, ctx, ServiceStream) -> BoxFuture>` |
| Bidi streaming | `BidiStreamingHandler` | `fn call(&self, ctx, ServiceStream) -> BoxFuture>>` |
Each trait has a parallel *view* variant (`ViewHandler`, `ViewStreamingHandler`, `ViewClientStreamingHandler`, `ViewBidiStreamingHandler`) that receives an `OwnedView` instead of an owned `Req`. Views give zero-copy `&str` / `&[u8]` access into the decoded buffer without an extra allocation.
Sources: [connectrpc/src/handler.rs:154-170](), [connectrpc/src/handler.rs:276-297](), [connectrpc/src/handler.rs:415-429](), [connectrpc/src/handler.rs:537-554]()
### Function-wrapper helpers
You rarely implement these traits by hand. Four `*_handler_fn` helpers wrap closures:
```rust
// Unary: closure takes (ctx, owned Req)
let h = handler_fn(|ctx: RequestContext, req: SayRequest| async move {
Response::ok(SayResponse { sentence: "hello".into(), ..Default::default() })
});
// Server-streaming: closure returns a stream
let h = streaming_handler_fn(|ctx, req: IntroduceRequest| async move {
Response::stream_ok(futures::stream::iter([
Ok(IntroduceResponse { sentence: "Hi!".into(), ..Default::default() })
]))
});
// View (zero-copy): closure takes OwnedView
let h = view_handler_fn(|ctx, req: OwnedView>, format| async move {
let reply = lookup_reply(req.sentence); // req.sentence is &str, no allocation
Response::ok(SayResponse { sentence: reply, ..Default::default() })?.encode::(format)
});
```
Sources: [connectrpc/src/handler.rs:172-210](), [connectrpc/src/handler.rs:331-361](), [connectrpc/src/handler.rs:748-755]()
### Response metadata
Handlers return `ServiceResult` where `Body: Encodable`. The `Response` wrapper carries both the body and optional response-side metadata via a fluent builder:
```rust
Response::ok(body) // body only (most handlers)
Response::ok(body)
.with_header("x-trace-id", id) // add a response header
.with_trailer("grpc-status-bin", bin) // add a trailer
```
This separates read-only `RequestContext` (passed *in*) from `Response` (returned *out*), avoiding the earlier design where a mutable `Context` was threaded through both directions.
Sources: [connectrpc/src/response.rs:282-310]()
---
## Router
`Router` is the dynamic dispatch path. It maps `"service_name/method_name"` string keys to type-erased handlers stored in a `HashMap`.
### Registration methods
```rust
let router = Router::new()
// Unary
.route("pkg.v1.MyService", "DoThing", handler)
// Idempotent unary — enables Connect GET
.route_idempotent("pkg.v1.MyService", "GetThing", handler)
// Server streaming
.route_server_stream("pkg.v1.MyService", "Watch", streaming_handler)
// Client streaming
.route_client_stream("pkg.v1.MyService", "Upload", client_stream_handler)
// Bidi streaming
.route_bidi_stream("pkg.v1.MyService", "Chat", bidi_handler)
// Zero-copy view variants exist for all four shapes
.route_view("pkg.v1.MyService", "FastRead", view_handler);
```
Each `route_*` call wraps the handler in a type-erasing `*HandlerWrapper` (e.g. `UnaryHandlerWrapper`, `ServerStreamingHandlerWrapper`) and stores it behind `Arc`. This is the *dynamic path*: method lookup at call time goes through a `HashMap` and a trait-object vtable.
Sources: [connectrpc/src/router.rs:114-119](), [connectrpc/src/router.rs:142-209](), [connectrpc/src/router.rs:227-301]()
### Attaching a Spec
`Router::with_spec(spec)` attaches static method metadata to the last-registered route. The generated `FooServiceExt::register` always chains this call so that `RequestContext::spec()` is populated exactly as it would be in a monomorphic `FooServiceServer`:
```rust
const SAY_SPEC: Spec = Spec::server("/eliza.v1.Eliza/Say", StreamType::Unary);
let router = Router::new()
.route_view_idempotent("eliza.v1.Eliza", "Say", handler)
.with_spec(SAY_SPEC); // attaches the Spec so handlers can read ctx.spec()
```
In debug builds, `with_spec` panics if the route is not registered or the idempotency flag disagrees with the `route` vs `route_idempotent` choice; in release builds it silently drops a mismatched spec.
Sources: [connectrpc/src/router.rs:433-483]()
### Merging routers
Multiple `Router` instances can be combined:
```rust
let all = merge_routers([service_a_router, service_b_router]);
```
`merge_routers` extends one `HashMap` with another. Per-route `Spec`s are preserved across the merge.
Sources: [connectrpc/src/router.rs:569-576]()
---
## Generated Service Traits and `FooServiceExt::register`
`connectrpc-codegen` generates two items per service:
1. **`FooService` trait** — the async trait you implement. Methods take `OwnedView>` by default (zero-copy) and return `ServiceResult + Send + use>`.
2. **`FooServiceExt` blanket impl** — its single method `register(self: Arc, router: Router) -> Router` chains all the `route_view*` + `with_spec` calls for you.
```rust
// Generated trait (simplified from the Eliza example)
pub trait ElizaService: Send + Sync + 'static {
fn say<'a>(&'a self, ctx: RequestContext, request: OwnedSayRequestView)
-> impl Future