Skip to main content

buffa/
editions.rs

1//! Edition feature types and resolution.
2//!
3//! These types represent the protobuf edition features that control code
4//! generation and runtime behavior. They are resolved at compile time by
5//! `buffa-codegen` and baked into generated code.
6
7/// The edition of a `.proto` file.
8///
9/// # Variant ordering
10///
11/// Variants are declared in chronological edition order.  The derived
12/// `PartialOrd` / `Ord` implementations use declaration order, so new
13/// editions **must be appended** — inserting a variant between existing
14/// ones would silently break edition comparison logic.
15#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
16#[non_exhaustive]
17pub enum Edition {
18    /// Proto2 syntax (resolves to proto2 feature defaults).
19    Proto2,
20    /// Proto3 syntax (resolves to proto3 feature defaults).
21    Proto3,
22    /// Edition 2023.
23    Edition2023,
24    /// Edition 2024.
25    Edition2024,
26}
27
28/// Controls whether field presence is tracked.
29#[derive(Clone, Copy, Debug, PartialEq, Eq)]
30#[non_exhaustive]
31pub enum FieldPresence {
32    /// Presence is tracked explicitly (has-bit or Option).
33    Explicit,
34    /// No presence tracking; default value means "not set."
35    Implicit,
36    /// Legacy `required` behavior from proto2.
37    LegacyRequired,
38}
39
40/// Controls how unknown enum values are handled.
41#[derive(Clone, Copy, Debug, PartialEq, Eq)]
42#[non_exhaustive]
43pub enum EnumType {
44    /// Unknown values are preserved in the field (first-class `EnumValue<E>`).
45    Open,
46    /// Unknown values are stored in unknown fields.
47    Closed,
48}
49
50/// Controls wire encoding of repeated scalar fields.
51#[derive(Clone, Copy, Debug, PartialEq, Eq)]
52#[non_exhaustive]
53pub enum RepeatedFieldEncoding {
54    /// Packed encoding (length-delimited, all values concatenated).
55    Packed,
56    /// Expanded encoding (one tag per element).
57    Expanded,
58}
59
60/// Controls UTF-8 validation for string fields.
61#[derive(Clone, Copy, Debug, PartialEq, Eq)]
62#[non_exhaustive]
63pub enum Utf8Validation {
64    /// Validate that string fields contain valid UTF-8.
65    Verify,
66    /// Skip UTF-8 validation.
67    None,
68}
69
70/// Controls wire encoding of message fields.
71#[derive(Clone, Copy, Debug, PartialEq, Eq)]
72#[non_exhaustive]
73pub enum MessageEncoding {
74    /// Standard length-prefixed encoding.
75    LengthPrefixed,
76    /// Delimited (group-style) encoding.
77    Delimited,
78}
79
80/// Controls JSON format support.
81#[derive(Clone, Copy, Debug, PartialEq, Eq)]
82#[non_exhaustive]
83pub enum JsonFormat {
84    /// Full JSON support.
85    Allow,
86    /// Legacy best-effort JSON support.
87    LegacyBestEffort,
88}
89
90/// The resolved set of edition features for a protobuf element.
91///
92/// # Forward compatibility
93///
94/// This struct is intentionally **not** `#[non_exhaustive]`. It is
95/// constructed via struct literals by `buffa-codegen` (workspace sibling,
96/// always released in lockstep with this crate). Adding a new feature field
97/// here requires a coordinated change in `buffa-codegen::features::merge`.
98///
99/// User code should not construct `ResolvedFeatures` directly — use the
100/// `*_defaults()` associated functions instead.
101#[derive(Clone, Copy, Debug, PartialEq, Eq)]
102pub struct ResolvedFeatures {
103    pub field_presence: FieldPresence,
104    pub enum_type: EnumType,
105    pub repeated_field_encoding: RepeatedFieldEncoding,
106    pub utf8_validation: Utf8Validation,
107    pub message_encoding: MessageEncoding,
108    pub json_format: JsonFormat,
109}
110
111impl ResolvedFeatures {
112    /// Default features for Edition 2023.
113    pub fn edition_2023_defaults() -> Self {
114        Self {
115            field_presence: FieldPresence::Explicit,
116            enum_type: EnumType::Open,
117            repeated_field_encoding: RepeatedFieldEncoding::Packed,
118            utf8_validation: Utf8Validation::Verify,
119            message_encoding: MessageEncoding::LengthPrefixed,
120            json_format: JsonFormat::Allow,
121        }
122    }
123
124    /// Features that replicate proto2 behavior.
125    pub fn proto2_defaults() -> Self {
126        Self {
127            field_presence: FieldPresence::Explicit,
128            enum_type: EnumType::Closed,
129            repeated_field_encoding: RepeatedFieldEncoding::Expanded,
130            utf8_validation: Utf8Validation::None,
131            message_encoding: MessageEncoding::LengthPrefixed,
132            json_format: JsonFormat::LegacyBestEffort,
133        }
134    }
135
136    /// Features that replicate proto3 behavior.
137    pub fn proto3_defaults() -> Self {
138        Self {
139            field_presence: FieldPresence::Implicit,
140            enum_type: EnumType::Open,
141            repeated_field_encoding: RepeatedFieldEncoding::Packed,
142            utf8_validation: Utf8Validation::Verify,
143            message_encoding: MessageEncoding::LengthPrefixed,
144            json_format: JsonFormat::Allow,
145        }
146    }
147}