confluent_kafka/admin/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//! Kafka admin client.
16//!
17//! Corresponds to the `org.apache.kafka.clients.admin` package (the `clients`
18//! segment is dropped per the project naming conventions). See
19//! `.claude/rules/admin-client.md` for the design decisions that govern this
20//! module.
21
22mod abort_transaction_result;
23mod abort_transaction_spec;
24mod admin_client;
25mod admin_client_config;
26mod alter_client_quotas_result;
27pub mod alter_config_op;
28mod alter_configs_result;
29mod alter_consumer_group_offsets_result;
30mod alter_partition_reassignments_result;
31mod alter_replica_log_dirs_result;
32mod alter_user_scram_credentials_result;
33mod classic_group_description;
34mod config;
35pub mod config_entry;
36mod consumer_group_description;
37mod create_acls_result;
38mod create_delegation_token_result;
39mod create_partitions_result;
40pub mod create_topics_result;
41pub mod delete_acls_result;
42mod delete_consumer_group_offsets_result;
43mod delete_consumer_groups_result;
44mod delete_records_result;
45mod delete_topics_result;
46mod deleted_records;
47mod describe_acls_result;
48mod describe_classic_groups_result;
49mod describe_client_quotas_result;
50mod describe_cluster_result;
51mod describe_configs_result;
52mod describe_consumer_groups_result;
53mod describe_delegation_token_result;
54mod describe_features_result;
55mod describe_log_dirs_result;
56pub mod describe_producers_result;
57pub mod describe_replica_log_dirs_result;
58mod describe_topics_result;
59mod describe_transactions_result;
60mod describe_user_scram_credentials_result;
61mod elect_leaders_result;
62mod endpoint_type;
63mod expire_delegation_token_result;
64mod feature_metadata;
65pub mod feature_update;
66mod fence_producers_result;
67mod finalized_version_range;
68mod group_listing;
69mod kafka_admin_client;
70mod list_config_resources_result;
71mod list_consumer_group_offsets_result;
72mod list_consumer_group_offsets_spec;
73mod list_groups_result;
74pub mod list_offsets_result;
75mod list_partition_reassignments_result;
76mod list_topics_result;
77mod list_transactions_result;
78mod log_dir_description;
79mod member_assignment;
80mod member_description;
81mod member_to_remove;
82pub mod mock_admin_client;
83mod new_partition_reassignment;
84mod new_partitions;
85mod new_topic;
86pub mod offset_spec;
87pub mod options;
88mod partition_reassignment;
89mod producer_state;
90mod records_to_delete;
91mod remove_members_from_consumer_group_result;
92mod renew_delegation_token_result;
93mod replica_info;
94mod scram_credential_info;
95mod scram_mechanism;
96mod supported_version_range;
97mod terminate_transaction_result;
98mod topic_description;
99mod topic_listing;
100mod transaction_description;
101mod transaction_listing;
102mod transaction_state;
103mod unregister_controller_result;
104mod update_features_result;
105mod user_scram_credential_alteration;
106mod user_scram_credential_deletion;
107mod user_scram_credential_upsertion;
108mod user_scram_credentials_description;
109
110pub(crate) mod internals;
111
112pub use abort_transaction_result::AbortTransactionResult;
113pub use abort_transaction_spec::AbortTransactionSpec;
114pub use admin_client::AdminClient;
115pub use admin_client_config::AdminClientConfig;
116pub use alter_client_quotas_result::AlterClientQuotasResult;
117pub use alter_config_op::{AlterConfigOp, OpType};
118pub use alter_configs_result::AlterConfigsResult;
119pub use alter_consumer_group_offsets_result::AlterConsumerGroupOffsetsResult;
120pub use alter_partition_reassignments_result::AlterPartitionReassignmentsResult;
121pub use alter_replica_log_dirs_result::AlterReplicaLogDirsResult;
122pub use alter_user_scram_credentials_result::AlterUserScramCredentialsResult;
123pub use classic_group_description::ClassicGroupDescription;
124pub use config::Config;
125// `ConfigSource`, `ConfigSynonym` and `ConfigType` are NOT re-exported here:
126// they are nested classes of Java's `ConfigEntry`,
127// so per CLAUDE.md §2 they are reached through the file module that plays the
128// outer-class qualifier — `admin::config_entry::ConfigSource`, mirroring Java's
129// `ConfigEntry.ConfigSource`. `ConfigEntryOptions` / `ConfigEntryOptionsBuilder`
130// are CLAUDE.md-invented, not Java nested classes, so they stay flat.
131pub use config_entry::{ConfigEntry, ConfigEntryOptions, ConfigEntryOptionsBuilder};
132pub use consumer_group_description::ConsumerGroupDescription;
133use std::collections::HashMap;
134
135pub use create_acls_result::CreateAclsResult;
136pub use create_delegation_token_result::CreateDelegationTokenResult;
137pub use create_partitions_result::CreatePartitionsResult;
138pub use create_topics_result::{CreateTopicsResult, TopicMetadataAndConfig};
139pub use delete_acls_result::{DeleteAclsResult, FilterResult, FilterResults};
140pub use delete_consumer_group_offsets_result::DeleteConsumerGroupOffsetsResult;
141pub use delete_consumer_groups_result::DeleteConsumerGroupsResult;
142pub use delete_records_result::DeleteRecordsResult;
143pub use delete_topics_result::DeleteTopicsResult;
144pub use deleted_records::DeletedRecords;
145pub use describe_acls_result::DescribeAclsResult;
146pub use describe_classic_groups_result::DescribeClassicGroupsResult;
147pub use describe_client_quotas_result::DescribeClientQuotasResult;
148pub use describe_cluster_result::DescribeClusterResult;
149pub use describe_configs_result::DescribeConfigsResult;
150pub use describe_consumer_groups_result::DescribeConsumerGroupsResult;
151pub use describe_delegation_token_result::DescribeDelegationTokenResult;
152pub use describe_features_result::DescribeFeaturesResult;
153pub use describe_log_dirs_result::DescribeLogDirsResult;
154pub use describe_producers_result::{DescribeProducersResult, PartitionProducerState};
155pub use describe_replica_log_dirs_result::{DescribeReplicaLogDirsResult, ReplicaLogDirInfo};
156pub use describe_topics_result::DescribeTopicsResult;
157pub use describe_transactions_result::DescribeTransactionsResult;
158pub use describe_user_scram_credentials_result::DescribeUserScramCredentialsResult;
159pub use elect_leaders_result::ElectLeadersResult;
160pub use endpoint_type::EndpointType;
161pub use expire_delegation_token_result::ExpireDelegationTokenResult;
162pub use feature_metadata::FeatureMetadata;
163pub use feature_update::{FeatureUpdate, UpgradeType};
164pub use fence_producers_result::FenceProducersResult;
165pub use finalized_version_range::FinalizedVersionRange;
166pub use group_listing::GroupListing;
167pub use kafka_admin_client::KafkaAdminClient;
168pub use list_config_resources_result::ListConfigResourcesResult;
169pub(crate) use list_consumer_group_offsets_result::GroupOffsets;
170pub use list_consumer_group_offsets_result::ListConsumerGroupOffsetsResult;
171pub use list_consumer_group_offsets_spec::ListConsumerGroupOffsetsSpec;
172pub use list_groups_result::ListGroupsResult;
173pub use list_offsets_result::{ListOffsetsResult, ListOffsetsResultInfo};
174pub use list_partition_reassignments_result::ListPartitionReassignmentsResult;
175pub use list_topics_result::ListTopicsResult;
176pub use list_transactions_result::ListTransactionsResult;
177pub use log_dir_description::LogDirDescription;
178pub use member_assignment::MemberAssignment;
179pub use member_description::MemberDescription;
180pub use member_to_remove::MemberToRemove;
181pub use mock_admin_client::MockAdminClient;
182pub use new_partition_reassignment::NewPartitionReassignment;
183pub use new_partitions::NewPartitions;
184pub use new_topic::NewTopic;
185pub use offset_spec::OffsetSpec;
186pub use options::{
187 AbortTransactionOptions, AlterClientQuotasOptions, AlterConfigsOptions, AlterConsumerGroupOffsetsOptions,
188 AlterPartitionReassignmentsOptions, AlterReplicaLogDirsOptions, AlterUserScramCredentialsOptions,
189 CreateAclsOptions, CreateDelegationTokenOptions, CreatePartitionsOptions, CreateTopicsOptions, DeleteAclsOptions,
190 DeleteConsumerGroupOffsetsOptions, DeleteConsumerGroupsOptions, DeleteRecordsOptions, DeleteTopicsOptions,
191 DescribeAclsOptions, DescribeClassicGroupsOptions, DescribeClientQuotasOptions, DescribeClusterOptions,
192 DescribeConfigsOptions, DescribeConsumerGroupsOptions, DescribeDelegationTokenOptions, DescribeFeaturesOptions,
193 DescribeLogDirsOptions, DescribeProducersOptions, DescribeReplicaLogDirsOptions, DescribeTopicsOptions,
194 DescribeTransactionsOptions, DescribeUserScramCredentialsOptions, ElectLeadersOptions,
195 ExpireDelegationTokenOptions, FenceProducersOptions, ListConfigResourcesOptions, ListConsumerGroupOffsetsOptions,
196 ListGroupsOptions, ListOffsetsOptions, ListPartitionReassignmentsOptions, ListTopicsOptions,
197 ListTransactionsOptions, RemoveMembersFromConsumerGroupOptions, RenewDelegationTokenOptions,
198 TerminateTransactionOptions, UnregisterControllerOptions, UpdateFeaturesOptions,
199};
200pub use partition_reassignment::PartitionReassignment;
201pub use producer_state::ProducerState;
202pub use records_to_delete::RecordsToDelete;
203pub use remove_members_from_consumer_group_result::RemoveMembersFromConsumerGroupResult;
204pub use renew_delegation_token_result::RenewDelegationTokenResult;
205pub use replica_info::ReplicaInfo;
206pub use scram_credential_info::ScramCredentialInfo;
207pub use scram_mechanism::ScramMechanism;
208pub use supported_version_range::SupportedVersionRange;
209pub use terminate_transaction_result::TerminateTransactionResult;
210pub use topic_description::TopicDescription;
211pub use topic_listing::TopicListing;
212pub use transaction_description::TransactionDescription;
213pub use transaction_listing::TransactionListing;
214pub use transaction_state::TransactionState;
215pub use unregister_controller_result::UnregisterControllerResult;
216pub use update_features_result::UpdateFeaturesResult;
217pub use user_scram_credential_alteration::UserScramCredentialAlteration;
218pub use user_scram_credential_deletion::UserScramCredentialDeletion;
219pub use user_scram_credential_upsertion::UserScramCredentialUpsertion;
220pub use user_scram_credentials_description::UserScramCredentialsDescription;
221
222use std::time::Duration;
223
224use async_trait::async_trait;
225
226use crate::common::acl::{AclBinding, AclBindingFilter};
227use crate::common::config::{ConfigResource, config_resource};
228use crate::common::quota::{ClientQuotaAlteration, ClientQuotaFilter};
229use crate::common::{ElectionType, Error, TopicCollection, TopicPartition, TopicPartitionReplica};
230use crate::consumer::OffsetAndMetadata;
231
232use std::collections::HashSet;
233
234/// The administrative client for Kafka, which supports managing and inspecting topics, brokers,
235/// configurations and ACLs.
236///
237/// Instances returned from `AdminClient::create` are guaranteed to be thread safe. However, the
238/// `KafkaFuture`s returned from request methods are completed by a single task so it is important
239/// that any code which executes on that task when they complete (using `KafkaFuture::then_apply`,
240/// for example) doesn't block for too long. If necessary, processing of results should be passed
241/// to another task.
242///
243/// The operations exposed by Admin follow a consistent pattern:
244///
245/// - Admin instances should be created using `AdminClient::create`.
246/// - Each operation typically has two overloaded methods, one which uses a default set of options
247/// and an overloaded method where the last parameter is an explicit options object.
248/// - The operation method's first parameter is a collection of items to perform the operation on.
249/// Batching multiple requests into a single call is more efficient and should be preferred over
250/// multiple calls to the same method.
251/// - The operation methods execute asynchronously.
252/// - Each `xxx` operation method returns an `XxxResult` class with methods which expose
253/// `KafkaFuture` for accessing the result(s) of the operation.
254/// - Typically an `all()` method is provided for getting the overall success/failure of the batch
255/// and a `values()` method provided access to each item in a request batch. Other methods may
256/// also be provided.
257/// - For synchronous behavior, await `KafkaFuture::get`.
258///
259/// Here is a simple example of using an Admin client instance to create a new topic:
260///
261/// ```no_run
262/// use std::collections::{BTreeMap, HashMap};
263///
264/// use confluent_kafka::admin::{AdminClient, AdminClientConfig, NewTopic};
265///
266/// # async fn example() -> Result<(), confluent_kafka::common::Error> {
267/// let props = HashMap::from([(
268/// AdminClientConfig::BOOTSTRAP_SERVERS_CONFIG.to_string(),
269/// "localhost:9092".to_string(),
270/// )]);
271/// let admin = AdminClient::create(AdminClientConfig::new(&props)?)?;
272/// let topic_name = "my-topic";
273/// // Create a compacted topic
274/// let result = admin.create_topics(&[NewTopic::with_num_partitions_replication_factor(
275/// topic_name,
276/// Some(12),
277/// Some(3),
278/// )
279/// .set_configs(Some(BTreeMap::from([("cleanup.policy".to_string(), "compact".to_string())])))]);
280///
281/// // Call values() to get the result for a specific topic
282/// let future = result.values()[topic_name].clone();
283///
284/// // Await get() until the topic creation is complete or has failed
285/// future.get().await?;
286/// admin.close().await;
287/// # Ok(())
288/// # }
289/// ```
290///
291/// # Bootstrap and balancing
292///
293/// The `bootstrap.servers` config passed to `AdminClient::create` is only used for discovering
294/// the brokers in the cluster, which the client will then connect to as needed. As such, it is
295/// sufficient to include only two or three broker addresses to cope with the possibility of
296/// brokers being unavailable.
297///
298/// Different operations necessitate requests being sent to different nodes in the cluster. For
299/// example `Self::create_topics` communicates with the controller, but
300/// `Self::describe_topics_with_topic_names` can talk to any broker. When the recipient does not
301/// matter the instance will try to use the broker with the fewest outstanding requests.
302///
303/// The client will transparently retry certain errors which are usually transient. For example
304/// if the request for `create_topics()` get sent to a node which was not the controller the
305/// metadata would be refreshed and the request re-sent to the controller.
306///
307/// # Broker Compatibility
308///
309/// The minimum broker version required is 0.10.0.0. Methods with stricter requirements will
310/// specify the minimum broker version required.
311///
312/// # Translation notes
313///
314/// The request methods are plain `fn`s that return at once; only `close` and
315/// `close_with_timeout` are `async`, as Java's `close` joins the admin thread.
316#[async_trait]
317#[doc(alias = "org.apache.kafka.clients.admin.Admin")]
318pub trait Admin: Send + Sync {
319 /// Create a batch of new topics with the default options.
320 ///
321 /// This is a convenience method for `Self::create_topics_with_options` with default options.
322 /// See the overload for more details.
323 ///
324 /// This operation is supported by brokers with version 0.10.1.0 or higher.
325 ///
326 /// # Arguments
327 ///
328 /// - `new_topics` - The new topics to create.
329 ///
330 /// # Returns
331 ///
332 /// The CreateTopicsResult.
333 #[doc(alias = "org.apache.kafka.clients.admin.Admin#createTopics")]
334 fn create_topics(&self, new_topics: &[NewTopic]) -> CreateTopicsResult {
335 self.create_topics_with_options(new_topics, CreateTopicsOptions::default())
336 }
337
338 /// Create a batch of new topics.
339 ///
340 /// This operation is not transactional so it may succeed for some topics while fail for others.
341 ///
342 /// It may take several seconds after `CreateTopicsResult` returns success for all the brokers
343 /// to become aware that the topics have been created. During this time, `Self::list_topics` and
344 /// `Self::describe_topics_with_topic_names` may not return information about the new topics.
345 ///
346 /// This operation is supported by brokers with version 0.10.1.0 or higher. The validateOnly
347 /// option is supported from version 0.10.2.0.
348 ///
349 /// # Arguments
350 ///
351 /// - `new_topics` - The new topics to create.
352 /// - `options` - The options to use when creating the new topics.
353 ///
354 /// # Returns
355 ///
356 /// The CreateTopicsResult.
357 #[doc(alias = "org.apache.kafka.clients.admin.Admin#createTopics")]
358 fn create_topics_with_options(&self, new_topics: &[NewTopic], options: CreateTopicsOptions) -> CreateTopicsResult;
359
360 /// This is a convenience method for `Self::delete_topics_with_topic_collection_options` with
361 /// default options. See the overload for more details.
362 ///
363 /// This operation is supported by brokers with version 0.10.1.0 or higher.
364 ///
365 /// # Arguments
366 ///
367 /// - `topics` - The topic names to delete.
368 ///
369 /// # Returns
370 ///
371 /// The DeleteTopicsResult.
372 ///
373 /// # Translation notes
374 ///
375 /// Java names the parameter of every `deleteTopics` overload `topics`, so each form is
376 /// named after its type.
377 #[doc(alias = "org.apache.kafka.clients.admin.Admin#deleteTopics(Collection)")]
378 fn delete_topics_with_string_slice(&self, topics: &[String]) -> DeleteTopicsResult {
379 self.delete_topics_with_topic_collection_options(
380 TopicCollection::of_topic_names(topics.to_vec()),
381 DeleteTopicsOptions::default(),
382 )
383 }
384
385 /// This is a convenience method for `Self::delete_topics_with_topic_collection_options` with
386 /// default options. See the overload for more details.
387 ///
388 /// This operation is supported by brokers with version 0.10.1.0 or higher.
389 ///
390 /// # Arguments
391 ///
392 /// - `topics` - The topic names to delete.
393 /// - `options` - The options to use when deleting the topics.
394 ///
395 /// # Returns
396 ///
397 /// The DeleteTopicsResult.
398 #[doc(alias = "org.apache.kafka.clients.admin.Admin#deleteTopics(Collection,DeleteTopicsOptions)")]
399 fn delete_topics_with_string_slice_options(
400 &self,
401 topics: &[String],
402 options: DeleteTopicsOptions,
403 ) -> DeleteTopicsResult {
404 self.delete_topics_with_topic_collection_options(TopicCollection::of_topic_names(topics.to_vec()), options)
405 }
406
407 /// This is a convenience method for `Self::delete_topics_with_topic_collection_options` with
408 /// default options. See the overload for more details.
409 ///
410 /// When using topic IDs, this operation is supported by brokers with inter-broker protocol 2.8
411 /// or higher. When using topic names, this operation is supported by brokers with version
412 /// 0.10.1.0 or higher.
413 ///
414 /// # Arguments
415 ///
416 /// - `topics` - The topics to delete.
417 ///
418 /// # Returns
419 ///
420 /// The DeleteTopicsResult.
421 #[doc(alias = "org.apache.kafka.clients.admin.Admin#deleteTopics")]
422 fn delete_topics_with_topic_collection(&self, topics: TopicCollection) -> DeleteTopicsResult {
423 self.delete_topics_with_topic_collection_options(topics, DeleteTopicsOptions::default())
424 }
425
426 /// Delete a batch of topics.
427 ///
428 /// This operation is not transactional so it may succeed for some topics while fail for others.
429 ///
430 /// It may take several seconds after the `DeleteTopicsResult` returns success for all the
431 /// brokers to become aware that the topics are gone. During this time, `Self::list_topics` and
432 /// `Self::describe_topics_with_topic_names` may continue to return information about the
433 /// deleted topics.
434 ///
435 /// If delete.topic.enable is set to false on the brokers, an error will be returned to the
436 /// client indicating that topic deletion is disabled.
437 ///
438 /// When using topic IDs, this operation is supported by brokers with inter-broker protocol 2.8
439 /// or higher. When using topic names, this operation is supported by brokers with version
440 /// 0.10.1.0 or higher.
441 ///
442 /// # Arguments
443 ///
444 /// - `topics` - The topics to delete.
445 /// - `options` - The options to use when deleting the topics.
446 ///
447 /// # Returns
448 ///
449 /// The DeleteTopicsResult.
450 #[doc(alias = "org.apache.kafka.clients.admin.Admin#deleteTopics")]
451 fn delete_topics_with_topic_collection_options(
452 &self,
453 topics: TopicCollection,
454 options: DeleteTopicsOptions,
455 ) -> DeleteTopicsResult;
456
457 /// List the topics available in the cluster with the default options.
458 ///
459 /// This is a convenience method for `Self::list_topics_with_options` with default options. See
460 /// the overload for more details.
461 ///
462 /// # Returns
463 ///
464 /// The ListTopicsResult.
465 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listTopics")]
466 fn list_topics(&self) -> ListTopicsResult {
467 self.list_topics_with_options(ListTopicsOptions::default())
468 }
469
470 /// List the topics available in the cluster.
471 ///
472 /// # Arguments
473 ///
474 /// - `options` - The options to use when listing the topics.
475 ///
476 /// # Returns
477 ///
478 /// The ListTopicsResult.
479 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listTopics")]
480 fn list_topics_with_options(&self, options: ListTopicsOptions) -> ListTopicsResult;
481
482 /// Describe some topics in the cluster, with the default options.
483 ///
484 /// This is a convenience method for `Self::describe_topics_with_topic_names_options` with
485 /// default options. See the overload for more details.
486 ///
487 /// # Arguments
488 ///
489 /// - `topic_names` - The names of the topics to describe.
490 ///
491 /// # Returns
492 ///
493 /// The DescribeTopicsResult.
494 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeTopics")]
495 fn describe_topics_with_topic_names(&self, topic_names: &[String]) -> DescribeTopicsResult {
496 self.describe_topics_with_topic_names_options(topic_names, DescribeTopicsOptions::default())
497 }
498
499 /// Describe some topics in the cluster.
500 ///
501 /// # Arguments
502 ///
503 /// - `topic_names` - The names of the topics to describe.
504 /// - `options` - The options to use when describing the topic.
505 ///
506 /// # Returns
507 ///
508 /// The DescribeTopicsResult.
509 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeTopics")]
510 fn describe_topics_with_topic_names_options(
511 &self,
512 topic_names: &[String],
513 options: DescribeTopicsOptions,
514 ) -> DescribeTopicsResult {
515 self.describe_topics_with_topics_options(TopicCollection::of_topic_names(topic_names.to_vec()), options)
516 }
517
518 /// This is a convenience method for `Self::describe_topics_with_topics_options` with default
519 /// options. See the overload for more details.
520 ///
521 /// When using topic IDs, this operation is supported by brokers with version 3.1.0 or higher.
522 ///
523 /// # Arguments
524 ///
525 /// - `topics` - The topics to describe.
526 ///
527 /// # Returns
528 ///
529 /// The DescribeTopicsResult.
530 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeTopics")]
531 fn describe_topics_with_topics(&self, topics: TopicCollection) -> DescribeTopicsResult {
532 self.describe_topics_with_topics_options(topics, DescribeTopicsOptions::default())
533 }
534
535 /// Describe some topics in the cluster. When using topic IDs, this operation is supported by
536 /// brokers with version 3.1.0 or higher.
537 ///
538 /// # Arguments
539 ///
540 /// - `topics` - The topics to describe.
541 /// - `options` - The options to use when describing the topics.
542 ///
543 /// # Returns
544 ///
545 /// The DescribeTopicsResult.
546 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeTopics")]
547 fn describe_topics_with_topics_options(
548 &self,
549 topics: TopicCollection,
550 options: DescribeTopicsOptions,
551 ) -> DescribeTopicsResult;
552
553 /// Increase the number of partitions of the topics given as the keys of `new_partitions`
554 /// according to the corresponding values. **If partitions are increased for a topic that has a
555 /// key, the partition logic or ordering of the messages will be affected.**
556 ///
557 /// This is a convenience method for `Self::create_partitions_with_options` with default
558 /// options. See the overload for more details.
559 ///
560 /// # Arguments
561 ///
562 /// - `new_partitions` - The topics which should have new partitions created, and corresponding
563 /// parameters for the created partitions.
564 ///
565 /// # Returns
566 ///
567 /// The CreatePartitionsResult.
568 #[doc(alias = "org.apache.kafka.clients.admin.Admin#createPartitions")]
569 fn create_partitions(&self, new_partitions: &HashMap<String, NewPartitions>) -> CreatePartitionsResult {
570 self.create_partitions_with_options(new_partitions, CreatePartitionsOptions::default())
571 }
572
573 /// Increase the number of partitions of the topics given as the keys of `new_partitions`
574 /// according to the corresponding values. **If partitions are increased for a topic that has a
575 /// key, the partition logic or ordering of the messages will be affected.**
576 ///
577 /// This operation is not transactional so it may succeed for some topics while fail for others.
578 ///
579 /// It may take several seconds after this method returns success for all the brokers to become
580 /// aware that the partitions have been created. During this time,
581 /// `Self::describe_topics_with_topic_names` may not return information about the new
582 /// partitions.
583 ///
584 /// This operation is supported by brokers with version 1.0.0 or higher.
585 ///
586 /// The following errors can be anticipated when calling `get()` on the futures obtained from
587 /// the values() method of the returned `CreatePartitionsResult`
588 ///
589 /// - `Error::is_authorization_error` if the authenticated user is not authorized to alter the
590 /// topic
591 /// - `Error::is_timeout_error` if the request was not completed in within the given
592 /// `CreatePartitionsOptions::timeout_ms`.
593 /// - `Error::is_reassignment_in_progress_error` if a partition reassignment is currently in
594 /// progress
595 /// - `Error::is_broker_not_available_error` if the requested `NewPartitions::assignments`
596 /// contain a broker that is currently unavailable.
597 /// - `Error::is_invalid_replication_factor_error` if no `NewPartitions::assignments` are given
598 /// and it is impossible for the broker to assign replicas with the topics replication factor.
599 /// - Subclasses of `Error::is_kafka_error` if the request is invalid in some way.
600 /// - `Error::is_invalid_partitions_error` if the requested partition count is less than or
601 /// equal to the current partition count.
602 ///
603 /// # Arguments
604 ///
605 /// - `new_partitions` - The topics which should have new partitions created, and corresponding
606 /// parameters for the created partitions.
607 /// - `options` - The options to use when creating the new partitions.
608 ///
609 /// # Returns
610 ///
611 /// The CreatePartitionsResult.
612 #[doc(alias = "org.apache.kafka.clients.admin.Admin#createPartitions")]
613 fn create_partitions_with_options(
614 &self,
615 new_partitions: &HashMap<String, NewPartitions>,
616 options: CreatePartitionsOptions,
617 ) -> CreatePartitionsResult;
618
619 /// Delete records whose offset is smaller than the given offset of the corresponding partition.
620 ///
621 /// This is a convenience method for `Self::delete_records_with_options` with default options.
622 /// See the overload for more details.
623 ///
624 /// This operation is supported by brokers with version 0.11.0.0 or higher.
625 ///
626 /// # Arguments
627 ///
628 /// - `records_to_delete` - The topic partitions and related offsets from which records deletion
629 /// starts.
630 ///
631 /// # Returns
632 ///
633 /// The DeleteRecordsResult.
634 #[doc(alias = "org.apache.kafka.clients.admin.Admin#deleteRecords")]
635 fn delete_records(&self, records_to_delete: &HashMap<TopicPartition, RecordsToDelete>) -> DeleteRecordsResult {
636 self.delete_records_with_options(records_to_delete, DeleteRecordsOptions::default())
637 }
638
639 /// Delete records whose offset is smaller than the given offset of the corresponding partition.
640 ///
641 /// This operation is supported by brokers with version 0.11.0.0 or higher.
642 ///
643 /// # Arguments
644 ///
645 /// - `records_to_delete` - The topic partitions and related offsets from which records deletion
646 /// starts.
647 /// - `options` - The options to use when deleting records.
648 ///
649 /// # Returns
650 ///
651 /// The DeleteRecordsResult.
652 #[doc(alias = "org.apache.kafka.clients.admin.Admin#deleteRecords")]
653 fn delete_records_with_options(
654 &self,
655 records_to_delete: &HashMap<TopicPartition, RecordsToDelete>,
656 options: DeleteRecordsOptions,
657 ) -> DeleteRecordsResult;
658
659 /// Unregister a controller. This is a convenience method for
660 /// `Self::unregister_controller_with_options`
661 ///
662 /// # Arguments
663 ///
664 /// - `controller_id` - the controller id to unregister.
665 ///
666 /// # Returns
667 ///
668 /// the `UnregisterControllerResult` containing the result
669 #[doc(alias = "org.apache.kafka.clients.admin.Admin#unregisterController")]
670 fn unregister_controller(&self, controller_id: i32) -> UnregisterControllerResult {
671 self.unregister_controller_with_options(controller_id, UnregisterControllerOptions::default())
672 }
673
674 /// Unregister a controller. The following errors can be anticipated when calling `get()` on the
675 /// future from the returned `UnregisterControllerResult`:
676 ///
677 /// - `Error::is_timeout_error` If the request timed out before the unregister operation could
678 /// finish.
679 /// - `Error::is_unsupported_version_error` If the software is too old to support the
680 /// unregistration API.
681 /// - `Error::is_controller_id_not_registered_error` If the requested controller id is not
682 /// currently registered.
683 /// - `Error::is_not_controller_error` If the request does not arrive at the active controller.
684 /// - `Error::is_invalid_request_error` If the request tries to unregister the current active
685 /// controller id.
686 ///
687 /// # Arguments
688 ///
689 /// - `controller_id` - the controller id to unregister.
690 /// - `options` - the options to use.
691 ///
692 /// # Returns
693 ///
694 /// the `UnregisterControllerResult` containing the result
695 #[doc(alias = "org.apache.kafka.clients.admin.Admin#unregisterController")]
696 fn unregister_controller_with_options(
697 &self,
698 controller_id: i32,
699 options: UnregisterControllerOptions,
700 ) -> UnregisterControllerResult;
701
702 /// Describe producer state on a set of topic partitions. See
703 /// `Self::describe_producers_with_options` for more details.
704 ///
705 /// # Arguments
706 ///
707 /// - `partitions` - The set of partitions to query
708 ///
709 /// # Returns
710 ///
711 /// The result
712 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeProducers")]
713 fn describe_producers(&self, partitions: &[TopicPartition]) -> DescribeProducersResult {
714 self.describe_producers_with_options(partitions, DescribeProducersOptions::default())
715 }
716
717 /// Describe active producer state on a set of topic partitions. Unless a specific broker is
718 /// requested through `DescribeProducersOptions::broker_id`, this will query the partition
719 /// leader to find the producer state.
720 ///
721 /// # Arguments
722 ///
723 /// - `partitions` - The set of partitions to query
724 /// - `options` - Options to control the method behavior
725 ///
726 /// # Returns
727 ///
728 /// The result
729 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeProducers")]
730 fn describe_producers_with_options(
731 &self,
732 partitions: &[TopicPartition],
733 options: DescribeProducersOptions,
734 ) -> DescribeProducersResult;
735
736 /// Forcefully abort a transaction which is open on a topic partition. See
737 /// `Self::abort_transaction_with_options` for more details.
738 ///
739 /// # Arguments
740 ///
741 /// - `spec` - The transaction specification including topic partition and producer details
742 ///
743 /// # Returns
744 ///
745 /// The result
746 #[doc(alias = "org.apache.kafka.clients.admin.Admin#abortTransaction")]
747 fn abort_transaction(&self, spec: AbortTransactionSpec) -> AbortTransactionResult {
748 self.abort_transaction_with_options(spec, AbortTransactionOptions::default())
749 }
750
751 /// Forcefully abort a transaction which is open on a topic partition. This will send a
752 /// `WriteTxnMarkers` request to the partition leader in order to abort the transaction. This
753 /// requires administrative privileges.
754 ///
755 /// # Arguments
756 ///
757 /// - `spec` - The transaction specification including topic partition and producer details
758 /// - `options` - Options to control the method behavior (including filters)
759 ///
760 /// # Returns
761 ///
762 /// The result
763 #[doc(alias = "org.apache.kafka.clients.admin.Admin#abortTransaction")]
764 fn abort_transaction_with_options(
765 &self,
766 spec: AbortTransactionSpec,
767 options: AbortTransactionOptions,
768 ) -> AbortTransactionResult;
769
770 /// Describe the state of a set of transactional IDs. See
771 /// `Self::describe_transactions_with_options` for more details.
772 ///
773 /// # Arguments
774 ///
775 /// - `transactional_ids` - The set of transactional IDs to query
776 ///
777 /// # Returns
778 ///
779 /// The result
780 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeTransactions")]
781 fn describe_transactions(&self, transactional_ids: &[String]) -> DescribeTransactionsResult {
782 self.describe_transactions_with_options(transactional_ids, DescribeTransactionsOptions::default())
783 }
784
785 /// Describe the state of a set of transactional IDs from the respective transaction
786 /// coordinators, which are dynamically discovered.
787 ///
788 /// # Arguments
789 ///
790 /// - `transactional_ids` - The set of transactional IDs to query
791 /// - `options` - Options to control the method behavior
792 ///
793 /// # Returns
794 ///
795 /// The result
796 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeTransactions")]
797 fn describe_transactions_with_options(
798 &self,
799 transactional_ids: &[String],
800 options: DescribeTransactionsOptions,
801 ) -> DescribeTransactionsResult;
802
803 /// Fence out all active producers that use any of the provided transactional IDs, with the
804 /// default options.
805 ///
806 /// This is a convenience method for `Self::fence_producers_with_options` with default options.
807 /// See the overload for more details.
808 ///
809 /// # Arguments
810 ///
811 /// - `transactional_ids` - The IDs of the producers to fence.
812 ///
813 /// # Returns
814 ///
815 /// The FenceProducersResult.
816 #[doc(alias = "org.apache.kafka.clients.admin.Admin#fenceProducers")]
817 fn fence_producers(&self, transactional_ids: &[String]) -> FenceProducersResult {
818 self.fence_producers_with_options(transactional_ids, FenceProducersOptions::default())
819 }
820
821 /// Fence out all active producers that use any of the provided transactional IDs.
822 ///
823 /// # Arguments
824 ///
825 /// - `transactional_ids` - The IDs of the producers to fence.
826 /// - `options` - The options to use when fencing the producers.
827 ///
828 /// # Returns
829 ///
830 /// The FenceProducersResult.
831 #[doc(alias = "org.apache.kafka.clients.admin.Admin#fenceProducers")]
832 fn fence_producers_with_options(
833 &self,
834 transactional_ids: &[String],
835 options: FenceProducersOptions,
836 ) -> FenceProducersResult;
837
838 /// List active transactions in the cluster. See `Self::list_transactions_with_options` for more
839 /// details.
840 ///
841 /// # Returns
842 ///
843 /// The result
844 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listTransactions")]
845 fn list_transactions(&self) -> ListTransactionsResult {
846 self.list_transactions_with_options(ListTransactionsOptions::default())
847 }
848
849 /// List active transactions in the cluster. This will query all potential transaction
850 /// coordinators in the cluster and collect the state of all transactions. Users should
851 /// typically attempt to reduce the size of the result set using
852 /// `ListTransactionsOptions::filter_producer_ids` or `ListTransactionsOptions::filter_states`
853 /// or `ListTransactionsOptions::filter_on_duration`.
854 ///
855 /// # Arguments
856 ///
857 /// - `options` - Options to control the method behavior (including filters)
858 ///
859 /// # Returns
860 ///
861 /// The result
862 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listTransactions")]
863 fn list_transactions_with_options(&self, options: ListTransactionsOptions) -> ListTransactionsResult;
864
865 /// Force terminate a transaction for the given transactional ID with the default options.
866 ///
867 /// This is a convenience method for `Self::force_terminate_transaction_with_options` with
868 /// default options.
869 ///
870 /// # Arguments
871 ///
872 /// - `transactional_id` - The ID of the transaction to terminate.
873 ///
874 /// # Returns
875 ///
876 /// The TerminateTransactionResult.
877 #[doc(alias = "org.apache.kafka.clients.admin.Admin#forceTerminateTransaction")]
878 fn force_terminate_transaction(&self, transactional_id: &str) -> TerminateTransactionResult {
879 self.force_terminate_transaction_with_options(transactional_id, TerminateTransactionOptions::default())
880 }
881
882 /// Force terminate a transaction for the given transactional ID. This operation aborts any
883 /// ongoing transaction associated with the transactional ID. It's similar to fenceProducers but
884 /// only targets a single transactional ID to handle long-running transactions when 2PC is
885 /// enabled.
886 ///
887 /// # Arguments
888 ///
889 /// - `transactional_id` - The ID of the transaction to terminate.
890 /// - `options` - The options to use when terminating the transaction.
891 ///
892 /// # Returns
893 ///
894 /// The TerminateTransactionResult.
895 #[doc(alias = "org.apache.kafka.clients.admin.Admin#forceTerminateTransaction")]
896 fn force_terminate_transaction_with_options(
897 &self,
898 transactional_id: &str,
899 options: TerminateTransactionOptions,
900 ) -> TerminateTransactionResult;
901
902 /// Get information about the nodes in the cluster, using the default options.
903 ///
904 /// This is a convenience method for `Self::describe_cluster_with_options` with default options.
905 /// See the overload for more details.
906 ///
907 /// # Returns
908 ///
909 /// The DescribeClusterResult.
910 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeCluster")]
911 fn describe_cluster(&self) -> DescribeClusterResult {
912 self.describe_cluster_with_options(DescribeClusterOptions::default())
913 }
914
915 /// Get information about the nodes in the cluster.
916 ///
917 /// To obtain broker cluster information, you must configure
918 /// `AdminClientConfig::BOOTSTRAP_SERVERS_CONFIG`. To obtain controller cluster information, you
919 /// must configure `AdminClientConfig::BOOTSTRAP_CONTROLLERS_CONFIG`.
920 ///
921 /// # Arguments
922 ///
923 /// - `options` - The options to use when getting information about the cluster.
924 ///
925 /// # Returns
926 ///
927 /// The DescribeClusterResult.
928 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeCluster")]
929 fn describe_cluster_with_options(&self, options: DescribeClusterOptions) -> DescribeClusterResult;
930
931 /// Get the configuration for the specified resources with the default options.
932 ///
933 /// This is a convenience method for `Self::describe_configs_with_options` with default options.
934 /// See the overload for more details.
935 ///
936 /// This operation is supported by brokers with version 0.11.0.0 or higher.
937 ///
938 /// # Arguments
939 ///
940 /// - `config_resources` - The resources (topic and broker resource types are currently
941 /// supported)
942 ///
943 /// # Returns
944 ///
945 /// The DescribeConfigsResult
946 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeConfigs")]
947 fn describe_configs(&self, config_resources: &[ConfigResource]) -> DescribeConfigsResult {
948 self.describe_configs_with_options(config_resources, DescribeConfigsOptions::default())
949 }
950
951 /// Get the configuration for the specified resources.
952 ///
953 /// The returned configuration includes default values and the `ConfigEntry::is_default` method
954 /// can be used to distinguish them from user supplied values.
955 ///
956 /// The value of config entries where `ConfigEntry::is_sensitive` is true is always `None` so
957 /// that sensitive information is not disclosed.
958 ///
959 /// Config entries where `ConfigEntry::is_read_only` is true cannot be updated.
960 ///
961 /// The different behavior of nonexistent resource:
962 ///
963 /// - `config_resource::Type::Broker`: fails with `Error::is_timeout_error`
964 /// - `config_resource::Type::Topic`: fails with `Error::is_unknown_topic_or_partition_error`
965 /// - `config_resource::Type::Group`: just return default configs even if the target group is
966 /// nonexistent
967 /// - `config_resource::Type::BrokerLogger`: fails with `Error::is_timeout_error`
968 /// - `config_resource::Type::ClientMetrics`: will return empty configs
969 ///
970 /// Note that you cannot describe broker configs or broker logger using
971 /// `AdminClientConfig::BOOTSTRAP_CONTROLLERS_CONFIG`, and you cannot describe controller
972 /// configs or controller logger using `AdminClientConfig::BOOTSTRAP_SERVERS_CONFIG`.
973 ///
974 /// This operation is supported by brokers with version 0.11.0.0 or higher.
975 ///
976 /// # Arguments
977 ///
978 /// - `config_resources` - The resources (topic and broker resource types are currently
979 /// supported)
980 /// - `options` - The options to use when describing configs
981 ///
982 /// # Returns
983 ///
984 /// The DescribeConfigsResult
985 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeConfigs")]
986 fn describe_configs_with_options(
987 &self,
988 config_resources: &[ConfigResource],
989 options: DescribeConfigsOptions,
990 ) -> DescribeConfigsResult;
991
992 /// Incrementally updates the configuration for the specified resources with default options.
993 ///
994 /// This is a convenience method for `Self::incremental_alter_configs_with_options` with default
995 /// options. See the overload for more details.
996 ///
997 /// This operation is supported by brokers with version 2.3.0 or higher.
998 ///
999 /// # Arguments
1000 ///
1001 /// - `configs` - The resources with their configs
1002 ///
1003 /// # Returns
1004 ///
1005 /// The AlterConfigsResult
1006 #[doc(alias = "org.apache.kafka.clients.admin.Admin#incrementalAlterConfigs")]
1007 fn incremental_alter_configs(&self, configs: &HashMap<ConfigResource, Vec<AlterConfigOp>>) -> AlterConfigsResult {
1008 self.incremental_alter_configs_with_options(configs, AlterConfigsOptions::default())
1009 }
1010
1011 /// Incrementally update the configuration for the specified resources.
1012 ///
1013 /// Updates are not transactional so they may succeed for some resources while fail for others.
1014 /// The configs for a particular resource are updated atomically.
1015 ///
1016 /// The following errors can be anticipated when calling `get()` on the futures obtained from
1017 /// the returned `AlterConfigsResult`:
1018 ///
1019 /// - `Error::is_cluster_authorization_error` if the authenticated user didn't have alter access
1020 /// to the cluster.
1021 /// - `Error::is_topic_authorization_error` if the authenticated user didn't have alter access
1022 /// to the Topic.
1023 /// - `Error::is_unknown_topic_or_partition_error` if the Topic doesn't exist.
1024 /// - `Error::is_invalid_request_error` if the request details are invalid. e.g., a
1025 /// configuration key was specified more than once for a resource
1026 ///
1027 /// This operation is supported by brokers with version 2.3.0 or higher.
1028 ///
1029 /// # Arguments
1030 ///
1031 /// - `configs` - The resources with their configs
1032 /// - `options` - The options to use when altering configs
1033 ///
1034 /// # Returns
1035 ///
1036 /// The AlterConfigsResult
1037 #[doc(alias = "org.apache.kafka.clients.admin.Admin#incrementalAlterConfigs")]
1038 fn incremental_alter_configs_with_options(
1039 &self,
1040 configs: &HashMap<ConfigResource, Vec<AlterConfigOp>>,
1041 options: AlterConfigsOptions,
1042 ) -> AlterConfigsResult;
1043
1044 /// List all configuration resources available in the cluster with the default options.
1045 ///
1046 /// This is a convenience method for `Self::list_config_resources_with_options` with default
1047 /// options. See the overload for more details.
1048 ///
1049 /// # Returns
1050 ///
1051 /// The ListConfigurationResourcesResult.
1052 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listConfigResources")]
1053 fn list_config_resources(&self) -> ListConfigResourcesResult {
1054 self.list_config_resources_with_options(&HashSet::new(), ListConfigResourcesOptions::default())
1055 }
1056
1057 /// List the configuration resources available in the cluster which matches config resource
1058 /// type. If no config resource types are specified, all configuration resources will be listed.
1059 ///
1060 /// # Arguments
1061 ///
1062 /// - `config_resource_types` - The set of configuration resource types to list.
1063 /// - `options` - The options to use when listing the configuration resources.
1064 ///
1065 /// # Returns
1066 ///
1067 /// The ListConfigurationResourcesResult.
1068 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listConfigResources")]
1069 fn list_config_resources_with_options(
1070 &self,
1071 config_resource_types: &HashSet<config_resource::Type>,
1072 options: ListConfigResourcesOptions,
1073 ) -> ListConfigResourcesResult;
1074
1075 /// Query the information of all log directories on the given set of brokers
1076 ///
1077 /// This is a convenience method for `Self::describe_log_dirs_with_options` with default
1078 /// options. See the overload for more details.
1079 ///
1080 /// This operation is supported by brokers with version 1.0.0 or higher.
1081 ///
1082 /// # Arguments
1083 ///
1084 /// - `brokers` - A list of brokers
1085 ///
1086 /// # Returns
1087 ///
1088 /// The DescribeLogDirsResult
1089 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeLogDirs")]
1090 fn describe_log_dirs(&self, brokers: &[i32]) -> DescribeLogDirsResult {
1091 self.describe_log_dirs_with_options(brokers, DescribeLogDirsOptions::default())
1092 }
1093
1094 /// Query the information of all log directories on the given set of brokers
1095 ///
1096 /// This operation is supported by brokers with version 1.0.0 or higher.
1097 ///
1098 /// # Arguments
1099 ///
1100 /// - `brokers` - A list of brokers
1101 /// - `options` - The options to use when querying log dir info
1102 ///
1103 /// # Returns
1104 ///
1105 /// The DescribeLogDirsResult
1106 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeLogDirs")]
1107 fn describe_log_dirs_with_options(&self, brokers: &[i32], options: DescribeLogDirsOptions)
1108 -> DescribeLogDirsResult;
1109
1110 /// Change the log directory for the specified replicas. If the replica does not exist on the
1111 /// broker, the result shows REPLICA_NOT_AVAILABLE for the given replica and the replica will be
1112 /// created in the given log directory on the broker when it is created later. If the replica
1113 /// already exists on the broker, the replica will be moved to the given log directory if it is
1114 /// not already there. For detailed result, inspect the returned `AlterReplicaLogDirsResult`
1115 /// instance.
1116 ///
1117 /// This operation is not transactional so it may succeed for some replicas while fail for
1118 /// others.
1119 ///
1120 /// This is a convenience method for `Self::alter_replica_log_dirs_with_options` with default
1121 /// options. See the overload for more details.
1122 ///
1123 /// This operation is supported by brokers with version 1.1.0 or higher.
1124 ///
1125 /// # Arguments
1126 ///
1127 /// - `replica_assignment` - The replicas with their log directory absolute path
1128 ///
1129 /// # Returns
1130 ///
1131 /// The AlterReplicaLogDirsResult
1132 #[doc(alias = "org.apache.kafka.clients.admin.Admin#alterReplicaLogDirs")]
1133 fn alter_replica_log_dirs(
1134 &self,
1135 replica_assignment: &HashMap<TopicPartitionReplica, String>,
1136 ) -> AlterReplicaLogDirsResult {
1137 self.alter_replica_log_dirs_with_options(replica_assignment, AlterReplicaLogDirsOptions::default())
1138 }
1139
1140 /// Change the log directory for the specified replicas. If the replica does not exist on the
1141 /// broker, the result shows REPLICA_NOT_AVAILABLE for the given replica and the replica will be
1142 /// created in the given log directory on the broker when it is created later. If the replica
1143 /// already exists on the broker, the replica will be moved to the given log directory if it is
1144 /// not already there. For detailed result, inspect the returned `AlterReplicaLogDirsResult`
1145 /// instance.
1146 ///
1147 /// This operation is not transactional so it may succeed for some replicas while fail for
1148 /// others.
1149 ///
1150 /// This operation is supported by brokers with version 1.1.0 or higher.
1151 ///
1152 /// # Arguments
1153 ///
1154 /// - `replica_assignment` - The replicas with their log directory absolute path
1155 /// - `options` - The options to use when changing replica dir
1156 ///
1157 /// # Returns
1158 ///
1159 /// The AlterReplicaLogDirsResult
1160 #[doc(alias = "org.apache.kafka.clients.admin.Admin#alterReplicaLogDirs")]
1161 fn alter_replica_log_dirs_with_options(
1162 &self,
1163 replica_assignment: &HashMap<TopicPartitionReplica, String>,
1164 options: AlterReplicaLogDirsOptions,
1165 ) -> AlterReplicaLogDirsResult;
1166
1167 /// Query the replica log directory information for the specified replicas.
1168 ///
1169 /// This is a convenience method for `Self::describe_replica_log_dirs_with_options` with default
1170 /// options. See the overload for more details.
1171 ///
1172 /// This operation is supported by brokers with version 1.0.0 or higher.
1173 ///
1174 /// # Arguments
1175 ///
1176 /// - `replicas` - The replicas to query
1177 ///
1178 /// # Returns
1179 ///
1180 /// The DescribeReplicaLogDirsResult
1181 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeReplicaLogDirs")]
1182 fn describe_replica_log_dirs(&self, replicas: &[TopicPartitionReplica]) -> DescribeReplicaLogDirsResult {
1183 self.describe_replica_log_dirs_with_options(replicas, DescribeReplicaLogDirsOptions::default())
1184 }
1185
1186 /// Query the replica log directory information for the specified replicas.
1187 ///
1188 /// This operation is supported by brokers with version 1.0.0 or higher.
1189 ///
1190 /// # Arguments
1191 ///
1192 /// - `replicas` - The replicas to query
1193 /// - `options` - The options to use when querying replica log dir info
1194 ///
1195 /// # Returns
1196 ///
1197 /// The DescribeReplicaLogDirsResult
1198 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeReplicaLogDirs")]
1199 fn describe_replica_log_dirs_with_options(
1200 &self,
1201 replicas: &[TopicPartitionReplica],
1202 options: DescribeReplicaLogDirsOptions,
1203 ) -> DescribeReplicaLogDirsResult;
1204
1205 /// Elect a replica as leader for topic partitions.
1206 ///
1207 /// This is a convenience method for `Self::elect_leaders_with_options` with default options.
1208 ///
1209 /// # Arguments
1210 ///
1211 /// - `election_type` - The type of election to conduct.
1212 /// - `partitions` - The topics and partitions for which to conduct elections.
1213 ///
1214 /// # Returns
1215 ///
1216 /// The ElectLeadersResult.
1217 #[doc(alias = "org.apache.kafka.clients.admin.Admin#electLeaders")]
1218 fn elect_leaders(
1219 &self,
1220 election_type: ElectionType,
1221 partitions: Option<HashSet<TopicPartition>>,
1222 ) -> ElectLeadersResult {
1223 self.elect_leaders_with_options(election_type, partitions, ElectLeadersOptions::default())
1224 }
1225
1226 /// Elect a replica as leader for the given `partitions`, or for all partitions if the argument
1227 /// to `partitions` is None.
1228 ///
1229 /// This operation is not transactional so it may succeed for some partitions while fail for
1230 /// others.
1231 ///
1232 /// It may take several seconds after this method returns success for all the brokers in the
1233 /// cluster to become aware that the partitions have new leaders. During this time,
1234 /// `Self::describe_topics_with_topic_names` may not return information about the partitions'
1235 /// new leaders.
1236 ///
1237 /// This operation is supported by brokers with version 2.2.0 or later if preferred election is
1238 /// use; otherwise the brokers most be 2.4.0 or higher.
1239 ///
1240 /// The following errors can be anticipated when calling `get()` on the future obtained from the
1241 /// returned `ElectLeadersResult`:
1242 ///
1243 /// - `Error::is_cluster_authorization_error` if the authenticated user didn't have alter access
1244 /// to the cluster.
1245 /// - `Error::is_unknown_topic_or_partition_error` if the topic or partition did not exist
1246 /// within the cluster.
1247 /// - `Error::is_invalid_topic_error` if the topic was already queued for deletion.
1248 /// - `Error::is_not_controller_error` if the request was sent to a broker that was not the
1249 /// controller for the cluster.
1250 /// - `Error::is_timeout_error` if the request timed out before the election was complete.
1251 /// - `Error::is_leader_not_available_error` if the preferred leader was not alive or not in the
1252 /// ISR.
1253 ///
1254 /// # Arguments
1255 ///
1256 /// - `election_type` - The type of election to conduct.
1257 /// - `partitions` - The topics and partitions for which to conduct elections.
1258 /// - `options` - The options to use when electing the leaders.
1259 ///
1260 /// # Returns
1261 ///
1262 /// The ElectLeadersResult.
1263 #[doc(alias = "org.apache.kafka.clients.admin.Admin#electLeaders")]
1264 fn elect_leaders_with_options(
1265 &self,
1266 election_type: ElectionType,
1267 partitions: Option<HashSet<TopicPartition>>,
1268 options: ElectLeadersOptions,
1269 ) -> ElectLeadersResult;
1270
1271 /// Change the reassignments for one or more partitions. Providing `None` will revert the
1272 /// reassignment for the associated partition. This is a convenience method for
1273 /// `Self::alter_partition_reassignments_with_options` with default options. See the overload
1274 /// for more details.
1275 ///
1276 /// # Arguments
1277 ///
1278 /// - `reassignments` - The reassignments to add, modify, or remove. See
1279 /// `NewPartitionReassignment`.
1280 ///
1281 /// # Returns
1282 ///
1283 /// The result.
1284 #[doc(alias = "org.apache.kafka.clients.admin.Admin#alterPartitionReassignments")]
1285 fn alter_partition_reassignments(
1286 &self,
1287 reassignments: &HashMap<TopicPartition, Option<NewPartitionReassignment>>,
1288 ) -> AlterPartitionReassignmentsResult {
1289 self.alter_partition_reassignments_with_options(reassignments, AlterPartitionReassignmentsOptions::default())
1290 }
1291
1292 /// Change the reassignments for one or more partitions. Providing `None` will revert the
1293 /// reassignment for the associated partition.
1294 ///
1295 /// The following errors can be anticipated when calling `get()` on the futures obtained from
1296 /// the returned `AlterPartitionReassignmentsResult`:
1297 ///
1298 /// - `Error::is_cluster_authorization_error` If the authenticated user didn't have alter access
1299 /// to the cluster.
1300 /// - `Error::is_unknown_topic_or_partition_error` If the topic or partition does not exist
1301 /// within the cluster.
1302 /// - `Error::is_timeout_error` if the request timed out before the controller could record the
1303 /// new assignments.
1304 /// - `Error::is_invalid_replica_assignment_error` If the specified assignment was not valid.
1305 /// - `Error::is_invalid_replication_factor_error` If the replication factor was changed in an
1306 /// invalid way. Only thrown when
1307 /// `AlterPartitionReassignmentsOptions::allow_replication_factor_change` is set to false and
1308 /// the request is attempting to alter reassignments (not cancel)
1309 /// - `Error::is_unsupported_version_error` If
1310 /// `AlterPartitionReassignmentsOptions::allow_replication_factor_change` was changed outside
1311 /// the default and the server does not support the option (e.g due to an old Kafka version).
1312 /// - `Error::is_no_reassignment_in_progress_error` If there was an attempt to cancel a
1313 /// reassignment for a partition which was not being reassigned.
1314 ///
1315 /// # Arguments
1316 ///
1317 /// - `reassignments` - The reassignments to add, modify, or remove. See
1318 /// `NewPartitionReassignment`.
1319 /// - `options` - The options to use.
1320 ///
1321 /// # Returns
1322 ///
1323 /// The result.
1324 #[doc(alias = "org.apache.kafka.clients.admin.Admin#alterPartitionReassignments")]
1325 fn alter_partition_reassignments_with_options(
1326 &self,
1327 reassignments: &HashMap<TopicPartition, Option<NewPartitionReassignment>>,
1328 options: AlterPartitionReassignmentsOptions,
1329 ) -> AlterPartitionReassignmentsResult;
1330
1331 /// List all of the current partition reassignments.
1332 ///
1333 /// This is a convenience method for `Self::list_partition_reassignments_with_options` with
1334 /// default options. See the overload for more details.
1335 ///
1336 /// # Returns
1337 ///
1338 /// The result.
1339 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listPartitionReassignments")]
1340 fn list_partition_reassignments(&self) -> ListPartitionReassignmentsResult {
1341 self.list_partition_reassignments_with_options(ListPartitionReassignmentsOptions::default())
1342 }
1343
1344 /// List the current reassignments for the given partitions.
1345 ///
1346 /// This is a convenience method for
1347 /// `Self::list_partition_reassignments_with_partitions_options` with default options. See the
1348 /// overload for more details.
1349 ///
1350 /// # Arguments
1351 ///
1352 /// - `partitions` - The topic partitions to list reassignments for.
1353 ///
1354 /// # Returns
1355 ///
1356 /// The result.
1357 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listPartitionReassignments")]
1358 fn list_partition_reassignments_with_partitions(
1359 &self,
1360 partitions: HashSet<TopicPartition>,
1361 ) -> ListPartitionReassignmentsResult {
1362 self.list_partition_reassignments_with_partitions_options(
1363 Some(partitions),
1364 ListPartitionReassignmentsOptions::default(),
1365 )
1366 }
1367
1368 /// List all of the current partition reassignments.
1369 ///
1370 /// The following errors can be anticipated when calling `get()` on the futures obtained from
1371 /// the returned `ListPartitionReassignmentsResult`:
1372 ///
1373 /// - `Error::is_cluster_authorization_error` If the authenticated user doesn't have alter
1374 /// access to the cluster.
1375 /// - `Error::is_unknown_topic_or_partition_error` If a given topic or partition does not exist.
1376 /// - `Error::is_timeout_error` If the request timed out before the controller could list the
1377 /// current reassignments.
1378 ///
1379 /// # Arguments
1380 ///
1381 /// - `options` - The options to use.
1382 ///
1383 /// # Returns
1384 ///
1385 /// The result.
1386 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listPartitionReassignments")]
1387 fn list_partition_reassignments_with_options(
1388 &self,
1389 options: ListPartitionReassignmentsOptions,
1390 ) -> ListPartitionReassignmentsResult {
1391 self.list_partition_reassignments_with_partitions_options(None, options)
1392 }
1393
1394 /// List the current reassignments for the given partitions.
1395 ///
1396 /// The following errors can be anticipated when calling `get()` on the futures obtained from
1397 /// the returned `ListPartitionReassignmentsResult`:
1398 ///
1399 /// - `Error::is_cluster_authorization_error` If the authenticated user doesn't have alter
1400 /// access to the cluster.
1401 /// - `Error::is_unknown_topic_or_partition_error` If a given topic or partition does not exist.
1402 /// - `Error::is_timeout_error` If the request timed out before the controller could list the
1403 /// current reassignments.
1404 ///
1405 /// # Arguments
1406 ///
1407 /// - `partitions` - the partitions we want to get reassignment for, or `None` if we want to get
1408 /// the reassignments for all partitions in the cluster
1409 /// - `options` - The options to use.
1410 ///
1411 /// # Returns
1412 ///
1413 /// The result.
1414 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listPartitionReassignments")]
1415 fn list_partition_reassignments_with_partitions_options(
1416 &self,
1417 partitions: Option<HashSet<TopicPartition>>,
1418 options: ListPartitionReassignmentsOptions,
1419 ) -> ListPartitionReassignmentsResult;
1420
1421 /// List offset for the specified partitions and OffsetSpec. This operation enables to find the
1422 /// beginning offset, end offset as well as the offset matching a timestamp in partitions.
1423 ///
1424 /// This is a convenience method for `Self::list_offsets_with_options`
1425 ///
1426 /// # Arguments
1427 ///
1428 /// - `topic_partition_offsets` - The mapping from partition to the OffsetSpec to look up.
1429 ///
1430 /// # Returns
1431 ///
1432 /// The ListOffsetsResult.
1433 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listOffsets")]
1434 fn list_offsets(&self, topic_partition_offsets: &HashMap<TopicPartition, OffsetSpec>) -> ListOffsetsResult {
1435 self.list_offsets_with_options(topic_partition_offsets, ListOffsetsOptions::default())
1436 }
1437
1438 /// List offset for the specified partitions. This operation enables to find the beginning
1439 /// offset, end offset as well as the offset matching a timestamp in partitions.
1440 ///
1441 /// # Arguments
1442 ///
1443 /// - `topic_partition_offsets` - The mapping from partition to the OffsetSpec to look up.
1444 /// - `options` - The options to use when retrieving the offsets
1445 ///
1446 /// # Returns
1447 ///
1448 /// The ListOffsetsResult.
1449 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listOffsets")]
1450 fn list_offsets_with_options(
1451 &self,
1452 topic_partition_offsets: &HashMap<TopicPartition, OffsetSpec>,
1453 options: ListOffsetsOptions,
1454 ) -> ListOffsetsResult;
1455
1456 /// List the groups available in the cluster with the default options.
1457 ///
1458 /// This is a convenience method for `Self::list_groups_with_options` with default options. See
1459 /// the overload for more details.
1460 ///
1461 /// # Returns
1462 ///
1463 /// The ListGroupsResult.
1464 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listGroups")]
1465 fn list_groups(&self) -> ListGroupsResult {
1466 self.list_groups_with_options(ListGroupsOptions::default())
1467 }
1468
1469 /// List the groups available in the cluster.
1470 ///
1471 /// # Arguments
1472 ///
1473 /// - `options` - The options to use when listing the groups.
1474 ///
1475 /// # Returns
1476 ///
1477 /// The ListGroupsResult.
1478 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listGroups")]
1479 fn list_groups_with_options(&self, options: ListGroupsOptions) -> ListGroupsResult;
1480
1481 /// Describe some consumer groups in the cluster, with the default options.
1482 ///
1483 /// This is a convenience method for `Self::describe_consumer_groups_with_options` with default
1484 /// options. See the overload for more details.
1485 ///
1486 /// # Arguments
1487 ///
1488 /// - `group_ids` - The IDs of the groups to describe.
1489 ///
1490 /// # Returns
1491 ///
1492 /// The DescribeConsumerGroupsResult.
1493 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeConsumerGroups")]
1494 fn describe_consumer_groups(&self, group_ids: &[String]) -> DescribeConsumerGroupsResult {
1495 self.describe_consumer_groups_with_options(group_ids, DescribeConsumerGroupsOptions::default())
1496 }
1497
1498 /// Describe some consumer groups in the cluster.
1499 ///
1500 /// # Arguments
1501 ///
1502 /// - `group_ids` - The IDs of the groups to describe.
1503 /// - `options` - The options to use when describing the groups.
1504 ///
1505 /// # Returns
1506 ///
1507 /// The DescribeConsumerGroupsResult.
1508 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeConsumerGroups")]
1509 fn describe_consumer_groups_with_options(
1510 &self,
1511 group_ids: &[String],
1512 options: DescribeConsumerGroupsOptions,
1513 ) -> DescribeConsumerGroupsResult;
1514
1515 /// Describe some classic groups in the cluster, with the default options.
1516 ///
1517 /// This is a convenience method for `Self::describe_classic_groups_with_options` with default
1518 /// options. See the overload for more details.
1519 ///
1520 /// # Arguments
1521 ///
1522 /// - `group_ids` - The IDs of the groups to describe.
1523 ///
1524 /// # Returns
1525 ///
1526 /// The DescribeClassicGroupsResult.
1527 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeClassicGroups")]
1528 fn describe_classic_groups(&self, group_ids: &[String]) -> DescribeClassicGroupsResult {
1529 self.describe_classic_groups_with_options(group_ids, DescribeClassicGroupsOptions::default())
1530 }
1531
1532 /// Describe some classic groups in the cluster.
1533 ///
1534 /// # Arguments
1535 ///
1536 /// - `group_ids` - The IDs of the groups to describe.
1537 /// - `options` - The options to use when describing the groups.
1538 ///
1539 /// # Returns
1540 ///
1541 /// The DescribeClassicGroupsResult.
1542 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeClassicGroups")]
1543 fn describe_classic_groups_with_options(
1544 &self,
1545 group_ids: &[String],
1546 options: DescribeClassicGroupsOptions,
1547 ) -> DescribeClassicGroupsResult;
1548
1549 /// List the consumer group offsets available in the cluster with the default options.
1550 ///
1551 /// This is a convenience method for `Self::list_consumer_group_offsets_with_group_id_options`
1552 /// to list offsets of all partitions of one group with default options.
1553 ///
1554 /// # Arguments
1555 ///
1556 /// - `group_id` - The group to list the offsets of.
1557 ///
1558 /// # Returns
1559 ///
1560 /// The ListConsumerGroupOffsetsResult.
1561 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listConsumerGroupOffsets")]
1562 fn list_consumer_group_offsets_with_group_id(&self, group_id: &str) -> ListConsumerGroupOffsetsResult {
1563 self.list_consumer_group_offsets_with_group_id_options(group_id, ListConsumerGroupOffsetsOptions::default())
1564 }
1565
1566 /// List the consumer group offsets available in the cluster.
1567 ///
1568 /// # Arguments
1569 ///
1570 /// - `group_id` - The group to list the offsets of.
1571 /// - `options` - The options to use when listing the consumer group offsets.
1572 ///
1573 /// # Returns
1574 ///
1575 /// The ListConsumerGroupOffsetsResult
1576 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listConsumerGroupOffsets")]
1577 fn list_consumer_group_offsets_with_group_id_options(
1578 &self,
1579 group_id: &str,
1580 options: ListConsumerGroupOffsetsOptions,
1581 ) -> ListConsumerGroupOffsetsResult {
1582 let group_spec = ListConsumerGroupOffsetsSpec::new();
1583
1584 // We can use the provided options with the batched API, which uses topic partitions from
1585 // the group spec and ignores any topic partitions set in the options.
1586 self.list_consumer_group_offsets_with_group_specs_options(
1587 &HashMap::from([(group_id.to_string(), group_spec)]),
1588 options,
1589 )
1590 }
1591
1592 /// List the consumer group offsets available in the cluster for the specified groups with the
1593 /// default options.
1594 ///
1595 /// This is a convenience method for
1596 /// `Self::list_consumer_group_offsets_with_group_specs_options` with default options.
1597 ///
1598 /// # Arguments
1599 ///
1600 /// - `group_specs` - Map of consumer group ids to a spec that specifies the topic partitions of
1601 /// the group to list offsets for.
1602 ///
1603 /// # Returns
1604 ///
1605 /// The ListConsumerGroupOffsetsResult.
1606 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listConsumerGroupOffsets")]
1607 fn list_consumer_group_offsets_with_group_specs(
1608 &self,
1609 group_specs: &HashMap<String, ListConsumerGroupOffsetsSpec>,
1610 ) -> ListConsumerGroupOffsetsResult {
1611 self.list_consumer_group_offsets_with_group_specs_options(
1612 group_specs,
1613 ListConsumerGroupOffsetsOptions::default(),
1614 )
1615 }
1616
1617 /// List the consumer group offsets available in the cluster for the specified consumer groups.
1618 ///
1619 /// # Arguments
1620 ///
1621 /// - `group_specs` - Map of consumer group ids to a spec that specifies the topic partitions of
1622 /// the group to list offsets for.
1623 /// - `options` - The options to use when listing the consumer group offsets.
1624 ///
1625 /// # Returns
1626 ///
1627 /// The ListConsumerGroupOffsetsResult
1628 #[doc(alias = "org.apache.kafka.clients.admin.Admin#listConsumerGroupOffsets")]
1629 fn list_consumer_group_offsets_with_group_specs_options(
1630 &self,
1631 group_specs: &HashMap<String, ListConsumerGroupOffsetsSpec>,
1632 options: ListConsumerGroupOffsetsOptions,
1633 ) -> ListConsumerGroupOffsetsResult;
1634
1635 /// Alters offsets for the specified group. In order to succeed, the group must be empty.
1636 ///
1637 /// This is a convenience method for `Self::alter_consumer_group_offsets_with_options` with
1638 /// default options. See the overload for more details.
1639 ///
1640 /// # Arguments
1641 ///
1642 /// - `group_id` - The group for which to alter offsets.
1643 /// - `offsets` - A map of offsets by partition with associated metadata.
1644 ///
1645 /// # Returns
1646 ///
1647 /// The AlterOffsetsResult.
1648 #[doc(alias = "org.apache.kafka.clients.admin.Admin#alterConsumerGroupOffsets")]
1649 fn alter_consumer_group_offsets(
1650 &self,
1651 group_id: &str,
1652 offsets: &HashMap<TopicPartition, OffsetAndMetadata>,
1653 ) -> AlterConsumerGroupOffsetsResult {
1654 self.alter_consumer_group_offsets_with_options(group_id, offsets, AlterConsumerGroupOffsetsOptions::default())
1655 }
1656
1657 /// Alters offsets for the specified group. In order to succeed, the group must be empty.
1658 ///
1659 /// This operation is not transactional so it may succeed for some partitions while fail for
1660 /// others.
1661 ///
1662 /// # Arguments
1663 ///
1664 /// - `group_id` - The group for which to alter offsets.
1665 /// - `offsets` - A map of offsets by partition with associated metadata. Partitions not
1666 /// specified in the map are ignored.
1667 /// - `options` - The options to use when altering the offsets.
1668 ///
1669 /// # Returns
1670 ///
1671 /// The AlterOffsetsResult.
1672 #[doc(alias = "org.apache.kafka.clients.admin.Admin#alterConsumerGroupOffsets")]
1673 fn alter_consumer_group_offsets_with_options(
1674 &self,
1675 group_id: &str,
1676 offsets: &HashMap<TopicPartition, OffsetAndMetadata>,
1677 options: AlterConsumerGroupOffsetsOptions,
1678 ) -> AlterConsumerGroupOffsetsResult;
1679
1680 /// Delete committed offsets for a set of partitions in a consumer group with the default
1681 /// options. This will succeed at the partition level only if the group is not actively
1682 /// subscribed to the corresponding topic.
1683 ///
1684 /// # Arguments
1685 ///
1686 /// - `group_id` - The group to delete the offsets of.
1687 /// - `partitions` - The partitions whose committed offsets to delete.
1688 ///
1689 /// # Returns
1690 ///
1691 /// The DeleteConsumerGroupOffsetsResult.
1692 #[doc(alias = "org.apache.kafka.clients.admin.Admin#deleteConsumerGroupOffsets")]
1693 fn delete_consumer_group_offsets(
1694 &self,
1695 group_id: &str,
1696 partitions: &HashSet<TopicPartition>,
1697 ) -> DeleteConsumerGroupOffsetsResult {
1698 self.delete_consumer_group_offsets_with_options(
1699 group_id,
1700 partitions,
1701 DeleteConsumerGroupOffsetsOptions::default(),
1702 )
1703 }
1704
1705 /// Delete committed offsets for a set of partitions in a consumer group. This will succeed at
1706 /// the partition level only if the group is not actively subscribed to the corresponding topic.
1707 ///
1708 /// # Arguments
1709 ///
1710 /// - `group_id` - The group to delete the offsets of.
1711 /// - `partitions` - The partitions whose committed offsets to delete.
1712 /// - `options` - The options to use when deleting offsets in a consumer group.
1713 ///
1714 /// # Returns
1715 ///
1716 /// The DeleteConsumerGroupOffsetsResult.
1717 #[doc(alias = "org.apache.kafka.clients.admin.Admin#deleteConsumerGroupOffsets")]
1718 fn delete_consumer_group_offsets_with_options(
1719 &self,
1720 group_id: &str,
1721 partitions: &HashSet<TopicPartition>,
1722 options: DeleteConsumerGroupOffsetsOptions,
1723 ) -> DeleteConsumerGroupOffsetsResult;
1724
1725 /// Delete consumer groups from the cluster with the default options.
1726 ///
1727 /// # Arguments
1728 ///
1729 /// - `group_ids` - The ids of the groups to delete.
1730 ///
1731 /// # Returns
1732 ///
1733 /// The DeleteConsumerGroupResult.
1734 #[doc(alias = "org.apache.kafka.clients.admin.Admin#deleteConsumerGroups")]
1735 fn delete_consumer_groups(&self, group_ids: &[String]) -> DeleteConsumerGroupsResult {
1736 self.delete_consumer_groups_with_options(group_ids, DeleteConsumerGroupsOptions::default())
1737 }
1738
1739 /// Delete consumer groups from the cluster.
1740 ///
1741 /// # Arguments
1742 ///
1743 /// - `group_ids` - The ids of the groups to delete.
1744 /// - `options` - The options to use when deleting a consumer group.
1745 ///
1746 /// # Returns
1747 ///
1748 /// The DeleteConsumerGroupsResult.
1749 #[doc(alias = "org.apache.kafka.clients.admin.Admin#deleteConsumerGroups")]
1750 fn delete_consumer_groups_with_options(
1751 &self,
1752 group_ids: &[String],
1753 options: DeleteConsumerGroupsOptions,
1754 ) -> DeleteConsumerGroupsResult;
1755
1756 /// Remove members from the consumer group by given member identities.
1757 ///
1758 /// For possible error codes, refer to `LeaveGroupResponse`.
1759 ///
1760 /// # Arguments
1761 ///
1762 /// - `group_id` - The ID of the group to remove member from.
1763 /// - `options` - The options to carry removing members' information.
1764 ///
1765 /// # Returns
1766 ///
1767 /// The MembershipChangeResult.
1768 #[doc(alias = "org.apache.kafka.clients.admin.Admin#removeMembersFromConsumerGroup")]
1769 fn remove_members_from_consumer_group_with_options(
1770 &self,
1771 group_id: &str,
1772 options: RemoveMembersFromConsumerGroupOptions,
1773 ) -> RemoveMembersFromConsumerGroupResult;
1774
1775 /// This is a convenience method for `Self::create_acls_with_options` with default options. See
1776 /// the overload for more details.
1777 ///
1778 /// This operation is supported by brokers with version 0.11.0.0 or higher.
1779 ///
1780 /// # Arguments
1781 ///
1782 /// - `acls` - The ACLs to create
1783 ///
1784 /// # Returns
1785 ///
1786 /// The CreateAclsResult.
1787 #[doc(alias = "org.apache.kafka.clients.admin.Admin#createAcls")]
1788 fn create_acls(&self, acls: &[AclBinding]) -> CreateAclsResult {
1789 self.create_acls_with_options(acls, CreateAclsOptions::default())
1790 }
1791
1792 /// Creates access control lists (ACLs) which are bound to specific resources.
1793 ///
1794 /// This operation is not transactional so it may succeed for some ACLs while fail for others.
1795 ///
1796 /// If you attempt to add an ACL that duplicates an existing ACL, no error will be raised, but
1797 /// no changes will be made.
1798 ///
1799 /// This operation is supported by brokers with version 0.11.0.0 or higher.
1800 ///
1801 /// # Arguments
1802 ///
1803 /// - `acls` - The ACLs to create
1804 /// - `options` - The options to use when creating the ACLs.
1805 ///
1806 /// # Returns
1807 ///
1808 /// The CreateAclsResult.
1809 #[doc(alias = "org.apache.kafka.clients.admin.Admin#createAcls")]
1810 fn create_acls_with_options(&self, acls: &[AclBinding], options: CreateAclsOptions) -> CreateAclsResult;
1811
1812 /// This is a convenience method for `Self::describe_acls_with_options` with default options.
1813 /// See the overload for more details.
1814 ///
1815 /// This operation is supported by brokers with version 0.11.0.0 or higher.
1816 ///
1817 /// # Arguments
1818 ///
1819 /// - `filter` - The filter to use.
1820 ///
1821 /// # Returns
1822 ///
1823 /// The DescribeAclsResult.
1824 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeAcls")]
1825 fn describe_acls(&self, filter: &AclBindingFilter) -> DescribeAclsResult {
1826 self.describe_acls_with_options(filter, DescribeAclsOptions::default())
1827 }
1828
1829 /// Lists access control lists (ACLs) according to the supplied filter.
1830 ///
1831 /// Note: it may take some time for changes made by `createAcls` or `deleteAcls` to be reflected
1832 /// in the output of `describeAcls`.
1833 ///
1834 /// This operation is supported by brokers with version 0.11.0.0 or higher.
1835 ///
1836 /// # Arguments
1837 ///
1838 /// - `filter` - The filter to use.
1839 /// - `options` - The options to use when listing the ACLs.
1840 ///
1841 /// # Returns
1842 ///
1843 /// The DescribeAclsResult.
1844 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeAcls")]
1845 fn describe_acls_with_options(&self, filter: &AclBindingFilter, options: DescribeAclsOptions)
1846 -> DescribeAclsResult;
1847
1848 /// This is a convenience method for `Self::delete_acls_with_options` with default options. See
1849 /// the overload for more details.
1850 ///
1851 /// This operation is supported by brokers with version 0.11.0.0 or higher.
1852 ///
1853 /// # Arguments
1854 ///
1855 /// - `filters` - The filters to use.
1856 ///
1857 /// # Returns
1858 ///
1859 /// The DeleteAclsResult.
1860 #[doc(alias = "org.apache.kafka.clients.admin.Admin#deleteAcls")]
1861 fn delete_acls(&self, filters: &[AclBindingFilter]) -> DeleteAclsResult {
1862 self.delete_acls_with_options(filters, DeleteAclsOptions::default())
1863 }
1864
1865 /// Deletes access control lists (ACLs) according to the supplied filters.
1866 ///
1867 /// This operation is not transactional so it may succeed for some ACLs while fail for others.
1868 ///
1869 /// This operation is supported by brokers with version 0.11.0.0 or higher.
1870 ///
1871 /// # Arguments
1872 ///
1873 /// - `filters` - The filters to use.
1874 /// - `options` - The options to use when deleting the ACLs.
1875 ///
1876 /// # Returns
1877 ///
1878 /// The DeleteAclsResult.
1879 #[doc(alias = "org.apache.kafka.clients.admin.Admin#deleteAcls")]
1880 fn delete_acls_with_options(&self, filters: &[AclBindingFilter], options: DeleteAclsOptions) -> DeleteAclsResult;
1881
1882 /// Describes all entities matching the provided filter that have at least one client quota
1883 /// configuration value defined.
1884 ///
1885 /// This is a convenience method for `Self::describe_client_quotas_with_options` with default
1886 /// options. See the overload for more details.
1887 ///
1888 /// This operation is supported by brokers with version 2.6.0 or higher.
1889 ///
1890 /// # Arguments
1891 ///
1892 /// - `filter` - the filter to apply to match entities
1893 ///
1894 /// # Returns
1895 ///
1896 /// the DescribeClientQuotasResult containing the result
1897 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeClientQuotas")]
1898 fn describe_client_quotas(&self, filter: &ClientQuotaFilter) -> DescribeClientQuotasResult {
1899 self.describe_client_quotas_with_options(filter, DescribeClientQuotasOptions::default())
1900 }
1901
1902 /// Describes all entities matching the provided filter that have at least one client quota
1903 /// configuration value defined.
1904 ///
1905 /// The following errors can be anticipated when calling `get()` on the future from the returned
1906 /// `DescribeClientQuotasResult`:
1907 ///
1908 /// - `Error::is_cluster_authorization_error` If the authenticated user didn't have describe
1909 /// access to the cluster.
1910 /// - `Error::is_invalid_request_error` If the request details are invalid. e.g., an invalid
1911 /// entity type was specified.
1912 /// - `Error::is_timeout_error` If the request timed out before the describe could finish.
1913 ///
1914 /// This operation is supported by brokers with version 2.6.0 or higher.
1915 ///
1916 /// # Arguments
1917 ///
1918 /// - `filter` - the filter to apply to match entities
1919 /// - `options` - the options to use
1920 ///
1921 /// # Returns
1922 ///
1923 /// the DescribeClientQuotasResult containing the result
1924 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeClientQuotas")]
1925 fn describe_client_quotas_with_options(
1926 &self,
1927 filter: &ClientQuotaFilter,
1928 options: DescribeClientQuotasOptions,
1929 ) -> DescribeClientQuotasResult;
1930
1931 /// Alters client quota configurations with the specified alterations.
1932 ///
1933 /// This is a convenience method for `Self::alter_client_quotas_with_options` with default
1934 /// options. See the overload for more details.
1935 ///
1936 /// This operation is supported by brokers with version 2.6.0 or higher.
1937 ///
1938 /// # Arguments
1939 ///
1940 /// - `entries` - the alterations to perform
1941 ///
1942 /// # Returns
1943 ///
1944 /// the AlterClientQuotasResult containing the result
1945 #[doc(alias = "org.apache.kafka.clients.admin.Admin#alterClientQuotas")]
1946 fn alter_client_quotas(&self, entries: &[ClientQuotaAlteration]) -> AlterClientQuotasResult {
1947 self.alter_client_quotas_with_options(entries, AlterClientQuotasOptions::default())
1948 }
1949
1950 /// Alters client quota configurations with the specified alterations.
1951 ///
1952 /// Alterations for a single entity are atomic, but across entities is not guaranteed. The
1953 /// resulting per-entity error code should be evaluated to resolve the success or failure of all
1954 /// updates.
1955 ///
1956 /// The following errors can be anticipated when calling `get()` on the futures obtained from
1957 /// the returned `AlterClientQuotasResult`:
1958 ///
1959 /// - `Error::is_cluster_authorization_error` If the authenticated user didn't have alter access
1960 /// to the cluster.
1961 /// - `Error::is_invalid_request_error` If the request details are invalid. e.g., a
1962 /// configuration key was specified more than once for an entity.
1963 /// - `Error::is_timeout_error` If the request timed out before the alterations could finish. It
1964 /// cannot be guaranteed whether the update succeed or not.
1965 ///
1966 /// This operation is supported by brokers with version 2.6.0 or higher.
1967 ///
1968 /// # Arguments
1969 ///
1970 /// - `entries` - the alterations to perform
1971 /// - `options` - The options to use when altering the quotas.
1972 ///
1973 /// # Returns
1974 ///
1975 /// the AlterClientQuotasResult containing the result
1976 #[doc(alias = "org.apache.kafka.clients.admin.Admin#alterClientQuotas")]
1977 fn alter_client_quotas_with_options(
1978 &self,
1979 entries: &[ClientQuotaAlteration],
1980 options: AlterClientQuotasOptions,
1981 ) -> AlterClientQuotasResult;
1982
1983 /// Describe all SASL/SCRAM credentials.
1984 ///
1985 /// This is a convenience method for `Self::describe_user_scram_credentials_with_users_options`
1986 ///
1987 /// # Returns
1988 ///
1989 /// The DescribeUserScramCredentialsResult.
1990 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeUserScramCredentials")]
1991 fn describe_user_scram_credentials(&self) -> DescribeUserScramCredentialsResult {
1992 self.describe_user_scram_credentials_with_users_options(&[], DescribeUserScramCredentialsOptions::default())
1993 }
1994
1995 /// Describe SASL/SCRAM credentials for the given users.
1996 ///
1997 /// This is a convenience method for `Self::describe_user_scram_credentials_with_users_options`
1998 ///
1999 /// # Arguments
2000 ///
2001 /// - `users` - the users for which credentials are to be described; all users' credentials are
2002 /// described if empty.
2003 ///
2004 /// # Returns
2005 ///
2006 /// The DescribeUserScramCredentialsResult.
2007 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeUserScramCredentials")]
2008 fn describe_user_scram_credentials_with_users(&self, users: &[String]) -> DescribeUserScramCredentialsResult {
2009 self.describe_user_scram_credentials_with_users_options(users, DescribeUserScramCredentialsOptions::default())
2010 }
2011
2012 /// Describe SASL/SCRAM credentials.
2013 ///
2014 /// The following errors can be anticipated when calling `get()` on the futures from the
2015 /// returned `DescribeUserScramCredentialsResult`:
2016 ///
2017 /// - `Error::is_cluster_authorization_error` If the authenticated user didn't have describe
2018 /// access to the cluster.
2019 /// - `Error::is_resource_not_found_error` If the user did not exist/had no SCRAM credentials.
2020 /// - `Error::is_duplicate_resource_error` If the user was requested to be described more than
2021 /// once in the original request.
2022 /// - `Error::is_timeout_error` If the request timed out before the describe operation could
2023 /// finish.
2024 ///
2025 /// This operation is supported by brokers with version 2.7.0 or higher.
2026 ///
2027 /// # Arguments
2028 ///
2029 /// - `users` - the users for which credentials are to be described; all users' credentials are
2030 /// described if empty.
2031 /// - `options` - The options to use when describing the credentials
2032 ///
2033 /// # Returns
2034 ///
2035 /// The DescribeUserScramCredentialsResult.
2036 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeUserScramCredentials")]
2037 fn describe_user_scram_credentials_with_users_options(
2038 &self,
2039 users: &[String],
2040 options: DescribeUserScramCredentialsOptions,
2041 ) -> DescribeUserScramCredentialsResult;
2042
2043 /// Alter SASL/SCRAM credentials for the given users.
2044 ///
2045 /// This is a convenience method for `Self::alter_user_scram_credentials_with_options`
2046 ///
2047 /// # Arguments
2048 ///
2049 /// - `alterations` - the alterations to be applied
2050 ///
2051 /// # Returns
2052 ///
2053 /// The AlterUserScramCredentialsResult.
2054 #[doc(alias = "org.apache.kafka.clients.admin.Admin#alterUserScramCredentials")]
2055 fn alter_user_scram_credentials(
2056 &self,
2057 alterations: &[UserScramCredentialAlteration],
2058 ) -> AlterUserScramCredentialsResult {
2059 self.alter_user_scram_credentials_with_options(alterations, AlterUserScramCredentialsOptions::default())
2060 }
2061
2062 /// Alter SASL/SCRAM credentials.
2063 ///
2064 /// The following errors can be anticipated when calling `get()` any of the futures from the
2065 /// returned `AlterUserScramCredentialsResult`:
2066 ///
2067 /// - `Error::is_not_controller_error` If the request is not sent to the Controller broker.
2068 /// - `Error::is_cluster_authorization_error` If the authenticated user didn't have alter access
2069 /// to the cluster.
2070 /// - `Error::is_unsupported_by_authentication_error` If the user authenticated with a
2071 /// delegation token.
2072 /// - `Error::is_unsupported_sasl_mechanism_error` If the requested SCRAM mechanism is
2073 /// unrecognized or otherwise unsupported.
2074 /// - `Error::is_unacceptable_credential_error` If the username is empty or the requested number
2075 /// of iterations is too small or too large.
2076 /// - `Error::is_timeout_error` If the request timed out before the describe could finish.
2077 ///
2078 /// This operation is supported by brokers with version 2.7.0 or higher.
2079 ///
2080 /// # Arguments
2081 ///
2082 /// - `alterations` - the alterations to be applied
2083 /// - `options` - The options to use when altering the credentials
2084 ///
2085 /// # Returns
2086 ///
2087 /// The AlterUserScramCredentialsResult.
2088 #[doc(alias = "org.apache.kafka.clients.admin.Admin#alterUserScramCredentials")]
2089 fn alter_user_scram_credentials_with_options(
2090 &self,
2091 alterations: &[UserScramCredentialAlteration],
2092 options: AlterUserScramCredentialsOptions,
2093 ) -> AlterUserScramCredentialsResult;
2094
2095 /// Create a Delegation Token.
2096 ///
2097 /// This is a convenience method for `Self::create_delegation_token_with_options` with default
2098 /// options. See the overload for more details.
2099 ///
2100 /// # Returns
2101 ///
2102 /// The CreateDelegationTokenResult.
2103 #[doc(alias = "org.apache.kafka.clients.admin.Admin#createDelegationToken")]
2104 fn create_delegation_token(&self) -> CreateDelegationTokenResult {
2105 self.create_delegation_token_with_options(CreateDelegationTokenOptions::default())
2106 }
2107
2108 /// Create a Delegation Token.
2109 ///
2110 /// This operation is supported by brokers with version 1.1.0 or higher.
2111 ///
2112 /// The following errors can be anticipated when calling `get()` on the futures obtained from
2113 /// the delegationToken() method of the returned `CreateDelegationTokenResult`
2114 ///
2115 /// - `Error::is_unsupported_by_authentication_error` If the request sent on PLAINTEXT/1-way SSL
2116 /// channels or delegation token authenticated channels.
2117 /// - `Error::is_invalid_principal_type_error` if the renewers principal type is not supported.
2118 /// - `Error::is_delegation_token_disabled_error` if the delegation token feature is disabled.
2119 /// - `Error::is_timeout_error` if the request was not completed in within the given
2120 /// `CreateDelegationTokenOptions::timeout_ms`.
2121 ///
2122 /// # Arguments
2123 ///
2124 /// - `options` - The options to use when creating delegation token.
2125 ///
2126 /// # Returns
2127 ///
2128 /// The CreateDelegationTokenResult.
2129 #[doc(alias = "org.apache.kafka.clients.admin.Admin#createDelegationToken")]
2130 fn create_delegation_token_with_options(
2131 &self,
2132 options: CreateDelegationTokenOptions,
2133 ) -> CreateDelegationTokenResult;
2134
2135 /// Renew a Delegation Token.
2136 ///
2137 /// This is a convenience method for `Self::renew_delegation_token_with_options` with default
2138 /// options. See the overload for more details.
2139 ///
2140 /// # Arguments
2141 ///
2142 /// - `hmac` - HMAC of the Delegation token
2143 ///
2144 /// # Returns
2145 ///
2146 /// The RenewDelegationTokenResult.
2147 #[doc(alias = "org.apache.kafka.clients.admin.Admin#renewDelegationToken")]
2148 fn renew_delegation_token(&self, hmac: &[u8]) -> RenewDelegationTokenResult {
2149 self.renew_delegation_token_with_options(hmac, RenewDelegationTokenOptions::default())
2150 }
2151
2152 /// Renew a Delegation Token.
2153 ///
2154 /// This operation is supported by brokers with version 1.1.0 or higher.
2155 ///
2156 /// The following errors can be anticipated when calling `get()` on the futures obtained from
2157 /// the expiryTimestamp() method of the returned `RenewDelegationTokenResult`
2158 ///
2159 /// - `Error::is_unsupported_by_authentication_error` If the request sent on PLAINTEXT/1-way SSL
2160 /// channels or delegation token authenticated channels.
2161 /// - `Error::is_delegation_token_disabled_error` if the delegation token feature is disabled.
2162 /// - `Error::is_delegation_token_not_found_error` if the delegation token is not found on
2163 /// server.
2164 /// - `Error::is_delegation_token_owner_mismatch_error` if the authenticated user is not
2165 /// owner/renewer of the token.
2166 /// - `Error::is_delegation_token_expired_error` if the delegation token is expired.
2167 /// - `Error::is_timeout_error` if the request was not completed in within the given
2168 /// `RenewDelegationTokenOptions::timeout_ms`.
2169 ///
2170 /// # Arguments
2171 ///
2172 /// - `hmac` - HMAC of the Delegation token
2173 /// - `options` - The options to use when renewing delegation token.
2174 ///
2175 /// # Returns
2176 ///
2177 /// The RenewDelegationTokenResult.
2178 #[doc(alias = "org.apache.kafka.clients.admin.Admin#renewDelegationToken")]
2179 fn renew_delegation_token_with_options(
2180 &self,
2181 hmac: &[u8],
2182 options: RenewDelegationTokenOptions,
2183 ) -> RenewDelegationTokenResult;
2184
2185 /// Expire a Delegation Token.
2186 ///
2187 /// This is a convenience method for `Self::expire_delegation_token_with_options` with default
2188 /// options. This will expire the token immediately. See the overload for more details.
2189 ///
2190 /// # Arguments
2191 ///
2192 /// - `hmac` - HMAC of the Delegation token
2193 ///
2194 /// # Returns
2195 ///
2196 /// The ExpireDelegationTokenResult.
2197 #[doc(alias = "org.apache.kafka.clients.admin.Admin#expireDelegationToken")]
2198 fn expire_delegation_token(&self, hmac: &[u8]) -> ExpireDelegationTokenResult {
2199 self.expire_delegation_token_with_options(hmac, ExpireDelegationTokenOptions::default())
2200 }
2201
2202 /// Expire a Delegation Token.
2203 ///
2204 /// This operation is supported by brokers with version 1.1.0 or higher.
2205 ///
2206 /// The following errors can be anticipated when calling `get()` on the futures obtained from
2207 /// the expiryTimestamp() method of the returned `ExpireDelegationTokenResult`
2208 ///
2209 /// - `Error::is_unsupported_by_authentication_error` If the request sent on PLAINTEXT/1-way SSL
2210 /// channels or delegation token authenticated channels.
2211 /// - `Error::is_delegation_token_disabled_error` if the delegation token feature is disabled.
2212 /// - `Error::is_delegation_token_not_found_error` if the delegation token is not found on
2213 /// server.
2214 /// - `Error::is_delegation_token_owner_mismatch_error` if the authenticated user is not
2215 /// owner/renewer of the requested token.
2216 /// - `Error::is_delegation_token_expired_error` if the delegation token is expired.
2217 /// - `Error::is_timeout_error` if the request was not completed in within the given
2218 /// `ExpireDelegationTokenOptions::timeout_ms`.
2219 ///
2220 /// # Arguments
2221 ///
2222 /// - `hmac` - HMAC of the Delegation token
2223 /// - `options` - The options to use when expiring delegation token.
2224 ///
2225 /// # Returns
2226 ///
2227 /// The ExpireDelegationTokenResult.
2228 #[doc(alias = "org.apache.kafka.clients.admin.Admin#expireDelegationToken")]
2229 fn expire_delegation_token_with_options(
2230 &self,
2231 hmac: &[u8],
2232 options: ExpireDelegationTokenOptions,
2233 ) -> ExpireDelegationTokenResult;
2234
2235 /// Describe the Delegation Tokens.
2236 ///
2237 /// This is a convenience method for `Self::describe_delegation_token_with_options` with default
2238 /// options. This will return all the user owned tokens and tokens where user have Describe
2239 /// permission. See the overload for more details.
2240 ///
2241 /// # Returns
2242 ///
2243 /// The DescribeDelegationTokenResult.
2244 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeDelegationToken")]
2245 fn describe_delegation_token(&self) -> DescribeDelegationTokenResult {
2246 self.describe_delegation_token_with_options(DescribeDelegationTokenOptions::default())
2247 }
2248
2249 /// Describe the Delegation Tokens.
2250 ///
2251 /// This operation is supported by brokers with version 1.1.0 or higher.
2252 ///
2253 /// The following errors can be anticipated when calling `get()` on the futures obtained from
2254 /// the delegationTokens() method of the returned `DescribeDelegationTokenResult`
2255 ///
2256 /// - `Error::is_unsupported_by_authentication_error` If the request sent on PLAINTEXT/1-way SSL
2257 /// channels or delegation token authenticated channels.
2258 /// - `Error::is_delegation_token_disabled_error` if the delegation token feature is disabled.
2259 /// - `Error::is_timeout_error` if the request was not completed in within the given
2260 /// `DescribeDelegationTokenOptions::timeout_ms`.
2261 ///
2262 /// # Arguments
2263 ///
2264 /// - `options` - The options to use when describing delegation tokens.
2265 ///
2266 /// # Returns
2267 ///
2268 /// The DescribeDelegationTokenResult.
2269 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeDelegationToken")]
2270 fn describe_delegation_token_with_options(
2271 &self,
2272 options: DescribeDelegationTokenOptions,
2273 ) -> DescribeDelegationTokenResult;
2274
2275 /// Describes finalized as well as supported features.
2276 ///
2277 /// This is a convenience method for `Self::describe_features_with_options` with default
2278 /// options. See the overload for more details.
2279 ///
2280 /// # Returns
2281 ///
2282 /// the `DescribeFeaturesResult` containing the result
2283 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeFeatures")]
2284 fn describe_features(&self) -> DescribeFeaturesResult {
2285 self.describe_features_with_options(DescribeFeaturesOptions::default())
2286 }
2287
2288 /// Describes finalized as well as supported features. The request is issued to any random
2289 /// broker.
2290 ///
2291 /// The following errors can be anticipated when calling `get()` on the future from the returned
2292 /// `DescribeFeaturesResult`:
2293 ///
2294 /// - `Error::is_timeout_error` If the request timed out before the describe operation could
2295 /// finish.
2296 ///
2297 /// # Arguments
2298 ///
2299 /// - `options` - the options to use
2300 ///
2301 /// # Returns
2302 ///
2303 /// the `DescribeFeaturesResult` containing the result
2304 #[doc(alias = "org.apache.kafka.clients.admin.Admin#describeFeatures")]
2305 fn describe_features_with_options(&self, options: DescribeFeaturesOptions) -> DescribeFeaturesResult;
2306
2307 /// Applies specified updates to finalized features.
2308 ///
2309 /// This is a convenience method for `Self::update_features_with_options` with default options.
2310 /// See the overload for more details.
2311 ///
2312 /// # Arguments
2313 ///
2314 /// - `feature_updates` - the map of finalized feature name to `FeatureUpdate`
2315 ///
2316 /// # Returns
2317 ///
2318 /// the `UpdateFeaturesResult` containing the result
2319 ///
2320 /// # Errors
2321 ///
2322 /// - `Error::is_local_illegal_argument_error` if `feature_updates` is empty or any feature name
2323 /// is blank.
2324 #[doc(alias = "org.apache.kafka.clients.admin.Admin#updateFeatures")]
2325 fn update_features(&self, feature_updates: &HashMap<String, FeatureUpdate>) -> Result<UpdateFeaturesResult, Error> {
2326 self.update_features_with_options(feature_updates, UpdateFeaturesOptions::default())
2327 }
2328
2329 /// Applies specified updates to finalized features. This operation is not transactional so some
2330 /// updates may succeed while the rest may fail.
2331 ///
2332 /// The API takes in a map of finalized feature names to `FeatureUpdate` that needs to be
2333 /// applied. Each entry in the map specifies the finalized feature to be added or updated or
2334 /// deleted, along with the new max feature version level value. This request is issued only to
2335 /// the controller since the API is only served by the controller. The return value contains an
2336 /// error code for each supplied `FeatureUpdate`, and the code indicates if the update succeeded
2337 /// or failed in the controller.
2338 ///
2339 /// - Downgrading a feature version level is not a common operation and should only be performed
2340 /// when necessary. It is permitted only if the `FeatureUpdate` specifies the `upgradeType` as
2341 /// either `UpgradeType::SAFE_DOWNGRADE` or `UpgradeType::UNSAFE_DOWNGRADE`.
2342 /// - `SAFE_DOWNGRADE`: Allows downgrades that do not lead to metadata loss.
2343 /// - `UNSAFE_DOWNGRADE`: Permits downgrades that might result in metadata loss.
2344 ///
2345 /// Note that even with these settings, certain downgrades may still be rejected by the
2346 /// controller if they are considered unsafe or impossible.
2347 ///
2348 /// - Deleting a finalized feature version is also not a common operation. To delete a feature,
2349 /// set the `maxVersionLevel` to zero and specify the `upgradeType` as either
2350 /// `UpgradeType::SAFE_DOWNGRADE` or `UpgradeType::UNSAFE_DOWNGRADE`.
2351 /// - The `UpgradeType::UPGRADE` type cannot be used when the `maxVersionLevel` is zero.
2352 /// Attempting to do so will result in an `Error::is_local_illegal_argument_error`.
2353 ///
2354 /// The following errors can be anticipated when calling `get()` on the futures obtained from
2355 /// the returned `UpdateFeaturesResult`:
2356 ///
2357 /// - `Error::is_cluster_authorization_error` If the authenticated user didn't have alter access
2358 /// to the cluster.
2359 /// - `Error::is_invalid_request_error` If the request details are invalid. e.g., a non-existing
2360 /// finalized feature is attempted to be deleted or downgraded.
2361 /// - `Error::is_timeout_error` If the request timed out before the updates could finish. It
2362 /// cannot be guaranteed whether the updates succeeded or not.
2363 /// - `Error::is_feature_update_failed_error` This means there was an unexpected error
2364 /// encountered when the update was applied on the controller. There is no guarantee on
2365 /// whether the update succeeded or failed. The best way to find out is to issue a
2366 /// `Admin::describe_features` request.
2367 ///
2368 /// This operation is supported by brokers with version 2.7.0 or higher.
2369 ///
2370 /// # Arguments
2371 ///
2372 /// - `feature_updates` - the map of finalized feature name to `FeatureUpdate`
2373 /// - `options` - the options to use
2374 ///
2375 /// # Returns
2376 ///
2377 /// the `UpdateFeaturesResult` containing the result
2378 ///
2379 /// # Errors
2380 ///
2381 /// - `Error::is_local_illegal_argument_error` if `feature_updates` is empty or any feature name
2382 /// is blank.
2383 ///
2384 /// # Translation notes
2385 ///
2386 /// Java throws that `IllegalArgumentException` from the call; it is returned here as an `Err`.
2387 #[doc(alias = "org.apache.kafka.clients.admin.Admin#updateFeatures")]
2388 fn update_features_with_options(
2389 &self,
2390 feature_updates: &HashMap<String, FeatureUpdate>,
2391 options: UpdateFeaturesOptions,
2392 ) -> Result<UpdateFeaturesResult, Error>;
2393
2394 /// Close the Admin and release all associated resources.
2395 ///
2396 /// See `Self::close_with_timeout`
2397 #[doc(alias = "org.apache.kafka.clients.admin.Admin#close")]
2398 async fn close(&self) {
2399 self.close_with_timeout(Duration::from_millis(i64::MAX as u64)).await
2400 }
2401
2402 /// Close the Admin client and release all associated resources.
2403 ///
2404 /// The close operation has a grace period during which current operations will be allowed to
2405 /// complete, specified by the given duration. New operations will not be accepted during the
2406 /// grace period. Once the grace period is over, all operations that have not yet been completed
2407 /// will be aborted with a `Error::is_timeout_error`.
2408 ///
2409 /// # Arguments
2410 ///
2411 /// - `timeout` - The time to use for the wait time.
2412 ///
2413 /// # Translation notes
2414 ///
2415 /// Returns once `timeout` has elapsed, as Java's timed `join` does; a background task still
2416 /// running then is left running.
2417 #[doc(alias = "org.apache.kafka.clients.admin.Admin#close")]
2418 async fn close_with_timeout(&self, timeout: Duration);
2419}
2420
2421#[cfg(test)]
2422mod tests {
2423 //! Coverage for the `Admin` trait's `default` bodies — the Rust
2424 //! translations of Java's `default` convenience overloads
2425 //! (`Admin.java`). Each test asserts a convenience form agrees with the
2426 //! form it forwards to, exactly as the Java one-line body does.
2427
2428 use std::collections::{HashMap, HashSet};
2429 use std::time::Duration;
2430
2431 use super::*;
2432 use crate::admin::MockAdminClient;
2433 use crate::admin::mock_admin_client;
2434 use crate::common::{Node, TopicPartition, TopicPartitionInfo};
2435
2436 fn admin() -> MockAdminClient {
2437 let mock = mock_admin_client::Builder::new()
2438 .build()
2439 .expect("a fresh builder has one broker");
2440 // The mock seeds brokers as `localhost:1000 + id`.
2441 let leader = Node::new(0, "localhost".to_string(), 1000);
2442 mock.add_topic(
2443 false,
2444 "topic",
2445 vec![TopicPartitionInfo::with_elr_last_known_elr(
2446 0,
2447 Some(leader.clone()),
2448 vec![leader.clone()],
2449 vec![leader],
2450 Vec::new(),
2451 Vec::new(),
2452 )],
2453 None,
2454 )
2455 .expect("the seeded broker is known");
2456 mock
2457 }
2458
2459 /// Representative of the 42 generated no-options forwards: the convenience
2460 /// form must behave as `create_topics_with_options(.., CreateTopicsOptions::default())`
2461 /// does, mirroring `Admin#createTopics(Collection)`.
2462 #[tokio::test]
2463 async fn create_topics_forwards_to_the_options_form() {
2464 let mock = admin();
2465 mock.create_topics(&[NewTopic::with_num_partitions_replication_factor(
2466 "created",
2467 Some(1),
2468 Some(1),
2469 )])
2470 .all()
2471 .get()
2472 .await
2473 .expect("the topic is created");
2474
2475 let via_options = admin();
2476 via_options
2477 .create_topics_with_options(
2478 &[NewTopic::with_num_partitions_replication_factor(
2479 "created",
2480 Some(1),
2481 Some(1),
2482 )],
2483 CreateTopicsOptions::default(),
2484 )
2485 .all()
2486 .get()
2487 .await
2488 .expect("the topic is created");
2489
2490 assert_eq!(
2491 mock.list_topics().names().get().await.unwrap(),
2492 via_options
2493 .list_topics_with_options(ListTopicsOptions::default())
2494 .names()
2495 .get()
2496 .await
2497 .unwrap()
2498 );
2499 }
2500
2501 /// `Admin.listTopics()` — the zero-argument shape of the same forward.
2502 #[tokio::test]
2503 async fn list_topics_forwards_to_the_options_form() {
2504 let mock = admin();
2505 assert_eq!(
2506 mock.list_topics().names().get().await.unwrap(),
2507 mock.list_topics_with_options(ListTopicsOptions::default())
2508 .names()
2509 .get()
2510 .await
2511 .unwrap()
2512 );
2513 assert_eq!(
2514 mock.list_topics().names().get().await.unwrap(),
2515 HashSet::from(["topic".to_string()])
2516 );
2517 }
2518
2519 /// `Admin.describeTopics(Collection<String>)` and
2520 /// `describeTopics(Collection<String>, DescribeTopicsOptions)` — the
2521 /// latter wraps the names in a `TopicCollection`, so both must agree with
2522 /// the `TopicCollection` form.
2523 #[tokio::test]
2524 async fn describe_topics_by_name_wraps_the_names_in_a_topic_collection() {
2525 let mock = admin();
2526 let names = ["topic".to_string()];
2527
2528 let expected = mock
2529 .describe_topics_with_topics(TopicCollection::of_topic_names(names.to_vec()))
2530 .all_topic_names()
2531 .expect("described by name")
2532 .get()
2533 .await
2534 .expect("the topic exists");
2535
2536 for described in [
2537 mock.describe_topics_with_topic_names(&names),
2538 mock.describe_topics_with_topic_names_options(&names, DescribeTopicsOptions::default()),
2539 ] {
2540 let actual = described
2541 .all_topic_names()
2542 .expect("described by name")
2543 .get()
2544 .await
2545 .expect("the topic exists");
2546 assert_eq!(actual, expected);
2547 }
2548 }
2549
2550 /// `Admin.deleteTopics(Collection<String>)` and
2551 /// `deleteTopics(Collection<String>, DeleteTopicsOptions)` wrap the
2552 /// names in a `TopicCollection`, so both return a name-keyed result and
2553 /// delete the named topics, as `deleteTopics(TopicCollection)` does.
2554 #[tokio::test]
2555 async fn delete_topics_by_name_wraps_the_names_in_a_topic_collection() {
2556 let names = ["topic".to_string()];
2557 for delete in [
2558 Admin::delete_topics_with_string_slice as fn(&MockAdminClient, &[String]) -> DeleteTopicsResult,
2559 |mock, names| mock.delete_topics_with_string_slice_options(names, DeleteTopicsOptions::default()),
2560 |mock, names| mock.delete_topics_with_topic_collection(TopicCollection::of_topic_names(names.to_vec())),
2561 ] {
2562 let mock = admin();
2563 let result = delete(&mock, &names);
2564 assert!(result.topic_id_values().is_none(), "the names are not ids");
2565 let values = result.topic_name_values().expect("deleted by name");
2566 assert_eq!(values.keys().collect::<HashSet<_>>(), HashSet::from([&names[0]]));
2567 result.all().get().await.expect("the topic exists");
2568 assert!(
2569 mock.list_topics().names().get().await.unwrap().is_empty(),
2570 "the named topic is deleted"
2571 );
2572 }
2573 }
2574
2575 /// `Admin.listConfigResources()` passes `Set.of()` — "every
2576 /// supported type" — not an empty result.
2577 #[tokio::test]
2578 async fn list_config_resources_asks_for_every_type() {
2579 let mock = admin();
2580 let mut convenience = mock.list_config_resources().all().get().await.unwrap();
2581 let mut explicit = mock
2582 .list_config_resources_with_options(&HashSet::new(), ListConfigResourcesOptions::default())
2583 .all()
2584 .get()
2585 .await
2586 .unwrap();
2587 convenience.sort_by_key(|resource| (resource.r#type() as i32, resource.name().to_string()));
2588 explicit.sort_by_key(|resource| (resource.r#type() as i32, resource.name().to_string()));
2589
2590 assert_eq!(convenience, explicit);
2591 assert!(
2592 convenience
2593 .iter()
2594 .any(|resource| resource.r#type() == config_resource::Type::Topic),
2595 "an empty type set must not mean an empty result: {convenience:?}"
2596 );
2597 }
2598
2599 /// `Admin.describeUserScramCredentials()` passes a `null` user list,
2600 /// which Rust spells as an empty slice; `(List)` passes the caller's list.
2601 /// The mock rejects both alike, so the
2602 /// assertion is on the error message the forward propagates.
2603 #[tokio::test]
2604 async fn describe_user_scram_credentials_forwards_both_shapes() {
2605 let mock = admin();
2606 for described in [
2607 mock.describe_user_scram_credentials(),
2608 mock.describe_user_scram_credentials_with_users(&["user".to_string()]),
2609 mock.describe_user_scram_credentials_with_users_options(
2610 &[],
2611 DescribeUserScramCredentialsOptions::default(),
2612 ),
2613 ] {
2614 let error = described.all().get().await.expect_err("the mock does not implement this");
2615 assert!(error.is_local_unsupported_operation_error(), "{error:?}");
2616 assert_eq!(error.message(), "Not implemented yet");
2617 }
2618 }
2619
2620 /// `Admin.listPartitionReassignments()`, `(Set)` and
2621 /// `(options)`. The last passes `Optional.empty()`, so it must agree
2622 /// with the no-argument form rather than with an empty partition set.
2623 #[tokio::test]
2624 async fn list_partition_reassignments_forwards_every_shape() {
2625 let mock = admin();
2626 let partition = TopicPartition::new("topic", 0);
2627
2628 let all = mock.list_partition_reassignments().reassignments().get().await.unwrap();
2629 let all_with_options = mock
2630 .list_partition_reassignments_with_options(ListPartitionReassignmentsOptions::default())
2631 .reassignments()
2632 .get()
2633 .await
2634 .unwrap();
2635 let selected = mock
2636 .list_partition_reassignments_with_partitions(HashSet::from([partition.clone()]))
2637 .reassignments()
2638 .get()
2639 .await
2640 .unwrap();
2641 let selected_with_options = mock
2642 .list_partition_reassignments_with_partitions_options(
2643 Some(HashSet::from([partition])),
2644 ListPartitionReassignmentsOptions::default(),
2645 )
2646 .reassignments()
2647 .get()
2648 .await
2649 .unwrap();
2650
2651 // `PartitionReassignment` has no `PartialEq` (Java's does not override
2652 // `equals`), so the maps are compared by their replica lists.
2653 let view = |reassignments: &HashMap<TopicPartition, PartitionReassignment>| {
2654 reassignments
2655 .iter()
2656 .map(|(partition, r)| {
2657 let lists = (
2658 r.replicas().to_vec(),
2659 r.adding_replicas().to_vec(),
2660 r.removing_replicas().to_vec(),
2661 );
2662 (partition.clone(), lists)
2663 })
2664 .collect::<HashMap<_, _>>()
2665 };
2666 assert_eq!(view(&all), view(&all_with_options));
2667 assert_eq!(view(&selected), view(&selected_with_options));
2668 // Nothing is reassigning in a freshly seeded mock, so both are empty —
2669 // what matters is that `(options)` took the `None` branch, i.e. did not
2670 // request the empty *set*, which the mock would answer identically here
2671 // but which diverges as soon as a reassignment exists.
2672 assert!(all.is_empty());
2673 }
2674
2675 /// `Admin.listConsumerGroupOffsets(String)` and
2676 /// `(String, options)` — the latter builds a singleton map with a
2677 /// default `ListConsumerGroupOffsetsSpec`, i.e. "all partitions".
2678 #[tokio::test]
2679 async fn list_consumer_group_offsets_by_group_id_builds_a_singleton_spec() {
2680 let mock = admin();
2681 let partition = TopicPartition::new("topic", 0);
2682 mock.update_consumer_group_offsets(HashMap::from([(partition.clone(), 17)]));
2683
2684 let expected = mock
2685 .list_consumer_group_offsets_with_group_specs(&HashMap::from([(
2686 "group".to_string(),
2687 ListConsumerGroupOffsetsSpec::new(),
2688 )]))
2689 .partitions_to_offset_and_metadata()
2690 .expect("exactly one group")
2691 .get()
2692 .await
2693 .expect("offsets");
2694
2695 for listed in [
2696 mock.list_consumer_group_offsets_with_group_id("group"),
2697 mock.list_consumer_group_offsets_with_group_id_options("group", ListConsumerGroupOffsetsOptions::default()),
2698 ] {
2699 let actual = listed
2700 .partitions_to_offset_and_metadata()
2701 .expect("exactly one group")
2702 .get()
2703 .await
2704 .expect("offsets");
2705 assert_eq!(actual, expected);
2706 assert_eq!(actual[&partition].as_ref().expect("committed").offset(), 17);
2707 }
2708 }
2709
2710 /// `Admin.close()` waits `Long.MAX_VALUE` milliseconds; the forward
2711 /// must not overflow the `Duration` conversion.
2712 #[tokio::test]
2713 async fn close_forwards_to_the_timeout_form() {
2714 admin().close().await;
2715 admin().close_with_timeout(Duration::from_millis(i64::MAX as u64)).await;
2716 }
2717}