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;