# containerd/ttrpc-rust architecture

> Architecture diagram of the GitHub repository containerd/ttrpc-rust, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/containerd/ttrpc-rust
- Repository: https://github.com/containerd/ttrpc-rust

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build-Time Tools
    subgraph "Build-Time Tools"
        Developer[(Developer)]:::external
        Proto[".proto Files"]:::external
        Developer --> Proto
        Proto --> Protoc["protoc"]:::build
        Protoc --> PluginBin["ttrpc_rust_plugin"]:::build
        subgraph "Protoc Plugin (compiler/)"
            PluginBin
            CodegenPL["codegen.rs"]:::build
            Prost["prost_codegen.rs"]:::build
            UtilMod["util/mod.rs"]:::build
            Scope["util/scope.rs"]:::build
            Writer["util/writer.rs"]:::build
        end
        Proto --> CodegenCrate["ttrpc-codegen"]:::build
        subgraph "Standalone Codegen (ttrpc-codegen/)"
            Parser["parser.rs"]:::build
            Model["model.rs"]:::build
            Convert["convert.rs"]:::build
            StrLit["str_lit.rs"]:::build
            Lib["lib.rs"]:::build
        end
        PluginBin --> Generated["Generated Rust Code"]:::build
        CodegenCrate --> Generated
        Generated --> Cargo["cargo build"]:::build
    end

    %% Core Runtime Library
    subgraph "Core Runtime Library (src/)"
        subgraph Shared
            LibRs["lib.rs"]:::core
            Common["common.rs"]:::core
            Context["context.rs"]:::core
            Error["error.rs"]:::core
            Macros["macros.rs"]:::core
            ProtoMod["proto.rs"]:::core
        end
        subgraph "Sync Stack"
            SyncMod["mod.rs"]:::core
            SyncClient["client.rs"]:::core
            SyncServer["server.rs"]:::core
            Channel["channel.rs"]:::core
            SyncUtils["utils.rs"]:::core
            UnixNet["unix/net.rs"]:::core
            WinNet["windows/net.rs"]:::core
        end
        subgraph "Async Stack"
            AsyncMod["mod.rs"]:::core
            AsyncClient["client.rs"]:::core
            AsyncServer["server.rs"]:::core
            Connection["connection.rs"]:::core
            Stream["stream.rs"]:::core
            Shutdown["shutdown.rs"]:::core
            AsyncUtils["utils.rs"]:::core
            TransMod["transport/mod.rs"]:::core
            TrUnix["transport/unix.rs"]:::core
            TrVsock["transport/vsock.rs"]:::core
            TrWin["transport/windows.rs"]:::core
        end
    end

    %% Runtime Flow
    subgraph "Runtime Flow"
        AppCli["Client App"]:::example
        AppSrv["Server App"]:::example
        AppCli -->|"calls API"| LibRs
        AppSrv -->|"calls API"| LibRs
        LibRs -->|"uses Sync"| SyncClient
        LibRs -->|"uses Async"| AsyncClient
        SyncClient --> UnixNet
        SyncClient --> WinNet
        SyncClient --> TrVsock
        AsyncClient --> TrUnix
        AsyncClient --> TrVsock
        AsyncClient --> TrWin
        AppSrv --> SyncServer
        AppSrv --> AsyncServer
        SyncServer --> UnixNet
        AsyncServer --> TransMod
    end

    %% Examples
    subgraph Examples
        ExSyncCli["example/client.rs"]:::example
        ExSyncSrv["example/server.rs"]:::example
        ExAsyncCli["example/async-client.rs"]:::example
        ExAsyncSrv["example/async-server.rs"]:::example
        ExAsyncStrCli["example/async-stream-client.rs"]:::example
        ExAsyncStrSrv["example/async-stream-server.rs"]:::example
        BuildEx["example/build.rs"]:::example
    end

    %% Connections between build and core
    Cargo --> LibRs

    %% Click Events for Plugin
    click PluginBin "https://github.com/containerd/ttrpc-rust/blob/master/compiler/src/bin/ttrpc_rust_plugin.rs"
    click CodegenPL "https://github.com/containerd/ttrpc-rust/blob/master/compiler/src/codegen.rs"
    click Prost "https://github.com/containerd/ttrpc-rust/blob/master/compiler/src/prost_codegen.rs"
    click UtilMod "https://github.com/containerd/ttrpc-rust/blob/master/compiler/src/util/mod.rs"
    click Scope "https://github.com/containerd/ttrpc-rust/blob/master/compiler/src/util/scope.rs"
    click Writer "https://github.com/containerd/ttrpc-rust/blob/master/compiler/src/util/writer.rs"

    %% Click Events for Standalone Codegen
    click Parser "https://github.com/containerd/ttrpc-rust/blob/master/ttrpc-codegen/src/parser.rs"
    click Model "https://github.com/containerd/ttrpc-rust/blob/master/ttrpc-codegen/src/model.rs"
    click Convert "https://github.com/containerd/ttrpc-rust/blob/master/ttrpc-codegen/src/convert.rs"
    click StrLit "https://github.com/containerd/ttrpc-rust/blob/master/ttrpc-codegen/src/str_lit.rs"
    click Lib "https://github.com/containerd/ttrpc-rust/blob/master/ttrpc-codegen/src/lib.rs"

    %% Click Events for Core Runtime
    click LibRs "https://github.com/containerd/ttrpc-rust/blob/master/src/lib.rs"
    click Common "https://github.com/containerd/ttrpc-rust/blob/master/src/common.rs"
    click Context "https://github.com/containerd/ttrpc-rust/blob/master/src/context.rs"
    click Error "https://github.com/containerd/ttrpc-rust/blob/master/src/error.rs"
    click Macros "https://github.com/containerd/ttrpc-rust/blob/master/src/macros.rs"
    click ProtoMod "https://github.com/containerd/ttrpc-rust/blob/master/src/proto.rs"
    click SyncMod "https://github.com/containerd/ttrpc-rust/blob/master/src/sync/mod.rs"
    click SyncClient "https://github.com/containerd/ttrpc-rust/blob/master/src/sync/client.rs"
    click SyncServer "https://github.com/containerd/ttrpc-rust/blob/master/src/sync/server.rs"
    click Channel "https://github.com/containerd/ttrpc-rust/blob/master/src/sync/channel.rs"
    click SyncUtils "https://github.com/containerd/ttrpc-rust/blob/master/src/sync/utils.rs"
    click UnixNet "https://github.com/containerd/ttrpc-rust/blob/master/src/sync/sys/unix/net.rs"
    click WinNet "https://github.com/containerd/ttrpc-rust/blob/master/src/sync/sys/windows/net.rs"
    click AsyncMod "https://github.com/containerd/ttrpc-rust/blob/master/src/asynchronous/mod.rs"
    click AsyncClient "https://github.com/containerd/ttrpc-rust/blob/master/src/asynchronous/client.rs"
    click AsyncServer "https://github.com/containerd/ttrpc-rust/blob/master/src/asynchronous/server.rs"
    click Connection "https://github.com/containerd/ttrpc-rust/blob/master/src/asynchronous/connection.rs"
    click Stream "https://github.com/containerd/ttrpc-rust/blob/master/src/asynchronous/stream.rs"
    click Shutdown "https://github.com/containerd/ttrpc-rust/blob/master/src/asynchronous/shutdown.rs"
    click AsyncUtils "https://github.com/containerd/ttrpc-rust/blob/master/src/asynchronous/utils.rs"
    click TransMod "https://github.com/containerd/ttrpc-rust/blob/master/src/asynchronous/transport/mod.rs"
    click TrUnix "https://github.com/containerd/ttrpc-rust/blob/master/src/asynchronous/transport/unix.rs"
    click TrVsock "https://github.com/containerd/ttrpc-rust/blob/master/src/asynchronous/transport/vsock.rs"
    click TrWin "https://github.com/containerd/ttrpc-rust/blob/master/src/asynchronous/transport/windows.rs"

    %% Click Events for Examples
    click ExSyncCli "https://github.com/containerd/ttrpc-rust/blob/master/example/client.rs"
    click ExSyncSrv "https://github.com/containerd/ttrpc-rust/blob/master/example/server.rs"
    click ExAsyncCli "https://github.com/containerd/ttrpc-rust/blob/master/example/async-client.rs"
    click ExAsyncSrv "https://github.com/containerd/ttrpc-rust/blob/master/example/async-server.rs"
    click ExAsyncStrCli "https://github.com/containerd/ttrpc-rust/blob/master/example/async-stream-client.rs"
    click ExAsyncStrSrv "https://github.com/containerd/ttrpc-rust/blob/master/example/async-stream-server.rs"
    click BuildEx "https://github.com/containerd/ttrpc-rust/blob/master/example/build.rs"

    %% Styling
    classDef build fill:#D0E8FF,stroke:#069;
    classDef external fill:#F0F0F0,stroke:#999;
    classDef core fill:#E8F8E0,stroke:#2E8B57;
    classDef example fill:#FFE8C0,stroke:#E08;
```
