Skip to main content

kafka_client_engine/consumer/group_event/
model.rs

1//! Owned named facts observed from confirmed group membership.
2
3use std::sync::Arc;
4
5use kafka_client_core::GroupPositionFence;
6
7/// One named topic-partition in a confirmed classic-group assignment.
8#[derive(Debug, Eq, PartialEq)]
9pub struct GroupConsumerAssignmentPartition {
10    topic: Arc<str>,
11    partition: i32,
12}
13
14impl GroupConsumerAssignmentPartition {
15    pub(in crate::consumer) const fn new(topic: Arc<str>, partition: i32) -> Self {
16        Self { topic, partition }
17    }
18
19    /// Returns the exact Kafka topic spelling.
20    pub fn topic(&self) -> &str {
21        &self.topic
22    }
23
24    /// Returns the zero-based Kafka partition.
25    pub const fn partition(&self) -> i32 {
26        self.partition
27    }
28}
29
30/// One confirmed assignment fence and its ordered topic-partitions.
31#[derive(Debug, Eq, PartialEq)]
32pub struct GroupConsumerAssignment {
33    assignment_epoch: u64,
34    partitions: Box<[GroupConsumerAssignmentPartition]>,
35}
36
37impl GroupConsumerAssignment {
38    pub(in crate::consumer) fn new(
39        assignment_epoch: u64,
40        partitions: Vec<GroupConsumerAssignmentPartition>,
41    ) -> Self {
42        Self {
43            assignment_epoch,
44            partitions: partitions.into_boxed_slice(),
45        }
46    }
47
48    /// Returns the nonreused local assignment fence.
49    pub const fn assignment_epoch(&self) -> u64 {
50        self.assignment_epoch
51    }
52
53    /// Borrows the ordered unique topic-partitions.
54    pub fn partitions(&self) -> &[GroupConsumerAssignmentPartition] {
55        &self.partitions
56    }
57}
58
59/// Broker-issued fencing epoch for one confirmed group membership.
60#[derive(Clone, Copy, Debug, Eq, PartialEq)]
61pub enum GroupConsumerMembershipEpoch {
62    /// Generation assigned by the classic `JoinGroup` protocol.
63    Classic {
64        /// Nonnegative generation assigned by `JoinGroup`.
65        generation_id: i32,
66    },
67    /// Member epoch assigned by the KIP-848 consumer-group protocol.
68    Consumer {
69        /// Positive epoch assigned by `ConsumerGroupHeartbeat`.
70        member_epoch: i32,
71    },
72}
73
74impl GroupConsumerMembershipEpoch {
75    pub(crate) const fn generation_id_or_member_epoch(self) -> i32 {
76        match self {
77            Self::Classic { generation_id } => generation_id,
78            Self::Consumer { member_epoch } => member_epoch,
79        }
80    }
81}
82
83/// Stable protocol identity for one confirmed group membership.
84#[derive(Clone, Debug, Eq, PartialEq)]
85pub struct GroupConsumerMetadata {
86    group: Arc<str>,
87    group_instance_id: Option<Arc<str>>,
88    member: Arc<str>,
89    transaction_group_instance_id: Option<Arc<str>>,
90    membership_epoch: GroupConsumerMembershipEpoch,
91    assignment_epoch: u64,
92    position_fence: GroupPositionFence,
93}
94
95impl GroupConsumerMetadata {
96    pub(crate) const fn new_with_group_instance_id(
97        group: Arc<str>,
98        group_instance_id: Option<Arc<str>>,
99        member: Arc<str>,
100        transaction_group_instance_id: Option<Arc<str>>,
101        membership_epoch: GroupConsumerMembershipEpoch,
102        assignment_epoch: u64,
103        position_fence: GroupPositionFence,
104    ) -> Self {
105        Self {
106            group,
107            group_instance_id,
108            member,
109            transaction_group_instance_id,
110            membership_epoch,
111            assignment_epoch,
112            position_fence,
113        }
114    }
115
116    /// Returns the exact Kafka group spelling.
117    pub fn group(&self) -> &str {
118        &self.group
119    }
120
121    /// Returns the configured stable classic-group member identity, when present.
122    pub fn group_instance_id(&self) -> Option<&str> {
123        self.group_instance_id.as_deref()
124    }
125
126    /// Returns the broker-issued group member identity.
127    pub fn member(&self) -> &str {
128        &self.member
129    }
130
131    /// Returns the protocol-specific broker fencing epoch.
132    pub const fn membership_epoch(&self) -> GroupConsumerMembershipEpoch {
133        self.membership_epoch
134    }
135
136    pub(crate) const fn generation_id_or_member_epoch(&self) -> i32 {
137        self.membership_epoch.generation_id_or_member_epoch()
138    }
139
140    /// Returns the local assignment fence current for this metadata.
141    pub const fn assignment_epoch(&self) -> u64 {
142        self.assignment_epoch
143    }
144
145    pub(crate) fn group_arc(&self) -> Arc<str> {
146        Arc::clone(&self.group)
147    }
148
149    pub(crate) fn member_arc(&self) -> Arc<str> {
150        Arc::clone(&self.member)
151    }
152
153    pub(crate) fn group_instance_id_arc(&self) -> Option<Arc<str>> {
154        self.transaction_group_instance_id.as_ref().map(Arc::clone)
155    }
156
157    pub(crate) const fn position_fence(&self) -> GroupPositionFence {
158        self.position_fence
159    }
160}
161
162/// One atomically observed confirmed membership and assignment.
163#[derive(Debug, Eq, PartialEq)]
164pub struct GroupConsumerState {
165    assignment: GroupConsumerAssignment,
166    metadata: GroupConsumerMetadata,
167}
168
169impl GroupConsumerState {
170    pub(in crate::consumer) const fn new(
171        assignment: GroupConsumerAssignment,
172        metadata: GroupConsumerMetadata,
173    ) -> Self {
174        Self {
175            assignment,
176            metadata,
177        }
178    }
179
180    /// Borrows the current confirmed assignment.
181    pub const fn assignment(&self) -> &GroupConsumerAssignment {
182        &self.assignment
183    }
184
185    /// Borrows the current confirmed group metadata.
186    pub const fn metadata(&self) -> &GroupConsumerMetadata {
187        &self.metadata
188    }
189
190    /// Splits the atomically observed facts into their owned values.
191    pub fn into_parts(self) -> (GroupConsumerAssignment, GroupConsumerMetadata) {
192        (self.assignment, self.metadata)
193    }
194}
195
196/// Application-visible classic-group assignment transition.
197///
198/// The bounded lifecycle retains the prior terminal transition followed by a
199/// current assignment. An unobserved assignment may be superseded by revoked or
200/// lost state for that exact epoch.
201#[derive(Debug, Eq, PartialEq)]
202pub enum GroupConsumerEvent {
203    /// A successful Sync response was installed and driver-confirmed.
204    PartitionsAssigned(GroupConsumerAssignment),
205    /// The named assignment entered bounded graceful release and may be
206    /// completed by its exact assignment epoch.
207    PartitionsRevoked(GroupConsumerAssignment),
208    /// The named assignment was retired; its epoch and every older checkpoint
209    /// are stale.
210    PartitionsLost(GroupConsumerAssignment),
211}