If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/cloudwego/volo shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3w ago
• 15 active contributors
• Distributed ownership (top contributor 42% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live cloudwego/volo repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/cloudwego/volo.

What it runs against: a local clone of cloudwego/volo — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in cloudwego/volo | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 49 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of cloudwego/volo. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/cloudwego/volo.git
#   cd volo
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of cloudwego/volo and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "cloudwego/volo(\\.git)?\\b" \\
  && ok "origin remote is cloudwego/volo" \\
  || miss "origin remote is not cloudwego/volo (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "volo/Cargo.toml" \\
  && ok "volo/Cargo.toml" \\
  || miss "missing critical file: volo/Cargo.toml"
test -f "volo-build/Cargo.toml" \\
  && ok "volo-build/Cargo.toml" \\
  || miss "missing critical file: volo-build/Cargo.toml"
test -f "volo-grpc/Cargo.toml" \\
  && ok "volo-grpc/Cargo.toml" \\
  || miss "missing critical file: volo-grpc/Cargo.toml"
test -f "volo-thrift/Cargo.toml" \\
  && ok "volo-thrift/Cargo.toml" \\
  || miss "missing critical file: volo-thrift/Cargo.toml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 49 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~19d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/cloudwego/volo"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Volo is a high-performance async Rust RPC framework for building microservices with support for Thrift, gRPC, and HTTP protocols. It leverages Async Function in Traits (AFIT) and Return Position Impl Trait in Trait (RPITIT) to eliminate boxing overhead, powered by the Motore middleware abstraction layer. Monorepo using Cargo workspaces with 7 member crates: volo/ (core framework), volo-thrift/, volo-grpc/, volo-http/ (protocol implementations), volo-build/ and volo-cli/ (code generation and tooling), volo-macros/ (proc-macros). Examples in examples/ and benchmarks in benchmark/src/bin/ (client.rs, server.rs) with performance measurement in benchmark/src/perf/.

Rust microservice developers and infrastructure engineers at companies like ByteDance (Cloudwego) who need low-latency, low-memory RPC communication between services and want strong extensibility through middleware composition without the performance penalty of traditional trait object boxing.

Actively developed and production-ready. The repo shows consistent maintenance with workspace configuration for 7+ crates, comprehensive CI/CD in .github/workflows/ci.yaml, benchmark suite in benchmark/ directory, and appears to be backed by a major organization (Cloudwego/ByteDance). Rust version requirement is 1.85.0, indicating modern language feature adoption.

Moderate complexity risk: the framework depends heavily on cutting-edge Rust features (AFIT/RPITIT) which only stabilized in Rust 1.75+, creating potential breakage if those features change. The reliance on Pilota 0.13 for code generation and lack of visible alternative implementations means betting on that ecosystem. However, GitHub CI presence and structured issues template suggest active maintenance.

The repo maintains active CI workflows (see .github/workflows/ci.yaml) with dependency review automation. CHANGELOG.md and ROADMAP.md exist but specific recent commits aren't visible in provided data. The presence of benchmark infrastructure and multiple protocol implementations suggests ongoing optimization and feature expansion work.

git clone https://github.com/cloudwego/volo.git
cd volo
cargo build
cargo test

For CLI scaffolding: install volo-cli crate, then use volo new to bootstrap a project.

Daily commands: From workspace root: cargo run --bin client -p volo-thrift-example (adjust package name based on desired protocol). For benchmarks: cd benchmark && bash scripts/bench.sh. For development: cargo build compiles all crates, cargo test runs test suite.

• Cargo.toml — Workspace root configuration defining all member crates (volo, volo-build, volo-grpc, volo-http, volo-thrift) and shared dependencies; essential for understanding the project structure and dependency management.
• volo/Cargo.toml — Core framework crate definition; all RPC applications depend on this as the primary entry point for the Volo runtime and middleware system.
• volo-build/Cargo.toml — Code generation framework; responsible for compiling IDL (Thrift/gRPC) into Rust types and service stubs used by all generated code.
• volo-grpc/Cargo.toml — gRPC protocol implementation; defines how the framework handles gRPC-specific concerns (HTTP/2, protobuf serialization, streaming).
• volo-thrift/Cargo.toml — Thrift protocol implementation; defines how the framework handles Thrift-specific concerns (binary protocol, RPC semantics).
• volo-macros/Cargo.toml — Procedural macros for service and middleware definition (#[service], #[layer]); enables ergonomic API design across the framework.
• volo-http/Cargo.toml — HTTP/1.1 protocol support; provides web and REST capabilities alongside gRPC and Thrift RPC protocols.

Add a New gRPC Service

1. Create a .proto file defining your service in examples/proto/ (e.g., examples/proto/myservice.proto) with message and rpc definitions (examples/proto/helloworld.proto)
2. Run volo CLI to generate Rust code: volo init --idl examples/proto/myservice.proto. Generated code includes MyService trait in volo-gen/src/ (volo-cli/Cargo.toml)
3. Implement the MyService trait in a new examples/src/grpc/myservice/ directory with server and client binaries, following the pattern in examples/src/grpc/hello/server.rs (examples/src/grpc/hello/server.rs)
4. Use #[volo::main] macro and inject middleware via #[layer(...)] attributes to add logging, tracing, or timeout handling (volo-macros/Cargo.toml)

Add a Custom Middleware Layer

1. Create a new struct implementing the Layer trait from volo-core, parametrized on the inner Service type (volo/Cargo.toml)
2. Implement the Service trait on your layer's output type, wrapping the inner service call to intercept request/response (volo/Cargo.toml)
3. Derive or implement Clone and use it in a #[layer(YourMiddleware)] attribute on your service handler to inject into the middleware stack (volo-macros/Cargo.toml)

Add Support for a New Protocol

1. Create a new crate under the workspace (e.g., volo-myprotocol/Cargo.toml) depending on volo and motore for async transport (Cargo.toml)
2. Implement codec traits for serialization/deserialization of requests and responses following the pattern in volo-thrift or volo-grpc (volo-grpc/Cargo.toml)
3. Add a transport connector and connection pool implementing Dial and Connection traits, and register in the client builder (volo-http/Cargo.toml)
4. Implement a server listener to accept and decode incoming connections, and integrate via the #[volo::main] runtime bootstrap (volo-macros/Cargo.toml)

Add Distributed Tracing Integration

1. Depend on a tracing crate (e.g., opentelemetry, jaeger) in your service's Cargo.toml alongside metainfo for context propagation (Cargo.toml)
2. Create a custom middleware layer that wraps each service call to extract and propagate trace context using metainfo::Metainfo (volo/Cargo.toml)
3. In the middleware, emit span creation and event recording before/after the inner service call, and serialize trace IDs into outbound RPC headers (volo-macros/Cargo.toml)

• Rust + async/await (Tokio) — Memory safety and zero-cost abstractions enable high throughput and low latency without garbage collection; async foundation built on industry-standard Tokio runtime
• Thrift + Protocol Buffers (protobuf) — Language-agnostic IDL specifications enable cross-language microservice ecosystems; both serialization formats offer compact binary encoding for low bandwidth
• Procedural macros (#[service], #[layer]) — Compile-time code generation reduces runtime reflection overhead and enables type-safe middleware composition with zero-cost abstractions
• motore (async trait abstractions) — Provides Layer/Service trait pattern from tower ecosystem, standardizing middleware composition and enabling ecosystem interoperability
• pilota (Thrift/protobuf parsing & code generation) — Pure Rust implementation avoids external IDL compiler dependencies, enabling seamless integration into Volo's build pipeline

• Macro-based API (#[service], #[layer], #[volo::main])

  • Why: Eliminates boilerplate and enables declarative middleware injection, improving developer experience
  • Consequence: Requires understanding of procedural macros and generated code structure; adds compile-time overhead during macro expansion

• Support for multiple protocols (gRPC, Thrift, HTTP) in one framework

  • Why: Enables gradual migration and multi-protocol deployments in large organizations
  • Consequence: Increased codebase complexity; protocol-specific handlers must coexist and share core abstractions

• Middleware as explicit Layer trait implementations

  • Why: Type-safe composition and zero-cost abstractions; middleware order is compile-time deterministic
  • Consequence: Middleware order is fixed at compile time; requires code recompilation to reorder middleware

• Async-only runtime (no blocking sync API)

  • Why: Simplifies executor integration and prevents deadlock from blocking calls inside async code
  • Consequence: Not suitable for CPU-bound workloads or legacy blocking libraries without .block_on() wrapper

• Does not provide distributed consensus (e.g., service mesh control plane, distributed transactions)
• Does not include built-in authentication/authorization; delegates to middleware and IDL annotations
• Does not handle persistent message queuing; focuses on request-response RPC patterns
• Not designed for embedded systems or no_std environments (requires std and async runtime)
• Does not provide schema validation or API gateway features; these are expected to be external components

1. Rust version constraint: Minimum 1.85.0 required for AFIT/RPITIT features; older stable toolchains will fail immediately. 2. Pilota version lock: All crates inherit workspace dependency on Pilota 0.13; mismatched versions between volo-build and codegen can cause silent type mismatches. 3. Code generation timing: volo-build is a build dependency; ensure build.rs in your project calls it before compilation. 4. Async runtime: Framework is async-only (no sync API); requires Tokio or compatible executor. 5. Feature flags: Some crates like volo-http may have optional features (compression, middleware) not enabled by default; check Cargo features.

• Async Function in Traits (AFIT) — Core language feature (stabilized Rust 1.75) that Volo relies on to write async trait methods without boxing; essential to understanding why Volo is faster than async-trait-based competitors.
• Return Position Impl Trait in Trait (RPITIT) — Complementary language feature allowing trait methods to return impl Future instead of boxed trait objects; Volo uses this for zero-allocation middleware composition.
• Middleware Tower Pattern (Motore) — Volo's extensibility model via the Motore 0.4.1 crate; understanding Service/Layer traits is mandatory for writing custom middleware (logging, auth, metrics).
• Thrift Code Generation (Pilota) — Volo-thrift relies entirely on Pilota for parsing .thrift files and generating Rust code; understanding Pilota's output is critical for debugging generated RPC stubs.
• gRPC over HTTP/2 (h2) — Volo-grpc uses the h2 0.4 crate for HTTP/2 multiplexing; understanding H2 flow control and stream management is needed for production gRPC deployments at scale.
• Workspace Dependency Resolution — Volo is a 7-crate monorepo using Cargo workspace with resolver = '3'; understanding how workspace members inherit versions (e.g., all use Pilota 0.13) prevents version mismatch bugs.
• Proc-Macro Code Generation — Volo-macros provides derive macros for RPC trait definitions; understanding how proc-macros parse and generate code is essential for extending the framework with new decorators.

• cloudwego/kitex — Go RPC framework by same team (Cloudwego); Volo is the Rust equivalent with similar middleware-first philosophy but using AFIT instead of interfaces.
• tokio-rs/tokio — Async runtime that Volo depends on; understanding Tokio's task spawning and executor is critical for production Volo deployments.
• pilota-rs/pilota — Thrift/Protobuf code generation engine used by volo-build; Volo's IDL parsing and code generation is entirely built on Pilota.
• hyperium/hyper — HTTP client/server library underpinning volo-http and volo-grpc; understanding Hyper's service trait is essential for gRPC middleware.
• async-rs/async-trait — Earlier approach to async traits using boxed futures; Volo replaced this with AFIT to eliminate the allocation overhead that motivated the framework's creation.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for volo-http middleware chain

The repo has examples/src/grpc/* but lacks documented integration tests for the volo-http middleware system. Given that volo-http is a core workspace member, adding tests that verify middleware ordering, error handling, and request/response transformation would improve reliability and serve as documentation for users building HTTP services.

• [ ] Create tests/http-middleware/ directory mirroring the workspace structure
• [ ] Write tests covering middleware chain execution order in volo-http
• [ ] Add tests for error propagation through middleware layers
• [ ] Test integration between volo-http and volo-macros middleware attributes
• [ ] Add test documentation in tests/http-middleware/README.md explaining middleware patterns

Add missing DNS resolution integration tests for gRPC

examples/src/grpc/dns/ exists but there's no corresponding test in tests/code-generation/ or a dedicated gRPC DNS test directory. This is a critical feature for production microservices. Tests should verify DNS resolution behavior, failover, and integration with hickory-resolver (already in workspace.dependencies).

• [ ] Create tests/grpc-dns/ directory with integration tests
• [ ] Test DNS A record resolution with multiple addresses
• [ ] Test DNS SRV record handling for service discovery
• [ ] Verify fallback behavior when DNS resolution fails
• [ ] Test integration with volo-grpc client connection pooling
• [ ] Document DNS configuration in docs/grpc-dns.md

Add CI workflow for dependency security and audit

The repo has .github/workflows/dependency-review.yaml but lacks a complementary cargo audit or cargo deny workflow to catch security vulnerabilities in transitive dependencies. This is critical for a framework used in production microservices. The workflow should block PRs with high-severity issues.

• [ ] Create .github/workflows/security-audit.yaml workflow
• [ ] Add cargo-audit or cargo-deny checks for all workspace members
• [ ] Configure the workflow to fail on high/critical severity findings
• [ ] Add deny.toml or audit configuration at repo root
• [ ] Document security policy in SECURITY.md with workflow details
• [ ] Ensure workflow runs on: pull_request, push to main, and scheduled daily

• Add integration tests for volo-http in tests/code-generation/ mirroring the Thrift/gRPC test structure; currently only volo-thrift has comprehensive generated-code tests.: medium: Improves confidence in HTTP implementation correctness
• Document the Motore middleware trait contract in volo/src/ with inline examples showing how to write a custom middleware (e.g., custom logging, tracing).: low: Lowers barrier for framework extensibility
• Add benchmarks for code generation speed in benchmark/src/ comparing Pilota parsing time across different .thrift file sizes; currently only runtime performance is measured.: medium: Identifies codegen bottlenecks for large IDL schemas

The Volo RPC framework codebase demonstrates generally good security practices with a formal SECURITY.md policy and responsible disclosure procedures. However, there are several areas for improvement: (1) a critical configuration error with an invalid Rust edition specification that prevents compilation, (2) test TLS certificates stored in the repository that could establish poor practices, (3) lack of automated dependency vulnerability scanning in the CI/CD pipeline, and (4) careful review needed for security-sensitive library choices. The project uses well-maintained dependencies and follows Rust best practices. Primary recommendations: fix the edition configuration, integrate cargo-audit/cargo-deny into CI/CD, and ensure test certificates are clearly marked as non-production.

• Medium · Rust Edition Configuration Error — Cargo.toml - workspace.package.edition. The Cargo.toml specifies edition = "2024", which is invalid. The latest stable Rust edition is 2021. This will cause compilation failures and indicates a configuration error that may have been introduced accidentally. Fix: Change edition to "2021" (the latest stable edition) or verify the intended Rust version compatibility with the specified rust-version = "1.85.0"
• Low · Cryptographic Library Without Recent Audit History — Cargo.toml - ahash = "0.8". The codebase uses 'ahash' (0.8) for hashing. While not a cryptographic hash function, ahash is used for fast non-cryptographic hashing. For security-sensitive operations, this may be insufficient without explicit code review. Fix: Verify that ahash is not used for security-critical operations like HMAC or digital signatures. Use cryptographically secure hashing (e.g., sha2, blake3) for security-sensitive contexts.
• Low · TLS Certificate Files in Repository — examples/data/tls/ (ca.pem, server.key, server.pem). Test/example TLS certificates and keys are stored in the repository at examples/data/tls/. While these appear to be example certificates, storing certificate material in version control can set a bad precedent. Fix: Ensure these are clearly marked as test/example-only certificates. Consider moving to a secure location outside the repository for production. Add a README clarifying these are not for production use.
• Low · HTTP/2 Implementation via Dependency — Cargo.toml - h2 = "0.4". The codebase uses 'h2' (0.4) for HTTP/2 support. While h2 is a well-maintained crate, any HTTP/2 implementation should be kept up-to-date to address potential protocol-level vulnerabilities. Fix: Regularly update h2 and monitor for security advisories. Consider using cargo-audit in CI/CD pipeline.
• Low · Missing Dependency Security Scanning — .github/workflows/. While a dependency-review.yaml workflow exists in .github/workflows/, there is no evidence of cargo-audit or cargo-deny integration for automated vulnerability scanning of Rust dependencies. Fix: Add cargo-audit or cargo-deny to the CI pipeline to automatically detect known vulnerabilities in dependencies. This should fail the build if vulnerabilities are found.
• Low · Git Dependency with Default Features — Cargo.toml - git2 = { version = "0.20", default-features = false }. The 'git2' crate is included with default-features = false, but this should be reviewed to ensure libgit2 security patches are applied. The crate is used in build tools. Fix: Review why default features are disabled. Ensure that this doesn't exclude important security patches. Monitor git2 updates closely.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.