Skip to main content

confluent_kafka/common/
kafka_future.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//! A flexible future for asynchronous Kafka operations.
16//!
17//! Translated from `org.apache.kafka.common.KafkaFuture`.
18//!
19//! In Java, `KafkaFuture<T>` is an abstract class implementing `Future<T>`.
20//! In the Producer API, Java's `Producer.send()` returns `Future<RecordMetadata>`,
21//! hiding the internal `FutureRecordMetadata` behind the `Future` interface.
22//!
23//! In Rust, `KafkaFuture<T>` serves as the concrete return type that hides
24//! internal implementations behind a public, type-erased interface.
25//!
26//! [`KafkaFuture::then_apply`] takes a [`BaseFunction`]: a closure, or a value
27//! from [`BaseFunction_new`]. Rust infers a closure's parameter type only from
28//! an `Fn` bound, not from a trait the closure gets through a blanket impl,
29//! so a closure whose body calls a method on its argument writes the
30//! argument's type out (`|v: T| ..`). A function held as a trait object
31//! (`Box<dyn BaseFunction<T, R>>`, `Arc<..>`) is not itself a
32//! `BaseFunction`; it is passed as `move |v| f.apply(v)`:
33//!
34//! ```
35//! use confluent_kafka::common::KafkaFuture;
36//! use confluent_kafka::common::kafka_future::{self, BaseFunction};
37//!
38//! # #[tokio::main(flavor = "current_thread")]
39//! # async fn main() {
40//! let future = KafkaFuture::completed_future(Ok("four".to_string()));
41//!
42//! // The body calls `len()` on `v`, so its type is written out.
43//! let len = future.then_apply(|v: String| Ok(v.len()));
44//! assert_eq!(len.get().await.unwrap(), 4);
45//!
46//! // A stored function is forwarded to through a closure.
47//! let f: Box<dyn BaseFunction<String, usize>> = Box::new(kafka_future::BaseFunction_new(|v: String| Ok(v.len())));
48//! let len = future.then_apply(move |v| f.apply(v));
49//! assert_eq!(len.get().await.unwrap(), 4);
50//! # }
51//! ```
52
53use std::collections::HashMap;
54use std::hash::Hash;
55use std::panic::AssertUnwindSafe;
56use std::pin::Pin;
57use std::sync::{Arc, Mutex, PoisonError};
58use std::time::Duration;
59
60use futures_util::FutureExt;
61
62use crate::common::Error;
63use crate::common::internals::KafkaFutureImpl;
64
65/// A function which takes objects of type `A` and returns objects of type `B`.
66///
67/// # Translation notes
68///
69/// Any closure `Fn(A) -> Result<B, Error> + Send + Sync` implements it.
70#[doc(alias = "org.apache.kafka.common.KafkaFuture$BaseFunction")]
71pub trait BaseFunction<A, B>: Send + Sync {
72    /// Applies this function to `a`.
73    ///
74    /// # Arguments
75    ///
76    /// - `a` - the value to transform
77    ///
78    /// # Returns
79    ///
80    /// The transformed value.
81    ///
82    /// # Errors
83    ///
84    /// Any error the function returns; it fails the future `then_apply`
85    /// returned, as a throwing Java `apply` does.
86    #[doc(alias = "org.apache.kafka.common.KafkaFuture$BaseFunction#apply")]
87    fn apply(&self, a: A) -> Result<B, Error>;
88}
89
90impl<A, B, F> BaseFunction<A, B> for F
91where
92    F: Fn(A) -> Result<B, Error> + Send + Sync,
93{
94    fn apply(&self, a: A) -> Result<B, Error> {
95        self(a)
96    }
97}
98
99/// A [`BaseFunction`] that calls `function`, standing in for a Java lambda
100/// implementing `KafkaFuture.BaseFunction`. A method Java adds later as an
101/// overload of `apply` gets its own factory, `BaseFunction_with_<parameter>`.
102///
103/// `BaseFunction` is nested in `KafkaFuture`, so its factory lives in this
104/// module with the interface's name as a prefix. `A` is a
105/// parameter of this function, not of the caller's, so the closure's
106/// parameter type must be written out:
107///
108/// ```
109/// use confluent_kafka::common::kafka_future::{self, BaseFunction};
110///
111/// let len = kafka_future::BaseFunction_new(|s: String| Ok(s.len()));
112/// assert_eq!(len.apply("four".to_string()).unwrap(), 4);
113/// ```
114///
115/// # Arguments
116///
117/// - `function` - the body of [`apply`](BaseFunction::apply)
118///
119/// # Returns
120///
121/// A `BaseFunction` whose `apply` calls `function`.
122// stands in for a Java lambda implementing `KafkaFuture.BaseFunction` (CLAUDE.md §3)
123#[doc(alias = "rust-only")]
124#[expect(non_snake_case)]
125pub fn BaseFunction_new<A, B, F>(function: F) -> impl BaseFunction<A, B>
126where
127    F: Fn(A) -> Result<B, Error> + Send + Sync,
128{
129    struct FunctionBaseFunction<F>(F);
130
131    impl<A, B, F> BaseFunction<A, B> for FunctionBaseFunction<F>
132    where
133        F: Fn(A) -> Result<B, Error> + Send + Sync,
134    {
135        fn apply(&self, a: A) -> Result<B, Error> {
136            (self.0)(a)
137        }
138    }
139
140    FunctionBaseFunction(function)
141}
142
143/// Internal trait representing the abstract methods of `KafkaFuture`.
144///
145/// This is the Rust equivalent of the abstract method set in Java's `KafkaFuture<T>`.
146/// Different internal types (e.g., `FutureRecordMetadata` for the producer)
147/// implement this trait and are wrapped in a `KafkaFuture<T>`.
148pub(crate) trait KafkaFutureOps<T: Send>: Send + Sync {
149    /// Await the result of this future.
150    fn get(&self) -> Pin<Box<dyn std::future::Future<Output = Result<T, Error>> + Send + '_>>;
151
152    /// Await the result of this future with a timeout.
153    fn get_with_timeout(
154        &self,
155        timeout: Duration,
156    ) -> Pin<Box<dyn std::future::Future<Output = Result<T, Error>> + Send + '_>>;
157
158    /// Whether this future is complete.
159    fn is_done(&self) -> bool;
160
161    /// Registers `callback` to run once with this future's result: on the
162    /// code path that completes the future, after the result is stored, or at
163    /// once on the calling task when the future is already complete. This is
164    /// the hook behind the dependants of a future (`then_apply`, `all_of`),
165    /// which Java's `CompletableFuture` completes the same way.
166    fn on_complete(self: Arc<Self>, callback: CompletionCallback<T>);
167}
168
169/// A callback registered with [`KafkaFutureOps::on_complete`], invoked with a
170/// reference to the future's result when it completes.
171pub(crate) type CompletionCallback<T> = Box<dyn FnOnce(&Result<T, Error>) + Send>;
172
173/// A flexible future which supports call chaining and other asynchronous
174/// programming patterns.
175///
176/// # Translation notes
177///
178/// Java's `get()`, `get(timeout, unit)` and `isDone()` come from `Future<T>`;
179/// here `get` and `get_with_timeout` are async. This type is also what
180/// `Producer::send` returns, where Java returns `Future<RecordMetadata>`.
181/// `toCompletionStage` is not translated.
182#[doc(alias = "org.apache.kafka.common.KafkaFuture")]
183pub struct KafkaFuture<T: Send + 'static> {
184    inner: Arc<dyn KafkaFutureOps<T>>,
185}
186
187impl<T: Send + 'static> KafkaFuture<T> {
188    /// Create a new `KafkaFuture` wrapping an internal implementation.
189    pub(crate) fn new(inner: Arc<dyn KafkaFutureOps<T>>) -> Self {
190        Self { inner }
191    }
192
193    /// Returns a new `KafkaFuture` that is already completed with the given value.
194    ///
195    /// # Arguments
196    ///
197    /// - `result` - the value, or the error the future fails with
198    ///
199    /// # Translation notes
200    ///
201    /// `result` may also be an error.
202    #[doc(alias = "org.apache.kafka.common.KafkaFuture#completedFuture")]
203    pub fn completed_future(result: Result<T, Error>) -> Self
204    where
205        T: Clone + Sync,
206    {
207        Self { inner: Arc::new(CompletedFuture { result }) }
208    }
209
210    /// Waits if necessary for this future to complete, and then returns its result.
211    ///
212    /// # Returns
213    ///
214    /// The future's value.
215    ///
216    /// # Errors
217    ///
218    /// The error the underlying operation failed with.
219    #[doc(alias = "org.apache.kafka.common.KafkaFuture#get")]
220    pub fn get(&self) -> impl Future<Output = Result<T, Error>> + Send {
221        async move { self.inner.get().await }
222    }
223
224    /// Waits if necessary for at most the given time for this future to
225    /// complete, and then returns its result, if available.
226    ///
227    /// # Arguments
228    ///
229    /// - `timeout` - the maximum time to wait
230    ///
231    /// # Returns
232    ///
233    /// The future's value.
234    ///
235    /// # Errors
236    ///
237    /// - [`Error::is_local_timeout_error`] if the wait timed out: Java's
238    ///   `java.util.concurrent.TimeoutException`, not the retriable
239    ///   `org.apache.kafka.common.errors.TimeoutException`.
240    /// - The error the underlying operation failed with.
241    #[doc(alias = "org.apache.kafka.common.KafkaFuture#get")]
242    pub fn get_with_timeout(&self, timeout: Duration) -> impl Future<Output = Result<T, Error>> + Send {
243        async move { self.inner.get_with_timeout(timeout).await }
244    }
245
246    /// Returns true if completed in any fashion: normally, exceptionally, or via
247    /// cancellation.
248    #[doc(alias = "org.apache.kafka.common.KafkaFuture#isDone")]
249    pub fn is_done(&self) -> bool {
250        self.inner.is_done()
251    }
252
253    /// Returns a new `KafkaFuture` that is completed when all the given futures
254    /// have completed. If any future fails, the returned future returns its
255    /// error. If multiple futures fail, which error gets returned is
256    /// arbitrarily chosen.
257    ///
258    /// # Arguments
259    ///
260    /// - `futures` - the futures to wait for
261    ///
262    /// # Translation notes
263    ///
264    /// Unlike Java's variadic `allOf`, the futures share one type `T`. The
265    /// error is the first failed future's in `futures`.
266    #[doc(alias = "org.apache.kafka.common.KafkaFuture#allOf")]
267    pub fn all_of(futures: Vec<KafkaFuture<T>>) -> KafkaFuture<()>
268    where
269        T: Clone + Sync,
270    {
271        let all = KafkaFutureImpl::new();
272        if futures.is_empty() {
273            all.complete(());
274            return all.future();
275        }
276        // The number of futures still pending, and the first failure by
277        // position, as `CompletableFuture.allOf` relays the leftmost one.
278        let state = Arc::new(Mutex::new((futures.len(), None::<(usize, Error)>)));
279        for (index, future) in futures.into_iter().enumerate() {
280            let state = Arc::clone(&state);
281            let all = all.clone();
282            future.on_complete(move |result| {
283                let outcome = {
284                    let mut guard = state.lock().unwrap_or_else(PoisonError::into_inner);
285                    let (remaining, first_error) = &mut *guard;
286                    if let Err(error) = result
287                        && first_error.as_ref().is_none_or(|(first, _)| index < *first)
288                    {
289                        *first_error = Some((index, error.clone()));
290                    }
291                    *remaining -= 1;
292                    (*remaining == 0).then(|| first_error.take())
293                };
294                // Completed outside the lock: `all`'s own dependants run here.
295                match outcome {
296                    Some(None) => _ = all.complete(()),
297                    Some(Some((_, error))) => _ = all.complete_with_error(error),
298                    None => {},
299                }
300            });
301        }
302        all.future()
303    }
304
305    /// Returns a future that completes when all the given keyed futures
306    /// complete, yielding a map from each key to its value. As soon as one
307    /// future fails, the returned future fails with its error.
308    ///
309    /// This is the combinator behind the admin `*Result` aggregators
310    /// (`DescribeTopicsResult::all_topic_names`, etc.). Java expresses the same
311    /// thing inline as `KafkaFuture.allOf(...).thenApply(v -> collect each
312    /// future.get())`, or, in `ListTransactionsResult.allByBrokerId`, with one
313    /// `whenComplete` per future, which this is.
314    pub(crate) fn join_map<K>(entries: Vec<(K, KafkaFuture<T>)>) -> KafkaFuture<HashMap<K, T>>
315    where
316        T: Clone + Sync,
317        K: Hash + Eq + Clone + Send + Sync + 'static,
318    {
319        let joined = KafkaFutureImpl::new();
320        if entries.is_empty() {
321            joined.complete(HashMap::new());
322            return joined.future();
323        }
324        let state = Arc::new(Mutex::new((entries.len(), HashMap::with_capacity(entries.len()))));
325        for (key, future) in entries {
326            let state = Arc::clone(&state);
327            let joined = joined.clone();
328            future.on_complete(move |result| match result {
329                Err(error) => _ = joined.complete_with_error(error.clone()),
330                Ok(value) => {
331                    let map = {
332                        let mut guard = state.lock().unwrap_or_else(PoisonError::into_inner);
333                        let (remaining, map) = &mut *guard;
334                        map.insert(key, value.clone());
335                        *remaining -= 1;
336                        (*remaining == 0).then(|| std::mem::take(map))
337                    };
338                    // Completed outside the lock: `joined`'s own dependants run here.
339                    if let Some(map) = map {
340                        joined.complete(map);
341                    }
342                },
343            });
344        }
345        joined.future()
346    }
347
348    /// Returns a new `KafkaFuture` that, when this future completes normally,
349    /// is executed with this future's result as the argument to the supplied
350    /// function. The function may be invoked by the task that calls
351    /// `then_apply` or it may be invoked by the task that completes the future.
352    ///
353    /// # Arguments
354    ///
355    /// - `function` - a closure or a [`BaseFunction_new`] value; the module
356    ///   docs show how to write one
357    ///
358    /// # Translation notes
359    ///
360    /// An `Err` from `function`, or a panic in it, fails the returned future,
361    /// as a Java throw does.
362    #[doc(alias = "org.apache.kafka.common.KafkaFuture#thenApply")]
363    pub fn then_apply<R, F>(&self, function: F) -> KafkaFuture<R>
364    where
365        T: Clone + Sync,
366        R: Clone + Send + Sync + 'static,
367        F: BaseFunction<T, R> + 'static,
368    {
369        let applied = KafkaFutureImpl::new();
370        let completer = applied.clone();
371        self.on_complete(move |result| match result {
372            Ok(value) => _ = completer.complete_result(apply_function(&function, value.clone())),
373            // Java's `CompletableFuture.thenApply` skips the function and
374            // fails the dependant with the source's failure.
375            Err(error) => _ = completer.complete_with_error(error.clone()),
376        });
377        applied.future()
378    }
379
380    /// Registers `callback` to run once with this future's result, on the
381    /// code path completing it, or at once on the calling task when it is
382    /// already complete (see [`KafkaFutureOps::on_complete`]).
383    pub(crate) fn on_complete<F>(&self, callback: F)
384    where
385        F: FnOnce(&Result<T, Error>) + Send + 'static,
386    {
387        Arc::clone(&self.inner).on_complete(Box::new(callback));
388    }
389
390    /// The result of this future when it is already complete, read without
391    /// waiting, as Java's `getNow` reads a future that `allOf` has completed;
392    /// `None` while it is pending.
393    pub(crate) fn result_if_done(&self) -> Option<Result<T, Error>> {
394        if !self.is_done() {
395            return None;
396        }
397        self.inner.get().now_or_never()
398    }
399
400    /// A view of this future whose value is `map` applied to this one's, each
401    /// time it is read: by every `get`, and for every completion callback.
402    ///
403    /// Not `then_apply`, which runs its function once, eagerly: the C binding
404    /// maps every future it hands out to its C value with this, a pure
405    /// conversion that has no reason to run, nor to allocate the C value, for
406    /// a future nobody reads (a producer record's, one per record). No Java
407    /// counterpart (DoD #7): Java hands out its futures as they are.
408    /// Crate-internal, and only the `ffi` feature names it.
409    #[cfg(feature = "ffi")]
410    pub(crate) fn map_lazily<R, F>(&self, map: F) -> KafkaFuture<R>
411    where
412        T: Clone,
413        R: Send + 'static,
414        F: Fn(T) -> R + Send + Sync + 'static,
415    {
416        KafkaFuture::new(Arc::new(LazyMapFuture { source: self.clone(), map: Arc::new(map) }))
417    }
418}
419
420/// Internal `KafkaFutureOps` impl backing [`KafkaFuture::map_lazily`].
421#[cfg(feature = "ffi")]
422struct LazyMapFuture<T: Send + 'static, R> {
423    source: KafkaFuture<T>,
424    map: Arc<dyn Fn(T) -> R + Send + Sync>,
425}
426
427#[cfg(feature = "ffi")]
428impl<T: Clone + Send + 'static, R: Send + 'static> KafkaFutureOps<R> for LazyMapFuture<T, R> {
429    fn get(&self) -> Pin<Box<dyn std::future::Future<Output = Result<R, Error>> + Send + '_>> {
430        Box::pin(async move { self.source.get().await.map(&*self.map) })
431    }
432
433    fn get_with_timeout(
434        &self,
435        timeout: Duration,
436    ) -> Pin<Box<dyn std::future::Future<Output = Result<R, Error>> + Send + '_>> {
437        Box::pin(async move { self.source.get_with_timeout(timeout).await.map(&*self.map) })
438    }
439
440    fn is_done(&self) -> bool {
441        self.source.is_done()
442    }
443
444    fn on_complete(self: Arc<Self>, callback: CompletionCallback<R>) {
445        let map = Arc::clone(&self.map);
446        self.source.on_complete(move |result| match result {
447            Ok(value) => callback(&Ok(map(value.clone()))),
448            Err(error) => callback(&Err(error.clone())),
449        });
450    }
451}
452
453/// Applies a [`KafkaFuture::then_apply`] function, turning a panic into the
454/// error the dependant fails with: the function runs on the code path that
455/// completes the source (the admin client's background task, for instance),
456/// which a panicking function must not unwind, as a Java function that throws
457/// only fails its dependant.
458fn apply_function<T, R>(function: &dyn BaseFunction<T, R>, value: T) -> Result<R, Error> {
459    std::panic::catch_unwind(AssertUnwindSafe(|| function.apply(value))).unwrap_or_else(|payload| {
460        let message = payload
461            .downcast_ref::<&str>()
462            .copied()
463            .or_else(|| payload.downcast_ref::<String>().map(String::as_str))
464            .unwrap_or("non-string panic payload");
465        Err(Error::local_illegal_state(format!(
466            "KafkaFuture.then_apply function panicked: {message}"
467        )))
468    })
469}
470
471impl<T: Send + 'static> Clone for KafkaFuture<T> {
472    fn clone(&self) -> Self {
473        Self { inner: Arc::clone(&self.inner) }
474    }
475}
476
477impl<T: Send + 'static> std::fmt::Debug for KafkaFuture<T> {
478    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
479        f.debug_struct("KafkaFuture").field("is_done", &self.is_done()).finish()
480    }
481}
482
483/// Internal `KafkaFutureOps` impl for an already-resolved future.
484///
485/// Used by [`KafkaFuture::completed_future`] to wrap a value that is already known
486/// when the future is constructed. The result is cloned on each `get` call
487/// so the future is reusable, matching Java's `Future` semantics.
488struct CompletedFuture<T: Clone + Send + Sync + 'static> {
489    result: Result<T, Error>,
490}
491
492impl<T: Clone + Send + Sync + 'static> KafkaFutureOps<T> for CompletedFuture<T> {
493    fn get(&self) -> Pin<Box<dyn std::future::Future<Output = Result<T, Error>> + Send + '_>> {
494        let result = self.result.clone();
495        Box::pin(async move { result })
496    }
497
498    fn get_with_timeout(
499        &self,
500        _timeout: Duration,
501    ) -> Pin<Box<dyn std::future::Future<Output = Result<T, Error>> + Send + '_>> {
502        let result = self.result.clone();
503        Box::pin(async move { result })
504    }
505
506    fn is_done(&self) -> bool {
507        true
508    }
509
510    fn on_complete(self: Arc<Self>, callback: CompletionCallback<T>) {
511        callback(&self.result);
512    }
513}
514
515#[cfg(test)]
516mod tests {
517    use super::*;
518    use crate::common::internals::KafkaFutureImpl;
519    use crate::common::protocol::Errors;
520    use std::sync::Mutex;
521    use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
522
523    #[tokio::test]
524    async fn completed_resolves_with_ok_value() {
525        let f: KafkaFuture<i32> = KafkaFuture::completed_future(Ok(42));
526        assert!(f.is_done());
527        assert_eq!(f.get().await.unwrap(), 42);
528        // Reusable across multiple gets, matching Java Future semantics.
529        assert_eq!(f.get().await.unwrap(), 42);
530        assert_eq!(f.get_with_timeout(Duration::from_secs(1)).await.unwrap(), 42);
531    }
532
533    #[tokio::test]
534    async fn completed_resolves_with_err_value() {
535        let f: KafkaFuture<i32> = KafkaFuture::completed_future(Err(Error::local_illegal_argument("test".to_string())));
536        assert!(f.is_done());
537        assert!(matches!(f.get().await, Err(Error::LocalIllegalArgument(_))));
538        assert!(matches!(
539            f.get_with_timeout(Duration::from_secs(1)).await,
540            Err(Error::LocalIllegalArgument(_))
541        ));
542    }
543
544    #[tokio::test]
545    async fn completed_clone_shares_underlying_result() {
546        let f1: KafkaFuture<String> = KafkaFuture::completed_future(Ok("hello".to_string()));
547        let f2 = f1.clone();
548        assert_eq!(f1.get().await.unwrap(), "hello");
549        assert_eq!(f2.get().await.unwrap(), "hello");
550    }
551
552    #[tokio::test]
553    async fn impl_completes_value_after_the_fact() {
554        let handle: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
555        let future = handle.future();
556        assert!(!future.is_done());
557
558        let completer = handle.clone();
559        let task = tokio::spawn(async move { future.get().await });
560        // Give the awaiting task a chance to register interest, then complete.
561        tokio::task::yield_now().await;
562        assert!(completer.complete(42));
563        // Second completion is a no-op and returns false (first writer wins).
564        assert!(!completer.complete(99));
565
566        assert_eq!(task.await.unwrap().unwrap(), 42);
567        assert!(handle.is_done());
568    }
569
570    #[tokio::test]
571    async fn impl_completes_with_error() {
572        let handle: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
573        let future = handle.future();
574        assert!(handle.complete_with_error(Error::local_illegal_argument("boom".to_string())));
575        match future.get().await {
576            Err(Error::LocalIllegalArgument(msg)) => assert_eq!(msg.message(), "boom"),
577            other => panic!("expected IllegalArgument, got {other:?}"),
578        }
579    }
580
581    #[tokio::test]
582    async fn impl_get_timeout_elapses_when_never_completed() {
583        let handle: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
584        let future = handle.future();
585        let err = match future.get_with_timeout(Duration::from_millis(20)).await {
586            Err(e) => e,
587            other => panic!("expected a timeout, got {other:?}"),
588        };
589        // Java throws `java.util.concurrent.TimeoutException`
590        // (`org.apache.kafka.common.KafkaFuture#get`), a checked exception beside the Kafka
591        // hierarchy — so none of the predicates hold and there is no wire code.
592        // `Error::Timeout` would be
593        // `org.apache.kafka.common.errors.TimeoutException`: retriable, an
594        // api error, and code 7.
595        assert!(matches!(err, Error::LocalTimeout(_)), "got {err:?}");
596        assert!(!err.is_retriable_error());
597        assert!(!err.is_api_error());
598        assert!(!err.is_kafka_error());
599        assert_eq!(Errors::UnknownServerError, err.error());
600    }
601
602    #[tokio::test]
603    async fn when_complete_runs_eagerly_on_completion() {
604        let handle: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
605        let seen = Arc::new(Mutex::new(None));
606        let seen_clone = Arc::clone(&seen);
607        handle.when_complete(move |result| {
608            *seen_clone.lock().unwrap() = result.as_ref().ok().copied();
609        });
610        // Nobody awaits get(); the callback must still fire on complete().
611        handle.complete(7);
612        assert_eq!(*seen.lock().unwrap(), Some(7));
613    }
614
615    #[tokio::test]
616    async fn when_complete_runs_immediately_if_already_done() {
617        let handle: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
618        handle.complete(5);
619        let seen = Arc::new(Mutex::new(None));
620        let seen_clone = Arc::clone(&seen);
621        handle.when_complete(move |result| {
622            *seen_clone.lock().unwrap() = result.as_ref().ok().copied();
623        });
624        assert_eq!(*seen.lock().unwrap(), Some(5));
625    }
626
627    #[tokio::test]
628    async fn all_of_succeeds_when_all_succeed() {
629        let h1: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
630        let h2: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
631        let all = KafkaFuture::all_of(vec![h1.future(), h2.future()]);
632        h1.complete(1);
633        h2.complete(2);
634        assert_eq!(all.get().await.unwrap(), ());
635    }
636
637    #[tokio::test]
638    async fn all_of_fails_if_any_fails() {
639        let h1: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
640        let h2: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
641        let all = KafkaFuture::all_of(vec![h1.future(), h2.future()]);
642        h1.complete(1);
643        h2.complete_with_error(Error::local_illegal_argument("nope".to_string()));
644        assert!(matches!(all.get().await, Err(Error::LocalIllegalArgument(_))));
645    }
646
647    #[tokio::test]
648    async fn then_apply_transforms_value() {
649        let handle: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
650        let mapped = handle.future().then_apply(|v| Ok(v * 2));
651        handle.complete(21);
652        assert_eq!(mapped.get().await.unwrap(), 42);
653    }
654
655    #[tokio::test]
656    async fn then_apply_takes_a_base_function_made_by_the_factory() {
657        let handle: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
658        let mapped = handle.future().then_apply(BaseFunction_new(|v: i32| Ok(v.to_string())));
659        handle.complete(21);
660        assert_eq!(mapped.get().await.unwrap(), "21");
661    }
662
663    #[test]
664    fn base_function_new_returns_the_function_result() {
665        let function = BaseFunction_new(|v: i32| {
666            if v < 0 {
667                Err(Error::local_illegal_argument("negative".to_string()))
668            } else {
669                Ok(v * 2)
670            }
671        });
672        assert_eq!(function.apply(4).unwrap(), 8);
673        assert!(matches!(function.apply(-1), Err(Error::LocalIllegalArgument(_))));
674    }
675
676    #[tokio::test]
677    async fn then_apply_propagates_source_error() {
678        let handle: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
679        let mapped = handle.future().then_apply(|v| Ok(v * 2));
680        handle.complete_with_error(Error::local_illegal_argument("src".to_string()));
681        assert!(matches!(mapped.get().await, Err(Error::LocalIllegalArgument(_))));
682    }
683
684    #[tokio::test]
685    async fn join_map_collects_values_when_all_succeed() {
686        let h1: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
687        let h2: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
688        let joined = KafkaFuture::join_map(vec![("a", h1.future()), ("b", h2.future())]);
689        h1.complete(1);
690        h2.complete(2);
691        let map = joined.get().await.unwrap();
692        assert_eq!(map.len(), 2);
693        assert_eq!(map["a"], 1);
694        assert_eq!(map["b"], 2);
695    }
696
697    /// `join_map` short-circuits on the first error — the behavior
698    /// `join_map_results` exists to complement. Pinned so the two stay distinct.
699    ///
700    /// The discriminator is the third entry, which is **never completed**: a
701    /// short-circuiting implementation abandons it and returns the error at
702    /// once, whereas any collect-all implementation (even one that returned the
703    /// first error afterwards) would await it and hang past the timeout below.
704    /// Asserting only that the error surfaces would pass for both.
705    #[tokio::test]
706    async fn join_map_short_circuits_on_first_error() {
707        let bad: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
708        let ok: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
709        let never: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
710        let joined = KafkaFuture::join_map(vec![("bad", bad.future()), ("ok", ok.future()), ("never", never.future())]);
711        bad.complete_with_error(Error::local_illegal_argument("a failed"));
712        ok.complete(2);
713        // `never` is deliberately left pending.
714
715        let outcome = tokio::time::timeout(Duration::from_secs(5), joined.get())
716            .await
717            .expect("join_map must abandon the keys after the failing one, not await them");
718        match outcome {
719            Err(Error::LocalIllegalArgument(e)) => assert_eq!(e.message(), "a failed"),
720            other => panic!("expected IllegalArgument, got {other:?}"),
721        }
722    }
723
724    #[tokio::test]
725    async fn then_apply_can_fail() {
726        let handle: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
727        let mapped = handle
728            .future()
729            .then_apply(|_v| Err::<i32, _>(Error::local_illegal_state("bad".to_string())));
730        handle.complete(1);
731        assert!(matches!(mapped.get().await, Err(Error::LocalIllegalState(_))));
732    }
733
734    /// The value of a completed future, read without waiting, as Java's
735    /// `getNow(valueIfAbsent)`.
736    fn get_now<T: Clone + Send + 'static>(future: &KafkaFuture<T>, value_if_absent: T) -> Result<T, Error> {
737        future.result_if_done().unwrap_or(Ok(value_if_absent))
738    }
739
740    /// Asserts that `future` failed with `message` and, when given, a source
741    /// error carrying `source_message`, as Java's `awaitAndAssertFailure`.
742    async fn await_and_assert_failure<T: std::fmt::Debug + Send + 'static>(
743        future: &KafkaFuture<T>,
744        message: &str,
745        source_message: Option<&str>,
746    ) {
747        assert!(future.is_done());
748        let error = future.get().await.expect_err("the future failed");
749        assert_eq!(error.message(), message);
750        assert_eq!(error.source().map(Error::message), source_message);
751    }
752
753    /// `org.apache.kafka.common.KafkaFutureTest#testThenApplyOnSucceededFuture`
754    #[test]
755    fn test_then_apply_on_succeeded_future() {
756        let future: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
757        let doubled_future = future.future().then_apply(|integer| Ok(2 * integer));
758        assert!(!doubled_future.is_done());
759        let tripled_future = future.future().then_apply(|integer| Ok(3 * integer));
760        assert!(!tripled_future.is_done());
761        future.complete(21);
762        assert_eq!(get_now(&future.future(), -1).unwrap(), 21);
763        assert_eq!(get_now(&doubled_future, -1).unwrap(), 42);
764        assert_eq!(get_now(&tripled_future, -1).unwrap(), 63);
765        let quadrupled_future = future.future().then_apply(|integer| Ok(4 * integer));
766        assert_eq!(get_now(&quadrupled_future, -1).unwrap(), 84);
767    }
768
769    /// `org.apache.kafka.common.KafkaFutureTest#testThenApplyOnFailedFuture`
770    #[tokio::test]
771    async fn test_then_apply_on_failed_future() {
772        let future: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
773        let dependant_future = future.future().then_apply(|integer| Ok(2 * integer));
774        future.complete_with_error(Error::kafka_message("We require more vespene gas"));
775        await_and_assert_failure(&future.future(), "We require more vespene gas", None).await;
776        await_and_assert_failure(&dependant_future, "We require more vespene gas", None).await;
777    }
778
779    /// `org.apache.kafka.common.KafkaFutureTest#testThenApplyOnFailedFutureTricky`:
780    /// Java's `CompletionException` wrapping a cause has no Rust counterpart;
781    /// its shape here is an error with a source, which the dependant receives
782    /// unchanged, source included.
783    #[tokio::test]
784    async fn test_then_apply_on_failed_future_tricky() {
785        let future: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
786        let dependant_future = future.future().then_apply(|integer| Ok(2 * integer));
787        future.complete_with_error(Error::kafka_message_source(
788            "java.lang.RuntimeException: We require more vespene gas",
789            Error::kafka_message("We require more vespene gas"),
790        ));
791        let message = "java.lang.RuntimeException: We require more vespene gas";
792        await_and_assert_failure(&future.future(), message, Some("We require more vespene gas")).await;
793        await_and_assert_failure(&dependant_future, message, Some("We require more vespene gas")).await;
794    }
795
796    /// `org.apache.kafka.common.KafkaFutureTest#testThenApplyOnFailedFutureTricky2`:
797    /// the wrapped cause is one without a message, as Java's
798    /// `CancellationException()`.
799    #[tokio::test]
800    async fn test_then_apply_on_failed_future_tricky2() {
801        let future: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
802        let dependant_future = future.future().then_apply(|integer| Ok(2 * integer));
803        future.complete_with_error(Error::kafka_message_source(
804            "java.util.concurrent.CancellationException",
805            Error::kafka_message(""),
806        ));
807        let message = "java.util.concurrent.CancellationException";
808        await_and_assert_failure(&future.future(), message, Some("")).await;
809        await_and_assert_failure(&dependant_future, message, Some("")).await;
810    }
811
812    /// `org.apache.kafka.common.KafkaFutureTest#testThenApplyOnSucceededFutureAndFunctionThrows`
813    #[tokio::test]
814    async fn test_then_apply_on_succeeded_future_and_function_throws() {
815        let future: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
816        let dependant_future = future
817            .future()
818            .then_apply(|_integer| Err::<i32, _>(Error::kafka_message("We require more vespene gas")));
819        future.complete(21);
820        assert_eq!(future.future().get().await.unwrap(), 21);
821        await_and_assert_failure(&dependant_future, "We require more vespene gas", None).await;
822    }
823
824    /// `org.apache.kafka.common.KafkaFutureTest#testThenApplyOnSucceededFutureAndFunctionThrowsCompletionException`
825    #[tokio::test]
826    async fn test_then_apply_on_succeeded_future_and_function_throws_completion_exception() {
827        let future: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
828        let dependant_future = future.future().then_apply(|_integer| {
829            Err::<i32, _>(Error::kafka_message_source(
830                "java.lang.RuntimeException: We require more vespene gas",
831                Error::kafka_message("We require more vespene gas"),
832            ))
833        });
834        future.complete(21);
835        assert_eq!(future.future().get().await.unwrap(), 21);
836        await_and_assert_failure(
837            &dependant_future,
838            "java.lang.RuntimeException: We require more vespene gas",
839            Some("We require more vespene gas"),
840        )
841        .await;
842    }
843
844    /// `org.apache.kafka.common.KafkaFutureTest#testThenApplyOnFailedFutureFunctionNotCalled`
845    #[tokio::test]
846    async fn test_then_apply_on_failed_future_function_not_called() {
847        let future: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
848        let ran = Arc::new(AtomicBool::new(false));
849        let ran_in_function = Arc::clone(&ran);
850        let dependant_future = future.future().then_apply(move |_integer| {
851            // Because the top level future failed, this should never be called.
852            ran_in_function.store(true, Ordering::SeqCst);
853            Ok(0)
854        });
855        future.complete_with_error(Error::kafka_message("We require more minerals"));
856        await_and_assert_failure(&future.future(), "We require more minerals", None).await;
857        await_and_assert_failure(&dependant_future, "We require more minerals", None).await;
858        assert!(!ran.load(Ordering::SeqCst));
859    }
860
861    /// The function runs once, when the source completes, with nobody waiting
862    /// on the dependant; later reads answer the stored result without running
863    /// it again.
864    #[tokio::test]
865    async fn then_apply_runs_the_function_once_at_completion() {
866        let future: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
867        let calls = Arc::new(AtomicUsize::new(0));
868        let counted = Arc::clone(&calls);
869        let dependant_future = future.future().then_apply(move |integer| {
870            counted.fetch_add(1, Ordering::SeqCst);
871            Ok(2 * integer)
872        });
873        assert_eq!(calls.load(Ordering::SeqCst), 0);
874        assert!(!dependant_future.is_done());
875        future.complete(21);
876        assert_eq!(calls.load(Ordering::SeqCst), 1, "run by complete(), not by a get");
877        assert!(dependant_future.is_done());
878        for _ in 0..3 {
879            assert_eq!(dependant_future.get().await.unwrap(), 42);
880            assert_eq!(dependant_future.get_with_timeout(Duration::from_secs(1)).await.unwrap(), 42);
881        }
882        assert_eq!(calls.load(Ordering::SeqCst), 1);
883    }
884
885    /// Over a future already complete, the function runs inside `then_apply`.
886    #[test]
887    fn then_apply_runs_the_function_inline_when_the_source_is_done() {
888        let calls = Arc::new(AtomicUsize::new(0));
889        let counted = Arc::clone(&calls);
890        let dependant_future = KafkaFuture::completed_future(Ok(21)).then_apply(move |integer: i32| {
891            counted.fetch_add(1, Ordering::SeqCst);
892            Ok(2 * integer)
893        });
894        assert_eq!(calls.load(Ordering::SeqCst), 1);
895        assert!(dependant_future.is_done());
896        assert_eq!(get_now(&dependant_future, -1).unwrap(), 42);
897        assert_eq!(calls.load(Ordering::SeqCst), 1);
898    }
899
900    /// The function runs on the task completing the source, so a chain of
901    /// dependants completes from one `complete`.
902    #[test]
903    fn then_apply_chain_completes_from_the_completing_call() {
904        let future: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
905        let chained = future
906            .future()
907            .then_apply(|integer| Ok(integer + 1))
908            .then_apply(|integer| Ok(integer * 10));
909        assert!(!chained.is_done());
910        future.complete(1);
911        assert_eq!(get_now(&chained, -1).unwrap(), 20);
912    }
913
914    /// A panic in the function fails the dependant instead of unwinding the
915    /// code path that completes the source.
916    #[test]
917    fn then_apply_function_panic_fails_the_dependant() {
918        let future: KafkaFutureImpl<i32> = KafkaFutureImpl::new();
919        let dependant_future = future.future().then_apply(|_integer| -> Result<i32, Error> { panic!("boom") });
920        assert!(future.complete(21));
921        let error = get_now(&dependant_future, -1).expect_err("the function panicked");
922        assert!(error.is_local_illegal_state_error(), "got {error:?}");
923        assert_eq!(error.message(), "KafkaFuture.then_apply function panicked: boom");
924    }
925
926    /// `org.apache.kafka.common.KafkaFutureTest#testAllOfFuturesHandlesZeroFutures`
927    #[tokio::test]
928    async fn test_all_of_futures_handles_zero_futures() {
929        let all_future = KafkaFuture::<i32>::all_of(Vec::new());
930        assert!(all_future.is_done());
931        all_future.get().await.unwrap();
932    }
933
934    /// `org.apache.kafka.common.KafkaFutureTest#testAllOfFuturesWithFailure`
935    /// shape: `all_of` completes only once every future has, and then with the
936    /// failure of the first failed one in the list, as Java's
937    /// `CompletableFuture.allOf`.
938    #[test]
939    fn all_of_waits_for_every_future_and_fails_with_the_first_failure() {
940        let futures: Vec<KafkaFutureImpl<i32>> = (0..5).map(|_| KafkaFutureImpl::new()).collect();
941        let all_future = KafkaFuture::all_of(futures.iter().map(KafkaFutureImpl::future).collect());
942        futures[3].complete_with_error(Error::kafka_message("Fourth one failed"));
943        futures[1].complete_with_error(Error::kafka_message("Second one failed"));
944        futures[0].complete(0);
945        futures[2].complete(2);
946        assert!(!all_future.is_done(), "waits for the last future despite the failures");
947        futures[4].complete(4);
948        let error = get_now(&all_future, ()).expect_err("two futures failed");
949        assert_eq!(error.message(), "Second one failed");
950    }
951
952    /// `org.apache.kafka.common.KafkaFutureTest#testAllOfFutures` shape: a
953    /// dependant of `all_of` completes from the last source's completion,
954    /// without anyone waiting.
955    #[test]
956    fn all_of_completes_its_dependants_from_the_last_completion() {
957        let futures: Vec<KafkaFutureImpl<i32>> = (0..5).map(|_| KafkaFutureImpl::new()).collect();
958        let sources: Vec<KafkaFuture<i32>> = futures.iter().map(KafkaFutureImpl::future).collect();
959        let sum = KafkaFuture::all_of(sources.clone())
960            .then_apply(move |()| sources.iter().map(|future| get_now(future, -1)).sum::<Result<i32, Error>>());
961        for (index, future) in futures.iter().enumerate() {
962            assert!(!sum.is_done());
963            future.complete(index as i32);
964        }
965        assert_eq!(get_now(&sum, -1).unwrap(), 10);
966    }
967}