Skip to main content

confluent_kafka/admin/
member_description.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//! A detailed description of a single group member.
16
17use crate::admin::MemberAssignment;
18
19/// A detailed description of a single group member in the cluster.
20// Note: Java's four `@Deprecated(forRemoval = true)` convenience constructors
21// (which only supply default values already expressible through [`new`](Self::new)) are
22// omitted; the full-field [`new`](Self::new) constructor is the sole entry point and no
23// in-scope caller or test uses the deprecated overloads.
24#[derive(Clone, Debug, PartialEq, Eq, Hash)]
25#[doc(alias = "org.apache.kafka.clients.admin.MemberDescription")]
26pub struct MemberDescription {
27    member_id: String,
28    group_instance_id: Option<String>,
29    rack_id: Option<String>,
30    client_id: String,
31    host: String,
32    assignment: MemberAssignment,
33    target_assignment: Option<MemberAssignment>,
34    member_epoch: Option<i32>,
35    upgraded: Option<bool>,
36}
37
38impl MemberDescription {
39    /// Creates a member description with all fields.
40    ///
41    /// # Arguments
42    ///
43    /// - `member_id` - the consumer id of the group member.
44    /// - `group_instance_id` - the instance id of the group member, or `None` if not set.
45    /// - `rack_id` - the rack id of the group member, or `None` if not set.
46    /// - `client_id` - the client id of the group member.
47    /// - `host` - the host where the group member is running.
48    /// - `assignment` - the assignment of the group member.
49    /// - `target_assignment` - the target assignment of the member (consumer groups only).
50    /// - `member_epoch` - the epoch of the member (consumer groups only).
51    /// - `upgraded` - whether the member uses the consumer protocol (consumer groups only).
52    #[expect(clippy::too_many_arguments)]
53    #[doc(
54        alias = "org.apache.kafka.clients.admin.MemberDescription#MemberDescription(String,Optional,Optional,String,String,MemberAssignment,Optional,Optional,Optional)"
55    )]
56    pub fn new(
57        member_id: impl Into<String>,
58        group_instance_id: Option<String>,
59        rack_id: Option<String>,
60        client_id: impl Into<String>,
61        host: impl Into<String>,
62        assignment: MemberAssignment,
63        target_assignment: Option<MemberAssignment>,
64        member_epoch: Option<i32>,
65        upgraded: Option<bool>,
66    ) -> Self {
67        Self {
68            member_id: member_id.into(),
69            group_instance_id,
70            rack_id,
71            client_id: client_id.into(),
72            host: host.into(),
73            assignment,
74            target_assignment,
75            member_epoch,
76            upgraded,
77        }
78    }
79
80    /// Returns the consumer id of the group member.
81    #[doc(alias = "org.apache.kafka.clients.admin.MemberDescription#consumerId")]
82    pub fn consumer_id(&self) -> &str {
83        &self.member_id
84    }
85
86    /// Returns the instance id of the group member.
87    #[doc(alias = "org.apache.kafka.clients.admin.MemberDescription#groupInstanceId")]
88    pub fn group_instance_id(&self) -> Option<&str> {
89        self.group_instance_id.as_deref()
90    }
91
92    /// Returns the rack id of the group member.
93    ///
94    /// It is only available for consumer groups using the new consumer group protocol
95    /// (`group.protocol=consumer`).
96    #[doc(alias = "org.apache.kafka.clients.admin.MemberDescription#rackId")]
97    pub fn rack_id(&self) -> Option<&str> {
98        self.rack_id.as_deref()
99    }
100
101    /// Returns the client id of the group member.
102    #[doc(alias = "org.apache.kafka.clients.admin.MemberDescription#clientId")]
103    pub fn client_id(&self) -> &str {
104        &self.client_id
105    }
106
107    /// Returns the host where the group member is running.
108    #[doc(alias = "org.apache.kafka.clients.admin.MemberDescription#host")]
109    pub fn host(&self) -> &str {
110        &self.host
111    }
112
113    /// Returns the assignment of the group member. Provided for both classic group and consumer
114    /// group.
115    #[doc(alias = "org.apache.kafka.clients.admin.MemberDescription#assignment")]
116    pub fn assignment(&self) -> &MemberAssignment {
117        &self.assignment
118    }
119
120    /// Returns the target assignment of the member (consumer groups only).
121    #[doc(alias = "org.apache.kafka.clients.admin.MemberDescription#targetAssignment")]
122    pub fn target_assignment(&self) -> Option<&MemberAssignment> {
123        self.target_assignment.as_ref()
124    }
125
126    /// Returns the epoch of the group member. The optional is set to an integer if the member is
127    /// in a [`GroupType::Consumer`](crate::common::GroupType::Consumer) group, and to `None` if
128    /// it is in a [`GroupType::Classic`](crate::common::GroupType::Classic) group.
129    #[doc(alias = "org.apache.kafka.clients.admin.MemberDescription#memberEpoch")]
130    pub fn member_epoch(&self) -> Option<i32> {
131        self.member_epoch
132    }
133
134    /// Returns the flag indicating whether a member within a
135    /// [`GroupType::Consumer`](crate::common::GroupType::Consumer) group uses the
136    /// [`GroupType::Consumer`](crate::common::GroupType::Consumer) protocol. The optional is set
137    /// to true if it does, to false if it does not, and to `None` if it is unknown or if the
138    /// group is a [`GroupType::Classic`](crate::common::GroupType::Classic) group.
139    #[doc(alias = "org.apache.kafka.clients.admin.MemberDescription#upgraded")]
140    pub fn upgraded(&self) -> Option<bool> {
141        self.upgraded
142    }
143}
144
145impl std::fmt::Display for MemberDescription {
146    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
147        write!(
148            f,
149            "(memberId={}, groupInstanceId={}, rackId={}, clientId={}, host={}, assignment={}, \
150             targetAssignment={}, memberEpoch={}, upgraded={})",
151            self.member_id,
152            self.group_instance_id.as_deref().unwrap_or("null"),
153            self.rack_id.as_deref().unwrap_or("null"),
154            self.client_id,
155            self.host,
156            self.assignment,
157            self.target_assignment
158                .as_ref()
159                .map_or_else(|| "null".to_string(), |a| a.to_string()),
160            self.member_epoch.map_or_else(|| "null".to_string(), |e| e.to_string()),
161            self.upgraded.map_or_else(|| "null".to_string(), |u| u.to_string()),
162        )
163    }
164}
165
166#[cfg(test)]
167mod tests {
168    use std::collections::HashSet;
169
170    use super::*;
171    use crate::common::TopicPartition;
172
173    fn assignment() -> MemberAssignment {
174        MemberAssignment::new(HashSet::from([TopicPartition::new("topic", 1)]))
175    }
176
177    fn static_member() -> MemberDescription {
178        MemberDescription::new(
179            "member_id",
180            Some("instanceId".to_string()),
181            Some("rackId".to_string()),
182            "client_id",
183            "host",
184            assignment(),
185            None,
186            None,
187            None,
188        )
189    }
190
191    /// Translated from `testEqualsWithoutGroupInstanceId`.
192    #[test]
193    #[doc(alias = "org.apache.kafka.clients.admin.MemberDescriptionTest#testEqualsWithoutGroupInstanceId")]
194    fn test_equals_without_group_instance_id() {
195        let dynamic =
196            MemberDescription::new("member_id", None, None, "client_id", "host", assignment(), None, None, None);
197        let identity =
198            MemberDescription::new("member_id", None, None, "client_id", "host", assignment(), None, None, None);
199        assert_ne!(static_member(), dynamic);
200        assert_eq!(dynamic, identity);
201    }
202
203    /// Translated from `testEqualsWithGroupInstanceId`.
204    #[test]
205    #[doc(alias = "org.apache.kafka.clients.admin.MemberDescriptionTest#testEqualsWithGroupInstanceId")]
206    fn test_equals_with_group_instance_id() {
207        let identity = MemberDescription::new(
208            "member_id",
209            Some("instanceId".to_string()),
210            Some("rackId".to_string()),
211            "client_id",
212            "host",
213            assignment(),
214            None,
215            None,
216            None,
217        );
218        assert_eq!(static_member(), identity);
219    }
220
221    /// Translated from `testNonEqual`.
222    #[test]
223    #[doc(alias = "org.apache.kafka.clients.admin.MemberDescriptionTest#testNonEqual")]
224    fn test_non_equal() {
225        let new_member = MemberDescription::new(
226            "new_member",
227            Some("instanceId".to_string()),
228            Some("rackId".to_string()),
229            "client_id",
230            "host",
231            assignment(),
232            None,
233            None,
234            None,
235        );
236        assert_ne!(static_member(), new_member);
237
238        let new_instance = MemberDescription::new(
239            "member_id",
240            Some("new_instance".to_string()),
241            Some("rackId".to_string()),
242            "client_id",
243            "host",
244            assignment(),
245            None,
246            None,
247            None,
248        );
249        assert_ne!(static_member(), new_instance);
250
251        let new_target = MemberDescription::new(
252            "member_id",
253            Some("instanceId".to_string()),
254            Some("rackId".to_string()),
255            "client_id",
256            "host",
257            assignment(),
258            Some(assignment()),
259            None,
260            None,
261        );
262        assert_ne!(static_member(), new_target);
263
264        let new_epoch = MemberDescription::new(
265            "member_id",
266            Some("instanceId".to_string()),
267            Some("rackId".to_string()),
268            "client_id",
269            "host",
270            assignment(),
271            None,
272            Some(1),
273            None,
274        );
275        assert_ne!(static_member(), new_epoch);
276
277        let new_is_classic = MemberDescription::new(
278            "member_id",
279            Some("instanceId".to_string()),
280            Some("rackId".to_string()),
281            "client_id",
282            "host",
283            assignment(),
284            None,
285            None,
286            Some(false),
287        );
288        assert_ne!(static_member(), new_is_classic);
289    }
290}