Skip to main content

kafka_client_engine/consumer/assigned_host/
assignment.rs

1//! Stable engine-owned scalar inputs for one direct-assignment replacement.
2
3use std::sync::Arc;
4
5use kafka_client_core::{PartitionIndex, StartPosition};
6
7const MAX_TOPIC_NAME_BYTES: usize = 249;
8
9/// Explicit initial-position policy for one directly assigned partition.
10#[derive(Clone, Copy, Debug, Eq, PartialEq)]
11pub enum AssignedConsumerStartPosition {
12    /// Resolve Kafka's earliest available offset.
13    Beginning,
14    /// Resolve Kafka's end offset.
15    End,
16    /// Begin at this exact nonnegative next-fetch offset.
17    Offset(i64),
18}
19
20/// One caller-ordered topic-partition and its required initial position.
21#[derive(Clone, Debug, Eq, PartialEq)]
22pub struct AssignedConsumerAssignment {
23    pub(in crate::consumer) topic: Arc<str>,
24    partition: i32,
25    pub(in crate::consumer) start: StartPosition,
26}
27
28impl AssignedConsumerAssignment {
29    /// Validates one engine-owned assignment entry before operation admission.
30    pub fn try_new(
31        topic: impl Into<Arc<str>>,
32        partition: i32,
33        start: AssignedConsumerStartPosition,
34    ) -> Result<Self, AssignedConsumerAssignmentInputError> {
35        let topic = topic.into();
36        if topic.is_empty() {
37            return Err(AssignedConsumerAssignmentInputError::new(
38                AssignedConsumerAssignmentInputErrorKind::EmptyTopic,
39            ));
40        }
41        if topic.len() > MAX_TOPIC_NAME_BYTES {
42            return Err(AssignedConsumerAssignmentInputError::new(
43                AssignedConsumerAssignmentInputErrorKind::TopicTooLong,
44            ));
45        }
46        if partition.is_negative() {
47            return Err(AssignedConsumerAssignmentInputError::new(
48                AssignedConsumerAssignmentInputErrorKind::NegativePartition,
49            ));
50        }
51        let start = start
52            .try_into_core()
53            .ok_or(AssignedConsumerAssignmentInputError::new(
54                AssignedConsumerAssignmentInputErrorKind::NegativeOffset,
55            ))?;
56        Ok(Self {
57            topic,
58            partition,
59            start,
60        })
61    }
62
63    /// Returns the retained topic name.
64    pub fn topic(&self) -> &str {
65        &self.topic
66    }
67
68    /// Returns the validated Kafka partition.
69    pub const fn partition(&self) -> i32 {
70        self.partition
71    }
72
73    pub(in crate::consumer) const fn partition_index(&self) -> PartitionIndex {
74        PartitionIndex::from_raw(self.partition.cast_unsigned())
75    }
76
77    /// Returns the explicit initial-position policy.
78    pub const fn start(&self) -> AssignedConsumerStartPosition {
79        match self.start {
80            StartPosition::Beginning => AssignedConsumerStartPosition::Beginning,
81            StartPosition::End => AssignedConsumerStartPosition::End,
82            StartPosition::Offset(offset) => AssignedConsumerStartPosition::Offset(offset.get()),
83        }
84    }
85
86    #[cfg(test)]
87    pub(crate) const fn new(
88        topic: Arc<str>,
89        partition: PartitionIndex,
90        start: StartPosition,
91    ) -> Self {
92        Self {
93            topic,
94            partition: partition.get().cast_signed(),
95            start,
96        }
97    }
98}
99
100impl AssignedConsumerStartPosition {
101    pub(in crate::consumer) fn try_into_core(self) -> Option<StartPosition> {
102        match self {
103            Self::Beginning => Some(StartPosition::Beginning),
104            Self::End => Some(StartPosition::End),
105            Self::Offset(offset) => {
106                kafka_client_core::NextFetchOffset::try_from_raw(offset).map(StartPosition::Offset)
107            }
108        }
109    }
110}
111
112/// Stable reason one scalar assignment entry is not representable.
113#[derive(Clone, Copy, Debug, Eq, PartialEq)]
114pub enum AssignedConsumerAssignmentInputErrorKind {
115    /// Kafka topic names cannot be empty.
116    EmptyTopic,
117    /// The topic exceeds Kafka's 249-byte name limit.
118    TopicTooLong,
119    /// Kafka partitions are nonnegative signed 32-bit values.
120    NegativePartition,
121    /// Explicit next-fetch offsets are nonnegative.
122    NegativeOffset,
123}
124
125/// Rejection while constructing one assignment entry.
126#[derive(Clone, Copy, Debug, Eq, PartialEq)]
127pub struct AssignedConsumerAssignmentInputError {
128    kind: AssignedConsumerAssignmentInputErrorKind,
129}
130
131impl AssignedConsumerAssignmentInputError {
132    const fn new(kind: AssignedConsumerAssignmentInputErrorKind) -> Self {
133        Self { kind }
134    }
135
136    /// Returns the stable scalar-validation category.
137    pub const fn kind(&self) -> AssignedConsumerAssignmentInputErrorKind {
138        self.kind
139    }
140}
141
142impl std::fmt::Display for AssignedConsumerAssignmentInputError {
143    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
144        write!(
145            formatter,
146            "invalid assigned-consumer assignment entry: {:?}",
147            self.kind
148        )
149    }
150}
151
152impl std::error::Error for AssignedConsumerAssignmentInputError {}
153
154pub(crate) type AssignedPartitionInput = AssignedConsumerAssignment;