Skip to main content

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}