Skip to main content

kafka_client_engine/consumer/group_batch/
checkpoint.rs

1//! Stable public ownership of one exact core group checkpoint.
2
3use std::sync::Arc;
4
5use kafka_client_core::{
6    GroupCheckpoint, GroupCheckpointEntry, GroupPositionFence, PartitionIndex, TopicId,
7};
8
9use crate::consumer::group::ClassicGroupFetchDelivery;
10
11/// One linear assignment-fenced next-offset checkpoint.
12///
13/// The engine retains the exact group, member, assignment generation, and
14/// catalog topic identity required by commit admission without exposing those
15/// internal identities through the public API.
16#[must_use = "a group checkpoint should be committed or deliberately discarded"]
17pub struct GroupConsumerCheckpoint {
18    topic: Arc<str>,
19    partition: i32,
20    next_offset: i64,
21    position_fence: GroupPositionFence,
22    checkpoint: GroupCheckpoint,
23}
24
25/// Exact stable and catalog identities retained across public commit admission.
26pub(in crate::consumer) struct GroupConsumerCheckpointObservation {
27    checkpoint: GroupConsumerCheckpoint,
28    pub(in crate::consumer) topic_id: TopicId,
29    pub(in crate::consumer) partition_id: PartitionIndex,
30}
31
32impl GroupConsumerCheckpoint {
33    /// Returns the catalog-owned Kafka topic name.
34    pub fn topic(&self) -> &str {
35        &self.topic
36    }
37
38    /// Returns the zero-based Kafka partition.
39    pub const fn partition(&self) -> i32 {
40        self.partition
41    }
42
43    /// Returns the next offset to consume.
44    pub const fn next_offset(&self) -> i64 {
45        self.next_offset
46    }
47
48    pub(crate) const fn position_fence(&self) -> GroupPositionFence {
49        self.position_fence
50    }
51
52    pub(crate) fn transaction_offset(&self) -> (&Arc<str>, i32, i64, Option<i32>) {
53        let entry = self
54            .checkpoint
55            .entries()
56            .first()
57            .unwrap_or_else(|| unreachable!("public checkpoint retains one entry"));
58        (
59            &self.topic,
60            self.partition,
61            self.next_offset,
62            entry.leader_epoch(),
63        )
64    }
65
66    pub(in crate::consumer) fn try_into_commit_parts(
67        self,
68    ) -> Result<(GroupConsumerCheckpointObservation, GroupCheckpoint), Self> {
69        let entry = self
70            .checkpoint
71            .entries()
72            .first()
73            .unwrap_or_else(|| unreachable!("public checkpoint retains one entry"));
74        let mut entries = Vec::new();
75        if entries
76            .try_reserve_exact(self.checkpoint.entries().len())
77            .is_err()
78        {
79            return Err(self);
80        }
81        entries.extend_from_slice(self.checkpoint.entries());
82        let submission = GroupCheckpoint::try_new(
83            self.checkpoint.group_id(),
84            self.checkpoint.member_id(),
85            self.checkpoint.assignment_generation(),
86            entries,
87        )
88        .unwrap_or_else(|error| {
89            unreachable!("the exact admitted checkpoint copy remains structurally valid: {error}")
90        });
91        Ok((
92            GroupConsumerCheckpointObservation {
93                topic_id: entry.topic_id(),
94                partition_id: entry.partition(),
95                checkpoint: self,
96            },
97            submission,
98        ))
99    }
100
101    #[cfg(test)]
102    pub(in crate::consumer) fn into_core(self) -> GroupCheckpoint {
103        self.checkpoint
104    }
105
106    #[cfg(test)]
107    pub(in crate::consumer) fn storage_identity(
108        &self,
109    ) -> (*const str, *const GroupCheckpointEntry) {
110        (Arc::as_ptr(&self.topic), self.checkpoint.entries().as_ptr())
111    }
112
113    #[cfg(test)]
114    pub(in crate::consumer) fn from_test_parts(
115        topic: Arc<str>,
116        partition: i32,
117        next_offset: i64,
118        position_fence: GroupPositionFence,
119        checkpoint: GroupCheckpoint,
120    ) -> Self {
121        Self {
122            topic,
123            partition,
124            next_offset,
125            position_fence,
126            checkpoint,
127        }
128    }
129}
130
131impl GroupConsumerCheckpointObservation {
132    pub(in crate::consumer) fn topic(&self) -> &Arc<str> {
133        &self.checkpoint.topic
134    }
135
136    pub(in crate::consumer) const fn partition(&self) -> i32 {
137        self.checkpoint.partition
138    }
139
140    pub(in crate::consumer) fn into_checkpoint(self) -> GroupConsumerCheckpoint {
141        self.checkpoint
142    }
143
144    #[cfg(test)]
145    pub(in crate::consumer) fn from_checkpoint(checkpoint: GroupConsumerCheckpoint) -> Self {
146        let (observation, submission) = checkpoint
147            .try_into_commit_parts()
148            .unwrap_or_else(|_checkpoint| panic!("test checkpoint copy"));
149        drop(submission);
150        observation
151    }
152
153    #[cfg(test)]
154    pub(in crate::consumer) fn storage_identity(
155        &self,
156    ) -> (*const str, *const GroupCheckpointEntry) {
157        self.checkpoint.storage_identity()
158    }
159}
160
161impl std::fmt::Debug for GroupConsumerCheckpoint {
162    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
163        formatter
164            .debug_struct("GroupConsumerCheckpoint")
165            .field("topic", &self.topic)
166            .field("partition", &self.partition)
167            .field("next_offset", &self.next_offset)
168            .finish_non_exhaustive()
169    }
170}
171
172pub(super) fn checkpoint_from_delivery(
173    delivery: &ClassicGroupFetchDelivery,
174) -> GroupConsumerCheckpoint {
175    checkpoint_from_delivery_at(delivery, delivery.next_offset().get())
176}
177
178pub(super) fn checkpoint_from_delivery_at(
179    delivery: &ClassicGroupFetchDelivery,
180    next_offset: i64,
181) -> GroupConsumerCheckpoint {
182    let fence = delivery.position_fence();
183    let partition = delivery.partition_identity();
184    let entry = GroupCheckpointEntry::try_new(
185        partition.topic_id(),
186        partition.partition(),
187        next_offset,
188        None,
189    )
190    .unwrap_or_else(|error| unreachable!("Fetch delivery is checkpoint-valid: {error}"));
191    let checkpoint = GroupCheckpoint::try_new(
192        fence.group_id(),
193        fence.member_id(),
194        fence.assignment_generation(),
195        vec![entry],
196    )
197    .unwrap_or_else(|error| unreachable!("one Fetch delivery is a valid checkpoint: {error}"));
198    GroupConsumerCheckpoint {
199        topic: Arc::clone(delivery.topic_arc()),
200        partition: delivery.partition(),
201        next_offset,
202        position_fence: fence,
203        checkpoint,
204    }
205}