confluent_kafka/consumer/consumer_partition_assignor.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//! Data holders for the consumer partition assignor protocol.
16//!
17//! Translated from the `Subscription` and `Assignment` nested data classes of
18//! `org.apache.kafka.clients.consumer.ConsumerPartitionAssignor`.
19//!
20//! Only the two data holders are in scope here: they are consumed by
21//! `ConsumerProtocol`
22//! for (de)serializing member subscriptions/assignments, which the admin
23//! group-describe path relies on. The `ConsumerPartitionAssignor` trait itself
24//! and the client-side assignors (`RangeAssignor`, `StickyAssignor`, ...) are
25//! out of scope for Milestone 8/11 (KIP-848 uses server-side assignment) — see
26//! `consumer-threading.md` §20.
27
28use crate::common::Error;
29use crate::common::TopicPartition;
30
31/// The default generation id used when a subscription carries no generation.
32///
33/// Corresponds to `AbstractStickyAssignor.DEFAULT_GENERATION`, which
34/// `org.apache.kafka.clients.consumer.ConsumerPartitionAssignor` static-imports.
35///
36/// Stays a module-level constant rather than becoming an associated const:
37/// the Java class that *declares* it, `AbstractStickyAssignor`, is a
38/// client-side assignor and is out of scope per `consumer-threading.md` §20,
39/// so there is no translated type to host it on. It is referenced only within
40/// this file, and is not public: its Java home is in `consumer.internals`.
41pub(crate) const DEFAULT_GENERATION: i32 = -1;
42
43/// The parameters of [`Subscription::with_options`], built with
44/// [`SubscriptionOptionsBuilder`]: `topics` is mandatory.
45// The parameters of Java's widest `Subscription` constructor
46// (`Subscription(List, ByteBuffer, List, int, Optional<String>)`). That
47// constructor carries four parameters beyond the overload group's `{topics}`
48// intersection, so the naming rule caps its derived name and makes this struct
49// the method's only parameter, `topics` included (DoD #7).
50//
51// It deliberately has no `Default`: `topics` is what even Java's narrowest
52// `Subscription(List)` constructor takes from its caller, so it has no
53// Java-derived default, and a synthesised empty topic list would silently
54// produce a subscription to nothing.
55#[derive(Clone, Debug, PartialEq, Eq)]
56#[non_exhaustive]
57// the options of Subscription's constructor overloads (CLAUDE.md §2)
58#[doc(alias = "rust-only")]
59pub struct SubscriptionOptions {
60 // Java's `topics`.
61 pub(crate) topics: Vec<String>,
62 // Java's `userData`. Starts as `None`, as in `Subscription(List)`.
63 pub(crate) user_data: Option<Vec<u8>>,
64 // Java's `ownedPartitions`. Starts empty, as in `Subscription(List)`
65 // (`Collections.emptyList()`).
66 pub(crate) owned_partitions: Vec<TopicPartition>,
67 // Java's `generationId`. Starts as `DEFAULT_GENERATION`, as in
68 // `Subscription(List)`.
69 pub(crate) generation_id: i32,
70 // Java's `rackId`. Starts as `None`, as `Subscription(List)`'s
71 // `Optional.empty()`.
72 pub(crate) rack_id: Option<String>,
73}
74
75/// Fluent builder for [`SubscriptionOptions`]: every parameter has a setter,
76/// and [`Self::build`] checks that the mandatory ones were set.
77#[derive(Debug)]
78// builds SubscriptionOptions (CLAUDE.md §2)
79#[doc(alias = "rust-only")]
80pub struct SubscriptionOptionsBuilder {
81 topics: Option<Vec<String>>,
82 user_data: Option<Vec<u8>>,
83 owned_partitions: Vec<TopicPartition>,
84 generation_id: i32,
85 rack_id: Option<String>,
86}
87
88impl Default for SubscriptionOptionsBuilder {
89 fn default() -> Self {
90 Self::new()
91 }
92}
93
94impl SubscriptionOptionsBuilder {
95 /// Creates a builder with every mandatory parameter unset and every other
96 /// parameter at the value Java passes on the caller's behalf.
97 ///
98 /// # Returns
99 ///
100 /// The new builder.
101 pub fn new() -> Self {
102 Self {
103 topics: None,
104 user_data: None,
105 owned_partitions: Vec::new(),
106 generation_id: DEFAULT_GENERATION,
107 rack_id: None,
108 }
109 }
110
111 /// Sets `SubscriptionOptions::topics`, a mandatory parameter: [`Self::build`]
112 /// returns an error if it was not set.
113 ///
114 /// # Arguments
115 ///
116 /// - `topics` - The list of topics to subscribe to
117 ///
118 /// # Returns
119 ///
120 /// This builder.
121 pub fn set_topics(mut self, topics: Vec<String>) -> Self {
122 self.topics = Some(topics);
123 self
124 }
125 /// Sets `SubscriptionOptions::user_data`.
126 ///
127 /// # Arguments
128 ///
129 /// - `user_data` - Nullable user data to include in the subscription
130 ///
131 /// # Returns
132 ///
133 /// This builder.
134 pub fn set_user_data(mut self, user_data: Option<Vec<u8>>) -> Self {
135 self.user_data = user_data;
136 self
137 }
138 /// Sets `SubscriptionOptions::owned_partitions`.
139 ///
140 /// # Arguments
141 ///
142 /// - `owned_partitions` - The partitions currently owned by this consumer
143 ///
144 /// # Returns
145 ///
146 /// This builder.
147 pub fn set_owned_partitions(mut self, owned_partitions: Vec<TopicPartition>) -> Self {
148 self.owned_partitions = owned_partitions;
149 self
150 }
151 /// Sets `SubscriptionOptions::generation_id`.
152 ///
153 /// # Arguments
154 ///
155 /// - `generation_id` - The generation ID of the consumer group
156 ///
157 /// # Returns
158 ///
159 /// This builder.
160 pub fn set_generation_id(mut self, generation_id: i32) -> Self {
161 self.generation_id = generation_id;
162 self
163 }
164 /// Sets `SubscriptionOptions::rack_id`.
165 ///
166 /// # Arguments
167 ///
168 /// - `rack_id` - Optional rack ID for rack-aware assignment
169 ///
170 /// # Returns
171 ///
172 /// This builder.
173 pub fn set_rack_id(mut self, rack_id: Option<String>) -> Self {
174 self.rack_id = rack_id;
175 self
176 }
177
178 /// Returns the built options.
179 ///
180 /// # Errors
181 ///
182 /// - `Error::is_local_illegal_argument_error` naming the first mandatory
183 /// parameter (today only `topics`) that was not set.
184 // The mandatory parameters are validated here rather than being named in
185 // the constructor, so a later Java version that makes one of them optional
186 // changes the set this accepts instead of adding a second constructor.
187 // Only presence is checked here; semantic validation belongs to the method
188 // the options are passed to.
189 pub fn build(self) -> Result<SubscriptionOptions, Error> {
190 Ok(SubscriptionOptions {
191 topics: self.topics.ok_or_else(|| Self::missing("topics"))?,
192 user_data: self.user_data,
193 owned_partitions: self.owned_partitions,
194 generation_id: self.generation_id,
195 rack_id: self.rack_id,
196 })
197 }
198
199 /// Builds the error naming a mandatory parameter [`Self::build`] found
200 /// unset.
201 fn missing(parameter: &str) -> Error {
202 Error::local_illegal_argument(format!(
203 "SubscriptionOptionsBuilder::build: mandatory parameter `{parameter}` was not set"
204 ))
205 }
206}
207
208/// Represents a consumer's subscription information including topics, user
209/// data, and owned partitions.
210#[derive(Clone, Debug)]
211#[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Subscription")]
212pub struct Subscription {
213 topics: Vec<String>,
214 user_data: Option<Vec<u8>>,
215 owned_partitions: Vec<TopicPartition>,
216 group_instance_id: Option<String>,
217 generation_id: Option<i32>,
218 rack_id: Option<String>,
219}
220
221impl Subscription {
222 // Java's four `Subscription` constructors intersect on `{topics}`, and
223 // `Subscription(List topics)` is exactly that, so it keeps the plain name
224 // `new` and the others carry their Rust parameters beyond it (CLAUDE.md
225 // §2). Only the five-parameter one would need more than three parameters
226 // in its name, so it alone takes the `Options` shape, where the struct is
227 // the method's only parameter.
228
229 /// Constructs a basic subscription with only topics.
230 ///
231 /// # Arguments
232 ///
233 /// - `topics` - The list of topics to subscribe to
234 ///
235 /// # Returns
236 ///
237 /// The new `Subscription`.
238 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Subscription#Subscription")]
239 pub fn new(topics: Vec<String>) -> Self {
240 Self::with_options(
241 SubscriptionOptionsBuilder::new()
242 .set_topics(topics)
243 .build()
244 .expect("SubscriptionOptionsBuilder::build: every mandatory parameter is set above"),
245 )
246 }
247
248 /// Constructs a subscription without owned partitions.
249 ///
250 /// # Arguments
251 ///
252 /// - `topics` - The list of topics to subscribe to
253 /// - `user_data` - Nullable user data to include in the subscription
254 ///
255 /// # Returns
256 ///
257 /// The new `Subscription`.
258 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Subscription#Subscription")]
259 pub fn with_user_data(topics: Vec<String>, user_data: Option<Vec<u8>>) -> Self {
260 Self::with_options(
261 SubscriptionOptionsBuilder::new()
262 .set_topics(topics)
263 .set_user_data(user_data)
264 .build()
265 .expect("SubscriptionOptionsBuilder::build: every mandatory parameter is set above"),
266 )
267 }
268
269 /// Constructs a subscription without generation ID and rack ID.
270 ///
271 /// # Arguments
272 ///
273 /// - `topics` - The list of topics to subscribe to
274 /// - `user_data` - Nullable user data to include in the subscription
275 /// - `owned_partitions` - The partitions currently owned by this consumer
276 ///
277 /// # Returns
278 ///
279 /// The new `Subscription`.
280 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Subscription#Subscription")]
281 pub fn with_user_data_owned_partitions(
282 topics: Vec<String>,
283 user_data: Option<Vec<u8>>,
284 owned_partitions: Vec<TopicPartition>,
285 ) -> Self {
286 Self::with_options(
287 SubscriptionOptionsBuilder::new()
288 .set_topics(topics)
289 .set_user_data(user_data)
290 .set_owned_partitions(owned_partitions)
291 .build()
292 .expect("SubscriptionOptionsBuilder::build: every mandatory parameter is set above"),
293 )
294 }
295
296 /// Constructs a subscription with full details.
297 ///
298 /// # Arguments
299 ///
300 /// - `options` - The topics, user data, owned partitions, generation ID and
301 /// rack ID
302 ///
303 /// # Returns
304 ///
305 /// The new `Subscription`.
306 // A `generation_id` less than zero is mapped to `None`, matching Java's
307 // `generationId < 0 ? Optional.empty() : Optional.of(generationId)`.
308 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Subscription#Subscription")]
309 pub fn with_options(options: SubscriptionOptions) -> Self {
310 let SubscriptionOptions { topics, user_data, owned_partitions, generation_id, rack_id } = options;
311 Self {
312 topics,
313 user_data,
314 owned_partitions,
315 group_instance_id: None,
316 generation_id: if generation_id < 0 { None } else { Some(generation_id) },
317 rack_id,
318 }
319 }
320
321 /// The subscribed topics.
322 ///
323 /// # Returns
324 ///
325 /// The list of topics
326 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Subscription#topics")]
327 pub fn topics(&self) -> &[String] {
328 &self.topics
329 }
330
331 /// The opaque user data attached to the subscription.
332 ///
333 /// # Returns
334 ///
335 /// The user data, or None if none was provided
336 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Subscription#userData")]
337 pub fn user_data(&self) -> Option<&[u8]> {
338 self.user_data.as_deref()
339 }
340
341 /// The partitions currently owned by the member.
342 ///
343 /// # Returns
344 ///
345 /// The list of owned partitions
346 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Subscription#ownedPartitions")]
347 pub fn owned_partitions(&self) -> &[TopicPartition] {
348 &self.owned_partitions
349 }
350
351 /// The rack id of the member, if any.
352 ///
353 /// # Returns
354 ///
355 /// The rack ID, or empty if not provided
356 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Subscription#rackId")]
357 pub fn rack_id(&self) -> Option<&str> {
358 self.rack_id.as_deref()
359 }
360
361 /// Sets the group instance id.
362 ///
363 /// # Arguments
364 ///
365 /// - `group_instance_id` - The group instance ID
366 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Subscription#setGroupInstanceId")]
367 pub fn set_group_instance_id(&mut self, group_instance_id: Option<String>) {
368 self.group_instance_id = group_instance_id;
369 }
370
371 /// The group instance id of the member, if any.
372 ///
373 /// # Returns
374 ///
375 /// The group instance ID, or empty if this is a dynamic member
376 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Subscription#groupInstanceId")]
377 pub fn group_instance_id(&self) -> Option<&str> {
378 self.group_instance_id.as_deref()
379 }
380
381 /// The generation id of the subscription, if any.
382 ///
383 /// # Returns
384 ///
385 /// The generation ID, or empty if not provided
386 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Subscription#generationId")]
387 pub fn generation_id(&self) -> Option<i32> {
388 self.generation_id
389 }
390}
391
392/// Represents the partition assignment for a consumer.
393#[derive(Clone, Debug)]
394#[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Assignment")]
395pub struct Assignment {
396 partitions: Vec<TopicPartition>,
397 user_data: Option<Vec<u8>>,
398}
399
400impl Assignment {
401 // Java's two `Assignment` constructors intersect on `{partitions}`, and
402 // `Assignment(List partitions)` is exactly that, so it keeps the plain
403 // name `new` (CLAUDE.md §2).
404
405 /// Constructs an assignment with only partitions.
406 ///
407 /// # Arguments
408 ///
409 /// - `partitions` - The list of partitions assigned to the consumer
410 ///
411 /// # Returns
412 ///
413 /// The new `Assignment`.
414 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Assignment#Assignment")]
415 pub fn new(partitions: Vec<TopicPartition>) -> Self {
416 Self::with_user_data(partitions, None)
417 }
418
419 /// Constructs an assignment with partitions and user data.
420 ///
421 /// # Arguments
422 ///
423 /// - `partitions` - The list of partitions assigned to the consumer
424 /// - `user_data` - Nullable user data to include in the assignment
425 ///
426 /// # Returns
427 ///
428 /// The new `Assignment`.
429 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Assignment#Assignment")]
430 pub fn with_user_data(partitions: Vec<TopicPartition>, user_data: Option<Vec<u8>>) -> Self {
431 Self { partitions, user_data }
432 }
433
434 /// The assigned partitions.
435 ///
436 /// # Returns
437 ///
438 /// The list of partitions
439 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Assignment#partitions")]
440 pub fn partitions(&self) -> &[TopicPartition] {
441 &self.partitions
442 }
443
444 /// The opaque user data attached to the assignment.
445 ///
446 /// # Returns
447 ///
448 /// The user data, or None if none was provided
449 #[doc(alias = "org.apache.kafka.clients.consumer.ConsumerPartitionAssignor$Assignment#userData")]
450 pub fn user_data(&self) -> Option<&[u8]> {
451 self.user_data.as_deref()
452 }
453}
454
455/// Java's `List.toString()`: `[a, b]`.
456fn java_list<T: std::fmt::Display>(items: &[T]) -> String {
457 format!("[{}]", items.iter().map(ToString::to_string).collect::<Vec<_>>().join(", "))
458}
459
460impl std::fmt::Display for Subscription {
461 // Java's `toString()`: the user data prints as its size and only when
462 // present, an absent group instance or rack id as `null`, an absent
463 // generation as `-1`.
464 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
465 write!(f, "Subscription(topics={}", java_list(&self.topics))?;
466 if let Some(user_data) = &self.user_data {
467 write!(f, ", userDataSize={}", user_data.len())?;
468 }
469 write!(
470 f,
471 ", ownedPartitions={}, groupInstanceId={}, generationId={}, rackId={})",
472 java_list(&self.owned_partitions),
473 self.group_instance_id.as_deref().unwrap_or("null"),
474 self.generation_id.unwrap_or(-1),
475 self.rack_id.as_deref().unwrap_or("null")
476 )
477 }
478}
479
480impl std::fmt::Display for Assignment {
481 // Java's `toString()`: the user data prints as its size and only when
482 // present.
483 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
484 write!(f, "Assignment(partitions={}", java_list(&self.partitions))?;
485 if let Some(user_data) = &self.user_data {
486 write!(f, ", userDataSize={}", user_data.len())?;
487 }
488 f.write_str(")")
489 }
490}
491
492#[cfg(test)]
493mod tests {
494 use super::*;
495
496 #[test]
497 fn to_string_follows_java() {
498 let tp = |p| TopicPartition::new("t", p);
499 assert_eq!(
500 Subscription::new(vec!["a".to_string(), "b".to_string()]).to_string(),
501 "Subscription(topics=[a, b], ownedPartitions=[], groupInstanceId=null, generationId=-1, rackId=null)"
502 );
503 let mut s = Subscription::with_options(
504 SubscriptionOptionsBuilder::new()
505 .set_topics(vec!["t".to_string()])
506 .set_user_data(Some(vec![1, 2, 3]))
507 .set_owned_partitions(vec![tp(0), tp(1)])
508 .set_generation_id(5)
509 .set_rack_id(Some("r".to_string()))
510 .build()
511 .unwrap(),
512 );
513 s.set_group_instance_id(Some("i".to_string()));
514 assert_eq!(
515 s.to_string(),
516 "Subscription(topics=[t], userDataSize=3, ownedPartitions=[t-0, t-1], groupInstanceId=i, generationId=5, \
517 rackId=r)"
518 );
519 assert_eq!(Assignment::new(vec![tp(0)]).to_string(), "Assignment(partitions=[t-0])");
520 assert_eq!(
521 Assignment::with_user_data(Vec::new(), Some(Vec::new())).to_string(),
522 "Assignment(partitions=[], userDataSize=0)"
523 );
524 }
525
526 #[test]
527 fn subscription_negative_generation_is_none() {
528 let s = Subscription::with_options(
529 SubscriptionOptionsBuilder::new()
530 .set_topics(vec!["t".to_string()])
531 .set_generation_id(-1)
532 .build()
533 .unwrap(),
534 );
535 assert_eq!(s.generation_id(), None);
536 }
537
538 #[test]
539 fn subscription_non_negative_generation_is_some() {
540 let s = Subscription::with_options(
541 SubscriptionOptionsBuilder::new()
542 .set_topics(vec!["t".to_string()])
543 .set_generation_id(5)
544 .set_rack_id(Some("r".to_string()))
545 .build()
546 .unwrap(),
547 );
548 assert_eq!(s.generation_id(), Some(5));
549 assert_eq!(s.rack_id(), Some("r"));
550 }
551
552 #[test]
553 fn subscription_defaults() {
554 let s = Subscription::new(vec!["a".to_string(), "b".to_string()]);
555 assert_eq!(s.topics(), &["a".to_string(), "b".to_string()]);
556 assert!(s.user_data().is_none());
557 assert!(s.owned_partitions().is_empty());
558 assert_eq!(s.generation_id(), None);
559 }
560
561 #[test]
562 fn assignment_accessors() {
563 let a = Assignment::new(vec![TopicPartition::new("t", 0)]);
564 assert_eq!(a.partitions().len(), 1);
565 assert!(a.user_data().is_none());
566 }
567
568 /// CLAUDE.md §2: the mandatory parameters are validated in
569 /// [`SubscriptionOptionsBuilder::build`], not named in the constructor, so a
570 /// builder left untouched panics naming the first one it finds unset.
571 #[test]
572 fn subscription_options_builder_build_errors_when_no_mandatory_parameter_is_set() {
573 let Err(error) = SubscriptionOptionsBuilder::new().build() else {
574 panic!("build must reject the unset mandatory parameter");
575 };
576 assert!(matches!(error, Error::LocalIllegalArgument(_)), "{error:?}");
577 assert_eq!(
578 error.message(),
579 "SubscriptionOptionsBuilder::build: mandatory parameter `topics` was not set"
580 );
581 }
582}