Skip to main content

confluent_kafka/consumer/
mock_consumer.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//! In-memory `Consumer<K, V>` implementation for use in tests.
16//!
17//! Translated from `org.apache.kafka.clients.consumer.MockConsumer`.
18//! Mirrors the Java class field-for-field. Mock-specific driver methods
19//! (`add_record`, `update_beginning_offsets`, `rebalance`, `schedule_poll_task`,
20//! `set_poll_error`, etc.) live on the concrete `MockConsumer<K, V>`
21//! type — they are NOT on the [`Consumer<K, V>`](crate::consumer::Consumer)
22//! trait. Tests hold a `MockConsumer` directly and pass `&mut consumer` where
23//! a `C: Consumer<K, V>` or a `&mut dyn DynConsumer<K, V>` is expected (see
24//! `consumer-threading.md` §2).
25//!
26//! Threading: `MockConsumer` is `!Sync` and intended for single-task use
27//! through the `&mut self` dispatch surface. `wakeup()` is callable from
28//! any task because it takes `&self` and uses an atomic flag.
29
30use std::cell::Cell;
31use std::collections::{HashMap, HashSet, VecDeque};
32use std::marker::PhantomData;
33use std::sync::atomic::{AtomicBool, Ordering};
34use std::sync::{Arc, Mutex, PoisonError};
35use std::time::Duration;
36
37use indexmap::IndexMap;
38
39use crate::common::metrics::MetricsView;
40use crate::common::{Error, PartitionInfo, TopicPartition};
41use crate::consumer::internals::AutoOffsetResetStrategy;
42use crate::consumer::internals::StrategyType;
43use crate::consumer::internals::{FetchPosition, SubscriptionState};
44use crate::consumer::{
45    CloseOptions, Consumer, ConsumerGroupMetadata, ConsumerGroupMetadataImpl, ConsumerHandle,
46    ConsumerRebalanceListener, ConsumerRecord, ConsumerRecords, OffsetAndMetadata, OffsetAndTimestamp,
47    OffsetCommitCallback, SubscriptionPattern,
48};
49use crate::consumer::{ConsumerNoOffsetForPartitionError, ConsumerOffsetOutOfRangeError};
50use crate::metadata::LeaderAndEpoch;
51
52/// One scheduled poll task — see [`MockConsumer::schedule_poll_task`].
53///
54/// The deviation from Java's parameterless `Runnable` is documented on the
55/// `schedule_poll_task` method; the task receives an explicit
56/// `&mut MockConsumer<K, V>` because Rust closures cannot safely capture
57/// the outer struct.
58pub type PollTask<K, V> = Box<dyn FnOnce(&mut MockConsumer<K, V>) + Send>;
59
60/// A mock of the [`Consumer`] interface you can use for testing code that
61/// uses Kafka. This class is *not threadsafe*. However, you can use the
62/// [`Self::schedule_poll_task`] method to write multithreaded tests where a
63/// driver thread waits for [`Consumer::poll`] to be called by a background
64/// thread and then can safely perform operations during a callback.
65///
66/// # Translation notes
67///
68/// The mock is `Send` but not `Sync`: another task reaches it through
69/// [`Consumer::handle`].
70///
71/// ```compile_fail,E0277
72/// use confluent_kafka::consumer::MockConsumer;
73///
74/// fn assert_sync<T: Sync>() {}
75/// assert_sync::<MockConsumer<String, String>>();
76/// ```
77// Java's `MockConsumer(String offsetResetStrategy)` is `MockConsumer::new`. The
78// deprecated `MockConsumer(OffsetResetStrategy)` and the deprecated
79// `OffsetResetStrategy` enum are not translated (CLAUDE.md §3); that constructor
80// only forwards `offsetResetStrategy.toString()`, so Rust callers pass the
81// `auto.offset.reset` string to `MockConsumer::new` instead. Like `KafkaConsumer`,
82// the mock is `Send` but not `Sync` (`consumer-threading.md` §2).
83#[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer")]
84pub struct MockConsumer<K, V> {
85    partitions: HashMap<String, Vec<PartitionInfo>>,
86    /// Shared (`consumer-threading.md` §16: a `std::sync::Mutex`, never held
87    /// across an `.await` or a listener call) so a [`Consumer::handle`]
88    /// obtained from this mock reads the assignment and commits the consumed
89    /// positions as a Java callback calling back into the mock does
90    /// (`commitSync()` is `commitSync(subscriptions.allConsumed())`).
91    subscriptions: Arc<Mutex<SubscriptionState>>,
92    beginning_offsets: HashMap<TopicPartition, i64>,
93    /// Shared so a [`Consumer::handle`] obtained from this mock computes
94    /// `current_lag` over the same end offsets, as a Java callback calling
95    /// `consumer.currentLag(tp)` on the mock does.
96    end_offsets: Arc<Mutex<HashMap<TopicPartition, i64>>>,
97    duration_reset_offsets: HashMap<TopicPartition, i64>,
98    /// Shared so a [`Consumer::handle`] obtained from this mock commits into
99    /// the same map, as a Java callback calling back into the mock does.
100    committed: Arc<Mutex<HashMap<TopicPartition, OffsetAndMetadata>>>,
101    /// Java stores `Runnable` tasks that capture `MockConsumer` implicitly.
102    /// Rust closures cannot capture the outer struct safely without
103    /// `Arc<Mutex<...>>` wrapping, so we deviate: tasks receive `&mut
104    /// MockConsumer<K, V>` explicitly. Tests write
105    /// `consumer.schedule_poll_task(Box::new(|c| c.add_record(...).unwrap()));`.
106    poll_tasks: VecDeque<PollTask<K, V>>,
107    /// Shared for the same reason as `subscriptions`: the handle's `paused()`
108    /// is the mock's `paused()`.
109    paused: Arc<Mutex<HashSet<TopicPartition>>>,
110    /// Atomic so [`Consumer::wakeup`] can
111    /// take `&self` (callable from any task / signal handler). `SeqCst`
112    /// because wakeup is rare and reorder reasoning is not worth the win.
113    /// `Arc` so [`Consumer::handle`] can hand a shareable clone to
114    /// another task.
115    wakeup: Arc<AtomicBool>,
116    records: HashMap<TopicPartition, Vec<ConsumerRecord<K, V>>>,
117    poll_error: Option<Error>,
118    offsets_error: Option<Error>,
119    /// The three fields Java reads outside the mock's monitor
120    /// (`lastPollTimeout()`, `shouldRebalance()`) or under it while waiting
121    /// (`closed()`), shared so [`Consumer::handle`] can answer them while an
122    /// operation borrows the mock: the C binding reads them through the
123    /// handle rather than its single-owner flag.
124    last_poll_timeout: Arc<Mutex<Option<Duration>>>,
125    closed: Arc<AtomicBool>,
126    should_rebalance: Arc<AtomicBool>,
127    /// `i64::MAX` is the "no cap" sentinel mirroring Java's `Long.MAX_VALUE`.
128    max_poll_records: i64,
129    /// Zero-sized: keeps the mock `Send` and makes it `!Sync` whatever its
130    /// other fields are, as `KafkaConsumer` (see `Threads` above).
131    not_sync: PhantomData<Cell<()>>,
132}
133
134impl<K, V> std::fmt::Debug for MockConsumer<K, V> {
135    // Whether the mock is closed; the records and offsets it holds are not
136    // printed.
137    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
138        f.debug_struct("MockConsumer")
139            .field("closed", &self.closed())
140            .finish_non_exhaustive()
141    }
142}
143
144impl<K, V> MockConsumer<K, V> {
145    /// A mock consumer is instantiated by providing
146    /// `ConsumerConfig::AUTO_OFFSET_RESET_CONFIG` value as the input.
147    ///
148    /// # Arguments
149    ///
150    /// - `offset_reset_strategy` - the offset reset strategy to use
151    ///
152    /// # Returns
153    ///
154    /// The new mock consumer.
155    ///
156    /// # Errors
157    ///
158    /// - `Error::is_local_illegal_argument_error` if `offset_reset_strategy` is not a valid
159    ///   `auto.offset.reset` value
160    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#MockConsumer(String)")]
161    pub fn new(offset_reset_strategy: &str) -> Result<Self, Error> {
162        Ok(Self::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::from_string(
163            offset_reset_strategy,
164        )?))
165    }
166
167    /// Java's private `MockConsumer(AutoOffsetResetStrategy)`, which the public
168    /// constructors delegate to.
169    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#MockConsumer")]
170    pub(crate) fn with_auto_offset_reset_strategy(offset_reset_strategy: AutoOffsetResetStrategy) -> Self {
171        Self {
172            partitions: HashMap::new(),
173            subscriptions: Arc::new(Mutex::new(SubscriptionState::new(offset_reset_strategy))),
174            beginning_offsets: HashMap::new(),
175            end_offsets: Arc::new(Mutex::new(HashMap::new())),
176            duration_reset_offsets: HashMap::new(),
177            committed: Arc::new(Mutex::new(HashMap::new())),
178            poll_tasks: VecDeque::new(),
179            paused: Arc::new(Mutex::new(HashSet::new())),
180            wakeup: Arc::new(AtomicBool::new(false)),
181            records: HashMap::new(),
182            poll_error: None,
183            offsets_error: None,
184            last_poll_timeout: Arc::new(Mutex::new(None)),
185            closed: Arc::new(AtomicBool::new(false)),
186            should_rebalance: Arc::new(AtomicBool::new(false)),
187            max_poll_records: i64::MAX,
188            not_sync: PhantomData,
189        }
190    }
191
192    // ── Driver methods (mock-specific) ──────────────────────────────────
193
194    /// Adds a record to be returned when [`Consumer::poll`] is called.
195    ///
196    /// # Arguments
197    ///
198    /// - `record` - the record to add
199    ///
200    /// # Errors
201    ///
202    /// - `Error::is_local_illegal_state_error` if the partition is not assigned to the consumer
203    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#addRecord")]
204    pub fn add_record(&mut self, record: ConsumerRecord<K, V>) -> Result<(), Error> {
205        self.ensure_not_closed()?;
206        let tp = TopicPartition::new(record.topic().to_string(), record.partition());
207        if !self.subs().assigned_partitions().contains(&tp) {
208            return Err(Error::local_illegal_state(
209                "Cannot add records for a partition that is not assigned to the consumer",
210            ));
211        }
212        self.records.entry(tp).or_default().push(record);
213        Ok(())
214    }
215
216    /// Updates the beginning offsets for the specified partitions.
217    ///
218    /// # Arguments
219    ///
220    /// - `offsets` - the beginning offsets to set
221    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#updateBeginningOffsets")]
222    pub fn update_beginning_offsets(&mut self, offsets: HashMap<TopicPartition, i64>) {
223        self.beginning_offsets.extend(offsets);
224    }
225
226    /// Updates the end offsets for the specified partitions.
227    ///
228    /// # Arguments
229    ///
230    /// - `offsets` - the end offsets to set
231    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#updateEndOffsets")]
232    pub fn update_end_offsets(&mut self, offsets: HashMap<TopicPartition, i64>) {
233        self.end_offsets_lock().extend(offsets);
234    }
235
236    /// Locks the shared end offsets; never held across an `.await`.
237    fn end_offsets_lock(&self) -> std::sync::MutexGuard<'_, HashMap<TopicPartition, i64>> {
238        self.end_offsets.lock().unwrap_or_else(PoisonError::into_inner)
239    }
240
241    /// Updates the duration-based reset offsets for the specified partitions.
242    ///
243    /// # Arguments
244    ///
245    /// - `offsets` - the duration offsets to set
246    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#updateDurationOffsets")]
247    pub fn update_duration_offsets(&mut self, offsets: HashMap<TopicPartition, i64>) {
248        self.duration_reset_offsets.extend(offsets);
249    }
250
251    /// Updates the partition information for the specified topic.
252    ///
253    /// # Arguments
254    ///
255    /// - `topic` - the topic to update
256    /// - `partitions` - the partition information
257    ///
258    /// # Errors
259    ///
260    /// - `Error::is_local_illegal_state_error` if the consumer is closed
261    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#updatePartitions")]
262    pub fn update_partitions(&mut self, topic: &str, partitions: Vec<PartitionInfo>) -> Result<(), Error> {
263        self.ensure_not_closed()?;
264        self.partitions.insert(topic.to_string(), partitions);
265        Ok(())
266    }
267
268    /// Sets an exception to throw when [`Consumer::poll`] is called.
269    ///
270    /// # Arguments
271    ///
272    /// - `error` - the exception to throw; `None` clears a pending one
273    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#setPollException")]
274    pub fn set_poll_error(&mut self, error: Option<Error>) {
275        self.poll_error = error;
276    }
277
278    /// Sets an exception to throw when offset-related methods are called.
279    ///
280    /// # Arguments
281    ///
282    /// - `error` - the exception to throw; `None` clears a pending one
283    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#setOffsetsException")]
284    pub fn set_offsets_error(&mut self, error: Option<Error>) {
285        self.offsets_error = error;
286    }
287
288    /// Sets the maximum number of records returned in a single call to
289    /// [`Consumer::poll`].
290    ///
291    /// # Arguments
292    ///
293    /// - `max_poll_records` - the max.poll.records.
294    ///
295    /// # Errors
296    ///
297    /// - `Error::is_local_illegal_argument_error` if `max_poll_records` is less than 1
298    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#setMaxPollRecords")]
299    pub fn set_max_poll_records(&mut self, max_poll_records: i64) -> Result<(), Error> {
300        if max_poll_records < 1 {
301            return Err(Error::local_illegal_argument("MaxPollRecords must be strictly superior to 0"));
302        }
303        self.max_poll_records = max_poll_records;
304        Ok(())
305    }
306
307    /// Simulate a rebalance event.
308    ///
309    /// # Arguments
310    ///
311    /// - `new_assignment` - the new assignment
312    ///
313    /// # Errors
314    ///
315    /// - The error the listener returns.
316    /// - `Error::is_local_illegal_argument_error` if a partition is not of a subscribed topic
317    // Async because the Rust listener methods are `async fn`
318    // (`consumer-threading.md` §31); Java's listener methods are sync.
319    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#rebalance")]
320    pub fn rebalance(&mut self, new_assignment: &[TopicPartition]) -> impl Future<Output = Result<(), Error>> + Send
321    where
322        K: Send,
323        V: Send,
324    {
325        async move {
326            let old_assignment_set = self.subs().assigned_partitions();
327            let new_assignment_set: HashSet<TopicPartition> = new_assignment.iter().cloned().collect();
328
329            let added: Vec<TopicPartition> = new_assignment
330                .iter()
331                .filter(|tp| !old_assignment_set.contains(tp))
332                .cloned()
333                .collect();
334            let removed: Vec<TopicPartition> = old_assignment_set
335                .iter()
336                .filter(|tp| !new_assignment_set.contains(tp))
337                .cloned()
338                .collect();
339
340            // Clear buffered records (Java: `records.clear()`).
341            self.records.clear();
342
343            // Invoke onPartitionsRevoked first. Per
344            // consumer-threading.md §16, clone the Arc out before awaiting.
345            let listener = self.subs().rebalance_listener();
346            if !removed.is_empty()
347                && let Some(listener) = listener
348            {
349                listener.on_partitions_revoked(&removed).await?;
350            }
351
352            // Replace assignment (Java:
353            // `subscriptions.assignFromSubscribed(newAssignment)`).
354            self.subs().assign_from_subscribed(new_assignment)?;
355
356            // Invoke onPartitionsAssigned. Java passes only the
357            // *added* partitions, not the full new assignment.
358            let listener = self.subs().rebalance_listener();
359            if let Some(listener) = listener {
360                listener.on_partitions_assigned(&added).await?;
361            }
362
363            Ok(())
364        }
365    }
366
367    /// Simulates a partition loss event. Calls
368    /// [`ConsumerRebalanceListener::on_partitions_lost`] for the specified
369    /// partitions and removes them from the current assignment. Unlike
370    /// [`Self::rebalance`], which calls
371    /// [`ConsumerRebalanceListener::on_partitions_revoked`], this method models
372    /// the case where the consumer loses partitions without a graceful revoke.
373    ///
374    /// Only records belonging to the lost partitions are cleared; records for
375    /// retained partitions are unaffected.
376    ///
377    /// # Arguments
378    ///
379    /// - `partitions_lost` - the partitions to lose; all must be currently assigned
380    ///
381    /// # Errors
382    ///
383    /// - `Error::is_local_illegal_state_error` if any partition is not currently assigned
384    /// - The error the listener returns; the assignment is then left unchanged.
385    ///
386    /// [`ConsumerRebalanceListener::on_partitions_lost`]: crate::consumer::ConsumerRebalanceListener::on_partitions_lost
387    /// [`ConsumerRebalanceListener::on_partitions_revoked`]: crate::consumer::ConsumerRebalanceListener::on_partitions_revoked
388    // Async for the same reason as `rebalance`. Java hands the listener a
389    // `Set`; the lost partitions are passed deduplicated, in the order given.
390    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#losePartitions")]
391    pub fn lose_partitions(
392        &mut self,
393        partitions_lost: &[TopicPartition],
394    ) -> impl Future<Output = Result<(), Error>> + Send
395    where
396        K: Send,
397        V: Send,
398    {
399        async move {
400            let current_assignment = self.subs().assigned_partitions();
401            let mut lost: Vec<TopicPartition> = Vec::with_capacity(partitions_lost.len());
402            for tp in partitions_lost {
403                if !lost.contains(tp) {
404                    lost.push(tp.clone());
405                }
406            }
407            let not_assigned: Vec<String> = lost
408                .iter()
409                .filter(|tp| !current_assignment.contains(*tp))
410                .map(ToString::to_string)
411                .collect();
412            if !not_assigned.is_empty() {
413                // Java formats the `List` with `toString()`: `[test-1, test-2]`.
414                return Err(Error::local_illegal_state(format!(
415                    "Cannot lose partitions that are not currently assigned: [{}]",
416                    not_assigned.join(", ")
417                )));
418            }
419            for tp in &lost {
420                self.records.remove(tp);
421            }
422            // Clone the listener `Arc` out, dropping the guard, before awaiting
423            // (consumer-threading.md §16).
424            let listener = self.subs().rebalance_listener();
425            if let Some(listener) = listener {
426                listener.on_partitions_lost(&lost).await?;
427            }
428            let remaining: Vec<TopicPartition> =
429                current_assignment.into_iter().filter(|tp| !lost.contains(tp)).collect();
430            self.subs().assign_from_subscribed(&remaining)
431        }
432    }
433
434    /// Schedule a task to be executed during a poll(). One enqueued task will
435    /// be executed per [`Consumer::poll`] invocation. You can use this
436    /// repeatedly to mock out multiple responses to poll invocations.
437    ///
438    /// # Arguments
439    ///
440    /// - `task` - the task to be executed
441    ///
442    /// # Translation notes
443    ///
444    /// The task is called with the mock, `&mut MockConsumer<K, V>`, which a
445    /// Rust closure cannot capture.
446    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#schedulePollTask")]
447    pub fn schedule_poll_task(&mut self, task: PollTask<K, V>) {
448        self.poll_tasks.push_back(task);
449    }
450
451    /// Schedules a no-op task to be executed during a poll invocation.
452    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#scheduleNopPollTask")]
453    pub fn schedule_nop_poll_task(&mut self) {
454        self.schedule_poll_task(Box::new(|_| {}));
455    }
456
457    /// Return whether the consumer has been closed.
458    ///
459    /// # Returns
460    ///
461    /// true if closed, false otherwise
462    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#closed")]
463    pub fn closed(&self) -> bool {
464        self.closed.load(Ordering::SeqCst)
465    }
466
467    /// Return whether an `enforceRebalance` request is pending.
468    ///
469    /// # Returns
470    ///
471    /// true if rebalance is pending, false otherwise
472    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#shouldRebalance")]
473    pub fn should_rebalance(&self) -> bool {
474        self.should_rebalance.load(Ordering::SeqCst)
475    }
476
477    /// Resets the rebalance flag set by [`Consumer::enforce_rebalance`].
478    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#resetShouldRebalance")]
479    pub fn reset_should_rebalance(&mut self) {
480        self.should_rebalance.store(false, Ordering::SeqCst);
481    }
482
483    /// Returns the timeout used in the last [`Consumer::poll`] call.
484    ///
485    /// # Returns
486    ///
487    /// the last poll timeout, or None if poll has not been called
488    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#lastPollTimeout")]
489    pub fn last_poll_timeout(&self) -> Option<Duration> {
490        *self.last_poll_timeout.lock().unwrap_or_else(PoisonError::into_inner)
491    }
492
493    // ── Internal helpers (used by both inherent + Consumer impls) ───────
494
495    /// Mirrors Java's `ensureNotClosed`. Java throws
496    /// `IllegalStateException("This consumer has already been closed.")`.
497    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#ensureNotClosed")]
498    fn ensure_not_closed(&self) -> Result<(), Error> {
499        ensure_mock_not_closed(&self.closed)
500    }
501
502    /// The shared committed-offsets map, locked for a read or a merge.
503    fn lock_committed(&self) -> std::sync::MutexGuard<'_, HashMap<TopicPartition, OffsetAndMetadata>> {
504        self.committed.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
505    }
506
507    /// Locks the shared `SubscriptionState`. Each caller drops the guard
508    /// before awaiting or invoking a listener (`consumer-threading.md` §16),
509    /// and never locks it twice in one expression: the mutex is not
510    /// reentrant.
511    fn subs(&self) -> std::sync::MutexGuard<'_, SubscriptionState> {
512        self.subscriptions.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
513    }
514
515    /// Mirrors Java's private
516    /// `subscribe(Collection<String>, Optional<ConsumerRebalanceListener>)`
517    /// (`org.apache.kafka.clients.consumer.MockConsumer#subscribe`).
518    fn subscribe_internal_topics(
519        &mut self,
520        topics: Vec<String>,
521        listener: Option<Arc<dyn ConsumerRebalanceListener>>,
522    ) -> Result<(), Error> {
523        self.ensure_not_closed()?;
524        self.lock_committed().clear();
525        self.subs().subscribe_with_topics(topics.into_iter().collect(), listener)?;
526        Ok(())
527    }
528
529    // Java's private `subscribe(Pattern, Optional<ConsumerRebalanceListener>)`
530    // (`org.apache.kafka.clients.consumer.MockConsumer#subscribe`) has no Rust counterpart: the two public
531    // `subscribe(Pattern ...)` overloads it serves are deliberately NOT
532    // implemented (see `Consumer`), so the client-side matching loop it
533    // contained has no caller. Only the `SubscriptionPattern` form below is
534    // translated.
535
536    /// Mirrors Java's private
537    /// `subscribe(SubscriptionPattern, Optional<ConsumerRebalanceListener>)`
538    /// (`org.apache.kafka.clients.consumer.MockConsumer#subscribe`).
539    fn subscribe_internal_subscription_pattern(
540        &mut self,
541        pattern: SubscriptionPattern,
542        listener: Option<Arc<dyn ConsumerRebalanceListener>>,
543    ) -> Result<(), Error> {
544        // Java rejects an empty pattern. Java also rejects
545        // `null`, which Rust's non-`Option` parameter makes unrepresentable,
546        // so only the "empty" half of the message can be produced.
547        if pattern.pattern().is_empty() {
548            return Err(Error::local_illegal_argument("Topic pattern cannot be empty"));
549        }
550        self.ensure_not_closed()?;
551        self.lock_committed().clear();
552        self.subs().subscribe_with_pattern(pattern, listener)?;
553        Ok(())
554    }
555
556    /// Mirrors Java's `updateFetchPosition(TopicPartition)`
557    /// (`org.apache.kafka.clients.consumer.MockConsumer#updateFetchPosition`).
558    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#updateFetchPosition")]
559    fn update_fetch_position(&mut self, tp: &TopicPartition) -> Result<(), Error> {
560        if self.subs().is_offset_reset_needed(tp)? {
561            self.reset_offset_position(tp)
562        } else {
563            let committed_offset = self.lock_committed().get(tp).map(OffsetAndMetadata::offset);
564            match committed_offset {
565                None => {
566                    self.subs().request_offset_reset_default(tp)?;
567                    self.reset_offset_position(tp)
568                },
569                Some(offset) => self.subs().seek(tp, offset),
570            }
571        }
572    }
573
574    /// Mirrors Java's `resetOffsetPosition(TopicPartition)`
575    /// (`org.apache.kafka.clients.consumer.MockConsumer#resetOffsetPosition`). Picks the source map by the
576    /// partition's reset strategy and `seek`s to the configured offset.
577    /// Returns [`Error::LocalIllegalState`] when the map does not have an
578    /// entry for the partition (Java throws `IllegalStateException`), or
579    /// [`Error::ConsumerNoOffsetForPartition`](crate::common::Error::ConsumerNoOffsetForPartition)
580    /// (Java's `NoOffsetForPartitionException`) when the strategy is `None`.
581    #[doc(alias = "org.apache.kafka.clients.consumer.MockConsumer#resetOffsetPosition")]
582    fn reset_offset_position(&mut self, tp: &TopicPartition) -> Result<(), Error> {
583        let strategy = self.subs().reset_strategy(tp)?.unwrap_or(AutoOffsetResetStrategy::NONE);
584
585        if strategy == AutoOffsetResetStrategy::EARLIEST {
586            let offset = self.beginning_offsets.get(tp).copied().ok_or_else(|| {
587                Error::local_illegal_state(
588                    "MockConsumer didn't have beginning offset specified, but tried to seek to beginning",
589                )
590            })?;
591            self.subs().seek(tp, offset)
592        } else if strategy == AutoOffsetResetStrategy::LATEST {
593            let offset = self.end_offsets_lock().get(tp).copied().ok_or_else(|| {
594                Error::local_illegal_state("MockConsumer didn't have end offset specified, but tried to seek to end")
595            })?;
596            self.subs().seek(tp, offset)
597        } else if strategy.type_() == StrategyType::ByDuration {
598            let offset = self.duration_reset_offsets.get(tp).copied().ok_or_else(|| {
599                Error::local_illegal_state(
600                    "MockConsumer didn't have duration offset specified, but tried to seek to timestamp",
601                )
602            })?;
603            self.subs().seek(tp, offset)
604        } else {
605            // strategy == NONE
606            Err(crate::consumer::Error::ConsumerNoOffsetForPartition(
607                ConsumerNoOffsetForPartitionError::new(tp.clone()),
608            ))
609        }
610    }
611}
612
613/// Rust-only: releases the rebalance listener. A listener that captured
614/// [`Consumer::handle`] holds the shared `SubscriptionState` through the
615/// handle, and that state stores the listener, so without this the cycle would
616/// outlive the mock; Java's garbage collector frees the same graph. The
617/// release waits for the drop rather than `close()`, because Java's
618/// `rebalance` and `losePartitions` still run the listener on a closed mock
619/// (`org.apache.kafka.clients.consumer.MockConsumer#rebalance` and `org.apache.kafka.clients.consumer.MockConsumer#losePartitions` make no `ensureNotClosed()` check).
620impl<K, V> Drop for MockConsumer<K, V> {
621    fn drop(&mut self) {
622        self.subs().register_rebalance_listener(None);
623    }
624}
625
626// ─── Consumer<K, V> trait impl ──────────────────────────────────────────
627
628impl<K, V> Consumer<K, V> for MockConsumer<K, V>
629where
630    K: Send + 'static,
631    V: Send + 'static,
632{
633    // ── Sync accessors ─────────────────────────────────────────────────
634
635    // Java's `assignment()`, `subscription()`, `paused()` and
636    // `groupMetadata()` do not call `ensureNotClosed()`, so these answer on a
637    // closed mock too.
638
639    fn assignment(&mut self) -> HashSet<TopicPartition> {
640        self.subs().assigned_partitions()
641    }
642
643    fn subscription(&mut self) -> HashSet<String> {
644        self.subs().subscription()
645    }
646
647    fn paused(&mut self) -> HashSet<TopicPartition> {
648        // Java's `MockConsumer#paused` returns a copy of `paused`.
649        self.paused.lock().unwrap_or_else(PoisonError::into_inner).clone()
650    }
651
652    fn group_metadata(&mut self) -> Arc<dyn ConsumerGroupMetadata> {
653        mock_group_metadata()
654    }
655
656    /// Returns an empty view: the mock keeps no metrics.
657    ///
658    /// # Panics
659    ///
660    /// Panics with `"This consumer has already been closed."` on a closed
661    /// mock, where Java's `ensureNotClosed()` throws `IllegalStateException`:
662    /// calling it after `close()` is a programming error.
663    fn metrics(&self) -> MetricsView {
664        if let Err(error) = self.ensure_not_closed() {
665            panic!("{}", error.message());
666        }
667        MetricsView::default()
668    }
669
670    /// Returns the end offset set by [`MockConsumer::update_end_offsets`] minus
671    /// the position, or `0` when no end offset was set.
672    ///
673    /// # Arguments
674    ///
675    /// - `topic_partition` - The partition to get the lag for.
676    ///
677    /// # Errors
678    ///
679    /// - The error of [`Consumer::position`] (a closed mock, an unassigned partition).
680    // `org.apache.kafka.clients.consumer.MockConsumer#currentLag`:
681    // `endOffsets.get(tp) - position(tp)`, `position(tp)` seeding a missing
682    // position as Java's `updateFetchPosition` does.
683    async fn current_lag(&mut self, topic_partition: &TopicPartition) -> Result<Option<i64>, Error> {
684        let end = self.end_offsets_lock().get(topic_partition).copied();
685        match end {
686            Some(end) => Ok(Some(end - Consumer::position(self, topic_partition).await?)),
687            // If the test doesn't bother to set an end offset, we assume it
688            // wants to model being caught up.
689            None => Ok(Some(0)),
690        }
691    }
692
693    // ── Subscription / assignment ──────────────────────────────────────
694
695    async fn subscribe_with_topics(&mut self, topics: Vec<String>) -> Result<(), Error> {
696        self.subscribe_internal_topics(topics, None)
697    }
698
699    async fn subscribe_with_topics_listener(
700        &mut self,
701        topics: Vec<String>,
702        listener: Arc<dyn ConsumerRebalanceListener>,
703    ) -> Result<(), Error> {
704        self.subscribe_internal_topics(topics, Some(listener))
705    }
706
707    async fn subscribe_with_pattern(&mut self, pattern: SubscriptionPattern) -> Result<(), Error> {
708        self.subscribe_internal_subscription_pattern(pattern, None)
709    }
710
711    async fn subscribe_with_pattern_listener(
712        &mut self,
713        pattern: SubscriptionPattern,
714        listener: Arc<dyn ConsumerRebalanceListener>,
715    ) -> Result<(), Error> {
716        self.subscribe_internal_subscription_pattern(pattern, Some(listener))
717    }
718
719    async fn assign(&mut self, partitions: Vec<TopicPartition>) -> Result<(), Error> {
720        // Java `MockConsumer#assign`.
721        self.ensure_not_closed()?;
722        self.lock_committed().clear();
723        self.subs().assign_from_user(partitions.into_iter().collect())?;
724        Ok(())
725    }
726
727    async fn unsubscribe(&mut self) -> Result<(), Error> {
728        // Java `MockConsumer#unsubscribe`.
729        self.ensure_not_closed()?;
730        self.lock_committed().clear();
731        self.subs().unsubscribe();
732        Ok(())
733    }
734
735    // ── Poll ────────────────────────────────────────────────────────────
736
737    // `org.apache.kafka.clients.consumer.MockConsumer#poll(Duration)`.
738    async fn poll(&mut self, timeout: Duration) -> Result<ConsumerRecords<K, V>, Error> {
739        // Step 1: ensureNotClosed.
740        self.ensure_not_closed()?;
741
742        // Step 2: record the timeout.
743        *self.last_poll_timeout.lock().unwrap_or_else(PoisonError::into_inner) = Some(timeout);
744
745        // Step 3: drain one queued poll task. Pop with
746        // pop_front then invoke with &mut self — the task may schedule more
747        // tasks, but only one is consumed per poll call.
748        if let Some(task) = self.poll_tasks.pop_front() {
749            task(self);
750        }
751
752        // Step 4: check wakeup flag and clear it.
753        if self
754            .wakeup
755            .compare_exchange(true, false, Ordering::SeqCst, Ordering::SeqCst)
756            .is_ok()
757        {
758            return Err(Error::wakeup("Mock consumer was woken up"));
759        }
760
761        // Step 5: take poll exception.
762        if let Some(error) = self.poll_error.take() {
763            return Err(error);
764        }
765
766        // Step 6: update fetch positions for newly-assigned partitions that
767        // do not yet have a valid position.
768        let assigned: Vec<TopicPartition> = self.subs().assigned_partitions().into_iter().collect();
769        for tp in &assigned {
770            if !self.subs().has_valid_position(tp) {
771                self.update_fetch_position(tp)?;
772            }
773        }
774
775        // Step 7: drain records up to max_poll_records.
776        // Java iterates `records.entrySet()` with mutation; we collect the
777        // partition keys first to avoid simultaneous mutable borrows.
778        let mut results: IndexMap<TopicPartition, Vec<ConsumerRecord<K, V>>> = IndexMap::new();
779        let mut next_offset_and_metadata: HashMap<TopicPartition, OffsetAndMetadata> = HashMap::new();
780        let mut num_poll_records: i64 = 0;
781
782        // Snapshot the partition keys in insertion order — match Java which
783        // iterates the HashMap.entrySet() in whatever order Java's HashMap
784        // produces. Test ordering does not depend on this.
785        let partition_keys: Vec<TopicPartition> = self.records.keys().cloned().collect();
786
787        for tp in partition_keys {
788            if num_poll_records >= self.max_poll_records {
789                break;
790            }
791            // AK 4.3.1: skip the whole partition if it is paused OR not
792            // assigned. Java moved the `isAssigned` check up to the partition
793            // level (`!subscriptions.isPaused(tp) && subscriptions.isAssigned(tp)`)
794            // and dropped the per-record `assignment().contains(tp)` check.
795            let skip = {
796                let subs = self.subs();
797                subs.is_paused(&tp) || !subs.is_assigned(&tp)
798            };
799            if skip {
800                continue;
801            }
802
803            // Java's recIterator removes records in place; we take ownership
804            // of the partition's record list, drain it, and put the remainder
805            // back if any records are left.
806            let mut recs = self.records.remove(&tp).expect("key from records.keys()");
807            let mut kept: Vec<ConsumerRecord<K, V>> = Vec::new();
808            let mut iter = recs.drain(..);
809            while let Some(rec) = iter.next() {
810                if num_poll_records >= self.max_poll_records {
811                    // Push back the un-iterated remainder.
812                    kept.push(rec);
813                    kept.extend(iter);
814                    break;
815                }
816
817                // Read the current position. position_or_null returns the
818                // FetchPosition; we need its offset.
819                let position_opt = self.subs().position_or_null(&tp).map(|p| p.offset);
820                let Some(position) = position_opt else {
821                    // No valid position — preserve Java's behavior:
822                    // `subscriptions.position(...).offset` would NPE in Java
823                    // if position were null, but Java's loop only reaches
824                    // here AFTER updateFetchPosition has been called on the
825                    // partition (Step 6). If the partition has no position
826                    // here, it means the position was unset; skip the record.
827                    kept.push(rec);
828                    kept.extend(iter);
829                    break;
830                };
831
832                // OffsetOutOfRange check: if a beginning
833                // offset is configured and position is before it, throw.
834                if let Some(&begin) = self.beginning_offsets.get(&tp)
835                    && begin > position
836                {
837                    let mut m = HashMap::new();
838                    m.insert(tp.clone(), position);
839                    // Put the un-iterated remainder back BEFORE returning so
840                    // a subsequent poll sees the same record at the same
841                    // position.
842                    kept.push(rec);
843                    kept.extend(iter);
844                    self.records.insert(tp, kept);
845                    return Err(crate::consumer::Error::ConsumerOffsetOutOfRange(
846                        ConsumerOffsetOutOfRangeError::new(m),
847                    ));
848                }
849
850                // AK 4.3.1 (MockConsumer): the per-partition `isAssigned`
851                // check now sits at the entry level above, so the per-record
852                // guard is just `rec.offset() >= position`.
853                if rec.offset() >= position {
854                    let leader_epoch = rec.leader_epoch();
855                    let next_offset = rec.offset() + 1;
856
857                    // Push the record onto the result list.
858                    results.entry(tp.clone()).or_default().push(rec);
859
860                    // Update the partition's fetch position, as Java's
861                    // `MockConsumer#poll` does. Java uses `subscriptions.position(entry, fp)`
862                    // (not `seek`), which requires a valid current position.
863                    let leader_and_epoch = LeaderAndEpoch::new(None, leader_epoch);
864                    let new_position = FetchPosition::with_leader(next_offset, leader_epoch, leader_and_epoch);
865                    self.subs().set_position(&tp, new_position)?;
866
867                    // Build the next-offsets entry.
868                    let oam = OffsetAndMetadata::with_leader_epoch_metadata(next_offset, leader_epoch, String::new())?;
869                    next_offset_and_metadata.insert(tp.clone(), oam);
870
871                    num_poll_records += 1;
872                } else {
873                    // Java's loop simply does NOT remove the record (no
874                    // `recIterator.remove()` call). Keep it for the next poll.
875                    kept.push(rec);
876                }
877            }
878
879            // Drop empty entries from the records map, as Java does.
880            if !kept.is_empty() {
881                self.records.insert(tp, kept);
882            }
883            // If kept is empty, the entry was implicitly removed by the
884            // `remove` above — no further action needed.
885        }
886
887        Ok(ConsumerRecords::with_next_offsets(results, next_offset_and_metadata))
888    }
889
890    // ── Commit ─────────────────────────────────────────────────────────
891
892    async fn commit_sync(&mut self) -> Result<(), Error> {
893        // Java's `commitSync()` (`org.apache.kafka.clients.consumer.MockConsumer#commitSync`) reads
894        // `allConsumed()` BEFORE the closed check —
895        // `commitSync(allConsumed())` → `commitSync(Map)` →
896        // `commitAsync(offsets, null)`, where
897        // `ensureNotClosed()` is finally called. We tighten by checking
898        // closed first: end behavior is identical (both error when the
899        // consumer is closed) but Rust skips the wasted subscription-map
900        // traversal.
901        self.ensure_not_closed()?;
902        let offsets = self.subs().all_consumed();
903        self.commit_async_impl(offsets, None).await
904    }
905
906    async fn commit_sync_with_timeout(&mut self, _timeout: Duration) -> Result<(), Error> {
907        // Java's `commitSync(Duration)` ignores the timeout.
908        self.commit_sync().await
909    }
910
911    async fn commit_sync_with_offsets(
912        &mut self,
913        offsets: HashMap<TopicPartition, OffsetAndMetadata>,
914    ) -> Result<(), Error> {
915        // Java's `commitSync(Map)` delegates to `commitAsync`.
916        self.commit_async_impl(offsets, None).await
917    }
918
919    async fn commit_sync_with_offsets_timeout(
920        &mut self,
921        offsets: HashMap<TopicPartition, OffsetAndMetadata>,
922        _timeout: Duration,
923    ) -> Result<(), Error> {
924        // Java's `commitSync(Map, Duration)` ignores the timeout.
925        self.commit_sync_with_offsets(offsets).await
926    }
927
928    async fn commit_async(&mut self) -> Result<(), Error> {
929        // Java's `commitAsync()` → `commitAsync(OffsetCommitCallback)`, which `ensureNotClosed()`s BEFORE
930        // reading `allConsumed()`. Mirror that ordering so a closed consumer
931        // errors out without traversing the subscription map.
932        self.ensure_not_closed()?;
933        let offsets = self.subs().all_consumed();
934        self.commit_async_impl(offsets, None).await
935    }
936
937    async fn commit_async_with_callback(&mut self, callback: Arc<dyn OffsetCommitCallback>) -> Result<(), Error> {
938        // Java's `commitAsync(OffsetCommitCallback)` calls `ensureNotClosed()` BEFORE `allConsumed()`.
939        // Rust relies on `commit_async_impl`'s check at the cost of a wasted
940        // `all_consumed()` traversal when the consumer is already closed.
941        // Keeping the check only in `commit_async_impl` removes the redundant
942        // double-check the previous code had. (Unlike `commit_sync` /
943        // `commit_async`, which deliberately pre-check to skip that traversal,
944        // this path is left as-is because all `*_offsets` / callback variants
945        // funnel into `commit_async_impl` for the single closed check.)
946        let offsets = self.subs().all_consumed();
947        self.commit_async_impl(offsets, Some(callback)).await
948    }
949
950    async fn commit_async_with_offsets_callback(
951        &mut self,
952        offsets: HashMap<TopicPartition, OffsetAndMetadata>,
953        callback: Arc<dyn OffsetCommitCallback>,
954    ) -> Result<(), Error> {
955        // Java `MockConsumer#commitAsync(Map, OffsetCommitCallback)`.
956        self.commit_async_impl(offsets, Some(callback)).await
957    }
958
959    // ── Seek ───────────────────────────────────────────────────────────
960
961    async fn seek_with_offset(&mut self, partition: TopicPartition, offset: i64) -> Result<(), Error> {
962        // Java `MockConsumer#seek(TopicPartition, long)`.
963        self.ensure_not_closed()?;
964        self.subs().seek(&partition, offset)?;
965        Ok(())
966    }
967
968    async fn seek_with_offset_and_metadata(
969        &mut self,
970        partition: TopicPartition,
971        offset_and_metadata: OffsetAndMetadata,
972    ) -> Result<(), Error> {
973        // Java `MockConsumer#seek(TopicPartition, OffsetAndMetadata)`.
974        self.ensure_not_closed()?;
975        self.subs().seek(&partition, offset_and_metadata.offset())?;
976        Ok(())
977    }
978
979    async fn seek_to_beginning(&mut self, partitions: &[TopicPartition]) -> Result<(), Error> {
980        // Java `MockConsumer#seekToBeginning`.
981        self.ensure_not_closed()?;
982        self.subs()
983            .request_offset_reset_all(partitions, AutoOffsetResetStrategy::EARLIEST)?;
984        Ok(())
985    }
986
987    async fn seek_to_end(&mut self, partitions: &[TopicPartition]) -> Result<(), Error> {
988        // Java `MockConsumer#seekToEnd`.
989        self.ensure_not_closed()?;
990        self.subs()
991            .request_offset_reset_all(partitions, AutoOffsetResetStrategy::LATEST)?;
992        Ok(())
993    }
994
995    // ── Position / committed ───────────────────────────────────────────
996
997    async fn position(&mut self, partition: &TopicPartition) -> Result<i64, Error> {
998        // Java `MockConsumer#position(TopicPartition)`.
999        self.ensure_not_closed()?;
1000        if !self.subs().is_assigned(partition) {
1001            return Err(Error::local_illegal_argument(POSITION_NOT_ASSIGNED_MSG));
1002        }
1003        // First read; if absent, refresh via update_fetch_position and re-read.
1004        let pos = self.subs().position_or_null(partition).map(|p| p.offset);
1005        if let Some(off) = pos {
1006            return Ok(off);
1007        }
1008        self.update_fetch_position(partition)?;
1009        let pos = self.subs().position_or_null(partition).map(|p| p.offset).ok_or_else(|| {
1010            Error::local_illegal_state(format!(
1011                "Position for partition {partition} is still unset after update_fetch_position",
1012            ))
1013        })?;
1014        Ok(pos)
1015    }
1016
1017    async fn position_with_timeout(&mut self, partition: &TopicPartition, _timeout: Duration) -> Result<i64, Error> {
1018        // Java's `position(TopicPartition, Duration)` ignores the timeout.
1019        self.position(partition).await
1020    }
1021
1022    async fn committed(
1023        &mut self,
1024        partitions: &[TopicPartition],
1025    ) -> Result<HashMap<TopicPartition, Option<OffsetAndMetadata>>, Error> {
1026        // Java `MockConsumer#committed(Set)`.
1027        self.ensure_not_closed()?;
1028        let mut result = HashMap::new();
1029        let committed = self.lock_committed();
1030        let subs = self.subs();
1031        for tp in partitions {
1032            if let Some(om) = committed.get(tp) {
1033                // Java: `subscriptions.isAssigned(tp) ? committed.get(tp) : new OffsetAndMetadata(0)`.
1034                let value = if subs.is_assigned(tp) {
1035                    om.clone()
1036                } else {
1037                    // `OffsetAndMetadata::new(0)` is infallible for offset=0.
1038                    OffsetAndMetadata::new(0).expect("0 is non-negative")
1039                };
1040                result.insert(tp.clone(), Some(value));
1041            }
1042        }
1043        Ok(result)
1044    }
1045
1046    async fn committed_with_timeout(
1047        &mut self,
1048        partitions: &[TopicPartition],
1049        _timeout: Duration,
1050    ) -> Result<HashMap<TopicPartition, Option<OffsetAndMetadata>>, Error> {
1051        // Java's `committed(Set, Duration)` ignores the timeout.
1052        self.committed(partitions).await
1053    }
1054
1055    // ── Metadata ───────────────────────────────────────────────────────
1056
1057    async fn partitions_for(&mut self, topic: &str) -> Result<Vec<PartitionInfo>, Error> {
1058        // Java `MockConsumer#partitionsFor(String)`.
1059        self.ensure_not_closed()?;
1060        Ok(self.partitions.get(topic).cloned().unwrap_or_default())
1061    }
1062
1063    async fn partitions_for_with_timeout(
1064        &mut self,
1065        topic: &str,
1066        _timeout: Duration,
1067    ) -> Result<Vec<PartitionInfo>, Error> {
1068        // Java `MockConsumer#partitionsFor(String, Duration)`.
1069        self.partitions_for(topic).await
1070    }
1071
1072    async fn list_topics(&mut self) -> Result<HashMap<String, Vec<PartitionInfo>>, Error> {
1073        // Java `MockConsumer#listTopics()` returns the internal map reference; Rust
1074        // returns a clone so the caller is not exposed to subsequent
1075        // mutations of the mock's state.
1076        self.ensure_not_closed()?;
1077        Ok(self.partitions.clone())
1078    }
1079
1080    async fn list_topics_with_timeout(
1081        &mut self,
1082        _timeout: Duration,
1083    ) -> Result<HashMap<String, Vec<PartitionInfo>>, Error> {
1084        // Java `MockConsumer#listTopics(Duration)`.
1085        self.list_topics().await
1086    }
1087
1088    async fn offsets_for_times(
1089        &mut self,
1090        _timestamps_to_search: HashMap<TopicPartition, i64>,
1091    ) -> Result<HashMap<TopicPartition, Option<OffsetAndTimestamp>>, Error> {
1092        // Java throws UnsupportedOperationException("Not implemented yet.")
1093        // (`org.apache.kafka.clients.consumer.MockConsumer#offsetsForTimes`), translated as Error::LocalUnsupportedOperation
1094        // (`admin-client.md` §9). DoD #3 makes the message text part of the
1095        // contract, so the text is Java's verbatim rather than a Rust-side
1096        // restatement.
1097        Err(Error::local_unsupported_operation("Not implemented yet."))
1098    }
1099
1100    async fn offsets_for_times_with_timeout(
1101        &mut self,
1102        timestamps_to_search: HashMap<TopicPartition, i64>,
1103        _timeout: Duration,
1104    ) -> Result<HashMap<TopicPartition, Option<OffsetAndTimestamp>>, Error> {
1105        // Java's `offsetsForTimes(Map, Duration)` delegates to the no-timeout variant.
1106        self.offsets_for_times(timestamps_to_search).await
1107    }
1108
1109    async fn beginning_offsets(
1110        &mut self,
1111        partitions: &[TopicPartition],
1112    ) -> Result<HashMap<TopicPartition, i64>, Error> {
1113        // Java `MockConsumer#beginningOffsets(Collection)`.
1114        if let Some(error) = self.offsets_error.take() {
1115            return Err(error);
1116        }
1117        let mut result = HashMap::new();
1118        for tp in partitions {
1119            let off = self.beginning_offsets.get(tp).copied().ok_or_else(|| {
1120                Error::local_illegal_state(format!("The partition {tp} does not have a beginning offset."))
1121            })?;
1122            result.insert(tp.clone(), off);
1123        }
1124        Ok(result)
1125    }
1126
1127    async fn beginning_offsets_with_timeout(
1128        &mut self,
1129        partitions: &[TopicPartition],
1130        _timeout: Duration,
1131    ) -> Result<HashMap<TopicPartition, i64>, Error> {
1132        // Java `MockConsumer#beginningOffsets(Collection, Duration)`.
1133        self.beginning_offsets(partitions).await
1134    }
1135
1136    async fn end_offsets(&mut self, partitions: &[TopicPartition]) -> Result<HashMap<TopicPartition, i64>, Error> {
1137        // Java `MockConsumer#endOffsets(Collection)`.
1138        if let Some(error) = self.offsets_error.take() {
1139            return Err(error);
1140        }
1141        let mut result = HashMap::new();
1142        let end_offsets = self.end_offsets_lock();
1143        for tp in partitions {
1144            let off = end_offsets.get(tp).copied().ok_or_else(|| {
1145                Error::local_illegal_state(format!("The partition {tp} does not have an end offset."))
1146            })?;
1147            result.insert(tp.clone(), off);
1148        }
1149        Ok(result)
1150    }
1151
1152    async fn end_offsets_with_timeout(
1153        &mut self,
1154        partitions: &[TopicPartition],
1155        _timeout: Duration,
1156    ) -> Result<HashMap<TopicPartition, i64>, Error> {
1157        // Java `MockConsumer#endOffsets(Collection, Duration)`.
1158        self.end_offsets(partitions).await
1159    }
1160
1161    // ── Pause / resume ─────────────────────────────────────────────────
1162
1163    async fn pause(&mut self, partitions: &[TopicPartition]) -> Result<(), Error> {
1164        // Java `MockConsumer#pause`.
1165        for tp in partitions {
1166            self.subs().pause(tp)?;
1167            self.paused.lock().unwrap_or_else(PoisonError::into_inner).insert(tp.clone());
1168        }
1169        Ok(())
1170    }
1171
1172    async fn resume(&mut self, partitions: &[TopicPartition]) -> Result<(), Error> {
1173        // Java `MockConsumer#resume`.
1174        for tp in partitions {
1175            self.subs().resume(tp)?;
1176            self.paused.lock().unwrap_or_else(PoisonError::into_inner).remove(tp);
1177        }
1178        Ok(())
1179    }
1180
1181    // ── Lifecycle ──────────────────────────────────────────────────────
1182
1183    async fn enforce_rebalance(&mut self) -> Result<(), Error> {
1184        // Java's `enforceRebalance()` forwards to
1185        // `enforceRebalance(null)`; Rust's suffixed form takes a non-null
1186        // `&str`, so the flag is set directly here instead.
1187        self.should_rebalance.store(true, Ordering::SeqCst);
1188        Ok(())
1189    }
1190
1191    async fn enforce_rebalance_with_reason(&mut self, _reason: &str) -> Result<(), Error> {
1192        // Java's `enforceRebalance(String)` sets the flag; the reason is ignored.
1193        self.should_rebalance.store(true, Ordering::SeqCst);
1194        Ok(())
1195    }
1196
1197    async fn close(&mut self) -> Result<(), Error> {
1198        // Java's `close()` delegates to
1199        // `close(CloseOptions.timeout(Duration.ofMillis(DEFAULT_CLOSE_TIMEOUT_MS)))`.
1200        self.close_with_options(CloseOptions::new_with_timeout(Duration::from_millis(
1201            crate::consumer::internals::ConsumerUtils::DEFAULT_CLOSE_TIMEOUT_MS as u64,
1202        )))
1203        .await
1204    }
1205
1206    async fn close_with_options(&mut self, _options: CloseOptions) -> Result<(), Error> {
1207        // Java's `close(CloseOptions)` ignores the options.
1208        self.closed.store(true, Ordering::SeqCst);
1209        Ok(())
1210    }
1211
1212    fn wakeup(&self) {
1213        // Java's `wakeup()` sets the flag.
1214        self.wakeup.store(true, Ordering::SeqCst);
1215    }
1216
1217    fn handle(&self) -> ConsumerHandle {
1218        ConsumerHandle::for_mock(
1219            Arc::clone(&self.wakeup),
1220            Arc::clone(&self.closed),
1221            Arc::clone(&self.should_rebalance),
1222            Arc::clone(&self.last_poll_timeout),
1223            Arc::clone(&self.committed),
1224            Arc::clone(&self.subscriptions),
1225            Arc::clone(&self.paused),
1226            Arc::clone(&self.end_offsets),
1227        )
1228    }
1229}
1230
1231impl<K, V> MockConsumer<K, V> {
1232    /// Shared implementation for all `commit_*` variants; see
1233    /// [`mock_commit_async`].
1234    async fn commit_async_impl(
1235        &mut self,
1236        offsets: HashMap<TopicPartition, OffsetAndMetadata>,
1237        callback: Option<Arc<dyn OffsetCommitCallback>>,
1238    ) -> Result<(), Error> {
1239        mock_commit_async(&self.closed, &self.committed, offsets, callback).await
1240    }
1241}
1242
1243/// The message of the `IllegalArgumentException` Java's
1244/// `MockConsumer.position(TopicPartition)` throws for an unassigned partition.
1245const POSITION_NOT_ASSIGNED_MSG: &str = "You can only check the position for partitions assigned to this consumer.";
1246
1247/// Java's `ensureNotClosed()` (`org.apache.kafka.clients.consumer.MockConsumer#ensureNotClosed`) over the mock's
1248/// shared `closed` flag, so a [`ConsumerHandle`] obtained from the mock
1249/// checks it too.
1250fn ensure_mock_not_closed(closed: &AtomicBool) -> Result<(), Error> {
1251    if closed.load(Ordering::SeqCst) {
1252        Err(Error::local_illegal_state("This consumer has already been closed."))
1253    } else {
1254        Ok(())
1255    }
1256}
1257
1258/// Java's `groupMetadata()` (`org.apache.kafka.clients.consumer.MockConsumer#groupMetadata`): hard-coded
1259/// sentinel values, returned by the mock and by every [`ConsumerHandle`]
1260/// obtained from it.
1261pub(crate) fn mock_group_metadata() -> Arc<dyn ConsumerGroupMetadata> {
1262    Arc::new(ConsumerGroupMetadataImpl::with_generation_id_member_id_group_instance_id(
1263        "dummy.group.id",
1264        1,
1265        "1",
1266        None,
1267    ))
1268}
1269
1270/// Java's `currentLag(TopicPartition)` (`org.apache.kafka.clients.consumer.MockConsumer#currentLag`) over
1271/// the mock's shared state, for a [`ConsumerHandle`] obtained from the mock:
1272/// `endOffsets.get(tp) - position(tp)` when an end offset is set, else `0`
1273/// ("caught up"). Java's `position(tp)` checks that the mock is open and that
1274/// the partition is assigned, with its messages; a partition without a
1275/// position answers `None`, since the handle cannot seed one as
1276/// `updateFetchPosition` does.
1277pub(crate) fn mock_current_lag(
1278    closed: &AtomicBool,
1279    subscriptions: &Mutex<SubscriptionState>,
1280    end_offsets: &Mutex<HashMap<TopicPartition, i64>>,
1281    topic_partition: &TopicPartition,
1282) -> Result<Option<i64>, Error> {
1283    let end = end_offsets
1284        .lock()
1285        .unwrap_or_else(PoisonError::into_inner)
1286        .get(topic_partition)
1287        .copied();
1288    let Some(end) = end else {
1289        // If the test doesn't bother to set an end offset, we assume it wants
1290        // to model being caught up.
1291        return Ok(Some(0));
1292    };
1293    ensure_mock_not_closed(closed)?;
1294    let subs = subscriptions.lock().unwrap_or_else(PoisonError::into_inner);
1295    if !subs.is_assigned(topic_partition) {
1296        return Err(Error::local_illegal_argument(POSITION_NOT_ASSIGNED_MSG));
1297    }
1298    Ok(subs.position_or_null(topic_partition).map(|position| end - position.offset))
1299}
1300
1301/// Java's `commitAsync(Map, OffsetCommitCallback)` (`org.apache.kafka.clients.consumer.MockConsumer#commitAsync`)
1302/// over the mock's shared state: the commit path of the mock and of every
1303/// [`ConsumerHandle`] obtained from it.
1304///
1305/// Java's order: `committed.putAll(offsets)`, then
1306/// `callback.onComplete(offsets, null)` inline, so the callback (which may
1307/// commit again through a handle) observes the merged offsets and its own
1308/// commits land after them. The lock is released before the callback runs.
1309pub(crate) async fn mock_commit_async(
1310    closed: &AtomicBool,
1311    committed: &Mutex<HashMap<TopicPartition, OffsetAndMetadata>>,
1312    offsets: HashMap<TopicPartition, OffsetAndMetadata>,
1313    callback: Option<Arc<dyn OffsetCommitCallback>>,
1314) -> Result<(), Error> {
1315    ensure_mock_not_closed(closed)?;
1316    let lock = || committed.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
1317    match callback {
1318        None => lock().extend(offsets),
1319        Some(cb) => {
1320            lock().extend(offsets.iter().map(|(tp, om)| (tp.clone(), om.clone())));
1321            // Java calls `onComplete` with no try/catch: an exception it
1322            // throws propagates out of `commitAsync`.
1323            cb.on_complete(&offsets, None).await?;
1324        },
1325    }
1326    Ok(())
1327}
1328
1329/// The commits of a [`MockConsumer`] handle that name no offsets: Java's
1330/// `MockConsumer.commitAsync(callback)` (`ensureNotClosed()`, then
1331/// `commitAsync(subscriptions.allConsumed(), callback)`), which its
1332/// `commitSync()` and `commitAsync()` reach too. The `SubscriptionState`
1333/// guard is dropped before the commit awaits the callback
1334/// (`consumer-threading.md` §16).
1335pub(crate) async fn mock_commit_all_consumed(
1336    closed: &AtomicBool,
1337    committed: &Mutex<HashMap<TopicPartition, OffsetAndMetadata>>,
1338    subscriptions: &Mutex<SubscriptionState>,
1339    callback: Option<Arc<dyn OffsetCommitCallback>>,
1340) -> Result<(), Error> {
1341    ensure_mock_not_closed(closed)?;
1342    let offsets = subscriptions.lock().unwrap_or_else(PoisonError::into_inner).all_consumed();
1343    mock_commit_async(closed, committed, offsets, callback).await
1344}
1345
1346#[cfg(test)]
1347mod tests {
1348    //! Inherent-impl unit tests. The full [`MockConsumerTest`] translation
1349    //! lives in `tests/consumer/mock_consumer_test.rs` and exercises the
1350    //! public surface (incl. the `Consumer<K, V>` trait impl).
1351
1352    use async_trait::async_trait;
1353
1354    use super::*;
1355
1356    /// `MockConsumer` has the same thread shape as `KafkaConsumer`: it can
1357    /// move to another task but not be shared (`consumer-threading.md` §2),
1358    /// through its `not_sync` marker.
1359    #[test]
1360    fn mock_consumer_is_send_and_not_sync() {
1361        use crate::test_thread_safety::{is_send, is_sync};
1362        assert!(is_send!(MockConsumer<String, String>));
1363        assert!(!is_sync!(MockConsumer<String, String>));
1364    }
1365
1366    /// Java's `MockConsumer.metrics()` calls `ensureNotClosed()`
1367    /// (`org.apache.kafka.clients.consumer.MockConsumer#metrics`), which throws `IllegalStateException`.
1368    #[tokio::test]
1369    #[should_panic(expected = "This consumer has already been closed.")]
1370    async fn test_metrics_panics_after_close() {
1371        let mut c: MockConsumer<String, String> =
1372            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1373        Consumer::close(&mut c).await.expect("close");
1374        let _ = Consumer::metrics(&c);
1375    }
1376
1377    #[test]
1378    fn test_new_initial_state() {
1379        let c: MockConsumer<String, String> =
1380            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1381        assert!(!c.closed());
1382        assert!(!c.should_rebalance());
1383        assert!(c.last_poll_timeout().is_none());
1384        assert_eq!(c.max_poll_records, i64::MAX);
1385    }
1386
1387    #[test]
1388    fn test_set_max_poll_records_rejects_zero_and_negative() {
1389        let mut c: MockConsumer<String, String> =
1390            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1391        assert!(c.set_max_poll_records(0).is_err());
1392        assert!(c.set_max_poll_records(-1).is_err());
1393        assert!(c.set_max_poll_records(1).is_ok());
1394        assert_eq!(c.max_poll_records, 1);
1395    }
1396
1397    /// Java `MockConsumer.metrics()` returns `Collections.emptyMap()`
1398    /// (`org.apache.kafka.clients.consumer.MockConsumer#metrics`). The Rust port returns an empty map.
1399    #[test]
1400    fn test_metrics_returns_empty_map() {
1401        let c: MockConsumer<String, String> =
1402            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1403        assert!(Consumer::metrics(&c).is_empty());
1404    }
1405
1406    #[test]
1407    fn test_reset_should_rebalance() {
1408        let mut c: MockConsumer<String, String> =
1409            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1410        c.should_rebalance.store(true, Ordering::SeqCst);
1411        assert!(c.should_rebalance());
1412        c.reset_should_rebalance();
1413        assert!(!c.should_rebalance());
1414    }
1415
1416    #[test]
1417    fn test_update_partitions_after_close_errors() {
1418        let mut c: MockConsumer<String, String> =
1419            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1420        c.closed.store(true, Ordering::SeqCst);
1421        let err = c.update_partitions("t", Vec::new()).unwrap_err();
1422        assert!(matches!(err, Error::LocalIllegalState(_)));
1423    }
1424
1425    /// Java's `scheduleNopPollTask()` queues `() -> { }` like any other poll
1426    /// task (`org.apache.kafka.clients.consumer.MockConsumer#scheduleNopPollTask`): it consumes one `poll`, so the
1427    /// task scheduled after it runs on the next one.
1428    #[tokio::test]
1429    async fn schedule_nop_poll_task_takes_one_poll() {
1430        let mut c: MockConsumer<String, String> =
1431            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1432        c.schedule_nop_poll_task();
1433        c.schedule_poll_task(Box::new(|c| c.reset_should_rebalance()));
1434        c.should_rebalance.store(true, Ordering::SeqCst);
1435
1436        c.poll(Duration::from_millis(0)).await.expect("poll");
1437        assert!(c.should_rebalance(), "the first poll ran the no-op task");
1438        c.poll(Duration::from_millis(0)).await.expect("poll");
1439        assert!(!c.should_rebalance(), "the second poll ran the task scheduled after it");
1440        assert!(c.poll_tasks.is_empty());
1441    }
1442
1443    /// Java's `setPollException(null)` clears a pending poll exception
1444    /// (`org.apache.kafka.clients.consumer.MockConsumer#setPollException`): the next `poll` then succeeds.
1445    #[tokio::test]
1446    async fn set_poll_error_none_clears_the_pending_error() {
1447        let mut c: MockConsumer<String, String> =
1448            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1449        let tp = TopicPartition::new("t", 0);
1450        c.assign(vec![tp.clone()]).await.expect("assign");
1451        c.update_beginning_offsets(HashMap::from([(tp, 0)]));
1452
1453        c.set_poll_error(Some(Error::local_illegal_state("boom")));
1454        c.set_poll_error(None);
1455        assert!(
1456            c.poll(Duration::from_millis(0)).await.is_ok(),
1457            "the cleared error must not fire"
1458        );
1459
1460        c.set_poll_error(Some(Error::local_illegal_state("boom")));
1461        let err = c.poll(Duration::from_millis(0)).await.unwrap_err();
1462        assert_eq!(err.message(), "boom");
1463        assert!(c.poll(Duration::from_millis(0)).await.is_ok(), "the error fires once");
1464    }
1465
1466    /// Java's `setOffsetsException(null)` clears a pending offsets exception
1467    /// (`org.apache.kafka.clients.consumer.MockConsumer#setOffsetsException`).
1468    #[tokio::test]
1469    async fn set_offsets_error_none_clears_the_pending_error() {
1470        let mut c: MockConsumer<String, String> =
1471            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1472        let tp = TopicPartition::new("t", 0);
1473        c.update_end_offsets(HashMap::from([(tp.clone(), 5)]));
1474
1475        c.set_offsets_error(Some(Error::local_illegal_state("boom")));
1476        c.set_offsets_error(None);
1477        let offsets = c
1478            .end_offsets(std::slice::from_ref(&tp))
1479            .await
1480            .expect("the cleared error must not fire");
1481        assert_eq!(offsets.get(&tp), Some(&5));
1482
1483        c.set_offsets_error(Some(Error::local_illegal_state("boom")));
1484        let err = c.end_offsets(std::slice::from_ref(&tp)).await.unwrap_err();
1485        assert_eq!(err.message(), "boom");
1486    }
1487
1488    /// A [`ConsumerHandle`] obtained from the mock fires the SAME wakeup
1489    /// flag as `wakeup()`: the next `poll` observes it and returns `Wakeup`.
1490    #[tokio::test]
1491    async fn handle_wakeup_wakes_next_poll() {
1492        let mut c: MockConsumer<String, String> =
1493            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1494
1495        // Handle is moved into another task — no reference to the consumer
1496        // crosses the boundary.
1497        let handle = c.handle();
1498        tokio::spawn(async move {
1499            handle.wakeup();
1500        })
1501        .await
1502        .expect("waker task");
1503
1504        let err = c.poll(Duration::from_millis(0)).await.unwrap_err();
1505        assert!(matches!(err, Error::Wakeup(_)), "expected Wakeup, got {err:?}");
1506    }
1507
1508    /// Java's `MockConsumer.offsetsForTimes` throws
1509    /// `UnsupportedOperationException("Not implemented yet.")`
1510    /// (`org.apache.kafka.clients.consumer.MockConsumer#offsetsForTimes`), translated as
1511    /// [`Error::LocalUnsupportedOperation`]. The message text is part of the
1512    /// contract (DoD #3), so it must be Java's, not a Rust-side restatement.
1513    #[tokio::test]
1514    async fn offsets_for_times_reports_javas_not_implemented_message() {
1515        let mut consumer: MockConsumer<String, String> =
1516            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1517        let err = consumer
1518            .offsets_for_times(HashMap::new())
1519            .await
1520            .expect_err("Java's mock does not implement this");
1521        assert!(err.is_local_unsupported_operation_error(), "{err:?}");
1522        assert_eq!("Not implemented yet.", err.message());
1523    }
1524
1525    // ─── ConsumerHandle commits (Java callbacks calling back into the mock) ───
1526
1527    fn offsets(tp: &TopicPartition, offset: i64) -> HashMap<TopicPartition, OffsetAndMetadata> {
1528        HashMap::from([(tp.clone(), OffsetAndMetadata::new(offset).expect("non-negative"))])
1529    }
1530
1531    /// `offsets`, as `committed()` returns them.
1532    fn committed_offsets(tp: &TopicPartition, offset: i64) -> HashMap<TopicPartition, Option<OffsetAndMetadata>> {
1533        HashMap::from([(tp.clone(), Some(OffsetAndMetadata::new(offset).expect("non-negative")))])
1534    }
1535
1536    /// Java's `MockConsumer.commitSync(Map)` records the offsets in the
1537    /// mock's `committed` map; through a handle it records them in the same
1538    /// map, so the consumer's `committed()` returns them.
1539    #[tokio::test]
1540    async fn handle_commit_sync_with_offsets_records_committed() {
1541        let mut c: MockConsumer<String, String> =
1542            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1543        let tp = tp_of("test");
1544        c.assign(vec![tp.clone()]).await.expect("assign");
1545
1546        let handle = c.handle();
1547        handle.commit_sync_with_offsets(offsets(&tp, 5)).await.expect("commit sync");
1548        assert_eq!(
1549            c.committed(std::slice::from_ref(&tp)).await.expect("committed"),
1550            committed_offsets(&tp, 5)
1551        );
1552
1553        let seen = Arc::new(Mutex::new(Vec::new()));
1554        let cb = Arc::new(RecordingCallback { label: "async", seen: Arc::clone(&seen), nested: None });
1555        handle
1556            .commit_async_with_offsets_callback(offsets(&tp, 6), cb)
1557            .await
1558            .expect("commit async");
1559        assert_eq!(
1560            c.committed(std::slice::from_ref(&tp)).await.expect("committed"),
1561            committed_offsets(&tp, 6)
1562        );
1563        assert_eq!(*seen.lock().unwrap(), vec![("async", offsets(&tp, 6))]);
1564    }
1565
1566    fn tp_of(topic: &str) -> TopicPartition {
1567        TopicPartition::new(topic.to_string(), 0)
1568    }
1569
1570    /// A callback's label and the offsets it was handed.
1571    type Seen = (&'static str, HashMap<TopicPartition, OffsetAndMetadata>);
1572
1573    /// Records `(label, offsets)` and, with `nested`, commits again through
1574    /// the handle from inside the callback.
1575    struct RecordingCallback {
1576        label: &'static str,
1577        seen: Arc<Mutex<Vec<Seen>>>,
1578        nested: Option<(ConsumerHandle, HashMap<TopicPartition, OffsetAndMetadata>)>,
1579    }
1580
1581    #[async_trait]
1582    impl OffsetCommitCallback for RecordingCallback {
1583        async fn on_complete(
1584            &self,
1585            offsets: &HashMap<TopicPartition, OffsetAndMetadata>,
1586            error: Option<&Error>,
1587        ) -> Result<(), Error> {
1588            assert!(error.is_none(), "the mock completes commits without an error");
1589            self.seen.lock().unwrap().push((self.label, offsets.clone()));
1590            if let Some((handle, nested)) = &self.nested {
1591                let inner = Arc::new(RecordingCallback { label: "inner", seen: Arc::clone(&self.seen), nested: None });
1592                handle
1593                    .commit_async_with_offsets_callback(nested.clone(), inner)
1594                    .await
1595                    .expect("nested commit");
1596                self.seen.lock().unwrap().push(("outer-end", HashMap::new()));
1597            }
1598            Ok(())
1599        }
1600    }
1601
1602    /// Java's `MockConsumer.commitAsync(Map, OffsetCommitCallback)` puts the
1603    /// offsets, then calls the callback inline. A callback committing through
1604    /// the handle runs its own callback inline too, before the outer one
1605    /// returns, and its offsets land after the outer ones.
1606    #[tokio::test]
1607    async fn handle_commit_async_with_offsets_callback_nests_inline() {
1608        let mut c: MockConsumer<String, String> =
1609            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1610        let tp = tp_of("test");
1611        c.assign(vec![tp.clone()]).await.expect("assign");
1612        let seen = Arc::new(Mutex::new(Vec::new()));
1613        let outer = Arc::new(RecordingCallback {
1614            label: "outer",
1615            seen: Arc::clone(&seen),
1616            nested: Some((c.handle(), offsets(&tp, 9))),
1617        });
1618
1619        c.commit_async_with_offsets_callback(offsets(&tp, 3), outer)
1620            .await
1621            .expect("commit");
1622
1623        assert_eq!(
1624            *seen.lock().unwrap(),
1625            vec![
1626                ("outer", offsets(&tp, 3)),
1627                ("inner", offsets(&tp, 9)),
1628                ("outer-end", HashMap::new())
1629            ]
1630        );
1631        assert_eq!(
1632            c.committed(std::slice::from_ref(&tp)).await.expect("committed"),
1633            committed_offsets(&tp, 9)
1634        );
1635    }
1636
1637    /// Assigns `tp`, seeds its beginning offset and polls `count` records
1638    /// from offset `from`, so the mock's consumed position is `from + count`.
1639    async fn consume(c: &mut MockConsumer<String, String>, tp: &TopicPartition, from: i64, count: i64) {
1640        for offset in from..from + count {
1641            c.add_record(ConsumerRecord::new(tp.topic().to_string(), tp.partition(), offset, None, None))
1642                .expect("add record");
1643        }
1644        assert_eq!(c.poll(Duration::ZERO).await.expect("poll").count() as i64, count);
1645    }
1646
1647    /// Java's `MockConsumer.commitSync()`, `commitAsync()` and
1648    /// `commitAsync(callback)` commit `subscriptions.allConsumed()`; through a
1649    /// handle they commit the same mock's consumed positions, the callback
1650    /// running inline with them.
1651    #[tokio::test]
1652    async fn handle_commit_without_offsets_commits_consumed_positions() {
1653        let mut c: MockConsumer<String, String> =
1654            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1655        let tp = tp_of("test");
1656        c.assign(vec![tp.clone()]).await.expect("assign");
1657        c.update_beginning_offsets(HashMap::from([(tp.clone(), 0)]));
1658        let handle = c.handle();
1659
1660        consume(&mut c, &tp, 0, 1).await;
1661        handle.commit_sync().await.expect("commit sync");
1662        assert_eq!(
1663            c.committed(std::slice::from_ref(&tp)).await.expect("committed"),
1664            committed_offsets(&tp, 1)
1665        );
1666
1667        consume(&mut c, &tp, 1, 2).await;
1668        handle.commit_async().await.expect("commit async");
1669        assert_eq!(
1670            c.committed(std::slice::from_ref(&tp)).await.expect("committed"),
1671            committed_offsets(&tp, 3)
1672        );
1673
1674        consume(&mut c, &tp, 3, 1).await;
1675        let seen = Arc::new(Mutex::new(Vec::new()));
1676        handle
1677            .commit_async_with_callback(Arc::new(RecordingCallback {
1678                label: "cb",
1679                seen: Arc::clone(&seen),
1680                nested: None,
1681            }))
1682            .await
1683            .expect("commit async with callback");
1684        assert_eq!(*seen.lock().unwrap(), vec![("cb", offsets(&tp, 4))]);
1685        assert_eq!(
1686            c.committed(std::slice::from_ref(&tp)).await.expect("committed"),
1687            committed_offsets(&tp, 4)
1688        );
1689    }
1690
1691    /// The handle's getters read the mock's own state, as a Java callback
1692    /// calling `consumer.assignment()` / `paused()` / `currentLag()` /
1693    /// `groupMetadata()` does.
1694    #[tokio::test]
1695    async fn handle_getters_read_the_mock_state() {
1696        let mut c: MockConsumer<String, String> =
1697            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1698        let handle = c.handle();
1699        c.subscribe_with_topics(vec!["test".to_string()]).await.expect("subscribe");
1700        let tp = tp_of("test");
1701        // No end offset: caught up, assigned or not, as Java's mock.
1702        assert_eq!(handle.current_lag(&tp).await.expect("lag"), Some(0));
1703        c.update_end_offsets(HashMap::from([(tp.clone(), 10)]));
1704        // Unassigned with an end offset: Java's `position(tp)` throws.
1705        let error = handle.current_lag(&tp).await.expect_err("unassigned");
1706        assert!(error.is_local_illegal_argument_error(), "{error:?}");
1707        assert_eq!(
1708            error.message(),
1709            "You can only check the position for partitions assigned to this consumer."
1710        );
1711        c.rebalance(std::slice::from_ref(&tp)).await.expect("rebalance");
1712        assert_eq!(handle.assignment(), HashSet::from([tp.clone()]));
1713        c.pause(std::slice::from_ref(&tp)).await.expect("pause");
1714        assert_eq!(handle.paused(), HashSet::from([tp.clone()]));
1715        c.resume(std::slice::from_ref(&tp)).await.expect("resume");
1716        assert!(handle.paused().is_empty());
1717
1718        // Assigned with an end offset but no position yet: Java's mock would
1719        // reset the position through `position(tp)`; the handle cannot seed
1720        // one, so the lag is unknown.
1721        assert_eq!(handle.current_lag(&tp).await.expect("lag"), None);
1722        c.seek_with_offset(tp.clone(), 4).await.expect("seek");
1723        assert_eq!(
1724            handle.current_lag(&tp).await.expect("lag"),
1725            Some(6),
1726            "handle lag reads the mock's end offsets and position"
1727        );
1728        assert_eq!(
1729            handle.current_lag(&tp).await.expect("lag"),
1730            c.current_lag(&tp).await.expect("lag")
1731        );
1732
1733        // Java's `MockConsumer.groupMetadata()` sentinel values.
1734        let meta = handle.group_metadata();
1735        assert_eq!(meta.group_id(), "dummy.group.id");
1736        assert_eq!(meta.generation_id(), 1);
1737        assert_eq!(meta.member_id(), "1");
1738        assert_eq!(meta.group_instance_id(), None);
1739    }
1740
1741    /// Commits from inside `onPartitionsRevoked` through the handle, the
1742    /// canonical listener pattern: the mock holds no `SubscriptionState` lock
1743    /// while the listener runs, so the commit reads the consumed positions
1744    /// and records them before the rebalance replaces the assignment.
1745    #[tokio::test]
1746    async fn handle_commit_sync_inside_rebalance_listener() {
1747        struct CommitOnRevoke(ConsumerHandle, Arc<Mutex<Vec<HashSet<TopicPartition>>>>);
1748        #[async_trait]
1749        impl ConsumerRebalanceListener for CommitOnRevoke {
1750            async fn on_partitions_revoked(&self, _partitions: &[TopicPartition]) -> Result<(), Error> {
1751                self.1.lock().unwrap().push(self.0.assignment());
1752                self.0.commit_sync().await
1753            }
1754            async fn on_partitions_assigned(&self, _partitions: &[TopicPartition]) -> Result<(), Error> {
1755                Ok(())
1756            }
1757        }
1758
1759        let mut c: MockConsumer<String, String> =
1760            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1761        let tp = tp_of("test");
1762        let seen = Arc::new(Mutex::new(Vec::new()));
1763        c.subscribe_with_topics_listener(
1764            vec!["test".to_string()],
1765            Arc::new(CommitOnRevoke(c.handle(), Arc::clone(&seen))),
1766        )
1767        .await
1768        .expect("subscribe");
1769        c.rebalance(std::slice::from_ref(&tp)).await.expect("assign");
1770        c.update_beginning_offsets(HashMap::from([(tp.clone(), 0)]));
1771        consume(&mut c, &tp, 0, 2).await;
1772
1773        c.rebalance(&[]).await.expect("revoke");
1774        assert_eq!(*seen.lock().unwrap(), vec![HashSet::from([tp.clone()])]);
1775        // The commit recorded the consumed position (read directly: the
1776        // mock's `committed()` answers 0 for a partition no longer assigned).
1777        assert_eq!(*c.lock_committed(), offsets(&tp, 2));
1778    }
1779
1780    /// A listener that captured the mock's handle is freed with the mock, and
1781    /// until the drop it still runs on a closed mock, as Java's `rebalance`
1782    /// makes no `ensureNotClosed()` check (`org.apache.kafka.clients.consumer.MockConsumer#rebalance`).
1783    #[tokio::test]
1784    async fn listener_capturing_the_handle_is_freed_with_the_mock() {
1785        struct Sentinel(Arc<AtomicBool>);
1786        impl Drop for Sentinel {
1787            fn drop(&mut self) {
1788                self.0.store(true, Ordering::SeqCst);
1789            }
1790        }
1791        struct HandleListener {
1792            _handle: ConsumerHandle,
1793            _sentinel: Sentinel,
1794            assigned: Arc<Mutex<Vec<TopicPartition>>>,
1795        }
1796        #[async_trait]
1797        impl ConsumerRebalanceListener for HandleListener {
1798            async fn on_partitions_revoked(&self, _partitions: &[TopicPartition]) -> Result<(), Error> {
1799                Ok(())
1800            }
1801            async fn on_partitions_assigned(&self, partitions: &[TopicPartition]) -> Result<(), Error> {
1802                self.assigned.lock().unwrap().extend_from_slice(partitions);
1803                Ok(())
1804            }
1805        }
1806
1807        let mut c: MockConsumer<String, String> =
1808            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1809        let dropped = Arc::new(AtomicBool::new(false));
1810        let assigned = Arc::new(Mutex::new(Vec::new()));
1811        let subscriptions = Arc::downgrade(&c.subscriptions);
1812        c.subscribe_with_topics_listener(
1813            vec!["test".to_string()],
1814            Arc::new(HandleListener {
1815                _handle: c.handle(),
1816                _sentinel: Sentinel(Arc::clone(&dropped)),
1817                assigned: Arc::clone(&assigned),
1818            }),
1819        )
1820        .await
1821        .expect("subscribe");
1822        c.close().await.expect("close");
1823
1824        let tp = tp_of("test");
1825        c.rebalance(std::slice::from_ref(&tp)).await.expect("rebalance");
1826        assert_eq!(*assigned.lock().unwrap(), vec![tp]);
1827        assert!(!dropped.load(Ordering::SeqCst), "the listener is released only by the drop");
1828
1829        drop(c);
1830        assert!(dropped.load(Ordering::SeqCst), "listener still referenced");
1831        assert_eq!(0, subscriptions.strong_count(), "SubscriptionState still referenced");
1832    }
1833
1834    /// An error the callback returns (Java's `onComplete` throwing) propagates
1835    /// out of the mock's commit, after the offsets were committed: Java's
1836    /// `MockConsumer.commitAsync` calls the callback with no try/catch. The
1837    /// handle's commits behave the same.
1838    #[tokio::test]
1839    async fn commit_callback_error_propagates() {
1840        struct Raising;
1841        #[async_trait]
1842        impl OffsetCommitCallback for Raising {
1843            async fn on_complete(
1844                &self,
1845                _offsets: &HashMap<TopicPartition, OffsetAndMetadata>,
1846                _error: Option<&Error>,
1847            ) -> Result<(), Error> {
1848                Err(Error::local_illegal_state("callback failed"))
1849            }
1850        }
1851
1852        let mut c: MockConsumer<String, String> =
1853            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1854        let tp = tp_of("test");
1855        c.assign(vec![tp.clone()]).await.expect("assign");
1856        c.update_beginning_offsets(HashMap::from([(tp.clone(), 0)]));
1857        consume(&mut c, &tp, 0, 3).await;
1858
1859        let err = c
1860            .commit_async_with_offsets_callback(offsets(&tp, 2), Arc::new(Raising))
1861            .await
1862            .expect_err("propagates");
1863        assert!(err.is_local_illegal_state_error(), "unexpected error: {err:?}");
1864        assert_eq!(err.message(), "callback failed");
1865        assert_eq!(
1866            c.committed(std::slice::from_ref(&tp)).await.expect("committed"),
1867            committed_offsets(&tp, 2)
1868        );
1869
1870        let err = c.commit_async_with_callback(Arc::new(Raising)).await.expect_err("propagates");
1871        assert_eq!(err.message(), "callback failed");
1872        assert_eq!(
1873            c.committed(std::slice::from_ref(&tp)).await.expect("committed"),
1874            committed_offsets(&tp, 3)
1875        );
1876
1877        let handle = c.handle();
1878        let err = handle
1879            .commit_async_with_offsets_callback(offsets(&tp, 5), Arc::new(Raising))
1880            .await
1881            .expect_err("propagates");
1882        assert_eq!(err.message(), "callback failed");
1883        let err = handle
1884            .commit_async_with_callback(Arc::new(Raising))
1885            .await
1886            .expect_err("propagates");
1887        assert_eq!(err.message(), "callback failed");
1888        assert_eq!(
1889            c.committed(std::slice::from_ref(&tp)).await.expect("committed"),
1890            committed_offsets(&tp, 3)
1891        );
1892    }
1893
1894    /// Java's `commitAsync` starts with `ensureNotClosed()`, so a handle
1895    /// commit after `close()` fails with the mock's closed error.
1896    #[tokio::test]
1897    async fn handle_commit_after_close_fails() {
1898        let mut c: MockConsumer<String, String> =
1899            MockConsumer::with_auto_offset_reset_strategy(AutoOffsetResetStrategy::EARLIEST);
1900        let handle = c.handle();
1901        c.close().await.expect("close");
1902        let tp = tp_of("test");
1903        let err = handle.commit_sync_with_offsets(offsets(&tp, 1)).await.expect_err("closed");
1904        assert_eq!(err.message(), "This consumer has already been closed.");
1905        let err = handle
1906            .commit_async_with_offsets_callback(
1907                offsets(&tp, 1),
1908                Arc::new(RecordingCallback { label: "x", seen: Arc::new(Mutex::new(Vec::new())), nested: None }),
1909            )
1910            .await
1911            .expect_err("closed");
1912        assert_eq!(err.message(), "This consumer has already been closed.");
1913        for err in [
1914            handle.commit_sync().await.expect_err("closed"),
1915            handle.commit_async().await.expect_err("closed"),
1916            handle
1917                .commit_async_with_callback(Arc::new(RecordingCallback {
1918                    label: "x",
1919                    seen: Arc::new(Mutex::new(Vec::new())),
1920                    nested: None,
1921                }))
1922                .await
1923                .expect_err("closed"),
1924        ] {
1925            assert!(err.is_local_illegal_state_error(), "unexpected error: {err:?}");
1926            assert_eq!(err.message(), "This consumer has already been closed.");
1927        }
1928    }
1929}