rocketmq_protocol/protocol/header_codec/
schema.rs

1// Copyright 2026 The RocketMQ Rust Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use super::HeaderRange;
16use super::HeaderValueKind;
17
18/// Decode behavior when canonical and legacy alias keys coexist.
19#[derive(Clone, Copy, Debug, Eq, PartialEq)]
20pub enum AliasConflictPolicy {
21    /// Reject different canonical and alias values.
22    Error,
23    /// Use the canonical value when an audited compatibility rule permits it.
24    PreferCanonical,
25}
26
27/// Merge behavior between typed fields and dynamic extension fields.
28#[derive(Clone, Copy, Debug, Eq, PartialEq)]
29pub enum DynamicCollisionPolicy {
30    /// Accept an identical value but reject a different value.
31    ErrorOnDifferentValue,
32}
33
34/// Missing-field semantics recorded in generated header schemas.
35#[derive(Clone, Copy, Debug, Eq, PartialEq)]
36pub enum HeaderPresence {
37    /// The key must be present.
38    Required,
39    /// Absence decodes as `None`.
40    Optional,
41    /// Absence uses `Default::default`.
42    Default,
43    /// Absence calls the named, reviewed default provider.
44    DefaultWith(&'static str),
45}
46
47/// Presence semantics for a flattened nested header.
48#[derive(Clone, Copy, Debug, Eq, PartialEq)]
49pub enum FlattenPresenceSpec {
50    /// Always construct and validate the nested header.
51    Always,
52    /// Construct the nested header when any of its canonical keys or aliases exists.
53    Any,
54}
55
56/// Static schema metadata for one non-flattened header field.
57#[derive(Clone, Copy, Debug, Eq, PartialEq)]
58pub struct HeaderFieldSpec {
59    /// Rust source field name.
60    pub rust_field: &'static str,
61    /// Canonical wire key used by encoders.
62    pub key: &'static str,
63    /// Ordered decode-only aliases.
64    pub aliases: &'static [&'static str],
65    /// Canonical/alias conflict behavior.
66    pub alias_conflict: AliasConflictPolicy,
67    /// Protocol value category.
68    pub kind: HeaderValueKind,
69    /// Missing-field behavior.
70    pub presence: HeaderPresence,
71    /// Stable literal or dynamic default semantic identifier.
72    pub default_semantic: Option<&'static str>,
73    /// Optional Java type override for compatibility tooling.
74    ///
75    /// Tooling should infer the normal wire category from [`Self::kind`] when
76    /// this is `None`. Production headers only set this for exceptional
77    /// mappings that cannot be inferred from the Rust value type.
78    pub java_type: Option<&'static str>,
79    /// Signed Java range imposed on an unsigned Rust value.
80    pub java_range: Option<HeaderRange>,
81    /// Stable field order within the declaring header.
82    pub binary_order: u16,
83    /// Stable type identifier of the declaring header.
84    pub declared_in: &'static str,
85}
86
87/// Static schema metadata for one flattened nested header.
88#[derive(Clone, Copy, Debug, Eq, PartialEq)]
89pub struct HeaderFlattenSpec {
90    /// Rust source field name.
91    pub rust_field: &'static str,
92    /// Stable typed-codec identifier of the nested header.
93    pub nested_type_id: &'static str,
94    /// Nested construction policy.
95    pub presence: FlattenPresenceSpec,
96    /// Stable group order within the declaring header.
97    pub binary_order: u16,
98    /// Stable type identifier of the declaring header.
99    pub declared_in: &'static str,
100}
101
102/// Canonical resolution result for a canonical key or decode alias.
103#[derive(Clone, Copy, Debug, Eq, PartialEq)]
104pub struct ResolvedHeaderKey {
105    /// Stable header name used in diagnostics.
106    pub header: &'static str,
107    /// Stable type identifier of the field owner, including nested owners.
108    pub owner_type_id: &'static str,
109    /// Canonical wire key.
110    pub canonical: &'static str,
111    /// Resolution precedence: canonical is zero and alias `n` is `n + 1`.
112    pub precedence: u16,
113    /// Canonical/alias conflict behavior.
114    pub alias_conflict: AliasConflictPolicy,
115    /// Typed/dynamic collision behavior.
116    pub dynamic_collision: DynamicCollisionPolicy,
117}
rocketmq_protocol/protocol/header_codec/schema.rs

rocketmq_protocol/protocol/header_codec/
schema.rs
