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}