Skip to main content

confluent_kafka/consumer/
mod.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//! Consumer types (org.apache.kafka.clients.consumer).
16//!
17//! Translated from `org.apache.kafka.clients.consumer`. The `clients` Java
18//! package segment is intentionally dropped per CLAUDE.md §2.
19
20pub mod close_options;
21mod consumer_commit_failed_error;
22mod consumer_config;
23mod consumer_group_metadata;
24mod consumer_log_truncation_error;
25mod consumer_no_offset_for_partition_error;
26mod consumer_offset_out_of_range_error;
27pub mod consumer_partition_assignor;
28mod consumer_rebalance_listener;
29mod consumer_record;
30mod consumer_records;
31mod consumer_retriable_commit_failed_error;
32mod dyn_consumer;
33mod group_protocol;
34mod interceptor;
35mod kafka_consumer;
36mod mock_consumer;
37mod offset_and_metadata;
38mod offset_and_timestamp;
39pub mod offset_commit_callback;
40mod subscription_pattern;
41
42pub(crate) mod internals;
43
44pub use close_options::{CloseOptions, GroupMembershipOperation};
45pub use consumer_config::ConsumerConfig;
46pub use consumer_group_metadata::ConsumerGroupMetadata;
47pub(crate) use consumer_group_metadata::ConsumerGroupMetadataImpl;
48pub use consumer_rebalance_listener::ConsumerRebalanceListener;
49pub use consumer_record::{ConsumerRecord, ConsumerRecordOptions, ConsumerRecordOptionsBuilder};
50pub use consumer_records::ConsumerRecords;
51pub use dyn_consumer::DynConsumer;
52pub use group_protocol::GroupProtocol;
53pub use interceptor::ConsumerInterceptor;
54pub use internals::ConsumerHandle;
55pub use kafka_consumer::KafkaConsumer;
56pub use mock_consumer::MockConsumer;
57pub use offset_and_metadata::OffsetAndMetadata;
58pub use offset_and_timestamp::OffsetAndTimestamp;
59pub use offset_commit_callback::OffsetCommitCallback;
60pub use subscription_pattern::SubscriptionPattern;
61
62use std::collections::{HashMap, HashSet};
63use std::sync::Arc;
64use std::time::Duration;
65
66use crate::common::metrics::MetricsView;
67use crate::common::{Error, PartitionInfo, TopicPartition};
68
69/// The consumer interface, implemented by [`KafkaConsumer`] and
70/// [`MockConsumer`].
71///
72/// # Translation notes
73///
74/// Methods that block in Java are asynchronous, returning `impl Future + Send`;
75/// hold [`DynConsumer`] to keep different implementations behind one type.
76/// Methods taking a `Vec` or `HashMap` retain it; those taking a slice or a
77/// `&HashMap` only read it. The KIP-714 telemetry methods and the
78/// `subscribe` overloads taking a `java.util.regex.Pattern` are not translated.
79//
80// # Parameter conventions
81//
82// The trait uses three argument shapes deliberately:
83//
84// - **Owned collections (`Vec<T>`, `HashMap<K, V>`):** the implementation
85//   stores or forwards the input long-term (subscription state, request
86//   payload). Ownership transfer avoids a per-element clone.
87//
88// - **Borrowed slices / maps (`&[T]`, `&HashMap<K, V>`):** the
89//   implementation iterates but does not retain the input. Callers can
90//   pass `&Vec<T>`, `&[T; N]`, or any slice without conversion.
91//
92// - **Borrowed scalars (`&TopicPartition`, `&str`):** read-only access to
93//   a single value.
94//
95// Methods that take `Vec<T>` are the ones that *consume* the input;
96// methods that take `&[T]` only *iterate* it. This rule is mechanical:
97// if the impl retains, it owns; if the impl reads, it borrows.
98//
99// # Bounds: `Send + 'static`, NOT `Send + Sync`
100//
101// The trait is `Send + 'static` so a consumer, and its [`DynConsumer`]
102// view `Box<dyn DynConsumer<K, V>>`, can be moved between tokio tasks
103// (required for multi-thread runtime support). `Sync` is intentionally NOT
104// required because the API is `&mut self` — only one task can call methods
105// at a time, no shared `&Consumer` reference exists.
106//
107// Users who need cross-task sharing wrap in `Arc<Mutex<dyn DynConsumer>>`,
108// which works without `Sync` on the trait itself. Dropping `Sync` lets
109// users plug in `K`/`V` types that are `Send` but not `Sync` (e.g.
110// types containing `Cell`) without artificial restrictions.
111//
112// # Async surface
113//
114// Per `consumer-threading.md` §1: methods that block in Java are
115// asynchronous; non-blocking accessors stay `fn`. Every asynchronous method
116// returns `impl Future + Send` rather than being declared `async fn`, so
117// that generic code can move the returned futures across tasks and box them
118// as `dyn Future + Send`. That guarantee is what lets [`DynConsumer`] be
119// blanket-implemented for every `Consumer`. Implementations may still be
120// written with `async fn`.
121//
122// Returning `impl Future` keeps statically dispatched calls (on a concrete
123// [`KafkaConsumer`] or [`MockConsumer`], or through a generic
124// `C: Consumer<K, V>`) free of a boxed future, but makes the trait itself
125// not dyn-compatible. Hold [`DynConsumer`] to keep different consumer
126// implementations behind one type, as Java code holds the `Consumer`
127// interface (CLAUDE.md §3).
128//
129// # Methods NOT translated
130//
131// - `registerMetricForSubscription`, `unregisterMetricFromSubscription`,
132//   `clientInstanceId(Duration)`: KIP-714 broker-push telemetry, deferred
133//   to its own milestone (see Milestone-9 metrics plan, "Out of scope").
134//   They are omitted from the trait (no stub); when KIP-714 telemetry
135//   lands, the [`crate::producer::Producer`]-style traits and `Consumer`
136//   gain these methods together.
137// - `metrics()` IS translated (Phase M7) — it is in Java's `Consumer`
138//   interface and snapshots the registry that the metrics managers
139//   populate. See [`Consumer::metrics`].
140// - `subscribe(Pattern, [ConsumerRebalanceListener])` (Java regex):
141//   superseded by the [`SubscriptionPattern`] variants which match
142//   server-side regex semantics.
143// - `poll(long timeoutMs)`, `close(Duration timeout)` (both
144//   `@Deprecated` in Java): not translated per CLAUDE.md §3.
145#[doc(alias = "org.apache.kafka.clients.consumer.Consumer")]
146pub trait Consumer<K, V>: Send + 'static
147where
148    K: Send + 'static,
149    V: Send + 'static,
150{
151    // ── State reads (sync — Java: non-blocking accessors) ──
152
153    /// Get the set of partitions currently assigned to this consumer. If
154    /// subscription happened by directly assigning partitions using
155    /// [`Self::assign`] then this will simply return the same partitions that
156    /// were assigned. If topic subscription was used, then this will give the
157    /// set of topic partitions currently assigned to the consumer (which may
158    /// be none if the assignment hasn't happened yet, or the partitions are in
159    /// the process of getting reassigned).
160    ///
161    /// The returned set is a snapshot of the current assignment at the time of
162    /// the call. It will not be updated if the assignment changes afterward.
163    ///
164    /// # Returns
165    ///
166    /// An immutable snapshot of the set of partitions currently assigned to this consumer
167    ///
168    /// # Panics
169    ///
170    /// On [`KafkaConsumer`], panics with `"This consumer has already been
171    /// closed."` when the consumer is closed, where Java's
172    /// `acquireAndEnsureOpen()` throws `IllegalStateException`: calling it
173    /// after `close()` is a programming error. [`MockConsumer`] follows Java's
174    /// `MockConsumer`, which does not check.
175    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#assignment")]
176    fn assignment(&mut self) -> HashSet<TopicPartition>;
177
178    /// Get the current subscription. Will return the same topics used in the
179    /// most recent call to [`Self::subscribe_with_topics`] or
180    /// [`Self::subscribe_with_topics_listener`], or an empty set if no such
181    /// call has been made.
182    ///
183    /// The returned set is a snapshot of the current subscription at the time
184    /// of the call. It will not be updated if the subscription changes
185    /// afterward.
186    ///
187    /// # Returns
188    ///
189    /// An immutable snapshot of the set of topics currently subscribed to
190    ///
191    /// # Panics
192    ///
193    /// On [`KafkaConsumer`], panics with `"This consumer has already been
194    /// closed."` when the consumer is closed, where Java's
195    /// `acquireAndEnsureOpen()` throws `IllegalStateException`: calling it
196    /// after `close()` is a programming error. [`MockConsumer`] follows Java's
197    /// `MockConsumer`, which does not check.
198    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#subscription")]
199    fn subscription(&mut self) -> HashSet<String>;
200
201    /// Get the set of partitions that were previously paused by a call to `Self::pause`.
202    ///
203    /// # Returns
204    ///
205    /// The set of paused partitions
206    ///
207    /// # Panics
208    ///
209    /// On [`KafkaConsumer`], panics with `"This consumer has already been
210    /// closed."` when the consumer is closed, where Java's
211    /// `acquireAndEnsureOpen()` throws `IllegalStateException`: calling it
212    /// after `close()` is a programming error. [`MockConsumer`] follows Java's
213    /// `MockConsumer`, which does not check.
214    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#paused")]
215    fn paused(&mut self) -> HashSet<TopicPartition>;
216
217    /// Return the current group metadata associated with this consumer.
218    ///
219    /// # Returns
220    ///
221    /// consumer group metadata
222    ///
223    /// # Panics
224    ///
225    /// On [`KafkaConsumer`]: with `"This consumer has already been closed."`
226    /// when the consumer is closed, and with `InvalidGroupIdError`'s message
227    /// when the consumer has no `group.id`.
228    ///
229    /// # Translation notes
230    ///
231    /// A misuse Java throws for is a panic. [`MockConsumer`] does not check.
232    // `ConsumerGroupMetadata` is a trait, so the consumer returns its own
233    // implementation behind an `Arc`, cheap to clone and to hand to
234    // `Producer::send_offsets_to_transaction`. MockConsumer follows Java's
235    // MockConsumer, which returns a dummy group's metadata.
236    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#groupMetadata")]
237    fn group_metadata(&mut self) -> Arc<dyn ConsumerGroupMetadata>;
238
239    /// Get the consumer's current lag on the partition. Returns `None` if the
240    /// lag is not known, for example if there is no position yet, or if the
241    /// end offset is not known yet.
242    ///
243    /// This method uses locally cached metadata. If the log end offset is not
244    /// known yet, it triggers a request to fetch the log end offset, but
245    /// returns immediately.
246    ///
247    /// # Arguments
248    ///
249    /// - `topic_partition` - The partition to get the lag for.
250    ///
251    /// # Returns
252    ///
253    /// This `Consumer` instance's current lag for the given partition.
254    ///
255    /// # Errors
256    ///
257    /// - `Error::is_local_illegal_state_error` if the `topicPartition` is not assigned, or the
258    ///   consumer is closed
259    /// - `Error::is_timeout_error` if the background task does not answer within
260    ///   `default.api.timeout.ms`
261    ///
262    /// # Translation notes
263    ///
264    /// Asynchronous: Java's `currentLag` waits for the consumer's background
265    /// thread too.
266    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#currentLag")]
267    fn current_lag(
268        &mut self,
269        topic_partition: &TopicPartition,
270    ) -> impl Future<Output = Result<Option<i64>, Error>> + Send;
271
272    /// Get the metrics kept by the consumer
273    ///
274    /// The returned map is an unmodifiable live view of the metrics. Changes to
275    /// the underlying metrics will be reflected in the returned map.
276    ///
277    /// # Returns
278    ///
279    /// An unmodifiable live view of the map of metrics currently maintained by
280    /// the consumer
281    // The trait method has no default: it is in Java's `Consumer` interface, so
282    // every implementation provides it.
283    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#metrics")]
284    fn metrics(&self) -> MetricsView;
285
286    // ── Subscription / assignment (async per §1 — may interact with bg task) ──
287
288    // Java declares six `subscribe` overloads (`Consumer#subscribe`). The
289    // intersection of their parameters is empty, so under CLAUDE.md §2 no
290    // overload keeps the plain name `subscribe`; each is suffixed with the
291    // parameter names that distinguish it.
292    //
293    // Java has two pattern forms and they are NOT sugar for one another:
294    // `subscribe(Pattern)` matches a `java.util.regex.Pattern` **client-side**
295    // against the consumer's own metadata
296    // (`TopicPatternSubscriptionChangeEvent`), while
297    // `subscribe(SubscriptionPattern)` sends the pattern to the broker for
298    // **server-side** RE2/J evaluation
299    // (`TopicRe2JPatternSubscriptionChangeEvent`), in
300    // `AsyncKafkaConsumer#subscribe`.
301    //
302    // **Only the `SubscriptionPattern` form is translated.** The two
303    // `subscribe(Pattern ...)` overloads are deliberately NOT implemented in
304    // Rust, so there is no `subscribe_pattern` / `subscribe_pattern_listener`
305    // on this trait. Callers wanting a regex subscription use
306    // [`Self::subscribe_with_pattern`], whose pattern the group
307    // coordinator evaluates.
308
309    /// Subscribe to the given list of topics to get dynamically assigned partitions. **Topic
310    /// subscriptions are not incremental. This list will replace the current assignment (if
311    /// there is one).** It is not possible to combine topic subscription with group management
312    /// with manual partition assignment through `Self::assign`. If the given list of topics is
313    /// empty, it is treated the same as `Self::unsubscribe`.
314    ///
315    /// This is a short-hand for [`Self::subscribe_with_topics_listener`], which uses a no-op
316    /// listener. If you need the ability to seek to particular offsets, you should prefer
317    /// [`Self::subscribe_with_topics_listener`], since group rebalances will cause partition
318    /// offsets to be reset. You should also provide your own listener if you are doing your own
319    /// offset management since the listener gives you an opportunity to commit offsets before a
320    /// rebalance finishes.
321    ///
322    /// # Arguments
323    ///
324    /// - `topics` - The list of topics to subscribe to
325    ///
326    /// # Errors
327    ///
328    /// - `Error::is_local_illegal_argument_error` If topics is None or contains None or empty
329    ///   elements
330    /// - `Error::is_local_illegal_state_error` If `subscribe()` is called previously with pattern,
331    ///   or assign is called previously (without a subsequent call to `Self::unsubscribe`), or if
332    ///   not configured at-least one partition assignment strategy
333    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#subscribe")]
334    fn subscribe_with_topics(&mut self, topics: Vec<String>) -> impl Future<Output = Result<(), Error>> + Send;
335
336    /// Subscribe to the given list of topics to get dynamically assigned partitions. **Topic
337    /// subscriptions are not incremental. This list will replace the current assignment (if
338    /// there is one).** Note that it is not possible to combine topic subscription with group
339    /// management with manual partition assignment through `Self::assign`. If the given list of
340    /// topics is empty, it is treated the same as `Self::unsubscribe`.
341    ///
342    /// As part of group management, the group coordinator will keep track of the list of
343    /// consumers that belong to a particular group and will trigger a rebalance operation if
344    /// any one of the following events are triggered:
345    ///
346    /// - Number of partitions change for any of the subscribed topics
347    /// - A subscribed topic is created or deleted
348    /// - An existing member of the consumer group is shutdown or fails
349    /// - A new member is added to the consumer group
350    ///
351    /// When any of these events are triggered, the provided listener will be invoked in this
352    /// way:
353    ///
354    /// - [`ConsumerRebalanceListener::on_partitions_revoked`] will be invoked with the
355    ///   partitions to revoke, before re-assigning those partitions to another consumer.
356    /// - [`ConsumerRebalanceListener::on_partitions_assigned`] will be invoked when the
357    ///   rebalance completes (even if no new partitions are assigned to the consumer)
358    ///
359    /// Note that rebalances will only occur during an active call to `Self::poll`, so callbacks
360    /// will also only be invoked during that time. The provided listener will immediately
361    /// override any listener set in a previous call to subscribe. It is guaranteed, however,
362    /// that the partitions revoked/assigned through this interface are from topics subscribed
363    /// in this call. See `ConsumerRebalanceListener` for more details.
364    ///
365    /// # Arguments
366    ///
367    /// - `topics` - The list of topics to subscribe to
368    /// - `listener` - Non-None listener instance to get notifications on partition
369    ///   assignment/revocation for the subscribed topics
370    ///
371    /// # Errors
372    ///
373    /// - `Error::is_local_illegal_argument_error` If topics is None or contains None or empty
374    ///   elements, or if listener is None
375    /// - `Error::is_local_illegal_state_error` If `subscribe()` is called previously with pattern,
376    ///   or assign is called previously (without a subsequent call to `Self::unsubscribe`), or if
377    ///   not configured at-least one partition assignment strategy
378    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#subscribe")]
379    fn subscribe_with_topics_listener(
380        &mut self,
381        topics: Vec<String>,
382        listener: Arc<dyn ConsumerRebalanceListener>,
383    ) -> impl Future<Output = Result<(), Error>> + Send;
384
385    /// Subscribe to all topics matching the specified pattern, to get dynamically assigned
386    /// partitions. The pattern matching will be done periodically against topics. This is only
387    /// supported under the CONSUMER group protocol (see `ConsumerConfig::GROUP_PROTOCOL_CONFIG`)
388    ///
389    /// If the provided pattern is not compatible with Google RE2/J, an
390    /// `Error::is_invalid_regular_expression_error` will be eventually returned on a call to
391    /// [`Self::poll`] following this call to subscribe.
392    ///
393    /// This is a short-hand for [`Self::subscribe_with_pattern_listener`], which uses a no-op
394    /// listener.
395    ///
396    /// # Arguments
397    ///
398    /// - `pattern` - Pattern to subscribe to
399    ///
400    /// # Errors
401    ///
402    /// - `Error::is_local_illegal_argument_error` If pattern or listener is None
403    /// - `Error::is_local_illegal_state_error` If `subscribe()` is called previously with topics,
404    ///   or assign is called previously (without a subsequent call to `Self::unsubscribe`), or if
405    ///   not configured at-least one partition assignment strategy
406    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#subscribe")]
407    fn subscribe_with_pattern(
408        &mut self,
409        pattern: SubscriptionPattern,
410    ) -> impl Future<Output = Result<(), Error>> + Send;
411
412    /// Subscribe to all topics matching the specified pattern, to get dynamically assigned
413    /// partitions. The pattern matching will be done periodically against all topics. This is
414    /// only supported under the CONSUMER group protocol (see
415    /// `ConsumerConfig::GROUP_PROTOCOL_CONFIG`).
416    ///
417    /// If the provided pattern is not compatible with Google RE2/J, an
418    /// `Error::is_invalid_regular_expression_error` will be eventually returned on a call to
419    /// [`Self::poll`] following this call to subscribe.
420    ///
421    /// See [`Self::subscribe_with_topics_listener`] for details on the use of the
422    /// [`ConsumerRebalanceListener`]. Generally, rebalances are triggered when there is a change
423    /// to the topics matching the provided pattern and when consumer group membership changes.
424    /// Group rebalances only take place during an active call to [`Self::poll`].
425    ///
426    /// # Arguments
427    ///
428    /// - `pattern` - Pattern to subscribe to
429    /// - `listener` - Non-None listener instance to get notifications on partition
430    ///   assignment/revocation for the subscribed topics
431    ///
432    /// # Errors
433    ///
434    /// - `Error::is_local_illegal_argument_error` If pattern or listener is None
435    /// - `Error::is_local_illegal_state_error` If `subscribe()` is called previously with topics,
436    ///   or assign is called previously (without a subsequent call to `Self::unsubscribe`), or if
437    ///   not configured at-least one partition assignment strategy
438    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#subscribe")]
439    fn subscribe_with_pattern_listener(
440        &mut self,
441        pattern: SubscriptionPattern,
442        listener: Arc<dyn ConsumerRebalanceListener>,
443    ) -> impl Future<Output = Result<(), Error>> + Send;
444
445    /// Manually assign a list of partitions to this consumer. This interface does not allow for
446    /// incremental assignment and will replace the previous assignment (if there is one).
447    ///
448    /// If the given list of topic partitions is empty, it is treated the same as
449    /// `Self::unsubscribe`.
450    ///
451    /// Manual topic assignment through this method does not use the consumer's group management
452    /// functionality. As such, there will be no rebalance operation triggered when group
453    /// membership or cluster and topic metadata change. Note that it is not possible to use
454    /// both manual partition assignment with [`Self::assign`] and group assignment with
455    /// [`Self::subscribe_with_topics`].
456    ///
457    /// If auto-commit is enabled, an async commit (based on the old assignment) will be
458    /// triggered before the new assignment replaces the old one.
459    ///
460    /// # Arguments
461    ///
462    /// - `partitions` - The list of partitions to assign this consumer
463    ///
464    /// # Errors
465    ///
466    /// - `Error::is_local_illegal_argument_error` If partitions is None or contains None or empty
467    ///   topics
468    /// - `Error::is_local_illegal_state_error` If `subscribe()` is called previously with topics or
469    ///   pattern (without a subsequent call to `Self::unsubscribe`)
470    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#assign")]
471    fn assign(&mut self, partitions: Vec<TopicPartition>) -> impl Future<Output = Result<(), Error>> + Send;
472
473    /// Unsubscribe from topics currently subscribed with
474    /// [`Self::subscribe_with_topics`] or [`Self::subscribe_with_pattern`].
475    /// This also clears any partitions directly assigned through
476    /// [`Self::assign`].
477    ///
478    /// **Note:** Unlike [`Self::close`], this method does not commit the
479    /// pending offsets before unsubscribing, even if `enable.auto.commit` is
480    /// enabled. To avoid duplicate processing upon re-joining, it is
481    /// recommended to explicitly call [`Self::commit_sync`] before invoking this
482    /// method.
483    ///
484    /// # Errors
485    ///
486    /// - `Error::is_kafka_error` for any other unrecoverable errors (e.g. rebalance callback
487    ///   errors)
488    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#unsubscribe")]
489    fn unsubscribe(&mut self) -> impl Future<Output = Result<(), Error>> + Send;
490
491    // ── Poll ──
492
493    /// Fetch data for the topics or partitions specified using one of the subscribe/assign
494    /// APIs. It is an error to not have subscribed to any topics or partitions before polling
495    /// for data.
496    ///
497    /// On each poll, consumer will try to use the last consumed offset as the starting offset
498    /// and fetch sequentially. The last consumed offset can be manually set through
499    /// `Self::seek` or automatically set as the last committed offset for the subscribed list
500    /// of partitions
501    ///
502    /// This method returns immediately if there are records available or if the position
503    /// advances past control records or aborted transactions when
504    /// isolation.level=read_committed. Otherwise, it will await the passed timeout. If the
505    /// timeout expires, an empty record set will be returned. Note that this method may block
506    /// beyond the timeout in order to execute custom `ConsumerRebalanceListener` callbacks.
507    ///
508    /// # Arguments
509    ///
510    /// - `timeout` - The maximum time to block (must not be greater than `Long::MAX_VALUE`
511    ///   milliseconds)
512    ///
513    /// # Returns
514    ///
515    /// map of topic to records since the last fetch for the subscribed list of topics and
516    /// partitions
517    ///
518    /// # Errors
519    ///
520    /// - `Error::is_consumer_invalid_offset_error` if the offset for a partition or set of
521    ///   partitions is undefined or out of range and no offset reset policy has been configured
522    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
523    ///   called
524    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
525    ///   function is called
526    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
527    /// - `Error::is_authorization_error` if caller lacks Read access to any of the subscribed
528    ///   topics or to the configured groupId. See the error for more details
529    /// - `Error::is_bootstrap_resolution_error` if DNS resolution of the bootstrap servers fails
530    ///   within `bootstrap.resolve.timeout.ms`
531    /// - `Error::is_kafka_error` for any other unrecoverable errors (e.g. invalid groupId or
532    ///   session timeout, errors deserializing key/value pairs, your rebalance callback thrown
533    ///   errors, or any new error cases in future versions)
534    /// - `Error::is_local_illegal_argument_error` if the timeout value is negative
535    /// - `Error::is_local_illegal_state_error` if the consumer is not subscribed to any topics or
536    ///   manually assigned any partitions to consume from
537    /// - `Error::is_invalid_topic_error` if the current subscription contains any invalid topic
538    ///   (per `Topic::validate`)
539    /// - `Error::is_unsupported_version_error` if the consumer attempts to fetch stable offsets
540    ///   when the broker doesn't support this feature. Also, if the consumer attempts to subscribe
541    ///   to a SubscriptionPattern via [`Self::subscribe_with_pattern`] and the broker doesn't
542    ///   support this feature.
543    /// - `Error::is_fenced_instance_id_error` if this consumer instance gets fenced by broker.
544    ///
545    /// # Translation notes
546    ///
547    /// The returned future may be dropped before it completes, for example by
548    /// `tokio::time::timeout` or a `tokio::select!`, also while a
549    /// [`Deserializer`](crate::common::serialization::Deserializer) is
550    /// pending. The call then returns no records and leaves the positions
551    /// where they were before it, also when a partition's leader changed in
552    /// the meantime, so a later commit of the consumed offsets covers none of
553    /// the records it decoded, and a later `poll()` returns them, unless the
554    /// partition was sought, reset, paused or reassigned in between.
555    ///
556    /// WARNING: a `timeout` greater than `i64::MAX` milliseconds counts as
557    /// `i64::MAX` milliseconds, where Java throws `ArithmeticException`, so
558    /// `Duration::MAX` waits without limit.
559    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#poll")]
560    fn poll(&mut self, timeout: Duration) -> impl Future<Output = Result<ConsumerRecords<K, V>, Error>> + Send;
561
562    // ── Commit ──
563
564    /// Commit offsets returned on the last poll() for all the subscribed list of topics and
565    /// partitions.
566    ///
567    /// This commits offsets only to Kafka. The offsets committed using this API will be used on
568    /// the first fetch after every rebalance and also on startup. As such, if you need to store
569    /// offsets in anything other than Kafka, this API should not be used.
570    ///
571    /// This is a synchronous commit and will block until either the commit succeeds, an
572    /// unrecoverable error is encountered (in which case it is returned to the caller), or the
573    /// timeout specified by `default.api.timeout.ms` expires (in which case an
574    /// `Error::is_timeout_error` is returned to the caller).
575    ///
576    /// Note that asynchronous offset commits sent previously with the [`Self::commit_async`] (or
577    /// similar) are guaranteed to have their callbacks invoked prior to completion of this
578    /// method, but only when the consumer is using the consumer group protocol.
579    ///
580    /// # Errors
581    ///
582    /// - `Error::is_consumer_commit_failed_error` if the commit failed and cannot be retried. This
583    ///   fatal error can only occur if you are using automatic group management with
584    ///   `Self::subscribe`, or if there is an active group with the same `group.id` which is using
585    ///   group management. In such cases, when you are trying to commit to partitions that are no
586    ///   longer assigned to this consumer because the consumer is for example no longer part of the
587    ///   group this error would be thrown.
588    /// - `Error::is_rebalance_in_progress_error` if the consumer instance is in the middle of a
589    ///   rebalance so it is not yet determined which partitions would be assigned to the consumer.
590    ///   In such cases you can first complete the rebalance by calling `Self::poll` and commit can
591    ///   be reconsidered afterwards. NOTE when you reconsider committing after the rebalance, the
592    ///   assigned partitions may have changed, and also for those partitions that are still
593    ///   assigned their fetch positions may have changed too if more records are returned from the
594    ///   `Self::poll` call.
595    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
596    ///   called
597    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
598    ///   function is called
599    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
600    /// - `Error::is_authorization_error` if not authorized to the topic or to the configured
601    ///   groupId. See the error for more details
602    /// - `Error::is_kafka_error` for any other unrecoverable errors (e.g. if offset metadata is too
603    ///   large or if the topic does not exist).
604    /// - `Error::is_timeout_error` if the timeout specified by `default.api.timeout.ms` expires
605    ///   before successful completion of the offset commit
606    /// - `Error::is_fenced_instance_id_error` if this consumer is using the classic group protocol
607    ///   and this instance gets fenced by broker.
608    /// - `Error::is_bootstrap_resolution_error` if DNS resolution of the bootstrap servers fails
609    ///   within `bootstrap.resolve.timeout.ms`
610    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#commitSync")]
611    fn commit_sync(&mut self) -> impl Future<Output = Result<(), Error>> + Send;
612
613    /// Commit offsets returned on the last poll() for all the subscribed list of topics and
614    /// partitions.
615    ///
616    /// This commits offsets only to Kafka. The offsets committed using this API will be used on
617    /// the first fetch after every rebalance and also on startup. As such, if you need to store
618    /// offsets in anything other than Kafka, this API should not be used.
619    ///
620    /// This is a synchronous commit and will block until either the commit succeeds, an
621    /// unrecoverable error is encountered (in which case it is returned to the caller), or the
622    /// passed timeout expires.
623    ///
624    /// Note that asynchronous offset commits sent previously with the [`Self::commit_async`] (or
625    /// similar) are guaranteed to have their callbacks invoked prior to completion of this
626    /// method, but only when the consumer is using the consumer group protocol.
627    ///
628    /// # Arguments
629    ///
630    /// - `timeout` - The maximum amount of time to await completion of the offset commit
631    ///
632    /// # Errors
633    ///
634    /// - `Error::is_consumer_commit_failed_error` if the commit failed and cannot be retried. This
635    ///   can only occur if you are using automatic group management with `Self::subscribe`, or if
636    ///   there is an active group with the same `group.id` which is using group management. In such
637    ///   cases, when you are trying to commit to partitions that are no longer assigned to this
638    ///   consumer because the consumer is for example no longer part of the group this error would
639    ///   be thrown.
640    /// - `Error::is_rebalance_in_progress_error` if the consumer instance is in the middle of a
641    ///   rebalance so it is not yet determined which partitions would be assigned to the consumer.
642    ///   In such cases you can first complete the rebalance by calling `Self::poll` and commit can
643    ///   be reconsidered afterwards. NOTE when you reconsider committing after the rebalance, the
644    ///   assigned partitions may have changed, and also for those partitions that are still
645    ///   assigned their fetch positions may have changed too if more records are returned from the
646    ///   `Self::poll` call, so when you retry committing you should consider updating the passed in
647    ///   `offset` parameter.
648    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
649    ///   called
650    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
651    ///   function is called
652    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
653    /// - `Error::is_authorization_error` if not authorized to the topic or to the configured
654    ///   groupId. See the error for more details
655    /// - `Error::is_local_illegal_argument_error` if the committed offset is negative
656    /// - `Error::is_kafka_error` for any other unrecoverable errors (e.g. if offset metadata is too
657    ///   large or if the topic does not exist).
658    /// - `Error::is_timeout_error` if the timeout expires before successful completion of the
659    ///   offset commit
660    /// - `Error::is_fenced_instance_id_error` if this consumer is using the classic group protocol
661    ///   and this instance gets fenced by broker.
662    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#commitSync")]
663    fn commit_sync_with_timeout(&mut self, timeout: Duration) -> impl Future<Output = Result<(), Error>> + Send;
664
665    /// Commit the specified offsets for the specified list of topics and partitions.
666    ///
667    /// This commits offsets to Kafka. The offsets committed using this API will be used on the
668    /// first fetch after every rebalance and also on startup. As such, if you need to store
669    /// offsets in anything other than Kafka, this API should not be used. The committed offset
670    /// should be the next message your application will consume, i.e.
671    /// `nextRecordToBeProcessed.offset()` (or `ConsumerRecords::next_offsets`). You should also
672    /// add the leader epoch as commit metadata, which can be obtained from
673    /// `ConsumerRecord::leader_epoch` or `ConsumerRecords::next_offsets`. If automatic group
674    /// management with `Self::subscribe` is used, then the committed offsets must belong to the
675    /// currently auto-assigned partitions.
676    ///
677    /// This is a synchronous commit and will block until either the commit succeeds or an
678    /// unrecoverable error is encountered (in which case it is thrown to the caller), or the
679    /// timeout specified by `default.api.timeout.ms` expires (in which case a `TimeoutError` is
680    /// thrown to the caller).
681    ///
682    /// Note that asynchronous offset commits sent previously with the `Self::commit_async` (or
683    /// similar) are guaranteed to have their callbacks invoked prior to completion of this
684    /// method, but only when the consumer is using the consumer group protocol.
685    ///
686    /// # Arguments
687    ///
688    /// - `offsets` - A map of offsets by partition with associated metadata. This map will be
689    ///   copied internally, so it is safe to mutate the map after returning.
690    ///
691    /// # Errors
692    ///
693    /// - `Error::is_consumer_commit_failed_error` if the commit failed and cannot be retried. This
694    ///   can only occur if you are using automatic group management with `Self::subscribe`, or if
695    ///   there is an active group with the same `group.id` which is using group management. In such
696    ///   cases, when you are trying to commit to partitions that are no longer assigned to this
697    ///   consumer because the consumer is for example no longer part of the group this error would
698    ///   be thrown.
699    /// - `Error::is_rebalance_in_progress_error` if the consumer instance is in the middle of a
700    ///   rebalance so it is not yet determined which partitions would be assigned to the consumer.
701    ///   In such cases you can first complete the rebalance by calling `Self::poll` and commit can
702    ///   be reconsidered afterwards. NOTE when you reconsider committing after the rebalance, the
703    ///   assigned partitions may have changed, and also for those partitions that are still
704    ///   assigned their fetch positions may have changed too if more records are returned from the
705    ///   `Self::poll` call, so when you retry committing you should consider updating the passed in
706    ///   `offset` parameter.
707    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
708    ///   called
709    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
710    ///   function is called
711    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
712    /// - `Error::is_authorization_error` if not authorized to the topic or to the configured
713    ///   groupId. See the error for more details
714    /// - `Error::is_local_illegal_argument_error` if the committed offset is negative
715    /// - `Error::is_kafka_error` for any other unrecoverable errors (e.g. if offset metadata is too
716    ///   large or if the topic does not exist).
717    /// - `Error::is_timeout_error` if the timeout expires before successful completion of the
718    ///   offset commit
719    /// - `Error::is_fenced_instance_id_error` if this consumer is using the classic group protocol
720    ///   and this instance gets fenced by broker.
721    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#commitSync")]
722    fn commit_sync_with_offsets(
723        &mut self,
724        offsets: HashMap<TopicPartition, OffsetAndMetadata>,
725    ) -> impl Future<Output = Result<(), Error>> + Send;
726
727    /// Commit the specified offsets for the specified list of topics and partitions.
728    ///
729    /// This commits offsets to Kafka. The offsets committed using this API will be used on the
730    /// first fetch after every rebalance and also on startup. As such, if you need to store
731    /// offsets in anything other than Kafka, this API should not be used. The committed offset
732    /// should be the next message your application will consume, i.e.
733    /// `nextRecordToBeProcessed.offset()` (or `ConsumerRecords::next_offsets`). You should also
734    /// add the leader epoch as commit metadata, which can be obtained from
735    /// `ConsumerRecord::leader_epoch` or `ConsumerRecords::next_offsets`. If automatic group
736    /// management with `Self::subscribe` is used, then the committed offsets must belong to the
737    /// currently auto-assigned partitions.
738    ///
739    /// This is a synchronous commit and will block until either the commit succeeds, an
740    /// unrecoverable error is encountered (in which case it is thrown to the caller), or the
741    /// timeout expires.
742    ///
743    /// Note that asynchronous offset commits sent previously with the `Self::commit_async` (or
744    /// similar) are guaranteed to have their callbacks invoked prior to completion of this
745    /// method, but only when the consumer is using the consumer group protocol.
746    ///
747    /// # Arguments
748    ///
749    /// - `offsets` - A map of offsets by partition with associated metadata. This map will be
750    ///   copied internally, so it is safe to mutate the map after returning.
751    /// - `timeout` - The maximum amount of time to await completion of the offset commit
752    ///
753    /// # Errors
754    ///
755    /// - `Error::is_consumer_commit_failed_error` if the commit failed and cannot be retried. This
756    ///   can only occur if you are using automatic group management with `Self::subscribe`, or if
757    ///   there is an active group with the same `group.id` which is using group management. In such
758    ///   cases, when you are trying to commit to partitions that are no longer assigned to this
759    ///   consumer because the consumer is for example no longer part of the group this error would
760    ///   be thrown.
761    /// - `Error::is_rebalance_in_progress_error` if the consumer instance is in the middle of a
762    ///   rebalance so it is not yet determined which partitions would be assigned to the consumer.
763    ///   In such cases you can first complete the rebalance by calling `Self::poll` and commit can
764    ///   be reconsidered afterwards. NOTE when you reconsider committing after the rebalance, the
765    ///   assigned partitions may have changed, and also for those partitions that are still
766    ///   assigned their fetch positions may have changed too if more records are returned from the
767    ///   `Self::poll` call, so when you retry committing you should consider updating the passed in
768    ///   `offset` parameter.
769    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
770    ///   called
771    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
772    ///   function is called
773    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
774    /// - `Error::is_authorization_error` if not authorized to the topic or to the configured
775    ///   groupId. See the error for more details
776    /// - `Error::is_local_illegal_argument_error` if the committed offset is negative
777    /// - `Error::is_kafka_error` for any other unrecoverable errors (e.g. if offset metadata is too
778    ///   large or if the topic does not exist).
779    /// - `Error::is_timeout_error` if the timeout expires before successful completion of the
780    ///   offset commit
781    /// - `Error::is_fenced_instance_id_error` if this consumer is using the classic group protocol
782    ///   and this instance gets fenced by broker.
783    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#commitSync")]
784    fn commit_sync_with_offsets_timeout(
785        &mut self,
786        offsets: HashMap<TopicPartition, OffsetAndMetadata>,
787        timeout: Duration,
788    ) -> impl Future<Output = Result<(), Error>> + Send;
789
790    /// Commit offsets returned on the last `Self::poll` for all the subscribed list of topics
791    /// and partition. Same as commitAsync(None)
792    ///
793    /// # Errors
794    ///
795    /// - `Error::is_fenced_instance_id_error` if this consumer is using the classic group protocol
796    ///   and this instance gets fenced by broker.
797    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#commitAsync")]
798    fn commit_async(&mut self) -> impl Future<Output = Result<(), Error>> + Send;
799
800    /// Commit offsets returned on the last poll() for the subscribed list of topics and
801    /// partitions.
802    ///
803    /// This commits offsets only to Kafka. The offsets committed using this API will be used on
804    /// the first fetch after every rebalance and also on startup. As such, if you need to store
805    /// offsets in anything other than Kafka, this API should not be used.
806    ///
807    /// This is an asynchronous call and will not block. Any errors encountered are either
808    /// passed to the callback (if provided) or discarded.
809    ///
810    /// Offsets committed through multiple calls to this API are guaranteed to be sent in the
811    /// same order as the invocations. Corresponding commit callbacks are also invoked in the
812    /// same order. Additionally note that offsets committed through this API are guaranteed to
813    /// complete before a subsequent call to `Self::commit_sync` (and variants) returns.
814    ///
815    /// # Arguments
816    ///
817    /// - `callback` - Callback to invoke when the commit completes
818    ///
819    /// # Errors
820    ///
821    /// - `Error::is_fenced_instance_id_error` if this consumer is using the classic group protocol
822    ///   and this instance gets fenced by broker.
823    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#commitAsync")]
824    fn commit_async_with_callback(
825        &mut self,
826        callback: Arc<dyn OffsetCommitCallback>,
827    ) -> impl Future<Output = Result<(), Error>> + Send;
828
829    /// Commit the specified offsets for the specified list of topics and partitions to Kafka.
830    ///
831    /// This commits offsets to Kafka. The offsets committed using this API will be used on the
832    /// first fetch after every rebalance and also on startup. As such, if you need to store
833    /// offsets in anything other than Kafka, this API should not be used. The committed offset
834    /// should be the next message your application will consume, i.e.
835    /// `nextRecordToBeProcessed.offset()` (or `ConsumerRecords::next_offsets`). You should also
836    /// add the leader epoch as commit metadata, which can be obtained from
837    /// `ConsumerRecord::leader_epoch` or `ConsumerRecords::next_offsets`. If automatic group
838    /// management with `Self::subscribe` is used, then the committed offsets must belong to the
839    /// currently auto-assigned partitions.
840    ///
841    /// This is an asynchronous call and will not block. Any errors encountered are either
842    /// passed to the callback (if provided) or discarded.
843    ///
844    /// Offsets committed through multiple calls to this API are guaranteed to be sent in the
845    /// same order as the invocations. Corresponding commit callbacks are also invoked in the
846    /// same order. Additionally note that offsets committed through this API are guaranteed to
847    /// complete before a subsequent call to `Self::commit_sync` (and variants) returns.
848    ///
849    /// # Arguments
850    ///
851    /// - `offsets` - A map of offsets by partition with associated metadata. This map will be
852    ///   copied internally, so it is safe to mutate the map after returning.
853    /// - `callback` - Callback to invoke when the commit completes
854    ///
855    /// # Errors
856    ///
857    /// - `Error::is_fenced_instance_id_error` if this consumer is using the classic group protocol
858    ///   and this instance gets fenced by broker.
859    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#commitAsync")]
860    fn commit_async_with_offsets_callback(
861        &mut self,
862        offsets: HashMap<TopicPartition, OffsetAndMetadata>,
863        callback: Arc<dyn OffsetCommitCallback>,
864    ) -> impl Future<Output = Result<(), Error>> + Send;
865
866    // ── Seek (async — Java: addAndGet on SeekUnvalidatedEvent / ResetOffsetEvent) ──
867
868    /// Overrides the fetch offsets that the consumer will use on the next poll(timeout). If
869    /// this API is invoked for the same partition more than once, the latest offset will be
870    /// used on the next poll(). Note that you may lose data if this API is arbitrarily used in
871    /// the middle of consumption, to reset the fetch offsets
872    ///
873    /// The next Consumer Record which will be retrieved when poll() is invoked will have the
874    /// offset specified, given that a record with that offset exists (i.e. it is a valid
875    /// offset).
876    ///
877    /// `Self::seek_to_beginning` will go to the first offset in the topic. seek(0) is
878    /// equivalent to seekToBeginning for a TopicPartition with beginning offset 0, assuming
879    /// that there is a record at offset 0 still available. `Self::seek_to_end` is equivalent to
880    /// seeking to the last offset of the partition, but behavior depends on `isolation.level`,
881    /// so see `Self::seek_to_end` documentation for more details.
882    ///
883    /// Seeking to the offset smaller than the log start offset or larger than the log end
884    /// offset means an invalid offset is reached. Invalid offset behaviour is controlled by the
885    /// `auto.offset.reset` property. If this is set to "earliest", the next poll will return
886    /// records from the starting offset. If it is set to "latest", it will seek to the last
887    /// offset (similar to seekToEnd()). If it is set to "none", an
888    /// `ConsumerOffsetOutOfRangeError` will be thrown.
889    ///
890    /// Note that, the seek offset won't change to the in-flight fetch request, it will take
891    /// effect in next fetch request. So, the consumer might wait for `fetch.max.wait.ms` before
892    /// starting to fetch the records from desired offset.
893    ///
894    /// # Arguments
895    ///
896    /// - `partition` - the TopicPartition on which the seek will be performed.
897    /// - `offset` - the next offset returned by poll().
898    ///
899    /// # Errors
900    ///
901    /// - `Error::is_local_illegal_argument_error` if the provided offset is negative
902    /// - `Error::is_local_illegal_state_error` if the provided TopicPartition is not assigned to
903    ///   this consumer
904    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#seek")]
905    fn seek_with_offset(
906        &mut self,
907        partition: TopicPartition,
908        offset: i64,
909    ) -> impl Future<Output = Result<(), Error>> + Send;
910
911    /// Overrides the fetch offsets that the consumer will use on the next
912    /// `poll(timeout)`. If this API is invoked for the same partition more than
913    /// once, the latest offset will be used on the next `poll()`. Note that you
914    /// may lose data if this API is arbitrarily used in the middle of
915    /// consumption, to reset the fetch offsets. This method allows for setting
916    /// the leaderEpoch along with the desired offset.
917    ///
918    /// # Arguments
919    ///
920    /// - `partition` - the TopicPartition on which the seek will be performed.
921    /// - `offset_and_metadata` - the next offset returned by poll(), with its
922    ///   leader epoch.
923    ///
924    /// # Errors
925    ///
926    /// - `Error::is_local_illegal_argument_error` if the provided offset is negative
927    /// - `Error::is_local_illegal_state_error` if the provided TopicPartition is not assigned to
928    ///   this consumer
929    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#seek")]
930    fn seek_with_offset_and_metadata(
931        &mut self,
932        partition: TopicPartition,
933        offset_and_metadata: OffsetAndMetadata,
934    ) -> impl Future<Output = Result<(), Error>> + Send;
935
936    /// Seek to the first offset for each of the given partitions. This function
937    /// evaluates lazily, seeking to the first offset in all partitions only when
938    /// [`Self::poll`] or [`Self::position`] are called. If no partitions are
939    /// provided, seek to the first offset for all of the currently assigned
940    /// partitions.
941    ///
942    /// # Arguments
943    ///
944    /// - `partitions` - The partitions to seek
945    ///
946    /// # Errors
947    ///
948    /// - `Error::is_local_illegal_argument_error` if `partitions` is `None`
949    /// - `Error::is_local_illegal_state_error` if any of the provided partitions are not currently
950    ///   assigned to this consumer
951    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#seekToBeginning")]
952    fn seek_to_beginning(&mut self, partitions: &[TopicPartition]) -> impl Future<Output = Result<(), Error>> + Send;
953
954    /// Seek to the last offset for each of the given partitions. This function
955    /// evaluates lazily, seeking to the final offset in all partitions only when
956    /// [`Self::poll`] or [`Self::position`] are called. If no partitions are
957    /// provided, seek to the final offset for all of the currently assigned
958    /// partitions.
959    ///
960    /// If `isolation.level=read_committed`, the end offset will be the Last
961    /// Stable Offset, i.e., the offset of the first message with an open
962    /// transaction.
963    ///
964    /// # Arguments
965    ///
966    /// - `partitions` - The partitions to seek
967    ///
968    /// # Errors
969    ///
970    /// - `Error::is_local_illegal_argument_error` if `partitions` is `None`
971    /// - `Error::is_local_illegal_state_error` if any of the provided partitions are not currently
972    ///   assigned to this consumer
973    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#seekToEnd")]
974    fn seek_to_end(&mut self, partitions: &[TopicPartition]) -> impl Future<Output = Result<(), Error>> + Send;
975
976    // ── Position / committed (async — may fetch from broker) ──
977
978    /// Get the offset of the *next record* that will be fetched (if a record with that offset
979    /// exists). This method may issue a remote call to the server if there is no current
980    /// position for the given partition.
981    ///
982    /// This call will block until either the position could be determined or an unrecoverable
983    /// error is encountered (in which case it is thrown to the caller), or the timeout
984    /// specified by `default.api.timeout.ms` expires (in which case a `TimeoutError` is thrown
985    /// to the caller).
986    ///
987    /// # Arguments
988    ///
989    /// - `partition` - The partition to get the position for
990    ///
991    /// # Returns
992    ///
993    /// The current position of the consumer (that is, the offset of the next record to be fetched)
994    ///
995    /// # Errors
996    ///
997    /// - `Error::is_local_illegal_state_error` if the provided TopicPartition is not assigned to
998    ///   this consumer
999    /// - `Error::is_consumer_invalid_offset_error` if no offset is currently defined for the
1000    ///   partition
1001    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
1002    ///   called
1003    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
1004    ///   function is called
1005    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
1006    /// - `Error::is_authorization_error` if not authorized to the topic or to the configured
1007    ///   groupId. See the error for more details
1008    /// - `Error::is_unsupported_version_error` if the consumer attempts to fetch stable offsets
1009    ///   when the broker doesn't support this feature
1010    /// - `Error::is_kafka_error` for any other unrecoverable errors
1011    /// - `Error::is_timeout_error` if the position cannot be determined before the timeout
1012    ///   specified by `default.api.timeout.ms` expires
1013    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#position")]
1014    fn position(&mut self, partition: &TopicPartition) -> impl Future<Output = Result<i64, Error>> + Send;
1015
1016    /// Get the offset of the *next record* that will be fetched (if a record with that offset
1017    /// exists). This method may issue a remote call to the server if there is no current
1018    /// position for the given partition.
1019    ///
1020    /// This call will block until the position can be determined, an unrecoverable error is
1021    /// encountered (in which case it is thrown to the caller), or the timeout expires.
1022    ///
1023    /// # Arguments
1024    ///
1025    /// - `partition` - The partition to get the position for
1026    /// - `timeout` - The maximum amount of time to await determination of the current position
1027    ///
1028    /// # Returns
1029    ///
1030    /// The current position of the consumer (that is, the offset of the next record to be fetched)
1031    ///
1032    /// # Errors
1033    ///
1034    /// - `Error::is_local_illegal_state_error` if the provided TopicPartition is not assigned to
1035    ///   this consumer
1036    /// - `Error::is_consumer_invalid_offset_error` if no offset is currently defined for the
1037    ///   partition
1038    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
1039    ///   called
1040    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
1041    ///   function is called
1042    /// - `Error::is_timeout_error` if the position cannot be determined before the passed timeout
1043    ///   expires
1044    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
1045    /// - `Error::is_authorization_error` if not authorized to the topic or to the configured
1046    ///   groupId. See the error for more details
1047    /// - `Error::is_kafka_error` for any other unrecoverable errors
1048    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#position")]
1049    fn position_with_timeout(
1050        &mut self,
1051        partition: &TopicPartition,
1052        timeout: Duration,
1053    ) -> impl Future<Output = Result<i64, Error>> + Send;
1054
1055    /// Get the last committed offsets for the given partitions (whether the commit happened by
1056    /// this process or another). The returned offsets will be used as the position for the
1057    /// consumer in the event of a failure.
1058    ///
1059    /// If any of the partitions requested do not exist, the result map will contain `None` as the
1060    /// value for that partition.
1061    ///
1062    /// This call will do a remote call to get the latest committed offsets from the server, and
1063    /// will block until the committed offsets are gotten successfully, an unrecoverable error
1064    /// is encountered (in which case it is thrown to the caller), or the timeout specified by
1065    /// `default.api.timeout.ms` expires (in which case a `TimeoutError` is thrown to the
1066    /// caller).
1067    ///
1068    /// # Arguments
1069    ///
1070    /// - `partitions` - The partitions to check
1071    ///
1072    /// # Returns
1073    ///
1074    /// The latest committed offsets for the given partitions; `None` will be returned for the
1075    /// partition if there is no such message.
1076    ///
1077    /// # Errors
1078    ///
1079    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
1080    ///   called
1081    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
1082    ///   function is called
1083    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
1084    /// - `Error::is_authorization_error` if not authorized to the topic or to the configured
1085    ///   groupId. See the error for more details
1086    /// - `Error::is_unsupported_version_error` if the consumer attempts to fetch stable offsets
1087    ///   when the broker doesn't support this feature
1088    /// - `Error::is_kafka_error` for any other unrecoverable errors
1089    /// - `Error::is_timeout_error` if the committed offset cannot be found before the timeout
1090    ///   specified by `default.api.timeout.ms` expires.
1091    /// - `Error::is_bootstrap_resolution_error` if DNS resolution of the bootstrap servers fails
1092    ///   within `bootstrap.resolve.timeout.ms`
1093    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#committed")]
1094    fn committed(
1095        &mut self,
1096        partitions: &[TopicPartition],
1097    ) -> impl Future<Output = Result<HashMap<TopicPartition, Option<OffsetAndMetadata>>, Error>> + Send;
1098
1099    /// Get the last committed offsets for the given partitions (whether the commit happened by
1100    /// this process or another). The returned offsets will be used as the position for the
1101    /// consumer in the event of a failure.
1102    ///
1103    /// If any of the partitions requested do not exist, the result map will contain `None` as the
1104    /// value for that partition.
1105    ///
1106    /// This call will block to do a remote call to get the latest committed offsets from the
1107    /// server.
1108    ///
1109    /// # Arguments
1110    ///
1111    /// - `partitions` - The partitions to check
1112    /// - `timeout` - The maximum amount of time to await the latest committed offsets
1113    ///
1114    /// # Returns
1115    ///
1116    /// The latest committed offsets for the given partitions; `None` will be returned for the
1117    /// partition if there is no such message.
1118    ///
1119    /// # Errors
1120    ///
1121    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
1122    ///   called
1123    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
1124    ///   function is called
1125    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
1126    /// - `Error::is_authorization_error` if not authorized to the topic or to the configured
1127    ///   groupId. See the error for more details
1128    /// - `Error::is_kafka_error` for any other unrecoverable errors
1129    /// - `Error::is_timeout_error` if the committed offset cannot be found before expiration of the
1130    ///   timeout
1131    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#committed")]
1132    fn committed_with_timeout(
1133        &mut self,
1134        partitions: &[TopicPartition],
1135        timeout: Duration,
1136    ) -> impl Future<Output = Result<HashMap<TopicPartition, Option<OffsetAndMetadata>>, Error>> + Send;
1137
1138    // ── Metadata (async — may fetch from broker) ──
1139
1140    /// Get metadata about the partitions for a given topic. This method will issue a remote
1141    /// call to the server if it does not already have any metadata about the given topic.
1142    ///
1143    /// Returns the list of partitions, which will be empty when the given topic
1144    /// is not found. Note: when both the broker config
1145    /// `auto.create.topics.enable` and the consumer config
1146    /// `allow.auto.create.topics` are `true`, this method may return an empty
1147    /// list even though the topic is being auto-created in the background.
1148    /// Callers should not assume the topic does not exist based solely on an
1149    /// empty result.
1150    ///
1151    /// # Arguments
1152    ///
1153    /// - `topic` - The topic to get partition metadata for
1154    ///
1155    /// # Returns
1156    ///
1157    /// The list of partitions, which will be empty when the given topic is not found. Note: when
1158    /// both the broker config `auto.create.topics.enable` and the consumer config
1159    /// `allow.auto.create.topics` are `true`, this method may return an empty list even though the
1160    /// topic is being auto-created in the background. Callers should not assume the topic does not
1161    /// exist based solely on an empty result.
1162    ///
1163    /// # Errors
1164    ///
1165    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
1166    ///   called
1167    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
1168    ///   function is called
1169    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
1170    /// - `Error::is_authorization_error` if not authorized to the specified topic. See the error
1171    ///   for more details
1172    /// - `Error::is_kafka_error` for any other unrecoverable errors
1173    /// - `Error::is_timeout_error` if the offset metadata could not be fetched before the amount of
1174    ///   time allocated by `default.api.timeout.ms` expires.
1175    /// - `Error::is_bootstrap_resolution_error` if DNS resolution of the bootstrap servers fails
1176    ///   within `bootstrap.resolve.timeout.ms`
1177    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#partitionsFor")]
1178    fn partitions_for(&mut self, topic: &str) -> impl Future<Output = Result<Vec<PartitionInfo>, Error>> + Send;
1179
1180    /// Get metadata about the partitions for a given topic. This method will issue a remote
1181    /// call to the server if it does not already have any metadata about the given topic.
1182    ///
1183    /// Returns the list of partitions, which will be empty when the given topic
1184    /// is not found; see [`Self::partitions_for`] for the auto-topic-creation
1185    /// caveat on an empty result.
1186    ///
1187    /// # Arguments
1188    ///
1189    /// - `topic` - The topic to get partition metadata for
1190    /// - `timeout` - The maximum of time to await topic metadata
1191    ///
1192    /// # Returns
1193    ///
1194    /// The list of partitions, which will be empty when the given topic is not found. Note: when
1195    /// both the broker config `auto.create.topics.enable` and the consumer config
1196    /// `allow.auto.create.topics` are `true`, this method may return an empty list even though the
1197    /// topic is being auto-created in the background. Callers should not assume the topic does not
1198    /// exist based solely on an empty result.
1199    ///
1200    /// # Errors
1201    ///
1202    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
1203    ///   called
1204    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
1205    ///   function is called
1206    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
1207    /// - `Error::is_authorization_error` if not authorized to the specified topic. See the error
1208    ///   for more details
1209    /// - `Error::is_timeout_error` if topic metadata cannot be fetched before expiration of the
1210    ///   passed timeout
1211    /// - `Error::is_kafka_error` for any other unrecoverable errors
1212    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#partitionsFor")]
1213    fn partitions_for_with_timeout(
1214        &mut self,
1215        topic: &str,
1216        timeout: Duration,
1217    ) -> impl Future<Output = Result<Vec<PartitionInfo>, Error>> + Send;
1218
1219    /// Get metadata about partitions for all topics that the user is authorized to view. This
1220    /// method will issue a remote call to the server.
1221    ///
1222    /// # Returns
1223    ///
1224    /// The map of topics and its partitions
1225    ///
1226    /// # Errors
1227    ///
1228    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
1229    ///   called
1230    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
1231    ///   function is called
1232    /// - `Error::is_kafka_error` for any other unrecoverable errors
1233    /// - `Error::is_timeout_error` if the offset metadata could not be fetched before the amount of
1234    ///   time allocated by `default.api.timeout.ms` expires.
1235    /// - `Error::is_bootstrap_resolution_error` if DNS resolution of the bootstrap servers fails
1236    ///   within `bootstrap.resolve.timeout.ms`
1237    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#listTopics")]
1238    fn list_topics(&mut self) -> impl Future<Output = Result<HashMap<String, Vec<PartitionInfo>>, Error>> + Send;
1239
1240    /// Get metadata about partitions for all topics that the user is authorized to view. This
1241    /// method will issue a remote call to the server.
1242    ///
1243    /// # Arguments
1244    ///
1245    /// - `timeout` - The maximum time this operation will block to fetch topic metadata
1246    ///
1247    /// # Returns
1248    ///
1249    /// The map of topics and its partitions
1250    ///
1251    /// # Errors
1252    ///
1253    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
1254    ///   called
1255    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
1256    ///   function is called
1257    /// - `Error::is_timeout_error` if the topic metadata could not be fetched before expiration of
1258    ///   the passed timeout
1259    /// - `Error::is_kafka_error` for any other unrecoverable errors
1260    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#listTopics")]
1261    fn list_topics_with_timeout(
1262        &mut self,
1263        timeout: Duration,
1264    ) -> impl Future<Output = Result<HashMap<String, Vec<PartitionInfo>>, Error>> + Send;
1265
1266    /// Look up the offsets for the given partitions by timestamp. The returned offset for each
1267    /// partition is the earliest offset whose timestamp is greater than or equal to the given
1268    /// timestamp in the corresponding partition. This is a blocking call. The consumer does not
1269    /// have to be assigned the partitions. If the message format version in a partition is
1270    /// before 0.10.0, i.e. the messages do not have timestamps, `None` will be returned for
1271    /// that partition.
1272    ///
1273    /// # Arguments
1274    ///
1275    /// - `timestamps_to_search` - the mapping from partition to the timestamp to look up.
1276    ///
1277    /// # Returns
1278    ///
1279    /// a mapping from partition to the timestamp and offset of the first message with timestamp
1280    /// greater than or equal to the target timestamp. If the timestamp and offset for a specific
1281    /// partition cannot be found within the default timeout, and no corresponding message exists,
1282    /// the entry in the returned map will be `None`
1283    ///
1284    /// # Errors
1285    ///
1286    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
1287    /// - `Error::is_authorization_error` if not authorized to the topic(s). See the error for more
1288    ///   details
1289    /// - `Error::is_local_illegal_argument_error` if the target timestamp is negative
1290    /// - `Error::is_timeout_error` if the offset metadata could not be fetched before the amount of
1291    ///   time allocated by `default.api.timeout.ms` expires.
1292    /// - `Error::is_unsupported_version_error` if the broker does not support looking up the
1293    ///   offsets by timestamp
1294    /// - `Error::is_bootstrap_resolution_error` if DNS resolution of the bootstrap servers fails
1295    ///   within `bootstrap.resolve.timeout.ms`
1296    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#offsetsForTimes")]
1297    fn offsets_for_times(
1298        &mut self,
1299        timestamps_to_search: HashMap<TopicPartition, i64>,
1300    ) -> impl Future<Output = Result<HashMap<TopicPartition, Option<OffsetAndTimestamp>>, Error>> + Send;
1301
1302    /// Look up the offsets for the given partitions by timestamp. The returned offset for each
1303    /// partition is the earliest offset whose timestamp is greater than or equal to the given
1304    /// timestamp in the corresponding partition. This is a blocking call. The consumer does not
1305    /// have to be assigned the partitions. If the message format version in a partition is
1306    /// before 0.10.0, i.e. the messages do not have timestamps, `None` will be returned for
1307    /// that partition.
1308    ///
1309    /// # Arguments
1310    ///
1311    /// - `timestamps_to_search` - the mapping from partition to the timestamp to look up.
1312    /// - `timeout` - The maximum amount of time to await retrieval of the offsets
1313    ///
1314    /// # Returns
1315    ///
1316    /// a mapping from partition to the timestamp and offset of the first message with timestamp
1317    /// greater than or equal to the target timestamp. If the timestamp and offset for a specific
1318    /// partition cannot be found within timeout, and no corresponding message exists, the
1319    /// entry in the returned map will be `None`
1320    ///
1321    /// # Errors
1322    ///
1323    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
1324    /// - `Error::is_authorization_error` if not authorized to the topic(s). See the error for more
1325    ///   details
1326    /// - `Error::is_local_illegal_argument_error` if the target timestamp is negative
1327    /// - `Error::is_timeout_error` if the offset metadata could not be fetched before expiration of
1328    ///   the passed timeout
1329    /// - `Error::is_unsupported_version_error` if the broker does not support looking up the
1330    ///   offsets by timestamp
1331    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#offsetsForTimes")]
1332    fn offsets_for_times_with_timeout(
1333        &mut self,
1334        timestamps_to_search: HashMap<TopicPartition, i64>,
1335        timeout: Duration,
1336    ) -> impl Future<Output = Result<HashMap<TopicPartition, Option<OffsetAndTimestamp>>, Error>> + Send;
1337
1338    /// Get the first offset for the given partitions.
1339    ///
1340    /// This method does not change the current consumer position of the partitions.
1341    ///
1342    /// # Arguments
1343    ///
1344    /// - `partitions` - the partitions to get the earliest offsets.
1345    ///
1346    /// # Returns
1347    ///
1348    /// The earliest available offsets for the given partitions
1349    ///
1350    /// # Errors
1351    ///
1352    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
1353    /// - `Error::is_authorization_error` if not authorized to the topic(s). See the error for more
1354    ///   details
1355    /// - `Error::is_timeout_error` if the offset metadata could not be fetched before expiration of
1356    ///   the configured `default.api.timeout.ms`
1357    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#beginningOffsets")]
1358    fn beginning_offsets(
1359        &mut self,
1360        partitions: &[TopicPartition],
1361    ) -> impl Future<Output = Result<HashMap<TopicPartition, i64>, Error>> + Send;
1362
1363    /// Get the first offset for the given partitions.
1364    ///
1365    /// This method does not change the current consumer position of the partitions.
1366    ///
1367    /// # Arguments
1368    ///
1369    /// - `partitions` - the partitions to get the earliest offsets
1370    /// - `timeout` - The maximum amount of time to await retrieval of the beginning offsets
1371    ///
1372    /// # Returns
1373    ///
1374    /// The earliest available offsets for the given partitions, and it will return empty map if
1375    /// zero timeout is provided
1376    ///
1377    /// # Errors
1378    ///
1379    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
1380    /// - `Error::is_authorization_error` if not authorized to the topic(s). See the error for more
1381    ///   details
1382    /// - `Error::is_timeout_error` if the offset metadata could not be fetched before expiration of
1383    ///   the passed timeout
1384    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#beginningOffsets")]
1385    fn beginning_offsets_with_timeout(
1386        &mut self,
1387        partitions: &[TopicPartition],
1388        timeout: Duration,
1389    ) -> impl Future<Output = Result<HashMap<TopicPartition, i64>, Error>> + Send;
1390
1391    /// Get the end offsets for the given partitions. In the default `read_uncommitted`
1392    /// isolation level, the end offset is the high watermark (that is, the offset of the last
1393    /// successfully replicated message plus one). For `read_committed` consumers, the end
1394    /// offset is the last stable offset (LSO), which is the minimum of the high watermark and
1395    /// the smallest offset of any open transaction. Finally, if the partition has never been
1396    /// written to, the end offset is 0.
1397    ///
1398    /// This method does not change the current consumer position of the partitions.
1399    ///
1400    /// # Arguments
1401    ///
1402    /// - `partitions` - the partitions to get the end offsets.
1403    ///
1404    /// # Returns
1405    ///
1406    /// The end offsets for the given partitions.
1407    ///
1408    /// # Errors
1409    ///
1410    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
1411    /// - `Error::is_authorization_error` if not authorized to the topic(s). See the error for more
1412    ///   details
1413    /// - `Error::is_timeout_error` if the offset metadata could not be fetched before the amount of
1414    ///   time allocated by `default.api.timeout.ms` expires
1415    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#endOffsets")]
1416    fn end_offsets(
1417        &mut self,
1418        partitions: &[TopicPartition],
1419    ) -> impl Future<Output = Result<HashMap<TopicPartition, i64>, Error>> + Send;
1420
1421    /// Get the end offsets for the given partitions. In the default `read_uncommitted`
1422    /// isolation level, the end offset is the high watermark (that is, the offset of the last
1423    /// successfully replicated message plus one). For `read_committed` consumers, the end
1424    /// offset is the last stable offset (LSO), which is the minimum of the high watermark and
1425    /// the smallest offset of any open transaction. Finally, if the partition has never been
1426    /// written to, the end offset is 0.
1427    ///
1428    /// This method does not change the current consumer position of the partitions.
1429    ///
1430    /// # Arguments
1431    ///
1432    /// - `partitions` - the partitions to get the end offsets.
1433    /// - `timeout` - The maximum amount of time to await retrieval of the end offsets
1434    ///
1435    /// # Returns
1436    ///
1437    /// The end offsets for the given partitions, and it will return empty map if zero timeout is
1438    /// provided
1439    ///
1440    /// # Errors
1441    ///
1442    /// - `Error::is_authentication_error` if authentication fails. See the error for more details
1443    /// - `Error::is_authorization_error` if not authorized to the topic(s). See the error for more
1444    ///   details
1445    /// - `Error::is_timeout_error` if the offsets could not be fetched before expiration of the
1446    ///   passed timeout
1447    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#endOffsets")]
1448    fn end_offsets_with_timeout(
1449        &mut self,
1450        partitions: &[TopicPartition],
1451        timeout: Duration,
1452    ) -> impl Future<Output = Result<HashMap<TopicPartition, i64>, Error>> + Send;
1453
1454    // ── Pause / resume (async — Java: addAndGet on PausePartitions / ResumePartitions) ──
1455
1456    /// Suspend fetching from the requested partitions. Future calls to
1457    /// [`Self::poll`] will not return any records from these partitions until
1458    /// they have been resumed using [`Self::resume`]. Note that this method
1459    /// does not affect partition subscription. In particular, it does not cause
1460    /// a group rebalance when automatic assignment is used.
1461    ///
1462    /// The pause state is preserved across a rebalance for partitions that
1463    /// remain assigned to this consumer, but it is lost for partitions that are
1464    /// revoked. Which partitions are revoked depends on the group protocol in
1465    /// use (see [`ConsumerConfig::GROUP_PROTOCOL_CONFIG`]):
1466    ///
1467    /// - Classic group protocol: the behavior depends on the assignor
1468    ///   configured in `partition.assignment.strategy`: eager assignors (e.g.
1469    ///   `RangeAssignor`, `RoundRobinAssignor`) revoke all partitions on every
1470    ///   rebalance (pause state is not preserved); cooperative assignors (e.g.
1471    ///   `CooperativeStickyAssignor`) only revoke the partitions that are
1472    ///   reassigned to another consumer (pause state preserved for partitions
1473    ///   that remain assigned). This client does not implement the classic
1474    ///   protocol yet.
1475    /// - Consumer group protocol (KIP-848): only revokes partitions that are
1476    ///   reassigned to another consumer (pause state preserved for partitions
1477    ///   that remain assigned).
1478    ///
1479    /// # Arguments
1480    ///
1481    /// - `partitions` - The partitions which should be paused
1482    ///
1483    /// # Errors
1484    ///
1485    /// - `Error::is_local_illegal_state_error` if any of the provided partitions are not currently
1486    ///   assigned to this consumer
1487    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#pause")]
1488    fn pause(&mut self, partitions: &[TopicPartition]) -> impl Future<Output = Result<(), Error>> + Send;
1489
1490    /// Resume specified partitions which have been paused with `Self::pause`. New calls to
1491    /// `Self::poll` will return records from these partitions if there are any to be fetched.
1492    /// If the partitions were not previously paused, this method is a no-op.
1493    ///
1494    /// # Arguments
1495    ///
1496    /// - `partitions` - The partitions which should be resumed
1497    ///
1498    /// # Errors
1499    ///
1500    /// - `Error::is_local_illegal_state_error` if any of the provided partitions are not currently
1501    ///   assigned to this consumer
1502    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#resume")]
1503    fn resume(&mut self, partitions: &[TopicPartition]) -> impl Future<Output = Result<(), Error>> + Send;
1504
1505    // ── Lifecycle ──
1506
1507    /// Alert the consumer to trigger a new rebalance by rejoining the group.
1508    /// This is a nonblocking call that forces the consumer to trigger a new
1509    /// rebalance on the next [`Self::poll`] call. Note that this API does not
1510    /// itself initiate the rebalance, so you must still call [`Self::poll`]. If
1511    /// a rebalance is already in progress this call will be a no-op. If you wish
1512    /// to force an additional rebalance you must complete the current one by
1513    /// calling poll before retrying this API.
1514    ///
1515    /// # Errors
1516    ///
1517    /// - `Error::is_local_illegal_state_error` if the consumer does not use group subscription
1518    ///
1519    /// # Translation notes
1520    ///
1521    /// With `group.protocol=consumer` the call only logs a warning, as Java's.
1522    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#enforceRebalance")]
1523    fn enforce_rebalance(&mut self) -> impl Future<Output = Result<(), Error>> + Send;
1524
1525    /// Alert the consumer to trigger a new rebalance by rejoining the group.
1526    /// This is a nonblocking call that forces the consumer to trigger a new
1527    /// rebalance on the next [`Self::poll`] call. Note that this API does not
1528    /// itself initiate the rebalance, so you must still call [`Self::poll`]. If
1529    /// a rebalance is already in progress this call will be a no-op. If you wish
1530    /// to force an additional rebalance you must complete the current one by
1531    /// calling poll before retrying this API.
1532    ///
1533    /// # Arguments
1534    ///
1535    /// - `reason` - The reason why the new rebalance is needed.
1536    ///
1537    /// # Errors
1538    ///
1539    /// - `Error::is_local_illegal_state_error` if the consumer does not use group subscription
1540    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#enforceRebalance")]
1541    fn enforce_rebalance_with_reason(&mut self, reason: &str) -> impl Future<Output = Result<(), Error>> + Send;
1542
1543    /// Close the consumer with default leave group behavior, waiting for up to the default
1544    /// timeout of 30 seconds for any needed cleanup. If auto-commit is enabled, this will
1545    /// commit the current offsets if possible within the default timeout. See `Self::close` for
1546    /// details. Note that `Self::wakeup` cannot be used to interrupt close.
1547    ///
1548    /// This close operation will attempt all shutdown steps even if one of them fails. It logs
1549    /// all encountered errors, continues to execute the next steps, and finally throws the
1550    /// first error found.
1551    ///
1552    /// # Errors
1553    ///
1554    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
1555    ///   called
1556    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
1557    ///   function is called
1558    /// - `Error::is_kafka_error` for any other error during close (e.g., errors thrown from
1559    ///   rebalance callbacks or commit callbacks from previous asynchronous commits)
1560    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#close()")]
1561    fn close(&mut self) -> impl Future<Output = Result<(), Error>> + Send;
1562
1563    /// Close the consumer cleanly. [`CloseOptions`] allows to specify a timeout
1564    /// and a leave group behavior. If no timeout is specified, the default
1565    /// timeout of 30 seconds is used. If no leave group behavior is specified,
1566    /// the default leave group behavior is used.
1567    ///
1568    /// This method waits up to the timeout for the consumer to complete pending
1569    /// commits and maybe leave the group, depending on the specified leave group
1570    /// behavior. If auto-commit is enabled, this will commit the current offsets
1571    /// if possible within the timeout. If the consumer is unable to complete
1572    /// offset commits and to gracefully leave the group (if applicable) before
1573    /// the timeout expires, the consumer is force closed. Note that
1574    /// [`Self::wakeup`] cannot be used to interrupt close.
1575    ///
1576    /// # Arguments
1577    ///
1578    /// - `options` - see [`CloseOptions`]
1579    ///
1580    /// # Errors
1581    ///
1582    /// - `Error::is_local_illegal_argument_error` If the `options` timeout is negative
1583    /// - `Error::is_wakeup_error` if `Self::wakeup` is called before or while this function is
1584    ///   called
1585    /// - `Error::is_interrupt_error` if the calling thread is interrupted before or while this
1586    ///   function is called
1587    /// - `Error::is_kafka_error` for any other error during close (e.g., errors thrown from
1588    ///   rebalance callbacks or commit callbacks from previous asynchronous commits)
1589    // Java's deprecated `close(Duration)` is not translated (CLAUDE.md §3): pass
1590    // `CloseOptions::new_with_timeout(..)` instead.
1591    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#close(CloseOptions)")]
1592    fn close_with_options(&mut self, options: CloseOptions) -> impl Future<Output = Result<(), Error>> + Send;
1593
1594    /// Wakeup the consumer. This method is thread-safe and is useful in particular to abort a
1595    /// long poll. The thread which is blocking in an operation will throw `WakeupError`. If no
1596    /// thread is blocking in a method which can throw `WakeupError`, the next call to such a
1597    /// method will raise it instead.
1598    ///
1599    /// # Translation notes
1600    ///
1601    /// The consumer is not `Sync`: from another task, call
1602    /// [`ConsumerHandle::wakeup`] on [`Self::handle`]'s handle.
1603    #[doc(alias = "org.apache.kafka.clients.consumer.Consumer#wakeup")]
1604    fn wakeup(&self);
1605
1606    /// Returns a `Clone + Send + Sync` [`ConsumerHandle`] exposing
1607    /// [`Consumer::wakeup`] **and** the reentrant-safe consumer operations,
1608    /// callable from a task / thread other than the one that owns the
1609    /// consumer.
1610    ///
1611    /// No Java method counterpart — it recovers a Java capability. Java's
1612    /// `Consumer` reference is itself shareable across threads, so (1)
1613    /// `consumer.wakeup()` can be called from another thread while the
1614    /// owning thread blocks in `poll()` / `position()`, and (2) a
1615    /// `ConsumerRebalanceListener` can call back into the consumer
1616    /// (`assign`/`seek`/`pause`/`position`/...) from inside a callback by
1617    /// capturing the `consumer` variable. Rust borrows the consumer as
1618    /// `&mut self` for the duration of a blocking call and a consumer is not
1619    /// `Clone`, so neither is expressible with a
1620    /// bare reference; capture a [`ConsumerHandle`] instead. See
1621    /// [`ConsumerHandle`].
1622    ///
1623    /// The handle carries the other half of the `&mut self` exclusivity: its
1624    /// async operations are admitted only while this consumer is running a
1625    /// callback (a `ConsumerRebalanceListener` method or an
1626    /// `OffsetCommitCallback`), and otherwise return the
1627    /// `ConcurrentModificationError` Java's `acquire()` throws. `wakeup` and
1628    /// the sync reads work from any thread at any time. See the `Threads`
1629    /// section of [`ConsumerHandle`].
1630    // listener reentrancy handle (consumer-threading.md §31, §41)
1631    #[doc(alias = "rust-only")]
1632    fn handle(&self) -> ConsumerHandle;
1633}
1634
1635pub use consumer_commit_failed_error::ConsumerCommitFailedError;
1636pub use consumer_log_truncation_error::ConsumerLogTruncationError;
1637pub use consumer_no_offset_for_partition_error::ConsumerNoOffsetForPartitionError;
1638pub use consumer_offset_out_of_range_error::ConsumerOffsetOutOfRangeError;
1639pub use consumer_retriable_commit_failed_error::ConsumerRetriableCommitFailedError;