How containerd/ttrpc-rust works
Project Type and Purpose
• Project Type: An open-source Rust library and code-generation tool (ttrpc-codegen plugin + runtime crate)
• Purpose:
– Provide a Rust implementation of ttrpc (a lightweight RPC akin to gRPC)
– Offer a protoc plugin (ttrpc_rust_plugin) and programmatic API (protoc_rust_ttrpc::Codegen) to generate Rust code from .proto files
– Supply both sync and async/.await client/server runtimes with pluggable transports (Unix socket, Windows named pipes, vsock)
File Structure
Top-level crates:
– Root crate (Cargo.toml, src/…): core runtime library
– compiler/: protoc plugin source (ttrpc_rust_plugin)
– ttrpc-codegen/: standalone code-generation library with its own parser/model/codegen
– example/: usage demos (sync + async clients and servers)
Key directories within core library (src/):
– asynchronous/: async client/server/stream modules + transports
– sync/: synchronous counterparts + OS-specific net implementations
– Common modules: context.rs, error.rs, common.rs, macros.rs, proto.rs
Build/deploy:
– build.rs, Makefile, GitHub Actions workflows for sanity/BVT tests
Extract README Insights
• Two generation modes:
1. protoc invocation with plugin
2. Programmatic via protoc_rust_ttrpc::Codegen builder
• Async support via ttrpc-codegen with customization flags
• Examples drive home client/server implementations
Main Components (to include
A. User/Developer
– Writes .proto definitions
– Chooses protoc + plugin or Codegen API
B. Build-Time Codegen
1. protoc CLI
• Invokes --plugin=protoc-gen-ttrpc
2. ttrpc_rust_plugin (compiler/)
• Uses prost_codegen.rs, codegen.rs, util modules
• Emits .rs service stubs + message types
3. ttrpc-codegen crate (optional)
• Parser → Model → Convert → Codegen
• Generates async/.await compatible Rust code
C. Core Runtime Library (root src/)
1. Sync Stack
• sync/client.rs, sync/server.rs
• OS transports: Unix, Windows, Vsock
2. Async Stack
• asynchronous/client.rs, asynchronous/server.rs
• Uses Tokio/Futures (async/.await)
3. Shared
• Context, error handling, macros, protocol definitions
D. Examples
– Sync: example/client.rs, example/server.rs
– Async: example/async-client.rs, example/async-server.rs
– Build scripts illustrate programmatic generation (example/build.rs)
E. External Dependencies
– Protobuf compiler (protoc)
– rust-protobuf (protobuf-codegen)
– Containerd’s ttrpc spec
Relationships and Data Flow
Developer → .proto files → protoc + ttrpc_rust_plugin/ttrpc-codegen → generated Rust code
Generated code + core runtime ← cargo build
• Runtime Flow (right side)
Application (client/server) ↔ ttrpc library APIs ↔ Transport layer (Unix socket, Vsock, Win pipe)
Client ↔ Server message exchange over chosen transport
Architectural Patterns / Design Principles
• Plugin architecture for protoc integration
• Builder pattern (Codegen::new()…run()) for programmatic use
• Dual-stack abstraction: sync vs. async implementations
• Layered transport abstraction (OS-specific modules under sync/sys and asynchronous/transport)
Essential Details to Capture
• Distinct build-time vs. runtime paths
• Separation of sync and async stacks
• Plugin (compiler/) and standalone codegen (ttrpc-codegen/) as separate code emitters
• Transport abstractions per platform