confluent_kafka/common/header/mod.rs
1// Copyright 2025 Confluent Inc.
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
15//! Kafka record headers (org.apache.kafka.common.header).
16//!
17//! A header is a key-value pair attached to a Kafka record. The [`Header`] trait
18//! defines the contract, while [`Headers`] is a mutable ordered collection of
19//! headers.
20
21pub(crate) mod internals;
22
23// Re-export the canonical `RecordHeader` and `RecordHeaders` implementations
24// for external users. In Java these live in
25// `org.apache.kafka.common.header.internals` as `public class` declarations
26// — they are part of the public API surface despite being in an `internals`
27// package. The translation rules keep the `internals` Rust module `pub(crate)`, so
28// we re-export the public types at the `common::header` level to make them
29// reachable from external code (matching Java's effective visibility).
30use crate::common::LocalIllegalStateError;
31
32pub use internals::{RecordHeader, RecordHeaders};
33
34/// A header is a key-value pair.
35#[doc(alias = "org.apache.kafka.common.header.Header")]
36pub trait Header {
37 /// Returns the key of the header.
38 ///
39 /// # Returns
40 ///
41 /// the header's key; must not be `None`.
42 #[doc(alias = "org.apache.kafka.common.header.Header#key")]
43 fn key(&self) -> &str;
44
45 /// Returns the value of the header.
46 ///
47 /// # Returns
48 ///
49 /// the header's value; may be `None`.
50 #[doc(alias = "org.apache.kafka.common.header.Header#value")]
51 fn value(&self) -> Option<&[u8]>;
52}
53
54/// A mutable ordered collection of [`Header`] objects. Note that multiple headers may have the same
55/// key.
56///
57/// The order of headers is preserved in the order they were added.
58#[doc(alias = "org.apache.kafka.common.header.Headers")]
59pub trait Headers {
60 /// Adds a header (key inside), to the end, returning if the operation succeeded.
61 ///
62 /// # Arguments
63 ///
64 /// - `header` - the Header to be added.
65 ///
66 /// # Errors
67 ///
68 /// - [`Error::is_local_illegal_state_error`](crate::common::Error::is_local_illegal_state_error)
69 /// if headers are in a read-only state.
70 #[doc(alias = "org.apache.kafka.common.header.Headers#add")]
71 fn add_with_header(&mut self, header: RecordHeader) -> Result<(), LocalIllegalStateError>;
72
73 /// Creates and adds a header, to the end, returning if the operation succeeded.
74 ///
75 /// # Arguments
76 ///
77 /// - `key` - of the header to be added.
78 /// - `value` - of the header to be added; may be `None`.
79 ///
80 /// # Errors
81 ///
82 /// - [`Error::is_local_illegal_state_error`](crate::common::Error::is_local_illegal_state_error)
83 /// if headers are in a read-only state.
84 ///
85 /// # Translation notes
86 ///
87 /// The key and value are borrowed and copied into the new header.
88 #[doc(alias = "org.apache.kafka.common.header.Headers#add")]
89 fn add_with_key_value(&mut self, key: &str, value: Option<&[u8]>) -> Result<(), LocalIllegalStateError>;
90
91 /// Removes all headers for the given key returning if the operation succeeded,
92 /// while preserving the insertion order of the remaining headers.
93 ///
94 /// # Arguments
95 ///
96 /// - `key` - to remove all headers for.
97 ///
98 /// # Errors
99 ///
100 /// - [`Error::is_local_illegal_state_error`](crate::common::Error::is_local_illegal_state_error)
101 /// if headers are in a read-only state.
102 #[doc(alias = "org.apache.kafka.common.header.Headers#remove")]
103 fn remove(&mut self, key: &str) -> Result<(), LocalIllegalStateError>;
104
105 /// Returns just one (the very last) header for the given key, if present.
106 ///
107 /// # Arguments
108 ///
109 /// - `key` - to get the last header for.
110 ///
111 /// # Returns
112 ///
113 /// this last header matching the given key, returns `None` if not present.
114 #[doc(alias = "org.apache.kafka.common.header.Headers#lastHeader")]
115 fn last_header(&self, key: &str) -> Option<&RecordHeader>;
116
117 /// Returns all headers for the given key, in the order they were added in, if present.
118 ///
119 /// # Arguments
120 ///
121 /// - `key` - to return the headers for.
122 ///
123 /// # Returns
124 ///
125 /// all headers for the given key, in the order they were added in, if NO headers are present an
126 /// empty list is returned.
127 #[doc(alias = "org.apache.kafka.common.header.Headers#headers")]
128 fn headers(&self, key: &str) -> Vec<&RecordHeader>;
129
130 /// Returns all headers as a slice, in the order they were added in.
131 ///
132 /// # Returns
133 ///
134 /// the headers, if NO headers are present an empty slice is returned.
135 #[doc(alias = "org.apache.kafka.common.header.Headers#toArray")]
136 fn to_array(&self) -> &[RecordHeader];
137
138 /// Returns an iterator over the headers.
139 // Java's Iterable.iterator, a JDK interface Headers extends
140 #[doc(alias = "rust-only")]
141 fn iter(&self) -> std::slice::Iter<'_, RecordHeader>;
142}