Skip to main content

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}