Skip to main content

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}