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/stepancheg/rust-protobuf 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 all four use cases

• Last commit 8mo ago
• 19 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 8mo ago
• ⚠ Concentrated ownership — top contributor handles 67% of recent commits

_{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 stepancheg/rust-protobuf repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/stepancheg/rust-protobuf.

What it runs against: a local clone of stepancheg/rust-protobuf — 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 stepancheg/rust-protobuf | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 258 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of stepancheg/rust-protobuf. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/stepancheg/rust-protobuf.git
#   cd rust-protobuf
#
# 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 stepancheg/rust-protobuf and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "protobuf/Cargo.toml" \\
  && ok "protobuf/Cargo.toml" \\
  || miss "missing critical file: protobuf/Cargo.toml"
test -f "protobuf-codegen/Cargo.toml" \\
  && ok "protobuf-codegen/Cargo.toml" \\
  || miss "missing critical file: protobuf-codegen/Cargo.toml"
test -f "protobuf-parse/Cargo.toml" \\
  && ok "protobuf-parse/Cargo.toml" \\
  || miss "missing critical file: protobuf-parse/Cargo.toml"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 258 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~228d)"
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/stepancheg/rust-protobuf"
  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).

rust-protobuf is a pure-Rust implementation of Google Protocol Buffers that generates Rust code from .proto files and provides runtime serialization/deserialization support. It implements both Protobuf 2 and 3 specs with features like runtime reflection, JSON/text format parsing, and dynamic message creation without code generation. Monorepo structure with core packages: protobuf/ (runtime library), protobuf-codegen/ (code generator), protobuf-parse/ (parser), protobuf-json-mapping/ (JSON support), and protobuf-support/ (utilities). Separate test-crates/ directory contains integration tests (protobuf-codegen-pure-test, protobuf-test, etc.), examples/ demonstrate use cases, and ci-gen/ manages GitHub Actions workflow generation.

Rust developers building distributed systems, microservices, or applications requiring efficient message serialization; maintainers of Rust projects using Protocol Buffers for data interchange with other services or languages.

This project is in end-of-life / legacy status. The README explicitly warns that version 3 is approaching end of life, with the official Protobuf team developing a new Rust implementation (protobuf=4) in the main protobuf repository. Version 3 had stable releases, but maintenance is winding down; only critical fixes are being applied to the v2.x branch.

High maintenance risk: Single maintainer (stepancheg) with explicitly stated need for a new maintainer. The project is being superseded by the official protobuf Rust implementation. Breaking changes occurred between v2 and v3 (see CHANGELOG-before-3.md). While tested (ci-gen, test-crates/ present), relying on this for new projects is not recommended—migration path to official protobuf implementation should be planned.

Active maintenance has stalled. The README and CHANGELOG indicate the project is winding down, with focus shifted to the official Protobuf Rust implementation. No major feature work is visible; primarily bug fixes and stability maintenance occur. The ci-gen tool manages CI configuration, suggesting some internal build infrastructure work, but community contributions appear minimal.

git clone https://github.com/stepancheg/rust-protobuf.git
cd rust-protobuf
cargo build
cargo test

Requires Rust toolchain and protoc installed (install-protobuf.sh in ci/ directory provides guidance). Use cargo doc --open to read generated documentation locally.

Daily commands: Development workflow uses standard Cargo: cargo build builds all crates, cargo test runs unit + integration tests across workspace members, cargo test --test '*' runs specific test suites. Run examples with cargo run -p protobuf-examples/customize-serde. Protoc code generation demonstrated in test-crates/protobuf-codegen-protoc-test/.

• Cargo.toml — Workspace root configuration defining all member crates and shared dependencies; essential to understand project structure and versioning strategy
• protobuf/Cargo.toml — Core protobuf runtime library configuration; the primary public API that end-users depend on
• protobuf-codegen/Cargo.toml — Code generation engine that drives the protoc compiler plugin; critical for understanding how .proto files become Rust code
• protobuf-parse/Cargo.toml — Parser for protocol buffer files (.proto); foundational layer that all code generation depends on
• README.md — Project documentation noting end-of-life status and official protobuf=4 successor; essential context for contributors on project direction
• CONTRIBUTING.md — Contribution guidelines and development workflow; mandatory reading for pull request submissions
• .github/workflows/ci.yml — CI/CD pipeline definition; shows build, test, and deployment automation that must pass for all changes

Add Support for a New Protobuf Field Type

1. Update the parser to recognize the new type syntax in .proto files (protobuf-parse/src/lib.rs)
2. Add code generation logic to emit Rust struct fields for the new type (protobuf-codegen/src/lib.rs)
3. Implement serialization/deserialization logic in the runtime (protobuf/src/lib.rs)
4. Add test cases covering encoding, decoding, and edge cases (test-crates/protobuf-test/src/lib.rs)

Create a New Example Demonstrating Feature Usage

1. Create new example directory under protobuf-examples/ (protobuf-examples/new-feature/)
2. Write Cargo.toml with dependencies on protobuf and protobuf-codegen (protobuf-examples/new-feature/Cargo.toml)
3. Add .proto file demonstrating the feature (protobuf-examples/new-feature/src/example.proto)
4. Implement Rust code showing feature usage with generated types (protobuf-examples/new-feature/src/main.rs)
5. Add example to workspace members in root Cargo.toml (Cargo.toml)

Add a Conformance Test for Protocol Buffer Compliance

1. Add new .proto definition to google-protobuf-all-protos/ (google-protobuf-all-protos/protobuf/protobuf-git/conformance/conformance.proto)
2. Create test case in test-crates/protobuf-codegen-protoc-test/ (test-crates/protobuf-codegen-protoc-test/src/lib.rs)
3. Run code generation via protoc plugin to verify no errors (test-crates/protobuf-codegen-protoc-test/build.rs)
4. Add assertion logic to validate serialization matches expected output (test-crates/protobuf-test-common/src/lib.rs)

Implement a Custom Serialization Format Integration

1. Create new example crate under protobuf-examples/ (protobuf-examples/custom-format/Cargo.toml)
2. Define wrapper traits for encoding/decoding custom formats (protobuf-examples/custom-format/src/lib.rs)
3. Implement trait for generated message types or use serde bridge (protobuf-examples/custom-format/src/impl.rs)
4. Add tests validating round-trip serialization (protobuf-examples/custom-format/src/tests.rs)

• Rust — Memory-safe systems language with zero-cost abstractions; ideal for performant serialization without garbage collection
• Protocol Buffers (proto3/proto2) — Language-agnostic wire format with proven compatibility across 20+ languages; enables interoperability with C++, Java, Python implementations
• Cargo workspace — Monorepo structure allows tight coupling of parser, codegen, runtime, and tests while maintaining independent versioning for public crates
• protoc plugin architecture — Allows rust-protobuf to integrate seamlessly with official protobuf compiler; enables gradual adoption alongside existing build tooling

• Separate protobuf-parse and protobuf-codegen into distinct crates

  • Why: Codegen is a build-time dependency; parsing is only needed at compilation. Separation reduces runtime binary size and dependency tree.
  • Consequence: Developers must add both crates to build.rs; introduces slight complexity in build scripts

• End-of-life status with official protobuf=4 on horizon

  • Why: Official Rust implementation in protobuf repository is canonical and receives priority; rust-protobuf maintenance reduced
  • Consequence: New projects should prefer official protobuf=4; existing projects must plan migration. No breaking changes without strong justification.

• Zero-copy wire encoding (varint, fixed32/64)

  • Why: Maximizes performance for network and storage use cases; minimal allocations
  • Consequence: No built-in compression; custom middleware required for bandwidth-constrained scenarios

• Support both proto2 and proto3 syntax in single codebase

  • Why: Enterprise users require proto2 (groups, required fields); proto3 is simpler. Single implementation reduces bugs.
  • Consequence: Added code complexity for syntax variations; conditional codegen paths increase test matrix

• Does not provide real-time streaming (gRPC is separate project/dependency)
• Does not implement schema evolution/migration tooling (manual compatibility verification required)
• Does not support custom protobuf options code generation (custom options parsed but ignored)
• Does not include official Google proto definitions (google-protobuf-all-protos is reference only; must manage separately)
• Not compatible with async/await integration beyond what external crates provide

1. Protoc vendoring: protoc-bin-vendored=3.1.0 is pinned—updating requires careful testing against all test crates. 2. End-of-life status: New code should target the official protobuf Rust implementation instead; this repo actively directs users there. 3. Proto2 vs Proto3 divergence: Code paths differ significantly; test both syntax versions (benchmark datasets in google-protobuf-all-protos/ contain both proto2/ and proto3/ examples). 4. Generated code stability: Changes to codegen affect many test crates—validate via test-crates/protobuf-codegen-identical-test/ which checks generated output is byte-identical. 5. No C++ FFI: Unlike some alternatives, this is pure Rust—no linking issues but also no native code fallback.

• Protocol Buffers wire format — Core to understanding how rust-protobuf serializes/deserializes—variable-length encoding, varint, zigzag encoding, and field tags are in CodedInputStream/CodedOutputStream implementation
• Runtime reflection — Version 3 feature enabling dynamic message inspection without code generation—critical for implementing generic serialization, validation, or message introspection tools
• Code generation via procedural macros vs external tool — rust-protobuf uses external protoc tool + custom codegen (not procedural macros)—understanding this distinction affects how build.rs scripts invoke protobuf-codegen and when code is generated
• Proto2 vs Proto3 syntax differences — rust-protobuf supports both versions with different semantics (required fields in proto2, default values, field presence tracking)—test cases and generated code differ significantly between versions
• Text format and JSON mapping round-tripping — protobuf-json-mapping/ enables human-readable serialization—essential for debugging, APIs, and interoperability; requires faithful preservation of field ordering and type information
• nom parser combinator library — protobuf-parse/ uses nom for parsing .proto files—understanding combinator-based parsing helps troubleshoot parser bugs and extends proto syntax support

• tokio-rs/prost — Active Rust protobuf alternative with stronger maintenance; recommended replacement for new projects, also includes gRPC implementation
• tafia/quick-protobuf — Lightweight Rust protobuf implementation focused on performance; simpler API surface but less feature-complete than rust-protobuf
• protocolbuffers/protobuf — Official Google protobuf repository—contains the new official Rust implementation that will supersede rust-protobuf; this repo explicitly directs users there
• pingcap/grpc-rs — gRPC implementation for Rust; many rust-protobuf users need gRPC support and should consider prost+tonic stack instead
• stepancheg/grpc-rust — Author's incomplete gRPC implementation built on top of rust-protobuf; demonstrates use case but similarly abandoned

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 conformance test suite integration for proto3 compliance validation

The repository contains Google's conformance test suite proto definitions (google-protobuf-all-protos/protobuf/protobuf-git/conformance/conformance.proto) but lacks a Rust implementation of the conformance test runner. This would ensure rust-protobuf correctly implements proto3 specification, similar to official protobuf implementations, and is critical before the announced end-of-life transition to protobuf=4.

• [ ] Create new test crate test-crates/protobuf-conformance-test/ with Cargo.toml
• [ ] Implement conformance test runner in test-crates/protobuf-conformance-test/src/main.rs that parses ConformanceRequest/ConformanceResponse from google-protobuf-all-protos/protobuf/protobuf-git/conformance/conformance.proto
• [ ] Add GitHub Actions workflow in .github/workflows/conformance.yml to run conformance tests against current Rust implementation
• [ ] Document conformance test results in doc/conformance.md

Create benchmark comparison suite for protobuf vs prost vs alternative serialization formats

The repository has example crates showing prost comparison (protobuf-examples/vs-prost/) and benchmark proto files (google-protobuf-all-protos/protobuf/protobuf-git/benchmarks/), but lacks an integrated benchmark harness. This would help contributors and users understand performance characteristics across serialization libraries using Google's own benchmark message definitions.

• [ ] Create test-crates/protobuf-benchmark-suite/src/lib.rs with benchmark message generators using benchmark proto definitions from google-protobuf-all-protos/protobuf/protobuf-git/benchmarks/
• [ ] Add Criterion.rs-based benchmarks in test-crates/protobuf-benchmark-suite/benches/ comparing serialization/deserialization across protobuf, prost, and bincode
• [ ] Add GitHub Actions workflow in .github/workflows/benchmarks.yml to track performance regressions
• [ ] Document results in doc/benchmarks.md with comparison tables

Complete API documentation coverage for protobuf-codegen and protobuf-parse crates with examples

The workspace contains codegen and parsing crates (protobuf-codegen/, protobuf-parse/) that lack comprehensive rustdoc comments and inline usage examples. These are critical for users implementing custom code generation. The example crates (protobuf-examples/customize-serde/, protobuf-examples/dynamic/) only partially demonstrate the API.

• [ ] Add //! module-level documentation to protobuf-codegen/src/lib.rs with a full example showing how to programmatically invoke code generation
• [ ] Add //! module-level documentation to protobuf-parse/src/lib.rs with parsing workflow example
• [ ] Add /// doc comments with examples to public APIs in protobuf-codegen/src/codegen.rs and protobuf-parse/src/parser.rs
• [ ] Create new example crate protobuf-examples/custom-codegen/ demonstrating custom code generator implementation using the public API

• Add missing documentation examples for protobuf-json-mapping—the JSON serialization feature is mentioned in CHANGELOG but has minimal usage examples in doc/ directory; create simple examples showing JSON roundtrip serialization.
• Enhance error messages in protobuf-parse/src/—many parse errors likely report generic 'parse failed' without context; improve error types to include line/column numbers and suggest fixes for common mistakes (missing semicolons, typos in type names).
• Extend test coverage for proto2-specific features in test-crates/—google-protobuf-all-protos/protobuf-git/benchmarks contains proto2 benchmark messages (benchmark_message1_proto2.proto) but corresponding tests may be missing; add comprehensive proto2 serialization tests.

The rust-protobuf codebase shows reasonable security practices with no obvious injection vulnerabilities, hardcoded secrets, or misconfigurations detected in the visible file structure. However, the project's end-of-life status is the primary security concern, as it suggests reduced maintenance and potentially delayed security patches. Dependency management is generally sound with pinned versions, though this may prevent automatic patch updates. The large vendored protobuf repository increases maintenance overhead. Users should monitor this project's status and be prepared to migrate to the official protobuf implementation when available.

• Medium · End of Life Project with Limited Security Support — README.md. The README explicitly states this implementation is 'approaching end of life' with an official protobuf implementation planned as protobuf=4. This indicates the project may not receive timely security updates or patches for vulnerabilities discovered in the future. Fix: Consider migrating to the official protobuf implementation (protobuf=4) when available. If continuing to use this crate, implement additional security monitoring and dependency auditing practices.
• Low · Pinned Transitive Dependency Version — Cargo.toml (workspace.dependencies). The workspace dependency specifies 'protoc-bin-vendored = "=3.1.0"' with an exact version pin. While this ensures reproducibility, it may prevent receiving security patches if a newer patch version is released (e.g., 3.1.1). Fix: Consider using '^3.1.0' or '~3.1.0' version specifiers to allow patch-level security updates while maintaining stability. Regularly audit and update this dependency.
• Low · Large Vendored Protobuf Repository — google-protobuf-all-protos/. The repository includes a complete vendored copy of Google's protobuf repository in 'google-protobuf-all-protos/protobuf/protobuf-git/'. This increases the attack surface and maintenance burden, as security updates to protobuf definitions must be manually synchronized. Fix: Document the vendoring strategy and establish a process for regularly updating vendored protobuf definitions. Consider whether this extensive vendoring is necessary or if git submodules/external dependencies would be better.

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.