confluent_kafka/consumer/offset_commit_callback.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//! Callback interface notified when an async offset commit completes.
16//!
17//! Translated from `org.apache.kafka.clients.consumer.OffsetCommitCallback`.
18
19use std::collections::HashMap;
20
21use async_trait::async_trait;
22
23use crate::common::{Error, TopicPartition};
24use crate::consumer::OffsetAndMetadata;
25
26/// A callback interface that the user can implement to trigger custom actions
27/// when a commit request completes. The callback may be executed in any thread
28/// calling poll().
29///
30/// # Translation notes
31///
32/// It runs on the task inside `poll()`, `commit_*()` or `close()`.
33// Per `consumer-threading.md` §31, the callback executes on the caller's task
34// that is currently inside `poll()` / `commit_*()` / `close()`, never on the
35// background task.
36//
37// Bounds `Send + Sync + 'static`: the callback travels through events on the
38// background task and is invoked on the app task after the background task has
39// already moved on, so it is stored as `Arc<dyn>`.
40#[async_trait]
41#[doc(alias = "org.apache.kafka.clients.consumer.OffsetCommitCallback")]
42pub trait OffsetCommitCallback: Send + Sync + 'static {
43 /// A callback method the user can implement to provide asynchronous
44 /// handling of commit request completion. This method will be called
45 /// when the commit request sent to the server has been acknowledged.
46 ///
47 /// # Arguments
48 ///
49 /// - `offsets` - A map of the offsets and associated metadata that this
50 /// callback applies to
51 /// - `error` - The error raised during processing of the request, or
52 /// `None` if the commit completed successfully
53 ///
54 /// # Errors
55 ///
56 /// - `Error::is_consumer_commit_failed_error` if the commit failed and cannot be retried. This
57 /// can only occur if you are using automatic group management with
58 /// `KafkaConsumer::subscribe`, or if there is an active group with the same groupId which is
59 /// using group management.
60 /// - `Error::is_rebalance_in_progress_error` if the commit failed because it is in the middle
61 /// of a rebalance. In such cases commit could be retried after the rebalance is completed
62 /// with the `KafkaConsumer::poll` call.
63 /// - `Error::is_wakeup_error` if `KafkaConsumer::wakeup` is called before or while this
64 /// function is called
65 /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
66 /// function is called
67 /// - `Error::is_authorization_error` if not authorized to the topic or to the configured
68 /// groupId. See the error for more details
69 /// - `Error::is_kafka_error` for any other unrecoverable errors (e.g. if offset metadata is too
70 /// large or if the committed offset is invalid).
71 ///
72 /// # Translation notes
73 ///
74 /// The errors above are those `error` may carry. An `Err` returned here
75 /// propagates out of the call that ran the callback, as Java's thrown
76 /// exception does.
77 // Java's `onComplete` is `void` but may throw: an exception it throws is
78 // not caught (`OffsetCommitCallbackInvoker.executeCallbacks`) and
79 // propagates out of the call that ran the callback (`poll`, `commit_sync`,
80 // `commit_async`, `close`; `poll` wraps it as
81 // `ConsumerUtils.maybeWrapAsKafkaException` does). Callbacks queued behind
82 // this one stay queued for the next call that runs them. The commit itself
83 // has already completed.
84 #[doc(alias = "org.apache.kafka.clients.consumer.OffsetCommitCallback#onComplete")]
85 async fn on_complete(
86 &self,
87 offsets: &HashMap<TopicPartition, OffsetAndMetadata>,
88 error: Option<&Error>,
89 ) -> Result<(), Error>;
90}
91
92/// Returns an [`OffsetCommitCallback`] that calls `function`, standing in for
93/// a Java lambda implementing `OffsetCommitCallback`: `function` is
94/// [`on_complete`](OffsetCommitCallback::on_complete), run synchronously as
95/// Java's `onComplete` is. A method Java adds later as an overload of
96/// `onComplete` gets its own factory, `with_<parameter>`.
97///
98/// ```
99/// use std::sync::Arc;
100///
101/// use confluent_kafka::consumer::{offset_commit_callback, OffsetCommitCallback};
102///
103/// let callback: Arc<dyn OffsetCommitCallback> = Arc::new(offset_commit_callback::new(|offsets, error| {
104/// match error {
105/// Some(error) => eprintln!("commit of {} partitions failed: {error}", offsets.len()),
106/// None => println!("committed {} partitions", offsets.len()),
107/// }
108/// Ok(())
109/// }));
110/// ```
111///
112/// # Arguments
113///
114/// - `function` - the body of [`on_complete`](OffsetCommitCallback::on_complete),
115/// called with the committed offsets and the commit's error.
116// stands in for a Java lambda implementing `OffsetCommitCallback` (CLAUDE.md §3)
117#[doc(alias = "rust-only")]
118pub fn new<F>(function: F) -> impl OffsetCommitCallback
119where
120 F: Fn(&HashMap<TopicPartition, OffsetAndMetadata>, Option<&Error>) -> Result<(), Error> + Send + Sync + 'static,
121{
122 struct FunctionOffsetCommitCallback<F>(F);
123
124 #[async_trait]
125 impl<F> OffsetCommitCallback for FunctionOffsetCommitCallback<F>
126 where
127 F: Fn(&HashMap<TopicPartition, OffsetAndMetadata>, Option<&Error>) -> Result<(), Error> + Send + Sync + 'static,
128 {
129 async fn on_complete(
130 &self,
131 offsets: &HashMap<TopicPartition, OffsetAndMetadata>,
132 error: Option<&Error>,
133 ) -> Result<(), Error> {
134 (self.0)(offsets, error)
135 }
136 }
137
138 FunctionOffsetCommitCallback(function)
139}
140
141#[cfg(test)]
142mod tests {
143 use std::sync::{Arc, Mutex};
144
145 use super::*;
146
147 #[tokio::test]
148 async fn new_calls_the_function_with_the_offsets_and_error() {
149 let seen = Arc::new(Mutex::new(None));
150 let sink = Arc::clone(&seen);
151 let callback: Arc<dyn OffsetCommitCallback> = Arc::new(new(move |offsets, error| {
152 *sink.lock().unwrap() = Some((offsets.len(), error.is_some()));
153 Ok(())
154 }));
155 let offsets = HashMap::from([(TopicPartition::new("t", 0), OffsetAndMetadata::new(5).unwrap())]);
156 callback.on_complete(&offsets, None).await.unwrap();
157 assert_eq!(*seen.lock().unwrap(), Some((1, false)));
158 }
159
160 #[tokio::test]
161 async fn new_returns_the_function_error() {
162 let callback = new(|_offsets, _error| Err(Error::local_illegal_state("from callback")));
163 let result = callback
164 .on_complete(&HashMap::new(), Some(&Error::local_illegal_state("commit failed")))
165 .await;
166 assert!(result.unwrap_err().to_string().contains("from callback"));
167 }
168}