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}