Expand description
Shared code generation logic for buffa.
This crate takes protobuf descriptors (google.protobuf.FileDescriptorProto,
decoded from binary FileDescriptorSet data) and emits Rust source code
that uses the buffa runtime.
It is used by:
protoc-gen-reallyme-buffa(protoc plugin)buffa-build(build.rs integration)
§Architecture
The code generator is intentionally decoupled from how descriptors are
obtained. It receives fully-resolved FileDescriptorProtos and produces
Rust source strings. This means:
- It doesn’t parse
.protofiles. - It doesn’t invoke
protoc. - It doesn’t do import resolution or name linking.
All of that is handled upstream (by protoc, buf, or a future parser).
Modules§
- context
- Code generation context and descriptor-to-Rust mapping state.
- idents
- Rust identifier and path construction helpers.
Structs§
- Alias
Conflict - One CamelCase collision: a target identifier and the proto value names that would all convert onto it.
- Code
GenConfig - Configuration for code generation.
- Feature
Gate Names - Crate feature names used by the gated impls, customizable per impl kind.
- Generated
File - One generated output file.
- Shared
Corpus Context - The corpus-wide state
CodeGenContextderives on everygenerate()call — which oneof variants are unboxed, which message fields are stored inline, and the raw comment text per fully-qualified name — none of which depends on the extern paths that legitimately vary per call in a one-crate-per-package workspace. Build one withSharedCorpusContext::newfrom the whole corpus and setCodeGenConfig::shared_corpus_contexton every per-package config to skip that work on each call. - Table
Codec Fallback Reason - Why some messages selected for
CodecStrategy::Tablefell back toCodecStrategy::Unrolled, forCodeGenWarning::TableCodecFallbackSummary.
Enums§
- Bytes
Repr - The Rust type a proto
bytesfield maps to in generated owned structs. - Code
GenError - Code generation error.
- Code
GenWarning - A non-fatal diagnostic produced during code generation.
- Codec
Strategy - How a message’s binary
Messageimplementation is generated. Select it withCodeGenConfig::codec_strategyandCodeGenConfig::codec_strategy_in. - Enum
Type Override - Supported values for
FeatureOverride::EnumType. - FdsEmbedding
- How
shared_descriptor_root_moduleembeds the descriptor set into the generated tree. Both forms decode to byte-identical runtime data; they differ only in generated-source size and whether a sidecar file is written. - Feature
Override - A path-scoped protobuf editions feature override, applied by mutating the
parsed descriptors before generation (see
feature_overrides). - Generated
File Kind - Kind of
GeneratedFile. - Include
Mode - How
generate_module_treeemitsinclude!paths. - MapRepr
- The owned Rust collection a proto
map<K, V>field maps to in generated owned structs. - Pointer
Repr - The owned smart pointer a singular message field’s
buffa::MessageFieldwraps in generated owned structs. - Reflect
Mode - How much reflection support generated types get.
- Repeated
Repr - The owned Rust collection a proto
repeatedfield maps to in generated owned structs. - String
Repr - The Rust type a proto
stringfield maps to in generated owned structs. - Zeroize
Configuration Error Reason - Why a selected message cannot use recursive cleanup.
Constants§
- ALLOW_
LINTS - Lints suppressed on generated code at module boundaries.
- ELEMENT_
MEMORY_ LIMIT_ ENV - Environment variable overriding the element-memory bound buffa’s tooling applies when decoding a descriptor set.
- ELEMENT_
MEMORY_ LIMIT_ OPT - Plugin option, settable in the
protoc/bufparameter string, that sets the element-memory bound used to decode the request carrying it. - TOOLING_
ELEMENT_ MEMORY_ LIMIT - Element-memory bound buffa’s build tooling applies to a descriptor set —
the
protocplugins to aCodeGeneratorRequest,buffa-buildto aFileDescriptorSet.
Functions§
- allow_
lints_ attr - Render
ALLOW_LINTSas a#[allow(…)]attribute token stream. - apply_
companions - Merge downstream
Companionfiles into the per-package stitcher produced bygenerate. - decode_
failure - Describe a failure to decode a descriptor set, naming the override when the element-memory bound is what rejected it.
- decode_
request - Decode a
CodeGeneratorRequestfrom aprotocplugin’s stdin. - element_
memory_ limit_ opt - Find
element_memory_limit=<value>in aprotocplugin parameter string. - encode_
descriptor_ set - Encode the shared reflection
FileDescriptorSetfor a codegen run, withsource_code_infostripped, ready to embed once at the module-tree root in shared-pool mode. - generate
- Generate Rust source files from a set of file descriptors.
- generate_
module_ tree - Generate a module tree that assembles per-package
.mod.rsfiles into nestedpub modblocks matching the protobuf package hierarchy. - generate_
with_ diagnostics - Like
generate, but also returns the non-fatalCodeGenWarnings collected during generation (e.g. enums whose idiomatic CamelCase aliases were suppressed by a naming conflict). - normalize_
exclude_ package - Normalize and validate one
exclude_packageoption value: trim whitespace, strip the optional leading dot, reject an empty result or a value with empty components (buf.validate.,buf..validate) — those could never match a real package, so a typo would otherwise be a silent no-op. - normalize_
extern_ path_ proto_ name - Normalize and validate the proto side of one
extern_pathmapping. - package_
is_ excluded - Returns
trueifpackageis covered by any entry inexcludes. - package_
to_ filename - Convert a proto package name to its
file_per_packageoutput filename. - package_
to_ mod_ filename - Convert a proto package name to its
.mod.rsstitcher filename. - peek_
request_ parameter - Read
CodeGeneratorRequest.parameter(field 2) straight off the wire, without decoding the request. - proto_
path_ to_ stem - Convert a
.protofile path to its content-file stem. - shared_
descriptor_ root_ module - Render the shared
__buffa_fdsroot module as formatted Rust source, for a front-end to prepend to the module-tree file in shared-pool mode. Every package’s__buffa::reflectmodule delegates here, so the descriptor set is embedded once for the whole tree instead of once per package. - tooling_
decode_ options - Decode options for a descriptor set produced by the caller’s own build,
honouring
ELEMENT_MEMORY_LIMIT_ENV.