pub mod adapters;
pub(crate) mod comments;
pub mod context;
pub(crate) mod defaults;
pub(crate) mod enumeration;
pub(crate) mod extension;
pub(crate) mod feature_gates;
pub use feature_gates::FeatureGateNames;
pub(crate) mod features;
pub(crate) mod field_names;
#[doc(hidden)]
pub use buffa_descriptor::generated;
pub(crate) mod feature_overrides;
pub mod idents;
pub(crate) mod impl_message;
pub(crate) mod impl_text;
pub(crate) mod imports;
pub(crate) mod json_policy;
mod serde_input;
pub use serde_input::ErrorReason as CleanupJsonAttributeErrorReason;
pub(crate) mod lazy_view;
pub(crate) mod message;
pub(crate) mod oneof;
pub(crate) mod owned_view;
pub(crate) mod reflect;
pub(crate) mod reflect_owned;
pub(crate) mod reflect_view;
pub(crate) mod table_codec;
pub(crate) mod table_plan;
pub(crate) mod view;
use crate::generated::descriptor::{DescriptorProto, EnumDescriptorProto, FileDescriptorProto};
use proc_macro2::TokenStream;
use quote::{format_ident, quote};
const GENERATED_HEADER: &str = concat!(
"// @generated by reallyme-buffa-codegen ",
env!("CARGO_PKG_VERSION"),
". DO NOT EDIT.\n",
"// Modified by ReallyMe Technologies Limited.\n",
);
pub const ELEMENT_MEMORY_LIMIT_ENV: &str = "BUFFA_ELEMENT_MEMORY_LIMIT";
pub const TOOLING_ELEMENT_MEMORY_LIMIT: usize = 1024 * 1024 * 1024;
pub fn tooling_decode_options() -> Result<buffa::DecodeOptions, String> {
let raw = std::env::var(ELEMENT_MEMORY_LIMIT_ENV).ok();
let limit = parse_element_memory_limit(raw.as_deref())?;
Ok(buffa::DecodeOptions::new().with_element_memory_limit(limit))
}
#[must_use]
pub fn decode_failure(subject: &str, err: &buffa::DecodeError, limit: usize) -> String {
let base = format!("failed to decode {subject}: {err}");
match err {
buffa::DecodeError::ElementMemoryLimitExceeded => format!(
"{base}\n\
These descriptors exceed the {budget} element-memory budget in force. \
Raise it with the {opt}=<bytes> plugin option or the {env} environment \
variable; either accepts 'unlimited'. See \"Very large schemas\" in the \
buffa guide.",
budget = describe_byte_budget(limit),
opt = ELEMENT_MEMORY_LIMIT_OPT,
env = ELEMENT_MEMORY_LIMIT_ENV,
),
_ => base,
}
}
fn describe_byte_budget(bytes: usize) -> String {
const MIB: usize = 1024 * 1024;
if bytes >= MIB && bytes.is_multiple_of(MIB) {
format!("{} MiB", bytes / MIB)
} else {
format!("{bytes}-byte")
}
}
pub const ELEMENT_MEMORY_LIMIT_OPT: &str = "element_memory_limit";
pub fn peek_request_parameter(mut buf: &[u8]) -> Result<Option<&str>, buffa::DecodeError> {
use buffa::encoding::{decode_varint, skip_field, Tag, WireType};
const PARAMETER_FIELD: u32 = 2;
let mut found = None;
while !buf.is_empty() {
let tag = Tag::decode(&mut buf)?;
if tag.field_number() == PARAMETER_FIELD && tag.wire_type() == WireType::LengthDelimited {
let len = usize::try_from(decode_varint(&mut buf)?)
.map_err(|_| buffa::DecodeError::MessageTooLarge)?;
if len > buf.len() {
return Err(buffa::DecodeError::UnexpectedEof);
}
let (value, rest) = buf.split_at(len);
found = Some(core::str::from_utf8(value).map_err(|_| buffa::DecodeError::InvalidUtf8)?);
buf = rest;
continue;
}
skip_field(tag, &mut buf)?;
}
Ok(found)
}
pub fn element_memory_limit_opt(parameter: &str) -> Result<Option<usize>, String> {
let mut found = None;
for entry in parameter.split(',').map(str::trim) {
if let Some((key, value)) = entry.split_once('=') {
if key.trim() == ELEMENT_MEMORY_LIMIT_OPT {
found = Some(parse_element_memory_limit(Some(value))?);
}
}
}
Ok(found)
}
pub fn decode_request(input: &[u8]) -> Result<generated::compiler::CodeGeneratorRequest, String> {
let parameter = peek_request_parameter(input)
.map_err(|e| format!("failed to read the plugin parameter: {e}"))?
.unwrap_or_default();
let options = match element_memory_limit_opt(parameter)? {
Some(limit) => buffa::DecodeOptions::new().with_element_memory_limit(limit),
None => tooling_decode_options()?,
};
options
.decode_from_slice::<generated::compiler::CodeGeneratorRequest>(input)
.map_err(|e| decode_failure("CodeGeneratorRequest", &e, options.element_memory_limit()))
}
#[must_use]
pub fn plugin_response_metadata() -> generated::compiler::CodeGeneratorResponse {
use generated::compiler::code_generator_response::Feature;
use generated::descriptor::Edition;
generated::compiler::CodeGeneratorResponse {
supported_features: Some(
Feature::FEATURE_PROTO3_OPTIONAL as u64 | Feature::FEATURE_SUPPORTS_EDITIONS as u64,
),
minimum_edition: Some(Edition::EDITION_PROTO2 as i32),
maximum_edition: Some(Edition::EDITION_2024 as i32),
..Default::default()
}
}
pub(crate) fn parse_element_memory_limit(raw: Option<&str>) -> Result<usize, String> {
let Some(raw) = raw else {
return Ok(TOOLING_ELEMENT_MEMORY_LIMIT);
};
match raw.trim() {
"" => Ok(TOOLING_ELEMENT_MEMORY_LIMIT),
"unlimited" | "max" => Ok(usize::MAX),
n => n.parse::<usize>().map_err(|_| {
format!("{ELEMENT_MEMORY_LIMIT_ENV}: expected a byte count or 'unlimited', got '{raw}'")
}),
}
}
pub const ALLOW_LINTS: &[&str] = &[
"non_camel_case_types",
"dead_code",
"unused_imports",
"unused_qualifications",
"clippy::derivable_impls",
"clippy::match_single_binding",
"clippy::uninlined_format_args",
"clippy::doc_lazy_continuation",
"clippy::module_inception",
];
pub fn allow_lints_attr() -> TokenStream {
let lints: Vec<TokenStream> = ALLOW_LINTS
.iter()
.map(|l| syn::parse_str(l).expect("lint name parses as path"))
.collect();
quote! { #[allow( #(#lints),* )] }
}
#[derive(Debug)]
pub struct GeneratedFile {
pub name: String,
pub package: String,
pub kind: GeneratedFileKind,
pub content: String,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum GeneratedFileKind {
Adapter,
Owned,
View,
LazyView,
Oneof,
ViewOneof,
Ext,
PackageMod,
Companion,
}
pub(crate) fn parse_custom_type_path(path: &str) -> Result<proc_macro2::TokenStream, CodeGenError> {
let ty: syn::Type = context::normalized_rust_type(path)
.map_err(|_| CodeGenError::InvalidTypePath(path.to_string()))?;
if !is_type_path(&ty) {
return Err(CodeGenError::InvalidTypePath(format!(
"{path} (a custom type must be a type path such as `crate::Name`)"
)));
}
Ok(quote::quote! { #ty })
}
fn is_type_path(mut ty: &syn::Type) -> bool {
while let syn::Type::Paren(inner) = ty {
ty = &inner.elem;
}
matches!(ty, syn::Type::Path(_))
}
pub(crate) fn parse_custom_map_path(path: &str) -> Result<proc_macro2::TokenStream, CodeGenError> {
let ty: syn::Type = syn::parse_str(path).map_err(|_| {
CodeGenError::InvalidTypePath(format!(
"{path} (map custom path takes no `<K, V>` parameters and no `*` placeholder)"
))
})?;
let syn::Type::Path(tp) = &ty else {
return Err(CodeGenError::InvalidTypePath(format!(
"{path} (map custom path must be a plain type path)"
)));
};
if tp
.path
.segments
.iter()
.any(|s| !matches!(s.arguments, syn::PathArguments::None))
{
return Err(CodeGenError::InvalidTypePath(format!(
"{path} (map custom path must not include `<K, V>`; the key and value are appended automatically)"
)));
}
Ok(quote::quote! { #ty })
}
pub(crate) fn parse_wildcard_type_path(
template: &str,
inner: &proc_macro2::TokenStream,
) -> Result<proc_macro2::TokenStream, CodeGenError> {
if !template.contains('*') {
return Err(CodeGenError::MissingWildcard(template.to_string()));
}
let substituted = template.replace('*', &inner.to_string());
let ty: syn::Type = syn::parse_str(&substituted)
.map_err(|_| CodeGenError::InvalidTypePath(format!("{template} (as {substituted})")))?;
Ok(quote::quote! { #ty })
}
pub(crate) fn parse_custom_list_path(
template: &str,
elem: &proc_macro2::TokenStream,
) -> Result<proc_macro2::TokenStream, CodeGenError> {
if !template.contains('*') {
return Err(CodeGenError::MissingListPlaceholder(template.to_string()));
}
let substituted = template.replace('*', &elem.to_string());
let ty: syn::Type = context::normalized_rust_type(&substituted)
.map_err(|_| CodeGenError::InvalidTypePath(format!("{template} (as {substituted})")))?;
if !is_type_path(&ty) {
return Err(CodeGenError::InvalidTypePath(format!(
"{template} (as {substituted}; a custom collection must be a type path \
such as `crate::List<*>`)"
)));
}
Ok(quote::quote! { #ty })
}
#[derive(Debug, Clone, PartialEq, Eq, Default)]
#[non_exhaustive]
pub enum StringRepr {
#[default]
String,
Custom(String),
}
impl StringRepr {
pub(crate) fn type_path(
&self,
resolver: &imports::ImportResolver,
ctx: &context::CodeGenContext,
nesting: usize,
) -> Result<proc_macro2::TokenStream, CodeGenError> {
match self {
StringRepr::String => Ok(resolver.string_at(ctx, nesting)),
StringRepr::Custom(path) => parse_custom_type_path(path),
}
}
pub(crate) fn is_default(&self) -> bool {
matches!(self, StringRepr::String)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Default)]
#[non_exhaustive]
pub enum BytesRepr {
#[default]
Vec,
Bytes,
Custom(String),
}
impl BytesRepr {
pub(crate) fn type_path(
&self,
resolver: &imports::ImportResolver,
ctx: &context::CodeGenContext,
nesting: usize,
) -> Result<proc_macro2::TokenStream, CodeGenError> {
use quote::quote;
match self {
BytesRepr::Vec => {
let vec = resolver.vec_at(ctx, nesting);
Ok(quote! { #vec<u8> })
}
BytesRepr::Bytes => Ok(quote! { ::buffa::bytes::Bytes }),
BytesRepr::Custom(path) => parse_custom_type_path(path),
}
}
pub(crate) fn is_default(&self) -> bool {
matches!(self, BytesRepr::Vec)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Default)]
#[non_exhaustive]
pub enum MapRepr {
#[default]
HashMap,
BTreeMap,
Custom(String),
}
impl MapRepr {
pub(crate) fn type_path(
&self,
key: &proc_macro2::TokenStream,
value: &proc_macro2::TokenStream,
resolver: &imports::ImportResolver,
ctx: &context::CodeGenContext,
nesting: usize,
) -> Result<proc_macro2::TokenStream, CodeGenError> {
use quote::quote;
match self {
MapRepr::HashMap => {
let hm = resolver.hashmap_at(ctx, nesting);
Ok(quote! { #hm<#key, #value> })
}
MapRepr::BTreeMap => Ok(quote! { ::buffa::alloc::collections::BTreeMap<#key, #value> }),
MapRepr::Custom(path) => {
let ty = parse_custom_map_path(path)?;
Ok(quote! { #ty<#key, #value> })
}
}
}
pub(crate) fn is_default(&self) -> bool {
matches!(self, MapRepr::HashMap)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Default)]
#[non_exhaustive]
pub enum PointerRepr {
Box,
#[default]
Inline,
Custom(String),
}
impl PointerRepr {
pub(crate) fn type_path(
&self,
message_field: &proc_macro2::TokenStream,
inner: &proc_macro2::TokenStream,
) -> Result<proc_macro2::TokenStream, CodeGenError> {
use quote::quote;
match self {
PointerRepr::Box => Ok(quote! { #message_field<#inner> }),
PointerRepr::Inline => Ok(quote! { #message_field<#inner, ::buffa::Inline<#inner>> }),
PointerRepr::Custom(template) => {
let ptr = parse_wildcard_type_path(template, inner)?;
Ok(quote! { #message_field<#inner, #ptr> })
}
}
}
pub(crate) fn some_path(
&self,
inner: &proc_macro2::TokenStream,
) -> Result<proc_macro2::TokenStream, CodeGenError> {
use quote::quote;
match self {
PointerRepr::Box => Ok(quote! { ::buffa::MessageField::<#inner> }),
PointerRepr::Inline => {
Ok(quote! { ::buffa::MessageField::<#inner, ::buffa::Inline<#inner>> })
}
PointerRepr::Custom(template) => {
let ptr = parse_wildcard_type_path(template, inner)?;
Ok(quote! { ::buffa::MessageField::<#inner, #ptr> })
}
}
}
pub(crate) fn pointer_type(
&self,
inner: &proc_macro2::TokenStream,
) -> Result<proc_macro2::TokenStream, CodeGenError> {
use quote::quote;
match self {
PointerRepr::Box => Ok(quote! { ::buffa::alloc::boxed::Box<#inner> }),
PointerRepr::Inline => Ok(quote! { ::buffa::Inline<#inner> }),
PointerRepr::Custom(template) => parse_wildcard_type_path(template, inner),
}
}
pub(crate) fn pointer_new(
&self,
inner: &proc_macro2::TokenStream,
value: &proc_macro2::TokenStream,
) -> Result<proc_macro2::TokenStream, CodeGenError> {
use quote::quote;
match self {
PointerRepr::Box => Ok(quote! { ::buffa::alloc::boxed::Box::new(#value) }),
PointerRepr::Inline => Ok(quote! { ::buffa::Inline(#value) }),
PointerRepr::Custom(template) => {
let ptr = parse_wildcard_type_path(template, inner)?;
Ok(quote! { <#ptr as ::buffa::ProtoBox<#inner>>::new(#value) })
}
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Default)]
#[non_exhaustive]
pub enum RepeatedRepr {
#[default]
Vec,
Custom(String),
}
impl RepeatedRepr {
pub(crate) fn type_path(
&self,
elem: &proc_macro2::TokenStream,
resolver: &imports::ImportResolver,
ctx: &context::CodeGenContext,
nesting: usize,
) -> Result<proc_macro2::TokenStream, CodeGenError> {
use quote::quote;
match self {
RepeatedRepr::Vec => {
let vec = resolver.vec_at(ctx, nesting);
Ok(quote! { #vec<#elem> })
}
RepeatedRepr::Custom(template) => parse_custom_list_path(template, elem),
}
}
pub(crate) fn is_default(&self) -> bool {
matches!(self, RepeatedRepr::Vec)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[non_exhaustive]
pub enum ReflectMode {
#[default]
Off,
Bridge,
VTable,
}
impl ReflectMode {
pub fn apply(self, config: &mut CodeGenConfig) {
let (reflection, vtable) = match self {
ReflectMode::Off => (false, false),
ReflectMode::Bridge => (true, false),
ReflectMode::VTable => (true, true),
};
config.generate_reflection = reflection;
config.generate_reflection_vtable = vtable;
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum FeatureOverride {
EnumType(EnumTypeOverride),
}
impl FeatureOverride {
#[must_use]
pub fn feature_name(&self) -> &'static str {
match self {
Self::EnumType(_) => "enum_type",
}
}
#[must_use]
pub fn value_name(&self) -> &'static str {
match self {
Self::EnumType(EnumTypeOverride::Open) => "OPEN",
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum EnumTypeOverride {
Open,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum CodecStrategy {
#[default]
Unrolled,
Table,
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct TableCodecFallbackReason {
pub reason: String,
pub messages: Vec<String>,
}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct CodeGenConfig {
pub adapters: Option<adapters::AdapterConfig>,
pub generate_adapters: bool,
pub generate_zeroize: bool,
pub zeroize_messages: Vec<String>,
pub deny_view_json: Vec<String>,
pub borrowed_views_only_in: Vec<String>,
pub allow_unmatched_message_rules: bool,
pub generate_views: bool,
pub lazy_views: bool,
pub preserve_unknown_fields: bool,
pub preserve_unknown_fields_in: Vec<(String, bool)>,
pub deny_unknown_json_fields: bool,
pub deny_unknown_json_fields_in: Vec<(String, bool)>,
pub generate_json: bool,
pub generate_arbitrary: bool,
pub skip_debug: Vec<String>,
pub extern_paths: Vec<(String, String)>,
pub bytes_fields: Vec<(String, BytesRepr)>,
pub string_fields: Vec<(String, StringRepr)>,
pub json_policy_types: Vec<String>,
pub emit_custom_type_impls: bool,
pub map_fields: Vec<(String, MapRepr)>,
pub pointer_fields: Vec<(String, PointerRepr)>,
pub repeated_fields: Vec<(String, RepeatedRepr)>,
pub feature_overrides: Vec<(String, FeatureOverride)>,
pub unboxed_oneof_fields: Vec<String>,
pub strict_utf8_mapping: bool,
pub allow_message_set: bool,
pub generate_text: bool,
pub emit_register_fn: bool,
pub file_per_package: bool,
pub type_attributes: Vec<(String, String)>,
pub field_attributes: Vec<(String, String)>,
pub message_attributes: Vec<(String, String)>,
pub enum_attributes: Vec<(String, String)>,
pub oneof_attributes: Vec<(String, String)>,
pub oneof_struct_field_attributes: Vec<(String, String)>,
pub gate_impls_on_crate_features: bool,
pub generate_with_setters: bool,
pub map_entries_omit_defaults: bool,
pub generate_reflection: bool,
pub generate_reflection_vtable: bool,
pub shared_descriptor_pool: bool,
pub shared_descriptor_pool_root: Option<String>,
pub shared_corpus_context: Option<SharedCorpusContext>,
pub gate_reflect_on_crate_feature: bool,
pub idiomatic_enum_aliases: bool,
pub idiomatic_imports: bool,
pub idiomatic_field_names: bool,
pub feature_gate_names: FeatureGateNames,
pub type_name_prefix: String,
pub exclude_packages: Vec<String>,
pub codec_strategy: CodecStrategy,
pub codec_strategy_in: Vec<(String, CodecStrategy)>,
}
impl Default for CodeGenConfig {
fn default() -> Self {
Self {
adapters: None,
generate_adapters: false,
generate_zeroize: false,
zeroize_messages: Vec::new(),
deny_view_json: Vec::new(),
borrowed_views_only_in: Vec::new(),
allow_unmatched_message_rules: false,
generate_views: true,
lazy_views: false,
preserve_unknown_fields: true,
preserve_unknown_fields_in: Vec::new(),
deny_unknown_json_fields: false,
deny_unknown_json_fields_in: Vec::new(),
generate_json: false,
generate_arbitrary: false,
skip_debug: Vec::new(),
extern_paths: Vec::new(),
bytes_fields: Vec::new(),
string_fields: Vec::new(),
json_policy_types: Vec::new(),
emit_custom_type_impls: true,
map_fields: Vec::new(),
pointer_fields: Vec::new(),
repeated_fields: Vec::new(),
feature_overrides: Vec::new(),
unboxed_oneof_fields: Vec::new(),
strict_utf8_mapping: false,
allow_message_set: false,
generate_text: false,
emit_register_fn: true,
file_per_package: false,
type_attributes: Vec::new(),
field_attributes: Vec::new(),
message_attributes: Vec::new(),
enum_attributes: Vec::new(),
oneof_attributes: Vec::new(),
oneof_struct_field_attributes: Vec::new(),
gate_impls_on_crate_features: false,
generate_with_setters: true,
map_entries_omit_defaults: false,
generate_reflection: false,
generate_reflection_vtable: false,
shared_descriptor_pool: false,
shared_descriptor_pool_root: None,
shared_corpus_context: None,
gate_reflect_on_crate_feature: false,
idiomatic_enum_aliases: true,
idiomatic_imports: false,
idiomatic_field_names: false,
feature_gate_names: FeatureGateNames::default(),
type_name_prefix: String::new(),
exclude_packages: Vec::new(),
codec_strategy: CodecStrategy::Unrolled,
codec_strategy_in: Vec::new(),
}
}
}
impl CodeGenConfig {
pub(crate) fn has_enum_type_overrides(&self) -> bool {
self.feature_overrides
.iter()
.any(|(_, o)| matches!(o, FeatureOverride::EnumType(_)))
}
pub(crate) fn feature_gates(&self) -> feature_gates::FeatureGates<'_> {
feature_gates::FeatureGates::for_config(self)
}
#[must_use]
pub fn reflect_feature_gate(&self) -> Option<&str> {
self.feature_gates().reflect
}
pub(crate) fn prefixed_type_name(&self, proto_name: &str) -> String {
idents::local_type_name(&self.type_name_prefix, proto_name)
}
pub(crate) fn validate_type_name_prefix(&self) -> Result<(), CodeGenError> {
let prefix = &self.type_name_prefix;
let valid = prefix.is_empty()
|| (prefix.starts_with(|c: char| c.is_ascii_uppercase())
&& prefix.chars().all(|c| c.is_ascii_alphanumeric()));
if valid {
Ok(())
} else {
Err(CodeGenError::InvalidTypeNamePrefix {
prefix: prefix.clone(),
})
}
}
}
pub(crate) fn effective_extern_paths(
file_descriptors: &[FileDescriptorProto],
files_to_generate: &[String],
config: &CodeGenConfig,
) -> Vec<(String, String)> {
let mut paths = config.extern_paths.clone();
let has_wkt_mapping = paths.iter().any(|(proto, _)| proto == ".google.protobuf");
if !has_wkt_mapping {
let generating_wkts = file_descriptors
.iter()
.filter(|fd| {
fd.name
.as_deref()
.is_some_and(|n| files_to_generate.iter().any(|f| f == n))
})
.any(|fd| fd.package.as_deref() == Some("google.protobuf"));
if !generating_wkts {
paths.push((
".google.protobuf".to_string(),
"::buffa_types::google::protobuf".to_string(),
));
}
}
paths
}
pub(crate) fn effective_file_extern_paths(
files_to_generate: &[String],
config: &CodeGenConfig,
) -> Vec<(String, String)> {
const DESCRIPTOR_FILES: [(&str, &str, &str); 2] = [
(
"google/protobuf/descriptor.proto",
"google.protobuf",
"::buffa_descriptor::generated::descriptor",
),
(
"google/protobuf/compiler/plugin.proto",
"google.protobuf.compiler",
"::buffa_descriptor::generated::compiler",
),
];
DESCRIPTOR_FILES
.into_iter()
.filter(|(proto_file, package, _)| {
if context::resolve_extern_prefix(package, &config.extern_paths).is_some() {
return false;
}
!files_to_generate.iter().any(|f| f == proto_file)
})
.map(|(proto_file, _, rust_module)| (proto_file.to_string(), rust_module.to_string()))
.collect()
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct AliasConflict {
pub camel_target: String,
pub proto_values: Vec<String>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum CodeGenWarning {
#[non_exhaustive]
ZeroizeRuleMatchedNothing { rule: String },
#[non_exhaustive]
ViewJsonRuleMatchedNothing { rule: String },
#[non_exhaustive]
BorrowedViewsRuleMatchedNothing { rule: String },
#[non_exhaustive]
ViewJsonRulesRequireJsonAndViews,
#[non_exhaustive]
IdiomaticAliasesSuppressed {
enum_name: String,
conflicts: Vec<AliasConflict>,
invalid: Vec<String>,
},
#[non_exhaustive]
OwnedViewAccessorSuppressed {
wrapper_name: String,
field_name: String,
},
#[non_exhaustive]
LazyViewsRequireViews,
#[non_exhaustive]
DenyUnknownJsonFieldsRequiresJson,
#[non_exhaustive]
JsonPolicyTypesRequireJson,
#[non_exhaustive]
JsonPolicyReflectionBypass {
policy_types: Vec<String>,
},
#[non_exhaustive]
IdiomaticFieldNamesAdjusted {
message_name: String,
assignments: Vec<(String, String)>,
},
#[non_exhaustive]
KeywordEscapedNamesAdjusted {
message_name: String,
assignments: Vec<(String, String)>,
},
#[non_exhaustive]
ExcludedPackageFieldRef {
file_name: String,
message_name: String,
field_name: String,
ref_package: String,
type_fqn: String,
},
#[non_exhaustive]
ExcludePackageMatchedNothing {
package: String,
},
#[non_exhaustive]
FeatureOverrideMatchedNothing {
rule: String,
feature: &'static str,
value: &'static str,
},
#[non_exhaustive]
PreserveUnknownFieldsRuleMatchedNothing {
rule: String,
},
#[non_exhaustive]
DenyUnknownJsonFieldsRuleMatchedNothing {
rule: String,
},
#[non_exhaustive]
SkipDebugRuleMatchedNothing {
rule: String,
},
#[non_exhaustive]
FieldTypeRuleMatchedNothing {
rule: String,
option: &'static str,
matches_ungenerated: bool,
names_extension: bool,
},
#[non_exhaustive]
CodecStrategyRuleMatchedNothing {
rule: String,
},
#[non_exhaustive]
TableCodecFallbackSummary {
fallbacks: usize,
selected: usize,
reasons: Vec<TableCodecFallbackReason>,
},
}
fn field_type_rule_kind(option: &str) -> (&'static str, &'static str) {
match option {
"bytes_fields" => (
"bytes",
"bytes_type_in / use_bytes_type_in / bytes_type_custom_in",
),
"string_fields" => ("string", "string_type_in / string_type_custom_in"),
"map_fields" => ("map", "map_type_in / map_type_custom_in"),
"repeated_fields" => ("repeated", "repeated_type_in / repeated_type_custom_in"),
_ => ("field", ""),
}
}
impl core::fmt::Display for CodeGenWarning {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
match self {
Self::ViewJsonRulesRequireJsonAndViews => f.write_str(
"deny_view_json requires both generate_json and generate_views; the configured restrictions are inactive"
),
Self::ZeroizeRuleMatchedNothing { rule } => write!(
f, "zeroize_in rule '{rule}' matches no message in this scoped request; validate the full project with allow_unmatched_message_rules=false"
),
Self::BorrowedViewsRuleMatchedNothing { rule } => write!(
f, "borrowed_views_only_in rule '{rule}' matches no message in this scoped request; validate the full project with allow_unmatched_message_rules=false"
),
Self::ViewJsonRuleMatchedNothing { rule } => write!(
f, "deny_view_json rule '{rule}' matches no message in this scoped request; validate the full project with allow_unmatched_message_rules=false"
),
Self::IdiomaticAliasesSuppressed {
enum_name,
conflicts,
invalid,
} => {
let cause = match (conflicts.is_empty(), invalid.is_empty()) {
(false, true) => "naming conflict",
(true, false) => "invalid identifier",
_ => "naming conflict / invalid identifier",
};
write!(
f,
"enum `{enum_name}`: idiomatic CamelCase aliases suppressed ({cause})"
)?;
let mut parts: Vec<String> = conflicts
.iter()
.map(|c| format!("{} → {}", c.proto_values.join(", "), c.camel_target))
.collect();
parts.extend(invalid.iter().map(|n| format!("{n} → invalid identifier")));
if !parts.is_empty() {
write!(f, ": {}", parts.join("; "))?;
}
Ok(())
}
Self::OwnedViewAccessorSuppressed {
wrapper_name,
field_name,
} => {
write!(
f,
"`{wrapper_name}`: accessor for field `{field_name}` suppressed \
(collides with a reserved wrapper method); use `.view().{field_name}` instead"
)
}
Self::JsonPolicyReflectionBypass { policy_types } => {
write!(
f,
"json_policy_type for {} governs only the generated serde impls: \
with reflection generated, `to_dynamic` (like \
`DynamicMessage::try_from_message`, which works without it) \
gives `DynamicMessage` JSON that prints and reads fields of \
the listed types as standard base64 or plain strings without \
calling their policy, so a policy that refuses export does \
not stop it and its import checks do not run; a policy is \
not a confidentiality boundary, so keep reflective JSON, \
text format and binary output of these messages away from \
sinks that must not see the values",
policy_types.join(", ")
)
}
Self::JsonPolicyTypesRequireJson => {
write!(
f,
"json_policy_type requires generate_json (there is no generated \
JSON to route through a policy) — enable generate_json \
(buffa-build: `.generate_json(true)`; plugin: `json=true`)"
)
}
Self::DenyUnknownJsonFieldsRequiresJson => {
write!(
f,
"deny_unknown_json_fields requires generate_json (there are no \
generated JSON deserializers to make strict); unknown JSON keys \
are still ignored — enable generate_json (buffa-build: \
`.generate_json(true)`; plugin: `json=true`)"
)
}
Self::LazyViewsRequireViews => {
write!(
f,
"lazy_views requires generate_views (the lazy family reuses the \
eager view-oneof enums and sub-view types); no lazy views were \
generated — enable generate_views (buffa-build: \
`.generate_views(true)`, the default; plugin: `views=true`)"
)
}
Self::IdiomaticFieldNamesAdjusted {
message_name,
assignments,
} => {
let parts: Vec<String> = assignments
.iter()
.map(|(proto, rust)| format!("`{proto}` → `{rust}`"))
.collect();
write!(
f,
"message `{message_name}`: idiomatic snake_case field names collide; \
adjusted: {} (wire/JSON/text names are unaffected)",
parts.join(", ")
)
}
Self::KeywordEscapedNamesAdjusted {
message_name,
assignments,
} => {
let parts: Vec<String> = assignments
.iter()
.map(|(proto, rust)| format!("`{proto}` → `{rust}`"))
.collect();
write!(
f,
"message `{message_name}`: a member's keyword-escaped Rust name is the \
name of another member, in this message or in one that declares the \
same member; adjusted: {} (wire/JSON/text names are unaffected)",
parts.join(", ")
)
}
Self::ExcludedPackageFieldRef {
file_name,
message_name,
field_name,
ref_package,
type_fqn,
} => {
let location = if message_name.is_empty() {
format!("{file_name}: {field_name}")
} else {
format!("{file_name}: {message_name}.{field_name}")
};
write!(
f,
"field `{location}` references `{type_fqn}`, which is not being \
generated and has no extern_path mapping; the generated code will \
contain a dangling type path — map the type or its package \
`{ref_package}` to the crate that defines it \
(buffa-build: `.extern_path(\"{type_fqn}\", \"::your_crate::Type\")` \
or `.extern_path(\".{ref_package}\", \"::your_crate\")`; \
plugin: `extern_path={type_fqn}=::your_crate::Type` or \
`extern_path=.{ref_package}=::your_crate`), or include the \
defining .proto file in the generate set \
(buffa-build: `.files(&[…])` or drop `.exclude_package(…)`; \
plugin: drop `exclude_package=`)"
)
}
Self::ExcludePackageMatchedNothing { package } => {
write!(
f,
"exclude_package entry \"{package}\" matched no proto package in the \
descriptor set — check for a typo or a stale entry \
(exact match or dotted-prefix: \"buf.validate\" covers \
buf.validate and buf.validate.priv, not buf.validatex)"
)
}
Self::FeatureOverrideMatchedNothing {
rule,
feature,
value,
} => {
write!(
f,
"feature override '{rule}' ({feature} = {value}) matched nothing in \
the compiled set; the affected paths keep their default semantics — \
check the path against the fully-qualified proto names"
)
}
Self::PreserveUnknownFieldsRuleMatchedNothing { rule } => {
write!(
f,
"preserve_unknown_fields_in rule '{rule}' matched no generated message; \
those messages keep the global preserve_unknown_fields setting — \
check the path against the fully-qualified proto message names"
)
}
Self::CodecStrategyRuleMatchedNothing { rule } => {
write!(
f,
"codec_strategy_in rule '{rule}' matched no generated message; those \
messages keep the global codec_strategy setting — check the path \
against the fully-qualified proto message names"
)
}
Self::TableCodecFallbackSummary {
fallbacks,
selected,
reasons,
} => {
write!(
f,
"{fallbacks} of {selected} messages selected for the table codec use the \
unrolled codec instead"
)?;
for (i, r) in reasons.iter().enumerate() {
let sep = if i == 0 { ": " } else { "; " };
let shown = r.messages.len().min(3);
let examples = r.messages[..shown].join(", ");
let more = match r.messages.len() - shown {
0 => String::new(),
n => format!(", and {n} more"),
};
write!(
f,
"{sep}{} ({}: {examples}{more})",
r.reason,
r.messages.len()
)?;
}
write!(
f,
". To silence this warning, set the messages that fell back to the unrolled \
codec (buffa-build: `.codec_strategy_in(CodecStrategy::Unrolled, \
&[\"<path>\"])`; plugin: `codec_strategy_in=<path>=unrolled`)"
)
}
Self::DenyUnknownJsonFieldsRuleMatchedNothing { rule } => {
write!(
f,
"deny_unknown_json_fields_in rule '{rule}' matched no generated message; \
those messages keep the global deny_unknown_json_fields setting — \
check the path against the fully-qualified proto message names"
)
}
Self::SkipDebugRuleMatchedNothing { rule } => {
write!(
f,
"skip_debug rule '{rule}' matched no generated message or enum, \
so a hand-written Debug impl will conflict with the generated one — \
use the fully-qualified proto type name \
(a oneof is covered by its message's rule)"
)
}
Self::FieldTypeRuleMatchedNothing {
rule,
option,
matches_ungenerated,
names_extension,
} => {
let (kind, options) = field_type_rule_kind(option);
write!(f, "{kind} type rule '{rule}' ({options}) ")?;
if *matches_ungenerated {
write!(
f,
"matches only fields of messages this run does not generate \
(an imported file, or a package under extern_path or \
exclude_package), so it changed nothing here"
)
} else if *names_extension {
write!(
f,
"names (or covers only) extension fields, so it changed nothing — custom field \
type rules do not apply to extensions, which keep their default \
Rust type"
)
} else {
write!(
f,
"matched no field of a generated message, so it changed nothing — \
a rule is a fully-qualified proto path with its leading dot \
('.my.pkg', '.my.pkg.Msg' or '.my.pkg.Msg.field'); a bare name \
such as 'field' or 'Msg.field' does not match. Only the files \
this run generates are checked, so a rule for files that a \
separate run generates also warns here"
)
}
}
}
}
}
fn generated_files<'a>(
file_descriptors: &'a [FileDescriptorProto],
files_to_generate: &'a [String],
) -> impl Iterator<Item = (&'a FileDescriptorProto, String)> {
file_descriptors
.iter()
.filter(move |fd| {
fd.name
.as_deref()
.is_some_and(|n| files_to_generate.iter().any(|g| g == n))
})
.map(|fd| {
let package = fd.package.as_deref().unwrap_or("");
let package_fqn = if package.is_empty() {
String::new()
} else {
format!(".{package}")
};
(fd, package_fqn)
})
}
fn rule_matches_generated_message(
rule: &str,
file_descriptors: &[FileDescriptorProto],
files_to_generate: &[String],
) -> bool {
fn any_message_matches(rule: &str, parent_fqn: &str, messages: &[DescriptorProto]) -> bool {
messages.iter().any(|m| {
let fqn = format!("{parent_fqn}.{}", m.name.as_deref().unwrap_or(""));
context::matches_proto_prefix(rule, &fqn)
|| any_message_matches(rule, &fqn, &m.nested_type)
})
}
rule == "."
|| generated_files(file_descriptors, files_to_generate)
.any(|(fd, package_fqn)| any_message_matches(rule, &package_fqn, &fd.message_type))
}
fn rule_names_generated_enum(
rule: &str,
file_descriptors: &[FileDescriptorProto],
files_to_generate: &[String],
) -> bool {
fn names_enum(rule: &str, parent_fqn: &str, enums: &[EnumDescriptorProto]) -> bool {
enums
.iter()
.any(|e| format!("{parent_fqn}.{}", e.name.as_deref().unwrap_or("")) == rule)
}
fn names_nested_enum(rule: &str, parent_fqn: &str, messages: &[DescriptorProto]) -> bool {
messages.iter().any(|m| {
let fqn = format!("{parent_fqn}.{}", m.name.as_deref().unwrap_or(""));
names_enum(rule, &fqn, &m.enum_type) || names_nested_enum(rule, &fqn, &m.nested_type)
})
}
generated_files(file_descriptors, files_to_generate).any(|(fd, package_fqn)| {
names_enum(rule, &package_fqn, &fd.enum_type)
|| names_nested_enum(rule, &package_fqn, &fd.message_type)
})
}
fn rule_matches_field_in(
rule: &str,
file_descriptors: &[FileDescriptorProto],
file_names: &[String],
) -> bool {
fn any_field_matches(rule: &str, parent_fqn: &str, messages: &[DescriptorProto]) -> bool {
messages.iter().any(|m| {
let is_map_entry = m
.options
.as_option()
.and_then(|o| o.map_entry)
.unwrap_or(false);
if is_map_entry {
return false;
}
let fqn = format!("{parent_fqn}.{}", m.name.as_deref().unwrap_or(""));
m.field.iter().any(|f| {
let field_fqn = format!("{fqn}.{}", f.name.as_deref().unwrap_or(""));
context::matches_proto_prefix(rule, &field_fqn)
}) || any_field_matches(rule, &fqn, &m.nested_type)
})
}
rule == "."
|| generated_files(file_descriptors, file_names)
.any(|(fd, package_fqn)| any_field_matches(rule, &package_fqn, &fd.message_type))
}
fn rule_matches_extension_in(rule: &str, file_descriptors: &[FileDescriptorProto]) -> bool {
fn any_extension_matches(
rule: &str,
parent_fqn: &str,
extensions: &[crate::generated::descriptor::FieldDescriptorProto],
messages: &[DescriptorProto],
) -> bool {
extensions.iter().any(|ext| {
let ext_fqn = format!("{parent_fqn}.{}", ext.name.as_deref().unwrap_or(""));
context::matches_proto_prefix(rule, &ext_fqn)
}) || messages.iter().any(|m| {
let fqn = format!("{parent_fqn}.{}", m.name.as_deref().unwrap_or(""));
any_extension_matches(rule, &fqn, &m.extension, &m.nested_type)
})
}
file_descriptors.iter().any(|fd| {
let package_fqn = match fd.package.as_deref() {
Some(pkg) if !pkg.is_empty() => format!(".{pkg}"),
_ => String::new(),
};
any_extension_matches(rule, &package_fqn, &fd.extension, &fd.message_type)
})
}
fn rule_paths<R>(rules: &[(String, R)]) -> Vec<&String> {
rules.iter().map(|(path, _)| path).collect()
}
fn unshadowed_rules<R>(rules: &[(String, R)]) -> impl Iterator<Item = &R> {
rules
.iter()
.enumerate()
.filter_map(|(index, (path, repr))| {
let next = index.checked_add(1)?;
(!rules
.iter()
.skip(next)
.any(|(later, _)| context::matches_proto_prefix(later, path)))
.then_some(repr)
})
}
pub fn generate(
file_descriptors: &[FileDescriptorProto],
files_to_generate: &[String],
config: &CodeGenConfig,
) -> Result<Vec<GeneratedFile>, CodeGenError> {
Ok(generate_with_diagnostics(file_descriptors, files_to_generate, config)?.0)
}
#[derive(Clone, Copy, PartialEq, Eq)]
enum CustomElemKind {
String,
Bytes,
}
#[derive(Default)]
struct CustomElements {
elements: std::collections::BTreeMap<String, CustomElemKind>,
map_keys: std::collections::BTreeSet<String>,
}
fn collect_custom_elements(
ctx: &context::CodeGenContext,
file_descriptors: &[FileDescriptorProto],
files_to_generate: &[String],
all_fields: bool,
) -> CustomElements {
use crate::generated::descriptor::field_descriptor_proto::{Label, Type};
fn walk(
ctx: &context::CodeGenContext,
messages: &[crate::generated::descriptor::DescriptorProto],
scope: &str,
parent_features: &crate::features::ResolvedFeatures,
out: &mut CustomElements,
all_fields: bool,
) {
for msg in messages {
if msg
.options
.as_option()
.and_then(|options| options.map_entry)
.unwrap_or(false)
{
continue;
}
let name = msg.name.as_deref().unwrap_or("");
let fqn = if scope.is_empty() {
name.to_string()
} else {
format!("{scope}.{name}")
};
let msg_features = crate::features::resolve_child(
parent_features,
crate::features::message_features(msg),
);
for field in &msg.field {
if !all_fields && field.label.unwrap_or_default() != Label::LABEL_REPEATED {
continue;
}
let field_name = field.name.as_deref().unwrap_or("");
let field_fqn = format!(".{fqn}.{field_name}");
if let Some(entry) = crate::message::find_map_entry(msg, field) {
let key_ty = crate::message::map_entry_key_type(ctx, entry, &msg_features);
let val_ty = crate::message::map_entry_value_type(ctx, entry, &msg_features);
if let crate::BytesRepr::Custom(path) =
crate::impl_message::map_value_bytes_repr(
ctx, key_ty, val_ty, &fqn, field_name,
)
{
out.elements
.entry(context::rust_type_key(&path))
.or_insert(CustomElemKind::Bytes);
}
if let crate::StringRepr::Custom(path) = ctx.string_repr(&field_fqn) {
if key_ty == Some(Type::TYPE_STRING) {
out.map_keys.insert(context::rust_type_key(&path));
}
if val_ty == Some(Type::TYPE_STRING) {
out.elements
.entry(context::rust_type_key(&path))
.or_insert(CustomElemKind::String);
}
}
continue;
}
let field_features = crate::features::resolve_field(ctx, field, &msg_features);
let ty = crate::impl_message::effective_type(ctx, field, &field_features);
match ty {
Type::TYPE_STRING => {
if let crate::StringRepr::Custom(path) = ctx.string_repr(&field_fqn) {
out.elements
.entry(context::rust_type_key(&path))
.or_insert(CustomElemKind::String);
}
}
Type::TYPE_BYTES => {
if let crate::BytesRepr::Custom(path) = ctx.bytes_repr(&field_fqn) {
out.elements
.entry(context::rust_type_key(&path))
.or_insert(CustomElemKind::Bytes);
}
}
_ => {}
}
}
walk(ctx, &msg.nested_type, &fqn, &msg_features, out, all_fields);
}
}
let mut out = CustomElements::default();
for file_name in files_to_generate {
let Some(file) = file_descriptors
.iter()
.find(|f| f.name.as_deref() == Some(file_name.as_str()))
else {
continue;
};
let pkg = file.package.as_deref().unwrap_or("");
let file_features = crate::features::for_file(file);
walk(
ctx,
&file.message_type,
pkg,
&file_features,
&mut out,
all_fields,
);
}
out
}
fn render_custom_elem_impls(
ctx: &context::CodeGenContext,
elems: &CustomElements,
) -> Result<TokenStream, CodeGenError> {
if !ctx.config.emit_custom_type_impls {
return Ok(TokenStream::new());
}
let json_gate = ctx.config.feature_gates().json;
let reflect_gate = ctx.config.feature_gates().reflect;
let mut out = TokenStream::new();
for (path, kind) in &elems.elements {
let ty = parse_custom_type_path(path)?;
if ctx.config.generate_json
&& *kind == CustomElemKind::Bytes
&& !ctx.is_json_policy_type(path)
{
out.extend(feature_gates::cfg_block(
quote! {
impl ::buffa::json_helpers::ProtoElemJson for #ty {
fn serialize_proto_json<__S: ::serde::Serializer>(
v: &Self,
s: __S,
) -> ::core::result::Result<__S::Ok, __S::Error> {
::buffa::json_helpers::bytes::serialize(
::core::convert::AsRef::<[u8]>::as_ref(v),
s,
)
}
fn deserialize_proto_json<'de, __D: ::serde::Deserializer<'de>>(
d: __D,
) -> ::core::result::Result<Self, __D::Error> {
::buffa::json_helpers::bytes::deserialize(d)
}
}
},
json_gate,
));
}
if ctx.config.generate_reflection_vtable {
let value_ref = match kind {
CustomElemKind::String => quote! {
::buffa_descriptor::reflect::ValueRef::String(
::core::convert::AsRef::<str>::as_ref(self),
)
},
CustomElemKind::Bytes => quote! {
::buffa_descriptor::reflect::ValueRef::Bytes(
::core::convert::AsRef::<[u8]>::as_ref(self),
)
},
};
out.extend(feature_gates::cfg_block(
quote! {
impl ::buffa_descriptor::reflect::ReflectElement for #ty {
fn as_value_ref(&self) -> ::buffa_descriptor::reflect::ValueRef<'_> {
#value_ref
}
}
},
reflect_gate,
));
}
if ctx.config.generate_reflection
&& (ctx.config.generate_zeroize || !ctx.config.zeroize_messages.is_empty())
{
let value = match kind {
CustomElemKind::String => quote! {
::buffa_descriptor::reflect::InspectValueRef::String(self.as_ref())
},
CustomElemKind::Bytes => quote! {
::buffa_descriptor::reflect::InspectValueRef::Bytes(self.as_ref())
},
};
out.extend(feature_gates::cfg_block(
quote! {
impl ::buffa_descriptor::reflect::InspectElement for #ty {
fn as_inspect_value(&self) -> ::buffa_descriptor::reflect::InspectValueRef<'_> {
#value
}
}
},
reflect_gate,
));
}
}
if ctx.config.generate_reflection_vtable
|| (ctx.config.generate_reflection
&& (ctx.config.generate_zeroize || !ctx.config.zeroize_messages.is_empty()))
{
for path in &elems.map_keys {
let ty = parse_custom_type_path(path)?;
out.extend(feature_gates::cfg_block(
quote! {
impl ::buffa_descriptor::reflect::ReflectMapKey for #ty {
fn as_map_key_ref(&self) -> ::buffa_descriptor::reflect::MapKeyRef<'_> {
::buffa_descriptor::reflect::MapKeyRef::String(
::core::convert::AsRef::<str>::as_ref(self),
)
}
}
},
reflect_gate,
));
}
}
Ok(out)
}
#[derive(Clone, Copy)]
struct ExcludedRefScan<'a> {
ctx: &'a context::CodeGenContext<'a>,
extern_paths: &'a [(String, String)],
declared_in_kept: &'a std::collections::HashSet<String>,
file_extern_covered: &'a std::collections::HashSet<String>,
}
fn collect_fqns_in_file(file: &FileDescriptorProto, out: &mut std::collections::HashSet<String>) {
let pkg = file.package.as_deref().unwrap_or("");
for msg in &file.message_type {
let Some(name) = &msg.name else { continue };
let fqn = if pkg.is_empty() {
format!(".{name}")
} else {
format!(".{pkg}.{name}")
};
collect_fqns_msg_recursive(&fqn, msg, out);
}
for en in &file.enum_type {
let Some(name) = &en.name else { continue };
let fqn = if pkg.is_empty() {
format!(".{name}")
} else {
format!(".{pkg}.{name}")
};
out.insert(fqn);
}
}
fn collect_fqns_msg_recursive(
msg_fqn: &str,
msg: &crate::generated::descriptor::DescriptorProto,
out: &mut std::collections::HashSet<String>,
) {
out.insert(msg_fqn.to_string());
for nested in &msg.nested_type {
let Some(name) = &nested.name else { continue };
let nested_fqn = format!("{msg_fqn}.{name}");
collect_fqns_msg_recursive(&nested_fqn, nested, out);
}
for en in &msg.enum_type {
let Some(name) = &en.name else { continue };
out.insert(format!("{msg_fqn}.{name}"));
}
}
fn warn_excluded_refs_type(
scan: ExcludedRefScan<'_>,
file_name: &str,
message_name: &str,
field_name: &str,
type_fqn: &str,
warned: &mut std::collections::HashSet<(String, String)>,
) {
if scan.declared_in_kept.contains(type_fqn) {
return;
}
let Some(ref_package) = scan.ctx.package_of(type_fqn) else {
return;
};
if ref_package.is_empty() {
return;
}
if context::resolve_extern_type(type_fqn, scan.extern_paths).is_some() {
return;
}
if scan.file_extern_covered.contains(type_fqn) {
return;
}
if !warned.insert((file_name.to_string(), type_fqn.to_string())) {
return;
}
scan.ctx.warn(CodeGenWarning::ExcludedPackageFieldRef {
file_name: file_name.to_string(),
message_name: message_name.to_string(),
field_name: field_name.to_string(),
ref_package: ref_package.to_string(),
type_fqn: type_fqn.to_string(),
});
}
fn warn_excluded_refs_field(
scan: ExcludedRefScan<'_>,
file_name: &str,
field: &crate::generated::descriptor::FieldDescriptorProto,
message_name: &str,
warned: &mut std::collections::HashSet<(String, String)>,
) {
let Some(type_fqn) = field.type_name.as_deref().filter(|s| !s.is_empty()) else {
return;
};
warn_excluded_refs_type(
scan,
file_name,
message_name,
field.name.as_deref().unwrap_or("?"),
type_fqn,
warned,
);
}
fn warn_excluded_refs_msg(
scan: ExcludedRefScan<'_>,
file_name: &str,
msg: &crate::generated::descriptor::DescriptorProto,
parent_path: &str,
warned: &mut std::collections::HashSet<(String, String)>,
) {
let msg_name = msg.name.as_deref().unwrap_or("?");
let message_path = if parent_path.is_empty() {
msg_name.to_string()
} else {
format!("{parent_path}.{msg_name}")
};
use crate::generated::descriptor::field_descriptor_proto::Label;
for field in &msg.field {
warn_excluded_refs_field(scan, file_name, field, &message_path, warned);
let is_repeated = field.label.unwrap_or_default() == Label::LABEL_REPEATED;
if is_repeated && crate::message::is_map_field(msg, field) {
if let Ok((_, value_field)) = crate::impl_message::find_map_entry_fields(msg, field) {
if let Some(type_fqn) = value_field.type_name.as_deref().filter(|s| !s.is_empty()) {
warn_excluded_refs_type(
scan,
file_name,
&message_path,
field.name.as_deref().unwrap_or("?"),
type_fqn,
warned,
);
}
}
}
}
for ext in &msg.extension {
warn_excluded_refs_field(scan, file_name, ext, &message_path, warned);
}
for nested in &msg.nested_type {
if nested
.options
.as_option()
.and_then(|o| o.map_entry)
.unwrap_or(false)
{
continue;
}
warn_excluded_refs_msg(scan, file_name, nested, &message_path, warned);
}
}
pub fn generate_with_diagnostics(
file_descriptors: &[FileDescriptorProto],
files_to_generate: &[String],
config: &CodeGenConfig,
) -> Result<(Vec<GeneratedFile>, Vec<CodeGenWarning>), CodeGenError> {
if config.generate_reflection_vtable && !config.generate_reflection {
return Err(CodeGenError::Other(
"generate_reflection_vtable requires generate_reflection to be enabled \
(it provides the descriptor pool the reflect impls resolve against)"
.into(),
));
}
if config.shared_descriptor_pool && !config.generate_reflection {
return Err(CodeGenError::Other(
"shared_descriptor_pool requires generate_reflection to be enabled \
(it deduplicates the embedded reflection descriptor pool)"
.into(),
));
}
if let Some(root) = &config.shared_descriptor_pool_root {
if !config.shared_descriptor_pool {
return Err(CodeGenError::Other(
"shared_descriptor_pool_root requires shared_descriptor_pool to be \
enabled (it overrides the path to the shared root, which only exists \
in shared-pool mode)"
.into(),
));
}
validate_shared_root_path(root)?;
}
if config.idiomatic_imports && !config.file_per_package {
return Err(CodeGenError::Other(
"idiomatic_imports requires file_per_package to be enabled (the multi-file \
layout include!-merges every proto's content into the shared package root, \
where emitted `use` directives could collide across files)"
.into(),
));
}
if let Err((kind, name)) = config.feature_gates().validate() {
return Err(CodeGenError::Other(format!(
"invalid {kind} feature-gate name {name:?}: a Cargo feature name starts \
with an ASCII alphanumeric or '_' and contains only alphanumerics, \
'_', '-', '+', or '.'; an invalid name would leave the emitted \
#[cfg(feature = ...)] permanently false, silently compiling the \
gated impls away"
)));
}
config.validate_type_name_prefix()?;
context::validate_custom_attributes(config)?;
let normalized_excludes: Vec<String> = config
.exclude_packages
.iter()
.map(|entry| {
normalize_exclude_package(entry)
.map_err(|e| CodeGenError::Other(format!("exclude_package {entry:?}: {e}")))
})
.collect::<Result<_, _>>()?;
let effective_files_to_generate: std::borrow::Cow<'_, [String]> =
if normalized_excludes.is_empty() {
std::borrow::Cow::Borrowed(files_to_generate)
} else {
std::borrow::Cow::Owned(
files_to_generate
.iter()
.filter(|name| {
match file_descriptors
.iter()
.find(|fd| fd.name.as_deref() == Some(name.as_str()))
{
Some(fd) => !package_is_excluded(
fd.package.as_deref().unwrap_or(""),
&normalized_excludes,
),
None => true,
}
})
.cloned()
.collect(),
)
};
let files_to_generate: &[String] = &effective_files_to_generate;
let overridden =
feature_overrides::apply_feature_overrides(file_descriptors, &config.feature_overrides);
let file_descriptors: &[FileDescriptorProto] =
overridden.as_ref().map_or(file_descriptors, |o| &o.files);
if let Some(shared) = &config.shared_corpus_context {
shared.check(file_descriptors, config)?;
}
let ctx = context::CodeGenContext::for_generate(file_descriptors, files_to_generate, config);
if let Some(o) = &overridden {
for (rule, ovr) in &o.unmatched {
ctx.warn(CodeGenWarning::FeatureOverrideMatchedNothing {
rule: rule.clone(),
feature: ovr.feature_name(),
value: ovr.value_name(),
});
}
}
for (rule, _) in &config.preserve_unknown_fields_in {
if !rule_matches_generated_message(rule, file_descriptors, files_to_generate) {
ctx.warn(CodeGenWarning::PreserveUnknownFieldsRuleMatchedNothing {
rule: rule.clone(),
});
}
}
let known_files = file_descriptors
.iter()
.filter_map(|file| file.name.clone())
.collect::<Vec<_>>();
for rule in &config.zeroize_messages {
if rule.trim().is_empty() {
return Err(CodeGenError::ZeroizeRuleMatchedNothing { rule: rule.clone() });
}
if !rule_matches_generated_message(rule, file_descriptors, &known_files) {
if config.allow_unmatched_message_rules {
ctx.warn(CodeGenWarning::ZeroizeRuleMatchedNothing { rule: rule.clone() });
} else {
return Err(CodeGenError::ZeroizeRuleMatchedNothing { rule: rule.clone() });
}
}
}
for rule in &config.deny_view_json {
if rule.trim().is_empty() {
return Err(CodeGenError::ViewJsonRuleMatchedNothing { rule: rule.clone() });
}
if !rule_matches_generated_message(rule, file_descriptors, &known_files) {
if config.allow_unmatched_message_rules {
ctx.warn(CodeGenWarning::ViewJsonRuleMatchedNothing { rule: rule.clone() });
} else {
return Err(CodeGenError::ViewJsonRuleMatchedNothing { rule: rule.clone() });
}
}
}
for (rule_index, rule) in config.borrowed_views_only_in.iter().enumerate() {
if rule.trim().is_empty() {
return Err(CodeGenError::BorrowedViewsRuleMatchedNothing { rule_index });
}
if !rule_matches_generated_message(rule, file_descriptors, &known_files) {
if config.allow_unmatched_message_rules {
ctx.warn(CodeGenWarning::BorrowedViewsRuleMatchedNothing { rule: rule.clone() });
} else {
return Err(CodeGenError::BorrowedViewsRuleMatchedNothing { rule_index });
}
}
}
if !config.deny_view_json.is_empty() && (!config.generate_json || !config.generate_views) {
ctx.warn(CodeGenWarning::ViewJsonRulesRequireJsonAndViews);
}
if !config.json_policy_types.is_empty() && !config.generate_json {
ctx.warn(CodeGenWarning::JsonPolicyTypesRequireJson);
}
let representation_types = unshadowed_rules(&config.bytes_fields)
.filter_map(|repr| match repr {
BytesRepr::Custom(path) => Some(path),
_ => None,
})
.chain(
unshadowed_rules(&config.string_fields).filter_map(|repr| match repr {
StringRepr::Custom(path) => Some(path),
_ => None,
}),
)
.collect::<Vec<_>>();
for rust_type in &config.json_policy_types {
let key = context::rust_type_key(rust_type);
let selected = representation_types
.iter()
.any(|path| context::rust_type_key(path) == key);
if !selected {
return Err(CodeGenError::JsonPolicyTypeMatchedNothing {
rust_type: rust_type.clone(),
});
}
}
for selected in representation_types {
if config
.json_policy_types
.iter()
.any(|listed| context::rust_type_key(listed) == context::rust_type_key(selected))
{
continue;
}
let Some(selected_name) = context::rust_type_name(selected) else {
continue;
};
if let Some(listed) = config.json_policy_types.iter().find(|listed| {
context::rust_type_name(listed).as_deref() == Some(selected_name.as_str())
}) {
return Err(CodeGenError::JsonPolicyTypeNearMiss {
selected: selected.clone(),
listed: listed.clone(),
});
}
}
if !config.generate_json
&& (config.deny_unknown_json_fields
|| config
.deny_unknown_json_fields_in
.iter()
.any(|(_, enabled)| *enabled))
{
ctx.warn(CodeGenWarning::DenyUnknownJsonFieldsRequiresJson);
}
for (rule, _) in &config.deny_unknown_json_fields_in {
if !rule_matches_generated_message(rule, file_descriptors, files_to_generate) {
ctx.warn(CodeGenWarning::DenyUnknownJsonFieldsRuleMatchedNothing {
rule: rule.clone(),
});
}
}
for rule in &config.skip_debug {
if !rule_matches_generated_message(rule, file_descriptors, files_to_generate)
&& !rule_names_generated_enum(rule, file_descriptors, files_to_generate)
{
ctx.warn(CodeGenWarning::SkipDebugRuleMatchedNothing { rule: rule.clone() });
}
}
let field_type_rules = [
("bytes_fields", rule_paths(&config.bytes_fields)),
("string_fields", rule_paths(&config.string_fields)),
("map_fields", rule_paths(&config.map_fields)),
("repeated_fields", rule_paths(&config.repeated_fields)),
];
let mut every_file: Option<Vec<String>> = None;
for (option, rules) in field_type_rules {
for rule in rules {
if rule_matches_field_in(rule, file_descriptors, files_to_generate) {
continue;
}
let every_file: &[String] = every_file.get_or_insert_with(|| {
file_descriptors
.iter()
.filter_map(|fd| fd.name.clone())
.collect()
});
ctx.warn(CodeGenWarning::FieldTypeRuleMatchedNothing {
rule: rule.clone(),
option,
matches_ungenerated: rule_matches_field_in(rule, file_descriptors, every_file),
names_extension: rule_matches_extension_in(rule, file_descriptors),
});
}
}
for (rule, _) in &config.codec_strategy_in {
if !rule_matches_generated_message(rule, file_descriptors, files_to_generate) {
ctx.warn(CodeGenWarning::CodecStrategyRuleMatchedNothing { rule: rule.clone() });
}
}
for (file, _) in generated_files(file_descriptors, files_to_generate) {
check_field_numbers(&file.message_type, file.package.as_deref().unwrap_or(""))?;
}
if ctx.table_codec_requested() {
ctx.plan_table_codec(file_descriptors, files_to_generate)?;
}
if config.lazy_views && !config.generate_views {
ctx.warn(CodeGenWarning::LazyViewsRequireViews);
}
for package in &normalized_excludes {
let matched = file_descriptors.iter().any(|fd| {
package_is_excluded(
fd.package.as_deref().unwrap_or(""),
std::slice::from_ref(package),
)
});
if !matched {
ctx.warn(CodeGenWarning::ExcludePackageMatchedNothing {
package: package.clone(),
});
}
}
let mut by_package: std::collections::BTreeMap<String, Vec<&FileDescriptorProto>> =
std::collections::BTreeMap::new();
let mut grouped = std::collections::HashSet::new();
for file_name in files_to_generate {
if !grouped.insert(file_name.as_str()) {
continue;
}
let file_desc = file_descriptors
.iter()
.find(|f| f.name.as_deref() == Some(file_name.as_str()))
.ok_or_else(|| CodeGenError::FileNotFound(file_name.clone()))?;
let pkg = file_desc.package.as_deref().unwrap_or("").to_string();
by_package.entry(pkg).or_default().push(file_desc);
}
{
let extern_paths = effective_extern_paths(file_descriptors, files_to_generate, config);
let mut declared_in_kept: std::collections::HashSet<String> =
std::collections::HashSet::new();
for files in by_package.values() {
for &file in files {
collect_fqns_in_file(file, &mut declared_in_kept);
}
}
let file_extern_paths = effective_file_extern_paths(files_to_generate, config);
let mut file_extern_covered: std::collections::HashSet<String> =
std::collections::HashSet::new();
for (fe_file, _) in &file_extern_paths {
if let Some(fd) = file_descriptors
.iter()
.find(|f| f.name.as_deref() == Some(fe_file.as_str()))
{
collect_fqns_in_file(fd, &mut file_extern_covered);
}
}
let scan = ExcludedRefScan {
ctx: &ctx,
extern_paths: &extern_paths,
declared_in_kept: &declared_in_kept,
file_extern_covered: &file_extern_covered,
};
let mut warned: std::collections::HashSet<(String, String)> =
std::collections::HashSet::new();
for files in by_package.values() {
for &file in files {
let file_name = file.name.as_deref().unwrap_or("?");
for msg in &file.message_type {
warn_excluded_refs_msg(scan, file_name, msg, "", &mut warned);
}
for ext in &file.extension {
warn_excluded_refs_field(scan, file_name, ext, "", &mut warned);
}
}
}
}
if config.shared_descriptor_pool && config.shared_descriptor_pool_root.is_none() {
validate_shared_root_name(file_descriptors, files_to_generate)?;
}
let fds_bytes = if config.generate_reflection && !config.shared_descriptor_pool {
reflect::encode_fds_once(file_descriptors)
} else {
Vec::new()
};
let custom_elems = collect_custom_elements(&ctx, file_descriptors, files_to_generate, false);
let custom_elem_impls = render_custom_elem_impls(&ctx, &custom_elems)?;
let empty_impls = TokenStream::new();
let mut output = Vec::new();
let mut output_names = OutputNames::default();
let mut custom_emitted = false;
for (package, files) in by_package {
let impls = if custom_emitted {
&empty_impls
} else {
custom_emitted = true;
&custom_elem_impls
};
generate_package(
&ctx,
&package,
&files,
&fds_bytes,
impls,
&mut output_names,
&mut output,
)?;
}
if config.generate_json && config.generate_reflection {
let policy_types = ctx.used_json_policy_types();
if !policy_types.is_empty() {
ctx.warn(CodeGenWarning::JsonPolicyReflectionBypass { policy_types });
}
}
let mut native_config = config.adapters.clone();
if config.generate_adapters {
let from_schema = adapters::descriptor_options(file_descriptors, files_to_generate)?;
native_config = match (from_schema, native_config) {
(Some(mut from_schema), Some(mut explicit)) => {
explicit.selectors.append(&mut from_schema.selectors);
explicit.payloads.append(&mut from_schema.payloads);
explicit.borrowed.append(&mut from_schema.borrowed);
explicit.ports.append(&mut from_schema.ports);
Some(explicit)
}
(from_schema, explicit) => from_schema.or(explicit),
};
if native_config.is_none() {
return Err(
adapters::AdapterError::from(adapters::ErrorReason::MissingSchemaAdapters).into(),
);
}
}
if let Some(adapters) = &native_config {
let native = adapters::generate_adapters(file_descriptors, files_to_generate, adapters)?;
for file in native {
if output
.iter()
.any(|existing| existing.name.eq_ignore_ascii_case(&file.name))
{
return Err(
adapters::AdapterError::from(adapters::ErrorReason::DuplicateOutput).into(),
);
}
output.push(file);
}
}
Ok((output, ctx.take_warnings()))
}
#[derive(Default)]
struct OutputNames(std::collections::HashMap<String, String>);
impl OutputNames {
fn claim(&mut self, file_name: &str, source: String) -> Result<(), CodeGenError> {
use std::collections::hash_map::Entry;
match self.0.entry(file_name.to_owned()) {
Entry::Occupied(first) => Err(CodeGenError::OutputFileNameConflict {
file_name: file_name.to_owned(),
first_source: first.get().clone(),
second_source: source,
}),
Entry::Vacant(slot) => {
slot.insert(source);
Ok(())
}
}
}
}
pub fn generate_module_tree<F: AsRef<str>, P: AsRef<str>>(
entries: &[(F, P)],
include_mode: IncludeMode<'_>,
emit_inner_allow: bool,
) -> String {
use std::collections::BTreeMap;
use std::fmt::Write;
use crate::idents::escape_mod_ident;
#[derive(Default)]
struct ModNode {
files: Vec<String>,
children: BTreeMap<String, Self>,
}
let mut root = ModNode::default();
for (file_name, package) in entries {
let package = package.as_ref();
let pkg_parts: Vec<&str> = if package.is_empty() {
vec![]
} else {
package.split('.').collect()
};
let mut node = &mut root;
for seg in &pkg_parts {
node = node.children.entry(seg.to_string()).or_default();
}
node.files.push(file_name.as_ref().to_string());
}
let lints = ALLOW_LINTS.join(", ");
let mut out = String::new();
out.push_str(GENERATED_HEADER);
if emit_inner_allow {
let _ = writeln!(out, "#![allow({lints})]");
}
let _ = writeln!(out);
fn emit(out: &mut String, node: &ModNode, depth: usize, mode: IncludeMode<'_>, lints: &str) {
let indent = " ".repeat(depth);
for file in &node.files {
match mode {
IncludeMode::Relative(prefix) => {
let path = format!("{prefix}{file}");
let _ = writeln!(out, "{indent}include!({path:?});");
}
IncludeMode::OutDir => {
let path = format!("/{file}");
let _ = writeln!(
out,
"{indent}include!(concat!(env!(\"OUT_DIR\"), {path:?}));"
);
}
}
}
for (name, child) in &node.children {
let escaped = escape_mod_ident(name);
let _ = writeln!(out, "{indent}#[allow({lints})]");
let _ = writeln!(out, "{indent}pub mod {escaped} {{");
let _ = writeln!(out, "{indent} use super::*;");
emit(out, child, depth + 1, mode, lints);
let _ = writeln!(out, "{indent}}}");
}
}
emit(&mut out, &root, 0, include_mode, &lints);
out
}
#[derive(Debug, Clone, Copy)]
pub enum IncludeMode<'a> {
Relative(&'a str),
OutDir,
}
#[derive(Clone)]
pub struct SharedCorpusContext {
files: std::sync::Arc<Vec<generated::descriptor::FileDescriptorProto>>,
unboxed_oneof_fields: std::sync::Arc<Vec<String>>,
pointer_fields: std::sync::Arc<Vec<(String, PointerRepr)>>,
unboxed_oneof_variants: std::sync::Arc<std::collections::HashSet<String>>,
inlined_message_fields: std::sync::Arc<std::collections::HashSet<String>>,
comment_map: std::sync::Arc<std::collections::HashMap<String, String>>,
}
impl SharedCorpusContext {
#[must_use]
pub fn new(
files: &[generated::descriptor::FileDescriptorProto],
config: &CodeGenConfig,
) -> Self {
let msg_index = oneof::message_index(files);
let unboxed_oneof_variants = oneof::resolve_unboxed_variants(
&msg_index,
&config.unboxed_oneof_fields,
&config.pointer_fields,
);
let inlined_message_fields = oneof::resolve_inlined_fields(
&msg_index,
&config.unboxed_oneof_fields,
&config.pointer_fields,
);
let comment_map = files.iter().flat_map(comments::fqn_comments).collect();
Self {
files: std::sync::Arc::new(files.to_vec()),
unboxed_oneof_fields: std::sync::Arc::new(config.unboxed_oneof_fields.clone()),
pointer_fields: std::sync::Arc::new(config.pointer_fields.clone()),
unboxed_oneof_variants: std::sync::Arc::new(unboxed_oneof_variants),
inlined_message_fields: std::sync::Arc::new(inlined_message_fields),
comment_map: std::sync::Arc::new(comment_map),
}
}
pub(crate) fn check(
&self,
files: &[generated::descriptor::FileDescriptorProto],
config: &CodeGenConfig,
) -> Result<(), CodeGenError> {
let what = if *files != self.files[..] {
"files"
} else if *self.unboxed_oneof_fields != config.unboxed_oneof_fields {
"unboxed_oneof_fields"
} else if *self.pointer_fields != config.pointer_fields {
"pointer_fields"
} else {
return Ok(());
};
Err(CodeGenError::SharedCorpusContextMismatch { what })
}
pub(crate) fn unboxed_oneof_variants(
&self,
) -> &std::sync::Arc<std::collections::HashSet<String>> {
&self.unboxed_oneof_variants
}
pub(crate) fn inlined_message_fields(
&self,
) -> &std::sync::Arc<std::collections::HashSet<String>> {
&self.inlined_message_fields
}
pub(crate) fn comment_map(&self) -> &std::sync::Arc<std::collections::HashMap<String, String>> {
&self.comment_map
}
}
impl core::fmt::Debug for SharedCorpusContext {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.debug_struct("SharedCorpusContext")
.field("files", &self.files.len())
.field("unboxed_oneof_variants", &self.unboxed_oneof_variants.len())
.field("inlined_message_fields", &self.inlined_message_fields.len())
.field("comments", &self.comment_map.len())
.finish()
}
}
#[must_use]
pub fn encode_descriptor_set(
file_descriptors: &[generated::descriptor::FileDescriptorProto],
feature_overrides: &[(String, FeatureOverride)],
) -> Vec<u8> {
let overridden =
feature_overrides::apply_feature_overrides(file_descriptors, feature_overrides);
let files = overridden.as_ref().map_or(file_descriptors, |o| &o.files);
reflect::encode_fds_once(files)
}
#[derive(Debug, Clone, Copy)]
#[non_exhaustive]
pub enum FdsEmbedding<'a> {
Inline,
Sidecar {
file_name: &'a str,
mode: IncludeMode<'a>,
},
}
#[must_use]
pub fn shared_descriptor_root_module(
fds_bytes: &[u8],
embedding: FdsEmbedding<'_>,
gate: Option<&str>,
) -> String {
let source = match embedding {
FdsEmbedding::Inline => reflect::FdsSource::Inline(fds_bytes),
FdsEmbedding::Sidecar {
file_name,
mode: IncludeMode::Relative(prefix),
} => {
let path = format!("{prefix}{file_name}");
reflect::FdsSource::IncludeBytes(quote::quote! { #path })
}
FdsEmbedding::Sidecar {
file_name,
mode: IncludeMode::OutDir,
} => {
let slash_name = format!("/{file_name}");
reflect::FdsSource::IncludeBytes(
quote::quote! { concat!(env!("OUT_DIR"), #slash_name) },
)
}
};
let tokens = feature_gates::cfg_block(reflect::shared_root_module(source), gate);
let file = syn::parse2::<syn::File>(tokens)
.expect("shared descriptor root module must parse as a Rust file");
prettyplease::unparse(&file)
}
fn validate_shared_root_path(path: &str) -> Result<(), CodeGenError> {
let is_absolute = path.starts_with("::");
let is_crate_relative = path == "crate" || path.starts_with("crate::");
if !is_absolute && !is_crate_relative {
return Err(CodeGenError::Other(format!(
"shared_descriptor_pool_root must be an absolute (`::`-prefixed) or \
crate-relative (`crate`-prefixed) path — the same value is spliced \
verbatim at every package depth, so a plain relative path would only \
be correct from one depth: {path:?}"
)));
}
let rest = path.strip_prefix("::").unwrap_or(path);
if rest.is_empty() {
return Err(CodeGenError::Other(format!(
"shared_descriptor_pool_root has no path after the `::` prefix: {path:?}"
)));
}
for (i, segment) in rest.split("::").enumerate() {
let mut chars = segment.chars();
let is_ident = chars
.next()
.is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
&& chars.all(|c| c.is_ascii_alphanumeric() || c == '_');
if !is_ident {
return Err(CodeGenError::Other(format!(
"shared_descriptor_pool_root segment {segment:?} is not a plain \
identifier (no generic or parenthesized arguments, ASCII only) — \
the value is spliced verbatim into generated code: {path:?}"
)));
}
let is_path_keyword =
matches!(segment, "_" | "self" | "Self" | "super") || (i > 0 && segment == "crate");
if is_path_keyword {
return Err(CodeGenError::Other(format!(
"shared_descriptor_pool_root segment {segment:?} is a path keyword \
and cannot be spliced into generated code: {path:?}"
)));
}
}
Ok(())
}
fn validate_shared_root_name(
files: &[FileDescriptorProto],
files_to_generate: &[String],
) -> Result<(), CodeGenError> {
use std::collections::HashSet;
let reserved = reflect::SHARED_ROOT_MOD;
let generated: HashSet<&str> = files_to_generate.iter().map(String::as_str).collect();
let reserved_err = |location: String| CodeGenError::ReservedModuleName {
name: reserved.to_string(),
location,
};
for file in files {
if !generated.contains(file.name.as_deref().unwrap_or("")) {
continue;
}
let package = file.package.as_deref().unwrap_or("");
if package.split('.').any(|seg| seg == reserved) {
return Err(reserved_err(format!(
"package '{package}' (reserved by shared_descriptor_pool)"
)));
}
if package.is_empty() {
for m in &file.message_type {
let name = m.name.as_deref().unwrap_or("");
if crate::oneof::to_snake_case(name) == reserved {
return Err(reserved_err(format!(
"message '{name}' (its module `{reserved}` is reserved by \
shared_descriptor_pool)"
)));
}
}
for e in &file.enum_type {
if e.name.as_deref() == Some(reserved) {
return Err(reserved_err(format!(
"enum '{reserved}' (reserved by shared_descriptor_pool)"
)));
}
}
}
}
Ok(())
}
fn check_type_names<'a>(
scope: &str,
names: impl Iterator<Item = &'a str>,
type_name_prefix: &str,
) -> Result<(), CodeGenError> {
let mut seen: std::collections::HashMap<String, &str> = std::collections::HashMap::new();
for name in names.filter(|name| !name.is_empty()) {
let rust_name = idents::local_type_name(type_name_prefix, name);
if let Some(first) = seen.insert(rust_name.clone(), name) {
return Err(CodeGenError::TypeNameConflict {
scope: scope.to_string(),
first_type: first.to_string(),
second_type: name.to_string(),
rust_name,
});
}
}
Ok(())
}
fn check_field_numbers(
messages: &[crate::generated::descriptor::DescriptorProto],
scope: &str,
) -> Result<(), CodeGenError> {
for msg in messages {
let name = msg.name.as_deref().unwrap_or("");
let fqn = if scope.is_empty() {
name.to_string()
} else {
format!("{scope}.{name}")
};
let mut seen: std::collections::HashMap<i32, &str> = std::collections::HashMap::new();
for field in &msg.field {
let Some(number) = field.number else {
continue;
};
let field_name = field.name.as_deref().unwrap_or("");
if let Some(first) = seen.insert(number, field_name) {
return Err(CodeGenError::DuplicateFieldNumber {
message_name: fqn,
first_field: first.to_string(),
second_field: field_name.to_string(),
number,
});
}
}
check_field_numbers(&msg.nested_type, &fqn)?;
}
Ok(())
}
fn validate_file(file: &FileDescriptorProto, type_name_prefix: &str) -> Result<(), CodeGenError> {
use std::collections::HashMap;
let sentinel = context::SENTINEL_MOD;
let package = file.package.as_deref().unwrap_or("");
if package.split('.').any(|seg| seg == sentinel) {
return Err(CodeGenError::ReservedModuleName {
name: sentinel.to_string(),
location: format!("package '{package}'"),
});
}
for enum_type in &file.enum_type {
let name = required_type_name(enum_type.name.as_deref(), "enum.name")?;
if name == sentinel {
return Err(CodeGenError::ReservedModuleName {
name: sentinel.to_string(),
location: format!("enum '{package}.{name}'"),
});
}
}
fn walk(
messages: &[crate::generated::descriptor::DescriptorProto],
scope: &str,
sentinel: &str,
type_name_prefix: &str,
) -> Result<(), CodeGenError> {
let mut seen: HashMap<String, &str> = HashMap::new();
for msg in messages {
let name = required_type_name(msg.name.as_deref(), "message.name")?;
let fqn = if scope.is_empty() {
name.to_string()
} else {
format!("{scope}.{name}")
};
for enum_type in &msg.enum_type {
required_type_name(enum_type.name.as_deref(), "enum.name")?;
}
check_type_names(
&fqn,
msg.nested_type
.iter()
.filter_map(|m| m.name.as_deref())
.chain(msg.enum_type.iter().filter_map(|e| e.name.as_deref())),
type_name_prefix,
)?;
for field in &msg.field {
if let Some(fname) = &field.name {
if fname.starts_with("__buffa_") {
return Err(CodeGenError::ReservedFieldName {
message_name: fqn,
field_name: fname.clone(),
});
}
}
}
let module_name = crate::oneof::to_snake_case(name);
if module_name == sentinel {
return Err(CodeGenError::ReservedModuleName {
name: sentinel.to_string(),
location: format!("message '{fqn}'"),
});
}
if let Some(existing) = seen.get(&module_name) {
return Err(CodeGenError::ModuleNameConflict {
scope: scope.to_string(),
name_a: existing.to_string(),
name_b: name.to_string(),
module_name,
});
}
seen.insert(module_name, name);
walk(&msg.nested_type, &fqn, sentinel, type_name_prefix)?;
}
Ok(())
}
walk(&file.message_type, package, sentinel, type_name_prefix)
}
fn required_type_name<'a>(
name: Option<&'a str>,
field: &'static str,
) -> Result<&'a str, CodeGenError> {
name.filter(|name| !name.is_empty())
.ok_or(CodeGenError::MissingField(field))
}
struct ProtoContent {
stem: String,
owned: TokenStream,
view: TokenStream,
lazy_view: TokenStream,
oneof: TokenStream,
view_oneof: TokenStream,
ext: TokenStream,
root_reexports: Vec<message::ReexportCandidate>,
}
fn generate_proto_content(
ctx: &context::CodeGenContext,
current_package: &str,
file: &FileDescriptorProto,
reg: &mut message::RegistryPaths,
) -> Result<ProtoContent, CodeGenError> {
use crate::idents::make_field_ident;
use crate::message::MessageOutput;
validate_file(file, &ctx.config.type_name_prefix)?;
let resolver = imports::ImportResolver::new();
let features = crate::features::for_file(file);
let mut owned = TokenStream::new();
let mut view = TokenStream::new();
let mut lazy_view = TokenStream::new();
let mut oneof = TokenStream::new();
let mut view_oneof = TokenStream::new();
let mut ext = TokenStream::new();
let mut root_reexports: Vec<message::ReexportCandidate> = Vec::new();
let sentinel = make_field_ident(context::SENTINEL_MOD);
for enum_type in &file.enum_type {
let enum_proto_name = enum_type.name.as_deref().unwrap_or("");
let enum_rust_name = ctx.config.prefixed_type_name(enum_proto_name);
let enum_fqn = if current_package.is_empty() {
enum_proto_name.to_string()
} else {
format!("{}.{}", current_package, enum_proto_name)
};
owned.extend(enumeration::generate_enum(
ctx,
enum_type,
&enum_rust_name,
&enum_fqn,
&features,
&resolver,
)?);
}
for message_type in &file.message_type {
let top_level_name = message_type.name.as_deref().unwrap_or("");
let rust_name = ctx.config.prefixed_type_name(top_level_name);
let proto_fqn = if current_package.is_empty() {
top_level_name.to_string()
} else {
format!("{}.{}", current_package, top_level_name)
};
let MessageOutput {
owned_top,
owned_mod,
oneof_tree: msg_oneof,
view_tree: msg_view,
lazy_view_tree: msg_lazy_view,
view_oneof_tree: msg_view_oneof,
reg: msg_reg,
} = message::generate_message(
ctx,
message_type,
current_package,
&rust_name,
&proto_fqn,
&crate::features::message_scope_features(&features, message_type, true),
&resolver,
)?;
owned.extend(owned_top);
let mod_name = ctx.nested_module_name(current_package, top_level_name);
let mod_ident = make_field_ident(&mod_name);
let mod_doc = message::module_rename_doc(top_level_name, &mod_name);
for p in msg_reg.json_ext {
reg.json_ext.push(quote! { #mod_ident :: #p });
}
for p in msg_reg.text_ext {
reg.text_ext.push(quote! { #mod_ident :: #p });
}
reg.json_any.extend(msg_reg.json_any);
reg.text_any.extend(msg_reg.text_any);
if !owned_mod.is_empty() {
owned.extend(quote! {
#mod_doc
pub mod #mod_ident {
#[allow(unused_imports)]
use super::*;
#owned_mod
}
});
}
oneof.extend(msg_oneof);
view.extend(msg_view);
lazy_view.extend(msg_lazy_view);
view_oneof.extend(msg_view_oneof);
if ctx.config.generate_views {
let view_ident = format_ident!("{rust_name}View");
root_reexports.push(message::ReexportCandidate {
name: view_ident.to_string(),
tokens: feature_gates::cfg_block(
quote! {
#[doc(inline)]
pub use self :: #sentinel :: view :: #view_ident;
},
ctx.config.feature_gates().views,
),
});
if !ctx.borrowed_views_only(&proto_fqn) {
let owned_view_ident = format_ident!("{rust_name}OwnedView");
root_reexports.push(message::ReexportCandidate {
name: owned_view_ident.to_string(),
tokens: feature_gates::cfg_block(
quote! {
#[doc(inline)]
pub use self :: #sentinel :: view :: #owned_view_ident;
},
ctx.config.feature_gates().views,
),
});
}
if ctx.config.lazy_views {
let lazy_ident = format_ident!("{rust_name}LazyView");
root_reexports.push(message::ReexportCandidate {
name: lazy_ident.to_string(),
tokens: feature_gates::cfg_block(
quote! {
#[doc(inline)]
pub use self :: #sentinel :: lazy_view :: #lazy_ident;
},
ctx.config.feature_gates().views,
),
});
}
}
}
let (file_ext_tokens, file_ext_json, file_ext_text) = extension::generate_extensions(
ctx,
&file.extension,
current_package,
2,
&features,
current_package,
)?;
ext.extend(file_ext_tokens);
for id in file_ext_json {
reg.json_ext.push(quote! { #sentinel :: ext :: #id });
}
for id in file_ext_text {
reg.text_ext.push(quote! { #sentinel :: ext :: #id });
}
for ext_field in &file.extension {
let const_ident = extension::extension_const_ident(ext_field.name.as_deref().unwrap_or(""));
root_reexports.push(message::ReexportCandidate {
name: const_ident.to_string(),
tokens: quote! {
#[doc(inline)]
pub use self :: #sentinel :: ext :: #const_ident;
},
});
}
Ok(ProtoContent {
stem: proto_path_to_stem(file.name.as_deref().unwrap_or("")),
owned,
view,
lazy_view,
oneof,
view_oneof,
ext,
root_reexports,
})
}
#[derive(Default)]
struct PackageSections {
owned: Vec<TokenStream>,
view: Vec<TokenStream>,
lazy_view: Vec<TokenStream>,
oneof: Vec<TokenStream>,
view_oneof: Vec<TokenStream>,
ext: Vec<TokenStream>,
}
impl PackageSections {
fn push_inline(&mut self, pc: ProtoContent) {
let push_if_nonempty = |dst: &mut Vec<TokenStream>, ts: TokenStream| {
if !ts.is_empty() {
dst.push(ts);
}
};
push_if_nonempty(&mut self.owned, pc.owned);
push_if_nonempty(&mut self.view, pc.view);
push_if_nonempty(&mut self.lazy_view, pc.lazy_view);
push_if_nonempty(&mut self.oneof, pc.oneof);
push_if_nonempty(&mut self.view_oneof, pc.view_oneof);
push_if_nonempty(&mut self.ext, pc.ext);
}
}
fn generate_package(
ctx: &context::CodeGenContext,
current_package: &str,
files: &[&FileDescriptorProto],
fds_bytes: &[u8],
custom_elem_impls: &TokenStream,
output_names: &mut OutputNames,
out: &mut Vec<GeneratedFile>,
) -> Result<(), CodeGenError> {
let mut reg = message::RegistryPaths::default();
let mut root_reexports: Vec<message::ReexportCandidate> = Vec::new();
check_type_names(
current_package,
files.iter().flat_map(|file| {
file.message_type
.iter()
.filter_map(|m| m.name.as_deref())
.chain(file.enum_type.iter().filter_map(|e| e.name.as_deref()))
}),
&ctx.config.type_name_prefix,
)?;
if ctx.config.idiomatic_imports && ctx.config.file_per_package {
ctx.imports_begin_collecting();
let warn_mark = ctx.warnings_len();
let mut scratch_reg = message::RegistryPaths::default();
let mut occupied = root_occupied_names(ctx, files);
for file in files {
let pc = generate_proto_content(ctx, current_package, file, &mut scratch_reg)?;
occupied.extend(pc.root_reexports.into_iter().map(|c| c.name));
}
ctx.truncate_warnings(warn_mark);
occupied.insert("register_types".to_string());
let collected = ctx.imports_take_collected();
ctx.imports_set_resolving(imports::RootImports::assign(&collected, &occupied));
}
let sections = if ctx.config.file_per_package {
let mut sections = PackageSections::default();
for file in files {
let mut pc = generate_proto_content(ctx, current_package, file, &mut reg)?;
root_reexports.append(&mut pc.root_reexports);
sections.push_inline(pc);
}
sections
} else {
let mut sections = PackageSections::default();
for file in files {
let mut pc = generate_proto_content(ctx, current_package, file, &mut reg)?;
root_reexports.append(&mut pc.root_reexports);
let source = file.name.as_deref().unwrap_or("");
let stem = pc.stem;
let emit = |suffix: &str,
kind: GeneratedFileKind,
tokens: TokenStream,
section: &mut Vec<TokenStream>,
output_names: &mut OutputNames,
out: &mut Vec<GeneratedFile>|
-> Result<(), CodeGenError> {
if tokens.is_empty() {
return Ok(());
}
let name = format!("{stem}{suffix}.rs");
output_names.claim(&name, source.to_owned())?;
section.push(quote! { include!(#name); });
out.push(GeneratedFile {
name,
package: current_package.to_string(),
kind,
content: format_tokens(tokens, source)?,
});
Ok(())
};
emit(
"",
GeneratedFileKind::Owned,
pc.owned,
&mut sections.owned,
output_names,
out,
)?;
emit(
".__view",
GeneratedFileKind::View,
pc.view,
&mut sections.view,
output_names,
out,
)?;
emit(
".__lazy_view",
GeneratedFileKind::LazyView,
pc.lazy_view,
&mut sections.lazy_view,
output_names,
out,
)?;
emit(
".__oneof",
GeneratedFileKind::Oneof,
pc.oneof,
&mut sections.oneof,
output_names,
out,
)?;
emit(
".__view_oneof",
GeneratedFileKind::ViewOneof,
pc.view_oneof,
&mut sections.view_oneof,
output_names,
out,
)?;
emit(
".__ext",
GeneratedFileKind::Ext,
pc.ext,
&mut sections.ext,
output_names,
out,
)?;
}
sections
};
let reexport_block = surviving_root_reexports(ctx, files, ®, root_reexports);
let mod_name = if ctx.config.file_per_package {
package_to_filename(current_package)
} else {
package_to_mod_filename(current_package)
};
let mod_source = if current_package.is_empty() {
"the unnamed package".to_owned()
} else {
format!("package {current_package}")
};
output_names.claim(&mod_name, mod_source)?;
out.push(GeneratedFile {
name: mod_name,
package: current_package.to_string(),
kind: GeneratedFileKind::PackageMod,
content: generate_package_mod(
ctx,
current_package,
§ions,
®,
&reexport_block,
fds_bytes,
custom_elem_impls,
)?,
});
ctx.imports_reset();
Ok(())
}
fn root_occupied_names(
ctx: &context::CodeGenContext,
files: &[&FileDescriptorProto],
) -> std::collections::BTreeSet<String> {
let mut occupied = std::collections::BTreeSet::new();
occupied.insert(context::SENTINEL_MOD.to_string());
for file in files {
let package = file.package.as_deref().unwrap_or("");
for m in &file.message_type {
let name = m.name.as_deref().unwrap_or("");
occupied.insert(ctx.config.prefixed_type_name(name));
occupied.insert(ctx.nested_module_name(package, name));
}
for e in &file.enum_type {
occupied.insert(
ctx.config
.prefixed_type_name(e.name.as_deref().unwrap_or("")),
);
}
}
if ctx.config.generate_reflection {
occupied.insert("descriptor_pool".to_string());
occupied.insert("FILE_DESCRIPTOR_SET_BYTES".to_string());
}
occupied
}
fn surviving_root_reexports(
ctx: &context::CodeGenContext,
files: &[&FileDescriptorProto],
reg: &message::RegistryPaths,
mut candidates: Vec<message::ReexportCandidate>,
) -> TokenStream {
use crate::idents::make_field_ident;
let occupied = root_occupied_names(ctx, files);
if ctx.config.emit_register_fn && !reg.is_empty() {
let sentinel = make_field_ident(context::SENTINEL_MOD);
let json_or_text = ctx.config.feature_gates().json_or_text();
candidates.push(message::ReexportCandidate {
name: "register_types".to_string(),
tokens: feature_gates::cfg_block_any(
quote! {
#[doc(inline)]
pub use self :: #sentinel :: register_types;
},
&json_or_text,
),
});
}
message::emit_surviving_reexports(candidates, &occupied)
}
fn generate_package_mod(
ctx: &context::CodeGenContext,
current_package: &str,
sections: &PackageSections,
reg: &message::RegistryPaths,
root_reexports: &TokenStream,
fds_bytes: &[u8],
custom_elem_impls: &TokenStream,
) -> Result<String, CodeGenError> {
use crate::idents::make_field_ident;
let owned = §ions.owned;
let view = §ions.view;
let lazy_view = §ions.lazy_view;
let view_oneof = §ions.view_oneof;
let oneof = §ions.oneof;
let ext = §ions.ext;
let view_oneof_mod = if !view_oneof.is_empty() {
quote! {
pub mod oneof {
#[allow(unused_imports)]
use super::*;
#(#view_oneof)*
}
}
} else {
TokenStream::new()
};
debug_assert!(view_oneof.is_empty() || !view.is_empty());
let view_mod = if ctx.config.generate_views && !view.is_empty() {
feature_gates::cfg_block(
quote! {
pub mod view {
#[allow(unused_imports)]
use super::*;
#(#view)*
#view_oneof_mod
}
},
ctx.config.feature_gates().views,
)
} else {
TokenStream::new()
};
debug_assert!(lazy_view.is_empty() || !view.is_empty());
let lazy_view_mod = if !lazy_view.is_empty() {
feature_gates::cfg_block(
quote! {
pub mod lazy_view {
#[allow(unused_imports)]
use super::*;
#(#lazy_view)*
}
},
ctx.config.feature_gates().views,
)
} else {
TokenStream::new()
};
let oneof_mod = if !oneof.is_empty() {
quote! {
pub mod oneof {
#[allow(unused_imports)]
use super::*;
#(#oneof)*
}
}
} else {
TokenStream::new()
};
let ext_mod = if !ext.is_empty() {
quote! {
pub mod ext {
#[allow(unused_imports)]
use super::*;
#(#ext)*
}
}
} else {
TokenStream::new()
};
let register_fn = if ctx.config.emit_register_fn && !reg.is_empty() {
let gates = ctx.config.feature_gates();
let json_regs = reg
.json_any
.iter()
.map(|p| {
feature_gates::cfg_block(quote! { reg.register_json_any(super::#p); }, gates.json)
})
.chain(reg.json_ext.iter().map(|p| {
feature_gates::cfg_block(quote! { reg.register_json_ext(super::#p); }, gates.json)
}));
let text_regs = reg
.text_any
.iter()
.map(|p| {
feature_gates::cfg_block(quote! { reg.register_text_any(super::#p); }, gates.text)
})
.chain(reg.text_ext.iter().map(|p| {
feature_gates::cfg_block(quote! { reg.register_text_ext(super::#p); }, gates.text)
}));
let allow_unused = if ctx.config.gate_impls_on_crate_features {
quote! { #[allow(unused_variables)] }
} else {
quote! {}
};
feature_gates::cfg_block_any(
quote! {
#allow_unused
pub fn register_types(reg: &mut ::buffa::type_registry::TypeRegistry) {
#(#json_regs)*
#(#text_regs)*
}
},
&gates.json_or_text(),
)
} else {
TokenStream::new()
};
let (reflect_mod, reflect_reexport) = if ctx.config.generate_reflection {
let gate = ctx.config.feature_gates().reflect;
let pool_module = if ctx.config.shared_descriptor_pool {
reflect::reflect_pool_module_shared(
current_package,
ctx.config.shared_descriptor_pool_root.as_deref(),
)
} else {
reflect::reflect_pool_module(fds_bytes)
};
(
feature_gates::cfg_block(pool_module, gate),
reflect::reflect_reexports("e! { __buffa }, gate),
)
} else {
(TokenStream::new(), TokenStream::new())
};
let sentinel = make_field_ident(context::SENTINEL_MOD);
let buffa_mod = if view_mod.is_empty()
&& lazy_view_mod.is_empty()
&& oneof_mod.is_empty()
&& ext_mod.is_empty()
&& register_fn.is_empty()
&& reflect_mod.is_empty()
&& custom_elem_impls.is_empty()
{
TokenStream::new()
} else {
let allow = allow_lints_attr();
quote! {
#allow
pub mod #sentinel {
#[allow(unused_imports)]
use super::*;
#view_mod
#lazy_view_mod
#oneof_mod
#ext_mod
#register_fn
#reflect_mod
#custom_elem_impls
}
}
};
let use_block = ctx.imports_use_block();
let tokens = quote! {
#use_block
#(#owned)*
#buffa_mod
#reflect_reexport
#root_reexports
};
format_tokens(tokens, "")
}
fn format_tokens(tokens: TokenStream, source: &str) -> Result<String, CodeGenError> {
let syntax_tree =
syn::parse2::<syn::File>(tokens).map_err(|e| CodeGenError::InvalidSyntax(e.to_string()))?;
let formatted = prettyplease::unparse(&syntax_tree);
let source_line = if source.is_empty() {
String::new()
} else {
format!("// source: {source}\n")
};
Ok(format!("{GENERATED_HEADER}{source_line}\n{formatted}"))
}
pub fn package_to_mod_filename(package: &str) -> String {
if package.is_empty() {
format!("{}.mod.rs", context::SENTINEL_MOD)
} else {
format!("{package}.mod.rs")
}
}
pub fn package_is_excluded(package: &str, excludes: &[String]) -> bool {
excludes.iter().any(|ex| {
package == ex
|| (package.len() > ex.len()
&& package.starts_with(ex.as_str())
&& package.as_bytes()[ex.len()] == b'.')
})
}
pub fn normalize_exclude_package(value: &str) -> Result<String, String> {
let pkg = value.trim();
let pkg = pkg.strip_prefix('.').unwrap_or(pkg);
if pkg.is_empty() || pkg.split('.').any(str::is_empty) {
return Err(
"'exclude_package' requires a non-empty proto package with no \
empty components, e.g. exclude_package=.buf.validate"
.to_string(),
);
}
Ok(pkg.to_string())
}
pub fn normalize_extern_path_proto_name(value: &str) -> Result<String, String> {
const EXPECTED: &str = "expected '.' or a dotted protobuf package or type name, \
e.g. .my.pkg or .my.pkg.Type";
let given = value.trim();
if given == "." {
return Ok(given.to_string());
}
let name = given.strip_prefix('.').unwrap_or(given);
let name = name.strip_suffix('.').unwrap_or(name);
for segment in name.split('.') {
if segment.is_empty() {
return Err(format!(
"'extern_path' proto name '{given}' has an empty segment; {EXPECTED}"
));
}
let mut chars = segment.chars();
let starts_ok = chars
.next()
.is_some_and(|c| c.is_ascii_alphabetic() || c == '_');
if !(starts_ok && chars.all(|c| c.is_ascii_alphanumeric() || c == '_')) {
return Err(format!(
"'extern_path' proto name '{given}': segment '{segment}' is not a \
protobuf identifier; {EXPECTED}"
));
}
}
Ok(format!(".{name}"))
}
#[cfg(test)]
mod extern_path_proto_name_tests {
use super::normalize_extern_path_proto_name as normalize;
#[test]
fn accepts_and_normalizes_valid_names() {
for (given, normalized) in [
(".", "."),
(".my.common", ".my.common"),
("my.common", ".my.common"),
(".my.common.", ".my.common"),
(" my.v2.Type_1 ", ".my.v2.Type_1"),
("._internal._Foo", "._internal._Foo"),
] {
assert_eq!(normalize(given), Ok(normalized.to_string()), "{given:?}");
}
}
#[test]
fn empty_segment_error_quotes_the_name_as_given() {
for given in [
"",
"..",
"..my",
"my..common",
".my.common..",
".my.common..Shared",
] {
let err = normalize(given).unwrap_err();
assert!(
err.contains(&format!("'{given}' has an empty segment")),
"{given:?}: {err}"
);
}
}
#[test]
fn invalid_identifier_error_names_the_segment() {
for (given, segment) in [
("my.123", "123"),
(".my.common-name.", "common-name"),
("my.com mon", "com mon"),
] {
let err = normalize(given).unwrap_err();
assert!(
err.contains(&format!("proto name '{given}': segment '{segment}'")),
"{given:?}: {err}"
);
}
}
}
#[cfg(test)]
mod package_exclusion_tests {
use super::package_is_excluded;
fn ex(list: &[&str]) -> Vec<String> {
list.iter().map(|s| s.to_string()).collect()
}
#[test]
fn exact_match_is_excluded() {
assert!(package_is_excluded("buf.validate", &ex(&["buf.validate"])));
}
#[test]
fn subpackage_matches_on_component_boundary() {
assert!(package_is_excluded("gnostic.openapi.v3", &ex(&["gnostic"])));
assert!(package_is_excluded(
"buf.validate.priv",
&ex(&["buf.validate"])
));
}
#[test]
fn prefix_without_boundary_does_not_match() {
assert!(!package_is_excluded(
"buf.validatex",
&ex(&["buf.validate"])
));
assert!(!package_is_excluded("gnostics", &ex(&["gnostic"])));
}
#[test]
fn unrelated_package_is_kept() {
assert!(!package_is_excluded(
"example.user.v1",
&ex(&["buf.validate", "gnostic"])
));
}
#[test]
fn empty_exclude_list_keeps_everything() {
assert!(!package_is_excluded("buf.validate", &ex(&[])));
}
#[test]
fn empty_entry_matches_only_the_unnamed_package() {
assert!(package_is_excluded("", &ex(&[""])));
assert!(!package_is_excluded("foo", &ex(&[""])));
}
#[test]
fn normalize_strips_dot_and_rejects_malformed() {
use super::normalize_exclude_package;
assert_eq!(
normalize_exclude_package(".buf.validate").as_deref(),
Ok("buf.validate")
);
assert_eq!(
normalize_exclude_package("gnostic").as_deref(),
Ok("gnostic")
);
assert!(normalize_exclude_package("").is_err());
assert!(normalize_exclude_package(".").is_err());
assert!(normalize_exclude_package(" ").is_err());
assert!(normalize_exclude_package("buf.validate.").is_err());
assert!(normalize_exclude_package("buf..validate").is_err());
}
}
pub fn package_to_filename(package: &str) -> String {
if package.is_empty() {
format!("{}.rs", context::SENTINEL_MOD)
} else {
format!("{package}.rs")
}
}
pub fn proto_path_to_stem(proto_path: &str) -> String {
let without_ext = proto_path.strip_suffix(".proto").unwrap_or(proto_path);
without_ext.replace('/', ".")
}
#[track_caller]
pub fn apply_companions(files: &mut Vec<GeneratedFile>, companions: Vec<GeneratedFile>) {
for comp in &companions {
assert!(
!comp.name.contains(['/', '\\']),
"companion file name {:?} contains a path separator ('/' or '\\'); use a \
bare file name such as `<stem>.__myplugin.rs`, which include!() resolves \
next to the stitcher",
comp.name
);
assert!(
!matches!(comp.name.as_str(), "" | "." | ".."),
"companion file name {:?} is empty, `.` or `..`, which names a directory, \
not a file; use a bare file name such as `<stem>.__myplugin.rs`",
comp.name
);
}
for comp in &companions {
if let Some(pkg_mod) = files
.iter_mut()
.find(|f| f.kind == GeneratedFileKind::PackageMod && f.package == comp.package)
{
pkg_mod
.content
.push_str(&format!("include!({:?});\n", comp.name));
}
}
files.extend(companions);
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
#[non_exhaustive]
pub enum ZeroizeConfigurationErrorReason {
#[error(
"containing messages need cleanup too so reflection cannot snapshot a guarded descendant"
)]
ReflectionParent,
#[error(
"contains a cleanup-selected message, so it must be selected too (add it to zeroize_in); otherwise its ordinary fields and collections relocate the guarded descendant without wiping"
)]
ContainingMessage,
#[error(
"a repeated or map field has an explicit Vec, HashMap or BTreeMap rule (prefix rules count); remove it or select ::buffa::sensitive::List<*> or ::buffa::sensitive::Map for the field"
)]
CollectionRepresentation,
#[error("requires unknown_fields=false")]
UnknownFieldStorage,
#[error("raw byte map keys under strict_utf8_mapping cannot use guarded representations")]
RawMapKey,
#[error("every bytes/string slot requires a custom Zeroize + ZeroizeOnDrop representation")]
BufferRepresentation,
#[error(
"requires json_policy_type for each custom bytes/string representation when json=true"
)]
JsonPolicy,
}
#[derive(Debug, Clone, thiserror::Error)]
#[non_exhaustive]
pub enum CodeGenError {
#[error(transparent)]
Adapter(#[from] adapters::AdapterError),
#[error(transparent)]
CleanupJsonAttribute(#[from] CleanupJsonAttributeErrorReason),
#[error("deny_view_json rule '{rule}' matches no known message")]
ViewJsonRuleMatchedNothing { rule: String },
#[error("borrowed_views_only_in rule at index {rule_index} matches no known message")]
BorrowedViewsRuleMatchedNothing {
rule_index: usize,
},
#[error("zeroize_in rule '{rule}' matches no known message")]
ZeroizeRuleMatchedNothing { rule: String },
#[error("json_policy_type '{rust_type}' is not selected by any unshadowed bytes/string rule; match the representation type spelling exactly")]
JsonPolicyTypeMatchedNothing { rust_type: String },
#[error("representation type '{selected}' has the same name as json_policy_type '{listed}', but a different spelling; list the exact type or correct the representation rule")]
JsonPolicyTypeNearMiss { selected: String, listed: String },
#[error("zeroize message '{message}': {reason}")]
InvalidZeroizeConfiguration {
message: String,
reason: ZeroizeConfigurationErrorReason,
},
#[error("missing required descriptor field: {0}")]
MissingField(&'static str),
#[error("invalid Rust type path: '{0}'")]
InvalidTypePath(String),
#[error(
"enum-valued map field '{0}' has a json_policy_type string key; \
policy keys do not support enum map filtering, so select another key representation"
)]
JsonPolicyMapKey(String),
#[error("box_type template must contain a `*` placeholder for the message type: '{0}'")]
MissingWildcard(String),
#[error("repeated_type template must contain a `*` element placeholder: '{0}'")]
MissingListPlaceholder(String),
#[error("generated code failed to parse as Rust: {0}")]
InvalidSyntax(String),
#[error("file_to_generate '{0}' not found in descriptor set")]
FileNotFound(String),
#[error(
"output file name conflict: {first_source} and {second_source} both \
generate '{file_name}'; rename a proto file so that the output names \
differ, or enable file_per_package"
)]
OutputFileNameConflict {
file_name: String,
first_source: String,
second_source: String,
},
#[error("codegen error: {0}")]
Other(String),
#[error(
"reserved field name '{field_name}' in message '{message_name}': \
proto field names starting with '__buffa_' conflict with buffa's \
internal fields"
)]
ReservedFieldName {
message_name: String,
field_name: String,
},
#[error(
"module name conflict in '{scope}': messages '{name_a}' and '{name_b}' \
both produce module '{module_name}'"
)]
ModuleNameConflict {
scope: String,
name_a: String,
name_b: String,
module_name: String,
},
#[error(
"oneof enum name conflict in message '{message_name}': oneofs \
'{first_oneof}' and '{second_oneof}' both map to Rust enum '{rust_name}'; \
rename one of them"
)]
OneofEnumNameConflict {
message_name: String,
first_oneof: String,
second_oneof: String,
rust_name: String,
},
#[error(
"oneof variant name conflict in message '{message_name}': members \
'{first_field}' and '{second_field}' of oneof '{oneof_name}' both map \
to Rust variant '{rust_name}'; rename one of them"
)]
OneofVariantNameConflict {
message_name: String,
oneof_name: String,
first_field: String,
second_field: String,
rust_name: String,
},
#[error(
"type name conflict in '{scope}': '{first_type}' and '{second_type}' \
both map to Rust type '{rust_name}'; rename one of them"
)]
TypeNameConflict {
scope: String,
first_type: String,
second_type: String,
rust_name: String,
},
#[error(
"reserved name '{name}' at {location}: this name is reserved for \
buffa's generated ancillary types (views, oneof enums, \
extensions). Rename the proto element."
)]
ReservedModuleName { name: String, location: String },
#[error(
"shared_corpus_context was built from different {what} than this \
generate() call; build it from the same files and oneof/pointer-repr \
config as every call that uses it"
)]
SharedCorpusContextMismatch { what: &'static str },
#[error(
"message '{message_name}' uses `option message_set_wire_format = true` \
but CodeGenConfig::allow_message_set is false; MessageSet is a legacy \
wire format — set allow_message_set(true) if this is intentional"
)]
MessageSetNotSupported { message_name: String },
#[error(
"invalid custom attribute for path '{path}': '{attribute}' must be one or \
more outer `#[...]` attributes ({detail})"
)]
InvalidCustomAttribute {
path: String,
attribute: String,
detail: String,
},
#[error(
"invalid type_name_prefix '{prefix}': must be empty or PascalCase \
(start with an ASCII uppercase letter, followed by ASCII letters \
and digits only)"
)]
InvalidTypeNamePrefix { prefix: String },
#[error(
"duplicate field number in message '{message_name}': fields '{first_field}' and \
'{second_field}' are both numbered {number}; protoc rejects this, so renumber one of \
them in the code or tool that built the descriptor"
)]
DuplicateFieldNumber {
message_name: String,
first_field: String,
second_field: String,
number: i32,
},
}
#[cfg(test)]
mod tests;
mod guarded_arbitrary;
mod inspect;
mod sensitive;