Skip to main content

confluent_kafka/consumer/
close_options.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//! Options for closing a consumer.
16//!
17//! Translated from `org.apache.kafka.clients.consumer.CloseOptions`.
18
19use std::time::Duration;
20
21/// Enum to specify the group membership operation upon leaving a group.
22#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
23#[non_exhaustive]
24#[doc(alias = "org.apache.kafka.clients.consumer.CloseOptions$GroupMembershipOperation")]
25pub enum GroupMembershipOperation {
26    /// The consumer will leave the group. This is the default for dynamic
27    /// members, and can be used by static members when they want to
28    /// permanently leave the group and trigger a rebalance.
29    LeaveGroup,
30    /// The consumer will remain in the group. This is the default for static
31    /// members, allowing them to rejoin quickly without triggering a
32    /// rebalance. When used by dynamic members, no leave heartbeat will be
33    /// sent and the member will be removed by the coordinator after the
34    /// session timeout expires.
35    RemainInGroup,
36    /// Applies the default behavior:
37    /// - For **static members**: The consumer will remain in the group.
38    /// - For **dynamic members**: The consumer will leave the group.
39    Default,
40}
41
42/// Java's inherited `Enum.toString()`: the constant's name.
43impl std::fmt::Display for GroupMembershipOperation {
44    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
45        f.write_str(match self {
46            Self::LeaveGroup => "LEAVE_GROUP",
47            Self::RemainInGroup => "REMAIN_IN_GROUP",
48            Self::Default => "DEFAULT",
49        })
50    }
51}
52
53/// Options for controlling the consumer close behavior.
54///
55/// This class allows customization of the close timeout and group membership
56/// operation when a consumer is being shut down.
57#[derive(Clone, Debug)]
58#[doc(alias = "org.apache.kafka.clients.consumer.CloseOptions")]
59pub struct CloseOptions {
60    operation: GroupMembershipOperation,
61    timeout: Option<Duration>,
62}
63
64impl CloseOptions {
65    /// Create a new `CloseOptions` with default values (Java's private
66    /// no-arg constructor).
67    fn empty() -> Self {
68        Self { operation: GroupMembershipOperation::Default, timeout: None }
69    }
70
71    /// Static method to create a `CloseOptions` with a custom timeout.
72    ///
73    /// # Arguments
74    ///
75    /// - `timeout` - The maximum time to wait for the consumer to close.
76    ///
77    /// # Returns
78    ///
79    /// A new `CloseOptions` instance with the specified timeout.
80    ///
81    /// # Translation notes
82    ///
83    /// `timeout` cannot be `None`: for the default timeout use
84    /// [`CloseOptions::default`].
85    #[doc(alias = "org.apache.kafka.clients.consumer.CloseOptions#timeout")]
86    pub fn new_with_timeout(timeout: Duration) -> Self {
87        Self::empty().with_timeout(timeout)
88    }
89
90    /// Static method to create a `CloseOptions` with a specified group
91    /// membership operation.
92    ///
93    /// # Arguments
94    ///
95    /// - `operation` - The group membership operation to apply. Must be one of `LEAVE_GROUP`,
96    ///   `REMAIN_IN_GROUP`, or `DEFAULT`.
97    ///
98    /// # Returns
99    ///
100    /// A new `CloseOptions` instance with the specified group membership operation.
101    #[doc(alias = "org.apache.kafka.clients.consumer.CloseOptions#groupMembershipOperation")]
102    pub fn with_operation(operation: GroupMembershipOperation) -> Self {
103        Self::empty().with_group_membership_operation(operation)
104    }
105
106    /// Fluent method to set the timeout for the close process.
107    ///
108    /// # Arguments
109    ///
110    /// - `timeout` - The maximum time to wait for the consumer to close.
111    ///
112    /// # Returns
113    ///
114    /// This `CloseOptions` instance.
115    ///
116    /// # Translation notes
117    ///
118    /// `timeout` cannot be `None`: to keep the default timeout, do not call
119    /// this method.
120    #[doc(alias = "org.apache.kafka.clients.consumer.CloseOptions#withTimeout")]
121    pub fn with_timeout(mut self, timeout: Duration) -> Self {
122        self.timeout = Some(timeout);
123        self
124    }
125
126    /// Fluent method to set the group membership operation upon shutdown.
127    ///
128    /// # Arguments
129    ///
130    /// - `operation` - The group membership operation to apply. Must be one of `LEAVE_GROUP`,
131    ///   `REMAIN_IN_GROUP`, or `DEFAULT`.
132    ///
133    /// # Returns
134    ///
135    /// This `CloseOptions` instance.
136    #[doc(alias = "org.apache.kafka.clients.consumer.CloseOptions#withGroupMembershipOperation")]
137    pub fn with_group_membership_operation(mut self, operation: GroupMembershipOperation) -> Self {
138        self.operation = operation;
139        self
140    }
141
142    /// Returns the group membership operation configured for this close.
143    ///
144    /// # Returns
145    ///
146    /// The group membership operation
147    #[doc(alias = "org.apache.kafka.clients.consumer.CloseOptions#groupMembershipOperation")]
148    pub fn group_membership_operation(&self) -> GroupMembershipOperation {
149        self.operation
150    }
151
152    /// Returns the timeout configured for this close.
153    ///
154    /// # Returns
155    ///
156    /// The timeout, or `None` if using the default timeout
157    #[doc(alias = "org.apache.kafka.clients.consumer.CloseOptions#timeout")]
158    pub fn timeout(&self) -> Option<Duration> {
159        self.timeout
160    }
161}
162
163impl Default for CloseOptions {
164    fn default() -> Self {
165        Self::empty()
166    }
167}
168
169#[cfg(test)]
170mod tests {
171    use super::*;
172
173    #[test]
174    fn test_default_values() {
175        let opts = CloseOptions::default();
176        assert_eq!(opts.group_membership_operation(), GroupMembershipOperation::Default);
177        assert_eq!(opts.timeout(), None);
178    }
179
180    #[test]
181    fn test_timeout_constructor() {
182        let opts = CloseOptions::new_with_timeout(Duration::from_secs(1));
183        assert_eq!(opts.timeout(), Some(Duration::from_secs(1)));
184        assert_eq!(opts.group_membership_operation(), GroupMembershipOperation::Default);
185    }
186
187    #[test]
188    fn test_group_membership_operation_constructor() {
189        let opts = CloseOptions::with_operation(GroupMembershipOperation::LeaveGroup);
190        assert_eq!(opts.group_membership_operation(), GroupMembershipOperation::LeaveGroup);
191        assert_eq!(opts.timeout(), None);
192    }
193}