buffa_build/lib.rs
1// Modified by ReallyMe Technologies Limited.
2//! Build-time integration for buffa.
3//!
4//! Use this crate in your `build.rs` to compile `.proto` files into Rust code
5//! at build time. Parses `.proto` files into a `FileDescriptorSet` (via
6//! `protoc` or `buf`), then uses `buffa-codegen` to generate Rust source.
7//!
8//! # Example
9//!
10//! ```rust,ignore
11//! // build.rs
12//! fn main() {
13//! buffa_build::Config::new()
14//! .files(&["proto/my_service.proto"])
15//! .includes(&["proto/"])
16//! .compile()
17//! .unwrap();
18//! }
19//! ```
20//!
21//! # Requirements
22//!
23//! By default, requires `protoc` on the system PATH (or set via the `PROTOC`
24//! environment variable) — the same as `prost-build` and `tonic-build`.
25//!
26//! If `protoc` is unavailable or outdated on your platform, `buf` can be
27//! used instead — see [`Config::use_buf()`]. Alternatively, feed a
28//! pre-compiled descriptor set via [`Config::descriptor_set()`] (a file) or
29//! [`Config::descriptor_set_bytes()`] (in-memory bytes).
30
31use std::borrow::Cow;
32use std::collections::BTreeSet;
33use std::path::{Component, Path, PathBuf};
34use std::process::Command;
35
36use buffa_codegen::generated::descriptor::FileDescriptorSet;
37
38/// Typed configuration for opt-in native adapters.
39pub use buffa_codegen::adapters;
40#[doc(inline)]
41pub use buffa_codegen::CodeGenConfig;
42#[doc(inline)]
43pub use buffa_codegen::FeatureGateNames;
44#[doc(inline)]
45pub use buffa_codegen::ReflectMode;
46#[doc(inline)]
47pub use buffa_codegen::{BytesRepr, CodecStrategy, MapRepr, PointerRepr, RepeatedRepr, StringRepr};
48#[doc(inline)]
49pub use buffa_codegen::{EnumTypeOverride, FeatureOverride};
50
51/// How to produce a `FileDescriptorSet` from `.proto` files.
52#[derive(Debug, Clone, Default)]
53enum DescriptorSource {
54 /// Invoke `protoc` (default). Requires `protoc` on PATH or `PROTOC` env var.
55 #[default]
56 Protoc,
57 /// Invoke `buf build --as-file-descriptor-set`. Requires `buf` on PATH.
58 Buf,
59 /// Read a pre-built `FileDescriptorSet` from a file.
60 Precompiled(PathBuf),
61 /// Use a pre-built `FileDescriptorSet` already in memory.
62 Bytes(Vec<u8>),
63}
64
65/// Builder for configuring and running protobuf compilation.
66pub struct Config {
67 files: Vec<PathBuf>,
68 includes: Vec<PathBuf>,
69 out_dir: Option<PathBuf>,
70 codegen_config: CodeGenConfig,
71 descriptor_source: DescriptorSource,
72 /// If set, generate a module-tree include file with this name in the
73 /// output directory. Users can then `include!` this single file instead
74 /// of manually setting up `pub mod` nesting.
75 include_file: Option<String>,
76}
77
78impl Config {
79 /// Enable typed `(buffa.ext.file).adapters` options (default: false).
80 ///
81 /// Native files are written beside the portable output and included
82 /// explicitly in their API modules. No native adapter enters the portable
83 /// module tree. Missing or incomplete mappings fail before output is written.
84 /// Without an explicit [`Self::adapters`] configuration, at least one
85 /// requested file must declare the options, otherwise `compile()` fails
86 /// with [`adapters::ErrorReason::MissingSchemaAdapters`]. This setting
87 /// only controls the schema options: it does not suppress an explicit
88 /// [`Self::adapters`] configuration.
89 #[must_use]
90 pub fn generate_adapters(mut self, enabled: bool) -> Self {
91 self.codegen_config.generate_adapters = enabled;
92 self
93 }
94
95 /// Add descriptor-checked native adapters from a typed Rust configuration.
96 /// Replaces the previous explicit configuration; schema options, if enabled,
97 /// are combined with it and checked for collisions.
98 #[must_use]
99 pub fn adapters(mut self, config: adapters::AdapterConfig) -> Self {
100 self.codegen_config.adapters = Some(config);
101 self
102 }
103
104 /// Create a new configuration with defaults.
105 pub fn new() -> Self {
106 Self {
107 files: Vec::new(),
108 includes: Vec::new(),
109 out_dir: None,
110 codegen_config: CodeGenConfig::default(),
111 descriptor_source: DescriptorSource::default(),
112 include_file: None,
113 }
114 }
115
116 /// Add `.proto` files to compile.
117 #[must_use]
118 pub fn files(mut self, files: &[impl AsRef<Path>]) -> Self {
119 self.files
120 .extend(files.iter().map(|f| f.as_ref().to_path_buf()));
121 self
122 }
123
124 /// Add include directories for protoc to search for imports.
125 ///
126 /// Directories are searched in order. If directories overlap, the first
127 /// matching directory determines the proto-relative file name.
128 #[must_use]
129 pub fn includes(mut self, includes: &[impl AsRef<Path>]) -> Self {
130 self.includes
131 .extend(includes.iter().map(|i| i.as_ref().to_path_buf()));
132 self
133 }
134
135 /// Set the output directory for generated files.
136 /// Defaults to `$OUT_DIR` if not set.
137 #[must_use]
138 pub fn out_dir(mut self, dir: impl Into<PathBuf>) -> Self {
139 self.out_dir = Some(dir.into());
140 self
141 }
142
143 /// Enable or disable view type generation (default: true).
144 #[must_use]
145 pub fn generate_views(mut self, enabled: bool) -> Self {
146 self.codegen_config.generate_views = enabled;
147 self
148 }
149
150 /// Additionally generate the lazy view family (`FooLazyView<'a>`)
151 /// alongside the unchanged eager views (default: false).
152 ///
153 /// Lazy views decode in a single non-recursive pass, recording nested and
154 /// repeated message fields as undecoded byte ranges that decode on access
155 /// via fallible, by-value accessors (`.get()` / iteration) — untouched
156 /// sub-trees cost nothing. Validation of deferred bytes happens on
157 /// *access* (and in the fallible `to_owned_message`), not at decode.
158 /// Groups, oneof message variants, and map message values stay eager;
159 /// lazy views have no `ReflectMessage`/`OwnedView`/text surface. Eager
160 /// codegen output is byte-identical with or without the flag. Requires
161 /// [`generate_views`](Self::generate_views). See
162 /// [`CodeGenConfig::lazy_views`] for full semantics.
163 #[must_use]
164 pub fn lazy_views(mut self, enabled: bool) -> Self {
165 self.codegen_config.lazy_views = enabled;
166 self
167 }
168
169 /// Enable or disable serde JSON generation (default: false).
170 ///
171 /// When enabled:
172 /// - Generated message structs get `Serialize`/`Deserialize` derives.
173 /// - Generated enum types get `Serialize`/`Deserialize` derives.
174 /// - Generated view types (when `generate_views` is also enabled) get a
175 /// manual `impl Serialize` for zero-copy JSON serialization, so
176 /// `serde_json::to_string(&view)` works directly:
177 ///
178 /// ```ignore
179 /// let view = MyMsgView::decode_view(&bytes)?;
180 /// let json = serde_json::to_string(&view)?;
181 /// ```
182 ///
183 /// The downstream crate must depend on `serde` and enable the `buffa/json`
184 /// feature for the runtime helpers. When views are enabled, the crate must
185 /// also enable `buffa-types/json` so the well-known type views implement
186 /// `Serialize`; without it, references to e.g. `TimestampView<'_>` in the
187 /// generated `Serialize` impl will fail with
188 /// `the trait bound 'TimestampView<'_>: Serialize' is not satisfied`.
189 ///
190 /// **Limitations of the view `Serialize` impl:**
191 /// - Extension fields are not included in view JSON output; serialize the
192 /// owned form (`view.to_owned_message()`) to include extensions.
193 /// - The impl uses `serialize_map(None)` (unknown length) because the
194 /// number of emitted fields depends on default-omission rules. Most
195 /// self-describing serializers (notably `serde_json`) accept this, but
196 /// length-prefixed formats (e.g. `bincode`, `postcard`) will return a
197 /// runtime error. The owned types' derived `Serialize` does not have this
198 /// restriction.
199 #[must_use]
200 pub fn generate_json(mut self, enabled: bool) -> Self {
201 self.codegen_config.generate_json = enabled;
202 self
203 }
204
205 /// Enable or disable `impl buffa::text::TextFormat` on generated message
206 /// structs (default: false).
207 ///
208 /// When enabled, the downstream crate must enable the `buffa/text`
209 /// feature for the runtime textproto encoder/decoder.
210 #[must_use]
211 pub fn generate_text(mut self, enabled: bool) -> Self {
212 self.codegen_config.generate_text = enabled;
213 self
214 }
215
216 /// Enable or disable `#[derive(arbitrary::Arbitrary)]` on generated
217 /// types (default: false).
218 ///
219 /// The derive is gated behind `#[cfg_attr(feature = "arbitrary", ...)]`
220 /// so the downstream crate compiles with or without the feature enabled.
221 /// An enum with a `[deprecated = true]` variant gets a generated impl
222 /// under the same gate instead, because the derive would warn on that
223 /// variant. The impl maps input to variants as the derive does.
224 ///
225 /// Your crate's Cargo feature **must be named exactly `"arbitrary"`** —
226 /// the generated `cfg_attr` uses that literal string and cannot be
227 /// customised — and it must forward to `buffa/arbitrary`:
228 ///
229 /// ```toml
230 /// [features]
231 /// arbitrary = ["dep:arbitrary", "buffa/arbitrary"]
232 /// ```
233 ///
234 /// Forgetting `"buffa/arbitrary"` produces a confusing error in generated
235 /// code, such as ``cannot find function `arbitrary_proto_bytes` in module
236 /// `buffa::__private` ``, when a `string_type` or `bytes_type` rule selects
237 /// a non-default type: the functions that back `#[arbitrary(with = ...)]`
238 /// on those fields live in `buffa` under that feature gate.
239 #[must_use]
240 pub fn generate_arbitrary(mut self, enabled: bool) -> Self {
241 self.codegen_config.generate_arbitrary = enabled;
242 self
243 }
244
245 /// Omit the generated `Debug` implementation for the matching messages
246 /// and enums, so that your crate can write its own.
247 ///
248 /// Each path is a fully-qualified proto path. For messages it is a
249 /// prefix: `".demo.Uuid4"` names that message and the messages nested
250 /// inside it, `".demo"` every message in the package and its
251 /// sub-packages, and `"."` every message. A matched message's oneof
252 /// enums lose their `Debug` with it. An enum loses its `Debug` only when
253 /// a path is its exact name, such as `".demo.Level"`: a message or
254 /// package path leaves the enums under it as they are. A leading dot is
255 /// added if missing and trailing dots are trimmed. Repeated calls
256 /// accumulate.
257 ///
258 /// Eager, lazy, and owned views of matched messages, and their view oneofs,
259 /// keep `Debug` but print only the type name and `[REDACTED]`. This also
260 /// hides preserved unknown wire fields. The rule affects generated
261 /// formatting only. For selective redaction in generated and reflective
262 /// formatting, use `[debug_redact = true]`. A hand-written `Debug` impl
263 /// for a matched owned message or oneof decides what that value prints.
264 ///
265 /// Your crate then implements `Debug`:
266 ///
267 /// - for every matched enum, because [`buffa::Enumeration`] requires it;
268 /// - for a matched message that an unmatched message or oneof holds
269 /// (their generated `Debug` formats it), that is generated with
270 /// reflection, or that a custom `repeated_type` collection holds;
271 /// - for a matched message's oneof enum, if your `Debug` for the message
272 /// prints it. For a oneof `kind` in `demo.Uuid4` the enum is
273 /// `demo::uuid4::Kind`.
274 ///
275 /// A missing impl is a compile error. For an enum it is error E0277
276 /// (`Level` doesn't implement `Debug`) at the generated
277 /// `impl ::buffa::Enumeration for Level`. A path that matches no
278 /// generated message and names no generated enum prints a
279 /// `cargo:warning`.
280 ///
281 /// # Example
282 ///
283 /// ```rust,ignore
284 /// // build.rs
285 /// buffa_build::Config::new()
286 /// .files(&["proto/demo.proto"])
287 /// .includes(&["proto/"])
288 /// .skip_debug(&[".demo.Uuid4", ".demo.Level"])
289 /// .compile()?;
290 ///
291 /// // src/lib.rs
292 /// pub mod demo {
293 /// buffa::include_proto!("demo");
294 /// }
295 ///
296 /// impl core::fmt::Debug for demo::Uuid4 {
297 /// fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
298 /// write!(f, "Uuid4({:016x}{:016x})", self.msb, self.lsb)
299 /// }
300 /// }
301 ///
302 /// // Prints the value's proto name, as the derive it replaces does.
303 /// impl core::fmt::Debug for demo::Level {
304 /// fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
305 /// f.write_str(buffa::Enumeration::proto_name(self))
306 /// }
307 /// }
308 /// ```
309 #[must_use]
310 pub fn skip_debug(mut self, paths: &[impl AsRef<str>]) -> Self {
311 for raw in paths.iter().map(AsRef::as_ref) {
312 let normalized = normalize_override_path(raw);
313 if normalized.is_empty() {
314 println!(
315 "cargo:warning=buffa: skip_debug path '{raw}' \
316 normalizes to empty and will be ignored"
317 );
318 continue;
319 }
320 self.codegen_config.skip_debug.push(normalized);
321 }
322 self
323 }
324
325 /// Reject JSON serialization of the selected messages' eager, lazy and owned
326 /// views before writing any output. Owned-message JSON remains available.
327 /// The restriction propagates to containing messages, including map values.
328 /// `.` selects every message; unmatched rules cause a code generation error.
329 /// Empty paths are errors. Disabling JSON or views warns that the rule is inactive.
330 #[must_use]
331 pub fn deny_view_json(mut self, paths: &[impl AsRef<str>]) -> Self {
332 self.codegen_config.deny_view_json.extend(
333 paths
334 .iter()
335 .map(|path| normalize_override_path(path.as_ref())),
336 );
337 self
338 }
339
340 /// Omit standard owned-view wrappers and `HasMessageView` for matching
341 /// messages and their containers. Borrowed views remain available.
342 /// Use `.` to select every message. Rules must match a known message.
343 /// Messages selected for cleanup, and their containers, are always
344 /// treated as selected.
345 ///
346 /// This controls what code is generated. It does not disable explicit
347 /// use of the public `buffa::OwnedView` runtime with a borrowed view type.
348 #[must_use]
349 pub fn borrowed_views_only_in(mut self, paths: &[impl AsRef<str>]) -> Self {
350 self.codegen_config.borrowed_views_only_in.extend(
351 paths
352 .iter()
353 .map(|path| normalize_override_path(path.as_ref())),
354 );
355 self
356 }
357
358 /// Wrap generated `impl`s in `#[cfg(feature = "...")]` instead of
359 /// emitting them unconditionally (default: false).
360 ///
361 /// When enabled, the impls controlled by [`generate_json`],
362 /// [`generate_views`], and [`generate_text`] are wrapped in
363 /// `#[cfg(feature = "json" | "views" | "text")]` (or
364 /// `#[cfg_attr(feature = ..., ...)]` for derives and field attributes)
365 /// rather than emitted unconditionally. The crate consuming the
366 /// generated code must define matching Cargo features that enable the
367 /// corresponding runtime support:
368 ///
369 /// ```toml
370 /// [features]
371 /// json = ["buffa/json", "dep:serde", "dep:serde_json"]
372 /// views = []
373 /// text = ["buffa/text"]
374 /// ```
375 ///
376 /// The `generate_*` flags still control *whether* an impl kind is
377 /// emitted at all — this flag only controls whether it is `cfg`-gated.
378 /// `generate_arbitrary` is always `cfg_attr`-gated on
379 /// `feature = "arbitrary"` regardless of this flag, because `arbitrary`
380 /// is an optional dependency by design.
381 ///
382 /// Reach for this when generated code is the **public interface of a
383 /// library crate** consumed by downstream projects with different
384 /// feature needs — exactly the shape of `buffa-descriptor` and
385 /// `buffa-types`, which ship every impl while letting the codegen
386 /// toolchain (`buffa-codegen`/`buffa-build`/`protoc-gen-reallyme-buffa`) depend
387 /// on them with `default-features = false` and stay free of
388 /// `serde`/`serde_json`/`base64`. Most consumers of `buffa-build` are
389 /// **not** in this position: a `build.rs` that decides at build-script
390 /// time whether to generate JSON wants `impl Serialize` to just exist.
391 /// Default `false`.
392 ///
393 /// [`generate_json`]: Self::generate_json
394 /// [`generate_views`]: Self::generate_views
395 /// [`generate_text`]: Self::generate_text
396 #[must_use]
397 pub fn gate_impls_on_crate_features(mut self, enabled: bool) -> Self {
398 self.codegen_config.gate_impls_on_crate_features = enabled;
399 self
400 }
401
402 /// Gate only the reflection impls behind a `reflect` crate feature, without
403 /// gating json/views/text (unlike
404 /// [`gate_impls_on_crate_features`](Self::gate_impls_on_crate_features),
405 /// which gates them together).
406 ///
407 /// For crates that ship views/text unconditionally but want the
408 /// `buffa-descriptor`-dependent (and `std`-requiring) reflection surface to
409 /// be opt-in. `buffa-types` is the motivating case.
410 ///
411 /// **Experimental and `#[doc(hidden)]`.** This knob only controls the
412 /// crate-feature gate on the emitted reflection impls; the reflection
413 /// codegen mode itself is selected via the public
414 /// [`reflect_mode`](Self::reflect_mode) selector.
415 #[doc(hidden)]
416 #[must_use]
417 pub fn gate_reflect_on_crate_feature(mut self, enabled: bool) -> Self {
418 self.codegen_config.gate_reflect_on_crate_feature = enabled;
419 self
420 }
421
422 /// Set the crate feature name the gated JSON impls are conditioned on
423 /// (default: `"json"`).
424 ///
425 /// Only meaningful together with
426 /// [`gate_impls_on_crate_features`](Self::gate_impls_on_crate_features);
427 /// inert otherwise. Use when the consuming crate gates its JSON support
428 /// behind a differently-named feature:
429 ///
430 /// ```toml
431 /// [features]
432 /// serde = ["buffa/json", "dep:serde", "dep:serde_json"]
433 /// ```
434 ///
435 /// ```rust,ignore
436 /// buffa_build::Config::new()
437 /// .generate_json(true)
438 /// .gate_impls_on_crate_features(true)
439 /// .json_feature_name("serde")
440 /// # ;
441 /// ```
442 ///
443 /// The name is emitted verbatim into `#[cfg(feature = "...")]`
444 /// attributes and must be a valid Cargo feature name **declared in the
445 /// consuming crate's `[features]` table**. A misspelled or undeclared
446 /// name fails open: the `#[cfg]` is permanently false, so the gated
447 /// impls silently compile away (on Rust ≥ 1.80 an undeclared name at
448 /// least triggers the `unexpected_cfgs` warning). A name that is not a
449 /// valid Cargo feature name at all (empty, or containing characters
450 /// outside alphanumerics and `_`/`-`/`+`/`.`) makes [`compile`](Self::compile)
451 /// fail with an error when the gate is active.
452 #[must_use]
453 pub fn json_feature_name(mut self, name: impl Into<String>) -> Self {
454 self.codegen_config.feature_gate_names.json = name.into();
455 self
456 }
457
458 /// Set the crate feature name the gated view impls are conditioned on
459 /// (default: `"views"`).
460 ///
461 /// Only meaningful together with
462 /// [`gate_impls_on_crate_features`](Self::gate_impls_on_crate_features);
463 /// inert otherwise. See [`json_feature_name`](Self::json_feature_name).
464 #[must_use]
465 pub fn views_feature_name(mut self, name: impl Into<String>) -> Self {
466 self.codegen_config.feature_gate_names.views = name.into();
467 self
468 }
469
470 /// Set the crate feature name the gated textproto impls are conditioned
471 /// on (default: `"text"`).
472 ///
473 /// Only meaningful together with
474 /// [`gate_impls_on_crate_features`](Self::gate_impls_on_crate_features);
475 /// inert otherwise. See [`json_feature_name`](Self::json_feature_name).
476 #[must_use]
477 pub fn text_feature_name(mut self, name: impl Into<String>) -> Self {
478 self.codegen_config.feature_gate_names.text = name.into();
479 self
480 }
481
482 /// Set the crate feature name the gated reflection impls are conditioned
483 /// on (default: `"reflect"`).
484 ///
485 /// Only meaningful together with
486 /// [`gate_impls_on_crate_features`](Self::gate_impls_on_crate_features)
487 /// (or the experimental, hidden `gate_reflect_on_crate_feature`, which
488 /// gates reflection alone); inert otherwise. See
489 /// [`json_feature_name`](Self::json_feature_name).
490 #[must_use]
491 pub fn reflect_feature_name(mut self, name: impl Into<String>) -> Self {
492 self.codegen_config.feature_gate_names.reflect = name.into();
493 self
494 }
495
496 /// Prepend a prefix to every generated Rust type name (default: none).
497 ///
498 /// With prefix `"Rpc"`, `message User {}` generates `struct RpcUser`
499 /// (and `RpcUserView` / `RpcUserOwnedView`); every cross-reference uses
500 /// the prefixed name. Useful in multi-protocol systems where generated
501 /// types from different domains would otherwise collide with each other
502 /// or with a canonical hand-written model.
503 ///
504 /// Applies to message structs and enum types (top-level and nested).
505 /// Module names, oneof enums, [`extern_path`](Self::extern_path)-mapped
506 /// types (including well-known types), and the wire/JSON format are
507 /// unaffected.
508 ///
509 /// When another crate references these prefixed types via its own
510 /// [`extern_path`](Self::extern_path) mapping, the mapped Rust path must
511 /// spell out the prefixed name (e.g. `::crate_a::RpcUser`) — the proto
512 /// name carries no prefix, so the mapping is not derived automatically.
513 ///
514 /// The prefix must be PascalCase (`[A-Z][A-Za-z0-9]*`) — an ASCII
515 /// uppercase letter followed by ASCII letters and digits — so the
516 /// prefixed names stay conventionally cased; [`compile`](Self::compile)
517 /// fails otherwise.
518 #[must_use]
519 pub fn type_name_prefix(mut self, prefix: impl Into<String>) -> Self {
520 self.codegen_config.type_name_prefix = prefix.into();
521 self
522 }
523
524 /// Enable or disable `with_*` builder-style setter methods for
525 /// explicit-presence fields (default: true).
526 ///
527 /// Each explicit-presence scalar, bytes, or enum field gets a
528 /// `pub fn with_<name>(mut self, value: T) -> Self` method that wraps the
529 /// value in `Some(...)` and returns `self`, enabling chained construction
530 /// without the `Some(...)` boilerplate:
531 ///
532 /// ```ignore
533 /// let req = MyRequest::default()
534 /// .with_name("alice")
535 /// .with_timeout_ms(30_000);
536 /// ```
537 ///
538 /// String, bytes, and enum setters take `impl Into<T>` (so `&str`,
539 /// `b"..."` literals, and bare enum variants work directly); other
540 /// scalars take `T` to keep integer-literal inference unambiguous.
541 ///
542 /// Setters are pure inherent methods with no runtime dependency — they
543 /// don't interact with the `json`/`views`/`text` feature gates. Disable
544 /// only if you want to keep generated code minimal or have a competing
545 /// `with_*` convention in your own crate.
546 #[must_use]
547 pub fn generate_with_setters(mut self, enabled: bool) -> Self {
548 self.codegen_config.generate_with_setters = enabled;
549 self
550 }
551
552 /// Enable reflection on generated types (default: off).
553 ///
554 /// `generate_reflection(true)` selects [`ReflectMode::VTable`] — the fast
555 /// path: `foo.reflect()` borrows `foo` directly (no encode/decode
556 /// round-trip), and owned and view types implement `ReflectMessage`. For
557 /// the smaller bridge implementation (`reflect()` round-trips through a
558 /// [`DynamicMessage`]), use [`reflect_mode(ReflectMode::Bridge)`](Self::reflect_mode)
559 /// instead. `generate_reflection(false)` is [`ReflectMode::Off`].
560 ///
561 /// Either mode embeds a lazily-built [`DescriptorPool`] (as
562 /// `FileDescriptorSet` bytes) reachable as
563 /// `your_crate::your_pkg::descriptor_pool()`.
564 ///
565 /// # Cargo.toml setup
566 ///
567 /// The consuming crate must depend on `buffa-descriptor` with the
568 /// `reflect` feature and on `std`:
569 ///
570 /// ```toml
571 /// [dependencies]
572 /// buffa = { package = "reallyme-buffa", version = "=0.1.3", features = ["std"] }
573 /// buffa-descriptor = { package = "reallyme-buffa-descriptor", version = "=0.1.3", features = ["reflect", "std"] }
574 /// ```
575 ///
576 /// When [`gate_impls_on_crate_features`](Self::gate_impls_on_crate_features)
577 /// is also on, the impls are wrapped in `#[cfg(feature = "reflect")]`,
578 /// so the consuming crate must declare a forwarding feature:
579 ///
580 /// ```toml
581 /// [features]
582 /// reflect = ["buffa-descriptor/reflect"]
583 /// ```
584 ///
585 /// **Without the feature declared, the generated `Reflectable` impls
586 /// silently disappear** — `cfg(feature = "reflect")` is permanently
587 /// false in a crate that doesn't declare it. The first call to
588 /// `.reflect()` fails to compile with "trait `Reflectable` not
589 /// implemented", which is a misleading diagnostic. Most consumers
590 /// should leave `gate_impls_on_crate_features` off.
591 ///
592 /// Reflecting message-typed fields also requires every crate that field
593 /// types resolve to via an extern path — notably `buffa-types` for
594 /// well-known types — to enable its own reflection feature; see
595 /// [`reflect_mode`](Self::reflect_mode) ("Extern-path types") for the
596 /// `Cargo.toml` requirement and mixed-mode behavior.
597 ///
598 /// # Performance
599 ///
600 /// In the default vtable mode, `reflect()` borrows `self` — no round-trip,
601 /// no allocation; reflective accessors read fields in place. (Bridge mode
602 /// instead pays one encode/decode round-trip plus a heap allocation per
603 /// call.) Either way the first call pays a one-time pool build cost.
604 ///
605 /// # Build time and binary size
606 ///
607 /// By default each generated package embeds its own copy of the full
608 /// `FileDescriptorSet` (transitive closure). For a single-package
609 /// crate this is one copy. For a multi-package codegen run the bytes
610 /// duplicate per package — measurable for large proto trees;
611 /// [`shared_descriptor_pool`](Self::shared_descriptor_pool) collapses that
612 /// to one `include_bytes!` sidecar. The serialization happens once per
613 /// `compile()` call (not per package), so build-time CPU does not scale
614 /// with package count. Vtable mode also emits an `impl ReflectMessage` per
615 /// type, so it produces more code than bridge mode.
616 ///
617 /// [`ReflectCow`]: https://docs.rs/reallyme-buffa-descriptor/latest/buffa_descriptor/reflect/enum.ReflectCow.html
618 /// [`DynamicMessage`]: https://docs.rs/reallyme-buffa-descriptor/latest/buffa_descriptor/reflect/struct.DynamicMessage.html
619 /// [`DescriptorPool`]: https://docs.rs/reallyme-buffa-descriptor/latest/buffa_descriptor/struct.DescriptorPool.html
620 #[must_use]
621 pub fn generate_reflection(mut self, enabled: bool) -> Self {
622 // The simple on/off knob selects the fast vtable path; Bridge is opt-in
623 // via `reflect_mode`.
624 let mode = if enabled {
625 ReflectMode::VTable
626 } else {
627 ReflectMode::Off
628 };
629 mode.apply(&mut self.codegen_config);
630 self
631 }
632
633 /// Select the reflection mode (the fuller form of
634 /// [`generate_reflection`](Self::generate_reflection)).
635 ///
636 /// - [`ReflectMode::Off`] — no reflection (the default); equivalent to
637 /// `generate_reflection(false)`.
638 /// - [`ReflectMode::Bridge`] — `reflect()` round-trips through
639 /// `DynamicMessage`; smaller generated code, slower reflective access.
640 /// - [`ReflectMode::VTable`] — `impl ReflectMessage` on owned and view
641 /// types, and `reflect()` borrows `self` with no round-trip; equivalent
642 /// to `generate_reflection(true)`. Does not require view generation —
643 /// with views off, only the owned impls are emitted.
644 ///
645 /// All non-`Off` modes require the consuming crate to depend on
646 /// `buffa-descriptor` with its `reflect` feature and on `std`. The call
647 /// site (`foo.reflect().get(fd)`) is identical across modes.
648 ///
649 /// # Extern-path types
650 ///
651 /// Reflection on a message reaches into its message-typed fields, so
652 /// every crate that field types resolve to via an extern path must have
653 /// its own reflection enabled. In particular, well-known types resolve
654 /// to `buffa-types` by default, and its impls are behind a cargo
655 /// feature: depend on `buffa-types = { ..., features = ["reflect"] }`
656 /// or the build fails with unsatisfied `Reflectable` /
657 /// `ReflectMessage` bounds on the WKT.
658 ///
659 /// # Mixed modes
660 ///
661 /// A vtable-mode message may embed owned message types generated in
662 /// bridge mode (e.g. a dependency crate that chose the smaller output):
663 /// reflective access degrades to an owned `DynamicMessage` snapshot at
664 /// that boundary instead of failing. For a bridge-grade `repeated` or
665 /// `map` field the snapshot is taken per element on every access, so
666 /// reflecting a large mixed-mode collection scales the encode/decode
667 /// cost by the element count. The *view* reflection surface cannot
668 /// degrade — every view type embedded in a vtable-mode view must itself
669 /// be vtable-grade, and a bridge-grade view field is a compile error.
670 #[must_use]
671 pub fn reflect_mode(mut self, mode: ReflectMode) -> Self {
672 mode.apply(&mut self.codegen_config);
673 self
674 }
675
676 /// Deduplicate the embedded reflection descriptor pool across packages.
677 ///
678 /// With reflection enabled, each package normally embeds its own copy of
679 /// the full-closure `FileDescriptorSet`. For a multi-package build those
680 /// copies are identical, so a large proto tree carries the same bytes once
681 /// per package. When this is on, the descriptor set is written once as a
682 /// binary sidecar next to the generated tree and `include_bytes!`-d by a
683 /// single shared `__buffa_fds` module; every package's `descriptor_pool()`
684 /// / `FILE_DESCRIPTOR_SET_BYTES` delegates to it. This removes both the
685 /// per-package duplication and the byte-literal source expansion.
686 ///
687 /// The sidecar is named `<include-file-stem>.descriptor_set.binpb` (so
688 /// `.include_file("gen_mod.rs")` writes `gen_mod.descriptor_set.binpb`)
689 /// and lands in the output directory next to the include file. With a
690 /// checked-in [`out_dir`](Self::out_dir), commit the sidecar alongside
691 /// the generated `.rs` files — the `include_bytes!` resolves relative to
692 /// the include file, so the pair must travel together.
693 ///
694 /// Requires [`include_file`](Self::include_file) (the shared module is
695 /// emitted into that file at the tree root) and reflection to be enabled;
696 /// [`compile`](Self::compile) errors otherwise. The include file name must
697 /// be a bare file name, not a path: the sidecar is named after the stem
698 /// alone, so `a/gen.rs` and `b/gen.rs` would share one sidecar. See
699 /// [`CodeGenConfig::shared_descriptor_pool`].
700 ///
701 /// In this mode the generated tree must be consumed *through the include
702 /// file* (`include!(concat!(env!("OUT_DIR"), "/gen_mod.rs"))`, or the
703 /// checked-in `mod gen;` flavour). Each package delegates to `__buffa_fds`
704 /// by a fixed number of `super::` hops from the tree root, so wiring
705 /// packages individually with `buffa::include_proto!` does not compile
706 /// here: the delegation resolves against whatever module the macro lands
707 /// in. Two shared-pool `compile()` calls included at the same module scope
708 /// likewise collide on `__buffa_fds`; give each include file its own
709 /// module.
710 #[must_use]
711 pub fn shared_descriptor_pool(mut self, enabled: bool) -> Self {
712 self.codegen_config.shared_descriptor_pool = enabled;
713 self
714 }
715
716 /// Enable or disable idiomatic `UpperCamelCase` enum aliases (matches the
717 /// [`CodeGenConfig`] default, currently on).
718 ///
719 /// Protobuf enum values are `SHOUTY_SNAKE_CASE` and stay the definitive Rust
720 /// variants. When enabled, codegen additionally emits associated `const`s
721 /// with the enum-name prefix stripped and the name converted to
722 /// `UpperCamelCase` (`RULE_LEVEL_HIGH` → `RuleLevel::High`), purely
723 /// additively — existing references and `Debug` output are unchanged.
724 ///
725 /// Aliases are suppressed per enum (with a build warning and a doc note) if
726 /// any two values would collide after conversion, so a match is never forced
727 /// to mix conventions. See [`CodeGenConfig::idiomatic_enum_aliases`].
728 #[must_use]
729 pub fn idiomatic_enum_aliases(mut self, enabled: bool) -> Self {
730 self.codegen_config.idiomatic_enum_aliases = enabled;
731 self
732 }
733
734 /// Convert proto field and oneof names to idiomatic snake_case Rust
735 /// identifiers (`webMessageInfo` → `web_message_info`), matching
736 /// prost-build's behavior for protos that use camelCase field names.
737 /// Default: `false` (proto names are emitted verbatim).
738 ///
739 /// Only the generated Rust source names change; the wire format, JSON
740 /// (`json_name` plus the original proto name accepted on parse), text
741 /// format, and reflection lookups all keep the descriptor's names, so the
742 /// option is fully wire- and JSON-compatible. Enum values are covered by
743 /// [`idiomatic_enum_aliases`](Self::idiomatic_enum_aliases) instead.
744 ///
745 /// Word boundaries match prost-build's (heck's) segmentation, including
746 /// digit-transparent case boundaries (`v2Field` → `v2_field`); unlike
747 /// prost, authored underscores are always preserved (`_foo` stays
748 /// `_foo`), so already-snake_case names are never rewritten.
749 ///
750 /// If two members of one message collide after conversion (`userName` and
751 /// `user_name` — rejected by protoc for proto3/editions, so proto2 only),
752 /// the names are adjusted deterministically and a build warning is
753 /// emitted; see [`CodeGenConfig::idiomatic_field_names`] for the rules.
754 #[must_use]
755 pub fn idiomatic_field_names(mut self, enabled: bool) -> Self {
756 self.codegen_config.idiomatic_field_names = enabled;
757 self
758 }
759
760 /// Emit one `<dotted.package>.rs` file per proto package instead of the
761 /// per-proto-file content set plus `<pkg>.mod.rs` stitcher. Default:
762 /// `false`.
763 ///
764 /// The single file inlines what the stitcher would otherwise `include!`,
765 /// producing the same module structure. Required by
766 /// [`idiomatic_imports`](Self::idiomatic_imports). See
767 /// [`CodeGenConfig::file_per_package`] for caveats about packages that
768 /// span multiple directories.
769 #[must_use]
770 pub fn file_per_package(mut self, enabled: bool) -> Self {
771 self.codegen_config.file_per_package = enabled;
772 self
773 }
774
775 /// **Experimental.** Emit `use`-backed short type names at the package
776 /// root instead of fully-qualified paths, so struct fields read
777 /// `MessageField<Timestamp>` instead of
778 /// `::buffa::MessageField<::buffa_types::google::protobuf::Timestamp>`.
779 /// Default: `false` (output is byte-for-byte identical to previous
780 /// releases).
781 ///
782 /// Requires [`file_per_package`](Self::file_per_package) — the build
783 /// fails otherwise. Short names that would collide with another item at
784 /// the package root (or a name referenced bare by sibling emissions)
785 /// fall back to parent-module qualification, then to the
786 /// fully-qualified path.
787 ///
788 /// Only package-root type *declarations* are shortened; impl bodies,
789 /// nested-message modules, and `__buffa` internals keep fully-qualified
790 /// paths. "Experimental" means the output shape may change between
791 /// releases and the option may be renamed or removed outside semver
792 /// guarantees. See [`CodeGenConfig::idiomatic_imports`] for details.
793 #[must_use]
794 pub fn idiomatic_imports(mut self, enabled: bool) -> Self {
795 self.codegen_config.idiomatic_imports = enabled;
796 self
797 }
798
799 /// Enable or disable unknown field preservation (default: true).
800 ///
801 /// When enabled (the default), unrecognized fields encountered during
802 /// decode are stored and re-emitted on encode — essential for proxy /
803 /// middleware services and round-trip fidelity across schema versions.
804 ///
805 /// **Disabling is mostly a memory optimization**: 24 bytes per owned
806 /// message for the `UnknownFields` `Vec` header, and one pointer per
807 /// view, whose backing state is allocated only once an unknown field
808 /// actually arrives.
809 ///
810 /// A wire payload with no unknown fields does no per-field work either
811 /// way, but that does not make the two modes equivalent: carrying the
812 /// handle still shapes how the compiler moves the view, and that is
813 /// measurable on view-decode throughput for message-dense shapes.
814 /// Disabling is the only setting that removes the field outright, so it
815 /// is the lever to reach for when view decode is hot and round-trip
816 /// fidelity across schema versions is not required — as it is for
817 /// embedded / `no_std` targets and large in-memory collections of small
818 /// messages.
819 ///
820 /// To keep the global off-switch and still preserve selected messages, use
821 /// [`preserve_unknown_fields_in`](Self::preserve_unknown_fields_in).
822 #[must_use]
823 pub fn preserve_unknown_fields(mut self, enabled: bool) -> Self {
824 self.codegen_config.preserve_unknown_fields = enabled;
825 self
826 }
827
828 /// Generate recursive cleanup for every owned message.
829 /// Requires `buffa/zeroize` and guarded field representations; see the guarded-fields guide.
830 /// No owned-view wrapper or `HasMessageView` impl is generated, as with
831 /// [`borrowed_views_only_in`](Self::borrowed_views_only_in).
832 #[must_use]
833 pub fn generate_zeroize(mut self, enabled: bool) -> Self {
834 self.codegen_config.generate_zeroize = enabled;
835 self
836 }
837
838 /// Generate recursive cleanup for messages under these proto path prefixes.
839 /// `.` matches every message. Calls accumulate. Empty or unmatched paths
840 /// are errors; scoped requests can explicitly allow unmatched rules.
841 /// Selected messages and their containers get no owned-view wrapper or
842 /// `HasMessageView` impl, as with
843 /// [`borrowed_views_only_in`](Self::borrowed_views_only_in).
844 #[must_use]
845 pub fn zeroize_in(mut self, paths: &[impl AsRef<str>]) -> Self {
846 self.codegen_config.zeroize_messages.extend(
847 paths
848 .iter()
849 .map(|path| normalize_override_path(path.as_ref())),
850 );
851 self
852 }
853
854 /// Enable unknown-field preservation for matching messages, on top of
855 /// the global [`preserve_unknown_fields`](Self::preserve_unknown_fields)
856 /// setting.
857 ///
858 /// Each path is a fully-qualified proto path prefix, e.g.
859 /// `".wa.CallLogRecord"` for one message or `".wa"` for a package (same
860 /// matching as [`unbox_oneof_in`](Self::unbox_oneof_in)); `"."` matches
861 /// every message. A leading dot is added if missing and trailing dots
862 /// are trimmed. An empty path is warned about and ignored so `"."`
863 /// remains the only catch-all spelling.
864 ///
865 /// A rule covers the message it names **and every message nested inside
866 /// it**; a rule naming a nested message does not cover its enclosing
867 /// message. Rules are enable-only, so this builder cannot exclude a
868 /// nested message from a rule that names its parent
869 /// ([`CodeGenConfig::preserve_unknown_fields_in`](buffa_codegen::CodeGenConfig::preserve_unknown_fields_in)
870 /// also accepts disabling entries, and the last matching entry wins).
871 /// Preservation is a property of each message *type*: a preserved
872 /// message's sub-messages keep their own unknown fields only if their
873 /// types are covered too.
874 ///
875 /// Repeated calls accumulate. The call order relative to
876 /// [`preserve_unknown_fields`](Self::preserve_unknown_fields) does not
877 /// matter; the rules apply on top of whichever global value is in force
878 /// at [`compile`](Self::compile) time. They only change the outcome when
879 /// the global setting is off. A rule that matches no generated message
880 /// produces a `cargo:warning` from this build (surfaced via
881 /// [`CodeGenWarning`](buffa_codegen::CodeGenWarning)), since an inert
882 /// rule silently loses round-trip fidelity for the type it was meant to
883 /// keep.
884 ///
885 /// A message that does not preserve unknown fields has no
886 /// `__buffa_unknown_fields` field, and so also loses everything built on
887 /// it: the `ExtensionSet` impl (`extension()` / `set_extension()` /
888 /// `has_extension()`), `ReflectMessage::unknown_fields`, extension
889 /// round-tripping through textproto, and `[ext]` keys in JSON.
890 ///
891 /// ```rust,ignore
892 /// buffa_build::Config::new()
893 /// .preserve_unknown_fields(false)
894 /// .preserve_unknown_fields_in(&[".wa.CallLogRecord", ".wa.SyncdMutation"])
895 /// ```
896 #[must_use]
897 pub fn preserve_unknown_fields_in(mut self, paths: &[impl AsRef<str>]) -> Self {
898 for raw in paths.iter().map(AsRef::as_ref) {
899 let normalized = normalize_override_path(raw);
900 if normalized.is_empty() {
901 println!(
902 "cargo:warning=buffa: preserve_unknown_fields_in path '{raw}' \
903 normalizes to empty and will be ignored"
904 );
905 continue;
906 }
907 self.codegen_config
908 .preserve_unknown_fields_in
909 .push((normalized, true));
910 }
911 self
912 }
913
914 /// Make generated JSON deserializers reject unknown keys instead of
915 /// ignoring them (default: `false`, unknown keys are ignored).
916 ///
917 /// Strictness is fixed in the generated type: code that uses the type
918 /// cannot switch it per call or per process. To be strict for selected
919 /// messages only, use
920 /// [`deny_unknown_json_fields_in`](Self::deny_unknown_json_fields_in).
921 ///
922 /// With [`generate_json`](Self::generate_json) off there are no JSON
923 /// deserializers, so the option changes nothing and the build emits a
924 /// `cargo:warning` saying so.
925 ///
926 /// The guide's "Unknown fields in JSON" section covers the error a
927 /// rejected key produces, how `"[pkg.ext]"` extension keys are treated,
928 /// and what to weigh before enabling this for every message.
929 #[must_use]
930 pub fn deny_unknown_json_fields(mut self, enabled: bool) -> Self {
931 self.codegen_config.deny_unknown_json_fields = enabled;
932 self
933 }
934
935 /// Reject unknown JSON fields for matching messages, on top of the global
936 /// [`deny_unknown_json_fields`](Self::deny_unknown_json_fields) setting.
937 ///
938 /// Each path is a fully-qualified proto path prefix, e.g. `".demo.Config"`
939 /// for one message or `".demo"` for a package (same matching as
940 /// [`preserve_unknown_fields_in`](Self::preserve_unknown_fields_in));
941 /// `"."` matches every message. A leading dot is added if missing and
942 /// trailing dots are trimmed. An empty path is warned about and ignored so
943 /// `"."` remains the only catch-all spelling.
944 ///
945 /// A rule covers the message it names **and every message nested inside
946 /// it**; a rule naming a nested message does not cover its enclosing
947 /// message. Strictness is a property of each message *type*: a strict
948 /// message's sub-messages reject unknown keys only if their types are
949 /// covered too.
950 ///
951 /// Rules only enable, so this builder cannot exempt a message. With the
952 /// global flag on, every message is already strict and these rules add
953 /// nothing; to be strict everywhere except a few messages, leave the
954 /// global flag off and list the strict packages here.
955 /// (`buffa_codegen::CodeGenConfig` accepts disabling entries; neither
956 /// this builder nor the plugin exposes them.) With
957 /// [`generate_json`](Self::generate_json) off the rules change nothing,
958 /// and the build warns as it does for the global flag.
959 ///
960 /// Repeated calls accumulate. A rule that matches no generated message
961 /// produces a `cargo:warning` from this build (surfaced via
962 /// [`CodeGenWarning`](buffa_codegen::CodeGenWarning)), since an inert rule
963 /// leaves the message silently ignoring the keys it was meant to reject.
964 ///
965 /// ```rust,ignore
966 /// buffa_build::Config::new()
967 /// .generate_json(true)
968 /// .deny_unknown_json_fields_in(&[".demo.DeviceConfig"])
969 /// ```
970 #[must_use]
971 pub fn deny_unknown_json_fields_in(mut self, paths: &[impl AsRef<str>]) -> Self {
972 for raw in paths.iter().map(AsRef::as_ref) {
973 let normalized = normalize_override_path(raw);
974 if normalized.is_empty() {
975 println!(
976 "cargo:warning=buffa: deny_unknown_json_fields_in path '{raw}' \
977 normalizes to empty and will be ignored"
978 );
979 continue;
980 }
981 self.codegen_config
982 .deny_unknown_json_fields_in
983 .push((normalized, true));
984 }
985 self
986 }
987
988 /// Apply a path-scoped editions [`FeatureOverride`] to the compiled
989 /// descriptors before generation.
990 ///
991 /// This is buffa's mechanism for integrators who must work with protos
992 /// they cannot modify: editions unification models proto2 and proto3 as
993 /// editions with fixed feature defaults, and an override behaves as if
994 /// the proto had been migrated to editions with that feature set at the
995 /// matched paths. The supported overrides are the [`FeatureOverride`]
996 /// variants — each is admitted only once buffa's codegen, runtime, and
997 /// validation handle the descriptor states it can create. Overrides
998 /// never change the wire format.
999 ///
1000 /// `path` is a fully-qualified proto path prefix. A rule may name a type
1001 /// (for example, `".my.pkg.Status"`), a field
1002 /// (`".my.pkg.Response.status"`), a package/message prefix, or `"."` for
1003 /// everything the override targets. A leading dot is added if missing.
1004 /// Map enum values match the outer map field path; oneof enum variants
1005 /// match the direct field path. An empty path is warned about and
1006 /// ignored so `"."` remains the only global opt-in spelling. (The
1007 /// `protoc-gen-reallyme-buffa` plugin's `override_feature_in=` option rejects
1008 /// empty paths with a hard error instead: a stray build-script entry
1009 /// shouldn't fail the build, but plugin options are usually
1010 /// machine-assembled, where an empty value is a bug.)
1011 ///
1012 /// Repeated calls accumulate; rule order does not matter. A rule that
1013 /// matches nothing produces a `cargo:warning` from this build (surfaced
1014 /// via [`CodeGenWarning`](buffa_codegen::CodeGenWarning)), since an
1015 /// inert rule silently leaves the affected paths on the semantics the
1016 /// override exists to change.
1017 ///
1018 /// Under reflection, the embedded descriptor pool carries the injected
1019 /// features, so runtime reflection and descriptor-driven dynamic JSON
1020 /// stay consistent with the generated types for both enum-scoped and
1021 /// field-scoped rules. A field-scoped injection is buffa-specific,
1022 /// though: other runtimes reading the exported descriptor set ignore it.
1023 /// See [`FeatureOverride::EnumType`] for how the two scopes differ.
1024 #[must_use]
1025 pub fn override_feature_in(mut self, path: impl AsRef<str>, feature: FeatureOverride) -> Self {
1026 let raw = path.as_ref();
1027 let normalized = normalize_override_path(raw);
1028 if normalized.is_empty() {
1029 // Neutral wording: this also fires for the `open_enums_in` sugar,
1030 // so the message must not name a method the caller didn't invoke.
1031 println!(
1032 "cargo:warning=buffa: feature override path '{raw}' normalizes to empty and will be ignored"
1033 );
1034 return self;
1035 }
1036 self.codegen_config
1037 .feature_overrides
1038 .push((normalized, feature));
1039 self
1040 }
1041
1042 /// Treat selected closed enums (or closed enum fields) as open in the
1043 /// generated representation — shorthand for
1044 /// [`override_feature_in(path, FeatureOverride::EnumType(EnumTypeOverride::Open))`](Self::override_feature_in)
1045 /// applied to each path.
1046 ///
1047 /// Matching closed enum fields generate as `EnumValue<E>` instead of `E`,
1048 /// so unknown wire values are directly visible as `EnumValue::Unknown(n)`.
1049 /// This is an opt-in migration / interop mode: it deliberately changes
1050 /// closed-enum presence behavior for matching fields, making an unknown
1051 /// value read as present instead of unset with the raw value represented
1052 /// through unknown fields. An enum-type rule opens the enum itself, so
1053 /// every field referencing it is affected; a field rule opens just that
1054 /// field, leaving the enum's own declared openness unchanged. Both are
1055 /// honored by buffa's descriptor-driven codecs, which resolve openness
1056 /// per field. Prefer enum-type rules when the descriptor set leaves the
1057 /// process: a field-level `enum_type` is not a spec-valid editions
1058 /// feature, so other runtimes reading the exported set ignore it. That
1059 /// preference does not help for an enum reached through `extern_path` —
1060 /// its descriptor is not in the compiled set to mutate, so even an
1061 /// enum-type rule is carried as a field-level override. Path grammar,
1062 /// accumulation, and inert-rule warnings are as described on
1063 /// [`override_feature_in`](Self::override_feature_in).
1064 #[must_use]
1065 pub fn open_enums_in(mut self, paths: &[impl AsRef<str>]) -> Self {
1066 for path in paths {
1067 self = self.override_feature_in(
1068 path.as_ref(),
1069 FeatureOverride::EnumType(EnumTypeOverride::Open),
1070 );
1071 }
1072 self
1073 }
1074
1075 /// Honor `features.utf8_validation = NONE` by emitting `Vec<u8>` / `&[u8]`
1076 /// for such string fields instead of `String` / `&str` (default: false).
1077 ///
1078 /// When disabled (the default), all string fields map to `String` and
1079 /// UTF-8 is validated on decode — stricter than proto2 requires, but
1080 /// ergonomic and safe.
1081 ///
1082 /// When enabled, string fields with `utf8_validation = NONE` become
1083 /// `Vec<u8>` / `&[u8]`. Decode skips validation; the caller chooses
1084 /// whether to `std::str::from_utf8` (checked) or `from_utf8_unchecked`
1085 /// (trusted-input fast path). This is the only sound Rust mapping when
1086 /// strings may actually contain non-UTF-8 bytes.
1087 ///
1088 /// **Note for proto2 users**: proto2's default is `utf8_validation = NONE`,
1089 /// so enabling this turns ALL proto2 string fields into `Vec<u8>`. Use
1090 /// only for new code or when profiling identifies UTF-8 validation as a
1091 /// bottleneck (it can be 10%+ of decode CPU for string-heavy messages).
1092 ///
1093 /// **JSON note**: fields normalized to bytes serialize as base64 in JSON
1094 /// (the proto3 JSON encoding for `bytes`). Keep strict mapping disabled
1095 /// for fields that need JSON string interop with other implementations.
1096 ///
1097 /// **Interaction with [`use_bytes_type`]**: when both are enabled,
1098 /// `map<bytes, bytes>` values stay `Vec<u8>` (the bytes-keyed JSON helper
1099 /// is concrete `HashMap<Vec<u8>, Vec<u8>>`). All other `bytes` shapes —
1100 /// singular / optional / repeated / oneof / `map<non-bytes, bytes>` —
1101 /// still become `bytes::Bytes`. The asymmetry is documented; if you hit
1102 /// it, see issue #76.
1103 ///
1104 /// [`use_bytes_type`]: Self::use_bytes_type
1105 #[must_use]
1106 pub fn strict_utf8_mapping(mut self, enabled: bool) -> Self {
1107 self.codegen_config.strict_utf8_mapping = enabled;
1108 self
1109 }
1110
1111 /// Permit `option message_set_wire_format = true` on input messages.
1112 ///
1113 /// MessageSet is a legacy Google-internal wire format. Default: `false`
1114 /// (such messages produce a codegen error). Set to `true` only when
1115 /// compiling protos that interoperate with old Google-internal services.
1116 #[must_use]
1117 pub fn allow_message_set(mut self, enabled: bool) -> Self {
1118 self.codegen_config.allow_message_set = enabled;
1119 self
1120 }
1121
1122 /// Declare an external type path mapping.
1123 ///
1124 /// The matched types reference the specified Rust path instead of being
1125 /// generated. This allows shared proto packages to be compiled once in a
1126 /// dedicated crate and referenced from others.
1127 ///
1128 /// `proto_path` is a fully-qualified protobuf path — either a **package**
1129 /// (`".my.common"`, mapping every type under it to a Rust module root) or a
1130 /// single **type FQN** (`".google.protobuf.Timestamp"`, mapping just that
1131 /// type, the prost/tonic idiom). The leading dot is optional and is added
1132 /// automatically. As in prost, the most specific entry wins: an exact type
1133 /// FQN beats a covering package prefix, which in turn beats a shorter
1134 /// prefix.
1135 ///
1136 /// `rust_path` is where the type(s) are accessible — a module root for a
1137 /// package mapping (e.g. `"::common_protos"`) or a full type path for a
1138 /// per-type mapping (e.g. `"::pbjson_types::Timestamp"`). It must be an
1139 /// absolute path (starting with `::` or `crate::`); any other value is
1140 /// emitted into the generated code verbatim and will fail to resolve there.
1141 ///
1142 /// **Nested types** inherit an enclosing message's per-type override:
1143 /// mapping `.my.pkg.Outer` to `::ext::Outer` resolves `.my.pkg.Outer.Inner`
1144 /// to `::ext::outer::Inner` — the override's parent module plus buffa's
1145 /// usual `snake_case(MessageName)` nested-types module (snake case of the
1146 /// *proto* message name, regardless of the override's final segment). This
1147 /// matches the layout of another buffa-generated crate; for a target crate
1148 /// laid out differently, add explicit per-type entries for the nested types
1149 /// as well.
1150 ///
1151 /// # Limitations
1152 ///
1153 /// An extern type that is referenced by a generated **view** must map to
1154 /// another buffa-generated crate — the view path is composed as
1155 /// `<rust_path_root>::__buffa::view::…`, which a non-buffa crate (e.g.
1156 /// `pbjson_types`) does not provide. Map per-type to a buffa crate, or
1157 /// disable views ([`generate_views(false)`](Self::generate_views)), for
1158 /// such types.
1159 ///
1160 /// When JSON generation is enabled, an external message routed through a
1161 /// ProtoJSON container helper must implement
1162 /// `buffa::json_helpers::ProtoElemJson` so generated containers can apply
1163 /// ProtoJSON encoding and reject null elements/values. This includes
1164 /// external wrapper types in repeated/map fields and external message
1165 /// values in bytes-keyed maps; ordinary message containers use serde
1166 /// directly.
1167 ///
1168 /// `proto_path` is `.` or a dotted protobuf package or type name. The
1169 /// leading dot is optional and one trailing dot is ignored;
1170 /// [`compile`](Self::compile) returns an error for a name with an empty
1171 /// segment (`my..common`) or a segment that is not a protobuf identifier.
1172 ///
1173 /// Other misconfigurations (a typo'd FQN target, a non-absolute
1174 /// `rust_path`, or a view-referenced type mapped to a non-buffa crate)
1175 /// are not diagnosed at generation time; they surface as an
1176 /// unresolved-path error when the generated code is compiled.
1177 ///
1178 /// # Example
1179 ///
1180 /// ```rust,ignore
1181 /// buffa_build::Config::new()
1182 /// // Whole-package mapping.
1183 /// .extern_path(".my.common", "::common_protos")
1184 /// // Per-type mapping (issue #111) — overrides the package prefix for
1185 /// // just this type.
1186 /// .extern_path(".google.protobuf.Timestamp", "::common_protos::well_known::Timestamp")
1187 /// .files(&["proto/my_service.proto"])
1188 /// .includes(&["proto/"])
1189 /// .compile()
1190 /// .unwrap();
1191 /// ```
1192 #[must_use]
1193 pub fn extern_path(
1194 mut self,
1195 proto_path: impl Into<String>,
1196 rust_path: impl Into<String>,
1197 ) -> Self {
1198 // Stored as given: `compile` validates the name and normalizes it to
1199 // the fully-qualified form (".my.package" for "my.package"), so its
1200 // error can quote what the caller wrote.
1201 self.codegen_config
1202 .extern_paths
1203 .push((proto_path.into(), rust_path.into()));
1204 self
1205 }
1206
1207 /// Exclude a proto package from code generation.
1208 ///
1209 /// `package` is the proto package to exclude (e.g. `"buf.validate"`,
1210 /// `".gnostic.openapi.v3"`). A leading dot is optional and stripped
1211 /// automatically. The package and all of its sub-packages are excluded:
1212 /// `"buf.validate"` drops both `buf.validate` and `buf.validate.priv`.
1213 ///
1214 /// Use this when proto files from option-only packages (e.g.
1215 /// `buf/validate/validate.proto`, gnostic annotations) end up in the
1216 /// generate set through directory globbing, but you do not want Rust types
1217 /// generated for those packages. Their descriptors remain available for
1218 /// cross-package type resolution; only code generation is skipped.
1219 ///
1220 /// **Warning**: if any kept file references an excluded package as a field
1221 /// type, the generated code will contain dangling `super::…::Type` paths
1222 /// that fail to compile; the build emits a `cargo:warning` naming the
1223 /// file, message, and field before that happens. Pair `exclude_package` with
1224 /// [`extern_path`](Self::extern_path) to map the excluded types to an
1225 /// external crate, or do not list those `.proto` files in
1226 /// [`files`](Self::files).
1227 ///
1228 /// This method can be called multiple times to exclude multiple packages.
1229 ///
1230 /// # Validation
1231 ///
1232 /// [`compile`](Self::compile) returns an error, before running `protoc`, if
1233 /// `package` is empty or contains invalid components (empty segments,
1234 /// consecutive dots). A single leading dot is allowed and stripped.
1235 ///
1236 /// # Example
1237 ///
1238 /// ```rust,ignore
1239 /// buffa_build::Config::new()
1240 /// .exclude_package("buf.validate")
1241 /// .exclude_package(".gnostic.openapi.v3")
1242 /// .files(&["proto/my_service.proto"])
1243 /// .includes(&["proto/", "vendor/"])
1244 /// .compile()
1245 /// .unwrap();
1246 /// ```
1247 #[must_use]
1248 pub fn exclude_package(mut self, package: impl Into<String>) -> Self {
1249 // Stored raw. `compile()` rejects malformed entries up front, and
1250 // `generate_with_diagnostics` strips the optional leading dot.
1251 self.codegen_config.exclude_packages.push(package.into());
1252 self
1253 }
1254
1255 /// Configure `bytes` fields to use `bytes::Bytes` instead of `Vec<u8>`.
1256 ///
1257 /// Each path is a fully-qualified proto path prefix. Use `"."` to apply
1258 /// to all bytes fields, or specify individual field paths like
1259 /// `".my.pkg.MyMessage.data"`. Path normalization and the warning for a
1260 /// rule that matches nothing are as described on
1261 /// [`bytes_type_in`](Self::bytes_type_in).
1262 ///
1263 /// Applies uniformly to singular, optional, repeated, oneof, **and
1264 /// `map<K, bytes>`** values — the map case lets `view → owned`
1265 /// conversion participate in the `to_owned_from_source` zero-copy
1266 /// `slice_ref` path. One carve-out: an effective `map<bytes, bytes>` keeps
1267 /// `Vec<u8>` values (the JSON helper for that combination is concrete
1268 /// `HashMap<Vec<u8>, Vec<u8>>`); every other shape becomes `Bytes`. A
1269 /// `bytes` map key is only reachable when [`strict_utf8_mapping`] is enabled
1270 /// *and* the `map<string, bytes>` field carries
1271 /// `[features.utf8_validation = NONE]` on its key, which normalizes the
1272 /// string key to `bytes` — `strict_utf8_mapping` alone does not trigger it.
1273 ///
1274 /// A **custom** `bytes` representation
1275 /// ([`bytes_type_custom`](Self::bytes_type_custom)) is honored for
1276 /// `map<K, bytes>` values too, the same as the built-in `Bytes` — but a
1277 /// custom map value (like a custom `repeated` element) must be a crate-local
1278 /// type, since codegen emits its `ReflectElement` / `InspectElement` /
1279 /// `ProtoElemJson` impls (the orphan rule forbids them for a foreign type).
1280 /// A type listed with [`json_policy_type`](Self::json_policy_type) gets no
1281 /// `ProtoElemJson` impl, so only vtable reflection or reflection with
1282 /// message cleanup requires it to be local.
1283 ///
1284 /// [`strict_utf8_mapping`]: Self::strict_utf8_mapping
1285 ///
1286 /// # Example
1287 ///
1288 /// ```rust,ignore
1289 /// buffa_build::Config::new()
1290 /// .use_bytes_type_in(&["."]) // all bytes fields use Bytes
1291 /// .files(&["proto/my_service.proto"])
1292 /// .includes(&["proto/"])
1293 /// .compile()
1294 /// .unwrap();
1295 /// ```
1296 #[must_use]
1297 pub fn use_bytes_type_in(self, paths: &[impl AsRef<str>]) -> Self {
1298 self.bytes_type_in(BytesRepr::Bytes, paths)
1299 }
1300
1301 /// Use `bytes::Bytes` for all `bytes` fields in all messages.
1302 ///
1303 /// This is a convenience for `.use_bytes_type_in(&["."])`. Use
1304 /// [`use_bytes_type_in`] with specific proto paths if you only want `Bytes`
1305 /// for certain fields. See that method for the path-matching semantics, the
1306 /// `map<K, bytes>` rule, and the `map<bytes, bytes>` carve-out under
1307 /// [`strict_utf8_mapping`].
1308 ///
1309 /// [`use_bytes_type_in`]: Self::use_bytes_type_in
1310 /// [`strict_utf8_mapping`]: Self::strict_utf8_mapping
1311 #[must_use]
1312 pub fn use_bytes_type(self) -> Self {
1313 self.bytes_type(BytesRepr::Bytes)
1314 }
1315
1316 /// Map `bytes` fields to a [`BytesRepr`] other than `Vec<u8>` for the given
1317 /// proto path prefixes. The bytes counterpart to
1318 /// [`string_type_in`](Self::string_type_in).
1319 ///
1320 /// Each path is a fully-qualified proto path prefix: a field
1321 /// (`".my.pkg.Msg.data"`), a message, a package, or `"."` for every field.
1322 /// A leading dot is added to each path if missing, surrounding whitespace
1323 /// and trailing dots are ignored, and a blank entry is skipped with a
1324 /// `cargo:warning`.
1325 ///
1326 /// A rule whose path does not match a field of any type in a generated
1327 /// message produces a `cargo:warning`
1328 /// ([`CodeGenWarning::FieldTypeRuleMatchedNothing`](buffa_codegen::CodeGenWarning::FieldTypeRuleMatchedNothing)).
1329 /// A path that matches only fields of another type does not warn.
1330 ///
1331 /// Rules accumulate and the **last** matching rule wins, so call the broad
1332 /// [`bytes_type`](Self::bytes_type) *first*, then `bytes_type_in` for
1333 /// narrower overrides. For [`BytesRepr::Custom`], the downstream crate must
1334 /// depend on the crate providing the type (buffa does not re-export it).
1335 /// Only the owned Rust type changes — the wire format is unchanged and view
1336 /// types still borrow `&[u8]`.
1337 #[must_use]
1338 pub fn bytes_type_in(mut self, repr: BytesRepr, paths: &[impl AsRef<str>]) -> Self {
1339 self.codegen_config.bytes_fields.extend(
1340 field_rule_paths("bytes_type_in", paths)
1341 .into_iter()
1342 .map(|path| (path, repr.clone())),
1343 );
1344 self
1345 }
1346
1347 /// Map every `bytes` field in all messages to the given [`BytesRepr`].
1348 /// Convenience for `.bytes_type_in(repr, &["."])`; call before any
1349 /// [`bytes_type_in`](Self::bytes_type_in) overrides (last matching rule
1350 /// wins).
1351 #[must_use]
1352 pub fn bytes_type(mut self, repr: BytesRepr) -> Self {
1353 self.codegen_config
1354 .bytes_fields
1355 .push((".".to_string(), repr));
1356 self
1357 }
1358
1359 /// Map the matching `bytes` fields to a custom type named by its
1360 /// fully-qualified Rust path (e.g. `"::my_crate::MyBytes"`). The type must
1361 /// satisfy `buffa::ProtoBytes`, and the downstream crate must depend on the
1362 /// crate providing it. Shorthand for
1363 /// [`bytes_type_in`](Self::bytes_type_in)`(BytesRepr::Custom(path), paths)`.
1364 ///
1365 /// # Limitations
1366 ///
1367 /// - A **foreign** custom type used as a `repeated` element — or a
1368 /// `map<K, bytes>` value — fails to compile under JSON, vtable reflection
1369 /// or reflection with message cleanup: codegen emits `ProtoElemJson` /
1370 /// `ReflectElement` / `InspectElement` impls for it, which the orphan
1371 /// rule forbids for a foreign type. Wrap it in a crate-local newtype, or use
1372 /// [`emit_custom_type_impls(false)`](Self::emit_custom_type_impls) when
1373 /// the defining crate supplies those integrations. Singular / optional /
1374 /// oneof uses work directly. A type listed with
1375 /// [`json_policy_type`](Self::json_policy_type) gets no `ProtoElemJson`
1376 /// impl, so only vtable reflection or reflection with message cleanup
1377 /// requires it to be local.
1378 /// - A `Custom` rule **does** apply to `map<K, bytes>` values (honored like
1379 /// the built-in [`BytesRepr::Bytes`]); only the `map<bytes, bytes>`
1380 /// carve-out keeps `Vec<u8>` values.
1381 /// - A `path` that is not a Rust type path like `crate::Name` (for
1382 /// example `_`, `()` or `&'static [u8]`) is reported as a codegen error
1383 /// from [`compile`](Self::compile). Associated-type projections and
1384 /// parenthesized type paths are supported.
1385 /// - A custom bytes type needs no native `arbitrary::Arbitrary` impl (a
1386 /// generic builder handles it under `generate_arbitrary`).
1387 #[must_use]
1388 pub fn bytes_type_custom_in(self, path: &str, paths: &[impl AsRef<str>]) -> Self {
1389 self.bytes_type_in(BytesRepr::Custom(path.to_string()), paths)
1390 }
1391
1392 /// Map every `bytes` field to the given custom type path. Convenience for
1393 /// `.bytes_type_custom_in(path, &["."])`; see it for the limitations
1394 /// (foreign `repeated` elements, `map` values, path parsing).
1395 #[must_use]
1396 pub fn bytes_type_custom(self, path: &str) -> Self {
1397 self.bytes_type(BytesRepr::Custom(path.to_string()))
1398 }
1399
1400 /// Store the matching message-typed oneof variants inline instead of
1401 /// wrapping them in `Box<T>`.
1402 ///
1403 /// By default every message/group oneof variant is boxed so that recursive
1404 /// types compile. For non-recursive variants the `Box` is pure overhead (an
1405 /// allocation per construction); this opts the matching variants out.
1406 /// This affects the owned message enum only — view oneof variants remain
1407 /// boxed.
1408 ///
1409 /// Each path is a fully-qualified proto variant path prefix, e.g.
1410 /// `".my.pkg.MyMessage.body.small"` for one variant or `".my.pkg"` for a
1411 /// package (same matching as [`use_bytes_type_in`](Self::use_bytes_type_in)).
1412 /// Paths are normalized as for [`bytes_type_in`](Self::bytes_type_in). A
1413 /// rule that matches no variant is not reported.
1414 ///
1415 /// Recursive variants cannot be stored inline (the type would be
1416 /// unsized). A rule that names a recursive variant *exactly* is rejected
1417 /// at codegen time; a broader prefix rule silently keeps recursive
1418 /// variants boxed and inlines the rest. For example, with
1419 /// `unbox_oneof_in(&[".my.pkg.Node"])`, a self-referential
1420 /// `Node.kind.child` variant stays boxed while `Node`'s other message
1421 /// variants become inline.
1422 #[must_use]
1423 pub fn unbox_oneof_in(mut self, paths: &[impl AsRef<str>]) -> Self {
1424 self.codegen_config
1425 .unboxed_oneof_fields
1426 // The exact-path recursion error compares against the normalized
1427 // form.
1428 .extend(field_rule_paths("unbox_oneof_in", paths));
1429 self
1430 }
1431
1432 /// Store every non-recursive message-typed oneof variant inline instead of
1433 /// boxing it. Convenience for `.unbox_oneof_in(&["."])`; recursive
1434 /// variants stay boxed.
1435 #[must_use]
1436 pub fn unbox_oneof(mut self) -> Self {
1437 self.codegen_config
1438 .unboxed_oneof_fields
1439 .push(".".to_string());
1440 self
1441 }
1442
1443 /// Map `string` fields to a [`StringRepr`] other than `String` for the
1444 /// given proto path prefixes. The string counterpart to
1445 /// [`use_bytes_type_in`](Self::use_bytes_type_in).
1446 ///
1447 /// Each path is a fully-qualified proto path prefix (e.g.
1448 /// `".my.pkg.MyMessage.name"` for one field, `".my.pkg"` for a package).
1449 ///
1450 /// Rules accumulate and the **last** matching rule wins. Order therefore
1451 /// matters: call [`string_type`](Self::string_type) (the broad default)
1452 /// *first*, then `string_type_in` for narrower overrides — a broad rule
1453 /// added after a specific one will shadow it.
1454 ///
1455 /// For [`StringRepr::Custom`], the type must implement `buffa::ProtoString`,
1456 /// and the downstream crate must depend on the crate providing it (buffa does
1457 /// not re-export it). A foreign type cannot implement `ProtoString` directly
1458 /// (orphan rule) — point at a local newtype, or the `buffa-smolstr` crate for
1459 /// `smol_str::SmolStr`.
1460 ///
1461 /// Only the owned Rust type changes: the wire format is unchanged and view
1462 /// types still borrow `&str`. A rule that matches a `map` field applies to
1463 /// its `string` key and its `string` value.
1464 ///
1465 /// Path normalization and the warning for a rule that matches nothing are
1466 /// as described on [`bytes_type_in`](Self::bytes_type_in).
1467 ///
1468 /// # Example
1469 ///
1470 /// ```rust,ignore
1471 /// buffa_build::Config::new()
1472 /// .string_type_custom("::buffa_smolstr::SmolStr") // broad default first
1473 /// .string_type_custom_in("::my_crate::CompactStr", &[".my.pkg.Msg.body"]) // narrow override
1474 /// .files(&["proto/my_service.proto"])
1475 /// .includes(&["proto/"])
1476 /// .compile()
1477 /// .unwrap();
1478 /// ```
1479 #[must_use]
1480 pub fn string_type_in(mut self, repr: StringRepr, paths: &[impl AsRef<str>]) -> Self {
1481 self.codegen_config.string_fields.extend(
1482 field_rule_paths("string_type_in", paths)
1483 .into_iter()
1484 .map(|path| (path, repr.clone())),
1485 );
1486 self
1487 }
1488
1489 /// Map every `string` field in all messages to the given [`StringRepr`].
1490 ///
1491 /// Convenience for `.string_type_in(repr, &["."])`. Call this *before* any
1492 /// [`string_type_in`](Self::string_type_in) overrides, since the last
1493 /// matching rule wins (a `"."` rule added later shadows earlier specific
1494 /// rules). The rule also covers the `string` keys and values of `map`
1495 /// fields.
1496 #[must_use]
1497 pub fn string_type(mut self, repr: StringRepr) -> Self {
1498 self.codegen_config
1499 .string_fields
1500 .push((".".to_string(), repr));
1501 self
1502 }
1503
1504 /// Map the matching `string` fields to a custom type that implements
1505 /// `buffa::ProtoString`, named by its fully-qualified Rust path (e.g.
1506 /// `"::buffa_smolstr::SmolStr"`, or a local newtype — a foreign type cannot
1507 /// implement the trait directly). The downstream crate must depend on the
1508 /// crate providing it. Shorthand for
1509 /// [`string_type_in`](Self::string_type_in)`(StringRepr::Custom(path), paths)`.
1510 ///
1511 /// # Limitations
1512 ///
1513 /// - Under vtable reflection ([`reflect_mode`](Self::reflect_mode) with
1514 /// `ReflectMode::VTable`), or any reflection with message cleanup, a
1515 /// **foreign** custom type used as a `repeated` element or as a `map` key
1516 /// or value fails to compile: codegen emits a `ReflectElement`,
1517 /// `InspectElement` or `ReflectMapKey` impl for it, which the orphan rule
1518 /// forbids for a foreign type. Wrap it in a crate-local newtype, or use
1519 /// [`emit_custom_type_impls(false)`](Self::emit_custom_type_impls) when
1520 /// the defining crate supplies those integrations. Singular / optional /
1521 /// oneof uses work directly.
1522 /// - **JSON of a custom string with explicit presence (proto3 or proto2
1523 /// `optional`, and the edition 2023 default), in a `repeated` field, in
1524 /// a oneof, or in a `map`,** serializes through the type's own `serde`
1525 /// impls, so such a type must implement `Serialize` / `Deserialize`. A
1526 /// `buffa-remote-derive` newtype gets them from
1527 /// `#[buffa(remote = ..., serde)]`; any other type derives them (an
1528 /// external type enables its `serde` feature). A singular field with
1529 /// implicit presence, or a proto2 `required` field, uses the
1530 /// `proto_string` with-module and needs no `serde` impl, and so does a
1531 /// type listed with [`json_policy_type`](Self::json_policy_type), whose
1532 /// JSON goes through its policy in every generated JSON position.
1533 /// - A custom type used as a `map` key must implement `Hash + Eq` for the
1534 /// default `HashMap` container, or `Ord` for `BTreeMap`.
1535 /// - A `path` that is not a Rust type path like `crate::Name` (for
1536 /// example `_`, `()` or `&'static [u8]`) is reported as a codegen error
1537 /// from [`compile`](Self::compile). Associated-type projections and
1538 /// parenthesized type paths are supported.
1539 /// - A custom string type needs no native `arbitrary::Arbitrary` impl (a
1540 /// generic builder handles it under `generate_arbitrary`, as a `map` key
1541 /// or value too).
1542 #[must_use]
1543 pub fn string_type_custom_in(self, path: &str, paths: &[impl AsRef<str>]) -> Self {
1544 self.string_type_in(StringRepr::Custom(path.to_string()), paths)
1545 }
1546
1547 /// Route the protobuf JSON of a custom `bytes` or `string` representation
1548 /// through its `buffa::json_helpers::ProtoBytesJson` or `ProtoStringJson`
1549 /// impl.
1550 ///
1551 /// `path` names the type exactly as its
1552 /// [`bytes_type_custom_in`](Self::bytes_type_custom_in) or
1553 /// [`string_type_custom_in`](Self::string_type_custom_in) rule does
1554 /// (whitespace aside). Every field of that type then serializes and
1555 /// deserializes through the policy in the generated `serde` impls:
1556 /// singular, optional, repeated and oneof fields, `map` keys and values,
1557 /// and the matching fields of generated views, lazy views and owned views.
1558 /// The type's own `serde` impls are not consulted.
1559 /// Generated code implements no JSON trait for the type (repeated elements
1560 /// and `map` values go through buffa's policy with-modules). With JSON
1561 /// alone, the type may therefore be defined, together with its
1562 /// representation and policy impls, in another crate, and separate
1563 /// `compile()` runs into one crate may share it. With vtable reflection,
1564 /// or reflection with message cleanup, its `repeated` and `map` uses still
1565 /// get per-run element impls, so there it must be crate-local and
1566 /// generated in one run (or use
1567 /// [`emit_custom_type_impls(false)`](Self::emit_custom_type_impls)). Call
1568 /// it once per type, in every `Config` that generates a field of the type:
1569 /// a run that does not list it never calls the policy (bytes fields become
1570 /// plain base64; string fields use the type's own `serde` impls). Unlisted
1571 /// custom types keep their existing JSON behavior.
1572 ///
1573 /// A policy shapes only the generated JSON and is not a confidentiality
1574 /// boundary. Binary encoding, generated text format and descriptor-driven
1575 /// reflection never call it: JSON produced or read through `DynamicMessage`
1576 /// (including a message converted with `ReflectMessage::to_dynamic`, or with
1577 /// `DynamicMessage::try_from_message`, which works whether or not
1578 /// reflection is generated) encodes the field as standard base64 or a
1579 /// plain string, so a policy that refuses export does not stop it and its
1580 /// import checks do not run.
1581 ///
1582 /// # Limitations
1583 ///
1584 /// - The type must implement the policy trait; a missing impl is a
1585 /// compile error in the generated code, naming the trait.
1586 /// - A listed `string` type used as the key of a `map` with enum values
1587 /// is a codegen error from [`compile`](Self::compile).
1588 /// - A listed `string` type used as a `map` key must have a policy that
1589 /// round-trips, and so is injective (see the `ProtoStringJson` contract):
1590 /// otherwise import loses or alters entries. This is not checked.
1591 /// - A type that no effective representation rule selects is an error.
1592 /// Binding and spelling errors remain errors with JSON disabled. A valid
1593 /// listed type while [`generate_json`](Self::generate_json) is off
1594 /// produces a `cargo:warning` because its policy is inactive.
1595 /// - With JSON and reflection both on
1596 /// ([`generate_reflection`](Self::generate_reflection), or any
1597 /// [`reflect_mode`](Self::reflect_mode) other than off), listing any type
1598 /// produces one `cargo:warning` per `compile()` that reflective JSON
1599 /// bypasses the policy. It is a standing reminder, not a check of your
1600 /// schema, and buffa-build always prints it.
1601 #[must_use]
1602 pub fn json_policy_type(mut self, path: &str) -> Self {
1603 self.codegen_config
1604 .json_policy_types
1605 .push(path.trim().to_string());
1606 self
1607 }
1608
1609 /// Control emission of custom bytes/string element integration impls.
1610 ///
1611 /// Set this to `false` when shared representation types provide their
1612 /// `ProtoElemJson`, `ReflectElement`, `ReflectMapKey` and `InspectElement` implementations in
1613 /// their defining crate. A type listed with
1614 /// [`json_policy_type`](Self::json_policy_type) needs no `ProtoElemJson`.
1615 /// This permits foreign types and multiple generation calls without
1616 /// orphan-rule or duplicate-impl errors. Missing traits fail
1617 /// compilation; JSON policy selection is still required separately.
1618 #[must_use]
1619 pub fn emit_custom_type_impls(mut self, enabled: bool) -> Self {
1620 self.codegen_config.emit_custom_type_impls = enabled;
1621 self
1622 }
1623
1624 /// Permit global message selectors absent from a scoped generation request.
1625 /// Unmatched selectors still warn. Validate the complete project with this
1626 /// disabled to catch misspelled cleanup or view-export rules as errors.
1627 #[must_use]
1628 pub fn allow_unmatched_message_rules(mut self, enabled: bool) -> Self {
1629 self.codegen_config.allow_unmatched_message_rules = enabled;
1630 self
1631 }
1632
1633 /// Map every `string` field to the given custom type path. Convenience for
1634 /// `.string_type_custom_in(path, &["."])`; see it for the limitations.
1635 #[must_use]
1636 pub fn string_type_custom(self, path: &str) -> Self {
1637 self.string_type(StringRepr::Custom(path.to_string()))
1638 }
1639
1640 /// Map the matching `map` fields to a [`MapRepr`] other than the default
1641 /// `HashMap`. Rules are matched with proto-segment-aware prefix logic; the
1642 /// **last** matching rule wins, so add a broad rule first and narrower
1643 /// overrides after.
1644 ///
1645 /// Path normalization and the warning for a rule that matches nothing are
1646 /// as described on [`bytes_type_in`](Self::bytes_type_in).
1647 ///
1648 /// Use [`MapRepr::BTreeMap`] for the buffa-provided `BTreeMap` (deterministic
1649 /// key order, no extra dependency, no consumer code), or
1650 /// [`MapRepr::Custom`] for a crate-local newtype that implements
1651 /// `buffa::map_codec::MapStorage`.
1652 ///
1653 /// Only the owned collection changes: the wire format is unchanged and view
1654 /// types are unaffected.
1655 ///
1656 /// # Example
1657 ///
1658 /// ```rust,ignore
1659 /// buffa_build::Config::new()
1660 /// .map_type(buffa_build::MapRepr::BTreeMap) // broad default
1661 /// .map_type_in(buffa_build::MapRepr::HashMap, &[".my.pkg.Msg.cache"]) // narrow override
1662 /// .compile()
1663 /// .unwrap();
1664 /// ```
1665 #[must_use]
1666 pub fn map_type_in(mut self, repr: MapRepr, paths: &[impl AsRef<str>]) -> Self {
1667 self.codegen_config.map_fields.extend(
1668 field_rule_paths("map_type_in", paths)
1669 .into_iter()
1670 .map(|path| (path, repr.clone())),
1671 );
1672 self
1673 }
1674
1675 /// Map every `map` field in all messages to the given [`MapRepr`].
1676 /// Convenience for `.map_type_in(repr, &["."])`. Call this *before* any
1677 /// [`map_type_in`](Self::map_type_in) overrides, since the last matching
1678 /// rule wins.
1679 #[must_use]
1680 pub fn map_type(mut self, repr: MapRepr) -> Self {
1681 self.codegen_config.map_fields.push((".".to_string(), repr));
1682 self
1683 }
1684
1685 /// Encode map entries as prost does: leave an entry's key or value out
1686 /// when it holds the default (default: false, both are always written, as
1687 /// the C++ and Java runtimes write them). Entries themselves are never
1688 /// dropped.
1689 ///
1690 /// For migrations from prost where stored or hashed map encodings must
1691 /// not change. Decoding is unchanged: buffa, like every protobuf runtime,
1692 /// reads both forms to the same map. One value does not survive the round
1693 /// trip: a `-0.0` float value is left out, as prost leaves it out, and
1694 /// decodes as `0.0`.
1695 ///
1696 /// The default is what a missing field decodes to: zero, `false`, empty,
1697 /// an open enum's 0 or a closed enum's first value. A message value is
1698 /// left out when it encodes to nothing.
1699 ///
1700 /// # Differences from prost
1701 ///
1702 /// - prost leaves out a message value equal to its default. A value that
1703 /// equals its default and still encodes a field, such as one with a
1704 /// `required` field at its default or a float field holding `-0.0`, is
1705 /// written here and not by prost.
1706 /// - A value of an enum made open with
1707 /// [`open_enums_in`](Self::open_enums_in) is left out at 0, which a
1708 /// missing open enum decodes to, where prost leaves out the enum's
1709 /// first value. The two differ only for an enum whose first value is
1710 /// not 0. protoc rejects that as a map value, so the case can occur
1711 /// only with a descriptor set that another tool built
1712 /// ([`use_buf`](Self::use_buf), [`descriptor_set`](Self::descriptor_set)).
1713 /// - The option covers the entries' bytes only. For a map with more than
1714 /// one entry to encode identically, the entries must also come in the
1715 /// same order: use [`map_type`](Self::map_type) with
1716 /// [`MapRepr::BTreeMap`] where prost used `btree_map`.
1717 ///
1718 /// # Scope
1719 ///
1720 /// - The option applies to the owned, view and lazy view encoders of the
1721 /// messages generated in this run. Each crate's types encode as that
1722 /// crate was generated.
1723 /// - `google.protobuf.Struct`, the well-known type with a map field,
1724 /// comes from `buffa-types` and writes both fields, and so does
1725 /// `DynamicMessage`.
1726 /// - A lazy view keeps its singular and repeated message fields undecoded
1727 /// and writes them as they were read, so map entries inside them keep
1728 /// the encoding they arrived with. Every encoder writes entries kept as
1729 /// unknown fields as they were read.
1730 /// - With [`CodecStrategy::Table`], messages with a map field keep the
1731 /// unrolled codec, and a
1732 /// [`codec_strategy_in`](Self::codec_strategy_in) rule that selects the
1733 /// table for such a message by its exact path is an error.
1734 #[must_use]
1735 pub fn map_entries_omit_defaults(mut self, enabled: bool) -> Self {
1736 self.codegen_config.map_entries_omit_defaults = enabled;
1737 self
1738 }
1739
1740 /// Map the matching `map` fields to a custom collection implementing
1741 /// `buffa::map_codec::MapStorage`, named by its fully-qualified Rust path
1742 /// (e.g. `"::my_crate::OrderedMap"`). The path must **not** include the
1743 /// `<K, V>` parameters — they are applied positionally. Shorthand for
1744 /// [`map_type_in`](Self::map_type_in)`(MapRepr::Custom(path), paths)`.
1745 ///
1746 /// # Limitations
1747 ///
1748 /// - The path must name a **crate-local newtype** — a foreign map cannot
1749 /// implement the buffa-owned reflection / serde traits (orphan rule).
1750 /// Prefer the built-in [`MapRepr::BTreeMap`] unless you need a specific
1751 /// foreign map.
1752 /// - The newtype must implement `buffa::MapStorage` plus the derive /
1753 /// `FromIterator` / `ReflectMap` / serde / `arbitrary` bounds documented on
1754 /// `buffa::map_codec::MapStorage` (the canonical list). JSON and
1755 /// `arbitrary` work for every proto map key/value type regardless of the
1756 /// container.
1757 /// - A path that does not parse as a Rust type is reported as a codegen
1758 /// error from [`compile`](Self::compile).
1759 #[must_use]
1760 pub fn map_type_custom_in(self, path: &str, paths: &[impl AsRef<str>]) -> Self {
1761 self.map_type_in(MapRepr::Custom(path.to_string()), paths)
1762 }
1763
1764 /// Map every `map` field to the given custom collection path. Convenience
1765 /// for `.map_type_custom_in(path, &["."])`; see it for the limitations (the
1766 /// crate-local newtype requirement, the trait bounds, path parsing).
1767 #[must_use]
1768 pub fn map_type_custom(self, path: &str) -> Self {
1769 self.map_type(MapRepr::Custom(path.to_string()))
1770 }
1771
1772 /// Map the matching message fields to a [`PointerRepr`] other than the
1773 /// default `Inline`. Rules are matched with proto-segment-aware prefix
1774 /// logic; the **last** matching rule wins, so add a broad rule first and
1775 /// narrower overrides after.
1776 ///
1777 /// Paths are normalized as for [`bytes_type_in`](Self::bytes_type_in). A
1778 /// rule that matches no field is not reported.
1779 ///
1780 /// The default `Inline` is recursion-aware (recursive fields stay on
1781 /// `Box`), so this knob is for opting *out*: `PointerRepr::Box` for large
1782 /// or rarely-set submessages where reserving `size_of::<T>()` in the parent
1783 /// is wasteful, or `PointerRepr::Custom` for a third-party pointer.
1784 ///
1785 /// Applies to singular (and proto2 optional/required) message fields and to
1786 /// **boxed** oneof message/group variants (matched by the variant's path).
1787 /// A oneof variant opted into inline storage via [`unbox_oneof_in`](Self::unbox_oneof_in)
1788 /// takes precedence and gets no pointer; recursive variants stay boxed and so
1789 /// accept a custom pointer. Repeated message fields use a collection, not a
1790 /// pointer. For [`PointerRepr::Custom`], the pointer must implement
1791 /// `buffa::ProtoBox<T>` and be a crate-local newtype; the path is a
1792 /// **template** with a `*` placeholder for the message type (e.g.
1793 /// `"::my_crate::SmallBox<*>"`).
1794 ///
1795 /// Only the in-memory pointer changes: the wire format is unchanged and view
1796 /// types are unaffected.
1797 #[must_use]
1798 pub fn box_type_in(mut self, repr: PointerRepr, paths: &[impl AsRef<str>]) -> Self {
1799 self.codegen_config
1800 .pointer_fields
1801 // The exact-path Inline recursion error compares against the
1802 // normalized form.
1803 .extend(
1804 field_rule_paths("box_type_in", paths)
1805 .into_iter()
1806 .map(|path| (path, repr.clone())),
1807 );
1808 self
1809 }
1810
1811 /// Choose how the binary `Message` implementation of every message is
1812 /// generated (default: [`CodecStrategy::Unrolled`]).
1813 ///
1814 /// On a large schema, [`CodecStrategy::Table`] makes the compiled code
1815 /// about 40% smaller at `opt-level = "z"`, and it slows messages made of
1816 /// many small fields; a message that cannot use it keeps its size.
1817 /// [`CodecStrategy::Table`] says which messages stay unrolled and how a
1818 /// table message behaves differently, and this build reports the messages
1819 /// that stay unrolled in one `cargo:warning`. The option never changes the
1820 /// wire format. The generated code needs Rust 1.77 or later, and `compile`
1821 /// returns an error on an older compiler when a build script runs it (the
1822 /// compiler is read from `RUSTC`).
1823 ///
1824 /// Path-scoped rules for individual messages go in
1825 /// [`codec_strategy_in`](Self::codec_strategy_in), and take precedence
1826 /// over this setting whatever the call order.
1827 ///
1828 /// ```rust,ignore
1829 /// // build.rs
1830 /// buffa_build::Config::new()
1831 /// .files(&["proto/wa.proto"])
1832 /// .includes(&["proto/"])
1833 /// .codec_strategy(buffa_build::CodecStrategy::Table)
1834 /// .codec_strategy_in(buffa_build::CodecStrategy::Unrolled, &[".wa.Message"])
1835 /// .compile()?;
1836 /// ```
1837 #[must_use]
1838 pub fn codec_strategy(mut self, strategy: CodecStrategy) -> Self {
1839 self.codegen_config.codec_strategy = strategy;
1840 self
1841 }
1842
1843 /// Choose the [`CodecStrategy`] of the matching messages, on top of the
1844 /// global [`codec_strategy`](Self::codec_strategy).
1845 ///
1846 /// Each path is a fully-qualified proto path prefix, e.g. `".wa.Message"`
1847 /// for one message or `".wa"` for a package (same matching as
1848 /// [`preserve_unknown_fields_in`](Self::preserve_unknown_fields_in));
1849 /// `"."` matches every message. A leading dot is added if missing,
1850 /// trailing dots are trimmed, and a path that is empty after that prints a
1851 /// `cargo:warning` and is ignored. A rule covers the message it names
1852 /// **and every message nested inside it**. The **last** matching rule wins,
1853 /// so call this after any broader rule.
1854 ///
1855 /// A message selected for the table by a rule that cannot use it stays
1856 /// unrolled and is counted in the warning, and it is an error if the rule
1857 /// names the message by its exact path. A rule that matches no message
1858 /// produces a warning.
1859 ///
1860 /// A rule does not extend to the messages a message holds; see
1861 /// [`CodecStrategy::Table`].
1862 #[must_use]
1863 pub fn codec_strategy_in(mut self, strategy: CodecStrategy, paths: &[impl AsRef<str>]) -> Self {
1864 for raw in paths.iter().map(AsRef::as_ref) {
1865 let normalized = normalize_override_path(raw);
1866 if normalized.is_empty() {
1867 println!(
1868 "cargo:warning=buffa: codec_strategy_in path '{raw}' \
1869 normalizes to empty and will be ignored"
1870 );
1871 continue;
1872 }
1873 self.codegen_config
1874 .codec_strategy_in
1875 .push((normalized, strategy));
1876 }
1877 self
1878 }
1879
1880 /// Map every message field (and boxed oneof variant) to the given [`PointerRepr`].
1881 /// Convenience for `.box_type_in(repr, &["."])`. Call before any
1882 /// [`box_type_in`](Self::box_type_in) overrides, since the last matching
1883 /// rule wins. `box_type(PointerRepr::Box)` restores the pre-0.9 boxed
1884 /// default for every singular message field.
1885 #[must_use]
1886 pub fn box_type(mut self, repr: PointerRepr) -> Self {
1887 self.codegen_config
1888 .pointer_fields
1889 .push((".".to_string(), repr));
1890 self
1891 }
1892
1893 /// Map the matching singular message fields to a custom pointer implementing
1894 /// `buffa::ProtoBox<T>`, named by a Rust type-path **template** with a `*`
1895 /// placeholder for the message type (e.g. `"::my_crate::SmallBox<*>"`).
1896 /// Shorthand for
1897 /// [`box_type_in`](Self::box_type_in)`(PointerRepr::Custom(template), paths)`.
1898 ///
1899 /// # Limitations
1900 ///
1901 /// - The template must contain at least one `*`; a template that omits it,
1902 /// or whose substitution does not parse as a Rust type, is reported as a
1903 /// codegen error from [`compile`](Self::compile).
1904 /// - The pointer must be exclusively owned (`Rc`/`Arc` are unusable — the
1905 /// decoder needs `DerefMut`) and a crate-local newtype (a foreign pointer
1906 /// cannot implement the buffa-owned `ProtoBox`).
1907 #[must_use]
1908 pub fn box_type_custom_in(self, template: &str, paths: &[impl AsRef<str>]) -> Self {
1909 self.box_type_in(PointerRepr::Custom(template.to_string()), paths)
1910 }
1911
1912 /// Map every message field (and boxed oneof variant) to the given custom pointer template.
1913 /// Convenience for `.box_type_custom_in(template, &["."])`; see it for the
1914 /// limitations (the `*` placeholder, `Rc`/`Arc` exclusion, newtype rule).
1915 #[must_use]
1916 pub fn box_type_custom(self, template: &str) -> Self {
1917 self.box_type(PointerRepr::Custom(template.to_string()))
1918 }
1919
1920 /// Map the matching `repeated` fields to a [`RepeatedRepr`] other than the
1921 /// default `Vec<T>`. Rules are matched with proto-segment-aware prefix
1922 /// logic; the **last** matching rule wins, so add a broad rule first and
1923 /// narrower overrides after. Applies only to `repeated` fields (not `map`).
1924 ///
1925 /// Path normalization and the warning for a rule that matches nothing are
1926 /// as described on [`bytes_type_in`](Self::bytes_type_in).
1927 ///
1928 /// For [`RepeatedRepr::Custom`], the collection must implement
1929 /// `buffa::ProtoList<T>`. Unlike the scalar `string_type_custom` /
1930 /// `bytes_type_custom` knobs (which take a *complete* type path), this path
1931 /// is a **template** with a `*` placeholder for the element type. Existing
1932 /// `ProtoList` implementations work through aliases and associated types.
1933 /// If the defining crate provides no implementation, use a crate-local
1934 /// newtype to satisfy the orphan rule. See [`RepeatedRepr::Custom`] for
1935 /// the bounds required by JSON, reflection and arbitrary generation.
1936 ///
1937 /// Only the owned collection changes: the wire format is unchanged and view
1938 /// types still borrow `&[T]`.
1939 ///
1940 /// # Example
1941 ///
1942 /// ```rust,ignore
1943 /// // `SmallList<T>` is a crate-local newtype over smallvec::SmallVec that
1944 /// // implements buffa::ProtoList (see the ProtoList docs for the template).
1945 /// buffa_build::Config::new()
1946 /// .repeated_type_custom("::my_crate::SmallList<*>") // broad default
1947 /// .repeated_type_custom_in("::my_crate::SmallList8<*>", &[".my.pkg.Msg.tags"])
1948 /// .compile()
1949 /// .unwrap();
1950 /// ```
1951 #[must_use]
1952 pub fn repeated_type_in(mut self, repr: RepeatedRepr, paths: &[impl AsRef<str>]) -> Self {
1953 self.codegen_config.repeated_fields.extend(
1954 field_rule_paths("repeated_type_in", paths)
1955 .into_iter()
1956 .map(|path| (path, repr.clone())),
1957 );
1958 self
1959 }
1960
1961 /// Map every `repeated` field in all messages to the given
1962 /// [`RepeatedRepr`]. Convenience for `.repeated_type_in(repr, &["."])`.
1963 /// Call this *before* any [`repeated_type_in`](Self::repeated_type_in)
1964 /// overrides, since the last matching rule wins.
1965 #[must_use]
1966 pub fn repeated_type(mut self, repr: RepeatedRepr) -> Self {
1967 self.codegen_config
1968 .repeated_fields
1969 .push((".".to_string(), repr));
1970 self
1971 }
1972
1973 /// Map the matching `repeated` fields to a custom collection implementing
1974 /// `buffa::ProtoList<T>`, named by a Rust type-path **template** with a `*`
1975 /// placeholder for the element type (e.g. `"::my_crate::SmallList<*>"`).
1976 /// Note the asymmetry with the scalar `string_type_custom` /
1977 /// `bytes_type_custom` knobs: those take a *complete* path, this takes a
1978 /// `*`-template that wraps the element. Shorthand for
1979 /// [`repeated_type_in`](Self::repeated_type_in)`(RepeatedRepr::Custom(template), paths)`.
1980 ///
1981 /// # Limitations
1982 ///
1983 /// - The template must contain at least one `*`; a template that omits it,
1984 /// or whose substitution is not a Rust type path, is reported as a
1985 /// codegen error from [`compile`](Self::compile).
1986 /// - The resolved collection must implement `buffa::ProtoList<T>`. An
1987 /// associated type resolving to `Vec<T>` already satisfies this; a
1988 /// foreign collection without an implementation needs a crate-local
1989 /// newtype to satisfy the orphan rule.
1990 /// - Vtable reflection requires `ReflectList`; cleanup-profile borrowed
1991 /// inspection requires `InspectList`. Ordinary bridge reflection needs
1992 /// neither on the owned collection.
1993 /// - JSON scalar, enum and policy helpers decode through `ProtoList<T>`
1994 /// and the element's JSON traits, without requiring the collection's
1995 /// `Deserialize`. Positions using ordinary serde instead require the
1996 /// collection's `Serialize` / `Deserialize`. See [`RepeatedRepr::Custom`]
1997 /// for the complete representation requirements and `buffa::ProtoList`
1998 /// for a worked newtype example.
1999 #[must_use]
2000 pub fn repeated_type_custom_in(self, template: &str, paths: &[impl AsRef<str>]) -> Self {
2001 self.repeated_type_in(RepeatedRepr::Custom(template.to_string()), paths)
2002 }
2003
2004 /// Map every `repeated` field to the given custom collection template.
2005 /// Convenience for `.repeated_type_custom_in(template, &["."])`; see it for
2006 /// the limitations (the `*` placeholder, foreign reflection, the JSON /
2007 /// `arbitrary` requirements).
2008 #[must_use]
2009 pub fn repeated_type_custom(self, template: &str) -> Self {
2010 self.repeated_type(RepeatedRepr::Custom(template.to_string()))
2011 }
2012
2013 /// Add a custom attribute to generated types (messages and enums)
2014 /// matching a proto path prefix.
2015 ///
2016 /// `path` is a fully-qualified proto path prefix: `"."` applies to all
2017 /// types, `".my.pkg"` to types in that package, `".my.pkg.MyMessage"`
2018 /// to a specific type. A leading `.` is auto-prepended if omitted; a
2019 /// trailing `.` is trimmed. Prefix matching respects proto-segment
2020 /// boundaries, so `".my.pk"` does not match `".my.pkg.Msg"`.
2021 ///
2022 /// `attribute` is one or more outer Rust attributes, each written with
2023 /// its `#[...]` (e.g., `"#[derive(serde::Serialize)]"`). Any other
2024 /// string, such as `"serde(skip)"` or an empty one, makes
2025 /// [`compile`](Self::compile) fail with
2026 /// [`CodeGenError::InvalidCustomAttribute`](buffa_codegen::CodeGenError),
2027 /// whether or not `path` matches a generated type.
2028 ///
2029 /// Multiple calls accumulate in insertion order — all matching attributes
2030 /// are emitted, and ordering is preserved in generated code.
2031 ///
2032 /// Also applies to generated oneof enums when `path` matches
2033 /// `".pkg.Msg.my_oneof"` (the oneof's fully-qualified path).
2034 ///
2035 /// # Pitfalls
2036 ///
2037 /// buffa already emits `#[derive(Clone, PartialEq)]` on messages and
2038 /// `#[derive(Clone, PartialEq, Debug)]` on oneofs (oneofs with a
2039 /// `[debug_redact = true]` variant get a generated `Debug` impl instead
2040 /// of the `Debug` derive); adding a duplicate derive via
2041 /// `type_attribute(".", "#[derive(Clone)]")` produces a compile error in
2042 /// the generated code.
2043 ///
2044 /// A custom `serde::Serialize` derive has two additional requirements:
2045 /// messages must disable unknown-field preservation because
2046 /// `UnknownFields` does not implement `serde::Serialize`, and the `json`
2047 /// feature must be enabled for buffa's `EnumValue` and `MessageField`
2048 /// serde implementations. Do not combine a custom derive with
2049 /// [`generate_json(true)`](Self::generate_json), which already generates
2050 /// the message's serde implementations.
2051 ///
2052 /// # Example
2053 ///
2054 /// ```rust,ignore
2055 /// buffa_build::Config::new()
2056 /// // `UnknownFields` does not implement `serde::Serialize`; with this
2057 /// // off, unknown fields are dropped on decode.
2058 /// .preserve_unknown_fields(false)
2059 /// .type_attribute(".", "#[derive(serde::Serialize)]")
2060 /// .type_attribute(".my.pkg.MyEnum", "#[derive(strum::EnumIter)]")
2061 /// .files(&["proto/my_service.proto"])
2062 /// .includes(&["proto/"])
2063 /// .compile()
2064 /// .unwrap();
2065 /// ```
2066 #[must_use]
2067 pub fn type_attribute(mut self, path: impl Into<String>, attribute: impl Into<String>) -> Self {
2068 self.codegen_config
2069 .type_attributes
2070 .push((normalize_attr_path(path.into()), attribute.into()));
2071 self
2072 }
2073
2074 /// Add a custom attribute to generated struct fields matching a proto
2075 /// path prefix.
2076 ///
2077 /// `path` is a fully-qualified proto field path (e.g.,
2078 /// `".my.pkg.MyMessage.my_field"`). `"."` applies to all fields. A
2079 /// leading `.` is auto-prepended if omitted; a trailing `.` is trimmed.
2080 /// Prefix matching respects proto-segment boundaries.
2081 ///
2082 /// Also applies to oneof variants when `path` matches
2083 /// `".pkg.Msg.my_oneof.variant_name"`, but not to the struct field holding
2084 /// the oneof; use
2085 /// [`oneof_struct_field_attribute`](Self::oneof_struct_field_attribute) for
2086 /// that.
2087 ///
2088 /// `attribute` follows the rule given for
2089 /// [`type_attribute`](Self::type_attribute): any string that is not one
2090 /// or more `#[...]` attributes, an empty one included, makes
2091 /// [`compile`](Self::compile) fail.
2092 ///
2093 /// A `#[deprecated]` supplied here wins over the one codegen derives from
2094 /// the field's `[deprecated = true]` option — rustc permits only one
2095 /// `deprecated` attribute per item — so this is also how to attach a note
2096 /// naming the replacement. Either source marks every generated way to
2097 /// reach a message field: the `with_*` setter, the same field on the
2098 /// views, its `OwnedView` accessor and, for a `required` field, the views'
2099 /// `has_*` method. Those carry a bare `#[deprecated]`; the attribute given
2100 /// here, with its note, stays on the owned struct's field. Either source
2101 /// also makes the generated items that visit the field carry
2102 /// `#[allow(deprecated)]`.
2103 ///
2104 /// A `deprecated` inside `cfg_attr` counts too: it replaces the
2105 /// option-derived marker on the owned field, and the setter and view
2106 /// markers stay unconditional.
2107 ///
2108 /// A oneof variant gets only the attribute given here. Its view variant is
2109 /// unmarked and the generated impls that match on it are not guarded, so
2110 /// put `#[allow(deprecated)]` on the `mod` that includes the generated
2111 /// file.
2112 ///
2113 /// # Example
2114 ///
2115 /// ```rust,ignore
2116 /// buffa_build::Config::new()
2117 /// .field_attribute(".my.pkg.MyMessage.secret_key", "#[serde(skip)]")
2118 /// .files(&["proto/my_service.proto"])
2119 /// .includes(&["proto/"])
2120 /// .compile()
2121 /// .unwrap();
2122 /// ```
2123 #[must_use]
2124 pub fn field_attribute(
2125 mut self,
2126 path: impl Into<String>,
2127 attribute: impl Into<String>,
2128 ) -> Self {
2129 self.codegen_config
2130 .field_attributes
2131 .push((normalize_attr_path(path.into()), attribute.into()));
2132 self
2133 }
2134
2135 /// Add a custom attribute to generated message structs only (not enums,
2136 /// not oneof enums — those are reached by
2137 /// [`enum_attribute`](Self::enum_attribute) and
2138 /// [`oneof_attribute`](Self::oneof_attribute) respectively) matching a
2139 /// proto path prefix.
2140 ///
2141 /// Same path-matching semantics as [`type_attribute`](Self::type_attribute) —
2142 /// leading `.` auto-prepended, trailing `.` trimmed, proto-segment-aware
2143 /// prefix matching, accumulation in insertion order. Useful for
2144 /// struct-only attributes like `#[serde(default)]`.
2145 ///
2146 /// `attribute` follows the rule given for
2147 /// [`type_attribute`](Self::type_attribute): any string that is not one
2148 /// or more `#[...]` attributes, an empty one included, makes
2149 /// [`compile`](Self::compile) fail.
2150 ///
2151 /// # Example
2152 ///
2153 /// ```rust,ignore
2154 /// buffa_build::Config::new()
2155 /// .message_attribute(".", "#[serde(default)]")
2156 /// .files(&["proto/my_service.proto"])
2157 /// .includes(&["proto/"])
2158 /// .compile()
2159 /// .unwrap();
2160 /// ```
2161 #[must_use]
2162 pub fn message_attribute(
2163 mut self,
2164 path: impl Into<String>,
2165 attribute: impl Into<String>,
2166 ) -> Self {
2167 self.codegen_config
2168 .message_attributes
2169 .push((normalize_attr_path(path.into()), attribute.into()));
2170 self
2171 }
2172
2173 /// Add a custom attribute to generated enum types only (not message
2174 /// structs, not oneof enums — those are reached by
2175 /// [`type_attribute`](Self::type_attribute) on the oneof's path or by
2176 /// [`oneof_attribute`](Self::oneof_attribute)) matching a proto path
2177 /// prefix.
2178 ///
2179 /// Same path-matching semantics as [`type_attribute`](Self::type_attribute) —
2180 /// leading `.` auto-prepended, trailing `.` trimmed, proto-segment-aware
2181 /// prefix matching, accumulation in insertion order. Useful when you want
2182 /// to inject an attribute on every enum in a package without also matching
2183 /// the (often more numerous) messages that share the path prefix — e.g.
2184 /// `#[derive(strum::EnumIter)]`, which only makes sense on enums.
2185 ///
2186 /// `attribute` follows the rule given for
2187 /// [`type_attribute`](Self::type_attribute): any string that is not one
2188 /// or more `#[...]` attributes, an empty one included, makes
2189 /// [`compile`](Self::compile) fail.
2190 ///
2191 /// # Example
2192 ///
2193 /// ```rust,ignore
2194 /// buffa_build::Config::new()
2195 /// .enum_attribute(".my.pkg", "#[derive(strum::EnumIter)]")
2196 /// .files(&["proto/my_service.proto"])
2197 /// .includes(&["proto/"])
2198 /// .compile()
2199 /// .unwrap();
2200 /// ```
2201 #[must_use]
2202 pub fn enum_attribute(mut self, path: impl Into<String>, attribute: impl Into<String>) -> Self {
2203 self.codegen_config
2204 .enum_attributes
2205 .push((normalize_attr_path(path.into()), attribute.into()));
2206 self
2207 }
2208
2209 /// Add a custom attribute to generated oneof enums only (not message
2210 /// structs, not regular enums) matching a proto path prefix.
2211 ///
2212 /// Same path-matching semantics as [`type_attribute`](Self::type_attribute):
2213 /// a leading `.` is auto-prepended, a trailing `.` is trimmed, prefixes
2214 /// match on proto-path segments, and attributes accumulate in insertion
2215 /// order. The match key is the oneof's fully-qualified path
2216 /// (`.my.pkg.MyMessage.my_oneof`) — the whole-enum path has no variant
2217 /// segment; to target a single variant's field, append `.variant_name`
2218 /// and use [`field_attribute`](Self::field_attribute) instead, and for the
2219 /// message struct's field holding the oneof, use
2220 /// [`oneof_struct_field_attribute`](Self::oneof_struct_field_attribute).
2221 /// `attribute` follows the rule given for
2222 /// [`type_attribute`](Self::type_attribute): any string that is not one
2223 /// or more `#[...]` attributes, an empty one included, makes
2224 /// [`compile`](Self::compile) fail.
2225 ///
2226 /// Useful when a oneof needs a different attribute set than the
2227 /// surrounding types — for example to keep `#[derive(serde::Serialize)]`
2228 /// on messages and oneofs while
2229 /// [`enum_attribute`](Self::enum_attribute) gives the regular enums a
2230 /// different serde derive.
2231 ///
2232 /// Applies to the owned oneof enum only; the zero-copy view-of-oneof
2233 /// enum receives no custom attributes (true of the whole attribute
2234 /// family). For JSON serialization of both owned types and views, use
2235 /// [`generate_json(true)`](Self::generate_json), which emits canonical
2236 /// protobuf-JSON impls rather than derived ones.
2237 ///
2238 /// # Pitfalls
2239 ///
2240 /// Generated oneof enums already derive `Clone`, `PartialEq`, and
2241 /// `Debug` (oneofs containing `[debug_redact = true]` fields replace the
2242 /// `Debug` derive with a manual impl). Re-deriving any of these via
2243 /// `oneof_attribute` produces a conflicting-implementation compile error
2244 /// inside the generated code.
2245 ///
2246 /// For the `serde::Serialize` requirements when the surrounding messages
2247 /// also use a custom derive, see the [`type_attribute`](Self::type_attribute)
2248 /// pitfalls: disable unknown-field preservation for messages and enable
2249 /// the `json` feature for buffa's serde implementations. Do not combine
2250 /// custom derives with [`generate_json(true)`](Self::generate_json).
2251 ///
2252 /// # Example
2253 ///
2254 /// ```rust,ignore
2255 /// buffa_build::Config::new()
2256 /// // one specific oneof; ".my.pkg" would match every oneof in the package
2257 /// .oneof_attribute(".my.pkg.MyMessage.my_oneof", "#[derive(serde::Serialize)]")
2258 /// .files(&["proto/my_service.proto"])
2259 /// .includes(&["proto/"])
2260 /// .compile()
2261 /// .unwrap();
2262 /// ```
2263 #[must_use]
2264 pub fn oneof_attribute(
2265 mut self,
2266 path: impl Into<String>,
2267 attribute: impl Into<String>,
2268 ) -> Self {
2269 self.codegen_config
2270 .oneof_attributes
2271 .push((normalize_attr_path(path.into()), attribute.into()));
2272 self
2273 }
2274
2275 /// Add a custom attribute to the message struct's field holding a oneof
2276 /// (the `Option<OneofEnum>` member), not to the oneof's variants.
2277 ///
2278 /// The match key is the oneof's fully-qualified path
2279 /// (`.my.pkg.MyMessage.my_oneof`), with the same path-matching semantics
2280 /// as [`type_attribute`](Self::type_attribute): `".my.pkg"` reaches the
2281 /// oneof field of every message in the package, nested ones included.
2282 /// Attributes accumulate in insertion order, after buffa's own attributes
2283 /// on the field.
2284 ///
2285 /// `attribute` follows the rule given for
2286 /// [`type_attribute`](Self::type_attribute): any string that is not one
2287 /// or more `#[...]` attributes, an empty one included, makes
2288 /// [`compile`](Self::compile) fail.
2289 ///
2290 /// A rule on a variant's path (`.my.pkg.MyMessage.my_oneof.variant_name`)
2291 /// does not match the oneof, so it has no effect, and the build does not
2292 /// warn about it. Variants take their attributes from
2293 /// [`field_attribute`](Self::field_attribute).
2294 ///
2295 /// Each of these lines of the generated code for a oneof takes its
2296 /// attributes from a different method:
2297 ///
2298 /// ```rust,ignore
2299 /// pub struct Event {
2300 /// // oneof_struct_field_attribute(".pkg.Event.payload", ..)
2301 /// pub payload: Option<event::Payload>,
2302 /// }
2303 ///
2304 /// // oneof_attribute(".pkg.Event.payload", ..), or type_attribute on the same path
2305 /// pub enum Payload {
2306 /// // field_attribute(".pkg.Event.payload.text", ..)
2307 /// Text(String),
2308 /// }
2309 /// ```
2310 ///
2311 /// `field_attribute` on the oneof's path (`.pkg.Event.payload`) matches
2312 /// the variants only, where an attribute
2313 /// such as `#[serde(skip_serializing_if = "...")]` is rejected. prost-build
2314 /// puts such a `field_attribute` on the struct field as well; use this
2315 /// method for the struct field.
2316 ///
2317 /// Applies to the owned message struct only; the view structs do not get
2318 /// the attribute.
2319 ///
2320 /// A `#[deprecated]` given here marks the owned struct's field only. The
2321 /// same field on the view structs stays unmarked, so reading the oneof
2322 /// through a view does not warn, unlike a field deprecated through
2323 /// `field_attribute`. The generated items that visit the owned field
2324 /// carry `#[allow(deprecated)]`.
2325 ///
2326 /// # Pitfalls
2327 ///
2328 /// With [`generate_json(true)`](Self::generate_json) the field already
2329 /// carries buffa's `#[serde(flatten)]` for the derived `Serialize`, and
2330 /// buffa generates the `Deserialize` impl of a message with a oneof
2331 /// instead of deriving it. So a serde attribute given here changes the
2332 /// owned message's `Serialize` output only: `Deserialize` and the views'
2333 /// `Serialize` ignore it. A second `flatten` is a compile error in the
2334 /// generated code. Serde attributes here are for a serde derive that you
2335 /// attach yourself, with `generate_json` off.
2336 ///
2337 /// With
2338 /// [`gate_impls_on_crate_features(true)`](Self::gate_impls_on_crate_features)
2339 /// buffa's serde derive is compiled only under the JSON feature. Write a
2340 /// serde attribute for it as `#[cfg_attr(feature = "json", serde(...))]`,
2341 /// with your JSON feature's name if you renamed it, so that it is compiled
2342 /// under the same feature.
2343 ///
2344 /// # Example
2345 ///
2346 /// ```rust,ignore
2347 /// buffa_build::Config::new()
2348 /// // `UnknownFields` does not implement `serde::Serialize`. With this
2349 /// // off, unknown fields are dropped on decode.
2350 /// .preserve_unknown_fields(false)
2351 /// .message_attribute(".my.pkg.MyMessage", "#[derive(serde::Serialize)]")
2352 /// .oneof_attribute(".my.pkg.MyMessage.my_oneof", "#[derive(serde::Serialize)]")
2353 /// .oneof_struct_field_attribute(
2354 /// ".my.pkg.MyMessage.my_oneof",
2355 /// "#[serde(skip_serializing_if = \"Option::is_none\")]",
2356 /// )
2357 /// .files(&["proto/my_service.proto"])
2358 /// .includes(&["proto/"])
2359 /// .compile()
2360 /// .unwrap();
2361 /// ```
2362 #[must_use]
2363 pub fn oneof_struct_field_attribute(
2364 mut self,
2365 path: impl Into<String>,
2366 attribute: impl Into<String>,
2367 ) -> Self {
2368 self.codegen_config
2369 .oneof_struct_field_attributes
2370 .push((normalize_attr_path(path.into()), attribute.into()));
2371 self
2372 }
2373
2374 /// Use `buf build` instead of `protoc` for descriptor generation.
2375 ///
2376 /// `buf` is often easier to install and keep current than `protoc`
2377 /// (which many distros pin to old versions). This mode is intended for
2378 /// the **single-crate case**: a `buf.yaml` at the crate root defining
2379 /// the module layout.
2380 ///
2381 /// Requires `buf` on PATH and a `buf.yaml` at the crate root. The
2382 /// [`includes()`](Self::includes) setting is ignored — buf resolves
2383 /// imports via its own module configuration.
2384 ///
2385 /// Each path given to [`files()`](Self::files) must be **relative to its
2386 /// owning module's directory** (the `path:` value inside `buf.yaml`), not
2387 /// the crate root where `buf.yaml` itself lives. buf strips the module
2388 /// path when producing `FileDescriptorProto.name`, so for
2389 /// `modules: [{path: proto}]` and a file on disk at
2390 /// `proto/api/v1/service.proto`, the descriptor name is
2391 /// `api/v1/service.proto` — that is what `.files()` must contain.
2392 /// Multiple modules in one `buf.yaml` work fine; buf enforces that
2393 /// module-relative names are unique across the workspace.
2394 ///
2395 /// # Monorepo / multi-module setups
2396 ///
2397 /// For a workspace-root `buf.yaml` with many modules, this mode is a
2398 /// poor fit. Prefer running `buf generate` with the `protoc-gen-reallyme-buffa`
2399 /// plugin and checking in the generated code, or use
2400 /// [`descriptor_set()`](Self::descriptor_set) with the output of
2401 /// `buf build --as-file-descriptor-set -o fds.binpb <module-path>`
2402 /// run as a pre-build step.
2403 ///
2404 /// # Example
2405 ///
2406 /// ```rust,ignore
2407 /// // buf.yaml (at crate root):
2408 /// // version: v2
2409 /// // modules:
2410 /// // - path: proto
2411 /// //
2412 /// // build.rs:
2413 /// buffa_build::Config::new()
2414 /// .use_buf()
2415 /// .files(&["api/v1/service.proto"]) // relative to module root
2416 /// .compile()
2417 /// .unwrap();
2418 /// ```
2419 #[must_use]
2420 pub fn use_buf(mut self) -> Self {
2421 self.descriptor_source = DescriptorSource::Buf;
2422 self
2423 }
2424
2425 /// Use a pre-compiled `FileDescriptorSet` binary file as input.
2426 ///
2427 /// Skips invoking `protoc` or `buf` entirely. The file must contain a
2428 /// serialized `google.protobuf.FileDescriptorSet` (as produced by
2429 /// `protoc --descriptor_set_out` or `buf build --as-file-descriptor-set`).
2430 ///
2431 /// When using this, `.files()` specifies which proto files in the
2432 /// descriptor set to generate code for (matching by proto file name).
2433 /// For in-memory input, use [`descriptor_set_bytes()`](Self::descriptor_set_bytes).
2434 #[must_use]
2435 pub fn descriptor_set(mut self, path: impl Into<PathBuf>) -> Self {
2436 self.descriptor_source = DescriptorSource::Precompiled(path.into());
2437 self
2438 }
2439
2440 /// Use a serialized `google.protobuf.FileDescriptorSet` held in memory.
2441 ///
2442 /// Use this when the build script produces the descriptor set itself, for
2443 /// example with an in-process compiler such as `protox`.
2444 /// [`compile()`](Self::compile) decodes the bytes and does not invoke
2445 /// `protoc` or `buf`. This replaces any previously configured descriptor
2446 /// source. Pass a slice as `bytes.to_vec()`.
2447 ///
2448 /// [`files()`](Self::files) selects which proto files in the descriptor set
2449 /// to generate, using their exact descriptor names (relative to the proto
2450 /// source root). The set must also contain their transitive imports.
2451 /// [`includes()`](Self::includes) is ignored.
2452 ///
2453 /// # Rebuilds
2454 ///
2455 /// Print a `cargo:rerun-if-changed` or `cargo:rerun-if-env-changed` line
2456 /// for every input the bytes were built from. `buffa-build` cannot see
2457 /// those inputs, and `compile()` always prints a `rerun-if-env-changed`
2458 /// line of its own, which turns off Cargo's default of rerunning the build
2459 /// script when any file in the package changes. Without your own lines, an
2460 /// edited `.proto` file does not rerun the script, and the generated code
2461 /// goes stale.
2462 ///
2463 /// # Example
2464 ///
2465 /// ```no_run
2466 /// # fn compile_protos_in_process() -> Vec<u8> { Vec::new() }
2467 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
2468 /// let bytes: Vec<u8> = compile_protos_in_process();
2469 /// println!("cargo:rerun-if-changed=proto");
2470 /// buffa_build::Config::new()
2471 /// .descriptor_set_bytes(bytes)
2472 /// .files(&["api/v1/service.proto"])
2473 /// .compile()?;
2474 /// # Ok(())
2475 /// # }
2476 /// ```
2477 #[must_use]
2478 pub fn descriptor_set_bytes(mut self, bytes: Vec<u8>) -> Self {
2479 self.descriptor_source = DescriptorSource::Bytes(bytes);
2480 self
2481 }
2482
2483 /// Generate a module-tree include file alongside the per-package `.rs`
2484 /// files.
2485 ///
2486 /// The include file contains nested `pub mod` declarations with
2487 /// `include!()` directives that assemble the generated code into a
2488 /// module hierarchy matching the protobuf package structure. Users can
2489 /// then include this single file instead of manually creating the
2490 /// module tree.
2491 ///
2492 /// The form of the emitted `include!` directives depends on whether
2493 /// [`out_dir`](Self::out_dir) was set:
2494 ///
2495 /// - **Default (`$OUT_DIR`)**: emits
2496 /// `include!(concat!(env!("OUT_DIR"), "/foo.rs"))`, for use from
2497 /// `build.rs` via `include!(concat!(env!("OUT_DIR"), "/<name>"))`.
2498 /// - **Explicit `out_dir`**: emits sibling-relative `include!("foo.rs")`,
2499 /// for checking the generated code into the source tree and referencing
2500 /// it as a module (e.g. `mod gen;`). The include file then has to sit in
2501 /// `out_dir` itself: `name` must be a bare file name, and
2502 /// [`compile`](Self::compile) rejects a name with a directory part.
2503 ///
2504 /// With [`shared_descriptor_pool`](Self::shared_descriptor_pool), `name`
2505 /// must be a bare file name in both modes. In `$OUT_DIR` mode without the
2506 /// shared pool, `name` may have a directory part (`"nested/_include.rs"`),
2507 /// and [`compile`](Self::compile) creates that directory.
2508 ///
2509 /// # Example — `build.rs` / `$OUT_DIR`
2510 ///
2511 /// ```rust,ignore
2512 /// // build.rs
2513 /// buffa_build::Config::new()
2514 /// .files(&["proto/my_service.proto"])
2515 /// .includes(&["proto/"])
2516 /// .include_file("_include.rs")
2517 /// .compile()
2518 /// .unwrap();
2519 ///
2520 /// // lib.rs
2521 /// include!(concat!(env!("OUT_DIR"), "/_include.rs"));
2522 /// ```
2523 ///
2524 /// # Example — checked-in source
2525 ///
2526 /// ```rust,ignore
2527 /// // codegen.rs (run manually, not from build.rs)
2528 /// buffa_build::Config::new()
2529 /// .files(&["proto/my_service.proto"])
2530 /// .includes(&["proto/"])
2531 /// .out_dir("src/gen")
2532 /// .include_file("mod.rs")
2533 /// .compile()
2534 /// .unwrap();
2535 ///
2536 /// // lib.rs
2537 /// mod gen;
2538 /// ```
2539 #[must_use]
2540 pub fn include_file(mut self, name: impl Into<String>) -> Self {
2541 self.include_file = Some(name.into());
2542 self
2543 }
2544
2545 /// Compile proto files and generate Rust source.
2546 ///
2547 /// # Errors
2548 ///
2549 /// Returns an error if:
2550 /// - `OUT_DIR` is not set and no `out_dir` was configured
2551 /// - [`shared_descriptor_pool`](Self::shared_descriptor_pool) is set
2552 /// without reflection enabled, without
2553 /// [`include_file`](Self::include_file), or with an `include_file`
2554 /// that is not a bare file name or lacks a file-name stem
2555 /// - an explicit [`out_dir`](Self::out_dir) is combined with an
2556 /// [`include_file`](Self::include_file) that is not a bare file name
2557 /// - `protoc` or `buf` cannot be found on `PATH` (when using those sources)
2558 /// - the proto compiler exits with a non-zero status (syntax errors,
2559 /// missing imports, etc.)
2560 /// - a precompiled descriptor set file cannot be read
2561 /// - the descriptor set bytes cannot be decoded as a `FileDescriptorSet`
2562 /// - an [`extern_path`](Self::extern_path) proto name has an empty
2563 /// segment or a segment that is not a protobuf identifier
2564 /// - a custom attribute string, given to
2565 /// [`type_attribute`](Self::type_attribute) or one of the five methods
2566 /// beside it, is not one or more `#[...]` attributes
2567 /// - code generation fails (e.g. unsupported proto feature), including a
2568 /// [`codec_strategy_in`](Self::codec_strategy_in) rule that names by its
2569 /// exact path a message that cannot use the table codec
2570 /// - [`CodecStrategy::Table`] is requested and the compiler is older than
2571 /// Rust 1.77
2572 /// - the output directory cannot be created or written to
2573 pub fn compile(mut self) -> Result<(), Box<dyn std::error::Error>> {
2574 // Table code needs `offset_of!`, stable in Rust 1.77. Say so once here,
2575 // and not once per field in the compiler's output.
2576 let table_codec_requested = self.codegen_config.codec_strategy == CodecStrategy::Table
2577 || self
2578 .codegen_config
2579 .codec_strategy_in
2580 .iter()
2581 .any(|(_, strategy)| *strategy == CodecStrategy::Table);
2582 // Outside a build script `RUSTC` is unset, and the toolchain that
2583 // compiles the generated code is unknown, so it is not checked.
2584 if table_codec_requested {
2585 if let Some(minor) = rustc_minor_version() {
2586 if minor < 77 {
2587 return Err(format!(
2588 "CodecStrategy::Table needs Rust 1.77 or later, and this build uses \
2589 1.{minor}; use a newer compiler or select CodecStrategy::Unrolled"
2590 )
2591 .into());
2592 }
2593 }
2594 }
2595
2596 // Reject malformed `exclude_package` entries before protoc runs; the
2597 // codegen normalizes them again, but a typo should not cost a protoc
2598 // invocation to surface.
2599 for entry in &self.codegen_config.exclude_packages {
2600 if let Err(e) = buffa_codegen::normalize_exclude_package(entry) {
2601 return Err(format!("exclude_package {entry:?}: {e}").into());
2602 }
2603 }
2604
2605 // Same for `extern_path`: a name that can match no type would leave
2606 // the mapping silently unused. The plugin applies the same function.
2607 for (proto, _) in &mut self.codegen_config.extern_paths {
2608 *proto = buffa_codegen::normalize_extern_path_proto_name(proto)?;
2609 }
2610
2611 // Validate the shared-pool prerequisites before doing any work, and
2612 // check reflection first so the error names the actually-missing
2613 // prerequisite rather than a downstream one. `generate_reflection` is
2614 // also enforced in `buffa-codegen`, but catching it here gives a
2615 // buffa-build-shaped message.
2616 let sidecar = if self.codegen_config.shared_descriptor_pool {
2617 if !self.codegen_config.generate_reflection {
2618 return Err("shared_descriptor_pool requires reflection to be enabled \
2619 (call generate_reflection(true) or reflect_mode(...))"
2620 .into());
2621 }
2622 // The shared `__buffa_fds` module is emitted into the include file
2623 // at the tree root; without it the per-package delegations have
2624 // nothing to resolve against.
2625 let Some(include_name) = self.include_file.as_deref() else {
2626 return Err("shared_descriptor_pool requires include_file to be set \
2627 (the shared descriptor module is emitted into it)"
2628 .into());
2629 };
2630 // The sidecar is named after the include file's stem; reject names
2631 // without one ("", ".", "..") here rather than writing a stray
2632 // misnamed sidecar before the include-file write fails. The stem
2633 // is computed once here and reused when the sidecar is written.
2634 let Some(stem) = Path::new(include_name).file_stem().and_then(|s| s.to_str()) else {
2635 return Err(format!(
2636 "shared_descriptor_pool requires include_file to have a file name \
2637 (the descriptor-set sidecar is named after its stem); \
2638 got {include_name:?}"
2639 )
2640 .into());
2641 };
2642 // The sidecar is named after the stem alone and written at the
2643 // output root, so `a/gen.rs` and `b/gen.rs` from two compile()
2644 // calls would share `gen.descriptor_set.binpb`, and the first tree
2645 // would build its pool from the second tree's descriptors.
2646 if !is_bare_file_name(include_name) {
2647 let reason = if include_name.contains('\0') {
2648 NUL_IN_FILE_NAME
2649 } else {
2650 "the descriptor-set sidecar is named after the stem alone and \
2651 written at the output root, so include files in two directories \
2652 would share it"
2653 };
2654 return Err(format!(
2655 "shared_descriptor_pool requires include_file to be a bare file name \
2656 ({reason}); got {include_name:?}"
2657 )
2658 .into());
2659 }
2660 Some(format!("{stem}.descriptor_set.binpb"))
2661 } else {
2662 None
2663 };
2664
2665 // When out_dir is explicitly set, the include file should use
2666 // relative `include!("foo.rs")` paths (the index is a sibling of the
2667 // generated files). When defaulted to $OUT_DIR, keep the
2668 // `concat!(env!("OUT_DIR"), ...)` form so that
2669 // `include!(concat!(env!("OUT_DIR"), "/_include.rs"))` from src/
2670 // still resolves to absolute paths.
2671 let relative_includes = self.out_dir.is_some();
2672 // Those relative paths name siblings of the include file, so the
2673 // include file has to sit in the output directory itself, with or
2674 // without the shared pool (which has already required a bare name
2675 // above). `$OUT_DIR` mode emits absolute paths, which resolve from any
2676 // directory.
2677 if let Some(include_name) = self.include_file.as_deref() {
2678 if relative_includes && !is_bare_file_name(include_name) {
2679 let reason = if include_name.contains('\0') {
2680 NUL_IN_FILE_NAME
2681 } else {
2682 "the generated include! paths are relative to the include file"
2683 };
2684 return Err(format!(
2685 "include_file must be a bare file name when out_dir is set \
2686 ({reason}); got {include_name:?}"
2687 )
2688 .into());
2689 }
2690 }
2691 let out_dir = self
2692 .out_dir
2693 .or_else(|| std::env::var("OUT_DIR").ok().map(PathBuf::from))
2694 .ok_or("OUT_DIR not set and no out_dir configured")?;
2695
2696 // Produce a FileDescriptorSet from the configured source.
2697 let descriptor_bytes: Cow<'_, [u8]> = match &self.descriptor_source {
2698 DescriptorSource::Protoc => invoke_protoc(&self.files, &self.includes)?.into(),
2699 DescriptorSource::Buf => invoke_buf()?.into(),
2700 DescriptorSource::Precompiled(path) => std::fs::read(path)
2701 .map_err(|e| format!("failed to read descriptor set '{}': {}", path.display(), e))?
2702 .into(),
2703 DescriptorSource::Bytes(bytes) => Cow::Borrowed(bytes),
2704 };
2705 // This descriptor set came from a protoc (or buf) invocation this build
2706 // controls, or a path or bytes the caller supplied, so the bound is far above
2707 // buffa's untrusted-input default — that default is sized for wire
2708 // input and a schema of a few hundred `.proto` files exceeds it,
2709 // descriptor types being wide structs. Still finite, so a truncated or
2710 // stale precompiled set fails with an error rather than an OOM.
2711 let decode_options = buffa_codegen::tooling_decode_options()?;
2712 let fds = decode_options
2713 .decode_from_slice::<FileDescriptorSet>(&descriptor_bytes)
2714 .map_err(|e| {
2715 buffa_codegen::decode_failure(
2716 "FileDescriptorSet",
2717 &e,
2718 decode_options.element_memory_limit(),
2719 )
2720 })?;
2721
2722 // Determine which files were explicitly requested.
2723 //
2724 // `FileDescriptorProto.name` contains the path relative to the proto
2725 // source root (protoc: `--proto_path`; buf: the module root). For
2726 // Precompiled, Bytes, and Buf mode, `.files()` are expected to already be
2727 // proto-relative names. For Protoc mode, strip the first matching
2728 // include prefix.
2729 let files_to_generate: Vec<String> = if matches!(
2730 self.descriptor_source,
2731 DescriptorSource::Precompiled(_) | DescriptorSource::Bytes(_) | DescriptorSource::Buf
2732 ) {
2733 self.files
2734 .iter()
2735 .filter_map(|f| f.to_str().map(str::to_string))
2736 .collect()
2737 } else {
2738 self.files
2739 .iter()
2740 .map(|f| proto_relative_name(f, &self.includes))
2741 .filter(|s| !s.is_empty())
2742 .collect()
2743 };
2744
2745 // Generate Rust source. Per-proto content files plus a per-package
2746 // `.mod.rs` stitcher; only the stitchers need wiring into the
2747 // module tree (content files are reached via `include!` from
2748 // there).
2749 let (generated, warnings) = buffa_codegen::generate_with_diagnostics(
2750 &fds.file,
2751 &files_to_generate,
2752 &self.codegen_config,
2753 )?;
2754
2755 // An include tree is written after content files. Compare destinations
2756 // before any writes: relative components, absolute paths, and existing
2757 // directory symlinks may name an adapter despite different spellings.
2758 // Runs without native adapters retain their existing include behavior.
2759 if let Some(include) = self.include_file.as_deref().filter(|_| {
2760 generated
2761 .iter()
2762 .any(|file| file.kind == buffa_codegen::GeneratedFileKind::Adapter)
2763 }) {
2764 let include_path = normalize_output_destination(&out_dir.join(include))?;
2765 for file in generated
2766 .iter()
2767 .filter(|file| file.kind == buffa_codegen::GeneratedFileKind::Adapter)
2768 {
2769 let adapter_path = normalize_output_destination(&out_dir.join(&file.name))?;
2770 if adapter_path
2771 .as_os_str()
2772 .as_encoded_bytes()
2773 .eq_ignore_ascii_case(include_path.as_os_str().as_encoded_bytes())
2774 {
2775 return Err(adapters::AdapterError::from(
2776 adapters::ErrorReason::DuplicateOutput,
2777 )
2778 .into());
2779 }
2780 }
2781 }
2782
2783 // Surface non-fatal codegen diagnostics as Cargo build warnings. This
2784 // runs inside the consumer's `build.rs`, so `cargo:warning=` is shown in
2785 // their normal `cargo build` output.
2786 for warning in warnings {
2787 println!("cargo:warning=buffa: {warning}");
2788 }
2789
2790 // Write output files; collect (name, package) for PackageMod entries.
2791 let mut output_entries: Vec<(String, String)> = Vec::new();
2792 for file in generated {
2793 let path = out_dir.join(&file.name);
2794 if let Some(parent) = path.parent() {
2795 std::fs::create_dir_all(parent)?;
2796 }
2797 write_if_changed(&path, file.content.as_bytes())?;
2798 if file.kind == buffa_codegen::GeneratedFileKind::PackageMod {
2799 output_entries.push((file.name, file.package));
2800 }
2801 }
2802
2803 // Shared-pool mode needs a tree root to host the one `__buffa_fds`
2804 // module; that root is the include file. The reflection and
2805 // include-file prerequisites were validated up front, and `sidecar`
2806 // is `Some` exactly when the mode is on.
2807
2808 // Generate the include file if requested.
2809 if let Some(ref include_name) = self.include_file {
2810 std::fs::create_dir_all(&out_dir)?;
2811 let tree = generate_include_file(&output_entries, relative_includes);
2812 let include_content = if let Some(sidecar) = sidecar {
2813 // Embed the descriptor set once, at the tree root, instead of a
2814 // per-package copy. Write it as a binary sidecar and
2815 // `include_bytes!` it from the shared `__buffa_fds` module, so
2816 // the bytes never expand into Rust byte-literal source. Every
2817 // package's `__buffa::reflect` delegates to that module.
2818 // The sidecar name was derived from the include file's stem up
2819 // front, so two compile() calls sharing an out_dir don't
2820 // clobber each other's descriptor set as long as their include
2821 // file stems differ (`a.rs` and `b.rs`; `gen.rs` and `gen.txt`
2822 // share `gen.descriptor_set.binpb`). The bare-name requirement
2823 // keeps two directories from hiding one stem.
2824 let fds_bytes = buffa_codegen::encode_descriptor_set(
2825 &fds.file,
2826 &self.codegen_config.feature_overrides,
2827 );
2828 write_if_changed(&out_dir.join(&sidecar), &fds_bytes)?;
2829 let mode = if relative_includes {
2830 buffa_codegen::IncludeMode::Relative("")
2831 } else {
2832 buffa_codegen::IncludeMode::OutDir
2833 };
2834 let root = buffa_codegen::shared_descriptor_root_module(
2835 &fds_bytes,
2836 buffa_codegen::FdsEmbedding::Sidecar {
2837 file_name: &sidecar,
2838 mode,
2839 },
2840 self.codegen_config.reflect_feature_gate(),
2841 );
2842 // Keep the tree's `// @generated` marker on line 1 —
2843 // first-line generated-file detection (rustfmt's five-line
2844 // window, diff-collapse heuristics) misses a mid-file marker —
2845 // and put the shared root module between the header and the
2846 // `include!` items. This relies on `generate_include_file`
2847 // passing `emit_inner_allow = false`: an inner `#![allow]` on
2848 // the tree's second line would be illegal after an outer item.
2849 let (header, items) = tree
2850 .split_once('\n')
2851 .expect("generate_module_tree output starts with a header line");
2852 debug_assert!(
2853 !items.trim_start().starts_with("#!["),
2854 "shared root module cannot precede an inner attribute"
2855 );
2856 format!("{header}\n{root}{items}")
2857 } else {
2858 tree
2859 };
2860 let include_path = out_dir.join(include_name);
2861 // In `$OUT_DIR` mode the name may have a directory part.
2862 if let Some(parent) = include_path.parent() {
2863 std::fs::create_dir_all(parent)?;
2864 }
2865 write_if_changed(&include_path, include_content.as_bytes())?;
2866 }
2867
2868 // Tell cargo to re-run if any proto file changes.
2869 //
2870 // For Buf mode, `self.files` are module-root-relative and cargo can't
2871 // stat them — use `buf ls-files` instead, which lists all workspace
2872 // protos with workspace-relative paths. Protoc mode uses the decoded
2873 // descriptor set below to watch resolved transitive imports.
2874 // The decode bound is read from the environment, and this script
2875 // disables cargo's default env tracking by emitting rerun-if-* keys.
2876 println!(
2877 "cargo:rerun-if-env-changed={}",
2878 buffa_codegen::ELEMENT_MEMORY_LIMIT_ENV
2879 );
2880 match self.descriptor_source {
2881 DescriptorSource::Buf => emit_buf_rerun_if_changed(),
2882 DescriptorSource::Protoc => {
2883 // Rerun if PROTOC changes (different binary may accept
2884 // protos the previous one rejected, e.g. newer editions).
2885 println!("cargo:rerun-if-env-changed=PROTOC");
2886 for proto_file in protoc_rerun_if_changed_paths(&fds, &self.files, &self.includes) {
2887 println!("cargo:rerun-if-changed={}", proto_file.display());
2888 }
2889 }
2890 DescriptorSource::Precompiled(ref path) => {
2891 println!("cargo:rerun-if-changed={}", path.display());
2892 }
2893 // The caller tracks the inputs used to produce these bytes.
2894 DescriptorSource::Bytes(_) => {}
2895 }
2896
2897 Ok(())
2898 }
2899}
2900
2901/// The reason given when an include file name contains a NUL byte.
2902const NUL_IN_FILE_NAME: &str = "a file name cannot contain a NUL byte";
2903
2904/// Resolve an output's existing components without creating its missing ones.
2905/// Resolve symlinks before processing `..`, matching filesystem traversal;
2906/// reducing all `..` components first would misidentify symlinked parents.
2907fn normalize_output_destination(path: &Path) -> Result<PathBuf, adapters::AdapterError> {
2908 let invalid = || adapters::AdapterError::from(adapters::ErrorReason::InvalidOutput);
2909 let absolute = if path.is_absolute() {
2910 path.to_owned()
2911 } else {
2912 std::env::current_dir().map_err(|_| invalid())?.join(path)
2913 };
2914 let mut normalized = PathBuf::new();
2915 for component in absolute.components() {
2916 match component {
2917 Component::Prefix(_) | Component::RootDir => normalized.push(component.as_os_str()),
2918 Component::CurDir => {}
2919 Component::ParentDir => {
2920 normalized.pop();
2921 }
2922 Component::Normal(name) => {
2923 normalized.push(name);
2924 match normalized.canonicalize() {
2925 Ok(existing) => normalized = existing,
2926 Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
2927 // A dangling link can become live when an earlier output
2928 // is written. Do not treat that link as a new file: its
2929 // eventual destination cannot be compared safely yet.
2930 match normalized.symlink_metadata() {
2931 Ok(metadata) if !metadata.file_type().is_symlink() => {}
2932 Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
2933 _ => return Err(invalid()),
2934 }
2935 }
2936 Err(_) => return Err(invalid()),
2937 }
2938 }
2939 }
2940 }
2941 Ok(normalized)
2942}
2943
2944/// Whether `name` places a file directly in the directory it is joined to. A
2945/// leading `./` is accepted; a backslash and a drive prefix are rejected on
2946/// every platform, so one build script behaves the same everywhere. A name
2947/// containing a NUL byte, which cannot name a file, is rejected too.
2948fn is_bare_file_name(name: &str) -> bool {
2949 let name = name.strip_prefix("./").unwrap_or(name);
2950 if name.contains('/') || name.contains('\\') || name.contains('\0') {
2951 return false;
2952 }
2953 if name.as_bytes().get(1) == Some(&b':')
2954 && name.as_bytes().first().is_some_and(u8::is_ascii_alphabetic)
2955 {
2956 return false;
2957 }
2958 // With the separators and the drive prefix ruled out, `name` is one
2959 // component: empty, `.`, `..`, or the file name itself.
2960 let mut components = Path::new(name).components();
2961 matches!(components.next(), Some(Component::Normal(_))) && components.next().is_none()
2962}
2963
2964impl Default for Config {
2965 fn default() -> Self {
2966 Self::new()
2967 }
2968}
2969
2970/// Normalize a user-supplied attribute-match path.
2971///
2972/// - Prepends `.` if absent so all stored paths are rooted.
2973/// - Trims trailing `.` so `".my.pkg."` and `".my.pkg"` behave identically
2974/// (trailing-dot patterns otherwise never match a real FQN).
2975/// - The bare catch-all `"."` is preserved as-is.
2976fn normalize_attr_path(mut path: String) -> String {
2977 if !path.starts_with('.') {
2978 path.insert(0, '.');
2979 }
2980 if path.len() > 1 {
2981 while path.ends_with('.') {
2982 path.pop();
2983 }
2984 }
2985 path
2986}
2987
2988/// The minor version of the compiler that builds the crate, if `RUSTC` names
2989/// one and it can be read.
2990fn rustc_minor_version() -> Option<u32> {
2991 let rustc = std::env::var_os("RUSTC")?;
2992 let output = std::process::Command::new(rustc)
2993 .arg("--version")
2994 .output()
2995 .ok()?;
2996 parse_rustc_minor_version(&String::from_utf8_lossy(&output.stdout))
2997}
2998
2999/// The minor version in the output of `rustc --version`, such as `75` in
3000/// `rustc 1.75.0 (82e1608df 2023-12-21)`.
3001fn parse_rustc_minor_version(version_output: &str) -> Option<u32> {
3002 version_output
3003 .split_whitespace()
3004 .nth(1)?
3005 .split('.')
3006 .nth(1)?
3007 .parse()
3008 .ok()
3009}
3010
3011/// Normalize a path-scoped rule's proto path: trim whitespace, prepend the
3012/// leading dot if absent, and strip trailing dots. Unlike
3013/// [`normalize_attr_path`], an entry that normalizes to empty (e.g. `"..."`)
3014/// is returned empty rather than collapsing to the `"."` catch-all — the
3015/// caller skips it, so `"."` stays the only global opt-in spelling.
3016fn normalize_override_path(path: &str) -> String {
3017 let mut path = path.trim().to_string();
3018 if path.is_empty() || path == "." {
3019 return path;
3020 }
3021 if !path.starts_with('.') {
3022 path.insert(0, '.');
3023 }
3024 while path.ends_with('.') {
3025 path.pop();
3026 }
3027 path
3028}
3029
3030/// Normalize the paths given to the field-rule builder method `method` with
3031/// [`normalize_override_path`]. An entry that normalizes to empty is skipped
3032/// with a `cargo:warning`.
3033fn field_rule_paths(method: &str, paths: &[impl AsRef<str>]) -> Vec<String> {
3034 paths
3035 .iter()
3036 .map(AsRef::as_ref)
3037 .filter_map(|raw| {
3038 let normalized = normalize_override_path(raw);
3039 if normalized.is_empty() {
3040 println!(
3041 "cargo:warning=buffa: {method} path '{raw}' normalizes to empty \
3042 and will be ignored"
3043 );
3044 return None;
3045 }
3046 Some(normalized)
3047 })
3048 .collect()
3049}
3050
3051/// Write `content` to `path` only if the file doesn't already exist with
3052/// identical content. Avoids bumping timestamps on unchanged files, which
3053/// prevents unnecessary downstream recompilation.
3054fn write_if_changed(path: &Path, content: &[u8]) -> std::io::Result<()> {
3055 if let Ok(existing) = std::fs::read(path) {
3056 if existing == content {
3057 return Ok(());
3058 }
3059 }
3060 std::fs::write(path, content)
3061}
3062
3063/// Invoke `protoc` to produce a `FileDescriptorSet` (serialized bytes).
3064fn invoke_protoc(
3065 files: &[PathBuf],
3066 includes: &[PathBuf],
3067) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
3068 let protoc = std::env::var("PROTOC").unwrap_or_else(|_| "protoc".to_string());
3069
3070 let descriptor_file =
3071 tempfile::NamedTempFile::new().map_err(|e| format!("failed to create temp file: {}", e))?;
3072 let descriptor_path = descriptor_file.path().to_path_buf();
3073
3074 let mut cmd = Command::new(&protoc);
3075 cmd.arg("--include_imports");
3076 cmd.arg("--include_source_info");
3077 cmd.arg(format!(
3078 "--descriptor_set_out={}",
3079 descriptor_path.display()
3080 ));
3081
3082 for include in includes {
3083 cmd.arg(format!("--proto_path={}", include.display()));
3084 }
3085
3086 for file in files {
3087 cmd.arg(file.as_os_str());
3088 }
3089
3090 let output = cmd
3091 .output()
3092 .map_err(|e| format!("failed to run protoc ({}): {}", protoc, e))?;
3093
3094 if !output.status.success() {
3095 let stderr = String::from_utf8_lossy(&output.stderr);
3096 return Err(format!("protoc failed: {}", stderr).into());
3097 }
3098
3099 let bytes = std::fs::read(&descriptor_path)
3100 .map_err(|e| format!("failed to read descriptor set: {}", e))?;
3101
3102 Ok(bytes)
3103}
3104
3105/// Invoke `buf build` to produce a `FileDescriptorSet` (serialized bytes).
3106///
3107/// Requires a `buf.yaml` discoverable from the build script's cwd. Builds
3108/// the entire workspace — no `--path` filtering, because buf's `--path` flag
3109/// expects workspace-relative paths while `FileDescriptorProto.name` is
3110/// module-root-relative; passing user paths to both would be a contradiction.
3111/// Codegen filtering happens on our side via `files_to_generate` matching.
3112fn invoke_buf() -> Result<Vec<u8>, Box<dyn std::error::Error>> {
3113 // buf build includes SourceCodeInfo by default (there's an
3114 // --exclude-source-info flag to disable it), so proto comments
3115 // propagate to generated code without an explicit opt-in here.
3116 let output = Command::new("buf")
3117 .arg("build")
3118 .arg("--as-file-descriptor-set")
3119 .arg("-o")
3120 .arg("-")
3121 .output()
3122 .map_err(|e| format!("failed to run buf (is it installed and on PATH?): {e}"))?;
3123
3124 if !output.status.success() {
3125 let stderr = String::from_utf8_lossy(&output.stderr);
3126 return Err(
3127 format!("buf build failed (is buf.yaml present at crate root?): {stderr}").into(),
3128 );
3129 }
3130
3131 Ok(output.stdout)
3132}
3133
3134/// Emit `cargo:rerun-if-changed` directives for a buf workspace.
3135///
3136/// Runs `buf ls-files` to discover all proto files with workspace-relative
3137/// paths (which cargo can stat). Also watches `buf.yaml` and `buf.lock`
3138/// (the latter only if it exists — cargo treats a missing rerun-if-changed
3139/// path as always-dirty). Failure is non-fatal: worst case cargo reruns
3140/// every build.
3141fn emit_buf_rerun_if_changed() {
3142 println!("cargo:rerun-if-changed=buf.yaml");
3143 if Path::new("buf.lock").exists() {
3144 println!("cargo:rerun-if-changed=buf.lock");
3145 }
3146 match Command::new("buf").arg("ls-files").output() {
3147 Ok(out) if out.status.success() => {
3148 for line in String::from_utf8_lossy(&out.stdout).lines() {
3149 let path = line.trim();
3150 if !path.is_empty() {
3151 println!("cargo:rerun-if-changed={path}");
3152 }
3153 }
3154 }
3155 _ => {
3156 // ls-files failed; cargo already knows about buf.yaml above.
3157 // If buf itself is missing, invoke_buf() will error clearly.
3158 }
3159 }
3160}
3161
3162/// Convert a filesystem proto path to the name protoc uses in the descriptor.
3163///
3164/// `FileDescriptorProto.name` is relative to the `--proto_path` include
3165/// directory. The name is what remains after the first include that is a
3166/// prefix of the file and leaves no `..` in the remainder: protoc refuses to
3167/// map a file through an include when the result would contain `..`, and
3168/// tries the next one. If no include qualifies, the name is the full path
3169/// (not just file_name — that would break nested proto directories).
3170/// Current-directory components and redundant separators are removed first,
3171/// as protoc does, without resolving symlinks or `..`.
3172fn proto_relative_name(file: &Path, includes: &[PathBuf]) -> String {
3173 let file = normalize_proto_path(file);
3174 let name = includes
3175 .iter()
3176 .find_map(|include| {
3177 let include = normalize_proto_path(include);
3178 // `.` contains every relative path and no rooted one. `has_root`
3179 // also covers a Windows path that starts at the root of the
3180 // current drive, which `is_absolute` reports as relative.
3181 if include.as_os_str().is_empty() && file.has_root() {
3182 return None;
3183 }
3184 file.strip_prefix(include).ok().filter(|name| {
3185 !name
3186 .components()
3187 .any(|component| component == Component::ParentDir)
3188 })
3189 })
3190 .unwrap_or(&file)
3191 .to_str()
3192 .unwrap_or("")
3193 .to_string();
3194 #[cfg(windows)]
3195 let name = name.replace('\\', "/");
3196 name
3197}
3198
3199fn normalize_proto_path(path: &Path) -> PathBuf {
3200 path.components()
3201 .filter(|component| *component != Component::CurDir)
3202 .collect()
3203}
3204
3205/// Files Cargo should watch for protoc-based builds.
3206///
3207/// `protoc --include_imports` records the full transitive import closure in
3208/// the descriptor set. Convert descriptor-relative names back to filesystem
3209/// paths under the configured include roots so edits to imported protos rerun
3210/// codegen even when `.files()` listed only the leaf proto. Imports resolved
3211/// from protoc's bundled includes (the well-known types) are not under any
3212/// configured root and are deliberately left unwatched — they ship with the
3213/// protoc binary and are not user-editable.
3214fn protoc_rerun_if_changed_paths(
3215 fds: &FileDescriptorSet,
3216 files: &[PathBuf],
3217 includes: &[PathBuf],
3218) -> Vec<PathBuf> {
3219 let mut paths: BTreeSet<PathBuf> = files.iter().cloned().collect();
3220 for file in &fds.file {
3221 if let Some(name) = file.name.as_deref() {
3222 if let Some(path) = resolve_descriptor_name_under_include(name, includes) {
3223 paths.insert(path);
3224 }
3225 }
3226 }
3227 paths.into_iter().collect()
3228}
3229
3230/// Map an include-relative descriptor name back to an on-disk path, trying
3231/// the include roots in `-I` order (matching protoc's own resolution).
3232/// Absolute or parent-traversing names are rejected outright; with no
3233/// include roots, the name is tried relative to the working directory.
3234fn resolve_descriptor_name_under_include(name: &str, includes: &[PathBuf]) -> Option<PathBuf> {
3235 let rel = Path::new(name);
3236 if rel.is_absolute()
3237 || rel
3238 .components()
3239 .any(|c| matches!(c, Component::ParentDir | Component::Prefix(_)))
3240 {
3241 return None;
3242 }
3243
3244 if includes.is_empty() {
3245 let path = PathBuf::from(rel);
3246 return path.exists().then_some(path);
3247 }
3248
3249 for include in includes {
3250 let path = include.join(rel);
3251 if path.exists() {
3252 return Some(path);
3253 }
3254 }
3255 None
3256}
3257
3258/// Generate the content of an include file that assembles generated `.rs`
3259/// files into a nested module tree matching the protobuf package hierarchy.
3260///
3261/// Each generated file is named like `my.package.file_name.rs`. The package
3262/// segments become `pub mod` wrappers, and the file is `include!`d inside
3263/// the innermost module.
3264///
3265/// For example, files `["foo.bar.rs", "foo.baz.rs"]` produce:
3266/// ```text
3267/// pub mod foo {
3268/// #[allow(unused_imports)]
3269/// use super::*;
3270/// include!(concat!(env!("OUT_DIR"), "/foo.bar.rs"));
3271/// include!(concat!(env!("OUT_DIR"), "/foo.baz.rs"));
3272/// }
3273/// ```
3274///
3275/// When `relative` is true (the caller set [`Config::out_dir`] explicitly),
3276/// `include!` directives use bare sibling paths (`include!("foo.bar.rs")`)
3277/// instead of the `env!("OUT_DIR")` prefix, so the include file works when
3278/// checked into the source tree and referenced via `mod`.
3279fn generate_include_file(entries: &[(String, String)], relative: bool) -> String {
3280 let mode = if relative {
3281 buffa_codegen::IncludeMode::Relative("")
3282 } else {
3283 buffa_codegen::IncludeMode::OutDir
3284 };
3285 // Inner-allow off: this output is consumed via `include!` from
3286 // user-authored `lib.rs`, where `#![allow(...)]` is not valid.
3287 buffa_codegen::generate_module_tree(entries, mode, false)
3288}
3289
3290#[cfg(test)]
3291mod tests {
3292 use super::*;
3293
3294 fn native_adapter_input() -> (Vec<u8>, adapters::AdapterConfig) {
3295 use buffa_codegen::generated::descriptor::{
3296 EnumDescriptorProto, EnumValueDescriptorProto, FileDescriptorProto,
3297 };
3298 let file = FileDescriptorProto {
3299 name: Some("mode.proto".into()),
3300 package: Some("p".into()),
3301 syntax: Some("proto3".into()),
3302 enum_type: vec![EnumDescriptorProto {
3303 name: Some("Mode".into()),
3304 value: vec![
3305 EnumValueDescriptorProto {
3306 name: Some("MODE_UNSPECIFIED".into()),
3307 number: Some(0),
3308 ..Default::default()
3309 },
3310 EnumValueDescriptorProto {
3311 name: Some("MODE_MESSAGE".into()),
3312 number: Some(1),
3313 ..Default::default()
3314 },
3315 ],
3316 ..Default::default()
3317 }],
3318 ..Default::default()
3319 };
3320 let config = adapters::AdapterConfig::from_json(br#"{"version":1,"selectors":[{
3321 "file":"native.rs","name":"NativeMode","wire":{"source":".p.Mode","rust_type":"crate::wire::Mode"},
3322 "error":{"rust_type":"crate::ContractError","value":"crate::ContractError::Invalid"},
3323 "variants":[{"source":"MODE_MESSAGE","name":"Message"}]
3324 }]}"#).unwrap();
3325 (buffa_codegen::encode_descriptor_set(&[file], &[]), config)
3326 }
3327
3328 #[test]
3329 fn native_adapters_are_written_outside_the_portable_include_tree() {
3330 let (bytes, adapters) = native_adapter_input();
3331 let directory = tempfile::tempdir().unwrap();
3332 Config::new()
3333 .descriptor_set_bytes(bytes)
3334 .files(&["mode.proto"])
3335 .adapters(adapters)
3336 .out_dir(directory.path())
3337 .include_file("tree.rs")
3338 .compile()
3339 .unwrap();
3340 assert!(directory.path().join("native.rs").is_file());
3341 let tree = std::fs::read_to_string(directory.path().join("tree.rs")).unwrap();
3342 assert!(!tree.contains("native.rs"));
3343 assert!(tree.contains("p.mod.rs"));
3344 }
3345
3346 #[test]
3347 fn native_include_collisions_fail_before_writing_any_output() {
3348 for include in ["native.rs", "NATIVE.rs", "./native.rs", "./NATIVE.rs"] {
3349 assert_native_include_collision(include, true);
3350 }
3351 }
3352
3353 fn assert_native_include_collision(include: &str, explicit_out_dir: bool) {
3354 let (bytes, adapters) = native_adapter_input();
3355 let directory = explicit_out_dir.then(|| tempfile::tempdir().unwrap());
3356 let path = directory.as_ref().map_or_else(
3357 || PathBuf::from(std::env::var_os("OUT_DIR").unwrap()),
3358 |dir| dir.path().to_owned(),
3359 );
3360 std::fs::create_dir_all(&path).unwrap();
3361 let preserved = path.join("native.rs");
3362 std::fs::write(&preserved, b"preserved adapter").unwrap();
3363 std::fs::write(path.join("p.rs"), b"preserved portable").unwrap();
3364 let mut config = Config::new()
3365 .descriptor_set_bytes(bytes)
3366 .files(&["mode.proto"])
3367 .adapters(adapters)
3368 .include_file(include);
3369 if explicit_out_dir {
3370 config = config.out_dir(&path);
3371 }
3372 let error = config.compile().unwrap_err();
3373 assert_eq!(
3374 error
3375 .downcast_ref::<adapters::AdapterError>()
3376 .unwrap()
3377 .reason,
3378 adapters::ErrorReason::DuplicateOutput
3379 );
3380 assert_eq!(std::fs::read(preserved).unwrap(), b"preserved adapter");
3381 assert_eq!(
3382 std::fs::read(path.join("p.rs")).unwrap(),
3383 b"preserved portable"
3384 );
3385 assert!(!path.join("p.mod.rs").exists());
3386 assert_eq!(std::fs::read_dir(&path).unwrap().count(), 2);
3387 }
3388
3389 #[test]
3390 fn native_include_out_dir_collision_child() {
3391 // OUT_DIR belongs to the child process so parallel tests never observe
3392 // a temporary change to their build environment.
3393 let Some(include) = std::env::var_os("NATIVE_COLLISION_INCLUDE") else {
3394 return;
3395 };
3396 assert_native_include_collision(include.to_str().unwrap(), false);
3397 }
3398
3399 #[test]
3400 fn native_include_out_dir_aliases_fail_before_writing() {
3401 let directory = tempfile::tempdir().unwrap();
3402 let output = directory.path().join("out");
3403 for include in [
3404 "././native.rs".to_owned(),
3405 "unused/../native.rs".to_owned(),
3406 "../out/NATIVE.rs".to_owned(),
3407 output.join("native.rs").to_str().unwrap().to_owned(),
3408 ] {
3409 let result = std::process::Command::new(std::env::current_exe().unwrap())
3410 .args(["--exact", "tests::native_include_out_dir_collision_child"])
3411 .env("OUT_DIR", &output)
3412 .env("NATIVE_COLLISION_INCLUDE", &include)
3413 .output()
3414 .unwrap();
3415 assert!(
3416 result.status.success(),
3417 "{include}: {}",
3418 String::from_utf8_lossy(&result.stdout)
3419 );
3420 }
3421 }
3422
3423 #[test]
3424 fn native_noncolliding_out_dir_include_child() {
3425 let Some(include) = std::env::var_os("NATIVE_VALID_INCLUDE") else {
3426 return;
3427 };
3428 let (bytes, adapters) = native_adapter_input();
3429 Config::new()
3430 .descriptor_set_bytes(bytes)
3431 .files(&["mode.proto"])
3432 .adapters(adapters)
3433 .include_file(include.to_str().unwrap())
3434 .compile()
3435 .unwrap();
3436 let output = PathBuf::from(std::env::var_os("OUT_DIR").unwrap());
3437 assert!(std::fs::read_to_string(output.join("native.rs"))
3438 .unwrap()
3439 .contains("pub enum NativeMode"));
3440 assert!(std::fs::read_to_string(output.join(include))
3441 .unwrap()
3442 .contains("p.mod.rs"));
3443 }
3444
3445 #[test]
3446 fn native_out_dir_includes_keep_distinct_destinations() {
3447 let directory = tempfile::tempdir().unwrap();
3448 let output = directory.path().join("out");
3449 let includes = vec![
3450 PathBuf::from("nested/tree.rs"),
3451 directory.path().join("separate/native.rs"),
3452 ];
3453 #[cfg(unix)]
3454 let includes = {
3455 let mut includes = includes;
3456 // `link/..` is the symlink target's parent, not the output
3457 // directory. A lexical reduction alone would reject this valid case.
3458 std::fs::create_dir_all(directory.path().join("target/child")).unwrap();
3459 std::fs::create_dir(&output).unwrap();
3460 std::os::unix::fs::symlink(directory.path().join("target/child"), output.join("link"))
3461 .unwrap();
3462 includes.push(PathBuf::from("link/../native.rs"));
3463 includes
3464 };
3465 for include in includes {
3466 let result = std::process::Command::new(std::env::current_exe().unwrap())
3467 .args([
3468 "--exact",
3469 "tests::native_noncolliding_out_dir_include_child",
3470 ])
3471 .env("OUT_DIR", &output)
3472 .env("NATIVE_VALID_INCLUDE", &include)
3473 .output()
3474 .unwrap();
3475 assert!(
3476 result.status.success(),
3477 "{include:?}: {}",
3478 String::from_utf8_lossy(&result.stdout)
3479 );
3480 }
3481 }
3482
3483 #[cfg(unix)]
3484 #[test]
3485 fn native_include_directory_symlink_alias_is_a_collision() {
3486 let directory = tempfile::tempdir().unwrap();
3487 let output = directory.path().join("out");
3488 std::fs::create_dir(&output).unwrap();
3489 let alias = directory.path().join("alias");
3490 std::os::unix::fs::symlink(&output, &alias).unwrap();
3491 let result = std::process::Command::new(std::env::current_exe().unwrap())
3492 .args(["--exact", "tests::native_include_out_dir_collision_child"])
3493 .env("OUT_DIR", &output)
3494 .env("NATIVE_COLLISION_INCLUDE", alias.join("native.rs"))
3495 .output()
3496 .unwrap();
3497 assert!(
3498 result.status.success(),
3499 "{}",
3500 String::from_utf8_lossy(&result.stdout)
3501 );
3502 }
3503
3504 #[cfg(unix)]
3505 #[test]
3506 fn native_include_dangling_symlink_is_rejected_before_any_writes() {
3507 let (bytes, adapters) = native_adapter_input();
3508 let directory = tempfile::tempdir().unwrap();
3509 let include = directory.path().join("tree.rs");
3510 std::os::unix::fs::symlink("native.rs", &include).unwrap();
3511 let portable = directory.path().join("p.rs");
3512 std::fs::write(&portable, b"preserved portable").unwrap();
3513 let error = Config::new()
3514 .descriptor_set_bytes(bytes)
3515 .files(&["mode.proto"])
3516 .adapters(adapters)
3517 .out_dir(directory.path())
3518 .include_file("tree.rs")
3519 .compile()
3520 .unwrap_err();
3521 assert_eq!(
3522 error
3523 .downcast_ref::<adapters::AdapterError>()
3524 .unwrap()
3525 .reason,
3526 adapters::ErrorReason::InvalidOutput
3527 );
3528 assert_eq!(std::fs::read(portable).unwrap(), b"preserved portable");
3529 assert_eq!(std::fs::read_link(include).unwrap(), Path::new("native.rs"));
3530 assert!(!directory.path().join("native.rs").exists());
3531 assert_eq!(std::fs::read_dir(directory.path()).unwrap().count(), 2);
3532 }
3533
3534 #[test]
3535 fn feature_name_setters_reach_codegen_config() {
3536 let config = Config::new()
3537 .json_feature_name("serde")
3538 .views_feature_name("zero-copy")
3539 .text_feature_name(String::from("textproto"))
3540 .reflect_feature_name("reflection")
3541 .codegen_config;
3542 let names = &config.feature_gate_names;
3543 assert_eq!(names.json, "serde");
3544 assert_eq!(names.views, "zero-copy");
3545 assert_eq!(names.text, "textproto");
3546 assert_eq!(names.reflect, "reflection");
3547 }
3548
3549 #[test]
3550 fn shared_descriptor_pool_requires_include_file() {
3551 // The shared root module has no home without an include file, so
3552 // compile() must reject the combination before doing any work.
3553 let err = Config::new()
3554 .generate_reflection(true)
3555 .shared_descriptor_pool(true)
3556 .out_dir("unused")
3557 .compile()
3558 .expect_err("shared_descriptor_pool without include_file must error");
3559 assert!(
3560 err.to_string().contains("include_file"),
3561 "error should name the missing include_file: {err}"
3562 );
3563 }
3564
3565 #[test]
3566 fn shared_descriptor_pool_setter_reaches_codegen_config() {
3567 let config = Config::new().shared_descriptor_pool(true).codegen_config;
3568 assert!(config.shared_descriptor_pool);
3569 }
3570
3571 #[test]
3572 fn shared_descriptor_pool_rejects_stemless_include_file() {
3573 // The sidecar is named after the include file's stem; a name without
3574 // one ("", ".", "..") must fail up front rather than writing a
3575 // misnamed stray sidecar before the include-file write errors.
3576 let err = Config::new()
3577 .generate_reflection(true)
3578 .shared_descriptor_pool(true)
3579 .include_file("..")
3580 .out_dir("unused")
3581 .compile()
3582 .expect_err("shared_descriptor_pool with a stemless include_file must error");
3583 assert!(
3584 err.to_string().contains("file name"),
3585 "error should name the degenerate include_file: {err}"
3586 );
3587 }
3588
3589 #[test]
3590 fn is_bare_file_name_accepts_names_in_the_joined_directory() {
3591 for name in ["gen_mod.rs", ".gen_mod.rs", "gen_mod", "./gen_mod.rs"] {
3592 assert!(is_bare_file_name(name), "{name:?} should be bare");
3593 }
3594 }
3595
3596 #[test]
3597 fn is_bare_file_name_rejects_paths_and_nul() {
3598 for name in [
3599 "",
3600 ".",
3601 "./",
3602 "..",
3603 "../gen_mod.rs",
3604 "nested/gen_mod.rs",
3605 "nested\\gen_mod.rs",
3606 "/gen_mod.rs",
3607 "C:gen_mod.rs",
3608 "gen_mod.rs/",
3609 "gen_mod.rs\0",
3610 ] {
3611 assert!(!is_bare_file_name(name), "{name:?} should not be bare");
3612 }
3613 }
3614
3615 #[test]
3616 fn shared_descriptor_pool_rejects_path_include_file() {
3617 let dir = tempfile::tempdir().unwrap();
3618 std::fs::create_dir(dir.path().join("nested")).unwrap();
3619
3620 let err = Config::new()
3621 .generate_reflection(true)
3622 .shared_descriptor_pool(true)
3623 .include_file("nested/gen_mod.rs")
3624 .descriptor_set_bytes(Vec::new())
3625 .out_dir(dir.path())
3626 .compile()
3627 .expect_err("shared descriptor include_file paths must be rejected");
3628 let message = err.to_string();
3629 assert!(
3630 message.contains("bare file name") && message.contains("sidecar"),
3631 "error should name the bare-file requirement and its reason: {message}"
3632 );
3633 }
3634
3635 #[test]
3636 fn shared_descriptor_pool_rejects_nul_include_file() {
3637 let dir = tempfile::tempdir().unwrap();
3638
3639 let err = Config::new()
3640 .generate_reflection(true)
3641 .shared_descriptor_pool(true)
3642 .include_file("gen_mod.rs\0")
3643 .descriptor_set_bytes(Vec::new())
3644 .out_dir(dir.path())
3645 .compile()
3646 .expect_err("shared descriptor include_file names must not contain NUL");
3647 let message = err.to_string();
3648 assert!(
3649 message.contains("bare file name") && message.contains("NUL"),
3650 "error should name the bare-file requirement and the NUL byte: {message}"
3651 );
3652 assert!(
3653 !message.contains("sidecar"),
3654 "a NUL name is not a path problem: {message}"
3655 );
3656 }
3657
3658 #[test]
3659 fn explicit_out_dir_rejects_nul_include_file() {
3660 let dir = tempfile::tempdir().unwrap();
3661
3662 let err = Config::new()
3663 .include_file("gen_mod.rs\0")
3664 .descriptor_set_bytes(Vec::new())
3665 .out_dir(dir.path())
3666 .compile()
3667 .expect_err("include_file names must not contain NUL");
3668 let message = err.to_string();
3669 assert!(
3670 message.contains("bare file name") && message.contains("NUL"),
3671 "error should name the bare-file requirement and the NUL byte: {message}"
3672 );
3673 assert!(
3674 !message.contains("relative to the include file"),
3675 "a NUL name is not a path problem: {message}"
3676 );
3677 }
3678
3679 #[test]
3680 fn shared_descriptor_pool_requires_reflection() {
3681 // Checked before include_file so the error names the first missing
3682 // prerequisite.
3683 let err = Config::new()
3684 .shared_descriptor_pool(true)
3685 .include_file("gen_mod.rs")
3686 .out_dir("unused")
3687 .compile()
3688 .expect_err("shared_descriptor_pool without reflection must error");
3689 assert!(
3690 err.to_string().contains("reflection"),
3691 "error should name the missing reflection prerequisite: {err}"
3692 );
3693 }
3694
3695 #[test]
3696 fn shared_descriptor_pool_writes_sidecar_and_shared_root() {
3697 use buffa_codegen::generated::descriptor::field_descriptor_proto::{Label, Type};
3698 use buffa_codegen::generated::descriptor::{
3699 DescriptorProto, FieldDescriptorProto, FileDescriptorProto,
3700 };
3701
3702 // A minimal one-package descriptor set, fed through descriptor_set()
3703 // so the test needs no protoc.
3704 let file = FileDescriptorProto {
3705 name: Some("foo/v1/thing.proto".into()),
3706 package: Some("foo.v1".into()),
3707 syntax: Some("proto3".into()),
3708 message_type: vec![DescriptorProto {
3709 name: Some("Thing".into()),
3710 field: vec![FieldDescriptorProto {
3711 name: Some("id".into()),
3712 number: Some(1),
3713 label: Some(Label::LABEL_OPTIONAL),
3714 r#type: Some(Type::TYPE_INT32),
3715 ..Default::default()
3716 }],
3717 ..Default::default()
3718 }],
3719 ..Default::default()
3720 };
3721 let fds_bytes = buffa_codegen::encode_descriptor_set(std::slice::from_ref(&file), &[]);
3722
3723 let dir = tempfile::tempdir().unwrap();
3724 let fds_path = dir.path().join("set.binpb");
3725 std::fs::write(&fds_path, &fds_bytes).unwrap();
3726 let out = dir.path().join("gen");
3727
3728 Config::new()
3729 .descriptor_set(&fds_path)
3730 .files(&["foo/v1/thing.proto"])
3731 .out_dir(&out)
3732 .include_file("gen_mod.rs")
3733 .generate_reflection(true)
3734 .shared_descriptor_pool(true)
3735 .compile()
3736 .expect("shared-pool compile should succeed");
3737
3738 // The sidecar is named after the include file's stem and carries the
3739 // same bytes the generated code was built against.
3740 let sidecar = std::fs::read(out.join("gen_mod.descriptor_set.binpb"))
3741 .expect("sidecar must be written next to the include file");
3742 assert_eq!(sidecar, fds_bytes);
3743
3744 // The include file hosts the shared root and `include_bytes!`s the
3745 // sidecar (out_dir is explicit, so paths are include-file-relative)
3746 // instead of inlining the descriptor bytes as a source literal.
3747 let include = std::fs::read_to_string(out.join("gen_mod.rs")).unwrap();
3748 // The generated-file marker must stay on line 1 (first-line `@generated`
3749 // detection: rustfmt, diff-collapsing heuristics), with the shared root
3750 // module below it.
3751 assert!(
3752 include.starts_with("// @generated"),
3753 "include file must lead with the @generated marker: {include}"
3754 );
3755 assert!(include.contains("pub mod __buffa_fds"), "{include}");
3756 // (Two containment checks rather than one exact call text —
3757 // prettyplease may wrap the macro call across lines.)
3758 assert!(include.contains("include_bytes!"), "{include}");
3759 assert!(
3760 include.contains("\"gen_mod.descriptor_set.binpb\""),
3761 "{include}"
3762 );
3763 assert!(
3764 !include.contains("FILE_DESCRIPTOR_SET_BYTES: &[u8] = b\""),
3765 "sidecar mode must not inline the bytes: {include}"
3766 );
3767
3768 // The package's `__buffa::reflect` surface (authored by the package
3769 // stitcher) delegates to the shared root instead of embedding its own
3770 // copy of the descriptor set.
3771 let pkg = std::fs::read_to_string(out.join("foo.v1.mod.rs")).unwrap();
3772 assert!(
3773 pkg.contains("__buffa_fds"),
3774 "package reflect surface must delegate to the shared root: {pkg}"
3775 );
3776 assert!(
3777 !pkg.contains("FILE_DESCRIPTOR_SET_BYTES: &[u8] = b\""),
3778 "package must not embed its own descriptor copy: {pkg}"
3779 );
3780 }
3781
3782 #[test]
3783 fn box_type_in_normalizes_leading_dot() {
3784 // Without normalization a dotless path would silently match nothing,
3785 // and the exact-path Inline recursion error would never fire for it.
3786 let config = Config::new()
3787 .box_type_in(PointerRepr::Box, &["my.pkg.Msg.inner", ".my.pkg.Other"])
3788 .codegen_config;
3789 assert_eq!(
3790 config.pointer_fields,
3791 vec![
3792 (".my.pkg.Msg.inner".to_string(), PointerRepr::Box),
3793 (".my.pkg.Other".to_string(), PointerRepr::Box),
3794 ]
3795 );
3796 }
3797
3798 fn rule_paths<R>(rules: &[(String, R)]) -> Vec<&str> {
3799 rules.iter().map(|(path, _)| path.as_str()).collect()
3800 }
3801
3802 #[test]
3803 fn type_in_builders_normalize_paths() {
3804 // A missing leading dot, surrounding whitespace and a trailing dot
3805 // are normalized; a blank entry is skipped, so `"."` is the only
3806 // spelling of "every field".
3807 let paths = &["my.pkg.Msg.field", " .my.pkg.Other. ", ".", "", " ", "..."];
3808 let expected = [".my.pkg.Msg.field", ".my.pkg.Other", "."];
3809 let config = Config::new()
3810 .bytes_type_in(BytesRepr::Bytes, paths)
3811 .string_type_in(StringRepr::String, paths)
3812 .map_type_in(MapRepr::BTreeMap, paths)
3813 .repeated_type_in(RepeatedRepr::Vec, paths)
3814 .box_type_in(PointerRepr::Box, paths)
3815 .unbox_oneof_in(paths)
3816 .codegen_config;
3817
3818 assert_eq!(rule_paths(&config.bytes_fields), expected);
3819 assert_eq!(rule_paths(&config.string_fields), expected);
3820 assert_eq!(rule_paths(&config.map_fields), expected);
3821 assert_eq!(rule_paths(&config.repeated_fields), expected);
3822 assert_eq!(rule_paths(&config.pointer_fields), expected);
3823 assert_eq!(config.unboxed_oneof_fields, expected);
3824 }
3825
3826 #[test]
3827 fn bytes_alias_and_custom_in_builders_normalize_paths() {
3828 let config = Config::new()
3829 .use_bytes_type_in(&["my.pkg.A.data"])
3830 .bytes_type_custom_in("::my::Bytes", &["my.pkg.B.data"])
3831 .string_type_custom_in("::my::Str", &["my.pkg.C.name"])
3832 .map_type_custom_in("::my::Map", &["my.pkg.D.entries"])
3833 .repeated_type_custom_in("::my::List<*>", &["my.pkg.E.items"])
3834 .codegen_config;
3835 assert_eq!(config.bytes_fields[0].0, ".my.pkg.A.data");
3836 assert_eq!(config.bytes_fields[1].0, ".my.pkg.B.data");
3837 assert_eq!(config.string_fields[0].0, ".my.pkg.C.name");
3838 assert_eq!(config.map_fields[0].0, ".my.pkg.D.entries");
3839 assert_eq!(config.repeated_fields[0].0, ".my.pkg.E.items");
3840 }
3841
3842 #[test]
3843 fn unbox_oneof_in_normalizes_leading_dot() {
3844 // Without normalization a dotless path would silently match nothing,
3845 // and the exact-path recursion error would never fire for it.
3846 let config = Config::new()
3847 .unbox_oneof_in(&["my.pkg.Msg.body.small", ".my.pkg.Other"])
3848 .codegen_config;
3849 assert_eq!(
3850 config.unboxed_oneof_fields,
3851 vec![
3852 ".my.pkg.Msg.body.small".to_string(),
3853 ".my.pkg.Other".to_string()
3854 ]
3855 );
3856 }
3857
3858 #[test]
3859 fn skip_debug_normalizes_and_accumulates_paths() {
3860 let config = Config::new()
3861 .skip_debug(&["demo.Uuid4", ".demo.Level.", "..."])
3862 .skip_debug(&[" .demo.Other ", "."])
3863 .codegen_config;
3864 // `"..."` normalizes to empty and is dropped.
3865 assert_eq!(
3866 config.skip_debug,
3867 [".demo.Uuid4", ".demo.Level", ".demo.Other", "."]
3868 );
3869 }
3870
3871 #[test]
3872 fn deny_view_json_normalizes_and_accumulates_paths() {
3873 let config = Config::new()
3874 .deny_view_json(&["demo.Private.", " .demo.Other "])
3875 .deny_view_json(&["."])
3876 .codegen_config;
3877 assert_eq!(config.deny_view_json, [".demo.Private", ".demo.Other", "."]);
3878 }
3879
3880 #[test]
3881 fn codec_strategy_in_normalizes_paths_and_keeps_rule_order() {
3882 let config = Config::new()
3883 .codec_strategy(CodecStrategy::Table)
3884 .codec_strategy_in(CodecStrategy::Unrolled, &["my.pkg.Msg", ".my.pkg.Other."])
3885 .codec_strategy_in(CodecStrategy::Table, &[" .my.pkg.Msg.Inner ", "."])
3886 .codegen_config;
3887 assert_eq!(config.codec_strategy, CodecStrategy::Table);
3888 assert_eq!(
3889 config.codec_strategy_in,
3890 vec![
3891 (".my.pkg.Msg".to_string(), CodecStrategy::Unrolled),
3892 (".my.pkg.Other".to_string(), CodecStrategy::Unrolled),
3893 (".my.pkg.Msg.Inner".to_string(), CodecStrategy::Table),
3894 (".".to_string(), CodecStrategy::Table),
3895 ]
3896 );
3897 }
3898
3899 #[test]
3900 fn rustc_minor_version_is_read_from_the_version_line() {
3901 assert_eq!(
3902 parse_rustc_minor_version("rustc 1.75.0 (82e1608df 2023-12-21)"),
3903 Some(75)
3904 );
3905 assert_eq!(
3906 parse_rustc_minor_version("rustc 1.98.0-nightly (abc 2027-01-01)\n"),
3907 Some(98)
3908 );
3909 assert_eq!(parse_rustc_minor_version(""), None);
3910 assert_eq!(parse_rustc_minor_version("not rustc"), None);
3911 }
3912
3913 #[test]
3914 fn codec_strategy_defaults_to_unrolled() {
3915 let config = Config::new().codegen_config;
3916 assert_eq!(config.codec_strategy, CodecStrategy::Unrolled);
3917 assert!(config.codec_strategy_in.is_empty());
3918 }
3919
3920 #[test]
3921 fn deny_unknown_json_fields_in_normalizes_paths() {
3922 let config = Config::new()
3923 .deny_unknown_json_fields_in(&["demo.Config", ".demo.Other.", " .demo.Third ", "."])
3924 .codegen_config;
3925 // The global default is untouched by the path-scoped builder.
3926 assert!(!config.deny_unknown_json_fields);
3927 assert_eq!(
3928 config.deny_unknown_json_fields_in,
3929 vec![
3930 (".demo.Config".to_string(), true),
3931 (".demo.Other".to_string(), true),
3932 (".demo.Third".to_string(), true),
3933 (".".to_string(), true),
3934 ]
3935 );
3936 }
3937
3938 #[test]
3939 fn deny_unknown_json_fields_sets_the_global_flag() {
3940 assert!(
3941 Config::new()
3942 .deny_unknown_json_fields(true)
3943 .codegen_config
3944 .deny_unknown_json_fields
3945 );
3946 }
3947
3948 #[test]
3949 fn preserve_unknown_fields_in_normalizes_paths() {
3950 let config = Config::new()
3951 .preserve_unknown_fields(false)
3952 .preserve_unknown_fields_in(&[
3953 "wa.CallLogRecord",
3954 ".wa.SyncdMutation.",
3955 " .wa.Other ",
3956 ".",
3957 ])
3958 .codegen_config;
3959 assert!(!config.preserve_unknown_fields);
3960 assert_eq!(
3961 config.preserve_unknown_fields_in,
3962 vec![
3963 (".wa.CallLogRecord".to_string(), true),
3964 (".wa.SyncdMutation".to_string(), true),
3965 (".wa.Other".to_string(), true),
3966 (".".to_string(), true),
3967 ]
3968 );
3969 }
3970
3971 #[test]
3972 fn preserve_unknown_fields_in_empty_path_is_not_catchall() {
3973 // `""` and `"..."` must not collapse to the `"."` catch-all, which
3974 // would re-enable preservation for every message.
3975 let config = Config::new()
3976 .preserve_unknown_fields(false)
3977 .preserve_unknown_fields_in(&["", " ", "...", ".wa.Keep"])
3978 .codegen_config;
3979 assert_eq!(
3980 config.preserve_unknown_fields_in,
3981 vec![(".wa.Keep".to_string(), true)]
3982 );
3983 }
3984
3985 #[test]
3986 fn open_enums_in_normalizes_paths() {
3987 // Without normalization, dotless or trailing-dot paths would silently
3988 // match nothing.
3989 let config = Config::new()
3990 .open_enums_in(&[
3991 "my.pkg.Status.",
3992 ".my.pkg.Msg.status",
3993 ".",
3994 " my.pkg.Trimmed ",
3995 ])
3996 .codegen_config;
3997 let paths: Vec<&str> = config
3998 .feature_overrides
3999 .iter()
4000 .map(|(p, _)| p.as_str())
4001 .collect();
4002 assert_eq!(
4003 paths,
4004 vec![
4005 ".my.pkg.Status",
4006 ".my.pkg.Msg.status",
4007 ".",
4008 ".my.pkg.Trimmed"
4009 ]
4010 );
4011 assert!(config
4012 .feature_overrides
4013 .iter()
4014 .all(|(_, o)| *o == FeatureOverride::EnumType(EnumTypeOverride::Open)));
4015 }
4016
4017 #[test]
4018 fn override_feature_in_accumulates_and_normalizes() {
4019 let config = Config::new()
4020 .override_feature_in(
4021 "my.pkg.Status.",
4022 FeatureOverride::EnumType(EnumTypeOverride::Open),
4023 )
4024 .override_feature_in(
4025 ".my.pkg.Msg.e",
4026 FeatureOverride::EnumType(EnumTypeOverride::Open),
4027 )
4028 .override_feature_in("...", FeatureOverride::EnumType(EnumTypeOverride::Open))
4029 .codegen_config;
4030 assert_eq!(
4031 config.feature_overrides,
4032 vec![
4033 (
4034 ".my.pkg.Status".to_string(),
4035 FeatureOverride::EnumType(EnumTypeOverride::Open)
4036 ),
4037 (
4038 ".my.pkg.Msg.e".to_string(),
4039 FeatureOverride::EnumType(EnumTypeOverride::Open)
4040 ),
4041 ]
4042 );
4043 }
4044
4045 #[test]
4046 fn open_enums_in_empty_path_is_not_catchall() {
4047 let config = Config::new()
4048 .open_enums_in(&["", " ", "..."])
4049 .codegen_config;
4050 assert!(config.feature_overrides.is_empty());
4051 }
4052
4053 #[test]
4054 fn proto_relative_name_strips_include() {
4055 let got = proto_relative_name(
4056 Path::new("proto/my/service.proto"),
4057 &[PathBuf::from("proto/")],
4058 );
4059 assert_eq!(got, "my/service.proto");
4060 }
4061
4062 #[test]
4063 fn proto_relative_name_normalizes_current_directory_components() {
4064 for (file, includes, expected) in [
4065 (
4066 "./proto/my/service.proto",
4067 vec!["proto"],
4068 "my/service.proto",
4069 ),
4070 (
4071 "proto/my/service.proto",
4072 vec!["./proto"],
4073 "my/service.proto",
4074 ),
4075 (
4076 "./proto/my/service.proto",
4077 vec!["./proto"],
4078 "my/service.proto",
4079 ),
4080 (
4081 "proto/my/./service.proto",
4082 vec!["proto"],
4083 "my/service.proto",
4084 ),
4085 ("./my//pkg/./service.proto", vec![], "my/pkg/service.proto"),
4086 ("./my/pkg/service.proto", vec!["."], "my/pkg/service.proto"),
4087 ("my/pkg/service.proto", vec!["./."], "my/pkg/service.proto"),
4088 (
4089 "./my/pkg/service.proto",
4090 vec!["other"],
4091 "my/pkg/service.proto",
4092 ),
4093 ] {
4094 let includes = includes.into_iter().map(PathBuf::from).collect::<Vec<_>>();
4095 assert_eq!(proto_relative_name(Path::new(file), &includes), expected);
4096 }
4097 }
4098
4099 #[test]
4100 fn proto_relative_name_normalization_preserves_include_order() {
4101 let file = Path::new("./proto/vendor/./ext.proto");
4102 assert_eq!(
4103 proto_relative_name(
4104 file,
4105 &[PathBuf::from("./proto"), PathBuf::from("proto/vendor")]
4106 ),
4107 "vendor/ext.proto"
4108 );
4109 assert_eq!(
4110 proto_relative_name(
4111 file,
4112 &[PathBuf::from("./proto/vendor"), PathBuf::from("proto")]
4113 ),
4114 "ext.proto"
4115 );
4116 }
4117
4118 #[test]
4119 fn proto_relative_name_current_directory_include_contains_relative_files() {
4120 // `.` listed first names the file by its full relative path, even
4121 // when a later include is a closer match.
4122 assert_eq!(
4123 proto_relative_name(
4124 Path::new("proto/my/service.proto"),
4125 &[PathBuf::from("."), PathBuf::from("proto")]
4126 ),
4127 "proto/my/service.proto"
4128 );
4129 }
4130
4131 #[test]
4132 fn proto_relative_name_current_directory_does_not_match_absolute_path() {
4133 let root = std::env::current_dir().unwrap().join("proto");
4134 let file = root.join("my/service.proto");
4135 assert_eq!(
4136 proto_relative_name(&file, &[PathBuf::from("."), root]),
4137 "my/service.proto"
4138 );
4139 }
4140
4141 #[test]
4142 fn proto_relative_name_preserves_parent_directory_components() {
4143 assert_eq!(
4144 proto_relative_name(Path::new("./proto/../vendor/service.proto"), &[]),
4145 "proto/../vendor/service.proto"
4146 );
4147 assert_eq!(
4148 proto_relative_name(
4149 Path::new("./proto/../vendor/service.proto"),
4150 &[PathBuf::from("proto/../vendor")],
4151 ),
4152 "service.proto"
4153 );
4154 }
4155
4156 #[test]
4157 fn proto_relative_name_skips_prefixes_leaving_parent_components() {
4158 assert_eq!(
4159 proto_relative_name(
4160 Path::new("./proto/../vendor/service.proto"),
4161 &[
4162 PathBuf::from("."),
4163 PathBuf::from("proto"),
4164 PathBuf::from("proto/../vendor"),
4165 ],
4166 ),
4167 "service.proto"
4168 );
4169 }
4170
4171 #[test]
4172 fn proto_relative_name_first_matching_prefix_wins() {
4173 let got = proto_relative_name(
4174 Path::new("proto/vendor/ext.proto"),
4175 &[PathBuf::from("proto/"), PathBuf::from("proto/vendor/")],
4176 );
4177 assert_eq!(got, "vendor/ext.proto");
4178 let got = proto_relative_name(
4179 Path::new("proto/vendor/ext.proto"),
4180 &[PathBuf::from("proto/vendor/"), PathBuf::from("proto/")],
4181 );
4182 assert_eq!(got, "ext.proto");
4183 }
4184
4185 #[test]
4186 fn proto_relative_name_skips_unmatched_prefixes() {
4187 let got = proto_relative_name(
4188 Path::new("proto/vendor/ext.proto"),
4189 &[
4190 PathBuf::from("unrelated"),
4191 PathBuf::from("proto/"),
4192 PathBuf::from("proto/vendor/"),
4193 ],
4194 );
4195 assert_eq!(got, "vendor/ext.proto");
4196 }
4197
4198 #[test]
4199 fn proto_relative_name_requires_a_complete_path_component() {
4200 let got = proto_relative_name(
4201 Path::new("proto/vendor2/ext.proto"),
4202 &[PathBuf::from("proto/vendor"), PathBuf::from("proto/")],
4203 );
4204 assert_eq!(got, "vendor2/ext.proto");
4205 }
4206
4207 #[cfg(windows)]
4208 #[test]
4209 fn proto_relative_name_normalizes_windows_separators() {
4210 let got = proto_relative_name(
4211 Path::new(r"C:\proto\vendor\ext.proto"),
4212 &[
4213 PathBuf::from(r"C:\proto"),
4214 PathBuf::from(r"C:\proto\vendor"),
4215 ],
4216 );
4217 assert_eq!(got, "vendor/ext.proto");
4218 let got = proto_relative_name(Path::new(r"vendor\ext.proto"), &[]);
4219 assert_eq!(got, "vendor/ext.proto");
4220 }
4221
4222 #[cfg(unix)]
4223 #[test]
4224 fn proto_relative_name_preserves_literal_backslashes() {
4225 let got = proto_relative_name(
4226 Path::new(r"proto/vendor\ext.proto"),
4227 &[PathBuf::from("proto")],
4228 );
4229 assert_eq!(got, r"vendor\ext.proto");
4230 }
4231
4232 #[test]
4233 fn proto_relative_name_no_match_returns_full_path() {
4234 // The fallback is the whole path: file_name() alone would drop the
4235 // directories that descriptor_set() mode needs for nested packages.
4236 let got = proto_relative_name(Path::new("my/pkg/service.proto"), &[]);
4237 assert_eq!(got, "my/pkg/service.proto");
4238 }
4239
4240 #[test]
4241 fn proto_relative_name_no_match_with_unrelated_includes() {
4242 let got = proto_relative_name(
4243 Path::new("src/my.proto"),
4244 &[PathBuf::from("other/"), PathBuf::from("third/")],
4245 );
4246 assert_eq!(got, "src/my.proto");
4247 }
4248
4249 #[test]
4250 fn protoc_rerun_paths_include_transitive_imports() {
4251 use buffa_codegen::generated::descriptor::FileDescriptorProto;
4252
4253 let dir = tempfile::tempdir().unwrap();
4254 let include = dir.path().join("proto");
4255 std::fs::create_dir_all(include.join("svc")).unwrap();
4256 std::fs::write(include.join("svc/service.proto"), b"syntax = \"proto3\";").unwrap();
4257 std::fs::write(include.join("common.proto"), b"syntax = \"proto3\";").unwrap();
4258
4259 let fds = FileDescriptorSet {
4260 file: vec![
4261 FileDescriptorProto {
4262 name: Some("svc/service.proto".into()),
4263 ..Default::default()
4264 },
4265 FileDescriptorProto {
4266 name: Some("common.proto".into()),
4267 ..Default::default()
4268 },
4269 ],
4270 ..Default::default()
4271 };
4272 let explicit = vec![include.join("svc/service.proto")];
4273
4274 let got: BTreeSet<_> =
4275 protoc_rerun_if_changed_paths(&fds, &explicit, std::slice::from_ref(&include))
4276 .into_iter()
4277 .collect();
4278 let expected: BTreeSet<_> = [
4279 include.join("svc/service.proto"),
4280 include.join("common.proto"),
4281 ]
4282 .into_iter()
4283 .collect();
4284 assert_eq!(got, expected);
4285 }
4286
4287 #[test]
4288 fn protoc_rerun_paths_skip_descriptor_names_not_under_include_roots() {
4289 use buffa_codegen::generated::descriptor::FileDescriptorProto;
4290
4291 let dir = tempfile::tempdir().unwrap();
4292 let include = dir.path().join("proto");
4293 std::fs::create_dir_all(&include).unwrap();
4294
4295 let fds = FileDescriptorSet {
4296 file: vec![
4297 FileDescriptorProto {
4298 name: Some("missing.proto".into()),
4299 ..Default::default()
4300 },
4301 FileDescriptorProto {
4302 name: Some("../outside.proto".into()),
4303 ..Default::default()
4304 },
4305 ],
4306 ..Default::default()
4307 };
4308 let explicit = vec![PathBuf::from("service.proto")];
4309
4310 assert_eq!(
4311 protoc_rerun_if_changed_paths(&fds, &explicit, &[include]),
4312 explicit
4313 );
4314 }
4315
4316 #[test]
4317 fn include_file_out_dir_mode_uses_env_var() {
4318 let entries = vec![
4319 ("foo.bar.rs".to_string(), "foo".to_string()),
4320 ("root.rs".to_string(), String::new()),
4321 ];
4322 let out = generate_include_file(&entries, false);
4323 assert!(
4324 out.contains(r#"include!(concat!(env!("OUT_DIR"), "/foo.bar.rs"));"#),
4325 "nested-package file should use env!(OUT_DIR): {out}"
4326 );
4327 assert!(
4328 out.contains(r#"include!(concat!(env!("OUT_DIR"), "/root.rs"));"#),
4329 "empty-package file should use env!(OUT_DIR): {out}"
4330 );
4331 assert!(!out.contains(r#"include!("foo.bar.rs")"#));
4332 }
4333
4334 #[test]
4335 fn include_file_relative_mode_uses_sibling_paths() {
4336 let entries = vec![
4337 ("foo.bar.rs".to_string(), "foo".to_string()),
4338 ("root.rs".to_string(), String::new()),
4339 ];
4340 let out = generate_include_file(&entries, true);
4341 assert!(
4342 out.contains(r#"include!("foo.bar.rs");"#),
4343 "nested-package file should use relative path: {out}"
4344 );
4345 assert!(
4346 out.contains(r#"include!("root.rs");"#),
4347 "empty-package file should use relative path: {out}"
4348 );
4349 assert!(
4350 !out.contains("OUT_DIR"),
4351 "relative mode must not reference OUT_DIR: {out}"
4352 );
4353 }
4354
4355 fn config_with_excluded_package() -> Config {
4356 use buffa_codegen::generated::descriptor::{DescriptorProto, FileDescriptorProto};
4357
4358 let file = FileDescriptorProto {
4359 name: Some("example.proto".into()),
4360 package: Some("example".into()),
4361 syntax: Some("proto3".into()),
4362 message_type: vec![DescriptorProto {
4363 name: Some("Message".into()),
4364 ..Default::default()
4365 }],
4366 ..Default::default()
4367 };
4368 Config::new()
4369 .descriptor_set_bytes(buffa_codegen::encode_descriptor_set(&[file], &[]))
4370 .files(&["example.proto"])
4371 .exclude_package("example")
4372 }
4373
4374 #[test]
4375 fn include_file_creates_output_directory_without_generated_files() {
4376 for config in [
4377 Config::new().descriptor_set_bytes(Vec::new()),
4378 config_with_excluded_package(),
4379 ] {
4380 let dir = tempfile::tempdir().unwrap();
4381 let out = dir.path().join("nested/gen");
4382 assert!(!out.exists());
4383
4384 config
4385 .out_dir(&out)
4386 .include_file("gen_mod.rs")
4387 .compile()
4388 .unwrap();
4389
4390 assert_eq!(
4391 std::fs::read_to_string(out.join("gen_mod.rs")).unwrap(),
4392 generate_include_file(&[], true)
4393 );
4394 assert_eq!(std::fs::read_dir(&out).unwrap().count(), 1);
4395 }
4396 }
4397
4398 #[test]
4399 fn shared_descriptor_pool_writes_output_without_generated_files() {
4400 let config = config_with_excluded_package();
4401 let DescriptorSource::Bytes(ref bytes) = config.descriptor_source else {
4402 unreachable!();
4403 };
4404 let expected_bytes = bytes.clone();
4405 let dir = tempfile::tempdir().unwrap();
4406 let out = dir.path().join("nested/gen");
4407
4408 config
4409 .out_dir(&out)
4410 .include_file("gen_mod.rs")
4411 .generate_reflection(true)
4412 .shared_descriptor_pool(true)
4413 .compile()
4414 .unwrap();
4415
4416 assert_eq!(
4417 std::fs::read(out.join("gen_mod.descriptor_set.binpb")).unwrap(),
4418 expected_bytes
4419 );
4420 let include = std::fs::read_to_string(out.join("gen_mod.rs")).unwrap();
4421 assert!(include.contains("pub mod __buffa_fds"), "{include}");
4422 assert!(
4423 include.contains("\"gen_mod.descriptor_set.binpb\""),
4424 "{include}"
4425 );
4426 assert_eq!(std::fs::read_dir(&out).unwrap().count(), 2);
4427 }
4428
4429 #[test]
4430 fn include_file_preserves_existing_directory_without_generated_files() {
4431 let dir = tempfile::tempdir().unwrap();
4432 let preserved = dir.path().join("existing.rs");
4433 std::fs::write(&preserved, b"existing content").unwrap();
4434
4435 config_with_excluded_package()
4436 .out_dir(dir.path())
4437 .include_file("gen_mod.rs")
4438 .compile()
4439 .unwrap();
4440
4441 assert_eq!(std::fs::read(&preserved).unwrap(), b"existing content");
4442 assert_eq!(
4443 std::fs::read_to_string(dir.path().join("gen_mod.rs")).unwrap(),
4444 generate_include_file(&[], true)
4445 );
4446 }
4447
4448 #[test]
4449 fn include_file_reports_output_directory_that_is_a_file() {
4450 let dir = tempfile::tempdir().unwrap();
4451 let out = dir.path().join("gen");
4452 std::fs::write(&out, b"existing content").unwrap();
4453
4454 let err = config_with_excluded_package()
4455 .out_dir(&out)
4456 .include_file("gen_mod.rs")
4457 .compile()
4458 .unwrap_err();
4459
4460 assert!(err.downcast_ref::<std::io::Error>().is_some(), "{err}");
4461 assert_eq!(std::fs::read(&out).unwrap(), b"existing content");
4462 }
4463
4464 #[test]
4465 fn compile_without_include_file_does_not_create_empty_output_directory() {
4466 let dir = tempfile::tempdir().unwrap();
4467 let out = dir.path().join("nested/gen");
4468
4469 config_with_excluded_package()
4470 .out_dir(&out)
4471 .compile()
4472 .unwrap();
4473
4474 assert!(!out.exists());
4475 }
4476
4477 #[test]
4478 fn include_file_relative_mode_nested_packages() {
4479 // Two files in the same depth-2 package: verifies the relative flag
4480 // propagates through recursive emit() calls and both files land in
4481 // the same innermost mod.
4482 let entries = vec![
4483 ("a.b.one.rs".to_string(), "a.b".to_string()),
4484 ("a.b.two.rs".to_string(), "a.b".to_string()),
4485 ];
4486 let out = generate_include_file(&entries, true);
4487 // Both includes should appear once, at the same depth-2 indent,
4488 // inside a single `pub mod b { ... }`.
4489 let indent = " "; // depth 2 = 8 spaces
4490 assert!(
4491 out.contains(&format!(r#"{indent}include!("a.b.one.rs");"#)),
4492 "first file at depth 2: {out}"
4493 );
4494 assert!(
4495 out.contains(&format!(r#"{indent}include!("a.b.two.rs");"#)),
4496 "second file at depth 2: {out}"
4497 );
4498 assert_eq!(
4499 out.matches("pub mod b {").count(),
4500 1,
4501 "both files share one `mod b`: {out}"
4502 );
4503 assert!(!out.contains("OUT_DIR"));
4504 }
4505
4506 #[test]
4507 fn write_if_changed_creates_new_file() {
4508 let dir = tempfile::tempdir().unwrap();
4509 let path = dir.path().join("new.rs");
4510 write_if_changed(&path, b"hello").unwrap();
4511 assert_eq!(std::fs::read(&path).unwrap(), b"hello");
4512 }
4513
4514 #[test]
4515 fn write_if_changed_skips_identical_content() {
4516 let dir = tempfile::tempdir().unwrap();
4517 let path = dir.path().join("same.rs");
4518 std::fs::write(&path, b"content").unwrap();
4519 let mtime_before = std::fs::metadata(&path).unwrap().modified().unwrap();
4520
4521 // Sleep briefly so any write would produce a different mtime.
4522 std::thread::sleep(std::time::Duration::from_millis(50));
4523
4524 write_if_changed(&path, b"content").unwrap();
4525 let mtime_after = std::fs::metadata(&path).unwrap().modified().unwrap();
4526 assert_eq!(mtime_before, mtime_after);
4527 }
4528
4529 #[test]
4530 fn write_if_changed_overwrites_different_content() {
4531 let dir = tempfile::tempdir().unwrap();
4532 let path = dir.path().join("changed.rs");
4533 std::fs::write(&path, b"old").unwrap();
4534
4535 write_if_changed(&path, b"new").unwrap();
4536 assert_eq!(std::fs::read(&path).unwrap(), b"new");
4537 }
4538
4539 #[test]
4540 fn security_rule_normalization_never_turns_an_empty_path_into_a_catch_all() {
4541 let config = Config::new()
4542 .zeroize_in(&["", " . ", " demo.Record. "])
4543 .deny_view_json(&["", " . ", " demo.Record. "]);
4544 assert_eq!(
4545 config.codegen_config.zeroize_messages,
4546 ["", ".", ".demo.Record"]
4547 );
4548 assert_eq!(
4549 config.codegen_config.deny_view_json,
4550 ["", ".", ".demo.Record"]
4551 );
4552 }
4553
4554 #[test]
4555 fn normalize_attr_path_prepends_leading_dot() {
4556 assert_eq!(normalize_attr_path("my.pkg".into()), ".my.pkg");
4557 }
4558
4559 #[test]
4560 fn normalize_attr_path_preserves_leading_dot() {
4561 assert_eq!(normalize_attr_path(".my.pkg".into()), ".my.pkg");
4562 }
4563
4564 #[test]
4565 fn normalize_attr_path_trims_trailing_dot() {
4566 assert_eq!(normalize_attr_path("my.pkg.".into()), ".my.pkg");
4567 assert_eq!(normalize_attr_path(".my.pkg.".into()), ".my.pkg");
4568 assert_eq!(normalize_attr_path(".my.pkg...".into()), ".my.pkg");
4569 }
4570
4571 #[test]
4572 fn normalize_attr_path_preserves_catchall() {
4573 assert_eq!(normalize_attr_path(".".into()), ".");
4574 assert_eq!(normalize_attr_path("".into()), ".");
4575 }
4576
4577 #[test]
4578 fn type_attribute_forwards_normalized_path() {
4579 let cfg = Config::new().type_attribute("my.pkg.", "#[derive(Foo)]");
4580 assert_eq!(
4581 cfg.codegen_config.type_attributes,
4582 vec![(".my.pkg".to_string(), "#[derive(Foo)]".to_string())]
4583 );
4584 }
4585
4586 #[test]
4587 fn field_attribute_forwards_normalized_path() {
4588 let cfg = Config::new().field_attribute("pkg.Msg.f", "#[serde(skip)]");
4589 assert_eq!(
4590 cfg.codegen_config.field_attributes,
4591 vec![(".pkg.Msg.f".to_string(), "#[serde(skip)]".to_string())]
4592 );
4593 }
4594
4595 #[test]
4596 fn message_attribute_forwards_normalized_path() {
4597 let cfg = Config::new().message_attribute(".", "#[serde(default)]");
4598 assert_eq!(
4599 cfg.codegen_config.message_attributes,
4600 vec![(".".to_string(), "#[serde(default)]".to_string())]
4601 );
4602 }
4603
4604 #[test]
4605 fn enum_attribute_forwards_normalized_path() {
4606 let cfg = Config::new().enum_attribute("my.pkg.", "#[derive(strum::EnumIter)]");
4607 assert_eq!(
4608 cfg.codegen_config.enum_attributes,
4609 vec![(
4610 ".my.pkg".to_string(),
4611 "#[derive(strum::EnumIter)]".to_string(),
4612 )]
4613 );
4614 // Other attribute lists must remain untouched.
4615 assert!(cfg.codegen_config.type_attributes.is_empty());
4616 assert!(cfg.codegen_config.message_attributes.is_empty());
4617 assert!(cfg.codegen_config.field_attributes.is_empty());
4618 }
4619
4620 #[test]
4621 fn oneof_struct_field_attribute_forwards_normalized_path() {
4622 let cfg =
4623 Config::new().oneof_struct_field_attribute("my.pkg.Msg.payload.", "#[serde(skip)]");
4624 assert_eq!(
4625 cfg.codegen_config.oneof_struct_field_attributes,
4626 vec![(
4627 ".my.pkg.Msg.payload".to_string(),
4628 "#[serde(skip)]".to_string()
4629 )]
4630 );
4631 assert!(cfg.codegen_config.oneof_attributes.is_empty());
4632 assert!(cfg.codegen_config.field_attributes.is_empty());
4633 assert!(cfg.codegen_config.type_attributes.is_empty());
4634 assert!(cfg.codegen_config.message_attributes.is_empty());
4635 assert!(cfg.codegen_config.enum_attributes.is_empty());
4636 }
4637
4638 #[test]
4639 fn oneof_attribute_forwards_normalized_path() {
4640 let cfg = Config::new().oneof_attribute("my.pkg.Msg.payload.", "#[derive(Hash)]");
4641 assert_eq!(
4642 cfg.codegen_config.oneof_attributes,
4643 vec![(
4644 ".my.pkg.Msg.payload".to_string(),
4645 "#[derive(Hash)]".to_string()
4646 )]
4647 );
4648 // Other attribute lists must remain untouched.
4649 assert!(cfg.codegen_config.type_attributes.is_empty());
4650 assert!(cfg.codegen_config.enum_attributes.is_empty());
4651 assert!(cfg.codegen_config.message_attributes.is_empty());
4652 assert!(cfg.codegen_config.field_attributes.is_empty());
4653 assert!(cfg.codegen_config.oneof_struct_field_attributes.is_empty());
4654 }
4655
4656 #[test]
4657 fn attribute_calls_accumulate_in_insertion_order() {
4658 let cfg = Config::new()
4659 .type_attribute(".", "#[derive(A)]")
4660 .type_attribute(".pkg.M", "#[derive(B)]")
4661 .type_attribute(".", "#[derive(C)]");
4662 let paths: Vec<_> = cfg
4663 .codegen_config
4664 .type_attributes
4665 .iter()
4666 .map(|(_, a)| a.as_str())
4667 .collect();
4668 assert_eq!(paths, vec!["#[derive(A)]", "#[derive(B)]", "#[derive(C)]"]);
4669 }
4670
4671 #[test]
4672 fn descriptor_set_bytes_matches_file_input() {
4673 use buffa_codegen::generated::descriptor::field_descriptor_proto::{Label, Type};
4674 use buffa_codegen::generated::descriptor::{
4675 DescriptorProto, FieldDescriptorProto, FileDescriptorProto,
4676 };
4677
4678 let files = [
4679 FileDescriptorProto {
4680 name: Some("common/types.proto".into()),
4681 package: Some("common".into()),
4682 syntax: Some("proto3".into()),
4683 message_type: vec![DescriptorProto {
4684 name: Some("Item".into()),
4685 ..Default::default()
4686 }],
4687 ..Default::default()
4688 },
4689 FileDescriptorProto {
4690 name: Some("api/v1/service.proto".into()),
4691 package: Some("api.v1".into()),
4692 syntax: Some("proto3".into()),
4693 dependency: vec!["common/types.proto".into()],
4694 message_type: vec![DescriptorProto {
4695 name: Some("Request".into()),
4696 field: vec![FieldDescriptorProto {
4697 name: Some("item".into()),
4698 number: Some(1),
4699 label: Some(Label::LABEL_OPTIONAL),
4700 r#type: Some(Type::TYPE_MESSAGE),
4701 type_name: Some(".common.Item".into()),
4702 ..Default::default()
4703 }],
4704 ..Default::default()
4705 }],
4706 ..Default::default()
4707 },
4708 ];
4709 let bytes = buffa_codegen::encode_descriptor_set(&files, &[]);
4710 let dir = tempfile::tempdir().unwrap();
4711 let path = dir.path().join("set.binpb");
4712 std::fs::write(&path, &bytes).unwrap();
4713
4714 // The file and in-memory sources produce the same output, and
4715 // `descriptor_set_bytes` replaces a previously configured file or
4716 // `buf` source. No proto sources or external compiler are needed.
4717 let configs = [
4718 Config::new().descriptor_set(&path),
4719 Config::new()
4720 .descriptor_set(dir.path().join("missing.binpb"))
4721 .descriptor_set_bytes(bytes.clone()),
4722 Config::new().use_buf().descriptor_set_bytes(bytes),
4723 ];
4724 let mut outputs = Vec::new();
4725 for (i, config) in configs.into_iter().enumerate() {
4726 let out = dir.path().join(i.to_string());
4727 config
4728 .files(&["api/v1/service.proto"])
4729 // Must not strip this prefix from descriptor-relative names.
4730 .includes(&["api"])
4731 .out_dir(&out)
4732 .include_file("gen_mod.rs")
4733 .generate_reflection(true)
4734 .shared_descriptor_pool(true)
4735 .compile()
4736 .unwrap();
4737 let generated: std::collections::BTreeMap<_, _> = std::fs::read_dir(&out)
4738 .unwrap()
4739 .map(|entry| {
4740 let entry = entry.unwrap();
4741 (entry.file_name(), std::fs::read(entry.path()).unwrap())
4742 })
4743 .collect();
4744 let source = generated
4745 .values()
4746 .map(|bytes| String::from_utf8_lossy(bytes))
4747 .collect::<Vec<_>>()
4748 .join("\n");
4749 assert!(source.contains("pub struct Request"));
4750 assert!(!source.contains("pub struct Item"));
4751 outputs.push(generated);
4752 }
4753 assert_eq!(outputs[0], outputs[1]);
4754 assert_eq!(outputs[0], outputs[2]);
4755 }
4756
4757 #[test]
4758 fn descriptor_set_bytes_rejects_malformed_input() {
4759 let dir = tempfile::tempdir().unwrap();
4760 let out = dir.path().join("gen");
4761 let err = Config::new()
4762 .descriptor_set_bytes(vec![0xff])
4763 .out_dir(&out)
4764 .compile()
4765 .unwrap_err();
4766 assert!(err.to_string().contains("FileDescriptorSet"), "{err}");
4767 assert!(!out.exists(), "invalid input must not produce output");
4768 }
4769
4770 #[test]
4771 fn descriptor_set_bytes_can_be_replaced() {
4772 let cfg = Config::new().descriptor_set_bytes(Vec::new()).use_buf();
4773 assert!(matches!(cfg.descriptor_source, DescriptorSource::Buf));
4774
4775 let cfg = Config::new()
4776 .descriptor_set_bytes(Vec::new())
4777 .descriptor_set("set.binpb");
4778 assert!(matches!(
4779 cfg.descriptor_source,
4780 DescriptorSource::Precompiled(path) if path == Path::new("set.binpb")
4781 ));
4782 }
4783
4784 #[test]
4785 fn exclude_package_stores_raw_value_for_deferred_normalization() {
4786 // Normalization (leading-dot strip, validation) happens in
4787 // generate_with_diagnostics; the builder stores the raw string so
4788 // compile() can surface errors with the original user-supplied value.
4789 let cfg = Config::new()
4790 .exclude_package(".buf.validate")
4791 .exclude_package("gnostic");
4792 assert_eq!(
4793 cfg.codegen_config.exclude_packages,
4794 vec![".buf.validate", "gnostic"],
4795 );
4796 }
4797
4798 #[test]
4799 fn exclude_package_accumulates_in_order() {
4800 let cfg = Config::new()
4801 .exclude_package("a.b")
4802 .exclude_package("c.d")
4803 .exclude_package("e.f");
4804 assert_eq!(
4805 cfg.codegen_config.exclude_packages,
4806 vec!["a.b", "c.d", "e.f"]
4807 );
4808 }
4809
4810 #[test]
4811 fn exclude_package_rejects_malformed_entries_before_reading_input() {
4812 // The descriptor set path does not exist, so an error can only come
4813 // from the validation that runs ahead of any input processing.
4814 let err = Config::new()
4815 .descriptor_set("/nonexistent/set.binpb")
4816 .files(&["foo/v1/thing.proto"])
4817 .out_dir("/nonexistent/out")
4818 .exclude_package("buf..validate")
4819 .compile()
4820 .expect_err("malformed exclude_package must fail compile()");
4821 let msg = err.to_string();
4822 assert!(msg.contains("exclude_package \"buf..validate\""), "{msg}");
4823 assert!(msg.contains("empty components"), "{msg}");
4824 }
4825
4826 #[test]
4827 fn exclude_package_drops_the_package_from_the_output() {
4828 use buffa_codegen::generated::descriptor::field_descriptor_proto::{Label, Type};
4829 use buffa_codegen::generated::descriptor::{
4830 DescriptorProto, FieldDescriptorProto, FileDescriptorProto,
4831 };
4832
4833 // Two single-message packages, both listed for generation; the
4834 // excluded one must produce no module, no include entry, and no
4835 // stitcher.
4836 let file = |name: &str, package: &str, message: &str| FileDescriptorProto {
4837 name: Some(name.into()),
4838 package: Some(package.into()),
4839 syntax: Some("proto3".into()),
4840 message_type: vec![DescriptorProto {
4841 name: Some(message.into()),
4842 field: vec![FieldDescriptorProto {
4843 name: Some("id".into()),
4844 number: Some(1),
4845 label: Some(Label::LABEL_OPTIONAL),
4846 r#type: Some(Type::TYPE_INT32),
4847 ..Default::default()
4848 }],
4849 ..Default::default()
4850 }],
4851 ..Default::default()
4852 };
4853 let files = [
4854 file("foo/v1/thing.proto", "foo.v1", "Thing"),
4855 file("buf/validate/validate.proto", "buf.validate", "Rule"),
4856 ];
4857 let fds_bytes = buffa_codegen::encode_descriptor_set(&files, &[]);
4858
4859 let dir = tempfile::tempdir().unwrap();
4860 let fds_path = dir.path().join("set.binpb");
4861 std::fs::write(&fds_path, &fds_bytes).unwrap();
4862 let out = dir.path().join("gen");
4863
4864 Config::new()
4865 .descriptor_set(&fds_path)
4866 .files(&["foo/v1/thing.proto", "buf/validate/validate.proto"])
4867 .out_dir(&out)
4868 .include_file("gen_mod.rs")
4869 .exclude_package(".buf.validate")
4870 .compile()
4871 .expect("compile with an excluded package should succeed");
4872
4873 let names: Vec<String> = std::fs::read_dir(&out)
4874 .unwrap()
4875 .map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
4876 .collect();
4877 assert!(
4878 names.iter().any(|n| n.starts_with("foo.v1.")),
4879 "kept package must be generated: {names:?}"
4880 );
4881 assert!(
4882 !names.iter().any(|n| n.contains("buf.validate")),
4883 "excluded package must produce no files: {names:?}"
4884 );
4885 let include = std::fs::read_to_string(out.join("gen_mod.rs")).unwrap();
4886 assert!(include.contains("foo"), "{include}");
4887 assert!(!include.contains("validate"), "{include}");
4888 }
4889}