buffa-test-fixtures: minimal #[derive(Message)] for tests and doc examples

[iainmcgin]

Motivation

While spiking a buffa port for axum-extra's protobuf extractor, the main ergonomics gap relative to prost was the lack of an inline #[derive] for test and example code. prost users write:

#[derive(prost::Message)]
struct Input {
    #[prost(string, tag = "1")]
    foo: String,
}

directly inside #[cfg(test)] modules and doc examples. buffa is codegen-only, so the equivalent today is either:

• pull in buffa-types and use a well-known type (StringValue, Int32Value) as a stand-in fixture, or
• add a build.rs + .proto file just for tests.

The first works but reads oddly in docs ("where MyMessage is a type generated by protoc-gen-buffa…"); the second is heavyweight for a downstream crate that only wants one tiny test message.

This will recur on every downstream port (prometheus-client, pprof, libp2p-identity, etc.) — each has prost-derive test fixtures that need a buffa equivalent.

Proposal

A buffa-test-fixtures crate (or buffa-derive, name TBD) that provides a #[derive(buffa::Message)] proc-macro covering the minimal field set needed for tests and examples:

• scalar fields (string, int32, int64, uint32, uint64, bool, bytes)
• optional / repeated
• nested messages
• explicit tag = N

Explicitly out of scope (to keep it from becoming a parallel production codegen path): maps, oneofs, enums, groups, extensions, editions feature resolution, view types, reflection, JSON/textproto. If a test needs those, it should use real codegen.

Positioning

The crate docs and README should be unambiguous that this is for tests and examples only — protoc-gen-buffa / buffa-build remain the supported path for production schemas. Something along the lines of:

This derive exists so downstream crates can write self-contained tests and doc examples without a build.rs. It supports a deliberately small subset of protobuf. For application code, generate types from .proto files.

A #[doc(hidden)] re-export from the main buffa crate behind a derive feature would let examples write #[derive(buffa::Message)] without a second dependency line, but that may invite production use — open to leaving it as a separate explicit dep instead.

Prior art

• prost's prost-derive (the thing we're matching ergonomically)
• serde's split between serde and serde_derive

[iainmcgin]

[claude code]

Adding the design rationale for why this stays test-only, so it's recorded in one place we can point to when (not if) someone asks for a production derive.

Why no production #[derive(Message)]

.proto is the portable source of truth. Protobuf's value is that the schema is language-neutral and tooling-rich — protoc, buf lint/breaking-change detection, schema registries, cross-language codegen. A derive inverts that: the Rust struct becomes the source of truth, and the wire schema is implicit in annotations scattered across it. That's fine for a Rust-only, both-ends-controlled format, but it's the wrong default for protobuf, where the consumer on the other end is often not Rust.

A reliable derive recreates .proto syntax with worse tooling. To get a stable wire encoding from a Rust struct you need explicit field numbers (#[buffa(tag = 3)]), explicit wire-type selection where Rust types are ambiguous (i32 → int32/sint32/sfixed32?), presence annotations, packed-vs-expanded for repeated fields, and enforcement of protobuf invariants (no u8/u16/usize, no tuples, no fixed arrays as fields, oneof must be a flat enum, recursive messages must be boxed). By the time the annotations are complete enough to be reliable, you've written a .proto file in attribute syntax — without protoc's validation, without buf's breaking-change detection, and without anything another language can consume.

The use cases that look like they want it are already served:

• "Encode my own struct without a populate/conversion step" → extern_path plus the custom-type knobs (string_type_custom, box_type_custom, etc.) let codegen emit your type's name and attach the impls to it. The .proto stays canonical and you skip the conversion.
• "Rust on both ends, just want a fast tagged binary format" → that's bilrost or postcard's job. A buffa derive would be a strictly worse bilrost — same annotations, slower wire format, none of the cross-language benefit that justifies protobuf's overhead.
• "Self-contained test/doc fixture" → this issue.

One addition to the proposal: the main buffa crate docs (and the migration-from-prost guide) should carry a short "Where's #[derive(Message)]?" section that links here. The rust_serialization_benchmark integration showed that users coming from prost reach for the derive first, don't find it, and read the absence as a gap rather than a position. A two-line pointer ("for tests use buffa-test-fixtures; for application code generate from .proto, here's why") would head that off.