Skip to main content

confluent_kafka/admin/
kafka_admin_client.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//! The network-backed administrative client.
16//!
17//! Translated from `org.apache.kafka.clients.admin.KafkaAdminClient`. Per
18//! `.claude/rules/admin-client.md` §1 the RPC methods are plain sync `fn`s that
19//! enqueue a [`Call`] onto the single background task
20//! ([`AdminClientRunnable`]) and return a `*Result` holding per-key
21//! [`KafkaFuture`]s; only [`close`](KafkaAdminClient::close) is `async`.
22//!
23//! # `describeTopics`
24//!
25//! By **name**, topics are described as Java describes them: a
26//! `describeCluster` call for the node map, then the paginated KIP-966
27//! `describeTopicPartitions` call, which follows each response's `NextCursor`,
28//! honours `DescribeTopicsOptions::partition_size_limit_per_response`, and
29//! falls back to the Metadata API (`describeTopics`,
30//! `generateDescribeTopicsCallWithMetadataApi`) on `UnsupportedVersionException`.
31//! By **id** Java uses the Metadata API only (`handleDescribeTopicsByIds`), and
32//! so does this port.
33//!
34//! A client configured with `bootstrap.controllers` (KIP-919) talks to the
35//! controller quorum: it refreshes its metadata with `DescribeCluster` for the
36//! CONTROLLER endpoint instead of the `Metadata` API, and fails at once every
37//! call whose node provider cannot reach a controller, with an
38//! [`UnsupportedEndpointTypeError`](crate::common::errors::UnsupportedEndpointTypeError).
39
40use crate::admin::CreateTopicsResult;
41use crate::admin::EndpointType;
42use crate::common::requests::MetadataResponse;
43use crate::{kafka_debug, kafka_error, kafka_warn};
44use std::collections::HashMap;
45use std::sync::{Arc, Mutex};
46use std::time::Duration;
47
48use async_trait::async_trait;
49use tokio::sync::Notify;
50use tokio::sync::mpsc;
51use tokio::task::JoinHandle;
52
53use crate::AlterReplicaLogDirsRequestData;
54use crate::AlterUserScramCredentialsRequestData;
55use crate::ApiVersions;
56use crate::ClientUtils;
57use crate::CreateAclsRequestData;
58use crate::CreatePartitionsRequestData;
59use crate::CreateTopicsRequestData;
60use crate::DefaultHostResolver;
61use crate::DeleteAclsRequestData;
62use crate::DeleteTopicsRequestData;
63use crate::DescribeClusterRequestData;
64use crate::DescribeClusterResponseData;
65use crate::DescribeConfigsRequestData;
66use crate::DescribeLogDirsRequestData;
67use crate::DescribeTopicPartitionsRequestData;
68use crate::DescribeUserScramCredentialsRequestData;
69use crate::DescribeUserScramCredentialsResponseData;
70use crate::HostResolver;
71use crate::IncrementalAlterConfigsRequestData;
72use crate::KafkaClient;
73use crate::ListConfigResourcesRequestData;
74use crate::ListGroupsRequestData;
75use crate::MetadataUpdater;
76use crate::NetworkClient;
77use crate::admin::ConfigEntryOptionsBuilder;
78use crate::admin::config_entry::{ConfigSource, ConfigSynonym, ConfigType};
79use crate::alter_replica_log_dirs_request_data::{AlterReplicaLogDir, AlterReplicaLogDirTopic};
80use crate::alter_user_scram_credentials_request_data::{ScramCredentialDeletion, ScramCredentialUpsertion};
81use crate::common::acl::{AclBinding, AclBindingFilter, AclOperation};
82use crate::common::config::{ConfigResource, config_resource};
83use crate::common::errors::ApiError;
84use crate::common::errors::MismatchedEndpointTypeError;
85use crate::common::internals::KafkaFutureImpl;
86use crate::common::network::ChannelBuilders;
87use crate::common::network::Selectable;
88use crate::common::network::Selector;
89use crate::common::protocol::Errors;
90use crate::common::quota::{ClientQuotaAlteration, ClientQuotaEntity, ClientQuotaFilter};
91use crate::common::requests::{
92    ConcreteResponse, CreateAclsRequest, DeleteAclsRequest, DeleteAclsResponse, DescribeAclsResponse,
93    DescribeLogDirsResponse, DescribeTopicPartitionsResponse, RequestBuilder, alter_client_quotas_request,
94    alter_replica_log_dirs_request, alter_user_scram_credentials_request, create_acls_request,
95    create_delegation_token_request, create_partitions_request, create_topics_request, delete_acls_request,
96    delete_topics_request, describe_acls_request, describe_client_quotas_request, describe_cluster_request,
97    describe_configs_request, describe_delegation_token_request, describe_log_dirs_request,
98    describe_topic_partitions_request, describe_user_scram_credentials_request, expire_delegation_token_request,
99    incremental_alter_configs_request, list_config_resources_request, list_groups_request, metadata_request,
100    renew_delegation_token_request,
101};
102use crate::common::security::auth::KafkaPrincipal;
103#[cfg(feature = "aws-lc-rs")]
104use crate::common::security::scram::internals::ScramFormatter;
105use crate::common::security::scram::internals::ScramMechanism as InternalScramMechanism;
106use crate::common::security::token::delegation::{DelegationToken, TokenInformation};
107use crate::common::utils::{
108    SystemTime, Time,
109    internals::{ExponentialBackoff, LogContext},
110};
111use crate::common::{
112    Cluster, Error, GroupState, GroupType, KafkaFuture, TopicCollection, TopicPartition, TopicPartitionInfo, Uuid,
113};
114use crate::consumer::OffsetAndMetadata;
115use crate::create_acls_request_data::AclCreation;
116use crate::create_partitions_request_data::{CreatePartitionsAssignment, CreatePartitionsTopic};
117use crate::create_topics_request_data::CreatableTopic;
118use crate::delete_acls_request_data::DeleteAclsFilter;
119use crate::delete_topics_request_data::DeleteTopicState;
120use crate::describe_configs_request_data::DescribeConfigsResource;
121use crate::describe_log_dirs_request_data::DescribableLogDirTopic;
122use crate::describe_topic_partitions_request_data::{Cursor as DescribeTopicPartitionsCursor, TopicRequest};
123use crate::describe_topic_partitions_response_data::DescribeTopicPartitionsResponseTopic;
124use crate::describe_user_scram_credentials_request_data::UserName;
125use crate::incremental_alter_configs_request_data::{AlterConfigsResource, AlterableConfig};
126
127use super::RecordsToDelete;
128use super::internals::AbortTransactionHandler;
129use super::internals::AdminApiFuture;
130use super::internals::AdminMetadataManager;
131use super::internals::AdminUtils;
132use super::internals::AlterConsumerGroupOffsetsHandler;
133use super::internals::CoordinatorKey;
134use super::internals::DeleteConsumerGroupOffsetsHandler;
135use super::internals::DeleteConsumerGroupsHandler;
136use super::internals::DeleteGroupsHandler;
137use super::internals::DeleteRecordsHandler;
138use super::internals::DescribeClassicGroupsHandler;
139use super::internals::DescribeConsumerGroupsHandler;
140use super::internals::DescribeProducersHandler;
141use super::internals::DescribeTransactionsHandler;
142use super::internals::FenceProducersHandler;
143use super::internals::InternalDescribeFeaturesResult;
144use super::internals::ListConsumerGroupOffsetsHandler;
145use super::internals::ListOffsetsHandler;
146use super::internals::ListTransactionsHandler;
147use super::internals::PartitionLeaderCache;
148use super::internals::RemoveMembersFromConsumerGroupHandler;
149use super::internals::{AdminApiDriver, RequestSpec};
150use super::internals::{AdminClientRunnable, ShutdownSignal};
151use super::internals::{Call, HandleResult, MaybeRetryOutcome, NodeProvider};
152use super::{
153    AbortTransactionOptions, AbortTransactionResult, AbortTransactionSpec, DescribeProducersOptions,
154    DescribeProducersResult, DescribeTransactionsOptions, DescribeTransactionsResult, FenceProducersOptions,
155    FenceProducersResult, ListTransactionsOptions, ListTransactionsResult, TerminateTransactionOptions,
156    TerminateTransactionResult,
157};
158use super::{
159    Admin, AdminClientConfig, AlterClientQuotasOptions, AlterClientQuotasResult, AlterConfigOp, AlterConfigsOptions,
160    AlterConfigsResult, AlterConsumerGroupOffsetsOptions, AlterConsumerGroupOffsetsResult,
161    AlterPartitionReassignmentsOptions, AlterPartitionReassignmentsResult, AlterReplicaLogDirsOptions,
162    AlterReplicaLogDirsResult, Config, ConfigEntry, CreateAclsOptions, CreateAclsResult, CreateDelegationTokenOptions,
163    CreateDelegationTokenResult, CreatePartitionsOptions, CreatePartitionsResult, CreateTopicsOptions,
164    DeleteAclsOptions, DeleteAclsResult, DeleteConsumerGroupOffsetsOptions, DeleteConsumerGroupOffsetsResult,
165    DeleteConsumerGroupsOptions, DeleteConsumerGroupsResult, DeleteRecordsOptions, DeleteRecordsResult,
166    DeleteTopicsOptions, DeleteTopicsResult, DescribeAclsOptions, DescribeAclsResult, DescribeClassicGroupsOptions,
167    DescribeClassicGroupsResult, DescribeClientQuotasOptions, DescribeClientQuotasResult, DescribeClusterOptions,
168    DescribeClusterResult, DescribeConfigsOptions, DescribeConfigsResult, DescribeConsumerGroupsOptions,
169    DescribeConsumerGroupsResult, DescribeDelegationTokenOptions, DescribeDelegationTokenResult,
170    DescribeLogDirsOptions, DescribeLogDirsResult, DescribeReplicaLogDirsOptions, DescribeReplicaLogDirsResult,
171    DescribeTopicsOptions, DescribeTopicsResult, ElectLeadersOptions, ElectLeadersResult, ExpireDelegationTokenOptions,
172    ExpireDelegationTokenResult, FilterResult, FilterResults, GroupListing, ListConfigResourcesOptions,
173    ListConfigResourcesResult, ListConsumerGroupOffsetsOptions, ListConsumerGroupOffsetsResult,
174    ListConsumerGroupOffsetsSpec, ListGroupsOptions, ListGroupsResult, ListOffsetsOptions, ListOffsetsResult,
175    ListPartitionReassignmentsOptions, ListPartitionReassignmentsResult, ListTopicsOptions, ListTopicsResult,
176    LogDirDescription, NewPartitionReassignment, NewPartitions, NewTopic, OffsetSpec, PartitionReassignment,
177    RemoveMembersFromConsumerGroupOptions, RemoveMembersFromConsumerGroupResult, RenewDelegationTokenOptions,
178    RenewDelegationTokenResult, ReplicaInfo, ReplicaLogDirInfo, TopicDescription, TopicListing, TopicMetadataAndConfig,
179};
180use super::{
181    AlterUserScramCredentialsOptions, AlterUserScramCredentialsResult, DescribeUserScramCredentialsOptions,
182    DescribeUserScramCredentialsResult, ScramMechanism, UserScramCredentialAlteration, UserScramCredentialDeletion,
183    UserScramCredentialUpsertion,
184};
185use super::{
186    DescribeFeaturesOptions, DescribeFeaturesResult, FeatureMetadata, FeatureUpdate, FinalizedVersionRange,
187    SupportedVersionRange, UnregisterControllerOptions, UnregisterControllerResult, UpdateFeaturesOptions,
188    UpdateFeaturesResult,
189};
190use crate::AlterPartitionReassignmentsRequestData;
191use crate::ApiVersionsResponseData;
192use crate::CreateDelegationTokenRequestData;
193use crate::ExpireDelegationTokenRequestData;
194use crate::ListPartitionReassignmentsRequestData;
195use crate::NodeApiVersions;
196use crate::RenewDelegationTokenRequestData;
197use crate::UnregisterControllerRequestData;
198use crate::UpdateFeaturesRequestData;
199use crate::alter_partition_reassignments_request_data::{ReassignablePartition, ReassignableTopic};
200use crate::common::TopicPartitionReplica;
201use crate::common::requests::{
202    ElectLeadersResponse, JoinGroupRequest, alter_partition_reassignments_request, api_versions_request,
203    elect_leaders_request, list_partition_reassignments_request, unregister_controller_request,
204    update_features_request,
205};
206use crate::common::{ElectionType, Node};
207use crate::create_delegation_token_request_data::CreatableRenewers;
208use crate::leave_group_request_data::MemberIdentity;
209use crate::list_partition_reassignments_request_data::ListPartitionReassignmentsTopics;
210use crate::update_features_request_data::FeatureUpdateKey;
211use std::collections::{BTreeSet, HashSet};
212use std::sync::atomic::{self, AtomicI32};
213
214/// The default reason sent in a `LeaveGroup` request when an admin removes a
215/// member without providing one. Mirrors
216/// `KafkaAdminClient.DEFAULT_LEAVE_GROUP_REASON`.
217const DEFAULT_LEAVE_GROUP_REASON: &str = "member was removed by an admin";
218
219/// Process-wide counter for deriving a default `client.id`.
220///
221/// Corresponds to Java's `static AtomicInteger`
222/// `KafkaAdminClient#ADMIN_CLIENT_ID_SEQUENCE`, which starts at 1. Crate-level
223/// (not per-instance) to match Java's static scope, so successive admin clients
224/// in one process get distinct ids.
225static ADMIN_CLIENT_ID_SEQUENCE: AtomicI32 = AtomicI32::new(1);
226
227/// The `RETRY_BACKOFF_EXP_BASE` used by the admin retry backoff (Java constant).
228const RETRY_BACKOFF_EXP_BASE: i32 = 2;
229/// The `RETRY_BACKOFF_JITTER` used by the admin retry backoff (Java constant).
230const RETRY_BACKOFF_JITTER: f64 = 0.2;
231
232/// Upper bound on `close`'s wait, mirroring
233/// `Math.min(TimeUnit.DAYS.toMillis(365), waitTimeMs)` in
234/// `KafkaAdminClient.close(Duration)` ("Limit the timeout to a year").
235const MAX_CLOSE_WAIT_TIME_MS: i64 = 365 * 24 * 60 * 60 * 1000;
236
237/// State shared between the `KafkaAdminClient` handle and (indirectly) the
238/// background task.
239struct Shared {
240    client_id: String,
241    default_api_timeout_ms: i32,
242    /// The `request.timeout.ms` config, used as the default transaction timeout
243    /// for `fenceProducers` (mirrors `KafkaAdminClient.requestTimeoutMs`).
244    request_timeout_ms: i32,
245    /// Every enqueue path goes through it (Java's `runnable.call`).
246    call_sender: CallSender,
247    wakeup: Arc<Notify>,
248    shutdown: Arc<ShutdownSignal>,
249    metadata_manager: AdminMetadataManager,
250    time: Arc<dyn Time>,
251    bg_handle: Mutex<Option<JoinHandle<()>>>,
252    /// Retry-backoff parameters for the `AdminApiDriver` (mirrors the fields
253    /// passed to the driver in `invokeDriver`).
254    retry_backoff_ms: i64,
255    retry_backoff_max_ms: i64,
256    /// Cache of partition-to-leader mappings shared across driver-backed calls
257    /// (`deleteRecords`), mirroring `KafkaAdminClient.partitionLeaderCache`.
258    partition_leader_cache: Arc<PartitionLeaderCache>,
259    /// Prefix for log lines emitted on the application side (`close`), mirroring
260    /// `KafkaAdminClient.logContext`.
261    log_context: LogContext,
262}
263
264/// The default implementation of [`Admin`](crate::admin::Admin). An instance of this class is
265/// created by invoking [`AdminClient::create`](crate::admin::AdminClient::create).
266/// Users should not refer to this class directly.
267///
268/// This class is thread-safe.
269#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient")]
270pub struct KafkaAdminClient {
271    shared: Arc<Shared>,
272}
273
274impl std::fmt::Debug for KafkaAdminClient {
275    // The client id only, never the configuration.
276    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
277        f.debug_struct("KafkaAdminClient")
278            .field("client_id", &self.shared.client_id)
279            .finish_non_exhaustive()
280    }
281}
282
283impl KafkaAdminClient {
284    /// `KafkaAdminClient.describeFeatures(DescribeFeaturesOptions)` with its
285    /// concrete return type, `InternalDescribeFeaturesResult` (KAFKA-19663),
286    /// which also carries the answering node's API versions. Java's internal
287    /// tools reach it by casting the `Admin.describeFeatures` result; Rust has
288    /// no downcast, so the crate calls this instead. (A Rust-only accessor: the
289    /// Java method's marker stays on the trait method.)
290    pub(crate) fn describe_features_internal(
291        &self,
292        options: DescribeFeaturesOptions,
293    ) -> InternalDescribeFeaturesResult {
294        let handle: KafkaFutureImpl<FeatureMetadata> = KafkaFutureImpl::new();
295        let public = handle.future();
296        let node_api_versions_handle: KafkaFutureImpl<NodeApiVersions> = KafkaFutureImpl::new();
297        let node_api_versions_public = node_api_versions_handle.future();
298        let now = self.now();
299        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
300
301        // Mirrors `KafkaAdminClient#describeFeatures`: a set nodeId routes to
302        // that specific node via
303        // `new ConstantNodeIdProvider(options.nodeId().getAsInt(), true)`, a broker or, for a
304        // `bootstrap.controllers` client, a controller; otherwise the request
305        // goes to an arbitrary broker or the active controller.
306        let node_provider = match options.node_id() {
307            Some(node_id) => NodeProvider::ConstantNodeId { node_id, supports_use_controllers: true },
308            None => NodeProvider::LeastLoadedBrokerOrActiveKController,
309        };
310
311        let create_request = Box::new(move |_timeout_ms: i32| {
312            Ok(Box::new(api_versions_request::Builder::new()) as Box<dyn RequestBuilder>)
313        });
314
315        let resp_handle = handle.clone();
316        let resp_versions_handle = node_api_versions_handle.clone();
317        let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
318            let ConcreteResponse::ApiVersions(api_versions) = response else {
319                return HandleResult::Retry(Error::local_illegal_state("Expected an ApiVersions response"));
320            };
321            let data = api_versions.data();
322            if data.error_code == Errors::None.code() {
323                // An invalid range throws from `createFeatureMetadata` before either
324                // future completes; the throw escapes `handleResponse` into
325                // `Call.fail`, whose `handleFailure` fails both futures. `Retry`
326                // is the crate's translation of that escape.
327                match create_feature_metadata(data) {
328                    Ok(metadata) => {
329                        resp_handle.complete(metadata);
330                        resp_versions_handle.complete(create_node_api_version(data));
331                    },
332                    Err(e) => return HandleResult::Retry(e),
333                };
334            } else {
335                // One exception completes both futures, as Java's does.
336                let error = Error::new(Errors::for_code(data.error_code));
337                resp_handle.complete_with_error(error.clone());
338                resp_versions_handle.complete_with_error(error);
339            }
340            HandleResult::Done
341        });
342
343        // 58f63f448e: a failed call (e.g. a timeout) completes the
344        // `nodeApiVersions` future too, or a caller waiting on it would hang.
345        let fail_handle = handle.clone();
346        let fail_versions_handle = node_api_versions_handle;
347        let handle_failure = Box::new(move |error: &Error| {
348            fail_handle.complete_with_error(error.clone());
349            fail_versions_handle.complete_with_error(error.clone());
350        });
351
352        let call = Call::new(
353            "describeFeatures",
354            deadline,
355            node_provider,
356            create_request,
357            handle_response,
358            handle_failure,
359            Box::new(|_| false),
360        );
361        self.submit(call);
362        InternalDescribeFeaturesResult::new(public, node_api_versions_public)
363    }
364
365    /// Returns the response error message with a fallback to the error code's
366    /// default message. Mirrors Java's `ApiError.messageWithFallback`.
367    pub(crate) fn message_with_fallback(code: i16, message: &Option<String>) -> String {
368        // Java `ApiError.messageWithFallback()` falls back to the code's default text
369        // ONLY when the broker sent no message (null); a non-null empty message is
370        // returned verbatim.
371        match message {
372            Some(m) => m.clone(),
373            None => Errors::for_code(code).message().to_string(),
374        }
375    }
376
377    /// Sentinel for "no hard-shutdown deadline set".
378    ///
379    /// Translates Java's `KafkaAdminClient#INVALID_SHUTDOWN_TIME`: it is lower
380    /// than every reachable deadline, so the "is an earlier deadline already
381    /// installed?" comparison in [`close`](Self::close) orders the same way.
382    pub(crate) const NO_HARD_SHUTDOWN: i64 = i64::MIN;
383
384    /// Creates a network-backed admin client from configuration, spawning the
385    /// background I/O task.
386    ///
387    /// Mirrors `KafkaAdminClient.createInternal`. Selects the channel builder
388    /// from `security.protocol` + `ssl.*` / `sasl.*` (PLAINTEXT / SSL /
389    /// SASL_PLAINTEXT / SASL_SSL); SASL mechanism PLAIN only, any other one
390    /// being rejected when the `AdminClientConfig` is built.
391    ///
392    /// # Errors
393    ///
394    /// Returns a Kafka error, `Failed to create new KafkaAdminClient`, whose
395    /// source is the failure: neither or both of `bootstrap.servers` and
396    /// `bootstrap.controllers` are set
397    /// ([`determine_bootstrap_type`](Self::determine_bootstrap_type)), the
398    /// bootstrap addresses cannot be resolved, the channel builder cannot be
399    /// created, or `default.api.timeout.ms` is set explicitly below
400    /// `request.timeout.ms`
401    /// ([`configure_default_api_timeout_ms`](Self::configure_default_api_timeout_ms)).
402    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#KafkaAdminClient")]
403    pub(crate) fn new(config: AdminClientConfig) -> Result<Self, Error> {
404        // Java wraps the whole constructor in `catch (Throwable exc)` and relabels
405        // every failure, in both overloads of
406        // `org.apache.kafka.clients.admin.KafkaAdminClient#createInternal`:
407        //
408        //     throw new KafkaException("Failed to create new KafkaAdminClient", exc);
409        //
410        // so a caller has one class and one message to guard construction with.
411        // Without it the three failure points surfaced in three different shapes,
412        // none of them Java's.
413        //
414        // The `closeQuietly(metrics, ..)` / `closeQuietly(networkClient, ..)` half of
415        // Java's catch is not needed here: the `Selector` / `NetworkClient` are
416        // RVO'd locals, so a failure after they are built (the bootstrap
417        // configuration, or `configure_default_api_timeout_ms` in `build`) just
418        // drops them. Nothing has connected by then, so there is nothing else to
419        // release.
420        Self::new_inner(config).map_err(|e| Error::kafka_message_source("Failed to create new KafkaAdminClient", e))
421    }
422
423    /// Returns the configured `client.id`, or generates `adminclient-<n>` when
424    /// it is empty.
425    ///
426    /// Translated from `KafkaAdminClient#generateClientId`; `<n>` comes from
427    /// the process-wide [`ADMIN_CLIENT_ID_SEQUENCE`], starting at 1.
428    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#generateClientId")]
429    pub(crate) fn generate_client_id(config: &AdminClientConfig) -> String {
430        let client_id = config.client_id();
431        if !client_id.is_empty() {
432            return client_id.to_string();
433        }
434        format!(
435            "adminclient-{}",
436            ADMIN_CLIENT_ID_SEQUENCE.fetch_add(1, atomic::Ordering::Relaxed)
437        )
438    }
439
440    fn new_inner(config: AdminClientConfig) -> Result<Self, Error> {
441        // `org.apache.kafka.clients.admin.Admin#create(Properties)` builds the
442        // configuration with `doLog = true`, which logs every value; a Rust
443        // caller builds the `AdminClientConfig` itself, so the client logs them
444        // here.
445        config.log_values();
446        let client_id = Self::generate_client_id(&config);
447        let log_context = LogContext::new(format!("[AdminClient clientId={client_id}] "));
448
449        // `boolean usingBootstrapControllers = determineBootstrapType(config)`,
450        // the first step inside the `try` of
451        // `org.apache.kafka.clients.admin.KafkaAdminClient#createInternal`, so its
452        // `ConfigException` reaches the caller wrapped by `new`, in both
453        // resolution modes: it runs before the `bootstrap.resolve.timeout.ms`
454        // branch.
455        let using_bootstrap_controllers = Self::determine_bootstrap_type(&config)?;
456
457        // Java's `Time.SYSTEM`.
458        let time: Arc<dyn Time> = Arc::new(SystemTime);
459
460        let metadata_manager = AdminMetadataManager::new(
461            config.retry_backoff_ms(),
462            config.metadata_max_age_ms(),
463            using_bootstrap_controllers,
464            log_context.clone(),
465        );
466
467        // Get the appropriate bootstrap configuration: Java's
468        // `bootstrapAddressesToUse` in `KafkaAdminClient#createInternal`, used both
469        // for the synchronous DNS resolution below and for the `NetworkClient`'s
470        // bootstrap configuration, which also drives its rebootstrap.
471        let bootstrap: &[String] = if using_bootstrap_controllers {
472            config.bootstrap_controllers()
473        } else {
474            config.bootstrap_servers()
475        };
476        // bootstrap.resolve.timeout.ms=0 resolves DNS synchronously here and primes the
477        // metadata manager, so any DNS failure surfaces as a ConfigException and no admin
478        // client instance is created. A positive value opts in to asynchronous bootstrap
479        // resolution, where resolution is deferred to the first poll.
480        if config.bootstrap_resolve_timeout_ms() == 0 {
481            let addresses = ClientUtils::parse_and_validate_addresses(bootstrap, config.client_dns_lookup())?;
482            metadata_manager.update(Cluster::bootstrap(&addresses), time.milliseconds());
483        }
484        // Otherwise, let NetworkClient::ensure_bootstrapped() handle it during the first poll
485        // after DNS resolution succeeds.
486
487        // Selects the channel builder from `security.protocol` + `ssl.*` /
488        // `sasl.*` (PLAINTEXT / SSL / SASL_PLAINTEXT / SASL_SSL); SASL mechanism
489        // PLAIN only (`AdminClientConfig` rejected any other one). Mirrors `ClientUtils.createChannelBuilder(config, time,
490        // logContext)` as used by `KafkaAdminClient.createInternal`.
491        let channel_builder = ChannelBuilders::client_channel_builder(
492            config.security_protocol(),
493            Some(config.ssl_config()),
494            Some(config.sasl_config()),
495            None,
496            &client_id,
497            log_context.clone(),
498        )
499        // `ConfigException` in Java
500        // (`org.apache.kafka.common.security.ssl.SslFactory#configure`), i.e.
501        // inside the `KafkaException` hierarchy; `illegal_argument` put it
502        // outside, where `is_kafka_error()` answers `false`. Same fix as
503        // `KafkaProducer::new`.
504        .map_err(|e| Error::config_message(format!("Failed to create channel builder: {e}")))?;
505        let mut selector = Selector::with_defaults_and_log_context(
506            config.connections_max_idle_ms(),
507            channel_builder,
508            log_context.clone(),
509        );
510        selector.set_time(Arc::clone(&time));
511        let api_versions = Arc::new(ApiVersions::new());
512
513        let mut client = Self::create_network_client(
514            &config,
515            selector,
516            metadata_manager.updater(),
517            &client_id,
518            api_versions,
519            DefaultHostResolver::new(),
520            log_context.clone(),
521        );
522        client.set_time(Arc::clone(&time));
523        // `org.apache.kafka.clients.ClientUtils#createNetworkClient` passes
524        // `metadata.cluster.check.enable` to the `NetworkClient` constructor
525        // (KIP-1242). It has no effect here, as in Java: see
526        // `AdminClientConfig::metadata_cluster_check_enable`.
527        client.set_metadata_cluster_check_enable(config.metadata_cluster_check_enable());
528        // `ClientUtils.createNetworkClient` passes
529        // `bootstrapConfiguration(config, bootstrapAddressesToUse)` to the
530        // `NetworkClient` constructor.
531        client.set_bootstrap_configuration(ClientUtils::bootstrap_configuration(
532            config.bootstrap_resolve_timeout_ms(),
533            config.client_dns_lookup(),
534            config.retry_backoff_ms(),
535            bootstrap,
536        )?);
537
538        let (admin, runnable) = Self::build(client, metadata_manager, &config, client_id, time, log_context)?;
539        // Java's constructor reads its settings through the config's getters,
540        // then logs what it did not read
541        // (`org.apache.kafka.clients.admin.KafkaAdminClient#KafkaAdminClient`).
542        config.mark_read_keys_used();
543        config.log_unused();
544        admin.spawn(runnable);
545        Ok(admin)
546    }
547
548    /// Builds the admin `NetworkClient` with the arguments
549    /// `KafkaAdminClient#createInternal` passes to
550    /// `org.apache.kafka.clients.ClientUtils#createNetworkClient`, the overload
551    /// taking a `MetadataUpdater`: the socket buffers,
552    /// `metadata.recovery.strategy` and
553    /// `metadata.recovery.rebootstrap.trigger.ms` come from the config.
554    ///
555    /// `maxInFlightRequestsPerConnection` is `1`. The admin loop sends at
556    /// most one call per node and checks `client.ready(..)` first, so the limit
557    /// does not change what is sent; it matters to `least_loaded_node` and
558    /// `ready`, which treat a node with an in-flight request as busy only when the
559    /// connection cannot take another one.
560    ///
561    /// The `NetworkClient`'s default request timeout is one hour,
562    /// `(int) TimeUnit.HOURS.toMillis(1)`, not `request.timeout.ms`.
563    /// Every admin call is sent with its own timeout, `min(request.timeout.ms,
564    /// time left to the call deadline)` (`sendEligibleCalls`), so the default
565    /// bounds only what the `NetworkClient` sends on its own, the `ApiVersions`
566    /// handshake, and caps its `poll` timeout. A broker that takes longer than
567    /// `request.timeout.ms` to answer the handshake is therefore waited for, not
568    /// disconnected; the admin loop still bounds each call by its deadline and
569    /// each node assignment by `request.timeout.ms` (`nodeReadyDeadlines`).
570    pub(crate) fn create_network_client<S: Selectable, H: HostResolver>(
571        config: &AdminClientConfig,
572        selector: S,
573        metadata_updater: Box<dyn MetadataUpdater>,
574        client_id: &str,
575        api_versions: Arc<ApiVersions>,
576        host_resolver: H,
577        log_context: LogContext,
578    ) -> NetworkClient<S, H> {
579        NetworkClient::with_metadata_updater_rebootstrap_trigger_ms(
580            selector,
581            metadata_updater,
582            client_id,
583            1, // maxInFlightRequestsPerConnection in `KafkaAdminClient#createInternal`
584            config.reconnect_backoff_ms(),
585            config.reconnect_backoff_max_ms(),
586            config.send_buffer_bytes(),
587            config.receive_buffer_bytes(),
588            3_600_000, // defaultRequestTimeoutMs: `(int) TimeUnit.HOURS.toMillis(1)`, as above
589            config.socket_connection_setup_timeout_ms(),
590            config.socket_connection_setup_timeout_max_ms(),
591            true, // discover_broker_versions
592            api_versions,
593            host_resolver,
594            config.metadata_recovery_rebootstrap_trigger_ms(),
595            config.metadata_recovery_strategy(),
596            log_context,
597        )
598    }
599
600    /// Determines which bootstrap configuration to use based on the provided
601    /// config. Validates that exactly one of `bootstrap.servers` or
602    /// `bootstrap.controllers` is configured.
603    ///
604    /// Returns `true` if using `bootstrap.controllers`, `false` if using
605    /// `bootstrap.servers`.
606    ///
607    /// Translated from `KafkaAdminClient#determineBootstrapType`. An unset list
608    /// reads as empty, as Java's `null` does.
609    ///
610    /// # Errors
611    ///
612    /// [`Error::Config`] if both or neither bootstrap configurations are set.
613    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#determineBootstrapType")]
614    fn determine_bootstrap_type(config: &AdminClientConfig) -> Result<bool, Error> {
615        let bootstrap_servers = config.bootstrap_servers();
616        let controller_servers = config.bootstrap_controllers();
617        if bootstrap_servers.is_empty() {
618            if controller_servers.is_empty() {
619                Err(Error::config_message(format!(
620                    "You must set either {} or {}",
621                    AdminClientConfig::BOOTSTRAP_SERVERS_CONFIG,
622                    AdminClientConfig::BOOTSTRAP_CONTROLLERS_CONFIG
623                )))
624            } else {
625                Ok(true) // Using bootstrap.controllers
626            }
627        } else if controller_servers.is_empty() {
628            Ok(false) // Using bootstrap.servers
629        } else {
630            Err(Error::config_message(format!(
631                "You cannot set both {} and {}",
632                AdminClientConfig::BOOTSTRAP_SERVERS_CONFIG,
633                AdminClientConfig::BOOTSTRAP_CONTROLLERS_CONFIG
634            )))
635        }
636    }
637
638    /// Builds the [`Cluster`] that a `DescribeCluster` response from the
639    /// CONTROLLER endpoint describes (KIP-919): the controllers as its nodes,
640    /// and the active controller as its controller (none when the response's
641    /// controller id names none of them).
642    ///
643    /// Translated from `KafkaAdminClient#parseDescribeClusterResponse`, which
644    /// the metadata refresh of a `bootstrap.controllers` client calls.
645    ///
646    /// # Errors
647    ///
648    /// The response's error, as `ApiError.exception()` builds it, when the
649    /// response carries one; otherwise a
650    /// [`MismatchedEndpointTypeError`] when the response comes from an endpoint
651    /// other than CONTROLLER.
652    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#parseDescribeClusterResponse")]
653    pub(crate) fn parse_describe_cluster_response(response: &DescribeClusterResponseData) -> Result<Cluster, Error> {
654        // `new ApiError(response.errorCode(), response.errorMessage())`;
655        // `apiError.isFailure()` -> `throw apiError.exception()`.
656        if Errors::for_code(response.error_code) != Errors::None {
657            return Err(api_error(response.error_code, &response.error_message));
658        }
659        if response.endpoint_type != EndpointType::Controller.id() {
660            return Err(Error::MismatchedEndpointType(MismatchedEndpointTypeError::new(format!(
661                "Expected response from CONTROLLER endpoint, but got response from endpoint type {}",
662                response.endpoint_type
663            ))));
664        }
665        let mut nodes = Vec::with_capacity(response.brokers.len());
666        let mut controller_node = None;
667        for node in &response.brokers {
668            let new_node = Node::with_rack(node.broker_id, node.host.clone(), node.port, node.rack.clone());
669            if node.broker_id == response.controller_id {
670                controller_node = Some(new_node.clone());
671            }
672            nodes.push(new_node);
673        }
674        Ok(Cluster::with_controller(
675            Some(response.cluster_id.clone()),
676            nodes,
677            Vec::new(),
678            HashSet::new(),
679            HashSet::new(),
680            controller_node,
681        ))
682    }
683
684    /// If a `default.api.timeout.ms` has been explicitly specified, raise an
685    /// error if it conflicts with `request.timeout.ms`. If no
686    /// `default.api.timeout.ms` has been configured, then set its value as the
687    /// max of the default and `request.timeout.ms`. Also we should probably log
688    /// a warning. Otherwise, use the provided values for both configurations.
689    ///
690    /// Translated from `KafkaAdminClient#configureDefaultApiTimeoutMs`.
691    ///
692    /// # Errors
693    ///
694    /// [`Error::Config`] when `default.api.timeout.ms` is set explicitly below
695    /// `request.timeout.ms`, with Java's single-message `ConfigException` text.
696    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#configureDefaultApiTimeoutMs")]
697    fn configure_default_api_timeout_ms(config: &AdminClientConfig, log_context: &LogContext) -> Result<i32, Error> {
698        let request_timeout_ms = config.request_timeout_ms();
699        let default_api_timeout_ms = config.default_api_timeout_ms();
700
701        if default_api_timeout_ms < request_timeout_ms {
702            if config.user_configured(AdminClientConfig::DEFAULT_API_TIMEOUT_MS_CONFIG) {
703                return Err(Error::config_message(format!(
704                    "The specified value of {} must be no smaller than the value of {}.",
705                    AdminClientConfig::DEFAULT_API_TIMEOUT_MS_CONFIG,
706                    AdminClientConfig::REQUEST_TIMEOUT_MS_CONFIG
707                )));
708            }
709            kafka_warn!(
710                log_context,
711                "Overriding the default value for {} ({}) with the explicitly configured request timeout {}",
712                AdminClientConfig::DEFAULT_API_TIMEOUT_MS_CONFIG,
713                default_api_timeout_ms,
714                request_timeout_ms
715            );
716            return Ok(request_timeout_ms);
717        }
718        Ok(default_api_timeout_ms)
719    }
720
721    /// Wires up the shared state and the (not-yet-running) background runnable.
722    ///
723    /// `client_id` is the resolved id from [`generate_client_id`](Self::generate_client_id),
724    /// not `config.client_id()`, which may be empty.
725    ///
726    /// Shared by production ([`new`](Self::new)) and the test constructor, as
727    /// Java's private constructor is shared by both `createInternal` paths;
728    /// like it, this resolves the effective `default.api.timeout.ms`
729    /// ([`configure_default_api_timeout_ms`](Self::configure_default_api_timeout_ms)).
730    fn build<C: KafkaClient + Send + 'static>(
731        client: C,
732        metadata_manager: AdminMetadataManager,
733        config: &AdminClientConfig,
734        client_id: String,
735        time: Arc<dyn Time>,
736        log_context: LogContext,
737    ) -> Result<(Self, AdminClientRunnable<C>), Error> {
738        // `this.defaultApiTimeoutMs = configureDefaultApiTimeoutMs(config)` in
739        // the constructor `KafkaAdminClient#KafkaAdminClient`.
740        let default_api_timeout_ms = Self::configure_default_api_timeout_ms(config, &log_context)?;
741        let (admin_tx, admin_rx) = mpsc::unbounded_channel();
742        let wakeup = client.wakeup_notify();
743        let shutdown = Arc::new(ShutdownSignal::new());
744        // Propagated rather than `expect`ed: Java's constructor-wide
745        // `catch (Throwable exc)` (in the `HostResolver` overload of
746        // `org.apache.kafka.clients.admin.KafkaAdminClient#createInternal`)
747        // converts every construction failure into a `KafkaException`, and `new` is
748        // where that wrap happens. `ExponentialBackoff::new` only rejects an
749        // out-of-range jitter, so this is unreachable with the constant above — but
750        // panicking on the admin construction path is precisely what Java does not.
751        let retry_backoff = ExponentialBackoff::new(
752            config.retry_backoff_ms(),
753            RETRY_BACKOFF_EXP_BASE,
754            config.retry_backoff_max_ms(),
755            RETRY_BACKOFF_JITTER,
756        )
757        .map_err(Error::config_message)?;
758
759        let runnable = AdminClientRunnable::new(
760            client,
761            metadata_manager.clone(),
762            admin_rx,
763            retry_backoff.clone(),
764            config.retry_backoff_ms(),
765            config.retries(),
766            config.request_timeout_ms(),
767            config.metadata_recovery_strategy(),
768            Arc::clone(&time),
769            Arc::clone(&shutdown),
770            log_context.clone(),
771        );
772
773        let shared = Shared {
774            client_id,
775            default_api_timeout_ms,
776            request_timeout_ms: config.request_timeout_ms(),
777            call_sender: CallSender {
778                tx: admin_tx,
779                wakeup: Arc::clone(&wakeup),
780                shutdown: Arc::clone(&shutdown),
781                metadata_manager: metadata_manager.clone(),
782                max_retries: config.retries(),
783                retry_backoff,
784                time: Arc::clone(&time),
785                log_context: log_context.clone(),
786            },
787            wakeup,
788            shutdown,
789            metadata_manager,
790            time,
791            bg_handle: Mutex::new(None),
792            retry_backoff_ms: config.retry_backoff_ms(),
793            retry_backoff_max_ms: config.retry_backoff_max_ms(),
794            partition_leader_cache: Arc::new(PartitionLeaderCache::new()),
795            log_context,
796        };
797        Ok((Self { shared: Arc::new(shared) }, runnable))
798    }
799
800    /// Spawns the background task.
801    fn spawn<C: KafkaClient + Send + 'static>(&self, mut runnable: AdminClientRunnable<C>) {
802        let handle = tokio::task::spawn(async move {
803            runnable.run().await;
804        });
805        *self.shared.bg_handle.lock().unwrap() = Some(handle);
806    }
807
808    /// Submits a call to the background task, failing it immediately if the
809    /// client is closed. Mirrors `AdminClientRunnable.call` / `enqueue`; the
810    /// checks live in [`CallSender::call`], which the `AdminApiDriver` path uses
811    /// too.
812    fn submit(&self, call: Call) {
813        self.shared.call_sender.call(call);
814    }
815
816    fn now(&self) -> i64 {
817        self.shared.time.milliseconds()
818    }
819
820    /// `describeTopics` by name: describes the cluster for the node map, then
821    /// issues the paginated `describeTopicPartitions` call (KIP-966), which falls
822    /// back to the Metadata API on an older broker. Names that cannot be
823    /// represented in a request fail at once, and no request is sent if none is
824    /// left.
825    ///
826    /// Translated from
827    /// `KafkaAdminClient#handleDescribeTopicsByNamesWithDescribeTopicPartitionsApi`.
828    /// The follow-up call is chained on the `describeCluster` nodes future as Java
829    /// chains it with `whenComplete`, so it is issued from the I/O task through
830    /// `runnable.call` ([`DriverContext::call`]).
831    fn handle_describe_topics_by_names_with_describe_topic_partitions_api(
832        &self,
833        topic_names: &[String],
834        options: &DescribeTopicsOptions,
835    ) -> HashMap<String, KafkaFuture<TopicDescription>> {
836        let mut topic_futures: HashMap<String, KafkaFutureImpl<TopicDescription>> = HashMap::new();
837        let mut topic_names_list: Vec<String> = Vec::new();
838        for topic_name in topic_names {
839            if topic_name_is_unrepresentable(topic_name) {
840                let future: KafkaFutureImpl<TopicDescription> = KafkaFutureImpl::new();
841                future.complete_with_error(Error::with_message(
842                    Errors::InvalidTopicError,
843                    format!("The given topic name '{topic_name}' cannot be represented in a request."),
844                ));
845                topic_futures.insert(topic_name.clone(), future);
846            } else if let std::collections::hash_map::Entry::Vacant(entry) = topic_futures.entry(topic_name.clone()) {
847                entry.insert(KafkaFutureImpl::new());
848                topic_names_list.push(topic_name.clone());
849            }
850        }
851        let public: HashMap<String, KafkaFuture<TopicDescription>> = topic_futures
852            .iter()
853            .map(|(name, future)| (name.clone(), future.future()))
854            .collect();
855        if topic_names_list.is_empty() {
856            return public;
857        }
858
859        // First, we need to retrieve the node info.
860        let (_cluster_result, nodes) =
861            self.describe_cluster_with_nodes_handle(DescribeClusterOptions::new().set_timeout_ms(options.timeout_ms()));
862        let topic_futures = Arc::new(topic_futures);
863        let ctx = self.driver_context();
864        let default_api_timeout_ms = self.shared.default_api_timeout_ms;
865        let options = options.clone();
866        nodes.when_complete(move |result| match result {
867            Err(error) => {
868                for future in topic_futures.values() {
869                    future.complete_with_error(error.clone());
870                }
871            },
872            Ok(nodes) => {
873                let now = ctx.time.milliseconds();
874                let node_id_map: HashMap<i32, Node> = nodes.iter().map(|node| (node.id(), node.clone())).collect();
875                let call = generate_describe_topics_call_with_describe_topic_partitions_api(
876                    topic_names_list,
877                    topic_futures,
878                    node_id_map,
879                    options,
880                    now,
881                    ctx.clone(),
882                    default_api_timeout_ms,
883                );
884                ctx.sender.call(call);
885            },
886        });
887        public
888    }
889
890    /// `describeCluster`, also returning the completable handle behind
891    /// `DescribeClusterResult.nodes()`.
892    ///
893    /// `describeTopics` by name chains its `DescribeTopicPartitions` call on
894    /// `describeCluster(..).nodes().whenComplete(..)`
895    /// (`KafkaAdminClient#handleDescribeTopicsByNamesWithDescribeTopicPartitionsApi`).
896    /// Java's public `KafkaFuture` has `whenComplete`; the Rust one does not
897    /// (`admin-client.md` §4 keeps it on the crate-internal `KafkaFutureImpl`), so
898    /// the handle is returned alongside the public result.
899    fn describe_cluster_with_nodes_handle(
900        &self,
901        options: DescribeClusterOptions,
902    ) -> (DescribeClusterResult, KafkaFutureImpl<Vec<Node>>) {
903        let now = self.now();
904        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
905
906        let nodes_handle: KafkaFutureImpl<Vec<Node>> = KafkaFutureImpl::new();
907        let controller_handle: KafkaFutureImpl<Option<Node>> = KafkaFutureImpl::new();
908        let cluster_id_handle: KafkaFutureImpl<String> = KafkaFutureImpl::new();
909        let authorized_ops_handle: KafkaFutureImpl<Option<BTreeSet<AclOperation>>> = KafkaFutureImpl::new();
910
911        let public = DescribeClusterResult::new(
912            nodes_handle.future(),
913            controller_handle.future(),
914            cluster_id_handle.future(),
915            authorized_ops_handle.future(),
916        );
917
918        // `useMetadataRequest` is toggled to true by the UnsupportedVersion
919        // handler so the retry falls back to a Metadata request (mirrors Java).
920        let use_metadata_request = Arc::new(std::sync::atomic::AtomicBool::new(false));
921        let mm = self.shared.metadata_manager.clone();
922        let include_authorized_operations = options.include_authorized_operations();
923        let include_fenced_brokers = options.include_fenced_brokers();
924
925        let req_use_metadata = Arc::clone(&use_metadata_request);
926        let req_mm = mm.clone();
927        let create_request = Box::new(move |_timeout_ms: i32| {
928            if req_use_metadata.load(std::sync::atomic::Ordering::Acquire) {
929                // Only requests node information; allow_auto_topic_creation=true
930                // simplifies communication with older brokers.
931                let mut data = crate::MetadataRequestData::new();
932                data.set_topics(Some(Vec::new()));
933                data.set_allow_auto_topic_creation(true);
934                data.set_include_cluster_authorized_operations(include_authorized_operations);
935                Ok(Box::new(metadata_request::Builder::with_data(data)) as Box<dyn RequestBuilder>)
936            } else {
937                if req_mm.using_bootstrap_controllers() && include_fenced_brokers {
938                    return Err(Error::local_illegal_argument(
939                        "Cannot request fenced brokers from controller endpoint",
940                    ));
941                }
942                let endpoint_type = if req_mm.using_bootstrap_controllers() {
943                    EndpointType::Controller.id()
944                } else {
945                    EndpointType::Broker.id()
946                };
947                let mut data = DescribeClusterRequestData::new();
948                data.set_include_cluster_authorized_operations(include_authorized_operations);
949                data.set_endpoint_type(endpoint_type);
950                data.set_include_fenced_brokers(include_fenced_brokers);
951                Ok(Box::new(describe_cluster_request::Builder::new(data)) as Box<dyn RequestBuilder>)
952            }
953        });
954
955        let resp_use_metadata = Arc::clone(&use_metadata_request);
956        let resp_nodes = nodes_handle.clone();
957        let resp_controller = controller_handle.clone();
958        let resp_cluster_id = cluster_id_handle.clone();
959        let resp_authorized = authorized_ops_handle.clone();
960        let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
961            if resp_use_metadata.load(std::sync::atomic::Ordering::Acquire) {
962                let ConcreteResponse::Metadata(metadata_response) = response else {
963                    return HandleResult::Retry(Error::local_illegal_state("Expected a Metadata response"));
964                };
965                resp_nodes.complete(metadata_response.brokers().to_vec());
966                let controller = metadata_response
967                    .controller()
968                    .filter(|c| c.id() != MetadataResponse::NO_CONTROLLER_ID)
969                    .cloned();
970                resp_controller.complete(controller);
971                resp_cluster_id.complete(metadata_response.cluster_id().unwrap_or_default().to_string());
972                resp_authorized.complete(AdminUtils::valid_acl_operations(
973                    metadata_response.cluster_authorized_operations(),
974                ));
975            } else {
976                let ConcreteResponse::DescribeCluster(describe_response) = response else {
977                    return HandleResult::Retry(Error::local_illegal_state("Expected a DescribeCluster response"));
978                };
979                let error = Errors::for_code(describe_response.data().error_code);
980                if error != Errors::None {
981                    // Mirrors Java's `handleFailure(error.exception(errorMessage))`:
982                    // fail all four futures directly rather than retrying.
983                    let err = api_error(describe_response.data().error_code, &describe_response.data().error_message);
984                    resp_nodes.complete_with_error(err.clone());
985                    resp_controller.complete_with_error(err.clone());
986                    resp_cluster_id.complete_with_error(err.clone());
987                    resp_authorized.complete_with_error(err);
988                    return HandleResult::Done;
989                }
990                let nodes = describe_response.nodes();
991                let controller_id = describe_response.data().controller_id;
992                resp_nodes.complete(nodes.values().cloned().collect());
993                // Controller is None if the controller id is NO_CONTROLLER_ID.
994                resp_controller.complete(nodes.get(&controller_id).cloned());
995                resp_cluster_id.complete(describe_response.data().cluster_id.clone());
996                resp_authorized.complete(AdminUtils::valid_acl_operations(
997                    describe_response.data().cluster_authorized_operations,
998                ));
999            }
1000            HandleResult::Done
1001        });
1002
1003        let fail_nodes = nodes_handle.clone();
1004        let fail_controller = controller_handle.clone();
1005        let fail_cluster_id = cluster_id_handle.clone();
1006        let fail_authorized = authorized_ops_handle.clone();
1007        let handle_failure = Box::new(move |error: &Error| {
1008            fail_nodes.complete_with_error(error.clone());
1009            fail_controller.complete_with_error(error.clone());
1010            fail_cluster_id.complete_with_error(error.clone());
1011            fail_authorized.complete_with_error(error.clone());
1012        });
1013
1014        let uv_mm = mm.clone();
1015        let uv_use_metadata = Arc::clone(&use_metadata_request);
1016        let handle_uv = Box::new(move |_error: &Error| {
1017            if uv_mm.using_bootstrap_controllers() {
1018                return false;
1019            }
1020            if uv_use_metadata.load(std::sync::atomic::Ordering::Acquire) {
1021                return false;
1022            }
1023            // If the UnsupportedVersion was caused by requesting fenced brokers
1024            // (only supported at v2+), do not fall back to the metadata request.
1025            if include_fenced_brokers {
1026                return false;
1027            }
1028            uv_use_metadata.store(true, std::sync::atomic::Ordering::Release);
1029            true
1030        });
1031
1032        let call = Call::new(
1033            "listNodes",
1034            deadline,
1035            NodeProvider::LeastLoadedBrokerOrActiveKController,
1036            create_request,
1037            handle_response,
1038            handle_failure,
1039            handle_uv,
1040        );
1041        self.submit(call);
1042        (public, nodes_handle)
1043    }
1044
1045    /// Builds the context used to submit `AdminApiDriver`-generated calls
1046    /// (mirrors the closure over `runnable` in `KafkaAdminClient.maybeSendRequests`).
1047    fn driver_context(&self) -> DriverContext {
1048        DriverContext {
1049            sender: self.shared.call_sender.clone(),
1050            time: Arc::clone(&self.shared.time),
1051            log_context: LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id)),
1052        }
1053    }
1054
1055    /// Builds the exponential retry backoff used by `AdminApiDriver`-backed RPCs.
1056    fn retry_backoff(&self) -> ExponentialBackoff {
1057        ExponentialBackoff::new(
1058            self.shared.retry_backoff_ms,
1059            RETRY_BACKOFF_EXP_BASE,
1060            self.shared.retry_backoff_max_ms,
1061            RETRY_BACKOFF_JITTER,
1062        )
1063        .expect("ExponentialBackoff::new only fails on invalid jitter")
1064    }
1065
1066    /// Drives the `listGroups` broker-enumeration RPC: a `findAllBrokers`
1067    /// metadata call whose response fans out one per-broker `ListGroups` call,
1068    /// all feeding a shared [`ListGroupsResults`] accumulator.
1069    ///
1070    /// `maybe_add` maps a wire `ListedGroup` to an optional keyed listing
1071    /// (returning `None` filters the group out). Mirrors the structure of
1072    /// `KafkaAdminClient.listGroups`.
1073    fn submit_list_groups<F>(
1074        &self,
1075        deadline: i64,
1076        states_filter: Vec<String>,
1077        types_filter: Vec<String>,
1078        maybe_add: F,
1079    ) -> KafkaFuture<Vec<Result<GroupListing, Error>>>
1080    where
1081        F: Fn(&crate::list_groups_response_data::ListedGroup) -> Option<(String, GroupListing)>
1082            + Clone
1083            + Send
1084            + Sync
1085            + 'static,
1086    {
1087        let all: KafkaFutureImpl<Vec<Result<GroupListing, Error>>> = KafkaFutureImpl::new();
1088        let public = all.future();
1089        let ctx = self.driver_context();
1090
1091        let fail_all = all.clone();
1092        let handle_failure = Box::new(move |error: &Error| {
1093            // `new KafkaException("Failed to find brokers to send ListGroups", throwable)`
1094            // (`org.apache.kafka.clients.admin.KafkaAdminClient#listGroups`). A *bare*
1095            // `KafkaException`: `is_kafka_error()` true, `is_api_error()` /
1096            // `is_retriable_error()` / `is_authorization_error()` all false, the cause
1097            // reachable through `source()`, and the message fixed — it does not carry
1098            // the cause's text. Reusing `error.error()` made the wrapper inherit the
1099            // inner class, so a metadata `TimeoutError` came back retriable and
1100            // causeless (finding 243).
1101            let wrapped = Error::kafka_message_source("Failed to find brokers to send ListGroups", error.clone());
1102            fail_all.complete(vec![Err(wrapped)]);
1103        });
1104
1105        let create_request = Box::new(move |_timeout_ms: i32| {
1106            // Empty topic list (just the broker list), matching Java's
1107            // MetadataRequest with setTopics(emptyList).setAllowAutoTopicCreation(true).
1108            Ok(Box::new(metadata_request::Builder::with_topics_allow_auto_topic_creation(
1109                Some(&[]),
1110                true,
1111            )) as Box<dyn RequestBuilder>)
1112        });
1113
1114        let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
1115            let ConcreteResponse::Metadata(metadata_response) = response else {
1116                return HandleResult::Retry(Error::local_illegal_state("Expected a Metadata response"));
1117            };
1118            let nodes: Vec<Node> = metadata_response.brokers().to_vec();
1119            if nodes.is_empty() {
1120                // Java throws StaleMetadataException (retriable) so the metadata
1121                // fetch is retried; there is no dedicated StaleMetadata error code
1122                // in Rust, so we surface a retriable metadata error to trigger the
1123                // same retry.
1124                return HandleResult::Retry(Error::with_message(
1125                    Errors::LeaderNotAvailable,
1126                    "Metadata fetch failed due to missing broker list",
1127                ));
1128            }
1129
1130            let node_ids: HashSet<i32> = nodes.iter().map(Node::id).collect();
1131            let results = ListGroupsResults::new(node_ids, all.clone());
1132
1133            for node in nodes {
1134                let node_id = node.id();
1135                let states = states_filter.clone();
1136                let types = types_filter.clone();
1137                let node_create = node.clone();
1138                let create_list_request = Box::new(move |_timeout_ms: i32| {
1139                    let mut data = ListGroupsRequestData::new();
1140                    data.set_states_filter(states.clone());
1141                    data.set_types_filter(types.clone());
1142                    let _ = &node_create;
1143                    Ok(Box::new(list_groups_request::Builder::new(data)) as Box<dyn RequestBuilder>)
1144                });
1145
1146                let resp_results = Arc::clone(&results);
1147                let resp_node = node.clone();
1148                let resp_add = maybe_add.clone();
1149                let handle_list_response =
1150                    Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
1151                        let ConcreteResponse::ListGroups(list_response) = response else {
1152                            return HandleResult::Retry(Error::local_illegal_state("Expected a ListGroups response"));
1153                        };
1154                        let error = Errors::for_code(list_response.data().error_code);
1155                        if error == Errors::CoordinatorLoadInProgress || error == Errors::CoordinatorNotAvailable {
1156                            // Retriable at the broker level: retry this per-broker call.
1157                            return HandleResult::Retry(Error::new(error));
1158                        }
1159                        let mut results = resp_results.lock().unwrap();
1160                        if error != Errors::None {
1161                            results.add_error(&Error::new(error), &resp_node);
1162                        } else {
1163                            for group in &list_response.data().groups {
1164                                if let Some((group_id, listing)) = resp_add(group) {
1165                                    results.add_listing(group_id, listing);
1166                                }
1167                            }
1168                        }
1169                        results.complete_node(node_id);
1170                        HandleResult::Done
1171                    });
1172
1173                let fail_results = Arc::clone(&results);
1174                let fail_node = node.clone();
1175                let handle_list_failure = Box::new(move |error: &Error| {
1176                    let mut results = fail_results.lock().unwrap();
1177                    results.add_error(error, &fail_node);
1178                    results.complete_node(node_id);
1179                });
1180
1181                let list_call = Call::new(
1182                    "listGroups",
1183                    deadline,
1184                    NodeProvider::ConstantNodeId { node_id, supports_use_controllers: false },
1185                    create_list_request,
1186                    handle_list_response,
1187                    handle_list_failure,
1188                    Box::new(|_| false),
1189                );
1190                // Java: `runnable.call(new Call("listGroups", ..), now)`.
1191                ctx.sender.call(list_call);
1192            }
1193            HandleResult::Done
1194        });
1195
1196        let call = Call::new(
1197            "findAllBrokers",
1198            deadline,
1199            NodeProvider::LeastLoaded,
1200            create_request,
1201            handle_response,
1202            handle_failure,
1203            Box::new(|_| false),
1204        );
1205        self.submit(call);
1206        public
1207    }
1208
1209    /// Submits one `incrementalAlterConfigs` [`Call`] for the given `resources`
1210    /// (all routed to `node_provider`) and returns the per-resource futures.
1211    ///
1212    /// Translated from the private
1213    /// `KafkaAdminClient.incrementalAlterConfigs(configs, options, resources, nodeProvider)`.
1214    fn submit_incremental_alter_configs(
1215        &self,
1216        configs: &HashMap<ConfigResource, Vec<AlterConfigOp>>,
1217        options: &AlterConfigsOptions,
1218        resources: &[ConfigResource],
1219        node_provider: NodeProvider,
1220    ) -> HashMap<ConfigResource, KafkaFuture<()>> {
1221        let mut handles: HashMap<ConfigResource, KafkaFutureImpl<()>> = HashMap::new();
1222        for resource in resources {
1223            handles.insert(resource.clone(), KafkaFutureImpl::new());
1224        }
1225        let public: HashMap<ConfigResource, KafkaFuture<()>> =
1226            handles.iter().map(|(k, v)| (k.clone(), v.future())).collect();
1227
1228        let now = self.now();
1229        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
1230        let validate_only = options.should_validate_only();
1231
1232        // Build the request data from the admin `ConfigResource`/`AlterConfigOp`
1233        // types (Java's `IncrementalAlterConfigsRequest.Builder` does this).
1234        let mut request_data = IncrementalAlterConfigsRequestData::new();
1235        request_data.set_validate_only(validate_only);
1236        let mut wire_resources = Vec::with_capacity(resources.len());
1237        for resource in resources {
1238            let mut alterable_configs = Vec::new();
1239            if let Some(ops) = configs.get(resource) {
1240                for op in ops {
1241                    let mut c = AlterableConfig::new();
1242                    c.set_name(op.config_entry().name().to_string());
1243                    c.set_value(op.config_entry().value().map(str::to_string));
1244                    c.set_config_operation(op.op_type().id());
1245                    alterable_configs.push(c);
1246                }
1247            }
1248            let mut wire_resource = AlterConfigsResource::new();
1249            wire_resource.set_resource_type(resource.r#type().id());
1250            wire_resource.set_resource_name(resource.name().to_string());
1251            wire_resource.set_configs(alterable_configs);
1252            wire_resources.push(wire_resource);
1253        }
1254        request_data.set_resources(wire_resources);
1255
1256        let create_request = Box::new(move |_timeout_ms: i32| {
1257            Ok(
1258                Box::new(incremental_alter_configs_request::Builder::with_data(request_data.clone()))
1259                    as Box<dyn RequestBuilder>,
1260            )
1261        });
1262
1263        let handles = Arc::new(handles);
1264        let resp_mm = self.shared.metadata_manager.clone();
1265        let resp_handles = Arc::clone(&handles);
1266        let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
1267            let ConcreteResponse::IncrementalAlterConfigs(alter_response) = response else {
1268                return HandleResult::Retry(Error::local_illegal_state("Expected an IncrementalAlterConfigs response"));
1269            };
1270            if let Some(err) = handle_not_controller_error(&resp_mm, &alter_response.error_counts()) {
1271                return HandleResult::Retry(err);
1272            }
1273            let errors = alter_response.errors_by_resource();
1274            for (resource, future) in resp_handles.iter() {
1275                match errors.get(resource) {
1276                    Some((code, message)) if *code != Errors::None.code() => {
1277                        future.complete_with_error(api_error(*code, message));
1278                    },
1279                    _ => {
1280                        future.complete(());
1281                    },
1282                }
1283            }
1284            HandleResult::Done
1285        });
1286
1287        let fail_handles = Arc::clone(&handles);
1288        let handle_failure = Box::new(move |error: &Error| {
1289            for future in fail_handles.values() {
1290                future.complete_with_error(error.clone());
1291            }
1292        });
1293
1294        let call = Call::new(
1295            "incrementalAlterConfigs",
1296            deadline,
1297            node_provider,
1298            create_request,
1299            handle_response,
1300            handle_failure,
1301            Box::new(|_| false),
1302        );
1303        self.submit(call);
1304        public
1305    }
1306}
1307
1308/// The app-side handle that submits [`Call`]s to the background task: Java's
1309/// `AdminClientRunnable.call` / `enqueue`, which both `KafkaAdminClient`'s RPC
1310/// methods and the `AdminApiDriver` callbacks (`maybeSendRequests`) reach
1311/// through `runnable`.
1312///
1313/// Rust-only type (DoD #7): Java's closures capture the runnable itself, while
1314/// here the runnable is owned by the background task, so the channel and the
1315/// state its checks read (shutdown signal, metadata manager) are bundled into a
1316/// cloneable handle that every enqueue path shares, keeping Java's check order
1317/// in one place.
1318#[derive(Clone)]
1319struct CallSender {
1320    tx: mpsc::UnboundedSender<Call>,
1321    wakeup: Arc<Notify>,
1322    shutdown: Arc<ShutdownSignal>,
1323    metadata_manager: AdminMetadataManager,
1324    /// The `retries` config: `AdminClientRunnable`'s `maxRetries`, read by
1325    /// `enqueue`'s first check.
1326    max_retries: i32,
1327    /// The client's retry backoff, which `call.fail` advances when `call`
1328    /// rejects a call for a `bootstrap.controllers` client (the value appears in
1329    /// the timeout message).
1330    retry_backoff: ExponentialBackoff,
1331    /// `KafkaAdminClient.time`, which `enqueue` reads for `handleTimeoutFailure`.
1332    time: Arc<dyn Time>,
1333    log_context: LogContext,
1334}
1335
1336impl CallSender {
1337    /// Hands a call to the background task, or fails it at once. Translated
1338    /// from `KafkaAdminClient.AdminClientRunnable#call` and the
1339    /// `KafkaAdminClient.AdminClientRunnable#enqueue` it forwards to, in Java's
1340    /// order: hard shutdown → `bootstrap.controllers` endpoint check →
1341    /// (`enqueue`) retry budget → permanent bootstrap failure (KIP-909) → the
1342    /// task has exited.
1343    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient$AdminClientRunnable#call")]
1344    fn call(&self, call: Call) {
1345        // `org.apache.kafka.clients.admin.KafkaAdminClient.AdminClientRunnable#call`'s
1346        // two rejections: once `close()` has set a hard-shutdown time, and an
1347        // endpoint a `bootstrap.controllers` client cannot serve. The I/O task
1348        // applies the same gate to the follow-ups a response hook returns.
1349        let Some(call) = self.shutdown.admit_new_call(
1350            self.metadata_manager.using_bootstrap_controllers(),
1351            &self.retry_backoff,
1352            self.time.milliseconds(),
1353            call,
1354        ) else {
1355            return;
1356        };
1357        // Java's
1358        // `org.apache.kafka.clients.admin.KafkaAdminClient.AdminClientRunnable#enqueue`
1359        // begins with the retry budget. A call reaches it already tried when
1360        // the `AdminApiDriver` re-issues a request spec, which carries its
1361        // `tries` into the new call (`new_driver_call`).
1362        if call.tries > self.max_retries {
1363            let mut call = call;
1364            kafka_debug!(self.log_context, "Max retries {} for {} reached", self.max_retries, call);
1365            let message = format!("Exceeded maxRetries after {} tries.", call.tries);
1366            call.handle_timeout_failure(self.time.milliseconds(), Error::timeout(message));
1367            return;
1368        }
1369        // Java's `enqueue`: a permanent bootstrap failure (KIP-909) fails the
1370        // call with that error instead of accepting it. The I/O task has exited
1371        // by then (`AdminClientRunnable::process_requests`), so without this
1372        // the call would get "The AdminClient thread has exited." below.
1373        // Java's `enqueue` reads `metadataManager.bootstrapFatalException()` (KIP-909).
1374        if let Some(bootstrap_error) = self.metadata_manager.bootstrap_fatal_error() {
1375            let mut call = call;
1376            call.handle_failure(&Error::BootstrapResolution(bootstrap_error));
1377            return;
1378        }
1379        match self.tx.send(call) {
1380            Ok(()) => self.wakeup.notify_one(),
1381            Err(mpsc::error::SendError(mut call)) => {
1382                // `new TimeoutException("The AdminClient thread has exited.")`
1383                // (`org.apache.kafka.clients.admin.KafkaAdminClient.AdminClientRunnable#enqueue`).
1384                // `KafkaAdminClient.Call#handleTimeoutFailure` short-circuits on
1385                // `cause instanceof TimeoutException`, so the user sees exactly a
1386                // `TimeoutException` — a `RetriableException`. `illegal_state` sits
1387                // outside the `KafkaException` hierarchy entirely, so it answered
1388                // `false` to both `is_retriable_error()` and `is_kafka_error()`.
1389                call.handle_failure(&Error::timeout("The AdminClient thread has exited."));
1390            },
1391        }
1392    }
1393
1394    /// A sender over `tx` with a fresh shutdown signal and metadata manager,
1395    /// for tests that drive `AdminApiDriver` calls by hand.
1396    #[cfg(test)]
1397    fn for_test(tx: mpsc::UnboundedSender<Call>) -> Self {
1398        Self {
1399            tx,
1400            wakeup: Arc::new(Notify::new()),
1401            shutdown: Arc::new(ShutdownSignal::new()),
1402            metadata_manager: AdminMetadataManager::new(100, 300_000, false, LogContext::empty()),
1403            // `AdminClientConfig`'s `retries` default, `Integer.MAX_VALUE`.
1404            max_retries: i32::MAX,
1405            retry_backoff: ExponentialBackoff::new(100, RETRY_BACKOFF_EXP_BASE, 1000, 0.0).expect("a valid backoff"),
1406            time: Arc::new(SystemTime),
1407            log_context: LogContext::empty(),
1408        }
1409    }
1410}
1411
1412/// Shared handle used to submit `AdminApiDriver`-generated [`Call`]s onto the
1413/// background task, mirroring the `runnable.call(...)` closure in
1414/// `KafkaAdminClient.newCall` / `maybeSendRequests`.
1415#[derive(Clone)]
1416struct DriverContext {
1417    sender: CallSender,
1418    time: Arc<dyn Time>,
1419    log_context: LogContext,
1420}
1421
1422/// Kicks off a driver-backed RPC: polls the driver for its initial requests and
1423/// submits them. Mirrors `KafkaAdminClient.invokeDriver` + the initial
1424/// `maybeSendRequests`.
1425#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#invokeDriver")]
1426fn invoke_driver<K, V>(driver: AdminApiDriver<K, V>, ctx: DriverContext, now: i64)
1427where
1428    K: Clone + Eq + std::hash::Hash + std::fmt::Display + Send + 'static,
1429    V: Send + 'static,
1430{
1431    let driver = Arc::new(Mutex::new(driver));
1432    maybe_send_requests(&driver, &ctx, now);
1433}
1434
1435/// Polls the driver and submits one [`Call`] per produced request spec.
1436/// Mirrors `KafkaAdminClient.maybeSendRequests`.
1437#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#maybeSendRequests")]
1438fn maybe_send_requests<K, V>(driver: &Arc<Mutex<AdminApiDriver<K, V>>>, ctx: &DriverContext, _now: i64)
1439where
1440    K: Clone + Eq + std::hash::Hash + std::fmt::Display + Send + 'static,
1441    V: Send + 'static,
1442{
1443    // Also poison-tolerant: `handle_failure` calls this on the post-panic recovery
1444    // path, where the driver mutex may already be poisoned (see there).
1445    let specs = driver.lock().unwrap_or_else(std::sync::PoisonError::into_inner).poll();
1446    for spec in specs {
1447        let call = new_driver_call(Arc::clone(driver), spec, ctx.clone());
1448        // Java: `runnable.call(newCall(driver, spec), now)`
1449        // (`org.apache.kafka.clients.admin.KafkaAdminClient#maybeSendRequests`).
1450        ctx.sender.call(call);
1451    }
1452}
1453
1454/// Wraps a driver [`RequestSpec`] in a [`Call`] whose hooks feed responses and
1455/// failures back into the driver. Mirrors `KafkaAdminClient.newCall`.
1456fn new_driver_call<K, V>(driver: Arc<Mutex<AdminApiDriver<K, V>>>, spec: RequestSpec<K>, ctx: DriverContext) -> Call
1457where
1458    K: Clone + Eq + std::hash::Hash + std::fmt::Display + Send + 'static,
1459    V: Send + 'static,
1460{
1461    let RequestSpec { name, scope, keys, request, next_allowed_try_ms, deadline_ms, tries } = spec;
1462    let node_provider = match scope.destination_broker_id() {
1463        Some(node_id) => NodeProvider::ConstantNodeId { node_id, supports_use_controllers: false },
1464        None => NodeProvider::LeastLoaded,
1465    };
1466    // create_request: hand over the pre-built builder on first send; rebuild
1467    // from the driver on the rare non-disconnect retriable re-send.
1468    let mut prebuilt: Option<Box<dyn RequestBuilder>> = Some(request);
1469    let cr_driver = Arc::clone(&driver);
1470    let cr_scope = scope.clone();
1471    let cr_keys = keys.clone();
1472    let create_request = Box::new(move |_timeout_ms: i32| match prebuilt.take() {
1473        Some(rb) => Ok(rb),
1474        None => cr_driver
1475            .lock()
1476            .unwrap()
1477            .build_request_for_spec(&cr_scope, &cr_keys)
1478            .ok_or_else(|| Error::local_illegal_state("AdminApiDriver produced no request on retry")),
1479    });
1480
1481    let hr_driver = Arc::clone(&driver);
1482    let hr_ctx = ctx.clone();
1483    let hr_scope = scope.clone();
1484    let hr_keys = keys.clone();
1485    let handle_response = Box::new(move |response: &ConcreteResponse, now: i64, cur_node: Option<&Node>| {
1486        // Java passes `this.curNode()` — the fully resolved broker the request
1487        // was sent to. Handlers put it in public API (e.g.
1488        // `ConsumerGroupDescription.coordinator()` /
1489        // `ClassicGroupDescription.coordinator()`), so it must carry the real
1490        // host and port, not just the broker id.
1491        let Some(node) = cur_node else {
1492            // Unreachable: `maybe_drain_pending_call` assigns `cur_node` before
1493            // the request is sent and only clears it on unassign / failure, so a
1494            // response always arrives with its node still attached.
1495            return HandleResult::Retry(Error::local_illegal_state(
1496                "AdminApiDriver response arrived with no node assigned to the call",
1497            ));
1498        };
1499        hr_driver.lock().unwrap().on_response(now, &hr_scope, &hr_keys, response, node);
1500        maybe_send_requests(&hr_driver, &hr_ctx, now);
1501        HandleResult::Done
1502    });
1503
1504    let hf_driver = Arc::clone(&driver);
1505    let hf_ctx = ctx.clone();
1506    let hf_scope = scope.clone();
1507    let hf_keys = keys.clone();
1508    let hf_time = Arc::clone(&ctx.time);
1509    let handle_failure = Box::new(move |error: &Error| {
1510        let now = hf_time.milliseconds();
1511        // Poison-tolerant on purpose. This closure is the recovery path: it runs
1512        // from `AdminClientRunnable::fail_all_remaining` after `run()` catches a
1513        // panic, and that panic may have poisoned this very mutex inside
1514        // `handle_response` above. A `.unwrap()` here would panic a second time,
1515        // so the cleanup would not finish and every outstanding `KafkaFuture`
1516        // would hang — the opposite of what Java's `finally` guarantees.
1517        //
1518        // The trade-off being accepted: the driver's state is NOT per-call.
1519        // `AdminApiDriver` owns the persistent `lookup_map` / `fulfillment_map` /
1520        // `request_states` machinery for the whole RPC, and the panic poisoned
1521        // this mutex precisely because it interrupted a mutation of those maps,
1522        // so the guard taken here may expose half-updated ones. Running
1523        // `on_failure` against possibly-inconsistent state is accepted because
1524        // the alternative is a second panic that strands every future.
1525        //
1526        // This reasoning does NOT extend to the normal path: `create_request` and
1527        // `handle_response` above, and `maybe_retry`, keep `.unwrap()` and must.
1528        // They are not recovery code, so continuing there would drive the
1529        // *normal* protocol against half-mutated maps instead of surfacing the
1530        // fault.
1531        hf_driver
1532            .lock()
1533            .unwrap_or_else(std::sync::PoisonError::into_inner)
1534            .on_failure(now, &hf_scope, &hf_keys, error);
1535        maybe_send_requests(&hf_driver, &hf_ctx, now);
1536    });
1537
1538    let hnu_name = name.clone();
1539    let mut call = Call::new(
1540        name,
1541        deadline_ms,
1542        node_provider,
1543        create_request,
1544        handle_response,
1545        handle_failure,
1546        Box::new(|_| false),
1547    );
1548    call.next_allowed_try_ms = next_allowed_try_ms;
1549    call.tries = tries;
1550
1551    // handleNodeUnavailable override (KAFKA-20673): when no node can be assigned
1552    // to this fulfillment call because its target broker has left the cluster
1553    // metadata (a stale partition-leader-cache entry), send the keys back to the
1554    // lookup stage so the leader is re-resolved, rather than sitting in
1555    // pendingCalls until the deadline expires. The liveness check runs on the
1556    // admin client (background) task where `AdminMetadataManager` is safe to
1557    // access. Mirrors the `handleNodeUnavailable` override in `newCall`.
1558    let hnu_driver = Arc::clone(&driver);
1559    let hnu_ctx = ctx.clone();
1560    let hnu_scope = scope.clone();
1561    let hnu_keys = keys.clone();
1562    let hnu_log = ctx.log_context.clone();
1563    call.set_handle_node_unavailable_fn(Box::new(move |mm: &AdminMetadataManager, now: i64| {
1564        // Don't intervene while the client is shutting down (cb2f143b0d).
1565        // Re-running the lookup enqueues new calls via `CallSender::call`, which
1566        // are rejected during close ("Cannot accept new calls when AdminClient is
1567        // closing."). Leaving the call in pending calls preserves the normal
1568        // `close(timeout)` handling, so it can still be assigned, should the broker
1569        // reappear, within the shutdown grace period instead of failing
1570        // immediately. (Java would also retry a send that then fails; the Rust
1571        // close path sets `closing` at once, so it does not — Critic 102 Issue 1,
1572        // deferred to the human.) Java tests `hardShutdownTimeMs`, not `closing`.
1573        if hnu_ctx
1574            .sender
1575            .shutdown
1576            .hard_shutdown_deadline_ms
1577            .load(std::sync::atomic::Ordering::Acquire)
1578            != KafkaAdminClient::NO_HARD_SHUTDOWN
1579        {
1580            return false;
1581        }
1582        if let Some(broker_id) = hnu_scope.destination_broker_id()
1583            && mm.is_ready().unwrap_or(false)
1584            && mm.node_by_id(broker_id).is_none()
1585            && hnu_driver.lock().unwrap().maybe_retry_lookup(now, &hnu_scope, &hnu_keys)
1586        {
1587            kafka_debug!(
1588                hnu_log,
1589                "Broker {} for {} is no longer in the cluster metadata; retrying lookup.",
1590                broker_id,
1591                hnu_name
1592            );
1593            maybe_send_requests(&hnu_driver, &hnu_ctx, now);
1594            return true;
1595        }
1596        false
1597    }));
1598
1599    // maybeRetry override: a disconnect retries lookup via the driver rather
1600    // than re-sending to the (possibly dead) node. Mirrors `newCall.maybeRetry`.
1601    let mr_driver = Arc::clone(&driver);
1602    let mr_ctx = ctx.clone();
1603    let mr_scope = scope;
1604    let mr_keys = keys;
1605    call.set_maybe_retry_fn(Box::new(move |error: &Error, now: i64| {
1606        // `throwable instanceof DisconnectException`
1607        // (`org.apache.kafka.clients.admin.KafkaAdminClient#newCall`), raised as
1608        // `Error::Disconnect` by the runnable — not `Errors::NetworkError`, which
1609        // is a broker-reported code.
1610        if matches!(error, Error::Disconnect(_)) {
1611            mr_driver.lock().unwrap().on_failure(now, &mr_scope, &mr_keys, error);
1612            maybe_send_requests(&mr_driver, &mr_ctx, now);
1613            MaybeRetryOutcome::Handled
1614        } else {
1615            MaybeRetryOutcome::Requeue
1616        }
1617    }));
1618
1619    call
1620}
1621
1622/// Computes the absolute deadline for a call. Mirrors
1623/// `KafkaAdminClient#calcDeadlineMs`: a
1624/// negative option timeout is clamped to zero (`now + Math.max(0, optionTimeoutMs)`),
1625/// so the call is still sent once instead of expiring before it is assigned a node.
1626/// The default API timeout is not clamped, as in Java.
1627#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#calcDeadlineMs")]
1628fn calc_deadline_ms(now: i64, option_timeout: Option<i32>, default_api_timeout_ms: i32) -> i64 {
1629    match option_timeout {
1630        Some(option_timeout_ms) => now + i64::from(option_timeout_ms.max(0)),
1631        None => now + i64::from(default_api_timeout_ms),
1632    }
1633}
1634
1635/// Re-keys a `CoordinatorKey`-keyed future map by the coordinator key's id
1636/// value (the group id), mirroring Java's
1637/// `future.all().entrySet().stream().collect(toMap(e -> e.getKey().idValue, ...))`.
1638fn coordinator_keyed_by_id<V: Send + 'static>(
1639    map: HashMap<CoordinatorKey, KafkaFuture<V>>,
1640) -> HashMap<String, KafkaFuture<V>> {
1641    map.into_iter().map(|(key, future)| (key.id_value, future)).collect()
1642}
1643
1644/// Accumulates the per-broker results of a `listGroups` broker-enumeration RPC,
1645/// completing the combined future once every broker has reported. Mirrors
1646/// `KafkaAdminClient.ListGroupsResults`.
1647#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient$ListGroupsResults")]
1648struct ListGroupsResults {
1649    errors: Vec<Error>,
1650    listings: HashMap<String, GroupListing>,
1651    remaining: HashSet<i32>,
1652    future: KafkaFutureImpl<Vec<Result<GroupListing, Error>>>,
1653}
1654
1655impl ListGroupsResults {
1656    /// Creates the accumulator for the given broker node ids, completing the
1657    /// future immediately if there are no brokers.
1658    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient$ListGroupsResults#ListGroupsResults")]
1659    fn new(node_ids: HashSet<i32>, future: KafkaFutureImpl<Vec<Result<GroupListing, Error>>>) -> Arc<Mutex<Self>> {
1660        let results = Arc::new(Mutex::new(Self {
1661            errors: Vec::new(),
1662            listings: HashMap::new(),
1663            remaining: node_ids,
1664            future,
1665        }));
1666        results.lock().unwrap().try_complete();
1667        results
1668    }
1669
1670    /// Records an error for a broker, wrapping it with the broker context
1671    /// (mirrors Java's `ApiError.fromThrowable` + "Error listing groups on N").
1672    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient$ListGroupsResults#addError")]
1673    fn add_error(&mut self, error: &Error, node: &Node) {
1674        let message = error.message();
1675        let wrapped = if message.is_empty() {
1676            Error::with_message(error.error(), format!("Error listing groups on {node}"))
1677        } else {
1678            Error::with_message(error.error(), format!("Error listing groups on {node}: {message}"))
1679        };
1680        self.errors.push(wrapped);
1681    }
1682
1683    /// Records a listing keyed by group id.
1684    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient$ListGroupsResults#addListing")]
1685    fn add_listing(&mut self, group_id: String, listing: GroupListing) {
1686        self.listings.insert(group_id, listing);
1687    }
1688
1689    /// Marks a broker done and completes the future if it was the last one.
1690    fn complete_node(&mut self, node_id: i32) {
1691        self.remaining.remove(&node_id);
1692        self.try_complete();
1693    }
1694
1695    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient$ListGroupsResults#tryComplete")]
1696    fn try_complete(&mut self) {
1697        if self.remaining.is_empty() {
1698            let mut results: Vec<Result<GroupListing, Error>> = self.listings.values().cloned().map(Ok).collect();
1699            results.extend(self.errors.iter().cloned().map(Err));
1700            self.future.complete(results);
1701        }
1702    }
1703}
1704
1705/// Builds an [`Error`] from a wire error code and optional message, mirroring
1706/// Java's `ApiError.exception()`.
1707fn api_error(code: i16, message: &Option<String>) -> Error {
1708    let error = Errors::for_code(code);
1709    // `org.apache.kafka.common.protocol.Errors#exception(String)` falls back to
1710    // the code's default text ONLY when the broker sent `null`; a non-null EMPTY
1711    // message is passed through verbatim. The generated decoders keep the two
1712    // apart (`len == 0` -> `None`, `len == 1` -> `Some("")`), so treating
1713    // `Some("")` as absent substituted the code's default text where Java reports
1714    // `""` (finding 245). Same shape as `message_with_fallback` below.
1715    match message {
1716        Some(m) => Error::with_message(error, m.clone()),
1717        None => Error::new(error),
1718    }
1719}
1720
1721/// Builds a [`FeatureMetadata`] from an `ApiVersionsResponse`'s data, mirroring
1722/// the `createFeatureMetadata` closure inside `KafkaAdminClient.describeFeatures`.
1723///
1724/// # Errors
1725///
1726/// Returns an error if a finalized/supported version range from the response is
1727/// invalid (mirrors Java's constructor throwing `IllegalArgumentException`).
1728fn create_feature_metadata(data: &ApiVersionsResponseData) -> Result<FeatureMetadata, Error> {
1729    let mut finalized_features = HashMap::new();
1730    for key in &data.finalized_features {
1731        finalized_features.insert(
1732            key.name.clone(),
1733            FinalizedVersionRange::new(key.min_version_level, key.max_version_level)?,
1734        );
1735    }
1736
1737    // A finalized-features epoch of >= 0 is present; otherwise it is absent.
1738    let finalized_features_epoch = if data.finalized_features_epoch >= 0 {
1739        Some(data.finalized_features_epoch)
1740    } else {
1741        None
1742    };
1743
1744    let mut supported_features = HashMap::new();
1745    for key in &data.supported_features {
1746        supported_features.insert(key.name.clone(), SupportedVersionRange::new(key.min_version, key.max_version)?);
1747    }
1748
1749    Ok(FeatureMetadata::new(
1750        finalized_features,
1751        finalized_features_epoch,
1752        supported_features,
1753    ))
1754}
1755
1756/// Builds the answering node's [`NodeApiVersions`] from an `ApiVersionsResponse`'s
1757/// data, mirroring the `createNodeApiVersion` closure inside
1758/// `KafkaAdminClient.describeFeatures` (KAFKA-19663).
1759fn create_node_api_version(data: &ApiVersionsResponseData) -> NodeApiVersions {
1760    NodeApiVersions::with_node_finalized_features_finalized_features_epoch(
1761        &data.api_keys,
1762        &data.supported_features,
1763        &data.finalized_features,
1764        data.finalized_features_epoch,
1765    )
1766}
1767
1768/// Returns `true` if a topic name cannot be represented in an RPC (empty).
1769/// Mirrors `KafkaAdminClient.topicNameIsUnrepresentable`.
1770#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#topicNameIsUnrepresentable")]
1771fn topic_name_is_unrepresentable(topic_name: &str) -> bool {
1772    topic_name.is_empty()
1773}
1774
1775/// Returns `true` if a topic id cannot be represented in an RPC (the zero id).
1776/// Mirrors `KafkaAdminClient.topicIdIsUnrepresentable`.
1777#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#topicIdIsUnrepresentable")]
1778fn topic_id_is_unrepresentable(topic_id: Uuid) -> bool {
1779    topic_id == Uuid::ZERO_UUID
1780}
1781
1782/// Completes any future that was retried due to a quota-exceeded error with the
1783/// carried [`ThrottlingQuotaExceeded`](Error::ThrottlingQuotaExceeded)
1784/// error (reduced by the elapsed throttle time) when the request ultimately
1785/// timed out. Mirrors `KafkaAdminClient.maybeCompleteQuotaExceededException`.
1786fn maybe_complete_quota_exceeded<K, T>(
1787    should_retry_on_quota_violation: bool,
1788    error: &Error,
1789    futures: &HashMap<K, KafkaFutureImpl<T>>,
1790    quota_exceeded_errors: &HashMap<K, Error>,
1791    throttle_time_delta: i32,
1792) where
1793    K: std::hash::Hash + Eq,
1794    T: Clone + Send + Sync + 'static,
1795{
1796    if should_retry_on_quota_violation && matches!(error, Error::Timeout(_)) {
1797        for (key, quota_error) in quota_exceeded_errors {
1798            if let Some(future) = futures.get(key) {
1799                let throttle = quota_error.throttle_time_ms().unwrap_or(0);
1800                future.complete_with_error(Error::throttling_quota_exceeded(
1801                    (throttle - throttle_time_delta).max(0),
1802                    quota_error.message().to_string(),
1803                ));
1804            }
1805        }
1806    }
1807}
1808
1809// ---------------------------------------------------------------------------
1810// ACLs (createAcls / describeAcls / deleteAcls)
1811// ---------------------------------------------------------------------------
1812
1813/// Builds a `createAcls` [`Call`]. Translated from the anonymous `Call` in
1814/// `KafkaAdminClient.createAcls`.
1815fn get_create_acls_call(
1816    mm: AdminMetadataManager,
1817    futures: Arc<HashMap<AclBinding, KafkaFutureImpl<()>>>,
1818    acl_creations: Vec<AclCreation>,
1819    acl_bindings_sent: Vec<AclBinding>,
1820    deadline: i64,
1821) -> Call {
1822    let create_request = Box::new(move |_timeout_ms: i32| {
1823        let mut data = CreateAclsRequestData::new();
1824        data.set_creations(acl_creations.clone());
1825        Ok(Box::new(create_acls_request::Builder::new(data)) as Box<dyn RequestBuilder>)
1826    });
1827
1828    let resp_mm = mm.clone();
1829    let resp_futures = Arc::clone(&futures);
1830    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
1831        let ConcreteResponse::CreateAcls(create_response) = response else {
1832            return HandleResult::Retry(Error::local_illegal_state("Expected a CreateAcls response"));
1833        };
1834        if let Some(err) = handle_not_controller_error(&resp_mm, &create_response.error_counts()) {
1835            return HandleResult::Retry(err);
1836        }
1837        let mut iter = create_response.results().iter();
1838        for binding in &acl_bindings_sent {
1839            let Some(future) = resp_futures.get(binding) else {
1840                continue;
1841            };
1842            match iter.next() {
1843                None => {
1844                    future.complete_with_error(Error::with_message(
1845                        Errors::UnknownServerError,
1846                        format!("The broker reported no creation result for the given ACL: {binding}"),
1847                    ));
1848                },
1849                Some(creation) => {
1850                    if Errors::for_code(creation.error_code) != Errors::None {
1851                        future.complete_with_error(api_error(creation.error_code, &creation.error_message));
1852                    } else {
1853                        future.complete(());
1854                    }
1855                },
1856            }
1857        }
1858        HandleResult::Done
1859    });
1860
1861    let fail_futures = Arc::clone(&futures);
1862    let handle_failure = Box::new(move |error: &Error| {
1863        for future in fail_futures.values() {
1864            future.complete_with_error(error.clone());
1865        }
1866    });
1867
1868    Call::new(
1869        "createAcls",
1870        deadline,
1871        NodeProvider::LeastLoadedBrokerOrActiveKController,
1872        create_request,
1873        handle_response,
1874        handle_failure,
1875        Box::new(|_| false),
1876    )
1877}
1878
1879/// Builds an `unregisterController` [`Call`]. Translated from the anonymous
1880/// `Call` in `KafkaAdminClient.unregisterController` (KAFKA-20395), which routes
1881/// through `LeastLoadedBrokerOrActiveKController`: a broker forwards the request
1882/// to the active controller (`UNREGISTER_CONTROLLER` is forwardable), and a
1883/// `bootstrap.controllers` client would send it to the active controller itself.
1884fn get_unregister_controller_call(
1885    controller_id: i32,
1886    handle: KafkaFutureImpl<()>,
1887    deadline: i64,
1888    log_context: LogContext,
1889) -> Call {
1890    let create_request = Box::new(move |_timeout_ms: i32| {
1891        let mut data = UnregisterControllerRequestData::new();
1892        data.set_controller_id(controller_id);
1893        Ok(Box::new(unregister_controller_request::Builder::new(data)) as Box<dyn RequestBuilder>)
1894    });
1895
1896    let resp_handle = handle.clone();
1897    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
1898        let ConcreteResponse::UnregisterController(unregister_response) = response else {
1899            return HandleResult::Retry(Error::local_illegal_state("Expected an UnregisterController response"));
1900        };
1901        let data = unregister_response.data();
1902        match Errors::for_code(data.error_code()) {
1903            Errors::None => {
1904                resp_handle.complete(());
1905            },
1906            // `throw error.exception(response.data().errorMessage())`: the throw
1907            // reaches `Call.fail`, which retries this retriable error until the
1908            // retry budget or the deadline runs out.
1909            Errors::RequestTimedOut => {
1910                return HandleResult::Retry(api_error(data.error_code(), data.error_message()));
1911            },
1912            _ => {
1913                kafka_error!(
1914                    log_context,
1915                    "Unregister controller request for controller ID {} failed: {}",
1916                    controller_id,
1917                    data.error_message().as_deref().unwrap_or("null")
1918                );
1919                resp_handle.complete_with_error(api_error(data.error_code(), data.error_message()));
1920            },
1921        }
1922        HandleResult::Done
1923    });
1924
1925    let fail_handle = handle;
1926    let handle_failure = Box::new(move |error: &Error| {
1927        fail_handle.complete_with_error(error.clone());
1928    });
1929
1930    Call::new(
1931        "unregisterController",
1932        deadline,
1933        NodeProvider::LeastLoadedBrokerOrActiveKController,
1934        create_request,
1935        handle_response,
1936        handle_failure,
1937        Box::new(|_| false),
1938    )
1939}
1940
1941/// Builds a `describeAcls` [`Call`]. Translated from the anonymous `Call` in
1942/// `KafkaAdminClient.describeAcls`.
1943fn get_describe_acls_call(filter: AclBindingFilter, handle: KafkaFutureImpl<Vec<AclBinding>>, deadline: i64) -> Call {
1944    let create_request = Box::new(move |_timeout_ms: i32| {
1945        Ok(Box::new(describe_acls_request::Builder::new(&filter)) as Box<dyn RequestBuilder>)
1946    });
1947
1948    let resp_handle = handle.clone();
1949    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
1950        let ConcreteResponse::DescribeAcls(describe_response) = response else {
1951            return HandleResult::Retry(Error::local_illegal_state("Expected a DescribeAcls response"));
1952        };
1953        if Errors::for_code(describe_response.error_code()) != Errors::None {
1954            resp_handle.complete_with_error(api_error(
1955                describe_response.error_code(),
1956                &describe_response.error_message().map(str::to_string),
1957            ));
1958        } else {
1959            match DescribeAclsResponse::acl_bindings(describe_response.acls()) {
1960                Ok(bindings) => {
1961                    resp_handle.complete(bindings);
1962                },
1963                Err(e) => {
1964                    resp_handle.complete_with_error(e);
1965                },
1966            }
1967        }
1968        HandleResult::Done
1969    });
1970
1971    let fail_handle = handle.clone();
1972    let handle_failure = Box::new(move |error: &Error| {
1973        fail_handle.complete_with_error(error.clone());
1974    });
1975
1976    Call::new(
1977        "describeAcls",
1978        deadline,
1979        NodeProvider::LeastLoadedBrokerOrActiveKController,
1980        create_request,
1981        handle_response,
1982        handle_failure,
1983        Box::new(|_| false),
1984    )
1985}
1986
1987/// Builds a `describeClientQuotas` [`Call`]. Translated from the anonymous
1988/// `Call` in `KafkaAdminClient.describeClientQuotas`.
1989fn get_describe_client_quotas_call(
1990    filter: ClientQuotaFilter,
1991    handle: KafkaFutureImpl<HashMap<ClientQuotaEntity, HashMap<String, f64>>>,
1992    deadline: i64,
1993) -> Call {
1994    let create_request = Box::new(move |_timeout_ms: i32| {
1995        Ok(Box::new(describe_client_quotas_request::Builder::new(&filter)) as Box<dyn RequestBuilder>)
1996    });
1997
1998    let resp_handle = handle.clone();
1999    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
2000        let ConcreteResponse::DescribeClientQuotas(describe_response) = response else {
2001            return HandleResult::Retry(Error::local_illegal_state("Expected a DescribeClientQuotas response"));
2002        };
2003        // Mirrors DescribeClientQuotasResponse.complete: error first, else the
2004        // decoded entity map.
2005        if Errors::for_code(describe_response.error_code()) != Errors::None {
2006            resp_handle.complete_with_error(api_error(
2007                describe_response.error_code(),
2008                &describe_response.error_message().map(str::to_string),
2009            ));
2010        } else {
2011            resp_handle.complete(describe_response.entities());
2012        }
2013        HandleResult::Done
2014    });
2015
2016    let fail_handle = handle.clone();
2017    let handle_failure = Box::new(move |error: &Error| {
2018        fail_handle.complete_with_error(error.clone());
2019    });
2020
2021    Call::new(
2022        "describeClientQuotas",
2023        deadline,
2024        NodeProvider::LeastLoaded,
2025        create_request,
2026        handle_response,
2027        handle_failure,
2028        Box::new(|_| false),
2029    )
2030}
2031
2032/// Builds an `alterClientQuotas` [`Call`]. Translated from the anonymous `Call`
2033/// in `KafkaAdminClient.alterClientQuotas`.
2034fn get_alter_client_quotas_call(
2035    entries: Vec<ClientQuotaAlteration>,
2036    validate_only: bool,
2037    futures: Arc<HashMap<ClientQuotaEntity, KafkaFutureImpl<()>>>,
2038    deadline: i64,
2039) -> Call {
2040    let request_entries = entries;
2041    let create_request = Box::new(move |_timeout_ms: i32| {
2042        Ok(
2043            Box::new(alter_client_quotas_request::Builder::new(&request_entries, validate_only))
2044                as Box<dyn RequestBuilder>,
2045        )
2046    });
2047
2048    let resp_futures = Arc::clone(&futures);
2049    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
2050        let ConcreteResponse::AlterClientQuotas(alter_response) = response else {
2051            return HandleResult::Retry(Error::local_illegal_state("Expected an AlterClientQuotas response"));
2052        };
2053        // Mirrors AlterClientQuotasResponse.complete: complete each entity's
2054        // future by its result.
2055        for (entity, outcome) in alter_response.results() {
2056            let Some(future) = resp_futures.get(&entity) else {
2057                // Java throws IllegalArgumentException if the future map lacks
2058                // the entity; the broker only echoes requested entities, so an
2059                // unknown entity is skipped rather than aborting the bg task.
2060                continue;
2061            };
2062            match outcome {
2063                Ok(()) => {
2064                    future.complete(());
2065                },
2066                Err(e) => {
2067                    future.complete_with_error(e);
2068                },
2069            }
2070        }
2071        HandleResult::Done
2072    });
2073
2074    let fail_futures = Arc::clone(&futures);
2075    let handle_failure = Box::new(move |error: &Error| {
2076        for future in fail_futures.values() {
2077            future.complete_with_error(error.clone());
2078        }
2079    });
2080
2081    Call::new(
2082        "alterClientQuotas",
2083        deadline,
2084        NodeProvider::LeastLoaded,
2085        create_request,
2086        handle_response,
2087        handle_failure,
2088        Box::new(|_| false),
2089    )
2090}
2091
2092/// Builds a `describeUserScramCredentials` [`Call`]. Translated from the
2093/// anonymous `Call` in `KafkaAdminClient.describeUserScramCredentials`.
2094fn get_describe_user_scram_credentials_call(
2095    users: Vec<String>,
2096    handle: KafkaFutureImpl<DescribeUserScramCredentialsResponseData>,
2097    deadline: i64,
2098) -> Call {
2099    let create_request = Box::new(move |_timeout_ms: i32| {
2100        let mut data = DescribeUserScramCredentialsRequestData::new();
2101        // Mirrors Java: only set users when the list is non-empty, skipping any
2102        // null entries; an empty/absent list describes all users.
2103        if !users.is_empty() {
2104            let user_names: Vec<UserName> = users
2105                .iter()
2106                .map(|user| {
2107                    let mut name = UserName::new();
2108                    name.set_name(user.clone());
2109                    name
2110                })
2111                .collect();
2112            if !user_names.is_empty() {
2113                data.set_users(Some(user_names));
2114            }
2115        }
2116        Ok(Box::new(describe_user_scram_credentials_request::Builder::new(data)) as Box<dyn RequestBuilder>)
2117    });
2118
2119    let resp_handle = handle.clone();
2120    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
2121        let ConcreteResponse::DescribeUserScramCredentials(describe_response) = response else {
2122            return HandleResult::Retry(Error::local_illegal_state("Expected a DescribeUserScramCredentials response"));
2123        };
2124        // Mirrors handleResponse: a message-level error fails the whole future,
2125        // otherwise the raw data is handed to the *Result view helpers.
2126        let data = describe_response.data();
2127        let message_level_error_code = data.error_code;
2128        if message_level_error_code != Errors::None.code() {
2129            resp_handle.complete_with_error(api_error(message_level_error_code, &data.error_message));
2130        } else {
2131            resp_handle.complete(data.clone());
2132        }
2133        HandleResult::Done
2134    });
2135
2136    let fail_handle = handle.clone();
2137    let handle_failure = Box::new(move |error: &Error| {
2138        fail_handle.complete_with_error(error.clone());
2139    });
2140
2141    Call::new(
2142        "describeUserScramCredentials",
2143        deadline,
2144        NodeProvider::LeastLoaded,
2145        create_request,
2146        handle_response,
2147        handle_failure,
2148        Box::new(|_| false),
2149    )
2150}
2151
2152/// Builds an `alterUserScramCredentials` [`Call`]. Translated from the anonymous
2153/// `Call` in `KafkaAdminClient.alterUserScramCredentials`.
2154fn get_alter_user_scram_credentials_call(
2155    deletions: Vec<ScramCredentialDeletion>,
2156    upsertions: Vec<ScramCredentialUpsertion>,
2157    illegal: Arc<HashMap<String, Error>>,
2158    futures: Arc<HashMap<String, KafkaFutureImpl<()>>>,
2159    metadata_manager: AdminMetadataManager,
2160    deadline: i64,
2161) -> Call {
2162    let create_request = Box::new(move |_timeout_ms: i32| {
2163        let mut data = AlterUserScramCredentialsRequestData::new();
2164        data.set_upsertions(upsertions.clone()).set_deletions(deletions.clone());
2165        Ok(Box::new(alter_user_scram_credentials_request::Builder::new(data)) as Box<dyn RequestBuilder>)
2166    });
2167
2168    let resp_mm = metadata_manager;
2169    let resp_illegal = Arc::clone(&illegal);
2170    let resp_futures = Arc::clone(&futures);
2171    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
2172        let ConcreteResponse::AlterUserScramCredentials(alter_response) = response else {
2173            return HandleResult::Retry(Error::local_illegal_state("Expected an AlterUserScramCredentials response"));
2174        };
2175        // Check for controller change first, so that all errors are consistent
2176        // in that case (mirrors the NOT_CONTROLLER handling before completion).
2177        if let Some(err) = handle_not_controller_error(&resp_mm, &alter_response.error_counts()) {
2178            return HandleResult::Retry(err);
2179        }
2180        // Now that we have the results for the ones we sent, fail any users that
2181        // have an illegal alteration as identified above.
2182        for (user, error) in resp_illegal.iter() {
2183            if let Some(future) = resp_futures.get(user) {
2184                future.complete_with_error(error.clone());
2185            }
2186        }
2187        for result in &alter_response.data().results {
2188            match resp_futures.get(&result.user) {
2189                None => {
2190                    log::warn!("Server response mentioned unknown user {}", result.user);
2191                },
2192                Some(future) => {
2193                    let error = Errors::for_code(result.error_code);
2194                    if error != Errors::None {
2195                        future.complete_with_error(api_error(result.error_code, &result.error_message));
2196                    } else {
2197                        future.complete(());
2198                    }
2199                },
2200            }
2201        }
2202        // Sanity check: the broker should send back a result for every user
2203        // (mirrors completeUnrealizedFutures).
2204        for (user, future) in resp_futures.iter() {
2205            if !future.is_done() {
2206                // Java's
2207                // `org.apache.kafka.clients.admin.KafkaAdminClient#completeUnrealizedFutures`
2208                // throws `new ApiException(..)` — the concrete base, not the
2209                // `UnknownServerException` subclass it uses elsewhere for response
2210                // sanity checks (in `KafkaAdminClient#createAcls`,
2211                // `KafkaAdminClient#deleteAcls` and
2212                // `KafkaAdminClient#alterPartitionReassignments`). Finding 246.
2213                future.complete_with_error(Error::Api(ApiError::new(format!(
2214                    "The broker response did not contain a result for user {user}"
2215                ))));
2216            }
2217        }
2218        HandleResult::Done
2219    });
2220
2221    let fail_futures = Arc::clone(&futures);
2222    let handle_failure = Box::new(move |error: &Error| {
2223        for future in fail_futures.values() {
2224            future.complete_with_error(error.clone());
2225        }
2226    });
2227
2228    Call::new(
2229        "alterUserScramCredentials",
2230        deadline,
2231        NodeProvider::Controller { supports_use_controllers: false },
2232        create_request,
2233        handle_response,
2234        handle_failure,
2235        Box::new(|_| false),
2236    )
2237}
2238
2239/// Builds the wire upsertion for a user, computing the salted password via
2240/// PBKDF2. Mirrors `KafkaAdminClient.getScramCredentialUpsertion` /
2241/// `getSaltedPassword`.
2242///
2243/// # Errors
2244///
2245/// Returns an [`Errors::UnsupportedSaslMechanism`] error if the public mechanism
2246/// has no internal SCRAM mapping (the Rust analog of Java's
2247/// `NoSuchAlgorithmException`), and a `LocalUnsupportedOperationError` when
2248/// the client was built without the `aws-lc-rs` feature, which provides PBKDF2.
2249#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#getScramCredentialUpsertion")]
2250fn get_scram_credential_upsertion(upsertion: &UserScramCredentialUpsertion) -> Result<ScramCredentialUpsertion, Error> {
2251    let public_mechanism = upsertion.credential_info().mechanism();
2252    let internal = InternalScramMechanism::for_mechanism_name(public_mechanism.mechanism_name())
2253        .ok_or_else(|| unsupported_sasl_mechanism("Unknown SCRAM mechanism"))?;
2254    let salted_password = get_salted_password(internal, upsertion)?;
2255    let mut wire = ScramCredentialUpsertion::new();
2256    wire.set_name(upsertion.user().to_string())
2257        .set_mechanism(public_mechanism.r#type())
2258        .set_iterations(upsertion.credential_info().iterations())
2259        .set_salt(upsertion.salt().to_vec())
2260        .set_salted_password(salted_password);
2261    Ok(wire)
2262}
2263
2264/// The SCRAM salted password of `upsertion`: `ScramFormatter.hi` over its
2265/// password, salt and iterations.
2266#[cfg(feature = "aws-lc-rs")]
2267#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#getSaltedPassword")]
2268fn get_salted_password(
2269    mechanism: InternalScramMechanism,
2270    upsertion: &UserScramCredentialUpsertion,
2271) -> Result<Vec<u8>, Error> {
2272    Ok(ScramFormatter::new(mechanism).hi(
2273        upsertion.password(),
2274        upsertion.salt(),
2275        upsertion.credential_info().iterations(),
2276    ))
2277}
2278
2279/// Without the `aws-lc-rs` feature the client has no PBKDF2, so an upsertion
2280/// fails, and with it only that user's future.
2281#[cfg(not(feature = "aws-lc-rs"))]
2282#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#getSaltedPassword")]
2283fn get_salted_password(
2284    _mechanism: InternalScramMechanism,
2285    _upsertion: &UserScramCredentialUpsertion,
2286) -> Result<Vec<u8>, Error> {
2287    Err(Error::local_unsupported_operation(SCRAM_UPSERTION_DISABLED_MESSAGE))
2288}
2289
2290/// The error message of a SCRAM credential upsertion on a client built
2291/// without the `aws-lc-rs` feature.
2292#[cfg(not(feature = "aws-lc-rs"))]
2293const SCRAM_UPSERTION_DISABLED_MESSAGE: &str =
2294    "SCRAM credential upsertion is not available: the client was built without the `aws-lc-rs` feature";
2295
2296/// Builds the wire deletion for a user. Mirrors
2297/// `KafkaAdminClient.getScramCredentialDeletion`.
2298#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#getScramCredentialDeletion")]
2299fn get_scram_credential_deletion(deletion: &UserScramCredentialDeletion) -> ScramCredentialDeletion {
2300    let mut wire = ScramCredentialDeletion::new();
2301    wire.set_name(deletion.user().to_string())
2302        .set_mechanism(deletion.mechanism().r#type());
2303    wire
2304}
2305
2306/// Mirrors `new UnacceptableCredentialException(message)`.
2307fn unacceptable_credential(message: &str) -> Error {
2308    Error::with_message(Errors::UnacceptableCredential, message)
2309}
2310
2311/// Mirrors `new UnsupportedSaslMechanismException(message)`.
2312fn unsupported_sasl_mechanism(message: &str) -> Error {
2313    Error::with_message(Errors::UnsupportedSaslMechanism, message)
2314}
2315
2316/// Builds a `createDelegationToken` [`Call`]. Translated from the anonymous
2317/// `Call` in `KafkaAdminClient.createDelegationToken`.
2318fn get_create_delegation_token_call(
2319    options: CreateDelegationTokenOptions,
2320    handle: KafkaFutureImpl<DelegationToken>,
2321    deadline: i64,
2322) -> Call {
2323    // The renewer principals are needed both to build the request and to
2324    // reconstruct the returned TokenInformation (Java uses `options.renewers()`
2325    // in handleResponse), so capture them once.
2326    let renewer_principals = options.renewers().to_vec();
2327    let owner = options.owner().cloned();
2328    let max_lifetime_ms = options.max_lifetime_ms();
2329
2330    let create_request = Box::new(move |_timeout_ms: i32| {
2331        let mut data = CreateDelegationTokenRequestData::new();
2332        data.max_lifetime_ms = max_lifetime_ms;
2333        data.renewers = renewer_principals
2334            .iter()
2335            .map(|principal| {
2336                let mut renewer = CreatableRenewers::new();
2337                renewer.principal_name = principal.name().to_string();
2338                renewer.principal_type = principal.principal_type().to_string();
2339                renewer
2340            })
2341            .collect();
2342        if let Some(owner) = &owner {
2343            data.owner_principal_name = Some(owner.name().to_string());
2344            data.owner_principal_type = Some(owner.principal_type().to_string());
2345        }
2346        Ok(Box::new(create_delegation_token_request::Builder::new(data)) as Box<dyn RequestBuilder>)
2347    });
2348
2349    let resp_handle = handle.clone();
2350    let resp_renewers = options.renewers().to_vec();
2351    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
2352        let ConcreteResponse::CreateDelegationToken(create_response) = response else {
2353            return HandleResult::Retry(Error::local_illegal_state("Expected a CreateDelegationToken response"));
2354        };
2355        // Mirrors CreateDelegationToken handleResponse: error first, else build
2356        // the TokenInformation / DelegationToken from the response data using
2357        // the requested renewers.
2358        if create_response.has_error() {
2359            resp_handle.complete_with_error(Error::new(create_response.error()));
2360        } else {
2361            let data = create_response.data();
2362            let token_info = TokenInformation::with_token_requester(
2363                data.token_id.clone(),
2364                KafkaPrincipal::new(data.principal_type.clone(), data.principal_name.clone()),
2365                KafkaPrincipal::new(
2366                    data.token_requester_principal_type.clone(),
2367                    data.token_requester_principal_name.clone(),
2368                ),
2369                resp_renewers.clone(),
2370                data.issue_timestamp_ms,
2371                data.max_timestamp_ms,
2372                data.expiry_timestamp_ms,
2373            );
2374            let token = DelegationToken::new(token_info, data.hmac.clone());
2375            resp_handle.complete(token);
2376        }
2377        HandleResult::Done
2378    });
2379
2380    let fail_handle = handle.clone();
2381    let handle_failure = Box::new(move |error: &Error| {
2382        fail_handle.complete_with_error(error.clone());
2383    });
2384
2385    Call::new(
2386        "createDelegationToken",
2387        deadline,
2388        NodeProvider::LeastLoaded,
2389        create_request,
2390        handle_response,
2391        handle_failure,
2392        Box::new(|_| false),
2393    )
2394}
2395
2396/// Builds a `renewDelegationToken` [`Call`]. Translated from the anonymous
2397/// `Call` in `KafkaAdminClient.renewDelegationToken`.
2398fn get_renew_delegation_token_call(
2399    hmac: Vec<u8>,
2400    renew_time_period_ms: i64,
2401    handle: KafkaFutureImpl<i64>,
2402    deadline: i64,
2403) -> Call {
2404    let create_request = Box::new(move |_timeout_ms: i32| {
2405        let mut data = RenewDelegationTokenRequestData::new();
2406        data.hmac = hmac.clone();
2407        data.renew_period_ms = renew_time_period_ms;
2408        Ok(Box::new(renew_delegation_token_request::Builder::new(data)) as Box<dyn RequestBuilder>)
2409    });
2410
2411    let resp_handle = handle.clone();
2412    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
2413        let ConcreteResponse::RenewDelegationToken(renew_response) = response else {
2414            return HandleResult::Retry(Error::local_illegal_state("Expected a RenewDelegationToken response"));
2415        };
2416        if renew_response.has_error() {
2417            resp_handle.complete_with_error(Error::new(renew_response.error()));
2418        } else {
2419            resp_handle.complete(renew_response.expiry_timestamp());
2420        }
2421        HandleResult::Done
2422    });
2423
2424    let fail_handle = handle.clone();
2425    let handle_failure = Box::new(move |error: &Error| {
2426        fail_handle.complete_with_error(error.clone());
2427    });
2428
2429    Call::new(
2430        "renewDelegationToken",
2431        deadline,
2432        NodeProvider::LeastLoaded,
2433        create_request,
2434        handle_response,
2435        handle_failure,
2436        Box::new(|_| false),
2437    )
2438}
2439
2440/// Builds an `expireDelegationToken` [`Call`]. Translated from the anonymous
2441/// `Call` in `KafkaAdminClient.expireDelegationToken`.
2442fn get_expire_delegation_token_call(
2443    hmac: Vec<u8>,
2444    expiry_time_period_ms: i64,
2445    handle: KafkaFutureImpl<i64>,
2446    deadline: i64,
2447) -> Call {
2448    let create_request = Box::new(move |_timeout_ms: i32| {
2449        let mut data = ExpireDelegationTokenRequestData::new();
2450        data.hmac = hmac.clone();
2451        data.expiry_time_period_ms = expiry_time_period_ms;
2452        Ok(Box::new(expire_delegation_token_request::Builder::new(data)) as Box<dyn RequestBuilder>)
2453    });
2454
2455    let resp_handle = handle.clone();
2456    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
2457        let ConcreteResponse::ExpireDelegationToken(expire_response) = response else {
2458            return HandleResult::Retry(Error::local_illegal_state("Expected an ExpireDelegationToken response"));
2459        };
2460        if expire_response.has_error() {
2461            resp_handle.complete_with_error(Error::new(expire_response.error()));
2462        } else {
2463            resp_handle.complete(expire_response.expiry_timestamp());
2464        }
2465        HandleResult::Done
2466    });
2467
2468    let fail_handle = handle.clone();
2469    let handle_failure = Box::new(move |error: &Error| {
2470        fail_handle.complete_with_error(error.clone());
2471    });
2472
2473    Call::new(
2474        "expireDelegationToken",
2475        deadline,
2476        NodeProvider::LeastLoaded,
2477        create_request,
2478        handle_response,
2479        handle_failure,
2480        Box::new(|_| false),
2481    )
2482}
2483
2484/// Builds a `describeDelegationToken` [`Call`]. Translated from the anonymous
2485/// `Call` in `KafkaAdminClient.describeDelegationToken`.
2486fn get_describe_delegation_token_call(
2487    owners: Option<Vec<KafkaPrincipal>>,
2488    handle: KafkaFutureImpl<Vec<DelegationToken>>,
2489    deadline: i64,
2490) -> Call {
2491    let create_request = Box::new(move |_timeout_ms: i32| {
2492        Ok(Box::new(describe_delegation_token_request::Builder::new(owners.as_deref())) as Box<dyn RequestBuilder>)
2493    });
2494
2495    let resp_handle = handle.clone();
2496    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
2497        let ConcreteResponse::DescribeDelegationToken(describe_response) = response else {
2498            return HandleResult::Retry(Error::local_illegal_state("Expected a DescribeDelegationToken response"));
2499        };
2500        if describe_response.has_error() {
2501            resp_handle.complete_with_error(Error::new(describe_response.error()));
2502        } else {
2503            resp_handle.complete(describe_response.tokens());
2504        }
2505        HandleResult::Done
2506    });
2507
2508    let fail_handle = handle.clone();
2509    let handle_failure = Box::new(move |error: &Error| {
2510        fail_handle.complete_with_error(error.clone());
2511    });
2512
2513    Call::new(
2514        "describeDelegationToken",
2515        deadline,
2516        NodeProvider::LeastLoaded,
2517        create_request,
2518        handle_response,
2519        handle_failure,
2520        Box::new(|_| false),
2521    )
2522}
2523
2524/// Builds a `deleteAcls` [`Call`]. Translated from the anonymous `Call` in
2525/// `KafkaAdminClient.deleteAcls`.
2526fn get_delete_acls_call(
2527    mm: AdminMetadataManager,
2528    futures: Arc<HashMap<AclBindingFilter, KafkaFutureImpl<FilterResults>>>,
2529    acl_binding_filters_sent: Vec<AclBindingFilter>,
2530    delete_acls_filters: Vec<DeleteAclsFilter>,
2531    deadline: i64,
2532) -> Call {
2533    let create_request = Box::new(move |_timeout_ms: i32| {
2534        let mut data = DeleteAclsRequestData::new();
2535        data.set_filters(delete_acls_filters.clone());
2536        Ok(Box::new(delete_acls_request::Builder::new(data)) as Box<dyn RequestBuilder>)
2537    });
2538
2539    let resp_mm = mm.clone();
2540    let resp_futures = Arc::clone(&futures);
2541    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
2542        let ConcreteResponse::DeleteAcls(delete_response) = response else {
2543            return HandleResult::Retry(Error::local_illegal_state("Expected a DeleteAcls response"));
2544        };
2545        if let Some(err) = handle_not_controller_error(&resp_mm, &delete_response.error_counts()) {
2546            return HandleResult::Retry(err);
2547        }
2548        let mut iter = delete_response.filter_results().iter();
2549        for binding_filter in &acl_binding_filters_sent {
2550            let Some(future) = resp_futures.get(binding_filter) else {
2551                continue;
2552            };
2553            match iter.next() {
2554                None => {
2555                    future.complete_with_error(Error::with_message(
2556                        Errors::UnknownServerError,
2557                        "The broker reported no deletion result for the given filter.",
2558                    ));
2559                },
2560                Some(filter_result) => {
2561                    if Errors::for_code(filter_result.error_code) != Errors::None {
2562                        future.complete_with_error(api_error(filter_result.error_code, &filter_result.error_message));
2563                    } else {
2564                        let mut results = Vec::new();
2565                        for matching_acl in &filter_result.matching_acls {
2566                            let binding = DeleteAclsResponse::acl_binding(matching_acl).ok();
2567                            let error = if Errors::for_code(matching_acl.error_code) != Errors::None {
2568                                Some(api_error(matching_acl.error_code, &matching_acl.error_message))
2569                            } else {
2570                                None
2571                            };
2572                            results.push(FilterResult::new(binding, error));
2573                        }
2574                        future.complete(FilterResults::new(results));
2575                    }
2576                },
2577            }
2578        }
2579        HandleResult::Done
2580    });
2581
2582    let fail_futures = Arc::clone(&futures);
2583    let handle_failure = Box::new(move |error: &Error| {
2584        for future in fail_futures.values() {
2585            future.complete_with_error(error.clone());
2586        }
2587    });
2588
2589    Call::new(
2590        "deleteAcls",
2591        deadline,
2592        NodeProvider::LeastLoadedBrokerOrActiveKController,
2593        create_request,
2594        handle_response,
2595        handle_failure,
2596        Box::new(|_| false),
2597    )
2598}
2599
2600/// Checks a create/delete response for a controller-change error, mirroring
2601/// `KafkaAdminClient.handleNotControllerError`. Returns the error to retry with
2602/// if the controller changed.
2603#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#handleNotControllerError")]
2604fn handle_not_controller_error(mm: &AdminMetadataManager, error_counts: &HashMap<Errors, i32>) -> Option<Error> {
2605    // Java dispatches on which code was present and rethrows `error.exception()`
2606    // for *that* code (in both overloads of
2607    // `org.apache.kafka.clients.admin.KafkaAdminClient#handleNotControllerError`),
2608    // so a `NOT_LEADER_OR_FOLLOWER` seen by a `bootstrap.controllers` client
2609    // surfaces as `NotLeaderOrFollower`, not `NotController` (finding 247).
2610    let matched = if error_counts.contains_key(&Errors::NotController) {
2611        Some(Errors::NotController)
2612    } else if mm.using_bootstrap_controllers() && error_counts.contains_key(&Errors::NotLeaderOrFollower) {
2613        Some(Errors::NotLeaderOrFollower)
2614    } else {
2615        None
2616    };
2617    if let Some(error) = matched {
2618        mm.clear_controller();
2619        mm.request_update();
2620        Some(Error::new(error))
2621    } else {
2622        None
2623    }
2624}
2625
2626/// Maps an [`OffsetSpec`] to the wire-protocol timestamp sentinel used by
2627/// `ListOffsets`.
2628///
2629/// Mirrors `KafkaAdminClient.getOffsetFromSpec`.
2630#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#getOffsetFromSpec")]
2631fn get_offset_from_spec(offset_spec: &OffsetSpec) -> i64 {
2632    use crate::common::requests::ListOffsetsRequest;
2633    match offset_spec {
2634        OffsetSpec::Timestamp(spec) => spec.timestamp(),
2635        OffsetSpec::Earliest => ListOffsetsRequest::EARLIEST_TIMESTAMP,
2636        OffsetSpec::MaxTimestamp => ListOffsetsRequest::MAX_TIMESTAMP,
2637        OffsetSpec::EarliestLocal => ListOffsetsRequest::EARLIEST_LOCAL_TIMESTAMP,
2638        OffsetSpec::LatestTiered => ListOffsetsRequest::LATEST_TIERED_TIMESTAMP,
2639        OffsetSpec::EarliestPendingUpload => ListOffsetsRequest::EARLIEST_PENDING_UPLOAD_TIMESTAMP,
2640        OffsetSpec::Latest => ListOffsetsRequest::LATEST_TIMESTAMP,
2641    }
2642}
2643
2644/// Builds the `alterPartitionReassignments` controller call.
2645///
2646/// Mirrors the anonymous `Call` in `KafkaAdminClient.alterPartitionReassignments`.
2647fn get_alter_partition_reassignments_call(
2648    mm: AdminMetadataManager,
2649    futures: Arc<HashMap<TopicPartition, KafkaFutureImpl<()>>>,
2650    topics_to_reassignments: Arc<
2651        std::collections::BTreeMap<String, std::collections::BTreeMap<i32, Option<NewPartitionReassignment>>>,
2652    >,
2653    allow_replication_factor_change: bool,
2654    expected_responses_count: usize,
2655    deadline: i64,
2656) -> Call {
2657    let req_topics = Arc::clone(&topics_to_reassignments);
2658    let create_request = Box::new(move |timeout_ms: i32| {
2659        let mut data = AlterPartitionReassignmentsRequestData::new();
2660        let mut topics = Vec::new();
2661        for (topic_name, partitions_to_reassignments) in req_topics.iter() {
2662            let mut reassignable_partitions = Vec::new();
2663            for (partition_index, reassignment) in partitions_to_reassignments {
2664                let mut reassignable_partition = ReassignablePartition::new();
2665                reassignable_partition.set_partition_index(*partition_index);
2666                reassignable_partition.set_replicas(reassignment.as_ref().map(|r| r.target_replicas().to_vec()));
2667                reassignable_partitions.push(reassignable_partition);
2668            }
2669            let mut reassignable_topic = ReassignableTopic::new();
2670            reassignable_topic.set_name(topic_name.clone());
2671            reassignable_topic.set_partitions(reassignable_partitions);
2672            topics.push(reassignable_topic);
2673        }
2674        data.set_topics(topics);
2675        data.set_timeout_ms(timeout_ms);
2676        data.set_allow_replication_factor_change(allow_replication_factor_change);
2677        Ok(Box::new(alter_partition_reassignments_request::Builder::new(data)) as Box<dyn RequestBuilder>)
2678    });
2679
2680    let resp_mm = mm.clone();
2681    let resp_futures = Arc::clone(&futures);
2682    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
2683        let ConcreteResponse::AlterPartitionReassignments(alter_response) = response else {
2684            return HandleResult::Retry(Error::local_illegal_state("Expected an AlterPartitionReassignments response"));
2685        };
2686        let data = alter_response.data();
2687        let mut errors: HashMap<TopicPartition, Option<Error>> = HashMap::new();
2688        let mut received_responses_count: usize = 0;
2689        let top_level_error = Errors::for_code(data.error_code);
2690        match top_level_error {
2691            Errors::None => {
2692                for topic_response in &data.responses {
2693                    for part_response in &topic_response.partitions {
2694                        let tp = TopicPartition::new(topic_response.name.as_str(), part_response.partition_index);
2695                        let partition_error = Errors::for_code(part_response.error_code);
2696                        if partition_error == Errors::None {
2697                            errors.insert(tp, None);
2698                        } else {
2699                            let message = part_response.error_message.as_deref();
2700                            errors.insert(tp, Some(partition_error.error_with_optional_message(message)));
2701                        }
2702                        received_responses_count += 1;
2703                    }
2704                }
2705            },
2706            Errors::NotController => {
2707                if let Some(err) = handle_not_controller_error(&resp_mm, &alter_response.error_counts()) {
2708                    return HandleResult::Retry(err);
2709                }
2710            },
2711            _ => {
2712                for topic_response in &data.responses {
2713                    for part_response in &topic_response.partitions {
2714                        let tp = TopicPartition::new(topic_response.name.as_str(), part_response.partition_index);
2715                        let message = data.error_message.as_deref();
2716                        errors.insert(tp, Some(top_level_error.error_with_optional_message(message)));
2717                        received_responses_count += 1;
2718                    }
2719                }
2720            },
2721        }
2722
2723        // assertResponseCountMatch: if the server returned an inconsistent
2724        // number of results, fail every future with an UnknownServerException.
2725        if errors.values().all(Option::is_none) && received_responses_count != expected_responses_count {
2726            let quantifier = if received_responses_count > expected_responses_count {
2727                "many"
2728            } else {
2729                "less"
2730            };
2731            let error = Error::with_message(
2732                Errors::UnknownServerError,
2733                format!(
2734                    "The server returned too {quantifier} results.Expected {expected_responses_count} but received {received_responses_count}"
2735                ),
2736            );
2737            for future in resp_futures.values() {
2738                future.complete_with_error(error.clone());
2739            }
2740            return HandleResult::Done;
2741        }
2742
2743        for (tp, error) in errors {
2744            let Some(future) = resp_futures.get(&tp) else {
2745                continue;
2746            };
2747            match error {
2748                None => {
2749                    future.complete(());
2750                },
2751                Some(error) => {
2752                    future.complete_with_error(error);
2753                },
2754            }
2755        }
2756        HandleResult::Done
2757    });
2758
2759    let fail_futures = Arc::clone(&futures);
2760    let handle_failure = Box::new(move |error: &Error| {
2761        for future in fail_futures.values() {
2762            future.complete_with_error(error.clone());
2763        }
2764    });
2765
2766    Call::new(
2767        "alterPartitionReassignments",
2768        deadline,
2769        // `new ControllerNodeProvider(true)`, as in `KafkaAdminClient#alterPartitionReassignments`.
2770        NodeProvider::Controller { supports_use_controllers: true },
2771        create_request,
2772        handle_response,
2773        handle_failure,
2774        Box::new(|_| false),
2775    )
2776}
2777
2778/// Builds the `listPartitionReassignments` controller call.
2779///
2780/// Mirrors the anonymous `Call` in `KafkaAdminClient.listPartitionReassignments`.
2781fn get_list_partition_reassignments_call(
2782    mm: AdminMetadataManager,
2783    handle: KafkaFutureImpl<HashMap<TopicPartition, PartitionReassignment>>,
2784    request_partitions: Option<Vec<TopicPartition>>,
2785    deadline: i64,
2786) -> Call {
2787    let req_partitions = request_partitions.clone();
2788    let create_request = Box::new(move |timeout_ms: i32| {
2789        let mut list_data = ListPartitionReassignmentsRequestData::new();
2790        list_data.set_timeout_ms(timeout_ms);
2791        if let Some(partitions) = &req_partitions {
2792            let mut topics_by_name: HashMap<String, ListPartitionReassignmentsTopics> = HashMap::new();
2793            for tp in partitions {
2794                let topic = topics_by_name.entry(tp.topic().to_string()).or_insert_with(|| {
2795                    let mut t = ListPartitionReassignmentsTopics::new();
2796                    t.set_name(tp.topic().to_string());
2797                    t
2798                });
2799                topic.partition_indexes.push(tp.partition());
2800            }
2801            list_data.set_topics(Some(topics_by_name.into_values().collect()));
2802        }
2803        Ok(Box::new(list_partition_reassignments_request::Builder::new(list_data)) as Box<dyn RequestBuilder>)
2804    });
2805
2806    let resp_mm = mm.clone();
2807    let resp_handle = handle.clone();
2808    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
2809        let ConcreteResponse::ListPartitionReassignments(list_response) = response else {
2810            return HandleResult::Retry(Error::local_illegal_state("Expected a ListPartitionReassignments response"));
2811        };
2812        let data = list_response.data();
2813        let error = Errors::for_code(data.error_code);
2814        match error {
2815            Errors::None => {},
2816            Errors::NotController => {
2817                if let Some(err) = handle_not_controller_error(&resp_mm, &list_response.error_counts()) {
2818                    return HandleResult::Retry(err);
2819                }
2820            },
2821            _ => {
2822                resp_handle.complete_with_error(error.error_with_optional_message(data.error_message.as_deref()));
2823            },
2824        }
2825        let mut reassignment_map: HashMap<TopicPartition, PartitionReassignment> = HashMap::new();
2826        for topic_reassignment in &data.topics {
2827            for partition_reassignment in &topic_reassignment.partitions {
2828                reassignment_map.insert(
2829                    TopicPartition::new(topic_reassignment.name.as_str(), partition_reassignment.partition_index),
2830                    PartitionReassignment::new(
2831                        partition_reassignment.replicas.clone(),
2832                        partition_reassignment.adding_replicas.clone(),
2833                        partition_reassignment.removing_replicas.clone(),
2834                    ),
2835                );
2836            }
2837        }
2838        // First-writer-wins: a no-op if the future was already failed above.
2839        resp_handle.complete(reassignment_map);
2840        HandleResult::Done
2841    });
2842
2843    let fail_handle = handle.clone();
2844    let handle_failure = Box::new(move |error: &Error| {
2845        fail_handle.complete_with_error(error.clone());
2846    });
2847
2848    Call::new(
2849        "listPartitionReassignments",
2850        deadline,
2851        // `new ControllerNodeProvider(true)`, as in `KafkaAdminClient#listPartitionReassignments`.
2852        NodeProvider::Controller { supports_use_controllers: true },
2853        create_request,
2854        handle_response,
2855        handle_failure,
2856        Box::new(|_| false),
2857    )
2858}
2859
2860/// Returns the broker id pertaining to the given resource, or `None` if the
2861/// resource is not associated with a particular broker.
2862///
2863/// Mirrors `KafkaAdminClient.nodeFor`.
2864#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#nodeFor")]
2865fn node_for(resource: &ConfigResource) -> Option<i32> {
2866    if (resource.r#type() == config_resource::Type::Broker && !resource.is_default())
2867        || resource.r#type() == config_resource::Type::BrokerLogger
2868    {
2869        // Java parses `Integer.valueOf(resource.name())`; a non-numeric name
2870        // would throw. Here a parse failure degrades to "any broker" rather
2871        // than panicking on a recoverable path (CLAUDE.md §12).
2872        resource.name().parse::<i32>().ok()
2873    } else {
2874        None
2875    }
2876}
2877
2878/// Converts a `DescribeConfigsResult` wire result into a [`Config`], mirroring
2879/// `KafkaAdminClient.describeConfigResult`.
2880#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#describeConfigResult")]
2881fn describe_config_result(result: &crate::describe_configs_response_data::DescribeConfigsResult) -> Config {
2882    Config::new(result.configs.iter().map(|config| {
2883        let synonyms = config
2884            .synonyms
2885            .iter()
2886            .map(|synonym| {
2887                ConfigSynonym::new(
2888                    synonym.name.clone(),
2889                    synonym.value.clone(),
2890                    ConfigSource::for_id(synonym.source),
2891                )
2892            })
2893            .collect();
2894        ConfigEntry::with_options(
2895            ConfigEntryOptionsBuilder::new()
2896                .set_name(config.name.clone())
2897                .set_value(config.value.clone())
2898                .set_source(ConfigSource::for_id(config.config_source))
2899                .set_is_sensitive(config.is_sensitive)
2900                .set_is_read_only(config.read_only)
2901                .set_synonyms(synonyms)
2902                .set_config_type(Some(ConfigType::for_id(config.config_type)))
2903                .set_documentation(config.documentation.clone())
2904                .build()
2905                .expect("ConfigEntryOptionsBuilder::build: every mandatory parameter is set above"),
2906        )
2907    }))
2908}
2909
2910/// Builds a `describeConfigs` [`Call`] for a set of resources routed to a single
2911/// node (`Some(broker)`) or the least-loaded broker (`None`). Translated from
2912/// the `Call` created inside `KafkaAdminClient.describeConfigs`.
2913fn get_describe_configs_call(
2914    node: Option<i32>,
2915    unified: Arc<HashMap<ConfigResource, KafkaFutureImpl<Config>>>,
2916    include_synonyms: bool,
2917    include_documentation: bool,
2918    deadline: i64,
2919) -> Call {
2920    let req_unified = Arc::clone(&unified);
2921    let create_request = Box::new(move |_timeout_ms: i32| {
2922        let resources = req_unified
2923            .keys()
2924            .map(|resource| {
2925                let mut r = DescribeConfigsResource::new();
2926                r.set_resource_name(resource.name().to_string());
2927                r.set_resource_type(resource.r#type().id());
2928                r.set_configuration_keys(None);
2929                r
2930            })
2931            .collect();
2932        let mut data = DescribeConfigsRequestData::new();
2933        data.set_resources(resources);
2934        data.set_include_synonyms(include_synonyms);
2935        data.set_include_documentation(include_documentation);
2936        Ok(Box::new(describe_configs_request::Builder::new(data)) as Box<dyn RequestBuilder>)
2937    });
2938
2939    let resp_unified = Arc::clone(&unified);
2940    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
2941        let ConcreteResponse::DescribeConfigs(describe_response) = response else {
2942            return HandleResult::Retry(Error::local_illegal_state("Expected a DescribeConfigs response"));
2943        };
2944        for (config_resource, result) in describe_response.result_map() {
2945            let Some(future) = resp_unified.get(&config_resource) else {
2946                // A config in the response that was not in the request; Java
2947                // logs a warning and ignores it.
2948                continue;
2949            };
2950            if result.error_code != Errors::None.code() {
2951                future.complete_with_error(api_error(result.error_code, &result.error_message));
2952            } else {
2953                future.complete(describe_config_result(result));
2954            }
2955        }
2956        // Complete any future for which the node did not return a result.
2957        for (resource, future) in resp_unified.iter() {
2958            if !future.is_done() {
2959                // Java's
2960                // `org.apache.kafka.clients.admin.KafkaAdminClient#completeUnrealizedFutures`
2961                // throws `new ApiException(..)` — the concrete base, not the
2962                // `UnknownServerException` subclass it uses elsewhere for response
2963                // sanity checks (in `KafkaAdminClient#createAcls`,
2964                // `KafkaAdminClient#deleteAcls` and
2965                // `KafkaAdminClient#alterPartitionReassignments`). Finding 246.
2966                future.complete_with_error(Error::Api(ApiError::new(format!(
2967                    "The node response did not contain a result for config resource {resource}"
2968                ))));
2969            }
2970        }
2971        HandleResult::Done
2972    });
2973
2974    let fail_unified = Arc::clone(&unified);
2975    let handle_failure = Box::new(move |error: &Error| {
2976        for future in fail_unified.values() {
2977            future.complete_with_error(error.clone());
2978        }
2979    });
2980
2981    // `node != null ? new ConstantNodeIdProvider(node, true) : new
2982    // LeastLoadedBrokerOrActiveKController()`, as in `KafkaAdminClient#describeConfigs`.
2983    let node_provider = match node {
2984        Some(node_id) => NodeProvider::ConstantNodeId { node_id, supports_use_controllers: true },
2985        None => NodeProvider::LeastLoadedBrokerOrActiveKController,
2986    };
2987
2988    Call::new(
2989        "describeConfigs",
2990        deadline,
2991        node_provider,
2992        create_request,
2993        handle_response,
2994        handle_failure,
2995        Box::new(|_| false),
2996    )
2997}
2998
2999/// Completes any future not yet realized, mirroring
3000/// `KafkaAdminClient.completeUnrealizedFutures`.
3001fn complete_unrealized<T: Clone + Send + Sync + 'static>(
3002    futures: &HashMap<String, KafkaFutureImpl<T>>,
3003    message: impl Fn(&str) -> String,
3004) {
3005    for (name, future) in futures {
3006        if !future.is_done() {
3007            // Java throws `new ApiException(messageFormatter.apply(key))` in
3008            // `org.apache.kafka.clients.admin.KafkaAdminClient#completeUnrealizedFutures` —
3009            // the concrete base class, NOT the `UnknownServerException` subclass
3010            // Java uses for the *other* response sanity checks (in
3011            // `KafkaAdminClient#createAcls`, `KafkaAdminClient#deleteAcls` and
3012            // `KafkaAdminClient#alterPartitionReassignments`). Finding 246.
3013            future.complete_with_error(Error::Api(ApiError::new(message(name))));
3014        }
3015    }
3016}
3017
3018// ---------------------------------------------------------------------------
3019// describeLogDirs / alterReplicaLogDirs / describeReplicaLogDirs
3020// ---------------------------------------------------------------------------
3021
3022/// Maps a protocol error code to an optional error, mirroring Java's
3023/// `Errors.forCode(code).exception()` which returns `null` for `NONE`.
3024fn api_error_for_code(error_code: i16) -> Option<Error> {
3025    let error = Errors::for_code(error_code);
3026    (error != Errors::None).then(|| Error::new(error))
3027}
3028
3029/// Builds a map from log-directory path to [`LogDirDescription`] from a
3030/// `DescribeLogDirs` response. Mirrors `KafkaAdminClient.logDirDescriptions`.
3031#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#logDirDescriptions")]
3032fn log_dir_descriptions(response: &DescribeLogDirsResponse) -> HashMap<String, LogDirDescription> {
3033    let mut result = HashMap::with_capacity(response.data().results.len());
3034    for log_dir_result in &response.data().results {
3035        let mut replica_info_map = HashMap::new();
3036        for t in &log_dir_result.topics {
3037            for p in &t.partitions {
3038                replica_info_map.insert(
3039                    TopicPartition::new(t.name.clone(), p.partition_index),
3040                    ReplicaInfo::new(p.partition_size, p.offset_lag, p.is_future_key),
3041                );
3042            }
3043        }
3044        result.insert(
3045            log_dir_result.log_dir.clone(),
3046            LogDirDescription::with_total_bytes_usable_bytes_is_cordoned(
3047                api_error_for_code(log_dir_result.error_code),
3048                replica_info_map,
3049                log_dir_result.total_bytes,
3050                log_dir_result.usable_bytes,
3051                log_dir_result.is_cordoned,
3052            ),
3053        );
3054    }
3055    result
3056}
3057
3058/// Builds a per-broker `describeLogDirs` [`Call`]. Mirrors the anonymous `Call`
3059/// in `KafkaAdminClient.describeLogDirs`.
3060fn get_describe_log_dirs_call(
3061    broker_id: i32,
3062    handle: KafkaFutureImpl<HashMap<String, LogDirDescription>>,
3063    deadline: i64,
3064) -> Call {
3065    let create_request = Box::new(move |_timeout_ms: i32| {
3066        // Query selected partitions in all log directories (topics == null).
3067        let mut data = DescribeLogDirsRequestData::new();
3068        data.set_topics(None);
3069        Ok(Box::new(describe_log_dirs_request::Builder::new(data)) as Box<dyn RequestBuilder>)
3070    });
3071
3072    let resp_handle = handle.clone();
3073    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
3074        let ConcreteResponse::DescribeLogDirs(resp) = response else {
3075            return HandleResult::Retry(Error::local_illegal_state("Expected a DescribeLogDirs response"));
3076        };
3077        let descriptions = log_dir_descriptions(resp);
3078        if !descriptions.is_empty() {
3079            resp_handle.complete(descriptions);
3080        } else {
3081            // Up to v3 DescribeLogDirsResponse did not have an error code field,
3082            // hence it defaults to NONE.
3083            let error = if resp.data().error_code == Errors::None.code() {
3084                Errors::ClusterAuthorizationFailed
3085            } else {
3086                Errors::for_code(resp.data().error_code)
3087            };
3088            resp_handle.complete_with_error(Error::new(error));
3089        }
3090        HandleResult::Done
3091    });
3092
3093    let fail_handle = handle;
3094    let handle_failure = Box::new(move |error: &Error| {
3095        fail_handle.complete_with_error(error.clone());
3096    });
3097
3098    Call::new(
3099        "describeLogDirs",
3100        deadline,
3101        NodeProvider::ConstantNodeId { node_id: broker_id, supports_use_controllers: false },
3102        create_request,
3103        handle_response,
3104        handle_failure,
3105        Box::new(|_| false),
3106    )
3107}
3108
3109/// Builds a per-broker `alterReplicaLogDirs` [`Call`]. Mirrors the anonymous
3110/// `Call` in `KafkaAdminClient.alterReplicaLogDirs`. `futures` is shared across
3111/// all per-broker calls; each call only completes the replicas targeting its
3112/// own broker.
3113fn get_alter_replica_log_dirs_call(
3114    broker_id: i32,
3115    assignment: AlterReplicaLogDirsRequestData,
3116    futures: Arc<HashMap<TopicPartitionReplica, KafkaFutureImpl<()>>>,
3117    deadline: i64,
3118) -> Call {
3119    let create_request = Box::new(move |_timeout_ms: i32| {
3120        Ok(Box::new(alter_replica_log_dirs_request::Builder::new(assignment.clone())) as Box<dyn RequestBuilder>)
3121    });
3122
3123    let resp_futures = Arc::clone(&futures);
3124    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
3125        let ConcreteResponse::AlterReplicaLogDirs(resp) = response else {
3126            return HandleResult::Retry(Error::local_illegal_state("Expected an AlterReplicaLogDirs response"));
3127        };
3128        for topic_result in &resp.data().results {
3129            for partition_result in &topic_result.partitions {
3130                let replica = TopicPartitionReplica::new(
3131                    topic_result.topic_name.clone(),
3132                    partition_result.partition_index,
3133                    broker_id,
3134                );
3135                match resp_futures.get(&replica) {
3136                    // The partition in the response was not in the request;
3137                    // Java logs a warning and ignores it.
3138                    None => {},
3139                    Some(future) => {
3140                        if partition_result.error_code == Errors::None.code() {
3141                            future.complete(());
3142                        } else {
3143                            future.complete_with_error(Error::new(Errors::for_code(partition_result.error_code)));
3144                        }
3145                    },
3146                }
3147            }
3148        }
3149        // The server should send back a result for every replica. Do a sanity
3150        // check anyway (mirrors `completeUnrealizedFutures`).
3151        for (replica, future) in resp_futures.iter() {
3152            if replica.broker_id() == broker_id && !future.is_done() {
3153                // Java's
3154                // `org.apache.kafka.clients.admin.KafkaAdminClient#completeUnrealizedFutures`
3155                // throws `new ApiException(..)` — the concrete base, not the
3156                // `UnknownServerException` subclass it uses elsewhere for response
3157                // sanity checks (in `KafkaAdminClient#createAcls`,
3158                // `KafkaAdminClient#deleteAcls` and
3159                // `KafkaAdminClient#alterPartitionReassignments`). Finding 246.
3160                future.complete_with_error(Error::Api(ApiError::new(format!(
3161                    "The response from broker {broker_id} did not contain a result for replica {replica}"
3162                ))));
3163            }
3164        }
3165        HandleResult::Done
3166    });
3167
3168    let fail_futures = Arc::clone(&futures);
3169    let handle_failure = Box::new(move |error: &Error| {
3170        // Only completes the futures of brokerId.
3171        for (replica, future) in fail_futures.iter() {
3172            if replica.broker_id() == broker_id {
3173                future.complete_with_error(error.clone());
3174            }
3175        }
3176    });
3177
3178    Call::new(
3179        "alterReplicaLogDirs",
3180        deadline,
3181        NodeProvider::ConstantNodeId { node_id: broker_id, supports_use_controllers: false },
3182        create_request,
3183        handle_response,
3184        handle_failure,
3185        Box::new(|_| false),
3186    )
3187}
3188
3189/// Builds a per-broker `describeReplicaLogDirs` [`Call`]. Mirrors the anonymous
3190/// `Call` in `KafkaAdminClient.describeReplicaLogDirs`, which reshapes a
3191/// `DescribeLogDirs` response into per-replica `ReplicaLogDirInfo`s.
3192fn get_describe_replica_log_dirs_call(
3193    broker_id: i32,
3194    request_data: DescribeLogDirsRequestData,
3195    mut replica_dir_info_by_partition: HashMap<TopicPartition, ReplicaLogDirInfo>,
3196    futures: Arc<HashMap<TopicPartitionReplica, KafkaFutureImpl<ReplicaLogDirInfo>>>,
3197    deadline: i64,
3198) -> Call {
3199    let create_request = Box::new(move |_timeout_ms: i32| {
3200        // Query selected partitions in all log directories.
3201        Ok(Box::new(describe_log_dirs_request::Builder::new(request_data.clone())) as Box<dyn RequestBuilder>)
3202    });
3203
3204    let resp_futures = Arc::clone(&futures);
3205    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
3206        let ConcreteResponse::DescribeLogDirs(resp) = response else {
3207            return HandleResult::Retry(Error::local_illegal_state("Expected a DescribeLogDirs response"));
3208        };
3209        for (log_dir, log_dir_info) in log_dir_descriptions(resp) {
3210            if let Some(error) = log_dir_info.error() {
3211                // No replica info is provided if the log directory is offline.
3212                if error.error() == Errors::KafkaStorageError {
3213                    continue;
3214                }
3215                // Any other error for a log directory is illegal (mirrors Java's
3216                // `handleFailure(new IllegalStateException(...))`, which fails
3217                // every replica future).
3218                let illegal = Error::local_illegal_state(format!(
3219                    "The error {:?} for log directory {log_dir} in the response from broker {broker_id} is illegal",
3220                    error.error()
3221                ));
3222                for future in resp_futures.values() {
3223                    future.complete_with_error(illegal.clone());
3224                }
3225            }
3226
3227            for (tp, replica_info) in log_dir_info.replica_infos() {
3228                let Some(existing) = replica_dir_info_by_partition.get(tp) else {
3229                    // Server response mentioned an unknown partition; Java logs
3230                    // a warning.
3231                    continue;
3232                };
3233                let updated = if replica_info.is_future() {
3234                    ReplicaLogDirInfo::new(
3235                        existing.current_replica_log_dir().map(String::from),
3236                        existing.current_replica_offset_lag(),
3237                        Some(log_dir.clone()),
3238                        replica_info.offset_lag(),
3239                    )
3240                } else {
3241                    ReplicaLogDirInfo::new(
3242                        Some(log_dir.clone()),
3243                        replica_info.offset_lag(),
3244                        existing.future_replica_log_dir().map(String::from),
3245                        existing.future_replica_offset_lag(),
3246                    )
3247                };
3248                replica_dir_info_by_partition.insert(tp.clone(), updated);
3249            }
3250        }
3251
3252        for (tp, info) in &replica_dir_info_by_partition {
3253            let replica = TopicPartitionReplica::new(tp.topic().to_string(), tp.partition(), broker_id);
3254            if let Some(future) = resp_futures.get(&replica) {
3255                future.complete(info.clone());
3256            }
3257        }
3258        HandleResult::Done
3259    });
3260
3261    let fail_futures = Arc::clone(&futures);
3262    let handle_failure = Box::new(move |error: &Error| {
3263        for future in fail_futures.values() {
3264            future.complete_with_error(error.clone());
3265        }
3266    });
3267
3268    Call::new(
3269        "describeReplicaLogDirs",
3270        deadline,
3271        NodeProvider::ConstantNodeId { node_id: broker_id, supports_use_controllers: false },
3272        create_request,
3273        handle_response,
3274        handle_failure,
3275        Box::new(|_| false),
3276    )
3277}
3278
3279/// Builds a [`TopicDescription`] from cluster metadata, mirroring
3280/// `KafkaAdminClient.getTopicDescriptionFromCluster`.
3281#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#getTopicDescriptionFromCluster")]
3282fn topic_description_from_cluster(
3283    cluster: &Cluster,
3284    topic_name: &str,
3285    topic_id: Uuid,
3286    authorized_operations: i32,
3287) -> TopicDescription {
3288    let is_internal = cluster.internal_topics().contains(topic_name);
3289    let mut partitions: Vec<TopicPartitionInfo> = cluster
3290        .partitions_for_topic(topic_name)
3291        .iter()
3292        .map(|p| {
3293            let leader = match p.leader() {
3294                Some(node) if !node.is_empty() => Some(node.clone()),
3295                _ => None,
3296            };
3297            TopicPartitionInfo::new(p.partition(), leader, p.replicas().to_vec(), p.in_sync_replicas().to_vec())
3298        })
3299        .collect();
3300    partitions.sort_by_key(|p| p.partition());
3301    TopicDescription::with_authorized_operations_topic_id(
3302        topic_name,
3303        is_internal,
3304        partitions,
3305        AdminUtils::valid_acl_operations(authorized_operations),
3306        topic_id,
3307    )
3308}
3309
3310// ---------------------------------------------------------------------------
3311// createTopics
3312// ---------------------------------------------------------------------------
3313
3314/// Builds a `createTopics` [`Call`]. Free function so the quota-retry path can
3315/// rebuild a fresh call with the same futures. Translated from
3316/// `KafkaAdminClient.getCreateTopicsCall`.
3317#[expect(clippy::too_many_arguments)]
3318#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#getCreateTopicsCall")]
3319fn get_create_topics_call(
3320    mm: AdminMetadataManager,
3321    futures: Arc<HashMap<String, KafkaFutureImpl<TopicMetadataAndConfig>>>,
3322    topics_by_name: Arc<HashMap<String, CreatableTopic>>,
3323    names: Vec<String>,
3324    quota_exceeded_errors: HashMap<String, Error>,
3325    validate_only: bool,
3326    retry_on_quota: bool,
3327    now: i64,
3328    deadline: i64,
3329    time: Arc<dyn Time>,
3330) -> Call {
3331    let req_names = names.clone();
3332    let req_topics = Arc::clone(&topics_by_name);
3333    let create_request = Box::new(move |timeout_ms: i32| {
3334        let mut data = CreateTopicsRequestData::new();
3335        let topics: Vec<CreatableTopic> = req_names.iter().filter_map(|n| req_topics.get(n).cloned()).collect();
3336        data.set_topics(topics);
3337        data.set_timeout_ms(timeout_ms);
3338        data.set_validate_only(validate_only);
3339        Ok(Box::new(create_topics_request::Builder::new(data)) as Box<dyn RequestBuilder>)
3340    });
3341
3342    let resp_mm = mm.clone();
3343    let resp_futures = Arc::clone(&futures);
3344    let resp_topics = Arc::clone(&topics_by_name);
3345    let resp_time = Arc::clone(&time);
3346    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
3347        let ConcreteResponse::CreateTopics(create_response) = response else {
3348            return HandleResult::Retry(Error::local_illegal_state("Expected a CreateTopics response"));
3349        };
3350        if let Some(err) = handle_not_controller_error(&resp_mm, &create_response.error_counts()) {
3351            return HandleResult::Retry(err);
3352        }
3353        let throttle_time_ms = create_response.throttle_time_ms();
3354        let mut retry_names: Vec<String> = Vec::new();
3355        let mut retry_quota_exceeded: HashMap<String, Error> = HashMap::new();
3356        for result in &create_response.data().topics {
3357            let Some(future) = resp_futures.get(&result.name) else {
3358                continue;
3359            };
3360            let error = Errors::for_code(result.error_code);
3361            if error != Errors::None {
3362                if error == Errors::ThrottlingQuotaExceeded {
3363                    let quota_error = Error::throttling_quota_exceeded(
3364                        throttle_time_ms,
3365                        KafkaAdminClient::message_with_fallback(result.error_code, &result.error_message),
3366                    );
3367                    if retry_on_quota {
3368                        retry_names.push(result.name.clone());
3369                        retry_quota_exceeded.insert(result.name.clone(), quota_error);
3370                    } else {
3371                        future.complete_with_error(quota_error);
3372                    }
3373                } else {
3374                    future.complete_with_error(api_error(result.error_code, &result.error_message));
3375                }
3376            } else if result.topic_config_error_code != Errors::None.code() {
3377                future.complete(TopicMetadataAndConfig::with_error(Error::new(Errors::for_code(
3378                    result.topic_config_error_code,
3379                ))));
3380            } else if result.num_partitions == CreateTopicsResult::UNKNOWN {
3381                future.complete(TopicMetadataAndConfig::with_error(Error::unsupported_version(
3382                    "Topic metadata and configs in CreateTopics response not supported",
3383                )));
3384            } else {
3385                let config = result
3386                    .configs
3387                    .as_ref()
3388                    .map(|configs| {
3389                        Config::new(configs.iter().map(|c| {
3390                            ConfigEntry::with_options(
3391                                ConfigEntryOptionsBuilder::new()
3392                                    .set_name(c.name.clone())
3393                                    .set_value(c.value.clone())
3394                                    .set_source(ConfigSource::for_id(c.config_source))
3395                                    .set_is_sensitive(c.is_sensitive)
3396                                    .set_is_read_only(c.read_only)
3397                                    // Java passes `null` for the type and the
3398                                    // documentation (the `configEntry` helper of `KafkaAdminClient#getCreateTopicsCall`).
3399                                    .set_config_type(None)
3400                                    .build()
3401                                    .expect("ConfigEntryOptionsBuilder::build: every mandatory parameter is set above"),
3402                            )
3403                        }))
3404                    })
3405                    .unwrap_or_else(|| Config::new(std::iter::empty()));
3406                future.complete(TopicMetadataAndConfig::new(
3407                    result.topic_id,
3408                    result.num_partitions,
3409                    result.replication_factor as i32,
3410                    config,
3411                ));
3412            }
3413        }
3414        if retry_names.is_empty() {
3415            complete_unrealized(&resp_futures, |topic| {
3416                format!("The controller response did not contain a result for topic {topic}")
3417            });
3418            HandleResult::Done
3419        } else {
3420            let retry_now = resp_time.milliseconds();
3421            let call = get_create_topics_call(
3422                resp_mm.clone(),
3423                Arc::clone(&resp_futures),
3424                Arc::clone(&resp_topics),
3425                retry_names,
3426                retry_quota_exceeded,
3427                validate_only,
3428                retry_on_quota,
3429                retry_now,
3430                deadline,
3431                Arc::clone(&resp_time),
3432            );
3433            HandleResult::NewCall(Box::new(call))
3434        }
3435    });
3436
3437    let fail_futures = Arc::clone(&futures);
3438    let fail_time = Arc::clone(&time);
3439    let handle_failure = Box::new(move |error: &Error| {
3440        // If there were any topics retried due to a quota exceeded exception,
3441        // propagate the initial error back to the caller if the request timed
3442        // out (mirrors maybeCompleteQuotaExceededException).
3443        let throttle_time_delta = (fail_time.milliseconds() - now).clamp(0, i32::MAX as i64) as i32;
3444        maybe_complete_quota_exceeded(
3445            retry_on_quota,
3446            error,
3447            &fail_futures,
3448            &quota_exceeded_errors,
3449            throttle_time_delta,
3450        );
3451        for future in fail_futures.values() {
3452            future.complete_with_error(error.clone());
3453        }
3454    });
3455
3456    Call::new(
3457        "createTopics",
3458        deadline,
3459        NodeProvider::Controller { supports_use_controllers: false },
3460        create_request,
3461        handle_response,
3462        handle_failure,
3463        Box::new(|_| false),
3464    )
3465}
3466
3467// ---------------------------------------------------------------------------
3468// createPartitions
3469// ---------------------------------------------------------------------------
3470
3471/// Builds a `createPartitions` [`Call`]. Free function so the quota-retry path
3472/// can rebuild a fresh call with the same futures. Translated from
3473/// `KafkaAdminClient.getCreatePartitionsCall`.
3474#[expect(clippy::too_many_arguments)]
3475#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#getCreatePartitionsCall")]
3476fn get_create_partitions_call(
3477    mm: AdminMetadataManager,
3478    futures: Arc<HashMap<String, KafkaFutureImpl<()>>>,
3479    topics_by_name: Arc<HashMap<String, CreatePartitionsTopic>>,
3480    names: Vec<String>,
3481    quota_exceeded_errors: HashMap<String, Error>,
3482    validate_only: bool,
3483    retry_on_quota: bool,
3484    now: i64,
3485    deadline: i64,
3486    time: Arc<dyn Time>,
3487) -> Call {
3488    let req_names = names.clone();
3489    let req_topics = Arc::clone(&topics_by_name);
3490    let create_request = Box::new(move |timeout_ms: i32| {
3491        let mut data = CreatePartitionsRequestData::new();
3492        let topics: Vec<CreatePartitionsTopic> = req_names.iter().filter_map(|n| req_topics.get(n).cloned()).collect();
3493        data.set_topics(topics);
3494        data.set_timeout_ms(timeout_ms);
3495        data.set_validate_only(validate_only);
3496        Ok(Box::new(create_partitions_request::Builder::new(data)) as Box<dyn RequestBuilder>)
3497    });
3498
3499    let resp_mm = mm.clone();
3500    let resp_futures = Arc::clone(&futures);
3501    let resp_topics = Arc::clone(&topics_by_name);
3502    let resp_time = Arc::clone(&time);
3503    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
3504        let ConcreteResponse::CreatePartitions(create_response) = response else {
3505            return HandleResult::Retry(Error::local_illegal_state("Expected a CreatePartitions response"));
3506        };
3507        if let Some(err) = handle_not_controller_error(&resp_mm, &create_response.error_counts()) {
3508            return HandleResult::Retry(err);
3509        }
3510        let throttle_time_ms = create_response.throttle_time_ms();
3511        let mut retry_names: Vec<String> = Vec::new();
3512        let mut retry_quota_exceeded: HashMap<String, Error> = HashMap::new();
3513        for result in &create_response.data().results {
3514            let Some(future) = resp_futures.get(&result.name) else {
3515                continue;
3516            };
3517            let error = Errors::for_code(result.error_code);
3518            if error != Errors::None {
3519                if error == Errors::ThrottlingQuotaExceeded {
3520                    let quota_error = Error::throttling_quota_exceeded(
3521                        throttle_time_ms,
3522                        KafkaAdminClient::message_with_fallback(result.error_code, &result.error_message),
3523                    );
3524                    if retry_on_quota {
3525                        retry_names.push(result.name.clone());
3526                        retry_quota_exceeded.insert(result.name.clone(), quota_error);
3527                    } else {
3528                        future.complete_with_error(quota_error);
3529                    }
3530                } else {
3531                    future.complete_with_error(api_error(result.error_code, &result.error_message));
3532                }
3533            } else {
3534                future.complete(());
3535            }
3536        }
3537        if retry_names.is_empty() {
3538            complete_unrealized(&resp_futures, |topic| {
3539                format!("The controller response did not contain a result for topic {topic}")
3540            });
3541            HandleResult::Done
3542        } else {
3543            let retry_now = resp_time.milliseconds();
3544            let call = get_create_partitions_call(
3545                resp_mm.clone(),
3546                Arc::clone(&resp_futures),
3547                Arc::clone(&resp_topics),
3548                retry_names,
3549                retry_quota_exceeded,
3550                validate_only,
3551                retry_on_quota,
3552                retry_now,
3553                deadline,
3554                Arc::clone(&resp_time),
3555            );
3556            HandleResult::NewCall(Box::new(call))
3557        }
3558    });
3559
3560    let fail_futures = Arc::clone(&futures);
3561    let fail_time = Arc::clone(&time);
3562    let handle_failure = Box::new(move |error: &Error| {
3563        let throttle_time_delta = (fail_time.milliseconds() - now).clamp(0, i32::MAX as i64) as i32;
3564        maybe_complete_quota_exceeded(
3565            retry_on_quota,
3566            error,
3567            &fail_futures,
3568            &quota_exceeded_errors,
3569            throttle_time_delta,
3570        );
3571        for future in fail_futures.values() {
3572            future.complete_with_error(error.clone());
3573        }
3574    });
3575
3576    Call::new(
3577        "createPartitions",
3578        deadline,
3579        NodeProvider::Controller { supports_use_controllers: false },
3580        create_request,
3581        handle_response,
3582        handle_failure,
3583        Box::new(|_| false),
3584    )
3585}
3586
3587// ---------------------------------------------------------------------------
3588// deleteTopics
3589// ---------------------------------------------------------------------------
3590
3591/// Builds a `deleteTopics` (by name) [`Call`]. Translated from
3592/// `KafkaAdminClient.getDeleteTopicsCall`.
3593#[expect(clippy::too_many_arguments)]
3594#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#getDeleteTopicsCall")]
3595fn get_delete_topics_call(
3596    mm: AdminMetadataManager,
3597    futures: Arc<HashMap<String, KafkaFutureImpl<()>>>,
3598    names: Vec<String>,
3599    quota_exceeded_errors: HashMap<String, Error>,
3600    retry_on_quota: bool,
3601    now: i64,
3602    deadline: i64,
3603    time: Arc<dyn Time>,
3604) -> Call {
3605    let req_names = names.clone();
3606    let create_request = Box::new(move |timeout_ms: i32| {
3607        let mut data = DeleteTopicsRequestData::new();
3608        data.set_topic_names(req_names.clone());
3609        data.set_timeout_ms(timeout_ms);
3610        Ok(Box::new(delete_topics_request::Builder::new(data)) as Box<dyn RequestBuilder>)
3611    });
3612
3613    let resp_mm = mm.clone();
3614    let resp_futures = Arc::clone(&futures);
3615    let resp_time = Arc::clone(&time);
3616    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
3617        let ConcreteResponse::DeleteTopics(delete_response) = response else {
3618            return HandleResult::Retry(Error::local_illegal_state("Expected a DeleteTopics response"));
3619        };
3620        if let Some(err) = handle_not_controller_error(&resp_mm, &delete_response.error_counts()) {
3621            return HandleResult::Retry(err);
3622        }
3623        let throttle_time_ms = delete_response.throttle_time_ms();
3624        let mut retry_names: Vec<String> = Vec::new();
3625        let mut retry_quota_exceeded: HashMap<String, Error> = HashMap::new();
3626        for result in &delete_response.data().responses {
3627            let Some(name) = result.name.as_ref() else {
3628                continue;
3629            };
3630            let Some(future) = resp_futures.get(name) else {
3631                continue;
3632            };
3633            let error = Errors::for_code(result.error_code);
3634            if error != Errors::None {
3635                if error == Errors::ThrottlingQuotaExceeded {
3636                    let quota_error = Error::throttling_quota_exceeded(
3637                        throttle_time_ms,
3638                        KafkaAdminClient::message_with_fallback(result.error_code, &result.error_message),
3639                    );
3640                    if retry_on_quota {
3641                        retry_names.push(name.clone());
3642                        retry_quota_exceeded.insert(name.clone(), quota_error);
3643                    } else {
3644                        future.complete_with_error(quota_error);
3645                    }
3646                } else {
3647                    future.complete_with_error(api_error(result.error_code, &result.error_message));
3648                }
3649            } else {
3650                future.complete(());
3651            }
3652        }
3653        if retry_names.is_empty() {
3654            complete_unrealized(&resp_futures, |topic| {
3655                format!("The controller response did not contain a result for topic {topic}")
3656            });
3657            HandleResult::Done
3658        } else {
3659            let retry_now = resp_time.milliseconds();
3660            let call = get_delete_topics_call(
3661                resp_mm.clone(),
3662                Arc::clone(&resp_futures),
3663                retry_names,
3664                retry_quota_exceeded,
3665                retry_on_quota,
3666                retry_now,
3667                deadline,
3668                Arc::clone(&resp_time),
3669            );
3670            HandleResult::NewCall(Box::new(call))
3671        }
3672    });
3673
3674    let fail_futures = Arc::clone(&futures);
3675    let fail_time = Arc::clone(&time);
3676    let handle_failure = Box::new(move |error: &Error| {
3677        let throttle_time_delta = (fail_time.milliseconds() - now).clamp(0, i32::MAX as i64) as i32;
3678        maybe_complete_quota_exceeded(
3679            retry_on_quota,
3680            error,
3681            &fail_futures,
3682            &quota_exceeded_errors,
3683            throttle_time_delta,
3684        );
3685        for future in fail_futures.values() {
3686            future.complete_with_error(error.clone());
3687        }
3688    });
3689
3690    Call::new(
3691        "deleteTopics",
3692        deadline,
3693        NodeProvider::Controller { supports_use_controllers: false },
3694        create_request,
3695        handle_response,
3696        handle_failure,
3697        Box::new(|_| false),
3698    )
3699}
3700
3701/// Builds a `deleteTopics` (by id) [`Call`]. Translated from
3702/// `KafkaAdminClient.getDeleteTopicsWithIdsCall`.
3703#[expect(clippy::too_many_arguments)]
3704#[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClient#getDeleteTopicsWithIdsCall")]
3705fn get_delete_topics_with_ids_call(
3706    mm: AdminMetadataManager,
3707    futures: Arc<HashMap<Uuid, KafkaFutureImpl<()>>>,
3708    ids: Vec<Uuid>,
3709    quota_exceeded_errors: HashMap<Uuid, Error>,
3710    retry_on_quota: bool,
3711    now: i64,
3712    deadline: i64,
3713    time: Arc<dyn Time>,
3714) -> Call {
3715    let req_ids = ids.clone();
3716    let create_request = Box::new(move |timeout_ms: i32| {
3717        let mut data = DeleteTopicsRequestData::new();
3718        let states: Vec<DeleteTopicState> = req_ids
3719            .iter()
3720            .map(|id| {
3721                let mut s = DeleteTopicState::new();
3722                s.set_topic_id(*id);
3723                s
3724            })
3725            .collect();
3726        data.set_topics(states);
3727        data.set_timeout_ms(timeout_ms);
3728        Ok(Box::new(delete_topics_request::Builder::new(data)) as Box<dyn RequestBuilder>)
3729    });
3730
3731    let resp_mm = mm.clone();
3732    let resp_futures = Arc::clone(&futures);
3733    let resp_time = Arc::clone(&time);
3734    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
3735        let ConcreteResponse::DeleteTopics(delete_response) = response else {
3736            return HandleResult::Retry(Error::local_illegal_state("Expected a DeleteTopics response"));
3737        };
3738        if let Some(err) = handle_not_controller_error(&resp_mm, &delete_response.error_counts()) {
3739            return HandleResult::Retry(err);
3740        }
3741        let throttle_time_ms = delete_response.throttle_time_ms();
3742        let mut retry_ids: Vec<Uuid> = Vec::new();
3743        let mut retry_quota_exceeded: HashMap<Uuid, Error> = HashMap::new();
3744        for result in &delete_response.data().responses {
3745            let Some(future) = resp_futures.get(&result.topic_id) else {
3746                continue;
3747            };
3748            let error = Errors::for_code(result.error_code);
3749            if error != Errors::None {
3750                if error == Errors::ThrottlingQuotaExceeded {
3751                    let quota_error = Error::throttling_quota_exceeded(
3752                        throttle_time_ms,
3753                        KafkaAdminClient::message_with_fallback(result.error_code, &result.error_message),
3754                    );
3755                    if retry_on_quota {
3756                        retry_ids.push(result.topic_id);
3757                        retry_quota_exceeded.insert(result.topic_id, quota_error);
3758                    } else {
3759                        future.complete_with_error(quota_error);
3760                    }
3761                } else {
3762                    future.complete_with_error(api_error(result.error_code, &result.error_message));
3763                }
3764            } else {
3765                future.complete(());
3766            }
3767        }
3768        // Complete any unrealized id-keyed future.
3769        if retry_ids.is_empty() {
3770            for (id, future) in resp_futures.iter() {
3771                if !future.is_done() {
3772                    // Java's
3773                    // `org.apache.kafka.clients.admin.KafkaAdminClient#completeUnrealizedFutures`
3774                    // throws `new ApiException(..)` — the concrete base, not the
3775                    // `UnknownServerException` subclass it uses elsewhere for response
3776                    // sanity checks (in `KafkaAdminClient#createAcls`,
3777                    // `KafkaAdminClient#deleteAcls` and
3778                    // `KafkaAdminClient#alterPartitionReassignments`). Finding 246.
3779                    future.complete_with_error(Error::Api(ApiError::new(format!(
3780                        "The controller response did not contain a result for topic {id}"
3781                    ))));
3782                }
3783            }
3784            HandleResult::Done
3785        } else {
3786            let retry_now = resp_time.milliseconds();
3787            let call = get_delete_topics_with_ids_call(
3788                resp_mm.clone(),
3789                Arc::clone(&resp_futures),
3790                retry_ids,
3791                retry_quota_exceeded,
3792                retry_on_quota,
3793                retry_now,
3794                deadline,
3795                Arc::clone(&resp_time),
3796            );
3797            HandleResult::NewCall(Box::new(call))
3798        }
3799    });
3800
3801    let fail_futures = Arc::clone(&futures);
3802    let fail_time = Arc::clone(&time);
3803    let handle_failure = Box::new(move |error: &Error| {
3804        let throttle_time_delta = (fail_time.milliseconds() - now).clamp(0, i32::MAX as i64) as i32;
3805        maybe_complete_quota_exceeded(
3806            retry_on_quota,
3807            error,
3808            &fail_futures,
3809            &quota_exceeded_errors,
3810            throttle_time_delta,
3811        );
3812        for future in fail_futures.values() {
3813            future.complete_with_error(error.clone());
3814        }
3815    });
3816
3817    Call::new(
3818        "deleteTopics",
3819        deadline,
3820        NodeProvider::Controller { supports_use_controllers: false },
3821        create_request,
3822        handle_response,
3823        handle_failure,
3824        Box::new(|_| false),
3825    )
3826}
3827
3828#[async_trait]
3829impl Admin for KafkaAdminClient {
3830    fn create_topics_with_options(&self, new_topics: &[NewTopic], options: CreateTopicsOptions) -> CreateTopicsResult {
3831        let now = self.now();
3832        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
3833
3834        let mut handles: HashMap<String, KafkaFutureImpl<TopicMetadataAndConfig>> = HashMap::new();
3835        let mut topics_by_name: HashMap<String, CreatableTopic> = HashMap::new();
3836        for new_topic in new_topics {
3837            let name = new_topic.name().to_string();
3838            if topic_name_is_unrepresentable(&name) {
3839                let future: KafkaFutureImpl<TopicMetadataAndConfig> = KafkaFutureImpl::new();
3840                future.complete_with_error(Error::with_message(
3841                    Errors::InvalidTopicError,
3842                    format!("The given topic name '{name}' cannot be represented in a request."),
3843                ));
3844                handles.insert(name, future);
3845            } else if let std::collections::hash_map::Entry::Vacant(entry) = handles.entry(name.clone()) {
3846                entry.insert(KafkaFutureImpl::new());
3847                topics_by_name.insert(name, new_topic.convert_to_creatable_topic());
3848            }
3849        }
3850        let public: HashMap<String, KafkaFuture<TopicMetadataAndConfig>> =
3851            handles.iter().map(|(k, v)| (k.clone(), v.future())).collect();
3852
3853        if !topics_by_name.is_empty() {
3854            let names: Vec<String> = topics_by_name.keys().cloned().collect();
3855            let call = get_create_topics_call(
3856                self.shared.metadata_manager.clone(),
3857                Arc::new(handles),
3858                Arc::new(topics_by_name),
3859                names,
3860                HashMap::new(),
3861                options.should_validate_only(),
3862                options.should_retry_on_quota_violation(),
3863                now,
3864                deadline,
3865                Arc::clone(&self.shared.time),
3866            );
3867            self.submit(call);
3868        }
3869        CreateTopicsResult::new(public)
3870    }
3871
3872    fn delete_topics_with_topic_collection_options(
3873        &self,
3874        topics: TopicCollection,
3875        options: DeleteTopicsOptions,
3876    ) -> DeleteTopicsResult {
3877        let now = self.now();
3878        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
3879        match topics {
3880            TopicCollection::TopicNames(collection) => {
3881                let mut handles: HashMap<String, KafkaFutureImpl<()>> = HashMap::new();
3882                let mut valid_topic_names: Vec<String> = Vec::new();
3883                for name in collection.topic_names() {
3884                    if topic_name_is_unrepresentable(name) {
3885                        let future: KafkaFutureImpl<()> = KafkaFutureImpl::new();
3886                        future.complete_with_error(Error::with_message(
3887                            Errors::InvalidTopicError,
3888                            format!("The given topic name '{name}' cannot be represented in a request."),
3889                        ));
3890                        handles.insert(name.clone(), future);
3891                    } else if let std::collections::hash_map::Entry::Vacant(entry) = handles.entry(name.clone()) {
3892                        entry.insert(KafkaFutureImpl::new());
3893                        valid_topic_names.push(name.clone());
3894                    }
3895                }
3896                let public: HashMap<String, KafkaFuture<()>> =
3897                    handles.iter().map(|(k, v)| (k.clone(), v.future())).collect();
3898                if !valid_topic_names.is_empty() {
3899                    let call = get_delete_topics_call(
3900                        self.shared.metadata_manager.clone(),
3901                        Arc::new(handles),
3902                        valid_topic_names,
3903                        HashMap::new(),
3904                        options.should_retry_on_quota_violation(),
3905                        now,
3906                        deadline,
3907                        Arc::clone(&self.shared.time),
3908                    );
3909                    self.submit(call);
3910                }
3911                DeleteTopicsResult::of_topic_names(public)
3912            },
3913            TopicCollection::TopicIds(collection) => {
3914                let mut handles: HashMap<Uuid, KafkaFutureImpl<()>> = HashMap::new();
3915                let mut valid_topic_ids: Vec<Uuid> = Vec::new();
3916                for id in collection.topic_ids() {
3917                    if topic_id_is_unrepresentable(*id) {
3918                        let future: KafkaFutureImpl<()> = KafkaFutureImpl::new();
3919                        future.complete_with_error(Error::with_message(
3920                            Errors::InvalidTopicError,
3921                            format!("The given topic ID '{id}' cannot be represented in a request."),
3922                        ));
3923                        handles.insert(*id, future);
3924                    } else if let std::collections::hash_map::Entry::Vacant(entry) = handles.entry(*id) {
3925                        entry.insert(KafkaFutureImpl::new());
3926                        valid_topic_ids.push(*id);
3927                    }
3928                }
3929                let public: HashMap<Uuid, KafkaFuture<()>> = handles.iter().map(|(k, v)| (*k, v.future())).collect();
3930                if !valid_topic_ids.is_empty() {
3931                    let call = get_delete_topics_with_ids_call(
3932                        self.shared.metadata_manager.clone(),
3933                        Arc::new(handles),
3934                        valid_topic_ids,
3935                        HashMap::new(),
3936                        options.should_retry_on_quota_violation(),
3937                        now,
3938                        deadline,
3939                        Arc::clone(&self.shared.time),
3940                    );
3941                    self.submit(call);
3942                }
3943                DeleteTopicsResult::of_topic_ids(public)
3944            },
3945        }
3946    }
3947
3948    fn list_topics_with_options(&self, options: ListTopicsOptions) -> ListTopicsResult {
3949        let now = self.now();
3950        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
3951        let handle: KafkaFutureImpl<HashMap<String, TopicListing>> = KafkaFutureImpl::new();
3952        let public = handle.future();
3953        let list_internal = options.should_list_internal();
3954
3955        let create_request = Box::new(move |_timeout_ms: i32| {
3956            Ok(Box::new(metadata_request::Builder::all_topics()) as Box<dyn RequestBuilder>)
3957        });
3958
3959        let resp_handle = handle.clone();
3960        let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
3961            let ConcreteResponse::Metadata(metadata_response) = response else {
3962                return HandleResult::Retry(Error::local_illegal_state("Expected a Metadata response"));
3963            };
3964            let mut topics: HashMap<String, TopicListing> = HashMap::new();
3965            for topic in metadata_response.topic_metadata() {
3966                if topic.error() != Errors::None {
3967                    continue;
3968                }
3969                if topic.is_internal() && !list_internal {
3970                    continue;
3971                }
3972                topics.insert(
3973                    topic.topic().to_string(),
3974                    TopicListing::new(topic.topic().to_string(), topic.topic_id(), topic.is_internal()),
3975                );
3976            }
3977            resp_handle.complete(topics);
3978            HandleResult::Done
3979        });
3980
3981        let fail_handle = handle.clone();
3982        let handle_failure = Box::new(move |error: &Error| {
3983            fail_handle.complete_with_error(error.clone());
3984        });
3985
3986        let call = Call::new(
3987            "listTopics",
3988            deadline,
3989            NodeProvider::LeastLoaded,
3990            create_request,
3991            handle_response,
3992            handle_failure,
3993            Box::new(|_| false),
3994        );
3995        self.submit(call);
3996        ListTopicsResult::new(public)
3997    }
3998
3999    fn describe_topics_with_topics_options(
4000        &self,
4001        topics: TopicCollection,
4002        options: DescribeTopicsOptions,
4003    ) -> DescribeTopicsResult {
4004        match topics {
4005            TopicCollection::TopicNames(collection) => DescribeTopicsResult::of_topic_names(
4006                self.handle_describe_topics_by_names_with_describe_topic_partitions_api(
4007                    collection.topic_names(),
4008                    &options,
4009                ),
4010            ),
4011            TopicCollection::TopicIds(collection) => {
4012                // Describing by id uses the Metadata API in Java too
4013                // (handleDescribeTopicsByIds → convertTopicIdsToMetadataRequestTopic),
4014                // not DescribeTopicPartitions, so it is translated faithfully here.
4015                let mut handles: HashMap<Uuid, KafkaFutureImpl<TopicDescription>> = HashMap::new();
4016                let mut valid_topic_ids: Vec<Uuid> = Vec::new();
4017                for id in collection.topic_ids() {
4018                    if topic_id_is_unrepresentable(*id) {
4019                        let future: KafkaFutureImpl<TopicDescription> = KafkaFutureImpl::new();
4020                        future.complete_with_error(Error::with_message(
4021                            Errors::InvalidTopicError,
4022                            format!("The given topic id '{id}' cannot be represented in a request."),
4023                        ));
4024                        handles.insert(*id, future);
4025                    } else if let std::collections::hash_map::Entry::Vacant(entry) = handles.entry(*id) {
4026                        entry.insert(KafkaFutureImpl::new());
4027                        valid_topic_ids.push(*id);
4028                    }
4029                }
4030                let public: HashMap<Uuid, KafkaFuture<TopicDescription>> =
4031                    handles.iter().map(|(k, v)| (*k, v.future())).collect();
4032                if !valid_topic_ids.is_empty() {
4033                    let now = self.now();
4034                    let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4035                    let call = get_describe_topics_by_ids_call(
4036                        Arc::new(handles),
4037                        valid_topic_ids,
4038                        options.include_authorized_operations(),
4039                        deadline,
4040                    );
4041                    self.submit(call);
4042                }
4043                DescribeTopicsResult::of_topic_ids(public)
4044            },
4045        }
4046    }
4047
4048    fn create_partitions_with_options(
4049        &self,
4050        new_partitions: &HashMap<String, NewPartitions>,
4051        options: CreatePartitionsOptions,
4052    ) -> CreatePartitionsResult {
4053        let mut handles: HashMap<String, KafkaFutureImpl<()>> = HashMap::new();
4054        let mut topics_by_name: HashMap<String, CreatePartitionsTopic> = HashMap::new();
4055        for (topic, new_partition) in new_partitions {
4056            let assignments = new_partition.assignments().map(|new_assignments| {
4057                new_assignments
4058                    .iter()
4059                    .map(|broker_ids| {
4060                        let mut a = CreatePartitionsAssignment::new();
4061                        a.set_broker_ids(broker_ids.clone());
4062                        a
4063                    })
4064                    .collect::<Vec<_>>()
4065            });
4066            let mut created = CreatePartitionsTopic::new();
4067            created.set_name(topic.clone());
4068            created.set_count(new_partition.total_count());
4069            created.set_assignments(assignments);
4070            topics_by_name.insert(topic.clone(), created);
4071            handles.insert(topic.clone(), KafkaFutureImpl::new());
4072        }
4073        let public: HashMap<String, KafkaFuture<()>> = handles.iter().map(|(k, v)| (k.clone(), v.future())).collect();
4074
4075        if !topics_by_name.is_empty() {
4076            let now = self.now();
4077            let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4078            let names: Vec<String> = topics_by_name.keys().cloned().collect();
4079            let call = get_create_partitions_call(
4080                self.shared.metadata_manager.clone(),
4081                Arc::new(handles),
4082                Arc::new(topics_by_name),
4083                names,
4084                HashMap::new(),
4085                options.validate_only(),
4086                options.should_retry_on_quota_violation(),
4087                now,
4088                deadline,
4089                Arc::clone(&self.shared.time),
4090            );
4091            self.submit(call);
4092        }
4093        CreatePartitionsResult::new(public)
4094    }
4095
4096    fn delete_records_with_options(
4097        &self,
4098        records_to_delete: &HashMap<TopicPartition, RecordsToDelete>,
4099        options: DeleteRecordsOptions,
4100    ) -> DeleteRecordsResult {
4101        let keys: std::collections::HashSet<TopicPartition> = records_to_delete.keys().cloned().collect();
4102        let future = DeleteRecordsHandler::new_future(keys, Arc::clone(&self.shared.partition_leader_cache));
4103        let result_map = future.all();
4104
4105        let timeout_ms = options.timeout_ms().unwrap_or(self.shared.default_api_timeout_ms);
4106        let handler = DeleteRecordsHandler::new(
4107            records_to_delete.clone(),
4108            LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id)),
4109            timeout_ms,
4110        );
4111
4112        let now = self.now();
4113        // Java calc: calcDeadlineMs(now, options.timeoutMs()) — the raw option
4114        // (which may be null → default), not the resolved handler timeout.
4115        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4116        let retry_backoff = ExponentialBackoff::new(
4117            self.shared.retry_backoff_ms,
4118            RETRY_BACKOFF_EXP_BASE,
4119            self.shared.retry_backoff_max_ms,
4120            RETRY_BACKOFF_JITTER,
4121        )
4122        .expect("ExponentialBackoff::new only fails on invalid jitter");
4123        let driver = AdminApiDriver::new(
4124            Box::new(handler),
4125            Box::new(future),
4126            deadline,
4127            retry_backoff,
4128            LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id)),
4129        );
4130        invoke_driver(driver, self.driver_context(), now);
4131
4132        DeleteRecordsResult::new(result_map)
4133    }
4134
4135    fn describe_producers_with_options(
4136        &self,
4137        partitions: &[TopicPartition],
4138        options: DescribeProducersOptions,
4139    ) -> DescribeProducersResult {
4140        let keys: std::collections::HashSet<TopicPartition> = partitions.iter().cloned().collect();
4141        let future = DescribeProducersHandler::new_future(keys, Arc::clone(&self.shared.partition_leader_cache));
4142        let result_map = future.all();
4143
4144        let log_context = LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id));
4145        let handler = DescribeProducersHandler::new(options.clone(), log_context.clone());
4146
4147        let now = self.now();
4148        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4149        let retry_backoff = self.retry_backoff();
4150        let driver = AdminApiDriver::new(Box::new(handler), Box::new(future), deadline, retry_backoff, log_context);
4151        invoke_driver(driver, self.driver_context(), now);
4152
4153        DescribeProducersResult::new(result_map)
4154    }
4155
4156    fn unregister_controller_with_options(
4157        &self,
4158        controller_id: i32,
4159        options: UnregisterControllerOptions,
4160    ) -> UnregisterControllerResult {
4161        let handle: KafkaFutureImpl<()> = KafkaFutureImpl::new();
4162        let public = handle.future();
4163        let now = self.now();
4164        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4165        let call = get_unregister_controller_call(controller_id, handle, deadline, self.shared.log_context.clone());
4166        self.submit(call);
4167        UnregisterControllerResult::new(public)
4168    }
4169
4170    fn abort_transaction_with_options(
4171        &self,
4172        spec: AbortTransactionSpec,
4173        options: AbortTransactionOptions,
4174    ) -> AbortTransactionResult {
4175        let keys = std::collections::HashSet::from([spec.topic_partition().clone()]);
4176        let future = AbortTransactionHandler::new_future(keys, Arc::clone(&self.shared.partition_leader_cache));
4177        let result_map = future.all();
4178
4179        let log_context = LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id));
4180        let handler = AbortTransactionHandler::new(spec, log_context.clone());
4181
4182        let now = self.now();
4183        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4184        let retry_backoff = self.retry_backoff();
4185        let driver = AdminApiDriver::new(Box::new(handler), Box::new(future), deadline, retry_backoff, log_context);
4186        invoke_driver(driver, self.driver_context(), now);
4187
4188        AbortTransactionResult::new(result_map)
4189    }
4190
4191    fn describe_transactions_with_options(
4192        &self,
4193        transactional_ids: &[String],
4194        options: DescribeTransactionsOptions,
4195    ) -> DescribeTransactionsResult {
4196        let log_context = LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id));
4197        let future = DescribeTransactionsHandler::new_future(transactional_ids);
4198        let result_map = future.all();
4199        let handler = DescribeTransactionsHandler::new(log_context.clone());
4200
4201        let now = self.now();
4202        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4203        let retry_backoff = self.retry_backoff();
4204        let driver = AdminApiDriver::new(Box::new(handler), Box::new(future), deadline, retry_backoff, log_context);
4205        invoke_driver(driver, self.driver_context(), now);
4206
4207        DescribeTransactionsResult::new(coordinator_keyed_by_id(result_map))
4208    }
4209
4210    fn fence_producers_with_options(
4211        &self,
4212        transactional_ids: &[String],
4213        options: FenceProducersOptions,
4214    ) -> FenceProducersResult {
4215        let log_context = LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id));
4216        let future = FenceProducersHandler::new_future(transactional_ids);
4217        let result_map = future.all();
4218        let handler = FenceProducersHandler::new(&options, log_context.clone(), self.shared.request_timeout_ms);
4219
4220        let now = self.now();
4221        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4222        let retry_backoff = self.retry_backoff();
4223        let driver = AdminApiDriver::new(Box::new(handler), Box::new(future), deadline, retry_backoff, log_context);
4224        invoke_driver(driver, self.driver_context(), now);
4225
4226        FenceProducersResult::new(coordinator_keyed_by_id(result_map))
4227    }
4228
4229    fn list_transactions_with_options(&self, options: ListTransactionsOptions) -> ListTransactionsResult {
4230        let log_context = LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id));
4231        let future = ListTransactionsHandler::new_future();
4232        let result_future = future.all();
4233
4234        let now = self.now();
4235        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4236        let handler = ListTransactionsHandler::new(options, log_context.clone());
4237        let retry_backoff = self.retry_backoff();
4238        let driver = AdminApiDriver::new(Box::new(handler), Box::new(future), deadline, retry_backoff, log_context);
4239        invoke_driver(driver, self.driver_context(), now);
4240
4241        ListTransactionsResult::new(result_future)
4242    }
4243
4244    fn force_terminate_transaction_with_options(
4245        &self,
4246        transactional_id: &str,
4247        options: TerminateTransactionOptions,
4248    ) -> TerminateTransactionResult {
4249        // Simply leverage the existing fenceProducers implementation with a
4250        // single transactional id (mirrors Java's forceTerminateTransaction).
4251        let mut fence_options = FenceProducersOptions::new();
4252        if options.timeout_ms().is_some() {
4253            fence_options = fence_options.set_timeout_ms(options.timeout_ms());
4254        }
4255        let ids = vec![transactional_id.to_string()];
4256        let fence_result = self.fence_producers_with_options(&ids, fence_options);
4257
4258        // Convert the result to a TerminateTransactionResult.
4259        let future = fence_result
4260            .fenced_producers()
4261            .get(transactional_id)
4262            .cloned()
4263            .expect("the transactional id was included in the fenceProducers request");
4264        TerminateTransactionResult::new(future)
4265    }
4266
4267    fn describe_cluster_with_options(&self, options: DescribeClusterOptions) -> DescribeClusterResult {
4268        self.describe_cluster_with_nodes_handle(options).0
4269    }
4270
4271    fn describe_configs_with_options(
4272        &self,
4273        config_resources: &[ConfigResource],
4274        options: DescribeConfigsOptions,
4275    ) -> DescribeConfigsResult {
4276        // Partition the requested config resources based on which broker they
4277        // must be sent to (null broker == obtainable from any broker).
4278        let mut node_futures: HashMap<Option<i32>, HashMap<ConfigResource, KafkaFutureImpl<Config>>> = HashMap::new();
4279        for resource in config_resources {
4280            let broker = node_for(resource);
4281            node_futures
4282                .entry(broker)
4283                .or_default()
4284                .insert(resource.clone(), KafkaFutureImpl::new());
4285        }
4286
4287        let now = self.now();
4288        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4289        let include_synonyms = options.include_synonyms();
4290        let include_documentation = options.include_documentation();
4291
4292        let mut public: HashMap<ConfigResource, KafkaFuture<Config>> = HashMap::new();
4293        for (node, unified) in &node_futures {
4294            for (resource, handle) in unified {
4295                public.insert(resource.clone(), handle.future());
4296            }
4297            let call = get_describe_configs_call(
4298                *node,
4299                Arc::new(unified.clone()),
4300                include_synonyms,
4301                include_documentation,
4302                deadline,
4303            );
4304            self.submit(call);
4305        }
4306
4307        DescribeConfigsResult::new(public)
4308    }
4309
4310    fn incremental_alter_configs_with_options(
4311        &self,
4312        configs: &HashMap<ConfigResource, Vec<AlterConfigOp>>,
4313        options: AlterConfigsOptions,
4314    ) -> AlterConfigsResult {
4315        let mut all_futures: HashMap<ConfigResource, KafkaFuture<()>> = HashMap::new();
4316        // BROKER_LOGGER requests always go to a specific, constant broker or controller node.
4317        //
4318        // BROKER resource changes for a specific (non-default) resource go to either that specific
4319        // node (if using bootstrap.servers), or directly to the active controller (if using
4320        // bootstrap.controllers)
4321        //
4322        // All other requests go to the least loaded broker (if using bootstrap.servers) or the
4323        // active controller (if using bootstrap.controllers)
4324        let mut unified_request_resources: Vec<ConfigResource> = Vec::new();
4325
4326        for resource in configs.keys() {
4327            let mut node = node_for(resource);
4328            if self.shared.metadata_manager.using_bootstrap_controllers()
4329                && resource.r#type() != config_resource::Type::BrokerLogger
4330            {
4331                node = None;
4332            }
4333            if let Some(node_id) = node {
4334                let futures = self.submit_incremental_alter_configs(
4335                    configs,
4336                    &options,
4337                    std::slice::from_ref(resource),
4338                    // `new ConstantNodeIdProvider(node, true)`, as in
4339                    // `KafkaAdminClient#incrementalAlterConfigs`.
4340                    NodeProvider::ConstantNodeId { node_id, supports_use_controllers: true },
4341                );
4342                all_futures.extend(futures);
4343            } else {
4344                unified_request_resources.push(resource.clone());
4345            }
4346        }
4347        if !unified_request_resources.is_empty() {
4348            let futures = self.submit_incremental_alter_configs(
4349                configs,
4350                &options,
4351                &unified_request_resources,
4352                NodeProvider::LeastLoadedBrokerOrActiveKController,
4353            );
4354            all_futures.extend(futures);
4355        }
4356
4357        AlterConfigsResult::new(all_futures)
4358    }
4359
4360    fn list_config_resources_with_options(
4361        &self,
4362        config_resource_types: &HashSet<config_resource::Type>,
4363        options: ListConfigResourcesOptions,
4364    ) -> ListConfigResourcesResult {
4365        let now = self.now();
4366        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4367        let handle: KafkaFutureImpl<Vec<ConfigResource>> = KafkaFutureImpl::new();
4368        let public = handle.future();
4369
4370        let resource_type_ids: Vec<i8> = config_resource_types.iter().map(config_resource::Type::id).collect();
4371        let create_request = Box::new(move |_timeout_ms: i32| {
4372            let mut data = ListConfigResourcesRequestData::new();
4373            data.set_resource_types(resource_type_ids.clone());
4374            Ok(Box::new(list_config_resources_request::Builder::new(data)) as Box<dyn RequestBuilder>)
4375        });
4376
4377        let resp_handle = handle.clone();
4378        let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
4379            let ConcreteResponse::ListConfigResources(list_response) = response else {
4380                return HandleResult::Retry(Error::local_illegal_state("Expected a ListConfigResources response"));
4381            };
4382            let error = list_response.error();
4383            if error != Errors::None {
4384                resp_handle.complete_with_error(Error::new(error));
4385            } else {
4386                resp_handle.complete(list_response.config_resources());
4387            }
4388            HandleResult::Done
4389        });
4390
4391        let fail_handle = handle.clone();
4392        let handle_failure = Box::new(move |error: &Error| {
4393            fail_handle.complete_with_error(error.clone());
4394        });
4395
4396        let call = Call::new(
4397            "listConfigResources",
4398            deadline,
4399            NodeProvider::LeastLoaded,
4400            create_request,
4401            handle_response,
4402            handle_failure,
4403            Box::new(|_| false),
4404        );
4405        self.submit(call);
4406        ListConfigResourcesResult::new(public)
4407    }
4408
4409    fn describe_log_dirs_with_options(
4410        &self,
4411        brokers: &[i32],
4412        options: DescribeLogDirsOptions,
4413    ) -> DescribeLogDirsResult {
4414        let now = self.now();
4415        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4416
4417        let mut public: HashMap<i32, KafkaFuture<HashMap<String, LogDirDescription>>> = HashMap::new();
4418        for &broker_id in brokers {
4419            let handle: KafkaFutureImpl<HashMap<String, LogDirDescription>> = KafkaFutureImpl::new();
4420            public.insert(broker_id, handle.future());
4421            let call = get_describe_log_dirs_call(broker_id, handle, deadline);
4422            self.submit(call);
4423        }
4424
4425        DescribeLogDirsResult::new(public)
4426    }
4427
4428    fn alter_replica_log_dirs_with_options(
4429        &self,
4430        replica_assignment: &HashMap<TopicPartitionReplica, String>,
4431        options: AlterReplicaLogDirsOptions,
4432    ) -> AlterReplicaLogDirsResult {
4433        let mut futures: HashMap<TopicPartitionReplica, KafkaFutureImpl<()>> = HashMap::new();
4434        for replica in replica_assignment.keys() {
4435            futures.insert(replica.clone(), KafkaFutureImpl::new());
4436        }
4437
4438        // Group the requested moves by destination broker, mirroring Java's
4439        // `replicaAssignmentByBroker`. Each broker's request carries one entry
4440        // per (log dir, topic) with the target partitions.
4441        let mut assignment_by_broker: HashMap<i32, AlterReplicaLogDirsRequestData> = HashMap::new();
4442        for (replica, log_dir) in replica_assignment {
4443            let data = assignment_by_broker
4444                .entry(replica.broker_id())
4445                .or_insert_with(AlterReplicaLogDirsRequestData::new);
4446            if !data.dirs.iter().any(|d| d.path == *log_dir) {
4447                let mut d = AlterReplicaLogDir::new();
4448                d.set_path(log_dir.clone());
4449                data.dirs.push(d);
4450            }
4451            let dir = data.dirs.iter_mut().find(|d| d.path == *log_dir).expect("dir just inserted");
4452            if !dir.topics.iter().any(|t| t.name == replica.topic()) {
4453                let mut t = AlterReplicaLogDirTopic::new();
4454                t.set_name(replica.topic().to_string());
4455                dir.topics.push(t);
4456            }
4457            let topic = dir
4458                .topics
4459                .iter_mut()
4460                .find(|t| t.name == replica.topic())
4461                .expect("topic just inserted");
4462            topic.partitions.push(replica.partition());
4463        }
4464
4465        let now = self.now();
4466        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4467
4468        let public: HashMap<TopicPartitionReplica, KafkaFuture<()>> =
4469            futures.iter().map(|(k, v)| (k.clone(), v.future())).collect();
4470        let shared = Arc::new(futures);
4471        for (broker_id, assignment) in assignment_by_broker {
4472            let call = get_alter_replica_log_dirs_call(broker_id, assignment, Arc::clone(&shared), deadline);
4473            self.submit(call);
4474        }
4475
4476        AlterReplicaLogDirsResult::new(public)
4477    }
4478
4479    fn describe_replica_log_dirs_with_options(
4480        &self,
4481        replicas: &[TopicPartitionReplica],
4482        options: DescribeReplicaLogDirsOptions,
4483    ) -> DescribeReplicaLogDirsResult {
4484        let mut futures: HashMap<TopicPartitionReplica, KafkaFutureImpl<ReplicaLogDirInfo>> = HashMap::new();
4485        for replica in replicas {
4486            futures.insert(replica.clone(), KafkaFutureImpl::new());
4487        }
4488
4489        // Group the requested replicas by broker, mirroring Java's
4490        // `partitionsByBroker`.
4491        let mut partitions_by_broker: HashMap<i32, DescribeLogDirsRequestData> = HashMap::new();
4492        for replica in replicas {
4493            let data = partitions_by_broker
4494                .entry(replica.broker_id())
4495                .or_insert_with(DescribeLogDirsRequestData::new);
4496            let topics = data.topics.get_or_insert_with(Vec::new);
4497            if let Some(topic) = topics.iter_mut().find(|t| t.topic == replica.topic()) {
4498                topic.partitions.push(replica.partition());
4499            } else {
4500                let mut topic = DescribableLogDirTopic::new();
4501                topic.set_topic(replica.topic().to_string());
4502                topic.set_partitions(vec![replica.partition()]);
4503                topics.push(topic);
4504            }
4505        }
4506
4507        let now = self.now();
4508        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4509
4510        let public: HashMap<TopicPartitionReplica, KafkaFuture<ReplicaLogDirInfo>> =
4511            futures.iter().map(|(k, v)| (k.clone(), v.future())).collect();
4512        let shared = Arc::new(futures);
4513        for (broker_id, request_data) in partitions_by_broker {
4514            // Seed the per-partition result map with the default (empty)
4515            // `ReplicaLogDirInfo` for every requested partition.
4516            let mut seed: HashMap<TopicPartition, ReplicaLogDirInfo> = HashMap::new();
4517            if let Some(topics) = &request_data.topics {
4518                for topic in topics {
4519                    for &partition_id in &topic.partitions {
4520                        seed.insert(
4521                            TopicPartition::new(topic.topic.clone(), partition_id),
4522                            ReplicaLogDirInfo::default(),
4523                        );
4524                    }
4525                }
4526            }
4527            let call = get_describe_replica_log_dirs_call(broker_id, request_data, seed, Arc::clone(&shared), deadline);
4528            self.submit(call);
4529        }
4530
4531        DescribeReplicaLogDirsResult::new(public)
4532    }
4533
4534    fn elect_leaders_with_options(
4535        &self,
4536        election_type: ElectionType,
4537        partitions: Option<HashSet<TopicPartition>>,
4538        options: ElectLeadersOptions,
4539    ) -> ElectLeadersResult {
4540        let handle: KafkaFutureImpl<HashMap<TopicPartition, Option<Error>>> = KafkaFutureImpl::new();
4541        let public = handle.future();
4542        let now = self.now();
4543        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4544
4545        // Preserve the caller's null-means-all semantics: `None` requests
4546        // election for all partitions.
4547        let request_partitions: Option<Vec<TopicPartition>> = partitions.map(|set| set.into_iter().collect());
4548
4549        let req_partitions = request_partitions.clone();
4550        let create_request = Box::new(move |timeout_ms: i32| {
4551            Ok(Box::new(elect_leaders_request::Builder::new(
4552                election_type,
4553                req_partitions.clone(),
4554                timeout_ms,
4555            )) as Box<dyn RequestBuilder>)
4556        });
4557
4558        let resp_handle = handle.clone();
4559        let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
4560            let ConcreteResponse::ElectLeaders(elect_response) = response else {
4561                return HandleResult::Retry(Error::local_illegal_state("Expected an ElectLeaders response"));
4562            };
4563            let result = ElectLeadersResponse::elect_leaders_result(elect_response.data());
4564            // For version == 0 the errorCode is 0 which maps to Errors.NONE.
4565            let error = Errors::for_code(elect_response.data().error_code);
4566            if error != Errors::None {
4567                resp_handle.complete_with_error(Error::new(error));
4568                return HandleResult::Done;
4569            }
4570            resp_handle.complete(result);
4571            HandleResult::Done
4572        });
4573
4574        let fail_handle = handle.clone();
4575        let handle_failure = Box::new(move |error: &Error| {
4576            fail_handle.complete_with_error(error.clone());
4577        });
4578
4579        let call = Call::new(
4580            "electLeaders",
4581            deadline,
4582            NodeProvider::Controller { supports_use_controllers: false },
4583            create_request,
4584            handle_response,
4585            handle_failure,
4586            Box::new(|_| false),
4587        );
4588        self.submit(call);
4589        ElectLeadersResult::new(public)
4590    }
4591
4592    fn alter_partition_reassignments_with_options(
4593        &self,
4594        reassignments: &HashMap<TopicPartition, Option<NewPartitionReassignment>>,
4595        options: AlterPartitionReassignmentsOptions,
4596    ) -> AlterPartitionReassignmentsResult {
4597        let mut handles: HashMap<TopicPartition, KafkaFutureImpl<()>> = HashMap::new();
4598        // topic -> (partition -> reassignment); BTreeMap keeps a deterministic
4599        // topic/partition order, mirroring Java's TreeMap.
4600        let mut topics_to_reassignments: std::collections::BTreeMap<
4601            String,
4602            std::collections::BTreeMap<i32, Option<NewPartitionReassignment>>,
4603        > = std::collections::BTreeMap::new();
4604
4605        for (topic_partition, reassignment) in reassignments {
4606            let topic = topic_partition.topic().to_string();
4607            let partition = topic_partition.partition();
4608            let future: KafkaFutureImpl<()> = KafkaFutureImpl::new();
4609            handles.insert(topic_partition.clone(), future.clone());
4610
4611            if topic_name_is_unrepresentable(&topic) {
4612                future.complete_with_error(Error::with_message(
4613                    Errors::InvalidTopicError,
4614                    format!("The given topic name '{topic}' cannot be represented in a request."),
4615                ));
4616            } else if partition < 0 {
4617                future.complete_with_error(Error::with_message(
4618                    Errors::InvalidTopicError,
4619                    format!("The given partition index {partition} is not valid."),
4620                ));
4621            } else {
4622                topics_to_reassignments
4623                    .entry(topic)
4624                    .or_default()
4625                    .insert(partition, reassignment.clone());
4626            }
4627        }
4628
4629        let public: HashMap<TopicPartition, KafkaFuture<()>> =
4630            handles.iter().map(|(k, v)| (k.clone(), v.future())).collect();
4631
4632        if !topics_to_reassignments.is_empty() {
4633            let now = self.now();
4634            let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4635            let allow_replication_factor_change = options.allow_replication_factor_change();
4636            let expected_responses_count: usize =
4637                topics_to_reassignments.values().map(std::collections::BTreeMap::len).sum();
4638            let call = get_alter_partition_reassignments_call(
4639                self.shared.metadata_manager.clone(),
4640                Arc::new(handles),
4641                Arc::new(topics_to_reassignments),
4642                allow_replication_factor_change,
4643                expected_responses_count,
4644                deadline,
4645            );
4646            self.submit(call);
4647        }
4648        AlterPartitionReassignmentsResult::new(public)
4649    }
4650
4651    fn list_partition_reassignments_with_partitions_options(
4652        &self,
4653        partitions: Option<HashSet<TopicPartition>>,
4654        options: ListPartitionReassignmentsOptions,
4655    ) -> ListPartitionReassignmentsResult {
4656        let handle: KafkaFutureImpl<HashMap<TopicPartition, PartitionReassignment>> = KafkaFutureImpl::new();
4657
4658        // Client-side validation, mirroring Java: an unrepresentable topic name
4659        // or negative partition fails the whole future and is never sent.
4660        if let Some(partitions) = &partitions {
4661            for tp in partitions {
4662                if topic_name_is_unrepresentable(tp.topic()) {
4663                    handle.complete_with_error(Error::with_message(
4664                        Errors::InvalidTopicError,
4665                        format!("The given topic name '{}' cannot be represented in a request.", tp.topic()),
4666                    ));
4667                } else if tp.partition() < 0 {
4668                    handle.complete_with_error(Error::with_message(
4669                        Errors::InvalidTopicError,
4670                        format!("The given partition index {} is not valid.", tp.partition()),
4671                    ));
4672                }
4673                if handle.future().is_done() {
4674                    return ListPartitionReassignmentsResult::new(handle.future());
4675                }
4676            }
4677        }
4678
4679        let public = handle.future();
4680        let now = self.now();
4681        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4682        let request_partitions: Option<Vec<TopicPartition>> = partitions.map(|set| set.into_iter().collect());
4683        let call = get_list_partition_reassignments_call(
4684            self.shared.metadata_manager.clone(),
4685            handle,
4686            request_partitions,
4687            deadline,
4688        );
4689        self.submit(call);
4690        ListPartitionReassignmentsResult::new(public)
4691    }
4692
4693    fn list_offsets_with_options(
4694        &self,
4695        topic_partition_offsets: &HashMap<TopicPartition, OffsetSpec>,
4696        options: ListOffsetsOptions,
4697    ) -> ListOffsetsResult {
4698        let keys: HashSet<TopicPartition> = topic_partition_offsets.keys().cloned().collect();
4699        let future = ListOffsetsHandler::new_future(keys, Arc::clone(&self.shared.partition_leader_cache));
4700        let result_map = future.all();
4701
4702        let offset_queries_by_partition: HashMap<TopicPartition, i64> = topic_partition_offsets
4703            .iter()
4704            .map(|(tp, spec)| (tp.clone(), get_offset_from_spec(spec)))
4705            .collect();
4706
4707        let handler = ListOffsetsHandler::new(
4708            offset_queries_by_partition,
4709            options.clone(),
4710            LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id)),
4711            self.shared.default_api_timeout_ms,
4712        );
4713
4714        let now = self.now();
4715        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4716        let retry_backoff = ExponentialBackoff::new(
4717            self.shared.retry_backoff_ms,
4718            RETRY_BACKOFF_EXP_BASE,
4719            self.shared.retry_backoff_max_ms,
4720            RETRY_BACKOFF_JITTER,
4721        )
4722        .expect("ExponentialBackoff::new only fails on invalid jitter");
4723        let driver = AdminApiDriver::new(
4724            Box::new(handler),
4725            Box::new(future),
4726            deadline,
4727            retry_backoff,
4728            LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id)),
4729        );
4730        invoke_driver(driver, self.driver_context(), now);
4731
4732        ListOffsetsResult::new(result_map)
4733    }
4734
4735    fn list_groups_with_options(&self, options: ListGroupsOptions) -> ListGroupsResult {
4736        let now = self.now();
4737        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4738        let states: Vec<String> = options.group_states().iter().map(GroupState::to_string).collect();
4739        let types: Vec<String> = options.types().iter().map(GroupType::to_string).collect();
4740        let protocol_types: HashSet<String> = options.protocol_types().clone();
4741
4742        let future = self.submit_list_groups(deadline, states, types, move |group| {
4743            if !protocol_types.is_empty() && !protocol_types.contains(&group.protocol_type) {
4744                return None;
4745            }
4746            let group_type = if group.group_type.is_empty() {
4747                None
4748            } else {
4749                Some(GroupType::parse(&group.group_type))
4750            };
4751            let group_state = if group.group_state.is_empty() {
4752                None
4753            } else {
4754                Some(GroupState::parse(&group.group_state))
4755            };
4756            Some((
4757                group.group_id.clone(),
4758                GroupListing::new(group.group_id.clone(), group_type, group.protocol_type.clone(), group_state),
4759            ))
4760        });
4761        ListGroupsResult::new(future)
4762    }
4763
4764    fn describe_consumer_groups_with_options(
4765        &self,
4766        group_ids: &[String],
4767        options: DescribeConsumerGroupsOptions,
4768    ) -> DescribeConsumerGroupsResult {
4769        let log_context = LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id));
4770        let future = DescribeConsumerGroupsHandler::new_future(group_ids);
4771        let result_map = future.all();
4772        let handler = DescribeConsumerGroupsHandler::new(options.include_authorized_operations(), log_context.clone());
4773
4774        let now = self.now();
4775        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4776        let retry_backoff = self.retry_backoff();
4777        let driver = AdminApiDriver::new(Box::new(handler), Box::new(future), deadline, retry_backoff, log_context);
4778        invoke_driver(driver, self.driver_context(), now);
4779
4780        DescribeConsumerGroupsResult::new(coordinator_keyed_by_id(result_map))
4781    }
4782
4783    fn describe_classic_groups_with_options(
4784        &self,
4785        group_ids: &[String],
4786        options: DescribeClassicGroupsOptions,
4787    ) -> DescribeClassicGroupsResult {
4788        let log_context = LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id));
4789        let future = DescribeClassicGroupsHandler::new_future(group_ids);
4790        let result_map = future.all();
4791        let handler = DescribeClassicGroupsHandler::new(options.include_authorized_operations(), log_context.clone());
4792
4793        let now = self.now();
4794        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4795        let retry_backoff = self.retry_backoff();
4796        let driver = AdminApiDriver::new(Box::new(handler), Box::new(future), deadline, retry_backoff, log_context);
4797        invoke_driver(driver, self.driver_context(), now);
4798
4799        DescribeClassicGroupsResult::new(coordinator_keyed_by_id(result_map))
4800    }
4801
4802    fn list_consumer_group_offsets_with_group_specs_options(
4803        &self,
4804        group_specs: &HashMap<String, ListConsumerGroupOffsetsSpec>,
4805        options: ListConsumerGroupOffsetsOptions,
4806    ) -> ListConsumerGroupOffsetsResult {
4807        let log_context = LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id));
4808        let group_ids: Vec<String> = group_specs.keys().cloned().collect();
4809        let future = ListConsumerGroupOffsetsHandler::new_future(&group_ids);
4810        let result_map = future.all();
4811        let handler =
4812            ListConsumerGroupOffsetsHandler::new(group_specs.clone(), options.require_stable(), log_context.clone());
4813
4814        let now = self.now();
4815        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4816        let retry_backoff = self.retry_backoff();
4817        let driver = AdminApiDriver::new(Box::new(handler), Box::new(future), deadline, retry_backoff, log_context);
4818        invoke_driver(driver, self.driver_context(), now);
4819
4820        ListConsumerGroupOffsetsResult::new(coordinator_keyed_by_id(result_map))
4821    }
4822
4823    fn alter_consumer_group_offsets_with_options(
4824        &self,
4825        group_id: &str,
4826        offsets: &HashMap<TopicPartition, OffsetAndMetadata>,
4827        options: AlterConsumerGroupOffsetsOptions,
4828    ) -> AlterConsumerGroupOffsetsResult {
4829        let log_context = LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id));
4830        let future = AlterConsumerGroupOffsetsHandler::new_future(group_id);
4831        let result_map = future.all();
4832        let key = CoordinatorKey::by_group_id(group_id);
4833        let handler = AlterConsumerGroupOffsetsHandler::new(group_id, offsets.clone(), log_context.clone());
4834
4835        let now = self.now();
4836        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4837        let retry_backoff = self.retry_backoff();
4838        let driver = AdminApiDriver::new(Box::new(handler), Box::new(future), deadline, retry_backoff, log_context);
4839        invoke_driver(driver, self.driver_context(), now);
4840
4841        AlterConsumerGroupOffsetsResult::new(result_map.get(&key).expect("future exists for the group key").clone())
4842    }
4843
4844    fn delete_consumer_group_offsets_with_options(
4845        &self,
4846        group_id: &str,
4847        partitions: &HashSet<TopicPartition>,
4848        options: DeleteConsumerGroupOffsetsOptions,
4849    ) -> DeleteConsumerGroupOffsetsResult {
4850        let log_context = LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id));
4851        let future = DeleteConsumerGroupOffsetsHandler::new_future(group_id);
4852        let result_map = future.all();
4853        let key = CoordinatorKey::by_group_id(group_id);
4854        let handler = DeleteConsumerGroupOffsetsHandler::new(group_id, partitions.clone(), log_context.clone());
4855
4856        let now = self.now();
4857        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4858        let retry_backoff = self.retry_backoff();
4859        let driver = AdminApiDriver::new(Box::new(handler), Box::new(future), deadline, retry_backoff, log_context);
4860        invoke_driver(driver, self.driver_context(), now);
4861
4862        DeleteConsumerGroupOffsetsResult::new(
4863            result_map.get(&key).expect("future exists for the group key").clone(),
4864            partitions.clone(),
4865        )
4866    }
4867
4868    fn delete_consumer_groups_with_options(
4869        &self,
4870        group_ids: &[String],
4871        options: DeleteConsumerGroupsOptions,
4872    ) -> DeleteConsumerGroupsResult {
4873        let log_context = LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id));
4874        let future = DeleteGroupsHandler::new_future(group_ids);
4875        let result_map = future.all();
4876        let handler = DeleteConsumerGroupsHandler::new(log_context.clone());
4877
4878        let now = self.now();
4879        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4880        let retry_backoff = self.retry_backoff();
4881        let driver = AdminApiDriver::new(Box::new(handler), Box::new(future), deadline, retry_backoff, log_context);
4882        invoke_driver(driver, self.driver_context(), now);
4883
4884        DeleteConsumerGroupsResult::new(coordinator_keyed_by_id(result_map))
4885    }
4886
4887    fn remove_members_from_consumer_group_with_options(
4888        &self,
4889        group_id: &str,
4890        options: RemoveMembersFromConsumerGroupOptions,
4891    ) -> RemoveMembersFromConsumerGroupResult {
4892        let log_context = LogContext::new(format!("[AdminClient clientId={}] ", self.shared.client_id));
4893        let reason = match options.reason() {
4894            None | Some("") => DEFAULT_LEAVE_GROUP_REASON.to_string(),
4895            Some(r) => JoinGroupRequest::maybe_truncate_reason(r),
4896        };
4897
4898        let admin_future = RemoveMembersFromConsumerGroupHandler::new_future(group_id);
4899        let result_map = admin_future.all();
4900        let key = CoordinatorKey::by_group_id(group_id);
4901        let group_future = result_map.get(&key).expect("future exists for the group key").clone();
4902
4903        let now = self.now();
4904        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
4905        let retry_backoff = self.retry_backoff();
4906        let ctx = self.driver_context();
4907
4908        if options.remove_all() {
4909            // Mirrors `getMembersFromGroup`: describe the group, then chain the
4910            // `LeaveGroup` driver once the membership is known.
4911            //
4912            // The describe step is issued via
4913            // `describeConsumerGroups(Collections.singleton(groupId))` with a
4914            // *default* `DescribeConsumerGroupsOptions` (Java
4915            // `org.apache.kafka.clients.admin.KafkaAdminClient#getMembersFromGroup`),
4916            // whose `timeoutMs` is `null`. Its deadline is therefore
4917            // `now + defaultApiTimeoutMs`, independent of the removeMembers
4918            // request's `options.timeout_ms()`.
4919            let default_api_timeout_ms = self.shared.default_api_timeout_ms;
4920            let options_timeout = options.timeout_ms();
4921            let describe_deadline = calc_deadline_ms(now, None, default_api_timeout_ms);
4922
4923            let describe_group_ids = vec![group_id.to_string()];
4924            let describe_future = DescribeConsumerGroupsHandler::new_future(&describe_group_ids);
4925            let describe_handle = describe_future.handle(&key).expect("describe future exists for the group key");
4926            let describe_handler = DescribeConsumerGroupsHandler::new(false, log_context.clone());
4927            let describe_driver = AdminApiDriver::new(
4928                Box::new(describe_handler),
4929                Box::new(describe_future),
4930                describe_deadline,
4931                retry_backoff.clone(),
4932                log_context.clone(),
4933            );
4934            invoke_driver(describe_driver, ctx.clone(), now);
4935
4936            let group_id_owned = group_id.to_string();
4937            let key_for_cb = key.clone();
4938            describe_handle.when_complete(move |result| match result {
4939                Err(error) => {
4940                    // `new KafkaException("Encounter exception when trying to get members from group: " + groupId, ex)`
4941                    // (`org.apache.kafka.clients.admin.KafkaAdminClient#getMembersFromGroup`) —
4942                    // a bare `KafkaException` carrying the cause, NOT the inner class.
4943                    // Inheriting it made a `GroupAuthorizationError` cause answer
4944                    // `is_authorization_error()` (and so `is_fatal_error()`) where Java
4945                    // answers `false`, and lost the cause entirely (finding 243).
4946                    // "exception" is reworded to "error" per CLAUDE.md §2; the rest is
4947                    // Java's text verbatim.
4948                    admin_future.complete_with_error(HashMap::from([(
4949                        key_for_cb,
4950                        Error::kafka_message_source(
4951                            format!("Encounter error when trying to get members from group: {group_id_owned}"),
4952                            error.clone(),
4953                        ),
4954                    )]));
4955                },
4956                Ok(description) => {
4957                    let members: Vec<MemberIdentity> = description
4958                        .members()
4959                        .iter()
4960                        .map(|member| {
4961                            let mut identity = MemberIdentity::new();
4962                            match member.group_instance_id() {
4963                                Some(instance_id) => {
4964                                    identity.set_group_instance_id(Some(instance_id.to_string()));
4965                                },
4966                                None => {
4967                                    identity.set_member_id(member.consumer_id().to_string());
4968                                },
4969                            }
4970                            identity.set_reason(Some(reason.clone()));
4971                            identity
4972                        })
4973                        .collect();
4974                    let handler =
4975                        RemoveMembersFromConsumerGroupHandler::new(&group_id_owned, members, log_context.clone());
4976                    // Recompute the `LeaveGroup` deadline from the *current* time, now
4977                    // that the describe future has resolved. This mirrors Java's
4978                    // `memFuture.whenComplete(...)` (in
4979                    // `org.apache.kafka.clients.admin.KafkaAdminClient#removeMembersFromConsumerGroup`)
4980                    // calling `invokeDriver(handler, adminFuture, options.timeoutMs())`,
4981                    // whose `calcDeadlineMs(time.milliseconds(), timeoutMs)` runs at
4982                    // this later moment — giving `LeaveGroup` a fresh full timeout
4983                    // window rather than the (already partially consumed) describe one.
4984                    let leave_now = ctx.time.milliseconds();
4985                    let leave_deadline = calc_deadline_ms(leave_now, options_timeout, default_api_timeout_ms);
4986                    let driver = AdminApiDriver::new(
4987                        Box::new(handler),
4988                        Box::new(admin_future),
4989                        leave_deadline,
4990                        retry_backoff.clone(),
4991                        log_context.clone(),
4992                    );
4993                    invoke_driver(driver, ctx.clone(), leave_now);
4994                },
4995            });
4996        } else {
4997            let members: Vec<MemberIdentity> = options
4998                .members()
4999                .iter()
5000                .map(|member| {
5001                    let mut identity = member.to_member_identity();
5002                    identity.set_reason(Some(reason.clone()));
5003                    identity
5004                })
5005                .collect();
5006            let handler = RemoveMembersFromConsumerGroupHandler::new(group_id, members, log_context.clone());
5007            let driver =
5008                AdminApiDriver::new(Box::new(handler), Box::new(admin_future), deadline, retry_backoff, log_context);
5009            invoke_driver(driver, ctx, now);
5010        }
5011
5012        RemoveMembersFromConsumerGroupResult::new(group_future, options.members().clone())
5013    }
5014
5015    fn create_acls_with_options(&self, acls: &[AclBinding], options: CreateAclsOptions) -> CreateAclsResult {
5016        let now = self.now();
5017        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
5018
5019        let mut handles: HashMap<AclBinding, KafkaFutureImpl<()>> = HashMap::new();
5020        let mut acl_creations: Vec<AclCreation> = Vec::new();
5021        let mut acl_bindings_sent: Vec<AclBinding> = Vec::new();
5022        for acl in acls {
5023            if let std::collections::hash_map::Entry::Vacant(entry) = handles.entry(acl.clone()) {
5024                let future: KafkaFutureImpl<()> = KafkaFutureImpl::new();
5025                entry.insert(future.clone());
5026                match acl.to_filter().find_indefinite_field() {
5027                    None => {
5028                        acl_creations.push(CreateAclsRequest::acl_creation(acl));
5029                        acl_bindings_sent.push(acl.clone());
5030                    },
5031                    Some(indefinite) => {
5032                        future.complete_with_error(Error::with_message(
5033                            Errors::InvalidRequest,
5034                            format!("Invalid ACL creation: {indefinite}"),
5035                        ));
5036                    },
5037                }
5038            }
5039        }
5040        let public: HashMap<AclBinding, KafkaFuture<()>> =
5041            handles.iter().map(|(k, v)| (k.clone(), v.future())).collect();
5042
5043        let call = get_create_acls_call(
5044            self.shared.metadata_manager.clone(),
5045            Arc::new(handles),
5046            acl_creations,
5047            acl_bindings_sent,
5048            deadline,
5049        );
5050        self.submit(call);
5051        CreateAclsResult::new(public)
5052    }
5053
5054    fn describe_acls_with_options(
5055        &self,
5056        filter: &AclBindingFilter,
5057        options: DescribeAclsOptions,
5058    ) -> DescribeAclsResult {
5059        // Short-circuit on an unknown filter, mirroring
5060        // `KafkaAdminClient.describeAcls`: complete the future exceptionally
5061        // with InvalidRequestException and enqueue no Call.
5062        if filter.is_unknown() {
5063            let handle: KafkaFutureImpl<Vec<AclBinding>> = KafkaFutureImpl::new();
5064            handle.complete_with_error(Error::with_message(
5065                Errors::InvalidRequest,
5066                "The AclBindingFilter must not contain UNKNOWN elements.",
5067            ));
5068            return DescribeAclsResult::new(handle.future());
5069        }
5070
5071        let now = self.now();
5072        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
5073        let handle: KafkaFutureImpl<Vec<AclBinding>> = KafkaFutureImpl::new();
5074        let public = handle.future();
5075        let call = get_describe_acls_call(filter.clone(), handle, deadline);
5076        self.submit(call);
5077        DescribeAclsResult::new(public)
5078    }
5079
5080    fn delete_acls_with_options(&self, filters: &[AclBindingFilter], options: DeleteAclsOptions) -> DeleteAclsResult {
5081        let now = self.now();
5082        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
5083
5084        let mut handles: HashMap<AclBindingFilter, KafkaFutureImpl<FilterResults>> = HashMap::new();
5085        let mut acl_binding_filters_sent: Vec<AclBindingFilter> = Vec::new();
5086        let mut delete_acls_filters: Vec<DeleteAclsFilter> = Vec::new();
5087        for filter in filters {
5088            if let std::collections::hash_map::Entry::Vacant(entry) = handles.entry(filter.clone()) {
5089                acl_binding_filters_sent.push(filter.clone());
5090                delete_acls_filters.push(DeleteAclsRequest::delete_acls_filter(filter));
5091                entry.insert(KafkaFutureImpl::new());
5092            }
5093        }
5094        let public: HashMap<AclBindingFilter, KafkaFuture<FilterResults>> =
5095            handles.iter().map(|(k, v)| (k.clone(), v.future())).collect();
5096
5097        let call = get_delete_acls_call(
5098            self.shared.metadata_manager.clone(),
5099            Arc::new(handles),
5100            acl_binding_filters_sent,
5101            delete_acls_filters,
5102            deadline,
5103        );
5104        self.submit(call);
5105        DeleteAclsResult::new(public)
5106    }
5107
5108    fn describe_client_quotas_with_options(
5109        &self,
5110        filter: &ClientQuotaFilter,
5111        options: DescribeClientQuotasOptions,
5112    ) -> DescribeClientQuotasResult {
5113        let now = self.now();
5114        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
5115        let handle: KafkaFutureImpl<HashMap<ClientQuotaEntity, HashMap<String, f64>>> = KafkaFutureImpl::new();
5116        let public = handle.future();
5117        let call = get_describe_client_quotas_call(filter.clone(), handle, deadline);
5118        self.submit(call);
5119        DescribeClientQuotasResult::new(public)
5120    }
5121
5122    fn alter_client_quotas_with_options(
5123        &self,
5124        entries: &[ClientQuotaAlteration],
5125        options: AlterClientQuotasOptions,
5126    ) -> AlterClientQuotasResult {
5127        let now = self.now();
5128        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
5129
5130        // Mirrors Java: one future per entity (later entries with the same
5131        // entity share the single future for that entity).
5132        let mut handles: HashMap<ClientQuotaEntity, KafkaFutureImpl<()>> = HashMap::new();
5133        for entry in entries {
5134            handles.entry(entry.entity().clone()).or_default();
5135        }
5136        let public: HashMap<ClientQuotaEntity, KafkaFuture<()>> =
5137            handles.iter().map(|(k, v)| (k.clone(), v.future())).collect();
5138
5139        let call = get_alter_client_quotas_call(entries.to_vec(), options.validate_only(), Arc::new(handles), deadline);
5140        self.submit(call);
5141        AlterClientQuotasResult::new(public)
5142    }
5143
5144    fn describe_user_scram_credentials_with_users_options(
5145        &self,
5146        users: &[String],
5147        options: DescribeUserScramCredentialsOptions,
5148    ) -> DescribeUserScramCredentialsResult {
5149        let now = self.now();
5150        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
5151        let handle: KafkaFutureImpl<DescribeUserScramCredentialsResponseData> = KafkaFutureImpl::new();
5152        let public = handle.future();
5153        let call = get_describe_user_scram_credentials_call(users.to_vec(), handle, deadline);
5154        self.submit(call);
5155        DescribeUserScramCredentialsResult::new(public)
5156    }
5157
5158    fn alter_user_scram_credentials_with_options(
5159        &self,
5160        alterations: &[UserScramCredentialAlteration],
5161        options: AlterUserScramCredentialsOptions,
5162    ) -> AlterUserScramCredentialsResult {
5163        let now = self.now();
5164        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
5165
5166        // Mirrors Java: one future per user.
5167        let mut handles: HashMap<String, KafkaFutureImpl<()>> = HashMap::new();
5168        for alteration in alterations {
5169            handles.insert(alteration.user().to_string(), KafkaFutureImpl::new());
5170        }
5171
5172        // We track users with an illegal alteration so we can fail all their
5173        // alterations later; we also pre-build the wire deletions/upsertions for
5174        // the ones that pass validation. Building an upsertion runs PBKDF2.
5175        let unknown_scram_mechanism_msg = "Unknown SCRAM mechanism";
5176        let mut illegal: HashMap<String, Error> = HashMap::new();
5177
5178        // Deletions with an empty user or an unknown mechanism are illegal.
5179        for alteration in alterations {
5180            if let UserScramCredentialAlteration::Deletion(deletion) = alteration {
5181                let user = deletion.user();
5182                if user.is_empty() {
5183                    illegal.insert(user.to_string(), unacceptable_credential("Username must not be empty"));
5184                } else if deletion.mechanism() == ScramMechanism::Unknown {
5185                    illegal.insert(user.to_string(), unsupported_sasl_mechanism(unknown_scram_mechanism_msg));
5186                }
5187            }
5188        }
5189
5190        // Upsertions: validate and compute the salted password (PBKDF2) once.
5191        let mut user_insertions: HashMap<String, HashMap<i8, ScramCredentialUpsertion>> = HashMap::new();
5192        for alteration in alterations {
5193            let UserScramCredentialAlteration::Upsertion(upsertion) = alteration else {
5194                continue;
5195            };
5196            let user = upsertion.user();
5197            if illegal.contains_key(user) {
5198                continue;
5199            }
5200            if user.is_empty() {
5201                illegal.insert(user.to_string(), unacceptable_credential("Username must not be empty"));
5202                continue;
5203            }
5204            if upsertion.password().is_empty() {
5205                illegal.insert(user.to_string(), unacceptable_credential("Password must not be empty"));
5206                continue;
5207            }
5208            let mechanism = upsertion.credential_info().mechanism();
5209            if mechanism == ScramMechanism::Unknown {
5210                illegal.insert(user.to_string(), unsupported_sasl_mechanism(unknown_scram_mechanism_msg));
5211                continue;
5212            }
5213            match get_scram_credential_upsertion(upsertion) {
5214                Ok(wire) => {
5215                    user_insertions
5216                        .entry(user.to_string())
5217                        .or_default()
5218                        .insert(mechanism.r#type(), wire);
5219                },
5220                // Mirrors the NoSuchAlgorithmException branch (unknown mechanism).
5221                Err(e) => {
5222                    illegal.insert(user.to_string(), e);
5223                },
5224            }
5225        }
5226
5227        // Pre-build the request payloads (in alteration order) for the users that
5228        // survived validation. The crypto is already done, so retries just reuse
5229        // these; mirrors Java's `userInsertions` map being computed once.
5230        let mut request_upsertions = Vec::new();
5231        for alteration in alterations {
5232            if let UserScramCredentialAlteration::Upsertion(upsertion) = alteration {
5233                if illegal.contains_key(upsertion.user()) {
5234                    continue;
5235                }
5236                if let Some(wire) = user_insertions
5237                    .get(upsertion.user())
5238                    .and_then(|by_mech| by_mech.get(&upsertion.credential_info().mechanism().r#type()))
5239                {
5240                    request_upsertions.push(wire.clone());
5241                }
5242            }
5243        }
5244        let mut request_deletions = Vec::new();
5245        for alteration in alterations {
5246            if let UserScramCredentialAlteration::Deletion(deletion) = alteration {
5247                if illegal.contains_key(deletion.user()) {
5248                    continue;
5249                }
5250                request_deletions.push(get_scram_credential_deletion(deletion));
5251            }
5252        }
5253
5254        let handles = Arc::new(handles);
5255        let public: HashMap<String, KafkaFuture<()>> =
5256            handles.iter().map(|(user, handle)| (user.clone(), handle.future())).collect();
5257
5258        let call = get_alter_user_scram_credentials_call(
5259            request_deletions,
5260            request_upsertions,
5261            Arc::new(illegal),
5262            Arc::clone(&handles),
5263            self.shared.metadata_manager.clone(),
5264            deadline,
5265        );
5266        self.submit(call);
5267        AlterUserScramCredentialsResult::new(public)
5268    }
5269
5270    fn create_delegation_token_with_options(
5271        &self,
5272        options: CreateDelegationTokenOptions,
5273    ) -> CreateDelegationTokenResult {
5274        let now = self.now();
5275        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
5276        let handle: KafkaFutureImpl<DelegationToken> = KafkaFutureImpl::new();
5277        let public = handle.future();
5278        let call = get_create_delegation_token_call(options, handle, deadline);
5279        self.submit(call);
5280        CreateDelegationTokenResult::new(public)
5281    }
5282
5283    fn renew_delegation_token_with_options(
5284        &self,
5285        hmac: &[u8],
5286        options: RenewDelegationTokenOptions,
5287    ) -> RenewDelegationTokenResult {
5288        let now = self.now();
5289        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
5290        let handle: KafkaFutureImpl<i64> = KafkaFutureImpl::new();
5291        let public = handle.future();
5292        let call = get_renew_delegation_token_call(hmac.to_vec(), options.renew_time_period_ms(), handle, deadline);
5293        self.submit(call);
5294        RenewDelegationTokenResult::new(public)
5295    }
5296
5297    fn expire_delegation_token_with_options(
5298        &self,
5299        hmac: &[u8],
5300        options: ExpireDelegationTokenOptions,
5301    ) -> ExpireDelegationTokenResult {
5302        let now = self.now();
5303        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
5304        let handle: KafkaFutureImpl<i64> = KafkaFutureImpl::new();
5305        let public = handle.future();
5306        let call = get_expire_delegation_token_call(hmac.to_vec(), options.expiry_time_period_ms(), handle, deadline);
5307        self.submit(call);
5308        ExpireDelegationTokenResult::new(public)
5309    }
5310
5311    fn describe_delegation_token_with_options(
5312        &self,
5313        options: DescribeDelegationTokenOptions,
5314    ) -> DescribeDelegationTokenResult {
5315        let now = self.now();
5316        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
5317        let handle: KafkaFutureImpl<Vec<DelegationToken>> = KafkaFutureImpl::new();
5318        let public = handle.future();
5319        let owners = options.owners().map(<[KafkaPrincipal]>::to_vec);
5320        let call = get_describe_delegation_token_call(owners, handle, deadline);
5321        self.submit(call);
5322        DescribeDelegationTokenResult::new(public)
5323    }
5324
5325    fn describe_features_with_options(&self, options: DescribeFeaturesOptions) -> DescribeFeaturesResult {
5326        // Java returns the `InternalDescribeFeaturesResult` typed as its parent.
5327        self.describe_features_internal(options).into()
5328    }
5329
5330    fn update_features_with_options(
5331        &self,
5332        feature_updates: &HashMap<String, FeatureUpdate>,
5333        options: UpdateFeaturesOptions,
5334    ) -> Result<UpdateFeaturesResult, Error> {
5335        if feature_updates.is_empty() {
5336            return Err(Error::local_illegal_argument("Feature updates can not be null or empty."));
5337        }
5338
5339        let mut handles: HashMap<String, KafkaFutureImpl<()>> = HashMap::new();
5340        for feature in feature_updates.keys() {
5341            // Java's `Utils.isBlank`: `str.trim().isEmpty()`, and Java's `trim()`
5342            // strips every char up to U+0020 (Rust's `trim()` is Unicode white space).
5343            if feature.trim_matches(|c: char| c <= ' ').is_empty() {
5344                return Err(Error::local_illegal_argument("Provided feature can not be empty."));
5345            }
5346            handles.insert(feature.clone(), KafkaFutureImpl::new());
5347        }
5348        let handles = Arc::new(handles);
5349        let public: HashMap<String, KafkaFuture<()>> = handles
5350            .iter()
5351            .map(|(feature, handle)| (feature.clone(), handle.future()))
5352            .collect();
5353
5354        let now = self.now();
5355        let deadline = calc_deadline_ms(now, options.timeout_ms(), self.shared.default_api_timeout_ms);
5356
5357        // Snapshot the updates for the (possibly retried) request builder.
5358        let updates_for_request: Vec<(String, FeatureUpdate)> = feature_updates
5359            .iter()
5360            .map(|(feature, update)| (feature.clone(), update.clone()))
5361            .collect();
5362        let validate_only = options.validate_only();
5363        let create_request = Box::new(move |timeout_ms: i32| {
5364            let mut collection = Vec::with_capacity(updates_for_request.len());
5365            for (feature, update) in &updates_for_request {
5366                let mut item = FeatureUpdateKey::new();
5367                item.set_feature(feature.clone());
5368                item.set_max_version_level(update.max_version_level());
5369                item.set_upgrade_type(update.upgrade_type().code());
5370                collection.push(item);
5371            }
5372            let mut data = UpdateFeaturesRequestData::new();
5373            data.set_timeout_ms(timeout_ms);
5374            data.set_validate_only(validate_only);
5375            data.set_feature_updates(collection);
5376            Ok(Box::new(update_features_request::Builder::new(data)) as Box<dyn RequestBuilder>)
5377        });
5378
5379        let resp_mm = self.shared.metadata_manager.clone();
5380        let resp_handles = Arc::clone(&handles);
5381        let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
5382            let ConcreteResponse::UpdateFeatures(update_response) = response else {
5383                return HandleResult::Retry(Error::local_illegal_state("Expected an UpdateFeatures response"));
5384            };
5385            let data = update_response.data();
5386            let top_level_error = Errors::for_code(data.error_code);
5387            match top_level_error {
5388                Errors::None => {
5389                    if data.results.is_empty() {
5390                        // For V2 and above, NONE responses just have a top-level
5391                        // NONE error -- mark all the futures as completed.
5392                        for future in resp_handles.values() {
5393                            future.complete(());
5394                        }
5395                    } else {
5396                        for result in &data.results {
5397                            match resp_handles.get(&result.feature) {
5398                                // The server should send back a result for every
5399                                // feature, but we only complete known features.
5400                                None => {},
5401                                Some(future) => {
5402                                    let error = Errors::for_code(result.error_code);
5403                                    if error == Errors::None {
5404                                        future.complete(());
5405                                    } else {
5406                                        future.complete_with_error(api_error(result.error_code, &result.error_message));
5407                                    }
5408                                },
5409                            }
5410                        }
5411                        // Sanity check: the server should send back a response
5412                        // for every feature (mirrors completeUnrealizedFutures).
5413                        for (feature, future) in resp_handles.iter() {
5414                            if !future.is_done() {
5415                                // Java's
5416                                // `org.apache.kafka.clients.admin.KafkaAdminClient#completeUnrealizedFutures`
5417                                // throws `new ApiException(..)` — the concrete base, not the
5418                                // `UnknownServerException` subclass it uses elsewhere for response
5419                                // sanity checks (in `KafkaAdminClient#createAcls`,
5420                                // `KafkaAdminClient#deleteAcls` and
5421                                // `KafkaAdminClient#alterPartitionReassignments`). Finding 246.
5422                                future.complete_with_error(Error::Api(ApiError::new(format!(
5423                                    "The controller response did not contain a result for feature {feature}"
5424                                ))));
5425                            }
5426                        }
5427                    }
5428                },
5429                Errors::NotController => {
5430                    // Mirrors handleNotControllerError(Errors.NOT_CONTROLLER):
5431                    // clear the cached controller, request a metadata refresh and
5432                    // retry the call.
5433                    resp_mm.clear_controller();
5434                    resp_mm.request_update();
5435                    return HandleResult::Retry(Error::new(Errors::NotController));
5436                },
5437                _ => {
5438                    let error = api_error(data.error_code, &data.error_message);
5439                    for future in resp_handles.values() {
5440                        future.complete_with_error(error.clone());
5441                    }
5442                },
5443            }
5444            HandleResult::Done
5445        });
5446
5447        let fail_handles = Arc::clone(&handles);
5448        let handle_failure = Box::new(move |error: &Error| {
5449            for future in fail_handles.values() {
5450                future.complete_with_error(error.clone());
5451            }
5452        });
5453
5454        let call = Call::new(
5455            "updateFeatures",
5456            deadline,
5457            // `new ControllerNodeProvider(true)`, as in `KafkaAdminClient#updateFeatures`.
5458            NodeProvider::Controller { supports_use_controllers: true },
5459            create_request,
5460            handle_response,
5461            handle_failure,
5462            Box::new(|_| false),
5463        );
5464        self.submit(call);
5465        Ok(UpdateFeaturesResult::new(public))
5466    }
5467
5468    async fn close_with_timeout(&self, timeout: Duration) {
5469        // Java: `waitTimeMs = Math.min(TimeUnit.DAYS.toMillis(365), timeout.toMillis())`.
5470        // Its `waitTimeMs < 0` check throws `IllegalArgumentException`; a
5471        // `Duration` cannot be negative, so that branch is unrepresentable here.
5472        let wait_time_ms = timeout.as_millis().min(MAX_CLOSE_WAIT_TIME_MS as u128) as i64;
5473        let now = self.now();
5474        let new_hard_shutdown_time_ms = now.saturating_add(wait_time_ms);
5475
5476        // Java publishes the deadline through a compare-and-set loop whose whole
5477        // purpose is monotonicity: if another `close()` already installed an
5478        // earlier deadline it keeps that one ("Hard shutdown time is already
5479        // earlier than requested"), so the deadline only ever moves forward in
5480        // urgency. A plain store would let `close(60s)` after `close(100ms)`
5481        // re-widen the poll budget that `process_pending_calls` reads on every iteration.
5482        //
5483        // Java also reassigns `newHardShutdownTimeMs = prev` on that branch, but
5484        // only to feed a debug log, so it has no counterpart here.
5485        let mut prev = Self::NO_HARD_SHUTDOWN;
5486        loop {
5487            match self.shared.shutdown.hard_shutdown_deadline_ms.compare_exchange(
5488                prev,
5489                new_hard_shutdown_time_ms,
5490                std::sync::atomic::Ordering::AcqRel,
5491                std::sync::atomic::Ordering::Acquire,
5492            ) {
5493                Ok(_) => break,
5494                Err(actual) => {
5495                    if actual < new_hard_shutdown_time_ms {
5496                        // An earlier (more urgent) deadline is already installed.
5497                        break;
5498                    }
5499                    prev = actual;
5500                },
5501            }
5502        }
5503        // Java's `close()` publishes only `hardShutdownTimeMs`; the runnable's
5504        // `closing` flag is set by the I/O task itself once its loop exits (the
5505        // `finally` of `KafkaAdminClient.AdminClientRunnable#run`), so calls keep
5506        // being retried during the grace period.
5507        //
5508        // Java calls `client.wakeup()` from inside the successful CAS arm. Here
5509        // the wakeup follows the CAS, so the woken I/O task is guaranteed to
5510        // observe the deadline, and it is issued on the already-earlier-deadline
5511        // path too (where it is a harmless no-op: the `close()` that installed
5512        // that deadline has already woken the task).
5513        self.shared.wakeup.notify_one();
5514
5515        // Java ends with a *timed* join (`KafkaAdminClient.close`):
5516        //
5517        // ```java
5518        // if (Thread.currentThread() != thread) {
5519        //     thread.join(waitTimeMs);
5520        // }
5521        // ```
5522        //
5523        // The deadline installed above is only a hint to the I/O loop; the timed
5524        // join is the caller's guarantee, and it matters more here than in Java:
5525        // Java's `sendEligibleCalls` calls the non-blocking NIO
5526        // `client.ready(...)`, whereas ours awaits `NetworkClient::ready` →
5527        // `initiate_connect` → `Selector::connect`, which awaits the TCP
5528        // handshake and no shutdown deadline can interrupt.
5529        //
5530        // Java's `Thread.currentThread() != thread` self-deadlock guard has no
5531        // analogue: the I/O task owns no `Admin` handle and every per-`Call` hook
5532        // it runs is a sync closure, so `close()` cannot be re-entered from it.
5533        // Should that ever change, the timed join bounds the wait instead of
5534        // deadlocking, where Java skips the join entirely.
5535        //
5536        // Deliberate divergence: Java's `Thread.join(0)` means "wait forever", so
5537        // `close(Duration::ZERO)` there is unbounded. We treat 0 as 0, because
5538        // both `Admin::close`'s rustdoc and the exported C header promise a
5539        // return within `timeout`, and because of the uninterruptible connect
5540        // await above the Java behavior would be a genuine hang rather than the
5541        // near-immediate return it is in Java.
5542        let mut handle = self.shared.bg_handle.lock().unwrap().take();
5543        if let Some(join_handle) = handle.as_mut() {
5544            let joined = tokio::time::timeout(Duration::from_millis(wait_time_ms as u64), join_handle).await;
5545            // Java's counterpart logs when the join does not complete cleanly
5546            // (`org.apache.kafka.clients.admin.KafkaAdminClient#close`,
5547            // `catch (InterruptedException e)`). `InterruptedException` has no
5548            // Tokio analogue, but a `JoinError` — the task panicked or was
5549            // aborted — is the same class of "the I/O task did not shut down
5550            // normally" signal, and discarding it left `close()` returning as if
5551            // nothing had happened.
5552            match joined {
5553                Ok(Ok(())) => kafka_debug!(self.shared.log_context, "Kafka admin client closed."),
5554                Ok(Err(join_error)) => kafka_error!(
5555                    self.shared.log_context,
5556                    "The Kafka admin client I/O task did not exit cleanly: {}",
5557                    join_error
5558                ),
5559                Err(_elapsed) => {
5560                    // Expired: leave the task running, exactly as Java leaves the
5561                    // I/O thread running after an expired join, and put the handle
5562                    // back so a later `close()` can still join it.
5563                    *self.shared.bg_handle.lock().unwrap() = handle;
5564                },
5565            }
5566        }
5567    }
5568}
5569
5570/// Builds the `describeTopics` (by name) [`Call`] using the Metadata API: the
5571/// fallback `describeTopicPartitions` issues for a broker that does not support
5572/// `DescribeTopicPartitions`.
5573/// Translated from `KafkaAdminClient.generateDescribeTopicsCallWithMetadataApi`.
5574fn get_describe_topics_by_names_call(
5575    futures: Arc<HashMap<String, KafkaFutureImpl<TopicDescription>>>,
5576    names: Vec<String>,
5577    include_authorized_operations: bool,
5578    deadline: i64,
5579) -> Call {
5580    // `supports_disabling_topic_creation` toggles the metadata request between
5581    // per-topic (auto-creation disabled) and all-topics on the first
5582    // UnsupportedVersionException, mirroring Java's downgrade.
5583    let supports_disabling = Arc::new(std::sync::atomic::AtomicBool::new(true));
5584
5585    let req_names = names.clone();
5586    let req_supports = Arc::clone(&supports_disabling);
5587    let create_request = Box::new(move |_timeout_ms: i32| {
5588        if req_supports.load(std::sync::atomic::Ordering::Acquire) {
5589            let refs: Vec<&str> = req_names.iter().map(String::as_str).collect();
5590            let mut data = crate::MetadataRequestData::new();
5591            data.set_topics(Some(
5592                crate::common::requests::MetadataRequest::convert_to_metadata_request_topic(&refs),
5593            ));
5594            data.set_allow_auto_topic_creation(false);
5595            data.set_include_topic_authorized_operations(include_authorized_operations);
5596            Ok(Box::new(metadata_request::Builder::with_data(data)) as Box<dyn RequestBuilder>)
5597        } else {
5598            Ok(Box::new(metadata_request::Builder::all_topics()) as Box<dyn RequestBuilder>)
5599        }
5600    });
5601
5602    let resp_futures = Arc::clone(&futures);
5603    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
5604        let ConcreteResponse::Metadata(metadata_response) = response else {
5605            return HandleResult::Retry(Error::local_illegal_state("Expected a Metadata response"));
5606        };
5607        let cluster = metadata_response.build_cluster();
5608        let errors = metadata_response.errors();
5609        for (topic_name, future) in resp_futures.iter() {
5610            if let Some(topic_error) = errors.get(topic_name) {
5611                future.complete_with_error(Error::new(*topic_error));
5612                continue;
5613            }
5614            if !cluster.topics().any(|t| t == topic_name.as_str()) {
5615                future.complete_with_error(Error::with_message(
5616                    Errors::UnknownTopicOrPartition,
5617                    format!("Topic {topic_name} not found."),
5618                ));
5619                continue;
5620            }
5621            let topic_id = cluster.topic_id(topic_name);
5622            let authorized_operations = metadata_response
5623                .topic_authorized_operations(topic_name)
5624                .unwrap_or(MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED);
5625            future.complete(topic_description_from_cluster(
5626                &cluster,
5627                topic_name,
5628                topic_id,
5629                authorized_operations,
5630            ));
5631        }
5632        HandleResult::Done
5633    });
5634
5635    let fail_futures = Arc::clone(&futures);
5636    let handle_failure = Box::new(move |error: &Error| {
5637        for future in fail_futures.values() {
5638            future.complete_with_error(error.clone());
5639        }
5640    });
5641
5642    let uv_supports = Arc::clone(&supports_disabling);
5643    // First UnsupportedVersion: downgrade to all-topics and retry (returns
5644    // true). A second one is a real failure (returns false).
5645    let handle_uv = Box::new(move |_error: &Error| uv_supports.swap(false, std::sync::atomic::Ordering::AcqRel));
5646
5647    Call::new(
5648        "describeTopics",
5649        deadline,
5650        NodeProvider::LeastLoaded,
5651        create_request,
5652        handle_response,
5653        handle_failure,
5654        handle_uv,
5655    )
5656}
5657
5658/// The state [`generate_describe_topics_call_with_describe_topic_partitions_api`]'s
5659/// hooks share: the fields of Java's anonymous `Call` subclass
5660/// (`partiallyFinishedTopicDescription`) plus the `topicsRequests` map it
5661/// closes over. The request and response hooks are separate closures in Rust,
5662/// so what Java keeps in the one object is shared between them here.
5663struct DescribeTopicPartitionsState {
5664    /// Java's `topicsRequests`, a `LinkedHashMap` filled from the sorted topic
5665    /// names: the topics not yet fully described, in name order.
5666    topics_requests: BTreeSet<String>,
5667    /// Java's `partiallyFinishedTopicDescription`: the cursor topic of the
5668    /// previous page, whose partitions continue in the next one.
5669    partially_finished_topic_description: Option<TopicDescription>,
5670}
5671
5672/// Builds the paginated `describeTopicPartitions` [`Call`] for
5673/// `describeTopics` by name (KIP-966).
5674///
5675/// Translated from
5676/// `KafkaAdminClient#generateDescribeTopicsCallWithDescribeTopicPartitionsApi`:
5677///
5678/// - Every request names the topics not yet completed, sorted, with
5679///   `ResponsePartitionLimit = partitionSizeLimitPerResponse`. While a topic is
5680///   partially described, the request carries a cursor at that topic and its
5681///   next partition index.
5682/// - Each response completes the topics it finishes, fails the ones carrying a
5683///   topic error, and keeps the `NextCursor` topic as partially described. If
5684///   any topic is left, the call is issued again (`runnable.call(this, ..)`,
5685///   [`HandleResult::CallAgain`]), keeping its retry state.
5686/// - On `UnsupportedVersionException` it issues the Metadata-API call
5687///   ([`get_describe_topics_by_names_call`]) and fails itself without failing
5688///   the futures, which the Metadata call then completes.
5689///
5690/// `ctx` is the `runnable` Java's anonymous subclass closes over, and
5691/// `default_api_timeout_ms` the client field `calcDeadlineMs` reads.
5692fn generate_describe_topics_call_with_describe_topic_partitions_api(
5693    topic_names_list: Vec<String>,
5694    topic_futures: Arc<HashMap<String, KafkaFutureImpl<TopicDescription>>>,
5695    nodes: HashMap<i32, Node>,
5696    options: DescribeTopicsOptions,
5697    now: i64,
5698    ctx: DriverContext,
5699    default_api_timeout_ms: i32,
5700) -> Call {
5701    let timeout_ms = options.timeout_ms();
5702    let include_authorized_operations = options.include_authorized_operations();
5703    let partition_size_limit_per_response = options.partition_size_limit_per_response();
5704    let state = Arc::new(Mutex::new(DescribeTopicPartitionsState {
5705        topics_requests: topic_names_list.iter().cloned().collect(),
5706        partially_finished_topic_description: None,
5707    }));
5708
5709    let req_state = Arc::clone(&state);
5710    let create_request = Box::new(move |_timeout_ms: i32| {
5711        let state = req_state.lock().unwrap();
5712        let mut request = DescribeTopicPartitionsRequestData::new();
5713        request.set_topics(
5714            state
5715                .topics_requests
5716                .iter()
5717                .map(|topic_name| {
5718                    let mut topic = TopicRequest::new();
5719                    topic.set_name(topic_name.clone());
5720                    topic
5721                })
5722                .collect(),
5723        );
5724        request.set_response_partition_limit(partition_size_limit_per_response);
5725        if let Some(partially_finished) = &state.partially_finished_topic_description {
5726            // If the previous cursor points to partition 0, it will not be set
5727            // here. Instead, the previous cursor topic will be the first topic in
5728            // the request.
5729            let mut cursor = DescribeTopicPartitionsCursor::new();
5730            cursor
5731                .set_topic_name(partially_finished.name().to_string())
5732                .set_partition_index(partially_finished.partitions().len() as i32);
5733            request.set_cursor(Some(cursor));
5734        }
5735        Ok(Box::new(describe_topic_partitions_request::Builder::with_data(request)) as Box<dyn RequestBuilder>)
5736    });
5737
5738    let resp_state = Arc::clone(&state);
5739    let resp_futures = Arc::clone(&topic_futures);
5740    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
5741        let ConcreteResponse::DescribeTopicPartitions(response) = response else {
5742            return HandleResult::Retry(Error::local_illegal_state("Expected a DescribeTopicPartitions response"));
5743        };
5744        let mut state = resp_state.lock().unwrap();
5745        let mut response_cursor = response.data().next_cursor.as_ref();
5746        // The topicDescription for the cursor topic of the current batch.
5747        let mut next_topic_description: Option<TopicDescription> = None;
5748
5749        for topic in &response.data().topics {
5750            // Java looks the name up in `topicFutures` and dereferences the
5751            // result, so a topic the request did not name (or a null name)
5752            // would throw a `NullPointerException`. A broker only answers for
5753            // the topics it was asked about; such an entry is ignored here.
5754            let Some(topic_name) = topic.name.as_deref() else {
5755                continue;
5756            };
5757            let Some(future) = resp_futures.get(topic_name) else {
5758                continue;
5759            };
5760            let error = Errors::for_code(topic.error_code);
5761            if error != Errors::None {
5762                future.complete_with_error(Error::new(error));
5763                state.topics_requests.remove(topic_name);
5764                if response_cursor.is_some_and(|cursor| cursor.topic_name == topic_name) {
5765                    response_cursor = None;
5766                }
5767                continue;
5768            }
5769
5770            let current_topic_description =
5771                topic_description_from_describe_topics_response_topic(topic, &nodes, include_authorized_operations);
5772
5773            if let Some(partially_finished) = state.partially_finished_topic_description.as_mut()
5774                && partially_finished.name() == topic_name
5775            {
5776                // Add the partitions for the cursor topic of the previous batch.
5777                partially_finished
5778                    .partitions_mut()
5779                    .extend_from_slice(current_topic_description.partitions());
5780                continue;
5781            }
5782
5783            if response_cursor.is_some_and(|cursor| cursor.topic_name == topic_name) {
5784                // In the same batch of result, it may need to handle the
5785                // partitions for the previous cursor topic and the current
5786                // cursor topic. Cache the result in the nextTopicDescription.
5787                next_topic_description = Some(current_topic_description);
5788                continue;
5789            }
5790
5791            state.topics_requests.remove(topic_name);
5792            future.complete(current_topic_description);
5793        }
5794
5795        let finishes_partial = match (&state.partially_finished_topic_description, response_cursor) {
5796            (Some(partially_finished), Some(cursor)) => cursor.topic_name != partially_finished.name(),
5797            (Some(_), None) => true,
5798            (None, _) => false,
5799        };
5800        if finishes_partial {
5801            // We can't simply check nextTopicDescription != null here to close
5802            // the partiallyFinishedTopicDescription, because the responseCursor
5803            // topic may not show in the response.
5804            if let Some(partially_finished) = state.partially_finished_topic_description.take() {
5805                let topic_name = partially_finished.name().to_string();
5806                if let Some(future) = resp_futures.get(&topic_name) {
5807                    future.complete(partially_finished);
5808                }
5809                state.topics_requests.remove(&topic_name);
5810            }
5811        }
5812        if next_topic_description.is_some() {
5813            state.partially_finished_topic_description = next_topic_description;
5814        }
5815
5816        if state.topics_requests.is_empty() {
5817            HandleResult::Done
5818        } else {
5819            HandleResult::CallAgain
5820        }
5821    });
5822
5823    let fail_futures = Arc::clone(&topic_futures);
5824    let handle_failure = Box::new(move |error: &Error| {
5825        // An UnsupportedVersionException is not the user's failure: the
5826        // Metadata-API call issued by the hook below completes the futures
5827        // (`org.apache.kafka.clients.admin.KafkaAdminClient#generateDescribeTopicsCallWithDescribeTopicPartitionsApi`).
5828        // Detected by code, because `Error::unsupported_version` builds the
5829        // generic code-35 error, as `AdminClientRunnable::fail_call` does. As in
5830        // Java, this failure is only reached after
5831        // `handleUnsupportedVersionException` issued the fallback: `fail_call`
5832        // skips that hook only once `ShutdownSignal::closing` is set, which
5833        // happens when the I/O task exits and no response is handled any more.
5834        if error.error() == Errors::UnsupportedVersion {
5835            return;
5836        }
5837        for future in fail_futures.values() {
5838            future.complete_with_error(error.clone());
5839        }
5840    });
5841
5842    // `handleUnsupportedVersionException` in
5843    // `KafkaAdminClient#generateDescribeTopicsCallWithDescribeTopicPartitionsApi`:
5844    // issue the Metadata-API call through `runnable.call`, and return `false`.
5845    let handle_uv = Box::new(move |_error: &Error| {
5846        let now = ctx.time.milliseconds();
5847        ctx.sender.call(get_describe_topics_by_names_call(
5848            Arc::clone(&topic_futures),
5849            topic_names_list.clone(),
5850            include_authorized_operations,
5851            calc_deadline_ms(now, timeout_ms, default_api_timeout_ms),
5852        ));
5853        false
5854    });
5855
5856    Call::new(
5857        "describeTopicPartitions",
5858        calc_deadline_ms(now, timeout_ms, default_api_timeout_ms),
5859        NodeProvider::LeastLoaded,
5860        create_request,
5861        handle_response,
5862        handle_failure,
5863        handle_uv,
5864    )
5865}
5866
5867/// Builds a [`TopicDescription`] from one `DescribeTopicPartitions` response
5868/// topic, resolving broker ids through `nodes`. The authorized operations are
5869/// `None` unless `include_authorized_operations` was requested.
5870///
5871/// Translated from `KafkaAdminClient.getTopicDescriptionFromDescribeTopicsResponseTopic`.
5872fn topic_description_from_describe_topics_response_topic(
5873    topic: &DescribeTopicPartitionsResponseTopic,
5874    nodes: &HashMap<i32, Node>,
5875    include_authorized_operations: bool,
5876) -> TopicDescription {
5877    let partitions = topic
5878        .partitions
5879        .iter()
5880        .map(|partition| DescribeTopicPartitionsResponse::partition_to_topic_partition_info(partition, nodes))
5881        .collect();
5882    let authorised_operations = if include_authorized_operations {
5883        AdminUtils::valid_acl_operations(topic.topic_authorized_operations)
5884    } else {
5885        None
5886    };
5887    TopicDescription::with_authorized_operations_topic_id(
5888        topic.name.clone().unwrap_or_default(),
5889        topic.is_internal,
5890        partitions,
5891        authorised_operations,
5892        topic.topic_id,
5893    )
5894}
5895
5896/// Builds a `describeTopics` (by id) [`Call`] using the Metadata API.
5897/// Translated from `KafkaAdminClient.handleDescribeTopicsByIds`.
5898fn get_describe_topics_by_ids_call(
5899    futures: Arc<HashMap<Uuid, KafkaFutureImpl<TopicDescription>>>,
5900    ids: Vec<Uuid>,
5901    include_authorized_operations: bool,
5902    deadline: i64,
5903) -> Call {
5904    let req_ids = ids.clone();
5905    let create_request = Box::new(move |_timeout_ms: i32| {
5906        let mut data = crate::MetadataRequestData::new();
5907        data.set_topics(Some(
5908            crate::common::requests::MetadataRequest::convert_topic_ids_to_metadata_request_topic(&req_ids),
5909        ));
5910        data.set_allow_auto_topic_creation(false);
5911        data.set_include_topic_authorized_operations(include_authorized_operations);
5912        Ok(Box::new(metadata_request::Builder::with_data(data)) as Box<dyn RequestBuilder>)
5913    });
5914
5915    let resp_futures = Arc::clone(&futures);
5916    let handle_response = Box::new(move |response: &ConcreteResponse, _now: i64, _cur_node: Option<&Node>| {
5917        let ConcreteResponse::Metadata(metadata_response) = response else {
5918            return HandleResult::Retry(Error::local_illegal_state("Expected a Metadata response"));
5919        };
5920        let cluster = metadata_response.build_cluster();
5921        // Java's `errorsByTopicId()` throws `IllegalStateException` on a zero topic
5922        // id, and
5923        // `org.apache.kafka.clients.admin.KafkaAdminClient.AdminClientRunnable#handleResponses`
5924        // catches it with `call.fail(now, t)`. `Retry` routes the error through
5925        // `fail_call` the same way; it is not retriable, so only this call fails.
5926        let errors = match metadata_response.errors_by_topic_id() {
5927            Ok(errors) => errors,
5928            Err(error) => return HandleResult::Retry(error),
5929        };
5930        for (topic_id, future) in resp_futures.iter() {
5931            let Some(topic_name) = cluster.topic_name(topic_id) else {
5932                future.complete_with_error(Error::with_message(
5933                    Errors::UnknownTopicId,
5934                    format!("TopicId {topic_id} not found."),
5935                ));
5936                continue;
5937            };
5938            let topic_name = topic_name.to_string();
5939            if let Some(topic_error) = errors.get(topic_id) {
5940                future.complete_with_error(Error::new(*topic_error));
5941                continue;
5942            }
5943            let authorized_operations = metadata_response
5944                .topic_authorized_operations(&topic_name)
5945                .unwrap_or(MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED);
5946            future.complete(topic_description_from_cluster(
5947                &cluster,
5948                &topic_name,
5949                *topic_id,
5950                authorized_operations,
5951            ));
5952        }
5953        HandleResult::Done
5954    });
5955
5956    let fail_futures = Arc::clone(&futures);
5957    let handle_failure = Box::new(move |error: &Error| {
5958        for future in fail_futures.values() {
5959            future.complete_with_error(error.clone());
5960        }
5961    });
5962
5963    Call::new(
5964        "describeTopicsWithIds",
5965        deadline,
5966        NodeProvider::LeastLoaded,
5967        create_request,
5968        handle_response,
5969        handle_failure,
5970        Box::new(|_| false),
5971    )
5972}
5973
5974#[cfg(test)]
5975impl KafkaAdminClient {
5976    /// Test-only constructor: wires the client over an arbitrary
5977    /// [`KafkaClient`] with a pre-seeded cluster and does **not** spawn the
5978    /// background task. The caller drives [`AdminClientRunnable::run_once`].
5979    ///
5980    /// Mirrors Java's `AdminClientUnitTestEnv`, including how it picks the
5981    /// bootstrap mode: the client uses `bootstrap.controllers` when the config
5982    /// sets that key, whatever `bootstrap.servers` holds, as
5983    /// `config.containsKey(BOOTSTRAP_CONTROLLERS_CONFIG)` decides in its
5984    /// constructor. Like that constructor, it does not run
5985    /// `determineBootstrapType`.
5986    pub(crate) fn create_for_test<C: KafkaClient + Send + 'static>(
5987        client: C,
5988        cluster: Cluster,
5989        config: &AdminClientConfig,
5990        time: Arc<dyn Time>,
5991    ) -> (Self, AdminClientRunnable<C>) {
5992        // Java's `AdminClientUnitTestEnv` goes through `createInternal`, which
5993        // resolves the id with `generateClientId` exactly like production.
5994        let client_id = Self::generate_client_id(config);
5995        let log_context = LogContext::new(format!("[AdminClient clientId={client_id}] "));
5996        let metadata_manager = AdminMetadataManager::new(
5997            config.retry_backoff_ms(),
5998            config.metadata_max_age_ms(),
5999            config.user_configured(AdminClientConfig::BOOTSTRAP_CONTROLLERS_CONFIG),
6000            log_context.clone(),
6001        );
6002        metadata_manager.update(cluster, time.milliseconds());
6003        // Test-only: the fixture's config is valid (`default.api.timeout.ms` no
6004        // smaller than `request.timeout.ms` when set) and a bad
6005        // `RETRY_BACKOFF_JITTER` constant is a build error, so panicking here is
6006        // the right test behaviour.
6007        Self::build(client, metadata_manager, config, client_id, time, log_context)
6008            .expect("the test config is valid and the admin retry backoff constants are valid")
6009    }
6010}
6011
6012#[cfg(test)]
6013mod tests {
6014    use super::*;
6015    use crate::admin::mock_admin_client;
6016    use crate::common::utils::MockTime;
6017    use std::collections::{HashMap, HashSet};
6018    use std::sync::atomic::{AtomicI64, AtomicUsize, Ordering};
6019
6020    use crate::CreatePartitionsResponseData;
6021    use crate::CreateTopicsResponseData;
6022    use crate::DeleteRecordsResponseData;
6023    use crate::DeleteTopicsResponseData;
6024    use crate::MockClient;
6025    use crate::admin::MemberToRemove;
6026    use crate::admin::internals::AdminClientRunnable;
6027    use crate::common::Node;
6028    use crate::common::protocol::Errors;
6029    use crate::common::requests::RequestTestUtils;
6030    use crate::common::requests::metadata_response::{PartitionMetadata, TopicMetadata};
6031    use crate::common::requests::{CreatePartitionsResponse, DeleteRecordsResponse};
6032    use crate::common::requests::{CreateTopicsResponse, DeleteTopicsResponse};
6033    use crate::common::{TopicCollection, TopicPartition, Uuid};
6034    use crate::consumer::internals::ConsumerProtocol;
6035    use crate::create_partitions_response_data::CreatePartitionsTopicResult;
6036    use crate::create_topics_response_data::CreatableTopicResult;
6037    use crate::delete_records_response_data::{DeleteRecordsPartitionResult, DeleteRecordsTopicResult};
6038    use crate::delete_topics_response_data::DeletableTopicResult;
6039
6040    /// Mirrors Java `ApiError.messageWithFallback()`: the code's default text is
6041    /// used ONLY when the broker sent no message (null / `None`); a non-null
6042    /// empty message is returned verbatim, and any other message as-is.
6043    #[test]
6044    fn message_with_fallback_matches_java_apierror() {
6045        let code = Errors::InvalidTopicError.code();
6046        assert_eq!(
6047            KafkaAdminClient::message_with_fallback(code, &None),
6048            Errors::InvalidTopicError.message(),
6049            "null message falls back to the code's default text"
6050        );
6051        assert_eq!(
6052            KafkaAdminClient::message_with_fallback(code, &Some(String::new())),
6053            "",
6054            "a non-null empty message is returned verbatim, NOT the default"
6055        );
6056        assert_eq!(
6057            KafkaAdminClient::message_with_fallback(code, &Some("boom".to_string())),
6058            "boom",
6059            "a non-empty message is returned verbatim"
6060        );
6061    }
6062
6063    /// Mirrors Java `Errors#exception(String)`, which
6064    /// `ApiError.exception()` delegates to: the code's default text is used ONLY
6065    /// when the broker sent `null`; a non-null empty message is used verbatim.
6066    #[test]
6067    fn api_error_matches_java_errors_message_fallback() {
6068        let code = Errors::NotController.code();
6069        let default_message = Errors::NotController.message();
6070
6071        let absent = api_error(code, &None);
6072        assert_eq!(absent.error(), Errors::NotController);
6073        assert_eq!(
6074            absent.message(),
6075            default_message,
6076            "a null message falls back to the code's default text"
6077        );
6078
6079        let empty = api_error(code, &Some(String::new()));
6080        assert_eq!(empty.error(), Errors::NotController, "the code survives an empty message");
6081        assert_eq!(
6082            empty.message(),
6083            "",
6084            "a non-null empty message is used verbatim, NOT the default"
6085        );
6086
6087        let present = api_error(code, &Some("boom".to_string()));
6088        assert_eq!(present.error(), Errors::NotController);
6089        assert_eq!(present.message(), "boom");
6090    }
6091
6092    /// Java's `new MockTime()` started at `initial_ms`, with a frozen monotonic clock.
6093    fn mock_time(initial_ms: i64) -> Arc<MockTime> {
6094        Arc::new(MockTime::with_auto_tick_ms_current_time_ms_current_high_res_time_ns(
6095            0, initial_ms, 0,
6096        ))
6097    }
6098
6099    fn test_config() -> AdminClientConfig {
6100        let mut props = HashMap::new();
6101        props.insert("bootstrap.servers".to_string(), "localhost:9092".to_string());
6102        // Bound the retry count so failure tests terminate.
6103        props.insert("retries".to_string(), "2".to_string());
6104        AdminClientConfig::new(&props).unwrap()
6105    }
6106
6107    fn mock_cluster(num_nodes: i32, controller: i32) -> (Cluster, Vec<Node>) {
6108        let nodes: Vec<Node> = (0..num_nodes)
6109            .map(|i| Node::new(i, "localhost".to_string(), 9092 + i))
6110            .collect();
6111        let controller_node = nodes.iter().find(|n| n.id() == controller).cloned();
6112        let cluster = Cluster::with_invalid_topics_controller_topic_ids(
6113            Some("mock-cluster".to_string()),
6114            nodes.clone(),
6115            Vec::new(),
6116            HashSet::new(),
6117            HashSet::new(),
6118            HashSet::new(),
6119            controller_node,
6120            HashMap::new(),
6121        );
6122        (cluster, nodes)
6123    }
6124
6125    /// Builds a test environment mirroring Java's `AdminClientUnitTestEnv`.
6126    fn env() -> (KafkaAdminClient, AdminClientRunnable<MockClient>, Arc<MockTime>, Vec<Node>) {
6127        // Start at a non-zero time: MockClient's `not_throttled(0)` returns
6128        // false when `throttled_until_ms` is also 0, so a node never becomes
6129        // ready at t=0 (matching the producer's `SenderTest` which starts at
6130        // 1000 for the same reason).
6131        let time = mock_time(1000);
6132        let (cluster, nodes) = mock_cluster(3, 0);
6133        let client = MockClient::with_static_nodes(nodes.clone(), Arc::clone(&time) as Arc<dyn Time>);
6134        let config = test_config();
6135        let (admin, runnable) =
6136            KafkaAdminClient::create_for_test(client, cluster, &config, Arc::clone(&time) as Arc<dyn Time>);
6137        (admin, runnable, time, nodes)
6138    }
6139
6140    /// Builds a test environment with extra config properties (e.g. a custom
6141    /// `default.api.timeout.ms` or `retry.backoff.ms`).
6142    fn env_with_props(
6143        extra: &[(&str, &str)],
6144    ) -> (KafkaAdminClient, AdminClientRunnable<MockClient>, Arc<MockTime>, Vec<Node>) {
6145        let time = mock_time(1000);
6146        let (cluster, nodes) = mock_cluster(3, 0);
6147        let client = MockClient::with_static_nodes(nodes.clone(), Arc::clone(&time) as Arc<dyn Time>);
6148        let mut props = HashMap::new();
6149        props.insert("bootstrap.servers".to_string(), "localhost:9092".to_string());
6150        for (k, v) in extra {
6151            props.insert((*k).to_string(), (*v).to_string());
6152        }
6153        let config = AdminClientConfig::new(&props).unwrap();
6154        let (admin, runnable) =
6155            KafkaAdminClient::create_for_test(client, cluster, &config, Arc::clone(&time) as Arc<dyn Time>);
6156        (admin, runnable, time, nodes)
6157    }
6158
6159    /// Translated from `KafkaAdminClientTest.testGenerateClientId`.
6160    #[test]
6161    fn test_generate_client_id() {
6162        let conf = |client_id: &str| {
6163            let mut props = HashMap::new();
6164            props.insert("bootstrap.servers".to_string(), "localhost:9092".to_string());
6165            props.insert("client.id".to_string(), client_id.to_string());
6166            AdminClientConfig::new(&props).unwrap()
6167        };
6168        let mut ids = HashSet::new();
6169        for _ in 0..10 {
6170            let id = KafkaAdminClient::generate_client_id(&conf(""));
6171            assert!(!ids.contains(&id), "Got duplicate id {id}");
6172            ids.insert(id);
6173        }
6174        assert_eq!("myCustomId", KafkaAdminClient::generate_client_id(&conf("myCustomId")));
6175    }
6176
6177    /// `ConfigDef.parseType` trims `client.id`, so a blank one generates an id
6178    /// and a padded one is kept without its padding.
6179    #[test]
6180    fn test_generate_client_id_trims_client_id() {
6181        let conf = |client_id: &str| {
6182            let mut props = HashMap::new();
6183            props.insert("bootstrap.servers".to_string(), "localhost:9092".to_string());
6184            props.insert("client.id".to_string(), client_id.to_string());
6185            AdminClientConfig::new(&props).unwrap()
6186        };
6187        let id = KafkaAdminClient::generate_client_id(&conf(" "));
6188        assert!(id.starts_with("adminclient-"), "unexpected generated id {id:?}");
6189        assert_eq!("myCustomId", KafkaAdminClient::generate_client_id(&conf(" myCustomId ")));
6190    }
6191
6192    /// Beyond Java's test: the generated form is `adminclient-<n>`, and it is
6193    /// what the client carries (`Shared.client_id`), not the empty config
6194    /// value. Mirrors Java's `testMetricsReporterAutoGeneratedClientId`
6195    /// asserting the resolved id on the constructed client.
6196    #[test]
6197    fn test_generated_client_id_is_used_by_the_client() {
6198        let (admin, _runnable, _time, _nodes) = env();
6199        let id = admin.shared.client_id.clone();
6200        let n = id
6201            .strip_prefix("adminclient-")
6202            .unwrap_or_else(|| panic!("unexpected generated id {id}"));
6203        assert!(n.parse::<i32>().unwrap() >= 1, "unexpected generated id {id}");
6204
6205        let (admin, _runnable, _time, _nodes) = env_with_props(&[("client.id", "myCustomId")]);
6206        assert_eq!(admin.shared.client_id, "myCustomId");
6207    }
6208
6209    /// Like [`env_with_props`], but with a configurable broker count (mirrors
6210    /// Java's `mockCluster(numNodes, 0)`). Used by the group-listing broker
6211    /// enumeration tests that want a single broker.
6212    fn env_nodes_with_props(
6213        num_nodes: i32,
6214        extra: &[(&str, &str)],
6215    ) -> (KafkaAdminClient, AdminClientRunnable<MockClient>, Arc<MockTime>, Vec<Node>) {
6216        let time = mock_time(1000);
6217        let (cluster, nodes) = mock_cluster(num_nodes, 0);
6218        let client = MockClient::with_static_nodes(nodes.clone(), Arc::clone(&time) as Arc<dyn Time>);
6219        let mut props = HashMap::new();
6220        props.insert("bootstrap.servers".to_string(), "localhost:9092".to_string());
6221        for (k, v) in extra {
6222            props.insert((*k).to_string(), (*v).to_string());
6223        }
6224        let config = AdminClientConfig::new(&props).unwrap();
6225        let (admin, runnable) =
6226            KafkaAdminClient::create_for_test(client, cluster, &config, Arc::clone(&time) as Arc<dyn Time>);
6227        (admin, runnable, time, nodes)
6228    }
6229
6230    async fn pump(runnable: &mut AdminClientRunnable<MockClient>, iters: usize) {
6231        for _ in 0..iters {
6232            runnable.run_once().await;
6233        }
6234    }
6235
6236    /// Pumps `run_once` until at least one request is queued (sent but not yet
6237    /// responded), so a test can inspect the emitted wire request.
6238    async fn pump_until_request_queued(runnable: &mut AdminClientRunnable<MockClient>) {
6239        for _ in 0..40 {
6240            if runnable.client_mut().request_count() >= 1 {
6241                return;
6242            }
6243            runnable.run_once().await;
6244        }
6245        panic!("no request was queued after pumping");
6246    }
6247
6248    /// Builds a multi-group `ListGroups` response.
6249    fn listed_groups(groups: &[(&str, &str, &str, &str)]) -> ConcreteResponse {
6250        use crate::ListGroupsResponseData;
6251        use crate::list_groups_response_data::ListedGroup;
6252        let wire: Vec<ListedGroup> = groups
6253            .iter()
6254            .map(|(id, protocol_type, state, group_type)| {
6255                let mut g = ListedGroup::new();
6256                g.set_group_id((*id).to_string())
6257                    .set_protocol_type((*protocol_type).to_string())
6258                    .set_group_state((*state).to_string())
6259                    .set_group_type((*group_type).to_string());
6260                g
6261            })
6262            .collect();
6263        let mut data = ListGroupsResponseData::new();
6264        data.set_groups(wire);
6265        ConcreteResponse::ListGroups(crate::common::requests::ListGroupsResponse::new(data))
6266    }
6267
6268    fn create_result(name: &str, error: Errors, error_message: Option<&str>) -> CreatableTopicResult {
6269        let mut r = CreatableTopicResult::new();
6270        r.set_name(name.to_string());
6271        r.set_error_code(error.code());
6272        r.set_error_message(error_message.map(str::to_string));
6273        r.set_topic_id(Uuid::new(0, 7));
6274        r.set_num_partitions(1);
6275        r.set_replication_factor(1);
6276        r
6277    }
6278
6279    fn create_response(results: Vec<CreatableTopicResult>) -> ConcreteResponse {
6280        create_response_throttled(0, results)
6281    }
6282
6283    fn create_response_throttled(throttle_ms: i32, results: Vec<CreatableTopicResult>) -> ConcreteResponse {
6284        let mut data = CreateTopicsResponseData::new();
6285        data.set_throttle_time_ms(throttle_ms);
6286        data.set_topics(results);
6287        ConcreteResponse::CreateTopics(CreateTopicsResponse::new(data))
6288    }
6289
6290    fn delete_result_named(name: &str, error: Errors) -> DeletableTopicResult {
6291        let mut r = DeletableTopicResult::new();
6292        r.set_name(Some(name.to_string()));
6293        r.set_error_code(error.code());
6294        r
6295    }
6296
6297    fn delete_result_with_id(id: Uuid, error: Errors) -> DeletableTopicResult {
6298        let mut r = DeletableTopicResult::new();
6299        r.set_topic_id(id);
6300        r.set_error_code(error.code());
6301        r
6302    }
6303
6304    fn delete_response(results: Vec<DeletableTopicResult>) -> ConcreteResponse {
6305        delete_response_throttled(0, results)
6306    }
6307
6308    fn delete_response_throttled(throttle_ms: i32, results: Vec<DeletableTopicResult>) -> ConcreteResponse {
6309        let mut data = DeleteTopicsResponseData::new();
6310        data.set_throttle_time_ms(throttle_ms);
6311        data.set_responses(results);
6312        ConcreteResponse::DeleteTopics(DeleteTopicsResponse::new(data))
6313    }
6314
6315    /// Pumps `run_once` until `done` returns true or `max_iters` is reached,
6316    /// mirroring Java's `TestUtils.waitForCondition` over the driven runnable.
6317    async fn pump_until(
6318        runnable: &mut AdminClientRunnable<MockClient>,
6319        max_iters: usize,
6320        mut done: impl FnMut(&mut AdminClientRunnable<MockClient>) -> bool,
6321    ) {
6322        for _ in 0..max_iters {
6323            if done(runnable) {
6324                return;
6325            }
6326            runnable.run_once().await;
6327        }
6328    }
6329
6330    fn topic_meta(name: &str, internal: bool, id: Uuid, partitions: i32) -> TopicMetadata {
6331        let mut partition_metadata = Vec::new();
6332        for p in 0..partitions {
6333            partition_metadata.push(PartitionMetadata {
6334                error: Errors::None,
6335                topic_partition: TopicPartition::new(name.to_string(), p),
6336                leader_id: Some(0),
6337                leader_epoch: Some(0),
6338                replica_ids: vec![0],
6339                in_sync_replica_ids: vec![0],
6340                offline_replica_ids: vec![],
6341            });
6342        }
6343        TopicMetadata {
6344            error: Errors::None,
6345            topic: name.to_string(),
6346            topic_id: id,
6347            is_internal: internal,
6348            partition_metadata,
6349            authorized_operations: MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED,
6350        }
6351    }
6352
6353    // --- ACLs (createAcls / describeAcls / deleteAcls) -----------------------
6354
6355    use crate::CreateAclsResponseData;
6356    use crate::DeleteAclsResponseData;
6357    use crate::DescribeAclsResponseData;
6358    use crate::common::acl::{AccessControlEntry, AccessControlEntryFilter, AclPermissionType};
6359    use crate::common::protocol::ApiKeys;
6360    use crate::common::requests::{CreateAclsResponse, DeleteAclsResponse, DescribeAclsResponse};
6361    use crate::common::resource::{PatternType, ResourcePattern, ResourcePatternFilter, ResourceType};
6362    use crate::create_acls_response_data::AclCreationResult;
6363    use crate::delete_acls_response_data::DeleteAclsFilterResult;
6364
6365    fn acl1() -> AclBinding {
6366        AclBinding::new(
6367            ResourcePattern::new(ResourceType::Topic, "mytopic3", PatternType::Literal).unwrap(),
6368            AccessControlEntry::new("User:ANONYMOUS", "*", AclOperation::Describe, AclPermissionType::Allow).unwrap(),
6369        )
6370    }
6371
6372    fn acl2() -> AclBinding {
6373        AclBinding::new(
6374            ResourcePattern::new(ResourceType::Topic, "mytopic4", PatternType::Literal).unwrap(),
6375            AccessControlEntry::new("User:ANONYMOUS", "*", AclOperation::Describe, AclPermissionType::Deny).unwrap(),
6376        )
6377    }
6378
6379    fn filter1() -> AclBindingFilter {
6380        AclBindingFilter::new(
6381            ResourcePatternFilter::new(ResourceType::Any, None, PatternType::Literal),
6382            AccessControlEntryFilter::new(
6383                Some("User:ANONYMOUS".to_string()),
6384                None,
6385                AclOperation::Any,
6386                AclPermissionType::Any,
6387            ),
6388        )
6389    }
6390
6391    fn filter2() -> AclBindingFilter {
6392        AclBindingFilter::new(
6393            ResourcePatternFilter::new(ResourceType::Any, None, PatternType::Literal),
6394            AccessControlEntryFilter::new(
6395                Some("User:bob".to_string()),
6396                None,
6397                AclOperation::Any,
6398                AclPermissionType::Any,
6399            ),
6400        )
6401    }
6402
6403    fn unknown_filter() -> AclBindingFilter {
6404        AclBindingFilter::new(
6405            ResourcePatternFilter::new(ResourceType::Unknown, None, PatternType::Literal),
6406            AccessControlEntryFilter::new(
6407                Some("User:bob".to_string()),
6408                None,
6409                AclOperation::Any,
6410                AclPermissionType::Any,
6411            ),
6412        )
6413    }
6414
6415    fn create_acls_result_ok() -> AclCreationResult {
6416        AclCreationResult::new()
6417    }
6418
6419    fn create_acls_result_error(error: Errors, message: &str) -> AclCreationResult {
6420        let mut r = AclCreationResult::new();
6421        r.set_error_code(error.code());
6422        r.set_error_message(Some(message.to_string()));
6423        r
6424    }
6425
6426    fn create_acls_response(results: Vec<AclCreationResult>) -> ConcreteResponse {
6427        let mut data = CreateAclsResponseData::new();
6428        data.set_results(results);
6429        ConcreteResponse::CreateAcls(CreateAclsResponse::new(data))
6430    }
6431
6432    fn describe_acls_response(resources_from: &[AclBinding]) -> ConcreteResponse {
6433        let mut data = DescribeAclsResponseData::new();
6434        data.set_resources(DescribeAclsResponse::acls_resources(resources_from));
6435        ConcreteResponse::DescribeAcls(DescribeAclsResponse::new(data, ApiKeys::DESCRIBE_ACLS.latest_version()))
6436    }
6437
6438    fn describe_acls_error_response(error: Errors, message: &str) -> ConcreteResponse {
6439        let mut data = DescribeAclsResponseData::new();
6440        data.set_error_code(error.code());
6441        data.set_error_message(Some(message.to_string()));
6442        ConcreteResponse::DescribeAcls(DescribeAclsResponse::new(data, ApiKeys::DESCRIBE_ACLS.latest_version()))
6443    }
6444
6445    fn delete_acls_response(filter_results: Vec<DeleteAclsFilterResult>) -> ConcreteResponse {
6446        let mut data = DeleteAclsResponseData::new();
6447        data.set_throttle_time_ms(0);
6448        data.set_filter_results(filter_results);
6449        ConcreteResponse::DeleteAcls(DeleteAclsResponse::new(data, ApiKeys::DELETE_ACLS.latest_version()))
6450    }
6451
6452    /// Translated from `KafkaAdminClientTest.testDescribeAcls`.
6453    #[tokio::test]
6454    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testDescribeAcls")]
6455    async fn test_describe_acls() {
6456        let (admin, mut runnable, _time, _nodes) = env();
6457
6458        // Test a call where we get back ACL1 and ACL2.
6459        runnable
6460            .client_mut()
6461            .prepare_response(describe_acls_response(&[acl1(), acl2()]));
6462        let result = admin.describe_acls_with_options(&filter1(), DescribeAclsOptions::new());
6463        pump(&mut runnable, 5).await;
6464        let mut acls = result.values().get().await.unwrap();
6465        acls.sort_by(|a, b| a.pattern().name().cmp(b.pattern().name()));
6466        assert_eq!(acls, vec![acl1(), acl2()]);
6467
6468        // Test a call where we get back no results.
6469        runnable.client_mut().prepare_response(describe_acls_response(&[]));
6470        let result = admin.describe_acls_with_options(&filter2(), DescribeAclsOptions::new());
6471        pump(&mut runnable, 5).await;
6472        assert!(result.values().get().await.unwrap().is_empty());
6473
6474        // Test a call where we get back an error.
6475        runnable
6476            .client_mut()
6477            .prepare_response(describe_acls_error_response(Errors::SecurityDisabled, "Security is disabled"));
6478        let result = admin.describe_acls_with_options(&filter2(), DescribeAclsOptions::new());
6479        pump(&mut runnable, 5).await;
6480        let err = result.values().get().await.unwrap_err();
6481        assert_eq!(err.error(), Errors::SecurityDisabled);
6482
6483        // Test a call where we supply an invalid filter: completes exceptionally
6484        // with InvalidRequest and enqueues NO network call.
6485        let before = runnable.client_mut().request_count();
6486        let result = admin.describe_acls_with_options(&unknown_filter(), DescribeAclsOptions::new());
6487        assert!(result.values().is_done());
6488        pump(&mut runnable, 5).await;
6489        assert_eq!(
6490            runnable.client_mut().request_count(),
6491            before,
6492            "unknown filter must not enqueue a Call"
6493        );
6494        let err = result.values().get().await.unwrap_err();
6495        assert_eq!(err.error(), Errors::InvalidRequest);
6496        // Java's text
6497        // (`org.apache.kafka.clients.admin.KafkaAdminClient#describeAcls`).
6498        assert_eq!(err.message(), "The AclBindingFilter must not contain UNKNOWN elements.");
6499    }
6500
6501    /// Translated from `KafkaAdminClientTest.testCreateAcls`.
6502    #[tokio::test]
6503    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testCreateAcls")]
6504    async fn test_create_acls() {
6505        let (admin, mut runnable, _time, _nodes) = env();
6506
6507        // Test a call where we successfully create two ACLs.
6508        runnable
6509            .client_mut()
6510            .prepare_response(create_acls_response(vec![create_acls_result_ok(), create_acls_result_ok()]));
6511        let results = admin.create_acls_with_options(&[acl1(), acl2()], CreateAclsOptions::new());
6512        let keys: HashSet<AclBinding> = results.values().keys().cloned().collect();
6513        assert_eq!(keys, HashSet::from([acl1(), acl2()]));
6514        pump(&mut runnable, 5).await;
6515        for future in results.values().values() {
6516            future.get().await.unwrap();
6517        }
6518        results.all().get().await.unwrap();
6519
6520        // Test a call where we fail to create one ACL.
6521        runnable.client_mut().prepare_response(create_acls_response(vec![
6522            create_acls_result_error(Errors::SecurityDisabled, "Security is disabled"),
6523            create_acls_result_ok(),
6524        ]));
6525        let results = admin.create_acls_with_options(&[acl1(), acl2()], CreateAclsOptions::new());
6526        pump(&mut runnable, 5).await;
6527        assert_eq!(
6528            results.values()[&acl1()].get().await.unwrap_err().error(),
6529            Errors::SecurityDisabled
6530        );
6531        results.values()[&acl2()].get().await.unwrap();
6532        assert_eq!(results.all().get().await.unwrap_err().error(), Errors::SecurityDisabled);
6533    }
6534
6535    /// Translated from `KafkaAdminClientConfigTest.testCreateAclsToController`.
6536    ///
6537    /// A `bootstrap.controllers` client sends `createAcls` to the active
6538    /// controller (node 0). The NOT_CONTROLLER answer clears it, the retry waits
6539    /// for the interposed `DescribeCluster` refresh of the CONTROLLER endpoint,
6540    /// and goes to the controller that refresh names (node 2).
6541    #[tokio::test]
6542    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testCreateAclsToController")]
6543    async fn test_create_acls_to_controller() {
6544        let (admin, mut runnable, time, nodes) = controller_env();
6545        runnable.client_mut().prepare_response_from(
6546            create_acls_response(vec![create_acls_result_error(Errors::NotController, "not controller")]),
6547            &nodes[0],
6548        );
6549        // should retry the describe cluster to update the metadata
6550        runnable.client_mut().prepare_response_matcher(
6551            controller_metadata_request(),
6552            prepare_describe_cluster_response(
6553                0,
6554                &nodes,
6555                "mock-cluster",
6556                2,
6557                MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED,
6558                true,
6559            ),
6560        );
6561
6562        // Test a call where we successfully create two ACLs.
6563        runnable
6564            .client_mut()
6565            .prepare_response_from(create_acls_response(vec![create_acls_result_ok()]), &nodes[2]);
6566
6567        let results = admin.create_acls_with_options(&[acl1()], CreateAclsOptions::new());
6568        let keys: HashSet<AclBinding> = results.values().keys().cloned().collect();
6569        assert_eq!(keys, HashSet::from([acl1()]));
6570        for _ in 0..30 {
6571            if results.values()[&acl1()].is_done() {
6572                break;
6573            }
6574            runnable.run_once().await;
6575            time.sleep(200);
6576        }
6577        assert!(results.values()[&acl1()].is_done(), "the retry after the refresh must complete");
6578        for future in results.values().values() {
6579            future.get().await.unwrap();
6580        }
6581        results.all().get().await.unwrap();
6582        assert_eq!(runnable.metadata_manager().controller().map(|node| node.id()), Some(2));
6583    }
6584
6585    /// Translated from `KafkaAdminClientTest.testDeleteAcls`.
6586    #[tokio::test]
6587    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testDeleteAcls")]
6588    async fn test_delete_acls() {
6589        let (admin, mut runnable, _time, _nodes) = env();
6590
6591        // Test a call where one filter has an error.
6592        let mut filter1_result = DeleteAclsFilterResult::new();
6593        filter1_result.set_matching_acls(vec![
6594            DeleteAclsResponse::matching_acl(&acl1(), Errors::None, None),
6595            DeleteAclsResponse::matching_acl(&acl2(), Errors::None, None),
6596        ]);
6597        let mut filter2_result = DeleteAclsFilterResult::new();
6598        filter2_result.set_error_code(Errors::SecurityDisabled.code());
6599        filter2_result.set_error_message(Some("No security".to_string()));
6600        runnable
6601            .client_mut()
6602            .prepare_response(delete_acls_response(vec![filter1_result, filter2_result]));
6603        let results = admin.delete_acls_with_options(&[filter1(), filter2()], DeleteAclsOptions::new());
6604        pump(&mut runnable, 5).await;
6605        let filter1_results = results.values()[&filter1()].get().await.unwrap();
6606        assert!(filter1_results.values()[0].error().is_none());
6607        assert_eq!(filter1_results.values()[0].binding(), Some(&acl1()));
6608        assert!(filter1_results.values()[1].error().is_none());
6609        assert_eq!(filter1_results.values()[1].binding(), Some(&acl2()));
6610        assert_eq!(
6611            results.values()[&filter2()].get().await.unwrap_err().error(),
6612            Errors::SecurityDisabled
6613        );
6614        assert_eq!(results.all().get().await.unwrap_err().error(), Errors::SecurityDisabled);
6615
6616        // Test a call where one deletion result has an error.
6617        let mut err_matching = crate::delete_acls_response_data::DeleteAclsMatchingAcl::new();
6618        err_matching
6619            .set_error_code(Errors::SecurityDisabled.code())
6620            .set_error_message(Some("No security".to_string()))
6621            .set_permission_type(AclPermissionType::Allow.code())
6622            .set_operation(AclOperation::Alter.code())
6623            .set_resource_type(ResourceType::Cluster.code())
6624            .set_pattern_type(filter2().pattern_filter().pattern_type().code());
6625        let mut filter1_result = DeleteAclsFilterResult::new();
6626        filter1_result.set_matching_acls(vec![
6627            DeleteAclsResponse::matching_acl(&acl1(), Errors::None, None),
6628            err_matching,
6629        ]);
6630        let filter2_result = DeleteAclsFilterResult::new();
6631        runnable
6632            .client_mut()
6633            .prepare_response(delete_acls_response(vec![filter1_result, filter2_result]));
6634        let results = admin.delete_acls_with_options(&[filter1(), filter2()], DeleteAclsOptions::new());
6635        pump(&mut runnable, 5).await;
6636        assert!(results.values()[&filter2()].get().await.unwrap().values().is_empty());
6637        assert_eq!(results.all().get().await.unwrap_err().error(), Errors::SecurityDisabled);
6638
6639        // Test a call where there are no errors.
6640        let mut f1 = DeleteAclsFilterResult::new();
6641        f1.set_matching_acls(vec![DeleteAclsResponse::matching_acl(&acl1(), Errors::None, None)]);
6642        let mut f2 = DeleteAclsFilterResult::new();
6643        f2.set_matching_acls(vec![DeleteAclsResponse::matching_acl(&acl2(), Errors::None, None)]);
6644        runnable.client_mut().prepare_response(delete_acls_response(vec![f1, f2]));
6645        let results = admin.delete_acls_with_options(&[filter1(), filter2()], DeleteAclsOptions::new());
6646        pump(&mut runnable, 5).await;
6647        let mut deleted = results.all().get().await.unwrap();
6648        deleted.sort_by(|a, b| a.pattern().name().cmp(b.pattern().name()));
6649        assert_eq!(deleted, vec![acl1(), acl2()]);
6650    }
6651
6652    /// Translated from `KafkaAdminClientConfigTest.testDeleteAclsToController`:
6653    /// the `deleteAcls` twin of [`test_create_acls_to_controller`].
6654    #[tokio::test]
6655    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testDeleteAclsToController")]
6656    async fn test_delete_acls_to_controller() {
6657        let (admin, mut runnable, time, nodes) = controller_env();
6658        let mut not_controller = DeleteAclsFilterResult::new();
6659        not_controller.set_error_code(Errors::NotController.code());
6660        not_controller.set_error_message(Some("not controller".to_string()));
6661        runnable
6662            .client_mut()
6663            .prepare_response_from(delete_acls_response(vec![not_controller]), &nodes[0]);
6664        // should retry the describe cluster to update the metadata
6665        runnable.client_mut().prepare_response_matcher(
6666            controller_metadata_request(),
6667            prepare_describe_cluster_response(
6668                0,
6669                &nodes,
6670                "mock-cluster",
6671                2,
6672                MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED,
6673                true,
6674            ),
6675        );
6676        // Test a call where there are no errors.
6677        let mut ok = DeleteAclsFilterResult::new();
6678        ok.set_matching_acls(vec![DeleteAclsResponse::matching_acl(&acl1(), Errors::None, None)]);
6679        runnable
6680            .client_mut()
6681            .prepare_response_from(delete_acls_response(vec![ok]), &nodes[2]);
6682
6683        let results = admin.delete_acls_with_options(&[filter1()], DeleteAclsOptions::new());
6684        for _ in 0..30 {
6685            if results.values()[&filter1()].is_done() {
6686                break;
6687            }
6688            runnable.run_once().await;
6689            time.sleep(200);
6690        }
6691        assert!(
6692            results.values()[&filter1()].is_done(),
6693            "the retry after the refresh must complete"
6694        );
6695        let deleted = results.all().get().await.unwrap();
6696        assert_eq!(deleted, vec![acl1()]);
6697        assert_eq!(runnable.metadata_manager().controller().map(|node| node.id()), Some(2));
6698    }
6699
6700    /// Behavior test: a binding with an indefinite (UNKNOWN) field fails only its
6701    /// own future; other valid bindings in the same batch still succeed.
6702    /// Mirrors `KafkaAdminClient.createAcls`' per-binding `findIndefiniteField`
6703    /// rejection.
6704    #[tokio::test]
6705    async fn test_create_acls_rejects_indefinite_binding_per_binding() {
6706        let (admin, mut runnable, _time, _nodes) = env();
6707        let bad = AclBinding::new(
6708            ResourcePattern::new(ResourceType::Topic, "mytopic3", PatternType::Literal).unwrap(),
6709            AccessControlEntry::new("User:ANONYMOUS", "*", AclOperation::Unknown, AclPermissionType::Allow).unwrap(),
6710        );
6711        // Only the valid binding is sent, so a single-result response suffices.
6712        runnable
6713            .client_mut()
6714            .prepare_response(create_acls_response(vec![create_acls_result_ok()]));
6715        let results = admin.create_acls_with_options(&[acl1(), bad.clone()], CreateAclsOptions::new());
6716        pump(&mut runnable, 5).await;
6717        results.values()[&acl1()].get().await.unwrap();
6718        let err = results.values()[&bad].get().await.unwrap_err();
6719        assert_eq!(err.error(), Errors::InvalidRequest);
6720        assert!(err.message().contains("Invalid ACL creation"));
6721    }
6722
6723    // --- client quotas (describeClientQuotas / alterClientQuotas) ------------
6724
6725    use crate::common::quota::{ClientQuotaFilterComponent, Op};
6726    use crate::common::requests::{AlterClientQuotasResponse, DescribeClientQuotasResponse};
6727
6728    /// Mirrors `KafkaAdminClientTest.newClientQuotaEntity(String...)`.
6729    fn new_client_quota_entity(args: &[&str]) -> ClientQuotaEntity {
6730        assert_eq!(args.len() % 2, 0);
6731        let mut entity_map = HashMap::new();
6732        let mut index = 0;
6733        while index < args.len() {
6734            entity_map.insert(args[index].to_string(), Some(args[index + 1].to_string()));
6735            index += 2;
6736        }
6737        ClientQuotaEntity::new(entity_map)
6738    }
6739
6740    /// Translated from `KafkaAdminClientTest.testDescribeClientQuotas`.
6741    #[tokio::test]
6742    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testDescribeClientQuotas")]
6743    async fn test_describe_client_quotas() {
6744        let (admin, mut runnable, _time, _nodes) = env();
6745
6746        let value = "value";
6747        let entity1 =
6748            new_client_quota_entity(&[ClientQuotaEntity::USER, "user-1", ClientQuotaEntity::CLIENT_ID, value]);
6749        let entity2 =
6750            new_client_quota_entity(&[ClientQuotaEntity::USER, "user-2", ClientQuotaEntity::CLIENT_ID, value]);
6751        let mut response_data = HashMap::new();
6752        response_data.insert(entity1.clone(), HashMap::from([("consumer_byte_rate".to_string(), 10000.0)]));
6753        response_data.insert(entity2.clone(), HashMap::from([("producer_byte_rate".to_string(), 20000.0)]));
6754
6755        runnable.client_mut().prepare_response(ConcreteResponse::DescribeClientQuotas(
6756            DescribeClientQuotasResponse::from_quota_entities(&response_data, 0),
6757        ));
6758
6759        let filter =
6760            ClientQuotaFilter::contains(vec![ClientQuotaFilterComponent::of_entity(ClientQuotaEntity::USER, value)]);
6761        let result = admin.describe_client_quotas_with_options(&filter, DescribeClientQuotasOptions::new());
6762        pump(&mut runnable, 5).await;
6763
6764        let result_data = result.entities().get().await.unwrap();
6765        assert_eq!(result_data.len(), 2);
6766        assert!(result_data.contains_key(&entity1));
6767        let config1 = &result_data[&entity1];
6768        assert_eq!(config1.len(), 1);
6769        assert!((config1["consumer_byte_rate"] - 10000.0).abs() < 1e-6);
6770        assert!(result_data.contains_key(&entity2));
6771        let config2 = &result_data[&entity2];
6772        assert_eq!(config2.len(), 1);
6773        assert!((config2["producer_byte_rate"] - 20000.0).abs() < 1e-6);
6774    }
6775
6776    /// Translated from `KafkaAdminClientTest.testAlterClientQuotas`.
6777    #[tokio::test]
6778    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testAlterClientQuotas")]
6779    async fn test_alter_client_quotas() {
6780        let (admin, mut runnable, _time, _nodes) = env();
6781
6782        let good_entity = new_client_quota_entity(&[ClientQuotaEntity::USER, "user-1"]);
6783        let unauthorized_entity = new_client_quota_entity(&[ClientQuotaEntity::USER, "user-0"]);
6784        let invalid_entity = new_client_quota_entity(&["", "user-0"]);
6785
6786        let response_data = vec![
6787            (
6788                good_entity.clone(),
6789                Errors::ClusterAuthorizationFailed,
6790                Some("Authorization failed".to_string()),
6791            ),
6792            (
6793                unauthorized_entity.clone(),
6794                Errors::ClusterAuthorizationFailed,
6795                Some("Authorization failed".to_string()),
6796            ),
6797            (
6798                invalid_entity.clone(),
6799                Errors::InvalidRequest,
6800                Some("Invalid quota entity".to_string()),
6801            ),
6802        ];
6803        runnable.client_mut().prepare_response(ConcreteResponse::AlterClientQuotas(
6804            AlterClientQuotasResponse::from_quota_entities(&response_data, 0),
6805        ));
6806
6807        let entries = vec![
6808            ClientQuotaAlteration::new(good_entity.clone(), vec![Op::new("consumer_byte_rate", Some(10000.0))]),
6809            ClientQuotaAlteration::new(unauthorized_entity.clone(), vec![Op::new("producer_byte_rate", Some(10000.0))]),
6810            ClientQuotaAlteration::new(invalid_entity.clone(), vec![Op::new("producer_byte_rate", Some(100.0))]),
6811        ];
6812        let result = admin.alter_client_quotas_with_options(&entries, AlterClientQuotasOptions::new());
6813        pump(&mut runnable, 5).await;
6814
6815        // good_entity got CLUSTER_AUTHORIZATION_FAILED in this response fixture.
6816        assert_eq!(
6817            result.values()[&good_entity].get().await.unwrap_err().error(),
6818            Errors::ClusterAuthorizationFailed
6819        );
6820        assert_eq!(
6821            result.values()[&unauthorized_entity].get().await.unwrap_err().error(),
6822            Errors::ClusterAuthorizationFailed
6823        );
6824        assert_eq!(
6825            result.values()[&invalid_entity].get().await.unwrap_err().error(),
6826            Errors::InvalidRequest
6827        );
6828    }
6829
6830    // --- user SCRAM credentials ----------------------------------------------
6831    // (describeUserScramCredentials / alterUserScramCredentials)
6832
6833    use crate::AlterUserScramCredentialsResponseData;
6834    use crate::admin::{
6835        AlterUserScramCredentialsOptions, DescribeUserScramCredentialsOptions, ScramCredentialInfo,
6836        ScramMechanism as PublicScramMechanism, UserScramCredentialAlteration, UserScramCredentialDeletion,
6837        UserScramCredentialUpsertion,
6838    };
6839    use crate::alter_user_scram_credentials_response_data::AlterUserScramCredentialsResult as WireAlterResult;
6840    use crate::common::requests::{AlterUserScramCredentialsResponse, DescribeUserScramCredentialsResponse};
6841    use crate::describe_user_scram_credentials_response_data::CredentialInfo as WireCredentialInfo;
6842    use crate::describe_user_scram_credentials_response_data::DescribeUserScramCredentialsResult as WireDescribeResult;
6843
6844    /// Translated from `KafkaAdminClientTest.testDescribeUserScramCredentials`.
6845    #[tokio::test]
6846    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testDescribeUserScramCredentials")]
6847    async fn test_describe_user_scram_credentials() {
6848        let user0_name = "user0";
6849        let user0_mechanism0 = PublicScramMechanism::ScramSha256;
6850        let user0_iterations0 = 4096;
6851        let user0_mechanism1 = PublicScramMechanism::ScramSha512;
6852        let user0_iterations1 = 8192;
6853
6854        let user1_name = "user1";
6855        let user1_mechanism = PublicScramMechanism::ScramSha256;
6856        let user1_iterations = 4096;
6857
6858        let mut ci0 = WireCredentialInfo::new();
6859        ci0.set_mechanism(user0_mechanism0.r#type()).set_iterations(user0_iterations0);
6860        let mut ci1 = WireCredentialInfo::new();
6861        ci1.set_mechanism(user0_mechanism1.r#type()).set_iterations(user0_iterations1);
6862        let mut ci_user1 = WireCredentialInfo::new();
6863        ci_user1
6864            .set_mechanism(user1_mechanism.r#type())
6865            .set_iterations(user1_iterations);
6866
6867        let mut r0 = WireDescribeResult::new();
6868        r0.set_user(user0_name.to_string()).set_credential_infos(vec![ci0, ci1]);
6869        let mut r1 = WireDescribeResult::new();
6870        r1.set_user(user1_name.to_string()).set_credential_infos(vec![ci_user1]);
6871        let mut response_data = DescribeUserScramCredentialsResponseData::new();
6872        response_data.set_results(vec![r0, r1]);
6873
6874        let users_requested: HashSet<String> = [user0_name.to_string(), user1_name.to_string()].into_iter().collect();
6875
6876        // Mirrors the Java loop over [null, empty, [user0, null, user1]]. Rust
6877        // has no null in a `&[String]`, so the equivalent inputs are: empty,
6878        // empty, and the explicit two-user list.
6879        for users in [
6880            Vec::<String>::new(),
6881            Vec::new(),
6882            vec![user0_name.to_string(), user1_name.to_string()],
6883        ] {
6884            let (admin, mut runnable, _time, _nodes) = env();
6885            runnable
6886                .client_mut()
6887                .prepare_response(ConcreteResponse::DescribeUserScramCredentials(
6888                    DescribeUserScramCredentialsResponse::new(response_data.clone(), 0),
6889                ));
6890
6891            let result = admin
6892                .describe_user_scram_credentials_with_users_options(&users, DescribeUserScramCredentialsOptions::new());
6893            let user0_desc_future = result.description(user0_name);
6894            let user1_desc_future = result.description(user1_name);
6895            pump(&mut runnable, 5).await;
6896
6897            let description_results = result.all().get().await.unwrap();
6898            let users_described: HashSet<String> = result.users().get().await.unwrap().into_iter().collect();
6899            assert_eq!(users_requested, users_described);
6900            assert_eq!(users_requested, description_results.keys().cloned().collect::<HashSet<_>>());
6901
6902            let desc0 = &description_results[user0_name];
6903            assert_eq!(desc0.name(), user0_name);
6904            assert_eq!(desc0.credential_infos().len(), 2);
6905            assert_eq!(desc0.credential_infos()[0].mechanism(), user0_mechanism0);
6906            assert_eq!(desc0.credential_infos()[0].iterations(), user0_iterations0);
6907            assert_eq!(desc0.credential_infos()[1].mechanism(), user0_mechanism1);
6908            assert_eq!(desc0.credential_infos()[1].iterations(), user0_iterations1);
6909            assert_eq!(*desc0, user0_desc_future.get().await.unwrap());
6910
6911            let desc1 = &description_results[user1_name];
6912            assert_eq!(desc1.name(), user1_name);
6913            assert_eq!(desc1.credential_infos().len(), 1);
6914            assert_eq!(desc1.credential_infos()[0].mechanism(), user1_mechanism);
6915            assert_eq!(desc1.credential_infos()[0].iterations(), user1_iterations);
6916            assert_eq!(*desc1, user1_desc_future.get().await.unwrap());
6917        }
6918    }
6919
6920    /// Translated from
6921    /// `KafkaAdminClientTest.testAlterUserScramCredentialsUnknownMechanism`.
6922    #[tokio::test]
6923    #[doc(
6924        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testAlterUserScramCredentialsUnknownMechanism"
6925    )]
6926    #[cfg(feature = "aws-lc-rs")]
6927    async fn test_alter_user_scram_credentials_unknown_mechanism() {
6928        let (admin, mut runnable, _time, _nodes) = env();
6929
6930        let user0_name = "user0";
6931        let user0_mechanism = PublicScramMechanism::Unknown;
6932        let user1_name = "user1";
6933        let user1_mechanism = PublicScramMechanism::Unknown;
6934        let user2_name = "user2";
6935        let user2_mechanism = PublicScramMechanism::ScramSha256;
6936
6937        let mut result2 = WireAlterResult::new();
6938        result2.set_user(user2_name.to_string());
6939        let mut response_data = AlterUserScramCredentialsResponseData::new();
6940        response_data.set_results(vec![result2]);
6941        runnable
6942            .client_mut()
6943            .prepare_response(ConcreteResponse::AlterUserScramCredentials(
6944                AlterUserScramCredentialsResponse::new(response_data, 0),
6945            ));
6946
6947        let alterations: Vec<UserScramCredentialAlteration> = vec![
6948            UserScramCredentialDeletion::new(user0_name, user0_mechanism).into(),
6949            UserScramCredentialUpsertion::with_str(
6950                user1_name,
6951                ScramCredentialInfo::new(user1_mechanism, 8192),
6952                "password",
6953            )
6954            .into(),
6955            UserScramCredentialUpsertion::with_str(
6956                user2_name,
6957                ScramCredentialInfo::new(user2_mechanism, 4096),
6958                "password",
6959            )
6960            .into(),
6961        ];
6962        let result =
6963            admin.alter_user_scram_credentials_with_options(&alterations, AlterUserScramCredentialsOptions::new());
6964        pump(&mut runnable, 5).await;
6965
6966        let result_data = result.values();
6967        assert_eq!(result_data.len(), 3);
6968        // user0 and user1 have an unknown mechanism -> complete exceptionally.
6969        for user in [user0_name, user1_name] {
6970            assert!(result_data.contains_key(user));
6971            assert!(
6972                result_data[user].get().await.is_err(),
6973                "expected request for user {user} to complete with an error"
6974            );
6975        }
6976        assert!(result_data.contains_key(user2_name));
6977        result_data[user2_name].get().await.unwrap();
6978
6979        assert!(
6980            result.all().get().await.is_err(),
6981            "expected all() to fail since at least one user failed"
6982        );
6983    }
6984
6985    /// Java records an empty upsertion password against **that user only** —
6986    /// `userIllegalAlterationExceptions.put(user, new UnacceptableCredentialException(passwordMustNotBeEmptyMsg))`
6987    /// (`KafkaAdminClient#alterUserScramCredentials`) — and still builds and
6988    /// sends every other user's alteration. No Java test covers that branch,
6989    /// but the C and Python bindings depend on it: their marshaling layer
6990    /// deliberately passes an empty password through rather than failing the
6991    /// whole call.
6992    #[cfg(feature = "aws-lc-rs")]
6993    #[tokio::test]
6994    async fn test_alter_user_scram_credentials_empty_password_fails_only_that_user() {
6995        let (admin, mut runnable, _time, _nodes) = env();
6996
6997        let mut result1 = WireAlterResult::new();
6998        result1.set_user("user1".to_string()).set_error_code(Errors::None.code());
6999        let mut response_data = AlterUserScramCredentialsResponseData::new();
7000        response_data.set_results(vec![result1]);
7001        runnable
7002            .client_mut()
7003            .prepare_response(ConcreteResponse::AlterUserScramCredentials(
7004                AlterUserScramCredentialsResponse::new(response_data, 0),
7005            ));
7006
7007        let alterations: Vec<UserScramCredentialAlteration> = vec![
7008            UserScramCredentialUpsertion::with_bytes(
7009                "user0",
7010                ScramCredentialInfo::new(PublicScramMechanism::ScramSha256, 4096),
7011                Vec::new(),
7012            )
7013            .into(),
7014            UserScramCredentialUpsertion::with_str(
7015                "user1",
7016                ScramCredentialInfo::new(PublicScramMechanism::ScramSha512, 8192),
7017                "password",
7018            )
7019            .into(),
7020        ];
7021        let result =
7022            admin.alter_user_scram_credentials_with_options(&alterations, AlterUserScramCredentialsOptions::new());
7023        pump(&mut runnable, 5).await;
7024
7025        let result_data = result.values();
7026        assert_eq!(result_data.len(), 2);
7027        let err = result_data["user0"].get().await.unwrap_err();
7028        assert_eq!(err.message(), "Password must not be empty");
7029        // user1's alteration was still built and sent, and succeeded.
7030        result_data["user1"].get().await.unwrap();
7031    }
7032
7033    /// Without the `aws-lc-rs` feature there is no PBKDF2 to salt a password
7034    /// with: an upsertion fails its user's future with an explicit error,
7035    /// while a deletion, which needs no salting, is still sent.
7036    #[cfg(not(feature = "aws-lc-rs"))]
7037    #[tokio::test]
7038    async fn test_alter_user_scram_credentials_upsertion_needs_aws_lc_rs() {
7039        let (admin, mut runnable, _time, _nodes) = env();
7040
7041        let mut result0 = WireAlterResult::new();
7042        result0.set_user("user0".to_string()).set_error_code(Errors::None.code());
7043        let mut response_data = AlterUserScramCredentialsResponseData::new();
7044        response_data.set_results(vec![result0]);
7045        runnable
7046            .client_mut()
7047            .prepare_response(ConcreteResponse::AlterUserScramCredentials(
7048                AlterUserScramCredentialsResponse::new(response_data, 0),
7049            ));
7050
7051        let alterations: Vec<UserScramCredentialAlteration> = vec![
7052            UserScramCredentialDeletion::new("user0", PublicScramMechanism::ScramSha256).into(),
7053            UserScramCredentialUpsertion::with_str(
7054                "user1",
7055                ScramCredentialInfo::new(PublicScramMechanism::ScramSha512, 8192),
7056                "password",
7057            )
7058            .into(),
7059        ];
7060        let result =
7061            admin.alter_user_scram_credentials_with_options(&alterations, AlterUserScramCredentialsOptions::new());
7062        pump(&mut runnable, 5).await;
7063
7064        let result_data = result.values();
7065        assert_eq!(result_data.len(), 2);
7066        let err = result_data["user1"].get().await.unwrap_err();
7067        assert!(err.is_local_unsupported_operation_error(), "{err:?}");
7068        assert_eq!(
7069            err.message(),
7070            "SCRAM credential upsertion is not available: the client was built without the `aws-lc-rs` feature"
7071        );
7072        result_data["user0"].get().await.unwrap();
7073    }
7074
7075    /// Translated from `KafkaAdminClientTest.testAlterUserScramCredentials`.
7076    ///
7077    /// The Java test has no `throws` and runs real PBKDF2 synchronously; the
7078    /// Rust equivalent exercises the same crypto path (each upsertion computes a
7079    /// salted password via `ScramFormatter::hi`).
7080    #[cfg(feature = "aws-lc-rs")]
7081    #[tokio::test]
7082    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testAlterUserScramCredentials")]
7083    async fn test_alter_user_scram_credentials() {
7084        let (admin, mut runnable, _time, _nodes) = env();
7085
7086        let user0_name = "user0";
7087        let user0_mechanism0 = PublicScramMechanism::ScramSha256;
7088        let user0_mechanism1 = PublicScramMechanism::ScramSha512;
7089        let user1_name = "user1";
7090        let user1_mechanism0 = PublicScramMechanism::ScramSha256;
7091        let user2_name = "user2";
7092        let user2_mechanism0 = PublicScramMechanism::ScramSha512;
7093
7094        let mut response_data = AlterUserScramCredentialsResponseData::new();
7095        response_data.set_results(
7096            [user0_name, user1_name, user2_name]
7097                .into_iter()
7098                .map(|u| {
7099                    let mut r = WireAlterResult::new();
7100                    r.set_user(u.to_string()).set_error_code(Errors::None.code());
7101                    r
7102                })
7103                .collect(),
7104        );
7105        runnable
7106            .client_mut()
7107            .prepare_response(ConcreteResponse::AlterUserScramCredentials(
7108                AlterUserScramCredentialsResponse::new(response_data, 0),
7109            ));
7110
7111        let alterations: Vec<UserScramCredentialAlteration> = vec![
7112            UserScramCredentialDeletion::new(user0_name, user0_mechanism0).into(),
7113            UserScramCredentialUpsertion::with_str(
7114                user0_name,
7115                ScramCredentialInfo::new(user0_mechanism1, 8192),
7116                "password",
7117            )
7118            .into(),
7119            UserScramCredentialUpsertion::with_str(
7120                user1_name,
7121                ScramCredentialInfo::new(user1_mechanism0, 8192),
7122                "password",
7123            )
7124            .into(),
7125            UserScramCredentialDeletion::new(user2_name, user2_mechanism0).into(),
7126        ];
7127        let result =
7128            admin.alter_user_scram_credentials_with_options(&alterations, AlterUserScramCredentialsOptions::new());
7129        pump(&mut runnable, 5).await;
7130
7131        let result_data = result.values();
7132        assert_eq!(result_data.len(), 3);
7133        for user in [user0_name, user1_name, user2_name] {
7134            assert!(result_data.contains_key(user));
7135            result_data[user].get().await.unwrap();
7136        }
7137    }
7138
7139    // --- createTopics --------------------------------------------------------
7140
7141    #[tokio::test]
7142    async fn test_create_topics_success() {
7143        let (admin, mut runnable, _time, _nodes) = env();
7144        let result = admin.create_topics_with_options(
7145            &[NewTopic::with_num_partitions_replication_factor(
7146                "myTopic",
7147                Some(1),
7148                Some(1),
7149            )],
7150            CreateTopicsOptions::new(),
7151        );
7152        runnable
7153            .client_mut()
7154            .prepare_response(create_response(vec![create_result("myTopic", Errors::None, None)]));
7155        pump(&mut runnable, 5).await;
7156        result.all().get().await.unwrap();
7157        assert_eq!(result.num_partitions("myTopic").get().await.unwrap(), 1);
7158        assert_eq!(result.topic_id("myTopic").get().await.unwrap(), Uuid::new(0, 7));
7159    }
7160
7161    /// Translated from `KafkaAdminClientTest#testUnreachableBootstrapServer`.
7162    #[tokio::test]
7163    async fn test_unreachable_bootstrap_server() {
7164        verify_unreachable_bootstrap_server(crate::MetadataRecoveryStrategy::Rebootstrap).await;
7165    }
7166
7167    /// Translated from
7168    /// `KafkaAdminClientTest#testUnreachableBootstrapServerNoRebootstrap`.
7169    #[tokio::test]
7170    async fn test_unreachable_bootstrap_server_no_rebootstrap() {
7171        verify_unreachable_bootstrap_server(crate::MetadataRecoveryStrategy::None).await;
7172    }
7173
7174    /// Java `KafkaAdminClientTest#verifyUnreachableBootstrapServer`.
7175    ///
7176    /// Java runs it over `Time.SYSTEM`, where the 200 ms of unreachability pass
7177    /// in real time while `future.get()` waits; here the runnable is driven by
7178    /// hand over a `MockTime` advanced 50 ms per iteration, so the same 200 ms
7179    /// pass between iterations. The client config is Java's
7180    /// `AdminClientUnitTestEnv.clientConfigs(METADATA_RECOVERY_STRATEGY_CONFIG, name)`.
7181    async fn verify_unreachable_bootstrap_server(metadata_recovery_strategy: crate::MetadataRecoveryStrategy) {
7182        use crate::{CommonClientConfigs, MetadataRecoveryStrategy};
7183        // This tests the scenario in which the bootstrap server is unreachable for a short while,
7184        // which prevents AdminClient from being able to send the initial metadata request
7185
7186        let address = "127.0.0.1:8121".parse().expect("a socket address");
7187        let cluster = Cluster::bootstrap(&[("localhost".to_string(), address)]);
7188        let bootstrap_node = cluster.nodes()[0].clone();
7189        let time = mock_time(1000);
7190        let client = MockClient::with_static_nodes(cluster.nodes().to_vec(), Arc::clone(&time) as Arc<dyn Time>);
7191        let props = HashMap::from([
7192            (
7193                AdminClientConfig::BOOTSTRAP_SERVERS_CONFIG.to_string(),
7194                "localhost:8121".to_string(),
7195            ),
7196            (AdminClientConfig::REQUEST_TIMEOUT_MS_CONFIG.to_string(), "1000".to_string()),
7197            (
7198                CommonClientConfigs::METADATA_RECOVERY_STRATEGY_CONFIG.to_string(),
7199                metadata_recovery_strategy.name().to_string(),
7200            ),
7201        ]);
7202        let config = AdminClientConfig::new(&props).unwrap();
7203        let (admin, mut runnable) =
7204            KafkaAdminClient::create_for_test(client, cluster, &config, Arc::clone(&time) as Arc<dyn Time>);
7205        // `unreachableNodes.forEach(mockClient::setUnreachable)` in `AdminClientUnitTestEnv`.
7206        runnable.client_mut().set_unreachable(&bootstrap_node, 200);
7207
7208        let (_discovered_cluster, discovered_nodes) = mock_cluster(3, 0);
7209        // Bind responses to specific destinations so MockClient delivery does not depend on
7210        // the iteration order of AdminClient's callsToSend map (which is keyed by Node).
7211        let is_metadata = || -> crate::RequestMatcher {
7212            Box::new(|body: &AbstractRequest| matches!(body, AbstractRequest::Metadata(_)))
7213        };
7214        let discovered_metadata = || {
7215            ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
7216                &discovered_nodes,
7217                Some("mock-cluster"),
7218                1,
7219                Vec::new(),
7220            ))
7221        };
7222        runnable
7223            .client_mut()
7224            .prepare_response_from_matcher(is_metadata(), discovered_metadata(), &bootstrap_node);
7225        if metadata_recovery_strategy == MetadataRecoveryStrategy::Rebootstrap {
7226            runnable
7227                .client_mut()
7228                .prepare_response_from_matcher(is_metadata(), discovered_metadata(), &bootstrap_node);
7229        }
7230        runnable.client_mut().prepare_response_from_matcher(
7231            Box::new(|body: &AbstractRequest| matches!(body, AbstractRequest::CreateTopics(_))),
7232            create_response(vec![create_result("myTopic", Errors::None, None)]),
7233            &discovered_nodes[1],
7234        );
7235
7236        let future = admin
7237            .create_topics_with_options(
7238                &[NewTopic::with_replicas_assignments(
7239                    "myTopic",
7240                    std::collections::BTreeMap::from([(0, vec![0, 1, 2])]),
7241                )],
7242                CreateTopicsOptions::new().set_timeout_ms(Some(10000)),
7243            )
7244            .all();
7245
7246        // `future.get()`: drive the runnable until the future completes, well
7247        // within the request's 10 s timeout.
7248        for _ in 0..200 {
7249            if future.is_done() {
7250                break;
7251            }
7252            runnable.run_once().await;
7253            time.sleep(50);
7254        }
7255        assert!(future.is_done(), "createTopics did not complete");
7256        future.get().await.expect("createTopics succeeds");
7257    }
7258
7259    /// Steps the runnable until `future` completes and returns its error, failing
7260    /// with `api` if it does not complete or succeeds.
7261    async fn await_failure<T: Send + 'static>(
7262        runnable: &mut AdminClientRunnable<MockClient>,
7263        future: KafkaFuture<T>,
7264        api: &str,
7265    ) -> Error {
7266        pump_until(runnable, 40, |_| future.is_done()).await;
7267        assert!(future.is_done(), "{api}: the future did not complete");
7268        match future.get().await {
7269            Ok(_) => panic!("{api}: expected an authentication error, but the call succeeded"),
7270            Err(error) => error,
7271        }
7272    }
7273
7274    /// Asserts `error` is the error `MockClient.authenticationFailed` records,
7275    /// `Errors.SASL_AUTHENTICATION_FAILED.exception()` — a
7276    /// `SaslAuthenticationException`, and so an `AuthenticationException`.
7277    fn assert_sasl_authentication_error(error: &Error, api: &str) {
7278        assert!(
7279            error.is_authentication_error(),
7280            "{api}: Expected an authentication error, but got {error:?}"
7281        );
7282        assert!(
7283            matches!(error, Error::SaslAuthentication(_)),
7284            "{api}: expected a SaslAuthenticationException, but got {error:?}"
7285        );
7286        assert_eq!(error.message(), "SASL Authentication failed.", "{api}");
7287    }
7288
7289    /// Translated from `KafkaAdminClientTest.testPropagatedMetadataFetchException`:
7290    /// a pending authentication error on the controller fails `createTopics` with
7291    /// the `SaslAuthenticationException` the client reports for that node, rather
7292    /// than the call timing out.
7293    ///
7294    /// The request to node 0 is answered as disconnected, and the admin loop
7295    /// fails the call with `client.authenticationException(node)`
7296    /// (`KafkaAdminClient.AdminClientRunnable#handleResponses`), which is not
7297    /// retriable.
7298    ///
7299    /// Java runs on `Time.SYSTEM`; here the mock clock stays still, so neither
7300    /// `request.timeout.ms=10` nor the 1 s call timeout can expire, and the call
7301    /// can only fail through the authentication error.
7302    #[tokio::test]
7303    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testPropagatedMetadataFetchException")]
7304    async fn test_propagated_metadata_fetch_error() {
7305        let time = mock_time(1000);
7306        let (cluster, nodes) = mock_cluster(3, 0);
7307        let mut client = MockClient::with_static_nodes(nodes.clone(), Arc::clone(&time) as Arc<dyn Time>);
7308        client.create_pending_authentication_error(&nodes[0], Duration::from_secs(24 * 60 * 60).as_millis() as i64);
7309        let mut props = HashMap::new();
7310        props.insert("bootstrap.servers".to_string(), "localhost:8121".to_string());
7311        props.insert("request.timeout.ms".to_string(), "10".to_string());
7312        let config = AdminClientConfig::new(&props).unwrap();
7313        let (admin, mut runnable) =
7314            KafkaAdminClient::create_for_test(client, cluster, &config, Arc::clone(&time) as Arc<dyn Time>);
7315        runnable
7316            .client_mut()
7317            .prepare_response(create_response(vec![create_result("myTopic", Errors::None, None)]));
7318
7319        let result = admin.create_topics_with_options(
7320            &[NewTopic::with_replicas_assignments(
7321                "myTopic",
7322                std::collections::BTreeMap::from([(0, vec![0, 1, 2])]),
7323            )],
7324            CreateTopicsOptions::new().set_timeout_ms(Some(1000)),
7325        );
7326        let error = await_failure(&mut runnable, result.all(), "createTopics").await;
7327        assert_sasl_authentication_error(&error, "createTopics");
7328    }
7329
7330    /// Translated from `KafkaAdminClientTest.testAdminClientApisAuthenticationFailure`,
7331    /// with its helpers `callAdminClientApisAndExpectAnAuthenticationError` and
7332    /// `callClientQuotasApisAndExpectAnAuthenticationError`: once the bootstrap
7333    /// metadata call fails authentication, every API fails with that
7334    /// authentication error.
7335    ///
7336    /// The metadata call's failure reaches `AdminMetadataManager.updateFailed`,
7337    /// which keeps a fatal exception (`RequestUtils.isFatalException`) that
7338    /// `isReady()` rethrows to every call choosing a node from then on. As in
7339    /// Java, `metadata.recovery.strategy` is `none`: a rebootstrap updates the
7340    /// manager with the bootstrap cluster, which clears that exception
7341    /// (`AdminMetadataManager.update`).
7342    ///
7343    /// Java runs on `Time.SYSTEM` and blocks on each future. Here the mock clock
7344    /// starts at a wall-clock-sized value, so that, as under `Time.SYSTEM`, the
7345    /// metadata seeded from the bootstrap cluster (which leaves
7346    /// `lastMetadataUpdateMs` at 0) counts as expired; and it advances by
7347    /// `retry.backoff.ms` after each API, the case Java's comment below guards
7348    /// against: the backoff has passed, so the admin loop makes a new metadata
7349    /// call, whose `MetadataUpdateNodeIdProvider` finds the bootstrap node backing
7350    /// off and, under `rebootstrap`, would rebootstrap and clear the error. Each
7351    /// future is awaited after stepping the loop until it completes. The calls and
7352    /// their order are Java's: createTopics, createPartitions, createAcls,
7353    /// describeAcls, deleteAcls, describeConfigs, describeClientQuotas,
7354    /// alterClientQuotas.
7355    #[tokio::test]
7356    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testAdminClientApisAuthenticationFailure")]
7357    async fn test_admin_client_apis_authentication_failure() {
7358        const RETRY_BACKOFF_MS: i64 = 100;
7359        let time = mock_time(1_700_000_000_000);
7360        // Java's `mockBootstrapCluster()`.
7361        let cluster = Cluster::bootstrap(&[("localhost".to_string(), "127.0.0.1:8121".parse().unwrap())]);
7362        let bootstrap_node = cluster.nodes()[0].clone();
7363        let mut client =
7364            MockClient::with_static_nodes(vec![bootstrap_node.clone()], Arc::clone(&time) as Arc<dyn Time>);
7365        client
7366            .create_pending_authentication_error(&bootstrap_node, Duration::from_secs(24 * 60 * 60).as_millis() as i64);
7367        let mut props = HashMap::new();
7368        props.insert("bootstrap.servers".to_string(), "localhost:8121".to_string());
7369        props.insert("request.timeout.ms".to_string(), "1000".to_string());
7370        // Default "metadata.recovery.strategy" is rebootstrap. If it meets "retry.backoff.ms" (default is 100L),
7371        // following assertion will fail. Set it to none to avoid authentication error cleanup.
7372        props.insert("metadata.recovery.strategy".to_string(), "none".to_string());
7373        let config = AdminClientConfig::new(&props).unwrap();
7374        let (admin, mut runnable) =
7375            KafkaAdminClient::create_for_test(client, cluster, &config, Arc::clone(&time) as Arc<dyn Time>);
7376
7377        // callAdminClientApisAndExpectAnAuthenticationError
7378        let result = admin.create_topics_with_options(
7379            &[NewTopic::with_replicas_assignments(
7380                "myTopic",
7381                std::collections::BTreeMap::from([(0, vec![0, 1, 2])]),
7382            )],
7383            CreateTopicsOptions::new().set_timeout_ms(Some(10_000)),
7384        );
7385        let error = await_failure(&mut runnable, result.all(), "createTopics").await;
7386        assert_sasl_authentication_error(&error, "createTopics");
7387        time.sleep(RETRY_BACKOFF_MS);
7388
7389        let result = admin.create_partitions(&new_partitions_counts());
7390        let error = await_failure(&mut runnable, result.all(), "createPartitions").await;
7391        assert_sasl_authentication_error(&error, "createPartitions");
7392        time.sleep(RETRY_BACKOFF_MS);
7393
7394        let result = admin.create_acls(&[acl1(), acl2()]);
7395        let error = await_failure(&mut runnable, result.all(), "createAcls").await;
7396        assert_sasl_authentication_error(&error, "createAcls");
7397        time.sleep(RETRY_BACKOFF_MS);
7398
7399        let result = admin.describe_acls(&filter1());
7400        let error = await_failure(&mut runnable, result.values().clone(), "describeAcls").await;
7401        assert_sasl_authentication_error(&error, "describeAcls");
7402        time.sleep(RETRY_BACKOFF_MS);
7403
7404        let result = admin.delete_acls(&[filter1(), filter2()]);
7405        let error = await_failure(&mut runnable, result.all(), "deleteAcls").await;
7406        assert_sasl_authentication_error(&error, "deleteAcls");
7407        time.sleep(RETRY_BACKOFF_MS);
7408
7409        let result = admin.describe_configs(&[ConfigResource::new(config_resource::Type::Broker, "0".to_string())]);
7410        let error = await_failure(&mut runnable, result.all(), "describeConfigs").await;
7411        assert_sasl_authentication_error(&error, "describeConfigs");
7412        time.sleep(RETRY_BACKOFF_MS);
7413
7414        // callClientQuotasApisAndExpectAnAuthenticationError
7415        let result = admin.describe_client_quotas(&ClientQuotaFilter::all());
7416        let error = await_failure(&mut runnable, result.entities().clone(), "describeClientQuotas").await;
7417        assert_sasl_authentication_error(&error, "describeClientQuotas");
7418        time.sleep(RETRY_BACKOFF_MS);
7419
7420        let entity =
7421            ClientQuotaEntity::new(HashMap::from([(ClientQuotaEntity::USER.to_string(), Some("user".to_string()))]));
7422        let alteration = ClientQuotaAlteration::new(entity, vec![Op::new("consumer_byte_rate", Some(1000.0))]);
7423        let result = admin.alter_client_quotas(&[alteration]);
7424        let error = await_failure(&mut runnable, result.all(), "alterClientQuotas").await;
7425        assert_sasl_authentication_error(&error, "alterClientQuotas");
7426    }
7427
7428    #[tokio::test]
7429    async fn test_create_topics_error_surfaces_message() {
7430        let (admin, mut runnable, _time, _nodes) = env();
7431        let result = admin.create_topics_with_options(
7432            &[NewTopic::with_num_partitions_replication_factor(
7433                "bad",
7434                Some(1),
7435                Some(1),
7436            )],
7437            CreateTopicsOptions::new(),
7438        );
7439        runnable.client_mut().prepare_response(create_response(vec![create_result(
7440            "bad",
7441            Errors::InvalidTopicError,
7442            Some("Topic name is invalid"),
7443        )]));
7444        pump(&mut runnable, 5).await;
7445        let err = result.values()["bad"].get().await.unwrap_err();
7446        assert_eq!(err.error(), Errors::InvalidTopicError);
7447        assert_eq!(err.message(), "Topic name is invalid");
7448    }
7449
7450    #[tokio::test]
7451    async fn test_create_topics_partial_response_completes_unrealized() {
7452        let (admin, mut runnable, _time, _nodes) = env();
7453        let result = admin.create_topics_with_options(
7454            &[
7455                NewTopic::with_num_partitions_replication_factor("present", Some(1), Some(1)),
7456                NewTopic::with_num_partitions_replication_factor("missing", Some(1), Some(1)),
7457            ],
7458            CreateTopicsOptions::new(),
7459        );
7460        // Response omits "missing".
7461        runnable
7462            .client_mut()
7463            .prepare_response(create_response(vec![create_result("present", Errors::None, None)]));
7464        pump(&mut runnable, 5).await;
7465        result.values()["present"].get().await.unwrap();
7466        let err = result.values()["missing"].get().await.unwrap_err();
7467        assert_eq!(
7468            err.message(),
7469            "The controller response did not contain a result for topic missing"
7470        );
7471    }
7472
7473    #[tokio::test]
7474    async fn test_create_topics_retries_on_disconnect() {
7475        let (admin, mut runnable, time, _nodes) = env();
7476        let result = admin.create_topics_with_options(
7477            &[NewTopic::with_num_partitions_replication_factor(
7478                "myTopic",
7479                Some(1),
7480                Some(1),
7481            )],
7482            CreateTopicsOptions::new(),
7483        );
7484        // First a disconnect, then a success.
7485        runnable
7486            .client_mut()
7487            .prepare_response_disconnected(create_response(vec![]), true);
7488        runnable
7489            .client_mut()
7490            .prepare_response(create_response(vec![create_result("myTopic", Errors::None, None)]));
7491        for _ in 0..20 {
7492            if result.values()["myTopic"].is_done() {
7493                break;
7494            }
7495            runnable.run_once().await;
7496            time.sleep(500);
7497        }
7498        result.all().get().await.unwrap();
7499    }
7500
7501    /// Mirrors `KafkaAdminClientTest.testCreateTopicsRetryBackoff`: a retry must
7502    /// wait for the backoff to elapse before the next attempt is issued. The
7503    /// driven-runnable harness has no wall clock, so we assert the retry is
7504    /// gated by `next_allowed_try_ms` — it does not fire until the mock time
7505    /// advances past the backoff.
7506    #[tokio::test]
7507    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testCreateTopicsRetryBackoff")]
7508    async fn test_create_topics_retry_backoff() {
7509        let retry_backoff = 5000;
7510        let (admin, mut runnable, time, _nodes) = env_with_props(&[("retry.backoff.ms", &retry_backoff.to_string())]);
7511        let result = admin.create_topics_with_options(
7512            &[NewTopic::with_num_partitions_replication_factor(
7513                "myTopic",
7514                Some(1),
7515                Some(1),
7516            )],
7517            CreateTopicsOptions::new(),
7518        );
7519        // First attempt disconnects, second succeeds.
7520        runnable
7521            .client_mut()
7522            .prepare_response_disconnected(create_response(vec![]), true);
7523        runnable
7524            .client_mut()
7525            .prepare_response(create_response(vec![create_result("myTopic", Errors::None, None)]));
7526
7527        // Drive until the first (disconnected) attempt has failed and the retry
7528        // is scheduled. The success response must remain unconsumed while the
7529        // backoff has not yet elapsed.
7530        pump_until(&mut runnable, 20, |r| r.client_mut().num_awaiting_responses() == 1).await;
7531        assert!(!result.values()["myTopic"].is_done());
7532
7533        // Pump repeatedly without advancing time: the backoff gate holds and the
7534        // retry is not sent, so the success response stays queued.
7535        pump(&mut runnable, 5).await;
7536        assert_eq!(runnable.client_mut().num_awaiting_responses(), 1);
7537        assert!(!result.values()["myTopic"].is_done());
7538
7539        // Advance past the (jittered) upper-bound backoff; the retry now fires.
7540        let upper_bound = (retry_backoff as f64 * RETRY_BACKOFF_EXP_BASE as f64 * (1.0 + RETRY_BACKOFF_JITTER)) as i64;
7541        time.sleep(upper_bound);
7542        pump_until(&mut runnable, 20, |r| r.client_mut().num_awaiting_responses() == 0).await;
7543        result.all().get().await.unwrap();
7544    }
7545
7546    #[tokio::test]
7547    #[doc(
7548        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testCreateTopicsHandleNotControllerException"
7549    )]
7550    async fn test_create_topics_handle_not_controller_error() {
7551        let (admin, mut runnable, time, nodes) = env();
7552        // First attempt hits the wrong controller; then a metadata refresh
7553        // updates the controller; then the retry succeeds.
7554        runnable.client_mut().prepare_response(create_response(vec![create_result(
7555            "myTopic",
7556            Errors::NotController,
7557            None,
7558        )]));
7559        runnable
7560            .client_mut()
7561            .prepare_response(ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
7562                &nodes,
7563                Some("mock-cluster"),
7564                1,
7565                Vec::new(),
7566            )));
7567        runnable
7568            .client_mut()
7569            .prepare_response(create_response(vec![create_result("myTopic", Errors::None, None)]));
7570        let result = admin.create_topics_with_options(
7571            &[NewTopic::with_num_partitions_replication_factor(
7572                "myTopic",
7573                Some(1),
7574                Some(1),
7575            )],
7576            CreateTopicsOptions::new(),
7577        );
7578        // The NOT_CONTROLLER retry is routed through the retry-backoff gate, so
7579        // the mock clock must advance for the retry to become eligible.
7580        for _ in 0..30 {
7581            if result.values()["myTopic"].is_done() {
7582                break;
7583            }
7584            runnable.run_once().await;
7585            time.sleep(200);
7586        }
7587        result.all().get().await.unwrap();
7588    }
7589
7590    #[tokio::test]
7591    #[doc(
7592        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testCreateTopicsRetryThrottlingExceptionWhenEnabled"
7593    )]
7594    async fn test_create_topics_retry_throttling_error_when_enabled() {
7595        let (admin, mut runnable, _time, _nodes) = env();
7596        // topic1 succeeds, topic2 is throttled (retried until success), topic3 already exists.
7597        runnable.client_mut().prepare_response(create_response_throttled(
7598            1000,
7599            vec![
7600                create_result("topic1", Errors::None, None),
7601                create_result("topic2", Errors::ThrottlingQuotaExceeded, None),
7602                create_result("topic3", Errors::TopicAlreadyExists, None),
7603            ],
7604        ));
7605        runnable.client_mut().prepare_response(create_response_throttled(
7606            1000,
7607            vec![create_result("topic2", Errors::ThrottlingQuotaExceeded, None)],
7608        ));
7609        runnable
7610            .client_mut()
7611            .prepare_response(create_response_throttled(0, vec![create_result("topic2", Errors::None, None)]));
7612
7613        let result = admin.create_topics_with_options(
7614            &[
7615                NewTopic::with_num_partitions_replication_factor("topic1", Some(1), Some(1)),
7616                NewTopic::with_num_partitions_replication_factor("topic2", Some(1), Some(1)),
7617                NewTopic::with_num_partitions_replication_factor("topic3", Some(1), Some(1)),
7618            ],
7619            CreateTopicsOptions::new().set_retry_on_quota_violation(true),
7620        );
7621        pump_until(&mut runnable, 30, |r| r.client_mut().num_awaiting_responses() == 0).await;
7622        result.values()["topic1"].get().await.unwrap();
7623        result.values()["topic2"].get().await.unwrap();
7624        let err = result.values()["topic3"].get().await.unwrap_err();
7625        assert_eq!(err.error(), Errors::TopicAlreadyExists);
7626    }
7627
7628    #[tokio::test]
7629    #[doc(
7630        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testCreateTopicsDontRetryThrottlingExceptionWhenDisabled"
7631    )]
7632    async fn test_create_topics_dont_retry_throttling_error_when_disabled() {
7633        let (admin, mut runnable, _time, _nodes) = env();
7634        runnable.client_mut().prepare_response(create_response_throttled(
7635            1000,
7636            vec![
7637                create_result("topic1", Errors::None, None),
7638                create_result("topic2", Errors::ThrottlingQuotaExceeded, None),
7639                create_result("topic3", Errors::TopicAlreadyExists, None),
7640            ],
7641        ));
7642        let result = admin.create_topics_with_options(
7643            &[
7644                NewTopic::with_num_partitions_replication_factor("topic1", Some(1), Some(1)),
7645                NewTopic::with_num_partitions_replication_factor("topic2", Some(1), Some(1)),
7646                NewTopic::with_num_partitions_replication_factor("topic3", Some(1), Some(1)),
7647            ],
7648            CreateTopicsOptions::new().set_retry_on_quota_violation(false),
7649        );
7650        pump(&mut runnable, 5).await;
7651        result.values()["topic1"].get().await.unwrap();
7652        let err = result.values()["topic2"].get().await.unwrap_err();
7653        assert_eq!(err.error(), Errors::ThrottlingQuotaExceeded);
7654        assert_eq!(err.throttle_time_ms(), Some(1000));
7655        let err3 = result.values()["topic3"].get().await.unwrap_err();
7656        assert_eq!(err3.error(), Errors::TopicAlreadyExists);
7657    }
7658
7659    #[tokio::test]
7660    async fn test_create_topics_retry_throttling_error_when_enabled_until_request_timeout() {
7661        let default_api_timeout: i64 = 60000;
7662        let (admin, mut runnable, time, _nodes) =
7663            env_with_props(&[("default.api.timeout.ms", &default_api_timeout.to_string())]);
7664        runnable.client_mut().prepare_response(create_response_throttled(
7665            1000,
7666            vec![
7667                create_result("topic1", Errors::None, None),
7668                create_result("topic2", Errors::ThrottlingQuotaExceeded, None),
7669                create_result("topic3", Errors::TopicAlreadyExists, None),
7670            ],
7671        ));
7672        runnable.client_mut().prepare_response(create_response_throttled(
7673            1000,
7674            vec![create_result("topic2", Errors::ThrottlingQuotaExceeded, None)],
7675        ));
7676        let result = admin.create_topics_with_options(
7677            &[
7678                NewTopic::with_num_partitions_replication_factor("topic1", Some(1), Some(1)),
7679                NewTopic::with_num_partitions_replication_factor("topic2", Some(1), Some(1)),
7680                NewTopic::with_num_partitions_replication_factor("topic3", Some(1), Some(1)),
7681            ],
7682            CreateTopicsOptions::new().set_retry_on_quota_violation(true),
7683        );
7684        // Consume both prepared responses; the third (retry) request stays in flight.
7685        pump_until(&mut runnable, 30, |r| {
7686            !r.client_mut().has_pending_responses() && r.client_mut().request_count() >= 1
7687        })
7688        .await;
7689        // Advance past the default api timeout to time out the in-flight request.
7690        time.sleep(default_api_timeout + 1);
7691        pump_until(&mut runnable, 30, |r| {
7692            let _ = r;
7693            result.values()["topic2"].is_done()
7694        })
7695        .await;
7696        result.values()["topic1"].get().await.unwrap();
7697        let err = result.values()["topic2"].get().await.unwrap_err();
7698        assert_eq!(err.error(), Errors::ThrottlingQuotaExceeded);
7699        assert_eq!(err.throttle_time_ms(), Some(0));
7700        let err3 = result.values()["topic3"].get().await.unwrap_err();
7701        assert_eq!(err3.error(), Errors::TopicAlreadyExists);
7702    }
7703
7704    // --- deleteTopics --------------------------------------------------------
7705
7706    #[tokio::test]
7707    async fn test_delete_topics_by_name_success() {
7708        let (admin, mut runnable, _time, _nodes) = env();
7709        let result = admin.delete_topics_with_topic_collection_options(
7710            TopicCollection::of_topic_names(vec!["myTopic".to_string()]),
7711            DeleteTopicsOptions::new(),
7712        );
7713        runnable
7714            .client_mut()
7715            .prepare_response(delete_response(vec![delete_result_named("myTopic", Errors::None)]));
7716        pump(&mut runnable, 5).await;
7717        result.all().get().await.unwrap();
7718    }
7719
7720    #[tokio::test]
7721    async fn test_delete_topics_by_name_error() {
7722        let (admin, mut runnable, _time, _nodes) = env();
7723        let result = admin.delete_topics_with_topic_collection_options(
7724            TopicCollection::of_topic_names(vec!["ghost".to_string()]),
7725            DeleteTopicsOptions::new(),
7726        );
7727        runnable.client_mut().prepare_response(delete_response(vec![delete_result_named(
7728            "ghost",
7729            Errors::UnknownTopicOrPartition,
7730        )]));
7731        pump(&mut runnable, 5).await;
7732        let err = result.topic_name_values().unwrap()["ghost"].get().await.unwrap_err();
7733        assert_eq!(err.error(), Errors::UnknownTopicOrPartition);
7734    }
7735
7736    #[tokio::test]
7737    async fn test_delete_topics_by_id_success() {
7738        let (admin, mut runnable, _time, _nodes) = env();
7739        let id = Uuid::new(1, 2);
7740        let result = admin.delete_topics_with_topic_collection_options(
7741            TopicCollection::of_topic_ids(vec![id]),
7742            DeleteTopicsOptions::new(),
7743        );
7744        let mut r = DeletableTopicResult::new();
7745        r.set_topic_id(id);
7746        r.set_error_code(Errors::None.code());
7747        runnable.client_mut().prepare_response(delete_response(vec![r]));
7748        pump(&mut runnable, 5).await;
7749        result.all().get().await.unwrap();
7750    }
7751
7752    #[tokio::test]
7753    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDeleteTopicsPartialResponse")]
7754    async fn test_delete_topics_partial_response() {
7755        // By name: the response omits "myOtherTopic", so its future is
7756        // completed by the unrealized-futures sanity check.
7757        let (admin, mut runnable, _time, _nodes) = env();
7758        let result = admin.delete_topics_with_topic_collection_options(
7759            TopicCollection::of_topic_names(vec!["myTopic".to_string(), "myOtherTopic".to_string()]),
7760            DeleteTopicsOptions::new(),
7761        );
7762        runnable.client_mut().prepare_response(delete_response_throttled(
7763            1000,
7764            vec![delete_result_named("myTopic", Errors::None)],
7765        ));
7766        pump(&mut runnable, 5).await;
7767        result.topic_name_values().unwrap()["myTopic"].get().await.unwrap();
7768        let err = result.topic_name_values().unwrap()["myOtherTopic"].get().await.unwrap_err();
7769        assert_eq!(
7770            err.message(),
7771            "The controller response did not contain a result for topic myOtherTopic"
7772        );
7773
7774        // By id: the response omits topicId2.
7775        let (admin, mut runnable, _time, _nodes) = env();
7776        let id1 = Uuid::new(1, 1);
7777        let id2 = Uuid::new(2, 2);
7778        let result = admin.delete_topics_with_topic_collection_options(
7779            TopicCollection::of_topic_ids(vec![id1, id2]),
7780            DeleteTopicsOptions::new(),
7781        );
7782        runnable
7783            .client_mut()
7784            .prepare_response(delete_response_throttled(1000, vec![delete_result_with_id(id1, Errors::None)]));
7785        pump(&mut runnable, 5).await;
7786        result.topic_id_values().unwrap()[&id1].get().await.unwrap();
7787        let err = result.topic_id_values().unwrap()[&id2].get().await.unwrap_err();
7788        assert_eq!(
7789            err.message(),
7790            format!("The controller response did not contain a result for topic {id2}")
7791        );
7792    }
7793
7794    #[tokio::test]
7795    #[doc(
7796        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDeleteTopicsRetryThrottlingExceptionWhenEnabled"
7797    )]
7798    async fn test_delete_topics_retry_throttling_error_when_enabled() {
7799        // By name.
7800        let (admin, mut runnable, _time, _nodes) = env();
7801        runnable.client_mut().prepare_response(delete_response_throttled(
7802            1000,
7803            vec![
7804                delete_result_named("topic1", Errors::None),
7805                delete_result_named("topic2", Errors::ThrottlingQuotaExceeded),
7806                delete_result_named("topic3", Errors::TopicAlreadyExists),
7807            ],
7808        ));
7809        runnable.client_mut().prepare_response(delete_response_throttled(
7810            1000,
7811            vec![delete_result_named("topic2", Errors::ThrottlingQuotaExceeded)],
7812        ));
7813        runnable
7814            .client_mut()
7815            .prepare_response(delete_response_throttled(0, vec![delete_result_named("topic2", Errors::None)]));
7816        let result = admin.delete_topics_with_topic_collection_options(
7817            TopicCollection::of_topic_names(vec!["topic1".to_string(), "topic2".to_string(), "topic3".to_string()]),
7818            DeleteTopicsOptions::new().set_retry_on_quota_violation(true),
7819        );
7820        pump_until(&mut runnable, 30, |r| r.client_mut().num_awaiting_responses() == 0).await;
7821        result.topic_name_values().unwrap()["topic1"].get().await.unwrap();
7822        result.topic_name_values().unwrap()["topic2"].get().await.unwrap();
7823        let err = result.topic_name_values().unwrap()["topic3"].get().await.unwrap_err();
7824        assert_eq!(err.error(), Errors::TopicAlreadyExists);
7825
7826        // By id.
7827        let (admin, mut runnable, _time, _nodes) = env();
7828        let id1 = Uuid::new(1, 1);
7829        let id2 = Uuid::new(2, 2);
7830        let id3 = Uuid::new(3, 3);
7831        runnable.client_mut().prepare_response(delete_response_throttled(
7832            1000,
7833            vec![
7834                delete_result_with_id(id1, Errors::None),
7835                delete_result_with_id(id2, Errors::ThrottlingQuotaExceeded),
7836                delete_result_with_id(id3, Errors::UnknownTopicId),
7837            ],
7838        ));
7839        runnable.client_mut().prepare_response(delete_response_throttled(
7840            1000,
7841            vec![delete_result_with_id(id2, Errors::ThrottlingQuotaExceeded)],
7842        ));
7843        runnable
7844            .client_mut()
7845            .prepare_response(delete_response_throttled(0, vec![delete_result_with_id(id2, Errors::None)]));
7846        let result = admin.delete_topics_with_topic_collection_options(
7847            TopicCollection::of_topic_ids(vec![id1, id2, id3]),
7848            DeleteTopicsOptions::new().set_retry_on_quota_violation(true),
7849        );
7850        pump_until(&mut runnable, 30, |r| r.client_mut().num_awaiting_responses() == 0).await;
7851        result.topic_id_values().unwrap()[&id1].get().await.unwrap();
7852        result.topic_id_values().unwrap()[&id2].get().await.unwrap();
7853        let err = result.topic_id_values().unwrap()[&id3].get().await.unwrap_err();
7854        assert_eq!(err.error(), Errors::UnknownTopicId);
7855    }
7856
7857    #[tokio::test]
7858    #[doc(
7859        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDeleteTopicsDontRetryThrottlingExceptionWhenDisabled"
7860    )]
7861    async fn test_delete_topics_dont_retry_throttling_error_when_disabled() {
7862        // By name.
7863        let (admin, mut runnable, _time, _nodes) = env();
7864        runnable.client_mut().prepare_response(delete_response_throttled(
7865            1000,
7866            vec![
7867                delete_result_named("topic1", Errors::None),
7868                delete_result_named("topic2", Errors::ThrottlingQuotaExceeded),
7869                delete_result_named("topic3", Errors::TopicAlreadyExists),
7870            ],
7871        ));
7872        let result = admin.delete_topics_with_topic_collection_options(
7873            TopicCollection::of_topic_names(vec!["topic1".to_string(), "topic2".to_string(), "topic3".to_string()]),
7874            DeleteTopicsOptions::new().set_retry_on_quota_violation(false),
7875        );
7876        pump(&mut runnable, 5).await;
7877        result.topic_name_values().unwrap()["topic1"].get().await.unwrap();
7878        let err = result.topic_name_values().unwrap()["topic2"].get().await.unwrap_err();
7879        assert_eq!(err.error(), Errors::ThrottlingQuotaExceeded);
7880        assert_eq!(err.throttle_time_ms(), Some(1000));
7881        let err3 = result.topic_name_values().unwrap()["topic3"].get().await.unwrap_err();
7882        assert_eq!(err3.error(), Errors::TopicAlreadyExists);
7883
7884        // By id.
7885        let (admin, mut runnable, _time, _nodes) = env();
7886        let id1 = Uuid::new(1, 1);
7887        let id2 = Uuid::new(2, 2);
7888        let id3 = Uuid::new(3, 3);
7889        runnable.client_mut().prepare_response(delete_response_throttled(
7890            1000,
7891            vec![
7892                delete_result_with_id(id1, Errors::None),
7893                delete_result_with_id(id2, Errors::ThrottlingQuotaExceeded),
7894                delete_result_with_id(id3, Errors::UnknownTopicId),
7895            ],
7896        ));
7897        let result = admin.delete_topics_with_topic_collection_options(
7898            TopicCollection::of_topic_ids(vec![id1, id2, id3]),
7899            DeleteTopicsOptions::new().set_retry_on_quota_violation(false),
7900        );
7901        pump(&mut runnable, 5).await;
7902        result.topic_id_values().unwrap()[&id1].get().await.unwrap();
7903        let err = result.topic_id_values().unwrap()[&id2].get().await.unwrap_err();
7904        assert_eq!(err.error(), Errors::ThrottlingQuotaExceeded);
7905        assert_eq!(err.throttle_time_ms(), Some(1000));
7906        let err3 = result.topic_id_values().unwrap()[&id3].get().await.unwrap_err();
7907        assert_eq!(err3.error(), Errors::UnknownTopicId);
7908    }
7909
7910    #[tokio::test]
7911    async fn test_delete_topics_retry_throttling_error_when_enabled_until_request_timeout() {
7912        let default_api_timeout: i64 = 60000;
7913        // By name.
7914        let (admin, mut runnable, time, _nodes) =
7915            env_with_props(&[("default.api.timeout.ms", &default_api_timeout.to_string())]);
7916        runnable.client_mut().prepare_response(delete_response_throttled(
7917            1000,
7918            vec![
7919                delete_result_named("topic1", Errors::None),
7920                delete_result_named("topic2", Errors::ThrottlingQuotaExceeded),
7921                delete_result_named("topic3", Errors::TopicAlreadyExists),
7922            ],
7923        ));
7924        runnable.client_mut().prepare_response(delete_response_throttled(
7925            1000,
7926            vec![delete_result_named("topic2", Errors::ThrottlingQuotaExceeded)],
7927        ));
7928        let result = admin.delete_topics_with_topic_collection_options(
7929            TopicCollection::of_topic_names(vec!["topic1".to_string(), "topic2".to_string(), "topic3".to_string()]),
7930            DeleteTopicsOptions::new().set_retry_on_quota_violation(true),
7931        );
7932        pump_until(&mut runnable, 30, |r| {
7933            !r.client_mut().has_pending_responses() && r.client_mut().request_count() >= 1
7934        })
7935        .await;
7936        time.sleep(default_api_timeout + 1);
7937        pump_until(&mut runnable, 30, |_| result.topic_name_values().unwrap()["topic2"].is_done()).await;
7938        result.topic_name_values().unwrap()["topic1"].get().await.unwrap();
7939        let err = result.topic_name_values().unwrap()["topic2"].get().await.unwrap_err();
7940        assert_eq!(err.error(), Errors::ThrottlingQuotaExceeded);
7941        assert_eq!(err.throttle_time_ms(), Some(0));
7942        let err3 = result.topic_name_values().unwrap()["topic3"].get().await.unwrap_err();
7943        assert_eq!(err3.error(), Errors::TopicAlreadyExists);
7944
7945        // By id.
7946        let (admin, mut runnable, time, _nodes) =
7947            env_with_props(&[("default.api.timeout.ms", &default_api_timeout.to_string())]);
7948        let id1 = Uuid::new(1, 1);
7949        let id2 = Uuid::new(2, 2);
7950        let id3 = Uuid::new(3, 3);
7951        runnable.client_mut().prepare_response(delete_response_throttled(
7952            1000,
7953            vec![
7954                delete_result_with_id(id1, Errors::None),
7955                delete_result_with_id(id2, Errors::ThrottlingQuotaExceeded),
7956                delete_result_with_id(id3, Errors::UnknownTopicId),
7957            ],
7958        ));
7959        runnable.client_mut().prepare_response(delete_response_throttled(
7960            1000,
7961            vec![delete_result_with_id(id2, Errors::ThrottlingQuotaExceeded)],
7962        ));
7963        let result = admin.delete_topics_with_topic_collection_options(
7964            TopicCollection::of_topic_ids(vec![id1, id2, id3]),
7965            DeleteTopicsOptions::new().set_retry_on_quota_violation(true),
7966        );
7967        pump_until(&mut runnable, 30, |r| {
7968            !r.client_mut().has_pending_responses() && r.client_mut().request_count() >= 1
7969        })
7970        .await;
7971        time.sleep(default_api_timeout + 1);
7972        pump_until(&mut runnable, 30, |_| result.topic_id_values().unwrap()[&id2].is_done()).await;
7973        result.topic_id_values().unwrap()[&id1].get().await.unwrap();
7974        let err = result.topic_id_values().unwrap()[&id2].get().await.unwrap_err();
7975        assert_eq!(err.error(), Errors::ThrottlingQuotaExceeded);
7976        assert_eq!(err.throttle_time_ms(), Some(0));
7977        let err3 = result.topic_id_values().unwrap()[&id3].get().await.unwrap_err();
7978        assert_eq!(err3.error(), Errors::UnknownTopicId);
7979    }
7980
7981    /// `KafkaAdminClient.AdminClientRunnable#enqueue` fails a call submitted after
7982    /// the I/O thread is gone with
7983    /// `new TimeoutException("The AdminClient thread has exited.")`, and
7984    /// `KafkaAdminClient.Call#handleTimeoutFailure` short-circuits on
7985    /// `cause instanceof TimeoutException` so the user sees exactly a
7986    /// `TimeoutException` — i.e. a `RetriableException`.
7987    ///
7988    /// This used to be `Error::local_illegal_state`, whose `ErrorHierarchy` is empty, so
7989    /// **both** `is_retriable_error()` and `is_kafka_error()` answered `false`: a
7990    /// caller writing `if err.is_retriable_error() { retry }` behaved differently
7991    /// against the two clients for the identical condition.
7992    #[tokio::test]
7993    async fn a_call_submitted_after_the_io_task_exits_fails_with_a_timeout() {
7994        let (admin, runnable, _time, _nodes) = env();
7995        // Dropping the runnable drops the receiving end of the call channel, which
7996        // is what `CallSender::call`'s `SendError` arm observes.
7997        drop(runnable);
7998
7999        let result = admin.list_topics_with_options(ListTopicsOptions::new());
8000        let error = result.names().get().await.expect_err("the call cannot be delivered");
8001
8002        assert_eq!(error.message(), "The AdminClient thread has exited.");
8003        assert!(error.is_timeout_error(), "got {error:?}");
8004        assert!(error.is_retriable_error(), "a timeout error is retriable: {error:?}");
8005        assert!(
8006            error.is_kafka_error(),
8007            "... which is an API error, which is a Kafka error: {error:?}"
8008        );
8009    }
8010
8011    /// `KafkaAdminClient.AdminClientRunnable#handleResponses` cancels a call whose
8012    /// node disconnected with `new DisconnectException(...)`. It used to be built as
8013    /// `Errors::NetworkError`, so the user got protocol code 13 for a purely
8014    /// client-side event and a caller matching `Error::Disconnect(_)` never fired.
8015    ///
8016    /// The driver's `t instanceof DisconnectException` retry-lookup branch
8017    /// (`AdminApiDriver#onFailure`) keys off the same class, so the wrong class
8018    /// was load-bearing — hence this asserts the class, not just the message.
8019    ///
8020    /// It also pins `KafkaAdminClient.Call#handleTimeoutFailure`,
8021    /// which is what the retry-exhausted disconnect reaches:
8022    ///
8023    /// ```java
8024    /// handleFailure(new TimeoutException(this + " timed out at " + now
8025    ///     + " after " + tries + " attempt(s)", cause));
8026    /// ```
8027    ///
8028    /// The Rust message used to gain an invented `"Aborted due to timeout: "`
8029    /// prefix, drop the `Call(...)` rendering of `this`
8030    /// (`KafkaAdminClient.Call#toString`), and append the cause as text — leaving
8031    /// `Error::source()` empty where Java's `getCause()` is populated.
8032    #[tokio::test]
8033    async fn a_disconnect_fails_the_call_with_a_disconnect_error() {
8034        // One retry attempt only, so the call fails terminally rather than looping.
8035        let (admin, mut runnable, time, nodes) = env_with_props(&[("retries", "0")]);
8036        runnable.client_mut().prepare_response_disconnected(
8037            ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
8038                &nodes,
8039                Some("mock-cluster"),
8040                0,
8041                Vec::new(),
8042            )),
8043            true,
8044        );
8045
8046        let result = admin.list_topics_with_options(ListTopicsOptions::new());
8047        for _ in 0..30 {
8048            if result.names().is_done() {
8049                break;
8050            }
8051            runnable.run_once().await;
8052            time.sleep(200);
8053        }
8054        let error = result.names().get().await.expect_err("the disconnect must fail the call");
8055
8056        // With `retries=0` the call is out of retries immediately, so Java's
8057        // `handleTimeoutFailure` wraps the cause in a `TimeoutException`.
8058        assert!(error.is_timeout_error(), "got {error:?}");
8059        assert!(
8060            !error.message().starts_with("Aborted due to timeout"),
8061            "the invented prefix has no counterpart in the Kafka tree: {}",
8062            error.message()
8063        );
8064        assert!(
8065            error.message().starts_with("Call(callName=listTopics, deadlineMs="),
8066            "the message must open with Java's `Call.toString()` rendering: {}",
8067            error.message()
8068        );
8069        assert!(
8070            error.message().ends_with(" attempt(s)"),
8071            "and end exactly where Java's does, with the cause carried separately: {}",
8072            error.message()
8073        );
8074
8075        // The cause is the `DisconnectException` Java builds in
8076        // `org.apache.kafka.clients.admin.KafkaAdminClient.AdminClientRunnable#handleResponses`,
8077        // attached rather than stringified.
8078        let cause = error.source().expect("handleTimeoutFailure passes the cause through");
8079        assert!(
8080            matches!(cause, Error::Disconnect(_)),
8081            "expected a disconnect error; got {cause:?}"
8082        );
8083        assert!(
8084            cause.message().contains("being disconnected"),
8085            "the message keeps Java's text: {}",
8086            cause.message()
8087        );
8088        // `DisconnectException extends RetriableException`, so retriability is
8089        // unchanged relative to the old `NetworkError` — the class is the fix.
8090        assert!(cause.is_retriable_error(), "got {cause:?}");
8091    }
8092
8093    /// Translated from `KafkaAdminClientTest.testAdminBootstrapResolutionExceptionPropagated`
8094    /// (KIP-909): with a positive `bootstrap.resolve.timeout.ms` and an
8095    /// unresolvable bootstrap host, the client is created, calls fail with the
8096    /// `BootstrapResolutionException` once the budget runs out, and every later
8097    /// call fails with it too.
8098    #[tokio::test(flavor = "multi_thread")]
8099    #[doc(
8100        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testAdminBootstrapResolutionExceptionPropagated"
8101    )]
8102    async fn test_admin_bootstrap_resolution_error_propagated() {
8103        let invalid_host = "unresolvable.invalid:9092";
8104        let mut props = HashMap::new();
8105        props.insert(
8106            AdminClientConfig::BOOTSTRAP_SERVERS_CONFIG.to_string(),
8107            invalid_host.to_string(),
8108        );
8109        props.insert(
8110            AdminClientConfig::BOOTSTRAP_RESOLVE_TIMEOUT_MS_CONFIG.to_string(),
8111            "3000".to_string(),
8112        );
8113        let admin = KafkaAdminClient::new(AdminClientConfig::new(&props).unwrap())
8114            .expect("a positive timeout defers resolution, so creation succeeds");
8115
8116        let expected = "Failed to resolve bootstrap servers after 3000ms. \
8117                        Please check your bootstrap.servers configuration and DNS settings.";
8118        let start = std::time::Instant::now();
8119        let max_wait = std::time::Duration::from_millis(15000);
8120        loop {
8121            assert!(
8122                start.elapsed() < max_wait,
8123                "Expected the BootstrapResolutionError within {}ms",
8124                max_wait.as_millis()
8125            );
8126            if let Err(Error::BootstrapResolution(e)) = admin.list_topics().names().get().await {
8127                assert_eq!(e.message(), expected);
8128                break;
8129            }
8130        }
8131
8132        // After the first failure, any further API call must also surface the bootstrap error.
8133        match admin.list_topics().names().get().await {
8134            Err(Error::BootstrapResolution(e)) => assert_eq!(e.message(), expected),
8135            other => panic!("expected the bootstrap failure, got {other:?}"),
8136        }
8137
8138        // Rust-side (Critic 92, Issue 1): the `AdminApiDriver` RPCs reach Java's
8139        // `enqueue` through `runnable.call` too
8140        // (`org.apache.kafka.clients.admin.KafkaAdminClient#maybeSendRequests`),
8141        // so they fail with the same non-retriable error — not with the
8142        // retriable "thread has exited" timeout — and every future completes.
8143        let groups = vec!["group".to_string()];
8144        let bounded = Duration::from_secs(5);
8145        let driver_results = [
8146            tokio::time::timeout(bounded, admin.describe_consumer_groups(&groups).all().get())
8147                .await
8148                .map(|r| r.map(|_| ())),
8149            tokio::time::timeout(bounded, admin.delete_consumer_groups(&groups).all().get()).await,
8150            tokio::time::timeout(bounded, admin.list_transactions().all().get())
8151                .await
8152                .map(|r| r.map(|_| ())),
8153        ];
8154        for result in driver_results {
8155            match result.expect("a driver-path future must complete") {
8156                Err(Error::BootstrapResolution(e)) => assert_eq!(e.message(), expected),
8157                other => panic!("expected the bootstrap failure, got {other:?}"),
8158            }
8159        }
8160        admin.close().await;
8161    }
8162
8163    /// Translated from
8164    /// `KafkaAdminClientTest.testAdminConstructorFailsWithConfigExceptionOnUnresolvableBootstrapWhenTimeoutZero`
8165    /// (KAFKA-20939): the default `bootstrap.resolve.timeout.ms=0` resolves DNS
8166    /// synchronously in the constructor, so an unresolvable host fails creation
8167    /// with the `ConfigException` wrapped in the constructor's `KafkaException`.
8168    #[test]
8169    #[doc(
8170        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testAdminConstructorFailsWithConfigExceptionOnUnresolvableBootstrapWhenTimeoutZero"
8171    )]
8172    fn test_admin_constructor_fails_with_config_error_on_unresolvable_bootstrap_when_timeout_zero() {
8173        let mut props = HashMap::new();
8174        props.insert(
8175            AdminClientConfig::BOOTSTRAP_SERVERS_CONFIG.to_string(),
8176            "unresolvable.invalid:9092".to_string(),
8177        );
8178        let config = AdminClientConfig::new(&props).unwrap();
8179        assert_eq!(config.bootstrap_resolve_timeout_ms(), 0);
8180
8181        let error = KafkaAdminClient::new(config).expect_err("creation must fail");
8182        assert_eq!(error.message(), "Failed to create new KafkaAdminClient");
8183        let cause: &Error = std::error::Error::source(&error)
8184            .and_then(|e| e.downcast_ref::<Error>())
8185            .expect("the cause is a crate Error");
8186        assert!(matches!(cause, Error::Config(_)), "got {cause:?}");
8187        assert_eq!(cause.message(), "No resolvable bootstrap urls given in bootstrap.servers");
8188    }
8189
8190    /// The same for a client bootstrapping from `bootstrap.controllers`: its
8191    /// addresses go through the same `ClientUtils.parseAndValidateAddresses`,
8192    /// whose message names `bootstrap.servers` whichever list was given, so it
8193    /// does here too.
8194    #[test]
8195    fn test_admin_constructor_fails_with_config_error_on_unresolvable_bootstrap_controllers() {
8196        let mut props = HashMap::new();
8197        props.insert(
8198            AdminClientConfig::BOOTSTRAP_CONTROLLERS_CONFIG.to_string(),
8199            "unresolvable.invalid:9093".to_string(),
8200        );
8201        let config = AdminClientConfig::new(&props).unwrap();
8202
8203        let error = KafkaAdminClient::new(config).expect_err("creation must fail");
8204        assert_eq!(error.message(), "Failed to create new KafkaAdminClient");
8205        let cause: &Error = std::error::Error::source(&error)
8206            .and_then(|e| e.downcast_ref::<Error>())
8207            .expect("the cause is a crate Error");
8208        assert!(matches!(cause, Error::Config(_)), "got {cause:?}");
8209        assert_eq!(cause.message(), "No resolvable bootstrap urls given in bootstrap.servers");
8210    }
8211
8212    /// An admin config with `bootstrap.servers` and `bootstrap.controllers` set
8213    /// to the given values (`None` leaves a key unset).
8214    fn bootstrap_config(servers: Option<&str>, controllers: Option<&str>) -> AdminClientConfig {
8215        let mut props = HashMap::new();
8216        if let Some(servers) = servers {
8217            props.insert(AdminClientConfig::BOOTSTRAP_SERVERS_CONFIG.to_string(), servers.to_string());
8218        }
8219        if let Some(controllers) = controllers {
8220            props.insert(
8221                AdminClientConfig::BOOTSTRAP_CONTROLLERS_CONFIG.to_string(),
8222                controllers.to_string(),
8223            );
8224        }
8225        AdminClientConfig::new(&props).expect("the config accepts any bootstrap combination")
8226    }
8227
8228    /// `KafkaAdminClient#determineBootstrapType`'s three outcomes, with Java's
8229    /// messages. An empty list counts as unset.
8230    #[test]
8231    fn test_determine_bootstrap_type() {
8232        let determine =
8233            |servers, controllers| KafkaAdminClient::determine_bootstrap_type(&bootstrap_config(servers, controllers));
8234        assert!(!determine(Some("localhost:9092"), None).unwrap());
8235        assert!(!determine(Some("localhost:9092"), Some("")).unwrap());
8236        assert!(determine(None, Some("localhost:9093")).unwrap());
8237        assert!(determine(Some(" "), Some("localhost:9093")).unwrap());
8238        for (servers, controllers) in [(None, None), (Some(""), Some(" "))] {
8239            let error = determine(servers, controllers).unwrap_err();
8240            assert!(error.is_config_error(), "got {error:?}");
8241            assert_eq!(
8242                error.message(),
8243                "You must set either bootstrap.servers or bootstrap.controllers"
8244            );
8245        }
8246        let error = determine(Some("localhost:9092"), Some("localhost:9093")).unwrap_err();
8247        assert!(error.is_config_error(), "got {error:?}");
8248        assert_eq!(
8249            error.message(),
8250            "You cannot set both bootstrap.servers and bootstrap.controllers"
8251        );
8252    }
8253
8254    /// Java runs `determineBootstrapType` first inside the `try` of the
8255    /// `HostResolver` overload of
8256    /// `org.apache.kafka.clients.admin.KafkaAdminClient#createInternal`, before
8257    /// the `bootstrap.resolve.timeout.ms` branch, so a config with neither or
8258    /// both bootstrap lists fails client creation in both resolution modes, with
8259    /// `KafkaException("Failed to create new KafkaAdminClient", e)` whose cause
8260    /// is the `ConfigException`; the config itself is accepted. A
8261    /// whitespace-only value is an empty list, as Java's `ConfigDef` parses it.
8262    #[test]
8263    fn test_missing_bootstrap_fails_creation() {
8264        let neither = "You must set either bootstrap.servers or bootstrap.controllers";
8265        let both = "You cannot set both bootstrap.servers and bootstrap.controllers";
8266        for timeout in ["0", "1000"] {
8267            let with_timeout = |pairs: &[(&str, &str)]| {
8268                let mut props = HashMap::from([(
8269                    AdminClientConfig::BOOTSTRAP_RESOLVE_TIMEOUT_MS_CONFIG.to_string(),
8270                    timeout.to_string(),
8271                )]);
8272                for (key, value) in pairs {
8273                    props.insert((*key).to_string(), (*value).to_string());
8274                }
8275                props
8276            };
8277            for (props, message) in [
8278                (with_timeout(&[]), neither),
8279                (with_timeout(&[("bootstrap.servers", " ")]), neither),
8280                (with_timeout(&[("bootstrap.controllers", " ")]), neither),
8281                (
8282                    with_timeout(&[
8283                        ("bootstrap.servers", "localhost:9092"),
8284                        ("bootstrap.controllers", "localhost:9093"),
8285                    ]),
8286                    both,
8287                ),
8288            ] {
8289                let config = AdminClientConfig::new(&props).unwrap();
8290                let error = KafkaAdminClient::new(config).expect_err("creation must fail");
8291                assert_eq!(error.message(), "Failed to create new KafkaAdminClient", "{props:?}");
8292                assert!(error.is_kafka_error(), "got {error:?}");
8293                assert!(!error.is_api_error(), "got {error:?}");
8294                let cause: &Error = std::error::Error::source(&error)
8295                    .and_then(|e| e.downcast_ref::<Error>())
8296                    .expect("the cause is a crate Error");
8297                assert!(cause.is_config_error(), "got {cause:?}");
8298                assert_eq!(cause.message(), message, "{props:?}");
8299            }
8300        }
8301    }
8302
8303    /// Java's `newConfMap`: `bootstrap.servers` and `request.timeout.ms=1000`
8304    /// (`KafkaAdminClientTestBase.newStrMap`), plus `extra`.
8305    fn new_conf_map(extra: &[(&str, &str)]) -> AdminClientConfig {
8306        let mut props = HashMap::from([
8307            ("bootstrap.servers".to_string(), "localhost:8121".to_string()),
8308            ("request.timeout.ms".to_string(), "1000".to_string()),
8309        ]);
8310        props.extend(extra.iter().map(|(k, v)| (k.to_string(), v.to_string())));
8311        AdminClientConfig::new(&props).unwrap()
8312    }
8313
8314    /// Translated from `KafkaAdminClientTest.testDefaultApiTimeoutAndRequestTimeoutConflicts`:
8315    /// an explicit `default.api.timeout.ms` (500) below `request.timeout.ms`
8316    /// (1000) fails creation with `configureDefaultApiTimeoutMs`'s
8317    /// `ConfigException`, wrapped in the constructor's `KafkaException`
8318    /// (`KafkaAdminClient#createInternal`,
8319    /// `KafkaAdminClient#configureDefaultApiTimeoutMs`).
8320    #[tokio::test]
8321    #[doc(
8322        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testDefaultApiTimeoutAndRequestTimeoutConflicts"
8323    )]
8324    async fn test_default_api_timeout_and_request_timeout_conflicts() {
8325        let config = new_conf_map(&[("default.api.timeout.ms", "500")]);
8326        let error = KafkaAdminClient::new(config).expect_err("creation must fail");
8327        assert!(error.is_kafka_error(), "{error:?}");
8328        assert_eq!(error.message(), "Failed to create new KafkaAdminClient");
8329        let cause: &Error = std::error::Error::source(&error)
8330            .and_then(|e| e.downcast_ref::<Error>())
8331            .expect("the cause is a crate Error");
8332        assert!(matches!(cause, Error::Config(_)), "got {cause:?}");
8333        assert_eq!(
8334            cause.message(),
8335            "The specified value of default.api.timeout.ms must be no smaller than the value of request.timeout.ms."
8336        );
8337    }
8338
8339    /// `configureDefaultApiTimeoutMs`'s three branches: an explicit API timeout
8340    /// below the request timeout is an error; an unset one below it is raised
8341    /// to the request timeout (with a WARN); otherwise the API timeout is kept,
8342    /// explicit or default. The raised value is what the client's calls use.
8343    #[test]
8344    fn test_configure_default_api_timeout_ms() {
8345        let configure = |extra: &[(&str, &str)]| {
8346            let mut props = HashMap::from([("bootstrap.servers".to_string(), "localhost:9092".to_string())]);
8347            props.extend(extra.iter().map(|(k, v)| (k.to_string(), v.to_string())));
8348            KafkaAdminClient::configure_default_api_timeout_ms(
8349                &AdminClientConfig::new(&props).unwrap(),
8350                &LogContext::empty(),
8351            )
8352        };
8353        let err = configure(&[("default.api.timeout.ms", "10000"), ("request.timeout.ms", "30000")]).unwrap_err();
8354        assert!(matches!(err, Error::Config(_)), "got {err:?}");
8355        assert_eq!(
8356            err.message(),
8357            "The specified value of default.api.timeout.ms must be no smaller than the value of request.timeout.ms."
8358        );
8359        assert_eq!(configure(&[("request.timeout.ms", "70000")]).unwrap(), 70_000);
8360        assert_eq!(configure(&[("request.timeout.ms", "30000")]).unwrap(), 60_000);
8361        assert_eq!(configure(&[]).unwrap(), 60_000);
8362        assert_eq!(
8363            configure(&[("default.api.timeout.ms", "30000"), ("request.timeout.ms", "30000")]).unwrap(),
8364            30_000
8365        );
8366        assert_eq!(
8367            configure(&[("default.api.timeout.ms", "90000"), ("request.timeout.ms", "30000")]).unwrap(),
8368            90_000
8369        );
8370
8371        let (admin, _runnable, _time, _nodes) = env_with_props(&[("request.timeout.ms", "70000")]);
8372        assert_eq!(admin.shared.default_api_timeout_ms, 70_000);
8373    }
8374
8375    /// Java's `testApiTimeout(requestTimeoutMs, defaultApiTimeoutMs,
8376    /// overrideApiTimeoutMs)`: with an effective API timeout of twice the
8377    /// request timeout, the first `listTopics` attempt times out after the
8378    /// request timeout and is retried, and the call fails with a timeout after
8379    /// the second.
8380    async fn test_api_timeout(
8381        request_timeout_ms: i64,
8382        default_api_timeout_ms: i64,
8383        override_api_timeout_ms: Option<i32>,
8384    ) {
8385        let retry_backoff_ms = 100;
8386        let effective_timeout_ms = override_api_timeout_ms.map_or(default_api_timeout_ms, i64::from);
8387        assert_eq!(
8388            2 * request_timeout_ms,
8389            effective_timeout_ms,
8390            "This test expects the effective timeout to be twice the request timeout"
8391        );
8392        let (admin, mut runnable, time, _nodes) = env_nodes_with_props(
8393            1,
8394            &[
8395                ("retry.backoff.ms", &retry_backoff_ms.to_string()),
8396                ("request.timeout.ms", &request_timeout_ms.to_string()),
8397                ("default.api.timeout.ms", &default_api_timeout_ms.to_string()),
8398            ],
8399        );
8400        let options = ListTopicsOptions::new().set_timeout_ms(override_api_timeout_ms);
8401        let future = admin.list_topics_with_options(options).names_to_listings();
8402
8403        // Wait until the first attempt has been sent, then advance the time
8404        pump_until(&mut runnable, 40, |r| r.client_mut().has_in_flight_requests()).await;
8405        assert!(
8406            runnable.client_mut().has_in_flight_requests(),
8407            "Timed out waiting for Metadata request to be sent"
8408        );
8409        time.sleep(request_timeout_ms + 1);
8410
8411        // Wait for the request to be timed out before backing off
8412        pump_until(&mut runnable, 40, |r| !r.client_mut().has_in_flight_requests()).await;
8413        assert!(
8414            !runnable.client_mut().has_in_flight_requests(),
8415            "Timed out waiting for inFlightRequests to be timed out"
8416        );
8417
8418        // Since api timeout bound is not hit, AdminClient should retry
8419        pump_until(&mut runnable, 40, |r| {
8420            let has_inflight_requests = r.client_mut().has_in_flight_requests();
8421            if !has_inflight_requests {
8422                time.sleep(retry_backoff_ms);
8423            }
8424            has_inflight_requests
8425        })
8426        .await;
8427        assert!(
8428            runnable.client_mut().has_in_flight_requests(),
8429            "Timed out waiting for Metadata request to be sent"
8430        );
8431        time.sleep(request_timeout_ms + 1);
8432
8433        pump_until(&mut runnable, 40, |_| future.is_done()).await;
8434        assert!(future.is_done(), "Timed out waiting for the listTopics call to time out");
8435        let error = future.get().await.unwrap_err();
8436        assert!(matches!(error, Error::Timeout(_)), "got {error:?}");
8437    }
8438
8439    /// Translated from `KafkaAdminClientTest.testDefaultApiTimeout`.
8440    #[tokio::test]
8441    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testDefaultApiTimeout")]
8442    async fn test_default_api_timeout() {
8443        test_api_timeout(1500, 3000, None).await;
8444    }
8445
8446    /// Translated from `KafkaAdminClientTest.testDefaultApiTimeoutOverride`.
8447    #[tokio::test]
8448    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testDefaultApiTimeoutOverride")]
8449    async fn test_default_api_timeout_override() {
8450        test_api_timeout(1500, 10000, Some(3000)).await;
8451    }
8452
8453    /// Translated from `KafkaAdminClientTest.testRequestTimeoutExceedingDefaultApiTimeout`:
8454    /// with `request.timeout.ms=120000` and `default.api.timeout.ms` unset, the
8455    /// API timeout is raised to 120000, so the `listTopics` metadata request is
8456    /// still in flight after the default 60000 ms and the call fails with a
8457    /// timeout once the request timeout passes. Java's thread runs
8458    /// concurrently with the test; here the runnable is pumped after each
8459    /// `sleep`, so the in-flight check sees the timeouts processed.
8460    #[tokio::test]
8461    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testRequestTimeoutExceedingDefaultApiTimeout")]
8462    async fn test_request_timeout_exceeding_default_api_timeout() {
8463        // This test assumes the default api timeout value of 60000. When the request timeout
8464        // is set to something larger, we should adjust the api timeout accordingly for compatibility.
8465        let retry_backoff_ms = 100;
8466        let request_timeout_ms = 120_000;
8467        let (admin, mut runnable, time, _nodes) = env_nodes_with_props(
8468            1,
8469            &[
8470                ("retry.backoff.ms", &retry_backoff_ms.to_string()),
8471                ("request.timeout.ms", &request_timeout_ms.to_string()),
8472            ],
8473        );
8474        let future = admin.list_topics_with_options(ListTopicsOptions::new()).names_to_listings();
8475
8476        // Wait until the first attempt has been sent, then advance the time by the default api timeout
8477        pump_until(&mut runnable, 40, |r| r.client_mut().has_in_flight_requests()).await;
8478        assert!(
8479            runnable.client_mut().has_in_flight_requests(),
8480            "Timed out waiting for Metadata request to be sent"
8481        );
8482        time.sleep(60001);
8483        pump(&mut runnable, 5).await;
8484
8485        // The in-flight request should not be cancelled
8486        assert!(runnable.client_mut().has_in_flight_requests());
8487        assert!(!future.is_done());
8488
8489        // Now sleep the remaining time for the request timeout to expire
8490        time.sleep(60000);
8491        pump_until(&mut runnable, 40, |_| future.is_done()).await;
8492        assert!(future.is_done(), "Timed out waiting for the listTopics call to time out");
8493        let error = future.get().await.unwrap_err();
8494        assert!(matches!(error, Error::Timeout(_)), "got {error:?}");
8495    }
8496
8497    /// A [`Call`] whose failure hook records the error it was failed with.
8498    fn recording_call(name: &str) -> (Call, Arc<Mutex<Option<Error>>>) {
8499        let failure = Arc::new(Mutex::new(None));
8500        let recorded = Arc::clone(&failure);
8501        let call = Call::new(
8502            name,
8503            i64::MAX,
8504            NodeProvider::LeastLoaded,
8505            Box::new(|_| Err(Error::kafka_message("not sent"))),
8506            Box::new(|_, _, _| HandleResult::Done),
8507            Box::new(move |error: &Error| *recorded.lock().unwrap() = Some(error.clone())),
8508            Box::new(|_| false),
8509        );
8510        (call, failure)
8511    }
8512
8513    /// `CallSender::call` is the one enqueue path (Java's `runnable.call` →
8514    /// `enqueue`): once a bootstrap failure is recorded, a call is failed with
8515    /// it instead of being handed to the task, and a call reaching a task that
8516    /// has exited is failed rather than dropped.
8517    #[test]
8518    fn test_call_sender_applies_the_enqueue_checks() {
8519        let (tx, mut rx) = mpsc::unbounded_channel();
8520        let sender = CallSender::for_test(tx);
8521
8522        let (call, failure) = recording_call("accepted");
8523        sender.call(call);
8524        assert!(rx.try_recv().is_ok(), "accepted while nothing is recorded");
8525        assert!(failure.lock().unwrap().is_none());
8526
8527        let mut updater = sender.metadata_manager.updater();
8528        updater.bootstrap_failed(Error::BootstrapResolution(
8529            crate::common::errors::BootstrapResolutionError::new("dns"),
8530        ));
8531        // The I/O task has exited (it sets `closing` on the way out), but no
8532        // `close()` set a hard-shutdown time: the bootstrap failure wins.
8533        sender.shutdown.closing.store(true, atomic::Ordering::Release);
8534        let (call, failure) = recording_call("after the failure");
8535        sender.call(call);
8536        assert!(rx.try_recv().is_err(), "never handed to the task");
8537        match failure.lock().unwrap().take() {
8538            Some(Error::BootstrapResolution(e)) => assert_eq!(e.message(), "dns"),
8539            other => panic!("expected the bootstrap failure, got {other:?}"),
8540        }
8541
8542        // After `close()` set a hard-shutdown time, Java's `call()` rejects first.
8543        sender.shutdown.hard_shutdown_deadline_ms.store(0, atomic::Ordering::Release);
8544        let (call, failure) = recording_call("after close");
8545        sender.call(call);
8546        assert_eq!(
8547            failure.lock().unwrap().take().expect("failed").message(),
8548            "Cannot accept new calls when AdminClient is closing."
8549        );
8550
8551        // A task that has exited on its own without a bootstrap failure (e.g. a
8552        // panic caught in `run`): `fail_all_remaining` set `closing` and closed
8553        // the channel, but no `close()` set a hard-shutdown time. Java's `call()`
8554        // does not reject; `enqueue` answers with its `TimeoutException`, and the
8555        // call is never silently dropped (Critic 92, Issue 5).
8556        let (tx, mut rx) = mpsc::unbounded_channel();
8557        let sender = CallSender::for_test(tx);
8558        sender.shutdown.closing.store(true, atomic::Ordering::Release);
8559        rx.close();
8560        let (call, failure) = recording_call("exited");
8561        sender.call(call);
8562        let error = failure.lock().unwrap().take().expect("failed");
8563        assert!(matches!(error, Error::Timeout(_)), "got {error:?}");
8564        assert_eq!(error.message(), "The AdminClient thread has exited.");
8565    }
8566
8567    /// Java's `KafkaAdminClient.AdminClientRunnable#enqueue` starts with the
8568    /// retry budget: a call whose `tries` already exceed `maxRetries` is failed
8569    /// through `handleTimeoutFailure` with
8570    /// `TimeoutException("Exceeded maxRetries after N tries.")` — passed through
8571    /// unwrapped, being a timeout — and never handed to the task.
8572    /// `tries == maxRetries` is still accepted. The check precedes the
8573    /// bootstrap-failure check, so an exhausted call reports the retry budget
8574    /// even after a bootstrap failure.
8575    #[test]
8576    fn test_call_sender_fails_a_call_past_its_retry_budget() {
8577        let (tx, mut rx) = mpsc::unbounded_channel();
8578        let mut sender = CallSender::for_test(tx);
8579        sender.max_retries = 2;
8580
8581        let (mut call, failure) = recording_call("atTheBudget");
8582        call.tries = 2;
8583        sender.call(call);
8584        assert!(rx.try_recv().is_ok(), "tries == maxRetries is accepted");
8585        assert!(failure.lock().unwrap().is_none());
8586
8587        let (mut call, failure) = recording_call("pastTheBudget");
8588        call.tries = 3;
8589        sender.call(call);
8590        assert!(rx.try_recv().is_err(), "never handed to the task");
8591        let error = failure.lock().unwrap().take().expect("failed");
8592        assert!(matches!(error, Error::Timeout(_)), "got {error:?}");
8593        assert_eq!(error.message(), "Exceeded maxRetries after 3 tries.");
8594        assert!(std::error::Error::source(&error).is_none(), "the timeout is not wrapped");
8595
8596        // Java's order: `enqueue`'s budget check runs before its bootstrap check.
8597        let mut updater = sender.metadata_manager.updater();
8598        updater.bootstrap_failed(Error::BootstrapResolution(
8599            crate::common::errors::BootstrapResolutionError::new("dns"),
8600        ));
8601        let (mut call, failure) = recording_call("pastTheBudgetAfterBootstrapFailure");
8602        call.tries = 3;
8603        sender.call(call);
8604        assert_eq!(
8605            failure.lock().unwrap().take().expect("failed").message(),
8606            "Exceeded maxRetries after 3 tries."
8607        );
8608
8609        // ... but after `call()`'s own hard-shutdown check.
8610        sender.shutdown.hard_shutdown_deadline_ms.store(0, atomic::Ordering::Release);
8611        let (mut call, failure) = recording_call("pastTheBudgetWhileClosing");
8612        call.tries = 3;
8613        sender.call(call);
8614        assert_eq!(
8615            failure.lock().unwrap().take().expect("failed").message(),
8616            "Cannot accept new calls when AdminClient is closing."
8617        );
8618    }
8619
8620    /// End to end through a driver: `deleteRecords` with `retries=0` on a
8621    /// retriable partition error. The driver re-issues the spec with `tries = 1`,
8622    /// and `enqueue` fails it with the retry-budget timeout rather than letting it
8623    /// spin until the deadline.
8624    #[tokio::test]
8625    async fn test_driver_reissued_call_past_its_retry_budget_times_out() {
8626        let (admin, mut runnable, time, nodes) = env_with_props(&[("retries", "0")]);
8627        let tp0 = TopicPartition::new("foo", 0);
8628        runnable
8629            .client_mut()
8630            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 0)])]));
8631        runnable.client_mut().prepare_response_from(
8632            delete_records_resp("foo", vec![delete_records_partition(0, Errors::NotLeaderOrFollower, -1)]),
8633            &nodes[0],
8634        );
8635        let mut records = HashMap::new();
8636        records.insert(tp0.clone(), RecordsToDelete::with_offset(10));
8637        let result = admin.delete_records_with_options(&records, DeleteRecordsOptions::new());
8638        for _ in 0..40 {
8639            if result.low_watermarks()[&tp0].is_done() {
8640                break;
8641            }
8642            runnable.run_once().await;
8643            time.sleep(50);
8644        }
8645        // Without the budget check the re-issued call retries until the 60 s
8646        // deadline, far past this loop; fail fast rather than hang on `get`.
8647        assert!(result.low_watermarks()[&tp0].is_done(), "the exhausted call was not failed");
8648        let error = result.low_watermarks()[&tp0].get().await.unwrap_err();
8649        assert!(matches!(error, Error::Timeout(_)), "got {error:?}");
8650        assert!(
8651            error.message().starts_with("Exceeded maxRetries after"),
8652            "got {:?}",
8653            error.message()
8654        );
8655    }
8656
8657    /// Java wraps the admin-client constructor in `catch (Throwable exc)` and
8658    /// rethrows `new KafkaException("Failed to create new KafkaAdminClient", exc)`
8659    /// (in both overloads of `KafkaAdminClient#createInternal`), so a caller has one
8660    /// class and one message for "admin client construction failed".
8661    ///
8662    /// The three failure points used to surface in three different shapes, none of
8663    /// them Java's: a leaked underlying error, an `illegal_argument`
8664    /// (`is_kafka_error()` → `false`) with an invented message, and a panic.
8665    #[test]
8666    fn construction_failures_are_wrapped_as_a_kafka_error() {
8667        let mut props = HashMap::new();
8668        props.insert("bootstrap.servers".to_string(), "not-a-host-port".to_string());
8669        let config = AdminClientConfig::new(&props).expect("the config itself parses");
8670
8671        let error =
8672            KafkaAdminClient::new(config).expect_err("an unparseable bootstrap.servers entry must fail construction");
8673
8674        assert_eq!(error.message(), "Failed to create new KafkaAdminClient");
8675        // Java's replacement is a bare `KafkaException`.
8676        assert!(error.is_kafka_error(), "Java's replacement is a Kafka error: {error:?}");
8677        assert!(!error.is_api_error(), "a bare Kafka error is not an API error: {error:?}");
8678        assert!(error.source().is_some(), "the underlying failure must be the wrapper's cause");
8679        // The cause is `parseAndValidateAddresses`' `ConfigException`, with its
8680        // single-message text.
8681        let cause: &Error = std::error::Error::source(&error)
8682            .and_then(|e| e.downcast_ref::<Error>())
8683            .expect("the cause is a crate Error");
8684        assert!(matches!(cause, Error::Config(_)), "got {cause:?}");
8685        assert_eq!(cause.message(), "Invalid url in bootstrap.servers: not-a-host-port");
8686    }
8687
8688    /// `KafkaAdminClient.AdminClientRunnable#run`'s `finally`
8689    /// fails every pending call with
8690    /// `TimeoutException("The AdminClient thread has exited. Call: <name>")`,
8691    /// **however** `processRequests` terminated.
8692    ///
8693    /// Translated as straight-line code after the loop it was not a `finally` at
8694    /// all: any panic inside a loop iteration skipped both `fail_all_remaining` and
8695    /// `client.close()`, so no outstanding `KafkaFuture` was ever completed and no
8696    /// socket was closed — a silent permanent hang.
8697    #[tokio::test]
8698    async fn a_panicking_io_task_still_runs_its_finally() {
8699        let (admin, mut runnable, time, _nodes) = env();
8700
8701        // Inject a panic inside the loop body, standing in for the
8702        // `ClassCastException`s Java's `catch (Throwable t)` covers (the Issue-66
8703        // sites). An already-expired deadline makes `process_pending_calls`'s step 2
8704        // (`handle_timeouts` -> `fail_call` -> `handle_timeout_failure`) invoke this
8705        // call's failure hook on the very first iteration, so the injection is
8706        // deterministic. It panics only once, so the `finally`'s own re-failing of
8707        // the queue can be observed instead of panicking again.
8708        let failures = Arc::new(AtomicI64::new(0));
8709        let counter = Arc::clone(&failures);
8710        let now = time.milliseconds();
8711        admin.submit(Call::new(
8712            "panicOnPurpose",
8713            now - 1,
8714            NodeProvider::LeastLoaded,
8715            Box::new(|_timeout_ms| unreachable!("the call expires before it is ever sent")),
8716            Box::new(|_response, _now, _cur_node| HandleResult::Done),
8717            Box::new(move |_error| {
8718                if counter.fetch_add(1, Ordering::AcqRel) == 0 {
8719                    panic!("injected panic inside the I/O loop");
8720                }
8721            }),
8722            Box::new(|_| false),
8723        ));
8724
8725        // `run()` must return: the panic ends `process_requests`, and the `finally`
8726        // then runs. Bounded so a regression shows up as a failure, not a hang.
8727        tokio::time::timeout(std::time::Duration::from_secs(10), runnable.run())
8728            .await
8729            .expect("run() must reach its finally after a panic, not spin or abort");
8730
8731        assert_eq!(
8732            failures.load(Ordering::Acquire),
8733            1,
8734            "the injected panic must actually have fired"
8735        );
8736        // `client.close()` is the tail of Java's `finally`; it only runs if the
8737        // whole block was reached. Straight-line code after the loop skipped it.
8738        assert!(
8739            !runnable.client_mut().active(),
8740            "the finally must close the client even when the loop body panicked"
8741        );
8742    }
8743
8744    /// `KafkaAdminClient.AdminClientRunnable#sendEligibleCalls` wraps a
8745    /// `createRequest` failure as
8746    ///
8747    /// ```java
8748    /// new KafkaException(String.format("Internal error sending %s to %s.", call.callName, node), t)
8749    /// ```
8750    ///
8751    /// — a bare `KafkaException` carrying the original as its cause. It used to be
8752    /// an `Error::local_illegal_state` (`is_kafka_error()` → `false`) whose message had
8753    /// the cause text appended, so `Error::source()` was empty.
8754    #[tokio::test]
8755    async fn a_create_request_failure_is_wrapped_as_a_kafka_error() {
8756        let (admin, mut runnable, time, _nodes) = env_with_props(&[("retries", "0")]);
8757
8758        let failure: Arc<Mutex<Option<Error>>> = Arc::new(Mutex::new(None));
8759        let sink = Arc::clone(&failure);
8760        let now = time.milliseconds();
8761        admin.submit(Call::new(
8762            "createRequestBoom",
8763            now + 60_000,
8764            NodeProvider::LeastLoaded,
8765            Box::new(|_timeout_ms| Err(Error::new(Errors::InvalidRequest))),
8766            Box::new(|_response, _now, _cur_node| HandleResult::Done),
8767            Box::new(move |error| {
8768                *sink.lock().unwrap() = Some(error.clone());
8769            }),
8770            Box::new(|_| false),
8771        ));
8772
8773        for _ in 0..30 {
8774            runnable.run_once().await;
8775            time.sleep(200);
8776            if failure.lock().unwrap().is_some() {
8777                break;
8778            }
8779        }
8780
8781        let error = failure.lock().unwrap().take().expect("the call must be failed");
8782        assert_eq!(
8783            error.message(),
8784            "Internal error sending createRequestBoom to localhost:9092 (id: 0 rack: None isFenced: false)."
8785        );
8786        // Java's replacement is a bare `KafkaException`.
8787        assert!(error.is_kafka_error(), "Java's replacement is a Kafka error: {error:?}");
8788        assert!(!error.is_api_error(), "a bare Kafka error is not an API error: {error:?}");
8789        assert_eq!(
8790            error.source().expect("the createRequest error is the cause").error(),
8791            Errors::InvalidRequest,
8792            "the cause is attached, not stringified into the message"
8793        );
8794    }
8795
8796    /// `KafkaAdminClient.AdminClientRunnable#makeBrokerMetadataCall`'s
8797    /// `handleResponse` does `(MetadataResponse) abstractResponse` unguarded
8798    /// and relies on `KafkaAdminClient.AdminClientRunnable#handleResponses`'s
8799    /// `catch (Throwable t)` → `call.fail(now, t)` → non-retriable →
8800    /// `handleFailure` → `metadataManager.updateFailed(e)`.
8801    ///
8802    /// Swallowing the mismatch ran neither `update()` nor `update_failed()` while
8803    /// `process_pending_calls` had already called `transition_to_update_pending`, and
8804    /// `metadata_fetch_delay_ms` returns `i64::MAX` in `UPDATE_PENDING` — so the
8805    /// client never refreshed metadata again for its whole lifetime, and
8806    /// `HandleResult::Done` on an internal call also re-queued the pending calls
8807    /// against permanently stale metadata.
8808    #[tokio::test]
8809    async fn a_wrong_typed_metadata_response_does_not_pin_the_manager_in_update_pending() {
8810        let (_admin, mut runnable, time, _nodes) = env_with_props(&[("retries", "0")]);
8811
8812        // Force the internal metadata refresh, then answer it with the wrong type.
8813        runnable.metadata_manager().request_update();
8814        runnable.client_mut().prepare_response(ConcreteResponse::ListGroups(
8815            crate::common::requests::ListGroupsResponse::new(crate::ListGroupsResponseData::new()),
8816        ));
8817
8818        for _ in 0..30 {
8819            runnable.run_once().await;
8820            time.sleep(200);
8821            if runnable.client_mut().num_awaiting_responses() == 0 {
8822                break;
8823            }
8824        }
8825        // The refresh must actually have gone out and consumed the wrong-typed
8826        // response, or this test would pass vacuously.
8827        assert_eq!(
8828            runnable.client_mut().num_awaiting_responses(),
8829            0,
8830            "the internal metadata call must have been issued and answered"
8831        );
8832
8833        assert_ne!(
8834            runnable.metadata_manager().metadata_fetch_delay_ms(time.milliseconds()),
8835            i64::MAX,
8836            "the manager must leave UPDATE_PENDING and retry under backoff, as Java's \
8837             updateFailed(e) makes it"
8838        );
8839    }
8840
8841    /// `KafkaAdminClient.AdminClientRunnable#makeBrokerMetadataCall`'s
8842    /// `handleResponse`: a top-level `REBOOTSTRAP_REQUIRED` calls
8843    /// `initiateRebootstrap()` instead of `update(response.buildCluster(), now)`,
8844    /// so the next `NetworkClient` poll rebootstraps at once whatever
8845    /// `metadata.recovery.rebootstrap.trigger.ms` is.
8846    #[tokio::test]
8847    async fn a_rebootstrap_required_metadata_response_initiates_a_rebootstrap() {
8848        let (_admin, mut runnable, time, nodes) = env();
8849
8850        runnable.metadata_manager().request_update();
8851        let mut data = crate::MetadataResponseData::new();
8852        data.set_error_code(Errors::RebootstrapRequired.code());
8853        runnable
8854            .client_mut()
8855            .prepare_response(ConcreteResponse::Metadata(MetadataResponse::with_version(
8856                data,
8857                crate::common::protocol::ApiKeys::METADATA.latest_version(),
8858            )));
8859        for _ in 0..30 {
8860            runnable.run_once().await;
8861            time.sleep(200);
8862            if runnable.client_mut().num_awaiting_responses() == 0 {
8863                break;
8864            }
8865        }
8866        assert_eq!(
8867            runnable.client_mut().num_awaiting_responses(),
8868            0,
8869            "the internal metadata call must have been issued and answered"
8870        );
8871
8872        // `initiateRebootstrap` sets the attempt start to 0, which Java's
8873        // wall-clock `now` puts far beyond any trigger. The mock clock started at
8874        // 1000, so a trigger of `now - 1` is due only for a start before 1 ms: the
8875        // attempt started at 1000 or later would not explain it.
8876        let now = time.milliseconds();
8877        assert!(runnable.metadata_manager().needs_rebootstrap(now, now - 1));
8878        // `buildCluster()` was not applied: the cluster is still the three brokers.
8879        assert_eq!(runnable.metadata_manager().node_by_id(nodes[2].id()), Some(nodes[2].clone()));
8880    }
8881
8882    /// The counterpart: an ordinary metadata response is applied with `update`,
8883    /// which clears the attempt start, so no rebootstrap is due.
8884    #[tokio::test]
8885    async fn an_ordinary_metadata_response_does_not_initiate_a_rebootstrap() {
8886        let (_admin, mut runnable, time, nodes) = env();
8887
8888        runnable.metadata_manager().request_update();
8889        // Two of the three brokers, so the test can see `update` ran.
8890        runnable
8891            .client_mut()
8892            .prepare_response(ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
8893                &nodes[..2],
8894                Some("mock-cluster"),
8895                0,
8896                Vec::new(),
8897            )));
8898        for _ in 0..30 {
8899            runnable.run_once().await;
8900            time.sleep(200);
8901            if runnable.client_mut().num_awaiting_responses() == 0 {
8902                break;
8903            }
8904        }
8905        assert_eq!(runnable.client_mut().num_awaiting_responses(), 0);
8906        assert_eq!(runnable.metadata_manager().node_by_id(nodes[2].id()), None, "update ran");
8907        assert!(!runnable.metadata_manager().needs_rebootstrap(time.milliseconds(), 0));
8908    }
8909
8910    // --- listTopics ----------------------------------------------------------
8911
8912    #[tokio::test]
8913    async fn test_list_topics_filters_internal_by_default() {
8914        let (admin, mut runnable, _time, nodes) = env();
8915        let result = admin.list_topics_with_options(ListTopicsOptions::new());
8916        let topics = vec![
8917            topic_meta("visible", false, Uuid::new(0, 1), 1),
8918            topic_meta("__consumer_offsets", true, Uuid::new(0, 2), 1),
8919        ];
8920        runnable
8921            .client_mut()
8922            .prepare_response(ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
8923                &nodes,
8924                Some("mock-cluster"),
8925                0,
8926                topics,
8927            )));
8928        pump(&mut runnable, 5).await;
8929        let names = result.names().get().await.unwrap();
8930        assert!(names.contains("visible"));
8931        assert!(!names.contains("__consumer_offsets"));
8932    }
8933
8934    #[tokio::test]
8935    async fn test_list_topics_includes_internal_when_requested() {
8936        let (admin, mut runnable, _time, nodes) = env();
8937        let result = admin.list_topics_with_options(ListTopicsOptions::new().set_list_internal(true));
8938        let topics = vec![topic_meta("__consumer_offsets", true, Uuid::new(0, 2), 1)];
8939        runnable
8940            .client_mut()
8941            .prepare_response(ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
8942                &nodes,
8943                Some("mock-cluster"),
8944                0,
8945                topics,
8946            )));
8947        pump(&mut runnable, 5).await;
8948        let names = result.names().get().await.unwrap();
8949        assert!(names.contains("__consumer_offsets"));
8950    }
8951
8952    /// Java's `calcDeadlineMs` clamps a negative option timeout to zero
8953    /// (`now + Math.max(0, optionTimeoutMs)` in `KafkaAdminClient#calcDeadlineMs`),
8954    /// so on a frozen clock a call with `timeoutMs = -1` has `deadlineMs == now`.
8955    /// The timeout processor only expires a call whose remaining time is `< 0`
8956    /// (`KafkaAdminClient.TimeoutProcessor#handleTimeouts` and
8957    /// `KafkaAdminClient.TimeoutProcessor#callHasExpired`), so the call is sent and
8958    /// succeeds. Without the clamp the deadline is `now - 1` and the call expires
8959    /// unsent.
8960    #[tokio::test]
8961    async fn test_negative_option_timeout_is_clamped_to_zero() {
8962        let (admin, mut runnable, time, nodes) = env();
8963        let result = admin.list_topics_with_options(ListTopicsOptions::new().set_timeout_ms(Some(-1)));
8964        runnable
8965            .client_mut()
8966            .prepare_response(ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
8967                &nodes,
8968                Some("mock-cluster"),
8969                0,
8970                vec![topic_meta("visible", false, Uuid::new(0, 1), 1)],
8971            )));
8972        pump(&mut runnable, 5).await;
8973        let names = result.names().get().await.expect("the call must be sent, not expired");
8974        assert!(names.contains("visible"));
8975
8976        let now = time.milliseconds();
8977        assert_eq!(calc_deadline_ms(now, Some(-1), 60_000), now);
8978        assert_eq!(calc_deadline_ms(now, Some(i32::MIN), 60_000), now);
8979        assert_eq!(calc_deadline_ms(now, Some(0), 60_000), now);
8980        assert_eq!(calc_deadline_ms(now, Some(5), 60_000), now + 5);
8981        assert_eq!(calc_deadline_ms(now, None, 60_000), now + 60_000);
8982    }
8983
8984    // --- describeTopics ------------------------------------------------------
8985
8986    use crate::DescribeTopicPartitionsResponseData;
8987    use crate::common::utils::Utils;
8988    use crate::describe_topic_partitions_response_data::{
8989        Cursor as DescribeTopicPartitionsResponseCursor, DescribeTopicPartitionsResponsePartition,
8990    };
8991
8992    /// `KafkaAdminClientTest.addPartitionToDescribeTopicPartitionsResponse`:
8993    /// adds `topic_name` with one partition per index, each led by broker 0
8994    /// with replicas `[0, 1, 2]`, ISR `[0]`, ELR `[1]` and last-known ELR `[2]`.
8995    fn add_partition_to_describe_topic_partitions_response(
8996        data: &mut DescribeTopicPartitionsResponseData,
8997        topic_name: &str,
8998        topic_id: Uuid,
8999        partitions: &[i32],
9000    ) {
9001        let adding_partitions = partitions
9002            .iter()
9003            .map(|partition| {
9004                let mut p = DescribeTopicPartitionsResponsePartition::new();
9005                p.set_isr_nodes(vec![0])
9006                    .set_error_code(0)
9007                    .set_leader_epoch(0)
9008                    .set_leader_id(0)
9009                    .set_eligible_leader_replicas(Some(vec![1]))
9010                    .set_last_known_elr(Some(vec![2]))
9011                    .set_partition_index(*partition)
9012                    .set_replica_nodes(vec![0, 1, 2]);
9013                p
9014            })
9015            .collect();
9016        let mut topic = DescribeTopicPartitionsResponseTopic::new();
9017        topic
9018            .set_error_code(0)
9019            .set_topic_id(topic_id)
9020            .set_name(Some(topic_name.to_string()))
9021            .set_is_internal(false)
9022            .set_partitions(adding_partitions);
9023        data.topics.push(topic);
9024    }
9025
9026    fn set_next_cursor(data: &mut DescribeTopicPartitionsResponseData, topic_name: &str, partition_index: i32) {
9027        let mut cursor = DescribeTopicPartitionsResponseCursor::new();
9028        cursor
9029            .set_topic_name(topic_name.to_string())
9030            .set_partition_index(partition_index);
9031        data.set_next_cursor(Some(cursor));
9032    }
9033
9034    fn describe_topic_partitions_resp(data: DescribeTopicPartitionsResponseData) -> ConcreteResponse {
9035        ConcreteResponse::DescribeTopicPartitions(DescribeTopicPartitionsResponse::new(data))
9036    }
9037
9038    /// The request data of a `DescribeTopicPartitions` request, or `None` for
9039    /// any other request (Java's `(DescribeTopicPartitionsRequestData) body.data()`
9040    /// cast, which a matcher only reaches for that request).
9041    fn describe_topic_partitions_data(request: &AbstractRequest) -> Option<&DescribeTopicPartitionsRequestData> {
9042        match request {
9043            AbstractRequest::DescribeTopicPartitions(r) => Some(r.data()),
9044            _ => None,
9045        }
9046    }
9047
9048    /// Java's `RequestMatcher` bodies in the `DescribeTopicPartitions` tests:
9049    /// the request names exactly `topics`, in order, and carries `cursor`.
9050    fn describe_topic_partitions_matcher(
9051        topics: &'static [&'static str],
9052        cursor: Option<(&'static str, i32)>,
9053    ) -> crate::RequestMatcher {
9054        Box::new(move |body: &AbstractRequest| {
9055            let Some(request) = describe_topic_partitions_data(body) else {
9056                return false;
9057            };
9058            let names: Vec<&str> = request.topics.iter().map(|t| t.name.as_str()).collect();
9059            if names != topics {
9060                return false;
9061            }
9062            match (&request.cursor, cursor) {
9063                (None, None) => true,
9064                (Some(c), Some((topic_name, partition_index))) => {
9065                    c.topic_name == topic_name && c.partition_index == partition_index
9066                },
9067                _ => false,
9068            }
9069        })
9070    }
9071
9072    /// `prepareDescribeClusterResponse(0, env.cluster().nodes(), clusterId, 2,
9073    /// authorizedOperations, false)`.
9074    fn prepare_describe_cluster(runnable: &mut AdminClientRunnable<MockClient>, nodes: &[Node], authorized_ops: i32) {
9075        runnable
9076            .client_mut()
9077            .prepare_response(describe_cluster_response(2, nodes, "mock-cluster", authorized_ops));
9078    }
9079
9080    /// Pumps until every future of `result` is done.
9081    async fn pump_until_described(runnable: &mut AdminClientRunnable<MockClient>, result: &DescribeTopicsResult) {
9082        let futures: Vec<KafkaFuture<TopicDescription>> =
9083            result.topic_name_values().unwrap().values().cloned().collect();
9084        pump_until(runnable, 40, |_| futures.iter().all(KafkaFuture::is_done)).await;
9085    }
9086
9087    /// Translated from
9088    /// `KafkaAdminClientTest.testDescribeTopicsWithDescribeTopicPartitionsApiBasic`.
9089    ///
9090    /// Beyond Java's assertions, it checks that the ELR / last-known-ELR ids
9091    /// resolve through the `describeCluster` node map, since that is what the
9092    /// Metadata API could never report.
9093    #[tokio::test]
9094    async fn test_describe_topics_with_describe_topic_partitions_api_basic() {
9095        let (admin, mut runnable, _time, nodes) = env();
9096        let topic_name0 = "test-0";
9097        let topic_name1 = "test-1";
9098        let topics: HashMap<&str, Uuid> =
9099            HashMap::from([(topic_name0, Uuid::random_uuid()), (topic_name1, Uuid::random_uuid())]);
9100
9101        prepare_describe_cluster(&mut runnable, &nodes, MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED);
9102
9103        let mut data_first_part = DescribeTopicPartitionsResponseData::new();
9104        add_partition_to_describe_topic_partitions_response(
9105            &mut data_first_part,
9106            topic_name0,
9107            topics[topic_name0],
9108            &[0],
9109        );
9110        set_next_cursor(&mut data_first_part, topic_name0, 1);
9111        runnable.client_mut().prepare_response_matcher(
9112            describe_topic_partitions_matcher(&["test-0", "test-1"], None),
9113            describe_topic_partitions_resp(data_first_part),
9114        );
9115
9116        let mut data_second_part = DescribeTopicPartitionsResponseData::new();
9117        add_partition_to_describe_topic_partitions_response(
9118            &mut data_second_part,
9119            topic_name0,
9120            topics[topic_name0],
9121            &[1],
9122        );
9123        add_partition_to_describe_topic_partitions_response(
9124            &mut data_second_part,
9125            topic_name1,
9126            topics[topic_name1],
9127            &[0],
9128        );
9129        runnable.client_mut().prepare_response_matcher(
9130            describe_topic_partitions_matcher(&["test-0", "test-1"], Some(("test-0", 1))),
9131            describe_topic_partitions_resp(data_second_part),
9132        );
9133
9134        let result = admin.describe_topics_with_topic_names_options(
9135            &[topic_name0.to_string(), topic_name1.to_string()],
9136            DescribeTopicsOptions::new(),
9137        );
9138        pump_until_described(&mut runnable, &result).await;
9139        let topic_descriptions = result.all_topic_names().unwrap().get().await.unwrap();
9140        assert_eq!(topic_descriptions.len(), 2);
9141        let topic_description = &topic_descriptions[topic_name0];
9142        assert_eq!(topic_description.partitions().len(), 2);
9143        assert_eq!(topic_description.partitions()[0].partition(), 0);
9144        assert_eq!(topic_description.partitions()[1].partition(), 1);
9145        assert_eq!(topic_description.topic_id(), topics[topic_name0]);
9146        let topic_description = &topic_descriptions[topic_name1];
9147        assert_eq!(topic_description.partitions().len(), 1);
9148        assert_eq!(topic_description.authorized_operations(), None);
9149
9150        let partition = &topic_description.partitions()[0];
9151        assert_eq!(partition.leader(), Some(&nodes[0]));
9152        assert_eq!(partition.replicas(), &nodes[..]);
9153        assert_eq!(partition.isr(), &nodes[..1]);
9154        assert_eq!(partition.elr(), Some(&nodes[1..2]));
9155        assert_eq!(partition.last_known_elr(), Some(&nodes[2..3]));
9156        // Both pages were served; nothing else was sent.
9157        assert!(!runnable.client_mut().has_pending_responses());
9158        assert_eq!(runnable.client_mut().request_count(), 0);
9159    }
9160
9161    /// Translated from `KafkaAdminClientTest.testDescribeTopicPartitionsApiWithAuthorizedOps`.
9162    #[tokio::test]
9163    async fn test_describe_topic_partitions_api_with_authorized_ops() {
9164        let (admin, mut runnable, _time, nodes) = env();
9165        let topic_name0 = "test-0";
9166        let topic_id = Uuid::random_uuid();
9167
9168        let authorised_operations =
9169            Utils::to_32_bit_field(&HashSet::from([AclOperation::Describe.code(), AclOperation::Alter.code()]));
9170        prepare_describe_cluster(&mut runnable, &nodes, authorised_operations);
9171
9172        let mut response_data = DescribeTopicPartitionsResponseData::new();
9173        let mut topic = DescribeTopicPartitionsResponseTopic::new();
9174        topic
9175            .set_error_code(0)
9176            .set_topic_id(topic_id)
9177            .set_name(Some(topic_name0.to_string()))
9178            .set_is_internal(false)
9179            .set_topic_authorized_operations(authorised_operations);
9180        response_data.topics.push(topic);
9181        runnable
9182            .client_mut()
9183            .prepare_response(describe_topic_partitions_resp(response_data));
9184
9185        let result = admin.describe_topics_with_topic_names_options(
9186            &[topic_name0.to_string()],
9187            DescribeTopicsOptions::new().set_include_authorized_operations(true),
9188        );
9189        pump_until_described(&mut runnable, &result).await;
9190        let topic_descriptions = result.all_topic_names().unwrap().get().await.unwrap();
9191        let topic_description = &topic_descriptions[topic_name0];
9192        assert_eq!(
9193            topic_description.authorized_operations(),
9194            Some(&BTreeSet::from([AclOperation::Describe, AclOperation::Alter]))
9195        );
9196    }
9197
9198    /// Translated from `KafkaAdminClientTest.testDescribeTopicPartitionsApiWithoutAuthorizedOps`.
9199    #[tokio::test]
9200    async fn test_describe_topic_partitions_api_without_authorized_ops() {
9201        let (admin, mut runnable, _time, nodes) = env();
9202        let topic_name0 = "test-0";
9203        let topic_id = Uuid::random_uuid();
9204
9205        let authorised_operations =
9206            Utils::to_32_bit_field(&HashSet::from([AclOperation::Describe.code(), AclOperation::Alter.code()]));
9207        prepare_describe_cluster(&mut runnable, &nodes, authorised_operations);
9208
9209        let mut response_data = DescribeTopicPartitionsResponseData::new();
9210        let mut topic = DescribeTopicPartitionsResponseTopic::new();
9211        topic
9212            .set_error_code(0)
9213            .set_topic_id(topic_id)
9214            .set_name(Some(topic_name0.to_string()))
9215            .set_is_internal(false)
9216            .set_topic_authorized_operations(authorised_operations);
9217        response_data.topics.push(topic);
9218        runnable
9219            .client_mut()
9220            .prepare_response(describe_topic_partitions_resp(response_data));
9221
9222        let result = admin.describe_topics_with_topic_names_options(
9223            &[topic_name0.to_string()],
9224            DescribeTopicsOptions::new().set_include_authorized_operations(false),
9225        );
9226        pump_until_described(&mut runnable, &result).await;
9227        let topic_descriptions = result.all_topic_names().unwrap().get().await.unwrap();
9228        assert_eq!(topic_descriptions[topic_name0].authorized_operations(), None);
9229    }
9230
9231    /// Translated from
9232    /// `KafkaAdminClientTest.testDescribeTopicsWithDescribeTopicPartitionsApiEdgeCase`:
9233    /// one page finishes the previous cursor topic and starts a new one, and the
9234    /// requested names are sent sorted.
9235    #[tokio::test]
9236    async fn test_describe_topics_with_describe_topic_partitions_api_edge_case() {
9237        let (admin, mut runnable, _time, nodes) = env();
9238        let topic_name0 = "test-0";
9239        let topic_name1 = "test-1";
9240        let topic_name2 = "test-2";
9241        let topics: HashMap<&str, Uuid> = HashMap::from([
9242            (topic_name0, Uuid::random_uuid()),
9243            (topic_name1, Uuid::random_uuid()),
9244            (topic_name2, Uuid::random_uuid()),
9245        ]);
9246
9247        prepare_describe_cluster(&mut runnable, &nodes, MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED);
9248
9249        let mut data_first_part = DescribeTopicPartitionsResponseData::new();
9250        add_partition_to_describe_topic_partitions_response(
9251            &mut data_first_part,
9252            topic_name0,
9253            topics[topic_name0],
9254            &[0],
9255        );
9256        add_partition_to_describe_topic_partitions_response(
9257            &mut data_first_part,
9258            topic_name1,
9259            topics[topic_name1],
9260            &[0],
9261        );
9262        set_next_cursor(&mut data_first_part, topic_name1, 1);
9263        runnable.client_mut().prepare_response_matcher(
9264            describe_topic_partitions_matcher(&["test-0", "test-1", "test-2"], None),
9265            describe_topic_partitions_resp(data_first_part),
9266        );
9267
9268        let mut data_second_part = DescribeTopicPartitionsResponseData::new();
9269        add_partition_to_describe_topic_partitions_response(
9270            &mut data_second_part,
9271            topic_name1,
9272            topics[topic_name1],
9273            &[1],
9274        );
9275        add_partition_to_describe_topic_partitions_response(
9276            &mut data_second_part,
9277            topic_name2,
9278            topics[topic_name2],
9279            &[0],
9280        );
9281        set_next_cursor(&mut data_second_part, topic_name2, 1);
9282        runnable.client_mut().prepare_response_matcher(
9283            describe_topic_partitions_matcher(&["test-1", "test-2"], Some(("test-1", 1))),
9284            describe_topic_partitions_resp(data_second_part),
9285        );
9286
9287        let mut data_third_part = DescribeTopicPartitionsResponseData::new();
9288        add_partition_to_describe_topic_partitions_response(
9289            &mut data_third_part,
9290            topic_name2,
9291            topics[topic_name2],
9292            &[1],
9293        );
9294        runnable.client_mut().prepare_response_matcher(
9295            describe_topic_partitions_matcher(&["test-2"], Some(("test-2", 1))),
9296            describe_topic_partitions_resp(data_third_part),
9297        );
9298
9299        let result = admin.describe_topics_with_topic_names_options(
9300            &[
9301                topic_name1.to_string(),
9302                topic_name0.to_string(),
9303                topic_name2.to_string(),
9304            ],
9305            DescribeTopicsOptions::new(),
9306        );
9307        pump_until_described(&mut runnable, &result).await;
9308        let topic_descriptions = result.all_topic_names().unwrap().get().await.unwrap();
9309        assert_eq!(topic_descriptions.len(), 3);
9310        let topic_description = &topic_descriptions[topic_name0];
9311        assert_eq!(topic_description.partitions().len(), 1);
9312        assert_eq!(topic_description.partitions()[0].partition(), 0);
9313        let topic_description = &topic_descriptions[topic_name1];
9314        assert_eq!(topic_description.partitions().len(), 2);
9315        let topic_description = &topic_descriptions[topic_name2];
9316        assert_eq!(topic_description.partitions().len(), 2);
9317        assert_eq!(topic_description.authorized_operations(), None);
9318        assert!(!runnable.client_mut().has_pending_responses());
9319    }
9320
9321    /// Translated from
9322    /// `KafkaAdminClientTest.testDescribeTopicsWithDescribeTopicPartitionsApiErrorHandling`:
9323    /// a topic error (29, `TOPIC_AUTHORIZATION_FAILED`) fails that topic, and so
9324    /// `allTopicNames()`.
9325    #[tokio::test]
9326    async fn test_describe_topics_with_describe_topic_partitions_api_error_handling() {
9327        let (admin, mut runnable, _time, nodes) = env();
9328        let topic_name0 = "test-0";
9329        let topic_name1 = "test-1";
9330        let topics: HashMap<&str, Uuid> =
9331            HashMap::from([(topic_name0, Uuid::random_uuid()), (topic_name1, Uuid::random_uuid())]);
9332
9333        prepare_describe_cluster(&mut runnable, &nodes, MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED);
9334
9335        let mut data_first_part = DescribeTopicPartitionsResponseData::new();
9336        add_partition_to_describe_topic_partitions_response(
9337            &mut data_first_part,
9338            topic_name0,
9339            topics[topic_name0],
9340            &[0],
9341        );
9342        let mut failed = DescribeTopicPartitionsResponseTopic::new();
9343        failed
9344            .set_error_code(29)
9345            .set_topic_id(Uuid::ZERO_UUID)
9346            .set_name(Some(topic_name1.to_string()))
9347            .set_is_internal(false);
9348        data_first_part.topics.push(failed);
9349        runnable.client_mut().prepare_response_matcher(
9350            describe_topic_partitions_matcher(&["test-0", "test-1"], None),
9351            describe_topic_partitions_resp(data_first_part),
9352        );
9353        let result = admin.describe_topics_with_topic_names_options(
9354            &[topic_name1.to_string(), topic_name0.to_string()],
9355            DescribeTopicsOptions::new(),
9356        );
9357        pump_until_described(&mut runnable, &result).await;
9358
9359        let error = result.all_topic_names().unwrap().get().await.unwrap_err();
9360        assert!(matches!(error, Error::TopicAuthorization(_)), "got {error:?}");
9361        assert_eq!(error.message(), Errors::TopicAuthorizationFailed.message());
9362        // The other topic completed normally, and no further page was requested.
9363        let described = result.topic_name_values().unwrap()[topic_name0].get().await.unwrap();
9364        assert_eq!(described.partitions().len(), 1);
9365        assert_eq!(runnable.client_mut().request_count(), 0);
9366    }
9367
9368    /// `partitionSizeLimitPerResponse` is the request's `ResponsePartitionLimit`
9369    /// on every page, and the cursor points at the next partition of the topic
9370    /// being paged through. Java's tests never set the option; this pins that it
9371    /// is read.
9372    #[tokio::test]
9373    async fn describe_topics_sends_the_partition_size_limit_on_every_page() {
9374        let (admin, mut runnable, _time, nodes) = env();
9375        let topic_id = Uuid::random_uuid();
9376        prepare_describe_cluster(&mut runnable, &nodes, MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED);
9377        for (page, cursor) in [(0, None), (1, Some(("big", 1))), (2, Some(("big", 2)))] {
9378            let mut data = DescribeTopicPartitionsResponseData::new();
9379            add_partition_to_describe_topic_partitions_response(&mut data, "big", topic_id, &[page]);
9380            if page < 2 {
9381                set_next_cursor(&mut data, "big", page + 1);
9382            }
9383            let matches_topics = describe_topic_partitions_matcher(&["big"], cursor);
9384            runnable.client_mut().prepare_response_matcher(
9385                Box::new(move |body: &AbstractRequest| {
9386                    matches_topics(body)
9387                        && describe_topic_partitions_data(body).is_some_and(|r| r.response_partition_limit == 1)
9388                }),
9389                describe_topic_partitions_resp(data),
9390            );
9391        }
9392
9393        let result = admin.describe_topics_with_topic_names_options(
9394            &["big".to_string()],
9395            DescribeTopicsOptions::new().set_partition_size_limit_per_response(1),
9396        );
9397        pump_until_described(&mut runnable, &result).await;
9398        let described = result.topic_name_values().unwrap()["big"].get().await.unwrap();
9399        let partitions: Vec<i32> = described.partitions().iter().map(TopicPartitionInfo::partition).collect();
9400        assert_eq!(partitions, vec![0, 1, 2]);
9401        assert!(!runnable.client_mut().has_pending_responses());
9402    }
9403
9404    /// On `UnsupportedVersionException` (a broker without KIP-966)
9405    /// `describeTopicPartitions` issues the Metadata-API `describeTopics` call
9406    /// and fails itself without failing the futures
9407    /// (`KafkaAdminClient#generateDescribeTopicsCallWithDescribeTopicPartitionsApi`).
9408    /// The Metadata call then completes them, including its own "not found" for
9409    /// a topic missing from the cluster.
9410    #[tokio::test]
9411    async fn describe_topics_falls_back_to_metadata_on_unsupported_version() {
9412        let (admin, mut runnable, _time, nodes) = env();
9413        prepare_describe_cluster(&mut runnable, &nodes, MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED);
9414        runnable.client_mut().prepare_unsupported_version_response();
9415        runnable.client_mut().prepare_response_matcher(
9416            Box::new(|body: &AbstractRequest| match body {
9417                AbstractRequest::Metadata(request) => {
9418                    let names: Vec<&str> = request
9419                        .data()
9420                        .topics
9421                        .iter()
9422                        .flatten()
9423                        .filter_map(|t| t.name.as_deref())
9424                        .collect();
9425                    names == ["myTopic", "nope"] && !request.data().allow_auto_topic_creation
9426                },
9427                _ => false,
9428            }),
9429            metadata_resp(&nodes, vec![topic_meta("myTopic", false, Uuid::new(0, 9), 2)]),
9430        );
9431
9432        let result = admin.describe_topics_with_topic_names_options(
9433            &["myTopic".to_string(), "nope".to_string()],
9434            DescribeTopicsOptions::new(),
9435        );
9436        pump_until_described(&mut runnable, &result).await;
9437        let my = result.topic_name_values().unwrap()["myTopic"].get().await.unwrap();
9438        assert_eq!(my.name(), "myTopic");
9439        assert_eq!(my.partitions().len(), 2);
9440        assert_eq!(my.topic_id(), Uuid::new(0, 9));
9441        // The Metadata API carries no ELR information.
9442        assert_eq!(my.partitions()[0].elr(), None);
9443        let err = result.topic_name_values().unwrap()["nope"].get().await.unwrap_err();
9444        assert_eq!(err.error(), Errors::UnknownTopicOrPartition);
9445        assert_eq!(err.message(), "Topic nope not found.");
9446        assert!(!runnable.client_mut().has_pending_responses());
9447    }
9448
9449    /// Regression for COMMENTS.66 Issue 6: an `UnsupportedVersionException` for
9450    /// `describeTopicPartitions` during the `close(timeout)` grace period.
9451    ///
9452    /// In Java `Call.fail` still reaches `handleUnsupportedVersionException` then
9453    /// (`runnable.closing` is only set once the I/O thread exits), which issues
9454    /// the Metadata fallback through `runnable.call`; `call()` rejects it because
9455    /// the hard-shutdown deadline is set, and every topic future fails with
9456    /// `IllegalStateException("Cannot accept new calls when AdminClient is closing.")`
9457    /// (`KafkaAdminClient.Call#fail`,
9458    /// `KafkaAdminClient#generateDescribeTopicsCallWithDescribeTopicPartitionsApi`,
9459    /// `KafkaAdminClient.AdminClientRunnable#call`). Rust's `fail_call` reaches
9460    /// the hook too, since `close()` only publishes the deadline and `closing` is
9461    /// set once the loop exits. Before that fix the code-35 error was swallowed
9462    /// and the futures never completed.
9463    #[tokio::test]
9464    async fn an_unsupported_version_during_close_fails_the_by_name_describe() {
9465        let (admin, mut runnable, _time, nodes) = env();
9466        prepare_describe_cluster(&mut runnable, &nodes, MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED);
9467        let result = admin.describe_topics_with_topic_names_options(&["t".to_string()], DescribeTopicsOptions::new());
9468        let future = result.topic_name_values().unwrap()["t"].clone();
9469        // describeCluster is answered, which queues describeTopicPartitions.
9470        pump_until(&mut runnable, 20, |r| !r.client_mut().has_pending_responses()).await;
9471        assert!(!future.is_done());
9472
9473        // `close(30s)` with describeTopicPartitions queued. No task was spawned,
9474        // so this only publishes the deadline.
9475        admin.close_with_timeout(Duration::from_secs(30)).await;
9476        // The broker does not support DescribeTopicPartitions.
9477        runnable.client_mut().prepare_unsupported_version_response();
9478        pump(&mut runnable, 10).await;
9479        assert!(
9480            !runnable.client_mut().has_pending_responses(),
9481            "the UnsupportedVersion response was consumed"
9482        );
9483
9484        let error = tokio::time::timeout(Duration::from_secs(1), future.get())
9485            .await
9486            .expect("the topic future must complete, not hang")
9487            .expect_err("the rejected fallback fails the topic");
9488        assert!(matches!(error, Error::LocalIllegalState(_)), "got {error:?}");
9489        assert_eq!(error.message(), "Cannot accept new calls when AdminClient is closing.");
9490        assert!(!runnable.has_active_external_calls_for_test());
9491        assert_eq!(runnable.client_mut().request_count(), 0, "no Metadata fallback was sent");
9492    }
9493
9494    /// A failed `describeCluster` fails every topic future with its error
9495    /// (`completeAllExceptionally(topicFutures.values(), exception)`), and no
9496    /// `DescribeTopicPartitions` request is sent.
9497    #[tokio::test]
9498    async fn describe_topics_fails_every_topic_when_describe_cluster_fails() {
9499        let (admin, mut runnable, _time, _nodes) = env();
9500        let mut data = DescribeClusterResponseData::new();
9501        data.set_error_code(Errors::ClusterAuthorizationFailed.code());
9502        data.set_error_message(Some("not allowed".to_string()));
9503        runnable
9504            .client_mut()
9505            .prepare_response(ConcreteResponse::DescribeCluster(DescribeClusterResponse::new(data)));
9506
9507        let result = admin.describe_topics_with_topic_names_options(
9508            &["a".to_string(), "b".to_string()],
9509            DescribeTopicsOptions::new(),
9510        );
9511        pump_until_described(&mut runnable, &result).await;
9512        for name in ["a", "b"] {
9513            let err = result.topic_name_values().unwrap()[name].get().await.unwrap_err();
9514            assert_eq!(err.error(), Errors::ClusterAuthorizationFailed, "{name}");
9515            assert_eq!(err.message(), "not allowed", "{name}");
9516        }
9517        pump(&mut runnable, 3).await;
9518        assert_eq!(runnable.client_mut().request_count(), 0);
9519    }
9520
9521    /// Translated from `KafkaAdminClientTest.testDescribeTopicsTimeoutWhenNoBrokerResponds`:
9522    /// with no response, the topic future fails with a `TimeoutException` once
9523    /// the 200 ms `timeoutMs` passes. What times out is the `describeCluster`
9524    /// call (Java's `"listNodes"`), whose deadline is derived from the same
9525    /// option, so its name is in the message.
9526    #[tokio::test]
9527    async fn test_describe_topics_timeout_when_no_broker_responds() {
9528        let (admin, mut runnable, time, _nodes) =
9529            env_nodes_with_props(1, &[("retries", "0"), ("request.timeout.ms", "30000")]);
9530        let start = time.milliseconds();
9531        let result = admin.describe_topics_with_topic_names_options(
9532            &["test-topic".to_string()],
9533            DescribeTopicsOptions::new().set_timeout_ms(Some(200)),
9534        );
9535        let topic_description = result.topic_name_values().unwrap()["test-topic"].clone();
9536        pump_until_request_queued(&mut runnable).await;
9537        time.sleep(201);
9538        pump_until(&mut runnable, 20, |_| topic_description.is_done()).await;
9539        let error = topic_description.get().await.unwrap_err();
9540        assert!(matches!(error, Error::Timeout(_)), "got {error:?}");
9541        let now = time.milliseconds();
9542        assert!(now - start >= 150, "the timeout fired at {}", now - start);
9543        assert!(
9544            error.message().starts_with(&format!(
9545                "Call(callName=listNodes, deadlineMs={}, tries=1, nextAllowedTryMs=",
9546                start + 200
9547            )),
9548            "{}",
9549            error.message()
9550        );
9551        assert!(
9552            error.message().ends_with(&format!(") timed out at {now} after 1 attempt(s)")),
9553            "{}",
9554            error.message()
9555        );
9556    }
9557
9558    /// The `describeTopicPartitions` call's own timeout names it, as Java's
9559    /// `Call("describeTopicPartitions", ..)` does. The Metadata-API path used to
9560    /// answer by name, so its timeouts said `describeTopics`.
9561    #[tokio::test]
9562    async fn describe_topic_partitions_timeout_names_the_call() {
9563        let (admin, mut runnable, time, nodes) =
9564            env_nodes_with_props(1, &[("retries", "0"), ("request.timeout.ms", "30000")]);
9565        prepare_describe_cluster(&mut runnable, &nodes, MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED);
9566        let result = admin.describe_topics_with_topic_names_options(
9567            &["test-topic".to_string()],
9568            DescribeTopicsOptions::new().set_timeout_ms(Some(200)),
9569        );
9570        let topic_description = result.topic_name_values().unwrap()["test-topic"].clone();
9571        // describeCluster is answered; describeTopicPartitions is left in flight.
9572        pump_until(&mut runnable, 20, |r| {
9573            r.client_mut()
9574                .requests()
9575                .iter()
9576                .any(|request| request.api_key() == &ApiKeys::DESCRIBE_TOPIC_PARTITIONS)
9577        })
9578        .await;
9579        time.sleep(201);
9580        pump_until(&mut runnable, 20, |_| topic_description.is_done()).await;
9581        let error = topic_description.get().await.unwrap_err();
9582        assert!(matches!(error, Error::Timeout(_)), "got {error:?}");
9583        assert!(
9584            error.message().starts_with("Call(callName=describeTopicPartitions, "),
9585            "{}",
9586            error.message()
9587        );
9588        let now = time.milliseconds();
9589        assert!(
9590            error.message().ends_with(&format!(") timed out at {now} after 1 attempt(s)")),
9591            "{}",
9592            error.message()
9593        );
9594    }
9595
9596    /// `testInvalidTopicNames`' describe half: names that cannot be represented
9597    /// fail at once with Java's message, and no request — not even the
9598    /// `describeCluster` prerequisite — is sent.
9599    #[tokio::test]
9600    async fn describe_topics_with_only_invalid_names_sends_nothing() {
9601        let (admin, mut runnable, _time, _nodes) = env();
9602        let result = admin.describe_topics_with_topic_names_options(&[String::new()], DescribeTopicsOptions::new());
9603        let err = result.topic_name_values().unwrap()[""].get().await.unwrap_err();
9604        assert_eq!(err.error(), Errors::InvalidTopicError);
9605        assert_eq!(err.message(), "The given topic name '' cannot be represented in a request.");
9606        pump(&mut runnable, 3).await;
9607        assert_eq!(runnable.client_mut().request_count(), 0);
9608    }
9609
9610    #[tokio::test]
9611    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDescribeTopicsByIds")]
9612    async fn test_describe_topics_by_ids() {
9613        // Valid id: the metadata response carries the topic, so it is described.
9614        let (admin, mut runnable, _time, nodes) = env();
9615        let topic_id = Uuid::new(7, 7);
9616        let topics = vec![topic_meta("test-topic", false, topic_id, 1)];
9617        runnable
9618            .client_mut()
9619            .prepare_response(ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
9620                &nodes,
9621                Some("mock-cluster"),
9622                0,
9623                topics,
9624            )));
9625        let result = admin.describe_topics_with_topics_options(
9626            TopicCollection::of_topic_ids(vec![topic_id]),
9627            DescribeTopicsOptions::new(),
9628        );
9629        pump(&mut runnable, 5).await;
9630        let all = result.all_topic_ids().unwrap().get().await.unwrap();
9631        assert_eq!(all[&topic_id].name(), "test-topic");
9632
9633        // Id not present in the brokers: UnknownTopicId with the Java message.
9634        let (admin, mut runnable, _time, nodes) = env();
9635        let non_exist = Uuid::new(9, 9);
9636        runnable
9637            .client_mut()
9638            .prepare_response(ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
9639                &nodes,
9640                Some("mock-cluster"),
9641                0,
9642                Vec::new(),
9643            )));
9644        let result = admin.describe_topics_with_topics_options(
9645            TopicCollection::of_topic_ids(vec![non_exist]),
9646            DescribeTopicsOptions::new(),
9647        );
9648        pump(&mut runnable, 5).await;
9649        let err = result.all_topic_ids().unwrap().get().await.unwrap_err();
9650        assert_eq!(err.error(), Errors::UnknownTopicId);
9651        assert_eq!(err.message(), format!("TopicId {non_exist} not found."));
9652
9653        // The zero id cannot be represented in a request; no request is sent.
9654        let (admin, _runnable, _time, _nodes) = env();
9655        let result = admin.describe_topics_with_topics_options(
9656            TopicCollection::of_topic_ids(vec![Uuid::ZERO_UUID]),
9657            DescribeTopicsOptions::new(),
9658        );
9659        let err = result.all_topic_ids().unwrap().get().await.unwrap_err();
9660        assert_eq!(err.error(), Errors::InvalidTopicError);
9661        assert_eq!(
9662            err.message(),
9663            "The given topic id 'AAAAAAAAAAAAAAAAAAAAAA' cannot be represented in a request."
9664        );
9665    }
9666
9667    /// A zero topic id in a by-id Metadata response fails
9668    /// only that call.
9669    ///
9670    /// A 4.x broker returns the zero id for a topic deleted while a by-id
9671    /// `describeTopics` is being answered: it resolves the id to a name, then
9672    /// finds the topic gone and builds the entry with
9673    /// `metadataCache.getTopicId(topic)` (`KafkaApis.scala:875-880`), which is
9674    /// now the zero id. Java's `MetadataResponse#errorsByTopicId` throws
9675    /// `IllegalStateException("Use errors() when managing topic using topic name")`,
9676    /// and `KafkaAdminClient.AdminClientRunnable#handleResponses` catches it
9677    /// with `call.fail(now, t)`. The error is not retriable, so only that call
9678    /// fails and the client goes on. Rust used to `assert!`, which ended the
9679    /// whole I/O task: the call never resolved, and every later call was
9680    /// rejected.
9681    #[tokio::test]
9682    async fn a_zero_topic_id_in_a_by_id_describe_fails_only_that_call() {
9683        let (admin, mut runnable, _time, nodes) = env();
9684        let requested = Uuid::new(7, 7);
9685        // The topic was deleted mid-request: the broker reports it under its
9686        // name with the zero id and an error.
9687        let mut deleted = topic_meta("deleted-topic", false, Uuid::ZERO_UUID, 0);
9688        deleted.error = Errors::UnknownTopicOrPartition;
9689        runnable.client_mut().prepare_response(metadata_resp(&nodes, vec![deleted]));
9690
9691        let result = admin.describe_topics_with_topics_options(
9692            TopicCollection::of_topic_ids(vec![requested]),
9693            DescribeTopicsOptions::new(),
9694        );
9695        let future = result.topic_id_values().unwrap()[&requested].clone();
9696        pump_until(&mut runnable, 20, |_| future.is_done()).await;
9697        let error = future.get().await.expect_err("the zero topic id must fail the call");
9698        assert!(matches!(error, Error::LocalIllegalState(_)), "got {error:?}");
9699        assert_eq!(error.message(), "Use errors() when managing topic using topic name");
9700
9701        // The client is still usable: an unrelated call on the same runnable
9702        // succeeds.
9703        runnable
9704            .client_mut()
9705            .prepare_response(metadata_resp(&nodes, vec![topic_meta("other", false, Uuid::new(8, 8), 1)]));
9706        let names = admin.list_topics_with_options(ListTopicsOptions::new()).names();
9707        pump_until(&mut runnable, 20, |_| names.is_done()).await;
9708        let names = names.get().await.expect("a later listTopics must succeed");
9709        assert_eq!(names, HashSet::from(["other".to_string()]));
9710    }
9711
9712    #[tokio::test]
9713    async fn test_create_topics_response_config_metadata() {
9714        use crate::create_topics_response_data::CreatableTopicConfigs;
9715        let (admin, mut runnable, _time, _nodes) = env();
9716        let result = admin.create_topics_with_options(
9717            &[NewTopic::with_num_partitions_replication_factor(
9718                "myTopic",
9719                Some(1),
9720                Some(1),
9721            )],
9722            CreateTopicsOptions::new().set_validate_only(true),
9723        );
9724        let mut config = CreatableTopicConfigs::new();
9725        config.set_name("cleanup.policy".to_string());
9726        config.set_value(Some("compact".to_string()));
9727        config.set_read_only(true);
9728        config.set_is_sensitive(false);
9729        config.set_config_source(1); // DYNAMIC_TOPIC_CONFIG
9730        let mut r = create_result("myTopic", Errors::None, None);
9731        r.set_configs(Some(vec![config]));
9732        runnable.client_mut().prepare_response(create_response(vec![r]));
9733        pump(&mut runnable, 5).await;
9734        let cfg = result.config("myTopic").get().await.unwrap();
9735        let entry = cfg.get("cleanup.policy").expect("cleanup.policy present");
9736        assert_eq!(entry.value(), Some("compact"));
9737        assert!(entry.is_read_only());
9738        assert!(!entry.is_sensitive());
9739        assert_eq!(entry.source(), ConfigSource::DynamicTopicConfig);
9740        // Java builds the entry with a `null` type and documentation
9741        // (the `configEntry` helper of `KafkaAdminClient#getCreateTopicsCall`), and prints them as `null`.
9742        assert_eq!(entry.r#type(), None);
9743        assert_eq!(entry.documentation(), None);
9744        assert!(entry.synonyms().is_empty());
9745        assert_eq!(
9746            entry.to_string(),
9747            "ConfigEntry(name=cleanup.policy, value=compact, source=DYNAMIC_TOPIC_CONFIG, \
9748             isSensitive=false, isReadOnly=true, synonyms=[], type=null, documentation=null)"
9749        );
9750    }
9751
9752    #[tokio::test]
9753    async fn test_create_topics_invalid_name_unrepresentable() {
9754        let (admin, _runnable, _time, _nodes) = env();
9755        let result = admin.create_topics_with_options(
9756            &[NewTopic::with_num_partitions_replication_factor("", Some(1), Some(1))],
9757            CreateTopicsOptions::new(),
9758        );
9759        let err = result.values()[""].get().await.unwrap_err();
9760        assert_eq!(err.error(), Errors::InvalidTopicError);
9761        assert_eq!(err.message(), "The given topic name '' cannot be represented in a request.");
9762    }
9763
9764    #[tokio::test]
9765    async fn test_delete_topics_invalid_name_unrepresentable() {
9766        let (admin, _runnable, _time, _nodes) = env();
9767        let result = admin.delete_topics_with_topic_collection_options(
9768            TopicCollection::of_topic_names(vec![String::new()]),
9769            DeleteTopicsOptions::new(),
9770        );
9771        let err = result.topic_name_values().unwrap()[""].get().await.unwrap_err();
9772        assert_eq!(err.error(), Errors::InvalidTopicError);
9773        assert_eq!(err.message(), "The given topic name '' cannot be represented in a request.");
9774    }
9775
9776    // --- createPartitions ----------------------------------------------------
9777
9778    fn create_partitions_result_item(name: &str, error: Errors, msg: Option<&str>) -> CreatePartitionsTopicResult {
9779        let mut r = CreatePartitionsTopicResult::new();
9780        r.set_name(name.to_string());
9781        r.set_error_code(error.code());
9782        r.set_error_message(msg.map(str::to_string));
9783        r
9784    }
9785
9786    fn create_partitions_response(throttle_ms: i32, results: Vec<CreatePartitionsTopicResult>) -> ConcreteResponse {
9787        let mut data = CreatePartitionsResponseData::new();
9788        data.set_throttle_time_ms(throttle_ms);
9789        data.set_results(results);
9790        ConcreteResponse::CreatePartitions(CreatePartitionsResponse::new(data))
9791    }
9792
9793    fn new_partitions_counts() -> HashMap<String, NewPartitions> {
9794        let mut counts = HashMap::new();
9795        counts.insert("my_topic".to_string(), NewPartitions::increase_to(3));
9796        counts.insert(
9797            "other_topic".to_string(),
9798            NewPartitions::increase_to_with_new_assignments(3, vec![vec![2], vec![3]]),
9799        );
9800        counts
9801    }
9802
9803    /// Mirrors `KafkaAdminClientTest.testCreatePartitions`.
9804    #[tokio::test]
9805    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testCreatePartitions")]
9806    async fn test_create_partitions() {
9807        let (admin, mut runnable, _time, _nodes) = env();
9808        let result = admin.create_partitions_with_options(&new_partitions_counts(), CreatePartitionsOptions::new());
9809        runnable.client_mut().prepare_response(create_partitions_response(
9810            1000,
9811            vec![
9812                create_partitions_result_item("my_topic", Errors::None, None),
9813                create_partitions_result_item("other_topic", Errors::InvalidTopicError, Some("some detailed reason")),
9814            ],
9815        ));
9816        pump(&mut runnable, 5).await;
9817        result.values()["my_topic"].get().await.unwrap();
9818        let err = result.values()["other_topic"].get().await.unwrap_err();
9819        assert_eq!(err.error(), Errors::InvalidTopicError);
9820        assert_eq!(err.message(), "some detailed reason");
9821    }
9822
9823    /// Mirrors `KafkaAdminClientTest.testCreatePartitionsRetryThrottlingExceptionWhenEnabled`.
9824    #[tokio::test]
9825    #[doc(
9826        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testCreatePartitionsRetryThrottlingExceptionWhenEnabled"
9827    )]
9828    async fn test_create_partitions_retry_throttling_error_when_enabled() {
9829        let (admin, mut runnable, _time, _nodes) = env();
9830        runnable.client_mut().prepare_response(create_partitions_response(
9831            1000,
9832            vec![
9833                create_partitions_result_item("topic1", Errors::None, None),
9834                create_partitions_result_item("topic2", Errors::ThrottlingQuotaExceeded, None),
9835                create_partitions_result_item("topic3", Errors::TopicAlreadyExists, None),
9836            ],
9837        ));
9838        runnable.client_mut().prepare_response(create_partitions_response(
9839            1000,
9840            vec![create_partitions_result_item(
9841                "topic2",
9842                Errors::ThrottlingQuotaExceeded,
9843                None,
9844            )],
9845        ));
9846        runnable.client_mut().prepare_response(create_partitions_response(
9847            0,
9848            vec![create_partitions_result_item("topic2", Errors::None, None)],
9849        ));
9850
9851        let mut counts = HashMap::new();
9852        counts.insert("topic1".to_string(), NewPartitions::increase_to(1));
9853        counts.insert("topic2".to_string(), NewPartitions::increase_to(2));
9854        counts.insert("topic3".to_string(), NewPartitions::increase_to(3));
9855        let result = admin
9856            .create_partitions_with_options(&counts, CreatePartitionsOptions::new().set_retry_on_quota_violation(true));
9857
9858        pump_until(&mut runnable, 30, |r| r.client_mut().num_awaiting_responses() == 0).await;
9859        result.values()["topic1"].get().await.unwrap();
9860        result.values()["topic2"].get().await.unwrap();
9861        let err = result.values()["topic3"].get().await.unwrap_err();
9862        assert_eq!(err.error(), Errors::TopicAlreadyExists);
9863    }
9864
9865    /// Mirrors `KafkaAdminClientTest.testCreatePartitionsDontRetryThrottlingExceptionWhenDisabled`.
9866    #[tokio::test]
9867    #[doc(
9868        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testCreatePartitionsDontRetryThrottlingExceptionWhenDisabled"
9869    )]
9870    async fn test_create_partitions_dont_retry_throttling_error_when_disabled() {
9871        let (admin, mut runnable, _time, _nodes) = env();
9872        runnable.client_mut().prepare_response(create_partitions_response(
9873            1000,
9874            vec![
9875                create_partitions_result_item("topic1", Errors::None, None),
9876                create_partitions_result_item("topic2", Errors::ThrottlingQuotaExceeded, None),
9877                create_partitions_result_item("topic3", Errors::TopicAlreadyExists, None),
9878            ],
9879        ));
9880        let mut counts = HashMap::new();
9881        counts.insert("topic1".to_string(), NewPartitions::increase_to(1));
9882        counts.insert("topic2".to_string(), NewPartitions::increase_to(2));
9883        counts.insert("topic3".to_string(), NewPartitions::increase_to(3));
9884        let result = admin.create_partitions_with_options(
9885            &counts,
9886            CreatePartitionsOptions::new().set_retry_on_quota_violation(false),
9887        );
9888
9889        pump(&mut runnable, 5).await;
9890        result.values()["topic1"].get().await.unwrap();
9891        let err = result.values()["topic2"].get().await.unwrap_err();
9892        assert_eq!(err.error(), Errors::ThrottlingQuotaExceeded);
9893        assert_eq!(err.throttle_time_ms(), Some(1000));
9894        let err3 = result.values()["topic3"].get().await.unwrap_err();
9895        assert_eq!(err3.error(), Errors::TopicAlreadyExists);
9896    }
9897
9898    /// Mirrors `KafkaAdminClientTest.testCreatePartitionsRetryThrottlingExceptionWhenEnabledUntilRequestTimeOut`.
9899    #[tokio::test]
9900    async fn test_create_partitions_retry_throttling_error_when_enabled_until_request_timeout() {
9901        let default_api_timeout: i64 = 60000;
9902        let (admin, mut runnable, time, _nodes) =
9903            env_with_props(&[("default.api.timeout.ms", &default_api_timeout.to_string())]);
9904        runnable.client_mut().prepare_response(create_partitions_response(
9905            1000,
9906            vec![
9907                create_partitions_result_item("topic1", Errors::None, None),
9908                create_partitions_result_item("topic2", Errors::ThrottlingQuotaExceeded, None),
9909                create_partitions_result_item("topic3", Errors::TopicAlreadyExists, None),
9910            ],
9911        ));
9912        runnable.client_mut().prepare_response(create_partitions_response(
9913            1000,
9914            vec![create_partitions_result_item(
9915                "topic2",
9916                Errors::ThrottlingQuotaExceeded,
9917                None,
9918            )],
9919        ));
9920        let mut counts = HashMap::new();
9921        counts.insert("topic1".to_string(), NewPartitions::increase_to(1));
9922        counts.insert("topic2".to_string(), NewPartitions::increase_to(2));
9923        counts.insert("topic3".to_string(), NewPartitions::increase_to(3));
9924        let result = admin
9925            .create_partitions_with_options(&counts, CreatePartitionsOptions::new().set_retry_on_quota_violation(true));
9926
9927        pump_until(&mut runnable, 30, |r| {
9928            !r.client_mut().has_pending_responses() && r.client_mut().request_count() >= 1
9929        })
9930        .await;
9931        time.sleep(default_api_timeout + 1);
9932        pump_until(&mut runnable, 30, |_r| result.values()["topic2"].is_done()).await;
9933        result.values()["topic1"].get().await.unwrap();
9934        let err = result.values()["topic2"].get().await.unwrap_err();
9935        assert_eq!(err.error(), Errors::ThrottlingQuotaExceeded);
9936        assert_eq!(err.throttle_time_ms(), Some(0));
9937        let err3 = result.values()["topic3"].get().await.unwrap_err();
9938        assert_eq!(err3.error(), Errors::TopicAlreadyExists);
9939    }
9940
9941    // --- deleteRecords -------------------------------------------------------
9942
9943    fn topic_meta_error(name: &str, error: Errors) -> TopicMetadata {
9944        TopicMetadata {
9945            error,
9946            topic: name.to_string(),
9947            topic_id: Uuid::ZERO_UUID,
9948            is_internal: false,
9949            partition_metadata: Vec::new(),
9950            authorized_operations: MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED,
9951        }
9952    }
9953
9954    fn topic_meta_leaders(name: &str, leaders: &[(i32, i32)]) -> TopicMetadata {
9955        let partition_metadata = leaders
9956            .iter()
9957            .map(|(partition, leader)| PartitionMetadata {
9958                error: Errors::None,
9959                topic_partition: TopicPartition::new(name.to_string(), *partition),
9960                leader_id: Some(*leader),
9961                leader_epoch: Some(0),
9962                replica_ids: vec![*leader],
9963                in_sync_replica_ids: vec![*leader],
9964                offline_replica_ids: vec![],
9965            })
9966            .collect();
9967        TopicMetadata {
9968            error: Errors::None,
9969            topic: name.to_string(),
9970            topic_id: Uuid::ZERO_UUID,
9971            is_internal: false,
9972            partition_metadata,
9973            authorized_operations: MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED,
9974        }
9975    }
9976
9977    fn metadata_resp(nodes: &[Node], topics: Vec<TopicMetadata>) -> ConcreteResponse {
9978        ConcreteResponse::Metadata(RequestTestUtils::metadata_response(nodes, Some("mock-cluster"), 0, topics))
9979    }
9980
9981    fn delete_records_partition(index: i32, error: Errors, low_watermark: i64) -> DeleteRecordsPartitionResult {
9982        let mut p = DeleteRecordsPartitionResult::new();
9983        p.set_partition_index(index);
9984        p.set_error_code(error.code());
9985        p.set_low_watermark(low_watermark);
9986        p
9987    }
9988
9989    fn delete_records_resp(topic: &str, partitions: Vec<DeleteRecordsPartitionResult>) -> ConcreteResponse {
9990        let mut topic_result = DeleteRecordsTopicResult::new();
9991        topic_result.set_name(topic.to_string());
9992        topic_result.set_partitions(partitions);
9993        let mut data = DeleteRecordsResponseData::new();
9994        data.set_topics(vec![topic_result]);
9995        ConcreteResponse::DeleteRecords(DeleteRecordsResponse::new(data))
9996    }
9997
9998    /// Mirrors `KafkaAdminClientTest.testDeleteRecords`: two retriable metadata
9999    /// lookups precede a successful one, then a fulfillment response carries a
10000    /// success, an offset-out-of-range error, an authorization failure, and a
10001    /// missing partition (sanity-check failure).
10002    #[tokio::test]
10003    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDeleteRecords")]
10004    async fn test_delete_records() {
10005        let (admin, mut runnable, _time, nodes) = env();
10006        // Lookup retries: LEADER_NOT_AVAILABLE, then UNKNOWN_TOPIC_OR_PARTITION
10007        // (tolerated), then success mapping all partitions to node0.
10008        runnable.client_mut().prepare_response(metadata_resp(
10009            &nodes,
10010            vec![topic_meta_error("my_topic", Errors::LeaderNotAvailable)],
10011        ));
10012        runnable.client_mut().prepare_response(metadata_resp(
10013            &nodes,
10014            vec![topic_meta_error("my_topic", Errors::UnknownTopicOrPartition)],
10015        ));
10016        runnable.client_mut().prepare_response(metadata_resp(
10017            &nodes,
10018            vec![topic_meta_leaders("my_topic", &[(0, 0), (1, 0), (2, 0), (3, 0)])],
10019        ));
10020        runnable.client_mut().prepare_response(delete_records_resp(
10021            "my_topic",
10022            vec![
10023                delete_records_partition(0, Errors::None, 3),
10024                delete_records_partition(1, Errors::OffsetOutOfRange, -1),
10025                delete_records_partition(2, Errors::TopicAuthorizationFailed, -1),
10026                // partition 3 omitted → sanity-check failure
10027            ],
10028        ));
10029
10030        let mut records = HashMap::new();
10031        records.insert(TopicPartition::new("my_topic", 0), RecordsToDelete::with_offset(3));
10032        records.insert(TopicPartition::new("my_topic", 1), RecordsToDelete::with_offset(10));
10033        records.insert(TopicPartition::new("my_topic", 2), RecordsToDelete::with_offset(10));
10034        records.insert(TopicPartition::new("my_topic", 3), RecordsToDelete::with_offset(10));
10035        let result = admin.delete_records_with_options(&records, DeleteRecordsOptions::new());
10036
10037        let values = result.low_watermarks();
10038        pump_until(&mut runnable, 40, |_r| values.values().all(|f| f.is_done())).await;
10039
10040        assert_eq!(
10041            values[&TopicPartition::new("my_topic", 0)].get().await.unwrap().low_watermark(),
10042            3
10043        );
10044        assert_eq!(
10045            values[&TopicPartition::new("my_topic", 1)].get().await.unwrap_err().error(),
10046            Errors::OffsetOutOfRange
10047        );
10048        assert_eq!(
10049            values[&TopicPartition::new("my_topic", 2)].get().await.unwrap_err().error(),
10050            Errors::TopicAuthorizationFailed
10051        );
10052        let p3_err = values[&TopicPartition::new("my_topic", 3)].get().await.unwrap_err();
10053        assert!(p3_err.message().contains("did not contain a result for topic partition"));
10054    }
10055
10056    /// Mirrors `KafkaAdminClientTest.testDeleteRecordsTopicAuthorizationError`: a
10057    /// topic-level authorization failure during lookup fails the partition.
10058    #[tokio::test]
10059    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDeleteRecordsTopicAuthorizationError")]
10060    async fn test_delete_records_topic_authorization_error() {
10061        let (admin, mut runnable, _time, nodes) = env();
10062        runnable.client_mut().prepare_response(metadata_resp(
10063            &nodes,
10064            vec![topic_meta_error("foo", Errors::TopicAuthorizationFailed)],
10065        ));
10066
10067        let mut records = HashMap::new();
10068        records.insert(TopicPartition::new("foo", 0), RecordsToDelete::with_offset(10));
10069        let result = admin.delete_records_with_options(&records, DeleteRecordsOptions::new());
10070
10071        let values = result.low_watermarks();
10072        pump_until(&mut runnable, 20, |_r| values.values().all(|f| f.is_done())).await;
10073        let err = values[&TopicPartition::new("foo", 0)].get().await.unwrap_err();
10074        assert_eq!(err.error(), Errors::TopicAuthorizationFailed);
10075    }
10076
10077    /// Mirrors `KafkaAdminClientTest.testDeleteRecordsMultipleSends`: partitions
10078    /// spread across two leaders produce two fulfillment requests, and each
10079    /// broker's result completes independently.
10080    ///
10081    /// Deviation: Java fails one broker with a pending `SaslAuthenticationException`
10082    /// (a connection-level failure). `MockClient` cannot simulate a pending
10083    /// authentication error (its `authentication_error` always returns `None`),
10084    /// so this port substitutes a per-partition fatal error on the second broker
10085    /// to exercise the same multi-broker fan-out and independent completion.
10086    #[tokio::test]
10087    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDeleteRecordsMultipleSends")]
10088    async fn test_delete_records_multiple_sends() {
10089        let (admin, mut runnable, _time, nodes) = env();
10090        // tp0 -> node0, tp1 -> node1.
10091        runnable
10092            .client_mut()
10093            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 0), (1, 1)])]));
10094        runnable.client_mut().prepare_response_from(
10095            delete_records_resp("foo", vec![delete_records_partition(0, Errors::None, 3)]),
10096            &nodes[0],
10097        );
10098        runnable.client_mut().prepare_response_from(
10099            delete_records_resp("foo", vec![delete_records_partition(1, Errors::TopicAuthorizationFailed, -1)]),
10100            &nodes[1],
10101        );
10102
10103        let mut records = HashMap::new();
10104        records.insert(TopicPartition::new("foo", 0), RecordsToDelete::with_offset(10));
10105        records.insert(TopicPartition::new("foo", 1), RecordsToDelete::with_offset(10));
10106        let result = admin.delete_records_with_options(&records, DeleteRecordsOptions::new());
10107
10108        let values = result.low_watermarks();
10109        pump_until(&mut runnable, 40, |_r| values.values().all(|f| f.is_done())).await;
10110        assert_eq!(values[&TopicPartition::new("foo", 0)].get().await.unwrap().low_watermark(), 3);
10111        assert_eq!(
10112            values[&TopicPartition::new("foo", 1)].get().await.unwrap_err().error(),
10113            Errors::TopicAuthorizationFailed
10114        );
10115    }
10116
10117    /// The mock's `delete_records` returns an empty result for an empty request.
10118    #[tokio::test]
10119    async fn test_mock_delete_records_empty() {
10120        let mock = mock_admin_client::Builder::new()
10121            .build()
10122            .expect("a fresh builder has one broker");
10123        let result = mock.delete_records_with_options(&HashMap::new(), DeleteRecordsOptions::new());
10124        assert!(result.low_watermarks().is_empty());
10125    }
10126
10127    // --- describeProducers / abortTransaction --------------------------------
10128
10129    use crate::DescribeProducersResponseData;
10130    use crate::WriteTxnMarkersResponseData;
10131    use crate::admin::ProducerState;
10132    use crate::admin::{AbortTransactionOptions, AbortTransactionSpec, DescribeProducersOptions};
10133    use crate::common::requests::{DescribeProducersResponse, WriteTxnMarkersResponse};
10134    use crate::describe_producers_response_data::{
10135        PartitionResponse as DpPartitionResponse, ProducerState as WireProducerState, TopicResponse as DpTopicResponse,
10136    };
10137    use crate::write_txn_markers_response_data::{
10138        WritableTxnMarkerPartitionResult, WritableTxnMarkerResult, WritableTxnMarkerTopicResult,
10139    };
10140
10141    /// Mirrors `KafkaAdminClientTest.buildDescribeProducersResponse`.
10142    fn build_describe_producers_response(tp: &TopicPartition, states: &[ProducerState]) -> ConcreteResponse {
10143        let wire: Vec<WireProducerState> = states
10144            .iter()
10145            .map(|s| {
10146                let mut w = WireProducerState::new();
10147                w.set_producer_id(s.producer_id());
10148                w.set_producer_epoch(s.producer_epoch());
10149                w.set_last_sequence(s.last_sequence());
10150                w.set_last_timestamp(s.last_timestamp());
10151                w.set_coordinator_epoch(s.coordinator_epoch().unwrap_or(-1));
10152                w.set_current_txn_start_offset(s.current_transaction_start_offset().unwrap_or(-1));
10153                w
10154            })
10155            .collect();
10156        let mut partition_response = DpPartitionResponse::new();
10157        partition_response.set_partition_index(tp.partition());
10158        partition_response.set_error_code(Errors::None.code());
10159        partition_response.set_active_producers(wire);
10160        let mut topic_response = DpTopicResponse::new();
10161        topic_response.set_name(tp.topic().to_string());
10162        topic_response.set_partitions(vec![partition_response]);
10163        let mut data = DescribeProducersResponseData::new();
10164        data.set_topics(vec![topic_response]);
10165        ConcreteResponse::DescribeProducers(DescribeProducersResponse::new(data))
10166    }
10167
10168    /// Mirrors `KafkaAdminClientTest.writeTxnMarkersResponse`.
10169    fn write_txn_markers_response(spec: &AbortTransactionSpec, error: Errors) -> ConcreteResponse {
10170        let mut partition = WritableTxnMarkerPartitionResult::new();
10171        partition.set_partition_index(spec.topic_partition().partition());
10172        partition.set_error_code(error.code());
10173        let mut topic = WritableTxnMarkerTopicResult::new();
10174        topic.set_name(spec.topic_partition().topic().to_string());
10175        topic.set_partitions(vec![partition]);
10176        let mut marker = WritableTxnMarkerResult::new();
10177        marker.set_producer_id(spec.producer_id());
10178        marker.set_topics(vec![topic]);
10179        let mut data = WriteTxnMarkersResponseData::new();
10180        data.set_markers(vec![marker]);
10181        ConcreteResponse::WriteTxnMarkers(WriteTxnMarkersResponse::new(data))
10182    }
10183
10184    /// Mirrors `KafkaAdminClientTest.testDescribeProducers`.
10185    #[tokio::test]
10186    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTransactionTest#testDescribeProducers")]
10187    async fn test_describe_producers() {
10188        let (admin, mut runnable, time, nodes) = env();
10189        let tp = TopicPartition::new("foo", 0);
10190
10191        // Metadata lookup maps foo-0 to node0 (the leader).
10192        runnable
10193            .client_mut()
10194            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 0)])]));
10195
10196        let expected = vec![
10197            ProducerState::new(12345, 15, 30, time.milliseconds(), Some(99), None),
10198            ProducerState::new(12345, 15, 30, time.milliseconds(), None, Some(23423)),
10199        ];
10200        runnable
10201            .client_mut()
10202            .prepare_response_from(build_describe_producers_response(&tp, &expected), &nodes[0]);
10203
10204        let result = admin.describe_producers_with_options(std::slice::from_ref(&tp), DescribeProducersOptions::new());
10205        let partition_future = result.partition_result(&tp).unwrap();
10206        pump_until(&mut runnable, 40, |_r| partition_future.is_done()).await;
10207        let state = partition_future.get().await.unwrap();
10208        assert_eq!(
10209            state.active_producers().iter().cloned().collect::<HashSet<_>>(),
10210            expected.into_iter().collect::<HashSet<_>>()
10211        );
10212    }
10213
10214    /// Mirrors `KafkaAdminClientTest.testDescribeProducersTimeout(boolean)`
10215    /// (`@ParameterizedTest` over `{true, false}` → loop).
10216    #[tokio::test]
10217    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTransactionTest#testDescribeProducersTimeout")]
10218    async fn test_describe_producers_timeout() {
10219        for timeout_in_metadata_lookup in [true, false] {
10220            let request_timeout_ms = 15000;
10221            let (admin, mut runnable, time, nodes) = env();
10222            let tp = TopicPartition::new("foo", 0);
10223
10224            if !timeout_in_metadata_lookup {
10225                runnable
10226                    .client_mut()
10227                    .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 0)])]));
10228            }
10229
10230            let options = DescribeProducersOptions::new().set_timeout_ms(Some(request_timeout_ms));
10231            let result = admin.describe_producers_with_options(std::slice::from_ref(&tp), options);
10232            let all = result.all();
10233            // Drain whatever is prepared, then confirm the request has not
10234            // completed before the timeout elapses.
10235            pump(&mut runnable, 5).await;
10236            assert!(
10237                !all.is_done(),
10238                "future completed before timeout (metadata_lookup={timeout_in_metadata_lookup})"
10239            );
10240
10241            time.sleep(request_timeout_ms as i64 + 1);
10242            drive_until(&mut runnable, &time, 40, || all.is_done()).await;
10243            assert!(matches!(all.get().await.unwrap_err(), Error::Timeout(_)));
10244        }
10245    }
10246
10247    /// Mirrors `KafkaAdminClientTest.testDescribeProducersRetryAfterDisconnect`.
10248    #[tokio::test]
10249    #[doc(
10250        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTransactionTest#testDescribeProducersRetryAfterDisconnect"
10251    )]
10252    async fn test_describe_producers_retry_after_disconnect() {
10253        let (admin, mut runnable, time, nodes) = env_with_props(&[("retry.backoff.ms", "100")]);
10254        let tp = TopicPartition::new("foo", 0);
10255
10256        // Lookup maps to node0; the fulfillment disconnects; a fresh lookup maps
10257        // to node1; the retried fulfillment succeeds.
10258        runnable
10259            .client_mut()
10260            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 0)])]));
10261
10262        let expected = vec![
10263            ProducerState::new(12345, 15, 30, time.milliseconds(), Some(99), None),
10264            ProducerState::new(12345, 15, 30, time.milliseconds(), None, Some(23423)),
10265        ];
10266        runnable
10267            .client_mut()
10268            .prepare_response_disconnected(build_describe_producers_response(&tp, &expected), true);
10269        runnable
10270            .client_mut()
10271            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 1)])]));
10272        runnable
10273            .client_mut()
10274            .prepare_response_from(build_describe_producers_response(&tp, &expected), &nodes[1]);
10275
10276        let result = admin.describe_producers_with_options(std::slice::from_ref(&tp), DescribeProducersOptions::new());
10277        let partition_future = result.partition_result(&tp).unwrap();
10278        drive_until(&mut runnable, &time, 60, || partition_future.is_done()).await;
10279        let state = partition_future.get().await.unwrap();
10280        assert_eq!(
10281            state.active_producers().iter().cloned().collect::<HashSet<_>>(),
10282            expected.into_iter().collect::<HashSet<_>>()
10283        );
10284    }
10285
10286    /// Mirrors `KafkaAdminClientTest.testAbortTransaction`.
10287    #[tokio::test]
10288    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTransactionTest#testAbortTransaction")]
10289    async fn test_abort_transaction() {
10290        let (admin, mut runnable, _time, nodes) = env();
10291        let tp = TopicPartition::new("foo", 13);
10292        let spec = AbortTransactionSpec::new(tp.clone(), 12345, 15, 200);
10293
10294        runnable
10295            .client_mut()
10296            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(13, 0)])]));
10297        runnable
10298            .client_mut()
10299            .prepare_response_from(write_txn_markers_response(&spec, Errors::None), &nodes[0]);
10300
10301        let result = admin.abort_transaction_with_options(spec, AbortTransactionOptions::new());
10302        let all = result.all();
10303        pump_until(&mut runnable, 40, |_r| all.is_done()).await;
10304        all.get().await.unwrap();
10305    }
10306
10307    /// Mirrors `KafkaAdminClientTest.testAbortTransactionFindLeaderAfterDisconnect`.
10308    #[tokio::test]
10309    #[doc(
10310        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTransactionTest#testAbortTransactionFindLeaderAfterDisconnect"
10311    )]
10312    async fn test_abort_transaction_find_leader_after_disconnect() {
10313        let (admin, mut runnable, time, nodes) = env_with_props(&[("retry.backoff.ms", "100")]);
10314        let tp = TopicPartition::new("foo", 13);
10315        let spec = AbortTransactionSpec::new(tp.clone(), 12345, 15, 200);
10316
10317        runnable
10318            .client_mut()
10319            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(13, 0)])]));
10320        runnable
10321            .client_mut()
10322            .prepare_response_disconnected(write_txn_markers_response(&spec, Errors::None), true);
10323        runnable
10324            .client_mut()
10325            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(13, 1)])]));
10326        runnable
10327            .client_mut()
10328            .prepare_response_from(write_txn_markers_response(&spec, Errors::None), &nodes[1]);
10329
10330        let result = admin.abort_transaction_with_options(spec, AbortTransactionOptions::new());
10331        let all = result.all();
10332        drive_until(&mut runnable, &time, 60, || all.is_done()).await;
10333        all.get().await.unwrap();
10334    }
10335
10336    /// The mock's `describe_producers` mirrors Java's `UnsupportedOperationException`.
10337    #[tokio::test]
10338    async fn test_mock_describe_producers_unsupported() {
10339        let mock = mock_admin_client::Builder::new()
10340            .build()
10341            .expect("a fresh builder has one broker");
10342        let tp = TopicPartition::new("foo", 0);
10343        let result = mock.describe_producers_with_options(std::slice::from_ref(&tp), DescribeProducersOptions::new());
10344        let err = result.partition_result(&tp).unwrap().get().await.unwrap_err();
10345        assert!(err.is_local_unsupported_operation_error(), "{err:?}");
10346        assert_eq!(err.message(), "Not implemented yet");
10347    }
10348
10349    /// The mock's `abort_transaction` mirrors Java's `UnsupportedOperationException`.
10350    #[tokio::test]
10351    async fn test_mock_abort_transaction_unsupported() {
10352        let mock = mock_admin_client::Builder::new()
10353            .build()
10354            .expect("a fresh builder has one broker");
10355        let spec = AbortTransactionSpec::new(TopicPartition::new("foo", 0), 1, 1, 1);
10356        let result = mock.abort_transaction_with_options(spec, AbortTransactionOptions::new());
10357        let err = result.all().get().await.unwrap_err();
10358        assert!(err.is_local_unsupported_operation_error(), "{err:?}");
10359        assert_eq!(err.message(), "Not implemented yet");
10360    }
10361
10362    // --- describeTransactions / fenceProducers -------------------------------
10363
10364    use crate::DescribeTransactionsResponseData;
10365    use crate::InitProducerIdResponseData;
10366    use crate::admin::{DescribeTransactionsOptions, FenceProducersOptions, TransactionDescription, TransactionState};
10367    use crate::common::requests::InitProducerIdResponse;
10368    use crate::describe_transactions_response_data::TransactionState as WireTxnState;
10369
10370    fn describe_txn_state(
10371        transactional_id: &str,
10372        state: &str,
10373        producer_id: i64,
10374        producer_epoch: i16,
10375        timeout_ms: i32,
10376        start_time_ms: i64,
10377    ) -> WireTxnState {
10378        let mut s = WireTxnState::new();
10379        s.set_error_code(Errors::None.code());
10380        s.set_transactional_id(transactional_id.to_string());
10381        s.set_transaction_state(state.to_string());
10382        s.set_producer_id(producer_id);
10383        s.set_producer_epoch(producer_epoch);
10384        s.set_transaction_timeout_ms(timeout_ms);
10385        s.set_transaction_start_time_ms(start_time_ms);
10386        s
10387    }
10388
10389    fn describe_transactions_resp(states: Vec<WireTxnState>) -> ConcreteResponse {
10390        let mut data = DescribeTransactionsResponseData::new();
10391        data.set_transaction_states(states);
10392        ConcreteResponse::DescribeTransactions(crate::common::requests::DescribeTransactionsResponse::new(data))
10393    }
10394
10395    fn describe_txn_error_state(transactional_id: &str, error: Errors) -> WireTxnState {
10396        let mut s = WireTxnState::new();
10397        s.set_error_code(error.code());
10398        s.set_transactional_id(transactional_id.to_string());
10399        s
10400    }
10401
10402    fn init_producer_id_resp(error: Errors, producer_id: i64, producer_epoch: i16) -> ConcreteResponse {
10403        let mut data = InitProducerIdResponseData::new();
10404        data.set_error_code(error.code());
10405        data.set_producer_id(producer_id);
10406        data.set_producer_epoch(producer_epoch);
10407        ConcreteResponse::InitProducerId(InitProducerIdResponse::new(data))
10408    }
10409
10410    /// Mirrors `KafkaAdminClientTest.testDescribeTransactions`.
10411    #[tokio::test]
10412    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTransactionTest#testDescribeTransactions")]
10413    async fn test_describe_transactions() {
10414        let (admin, mut runnable, _time, nodes) = env();
10415        let transactional_id = "foo";
10416        let coordinator = &nodes[0];
10417
10418        runnable
10419            .client_mut()
10420            .prepare_response(find_coordinator_resp(&[(transactional_id, coordinator)]));
10421        runnable.client_mut().prepare_response_from(
10422            describe_transactions_resp(vec![describe_txn_state(
10423                transactional_id,
10424                "CompleteCommit",
10425                12345,
10426                15,
10427                10000,
10428                -1,
10429            )]),
10430            coordinator,
10431        );
10432
10433        let result = admin.describe_transactions_with_options(&["foo".to_string()], DescribeTransactionsOptions::new());
10434        let future = result.description(transactional_id).unwrap();
10435        pump_until(&mut runnable, 40, |_r| future.is_done()).await;
10436        let expected = TransactionDescription::new(
10437            coordinator.id(),
10438            TransactionState::CompleteCommit,
10439            12345,
10440            15,
10441            10000,
10442            None,
10443            HashSet::new(),
10444        );
10445        assert_eq!(future.get().await.unwrap(), expected);
10446    }
10447
10448    /// Mirrors `KafkaAdminClientTest.testRetryDescribeTransactionsAfterNotCoordinatorError`.
10449    #[tokio::test]
10450    #[doc(
10451        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTransactionTest#testRetryDescribeTransactionsAfterNotCoordinatorError"
10452    )]
10453    async fn test_retry_describe_transactions_after_not_coordinator_error() {
10454        let (admin, mut runnable, time, nodes) = env_with_props(&[("retry.backoff.ms", "100")]);
10455        let transactional_id = "foo";
10456        let coordinator1 = &nodes[0];
10457        let coordinator2 = &nodes[1];
10458
10459        runnable
10460            .client_mut()
10461            .prepare_response(find_coordinator_resp(&[(transactional_id, coordinator1)]));
10462        runnable.client_mut().prepare_response_from(
10463            describe_transactions_resp(vec![describe_txn_error_state(transactional_id, Errors::NotCoordinator)]),
10464            coordinator1,
10465        );
10466        runnable
10467            .client_mut()
10468            .prepare_response(find_coordinator_resp(&[(transactional_id, coordinator2)]));
10469        runnable.client_mut().prepare_response_from(
10470            describe_transactions_resp(vec![describe_txn_state(
10471                transactional_id,
10472                "CompleteCommit",
10473                12345,
10474                15,
10475                10000,
10476                -1,
10477            )]),
10478            coordinator2,
10479        );
10480
10481        let result = admin.describe_transactions_with_options(&["foo".to_string()], DescribeTransactionsOptions::new());
10482        let future = result.description(transactional_id).unwrap();
10483        drive_until(&mut runnable, &time, 60, || future.is_done()).await;
10484        let expected = TransactionDescription::new(
10485            coordinator2.id(),
10486            TransactionState::CompleteCommit,
10487            12345,
10488            15,
10489            10000,
10490            None,
10491            HashSet::new(),
10492        );
10493        assert_eq!(future.get().await.unwrap(), expected);
10494    }
10495
10496    /// A driver call (here the `FindCoordinator` lookup of `describeTransactions`)
10497    /// honours `retries`: `KafkaAdminClient.AdminClientRunnable#enqueue` fails a
10498    /// call whose `tries` exceed `maxRetries` with
10499    /// `TimeoutException("Exceeded maxRetries after " + tries + " tries.")`. With
10500    /// `retries=2` and a coordinator that is never available, Java sends exactly
10501    /// three `FindCoordinator` requests (tries 0, 1, 2) and fails the key when the
10502    /// driver offers the fourth.
10503    ///
10504    /// Rust-side test, no Java counterpart: it was added with this port to check
10505    /// the retry bound on a coordinator lookup directly. The translated Java tests
10506    /// (`testListOffsetsHandlesFulfillmentTimeouts` and the `*NumRetries` tests)
10507    /// cover the same bound through other APIs.
10508    #[tokio::test]
10509    async fn test_driver_lookup_retries_are_bounded_by_max_retries() {
10510        let (admin, mut runnable, time, _nodes) = env_with_props(&[("retries", "2"), ("retry.backoff.ms", "10")]);
10511        let find_coordinator_requests = Arc::new(AtomicUsize::new(0));
10512        // More error responses than Java consumes, so a fourth request would be
10513        // answered (and counted) rather than left waiting.
10514        for _ in 0..5 {
10515            let counter = Arc::clone(&find_coordinator_requests);
10516            runnable.client_mut().prepare_response_matcher(
10517                Box::new(move |body: &AbstractRequest| {
10518                    let is_find_coordinator = matches!(body, AbstractRequest::FindCoordinator(_));
10519                    if is_find_coordinator {
10520                        counter.fetch_add(1, Ordering::SeqCst);
10521                    }
10522                    is_find_coordinator
10523                }),
10524                find_coordinator_error_resp("foo", Errors::CoordinatorNotAvailable),
10525            );
10526        }
10527
10528        let result = admin.describe_transactions_with_options(&["foo".to_string()], DescribeTransactionsOptions::new());
10529        let future = result.description("foo").unwrap();
10530        drive_until(&mut runnable, &time, 200, || future.is_done()).await;
10531
10532        assert!(
10533            future.is_done(),
10534            "the lookup must fail once out of retries; {} FindCoordinator requests were sent",
10535            find_coordinator_requests.load(Ordering::SeqCst)
10536        );
10537        let err = future.get().await.expect_err("the lookup runs out of retries");
10538        assert!(matches!(err, Error::Timeout(_)), "got {err:?}");
10539        assert_eq!(err.message(), "Exceeded maxRetries after 3 tries.");
10540        assert_eq!(find_coordinator_requests.load(Ordering::SeqCst), 3);
10541    }
10542
10543    /// Mirrors `KafkaAdminClientTest.testFenceProducers`.
10544    #[tokio::test]
10545    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTransactionTest#testFenceProducers")]
10546    async fn test_fence_producers() {
10547        let (admin, mut runnable, time, nodes) = env_with_props(&[("retry.backoff.ms", "100")]);
10548        let transactional_id = "copyCat";
10549        let coordinator = &nodes[0];
10550
10551        // Retriable FindCoordinator error, then success, then a coordinator-load
10552        // InitProducerId retry, then a coordinator-moved retry, then success.
10553        runnable
10554            .client_mut()
10555            .prepare_response(find_coordinator_error_resp(transactional_id, Errors::CoordinatorNotAvailable));
10556        runnable
10557            .client_mut()
10558            .prepare_response(find_coordinator_resp(&[(transactional_id, coordinator)]));
10559        runnable
10560            .client_mut()
10561            .prepare_response_from(init_producer_id_resp(Errors::CoordinatorLoadInProgress, 0, 0), coordinator);
10562        runnable
10563            .client_mut()
10564            .prepare_response_from(init_producer_id_resp(Errors::NotCoordinator, 0, 0), coordinator);
10565        runnable
10566            .client_mut()
10567            .prepare_response(find_coordinator_resp(&[(transactional_id, coordinator)]));
10568        runnable
10569            .client_mut()
10570            .prepare_response_from(init_producer_id_resp(Errors::None, 4761, 489), coordinator);
10571
10572        let result = admin.fence_producers_with_options(&["copyCat".to_string()], FenceProducersOptions::new());
10573        let all = result.all();
10574        drive_until(&mut runnable, &time, 80, || all.is_done()).await;
10575        all.get().await.unwrap();
10576        assert_eq!(result.producer_id(transactional_id).unwrap().get().await.unwrap(), 4761);
10577        assert_eq!(result.epoch_id(transactional_id).unwrap().get().await.unwrap(), 489);
10578    }
10579
10580    /// The mock's `describe_transactions` mirrors Java's `UnsupportedOperationException`.
10581    #[tokio::test]
10582    async fn test_mock_describe_transactions_unsupported() {
10583        let mock = mock_admin_client::Builder::new()
10584            .build()
10585            .expect("a fresh builder has one broker");
10586        let result = mock.describe_transactions_with_options(&["t".to_string()], DescribeTransactionsOptions::new());
10587        let err = result.description("t").unwrap().get().await.unwrap_err();
10588        assert!(err.is_local_unsupported_operation_error(), "{err:?}");
10589        assert_eq!(err.message(), "Not implemented yet");
10590    }
10591
10592    /// The mock's `fence_producers` mirrors Java's `UnsupportedOperationException`.
10593    #[tokio::test]
10594    async fn test_mock_fence_producers_unsupported() {
10595        let mock = mock_admin_client::Builder::new()
10596            .build()
10597            .expect("a fresh builder has one broker");
10598        let result = mock.fence_producers_with_options(&["t".to_string()], FenceProducersOptions::new());
10599        let err = result.all().get().await.unwrap_err();
10600        assert!(err.is_local_unsupported_operation_error(), "{err:?}");
10601        assert_eq!(err.message(), "Not implemented yet");
10602    }
10603
10604    // --- listTransactions / forceTerminateTransaction ------------------------
10605
10606    use crate::ListTransactionsResponseData;
10607    use crate::admin::{ListTransactionsOptions, TerminateTransactionOptions, TransactionListing};
10608    use crate::list_transactions_response_data::TransactionState as WireListTxnState;
10609
10610    fn list_transactions_resp(listing: &TransactionListing) -> ConcreteResponse {
10611        let mut s = WireListTxnState::new();
10612        s.set_transactional_id(listing.transactional_id().to_string());
10613        s.set_producer_id(listing.producer_id());
10614        s.set_transaction_state(listing.state().to_string());
10615        let mut data = ListTransactionsResponseData::new();
10616        data.set_error_code(Errors::None.code());
10617        data.set_transaction_states(vec![s]);
10618        ConcreteResponse::ListTransactions(crate::common::requests::ListTransactionsResponse::new(data))
10619    }
10620
10621    /// Mirrors `KafkaAdminClientTest.testListTransactions`.
10622    #[tokio::test]
10623    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTransactionTest#testListTransactions")]
10624    async fn test_list_transactions() {
10625        let (admin, mut runnable, _time, nodes) = env();
10626        // The all-brokers lookup returns every broker; then each broker answers
10627        // its own `ListTransactions` request with one listing (indexed by id).
10628        runnable.client_mut().prepare_response(metadata_resp(&nodes, vec![]));
10629
10630        let expected = [
10631            TransactionListing::new("foo", 12345, TransactionState::Ongoing),
10632            TransactionListing::new("bar", 98765, TransactionState::PrepareAbort),
10633            TransactionListing::new("baz", 13579, TransactionState::CompleteCommit),
10634        ];
10635        for node in &nodes {
10636            runnable
10637                .client_mut()
10638                .prepare_response_from(list_transactions_resp(&expected[node.id() as usize]), node);
10639        }
10640
10641        let result = admin.list_transactions_with_options(ListTransactionsOptions::new());
10642        let all = result.all();
10643        pump_until(&mut runnable, 60, |_r| all.is_done()).await;
10644        assert_eq!(
10645            all.get().await.unwrap().into_iter().collect::<HashSet<_>>(),
10646            expected.into_iter().collect::<HashSet<_>>()
10647        );
10648    }
10649
10650    /// Java's `listTransactions()` is `listTransactions(new ListTransactionsOptions())`
10651    /// (`Admin#listTransactions()`), whose `filteredDuration` starts at `-1L`
10652    /// (`ListTransactionsOptions#filteredDuration`), and `ListTransactionsHandler.buildBatchedRequest`
10653    /// copies it into `DurationFilter`. So the no-arg call asks every broker with
10654    /// `DurationFilter = -1` (no duration filter), not `0`.
10655    #[tokio::test]
10656    async fn test_list_transactions_without_options_sends_no_duration_filter() {
10657        let (admin, mut runnable, _time, nodes) = env();
10658        runnable.client_mut().prepare_response(metadata_resp(&nodes, vec![]));
10659
10660        let duration_filters = Arc::new(Mutex::new(Vec::new()));
10661        for node in &nodes {
10662            let seen = Arc::clone(&duration_filters);
10663            runnable.client_mut().prepare_response_from_matcher(
10664                Box::new(move |body: &AbstractRequest| match body {
10665                    AbstractRequest::ListTransactions(request) => {
10666                        seen.lock().unwrap().push(request.data().duration_filter);
10667                        true
10668                    },
10669                    _ => false,
10670                }),
10671                list_transactions_resp(&TransactionListing::new(
10672                    format!("txn-{}", node.id()),
10673                    i64::from(node.id()),
10674                    TransactionState::Ongoing,
10675                )),
10676                node,
10677            );
10678        }
10679
10680        let result = admin.list_transactions();
10681        let all = result.all();
10682        pump_until(&mut runnable, 60, |_r| all.is_done()).await;
10683        assert_eq!(all.get().await.unwrap().len(), nodes.len());
10684        assert_eq!(*duration_filters.lock().unwrap(), vec![-1; nodes.len()]);
10685    }
10686
10687    /// Mirrors `KafkaAdminClientTest.testForceTerminateTransaction`.
10688    #[tokio::test]
10689    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTransactionTest#testForceTerminateTransaction")]
10690    async fn test_force_terminate_transaction() {
10691        let (admin, mut runnable, _time, nodes) = env();
10692        let transactional_id = "testForceTerminate";
10693        let coordinator = &nodes[0];
10694        runnable
10695            .client_mut()
10696            .prepare_response(find_coordinator_resp(&[(transactional_id, coordinator)]));
10697        runnable
10698            .client_mut()
10699            .prepare_response_from(init_producer_id_resp(Errors::None, 5678, 123), coordinator);
10700
10701        let result =
10702            admin.force_terminate_transaction_with_options(transactional_id, TerminateTransactionOptions::new());
10703        let future = result.result();
10704        pump_until(&mut runnable, 40, |_r| future.is_done()).await;
10705        future.get().await.unwrap();
10706    }
10707
10708    /// Mirrors `KafkaAdminClientTest.testForceTerminateTransactionWithError`.
10709    #[tokio::test]
10710    #[doc(
10711        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTransactionTest#testForceTerminateTransactionWithError"
10712    )]
10713    async fn test_force_terminate_transaction_with_error() {
10714        let (admin, mut runnable, _time, nodes) = env();
10715        let transactional_id = "testForceTerminateError";
10716        let coordinator = &nodes[0];
10717        runnable
10718            .client_mut()
10719            .prepare_response(find_coordinator_resp(&[(transactional_id, coordinator)]));
10720        runnable.client_mut().prepare_response_from(
10721            init_producer_id_resp(Errors::TransactionalIdAuthorizationFailed, 0, 0),
10722            coordinator,
10723        );
10724
10725        let result =
10726            admin.force_terminate_transaction_with_options(transactional_id, TerminateTransactionOptions::new());
10727        let future = result.result();
10728        pump_until(&mut runnable, 40, |_r| future.is_done()).await;
10729        assert_eq!(
10730            future.get().await.unwrap_err().error(),
10731            Errors::TransactionalIdAuthorizationFailed
10732        );
10733    }
10734
10735    /// Mirrors `KafkaAdminClientTest.testForceTerminateTransactionWithCustomTimeout`.
10736    #[tokio::test]
10737    #[doc(
10738        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTransactionTest#testForceTerminateTransactionWithCustomTimeout"
10739    )]
10740    async fn test_force_terminate_transaction_with_custom_timeout() {
10741        let (admin, mut runnable, _time, nodes) = env();
10742        let transactional_id = "testForceTerminateTimeout";
10743        let coordinator = &nodes[0];
10744        runnable
10745            .client_mut()
10746            .prepare_response(find_coordinator_resp(&[(transactional_id, coordinator)]));
10747        runnable
10748            .client_mut()
10749            .prepare_response_from(init_producer_id_resp(Errors::None, 9012, 456), coordinator);
10750
10751        let options = TerminateTransactionOptions::new().set_timeout_ms(Some(10000));
10752        let result = admin.force_terminate_transaction_with_options(transactional_id, options);
10753        let future = result.result();
10754        pump_until(&mut runnable, 40, |_r| future.is_done()).await;
10755        future.get().await.unwrap();
10756    }
10757
10758    /// The mock's `list_transactions` mirrors Java's `UnsupportedOperationException`.
10759    #[tokio::test]
10760    async fn test_mock_list_transactions_unsupported() {
10761        let mock = mock_admin_client::Builder::new()
10762            .build()
10763            .expect("a fresh builder has one broker");
10764        let result = mock.list_transactions_with_options(ListTransactionsOptions::new());
10765        let err = result.all().get().await.unwrap_err();
10766        assert!(err.is_local_unsupported_operation_error(), "{err:?}");
10767        assert_eq!(err.message(), "Not implemented yet");
10768    }
10769
10770    /// The mock's `force_terminate_transaction` mirrors Java's `UnsupportedOperationException`.
10771    #[tokio::test]
10772    async fn test_mock_force_terminate_transaction_unsupported() {
10773        let mock = mock_admin_client::Builder::new()
10774            .build()
10775            .expect("a fresh builder has one broker");
10776        let result = mock.force_terminate_transaction_with_options("t", TerminateTransactionOptions::new());
10777        let err = result.result().get().await.unwrap_err();
10778        assert!(err.is_local_unsupported_operation_error(), "{err:?}");
10779        assert_eq!(err.message(), "Not implemented yet");
10780    }
10781
10782    // --- describeCluster -----------------------------------------------------
10783
10784    use crate::DescribeClusterResponseData;
10785    use crate::DescribeConfigsResponseData;
10786    use crate::IncrementalAlterConfigsResponseData;
10787    use crate::ListConfigResourcesResponseData;
10788    use crate::admin::{
10789        AlterConfigOp, AlterConfigsOptions, DescribeClusterOptions, DescribeConfigsOptions, ListConfigResourcesOptions,
10790        OpType,
10791    };
10792    use crate::common::acl::AclOperation;
10793    use crate::common::config::{ConfigResource, config_resource};
10794    use crate::common::requests::{
10795        DescribeClusterResponse, DescribeConfigsResponse, IncrementalAlterConfigsResponse, ListConfigResourcesResponse,
10796    };
10797    use crate::describe_cluster_response_data::DescribeClusterBroker;
10798    use crate::describe_configs_response_data::DescribeConfigsResult as WireDescribeConfigsResult;
10799    use crate::incremental_alter_configs_response_data::AlterConfigsResourceResponse;
10800    use crate::list_config_resources_response_data::ConfigResource as WireConfigResource;
10801
10802    fn describe_cluster_response(
10803        controller_id: i32,
10804        brokers: &[Node],
10805        cluster_id: &str,
10806        authorized_ops: i32,
10807    ) -> ConcreteResponse {
10808        prepare_describe_cluster_response(0, brokers, cluster_id, controller_id, authorized_ops, false)
10809    }
10810
10811    /// Java's `KafkaAdminClientTestBase.prepareDescribeClusterResponse`: a
10812    /// `sentToController` response states the CONTROLLER endpoint type;
10813    /// otherwise it keeps the default, BROKER.
10814    fn prepare_describe_cluster_response(
10815        throttle_time_ms: i32,
10816        brokers: &[Node],
10817        cluster_id: &str,
10818        controller_id: i32,
10819        cluster_authorized_operations: i32,
10820        sent_to_controller: bool,
10821    ) -> ConcreteResponse {
10822        let mut data = DescribeClusterResponseData::new();
10823        data.set_error_code(Errors::None.code());
10824        data.set_throttle_time_ms(throttle_time_ms);
10825        data.set_controller_id(controller_id);
10826        data.set_cluster_id(cluster_id.to_string());
10827        data.set_cluster_authorized_operations(cluster_authorized_operations);
10828        if sent_to_controller {
10829            data.set_endpoint_type(EndpointType::Controller.id());
10830        }
10831        let wire_brokers = brokers
10832            .iter()
10833            .map(|n| {
10834                let mut b = DescribeClusterBroker::new();
10835                b.set_broker_id(n.id());
10836                b.set_host(n.host().to_string());
10837                b.set_port(n.port());
10838                b.set_rack(n.rack().map(str::to_string));
10839                b
10840            })
10841            .collect();
10842        data.set_brokers(wire_brokers);
10843        ConcreteResponse::DescribeCluster(DescribeClusterResponse::new(data))
10844    }
10845
10846    #[tokio::test]
10847    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testDescribeCluster")]
10848    async fn test_describe_cluster() {
10849        let (admin, mut runnable, _time, nodes) = env();
10850        let cluster_id = "mock-cluster";
10851
10852        // First call: authorized operations omitted, controller id 2.
10853        runnable.client_mut().prepare_response(describe_cluster_response(
10854            2,
10855            &nodes,
10856            cluster_id,
10857            MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED,
10858        ));
10859        let result = admin.describe_cluster_with_options(DescribeClusterOptions::new());
10860        pump(&mut runnable, 5).await;
10861        assert_eq!(result.cluster_id().get().await.unwrap(), cluster_id);
10862        let got: HashSet<Node> = result.nodes().get().await.unwrap().into_iter().collect();
10863        assert_eq!(got, nodes.iter().cloned().collect());
10864        assert_eq!(result.controller().get().await.unwrap().unwrap().id(), 2);
10865        assert_eq!(result.authorized_operations().get().await.unwrap(), None);
10866
10867        // Second call: authorized operations DESCRIBE|ALTER, controller id 1.
10868        let ops = (1 << AclOperation::Describe.code()) | (1 << AclOperation::Alter.code());
10869        runnable
10870            .client_mut()
10871            .prepare_response(describe_cluster_response(1, &nodes, cluster_id, ops));
10872        let result2 = admin.describe_cluster_with_options(DescribeClusterOptions::new());
10873        pump(&mut runnable, 5).await;
10874        assert_eq!(result2.controller().get().await.unwrap().unwrap().id(), 1);
10875        let expected: BTreeSet<AclOperation> = [AclOperation::Describe, AclOperation::Alter].into_iter().collect();
10876        assert_eq!(result2.authorized_operations().get().await.unwrap(), Some(expected));
10877    }
10878
10879    #[tokio::test]
10880    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testDescribeClusterHandleError")]
10881    async fn test_describe_cluster_handle_error() {
10882        let (admin, mut runnable, _time, _nodes) = env();
10883        let error_message = "my error";
10884        let mut data = DescribeClusterResponseData::new();
10885        data.set_error_code(Errors::InvalidRequest.code());
10886        data.set_error_message(Some(error_message.to_string()));
10887        runnable
10888            .client_mut()
10889            .prepare_response(ConcreteResponse::DescribeCluster(DescribeClusterResponse::new(data)));
10890
10891        let result = admin.describe_cluster_with_options(DescribeClusterOptions::new());
10892        pump(&mut runnable, 5).await;
10893        for err in [
10894            result.cluster_id().get().await.unwrap_err(),
10895            result.controller().get().await.unwrap_err(),
10896            result.nodes().get().await.unwrap_err(),
10897            result.authorized_operations().get().await.unwrap_err(),
10898        ] {
10899            assert_eq!(err.error(), Errors::InvalidRequest);
10900            assert!(err.message().contains(error_message), "message was: {}", err.message());
10901        }
10902    }
10903
10904    #[tokio::test]
10905    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testDescribeClusterFailBack")]
10906    async fn test_describe_cluster_fail_back() {
10907        let (admin, mut runnable, _time, nodes) = env();
10908        let cluster_id = "mock-cluster";
10909        // Reject the DescribeCluster request with an unsupported version, then
10910        // answer the Metadata fallback.
10911        runnable.client_mut().prepare_unsupported_version_response();
10912        runnable
10913            .client_mut()
10914            .prepare_response(ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
10915                &nodes,
10916                Some(cluster_id),
10917                2,
10918                Vec::new(),
10919            )));
10920
10921        let result = admin.describe_cluster_with_options(DescribeClusterOptions::new());
10922        pump(&mut runnable, 8).await;
10923        assert_eq!(result.cluster_id().get().await.unwrap(), cluster_id);
10924        let got: HashSet<Node> = result.nodes().get().await.unwrap().into_iter().collect();
10925        assert_eq!(got, nodes.iter().cloned().collect());
10926        assert_eq!(result.controller().get().await.unwrap().unwrap().id(), 2);
10927        assert_eq!(result.authorized_operations().get().await.unwrap(), None);
10928    }
10929
10930    #[tokio::test]
10931    async fn test_describe_cluster_unsupported_version_for_fenced_brokers() {
10932        let (admin, mut runnable, _time, _nodes) = env();
10933        // includeFencedBrokers=true: an UnsupportedVersion must NOT fall back to
10934        // the Metadata request; it propagates as UnsupportedVersion.
10935        runnable.client_mut().prepare_unsupported_version_response();
10936        let result =
10937            admin.describe_cluster_with_options(DescribeClusterOptions::new().set_include_fenced_brokers(true));
10938        pump(&mut runnable, 8).await;
10939        let err = result.nodes().get().await.unwrap_err();
10940        assert_eq!(err.error(), Errors::UnsupportedVersion);
10941    }
10942
10943    /// `KafkaAdminClient#describeCluster`'s `handleUnsupportedVersionException`
10944    /// answers `false` for a `bootstrap.controllers` client before anything
10945    /// else: a controller
10946    /// has no `Metadata` endpoint, so an UnsupportedVersion fails the call
10947    /// instead of falling back to a `MetadataRequest`. The Metadata answer
10948    /// prepared here is what a fallback would consume.
10949    #[tokio::test]
10950    async fn test_describe_cluster_unsupported_version_in_controller_mode_does_not_fall_back() {
10951        let (admin, mut runnable, _time, nodes) = controller_env();
10952        runnable.client_mut().prepare_unsupported_version_response();
10953        runnable
10954            .client_mut()
10955            .prepare_response(ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
10956                &nodes,
10957                Some("mock-cluster"),
10958                0,
10959                Vec::new(),
10960            )));
10961        let result = admin.describe_cluster_with_options(DescribeClusterOptions::new());
10962        let nodes_future = result.nodes();
10963        pump_until(&mut runnable, 20, |_| nodes_future.is_done()).await;
10964        assert!(nodes_future.is_done(), "describeCluster did not complete");
10965        let err = nodes_future.get().await.unwrap_err();
10966        assert_eq!(err.error(), Errors::UnsupportedVersion, "got {err:?}");
10967    }
10968
10969    // --- describeConfigs -----------------------------------------------------
10970
10971    fn describe_configs_result(name: &str, type_id: i8, error: Errors) -> WireDescribeConfigsResult {
10972        let mut r = WireDescribeConfigsResult::new();
10973        r.set_resource_name(name.to_string());
10974        r.set_resource_type(type_id);
10975        r.set_error_code(error.code());
10976        r.set_configs(Vec::new());
10977        r
10978    }
10979
10980    fn describe_configs_response(results: Vec<WireDescribeConfigsResult>) -> ConcreteResponse {
10981        let mut data = DescribeConfigsResponseData::new();
10982        data.set_results(results);
10983        ConcreteResponse::DescribeConfigs(DescribeConfigsResponse::new(data))
10984    }
10985
10986    /// New test, no Java original: unlike a `createTopics` entry, every entry
10987    /// `describeConfigs` builds has a type. Java's `describeConfigResult`
10988    /// passes `ConfigType.forId(id).type()`, which is `UNKNOWN` for an id it
10989    /// does not know, never `null`.
10990    #[test]
10991    fn describe_config_result_gives_every_entry_a_type() {
10992        use crate::describe_configs_response_data::DescribeConfigsResourceResult;
10993        let mut result = describe_configs_result("t", config_resource::Type::Topic.id(), Errors::None);
10994        let mut long = DescribeConfigsResourceResult::new();
10995        long.set_name("retention.ms".to_string());
10996        long.set_config_type(5);
10997        let mut unknown = DescribeConfigsResourceResult::new();
10998        unknown.set_name("future.config".to_string());
10999        unknown.set_config_type(42);
11000        result.set_configs(vec![long, unknown]);
11001
11002        let config = describe_config_result(&result);
11003        assert_eq!(config.get("retention.ms").unwrap().r#type(), Some(ConfigType::Long));
11004        assert_eq!(config.get("future.config").unwrap().r#type(), Some(ConfigType::Unknown));
11005    }
11006
11007    #[tokio::test]
11008    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testDescribeBrokerConfigs")]
11009    async fn test_describe_broker_configs() {
11010        let (admin, mut runnable, _time, nodes) = env();
11011        let broker0 = ConfigResource::new(config_resource::Type::Broker, "0".to_string());
11012        let broker1 = ConfigResource::new(config_resource::Type::Broker, "1".to_string());
11013        runnable.client_mut().prepare_response_from(
11014            describe_configs_response(vec![describe_configs_result(
11015                "0",
11016                config_resource::Type::Broker.id(),
11017                Errors::None,
11018            )]),
11019            &nodes[0],
11020        );
11021        runnable.client_mut().prepare_response_from(
11022            describe_configs_response(vec![describe_configs_result(
11023                "1",
11024                config_resource::Type::Broker.id(),
11025                Errors::None,
11026            )]),
11027            &nodes[1],
11028        );
11029        let result =
11030            admin.describe_configs_with_options(&[broker0.clone(), broker1.clone()], DescribeConfigsOptions::new());
11031        pump(&mut runnable, 8).await;
11032        let keys: HashSet<ConfigResource> = result.values().keys().cloned().collect();
11033        assert_eq!(keys, [broker0.clone(), broker1.clone()].into_iter().collect());
11034        result.values().get(&broker0).unwrap().get().await.unwrap();
11035        result.values().get(&broker1).unwrap().get().await.unwrap();
11036    }
11037
11038    #[tokio::test]
11039    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testDescribeBrokerAndLogConfigs")]
11040    async fn test_describe_broker_and_log_configs() {
11041        let (admin, mut runnable, _time, nodes) = env();
11042        let broker = ConfigResource::new(config_resource::Type::Broker, "0".to_string());
11043        let broker_logger = ConfigResource::new(config_resource::Type::BrokerLogger, "0".to_string());
11044        // Both broker and broker-logger resources for node 0 go to node 0 in one
11045        // request.
11046        runnable.client_mut().prepare_response_from(
11047            describe_configs_response(vec![
11048                describe_configs_result("0", config_resource::Type::Broker.id(), Errors::None),
11049                describe_configs_result("0", config_resource::Type::BrokerLogger.id(), Errors::None),
11050            ]),
11051            &nodes[0],
11052        );
11053        let result = admin
11054            .describe_configs_with_options(&[broker.clone(), broker_logger.clone()], DescribeConfigsOptions::new());
11055        pump(&mut runnable, 8).await;
11056        let keys: HashSet<ConfigResource> = result.values().keys().cloned().collect();
11057        assert_eq!(keys, [broker.clone(), broker_logger.clone()].into_iter().collect());
11058        result.values().get(&broker).unwrap().get().await.unwrap();
11059        result.values().get(&broker_logger).unwrap().get().await.unwrap();
11060    }
11061
11062    #[tokio::test]
11063    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testDescribeConfigsPartialResponse")]
11064    async fn test_describe_configs_partial_response() {
11065        let (admin, mut runnable, _time, _nodes) = env();
11066        let topic = ConfigResource::new(config_resource::Type::Topic, "topic".to_string());
11067        let topic2 = ConfigResource::new(config_resource::Type::Topic, "topic2".to_string());
11068        // The (single, least-loaded) response only contains `topic`.
11069        runnable
11070            .client_mut()
11071            .prepare_response(describe_configs_response(vec![describe_configs_result(
11072                "topic",
11073                config_resource::Type::Topic.id(),
11074                Errors::None,
11075            )]));
11076        let result =
11077            admin.describe_configs_with_options(&[topic.clone(), topic2.clone()], DescribeConfigsOptions::new());
11078        pump(&mut runnable, 8).await;
11079        let keys: HashSet<ConfigResource> = result.values().keys().cloned().collect();
11080        assert_eq!(keys, [topic.clone(), topic2.clone()].into_iter().collect());
11081        result.values().get(&topic).unwrap().get().await.unwrap();
11082        assert!(result.values().get(&topic2).unwrap().get().await.is_err());
11083    }
11084
11085    #[tokio::test]
11086    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testDescribeConfigsUnrequested")]
11087    async fn test_describe_configs_unrequested() {
11088        let (admin, mut runnable, _time, _nodes) = env();
11089        let topic = ConfigResource::new(config_resource::Type::Topic, "topic".to_string());
11090        // Response contains an extra, unrequested resource; it is ignored.
11091        runnable.client_mut().prepare_response(describe_configs_response(vec![
11092            describe_configs_result("topic", config_resource::Type::Topic.id(), Errors::None),
11093            describe_configs_result("unrequested", config_resource::Type::Topic.id(), Errors::None),
11094        ]));
11095        let result = admin.describe_configs_with_options(std::slice::from_ref(&topic), DescribeConfigsOptions::new());
11096        pump(&mut runnable, 8).await;
11097        let keys: HashSet<ConfigResource> = result.values().keys().cloned().collect();
11098        assert_eq!(keys, [topic.clone()].into_iter().collect());
11099        result.values().get(&topic).unwrap().get().await.unwrap();
11100    }
11101
11102    #[tokio::test]
11103    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testDescribeClientMetricsConfigs")]
11104    async fn test_describe_client_metrics_configs() {
11105        let (admin, mut runnable, _time, _nodes) = env();
11106        let sub1 = ConfigResource::new(config_resource::Type::ClientMetrics, "sub1".to_string());
11107        let sub2 = ConfigResource::new(config_resource::Type::ClientMetrics, "sub2".to_string());
11108        runnable.client_mut().prepare_response(describe_configs_response(vec![
11109            describe_configs_result("sub1", config_resource::Type::ClientMetrics.id(), Errors::None),
11110            describe_configs_result("sub2", config_resource::Type::ClientMetrics.id(), Errors::None),
11111        ]));
11112        let result = admin.describe_configs_with_options(&[sub1.clone(), sub2.clone()], DescribeConfigsOptions::new());
11113        pump(&mut runnable, 8).await;
11114        let keys: HashSet<ConfigResource> = result.values().keys().cloned().collect();
11115        assert_eq!(keys, [sub1.clone(), sub2.clone()].into_iter().collect());
11116        result.values().get(&sub1).unwrap().get().await.unwrap();
11117        result.values().get(&sub2).unwrap().get().await.unwrap();
11118    }
11119
11120    // --- incrementalAlterConfigs ---------------------------------------------
11121
11122    fn alter_configs_resource_response(
11123        name: &str,
11124        type_id: i8,
11125        error: Errors,
11126        message: &str,
11127    ) -> AlterConfigsResourceResponse {
11128        let mut r = AlterConfigsResourceResponse::new();
11129        r.set_resource_name(name.to_string());
11130        r.set_resource_type(type_id);
11131        r.set_error_code(error.code());
11132        r.set_error_message(Some(message.to_string()));
11133        r
11134    }
11135
11136    fn incremental_alter_configs_response(responses: Vec<AlterConfigsResourceResponse>) -> ConcreteResponse {
11137        let mut data = IncrementalAlterConfigsResponseData::new();
11138        data.set_responses(responses);
11139        ConcreteResponse::IncrementalAlterConfigs(IncrementalAlterConfigsResponse::new(data))
11140    }
11141
11142    #[tokio::test]
11143    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testIncrementalAlterConfigs")]
11144    async fn test_incremental_alter_configs() {
11145        let (admin, mut runnable, _time, _nodes) = env();
11146
11147        let broker_resource = ConfigResource::new(config_resource::Type::Broker, String::new());
11148        let topic_resource = ConfigResource::new(config_resource::Type::Topic, "topic1".to_string());
11149        let metric_resource = ConfigResource::new(config_resource::Type::ClientMetrics, "metric1".to_string());
11150        let group_resource = ConfigResource::new(config_resource::Type::Group, "group1".to_string());
11151
11152        // Error scenario: all four resources are least-loaded-routed (default
11153        // broker, topic, client-metrics, group all have node_for == None), so a
11154        // single request fails per-resource.
11155        runnable.client_mut().prepare_response(incremental_alter_configs_response(vec![
11156            alter_configs_resource_response(
11157                "",
11158                config_resource::Type::Broker.id(),
11159                Errors::ClusterAuthorizationFailed,
11160                "authorization error",
11161            ),
11162            alter_configs_resource_response(
11163                "metric1",
11164                config_resource::Type::ClientMetrics.id(),
11165                Errors::InvalidRequest,
11166                "Subscription is not allowed",
11167            ),
11168            alter_configs_resource_response(
11169                "topic1",
11170                config_resource::Type::Topic.id(),
11171                Errors::InvalidRequest,
11172                "Config value append is not allowed for config",
11173            ),
11174            alter_configs_resource_response(
11175                "group1",
11176                config_resource::Type::Group.id(),
11177                Errors::InvalidConfig,
11178                "Unknown group config name: group.initial.rebalance.delay.ms",
11179            ),
11180        ]));
11181
11182        let op1 = AlterConfigOp::new(
11183            ConfigEntry::new("log.segment.bytes".to_string(), Some("1073741".to_string())),
11184            OpType::Set,
11185        );
11186        let op2 = AlterConfigOp::new(
11187            ConfigEntry::new("compression.type".to_string(), Some("gzip".to_string())),
11188            OpType::Append,
11189        );
11190        let op3 = AlterConfigOp::new(
11191            ConfigEntry::new("interval.ms".to_string(), Some("1000".to_string())),
11192            OpType::Append,
11193        );
11194        let op4 = AlterConfigOp::new(
11195            ConfigEntry::new("group.initial.rebalance.delay.ms".to_string(), Some("1000".to_string())),
11196            OpType::Set,
11197        );
11198
11199        let mut configs = HashMap::new();
11200        configs.insert(broker_resource.clone(), vec![op1.clone()]);
11201        configs.insert(topic_resource.clone(), vec![op2]);
11202        configs.insert(metric_resource.clone(), vec![op3.clone()]);
11203        configs.insert(group_resource.clone(), vec![op4.clone()]);
11204
11205        let result = admin.incremental_alter_configs_with_options(&configs, AlterConfigsOptions::new());
11206        pump(&mut runnable, 8).await;
11207        assert_eq!(
11208            result.values().get(&broker_resource).unwrap().get().await.unwrap_err().error(),
11209            Errors::ClusterAuthorizationFailed
11210        );
11211        assert_eq!(
11212            result.values().get(&topic_resource).unwrap().get().await.unwrap_err().error(),
11213            Errors::InvalidRequest
11214        );
11215        assert_eq!(
11216            result.values().get(&metric_resource).unwrap().get().await.unwrap_err().error(),
11217            Errors::InvalidRequest
11218        );
11219        assert_eq!(
11220            result.values().get(&group_resource).unwrap().get().await.unwrap_err().error(),
11221            Errors::InvalidConfig
11222        );
11223
11224        // Success scenario.
11225        runnable.client_mut().prepare_response(incremental_alter_configs_response(vec![
11226            alter_configs_resource_response("", config_resource::Type::Broker.id(), Errors::None, ""),
11227            alter_configs_resource_response("metric1", config_resource::Type::ClientMetrics.id(), Errors::None, ""),
11228            alter_configs_resource_response("group1", config_resource::Type::Group.id(), Errors::None, ""),
11229        ]));
11230        let mut success = HashMap::new();
11231        success.insert(broker_resource, vec![op1]);
11232        success.insert(metric_resource, vec![op3]);
11233        success.insert(group_resource, vec![op4]);
11234        let result = admin.incremental_alter_configs_with_options(&success, AlterConfigsOptions::new());
11235        pump(&mut runnable, 8).await;
11236        result.all().get().await.unwrap();
11237    }
11238
11239    // --- listConfigResources -------------------------------------------------
11240
11241    fn list_config_resources_response(error: Errors, resources: &[(&str, i8)]) -> ConcreteResponse {
11242        let mut data = ListConfigResourcesResponseData::new();
11243        data.set_error_code(error.code());
11244        let wire = resources
11245            .iter()
11246            .map(|(name, type_id)| {
11247                let mut r = WireConfigResource::new();
11248                r.set_resource_name((*name).to_string());
11249                r.set_resource_type(*type_id);
11250                r
11251            })
11252            .collect();
11253        data.set_config_resources(wire);
11254        ConcreteResponse::ListConfigResources(ListConfigResourcesResponse::new(data))
11255    }
11256
11257    #[tokio::test]
11258    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testListConfigResources")]
11259    async fn test_list_config_resources() {
11260        let (admin, mut runnable, _time, _nodes) = env();
11261        let expected = [
11262            ("client-metrics", config_resource::Type::ClientMetrics.id()),
11263            ("1", config_resource::Type::Broker.id()),
11264            ("1", config_resource::Type::BrokerLogger.id()),
11265            ("topic", config_resource::Type::Topic.id()),
11266            ("group", config_resource::Type::Group.id()),
11267        ];
11268        runnable
11269            .client_mut()
11270            .prepare_response(list_config_resources_response(Errors::None, &expected));
11271        let result = admin.list_config_resources_with_options(&HashSet::new(), ListConfigResourcesOptions::new());
11272        pump(&mut runnable, 5).await;
11273        let listed = result.all().get().await.unwrap();
11274        assert_eq!(listed.len(), expected.len());
11275        let expected_set: HashSet<ConfigResource> = expected
11276            .iter()
11277            .map(|(name, type_id)| ConfigResource::new(config_resource::Type::for_id(*type_id), (*name).to_string()))
11278            .collect();
11279        assert_eq!(listed.into_iter().collect::<HashSet<_>>(), expected_set);
11280    }
11281
11282    #[tokio::test]
11283    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testListConfigResourcesEmpty")]
11284    async fn test_list_config_resources_empty() {
11285        let (admin, mut runnable, _time, _nodes) = env();
11286        runnable
11287            .client_mut()
11288            .prepare_response(list_config_resources_response(Errors::None, &[]));
11289        let result = admin.list_config_resources_with_options(&HashSet::new(), ListConfigResourcesOptions::new());
11290        pump(&mut runnable, 5).await;
11291        assert!(result.all().get().await.unwrap().is_empty());
11292    }
11293
11294    #[tokio::test]
11295    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testListConfigResourcesNotSupported")]
11296    async fn test_list_config_resources_not_supported() {
11297        let (admin, mut runnable, _time, _nodes) = env();
11298        runnable
11299            .client_mut()
11300            .prepare_response(list_config_resources_response(Errors::UnsupportedVersion, &[]));
11301        let mut types = HashSet::new();
11302        types.insert(config_resource::Type::Unknown);
11303        let result = admin.list_config_resources_with_options(&types, ListConfigResourcesOptions::new());
11304        pump(&mut runnable, 5).await;
11305        let err = result.all().get().await.unwrap_err();
11306        assert_eq!(err.error(), Errors::UnsupportedVersion);
11307    }
11308
11309    // Branch (2) coverage at the `Call` bridge: the `maybe_retry` hook installed
11310    // by `new_driver_call` turns a disconnect into a lookup retry driven through
11311    // the `AdminApiDriver` and reports `MaybeRetryOutcome::Handled`, instead of
11312    // re-queueing the call against the (dead) fulfillment node. Mirrors the hook
11313    // side of `AdminApiDriverTest.testRetryLookupAfterDisconnect`.
11314    #[test]
11315    fn driver_call_maybe_retry_disconnect_redrives_lookup() {
11316        use crate::admin::internals::admin_api_driver::test_support::{
11317            TestContext, completed, mapped, placeholder_response,
11318        };
11319
11320        let mut ctx = TestContext::dynamic_mapped(&["foo"]);
11321        let now = ctx.now;
11322
11323        // Drive the initial lookup so `foo` maps to broker 1.
11324        ctx.expect_lookup(&["foo"], mapped(&[("foo", 1)]));
11325        let lookup_specs = ctx.driver.poll();
11326        assert_eq!(lookup_specs.len(), 1);
11327        ctx.driver.on_response(
11328            now,
11329            &lookup_specs[0].scope,
11330            &lookup_specs[0].keys,
11331            &placeholder_response(),
11332            Node::no_node(),
11333        );
11334        assert_eq!(ctx.driver.key_to_broker_id(&"foo".to_string()), Some(1));
11335
11336        // Obtain the fulfillment spec targeting broker 1.
11337        ctx.expect_request(&["foo"], completed(&[("foo", 15)]));
11338        let mut fulfill_specs = ctx.driver.poll();
11339        assert_eq!(fulfill_specs.len(), 1);
11340        let spec = fulfill_specs.remove(0);
11341        assert_eq!(spec.scope.destination_broker_id(), Some(1));
11342
11343        // Wrap the spec in a real driver `Call` and fire a disconnect through it.
11344        let driver = Arc::new(Mutex::new(ctx.driver));
11345        let (tx, mut rx) = mpsc::unbounded_channel();
11346        let drv_ctx = DriverContext {
11347            sender: CallSender::for_test(tx),
11348            time: mock_time(now),
11349            log_context: LogContext::new("[test] "),
11350        };
11351        let mut call = new_driver_call(Arc::clone(&driver), spec, drv_ctx);
11352
11353        let outcome = call.maybe_retry(
11354            &Error::Disconnect(crate::common::errors::DisconnectError::new("disconnected")),
11355            now,
11356        );
11357        assert!(matches!(outcome, MaybeRetryOutcome::Handled));
11358
11359        // `foo` was unmapped and a fresh lookup call was enqueued (targeting a
11360        // least-loaded broker, not the disconnected fulfillment node).
11361        assert_eq!(driver.lock().unwrap().key_to_broker_id(&"foo".to_string()), None);
11362        let follow_up = rx.try_recv().expect("a lookup call should have been enqueued");
11363        assert!(matches!(follow_up.node_provider, NodeProvider::LeastLoaded));
11364    }
11365
11366    // A non-disconnect error falls through to the default `Requeue` outcome, so
11367    // the runnable re-queues the call honoring backoff/retries; the driver state
11368    // is untouched and nothing new is enqueued.
11369    #[test]
11370    fn driver_call_maybe_retry_non_network_requeues() {
11371        use crate::admin::internals::admin_api_driver::test_support::{TestContext, completed};
11372
11373        let ctx = TestContext::static_mapped(&[("foo", 0)]);
11374        let now = ctx.now;
11375        ctx.expect_request(&["foo"], completed(&[("foo", 15)]));
11376
11377        let mut driver = ctx.driver;
11378        let mut specs = driver.poll();
11379        assert_eq!(specs.len(), 1);
11380        let spec = specs.remove(0);
11381
11382        let driver = Arc::new(Mutex::new(driver));
11383        let (tx, mut rx) = mpsc::unbounded_channel();
11384        let drv_ctx = DriverContext {
11385            sender: CallSender::for_test(tx),
11386            time: mock_time(now),
11387            log_context: LogContext::new("[test] "),
11388        };
11389        let mut call = new_driver_call(Arc::clone(&driver), spec, drv_ctx);
11390
11391        let outcome = call.maybe_retry(&Error::new(Errors::UnknownServerError), now);
11392        assert!(matches!(outcome, MaybeRetryOutcome::Requeue));
11393        assert_eq!(driver.lock().unwrap().key_to_broker_id(&"foo".to_string()), Some(0));
11394        assert!(rx.try_recv().is_err());
11395    }
11396
11397    // --- describeLogDirs / alterReplicaLogDirs / describeReplicaLogDirs -------
11398
11399    use crate::AlterReplicaLogDirsResponseData;
11400    use crate::DescribeLogDirsResponseData;
11401    use crate::admin::{AlterReplicaLogDirsOptions, DescribeLogDirsOptions, DescribeReplicaLogDirsOptions};
11402    use crate::alter_replica_log_dirs_response_data::{
11403        AlterReplicaLogDirPartitionResult, AlterReplicaLogDirTopicResult,
11404    };
11405    use crate::common::TopicPartitionReplica;
11406    use crate::common::requests::AlterReplicaLogDirsResponse;
11407    use crate::describe_log_dirs_response_data::{
11408        DescribeLogDirsPartition, DescribeLogDirsResult as WireDescribeLogDirsResult, DescribeLogDirsTopic,
11409    };
11410
11411    fn describe_log_dirs_topics(
11412        partition_size: i64,
11413        offset_lag: i64,
11414        topic: &str,
11415        partition: i32,
11416        is_future: bool,
11417    ) -> Vec<DescribeLogDirsTopic> {
11418        let mut p = DescribeLogDirsPartition::new();
11419        p.set_partition_index(partition);
11420        p.set_partition_size(partition_size);
11421        p.set_is_future_key(is_future);
11422        p.set_offset_lag(offset_lag);
11423        let mut t = DescribeLogDirsTopic::new();
11424        t.set_name(topic.to_string());
11425        t.set_partitions(vec![p]);
11426        vec![t]
11427    }
11428
11429    fn describe_log_dirs_result(
11430        error: Errors,
11431        log_dir: &str,
11432        topics: Vec<DescribeLogDirsTopic>,
11433    ) -> WireDescribeLogDirsResult {
11434        let mut r = WireDescribeLogDirsResult::new();
11435        r.set_error_code(error.code());
11436        r.set_log_dir(log_dir.to_string());
11437        r.set_topics(topics);
11438        r
11439    }
11440
11441    fn describe_log_dirs_response(results: Vec<WireDescribeLogDirsResult>) -> ConcreteResponse {
11442        let mut data = DescribeLogDirsResponseData::new();
11443        data.set_results(results);
11444        ConcreteResponse::DescribeLogDirs(DescribeLogDirsResponse::new(data))
11445    }
11446
11447    fn describe_log_dirs_single(
11448        error: Errors,
11449        log_dir: &str,
11450        tp: &TopicPartition,
11451        partition_size: i64,
11452        offset_lag: i64,
11453    ) -> ConcreteResponse {
11454        describe_log_dirs_response(vec![describe_log_dirs_result(
11455            error,
11456            log_dir,
11457            describe_log_dirs_topics(partition_size, offset_lag, tp.topic(), tp.partition(), false),
11458        )])
11459    }
11460
11461    fn describe_log_dirs_single_with_bytes(
11462        error: Errors,
11463        log_dir: &str,
11464        tp: &TopicPartition,
11465        partition_size: i64,
11466        offset_lag: i64,
11467        total_bytes: i64,
11468        usable_bytes: i64,
11469    ) -> ConcreteResponse {
11470        let mut r = describe_log_dirs_result(
11471            error,
11472            log_dir,
11473            describe_log_dirs_topics(partition_size, offset_lag, tp.topic(), tp.partition(), false),
11474        );
11475        r.set_total_bytes(total_bytes);
11476        r.set_usable_bytes(usable_bytes);
11477        describe_log_dirs_response(vec![r])
11478    }
11479
11480    #[expect(clippy::too_many_arguments)]
11481    fn describe_log_dirs_single_cordoned(
11482        error: Errors,
11483        log_dir: &str,
11484        tp: &TopicPartition,
11485        partition_size: i64,
11486        offset_lag: i64,
11487        total_bytes: i64,
11488        usable_bytes: i64,
11489        is_cordoned: bool,
11490    ) -> ConcreteResponse {
11491        let mut r = describe_log_dirs_result(
11492            error,
11493            log_dir,
11494            describe_log_dirs_topics(partition_size, offset_lag, tp.topic(), tp.partition(), false),
11495        );
11496        r.set_total_bytes(total_bytes);
11497        r.set_usable_bytes(usable_bytes);
11498        r.set_is_cordoned(is_cordoned);
11499        describe_log_dirs_response(vec![r])
11500    }
11501
11502    fn empty_describe_log_dirs_response(error: Option<Errors>) -> ConcreteResponse {
11503        let mut data = DescribeLogDirsResponseData::new();
11504        if let Some(e) = error {
11505            data.set_error_code(e.code());
11506        }
11507        ConcreteResponse::DescribeLogDirs(DescribeLogDirsResponse::new(data))
11508    }
11509
11510    fn replica_describe_log_dirs_result(
11511        tpr: &TopicPartitionReplica,
11512        log_dir: &str,
11513        partition_size: i64,
11514        offset_lag: i64,
11515        is_future: bool,
11516    ) -> WireDescribeLogDirsResult {
11517        let mut r = WireDescribeLogDirsResult::new();
11518        r.set_error_code(Errors::None.code());
11519        r.set_log_dir(log_dir.to_string());
11520        r.set_topics(describe_log_dirs_topics(
11521            partition_size,
11522            offset_lag,
11523            tpr.topic(),
11524            tpr.partition(),
11525            is_future,
11526        ));
11527        r
11528    }
11529
11530    fn alter_log_dirs_response(error: Errors, topic: &str, partitions: &[i32]) -> ConcreteResponse {
11531        let mut topic_result = AlterReplicaLogDirTopicResult::new();
11532        topic_result.set_topic_name(topic.to_string());
11533        topic_result.set_partitions(
11534            partitions
11535                .iter()
11536                .map(|&partition_id| {
11537                    let mut p = AlterReplicaLogDirPartitionResult::new();
11538                    p.set_partition_index(partition_id);
11539                    p.set_error_code(error.code());
11540                    p
11541                })
11542                .collect(),
11543        );
11544        let mut data = AlterReplicaLogDirsResponseData::new();
11545        data.set_results(vec![topic_result]);
11546        ConcreteResponse::AlterReplicaLogDirs(AlterReplicaLogDirsResponse::new(data))
11547    }
11548
11549    /// Mirrors `KafkaAdminClientTest.testDescribeLogDirs`.
11550    #[tokio::test]
11551    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDescribeLogDirs")]
11552    async fn test_describe_log_dirs() {
11553        let log_dir = "/var/data/kafka";
11554        let tp = TopicPartition::new("topic", 12);
11555        let partition_size = 1234567890;
11556        let offset_lag = 24;
11557        let (admin, mut runnable, _time, nodes) = env();
11558
11559        runnable.client_mut().prepare_response_from(
11560            describe_log_dirs_single(Errors::None, log_dir, &tp, partition_size, offset_lag),
11561            &nodes[0],
11562        );
11563        let result = admin.describe_log_dirs_with_options(&[0], DescribeLogDirsOptions::new());
11564        pump_until(&mut runnable, 10, |_r| result.descriptions()[&0].is_done()).await;
11565
11566        let descriptions = result.descriptions();
11567        assert_eq!(descriptions.keys().copied().collect::<HashSet<_>>(), HashSet::from([0]));
11568        let map = descriptions[&0].get().await.unwrap();
11569        assert_description_contains(&map, log_dir, &tp, partition_size, offset_lag, None, None);
11570        let all = result.all_descriptions().get().await.unwrap();
11571        assert_eq!(all.keys().copied().collect::<HashSet<_>>(), HashSet::from([0]));
11572        assert_description_contains(&all[&0], log_dir, &tp, partition_size, offset_lag, None, None);
11573
11574        // Empty results when not authorized with version < 3.
11575        runnable
11576            .client_mut()
11577            .prepare_response_from(empty_describe_log_dirs_response(None), &nodes[0]);
11578        let error_result = admin.describe_log_dirs_with_options(&[0], DescribeLogDirsOptions::new());
11579        pump_until(&mut runnable, 10, |_r| error_result.descriptions()[&0].is_done()).await;
11580        let err = error_result.all_descriptions().get().await.unwrap_err();
11581        assert_eq!(err.error(), Errors::ClusterAuthorizationFailed);
11582
11583        // Empty results with an error with version >= 3.
11584        runnable
11585            .client_mut()
11586            .prepare_response_from(empty_describe_log_dirs_response(Some(Errors::UnknownServerError)), &nodes[0]);
11587        let error_result2 = admin.describe_log_dirs_with_options(&[0], DescribeLogDirsOptions::new());
11588        pump_until(&mut runnable, 10, |_r| error_result2.descriptions()[&0].is_done()).await;
11589        let err2 = error_result2.all_descriptions().get().await.unwrap_err();
11590        assert_eq!(err2.error(), Errors::UnknownServerError);
11591    }
11592
11593    fn assert_description_contains(
11594        map: &HashMap<String, LogDirDescription>,
11595        log_dir: &str,
11596        tp: &TopicPartition,
11597        partition_size: i64,
11598        offset_lag: i64,
11599        total_bytes: Option<i64>,
11600        usable_bytes: Option<i64>,
11601    ) {
11602        assert_eq!(
11603            map.keys().cloned().collect::<HashSet<_>>(),
11604            HashSet::from([log_dir.to_string()])
11605        );
11606        let desc = &map[log_dir];
11607        assert!(desc.error().is_none());
11608        let infos = desc.replica_infos();
11609        assert_eq!(infos.keys().cloned().collect::<HashSet<_>>(), HashSet::from([tp.clone()]));
11610        assert_eq!(infos[tp].size(), partition_size);
11611        assert_eq!(infos[tp].offset_lag(), offset_lag);
11612        assert!(!infos[tp].is_future());
11613        assert_eq!(desc.total_bytes(), total_bytes);
11614        assert_eq!(desc.usable_bytes(), usable_bytes);
11615        assert!(!desc.is_cordoned());
11616    }
11617
11618    /// Mirrors `KafkaAdminClientTest.testDescribeLogDirsWithVolumeBytes`.
11619    #[tokio::test]
11620    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDescribeLogDirsWithVolumeBytes")]
11621    async fn test_describe_log_dirs_with_volume_bytes() {
11622        let log_dir = "/var/data/kafka";
11623        let tp = TopicPartition::new("topic", 12);
11624        let partition_size = 1234567890;
11625        let offset_lag = 24;
11626        let total_bytes = 123;
11627        let usable_bytes = 456;
11628        let (admin, mut runnable, _time, nodes) = env();
11629
11630        runnable.client_mut().prepare_response_from(
11631            describe_log_dirs_single_with_bytes(
11632                Errors::None,
11633                log_dir,
11634                &tp,
11635                partition_size,
11636                offset_lag,
11637                total_bytes,
11638                usable_bytes,
11639            ),
11640            &nodes[0],
11641        );
11642        let result = admin.describe_log_dirs_with_options(&[0], DescribeLogDirsOptions::new());
11643        pump_until(&mut runnable, 10, |_r| result.descriptions()[&0].is_done()).await;
11644        let map = result.descriptions()[&0].get().await.unwrap();
11645        assert_description_contains(
11646            &map,
11647            log_dir,
11648            &tp,
11649            partition_size,
11650            offset_lag,
11651            Some(total_bytes),
11652            Some(usable_bytes),
11653        );
11654        let all = result.all_descriptions().get().await.unwrap();
11655        assert_description_contains(
11656            &all[&0],
11657            log_dir,
11658            &tp,
11659            partition_size,
11660            offset_lag,
11661            Some(total_bytes),
11662            Some(usable_bytes),
11663        );
11664    }
11665
11666    /// Mirrors `KafkaAdminClientTest.testDescribeLogDirsWithCordonedDir`
11667    /// (KIP-1066).
11668    #[tokio::test]
11669    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDescribeLogDirsWithCordonedDir")]
11670    async fn test_describe_log_dirs_with_cordoned_dir() {
11671        let log_dir = "/var/data/kafka";
11672        let tp = TopicPartition::new("topic", 12);
11673        let (admin, mut runnable, _time, nodes) = env();
11674
11675        runnable.client_mut().prepare_response_from(
11676            describe_log_dirs_single_cordoned(Errors::None, log_dir, &tp, 123, -1, -1, -1, true),
11677            &nodes[0],
11678        );
11679        let result = admin.describe_log_dirs_with_options(&[0], DescribeLogDirsOptions::new());
11680        pump_until(&mut runnable, 10, |_r| result.descriptions()[&0].is_done()).await;
11681
11682        let descriptions = result.descriptions();
11683        assert_eq!(descriptions.keys().copied().collect::<HashSet<_>>(), HashSet::from([0]));
11684        let map = descriptions[&0].get().await.unwrap();
11685        assert_eq!(
11686            map.keys().cloned().collect::<HashSet<_>>(),
11687            HashSet::from([log_dir.to_string()])
11688        );
11689        assert!(map[log_dir].is_cordoned());
11690        assert_eq!(
11691            map[log_dir].replica_infos().keys().cloned().collect::<HashSet<_>>(),
11692            HashSet::from([tp.clone()])
11693        );
11694
11695        let all = result.all_descriptions().get().await.unwrap();
11696        assert_eq!(all.keys().copied().collect::<HashSet<_>>(), HashSet::from([0]));
11697        let all_map = &all[&0];
11698        assert_eq!(
11699            all_map.keys().cloned().collect::<HashSet<_>>(),
11700            HashSet::from([log_dir.to_string()])
11701        );
11702        assert!(all_map[log_dir].is_cordoned());
11703        assert_eq!(
11704            all_map[log_dir].replica_infos().keys().cloned().collect::<HashSet<_>>(),
11705            HashSet::from([tp.clone()])
11706        );
11707    }
11708
11709    /// Mirrors `KafkaAdminClientTest.testDescribeLogDirsOfflineDir`.
11710    #[tokio::test]
11711    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDescribeLogDirsOfflineDir")]
11712    async fn test_describe_log_dirs_offline_dir() {
11713        let log_dir = "/var/data/kafka";
11714        let (admin, mut runnable, _time, nodes) = env();
11715        runnable.client_mut().prepare_response_from(
11716            describe_log_dirs_response(vec![describe_log_dirs_result(Errors::KafkaStorageError, log_dir, Vec::new())]),
11717            &nodes[0],
11718        );
11719        let result = admin.describe_log_dirs_with_options(&[0], DescribeLogDirsOptions::new());
11720        pump_until(&mut runnable, 10, |_r| result.descriptions()[&0].is_done()).await;
11721        let map = result.descriptions()[&0].get().await.unwrap();
11722        assert_eq!(
11723            map.keys().cloned().collect::<HashSet<_>>(),
11724            HashSet::from([log_dir.to_string()])
11725        );
11726        assert_eq!(map[log_dir].error().unwrap().error(), Errors::KafkaStorageError);
11727        assert!(map[log_dir].replica_infos().is_empty());
11728    }
11729
11730    /// Mirrors `KafkaAdminClientTest.testDescribeLogDirsPartialFailure`.
11731    #[tokio::test]
11732    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDescribeLogDirsPartialFailure")]
11733    async fn test_describe_log_dirs_partial_failure() {
11734        let default_api_timeout: i64 = 60000;
11735        let (admin, mut runnable, time, nodes) = env_with_props(&[
11736            ("default.api.timeout.ms", &default_api_timeout.to_string()),
11737            ("retries", "0"),
11738        ]);
11739        // Provide only node 1's response.
11740        runnable.client_mut().prepare_response_from(
11741            describe_log_dirs_response(vec![describe_log_dirs_result(Errors::None, "/data", Vec::new())]),
11742            &nodes[1],
11743        );
11744        let result = admin.describe_log_dirs_with_options(&[0, 1], DescribeLogDirsOptions::new());
11745        pump_until(&mut runnable, 30, |r| !r.client_mut().has_pending_responses()).await;
11746        time.sleep(default_api_timeout + 1);
11747        pump_until(&mut runnable, 30, |_r| {
11748            result.descriptions()[&0].is_done() && result.descriptions()[&1].is_done()
11749        })
11750        .await;
11751        assert!(matches!(result.descriptions()[&0].get().await.unwrap_err(), Error::Timeout(_)));
11752        assert!(result.descriptions()[&1].get().await.is_ok());
11753    }
11754
11755    /// Mirrors `KafkaAdminClientTest.testDescribeReplicaLogDirs`.
11756    #[tokio::test]
11757    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDescribeReplicaLogDirs")]
11758    async fn test_describe_replica_log_dirs() {
11759        let tpr1 = TopicPartitionReplica::new("topic", 12, 1);
11760        let tpr2 = TopicPartitionReplica::new("topic", 12, 2);
11761        let (admin, mut runnable, _time, nodes) = env();
11762
11763        let broker1log0 = "/var/data/kafka0";
11764        let broker1log1 = "/var/data/kafka1";
11765        let broker2log0 = "/var/data/kafka2";
11766        runnable.client_mut().prepare_response_from(
11767            describe_log_dirs_response(vec![
11768                replica_describe_log_dirs_result(&tpr1, broker1log0, 987654321, 24, false),
11769                replica_describe_log_dirs_result(&tpr1, broker1log1, 123456789, 4321, true),
11770            ]),
11771            &nodes[1],
11772        );
11773        runnable.client_mut().prepare_response_from(
11774            describe_log_dirs_response(vec![describe_log_dirs_result(
11775                Errors::KafkaStorageError,
11776                broker2log0,
11777                Vec::new(),
11778            )]),
11779            &nodes[2],
11780        );
11781
11782        let result = admin.describe_replica_log_dirs_with_options(
11783            &[tpr1.clone(), tpr2.clone()],
11784            DescribeReplicaLogDirsOptions::new(),
11785        );
11786        pump_until(&mut runnable, 20, |_r| {
11787            result.values()[&tpr1].is_done() && result.values()[&tpr2].is_done()
11788        })
11789        .await;
11790
11791        assert_eq!(
11792            result.values().keys().cloned().collect::<HashSet<_>>(),
11793            HashSet::from([tpr1.clone(), tpr2.clone()])
11794        );
11795        let info1 = result.values()[&tpr1].get().await.unwrap();
11796        assert_eq!(info1.current_replica_log_dir(), Some(broker1log0));
11797        assert_eq!(info1.current_replica_offset_lag(), 24);
11798        assert_eq!(info1.future_replica_log_dir(), Some(broker1log1));
11799        assert_eq!(info1.future_replica_offset_lag(), 4321);
11800
11801        let info2 = result.values()[&tpr2].get().await.unwrap();
11802        assert_eq!(info2.current_replica_log_dir(), None);
11803        assert_eq!(info2.current_replica_offset_lag(), -1);
11804        assert_eq!(info2.future_replica_log_dir(), None);
11805        assert_eq!(info2.future_replica_offset_lag(), -1);
11806    }
11807
11808    /// Mirrors `KafkaAdminClientTest.testDescribeReplicaLogDirsUnexpected`.
11809    #[tokio::test]
11810    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDescribeReplicaLogDirsUnexpected")]
11811    async fn test_describe_replica_log_dirs_unexpected() {
11812        let expected = TopicPartitionReplica::new("topic", 12, 1);
11813        let unexpected = TopicPartitionReplica::new("topic", 12, 2);
11814        let (admin, mut runnable, _time, nodes) = env();
11815
11816        let broker1log0 = "/var/data/kafka0";
11817        let broker1log1 = "/var/data/kafka1";
11818        runnable.client_mut().prepare_response_from(
11819            describe_log_dirs_response(vec![
11820                replica_describe_log_dirs_result(&expected, broker1log0, 987654321, 24, false),
11821                replica_describe_log_dirs_result(&unexpected, broker1log1, 123456789, 4321, true),
11822            ]),
11823            &nodes[1],
11824        );
11825
11826        let result = admin.describe_replica_log_dirs_with_options(
11827            std::slice::from_ref(&expected),
11828            DescribeReplicaLogDirsOptions::new(),
11829        );
11830        pump_until(&mut runnable, 20, |_r| result.values()[&expected].is_done()).await;
11831
11832        assert_eq!(
11833            result.values().keys().cloned().collect::<HashSet<_>>(),
11834            HashSet::from([expected.clone()])
11835        );
11836        let info = result.values()[&expected].get().await.unwrap();
11837        assert_eq!(info.current_replica_log_dir(), Some(broker1log0));
11838        assert_eq!(info.current_replica_offset_lag(), 24);
11839        assert_eq!(info.future_replica_log_dir(), Some(broker1log1));
11840        assert_eq!(info.future_replica_offset_lag(), 4321);
11841    }
11842
11843    /// Mirrors `KafkaAdminClientTest.testDescribeReplicaLogDirsWithNonExistReplica`.
11844    #[tokio::test]
11845    #[doc(
11846        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testDescribeReplicaLogDirsWithNonExistReplica"
11847    )]
11848    async fn test_describe_replica_log_dirs_with_non_exist_replica() {
11849        let broker_id = 0;
11850        let tpr1 = TopicPartitionReplica::new("topic1", 12, broker_id);
11851        let tpr2 = TopicPartitionReplica::new("topic2", 12, broker_id);
11852        let (admin, mut runnable, _time, nodes) = env();
11853
11854        let log_dir = "/var/data/kafka0";
11855        let offset_lag = 1;
11856        runnable.client_mut().prepare_response_from(
11857            describe_log_dirs_response(vec![replica_describe_log_dirs_result(
11858                &tpr1, log_dir, 123456, offset_lag, false,
11859            )]),
11860            &nodes[broker_id as usize],
11861        );
11862
11863        let result = admin.describe_replica_log_dirs_with_options(
11864            &[tpr1.clone(), tpr2.clone()],
11865            DescribeReplicaLogDirsOptions::new(),
11866        );
11867        pump_until(&mut runnable, 20, |_r| {
11868            result.values()[&tpr1].is_done() && result.values()[&tpr2].is_done()
11869        })
11870        .await;
11871
11872        let info1 = result.values()[&tpr1].get().await.unwrap();
11873        assert_eq!(info1.current_replica_log_dir(), Some(log_dir));
11874        assert_eq!(info1.future_replica_log_dir(), None);
11875        assert_eq!(info1.current_replica_offset_lag(), offset_lag);
11876        assert_eq!(info1.future_replica_offset_lag(), -1);
11877        let info2 = result.values()[&tpr2].get().await.unwrap();
11878        assert_eq!(info2.current_replica_log_dir(), None);
11879        assert_eq!(info2.future_replica_log_dir(), None);
11880        assert_eq!(info2.current_replica_offset_lag(), -1);
11881        assert_eq!(info2.future_replica_offset_lag(), -1);
11882    }
11883
11884    /// Mirrors `KafkaAdminClientTest.testAlterReplicaLogDirsSuccess`.
11885    #[tokio::test]
11886    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testAlterReplicaLogDirsSuccess")]
11887    async fn test_alter_replica_log_dirs_success() {
11888        let (admin, mut runnable, _time, nodes) = env();
11889        runnable
11890            .client_mut()
11891            .prepare_response_from(alter_log_dirs_response(Errors::None, "topic", &[0]), &nodes[0]);
11892        runnable
11893            .client_mut()
11894            .prepare_response_from(alter_log_dirs_response(Errors::None, "topic", &[0]), &nodes[1]);
11895
11896        let tpr0 = TopicPartitionReplica::new("topic", 0, 0);
11897        let tpr1 = TopicPartitionReplica::new("topic", 0, 1);
11898        let assignment = HashMap::from([
11899            (tpr0.clone(), "/data0".to_string()),
11900            (tpr1.clone(), "/data1".to_string()),
11901        ]);
11902        let result = admin.alter_replica_log_dirs_with_options(&assignment, AlterReplicaLogDirsOptions::new());
11903        pump_until(&mut runnable, 20, |_r| {
11904            result.values()[&tpr0].is_done() && result.values()[&tpr1].is_done()
11905        })
11906        .await;
11907        result.values()[&tpr0].get().await.unwrap();
11908        result.values()[&tpr1].get().await.unwrap();
11909    }
11910
11911    /// Mirrors `KafkaAdminClientTest.testAlterReplicaLogDirsLogDirNotFound`.
11912    #[tokio::test]
11913    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testAlterReplicaLogDirsLogDirNotFound")]
11914    async fn test_alter_replica_log_dirs_log_dir_not_found() {
11915        let (admin, mut runnable, _time, nodes) = env();
11916        runnable
11917            .client_mut()
11918            .prepare_response_from(alter_log_dirs_response(Errors::None, "topic", &[0]), &nodes[0]);
11919        runnable
11920            .client_mut()
11921            .prepare_response_from(alter_log_dirs_response(Errors::LogDirNotFound, "topic", &[0]), &nodes[1]);
11922
11923        let tpr0 = TopicPartitionReplica::new("topic", 0, 0);
11924        let tpr1 = TopicPartitionReplica::new("topic", 0, 1);
11925        let assignment = HashMap::from([
11926            (tpr0.clone(), "/data0".to_string()),
11927            (tpr1.clone(), "/data1".to_string()),
11928        ]);
11929        let result = admin.alter_replica_log_dirs_with_options(&assignment, AlterReplicaLogDirsOptions::new());
11930        pump_until(&mut runnable, 20, |_r| {
11931            result.values()[&tpr0].is_done() && result.values()[&tpr1].is_done()
11932        })
11933        .await;
11934        result.values()[&tpr0].get().await.unwrap();
11935        let err = result.values()[&tpr1].get().await.unwrap_err();
11936        assert_eq!(err.error(), Errors::LogDirNotFound);
11937    }
11938
11939    /// Mirrors `KafkaAdminClientTest.testAlterReplicaLogDirsUnrequested`.
11940    #[tokio::test]
11941    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testAlterReplicaLogDirsUnrequested")]
11942    async fn test_alter_replica_log_dirs_unrequested() {
11943        let (admin, mut runnable, _time, nodes) = env();
11944        // Response contains partitions 1 and 2, but only 1 was requested.
11945        runnable
11946            .client_mut()
11947            .prepare_response_from(alter_log_dirs_response(Errors::None, "topic", &[1, 2]), &nodes[0]);
11948
11949        let tpr1 = TopicPartitionReplica::new("topic", 1, 0);
11950        let assignment = HashMap::from([(tpr1.clone(), "/data1".to_string())]);
11951        let result = admin.alter_replica_log_dirs_with_options(&assignment, AlterReplicaLogDirsOptions::new());
11952        pump_until(&mut runnable, 20, |_r| result.values()[&tpr1].is_done()).await;
11953        result.values()[&tpr1].get().await.unwrap();
11954    }
11955
11956    /// Mirrors `KafkaAdminClientTest.testAlterReplicaLogDirsPartialResponse`.
11957    #[tokio::test]
11958    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testAlterReplicaLogDirsPartialResponse")]
11959    async fn test_alter_replica_log_dirs_partial_response() {
11960        let (admin, mut runnable, _time, nodes) = env();
11961        // Response contains only partition 1; partition 2 was also requested.
11962        runnable
11963            .client_mut()
11964            .prepare_response_from(alter_log_dirs_response(Errors::None, "topic", &[1]), &nodes[0]);
11965
11966        let tpr1 = TopicPartitionReplica::new("topic", 1, 0);
11967        let tpr2 = TopicPartitionReplica::new("topic", 2, 0);
11968        let assignment = HashMap::from([
11969            (tpr1.clone(), "/data1".to_string()),
11970            (tpr2.clone(), "/data1".to_string()),
11971        ]);
11972        let result = admin.alter_replica_log_dirs_with_options(&assignment, AlterReplicaLogDirsOptions::new());
11973        pump_until(&mut runnable, 20, |_r| {
11974            result.values()[&tpr1].is_done() && result.values()[&tpr2].is_done()
11975        })
11976        .await;
11977        result.values()[&tpr1].get().await.unwrap();
11978        // The sanity check completes the unrequested-in-response future with an
11979        // UnknownServerError (mirrors `completeUnrealizedFutures`).
11980        let err = result.values()[&tpr2].get().await.unwrap_err();
11981        assert_eq!(err.error(), Errors::UnknownServerError);
11982    }
11983
11984    /// Mirrors `KafkaAdminClientTest.testAlterReplicaLogDirsPartialFailure`.
11985    #[tokio::test]
11986    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testAlterReplicaLogDirsPartialFailure")]
11987    async fn test_alter_replica_log_dirs_partial_failure() {
11988        let default_api_timeout: i64 = 60000;
11989        let (admin, mut runnable, time, nodes) = env_with_props(&[
11990            ("default.api.timeout.ms", &default_api_timeout.to_string()),
11991            ("retries", "0"),
11992        ]);
11993        // Provide only node 1's response.
11994        runnable
11995            .client_mut()
11996            .prepare_response_from(alter_log_dirs_response(Errors::None, "topic", &[2]), &nodes[1]);
11997
11998        let tpr1 = TopicPartitionReplica::new("topic", 1, 0);
11999        let tpr2 = TopicPartitionReplica::new("topic", 2, 1);
12000        let assignment = HashMap::from([
12001            (tpr1.clone(), "/data1".to_string()),
12002            (tpr2.clone(), "/data1".to_string()),
12003        ]);
12004        let result = admin.alter_replica_log_dirs_with_options(&assignment, AlterReplicaLogDirsOptions::new());
12005        pump_until(&mut runnable, 30, |r| !r.client_mut().has_pending_responses()).await;
12006        time.sleep(default_api_timeout + 1);
12007        pump_until(&mut runnable, 30, |_r| {
12008            result.values()[&tpr1].is_done() && result.values()[&tpr2].is_done()
12009        })
12010        .await;
12011        assert!(matches!(result.values()[&tpr1].get().await.unwrap_err(), Error::Timeout(_)));
12012        result.values()[&tpr2].get().await.unwrap();
12013    }
12014
12015    // --- MockAdminClient log-dir methods -------------------------------------
12016
12017    fn mock_topic_partition_info(partition: i32, leader: &Node, replicas: Vec<Node>) -> TopicPartitionInfo {
12018        TopicPartitionInfo::with_elr_last_known_elr(
12019            partition,
12020            Some(leader.clone()),
12021            replicas,
12022            Vec::new(),
12023            Vec::new(),
12024            Vec::new(),
12025        )
12026    }
12027
12028    #[tokio::test]
12029    async fn test_mock_describe_log_dirs_reports_topic_replicas() {
12030        let mock = mock_admin_client::Builder::new()
12031            .set_num_brokers(2)
12032            .and_then(mock_admin_client::Builder::build)
12033            .expect("num_brokers is at least 1");
12034        let leader = Node::new(0, "localhost".to_string(), 1000);
12035        let replicas = vec![
12036            Node::new(0, "localhost".to_string(), 1000),
12037            Node::new(1, "localhost".to_string(), 1001),
12038        ];
12039        mock.add_topic(false, "topic", vec![mock_topic_partition_info(0, &leader, replicas)], None)
12040            .expect("seeding a topic with known brokers succeeds");
12041
12042        let result = mock.describe_log_dirs_with_options(&[0, 1], DescribeLogDirsOptions::new());
12043        let broker0 = result.descriptions()[&0].get().await.unwrap();
12044        assert!(broker0.contains_key("/tmp/kafka-logs"));
12045        let infos = broker0["/tmp/kafka-logs"].replica_infos();
12046        assert!(infos.contains_key(&TopicPartition::new("topic", 0)));
12047        // Broker 1 is a replica for the partition too.
12048        let broker1 = result.descriptions()[&1].get().await.unwrap();
12049        assert!(
12050            broker1["/tmp/kafka-logs"]
12051                .replica_infos()
12052                .contains_key(&TopicPartition::new("topic", 0))
12053        );
12054    }
12055
12056    #[tokio::test]
12057    async fn test_mock_alter_and_describe_replica_log_dirs() {
12058        let mock = mock_admin_client::Builder::new()
12059            .set_broker_log_dirs(vec![vec!["/data0".to_string(), "/data1".to_string()]])
12060            .build()
12061            .expect("a fresh builder has one broker");
12062        let leader = Node::new(0, "localhost".to_string(), 1000);
12063        mock.add_topic(
12064            false,
12065            "topic",
12066            vec![mock_topic_partition_info(0, &leader, vec![leader.clone()])],
12067            None,
12068        )
12069        .expect("seeding a topic with known brokers succeeds");
12070
12071        // Before any move, current log dir is the seeded first broker log dir.
12072        let tpr = TopicPartitionReplica::new("topic", 0, 0);
12073        let before = mock
12074            .describe_replica_log_dirs_with_options(std::slice::from_ref(&tpr), DescribeReplicaLogDirsOptions::new());
12075        let info = before.values()[&tpr].get().await.unwrap();
12076        assert_eq!(info.current_replica_log_dir(), Some("/data0"));
12077        assert_eq!(info.future_replica_log_dir(), None);
12078
12079        // Move to /data1; describe should reflect the pending move.
12080        let assignment = HashMap::from([(tpr.clone(), "/data1".to_string())]);
12081        let alter = mock.alter_replica_log_dirs_with_options(&assignment, AlterReplicaLogDirsOptions::new());
12082        alter.values()[&tpr].get().await.unwrap();
12083        let after = mock
12084            .describe_replica_log_dirs_with_options(std::slice::from_ref(&tpr), DescribeReplicaLogDirsOptions::new());
12085        let moved = after.values()[&tpr].get().await.unwrap();
12086        assert_eq!(moved.current_replica_log_dir(), Some("/data0"));
12087        assert_eq!(moved.future_replica_log_dir(), Some("/data1"));
12088    }
12089
12090    #[tokio::test]
12091    async fn test_mock_alter_replica_log_dirs_offline_dir() {
12092        let mock = mock_admin_client::Builder::new()
12093            .build()
12094            .expect("a fresh builder has one broker");
12095        let leader = Node::new(0, "localhost".to_string(), 1000);
12096        mock.add_topic(
12097            false,
12098            "topic",
12099            vec![mock_topic_partition_info(0, &leader, vec![leader.clone()])],
12100            None,
12101        )
12102        .expect("seeding a topic with known brokers succeeds");
12103        let tpr = TopicPartitionReplica::new("topic", 0, 0);
12104        // "/nope" is not among the broker's log dirs -> KafkaStorageError.
12105        let assignment = HashMap::from([(tpr.clone(), "/nope".to_string())]);
12106        let result = mock.alter_replica_log_dirs_with_options(&assignment, AlterReplicaLogDirsOptions::new());
12107        let err = result.values()[&tpr].get().await.unwrap_err();
12108        assert_eq!(err.error(), Errors::KafkaStorageError);
12109    }
12110
12111    #[tokio::test]
12112    async fn test_mock_alter_replica_log_dirs_negative_partition_does_not_panic() {
12113        let mock = mock_admin_client::Builder::new()
12114            .set_broker_log_dirs(vec![vec!["/data0".to_string()]])
12115            .build()
12116            .expect("a fresh builder has one broker");
12117        let leader = Node::new(0, "localhost".to_string(), 1000);
12118        mock.add_topic(
12119            false,
12120            "topic",
12121            vec![mock_topic_partition_info(0, &leader, vec![leader.clone()])],
12122            None,
12123        )
12124        .expect("seeding a topic with known brokers succeeds");
12125
12126        // A negative partition number has no constructor-time validation
12127        // (mirroring Java's equally unvalidated TopicPartitionReplica), so it
12128        // must be handled the same way an unknown replica is, not panic.
12129        let tpr = TopicPartitionReplica::new("topic", -1, 0);
12130        let assignment = HashMap::from([(tpr.clone(), "/data0".to_string())]);
12131        let result = mock.alter_replica_log_dirs_with_options(&assignment, AlterReplicaLogDirsOptions::new());
12132        let err = result.values()[&tpr].get().await.unwrap_err();
12133        assert_eq!(err.error(), Errors::ReplicaNotAvailable);
12134        assert!(err.message().starts_with("Can't find"), "message was: {}", err.message());
12135    }
12136
12137    #[tokio::test]
12138    async fn test_mock_describe_replica_log_dirs_negative_partition_does_not_panic() {
12139        let mock = mock_admin_client::Builder::new()
12140            .set_broker_log_dirs(vec![vec!["/data0".to_string()]])
12141            .build()
12142            .expect("a fresh builder has one broker");
12143        let leader = Node::new(0, "localhost".to_string(), 1000);
12144        mock.add_topic(
12145            false,
12146            "topic",
12147            vec![mock_topic_partition_info(0, &leader, vec![leader.clone()])],
12148            None,
12149        )
12150        .expect("seeding a topic with known brokers succeeds");
12151
12152        let tpr = TopicPartitionReplica::new("topic", -1, 0);
12153        let result = mock
12154            .describe_replica_log_dirs_with_options(std::slice::from_ref(&tpr), DescribeReplicaLogDirsOptions::new());
12155        let info = result.values()[&tpr].get().await.unwrap();
12156        let empty = ReplicaLogDirInfo::default();
12157        assert_eq!(info.current_replica_log_dir(), empty.current_replica_log_dir());
12158        assert_eq!(info.current_replica_offset_lag(), empty.current_replica_offset_lag());
12159        assert_eq!(info.future_replica_log_dir(), empty.future_replica_log_dir());
12160        assert_eq!(info.future_replica_offset_lag(), empty.future_replica_offset_lag());
12161    }
12162
12163    // --- electLeaders / (alter|list)PartitionReassignments / listOffsets -------
12164    //
12165    // `ElectLeadersResponse`, `ElectionType`, and the `*Options` / POJO types are
12166    // already in scope via `use super::*`. Only the wire *data* structs and the
12167    // `ListOffsetsResponse` wrapper need importing here.
12168
12169    use crate::AlterPartitionReassignmentsResponseData;
12170    use crate::ElectLeadersResponseData;
12171    use crate::ListOffsetsResponseData;
12172    use crate::ListPartitionReassignmentsResponseData;
12173    use crate::alter_partition_reassignments_response_data::{
12174        ReassignablePartitionResponse, ReassignableTopicResponse,
12175    };
12176    use crate::common::requests::{
12177        AlterPartitionReassignmentsResponse, ListOffsetsResponse, ListPartitionReassignmentsResponse,
12178    };
12179    use crate::elect_leaders_response_data::{PartitionResult, ReplicaElectionResult};
12180    use crate::list_partition_reassignments_response_data::{OngoingPartitionReassignment, OngoingTopicReassignment};
12181
12182    fn elect_leaders_resp(top_error: Errors, results: Vec<ReplicaElectionResult>) -> ConcreteResponse {
12183        let mut data = ElectLeadersResponseData::new();
12184        data.set_error_code(top_error.code());
12185        data.set_replica_election_results(results);
12186        ConcreteResponse::ElectLeaders(ElectLeadersResponse::with_data(data))
12187    }
12188
12189    fn election_result(topic: &str, partitions: &[(i32, Errors, Option<&str>)]) -> ReplicaElectionResult {
12190        let mut result = ReplicaElectionResult::new();
12191        result.set_topic(topic.to_string());
12192        for (partition, error, message) in partitions {
12193            let mut pr = PartitionResult::new();
12194            pr.set_partition_id(*partition);
12195            pr.set_error_code(error.code());
12196            pr.set_error_message(message.map(str::to_string));
12197            result.partition_result.push(pr);
12198        }
12199        result
12200    }
12201
12202    /// Mirrors `KafkaAdminClientTest.testElectLeaders`.
12203    #[tokio::test]
12204    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testElectLeaders")]
12205    async fn test_elect_leaders() {
12206        for &election_type in ElectionType::values() {
12207            let (admin, mut runnable, time, _nodes) = env();
12208            let topic1 = TopicPartition::new("topic", 0);
12209            let topic2 = TopicPartition::new("topic", 2);
12210
12211            // A call where both partitions fail with ClusterAuthorizationFailed.
12212            runnable.client_mut().prepare_response(elect_leaders_resp(
12213                Errors::None,
12214                vec![election_result(
12215                    "topic",
12216                    &[
12217                        (0, Errors::ClusterAuthorizationFailed, Some("no")),
12218                        (2, Errors::ClusterAuthorizationFailed, Some("no")),
12219                    ],
12220                )],
12221            ));
12222            let partitions: HashSet<TopicPartition> = [topic1.clone(), topic2.clone()].into_iter().collect();
12223            let result =
12224                admin.elect_leaders_with_options(election_type, Some(partitions.clone()), ElectLeadersOptions::new());
12225            pump(&mut runnable, 5).await;
12226            let map = result.partitions().get().await.unwrap();
12227            assert_eq!(map[&topic2].as_ref().unwrap().error(), Errors::ClusterAuthorizationFailed);
12228
12229            // A call where there are no errors.
12230            runnable.client_mut().prepare_response(elect_leaders_resp(
12231                Errors::None,
12232                vec![election_result(
12233                    "topic",
12234                    &[(0, Errors::None, None), (2, Errors::None, None)],
12235                )],
12236            ));
12237            let result =
12238                admin.elect_leaders_with_options(election_type, Some(partitions.clone()), ElectLeadersOptions::new());
12239            pump(&mut runnable, 5).await;
12240            let map = result.partitions().get().await.unwrap();
12241            assert!(map[&topic1].is_none());
12242            assert!(map[&topic2].is_none());
12243
12244            // A call that times out (no response prepared).
12245            let result = admin.elect_leaders_with_options(
12246                election_type,
12247                Some(partitions),
12248                ElectLeadersOptions::new().set_timeout_ms(Some(100)),
12249            );
12250            pump_until(&mut runnable, 5, |r| r.client_mut().request_count() >= 1).await;
12251            time.sleep(200);
12252            pump_until(&mut runnable, 30, |_r| result.partitions().is_done()).await;
12253            let err = result.partitions().get().await.unwrap_err();
12254            assert!(matches!(err, Error::Timeout(_)));
12255        }
12256    }
12257
12258    // --- describeFeatures / updateFeatures -------------------------------------
12259
12260    use crate::ApiVersionsResponseData;
12261    use crate::admin::UpgradeType;
12262    use crate::api_message_type::ListenerType;
12263    use crate::api_versions_response_data::SupportedFeatureKey;
12264    use crate::common::requests::{ApiVersionsResponse, UpdateFeaturesResponse, api_versions_response};
12265
12266    /// Mirrors `KafkaAdminClientTest.defaultFeatureMetadata`.
12267    fn default_feature_metadata() -> FeatureMetadata {
12268        let mut finalized = HashMap::new();
12269        finalized.insert("test_feature_1".to_string(), FinalizedVersionRange::new(2, 2).unwrap());
12270        let mut supported = HashMap::new();
12271        supported.insert("test_feature_1".to_string(), SupportedVersionRange::new(1, 5).unwrap());
12272        FeatureMetadata::new(finalized, Some(1), supported)
12273    }
12274
12275    /// Mirrors `KafkaAdminClientTest.prepareApiVersionsResponseForDescribeFeatures`.
12276    fn api_versions_feature_response(error: Errors) -> ConcreteResponse {
12277        if error == Errors::None {
12278            let mut supported = SupportedFeatureKey::new();
12279            supported.set_name("test_feature_1".to_string());
12280            supported.set_min_version(1);
12281            supported.set_max_version(5);
12282            let mut finalized = HashMap::new();
12283            finalized.insert("test_feature_1".to_string(), 2i16);
12284            let response = api_versions_response::Builder::new()
12285                .set_api_versions(ApiVersionsResponse::filter_apis(ListenerType::Broker, false, false))
12286                .set_supported_features(vec![supported])
12287                .set_finalized_features(finalized)
12288                .set_finalized_features_epoch(1)
12289                .build();
12290            ConcreteResponse::ApiVersions(response)
12291        } else {
12292            let mut data = ApiVersionsResponseData::new();
12293            data.set_throttle_time_ms(0);
12294            data.set_error_code(error.code());
12295            ConcreteResponse::ApiVersions(ApiVersionsResponse::new(data))
12296        }
12297    }
12298
12299    /// Builds an `UpdateFeatures` response echoing the given feature names when
12300    /// the top-level error is NONE (mirrors `UpdateFeaturesResponse.createWithErrors`).
12301    fn update_features_response(top_error: Errors, message: Option<&str>, updates: &[&str]) -> ConcreteResponse {
12302        let set: BTreeSet<String> = updates.iter().map(|s| (*s).to_string()).collect();
12303        ConcreteResponse::UpdateFeatures(UpdateFeaturesResponse::create_with_errors(
12304            top_error,
12305            message.map(str::to_string),
12306            &set,
12307            0,
12308        ))
12309    }
12310
12311    /// Mirrors `KafkaAdminClientTest.makeTestFeatureUpdates`.
12312    fn make_test_feature_updates() -> HashMap<String, FeatureUpdate> {
12313        let mut map = HashMap::new();
12314        map.insert(
12315            "test_feature_1".to_string(),
12316            FeatureUpdate::new(2, UpgradeType::Upgrade).unwrap(),
12317        );
12318        map.insert(
12319            "test_feature_2".to_string(),
12320            FeatureUpdate::new(3, UpgradeType::SafeDowngrade).unwrap(),
12321        );
12322        map
12323    }
12324
12325    /// Mirrors `KafkaAdminClientTest.testDescribeFeaturesSuccess`.
12326    #[tokio::test]
12327    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testDescribeFeaturesSuccess")]
12328    async fn test_describe_features_success() {
12329        let (admin, mut runnable, _time, _nodes) = env();
12330        runnable
12331            .client_mut()
12332            .prepare_response(api_versions_feature_response(Errors::None));
12333        // Java casts the result to `InternalDescribeFeaturesResult`
12334        // (KAFKA-19663); the crate asks for that type directly.
12335        let result = admin.describe_features_internal(DescribeFeaturesOptions::new().set_timeout_ms(Some(10000)));
12336        pump(&mut runnable, 5).await;
12337        let metadata = result.feature_metadata().get().await.unwrap();
12338        assert_eq!(metadata, default_feature_metadata());
12339        let versions = result.node_api_versions().get().await.unwrap();
12340        assert!(versions.api_version(&ApiKeys::API_VERSIONS).is_some());
12341    }
12342
12343    /// Mirrors `KafkaAdminClientTest.testDescribeFeaturesFailure`.
12344    #[tokio::test]
12345    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testDescribeFeaturesFailure")]
12346    async fn test_describe_features_failure() {
12347        let (admin, mut runnable, _time, _nodes) = env();
12348        runnable
12349            .client_mut()
12350            .prepare_response(api_versions_feature_response(Errors::InvalidRequest));
12351        let result = admin.describe_features_internal(DescribeFeaturesOptions::new().set_timeout_ms(Some(10000)));
12352        pump(&mut runnable, 5).await;
12353        let err = result.feature_metadata().get().await.unwrap_err();
12354        assert!(matches!(err, Error::InvalidRequest(_)), "got {err:?}");
12355        let err = result.node_api_versions().get().await.unwrap_err();
12356        assert!(matches!(err, Error::InvalidRequest(_)), "got {err:?}");
12357    }
12358
12359    /// Mirrors `KafkaAdminClientTest.testDescribeFeaturesWithNodeSuccess` — a set
12360    /// `nodeId` routes the request to that broker via `ConstantNodeIdProvider`.
12361    #[tokio::test]
12362    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testDescribeFeaturesWithNodeSuccess")]
12363    async fn test_describe_features_with_node_success() {
12364        let (admin, mut runnable, _time, nodes) = env();
12365        runnable
12366            .client_mut()
12367            .prepare_response_from(api_versions_feature_response(Errors::None), &nodes[0]);
12368        let result = admin
12369            .describe_features_with_options(DescribeFeaturesOptions::new().set_timeout_ms(Some(10000)).set_node_id(0));
12370        pump(&mut runnable, 5).await;
12371        let metadata = result.feature_metadata().get().await.unwrap();
12372        assert_eq!(metadata, default_feature_metadata());
12373    }
12374
12375    /// Mirrors `KafkaAdminClientTest.testDescribeFeaturesWithNodeFailure` — the
12376    /// response is prepared for node 1 but the request targets node 0, so it is
12377    /// never answered and the future times out.
12378    #[tokio::test]
12379    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testDescribeFeaturesWithNodeFailure")]
12380    async fn test_describe_features_with_node_failure() {
12381        let (admin, mut runnable, time, nodes) = env();
12382        runnable
12383            .client_mut()
12384            .prepare_response_from(api_versions_feature_response(Errors::None), &nodes[1]);
12385        let result =
12386            admin.describe_features_internal(DescribeFeaturesOptions::new().set_timeout_ms(Some(1000)).set_node_id(0));
12387        pump_until(&mut runnable, 5, |r| r.client_mut().request_count() >= 1).await;
12388        time.sleep(2000);
12389        pump_until(&mut runnable, 30, |_r| result.feature_metadata().is_done()).await;
12390        let err = result.feature_metadata().get().await.unwrap_err();
12391        assert!(matches!(err, Error::Timeout(_)), "got {err:?}");
12392        // 58f63f448e: without completing it in `handleFailure`, this future
12393        // never resolves (Java's test hung until the class timeout).
12394        assert!(result.node_api_versions().is_done(), "nodeApiVersions was left pending");
12395        let err = result.node_api_versions().get().await.unwrap_err();
12396        assert!(matches!(err, Error::Timeout(_)), "got {err:?}");
12397    }
12398
12399    // --- unregisterController (KAFKA-20395) ----------------------------------
12400
12401    use crate::UnregisterControllerResponseData;
12402    use crate::common::requests::{AbstractRequest, UnregisterControllerResponse};
12403
12404    /// Mirrors `KafkaAdminClientTest.UNREGISTER_NODE_ID`.
12405    const UNREGISTER_NODE_ID: i32 = 1;
12406
12407    /// Mirrors `KafkaAdminClientTest.CONTROLLER_RESPONSE_FACTORY`.
12408    fn unregister_controller_response(error: Errors) -> ConcreteResponse {
12409        let mut data = UnregisterControllerResponseData::new();
12410        data.set_error_code(error.code());
12411        data.set_error_message(Some(error.message().to_string()));
12412        ConcreteResponse::UnregisterController(UnregisterControllerResponse::new(data))
12413    }
12414
12415    /// Mirrors `KafkaAdminClientTest.runUnregisterScenario` for the controller
12416    /// arm: prepare one response per entry of `responses_to_prepare`, issue the
12417    /// call, and drive the runnable until the future resolves.
12418    ///
12419    /// Java's `env.kafkaClient().setNodeApiVersions(NodeApiVersions.create(
12420    /// UNREGISTER_CONTROLLER, 0, 0))` has no counterpart: the Rust `MockClient`
12421    /// does not negotiate versions, and the builder's only version is v0.
12422    ///
12423    /// Each pump iteration advances the mock clock by 100 ms so the retry
12424    /// backoff (`retry.backoff.ms`, 100 ms by default) elapses between attempts,
12425    /// as wall-clock time does under Java's `Time.SYSTEM` / `MockTime` env.
12426    async fn run_unregister_controller_scenario(
12427        extra_props: &[(&str, &str)],
12428        responses_to_prepare: &[Errors],
12429        options: Option<UnregisterControllerOptions>,
12430    ) -> Result<(), Error> {
12431        let (admin, mut runnable, time, _nodes) = env_with_props(extra_props);
12432        for error in responses_to_prepare {
12433            runnable.client_mut().prepare_response_matcher(
12434                Box::new(|request| match request {
12435                    AbstractRequest::UnregisterController(r) => r.data().controller_id() == UNREGISTER_NODE_ID,
12436                    _ => false,
12437                }),
12438                unregister_controller_response(*error),
12439            );
12440        }
12441        let result = match options {
12442            None => admin.unregister_controller(UNREGISTER_NODE_ID),
12443            Some(options) => admin.unregister_controller_with_options(UNREGISTER_NODE_ID, options),
12444        };
12445        let future = result.all();
12446        for _ in 0..100 {
12447            if future.is_done() {
12448                break;
12449            }
12450            runnable.run_once().await;
12451            time.sleep(100);
12452        }
12453        assert!(future.is_done(), "unregisterController did not complete");
12454        future.get().await
12455    }
12456
12457    /// Mirrors `KafkaAdminClientTest.testUnregisterControllerSuccess`.
12458    #[tokio::test]
12459    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testUnregisterControllerSuccess")]
12460    async fn test_unregister_controller_success() {
12461        run_unregister_controller_scenario(&[], &[Errors::None], None).await.unwrap();
12462    }
12463
12464    /// Mirrors `KafkaAdminClientTest.testUnregisterControllerFailure`.
12465    #[tokio::test]
12466    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testUnregisterControllerFailure")]
12467    async fn test_unregister_controller_failure() {
12468        let err = run_unregister_controller_scenario(&[], &[Errors::UnknownServerError], None)
12469            .await
12470            .unwrap_err();
12471        assert_eq!(err.error(), Errors::UnknownServerError);
12472        assert_eq!(err.message(), Errors::UnknownServerError.message());
12473    }
12474
12475    /// Mirrors `KafkaAdminClientTest.testUnregisterControllerTimeoutAndSuccessRetry`:
12476    /// `REQUEST_TIMED_OUT` is thrown from `handleResponse`, so the call retries.
12477    #[tokio::test]
12478    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testUnregisterControllerTimeoutAndSuccessRetry")]
12479    async fn test_unregister_controller_timeout_and_success_retry() {
12480        run_unregister_controller_scenario(&[], &[Errors::RequestTimedOut, Errors::None], None)
12481            .await
12482            .unwrap();
12483    }
12484
12485    /// Mirrors `KafkaAdminClientTest.testUnregisterControllerTimeoutAndFailureRetry`.
12486    #[tokio::test]
12487    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testUnregisterControllerTimeoutAndFailureRetry")]
12488    async fn test_unregister_controller_timeout_and_failure_retry() {
12489        let err = run_unregister_controller_scenario(&[], &[Errors::RequestTimedOut, Errors::UnknownServerError], None)
12490            .await
12491            .unwrap_err();
12492        assert_eq!(err.error(), Errors::UnknownServerError);
12493    }
12494
12495    /// Mirrors `KafkaAdminClientTest.testUnregisterControllerTimeoutMaxRetry`
12496    /// (`RETRIES_CONFIG = "1"`): the second `REQUEST_TIMED_OUT` exhausts the
12497    /// budget, and the `TimeoutException` cause is surfaced unwrapped.
12498    #[tokio::test]
12499    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testUnregisterControllerTimeoutMaxRetry")]
12500    async fn test_unregister_controller_timeout_max_retry() {
12501        let err = run_unregister_controller_scenario(
12502            &[("retries", "1")],
12503            &[Errors::RequestTimedOut, Errors::RequestTimedOut],
12504            None,
12505        )
12506        .await
12507        .unwrap_err();
12508        assert!(matches!(err, Error::Timeout(_)), "expected a timeout, got {err:?}");
12509        assert_eq!(err.message(), Errors::RequestTimedOut.message());
12510    }
12511
12512    /// Mirrors `KafkaAdminClientTest.testUnregisterControllerTimeoutMaxWait`: no
12513    /// response is ever prepared and the 10 ms option deadline expires.
12514    #[tokio::test]
12515    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testUnregisterControllerTimeoutMaxWait")]
12516    async fn test_unregister_controller_timeout_max_wait() {
12517        let err = run_unregister_controller_scenario(
12518            &[],
12519            &[],
12520            Some(UnregisterControllerOptions::new().set_timeout_ms(Some(10))),
12521        )
12522        .await
12523        .unwrap_err();
12524        assert!(matches!(err, Error::Timeout(_)), "expected a timeout, got {err:?}");
12525    }
12526
12527    /// Beyond Java's tests: the wire request carries the controller id, and a
12528    /// non-retriable error such as `CONTROLLER_ID_NOT_REGISTERED` (136) keeps
12529    /// the broker's message.
12530    #[tokio::test]
12531    async fn test_unregister_controller_not_registered_keeps_the_broker_message() {
12532        let (admin, mut runnable, _time, _nodes) = env();
12533        let mut data = UnregisterControllerResponseData::new();
12534        data.set_error_code(Errors::ControllerIdNotRegistered.code());
12535        data.set_error_message(Some("Controller 7 is not registered.".to_string()));
12536        // The matcher asserts (panics in `MockClient::poll`) unless the request
12537        // sent is an UnregisterController request for controller 7.
12538        runnable.client_mut().prepare_response_matcher(
12539            Box::new(
12540                |request| matches!(request, AbstractRequest::UnregisterController(r) if r.data().controller_id() == 7),
12541            ),
12542            ConcreteResponse::UnregisterController(UnregisterControllerResponse::new(data)),
12543        );
12544        let result = admin.unregister_controller(7);
12545        pump_until(&mut runnable, 10, |_r| result.all().is_done()).await;
12546        let err = result.all().get().await.unwrap_err();
12547        assert!(matches!(err, Error::ControllerIdNotRegistered(_)), "got {err:?}");
12548        assert_eq!(err.message(), "Controller 7 is not registered.");
12549    }
12550
12551    /// Beyond Java's tests (Critic 102, Issue 2): a feature range that
12552    /// `createFeatureMetadata` rejects throws out of `handleResponse` into
12553    /// `Call.fail`, so `handleFailure` fails **both** futures with the
12554    /// range-constructor error; `nodeApiVersions` must not complete successfully.
12555    #[tokio::test]
12556    async fn test_describe_features_invalid_range_fails_both_futures() {
12557        let (admin, mut runnable, _time, _nodes) = env();
12558        let mut supported = SupportedFeatureKey::new();
12559        supported.set_name("test_feature_1".to_string());
12560        supported.set_min_version(5);
12561        supported.set_max_version(1);
12562        let response = api_versions_response::Builder::new()
12563            .set_api_versions(ApiVersionsResponse::filter_apis(ListenerType::Broker, false, false))
12564            .set_supported_features(vec![supported])
12565            .set_finalized_features(HashMap::new())
12566            .set_finalized_features_epoch(1)
12567            .build();
12568        runnable.client_mut().prepare_response(ConcreteResponse::ApiVersions(response));
12569        let result = admin.describe_features_internal(DescribeFeaturesOptions::new().set_timeout_ms(Some(10000)));
12570        pump_until(&mut runnable, 10, |_r| result.node_api_versions().is_done()).await;
12571        let expected = "Expected 0 <= minVersion <= maxVersion but received minVersion:5, maxVersion:1.";
12572        let err = result.feature_metadata().get().await.unwrap_err();
12573        assert!(matches!(err, Error::LocalIllegalArgument(_)), "got {err:?}");
12574        assert_eq!(err.message(), expected);
12575        assert!(result.node_api_versions().is_done(), "nodeApiVersions was left pending");
12576        let err = result.node_api_versions().get().await.unwrap_err();
12577        assert!(matches!(err, Error::LocalIllegalArgument(_)), "got {err:?}");
12578        assert_eq!(err.message(), expected);
12579    }
12580
12581    /// Drives `KafkaAdminClientTest.testUpdateFeaturesDuringSuccess` — a
12582    /// `@ParameterizedTest` over `@ValueSource(shorts = {1, 2})`. v1 responses
12583    /// carry per-feature results; v2+ carry only a top-level NONE.
12584    #[tokio::test]
12585    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testUpdateFeaturesDuringSuccess")]
12586    async fn test_update_features_during_success() {
12587        for version in [1i16, 2] {
12588            let (admin, mut runnable, _time, _nodes) = env();
12589            let features: Vec<&str> = if version <= 1 {
12590                vec!["test_feature_1", "test_feature_2"]
12591            } else {
12592                Vec::new()
12593            };
12594            runnable
12595                .client_mut()
12596                .prepare_response(update_features_response(Errors::None, None, &features));
12597            let updates = make_test_feature_updates();
12598            let result = admin
12599                .update_features_with_options(&updates, UpdateFeaturesOptions::new().set_timeout_ms(Some(10000)))
12600                .unwrap();
12601            pump(&mut runnable, 5).await;
12602            for future in result.values().values() {
12603                future.get().await.unwrap();
12604            }
12605        }
12606    }
12607
12608    /// Mirrors `KafkaAdminClientTest.testUpdateFeaturesTopLevelError`.
12609    #[tokio::test]
12610    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testUpdateFeaturesTopLevelError")]
12611    async fn test_update_features_top_level_error() {
12612        let (admin, mut runnable, _time, _nodes) = env();
12613        runnable
12614            .client_mut()
12615            .prepare_response(update_features_response(Errors::InvalidRequest, None, &[]));
12616        let updates = make_test_feature_updates();
12617        let result = admin
12618            .update_features_with_options(&updates, UpdateFeaturesOptions::new().set_timeout_ms(Some(10000)))
12619            .unwrap();
12620        pump(&mut runnable, 5).await;
12621        for future in result.values().values() {
12622            let err = future.get().await.unwrap_err();
12623            assert_eq!(err.error(), Errors::InvalidRequest);
12624            // The top-level error carried no message, so it falls back to the
12625            // error code's default message (mirrors ApiError.exception()).
12626            assert_eq!(err.message(), Errors::InvalidRequest.message());
12627        }
12628    }
12629
12630    /// Drives `KafkaAdminClientTest.testUpdateFeaturesHandleNotControllerException`
12631    /// — a `@ParameterizedTest` over `@ValueSource(shorts = {1, 2})`.
12632    #[tokio::test]
12633    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testUpdateFeaturesHandleNotControllerException")]
12634    async fn test_update_features_handle_not_controller_error() {
12635        for version in [1i16, 2] {
12636            let (admin, mut runnable, time, nodes) = env();
12637            // First attempt hits the wrong controller.
12638            runnable
12639                .client_mut()
12640                .prepare_response(update_features_response(Errors::NotController, None, &[]));
12641            // Then a metadata refresh updates the controller to node 1.
12642            runnable
12643                .client_mut()
12644                .prepare_response(ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
12645                    &nodes,
12646                    Some("mock-cluster"),
12647                    1,
12648                    Vec::new(),
12649                )));
12650            // Then the retry succeeds.
12651            let features: Vec<&str> = if version <= 1 {
12652                vec!["test_feature_1", "test_feature_2"]
12653            } else {
12654                Vec::new()
12655            };
12656            runnable
12657                .client_mut()
12658                .prepare_response(update_features_response(Errors::None, None, &features));
12659            let updates = make_test_feature_updates();
12660            let result = admin
12661                .update_features_with_options(&updates, UpdateFeaturesOptions::new().set_timeout_ms(Some(10000)))
12662                .unwrap();
12663            // The NOT_CONTROLLER retry is gated by retry-backoff, so advance the
12664            // mock clock until every future resolves.
12665            for _ in 0..30 {
12666                if result.values().values().all(|f| f.is_done()) {
12667                    break;
12668                }
12669                runnable.run_once().await;
12670                time.sleep(200);
12671            }
12672            result.all().get().await.unwrap();
12673        }
12674    }
12675
12676    /// Mirrors `KafkaAdminClientTest.testUpdateFeaturesShouldFailRequestForEmptyUpdates`.
12677    #[tokio::test]
12678    #[doc(
12679        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testUpdateFeaturesShouldFailRequestForEmptyUpdates"
12680    )]
12681    async fn test_update_features_should_fail_request_for_empty_updates() {
12682        let (admin, _runnable, _time, _nodes) = env();
12683        let err = admin
12684            .update_features_with_options(&HashMap::new(), UpdateFeaturesOptions::new())
12685            .unwrap_err();
12686        assert_eq!(err.message(), "Feature updates can not be null or empty.");
12687    }
12688
12689    /// Mirrors `KafkaAdminClientTest.testUpdateFeaturesShouldFailRequestForInvalidFeatureName`.
12690    #[tokio::test]
12691    #[doc(
12692        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testUpdateFeaturesShouldFailRequestForInvalidFeatureName"
12693    )]
12694    async fn test_update_features_should_fail_request_for_invalid_feature_name() {
12695        let (admin, _runnable, _time, _nodes) = env();
12696        let mut updates = HashMap::new();
12697        updates.insert("feature".to_string(), FeatureUpdate::new(2, UpgradeType::Upgrade).unwrap());
12698        updates.insert(String::new(), FeatureUpdate::new(2, UpgradeType::Upgrade).unwrap());
12699        let err = admin
12700            .update_features_with_options(&updates, UpdateFeaturesOptions::new())
12701            .unwrap_err();
12702        assert_eq!(err.message(), "Provided feature can not be empty.");
12703    }
12704
12705    /// `testUpdateFeaturesShouldFailRequestForInvalidFeatureName` with a blank name:
12706    /// Java's `Utils.isBlank` is `trim().isEmpty()`, and Java's `trim()` strips every
12707    /// char up to U+0020, so `" "` and `"\t\n"` are rejected, while a no-break space
12708    /// (U+00A0, Unicode white space but above U+0020) is a name.
12709    #[tokio::test]
12710    async fn test_update_features_should_fail_request_for_blank_feature_name() {
12711        let (admin, _runnable, _time, _nodes) = env();
12712        for blank in [" ", "\t\n", "\u{0}"] {
12713            let mut updates = HashMap::new();
12714            updates.insert(blank.to_string(), FeatureUpdate::new(2, UpgradeType::Upgrade).unwrap());
12715            let err = admin
12716                .update_features_with_options(&updates, UpdateFeaturesOptions::new())
12717                .unwrap_err();
12718            assert_eq!(err.message(), "Provided feature can not be empty.", "{blank:?}");
12719        }
12720        let mut updates = HashMap::new();
12721        updates.insert("\u{a0}".to_string(), FeatureUpdate::new(2, UpgradeType::Upgrade).unwrap());
12722        assert!(
12723            admin
12724                .update_features_with_options(&updates, UpdateFeaturesOptions::new())
12725                .is_ok()
12726        );
12727    }
12728
12729    // `testUpdateFeaturesShouldFailRequestInClientWhenDowngradeFlagIsNotSetDuringDeletion`
12730    // is a `FeatureUpdate` constructor test; it lives in `feature_update.rs`
12731    // (`new_rejects_deletion_with_upgrade_flag`).
12732
12733    fn alter_reassignments_resp(
12734        top_error: Errors,
12735        error_message: Option<&str>,
12736        responses: Vec<ReassignableTopicResponse>,
12737    ) -> ConcreteResponse {
12738        let mut data = AlterPartitionReassignmentsResponseData::new();
12739        data.set_error_code(top_error.code());
12740        data.set_error_message(error_message.map(str::to_string));
12741        data.set_responses(responses);
12742        ConcreteResponse::AlterPartitionReassignments(AlterPartitionReassignmentsResponse::new(data))
12743    }
12744
12745    fn reassignable_topic_response(
12746        name: &str,
12747        partitions: &[(i32, Errors, Option<&str>)],
12748    ) -> ReassignableTopicResponse {
12749        let mut topic = ReassignableTopicResponse::new();
12750        topic.set_name(name.to_string());
12751        for (index, error, message) in partitions {
12752            let mut p = ReassignablePartitionResponse::new();
12753            p.set_partition_index(*index);
12754            p.set_error_code(error.code());
12755            p.set_error_message(message.map(str::to_string));
12756            topic.partitions.push(p);
12757        }
12758        topic
12759    }
12760
12761    fn reassignments_input() -> HashMap<TopicPartition, Option<NewPartitionReassignment>> {
12762        let mut reassignments = HashMap::new();
12763        reassignments.insert(TopicPartition::new("A", 0), None);
12764        reassignments.insert(
12765            TopicPartition::new("B", 0),
12766            Some(NewPartitionReassignment::new(vec![1, 2, 3]).unwrap()),
12767        );
12768        reassignments
12769    }
12770
12771    /// Mirrors the too-few-responses scenario of `testAlterPartitionReassignments`.
12772    #[tokio::test]
12773    async fn test_alter_partition_reassignments_too_few_responses() {
12774        let (admin, mut runnable, _time, _nodes) = env();
12775        // The server returns a result for A-0 only (expected 2).
12776        runnable.client_mut().prepare_response(alter_reassignments_resp(
12777            Errors::None,
12778            None,
12779            vec![reassignable_topic_response("A", &[(0, Errors::None, None)])],
12780        ));
12781        let result = admin.alter_partition_reassignments_with_options(
12782            &reassignments_input(),
12783            AlterPartitionReassignmentsOptions::new(),
12784        );
12785        pump(&mut runnable, 5).await;
12786        let all_err = result.all().get().await.unwrap_err();
12787        assert_eq!(all_err.error(), Errors::UnknownServerError);
12788        let a0_err = result.values()[&TopicPartition::new("A", 0)].get().await.unwrap_err();
12789        assert_eq!(a0_err.error(), Errors::UnknownServerError);
12790    }
12791
12792    /// Mirrors the partition-level and top-level error scenarios of
12793    /// `testAlterPartitionReassignments`.
12794    #[tokio::test]
12795    async fn test_alter_partition_reassignments_errors() {
12796        // Partition-level error: A-0 fails, B-0 succeeds.
12797        let (admin, mut runnable, _time, _nodes) = env();
12798        runnable.client_mut().prepare_response(alter_reassignments_resp(
12799            Errors::None,
12800            None,
12801            vec![
12802                reassignable_topic_response("A", &[(0, Errors::InvalidReplicaAssignment, Some("bad"))]),
12803                reassignable_topic_response("B", &[(0, Errors::None, None)]),
12804            ],
12805        ));
12806        let result = admin.alter_partition_reassignments_with_options(
12807            &reassignments_input(),
12808            AlterPartitionReassignmentsOptions::new(),
12809        );
12810        pump(&mut runnable, 5).await;
12811        assert_eq!(
12812            result.values()[&TopicPartition::new("A", 0)].get().await.unwrap_err().error(),
12813            Errors::InvalidReplicaAssignment
12814        );
12815        result.values()[&TopicPartition::new("B", 0)].get().await.unwrap();
12816
12817        // Top-level error: the custom message propagates to every future.
12818        let (admin, mut runnable, _time, _nodes) = env();
12819        let error_message = "this is custom error message";
12820        runnable.client_mut().prepare_response(alter_reassignments_resp(
12821            Errors::ClusterAuthorizationFailed,
12822            Some(error_message),
12823            vec![
12824                reassignable_topic_response("A", &[(0, Errors::None, None)]),
12825                reassignable_topic_response("B", &[(0, Errors::None, None)]),
12826            ],
12827        ));
12828        let result = admin.alter_partition_reassignments_with_options(
12829            &reassignments_input(),
12830            AlterPartitionReassignmentsOptions::new(),
12831        );
12832        pump(&mut runnable, 5).await;
12833        let all_err = result.all().get().await.unwrap_err();
12834        assert_eq!(all_err.error(), Errors::ClusterAuthorizationFailed);
12835        assert_eq!(all_err.message(), error_message);
12836        assert_eq!(
12837            result.values()[&TopicPartition::new("A", 0)].get().await.unwrap_err().message(),
12838            error_message
12839        );
12840    }
12841
12842    /// A null `ErrorMessage` must leave the error code's own text in place.
12843    ///
12844    /// Java builds these with `Errors.exception(errorMessage)`, which returns the
12845    /// pre-built exception (default text) when the message is null. Real brokers
12846    /// send null here: cancelling a reassignment with nothing in flight answers
12847    /// `NO_REASSIGNMENT_IN_PROGRESS` with no message, and the user must still see
12848    /// "No partition reassignment is in progress." — not an empty string.
12849    #[tokio::test]
12850    async fn test_alter_partition_reassignments_null_error_message_keeps_default_text() {
12851        let default_text = Errors::NoReassignmentInProgress.message();
12852        assert!(!default_text.is_empty(), "the code must have default text to preserve");
12853
12854        // Top-level error with a null message (the observed broker behaviour).
12855        let (admin, mut runnable, _time, _nodes) = env();
12856        runnable.client_mut().prepare_response(alter_reassignments_resp(
12857            Errors::NoReassignmentInProgress,
12858            None,
12859            vec![
12860                reassignable_topic_response("A", &[(0, Errors::None, None)]),
12861                reassignable_topic_response("B", &[(0, Errors::None, None)]),
12862            ],
12863        ));
12864        let result = admin.alter_partition_reassignments_with_options(
12865            &reassignments_input(),
12866            AlterPartitionReassignmentsOptions::new(),
12867        );
12868        pump(&mut runnable, 5).await;
12869        let all_err = result.all().get().await.unwrap_err();
12870        assert_eq!(all_err.error(), Errors::NoReassignmentInProgress);
12871        assert_eq!(all_err.message(), default_text);
12872        let a0_err = result.values()[&TopicPartition::new("A", 0)].get().await.unwrap_err();
12873        assert_eq!(a0_err.message(), default_text);
12874
12875        // Partition-level error with a null message goes through the same helper.
12876        let (admin, mut runnable, _time, _nodes) = env();
12877        runnable.client_mut().prepare_response(alter_reassignments_resp(
12878            Errors::None,
12879            None,
12880            vec![
12881                reassignable_topic_response("A", &[(0, Errors::NoReassignmentInProgress, None)]),
12882                reassignable_topic_response("B", &[(0, Errors::None, None)]),
12883            ],
12884        ));
12885        let result = admin.alter_partition_reassignments_with_options(
12886            &reassignments_input(),
12887            AlterPartitionReassignmentsOptions::new(),
12888        );
12889        pump(&mut runnable, 5).await;
12890        let a0_err = result.values()[&TopicPartition::new("A", 0)].get().await.unwrap_err();
12891        assert_eq!(a0_err.error(), Errors::NoReassignmentInProgress);
12892        assert_eq!(a0_err.message(), default_text);
12893        result.values()[&TopicPartition::new("B", 0)].get().await.unwrap();
12894
12895        // An empty-but-present message is kept verbatim, as Java's null-only
12896        // check does — this is the distinction `unwrap_or_default()` erased.
12897        let (admin, mut runnable, _time, _nodes) = env();
12898        runnable.client_mut().prepare_response(alter_reassignments_resp(
12899            Errors::None,
12900            None,
12901            vec![
12902                reassignable_topic_response("A", &[(0, Errors::NoReassignmentInProgress, Some(""))]),
12903                reassignable_topic_response("B", &[(0, Errors::None, None)]),
12904            ],
12905        ));
12906        let result = admin.alter_partition_reassignments_with_options(
12907            &reassignments_input(),
12908            AlterPartitionReassignmentsOptions::new(),
12909        );
12910        pump(&mut runnable, 5).await;
12911        assert_eq!(
12912            result.values()[&TopicPartition::new("A", 0)].get().await.unwrap_err().message(),
12913            ""
12914        );
12915    }
12916
12917    /// The `listPartitionReassignments` counterpart of
12918    /// `test_alter_partition_reassignments_null_error_message_keeps_default_text`.
12919    #[tokio::test]
12920    async fn test_list_partition_reassignments_null_error_message_keeps_default_text() {
12921        let default_text = Errors::ClusterAuthorizationFailed.message();
12922        assert!(!default_text.is_empty(), "the code must have default text to preserve");
12923
12924        let (admin, mut runnable, _time, _nodes) = env();
12925        let mut data = ListPartitionReassignmentsResponseData::new();
12926        data.set_error_code(Errors::ClusterAuthorizationFailed.code());
12927        data.set_error_message(None);
12928        runnable
12929            .client_mut()
12930            .prepare_response(ConcreteResponse::ListPartitionReassignments(
12931                ListPartitionReassignmentsResponse::new(data),
12932            ));
12933
12934        let result =
12935            admin.list_partition_reassignments_with_partitions_options(None, ListPartitionReassignmentsOptions::new());
12936        pump(&mut runnable, 5).await;
12937        let err = result.reassignments().get().await.unwrap_err();
12938        assert_eq!(err.error(), Errors::ClusterAuthorizationFailed);
12939        assert_eq!(err.message(), default_text);
12940    }
12941
12942    /// Mirrors the unrepresentable-topic scenario of `testAlterPartitionReassignments`.
12943    #[tokio::test]
12944    async fn test_alter_partition_reassignments_unrepresentable() {
12945        let (admin, mut runnable, _time, _nodes) = env();
12946        let invalid_topic = TopicPartition::new("", 0);
12947        let invalid_partition = TopicPartition::new("ABC", -1);
12948        let valid = TopicPartition::new("A", 0);
12949        let mut reassignments = HashMap::new();
12950        reassignments.insert(
12951            invalid_partition.clone(),
12952            Some(NewPartitionReassignment::new(vec![1, 2, 3]).unwrap()),
12953        );
12954        reassignments.insert(
12955            invalid_topic.clone(),
12956            Some(NewPartitionReassignment::new(vec![1, 2, 3]).unwrap()),
12957        );
12958        reassignments.insert(valid.clone(), Some(NewPartitionReassignment::new(vec![1, 2, 3]).unwrap()));
12959
12960        runnable.client_mut().prepare_response(alter_reassignments_resp(
12961            Errors::None,
12962            None,
12963            vec![reassignable_topic_response("A", &[(0, Errors::None, None)])],
12964        ));
12965        let result =
12966            admin.alter_partition_reassignments_with_options(&reassignments, AlterPartitionReassignmentsOptions::new());
12967        pump(&mut runnable, 5).await;
12968        assert_eq!(
12969            result.values()[&invalid_topic].get().await.unwrap_err().error(),
12970            Errors::InvalidTopicError
12971        );
12972        assert_eq!(
12973            result.values()[&invalid_partition].get().await.unwrap_err().error(),
12974            Errors::InvalidTopicError
12975        );
12976        result.values()[&valid].get().await.unwrap();
12977    }
12978
12979    /// Mirrors the NOT_CONTROLLER scenario of `testAlterPartitionReassignments`.
12980    #[tokio::test]
12981    async fn test_alter_partition_reassignments_not_controller() {
12982        let (admin, mut runnable, time, nodes) = env();
12983        runnable.client_mut().prepare_response(alter_reassignments_resp(
12984            Errors::NotController,
12985            Some(Errors::NotController.message()),
12986            vec![
12987                reassignable_topic_response("A", &[(0, Errors::None, None)]),
12988                reassignable_topic_response("B", &[(0, Errors::None, None)]),
12989            ],
12990        ));
12991        runnable
12992            .client_mut()
12993            .prepare_response(ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
12994                &nodes,
12995                Some("mock-cluster"),
12996                1,
12997                Vec::new(),
12998            )));
12999        runnable.client_mut().prepare_response(alter_reassignments_resp(
13000            Errors::None,
13001            None,
13002            vec![
13003                reassignable_topic_response("A", &[(0, Errors::None, None)]),
13004                reassignable_topic_response("B", &[(0, Errors::None, None)]),
13005            ],
13006        ));
13007        let result = admin.alter_partition_reassignments_with_options(
13008            &reassignments_input(),
13009            AlterPartitionReassignmentsOptions::new(),
13010        );
13011        for _ in 0..30 {
13012            if result.all().is_done() {
13013                break;
13014            }
13015            runnable.run_once().await;
13016            time.sleep(200);
13017        }
13018        result.all().get().await.unwrap();
13019        result.values()[&TopicPartition::new("A", 0)].get().await.unwrap();
13020        result.values()[&TopicPartition::new("B", 0)].get().await.unwrap();
13021    }
13022
13023    fn ongoing_topic(name: &str, partition: i32) -> OngoingTopicReassignment {
13024        let mut pr = OngoingPartitionReassignment::new();
13025        pr.set_partition_index(partition);
13026        pr.set_replicas(vec![1, 2, 3, 4, 5, 6]);
13027        pr.set_adding_replicas(vec![4, 5, 6]);
13028        pr.set_removing_replicas(vec![1, 2, 3]);
13029        let mut topic = OngoingTopicReassignment::new();
13030        topic.set_name(name.to_string());
13031        topic.set_partitions(vec![pr]);
13032        topic
13033    }
13034
13035    fn list_reassignments_resp(top_error: Errors, topics: Vec<OngoingTopicReassignment>) -> ConcreteResponse {
13036        let mut data = ListPartitionReassignmentsResponseData::new();
13037        data.set_error_code(top_error.code());
13038        data.set_error_message(Some(top_error.message().to_string()));
13039        data.set_topics(topics);
13040        ConcreteResponse::ListPartitionReassignments(ListPartitionReassignmentsResponse::new(data))
13041    }
13042
13043    /// Mirrors `KafkaAdminClientTest.testListPartitionReassignments`.
13044    #[tokio::test]
13045    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testListPartitionReassignments")]
13046    async fn test_list_partition_reassignments() {
13047        let tp1 = TopicPartition::new("A", 0);
13048        let tp2 = TopicPartition::new("B", 0);
13049
13050        // 1. NOT_CONTROLLER handling then success.
13051        let (admin, mut runnable, time, nodes) = env();
13052        runnable
13053            .client_mut()
13054            .prepare_response(list_reassignments_resp(Errors::NotController, Vec::new()));
13055        runnable
13056            .client_mut()
13057            .prepare_response(ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
13058                &nodes,
13059                Some("mock-cluster"),
13060                1,
13061                Vec::new(),
13062            )));
13063        runnable.client_mut().prepare_response(list_reassignments_resp(
13064            Errors::None,
13065            vec![ongoing_topic("A", 0), ongoing_topic("B", 0)],
13066        ));
13067        let result =
13068            admin.list_partition_reassignments_with_partitions_options(None, ListPartitionReassignmentsOptions::new());
13069        for _ in 0..30 {
13070            if result.reassignments().is_done() {
13071                break;
13072            }
13073            runnable.run_once().await;
13074            time.sleep(200);
13075        }
13076        result.reassignments().get().await.unwrap();
13077
13078        // 2. UNKNOWN_TOPIC_OR_PARTITION.
13079        let (admin, mut runnable, _time, _nodes) = env();
13080        runnable
13081            .client_mut()
13082            .prepare_response(list_reassignments_resp(Errors::UnknownTopicOrPartition, Vec::new()));
13083        let partitions: HashSet<TopicPartition> = [tp1.clone(), tp2.clone()].into_iter().collect();
13084        let result = admin.list_partition_reassignments_with_partitions_options(
13085            Some(partitions),
13086            ListPartitionReassignmentsOptions::new(),
13087        );
13088        pump(&mut runnable, 5).await;
13089        assert_eq!(
13090            result.reassignments().get().await.unwrap_err().error(),
13091            Errors::UnknownTopicOrPartition
13092        );
13093
13094        // 3. Success — the ongoing reassignments are mapped per partition.
13095        let (admin, mut runnable, _time, _nodes) = env();
13096        runnable.client_mut().prepare_response(list_reassignments_resp(
13097            Errors::None,
13098            vec![ongoing_topic("A", 0), ongoing_topic("B", 0)],
13099        ));
13100        let result =
13101            admin.list_partition_reassignments_with_partitions_options(None, ListPartitionReassignmentsOptions::new());
13102        pump(&mut runnable, 5).await;
13103        let reassignments = result.reassignments().get().await.unwrap();
13104        assert_eq!(reassignments[&tp1].adding_replicas(), &[4, 5, 6]);
13105        assert_eq!(reassignments[&tp1].removing_replicas(), &[1, 2, 3]);
13106        assert_eq!(reassignments[&tp1].replicas(), &[1, 2, 3, 4, 5, 6]);
13107        assert_eq!(reassignments[&tp2].replicas(), &[1, 2, 3, 4, 5, 6]);
13108    }
13109
13110    fn list_offsets_resp_from(results: &[(TopicPartition, Errors, i64, i64, i32)]) -> ConcreteResponse {
13111        let mut data = ListOffsetsResponseData::new();
13112        let topics = results
13113            .iter()
13114            .map(|(tp, error, timestamp, offset, epoch)| {
13115                ListOffsetsResponse::singleton_list_offsets_topic_response(tp, *error, *timestamp, *offset, *epoch)
13116            })
13117            .collect();
13118        data.set_topics(topics);
13119        ConcreteResponse::ListOffsets(ListOffsetsResponse::new(data))
13120    }
13121
13122    /// Mirrors `KafkaAdminClientTest.testListOffsets`.
13123    #[tokio::test]
13124    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testListOffsets")]
13125    async fn test_list_offsets() {
13126        let (admin, mut runnable, _time, nodes) = env();
13127        let tp0 = TopicPartition::new("foo", 0);
13128        let tp1 = TopicPartition::new("bar", 0);
13129        let tp2 = TopicPartition::new("baz", 0);
13130        let tp3 = TopicPartition::new("qux", 0);
13131        // Lookup: all partitions lead by node0.
13132        runnable.client_mut().prepare_response(metadata_resp(
13133            &nodes,
13134            vec![
13135                topic_meta_leaders("foo", &[(0, 0)]),
13136                topic_meta_leaders("bar", &[(0, 0)]),
13137                topic_meta_leaders("baz", &[(0, 0)]),
13138                topic_meta_leaders("qux", &[(0, 0)]),
13139            ],
13140        ));
13141        runnable.client_mut().prepare_response(list_offsets_resp_from(&[
13142            (tp0.clone(), Errors::None, -1, 123, 321),
13143            (tp1.clone(), Errors::None, -1, 234, 432),
13144            (tp2.clone(), Errors::None, 123456789, 345, 543),
13145            (tp3.clone(), Errors::None, 234567890, 456, 654),
13146        ]));
13147
13148        let mut partitions = HashMap::new();
13149        partitions.insert(tp0.clone(), OffsetSpec::latest());
13150        partitions.insert(tp1.clone(), OffsetSpec::earliest());
13151        partitions.insert(tp2.clone(), OffsetSpec::for_timestamp(1_000_000));
13152        partitions.insert(tp3.clone(), OffsetSpec::max_timestamp());
13153        let result = admin.list_offsets_with_options(&partitions, ListOffsetsOptions::new());
13154        pump_until(&mut runnable, 40, |_r| result.all().is_done()).await;
13155
13156        let offsets = result.all().get().await.unwrap();
13157        assert_eq!(offsets[&tp0].offset(), 123);
13158        assert_eq!(offsets[&tp0].leader_epoch(), Some(321));
13159        assert_eq!(offsets[&tp0].timestamp(), -1);
13160        assert_eq!(offsets[&tp1].offset(), 234);
13161        assert_eq!(offsets[&tp2].offset(), 345);
13162        assert_eq!(offsets[&tp2].timestamp(), 123456789);
13163        assert_eq!(offsets[&tp3].offset(), 456);
13164        assert_eq!(offsets[&tp3].timestamp(), 234567890);
13165        assert_eq!(result.partition_result(&tp0).unwrap().get().await.unwrap().offset(), 123);
13166        // A partition that was not attempted yields an error.
13167        assert!(result.partition_result(&TopicPartition::new("unknown", 0)).is_err());
13168    }
13169
13170    /// Mirrors `KafkaAdminClientTest.testListOffsetsNonRetriableErrors`.
13171    #[tokio::test]
13172    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testListOffsetsNonRetriableErrors")]
13173    async fn test_list_offsets_non_retriable_errors() {
13174        let (admin, mut runnable, _time, nodes) = env();
13175        let tp0 = TopicPartition::new("foo", 0);
13176        runnable
13177            .client_mut()
13178            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 0)])]));
13179        runnable.client_mut().prepare_response(list_offsets_resp_from(&[(
13180            tp0.clone(),
13181            Errors::TopicAuthorizationFailed,
13182            -1,
13183            -1,
13184            -1,
13185        )]));
13186        let mut partitions = HashMap::new();
13187        partitions.insert(tp0.clone(), OffsetSpec::latest());
13188        let result = admin.list_offsets_with_options(&partitions, ListOffsetsOptions::new());
13189        pump_until(&mut runnable, 40, |_r| result.all().is_done()).await;
13190        assert_eq!(result.all().get().await.unwrap_err().error(), Errors::TopicAuthorizationFailed);
13191    }
13192
13193    /// Mirrors `KafkaAdminClientTest.testListOffsetsRetriableErrors`: a
13194    /// LEADER_NOT_AVAILABLE partition triggers a metadata re-lookup then a retry.
13195    #[tokio::test]
13196    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testListOffsetsRetriableErrors")]
13197    async fn test_list_offsets_retriable_errors() {
13198        let (admin, mut runnable, time, nodes) = env();
13199        let tp0 = TopicPartition::new("foo", 0);
13200        let tp1 = TopicPartition::new("foo", 1);
13201        let tp2 = TopicPartition::new("bar", 0);
13202        // Lookup: foo-0/foo-1 -> node0, bar-0 -> node1.
13203        runnable.client_mut().prepare_response(metadata_resp(
13204            &nodes,
13205            vec![
13206                topic_meta_leaders("foo", &[(0, 0), (1, 0)]),
13207                topic_meta_leaders("bar", &[(0, 1)]),
13208            ],
13209        ));
13210        // node0 fulfillment: foo-0 LEADER_NOT_AVAILABLE (re-lookup), foo-1 ok.
13211        runnable.client_mut().prepare_response_from(
13212            list_offsets_resp_from(&[
13213                (tp0.clone(), Errors::LeaderNotAvailable, -1, 123, 321),
13214                (tp1.clone(), Errors::None, -1, 987, 789),
13215            ]),
13216            &nodes[0],
13217        );
13218        // node1 fulfillment: bar-0 ok.
13219        runnable
13220            .client_mut()
13221            .prepare_response_from(list_offsets_resp_from(&[(tp2.clone(), Errors::None, -1, 456, 654)]), &nodes[1]);
13222        // metadata re-lookup for the unmapped foo-0.
13223        runnable
13224            .client_mut()
13225            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 0), (1, 0)])]));
13226        // node0 fulfillment retry: foo-0 ok.
13227        runnable
13228            .client_mut()
13229            .prepare_response_from(list_offsets_resp_from(&[(tp0.clone(), Errors::None, -1, 345, 543)]), &nodes[0]);
13230
13231        let mut partitions = HashMap::new();
13232        partitions.insert(tp0.clone(), OffsetSpec::latest());
13233        partitions.insert(tp1.clone(), OffsetSpec::latest());
13234        partitions.insert(tp2.clone(), OffsetSpec::latest());
13235        let result = admin.list_offsets_with_options(&partitions, ListOffsetsOptions::new());
13236        for _ in 0..60 {
13237            if result.all().is_done() {
13238                break;
13239            }
13240            runnable.run_once().await;
13241            time.sleep(100);
13242        }
13243        let offsets = result.all().get().await.unwrap();
13244        assert_eq!(offsets[&tp0].offset(), 345);
13245        assert_eq!(offsets[&tp1].offset(), 987);
13246        assert_eq!(offsets[&tp2].offset(), 456);
13247    }
13248
13249    /// Mirrors `KafkaAdminClientTest.testListOffsetsMaxTimestampUnsupportedSingleOffsetSpec`.
13250    #[tokio::test]
13251    #[doc(
13252        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testListOffsetsMaxTimestampUnsupportedSingleOffsetSpec"
13253    )]
13254    async fn test_list_offsets_max_timestamp_unsupported_single_offset_spec() {
13255        let (admin, mut runnable, _time, nodes) = env();
13256        let tp0 = TopicPartition::new("foo", 0);
13257        runnable
13258            .client_mut()
13259            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 0)])]));
13260        runnable.client_mut().prepare_unsupported_version_response();
13261        let mut partitions = HashMap::new();
13262        partitions.insert(tp0.clone(), OffsetSpec::max_timestamp());
13263        let result = admin.list_offsets_with_options(&partitions, ListOffsetsOptions::new());
13264        pump_until(&mut runnable, 40, |_r| result.all().is_done()).await;
13265        assert_eq!(result.all().get().await.unwrap_err().error(), Errors::UnsupportedVersion);
13266    }
13267
13268    /// Mirrors `KafkaAdminClientTest.testListOffsetsMaxTimestampUnsupportedMultipleOffsetSpec`:
13269    /// only the MAX_TIMESTAMP partition fails; the other is retried and succeeds.
13270    #[tokio::test]
13271    #[doc(
13272        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testListOffsetsMaxTimestampUnsupportedMultipleOffsetSpec"
13273    )]
13274    async fn test_list_offsets_max_timestamp_unsupported_multiple_offset_spec() {
13275        let (admin, mut runnable, time, nodes) = env();
13276        let tp0 = TopicPartition::new("foo", 0);
13277        let tp1 = TopicPartition::new("foo", 1);
13278        runnable
13279            .client_mut()
13280            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 0), (1, 0)])]));
13281        runnable.client_mut().prepare_unsupported_version_response();
13282        // Retry for the non-max partition succeeds.
13283        runnable
13284            .client_mut()
13285            .prepare_response_from(list_offsets_resp_from(&[(tp1.clone(), Errors::None, -1, 345, 543)]), &nodes[0]);
13286        let mut partitions = HashMap::new();
13287        partitions.insert(tp0.clone(), OffsetSpec::max_timestamp());
13288        partitions.insert(tp1.clone(), OffsetSpec::latest());
13289        let result = admin.list_offsets_with_options(&partitions, ListOffsetsOptions::new());
13290        for _ in 0..60 {
13291            if result.partition_result(&tp0).unwrap().is_done() && result.partition_result(&tp1).unwrap().is_done() {
13292                break;
13293            }
13294            runnable.run_once().await;
13295            time.sleep(100);
13296        }
13297        assert_eq!(
13298            result.partition_result(&tp0).unwrap().get().await.unwrap_err().error(),
13299            Errors::UnsupportedVersion
13300        );
13301        assert_eq!(result.partition_result(&tp1).unwrap().get().await.unwrap().offset(), 345);
13302    }
13303
13304    /// Mirrors `KafkaAdminClientTest.testListOffsetsPartialResponse`: the leader
13305    /// omits a result for one partition, which fails the sanity check.
13306    #[tokio::test]
13307    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testListOffsetsPartialResponse")]
13308    async fn test_list_offsets_partial_response() {
13309        let (admin, mut runnable, _time, nodes) = env();
13310        let tp0 = TopicPartition::new("foo", 0);
13311        let tp1 = TopicPartition::new("foo", 1);
13312        runnable
13313            .client_mut()
13314            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 0), (1, 0)])]));
13315        // Only tp0 is present; tp1 is omitted.
13316        runnable
13317            .client_mut()
13318            .prepare_response(list_offsets_resp_from(&[(tp0.clone(), Errors::None, -2, 123, 456)]));
13319        let mut partitions = HashMap::new();
13320        partitions.insert(tp0.clone(), OffsetSpec::latest());
13321        partitions.insert(tp1.clone(), OffsetSpec::latest());
13322        let result = admin.list_offsets_with_options(&partitions, ListOffsetsOptions::new());
13323        pump_until(&mut runnable, 40, |_r| result.all().is_done()).await;
13324        assert!(result.partition_result(&tp0).unwrap().get().await.is_ok());
13325        assert!(result.partition_result(&tp1).unwrap().get().await.is_err());
13326        assert!(result.all().get().await.is_err());
13327    }
13328
13329    /// Translated from `testListOffsetsHandlesFulfillmentTimeouts`: a partition
13330    /// whose `ListOffsets` keeps answering `REQUEST_TIMED_OUT` is retried until its
13331    /// fulfillment `tries` exceed `retries`, when
13332    /// `KafkaAdminClient.AdminClientRunnable#enqueue` fails it with
13333    /// `TimeoutException("Exceeded maxRetries after " + tries + " tries.")`, while
13334    /// the partition that succeeded keeps its result. One timeout fewer lets both
13335    /// partitions succeed.
13336    ///
13337    /// Java asserts only the exception class; the message is asserted here as
13338    /// well, so the failure cannot be the API timeout's.
13339    #[tokio::test]
13340    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testListOffsetsHandlesFulfillmentTimeouts")]
13341    async fn test_list_offsets_handles_fulfillment_timeouts() {
13342        let num_retries: i32 = 2;
13343        let (admin, mut runnable, time, nodes) = env_nodes_with_props(1, &[("retries", &num_retries.to_string())]);
13344        let node = nodes[0].clone();
13345        let tp0 = TopicPartition::new("foo", 0);
13346        let tp1 = TopicPartition::new("foo", 1);
13347        let metadata = || metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 0), (1, 0)])]);
13348        let is_list_offsets: fn() -> crate::RequestMatcher =
13349            || Box::new(|body: &AbstractRequest| matches!(body, AbstractRequest::ListOffsets(_)));
13350        let response_with_error = || {
13351            list_offsets_resp_from(&[
13352                (tp0.clone(), Errors::RequestTimedOut, -1, -1, -1),
13353                (tp1.clone(), Errors::None, -1, 345, 543),
13354            ])
13355        };
13356        let response = || {
13357            list_offsets_resp_from(&[
13358                (tp0.clone(), Errors::None, -1, 789, 987),
13359                (tp1.clone(), Errors::None, -1, 345, 543),
13360            ])
13361        };
13362        let partitions = HashMap::from([(tp0.clone(), OffsetSpec::latest()), (tp1.clone(), OffsetSpec::latest())]);
13363
13364        // Test that one-too-many timeouts for partition 0 result in partial success overall -
13365        // timeout for partition 0 and success for partition 1.
13366
13367        // It might be desirable to have the AdminApiDriver mechanism also handle all retriable
13368        // exceptions like TimeoutException during the lookup stage (it currently doesn't).
13369        runnable.client_mut().prepare_response(metadata());
13370        for _ in 0..num_retries + 1 {
13371            runnable
13372                .client_mut()
13373                .prepare_response_from_matcher(is_list_offsets(), response_with_error(), &node);
13374        }
13375        let result = admin.list_offsets(&partitions);
13376        let tp0_future = result.partition_result(&tp0).unwrap();
13377        let tp1_future = result.partition_result(&tp1).unwrap();
13378        drive_until(&mut runnable, &time, 100, || tp0_future.is_done() && tp1_future.is_done()).await;
13379        assert!(tp0_future.is_done(), "partition 0 must fail once out of retries");
13380        let err = tp0_future.get().await.expect_err("partition 0 runs out of retries");
13381        assert!(matches!(err, Error::Timeout(_)), "got {err:?}");
13382        assert_eq!(err.message(), "Exceeded maxRetries after 3 tries.");
13383        let tp1_result = tp1_future.get().await.unwrap();
13384        assert_eq!(tp1_result.offset(), 345);
13385        assert_eq!(tp1_result.leader_epoch(), Some(543));
13386        assert_eq!(tp1_result.timestamp(), -1);
13387
13388        // Now test that only numRetries timeouts for partition 0 result in success for both
13389        // partition 0 and partition 1.
13390        runnable.client_mut().prepare_response(metadata());
13391        for _ in 0..num_retries {
13392            runnable
13393                .client_mut()
13394                .prepare_response_from_matcher(is_list_offsets(), response_with_error(), &node);
13395        }
13396        runnable
13397            .client_mut()
13398            .prepare_response_from_matcher(is_list_offsets(), response(), &node);
13399        let result = admin.list_offsets(&partitions);
13400        let tp0_future = result.partition_result(&tp0).unwrap();
13401        let tp1_future = result.partition_result(&tp1).unwrap();
13402        drive_until(&mut runnable, &time, 100, || tp0_future.is_done() && tp1_future.is_done()).await;
13403        let tp0_result = tp0_future.get().await.unwrap();
13404        assert_eq!(tp0_result.offset(), 789);
13405        assert_eq!(tp0_result.leader_epoch(), Some(987));
13406        assert_eq!(tp0_result.timestamp(), -1);
13407        let tp1_result = tp1_future.get().await.unwrap();
13408        assert_eq!(tp1_result.offset(), 345);
13409        assert_eq!(tp1_result.leader_epoch(), Some(543));
13410        assert_eq!(tp1_result.timestamp(), -1);
13411    }
13412
13413    /// KAFKA-20673. Reproduces the scenario where the partition-leader cache
13414    /// holds an entry pointing at a broker that has since left the cluster (for
13415    /// example after a broker is recycled with a new id). The cached leader
13416    /// sends the request straight to the fulfillment stage, but the admin client
13417    /// can never route it because the broker is no longer in the metadata.
13418    /// Without re-running the lookup, the call would sit unassigned until the
13419    /// request deadline expires and fail with "Timed out waiting for a node
13420    /// assignment". The admin client should instead re-resolve the leader and
13421    /// complete the request.
13422    ///
13423    /// Mirrors `KafkaAdminClientTest.testListOffsetsRetriesLookupWhenCachedLeaderLeavesCluster`.
13424    /// Java drops node1 by letting the periodic broker-info metadata refresh
13425    /// (driven by `metadata.max.age.ms=50`) observe a shrunk cluster; the Rust
13426    /// pump harness does not drive that refresh automatically, so the test
13427    /// reproduces the same observable precondition — node1 absent from the ready
13428    /// metadata — by updating the shared `AdminMetadataManager` cluster directly
13429    /// between the two calls. Everything else (cache seeding on the first call,
13430    /// the stale fulfillment fast-path on the second, the re-lookup, and the
13431    /// completion) exercises the production code path unchanged.
13432    #[tokio::test]
13433    #[doc(
13434        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTopicTest#testListOffsetsRetriesLookupWhenCachedLeaderLeavesCluster"
13435    )]
13436    async fn test_list_offsets_retries_lookup_when_cached_leader_leaves_cluster() {
13437        // node0 and node1 both exist initially; foo-0 is led by node1.
13438        // A large metadata.max.age.ms + retry.backoff.ms keeps the periodic
13439        // broker-info metadata refresh from firing during the pump (the
13440        // `request_update` that the stale ConstantNodeId provider schedules
13441        // would otherwise consume the prepared topic-metadata response), so
13442        // node1's departure is driven solely by the direct metadata update
13443        // below.
13444        let (admin, mut runnable, time, nodes) =
13445            env_with_props(&[("metadata.max.age.ms", "300000"), ("retry.backoff.ms", "300000")]);
13446        let node0 = nodes[0].clone();
13447        let node1 = nodes[1].clone();
13448        let tp0 = TopicPartition::new("foo", 0);
13449
13450        // First call: the lookup resolves foo-0 to node1 (and caches it), then
13451        // the offsets fetch succeeds on node1.
13452        runnable
13453            .client_mut()
13454            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 1)])]));
13455        runnable
13456            .client_mut()
13457            .prepare_response_from(list_offsets_resp_from(&[(tp0.clone(), Errors::None, -1, 100, 5)]), &node1);
13458
13459        let mut partitions = HashMap::new();
13460        partitions.insert(tp0.clone(), OffsetSpec::latest());
13461        let first = admin.list_offsets_with_options(&partitions, ListOffsetsOptions::new());
13462        pump_until(&mut runnable, 40, |_r| first.all().is_done()).await;
13463        assert_eq!(first.all().get().await.unwrap()[&tp0].offset(), 100);
13464
13465        // node1 leaves the cluster: foo-0 is now led by node0, and node1 is gone
13466        // from the admin client's metadata. The partition-leader cache still
13467        // points foo-0 at node1.
13468        let shrunk = Cluster::with_invalid_topics_controller_topic_ids(
13469            Some("mock-cluster".to_string()),
13470            vec![node0.clone()],
13471            Vec::new(),
13472            HashSet::new(),
13473            HashSet::new(),
13474            HashSet::new(),
13475            Some(node0.clone()),
13476            HashMap::new(),
13477        );
13478        admin.shared.metadata_manager.update(shrunk, admin.shared.time.milliseconds());
13479
13480        // Second call: the cache sends foo-0 straight to fulfillment on node1,
13481        // which is gone. The admin client must re-resolve the leader (now node0)
13482        // via a fresh lookup rather than getting stuck until the deadline.
13483        runnable.client_mut().prepare_response(metadata_resp(
13484            std::slice::from_ref(&node0),
13485            vec![topic_meta_leaders("foo", &[(0, 0)])],
13486        ));
13487        runnable
13488            .client_mut()
13489            .prepare_response_from(list_offsets_resp_from(&[(tp0.clone(), Errors::None, -1, 200, 5)]), &node0);
13490
13491        let second = admin.list_offsets_with_options(&partitions, ListOffsetsOptions::new());
13492        for _ in 0..60 {
13493            if second.all().is_done() {
13494                break;
13495            }
13496            runnable.run_once().await;
13497            time.sleep(20);
13498        }
13499        assert!(
13500            second.all().is_done(),
13501            "second listOffsets did not recover after the cached leader left the cluster"
13502        );
13503        assert_eq!(second.all().get().await.unwrap()[&tp0].offset(), 200);
13504    }
13505
13506    /// KAFKA-20673 follow-up (cb2f143b0d), which Java ships without a test: once
13507    /// `close(timeout)` has set a hard-shutdown time, a fulfillment call whose
13508    /// cached leader left the cluster is NOT sent back to the lookup stage.
13509    /// Re-running the lookup would enqueue through `CallSender::call`, which
13510    /// rejects every call during close, so the request would fail at once with
13511    /// "Cannot accept new calls when AdminClient is closing." instead of staying
13512    /// pending for the grace period. Same precondition as
13513    /// [`test_list_offsets_retries_lookup_when_cached_leader_leaves_cluster`].
13514    #[tokio::test]
13515    async fn test_list_offsets_skips_stale_leader_lookup_retry_while_closing() {
13516        let (admin, mut runnable, time, nodes) =
13517            env_with_props(&[("metadata.max.age.ms", "300000"), ("retry.backoff.ms", "300000")]);
13518        let node0 = nodes[0].clone();
13519        let node1 = nodes[1].clone();
13520        let tp0 = TopicPartition::new("foo", 0);
13521
13522        runnable
13523            .client_mut()
13524            .prepare_response(metadata_resp(&nodes, vec![topic_meta_leaders("foo", &[(0, 1)])]));
13525        runnable
13526            .client_mut()
13527            .prepare_response_from(list_offsets_resp_from(&[(tp0.clone(), Errors::None, -1, 100, 5)]), &node1);
13528        let mut partitions = HashMap::new();
13529        partitions.insert(tp0.clone(), OffsetSpec::latest());
13530        let first = admin.list_offsets_with_options(&partitions, ListOffsetsOptions::new());
13531        pump_until(&mut runnable, 40, |_r| first.all().is_done()).await;
13532        assert_eq!(first.all().get().await.unwrap()[&tp0].offset(), 100);
13533
13534        let shrunk = Cluster::with_invalid_topics_controller_topic_ids(
13535            Some("mock-cluster".to_string()),
13536            vec![node0.clone()],
13537            Vec::new(),
13538            HashSet::new(),
13539            HashSet::new(),
13540            HashSet::new(),
13541            Some(node0.clone()),
13542            HashMap::new(),
13543        );
13544        admin.shared.metadata_manager.update(shrunk, admin.shared.time.milliseconds());
13545
13546        // Submit the second call, then begin closing with a long grace period
13547        // (the hard-shutdown time `close(timeout)` publishes first).
13548        let second = admin.list_offsets_with_options(&partitions, ListOffsetsOptions::new());
13549        let grace_deadline = admin.shared.time.milliseconds() + 60_000;
13550        admin
13551            .shared
13552            .shutdown
13553            .hard_shutdown_deadline_ms
13554            .store(grace_deadline, std::sync::atomic::Ordering::Release);
13555        admin.shared.shutdown.closing.store(true, std::sync::atomic::Ordering::Release);
13556
13557        for _ in 0..20 {
13558            runnable.run_once().await;
13559            time.sleep(20);
13560        }
13561        assert!(
13562            !second.all().is_done(),
13563            "the stale-leader call must stay pending during the grace period, got {:?}",
13564            second.all().get().await
13565        );
13566        // Nothing is in flight: no re-lookup request was sent for the departed
13567        // leader.
13568        assert_eq!(runnable.client_mut().request_count(), 0);
13569    }
13570
13571    // Skipped `KafkaAdminClientTest` listOffsets slices (with rationale):
13572    // - testListOffsetsEarliestLocalSpecMinVersion / testListOffsetsLatestTierSpecSpecMinVersion
13573    //   / testListOffsetsEarliestPendingUploadSpecSpecMinVersion only assert the
13574    //   `oldestAllowedVersion()` of the built request (8 / 9 / 11). That version
13575    //   selection lives entirely in `ListOffsetsHandler::build_batched_request`
13576    //   and is covered directly by `list_offsets_handler::tests::build_request_allowed_versions`
13577    //   and the `list_offsets_request` builder tests — re-driving it end-to-end
13578    //   through the network mock would add no coverage.
13579
13580    /// The mock's `list_offsets` serves seeded beginning/end offsets and rejects
13581    /// timestamp specs.
13582    #[tokio::test]
13583    async fn test_mock_list_offsets() {
13584        let mock = mock_admin_client::Builder::new()
13585            .build()
13586            .expect("a fresh builder has one broker");
13587        let earliest = TopicPartition::new("t", 0);
13588        let latest = TopicPartition::new("t", 1);
13589        let ts = TopicPartition::new("t", 2);
13590        mock.update_beginning_offsets(HashMap::from([(earliest.clone(), 5)]));
13591        mock.update_end_offsets(HashMap::from([(latest.clone(), 99)]));
13592        let mut partitions = HashMap::new();
13593        partitions.insert(earliest.clone(), OffsetSpec::earliest());
13594        partitions.insert(latest.clone(), OffsetSpec::latest());
13595        partitions.insert(ts.clone(), OffsetSpec::for_timestamp(123));
13596        let result = mock.list_offsets_with_options(&partitions, ListOffsetsOptions::new());
13597        assert_eq!(result.partition_result(&earliest).unwrap().get().await.unwrap().offset(), 5);
13598        assert_eq!(result.partition_result(&latest).unwrap().get().await.unwrap().offset(), 99);
13599        assert!(result.partition_result(&ts).unwrap().get().await.is_err());
13600    }
13601
13602    /// The mock's `alter_partition_reassignments` / `list_partition_reassignments`
13603    /// track reassignments against added topics.
13604    #[tokio::test]
13605    async fn test_mock_partition_reassignments() {
13606        let mock = mock_admin_client::Builder::new()
13607            .set_num_brokers(3)
13608            .and_then(mock_admin_client::Builder::build)
13609            .expect("num_brokers is at least 1");
13610        let leader = Node::new(0, "localhost".to_string(), 1000);
13611        let replicas = vec![
13612            Node::new(0, "localhost".to_string(), 1000),
13613            Node::new(1, "localhost".to_string(), 1001),
13614        ];
13615        mock.add_topic(false, "topic", vec![mock_topic_partition_info(0, &leader, replicas)], None)
13616            .expect("seeding a topic with known brokers succeeds");
13617        let tp = TopicPartition::new("topic", 0);
13618        let mut reassignments = HashMap::new();
13619        reassignments.insert(tp.clone(), Some(NewPartitionReassignment::new(vec![1, 2]).unwrap()));
13620        let result =
13621            mock.alter_partition_reassignments_with_options(&reassignments, AlterPartitionReassignmentsOptions::new());
13622        result.values()[&tp].get().await.unwrap();
13623
13624        let listed = mock
13625            .list_partition_reassignments_with_partitions_options(None, ListPartitionReassignmentsOptions::new())
13626            .reassignments()
13627            .get()
13628            .await
13629            .unwrap();
13630        assert!(listed.contains_key(&tp));
13631        // target [1,2] vs current replicas [0,1]: adding 2, removing 0.
13632        assert_eq!(listed[&tp].adding_replicas(), &[2]);
13633        assert_eq!(listed[&tp].removing_replicas(), &[0]);
13634    }
13635
13636    /// The mock's `elect_leaders` mirrors Java's `UnsupportedOperationException`.
13637    #[tokio::test]
13638    async fn test_mock_elect_leaders_unsupported() {
13639        let mock = mock_admin_client::Builder::new()
13640            .build()
13641            .expect("a fresh builder has one broker");
13642        let result = mock.elect_leaders_with_options(ElectionType::Preferred, None, ElectLeadersOptions::new());
13643        let err = result.partitions().get().await.unwrap_err();
13644        assert!(err.is_local_unsupported_operation_error(), "{err:?}");
13645        assert_eq!(err.message(), "Not implemented yet");
13646    }
13647
13648    // ---- Group listing / describe (Tier 2 Phase 1) ----
13649
13650    fn listed_group(group_id: &str, protocol_type: &str, state: &str, group_type: &str) -> ConcreteResponse {
13651        use crate::ListGroupsResponseData;
13652        use crate::list_groups_response_data::ListedGroup;
13653        let mut g = ListedGroup::new();
13654        g.set_group_id(group_id.to_string())
13655            .set_protocol_type(protocol_type.to_string())
13656            .set_group_state(state.to_string())
13657            .set_group_type(group_type.to_string());
13658        let mut data = ListGroupsResponseData::new();
13659        data.set_groups(vec![g]);
13660        ConcreteResponse::ListGroups(crate::common::requests::ListGroupsResponse::new(data))
13661    }
13662
13663    fn empty_list_groups_resp() -> ConcreteResponse {
13664        use crate::ListGroupsResponseData;
13665        ConcreteResponse::ListGroups(crate::common::requests::ListGroupsResponse::new(ListGroupsResponseData::new()))
13666    }
13667
13668    fn find_coordinator_resp(entries: &[(&str, &Node)]) -> ConcreteResponse {
13669        use crate::FindCoordinatorResponseData;
13670        use crate::find_coordinator_response_data::Coordinator;
13671        let coordinators: Vec<Coordinator> = entries
13672            .iter()
13673            .map(|(key, node)| {
13674                let mut c = Coordinator::new();
13675                c.set_key(key.to_string())
13676                    .set_error_code(Errors::None.code())
13677                    .set_node_id(node.id())
13678                    .set_host(node.host().to_string())
13679                    .set_port(node.port());
13680                c
13681            })
13682            .collect();
13683        let mut data = FindCoordinatorResponseData::new();
13684        data.set_coordinators(coordinators);
13685        ConcreteResponse::FindCoordinator(crate::common::requests::FindCoordinatorResponse::new(data))
13686    }
13687
13688    fn consumer_group_describe_resp(group_id: &str) -> ConcreteResponse {
13689        use crate::ConsumerGroupDescribeResponseData;
13690        use crate::consumer_group_describe_response_data::DescribedGroup;
13691        let mut group = DescribedGroup::new();
13692        group
13693            .set_group_id(group_id.to_string())
13694            .set_group_state("Stable".to_string())
13695            .set_group_epoch(5)
13696            .set_assignment_epoch(5)
13697            .set_assignor_name("uniform".to_string());
13698        let mut data = ConsumerGroupDescribeResponseData::new();
13699        data.set_groups(vec![group]);
13700        ConcreteResponse::ConsumerGroupDescribe(crate::common::requests::ConsumerGroupDescribeResponse::new(data))
13701    }
13702
13703    fn consumer_group_describe_error_resp(group_id: &str, error: Errors, message: Option<&str>) -> ConcreteResponse {
13704        use crate::ConsumerGroupDescribeResponseData;
13705        use crate::consumer_group_describe_response_data::DescribedGroup;
13706        let mut group = DescribedGroup::new();
13707        group
13708            .set_group_id(group_id.to_string())
13709            .set_error_code(error.code())
13710            .set_error_message(message.map(str::to_string));
13711        let mut data = ConsumerGroupDescribeResponseData::new();
13712        data.set_groups(vec![group]);
13713        ConcreteResponse::ConsumerGroupDescribe(crate::common::requests::ConsumerGroupDescribeResponse::new(data))
13714    }
13715
13716    fn describe_groups_error_resp(group_id: &str, error: Errors, message: Option<&str>) -> ConcreteResponse {
13717        use crate::DescribeGroupsResponseData;
13718        use crate::describe_groups_response_data::DescribedGroup;
13719        let mut group = DescribedGroup::new();
13720        group
13721            .set_group_id(group_id.to_string())
13722            .set_error_code(error.code())
13723            .set_error_message(message.map(str::to_string));
13724        let mut data = DescribeGroupsResponseData::new();
13725        data.set_groups(vec![group]);
13726        ConcreteResponse::DescribeGroups(crate::common::requests::DescribeGroupsResponse::new(data))
13727    }
13728
13729    /// A `FindCoordinator` response carrying a single erroring coordinator for
13730    /// `key` (mirrors Java's `prepareFindCoordinatorResponse(error, key, Node.noNode())`
13731    /// for the retriable-error retry path).
13732    fn find_coordinator_error_resp(key: &str, error: Errors) -> ConcreteResponse {
13733        use crate::FindCoordinatorResponseData;
13734        use crate::find_coordinator_response_data::Coordinator;
13735        let mut c = Coordinator::new();
13736        c.set_key(key.to_string())
13737            .set_error_code(error.code())
13738            .set_node_id(-1)
13739            .set_host(String::new())
13740            .set_port(-1);
13741        let mut data = FindCoordinatorResponseData::new();
13742        data.set_coordinators(vec![c]);
13743        ConcreteResponse::FindCoordinator(crate::common::requests::FindCoordinatorResponse::new(data))
13744    }
13745
13746    /// A `DescribeGroups` member for a classic group (mirrors
13747    /// `DescribeGroupsResponseData.DescribedGroupMember`).
13748    fn described_member(
13749        member_id: &str,
13750        group_instance_id: Option<&str>,
13751        client_id: &str,
13752        client_host: &str,
13753        member_assignment: Vec<u8>,
13754    ) -> crate::describe_groups_response_data::DescribedGroupMember {
13755        let mut m = crate::describe_groups_response_data::DescribedGroupMember::new();
13756        m.set_member_id(member_id.to_string())
13757            .set_group_instance_id(group_instance_id.map(str::to_string))
13758            .set_client_id(client_id.to_string())
13759            .set_client_host(client_host.to_string())
13760            .set_member_assignment(member_assignment);
13761        m
13762    }
13763
13764    /// A full (non-error) `DescribeGroups` response for the given groups.
13765    fn describe_groups_full_resp(
13766        groups: Vec<crate::describe_groups_response_data::DescribedGroup>,
13767    ) -> ConcreteResponse {
13768        use crate::DescribeGroupsResponseData;
13769        let mut data = DescribeGroupsResponseData::new();
13770        data.set_groups(groups);
13771        ConcreteResponse::DescribeGroups(crate::common::requests::DescribeGroupsResponse::new(data))
13772    }
13773
13774    /// Broker enumeration: `list_groups` fans out one `ListGroups` per broker and
13775    /// unions the results.
13776    #[tokio::test]
13777    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testListGroups")]
13778    async fn test_list_groups() {
13779        let (admin, mut runnable, _time, nodes) = env();
13780        runnable.client_mut().prepare_response(metadata_resp(&nodes, Vec::new()));
13781        runnable
13782            .client_mut()
13783            .prepare_response_from(listed_group("g1", "consumer", "Stable", "Consumer"), &nodes[0]);
13784        runnable
13785            .client_mut()
13786            .prepare_response_from(listed_group("g2", "consumer", "Stable", "Consumer"), &nodes[1]);
13787        runnable.client_mut().prepare_response_from(empty_list_groups_resp(), &nodes[2]);
13788
13789        let result = admin.list_groups_with_options(ListGroupsOptions::new());
13790        pump_until(&mut runnable, 40, |_r| result.valid().is_done()).await;
13791
13792        let mut ids: Vec<String> = result
13793            .valid()
13794            .get()
13795            .await
13796            .unwrap()
13797            .iter()
13798            .map(|g| g.group_id().to_string())
13799            .collect();
13800        ids.sort();
13801        assert_eq!(ids, vec!["g1".to_string(), "g2".to_string()]);
13802        assert!(result.errors().get().await.unwrap().is_empty());
13803    }
13804
13805    /// `list_groups`' protocol-type filter excludes non-matching groups.
13806    #[tokio::test]
13807    async fn test_list_groups_filters_protocol_type() {
13808        let (admin, mut runnable, _time, nodes) = env();
13809        runnable.client_mut().prepare_response(metadata_resp(&nodes, Vec::new()));
13810        runnable
13811            .client_mut()
13812            .prepare_response_from(listed_group("g1", "consumer", "Stable", "Consumer"), &nodes[0]);
13813        runnable
13814            .client_mut()
13815            .prepare_response_from(listed_group("connect", "connect", "Stable", "Classic"), &nodes[1]);
13816        runnable.client_mut().prepare_response_from(empty_list_groups_resp(), &nodes[2]);
13817
13818        let options = ListGroupsOptions::new().with_protocol_types(HashSet::from(["consumer".to_string()]));
13819        let result = admin.list_groups_with_options(options);
13820        pump_until(&mut runnable, 40, |_r| result.valid().is_done()).await;
13821
13822        let ids: Vec<String> = result
13823            .valid()
13824            .get()
13825            .await
13826            .unwrap()
13827            .iter()
13828            .map(|g| g.group_id().to_string())
13829            .collect();
13830        assert_eq!(ids, vec!["g1".to_string()]);
13831    }
13832
13833    /// Translated from `KafkaAdminClientTest.testListConsumerGroups`.
13834    ///
13835    /// `list_groups(for_consumer_groups())` fans out one `ListGroups` per broker:
13836    /// an empty metadata response is retried, retriable per-broker errors are
13837    /// retried, `connector` groups are filtered out by the protocol-type filter,
13838    /// and a fatal broker error is surfaced through `all()` / `errors()` while
13839    /// `valid()` still carries the three consumer groups.
13840    #[tokio::test]
13841    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testListConsumerGroups")]
13842    async fn test_list_consumer_groups() {
13843        fn list_groups_error(error: Errors) -> ConcreteResponse {
13844            use crate::ListGroupsResponseData;
13845            let mut data = ListGroupsResponseData::new();
13846            data.set_error_code(error.code());
13847            ConcreteResponse::ListGroups(crate::common::requests::ListGroupsResponse::new(data))
13848        }
13849
13850        let (admin, mut runnable, time, nodes) = env_nodes_with_props(4, &[("retries", "2")]);
13851        let consumer = ConsumerProtocol::PROTOCOL_TYPE;
13852
13853        // Empty metadata response should be retried
13854        runnable.client_mut().prepare_response(metadata_resp(&[], Vec::new()));
13855        runnable.client_mut().prepare_response(metadata_resp(&nodes, Vec::new()));
13856
13857        runnable.client_mut().prepare_response_from(
13858            listed_groups(&[
13859                ("group-1", consumer, "Stable", ""),
13860                ("group-connect-1", "connector", "Stable", ""),
13861            ]),
13862            &nodes[0],
13863        );
13864        // handle retriable errors
13865        runnable
13866            .client_mut()
13867            .prepare_response_from(list_groups_error(Errors::CoordinatorNotAvailable), &nodes[1]);
13868        runnable
13869            .client_mut()
13870            .prepare_response_from(list_groups_error(Errors::CoordinatorLoadInProgress), &nodes[1]);
13871        runnable.client_mut().prepare_response_from(
13872            listed_groups(&[
13873                ("group-2", consumer, "Stable", ""),
13874                ("group-connect-2", "connector", "Stable", ""),
13875            ]),
13876            &nodes[1],
13877        );
13878        runnable.client_mut().prepare_response_from(
13879            listed_groups(&[
13880                ("group-3", consumer, "Stable", ""),
13881                ("group-connect-3", "connector", "Stable", ""),
13882            ]),
13883            &nodes[2],
13884        );
13885        // fatal error
13886        runnable
13887            .client_mut()
13888            .prepare_response_from(list_groups_error(Errors::UnknownServerError), &nodes[3]);
13889
13890        let result = admin.list_groups_with_options(ListGroupsOptions::for_consumer_groups());
13891        for _ in 0..80 {
13892            if result.all().is_done() {
13893                break;
13894            }
13895            runnable.run_once().await;
13896            time.sleep(100);
13897        }
13898        assert_eq!(result.all().get().await.unwrap_err().error(), Errors::UnknownServerError);
13899
13900        let listings = result.valid().get().await.unwrap();
13901        assert_eq!(listings.len(), 3);
13902        let mut group_ids = HashSet::new();
13903        for listing in &listings {
13904            group_ids.insert(listing.group_id().to_string());
13905            assert!(listing.group_state().is_some());
13906        }
13907        assert_eq!(
13908            group_ids,
13909            HashSet::from(["group-1".to_string(), "group-2".to_string(), "group-3".to_string()])
13910        );
13911        assert_eq!(result.errors().get().await.unwrap().len(), 1);
13912    }
13913
13914    /// Translated from `KafkaAdminClientTest.testListGroupsWithTypes`.
13915    ///
13916    /// Asserts the emitted `ListGroups` request carries the types filter
13917    /// derived from `ListGroupsOptions::with_types`, then that both listings are
13918    /// returned.
13919    #[tokio::test]
13920    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testListGroupsWithTypes")]
13921    async fn test_list_groups_with_types() {
13922        use crate::common::requests::AbstractRequest;
13923
13924        let (admin, mut runnable, _time, nodes) = env_nodes_with_props(1, &[]);
13925        runnable.client_mut().prepare_response(metadata_resp(&nodes, Vec::new()));
13926
13927        let options = ListGroupsOptions::new().with_types(HashSet::from([GroupType::Consumer]));
13928        let result = admin.list_groups_with_options(options);
13929        pump_until_request_queued(&mut runnable).await;
13930
13931        // The single per-broker ListGroups request carries the types filter.
13932        {
13933            let reqs = runnable.client_mut().requests_mut();
13934            assert_eq!(reqs.len(), 1);
13935            match reqs[0].request_builder_mut().build().unwrap() {
13936                AbstractRequest::ListGroups(req) => {
13937                    assert!(req.data().states_filter.is_empty());
13938                    assert_eq!(req.data().types_filter, vec![GroupType::Consumer.to_string()]);
13939                },
13940                other => panic!("expected a ListGroups request, got {other:?}"),
13941            }
13942        }
13943
13944        runnable.client_mut().respond_from(
13945            listed_groups(&[
13946                ("group-1", ConsumerProtocol::PROTOCOL_TYPE, "Stable", "Consumer"),
13947                ("group-2", "", "Empty", "Consumer"),
13948            ]),
13949            &nodes[0],
13950        );
13951        pump_until(&mut runnable, 40, |_r| result.valid().is_done()).await;
13952
13953        let mut ids: Vec<String> = result
13954            .valid()
13955            .get()
13956            .await
13957            .unwrap()
13958            .iter()
13959            .map(|g| g.group_id().to_string())
13960            .collect();
13961        ids.sort();
13962        assert_eq!(ids, vec!["group-1".to_string(), "group-2".to_string()]);
13963        assert!(result.errors().get().await.unwrap().is_empty());
13964    }
13965
13966    /// Translated from `KafkaAdminClientTest.testListGroupsWithTypesOlderBrokerVersion`.
13967    ///
13968    /// A `SHARE`/`CONSUMER`-only types filter surfaces `UnsupportedVersion`
13969    /// (the broker's older `ListGroups` version cannot express it), while a
13970    /// `CLASSIC`-only filter is silently omitted at the older version and
13971    /// succeeds. The Rust `MockClient` does not negotiate API versions, so the
13972    /// broker-side downgrade is modeled two ways: the omit path is verified by
13973    /// building the emitted request at v4 (mirroring the negotiated version) and
13974    /// asserting the types filter is dropped, and the reject path is modeled
13975    /// with `prepare_unsupported_version_response` (the same version-mismatch
13976    /// response the real `NetworkClient` produces when the builder throws).
13977    #[tokio::test]
13978    #[doc(
13979        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testListGroupsWithTypesOlderBrokerVersion"
13980    )]
13981    async fn test_list_groups_with_types_older_broker_version() {
13982        use crate::common::requests::AbstractRequest;
13983
13984        let (admin, mut runnable, _time, nodes) = env_nodes_with_props(1, &[]);
13985
13986        // A SHARE-only filter cannot be omitted, so it surfaces UnsupportedVersion.
13987        runnable.client_mut().prepare_response(metadata_resp(&nodes, Vec::new()));
13988        runnable.client_mut().prepare_unsupported_version_response();
13989        let result =
13990            admin.list_groups_with_options(ListGroupsOptions::new().with_types(HashSet::from([GroupType::Share])));
13991        pump_until(&mut runnable, 40, |_r| result.all().is_done()).await;
13992        assert_eq!(result.all().get().await.unwrap_err().error(), Errors::UnsupportedVersion);
13993
13994        // A CLASSIC-only filter is omitted on an older broker and succeeds.
13995        runnable.client_mut().prepare_response(metadata_resp(&nodes, Vec::new()));
13996        let result =
13997            admin.list_groups_with_options(ListGroupsOptions::new().with_types(HashSet::from([GroupType::Classic])));
13998        pump_until_request_queued(&mut runnable).await;
13999        {
14000            let reqs = runnable.client_mut().requests_mut();
14001            assert_eq!(reqs.len(), 1);
14002            // At v5 the request still carries the classic types filter ...
14003            match reqs[0].request_builder_mut().build().unwrap() {
14004                AbstractRequest::ListGroups(req) => {
14005                    assert_eq!(req.data().types_filter, vec![GroupType::Classic.to_string()]);
14006                },
14007                other => panic!("expected a ListGroups request, got {other:?}"),
14008            }
14009            // ... but building at the older broker's v4 omits it (the request
14010            // succeeds against the older broker with an empty filter).
14011            match reqs[0].request_builder_mut().build_version(4).unwrap() {
14012                AbstractRequest::ListGroups(req) => assert!(req.data().types_filter.is_empty()),
14013                other => panic!("expected a ListGroups request, got {other:?}"),
14014            }
14015        }
14016        runnable.client_mut().respond_from(
14017            listed_groups(&[("group-1", ConsumerProtocol::PROTOCOL_TYPE, "Stable", "")]),
14018            &nodes[0],
14019        );
14020        pump_until(&mut runnable, 40, |_r| result.all().is_done()).await;
14021        let listings = result.all().get().await.unwrap();
14022        assert_eq!(listings.len(), 1);
14023        assert_eq!(listings[0].group_id(), "group-1");
14024
14025        // A CONSUMER-only filter (without classic) also surfaces UnsupportedVersion.
14026        runnable.client_mut().prepare_response(metadata_resp(&nodes, Vec::new()));
14027        runnable.client_mut().prepare_unsupported_version_response();
14028        let result =
14029            admin.list_groups_with_options(ListGroupsOptions::new().with_types(HashSet::from([GroupType::Consumer])));
14030        pump_until(&mut runnable, 40, |_r| result.all().is_done()).await;
14031        assert_eq!(result.all().get().await.unwrap_err().error(), Errors::UnsupportedVersion);
14032    }
14033
14034    /// Translated from `KafkaAdminClientTest.testListConsumerGroupsWithStates`.
14035    ///
14036    /// `for_consumer_groups()` derives a `[Classic, Consumer]` types filter; this
14037    /// asserts that filter reaches the wire request, then that both consumer
14038    /// groups are returned.
14039    #[tokio::test]
14040    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testListConsumerGroupsWithStates")]
14041    async fn test_list_consumer_groups_with_states() {
14042        use crate::common::requests::AbstractRequest;
14043
14044        let (admin, mut runnable, _time, nodes) = env_nodes_with_props(1, &[]);
14045        runnable.client_mut().prepare_response(metadata_resp(&nodes, Vec::new()));
14046
14047        let result = admin.list_groups_with_options(ListGroupsOptions::for_consumer_groups());
14048        pump_until_request_queued(&mut runnable).await;
14049        {
14050            let reqs = runnable.client_mut().requests_mut();
14051            match reqs[0].request_builder_mut().build().unwrap() {
14052                AbstractRequest::ListGroups(req) => {
14053                    let mut types = req.data().types_filter.clone();
14054                    types.sort();
14055                    assert_eq!(types, vec![GroupType::Classic.to_string(), GroupType::Consumer.to_string()]);
14056                },
14057                other => panic!("expected a ListGroups request, got {other:?}"),
14058            }
14059        }
14060
14061        runnable.client_mut().respond_from(
14062            listed_groups(&[
14063                ("group-1", ConsumerProtocol::PROTOCOL_TYPE, "Stable", ""),
14064                ("group-2", "", "Empty", ""),
14065            ]),
14066            &nodes[0],
14067        );
14068        pump_until(&mut runnable, 40, |_r| result.valid().is_done()).await;
14069        let mut ids: Vec<String> = result
14070            .valid()
14071            .get()
14072            .await
14073            .unwrap()
14074            .iter()
14075            .map(|g| g.group_id().to_string())
14076            .collect();
14077        ids.sort();
14078        assert_eq!(ids, vec!["group-1".to_string(), "group-2".to_string()]);
14079        assert!(result.errors().get().await.unwrap().is_empty());
14080    }
14081
14082    /// Translated from
14083    /// `KafkaAdminClientTest.testListConsumerGroupsWithTypesOlderBrokerVersion`.
14084    ///
14085    /// A states filter reaches a v4 broker (states are v4+), and a `SHARE` types
14086    /// filter surfaces `UnsupportedVersion` against the older broker.
14087    #[tokio::test]
14088    #[doc(
14089        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testListConsumerGroupsWithTypesOlderBrokerVersion"
14090    )]
14091    async fn test_list_consumer_groups_with_types_older_broker_version() {
14092        use crate::common::requests::AbstractRequest;
14093
14094        let (admin, mut runnable, _time, nodes) = env_nodes_with_props(1, &[]);
14095
14096        // States filter with no types filter is fine at v4.
14097        runnable.client_mut().prepare_response(metadata_resp(&nodes, Vec::new()));
14098        let result = admin
14099            .list_groups_with_options(ListGroupsOptions::new().in_group_states(HashSet::from([GroupState::Stable])));
14100        pump_until_request_queued(&mut runnable).await;
14101        {
14102            let reqs = runnable.client_mut().requests_mut();
14103            match reqs[0].request_builder_mut().build_version(4).unwrap() {
14104                AbstractRequest::ListGroups(req) => {
14105                    assert_eq!(req.data().states_filter, vec![GroupState::Stable.to_string()]);
14106                    assert!(req.data().types_filter.is_empty());
14107                },
14108                other => panic!("expected a ListGroups request, got {other:?}"),
14109            }
14110        }
14111        runnable.client_mut().respond_from(
14112            listed_groups(&[("group-1", ConsumerProtocol::PROTOCOL_TYPE, "Stable", "")]),
14113            &nodes[0],
14114        );
14115        pump_until(&mut runnable, 40, |_r| result.all().is_done()).await;
14116        assert_eq!(result.all().get().await.unwrap().len(), 1);
14117
14118        // A SHARE types filter cannot be set against the older broker.
14119        runnable.client_mut().prepare_response(metadata_resp(&nodes, Vec::new()));
14120        runnable.client_mut().prepare_unsupported_version_response();
14121        let result =
14122            admin.list_groups_with_options(ListGroupsOptions::new().with_types(HashSet::from([GroupType::Share])));
14123        pump_until(&mut runnable, 40, |_r| result.all().is_done()).await;
14124        assert_eq!(result.all().get().await.unwrap_err().error(), Errors::UnsupportedVersion);
14125    }
14126
14127    /// Translated from `KafkaAdminClientTest.testListConsumerGroupsMetadataFailure`.
14128    ///
14129    /// An empty metadata response leaves no brokers to send `ListGroups` to; with
14130    /// `retries=0` the metadata call fails terminally and `handle_failure` wraps
14131    /// it as "Failed to find brokers to send ListGroups".
14132    #[tokio::test]
14133    #[doc(
14134        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testListConsumerGroupsMetadataFailure"
14135    )]
14136    async fn test_list_consumer_groups_metadata_failure() {
14137        let (admin, mut runnable, time, _nodes) = env_nodes_with_props(3, &[("retries", "0")]);
14138        // Empty broker list → no brokers to send to.
14139        runnable.client_mut().prepare_response(metadata_resp(&[], Vec::new()));
14140
14141        let result = admin.list_groups_with_options(ListGroupsOptions::for_consumer_groups());
14142        for _ in 0..40 {
14143            if result.all().is_done() {
14144                break;
14145            }
14146            runnable.run_once().await;
14147            time.sleep(100);
14148        }
14149        let err = result.all().get().await.unwrap_err();
14150        // Java hardcodes "ListGroups" in the message
14151        // (`org.apache.kafka.clients.admin.KafkaAdminClient#listGroups`),
14152        // and `testListConsumerGroupsMetadataFailure` / `testListGroupsMetadataFailure`
14153        // assert only `KafkaException.class`. The Rust message used to substitute
14154        // the lower-cased Rust call name and append the cause's text (finding 243).
14155        assert_eq!(err.message(), "Failed to find brokers to send ListGroups");
14156        assert!(err.is_kafka_error(), "Java's assertFutureThrows(KafkaException.class): {err:?}");
14157        assert!(!err.is_api_error(), "a bare KafkaException is not an ApiException: {err:?}");
14158    }
14159
14160    /// Translated from `KafkaAdminClientTest.testListGroupsMetadataFailure`.
14161    #[tokio::test]
14162    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testListGroupsMetadataFailure")]
14163    async fn test_list_groups_metadata_failure() {
14164        let (admin, mut runnable, time, _nodes) = env_nodes_with_props(3, &[("retries", "0")]);
14165        runnable.client_mut().prepare_response(metadata_resp(&[], Vec::new()));
14166
14167        let result = admin.list_groups_with_options(ListGroupsOptions::new());
14168        for _ in 0..40 {
14169            if result.all().is_done() {
14170                break;
14171            }
14172            runnable.run_once().await;
14173            time.sleep(100);
14174        }
14175        let err = result.all().get().await.unwrap_err();
14176        // Java hardcodes "ListGroups" in the message
14177        // (`org.apache.kafka.clients.admin.KafkaAdminClient#listGroups`),
14178        // and `testListConsumerGroupsMetadataFailure` / `testListGroupsMetadataFailure`
14179        // assert only `KafkaException.class`. The Rust message used to substitute
14180        // the lower-cased Rust call name and append the cause's text (finding 243).
14181        assert_eq!(err.message(), "Failed to find brokers to send ListGroups");
14182        assert!(err.is_kafka_error(), "Java's assertFutureThrows(KafkaException.class): {err:?}");
14183        assert!(!err.is_api_error(), "a bare KafkaException is not an ApiException: {err:?}");
14184    }
14185
14186    /// `describe_consumer_groups` finds the coordinator then describes the group
14187    /// with the KIP-848 `ConsumerGroupDescribe` API.
14188    #[tokio::test]
14189    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDescribeConsumerGroups")]
14190    async fn test_describe_consumer_groups() {
14191        let (admin, mut runnable, _time, nodes) = env();
14192        runnable
14193            .client_mut()
14194            .prepare_response(find_coordinator_resp(&[("g1", &nodes[0])]));
14195        runnable
14196            .client_mut()
14197            .prepare_response_from(consumer_group_describe_resp("g1"), &nodes[0]);
14198
14199        let result =
14200            admin.describe_consumer_groups_with_options(&["g1".to_string()], DescribeConsumerGroupsOptions::new());
14201        let future = result.described_groups()["g1"].clone();
14202        pump_until(&mut runnable, 40, |_r| future.is_done()).await;
14203
14204        let description = future.get().await.unwrap();
14205        assert_eq!(description.group_id(), "g1");
14206        assert_eq!(description.r#type(), GroupType::Consumer);
14207        assert_eq!(description.group_state(), GroupState::Stable);
14208        assert_eq!(description.partition_assignor(), "uniform");
14209        // `coordinator()` is the Node the fulfillment request was routed to, and
14210        // Java hands the handler `Call.curNode()` — a fully resolved broker. The
14211        // whole endpoint must survive, not just the id: a fabricated
14212        // `Node::new(id, "", -1)` would still satisfy an id-only assertion.
14213        let coordinator = description.coordinator().expect("coordinator present");
14214        assert_eq!(coordinator.id(), 0);
14215        assert_eq!(coordinator.host(), "localhost");
14216        assert_eq!(coordinator.port(), 9092);
14217        assert_eq!(coordinator, &nodes[0]);
14218    }
14219
14220    /// Translated from `testDescribeConsumerGroupNumRetries`: with `retries=0`,
14221    /// the re-lookup a `NOT_COORDINATOR` describe triggers exceeds the retry
14222    /// budget. As in Java the describe response is a classic `DescribeGroups`
14223    /// one, prepared without a node or matcher, so it answers whichever describe
14224    /// request goes out first.
14225    #[tokio::test]
14226    #[doc(
14227        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDescribeConsumerGroupNumRetries"
14228    )]
14229    async fn test_describe_consumer_group_num_retries() {
14230        let (admin, mut runnable, time, nodes) = env_nodes_with_props(3, &[("retries", "0")]);
14231        runnable
14232            .client_mut()
14233            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
14234        runnable
14235            .client_mut()
14236            .prepare_response(describe_groups_error_resp(GROUP_ID, Errors::NotCoordinator, None));
14237        runnable
14238            .client_mut()
14239            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
14240
14241        let result = admin.describe_consumer_groups(&[GROUP_ID.to_string()]);
14242        let all = result.all();
14243        drive_until(&mut runnable, &time, 100, || all.is_done()).await;
14244        assert_exceeded_max_retries_after_one_try(&all).await;
14245    }
14246
14247    /// A `describe_consumer_groups` on a nonexistent group id surfaces
14248    /// `GROUP_ID_NOT_FOUND` after the classic fallback also reports it, keeping
14249    /// the more-informative `ConsumerGroupDescribe` message.
14250    #[tokio::test]
14251    #[doc(
14252        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDescribeConsumerGroupsGroupIdNotFound"
14253    )]
14254    async fn test_describe_consumer_groups_group_id_not_found() {
14255        let (admin, mut runnable, time, nodes) = env();
14256        runnable
14257            .client_mut()
14258            .prepare_response(find_coordinator_resp(&[("missing", &nodes[0])]));
14259        runnable.client_mut().prepare_response_from(
14260            consumer_group_describe_error_resp("missing", Errors::GroupIdNotFound, Some("informative message")),
14261            &nodes[0],
14262        );
14263        // Fallback: classic DescribeGroups also reports GROUP_ID_NOT_FOUND.
14264        runnable.client_mut().prepare_response_from(
14265            describe_groups_error_resp("missing", Errors::GroupIdNotFound, Some("terse message")),
14266            &nodes[0],
14267        );
14268
14269        let result =
14270            admin.describe_consumer_groups_with_options(&["missing".to_string()], DescribeConsumerGroupsOptions::new());
14271        let future = result.described_groups()["missing"].clone();
14272        // The classic-API fallback is a driver retry gated on the retry backoff,
14273        // so the mock clock must advance for the second (DescribeGroups) request.
14274        for _ in 0..60 {
14275            if future.is_done() {
14276                break;
14277            }
14278            runnable.run_once().await;
14279            time.sleep(200);
14280        }
14281
14282        let err = future.get().await.unwrap_err();
14283        assert_eq!(err.error(), Errors::GroupIdNotFound);
14284        assert_eq!(err.message(), "informative message");
14285    }
14286
14287    /// Mirrors `testDescribeGroupsWithBothUnsupportedApis`: the first
14288    /// `ConsumerGroupDescribe` request fails with `UNSUPPORTED_VERSION`, the
14289    /// driver falls back to the classic `DescribeGroups` request, and when that
14290    /// too fails with `UNSUPPORTED_VERSION` the group future surfaces the
14291    /// `UnsupportedVersionException`.
14292    #[tokio::test]
14293    #[doc(
14294        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDescribeGroupsWithBothUnsupportedApis"
14295    )]
14296    async fn test_describe_groups_with_both_unsupported_apis() {
14297        let (admin, mut runnable, time, nodes) = env();
14298        runnable
14299            .client_mut()
14300            .prepare_response(find_coordinator_resp(&[("g1", &nodes[0])]));
14301        // The first request sent is a ConsumerGroupDescribe request. Fail it to
14302        // fall back to the classic version.
14303        runnable.client_mut().prepare_unsupported_version_response();
14304        // Fail the classic DescribeGroups fallback as well.
14305        runnable.client_mut().prepare_unsupported_version_response();
14306
14307        let result =
14308            admin.describe_consumer_groups_with_options(&["g1".to_string()], DescribeConsumerGroupsOptions::new());
14309        let future = result.described_groups()["g1"].clone();
14310        // The classic-API fallback is a driver retry gated on the retry backoff,
14311        // so the mock clock must advance for the second request to be sent.
14312        for _ in 0..60 {
14313            if future.is_done() {
14314                break;
14315            }
14316            runnable.run_once().await;
14317            time.sleep(200);
14318        }
14319
14320        let err = future.get().await.unwrap_err();
14321        assert_eq!(err.error(), Errors::UnsupportedVersion);
14322    }
14323
14324    /// Translated from `KafkaAdminClientTest.testDescribeClassicGroups`.
14325    ///
14326    /// Exercises the full classic-describe path: retriable `FindCoordinator`
14327    /// errors are retried, retriable/coordinator-moved `DescribeGroups` errors
14328    /// trigger a re-lookup, and the final response's two members have their
14329    /// assignment bytes decoded via `ConsumerProtocol::deserialize_assignment`.
14330    #[tokio::test]
14331    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDescribeClassicGroups")]
14332    async fn test_describe_classic_groups() {
14333        use crate::common::ClassicGroupState;
14334        use crate::consumer::consumer_partition_assignor::Assignment;
14335        use crate::consumer::internals::ConsumerProtocol;
14336        use crate::describe_groups_response_data::DescribedGroup;
14337
14338        // Default retries (i32::MAX) with a small backoff so the retry/re-lookup
14339        // sequence completes; `env()`'s `retries=2` is too few for this chain.
14340        let (admin, mut runnable, time, nodes) = env_with_props(&[("retry.backoff.ms", "10")]);
14341        {
14342            let c = runnable.client_mut();
14343            // Retriable FindCoordinatorResponse errors should be retried.
14344            c.prepare_response(find_coordinator_error_resp("group-0", Errors::CoordinatorNotAvailable));
14345            c.prepare_response(find_coordinator_error_resp("group-0", Errors::CoordinatorLoadInProgress));
14346            c.prepare_response(find_coordinator_resp(&[("group-0", &nodes[0])]));
14347            // Retriable DescribeGroups error should be retried.
14348            c.prepare_response(describe_groups_error_resp("group-0", Errors::CoordinatorLoadInProgress, None));
14349            // NOT_COORDINATOR: the coordinator moved, so re-run the lookup.
14350            c.prepare_response(describe_groups_error_resp("group-0", Errors::NotCoordinator, None));
14351            c.prepare_response(find_coordinator_resp(&[("group-0", &nodes[0])]));
14352            // COORDINATOR_NOT_AVAILABLE: same, re-run the lookup.
14353            c.prepare_response(describe_groups_error_resp("group-0", Errors::CoordinatorNotAvailable, None));
14354            c.prepare_response(find_coordinator_resp(&[("group-0", &nodes[0])]));
14355
14356            // Final good response: two members sharing one 3-partition assignment.
14357            let topic_partitions = vec![
14358                TopicPartition::new("my_topic", 0),
14359                TopicPartition::new("my_topic", 1),
14360                TopicPartition::new("my_topic", 2),
14361            ];
14362            let assignment_bytes = ConsumerProtocol::serialize_assignment(&Assignment::new(topic_partitions)).unwrap();
14363            let member_one = described_member("0", None, "clientId0", "clientHost", assignment_bytes.clone());
14364            let member_two = described_member("1", Some("static"), "clientId1", "clientHost", assignment_bytes.clone());
14365            let mut group = DescribedGroup::new();
14366            group
14367                .set_group_id("group-0".to_string())
14368                .set_protocol_type(ConsumerProtocol::PROTOCOL_TYPE.to_string())
14369                .set_group_state(ClassicGroupState::Stable.to_string())
14370                .set_members(vec![member_one, member_two]);
14371            c.prepare_response(describe_groups_full_resp(vec![group]));
14372        }
14373
14374        let result =
14375            admin.describe_classic_groups_with_options(&["group-0".to_string()], DescribeClassicGroupsOptions::new());
14376        let future = result.described_groups()["group-0"].clone();
14377        for _ in 0..300 {
14378            if future.is_done() {
14379                break;
14380            }
14381            runnable.run_once().await;
14382            time.sleep(50);
14383        }
14384
14385        let description = future.get().await.unwrap();
14386        assert_eq!(result.described_groups().len(), 1);
14387        assert_eq!(description.group_id(), "group-0");
14388        assert_eq!(description.state(), ClassicGroupState::Stable);
14389        assert_eq!(description.members().len(), 2);
14390
14391        let expected_partitions: HashSet<TopicPartition> = [
14392            TopicPartition::new("my_topic", 0),
14393            TopicPartition::new("my_topic", 1),
14394            TopicPartition::new("my_topic", 2),
14395        ]
14396        .into_iter()
14397        .collect();
14398        for member in description.members() {
14399            assert_eq!(member.assignment().topic_partitions(), &expected_partitions);
14400        }
14401        // The static member carries its group instance id.
14402        let member_ids: Vec<&str> = description.members().iter().map(|m| m.consumer_id()).collect();
14403        assert!(member_ids.contains(&"0"));
14404        assert!(member_ids.contains(&"1"));
14405        let static_member = description.members().iter().find(|m| m.consumer_id() == "1").unwrap();
14406        assert_eq!(static_member.group_instance_id(), Some("static"));
14407        // Same contract as `test_describe_consumer_groups`: the coordinator
14408        // reaching public API is the resolved broker, endpoint included. This
14409        // path re-ran the lookup twice, so it also covers a re-mapped coordinator.
14410        assert_eq!(description.coordinator(), Some(&nodes[0]));
14411    }
14412
14413    /// Translated from
14414    /// `KafkaAdminClientTest.testDescribeClassicGroupsWithAuthorizedOperationsOmitted`.
14415    #[tokio::test]
14416    #[doc(
14417        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDescribeClassicGroupsWithAuthorizedOperationsOmitted"
14418    )]
14419    async fn test_describe_classic_groups_with_authorized_operations_omitted() {
14420        use crate::describe_groups_response_data::DescribedGroup;
14421
14422        let (admin, mut runnable, _time, nodes) = env();
14423        {
14424            let c = runnable.client_mut();
14425            c.prepare_response(find_coordinator_resp(&[("group-0", &nodes[0])]));
14426            let mut group = DescribedGroup::new();
14427            group
14428                .set_group_id("group-0".to_string())
14429                .set_protocol_type(String::new())
14430                .set_authorized_operations(MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED);
14431            c.prepare_response_from(describe_groups_full_resp(vec![group]), &nodes[0]);
14432        }
14433
14434        let result =
14435            admin.describe_classic_groups_with_options(&["group-0".to_string()], DescribeClassicGroupsOptions::new());
14436        let future = result.described_groups()["group-0"].clone();
14437        pump_until(&mut runnable, 40, |_r| future.is_done()).await;
14438
14439        let description = future.get().await.unwrap();
14440        // Java asserts `assertNull(groupDescription.authorizedOperations())`: the
14441        // omitted sentinel means "not reported", which is not the same as a
14442        // broker reporting an empty set.
14443        assert_eq!(description.authorized_operations(), None);
14444    }
14445
14446    /// Translated from `KafkaAdminClientTest.testDescribeMultipleClassicGroups`.
14447    #[tokio::test]
14448    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDescribeMultipleClassicGroups")]
14449    async fn test_describe_multiple_classic_groups() {
14450        use crate::common::ClassicGroupState;
14451        use crate::consumer::consumer_partition_assignor::Assignment;
14452        use crate::consumer::internals::ConsumerProtocol;
14453        use crate::describe_groups_response_data::DescribedGroup;
14454
14455        let (admin, mut runnable, _time, nodes) = env();
14456        {
14457            let c = runnable.client_mut();
14458            // Both group ids resolve to the same coordinator.
14459            c.prepare_response(find_coordinator_resp(&[("group-0", &nodes[0]), ("group-1", &nodes[0])]));
14460
14461            let topic_partitions = vec![
14462                TopicPartition::new("my_topic", 0),
14463                TopicPartition::new("my_topic", 1),
14464                TopicPartition::new("my_topic", 2),
14465            ];
14466            let assignment_bytes = ConsumerProtocol::serialize_assignment(&Assignment::new(topic_partitions)).unwrap();
14467
14468            let mut group0 = DescribedGroup::new();
14469            group0
14470                .set_group_id("group-0".to_string())
14471                .set_protocol_type(ConsumerProtocol::PROTOCOL_TYPE.to_string())
14472                .set_group_state(ClassicGroupState::Stable.to_string())
14473                .set_members(vec![
14474                    described_member("0", None, "clientId0", "clientHost", assignment_bytes.clone()),
14475                    described_member("1", None, "clientId1", "clientHost", assignment_bytes.clone()),
14476                ]);
14477            let mut group1 = DescribedGroup::new();
14478            group1
14479                .set_group_id("group-1".to_string())
14480                .set_protocol_type("other".to_string())
14481                .set_group_state(ClassicGroupState::Stable.to_string())
14482                .set_members(vec![
14483                    described_member("0", None, "clientId0", "clientHost", Vec::new()),
14484                    described_member("1", None, "clientId1", "clientHost", Vec::new()),
14485                ]);
14486            // Both groups map to one coordinator, so the batched handler sends a
14487            // single DescribeGroups request for both ids.
14488            c.prepare_response_from(describe_groups_full_resp(vec![group0, group1]), &nodes[0]);
14489        }
14490
14491        let result = admin.describe_classic_groups_with_options(
14492            &["group-0".to_string(), "group-1".to_string()],
14493            DescribeClassicGroupsOptions::new(),
14494        );
14495        let g0 = result.described_groups()["group-0"].clone();
14496        let g1 = result.described_groups()["group-1"].clone();
14497        pump_until(&mut runnable, 60, |_r| g0.is_done() && g1.is_done()).await;
14498
14499        assert_eq!(result.described_groups().len(), 2);
14500        let keys: HashSet<String> = result.described_groups().keys().cloned().collect();
14501        assert_eq!(keys, HashSet::from(["group-0".to_string(), "group-1".to_string()]));
14502        assert!(g0.get().await.is_ok());
14503        assert!(g1.get().await.is_ok());
14504    }
14505
14506    /// Seeds a group config in the mock (the only way Java's mock populates its
14507    /// `groupConfigs` keyset is via `incrementalAlterConfigs` on a GROUP
14508    /// resource).
14509    async fn seed_mock_group(mock: &crate::admin::MockAdminClient, group_id: &str) {
14510        use crate::admin::{AlterConfigOp, ConfigEntry, OpType};
14511        let resource = ConfigResource::new(config_resource::Type::Group, group_id.to_string());
14512        let ops = vec![AlterConfigOp::new(
14513            ConfigEntry::new("consumer.session.timeout.ms".to_string(), Some("45000".to_string())),
14514            OpType::Set,
14515        )];
14516        let mut configs = HashMap::new();
14517        configs.insert(resource.clone(), ops);
14518        mock.incremental_alter_configs_with_options(&configs, AlterConfigsOptions::new())
14519            .all()
14520            .get()
14521            .await
14522            .unwrap();
14523    }
14524
14525    /// The mock's `list_groups` returns one CONSUMER/STABLE listing per seeded
14526    /// group config (mirrors Java's mock).
14527    #[tokio::test]
14528    async fn test_mock_list_groups() {
14529        let mock = mock_admin_client::Builder::new()
14530            .build()
14531            .expect("a fresh builder has one broker");
14532        seed_mock_group(&mock, "g1").await;
14533        let result = mock.list_groups_with_options(ListGroupsOptions::new());
14534        let listings = result.valid().get().await.unwrap();
14535        assert_eq!(listings.len(), 1);
14536        assert_eq!(listings[0].group_id(), "g1");
14537        assert_eq!(listings[0].r#type(), Some(GroupType::Consumer));
14538        assert_eq!(listings[0].group_state(), Some(GroupState::Stable));
14539    }
14540
14541    /// The mock's `describe_consumer_groups` mirrors Java's
14542    /// `UnsupportedOperationException`.
14543    #[tokio::test]
14544    async fn test_mock_describe_consumer_groups_unsupported() {
14545        let mock = mock_admin_client::Builder::new()
14546            .build()
14547            .expect("a fresh builder has one broker");
14548        let result =
14549            mock.describe_consumer_groups_with_options(&["g1".to_string()], DescribeConsumerGroupsOptions::new());
14550        let err = result.described_groups()["g1"].get().await.unwrap_err();
14551        assert!(err.is_local_unsupported_operation_error(), "{err:?}");
14552        assert_eq!(err.message(), "Not implemented yet");
14553    }
14554
14555    /// The mock's `describe_classic_groups` mirrors Java's
14556    /// `UnsupportedOperationException`.
14557    #[tokio::test]
14558    async fn test_mock_describe_classic_groups_unsupported() {
14559        let mock = mock_admin_client::Builder::new()
14560            .build()
14561            .expect("a fresh builder has one broker");
14562        let result =
14563            mock.describe_classic_groups_with_options(&["g1".to_string()], DescribeClassicGroupsOptions::new());
14564        let err = result.described_groups()["g1"].get().await.unwrap_err();
14565        assert!(err.is_local_unsupported_operation_error(), "{err:?}");
14566        assert_eq!(err.message(), "Not implemented yet");
14567    }
14568
14569    // --- consumer group offsets (list / alter / delete) ---------------------
14570
14571    const GROUP_ID: &str = "group0";
14572
14573    /// Drives `run_once` (advancing the mock clock so retry-backoff-gated retries
14574    /// fire) until `done` returns true or `max_iters` is reached.
14575    async fn drive_until(
14576        runnable: &mut AdminClientRunnable<MockClient>,
14577        time: &MockTime,
14578        max_iters: usize,
14579        done: impl Fn() -> bool,
14580    ) {
14581        for _ in 0..max_iters {
14582            if done() {
14583                return;
14584            }
14585            runnable.run_once().await;
14586            time.sleep(50);
14587        }
14588    }
14589
14590    /// Builds an environment whose driver retries essentially unbounded, so
14591    /// multi-step retry chains complete (Java's default `retries` is high, but
14592    /// the Rust `test_config` caps it at 2).
14593    fn offsets_env(num_nodes: i32) -> (KafkaAdminClient, AdminClientRunnable<MockClient>, Arc<MockTime>, Vec<Node>) {
14594        env_nodes_with_props(num_nodes, &[("retries", "2147483647"), ("retry.backoff.ms", "10")])
14595    }
14596
14597    fn offset_fetch_group_error(group: &str, error: Errors) -> ConcreteResponse {
14598        let mut g = crate::offset_fetch_response_data::OffsetFetchResponseGroup::new();
14599        g.set_group_id(group.to_string()).set_error_code(error.code());
14600        let mut data = crate::OffsetFetchResponseData::new();
14601        data.set_groups(vec![g]);
14602        ConcreteResponse::OffsetFetch(crate::common::requests::OffsetFetchResponse::new(
14603            data,
14604            crate::common::protocol::ApiKeys::OFFSET_FETCH.latest_version(),
14605        ))
14606    }
14607
14608    /// Builds a full (per-partition) `OffsetFetch` response for one group.
14609    fn offset_fetch_full(group: &str, topic: &str, partitions: &[(i32, i64)]) -> ConcreteResponse {
14610        use crate::OffsetFetchResponseData;
14611        use crate::offset_fetch_response_data::{
14612            OffsetFetchResponseGroup, OffsetFetchResponsePartitions, OffsetFetchResponseTopics,
14613        };
14614        let wire_partitions: Vec<OffsetFetchResponsePartitions> = partitions
14615            .iter()
14616            .map(|(index, offset)| {
14617                let mut p = OffsetFetchResponsePartitions::new();
14618                p.set_partition_index(*index).set_committed_offset(*offset);
14619                p
14620            })
14621            .collect();
14622        let mut wire_topic = OffsetFetchResponseTopics::new();
14623        wire_topic.set_name(topic.to_string()).set_partitions(wire_partitions);
14624        let mut g = OffsetFetchResponseGroup::new();
14625        g.set_group_id(group.to_string()).set_topics(vec![wire_topic]);
14626        let mut data = OffsetFetchResponseData::new();
14627        data.set_groups(vec![g]);
14628        ConcreteResponse::OffsetFetch(crate::common::requests::OffsetFetchResponse::new(
14629            data,
14630            crate::common::protocol::ApiKeys::OFFSET_FETCH.latest_version(),
14631        ))
14632    }
14633
14634    fn offset_commit_resp(entries: &[(TopicPartition, Errors)]) -> ConcreteResponse {
14635        let map: HashMap<TopicPartition, Errors> = entries.iter().cloned().collect();
14636        ConcreteResponse::OffsetCommit(
14637            crate::common::requests::OffsetCommitResponse::with_throttle_time_ms_response_data(0, &map),
14638        )
14639    }
14640
14641    fn offset_delete_top_level(error: Errors) -> ConcreteResponse {
14642        let mut data = crate::OffsetDeleteResponseData::new();
14643        data.set_error_code(error.code());
14644        ConcreteResponse::OffsetDelete(crate::common::requests::OffsetDeleteResponse::new(data))
14645    }
14646
14647    fn offset_delete_partition(topic: &str, partition: i32, error: Errors) -> ConcreteResponse {
14648        use crate::OffsetDeleteResponseData;
14649        use crate::offset_delete_response_data::{OffsetDeleteResponsePartition, OffsetDeleteResponseTopic};
14650        let mut p = OffsetDeleteResponsePartition::new();
14651        p.set_partition_index(partition).set_error_code(error.code());
14652        let mut t = OffsetDeleteResponseTopic::new();
14653        t.set_name(topic.to_string()).set_partitions(vec![p]);
14654        let mut data = OffsetDeleteResponseData::new();
14655        data.set_error_code(Errors::None.code());
14656        data.set_topics(vec![t]);
14657        ConcreteResponse::OffsetDelete(crate::common::requests::OffsetDeleteResponse::new(data))
14658    }
14659
14660    /// An old (v<=3) single-coordinator `FindCoordinator` response — the form a
14661    /// non-batched `FindCoordinator` request receives. Mirrors Java's
14662    /// `prepareOldFindCoordinatorResponse`; the empty coordinator key binds the
14663    /// response to whichever single key requested it.
14664    fn old_find_coordinator_resp(node: &Node) -> ConcreteResponse {
14665        use crate::FindCoordinatorResponseData;
14666        let mut data = FindCoordinatorResponseData::new();
14667        data.set_error_code(Errors::None.code())
14668            .set_node_id(node.id())
14669            .set_host(node.host().to_string())
14670            .set_port(node.port());
14671        ConcreteResponse::FindCoordinator(crate::common::requests::FindCoordinatorResponse::new(data))
14672    }
14673
14674    /// An old (single-coordinator) `FindCoordinator` error response, mirroring
14675    /// `prepareOldFindCoordinatorResponse(error, Node.noNode())`.
14676    fn old_find_coordinator_error_resp(error: Errors) -> ConcreteResponse {
14677        use crate::FindCoordinatorResponseData;
14678        let mut data = FindCoordinatorResponseData::new();
14679        data.set_error_code(error.code())
14680            .set_node_id(-1)
14681            .set_host(String::new())
14682            .set_port(-1);
14683        ConcreteResponse::FindCoordinator(crate::common::requests::FindCoordinatorResponse::new(data))
14684    }
14685
14686    fn single_spec(partitions: &[TopicPartition]) -> HashMap<String, ListConsumerGroupOffsetsSpec> {
14687        HashMap::from([(
14688            GROUP_ID.to_string(),
14689            ListConsumerGroupOffsetsSpec::new().set_topic_partitions(Some(partitions.to_vec())),
14690        )])
14691    }
14692
14693    /// Translated from `testListConsumerGroupOffsets`: retriable FindCoordinator
14694    /// and OffsetFetch errors are retried, and the final response's negative
14695    /// offset maps to `None`.
14696    #[tokio::test]
14697    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testListConsumerGroupOffsets")]
14698    async fn test_list_consumer_group_offsets() {
14699        let (admin, mut runnable, time, nodes) = offsets_env(1);
14700        let tp0 = TopicPartition::new("my_topic", 0);
14701        let tp1 = TopicPartition::new("my_topic", 1);
14702        let tp2 = TopicPartition::new("my_topic", 2);
14703        let tp3 = TopicPartition::new("my_topic", 3);
14704
14705        // Retriable FindCoordinator error is retried.
14706        runnable
14707            .client_mut()
14708            .prepare_response(find_coordinator_error_resp(GROUP_ID, Errors::CoordinatorNotAvailable));
14709        runnable
14710            .client_mut()
14711            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
14712        // Retriable OffsetFetch error is retried.
14713        runnable
14714            .client_mut()
14715            .prepare_response(offset_fetch_group_error(GROUP_ID, Errors::CoordinatorLoadInProgress));
14716        // NOT_COORDINATOR / COORDINATOR_NOT_AVAILABLE trigger a re-lookup.
14717        runnable
14718            .client_mut()
14719            .prepare_response(offset_fetch_group_error(GROUP_ID, Errors::NotCoordinator));
14720        runnable
14721            .client_mut()
14722            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
14723        runnable
14724            .client_mut()
14725            .prepare_response(offset_fetch_group_error(GROUP_ID, Errors::CoordinatorNotAvailable));
14726        runnable
14727            .client_mut()
14728            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
14729        runnable.client_mut().prepare_response(offset_fetch_full(
14730            GROUP_ID,
14731            "my_topic",
14732            &[(0, 10), (1, 0), (2, 20), (3, -1)],
14733        ));
14734
14735        let result = admin.list_consumer_group_offsets_with_group_specs_options(
14736            &single_spec(&[tp0.clone(), tp1.clone(), tp2.clone(), tp3.clone()]),
14737            ListConsumerGroupOffsetsOptions::new(),
14738        );
14739        let future = result.partitions_to_offset_and_metadata().unwrap();
14740        drive_until(&mut runnable, &time, 80, || future.is_done()).await;
14741
14742        let offsets = future.get().await.unwrap();
14743        assert_eq!(offsets.len(), 4);
14744        assert_eq!(offsets.get(&tp0).unwrap().as_ref().unwrap().offset(), 10);
14745        assert_eq!(offsets.get(&tp1).unwrap().as_ref().unwrap().offset(), 0);
14746        assert_eq!(offsets.get(&tp2).unwrap().as_ref().unwrap().offset(), 20);
14747        assert!(offsets.contains_key(&tp3));
14748        assert_eq!(offsets.get(&tp3).unwrap(), &None);
14749    }
14750
14751    /// Translated from `testListConsumerGroupOffsetsNumRetries`: with
14752    /// `retries=0`, the re-lookup a `NOT_COORDINATOR` fetch triggers exceeds the
14753    /// retry budget.
14754    #[tokio::test]
14755    #[doc(
14756        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testListConsumerGroupOffsetsNumRetries"
14757    )]
14758    async fn test_list_consumer_group_offsets_num_retries() {
14759        let (admin, mut runnable, time, nodes) = env_nodes_with_props(3, &[("retries", "0")]);
14760        runnable
14761            .client_mut()
14762            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
14763        runnable
14764            .client_mut()
14765            .prepare_response(offset_fetch_group_error(GROUP_ID, Errors::NotCoordinator));
14766        runnable
14767            .client_mut()
14768            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
14769
14770        let result = admin.list_consumer_group_offsets_with_group_id(GROUP_ID);
14771        let future = result.partitions_to_offset_and_metadata().unwrap();
14772        drive_until(&mut runnable, &time, 100, || future.is_done()).await;
14773        assert_exceeded_max_retries_after_one_try(&future).await;
14774    }
14775
14776    /// Translated from `testListConsumerGroupOffsetsNonRetriableErrors`.
14777    #[tokio::test]
14778    #[doc(
14779        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testListConsumerGroupOffsetsNonRetriableErrors"
14780    )]
14781    async fn test_list_consumer_group_offsets_non_retriable_errors() {
14782        let (admin, mut runnable, time, nodes) = offsets_env(1);
14783        for error in [
14784            Errors::GroupAuthorizationFailed,
14785            Errors::InvalidGroupId,
14786            Errors::GroupIdNotFound,
14787            Errors::UnknownMemberId,
14788            Errors::StaleMemberEpoch,
14789        ] {
14790            runnable
14791                .client_mut()
14792                .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
14793            runnable
14794                .client_mut()
14795                .prepare_response(offset_fetch_group_error(GROUP_ID, error));
14796
14797            let result = admin.list_consumer_group_offsets_with_group_specs_options(
14798                &single_spec(&[TopicPartition::new("t", 0)]),
14799                ListConsumerGroupOffsetsOptions::new(),
14800            );
14801            let future = result.partitions_to_offset_and_metadata().unwrap();
14802            drive_until(&mut runnable, &time, 40, || future.is_done()).await;
14803            assert_eq!(future.get().await.unwrap_err().error(), error);
14804        }
14805    }
14806
14807    fn batched_specs() -> HashMap<String, ListConsumerGroupOffsetsSpec> {
14808        HashMap::from([
14809            (
14810                "groupA".to_string(),
14811                ListConsumerGroupOffsetsSpec::new().set_topic_partitions(Some(vec![TopicPartition::new("A", 1)])),
14812            ),
14813            (
14814                "groupB".to_string(),
14815                ListConsumerGroupOffsetsSpec::new().set_topic_partitions(Some(vec![TopicPartition::new("B", 2)])),
14816            ),
14817        ])
14818    }
14819
14820    fn offset_fetch_multi(groups: &[(&str, &str, i32)]) -> ConcreteResponse {
14821        use crate::OffsetFetchResponseData;
14822        use crate::offset_fetch_response_data::{
14823            OffsetFetchResponseGroup, OffsetFetchResponsePartitions, OffsetFetchResponseTopics,
14824        };
14825        let wire_groups: Vec<OffsetFetchResponseGroup> = groups
14826            .iter()
14827            .map(|(group, topic, partition)| {
14828                let mut p = OffsetFetchResponsePartitions::new();
14829                p.set_partition_index(*partition).set_committed_offset(10);
14830                let mut t = OffsetFetchResponseTopics::new();
14831                t.set_name((*topic).to_string()).set_partitions(vec![p]);
14832                let mut g = OffsetFetchResponseGroup::new();
14833                g.set_group_id((*group).to_string()).set_topics(vec![t]);
14834                g
14835            })
14836            .collect();
14837        let mut data = OffsetFetchResponseData::new();
14838        data.set_groups(wire_groups);
14839        ConcreteResponse::OffsetFetch(crate::common::requests::OffsetFetchResponse::new(
14840            data,
14841            crate::common::protocol::ApiKeys::OFFSET_FETCH.latest_version(),
14842        ))
14843    }
14844
14845    /// Translated from `testBatchedListConsumerGroupOffsets`: two groups behind a
14846    /// single (batched) FindCoordinator and OffsetFetch.
14847    #[tokio::test]
14848    #[doc(
14849        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testBatchedListConsumerGroupOffsets"
14850    )]
14851    async fn test_batched_list_consumer_group_offsets() {
14852        let (admin, mut runnable, time, nodes) = offsets_env(1);
14853        runnable
14854            .client_mut()
14855            .prepare_response(find_coordinator_resp(&[("groupA", &nodes[0]), ("groupB", &nodes[0])]));
14856        runnable
14857            .client_mut()
14858            .prepare_response(offset_fetch_multi(&[("groupA", "A", 1), ("groupB", "B", 2)]));
14859
14860        let result = admin.list_consumer_group_offsets_with_group_specs_options(
14861            &batched_specs(),
14862            ListConsumerGroupOffsetsOptions::new(),
14863        );
14864        let all = result.all();
14865        drive_until(&mut runnable, &time, 40, || all.is_done()).await;
14866
14867        let map = all.get().await.unwrap();
14868        assert_eq!(map.len(), 2);
14869        // Each group's per-partition offsets match the requested spec.
14870        for group in ["groupA", "groupB"] {
14871            let future = result.partitions_to_offset_and_metadata_with_group_id(group).unwrap();
14872            assert_eq!(future.get().await.unwrap().len(), 1);
14873        }
14874    }
14875
14876    /// Translated from `testBatchedListConsumerGroupOffsetsWithNoFindCoordinatorBatching`:
14877    /// a `NoBatchedFindCoordinatorsException` disables batching, after which the
14878    /// groups are looked up individually.
14879    #[tokio::test]
14880    #[doc(
14881        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testBatchedListConsumerGroupOffsetsWithNoFindCoordinatorBatching"
14882    )]
14883    async fn test_batched_list_consumer_group_offsets_with_no_find_coordinator_batching() {
14884        let (admin, mut runnable, time, nodes) = offsets_env(1);
14885        // The batched FindCoordinator build fails (broker only supports v3) —
14886        // mirror the version-mismatch the real NetworkClient produces for
14887        // `NoBatchedFindCoordinatorsException`.
14888        runnable.client_mut().prepare_version_mismatch_response(
14889            "Cannot create a v3 FindCoordinator request because we require features supported only in 4 or later.",
14890        );
14891        // After disabling batching, each group is looked up individually with the
14892        // old single-coordinator FindCoordinator form.
14893        runnable.client_mut().prepare_response(old_find_coordinator_resp(&nodes[0]));
14894        runnable.client_mut().prepare_response(old_find_coordinator_resp(&nodes[0]));
14895        runnable
14896            .client_mut()
14897            .prepare_response(offset_fetch_multi(&[("groupA", "A", 1), ("groupB", "B", 2)]));
14898        runnable
14899            .client_mut()
14900            .prepare_response(offset_fetch_multi(&[("groupA", "A", 1), ("groupB", "B", 2)]));
14901
14902        let result = admin.list_consumer_group_offsets_with_group_specs_options(
14903            &batched_specs(),
14904            ListConsumerGroupOffsetsOptions::new(),
14905        );
14906        let all = result.all();
14907        drive_until(&mut runnable, &time, 80, || all.is_done()).await;
14908        assert_eq!(all.get().await.unwrap().len(), 2);
14909    }
14910
14911    /// Translated from `testBatchedListConsumerGroupOffsetsWithNoOffsetFetchBatching`:
14912    /// a `NoBatchedOffsetFetchRequestException` disables batching, after which
14913    /// both FindCoordinator and OffsetFetch are re-sent per group.
14914    #[tokio::test]
14915    #[doc(
14916        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testBatchedListConsumerGroupOffsetsWithNoOffsetFetchBatching"
14917    )]
14918    async fn test_batched_list_consumer_group_offsets_with_no_offset_fetch_batching() {
14919        let (admin, mut runnable, time, nodes) = offsets_env(1);
14920        // Batched FindCoordinator succeeds, but the batched OffsetFetch build
14921        // fails (broker only supports v7) — a `NoBatchedOffsetFetchRequestException`.
14922        runnable
14923            .client_mut()
14924            .prepare_response(find_coordinator_resp(&[("groupA", &nodes[0]), ("groupB", &nodes[0])]));
14925        runnable.client_mut().prepare_version_mismatch_response(
14926            "Broker does not support batching groups for fetch offset request on version 7",
14927        );
14928        // After disabling batching, FindCoordinator (old single-coordinator form)
14929        // + OffsetFetch are re-sent per group.
14930        runnable.client_mut().prepare_response(old_find_coordinator_resp(&nodes[0]));
14931        runnable.client_mut().prepare_response(old_find_coordinator_resp(&nodes[0]));
14932        runnable
14933            .client_mut()
14934            .prepare_response(offset_fetch_multi(&[("groupA", "A", 1), ("groupB", "B", 2)]));
14935        runnable
14936            .client_mut()
14937            .prepare_response(offset_fetch_multi(&[("groupA", "A", 1), ("groupB", "B", 2)]));
14938
14939        let result = admin.list_consumer_group_offsets_with_group_specs_options(
14940            &batched_specs(),
14941            ListConsumerGroupOffsetsOptions::new(),
14942        );
14943        let all = result.all();
14944        drive_until(&mut runnable, &time, 80, || all.is_done()).await;
14945        assert_eq!(all.get().await.unwrap().len(), 2);
14946    }
14947
14948    /// Translated from `KafkaAdminClientTest.testListConsumerGroupOffsetsOptionsWithBatchedApi`
14949    /// (helper `verifyListConsumerGroupOffsetsOptions`): the `requireStable`
14950    /// option and the request timeout propagate to the built `OffsetFetch` wire
14951    /// request, and the group id / topic / partition indexes map through.
14952    #[tokio::test]
14953    #[doc(
14954        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testListConsumerGroupOffsetsOptionsWithBatchedApi"
14955    )]
14956    async fn test_list_consumer_group_offsets_options_with_batched_api() {
14957        use crate::common::requests::AbstractRequest;
14958
14959        // Java uses mockCluster(3, 0) with RETRIES_CONFIG = "0".
14960        let (admin, mut runnable, _time, nodes) = env_with_props(&[("retries", "0")]);
14961        runnable
14962            .client_mut()
14963            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
14964
14965        let options = ListConsumerGroupOffsetsOptions::new()
14966            .set_require_stable(true)
14967            .set_timeout_ms(Some(300));
14968        let _result = admin.list_consumer_group_offsets_with_group_specs_options(
14969            &single_spec(&[TopicPartition::new("A", 0)]),
14970            options,
14971        );
14972
14973        // Pump until the `OffsetFetch` request is queued. The `FindCoordinator`
14974        // request is matched to the prepared response at send time (so it never
14975        // enters the queue); the first request left in the queue is the
14976        // `OffsetFetch` request built after the coordinator is resolved.
14977        pump_until_request_queued(&mut runnable).await;
14978
14979        let reqs = runnable.client_mut().requests_mut();
14980        assert_eq!(reqs.len(), 1);
14981        let client_request = &mut reqs[0];
14982        // The `ListConsumerGroupOffsetsOptions.timeoutMs(300)` propagates to the
14983        // sent request's timeout (Java asserts clientRequest.requestTimeoutMs()).
14984        assert_eq!(client_request.request_timeout_ms(), 300);
14985        match client_request.request_builder_mut().build().unwrap() {
14986            AbstractRequest::OffsetFetch(req) => {
14987                let data = req.data();
14988                // The core contract this test pins: requireStable(true) reaches
14989                // the wire.
14990                assert!(data.require_stable);
14991                let group_ids: Vec<String> = data.groups.iter().map(|g| g.group_id.clone()).collect();
14992                assert_eq!(group_ids, vec![GROUP_ID.to_string()]);
14993                let group = &data.groups[0];
14994                let topics = group.topics.as_ref().expect("topics present");
14995                let topic_names: Vec<String> = topics.iter().map(|t| t.name.clone()).collect();
14996                assert_eq!(topic_names, vec!["A".to_string()]);
14997                assert_eq!(topics[0].partition_indexes, vec![0]);
14998            },
14999            other => panic!("expected an OffsetFetch request, got {other:?}"),
15000        }
15001    }
15002
15003    fn offsets_to_alter() -> HashMap<TopicPartition, OffsetAndMetadata> {
15004        HashMap::from([
15005            (TopicPartition::new("foo", 0), OffsetAndMetadata::new(123).unwrap()),
15006            (TopicPartition::new("bar", 0), OffsetAndMetadata::new(456).unwrap()),
15007        ])
15008    }
15009
15010    /// Translated from `testAlterConsumerGroupOffsets` (happy path).
15011    #[tokio::test]
15012    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testAlterConsumerGroupOffsets")]
15013    async fn test_alter_consumer_group_offsets() {
15014        let (admin, mut runnable, time, nodes) = offsets_env(1);
15015        let tp1 = TopicPartition::new("foo", 0);
15016        let tp2 = TopicPartition::new("bar", 0);
15017        let tp3 = TopicPartition::new("foobar", 0);
15018        runnable
15019            .client_mut()
15020            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15021        runnable
15022            .client_mut()
15023            .prepare_response(offset_commit_resp(&[(tp1.clone(), Errors::None), (tp2.clone(), Errors::None)]));
15024
15025        let result = admin.alter_consumer_group_offsets_with_options(
15026            GROUP_ID,
15027            &offsets_to_alter(),
15028            AlterConsumerGroupOffsetsOptions::new(),
15029        );
15030        let all = result.all();
15031        drive_until(&mut runnable, &time, 40, || all.is_done()).await;
15032
15033        assert_eq!(all.get().await.unwrap(), ());
15034        assert_eq!(result.partition_result(&tp1).get().await.unwrap(), ());
15035        assert_eq!(result.partition_result(&tp2).get().await.unwrap(), ());
15036        // A partition not in the request fails with IllegalArgument.
15037        assert!(matches!(
15038            result.partition_result(&tp3).get().await.unwrap_err(),
15039            Error::LocalIllegalArgument(_)
15040        ));
15041    }
15042
15043    /// The failure Java's `KafkaAdminClient.AdminClientRunnable#enqueue` gives a
15044    /// coordinator re-lookup once `retries=0` is used up: the second
15045    /// `FindCoordinator` carries `tries == 1`. The `*NumRetries` tests assert
15046    /// only `TimeoutException.class`; the message is asserted as well, so the
15047    /// failure cannot be the API timeout's. The future must already be done:
15048    /// awaiting a pending one would hang the test rather than fail it.
15049    async fn assert_exceeded_max_retries_after_one_try<T: Send + 'static>(future: &KafkaFuture<T>) {
15050        assert!(future.is_done(), "the coordinator re-lookup must fail once out of retries");
15051        let Err(err) = future.get().await else {
15052            panic!("the coordinator re-lookup must fail once out of retries");
15053        };
15054        assert!(matches!(err, Error::Timeout(_)), "got {err:?}");
15055        assert_eq!(err.message(), "Exceeded maxRetries after 1 tries.");
15056    }
15057
15058    /// Translated from `testOffsetCommitNumRetries`: with `retries=0`, the
15059    /// re-lookup a `NOT_COORDINATOR` commit triggers exceeds the retry budget.
15060    #[tokio::test]
15061    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testOffsetCommitNumRetries")]
15062    async fn test_offset_commit_num_retries() {
15063        let (admin, mut runnable, time, nodes) = env_nodes_with_props(3, &[("retries", "0")]);
15064        let tp1 = TopicPartition::new("foo", 0);
15065        runnable
15066            .client_mut()
15067            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15068        runnable
15069            .client_mut()
15070            .prepare_response(offset_commit_resp(&[(tp1.clone(), Errors::NotCoordinator)]));
15071        runnable
15072            .client_mut()
15073            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15074
15075        let offsets = HashMap::from([(tp1.clone(), OffsetAndMetadata::new(123).unwrap())]);
15076        let result = admin.alter_consumer_group_offsets(GROUP_ID, &offsets);
15077        let all = result.all();
15078        drive_until(&mut runnable, &time, 100, || all.is_done()).await;
15079        assert_exceeded_max_retries_after_one_try(&all).await;
15080    }
15081
15082    /// Translated from `testOffsetCommitWithMultipleErrors`.
15083    #[tokio::test]
15084    #[doc(
15085        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testOffsetCommitWithMultipleErrors"
15086    )]
15087    async fn test_offset_commit_with_multiple_errors() {
15088        let (admin, mut runnable, time, nodes) = offsets_env(1);
15089        let foo0 = TopicPartition::new("foo", 0);
15090        let foo1 = TopicPartition::new("foo", 1);
15091        runnable
15092            .client_mut()
15093            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15094        runnable.client_mut().prepare_response(offset_commit_resp(&[
15095            (foo0.clone(), Errors::None),
15096            (foo1.clone(), Errors::UnknownTopicOrPartition),
15097        ]));
15098
15099        let offsets = HashMap::from([
15100            (foo0.clone(), OffsetAndMetadata::new(123).unwrap()),
15101            (foo1.clone(), OffsetAndMetadata::new(456).unwrap()),
15102        ]);
15103        let result = admin.alter_consumer_group_offsets_with_options(
15104            GROUP_ID,
15105            &offsets,
15106            AlterConsumerGroupOffsetsOptions::new(),
15107        );
15108        let all = result.all();
15109        drive_until(&mut runnable, &time, 40, || all.is_done()).await;
15110
15111        assert_eq!(result.partition_result(&foo0).get().await.unwrap(), ());
15112        assert_eq!(
15113            result.partition_result(&foo1).get().await.unwrap_err().error(),
15114            Errors::UnknownTopicOrPartition
15115        );
15116        assert_eq!(all.get().await.unwrap_err().error(), Errors::UnknownTopicOrPartition);
15117    }
15118
15119    /// Translated from `testAlterConsumerGroupOffsetsNonRetriableErrors`.
15120    #[tokio::test]
15121    #[doc(
15122        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testAlterConsumerGroupOffsetsNonRetriableErrors"
15123    )]
15124    async fn test_alter_consumer_group_offsets_non_retriable_errors() {
15125        let (admin, mut runnable, time, nodes) = offsets_env(1);
15126        let tp1 = TopicPartition::new("foo", 0);
15127        for error in [
15128            Errors::GroupAuthorizationFailed,
15129            Errors::InvalidGroupId,
15130            Errors::GroupIdNotFound,
15131            Errors::StaleMemberEpoch,
15132        ] {
15133            runnable
15134                .client_mut()
15135                .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15136            runnable
15137                .client_mut()
15138                .prepare_response(offset_commit_resp(&[(tp1.clone(), error)]));
15139
15140            let offsets = HashMap::from([(tp1.clone(), OffsetAndMetadata::new(123).unwrap())]);
15141            let result = admin.alter_consumer_group_offsets_with_options(
15142                GROUP_ID,
15143                &offsets,
15144                AlterConsumerGroupOffsetsOptions::new(),
15145            );
15146            let all = result.all();
15147            drive_until(&mut runnable, &time, 40, || all.is_done()).await;
15148            assert_eq!(all.get().await.unwrap_err().error(), error);
15149            assert_eq!(result.partition_result(&tp1).get().await.unwrap_err().error(), error);
15150        }
15151    }
15152
15153    /// Translated from `testAlterConsumerGroupOffsetsFindCoordinatorNonRetriableErrors`.
15154    #[tokio::test]
15155    #[doc(
15156        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testAlterConsumerGroupOffsetsFindCoordinatorNonRetriableErrors"
15157    )]
15158    async fn test_alter_consumer_group_offsets_find_coordinator_non_retriable_errors() {
15159        let (admin, mut runnable, time, _nodes) = offsets_env(1);
15160        let tp1 = TopicPartition::new("foo", 0);
15161        runnable
15162            .client_mut()
15163            .prepare_response(find_coordinator_error_resp(GROUP_ID, Errors::GroupAuthorizationFailed));
15164
15165        let offsets = HashMap::from([(tp1.clone(), OffsetAndMetadata::new(123).unwrap())]);
15166        let result = admin.alter_consumer_group_offsets_with_options(
15167            GROUP_ID,
15168            &offsets,
15169            AlterConsumerGroupOffsetsOptions::new(),
15170        );
15171        let all = result.all();
15172        drive_until(&mut runnable, &time, 40, || all.is_done()).await;
15173        assert_eq!(all.get().await.unwrap_err().error(), Errors::GroupAuthorizationFailed);
15174        assert_eq!(
15175            result.partition_result(&tp1).get().await.unwrap_err().error(),
15176            Errors::GroupAuthorizationFailed
15177        );
15178    }
15179
15180    /// Translated from `testDeleteConsumerGroupOffsets` (happy path with one
15181    /// partition-level `GROUP_SUBSCRIBED_TO_TOPIC`).
15182    #[tokio::test]
15183    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDeleteConsumerGroupOffsets")]
15184    async fn test_delete_consumer_group_offsets() {
15185        let (admin, mut runnable, time, nodes) = offsets_env(1);
15186        let tp1 = TopicPartition::new("foo", 0);
15187        let tp2 = TopicPartition::new("bar", 0);
15188        let tp3 = TopicPartition::new("foobar", 0);
15189        runnable
15190            .client_mut()
15191            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15192        // Two topics: foo -> NONE, bar -> GROUP_SUBSCRIBED_TO_TOPIC.
15193        {
15194            use crate::OffsetDeleteResponseData;
15195            use crate::offset_delete_response_data::{OffsetDeleteResponsePartition, OffsetDeleteResponseTopic};
15196            let mut foo_p = OffsetDeleteResponsePartition::new();
15197            foo_p.set_partition_index(0).set_error_code(Errors::None.code());
15198            let mut foo_t = OffsetDeleteResponseTopic::new();
15199            foo_t.set_name("foo".to_string()).set_partitions(vec![foo_p]);
15200            let mut bar_p = OffsetDeleteResponsePartition::new();
15201            bar_p
15202                .set_partition_index(0)
15203                .set_error_code(Errors::GroupSubscribedToTopic.code());
15204            let mut bar_t = OffsetDeleteResponseTopic::new();
15205            bar_t.set_name("bar".to_string()).set_partitions(vec![bar_p]);
15206            let mut data = OffsetDeleteResponseData::new();
15207            data.set_topics(vec![foo_t, bar_t]);
15208            runnable.client_mut().prepare_response(ConcreteResponse::OffsetDelete(
15209                crate::common::requests::OffsetDeleteResponse::new(data),
15210            ));
15211        }
15212
15213        let result = admin.delete_consumer_group_offsets_with_options(
15214            GROUP_ID,
15215            &HashSet::from([tp1.clone(), tp2.clone()]),
15216            DeleteConsumerGroupOffsetsOptions::new(),
15217        );
15218        let all = result.all();
15219        drive_until(&mut runnable, &time, 40, || all.is_done()).await;
15220
15221        assert_eq!(result.partition_result(&tp1).unwrap().get().await.unwrap(), ());
15222        assert_eq!(all.get().await.unwrap_err().error(), Errors::GroupSubscribedToTopic);
15223        assert_eq!(
15224            result.partition_result(&tp2).unwrap().get().await.unwrap_err().error(),
15225            Errors::GroupSubscribedToTopic
15226        );
15227        // A partition not in the request fails synchronously with IllegalArgument.
15228        assert!(matches!(result.partition_result(&tp3), Err(Error::LocalIllegalArgument(_))));
15229    }
15230
15231    /// Translated from `testDeleteConsumerGroupOffsetsNonRetriableErrors`.
15232    #[tokio::test]
15233    #[doc(
15234        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDeleteConsumerGroupOffsetsNonRetriableErrors"
15235    )]
15236    async fn test_delete_consumer_group_offsets_non_retriable_errors() {
15237        let (admin, mut runnable, time, nodes) = offsets_env(1);
15238        let tp1 = TopicPartition::new("foo", 0);
15239        for error in [
15240            Errors::GroupAuthorizationFailed,
15241            Errors::InvalidGroupId,
15242            Errors::GroupIdNotFound,
15243        ] {
15244            runnable
15245                .client_mut()
15246                .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15247            runnable.client_mut().prepare_response(offset_delete_top_level(error));
15248
15249            let result = admin.delete_consumer_group_offsets_with_options(
15250                GROUP_ID,
15251                &HashSet::from([tp1.clone()]),
15252                DeleteConsumerGroupOffsetsOptions::new(),
15253            );
15254            let all = result.all();
15255            drive_until(&mut runnable, &time, 40, || all.is_done()).await;
15256            assert_eq!(all.get().await.unwrap_err().error(), error);
15257            assert_eq!(result.partition_result(&tp1).unwrap().get().await.unwrap_err().error(), error);
15258        }
15259    }
15260
15261    /// Translated from `testDeleteConsumerGroupOffsetsFindCoordinatorNonRetriableErrors`.
15262    #[tokio::test]
15263    #[doc(
15264        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDeleteConsumerGroupOffsetsFindCoordinatorNonRetriableErrors"
15265    )]
15266    async fn test_delete_consumer_group_offsets_find_coordinator_non_retriable_errors() {
15267        let (admin, mut runnable, time, _nodes) = offsets_env(1);
15268        let tp1 = TopicPartition::new("foo", 0);
15269        runnable
15270            .client_mut()
15271            .prepare_response(find_coordinator_error_resp(GROUP_ID, Errors::GroupAuthorizationFailed));
15272
15273        let result = admin.delete_consumer_group_offsets_with_options(
15274            GROUP_ID,
15275            &HashSet::from([tp1.clone()]),
15276            DeleteConsumerGroupOffsetsOptions::new(),
15277        );
15278        let all = result.all();
15279        drive_until(&mut runnable, &time, 40, || all.is_done()).await;
15280        assert_eq!(all.get().await.unwrap_err().error(), Errors::GroupAuthorizationFailed);
15281        assert_eq!(
15282            result.partition_result(&tp1).unwrap().get().await.unwrap_err().error(),
15283            Errors::GroupAuthorizationFailed
15284        );
15285    }
15286
15287    /// Translated from `testDeleteConsumerGroupOffsetsNumRetries`: with
15288    /// `retries=0`, the re-lookup a `NOT_COORDINATOR` deletion triggers exceeds
15289    /// the retry budget.
15290    #[tokio::test]
15291    #[doc(
15292        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDeleteConsumerGroupOffsetsNumRetries"
15293    )]
15294    async fn test_delete_consumer_group_offsets_num_retries() {
15295        let (admin, mut runnable, time, nodes) = env_nodes_with_props(3, &[("retries", "0")]);
15296        let tp1 = TopicPartition::new("foo", 0);
15297        runnable
15298            .client_mut()
15299            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15300        runnable
15301            .client_mut()
15302            .prepare_response(offset_delete_top_level(Errors::NotCoordinator));
15303        runnable
15304            .client_mut()
15305            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15306
15307        let result = admin.delete_consumer_group_offsets(GROUP_ID, &HashSet::from([tp1.clone()]));
15308        let all = result.all();
15309        drive_until(&mut runnable, &time, 100, || all.is_done()).await;
15310        assert_exceeded_max_retries_after_one_try(&all).await;
15311    }
15312
15313    /// Translated from `testDeleteConsumerGroupOffsetsRetriableErrors`: retriable
15314    /// group errors are retried (with re-lookup for coordinator-moved errors).
15315    #[tokio::test]
15316    #[doc(
15317        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDeleteConsumerGroupOffsetsRetriableErrors"
15318    )]
15319    async fn test_delete_consumer_group_offsets_retriable_errors() {
15320        let (admin, mut runnable, time, nodes) = offsets_env(1);
15321        let tp1 = TopicPartition::new("foo", 0);
15322        runnable
15323            .client_mut()
15324            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15325        runnable
15326            .client_mut()
15327            .prepare_response(offset_delete_top_level(Errors::CoordinatorLoadInProgress));
15328        runnable
15329            .client_mut()
15330            .prepare_response(offset_delete_top_level(Errors::NotCoordinator));
15331        runnable
15332            .client_mut()
15333            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15334        runnable
15335            .client_mut()
15336            .prepare_response(offset_delete_top_level(Errors::CoordinatorNotAvailable));
15337        runnable
15338            .client_mut()
15339            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15340        runnable
15341            .client_mut()
15342            .prepare_response(offset_delete_partition("foo", 0, Errors::None));
15343
15344        let result = admin.delete_consumer_group_offsets_with_options(
15345            GROUP_ID,
15346            &HashSet::from([tp1.clone()]),
15347            DeleteConsumerGroupOffsetsOptions::new(),
15348        );
15349        let all = result.all();
15350        drive_until(&mut runnable, &time, 80, || all.is_done()).await;
15351        assert_eq!(all.get().await.unwrap(), ());
15352        assert_eq!(result.partition_result(&tp1).unwrap().get().await.unwrap(), ());
15353    }
15354
15355    // --- deleteConsumerGroups / removeMembersFromConsumerGroup --------------
15356
15357    /// A `DeleteGroups` response with one result per (group, error) entry.
15358    fn delete_groups_resp(entries: &[(&str, Errors)]) -> ConcreteResponse {
15359        use crate::DeleteGroupsResponseData;
15360        use crate::delete_groups_response_data::DeletableGroupResult;
15361        let results: Vec<DeletableGroupResult> = entries
15362            .iter()
15363            .map(|(group_id, error)| {
15364                let mut r = DeletableGroupResult::new();
15365                r.set_group_id((*group_id).to_string()).set_error_code(error.code());
15366                r
15367            })
15368            .collect();
15369        let mut data = DeleteGroupsResponseData::new();
15370        data.set_results(results);
15371        ConcreteResponse::DeleteGroups(crate::common::requests::DeleteGroupsResponse::new(data))
15372    }
15373
15374    /// A `LeaveGroup` response carrying only a top-level error.
15375    fn leave_group_top_level(error: Errors) -> ConcreteResponse {
15376        use crate::LeaveGroupResponseData;
15377        let mut data = LeaveGroupResponseData::new();
15378        data.set_error_code(error.code());
15379        ConcreteResponse::LeaveGroup(crate::common::requests::LeaveGroupResponse::new(data))
15380    }
15381
15382    /// A successful `LeaveGroup` response with one member response per
15383    /// `(group.instance.id, error)` entry (member id echoed as empty, as the
15384    /// broker does for a static member removed by instance id).
15385    fn leave_group_members_resp(members: &[(&str, Errors)]) -> ConcreteResponse {
15386        use crate::LeaveGroupResponseData;
15387        use crate::leave_group_response_data::MemberResponse;
15388        let member_responses: Vec<MemberResponse> = members
15389            .iter()
15390            .map(|(instance_id, error)| {
15391                let mut m = MemberResponse::new();
15392                m.set_group_instance_id(Some((*instance_id).to_string()))
15393                    .set_error_code(error.code());
15394                m
15395            })
15396            .collect();
15397        let mut data = LeaveGroupResponseData::new();
15398        data.set_error_code(Errors::None.code()).set_members(member_responses);
15399        ConcreteResponse::LeaveGroup(crate::common::requests::LeaveGroupResponse::new(data))
15400    }
15401
15402    /// A `ConsumerGroupDescribe` response listing static members (used by the
15403    /// `removeAll` describe path). Each member carries a `group.instance.id`.
15404    fn consumer_group_describe_members_resp(group_id: &str, instance_ids: &[&str]) -> ConcreteResponse {
15405        use crate::ConsumerGroupDescribeResponseData;
15406        use crate::consumer_group_describe_response_data::{DescribedGroup, Member};
15407        let members: Vec<Member> = instance_ids
15408            .iter()
15409            .enumerate()
15410            .map(|(i, instance_id)| {
15411                let mut m = Member::new();
15412                m.set_member_id(format!("member-{i}"))
15413                    .set_instance_id(Some((*instance_id).to_string()));
15414                m
15415            })
15416            .collect();
15417        let mut group = DescribedGroup::new();
15418        group
15419            .set_group_id(group_id.to_string())
15420            .set_group_state("Stable".to_string())
15421            .set_group_epoch(5)
15422            .set_assignment_epoch(5)
15423            .set_assignor_name("uniform".to_string())
15424            .set_members(members);
15425        let mut data = ConsumerGroupDescribeResponseData::new();
15426        data.set_groups(vec![group]);
15427        ConcreteResponse::ConsumerGroupDescribe(crate::common::requests::ConsumerGroupDescribeResponse::new(data))
15428    }
15429
15430    fn members_to_remove(instance_ids: &[&str]) -> RemoveMembersFromConsumerGroupOptions {
15431        RemoveMembersFromConsumerGroupOptions::with_members(instance_ids.iter().map(|id| MemberToRemove::new(*id)))
15432            .unwrap()
15433    }
15434
15435    /// Translated from `testDeleteConsumerGroupsNumRetries`: with `retries=0`, a
15436    /// `NOT_COORDINATOR` re-lookup exhausts the retry budget and the deletion
15437    /// times out.
15438    #[tokio::test]
15439    #[doc(
15440        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDeleteConsumerGroupsNumRetries"
15441    )]
15442    async fn test_delete_consumer_groups_num_retries() {
15443        let default_api_timeout: i64 = 60000;
15444        let (admin, mut runnable, time, nodes) = env_nodes_with_props(
15445            3,
15446            &[
15447                ("default.api.timeout.ms", &default_api_timeout.to_string()),
15448                ("retries", "0"),
15449            ],
15450        );
15451        runnable
15452            .client_mut()
15453            .prepare_response(find_coordinator_resp(&[("groupId", &nodes[0])]));
15454        runnable
15455            .client_mut()
15456            .prepare_response(delete_groups_resp(&[("groupId", Errors::NotCoordinator)]));
15457        runnable
15458            .client_mut()
15459            .prepare_response(find_coordinator_resp(&[("groupId", &nodes[0])]));
15460
15461        let result =
15462            admin.delete_consumer_groups_with_options(&["groupId".to_string()], DeleteConsumerGroupsOptions::new());
15463        let all = result.all();
15464        pump_until(&mut runnable, 40, |r| !r.client_mut().has_pending_responses()).await;
15465        time.sleep(default_api_timeout + 1);
15466        drive_until(&mut runnable, &time, 40, || all.is_done()).await;
15467        assert!(matches!(all.get().await.unwrap_err(), Error::Timeout(_)));
15468    }
15469
15470    /// Translated from `testDeleteConsumerGroupsWithOlderBroker`: retriable
15471    /// `FindCoordinator` errors are retried, non-retriable ones fail, and
15472    /// coordinator-moved `DeleteGroups` errors trigger a re-lookup. Uses the old
15473    /// (single-coordinator) `FindCoordinator` response form throughout.
15474    #[tokio::test]
15475    #[doc(
15476        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testDeleteConsumerGroupsWithOlderBroker"
15477    )]
15478    async fn test_delete_consumer_groups_with_older_broker() {
15479        let (admin, mut runnable, time, nodes) = env_nodes_with_props(1, &[("retries", "2147483647")]);
15480
15481        // Retriable FindCoordinator errors are retried, then a good coordinator.
15482        runnable
15483            .client_mut()
15484            .prepare_response(old_find_coordinator_error_resp(Errors::CoordinatorNotAvailable));
15485        runnable
15486            .client_mut()
15487            .prepare_response(old_find_coordinator_error_resp(Errors::CoordinatorLoadInProgress));
15488        runnable.client_mut().prepare_response(old_find_coordinator_resp(&nodes[0]));
15489        runnable
15490            .client_mut()
15491            .prepare_response(delete_groups_resp(&[("groupId", Errors::None)]));
15492
15493        let result =
15494            admin.delete_consumer_groups_with_options(&["groupId".to_string()], DeleteConsumerGroupsOptions::new());
15495        let deleted = result.deleted_groups()["groupId"].clone();
15496        drive_until(&mut runnable, &time, 80, || deleted.is_done()).await;
15497        assert_eq!(deleted.get().await.unwrap(), ());
15498
15499        // A non-retriable FindCoordinator error surfaces.
15500        runnable
15501            .client_mut()
15502            .prepare_response(old_find_coordinator_error_resp(Errors::GroupAuthorizationFailed));
15503        let error_result =
15504            admin.delete_consumer_groups_with_options(&["groupId".to_string()], DeleteConsumerGroupsOptions::new());
15505        let error_deleted = error_result.deleted_groups()["groupId"].clone();
15506        drive_until(&mut runnable, &time, 80, || error_deleted.is_done()).await;
15507        assert_eq!(error_deleted.get().await.unwrap_err().error(), Errors::GroupAuthorizationFailed);
15508
15509        // Retriable DeleteGroups errors (load-in-progress, then coordinator moved)
15510        // are retried, with a re-lookup for the coordinator-moved errors.
15511        runnable.client_mut().prepare_response(old_find_coordinator_resp(&nodes[0]));
15512        runnable
15513            .client_mut()
15514            .prepare_response(delete_groups_resp(&[("groupId", Errors::CoordinatorLoadInProgress)]));
15515        runnable
15516            .client_mut()
15517            .prepare_response(delete_groups_resp(&[("groupId", Errors::NotCoordinator)]));
15518        runnable.client_mut().prepare_response(old_find_coordinator_resp(&nodes[0]));
15519        runnable
15520            .client_mut()
15521            .prepare_response(delete_groups_resp(&[("groupId", Errors::CoordinatorNotAvailable)]));
15522        runnable.client_mut().prepare_response(old_find_coordinator_resp(&nodes[0]));
15523        runnable
15524            .client_mut()
15525            .prepare_response(delete_groups_resp(&[("groupId", Errors::None)]));
15526
15527        let retry_result =
15528            admin.delete_consumer_groups_with_options(&["groupId".to_string()], DeleteConsumerGroupsOptions::new());
15529        let retry_deleted = retry_result.deleted_groups()["groupId"].clone();
15530        drive_until(&mut runnable, &time, 120, || retry_deleted.is_done()).await;
15531        assert_eq!(retry_deleted.get().await.unwrap(), ());
15532    }
15533
15534    /// Translated from `testRemoveMembersFromGroupNumRetries`.
15535    #[tokio::test]
15536    #[doc(
15537        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testRemoveMembersFromGroupNumRetries"
15538    )]
15539    async fn test_remove_members_from_group_num_retries() {
15540        let default_api_timeout: i64 = 60000;
15541        let (admin, mut runnable, time, nodes) = env_nodes_with_props(
15542            3,
15543            &[
15544                ("default.api.timeout.ms", &default_api_timeout.to_string()),
15545                ("retries", "0"),
15546            ],
15547        );
15548        runnable
15549            .client_mut()
15550            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15551        runnable
15552            .client_mut()
15553            .prepare_response(leave_group_top_level(Errors::NotCoordinator));
15554        runnable
15555            .client_mut()
15556            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15557
15558        let result = admin.remove_members_from_consumer_group_with_options(
15559            GROUP_ID,
15560            members_to_remove(&["instance-1", "instance-2"]),
15561        );
15562        let all = result.all();
15563        pump_until(&mut runnable, 40, |r| !r.client_mut().has_pending_responses()).await;
15564        time.sleep(default_api_timeout + 1);
15565        drive_until(&mut runnable, &time, 40, || all.is_done()).await;
15566        assert!(matches!(all.get().await.unwrap_err(), Error::Timeout(_)));
15567    }
15568
15569    /// Translated from `testRemoveMembersFromGroupRetriableErrors`.
15570    #[tokio::test]
15571    #[doc(
15572        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testRemoveMembersFromGroupRetriableErrors"
15573    )]
15574    async fn test_remove_members_from_group_retriable_errors() {
15575        let (admin, mut runnable, time, nodes) = offsets_env(1);
15576        runnable
15577            .client_mut()
15578            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15579        runnable
15580            .client_mut()
15581            .prepare_response(leave_group_top_level(Errors::CoordinatorLoadInProgress));
15582        runnable
15583            .client_mut()
15584            .prepare_response(leave_group_top_level(Errors::NotCoordinator));
15585        runnable
15586            .client_mut()
15587            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15588        runnable
15589            .client_mut()
15590            .prepare_response(leave_group_top_level(Errors::CoordinatorNotAvailable));
15591        runnable
15592            .client_mut()
15593            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15594        runnable
15595            .client_mut()
15596            .prepare_response(leave_group_members_resp(&[("instance-1", Errors::None)]));
15597
15598        let member = MemberToRemove::new("instance-1");
15599        let result =
15600            admin.remove_members_from_consumer_group_with_options(GROUP_ID, members_to_remove(&["instance-1"]));
15601        let all = result.all();
15602        drive_until(&mut runnable, &time, 120, || all.is_done()).await;
15603        assert_eq!(all.get().await.unwrap(), ());
15604        assert_eq!(result.member_result(&member).unwrap().get().await.unwrap(), ());
15605    }
15606
15607    /// Translated from `testRemoveMembersFromGroupNonRetriableErrors`.
15608    #[tokio::test]
15609    #[doc(
15610        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testRemoveMembersFromGroupNonRetriableErrors"
15611    )]
15612    async fn test_remove_members_from_group_non_retriable_errors() {
15613        let (admin, mut runnable, time, nodes) = offsets_env(1);
15614        for error in [
15615            Errors::GroupAuthorizationFailed,
15616            Errors::InvalidGroupId,
15617            Errors::GroupIdNotFound,
15618        ] {
15619            runnable
15620                .client_mut()
15621                .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15622            runnable.client_mut().prepare_response(leave_group_top_level(error));
15623
15624            let member = MemberToRemove::new("instance-1");
15625            let result =
15626                admin.remove_members_from_consumer_group_with_options(GROUP_ID, members_to_remove(&["instance-1"]));
15627            let all = result.all();
15628            drive_until(&mut runnable, &time, 60, || all.is_done()).await;
15629            assert_eq!(all.get().await.unwrap_err().error(), error);
15630            assert_eq!(result.member_result(&member).unwrap().get().await.unwrap_err().error(), error);
15631        }
15632    }
15633
15634    /// Translated from `testRemoveMembersFromGroup`: member-level error, then a
15635    /// missing member, then success, and finally the two `removeAll` scenarios.
15636    #[tokio::test]
15637    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testRemoveMembersFromGroup")]
15638    async fn test_remove_members_from_group() {
15639        let (admin, mut runnable, time, nodes) = offsets_env(1);
15640        let instance_one = "instance-1";
15641        let instance_two = "instance-2";
15642        let member_one = MemberToRemove::new(instance_one);
15643        let member_two = MemberToRemove::new(instance_two);
15644
15645        // Inject one member-level error (instance-1 -> UNKNOWN_MEMBER_ID).
15646        runnable
15647            .client_mut()
15648            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15649        runnable.client_mut().prepare_response(leave_group_members_resp(&[
15650            (instance_one, Errors::UnknownMemberId),
15651            (instance_two, Errors::None),
15652        ]));
15653
15654        let member_level_error_result = admin.remove_members_from_consumer_group_with_options(
15655            GROUP_ID,
15656            members_to_remove(&[instance_one, instance_two]),
15657        );
15658        let all = member_level_error_result.all();
15659        drive_until(&mut runnable, &time, 60, || all.is_done()).await;
15660        assert_eq!(all.get().await.unwrap_err().error(), Errors::UnknownMemberId);
15661        assert_eq!(
15662            member_level_error_result
15663                .member_result(&member_one)
15664                .unwrap()
15665                .get()
15666                .await
15667                .unwrap_err()
15668                .error(),
15669            Errors::UnknownMemberId
15670        );
15671        assert_eq!(
15672            member_level_error_result
15673                .member_result(&member_two)
15674                .unwrap()
15675                .get()
15676                .await
15677                .unwrap(),
15678            ()
15679        );
15680
15681        // Return with a missing member (instance-1 absent from the response).
15682        runnable
15683            .client_mut()
15684            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15685        runnable
15686            .client_mut()
15687            .prepare_response(leave_group_members_resp(&[(instance_two, Errors::None)]));
15688
15689        let missing_member_result = admin.remove_members_from_consumer_group_with_options(
15690            GROUP_ID,
15691            members_to_remove(&[instance_one, instance_two]),
15692        );
15693        let missing_all = missing_member_result.all();
15694        drive_until(&mut runnable, &time, 60, || missing_all.is_done()).await;
15695        assert!(matches!(missing_all.get().await.unwrap_err(), Error::LocalIllegalArgument(_)));
15696        assert!(matches!(
15697            missing_member_result
15698                .member_result(&member_one)
15699                .unwrap()
15700                .get()
15701                .await
15702                .unwrap_err(),
15703            Error::LocalIllegalArgument(_)
15704        ));
15705        assert_eq!(
15706            missing_member_result.member_result(&member_two).unwrap().get().await.unwrap(),
15707            ()
15708        );
15709
15710        // Return with success for both members.
15711        runnable
15712            .client_mut()
15713            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15714        runnable.client_mut().prepare_response(leave_group_members_resp(&[
15715            (instance_two, Errors::None),
15716            (instance_one, Errors::None),
15717        ]));
15718        let no_error_result = admin.remove_members_from_consumer_group_with_options(
15719            GROUP_ID,
15720            members_to_remove(&[instance_one, instance_two]),
15721        );
15722        let no_error_all = no_error_result.all();
15723        drive_until(&mut runnable, &time, 60, || no_error_all.is_done()).await;
15724        assert_eq!(no_error_all.get().await.unwrap(), ());
15725        assert_eq!(no_error_result.member_result(&member_one).unwrap().get().await.unwrap(), ());
15726        assert_eq!(no_error_result.member_result(&member_two).unwrap().get().await.unwrap(), ());
15727
15728        // removeAll with a partial failure: describe the group, then remove all
15729        // members but one reports UNKNOWN_MEMBER_ID.
15730        runnable
15731            .client_mut()
15732            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15733        runnable
15734            .client_mut()
15735            .prepare_response(consumer_group_describe_members_resp(GROUP_ID, &[instance_one, instance_two]));
15736        runnable
15737            .client_mut()
15738            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15739        runnable.client_mut().prepare_response(leave_group_members_resp(&[
15740            (instance_one, Errors::UnknownMemberId),
15741            (instance_two, Errors::None),
15742        ]));
15743        let partial_failure_result = admin.remove_members_from_consumer_group_with_options(
15744            GROUP_ID,
15745            RemoveMembersFromConsumerGroupOptions::default(),
15746        );
15747        let partial_all = partial_failure_result.all();
15748        drive_until(&mut runnable, &time, 80, || partial_all.is_done()).await;
15749        assert_eq!(partial_all.get().await.unwrap_err().error(), Errors::UnknownMemberId);
15750
15751        // removeAll with success.
15752        runnable
15753            .client_mut()
15754            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15755        runnable
15756            .client_mut()
15757            .prepare_response(consumer_group_describe_members_resp(GROUP_ID, &[instance_one, instance_two]));
15758        runnable
15759            .client_mut()
15760            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15761        runnable.client_mut().prepare_response(leave_group_members_resp(&[
15762            (instance_two, Errors::None),
15763            (instance_one, Errors::None),
15764        ]));
15765        let success_result = admin.remove_members_from_consumer_group_with_options(
15766            GROUP_ID,
15767            RemoveMembersFromConsumerGroupOptions::default(),
15768        );
15769        let success_all = success_result.all();
15770        drive_until(&mut runnable, &time, 80, || success_all.is_done()).await;
15771        assert_eq!(success_all.get().await.unwrap(), ());
15772    }
15773
15774    /// Regression test for the `removeAll` describe step's timeout source.
15775    ///
15776    /// Java issues the describe via
15777    /// `describeConsumerGroups(Collections.singleton(groupId))` with a *default*
15778    /// `DescribeConsumerGroupsOptions` (its `timeoutMs` is `null`), so the describe
15779    /// driver's deadline is `now + defaultApiTimeoutMs` — INDEPENDENT of the
15780    /// removeMembers request's `options.timeout_ms()`
15781    /// (`KafkaAdminClient#getMembersFromGroup`). This asserts the first describe
15782    /// request (the coordinator lookup) carries the default-API-timeout budget, not
15783    /// the small `options.timeout_ms()` budget, and so fails against code that ties
15784    /// the describe deadline to `options.timeout_ms()`.
15785    #[tokio::test]
15786    async fn test_remove_all_describe_uses_default_api_timeout() {
15787        use crate::common::protocol::ApiKeys;
15788        // request.timeout.ms equals default.api.timeout.ms (20000): an explicit
15789        // API timeout below the request timeout is a `ConfigException` (see
15790        // `configure_default_api_timeout_ms`). The clock moves 2000 ms between
15791        // the call and the send, so the budget tells all three sources apart:
15792        // the default-API-timeout deadline leaves 18000, the options.timeout
15793        // (5000) deadline 3000, and request.timeout.ms alone would be 20000.
15794        let (admin, mut runnable, time, _nodes) = env_with_props(&[
15795            ("request.timeout.ms", "20000"),
15796            ("default.api.timeout.ms", "20000"),
15797            ("retries", "2147483647"),
15798            ("retry.backoff.ms", "10"),
15799        ]);
15800        // No responses prepared: the describe coordinator-lookup request is sent
15801        // but stays queued (unanswered), ready for inspection.
15802        let options = RemoveMembersFromConsumerGroupOptions::default().set_timeout_ms(Some(5000));
15803        assert!(options.remove_all());
15804        let _result = admin.remove_members_from_consumer_group_with_options(GROUP_ID, options);
15805        time.sleep(2000);
15806
15807        pump_until(&mut runnable, 40, |r| r.client_mut().request_count() >= 1).await;
15808
15809        let requests = runnable.client_mut().requests();
15810        assert_eq!(requests.len(), 1, "only the describe coordinator lookup should be queued");
15811        let describe_lookup = &requests[0];
15812        assert_eq!(describe_lookup.api_key(), &ApiKeys::FIND_COORDINATOR);
15813        // The call at 1000 sets the describe deadline to 1000 +
15814        // default.api.timeout.ms == 21000; sent at 3000, the budget is
15815        // min(request.timeout.ms=20000, 21000-3000) == 18000. The buggy code
15816        // (describe deadline tied to options.timeout=5000) would yield
15817        // min(20000, 6000-3000) == 3000.
15818        assert_eq!(
15819            describe_lookup.request_timeout_ms(),
15820            18000,
15821            "describe step must use default.api.timeout.ms (20000), not options.timeout (5000)"
15822        );
15823    }
15824
15825    /// Regression test for the `removeAll` `LeaveGroup` deadline recomputation.
15826    ///
15827    /// Java computes the `LeaveGroup` driver's deadline INSIDE
15828    /// `memFuture.whenComplete(...)`, after the describe future resolves
15829    /// (`KafkaAdminClient#removeMembersFromConsumerGroup` →
15830    /// `invokeDriver(..., options.timeoutMs())` →
15831    /// `calcDeadlineMs(time.milliseconds(), ...)`), so `LeaveGroup` gets a fresh
15832    /// full timeout window starting when describe completes. Here the mock clock is
15833    /// advanced past the ORIGINAL (call-time) `options.timeout` window before
15834    /// describe completes: the fix recomputes the LeaveGroup deadline from the
15835    /// post-describe time (so its coordinator lookup is issued with a fresh 5000ms
15836    /// budget), whereas code that baked the pre-describe deadline would have the
15837    /// LeaveGroup window already expired and issue no request at all.
15838    #[tokio::test]
15839    async fn test_remove_all_leave_group_deadline_computed_after_describe() {
15840        use crate::common::protocol::ApiKeys;
15841        // default.api.timeout.ms is large so the describe step survives the clock
15842        // advance (the describe-timeout fix is a prerequisite); options.timeout
15843        // (5000) is smaller than request.timeout.ms so the LeaveGroup budget is
15844        // observable uncapped.
15845        let (admin, mut runnable, time, nodes) = env_with_props(&[
15846            ("request.timeout.ms", "30000"),
15847            ("default.api.timeout.ms", "60000"),
15848            ("retries", "2147483647"),
15849            ("retry.backoff.ms", "10"),
15850        ]);
15851        // Answer the describe (coordinator lookup + ConsumerGroupDescribe). Do NOT
15852        // prepare the LeaveGroup coordinator lookup, so it stays queued for
15853        // inspection.
15854        runnable
15855            .client_mut()
15856            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15857        runnable
15858            .client_mut()
15859            .prepare_response(consumer_group_describe_members_resp(GROUP_ID, &["instance-1"]));
15860
15861        let options = RemoveMembersFromConsumerGroupOptions::default().set_timeout_ms(Some(5000));
15862        assert!(options.remove_all());
15863        let _result = admin.remove_members_from_consumer_group_with_options(GROUP_ID, options);
15864
15865        // Advance the clock to 10000 — past the pre-describe LeaveGroup deadline
15866        // (call-time 1000 + options.timeout 5000 == 6000) — before describe is
15867        // driven. With the fix, the LeaveGroup deadline is recomputed from the
15868        // post-describe time (10000 + 5000 == 15000). Without it, the baked-in
15869        // window is already expired, describe/LeaveGroup time out, and no
15870        // LeaveGroup coordinator lookup is ever issued.
15871        time.sleep(9000);
15872
15873        pump_until(&mut runnable, 40, |r| {
15874            r.client_mut()
15875                .requests()
15876                .iter()
15877                .any(|req| req.api_key() == &ApiKeys::FIND_COORDINATOR)
15878        })
15879        .await;
15880
15881        let leave_lookup = runnable
15882            .client_mut()
15883            .requests()
15884            .iter()
15885            .find(|req| req.api_key() == &ApiKeys::FIND_COORDINATOR)
15886            .expect("the LeaveGroup coordinator lookup should be queued with a fresh deadline");
15887        // now == 10000, fresh LeaveGroup deadline == 10000 + options.timeout 5000
15888        // == 15000, budget == min(request.timeout.ms=30000, 15000-10000) == 5000.
15889        assert_eq!(
15890            leave_lookup.request_timeout_ms(),
15891            5000,
15892            "LeaveGroup deadline must be recomputed fresh after describe completes"
15893        );
15894    }
15895
15896    /// Drives one `removeMembersFromConsumerGroup` with the given `reason`,
15897    /// asserting the emitted `LeaveGroup` request carried `expected_reason` on
15898    /// every member. Mirrors the private Java helper
15899    /// `testRemoveMembersFromGroup(reason, expectedReason)` — Java attaches a
15900    /// request-matcher predicate to the prepared response; our `MockClient` has
15901    /// no such matcher, so we inspect the emitted (queued, unanswered) request
15902    /// directly, which is the established request-inspection pattern.
15903    async fn assert_remove_members_reason(reason: Option<&str>, expected_reason: &str) {
15904        use crate::common::requests::AbstractRequest;
15905        let (admin, mut runnable, _time, nodes) = offsets_env(3);
15906        // Answer only FindCoordinator so the LeaveGroup request is sent but stays
15907        // queued (no prepared response), ready for inspection.
15908        runnable
15909            .client_mut()
15910            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
15911
15912        let mut options = members_to_remove(&["instance-1", "instance-2"]);
15913        // Java calls `options.reason(reason)` with the given value, `null`
15914        // included.
15915        options.set_reason(reason.map(str::to_string));
15916        let _result = admin.remove_members_from_consumer_group_with_options(GROUP_ID, options);
15917
15918        pump_until(&mut runnable, 40, |r| {
15919            r.client_mut()
15920                .requests_mut()
15921                .iter_mut()
15922                .any(|req| matches!(req.request_builder_mut().build(), Ok(AbstractRequest::LeaveGroup(_))))
15923        })
15924        .await;
15925
15926        let leave_request = runnable
15927            .client_mut()
15928            .requests_mut()
15929            .iter_mut()
15930            .find_map(|req| match req.request_builder_mut().build() {
15931                Ok(AbstractRequest::LeaveGroup(r)) => Some(r),
15932                _ => None,
15933            })
15934            .expect("a LeaveGroup request should be queued");
15935        assert!(!leave_request.data().members.is_empty());
15936        for member in &leave_request.data().members {
15937            assert_eq!(member.reason.as_deref(), Some(expected_reason));
15938        }
15939    }
15940
15941    /// Translated from `testRemoveMembersFromGroupReason`.
15942    #[tokio::test]
15943    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testRemoveMembersFromGroupReason")]
15944    async fn test_remove_members_from_group_reason() {
15945        assert_remove_members_reason(Some("testing remove members reason"), "testing remove members reason").await;
15946    }
15947
15948    /// Translated from `testRemoveMembersFromGroupTruncatesReason`: a reason
15949    /// longer than 255 chars is truncated to exactly 255 on the wire.
15950    #[tokio::test]
15951    #[doc(
15952        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testRemoveMembersFromGroupTruncatesReason"
15953    )]
15954    async fn test_remove_members_from_group_truncates_reason() {
15955        let reason = "Very looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong reason that is 271 characters long to make sure that length limit logic handles the scenario nicely";
15956        assert_eq!(reason.chars().count(), 271);
15957        let truncated: String = reason.chars().take(255).collect();
15958        assert_remove_members_reason(Some(reason), &truncated).await;
15959    }
15960
15961    /// Translated from `testRemoveMembersFromGroupDefaultReason`: a null or empty
15962    /// reason falls back to the default reason.
15963    #[tokio::test]
15964    #[doc(
15965        alias = "org.apache.kafka.clients.admin.KafkaAdminClientConsumerGroupTest#testRemoveMembersFromGroupDefaultReason"
15966    )]
15967    async fn test_remove_members_from_group_default_reason() {
15968        assert_remove_members_reason(None, DEFAULT_LEAVE_GROUP_REASON).await;
15969        assert_remove_members_reason(Some(""), DEFAULT_LEAVE_GROUP_REASON).await;
15970    }
15971
15972    /// A [`MockClient`] whose `authentication_error` reports a failure, mirroring
15973    /// Java's `MockClient.authenticationException(node)` being non-null after
15974    /// `createPendingAuthenticationError`. `MockClient` (outside this module)
15975    /// always answers `None`, and the trait method is the only way the admin
15976    /// runnable learns about an authentication failure
15977    /// (`KafkaAdminClient.AdminClientRunnable#handleResponses`).
15978    struct AuthFailingClient {
15979        inner: MockClient,
15980        error: Option<Error>,
15981    }
15982
15983    impl AuthFailingClient {
15984        /// `error` is the object the channel would have raised, so the test can
15985        /// pick the *subclass* — which is the whole point of the regression it
15986        /// backs.
15987        fn new(inner: MockClient, error: Error) -> Self {
15988            Self { inner, error: Some(error) }
15989        }
15990    }
15991
15992    impl KafkaClient for AuthFailingClient {
15993        fn authentication_error(&self, _node: &Node) -> Option<Error> {
15994            self.error.clone()
15995        }
15996
15997        fn is_ready(&self, node: &Node, now: i64) -> bool {
15998            self.inner.is_ready(node, now)
15999        }
16000
16001        fn ready(&mut self, node: &Node, now: i64) -> impl std::future::Future<Output = bool> + Send {
16002            self.inner.ready(node, now)
16003        }
16004
16005        fn connection_delay(&self, node: &Node, now: i64) -> i64 {
16006            self.inner.connection_delay(node, now)
16007        }
16008
16009        fn poll_delay_ms(&self, node: &Node, now: i64) -> i64 {
16010            self.inner.poll_delay_ms(node, now)
16011        }
16012
16013        fn connection_failed(&self, node: &Node) -> bool {
16014            self.inner.connection_failed(node)
16015        }
16016
16017        fn send(&mut self, request: crate::ClientRequest, now: i64) {
16018            self.inner.send(request, now)
16019        }
16020
16021        fn poll(
16022            &mut self,
16023            timeout: i64,
16024            now: i64,
16025        ) -> impl std::future::Future<Output = Vec<crate::ClientResponse>> + Send {
16026            self.inner.poll(timeout, now)
16027        }
16028
16029        fn disconnect(&mut self, node_id: &str) -> impl std::future::Future<Output = ()> + Send {
16030            self.inner.disconnect(node_id)
16031        }
16032
16033        fn close_connection(&mut self, node_id: &str) -> impl std::future::Future<Output = ()> + Send {
16034            self.inner.close_connection(node_id)
16035        }
16036
16037        fn least_loaded_node(&self, now: i64) -> crate::LeastLoadedNode {
16038            self.inner.least_loaded_node(now)
16039        }
16040
16041        fn in_flight_request_count(&self) -> i32 {
16042            self.inner.in_flight_request_count()
16043        }
16044
16045        fn has_in_flight_requests(&self) -> bool {
16046            self.inner.has_in_flight_requests()
16047        }
16048
16049        fn in_flight_request_count_for_node(&self, node_id: &str) -> usize {
16050            self.inner.in_flight_request_count_for_node(node_id)
16051        }
16052
16053        fn has_in_flight_requests_for_node(&self, node_id: &str) -> bool {
16054            self.inner.has_in_flight_requests_for_node(node_id)
16055        }
16056
16057        fn has_ready_nodes(&self, now: i64) -> bool {
16058            self.inner.has_ready_nodes(now)
16059        }
16060
16061        fn wakeup(&self) {
16062            self.inner.wakeup()
16063        }
16064
16065        fn wakeup_handle(&self) -> Arc<Notify> {
16066            self.inner.wakeup_handle()
16067        }
16068
16069        fn wakeup_notify(&self) -> Arc<Notify> {
16070            self.inner.wakeup_notify()
16071        }
16072
16073        fn new_client_request(
16074            &mut self,
16075            node_id: &str,
16076            request_builder: Box<dyn crate::common::requests::RequestBuilder>,
16077            created_time_ms: i64,
16078            expect_response: bool,
16079        ) -> crate::ClientRequest {
16080            self.inner
16081                .new_client_request(node_id, request_builder, created_time_ms, expect_response)
16082        }
16083
16084        fn new_client_request_with_timeout(
16085            &mut self,
16086            node_id: &str,
16087            request_builder: Box<dyn crate::common::requests::RequestBuilder>,
16088            created_time_ms: i64,
16089            expect_response: bool,
16090            request_timeout_ms: i32,
16091            callback: Option<crate::RequestCompletionHandler>,
16092        ) -> crate::ClientRequest {
16093            self.inner.new_client_request_with_timeout(
16094                node_id,
16095                request_builder,
16096                created_time_ms,
16097                expect_response,
16098                request_timeout_ms,
16099                callback,
16100            )
16101        }
16102
16103        fn initiate_close(&self) {
16104            self.inner.initiate_close()
16105        }
16106
16107        fn active(&self) -> bool {
16108            self.inner.active()
16109        }
16110
16111        fn close(&mut self) -> impl std::future::Future<Output = ()> + Send {
16112            self.inner.close()
16113        }
16114    }
16115
16116    /// Regression for finding 242. Java propagates the exception **object** —
16117    /// `AuthenticationException authException = client.authenticationException(call.curNode());
16118    /// if (authException != null) call.fail(now, authException);`
16119    /// (`KafkaAdminClient.AdminClientRunnable#handleResponses`) — so whichever
16120    /// `AuthenticationException` subclass the channel raised is what the admin
16121    /// future fails with. Rust hardcoded `Errors::SaslAuthenticationFailed`,
16122    /// reporting code 58 for a TLS certificate rejection (the
16123    /// `catch (SslAuthenticationException e)` of `KafkaChannel#receive`), on a
16124    /// connection that never performed a SASL exchange.
16125    ///
16126    /// It also pins finding 231's other half: the reason must be the
16127    /// authenticator's own text, with no second class prefix baked into
16128    /// `message()`.
16129    #[tokio::test]
16130    async fn an_admin_authentication_failure_is_not_reported_as_sasl() {
16131        let time = mock_time(1000);
16132        let (cluster, nodes) = mock_cluster(3, 0);
16133        let inner = MockClient::with_static_nodes(nodes.clone(), Arc::clone(&time) as Arc<dyn Time>);
16134        let client = AuthFailingClient::new(
16135            inner,
16136            Error::SslAuthentication(crate::common::errors::SslAuthenticationError::new(
16137                "SSL handshake failed: certificate rejected",
16138            )),
16139        );
16140        let mut props = HashMap::new();
16141        props.insert("bootstrap.servers".to_string(), "localhost:9092".to_string());
16142        props.insert("retries".to_string(), "0".to_string());
16143        let config = AdminClientConfig::new(&props).unwrap();
16144        let (admin, mut runnable) =
16145            KafkaAdminClient::create_for_test(client, cluster, &config, Arc::clone(&time) as Arc<dyn Time>);
16146
16147        runnable
16148            .client_mut()
16149            .inner
16150            .prepare_response_disconnected(metadata_resp(&nodes, Vec::new()), true);
16151
16152        let result = admin.list_topics_with_options(ListTopicsOptions::new());
16153        let names = result.names();
16154        for _ in 0..40 {
16155            if names.is_done() {
16156                break;
16157            }
16158            runnable.run_once().await;
16159            time.sleep(200);
16160        }
16161        let error = names.get().await.expect_err("the authentication failure must fail the call");
16162
16163        // `retries=0` means the call is out of retries, so Java's
16164        // `handleTimeoutFailure` wraps the cause; the authentication error is the
16165        // cause. Unwrap it if present, otherwise the error itself is it.
16166        let auth = error.source().unwrap_or(&error);
16167        assert!(auth.is_authentication_error(), "must classify as authentication: {auth:?}");
16168        assert_ne!(
16169            auth.error(),
16170            Errors::SaslAuthenticationFailed,
16171            "an SSL rejection must not be reported as SASL_AUTHENTICATION_FAILED: {auth:?}"
16172        );
16173        // The class itself, not just the code: Java hands the object through, so a
16174        // caller matching on the subclass — which is how it tells a certificate
16175        // rejection from a rejected credential — still fires.
16176        assert!(
16177            matches!(auth, Error::SslAuthentication(_)),
16178            "the subclass the channel raised must survive: {auth:?}"
16179        );
16180        assert_eq!(
16181            auth.message(),
16182            "SSL handshake failed: certificate rejected",
16183            "the authenticator's bare text: no second class prefix (finding 231)"
16184        );
16185        assert!(
16186            crate::common::requests::RequestUtils::is_fatal_error(auth),
16187            "RequestUtils.isFatalException answers true for an AuthenticationException: {auth:?}"
16188        );
16189    }
16190
16191    /// Regression for finding 243(a). `handleFailure` on the `findAllBrokers`
16192    /// metadata call builds
16193    /// `new KafkaException("Failed to find brokers to send ListGroups", throwable)`
16194    /// (`KafkaAdminClient#listGroups`) — a **bare** `KafkaException`, which is a
16195    /// *sibling* of `ApiException`, not a subclass. So:
16196    ///
16197    ///   * `is_kafka_error()` is `true`, `is_api_error()` / `is_retriable_error()`
16198    ///     are `false`;
16199    ///   * the cause is reachable through `getCause()`;
16200    ///   * the message is fixed — it does NOT carry the cause's text.
16201    ///
16202    /// Reusing the inner error's code made the wrapper *inherit* the inner class,
16203    /// so a metadata timeout came back retriable and causeless.
16204    #[tokio::test]
16205    async fn list_groups_metadata_failure_is_a_bare_kafka_error() {
16206        // retries=0 so the disconnected metadata call fails terminally instead of
16207        // looping.
16208        let (admin, mut runnable, time, nodes) = env_with_props(&[("retries", "0")]);
16209        runnable
16210            .client_mut()
16211            .prepare_response_disconnected(metadata_resp(&nodes, Vec::new()), true);
16212
16213        let result = admin.list_groups_with_options(ListGroupsOptions::new());
16214        let errors = result.errors();
16215        drive_until(&mut runnable, &time, 60, || errors.is_done()).await;
16216
16217        let reported = errors.get().await.expect("the metadata failure is reported through errors()");
16218        assert_eq!(reported.len(), 1, "one wrapped error, got {reported:?}");
16219        let error = &reported[0];
16220
16221        assert_eq!(
16222            error.message(),
16223            "Failed to find brokers to send ListGroups",
16224            "Java's message is fixed: no lower-cased call name, no appended cause text"
16225        );
16226        assert!(error.is_kafka_error(), "a bare KafkaException is a Kafka error: {error:?}");
16227        assert!(
16228            !error.is_api_error(),
16229            "a bare KafkaException is a SIBLING of ApiException, not a subclass: {error:?}"
16230        );
16231        assert!(
16232            !error.is_retriable_error(),
16233            "the wrapper must not inherit the inner TimeoutException's retriability: {error:?}"
16234        );
16235        assert_eq!(
16236            error.error(),
16237            Errors::UnknownServerError,
16238            "a client-built KafkaException has no wire code"
16239        );
16240        let cause = error.source().expect("Java passes the throwable as the cause");
16241        assert!(
16242            cause.is_timeout_error(),
16243            "expected the metadata timeout as the cause; got {cause:?}"
16244        );
16245    }
16246
16247    /// Regression for finding 243(b). `KafkaAdminClient#getMembersFromGroup`'s
16248    /// `whenComplete` builds
16249    /// `new KafkaException("Encounter exception when trying to get members from group: " + groupId, ex)` —
16250    /// again a bare `KafkaException` carrying the cause, NOT the inner class.
16251    /// Inheriting the inner class turned a `GroupAuthorizationException` cause
16252    /// into an `is_authorization_error()` (and therefore `is_fatal_error()`)
16253    /// wrapper where Java answers `false` to both, and dropped the cause.
16254    ///
16255    /// ("exception" is reworded to "error" in the Rust message per CLAUDE.md §2.)
16256    #[tokio::test]
16257    async fn remove_all_describe_failure_is_a_bare_kafka_error() {
16258        let (admin, mut runnable, time, nodes) = offsets_env(1);
16259        runnable
16260            .client_mut()
16261            .prepare_response(find_coordinator_resp(&[(GROUP_ID, &nodes[0])]));
16262        runnable.client_mut().prepare_response(consumer_group_describe_error_resp(
16263            GROUP_ID,
16264            Errors::GroupAuthorizationFailed,
16265            None,
16266        ));
16267
16268        let result = admin.remove_members_from_consumer_group_with_options(
16269            GROUP_ID,
16270            RemoveMembersFromConsumerGroupOptions::default(),
16271        );
16272        let all = result.all();
16273        drive_until(&mut runnable, &time, 80, || all.is_done()).await;
16274        let error = all.get().await.expect_err("the describe step must fail the removeAll");
16275
16276        assert_eq!(
16277            error.message(),
16278            format!("Encounter error when trying to get members from group: {GROUP_ID}")
16279        );
16280        assert!(error.is_kafka_error(), "got {error:?}");
16281        assert!(!error.is_api_error(), "a bare KafkaException is not an ApiException: {error:?}");
16282        assert!(
16283            !error.is_authorization_error(),
16284            "the wrapper must not inherit GroupAuthorizationException: {error:?}"
16285        );
16286        assert!(
16287            !crate::common::requests::RequestUtils::is_fatal_error(&error),
16288            "and therefore must not be fatal: {error:?}"
16289        );
16290        let cause = error.source().expect("Java passes `ex` as the cause");
16291        assert_eq!(cause.error(), Errors::GroupAuthorizationFailed, "got {cause:?}");
16292        assert!(cause.is_authorization_error(), "the cause keeps its own class: {cause:?}");
16293    }
16294
16295    /// Regression for finding 246. `KafkaAdminClient#completeUnrealizedFutures`
16296    /// throws `new ApiException(messageFormatter.apply(key))` — the concrete base
16297    /// class. It was spelled `Errors::UnknownServerError`, which resolves to the
16298    /// `UnknownServerException` *subclass*, so `Display` read
16299    /// `"UnknownServerError: .."` and `matches!(e, Error::Api(_))` never matched.
16300    ///
16301    /// Java uses `new UnknownServerException(..)` for its *other* response sanity
16302    /// checks (in `KafkaAdminClient#createAcls`, `KafkaAdminClient#deleteAcls`
16303    /// and `KafkaAdminClient#alterPartitionReassignments`), so this is not a
16304    /// blanket sweep.
16305    #[tokio::test]
16306    async fn an_unrealized_future_fails_with_a_bare_api_error() {
16307        let (admin, mut runnable, _time, _nodes) = env();
16308        let result = admin.create_topics_with_options(
16309            &[NewTopic::with_num_partitions_replication_factor(
16310                "myTopic",
16311                Some(1),
16312                Some(1),
16313            )],
16314            CreateTopicsOptions::new(),
16315        );
16316        // The broker answers with no per-topic result at all, so the requested
16317        // topic's future is left unrealized (`completeUnrealizedFutures`).
16318        runnable.client_mut().prepare_response(create_response(vec![]));
16319        for _ in 0..20 {
16320            if result.values()["myTopic"].is_done() {
16321                break;
16322            }
16323            runnable.run_once().await;
16324        }
16325
16326        let error = result.values()["myTopic"]
16327            .get()
16328            .await
16329            .expect_err("an unrealized future must fail");
16330        assert!(
16331            matches!(error, Error::Api(_)),
16332            "Java throws the concrete `ApiException`, not a subclass: {error:?}"
16333        );
16334        assert_eq!(
16335            error.message(),
16336            "The controller response did not contain a result for topic myTopic"
16337        );
16338        assert_eq!(
16339            error.to_string(),
16340            "ApiError: The controller response did not contain a result for topic myTopic",
16341            "Display names the class Java threw"
16342        );
16343        assert!(error.is_api_error(), "got {error:?}");
16344        assert!(error.is_kafka_error(), "an ApiException is a KafkaException: {error:?}");
16345        assert!(
16346            !error.is_retriable_error(),
16347            "the concrete ApiException is not retriable: {error:?}"
16348        );
16349    }
16350
16351    /// Regression for finding 247(a). Java rejects a call submitted once the
16352    /// client is closing with
16353    /// `new IllegalStateException("Cannot accept new calls when AdminClient is closing.")`
16354    /// (`KafkaAdminClient.AdminClientRunnable#call`). The Rust text had drifted
16355    /// to "The AdminClient is closed.", which is not the sanctioned
16356    /// "exception"->"error" rewording.
16357    #[tokio::test]
16358    async fn a_call_submitted_while_closing_uses_javas_message() {
16359        let (admin, _runnable, _time, _nodes) = env();
16360        admin.close_with_timeout(Duration::from_millis(0)).await;
16361
16362        let result = admin.list_topics_with_options(ListTopicsOptions::new());
16363        let error = result
16364            .names()
16365            .get()
16366            .await
16367            .expect_err("a call submitted while closing must fail");
16368
16369        assert_eq!(error.message(), "Cannot accept new calls when AdminClient is closing.");
16370        // Java throws an `IllegalStateException`, which is outside the
16371        // `KafkaException` hierarchy entirely.
16372        assert!(matches!(error, Error::LocalIllegalState(_)), "got {error:?}");
16373        assert!(!error.is_kafka_error(), "got {error:?}");
16374    }
16375
16376    /// Regression for finding 247. `KafkaAdminClient#handleNotControllerError`
16377    /// rethrows `error.exception()` for the code it matched, so a
16378    /// `NOT_LEADER_OR_FOLLOWER` seen by a `bootstrap.controllers` client surfaces
16379    /// as `NotLeaderOrFollower`. Rust always reported `NotController`.
16380    #[test]
16381    fn handle_not_controller_error_reports_the_matched_code() {
16382        let with_controllers = AdminMetadataManager::new(100, 1000, true, LogContext::empty());
16383        let without_controllers = AdminMetadataManager::new(100, 1000, false, LogContext::empty());
16384
16385        let not_controller = HashMap::from([(Errors::NotController, 1)]);
16386        let not_leader = HashMap::from([(Errors::NotLeaderOrFollower, 1)]);
16387
16388        assert_eq!(
16389            handle_not_controller_error(&without_controllers, &not_controller).map(|e| e.error()),
16390            Some(Errors::NotController)
16391        );
16392        assert_eq!(
16393            handle_not_controller_error(&with_controllers, &not_controller).map(|e| e.error()),
16394            Some(Errors::NotController)
16395        );
16396        assert_eq!(
16397            handle_not_controller_error(&with_controllers, &not_leader).map(|e| e.error()),
16398            Some(Errors::NotLeaderOrFollower),
16399            "Java rethrows the error built for the code it matched (`KafkaAdminClient#handleNotControllerError`)"
16400        );
16401        assert!(
16402            handle_not_controller_error(&without_controllers, &not_leader).is_none(),
16403            "the NOT_LEADER_OR_FOLLOWER arm is gated on usingBootstrapControllers"
16404        );
16405    }
16406
16407    /// A retry backoff with no jitter, so a test can assert `nextAllowedTryMs`.
16408    fn test_retry_backoff() -> ExponentialBackoff {
16409        ExponentialBackoff::new(100, RETRY_BACKOFF_EXP_BASE, 1000, 0.0).expect("a valid backoff")
16410    }
16411
16412    /// `KafkaAdminClient.AdminClientRunnable#call` hands a call that a
16413    /// `bootstrap.controllers` client cannot serve to `call.fail(now, ..)`.
16414    /// `KafkaAdminClient.Call#fail` counts the try and advances `nextAllowedTryMs`,
16415    /// then fails with `handleTimeoutFailure` when the deadline has already passed and
16416    /// with `handleFailure` otherwise; a `closing` runnable fails it at once.
16417    #[test]
16418    fn a_call_rejected_for_bootstrap_controllers_goes_through_call_fail() {
16419        fn rejected(deadline_ms: i64, captured: &Arc<Mutex<Option<Error>>>) -> Call {
16420            let captured = Arc::clone(captured);
16421            Call::new(
16422                "listTopics",
16423                deadline_ms,
16424                NodeProvider::LeastLoaded,
16425                Box::new(|_timeout_ms| unreachable!("a rejected call is never sent")),
16426                Box::new(|_response, _now, _cur_node| HandleResult::Done),
16427                Box::new(move |error| *captured.lock().unwrap() = Some(error.clone())),
16428                Box::new(|_| false),
16429            )
16430        }
16431        let endpoint_message =
16432            "This Admin API is not yet supported when communicating directly with the controller quorum.";
16433        let backoff = test_retry_backoff();
16434        let now = 1_000;
16435        let shutdown = ShutdownSignal::new();
16436
16437        // Deadline already passed (Java's `timeoutMs <= 0`): a TimeoutException
16438        // caused by the rejection.
16439        let captured = Arc::new(Mutex::new(None));
16440        assert!(shutdown.admit_new_call(true, &backoff, now, rejected(now, &captured)).is_none());
16441        let error = captured.lock().unwrap().take().expect("the call failed");
16442        assert!(matches!(error, Error::Timeout(_)), "got {error:?}");
16443        assert_eq!(
16444            error.message(),
16445            "Call(callName=listTopics, deadlineMs=1000, tries=1, nextAllowedTryMs=1100) timed out at 1000 after 1 \
16446             attempt(s)"
16447        );
16448        let cause = error.source().expect("the rejection is the cause");
16449        assert!(matches!(cause, Error::UnsupportedEndpointType(_)), "got {cause:?}");
16450        assert_eq!(cause.message(), endpoint_message);
16451
16452        // Deadline still ahead: the rejection itself.
16453        let captured = Arc::new(Mutex::new(None));
16454        assert!(
16455            shutdown
16456                .admit_new_call(true, &backoff, now, rejected(now + 1, &captured))
16457                .is_none()
16458        );
16459        let error = captured.lock().unwrap().take().expect("the call failed");
16460        assert!(matches!(error, Error::UnsupportedEndpointType(_)), "got {error:?}");
16461        assert_eq!(error.message(), endpoint_message);
16462
16463        // A closing runnable skips the deadline check.
16464        shutdown.closing.store(true, Ordering::Release);
16465        let captured = Arc::new(Mutex::new(None));
16466        assert!(shutdown.admit_new_call(true, &backoff, now, rejected(now, &captured)).is_none());
16467        let error = captured.lock().unwrap().take().expect("the call failed");
16468        assert!(matches!(error, Error::UnsupportedEndpointType(_)), "got {error:?}");
16469    }
16470
16471    // --- bootstrap.controllers (KIP-919) -------------------------------------
16472    //
16473    // `KafkaAdminClientTest.testCallFailWithUnsupportedVersionExceptionDoesNotHaveConcurrentModificationException`
16474    // is not translated. It replaces `AdminMetadataManager` with a Mockito mock
16475    // whose `requestUpdate()` throws once, so that `Call.fail` re-adds the call
16476    // to `pendingCalls` while `maybeDrainPendingCalls` iterates it. The Rust
16477    // manager is a concrete type with no such seam, and the hazard cannot
16478    // arise: `maybe_drain_pending_calls` takes the pending list out before it
16479    // iterates, and appends what `fail_call` re-queues afterwards. The
16480    // `AddRaftVoter` / `RemoveRaftVoter` tests, the other Java tests that set
16481    // `bootstrap.controllers`, need RPCs this client does not have.
16482
16483    /// Java's `mockClientEnv(AdminClientConfig.BOOTSTRAP_CONTROLLERS_CONFIG,
16484    /// "dummy")`: [`env_with_props`] with `bootstrap.controllers` set, so the
16485    /// client talks to the controllers, which the three mock nodes stand for
16486    /// (node 0 is the active controller). As in Java's `AdminClientUnitTestEnv`,
16487    /// the config keeps `bootstrap.servers` too.
16488    fn controller_env() -> (KafkaAdminClient, AdminClientRunnable<MockClient>, Arc<MockTime>, Vec<Node>) {
16489        env_with_props(&[(AdminClientConfig::BOOTSTRAP_CONTROLLERS_CONFIG, "dummy")])
16490    }
16491
16492    /// [`controller_env`] seeded with `cluster` instead of the three-node mock
16493    /// cluster.
16494    fn controller_env_with_cluster(
16495        cluster: Cluster,
16496    ) -> (KafkaAdminClient, AdminClientRunnable<MockClient>, Arc<MockTime>, Vec<Node>) {
16497        let time = mock_time(1000);
16498        let nodes = cluster.nodes().to_vec();
16499        let client = MockClient::with_static_nodes(nodes.clone(), Arc::clone(&time) as Arc<dyn Time>);
16500        let props = HashMap::from([
16501            (
16502                AdminClientConfig::BOOTSTRAP_SERVERS_CONFIG.to_string(),
16503                "localhost:9092".to_string(),
16504            ),
16505            (AdminClientConfig::BOOTSTRAP_CONTROLLERS_CONFIG.to_string(), "dummy".to_string()),
16506        ]);
16507        let config = AdminClientConfig::new(&props).unwrap();
16508        let (admin, runnable) =
16509            KafkaAdminClient::create_for_test(client, cluster, &config, Arc::clone(&time) as Arc<dyn Time>);
16510        (admin, runnable, time, nodes)
16511    }
16512
16513    /// A client that knows only its bootstrap address, as `new_inner` leaves
16514    /// it, so its first call needs a metadata refresh: the bootstrap cluster of
16515    /// `localhost:9093` (node -1). With `using_bootstrap_controllers` the config
16516    /// sets `bootstrap.controllers` (to that address), otherwise only
16517    /// `bootstrap.servers`. The three mock nodes are what the refresh can name.
16518    fn bootstrapping_env(
16519        using_bootstrap_controllers: bool,
16520    ) -> (KafkaAdminClient, AdminClientRunnable<MockClient>, Arc<MockTime>, Vec<Node>) {
16521        let time = mock_time(1000);
16522        let (_cluster, nodes) = mock_cluster(3, 0);
16523        let client = MockClient::with_static_nodes(nodes.clone(), Arc::clone(&time) as Arc<dyn Time>);
16524        let mut props = HashMap::from([(
16525            AdminClientConfig::BOOTSTRAP_SERVERS_CONFIG.to_string(),
16526            "localhost:9092".to_string(),
16527        )]);
16528        if using_bootstrap_controllers {
16529            props.insert(
16530                AdminClientConfig::BOOTSTRAP_CONTROLLERS_CONFIG.to_string(),
16531                "localhost:9093".to_string(),
16532            );
16533        }
16534        let config = AdminClientConfig::new(&props).unwrap();
16535        let bootstrap = Cluster::bootstrap(&[("localhost".to_string(), "127.0.0.1:9093".parse().unwrap())]);
16536        let (admin, runnable) =
16537            KafkaAdminClient::create_for_test(client, bootstrap, &config, Arc::clone(&time) as Arc<dyn Time>);
16538        (admin, runnable, time, nodes)
16539    }
16540
16541    /// Matches the metadata refresh of a `bootstrap.controllers` client: a
16542    /// `DescribeCluster` request for the CONTROLLER endpoint, without the
16543    /// authorized operations (the `createRequest` of
16544    /// `KafkaAdminClient.AdminClientRunnable#makeControllerMetadataCall`).
16545    fn controller_metadata_request() -> crate::RequestMatcher {
16546        Box::new(|request| {
16547            matches!(
16548                request,
16549                AbstractRequest::DescribeCluster(request)
16550                    if request.data().endpoint_type == EndpointType::Controller.id()
16551                        && !request.data().include_cluster_authorized_operations
16552                        && !request.data().include_fenced_brokers
16553            )
16554        })
16555    }
16556
16557    /// Java's `UnsupportedEndpointTypeException` text for a call a
16558    /// `bootstrap.controllers` client cannot send (`KafkaAdminClient.AdminClientRunnable#call`).
16559    const UNSUPPORTED_ENDPOINT_MESSAGE: &str =
16560        "This Admin API is not yet supported when communicating directly with the controller quorum.";
16561
16562    fn assert_unsupported_endpoint_type(api: &str, error: Error) {
16563        assert!(matches!(error, Error::UnsupportedEndpointType(_)), "{api}: got {error:?}");
16564        assert_eq!(error.message(), UNSUPPORTED_ENDPOINT_MESSAGE, "{api}");
16565    }
16566
16567    /// Translated from `KafkaAdminClientTest.testParseDescribeClusterResponseWithError`.
16568    #[test]
16569    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testParseDescribeClusterResponseWithError")]
16570    fn test_parse_describe_cluster_response_with_error() {
16571        let message =
16572            "The request was sent to an endpoint of type BROKER, but we wanted an endpoint of type CONTROLLER";
16573        let mut data = DescribeClusterResponseData::new();
16574        data.set_error_code(Errors::MismatchedEndpointType.code());
16575        data.set_error_message(Some(message.to_string()));
16576        let error = KafkaAdminClient::parse_describe_cluster_response(&data).unwrap_err();
16577        assert!(matches!(error, Error::MismatchedEndpointType(_)), "got {error:?}");
16578        assert_eq!(error.message(), message);
16579    }
16580
16581    /// Translated from
16582    /// `KafkaAdminClientTest.testParseDescribeClusterResponseWithUnexpectedEndpointType`.
16583    #[test]
16584    #[doc(
16585        alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testParseDescribeClusterResponseWithUnexpectedEndpointType"
16586    )]
16587    fn test_parse_describe_cluster_response_with_unexpected_endpoint_type() {
16588        let mut data = DescribeClusterResponseData::new();
16589        data.set_endpoint_type(EndpointType::Broker.id());
16590        let error = KafkaAdminClient::parse_describe_cluster_response(&data).unwrap_err();
16591        assert!(matches!(error, Error::MismatchedEndpointType(_)), "got {error:?}");
16592        assert_eq!(
16593            error.message(),
16594            "Expected response from CONTROLLER endpoint, but got response from endpoint type 1"
16595        );
16596    }
16597
16598    /// Translated from `KafkaAdminClientTest.testParseSuccessfulDescribeClusterResponse`
16599    /// (`@ValueSource(booleans = {false, true})`).
16600    #[test]
16601    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientTest#testParseSuccessfulDescribeClusterResponse")]
16602    fn test_parse_successful_describe_cluster_response() {
16603        for include_controller in [false, true] {
16604            let mut data = DescribeClusterResponseData::new();
16605            data.set_controller_id(if include_controller { 0 } else { -1 });
16606            data.set_endpoint_type(EndpointType::Controller.id());
16607            data.set_cluster_id("Ek8tjqq1QBWfnaoyHFZqDg".to_string());
16608            data.set_brokers(
16609                (0..3)
16610                    .map(|id| {
16611                        let mut broker = DescribeClusterBroker::new();
16612                        broker.set_broker_id(id);
16613                        broker.set_host(format!("controller{id}.com"));
16614                        broker.set_port(9092);
16615                        broker
16616                    })
16617                    .collect(),
16618            );
16619            let cluster = KafkaAdminClient::parse_describe_cluster_response(&data).unwrap();
16620            if include_controller {
16621                assert_eq!(cluster.controller().map(Node::id), Some(0));
16622            } else {
16623                assert!(cluster.controller().is_none());
16624            }
16625            assert_eq!(cluster.cluster_resource().cluster_id(), Some("Ek8tjqq1QBWfnaoyHFZqDg"));
16626            assert_eq!(
16627                HashSet::from([
16628                    Node::new(0, "controller0.com".to_string(), 9092),
16629                    Node::new(1, "controller1.com".to_string(), 9092),
16630                    Node::new(2, "controller2.com".to_string(), 9092),
16631                ]),
16632                cluster.nodes().iter().cloned().collect::<HashSet<Node>>()
16633            );
16634        }
16635    }
16636
16637    /// Translated from `KafkaAdminClientConfigTest.testIncrementalAlterConfigsToController`.
16638    ///
16639    /// The default BROKER resource of a `bootstrap.controllers` client goes to
16640    /// the active controller (node 0). The NOT_CONTROLLER answer is followed by
16641    /// the `DescribeCluster` refresh of the CONTROLLER endpoint, and the retry
16642    /// goes to the controller it names (node 2).
16643    #[tokio::test]
16644    #[doc(alias = "org.apache.kafka.clients.admin.KafkaAdminClientConfigTest#testIncrementalAlterConfigsToController")]
16645    async fn test_incremental_alter_configs_to_controller() {
16646        let (admin, mut runnable, time, nodes) = controller_env();
16647
16648        //test NOT_CONTROLLER error scenarios
16649        runnable.client_mut().prepare_response_from(
16650            incremental_alter_configs_response(vec![alter_configs_resource_response(
16651                "",
16652                config_resource::Type::Broker.id(),
16653                Errors::NotController,
16654                "not controller",
16655            )]),
16656            &nodes[0],
16657        );
16658
16659        // should retry the describe cluster to update the metadata
16660        runnable.client_mut().prepare_response_matcher(
16661            controller_metadata_request(),
16662            prepare_describe_cluster_response(
16663                0,
16664                &nodes,
16665                "mock-cluster",
16666                2,
16667                MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED,
16668                true,
16669            ),
16670        );
16671
16672        // `.setErrorMessage(ApiError.NONE.message())`, which is `null`.
16673        let mut success = alter_configs_resource_response("", config_resource::Type::Broker.id(), Errors::None, "");
16674        success.set_error_message(None);
16675
16676        let broker_resource = ConfigResource::new(config_resource::Type::Broker, String::new());
16677        let alter_config_op1 = AlterConfigOp::new(
16678            ConfigEntry::new("log.segment.bytes".to_string(), Some("1073741".to_string())),
16679            OpType::Set,
16680        );
16681        let configs = HashMap::from([(broker_resource.clone(), vec![alter_config_op1])]);
16682        runnable
16683            .client_mut()
16684            .prepare_response_from(incremental_alter_configs_response(vec![success]), &nodes[2]);
16685        let result = admin.incremental_alter_configs_with_options(&configs, AlterConfigsOptions::new());
16686        for _ in 0..30 {
16687            if result.values()[&broker_resource].is_done() {
16688                break;
16689            }
16690            runnable.run_once().await;
16691            time.sleep(200);
16692        }
16693        assert!(
16694            result.values()[&broker_resource].is_done(),
16695            "the retry after the refresh must complete"
16696        );
16697        result.all().get().await.unwrap();
16698        assert_eq!(runnable.metadata_manager().controller().map(|node| node.id()), Some(2));
16699    }
16700
16701    /// What a broker-only call's rejection resolved to: `None` when the call was
16702    /// not rejected as it was submitted, else its error.
16703    type Rejection = std::pin::Pin<Box<dyn std::future::Future<Output = Option<Error>>>>;
16704
16705    /// [`Rejection`] of `future`, read only once it is done, so a call that is
16706    /// sent instead of rejected cannot hang the test.
16707    fn rejection<T: Send + 'static>(future: KafkaFuture<T>) -> Rejection {
16708        Box::pin(async move {
16709            if !future.is_done() {
16710                return None;
16711            }
16712            future.get().await.err()
16713        })
16714    }
16715
16716    /// `KafkaAdminClient.AdminClientRunnable#call`: a
16717    /// `bootstrap.controllers` client fails every call whose node provider
16718    /// cannot reach a controller at once, with Java's message, and sends
16719    /// nothing. Covers every public API whose provider answers `false`: the
16720    /// least-loaded node (the topic, quota, SCRAM-describe, delegation-token
16721    /// and config-resource APIs, `listGroups`' broker lookup, and the
16722    /// `AdminApiDriver`'s coordinator, partition-leader and all-brokers
16723    /// lookups), the controller with `supportsUseControllers` false
16724    /// (`createTopics`, `createPartitions`, `deleteTopics`, `electLeaders`,
16725    /// `alterUserScramCredentials`) and a constant broker id with it false (the
16726    /// three log-dir APIs). The controller-capable APIs are
16727    /// `controller_capable_apis_are_sent_in_controller_mode`'s; between them the
16728    /// two tests cover the whole `Admin` surface.
16729    #[tokio::test]
16730    async fn broker_only_apis_fail_with_unsupported_endpoint_type_in_controller_mode() {
16731        type Issue = Box<dyn Fn(&KafkaAdminClient) -> Rejection>;
16732        let tp = || TopicPartition::new("topic", 0);
16733        let replica = || TopicPartitionReplica::new("topic".to_string(), 0, 0);
16734        let groups = || vec!["group".to_string()];
16735        let cases: Vec<(&str, Issue)> = vec![
16736            (
16737                "listTopics",
16738                Box::new(|a| rejection(a.list_topics_with_options(ListTopicsOptions::new()).names())),
16739            ),
16740            (
16741                "describeTopics by id",
16742                Box::new(|a| {
16743                    let topics = TopicCollection::of_topic_ids(vec![Uuid::random_uuid()]);
16744                    rejection(
16745                        a.describe_topics_with_topics_options(topics, DescribeTopicsOptions::new())
16746                            .all_topic_ids()
16747                            .expect("a by-id result"),
16748                    )
16749                }),
16750            ),
16751            (
16752                "createTopics",
16753                Box::new(|a| {
16754                    let topic = NewTopic::with_num_partitions_replication_factor("topic", Some(1), Some(1));
16755                    rejection(a.create_topics_with_options(&[topic], CreateTopicsOptions::new()).all())
16756                }),
16757            ),
16758            (
16759                "createPartitions",
16760                Box::new(|a| {
16761                    let partitions = HashMap::from([("topic".to_string(), NewPartitions::increase_to(2))]);
16762                    rejection(
16763                        a.create_partitions_with_options(&partitions, CreatePartitionsOptions::new())
16764                            .all(),
16765                    )
16766                }),
16767            ),
16768            (
16769                "deleteTopics by name",
16770                Box::new(|a| {
16771                    let topics = TopicCollection::of_topic_names(vec!["topic".to_string()]);
16772                    rejection(
16773                        a.delete_topics_with_topic_collection_options(topics, DeleteTopicsOptions::new())
16774                            .all(),
16775                    )
16776                }),
16777            ),
16778            (
16779                "deleteTopics by id",
16780                Box::new(|a| {
16781                    let topics = TopicCollection::of_topic_ids(vec![Uuid::random_uuid()]);
16782                    rejection(
16783                        a.delete_topics_with_topic_collection_options(topics, DeleteTopicsOptions::new())
16784                            .all(),
16785                    )
16786                }),
16787            ),
16788            (
16789                "deleteTopics with topic names",
16790                Box::new(|a| {
16791                    rejection(
16792                        a.delete_topics_with_string_slice_options(&["topic".to_string()], DeleteTopicsOptions::new())
16793                            .all(),
16794                    )
16795                }),
16796            ),
16797            (
16798                "deleteRecords",
16799                Box::new(move |a| {
16800                    let records = HashMap::from([(tp(), RecordsToDelete::with_offset(1))]);
16801                    rejection(a.delete_records_with_options(&records, DeleteRecordsOptions::new()).all())
16802                }),
16803            ),
16804            (
16805                "listOffsets",
16806                Box::new(move |a| {
16807                    let offsets = HashMap::from([(tp(), OffsetSpec::latest())]);
16808                    rejection(a.list_offsets_with_options(&offsets, ListOffsetsOptions::new()).all())
16809                }),
16810            ),
16811            (
16812                "electLeaders",
16813                Box::new(move |a| {
16814                    let partitions = HashSet::from([tp()]);
16815                    rejection(
16816                        a.elect_leaders_with_options(
16817                            ElectionType::Preferred,
16818                            Some(partitions),
16819                            ElectLeadersOptions::new(),
16820                        )
16821                        .all(),
16822                    )
16823                }),
16824            ),
16825            (
16826                "describeLogDirs",
16827                Box::new(|a| {
16828                    rejection(
16829                        a.describe_log_dirs_with_options(&[0], DescribeLogDirsOptions::new())
16830                            .all_descriptions(),
16831                    )
16832                }),
16833            ),
16834            (
16835                "alterReplicaLogDirs",
16836                Box::new(move |a| {
16837                    let assignment = HashMap::from([(replica(), "/tmp/log".to_string())]);
16838                    rejection(
16839                        a.alter_replica_log_dirs_with_options(&assignment, AlterReplicaLogDirsOptions::new())
16840                            .all(),
16841                    )
16842                }),
16843            ),
16844            (
16845                "describeReplicaLogDirs",
16846                Box::new(move |a| {
16847                    rejection(
16848                        a.describe_replica_log_dirs_with_options(&[replica()], DescribeReplicaLogDirsOptions::new())
16849                            .all(),
16850                    )
16851                }),
16852            ),
16853            (
16854                "listConfigResources",
16855                Box::new(|a| {
16856                    rejection(
16857                        a.list_config_resources_with_options(&HashSet::new(), ListConfigResourcesOptions::new())
16858                            .all(),
16859                    )
16860                }),
16861            ),
16862            (
16863                "listGroups",
16864                Box::new(|a| rejection(a.list_groups_with_options(ListGroupsOptions::new()).all())),
16865            ),
16866            (
16867                "describeConsumerGroups",
16868                Box::new(move |a| {
16869                    rejection(
16870                        a.describe_consumer_groups_with_options(&groups(), DescribeConsumerGroupsOptions::new())
16871                            .all(),
16872                    )
16873                }),
16874            ),
16875            (
16876                "describeClassicGroups",
16877                Box::new(move |a| {
16878                    rejection(
16879                        a.describe_classic_groups_with_options(&groups(), DescribeClassicGroupsOptions::new())
16880                            .all(),
16881                    )
16882                }),
16883            ),
16884            (
16885                "deleteConsumerGroups",
16886                Box::new(move |a| {
16887                    rejection(
16888                        a.delete_consumer_groups_with_options(&groups(), DeleteConsumerGroupsOptions::new())
16889                            .all(),
16890                    )
16891                }),
16892            ),
16893            (
16894                "listConsumerGroupOffsets",
16895                Box::new(|a| {
16896                    rejection(
16897                        a.list_consumer_group_offsets_with_group_id_options(
16898                            "group",
16899                            ListConsumerGroupOffsetsOptions::new(),
16900                        )
16901                        .all(),
16902                    )
16903                }),
16904            ),
16905            (
16906                "alterConsumerGroupOffsets",
16907                Box::new(move |a| {
16908                    let offsets = HashMap::from([(tp(), OffsetAndMetadata::new(1).unwrap())]);
16909                    rejection(
16910                        a.alter_consumer_group_offsets_with_options(
16911                            "group",
16912                            &offsets,
16913                            AlterConsumerGroupOffsetsOptions::new(),
16914                        )
16915                        .all(),
16916                    )
16917                }),
16918            ),
16919            (
16920                "deleteConsumerGroupOffsets",
16921                Box::new(move |a| {
16922                    let partitions = HashSet::from([tp()]);
16923                    rejection(
16924                        a.delete_consumer_group_offsets_with_options(
16925                            "group",
16926                            &partitions,
16927                            DeleteConsumerGroupOffsetsOptions::new(),
16928                        )
16929                        .all(),
16930                    )
16931                }),
16932            ),
16933            (
16934                "removeMembersFromConsumerGroup",
16935                Box::new(|a| {
16936                    rejection(
16937                        a.remove_members_from_consumer_group_with_options(
16938                            "group",
16939                            RemoveMembersFromConsumerGroupOptions::default(),
16940                        )
16941                        .all(),
16942                    )
16943                }),
16944            ),
16945            (
16946                "describeProducers",
16947                Box::new(move |a| {
16948                    rejection(
16949                        a.describe_producers_with_options(&[tp()], DescribeProducersOptions::new())
16950                            .all(),
16951                    )
16952                }),
16953            ),
16954            (
16955                "abortTransaction",
16956                Box::new(move |a| {
16957                    let spec = AbortTransactionSpec::new(tp(), 1, 0, 0);
16958                    rejection(a.abort_transaction_with_options(spec, AbortTransactionOptions::new()).all())
16959                }),
16960            ),
16961            (
16962                "describeTransactions",
16963                Box::new(|a| {
16964                    rejection(
16965                        a.describe_transactions_with_options(&["txn".to_string()], DescribeTransactionsOptions::new())
16966                            .all(),
16967                    )
16968                }),
16969            ),
16970            (
16971                "fenceProducers",
16972                Box::new(|a| {
16973                    rejection(
16974                        a.fence_producers_with_options(&["txn".to_string()], FenceProducersOptions::new())
16975                            .all(),
16976                    )
16977                }),
16978            ),
16979            (
16980                "listTransactions",
16981                Box::new(|a| rejection(a.list_transactions_with_options(ListTransactionsOptions::new()).all())),
16982            ),
16983            (
16984                "forceTerminateTransaction",
16985                Box::new(|a| {
16986                    rejection(
16987                        a.force_terminate_transaction_with_options("txn", TerminateTransactionOptions::new())
16988                            .result(),
16989                    )
16990                }),
16991            ),
16992            (
16993                "describeClientQuotas",
16994                Box::new(|a| {
16995                    rejection(
16996                        a.describe_client_quotas_with_options(
16997                            &ClientQuotaFilter::all(),
16998                            DescribeClientQuotasOptions::new(),
16999                        )
17000                        .entities()
17001                        .clone(),
17002                    )
17003                }),
17004            ),
17005            (
17006                "alterClientQuotas",
17007                Box::new(|a| {
17008                    let entity = ClientQuotaEntity::new(HashMap::from([(
17009                        ClientQuotaEntity::USER.to_string(),
17010                        Some("user".to_string()),
17011                    )]));
17012                    let alteration = ClientQuotaAlteration::new(entity, vec![Op::new("consumer_byte_rate", Some(1.0))]);
17013                    rejection(
17014                        a.alter_client_quotas_with_options(&[alteration], AlterClientQuotasOptions::new())
17015                            .all(),
17016                    )
17017                }),
17018            ),
17019            (
17020                "describeUserScramCredentials",
17021                Box::new(|a| {
17022                    rejection(
17023                        a.describe_user_scram_credentials_with_users_options(
17024                            &[],
17025                            DescribeUserScramCredentialsOptions::new(),
17026                        )
17027                        .all(),
17028                    )
17029                }),
17030            ),
17031            (
17032                "alterUserScramCredentials",
17033                Box::new(|a| {
17034                    let deletion = UserScramCredentialAlteration::Deletion(UserScramCredentialDeletion::new(
17035                        "user",
17036                        ScramMechanism::ScramSha256,
17037                    ));
17038                    rejection(
17039                        a.alter_user_scram_credentials_with_options(
17040                            &[deletion],
17041                            AlterUserScramCredentialsOptions::new(),
17042                        )
17043                        .all(),
17044                    )
17045                }),
17046            ),
17047            (
17048                "createDelegationToken",
17049                Box::new(|a| {
17050                    rejection(
17051                        a.create_delegation_token_with_options(CreateDelegationTokenOptions::new())
17052                            .delegation_token()
17053                            .clone(),
17054                    )
17055                }),
17056            ),
17057            (
17058                "renewDelegationToken",
17059                Box::new(|a| {
17060                    rejection(
17061                        a.renew_delegation_token_with_options(b"hmac", RenewDelegationTokenOptions::new())
17062                            .expiry_timestamp()
17063                            .clone(),
17064                    )
17065                }),
17066            ),
17067            (
17068                "expireDelegationToken",
17069                Box::new(|a| {
17070                    rejection(
17071                        a.expire_delegation_token_with_options(b"hmac", ExpireDelegationTokenOptions::new())
17072                            .expiry_timestamp()
17073                            .clone(),
17074                    )
17075                }),
17076            ),
17077            (
17078                "describeDelegationToken",
17079                Box::new(|a| {
17080                    rejection(
17081                        a.describe_delegation_token_with_options(DescribeDelegationTokenOptions::new())
17082                            .delegation_tokens()
17083                            .clone(),
17084                    )
17085                }),
17086            ),
17087        ];
17088
17089        let (admin, mut runnable, _time, nodes) = controller_env();
17090        for (api, issue) in &cases {
17091            // Each call is rejected when it is submitted, so its future is done
17092            // as soon as the call returns.
17093            let error = issue(&admin)
17094                .await
17095                .unwrap_or_else(|| panic!("{api}: the call was not rejected"));
17096            // Two APIs wrap the rejection, as Java does: `findAllBrokers`'
17097            // `handleFailure` in `KafkaAdminClient#listGroups` and
17098            // `KafkaAdminClient#getMembersFromGroup`.
17099            let wrapper = match *api {
17100                "listGroups" => Some("Failed to find brokers to send ListGroups"),
17101                "removeMembersFromConsumerGroup" => {
17102                    Some("Encounter error when trying to get members from group: group")
17103                },
17104                _ => None,
17105            };
17106            match wrapper {
17107                Some(message) => {
17108                    assert_eq!(error.message(), message, "{api}");
17109                    assert_unsupported_endpoint_type(api, error.source().expect("the cause").clone());
17110                },
17111                None => assert_unsupported_endpoint_type(api, error),
17112            }
17113        }
17114
17115        pump(&mut runnable, 5).await;
17116        assert_eq!(runnable.client_mut().request_count(), 0, "nothing is sent");
17117
17118        // describeTopics by name first describes the cluster, which a controller
17119        // answers, and only then submits its DescribeTopicPartitions call, which
17120        // is rejected, as in Java's
17121        // `KafkaAdminClient#handleDescribeTopicsByNamesWithDescribeTopicPartitionsApi`.
17122        runnable.client_mut().prepare_response(prepare_describe_cluster_response(
17123            0,
17124            &nodes,
17125            "mock-cluster",
17126            0,
17127            MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED,
17128            true,
17129        ));
17130        let by_name = admin
17131            .describe_topics_with_topic_names_options(&["topic".to_string()], DescribeTopicsOptions::new())
17132            .all_topic_names()
17133            .expect("a by-name result");
17134        pump_until(&mut runnable, 20, |_| by_name.is_done()).await;
17135        assert!(by_name.is_done(), "describeTopics by name: the call was not rejected");
17136        assert_unsupported_endpoint_type("describeTopics by name", by_name.get().await.unwrap_err());
17137    }
17138
17139    /// The calls a `bootstrap.controllers` client may send: those whose Java
17140    /// node provider is `ControllerNodeProvider(true)` or
17141    /// `ConstantNodeIdProvider(node, true)` (`describeConfigs`,
17142    /// `incrementalAlterConfigs`, `alterPartitionReassignments`,
17143    /// `listPartitionReassignments`, `describeFeatures`, `updateFeatures`),
17144    /// and those using
17145    /// `LeastLoadedBrokerOrActiveKController`, which go to the active
17146    /// controller (node 0). Each is sent to the node Java sends it to.
17147    #[tokio::test]
17148    async fn controller_capable_apis_are_sent_in_controller_mode() {
17149        type Issue = Box<dyn Fn(&KafkaAdminClient)>;
17150        let partition = TopicPartition::new("topic", 0);
17151        let broker_1 = ConfigResource::new(config_resource::Type::Broker, "1".to_string());
17152        let broker_logger_1 = ConfigResource::new(config_resource::Type::BrokerLogger, "1".to_string());
17153        let set = |name: &str| {
17154            vec![AlterConfigOp::new(
17155                ConfigEntry::new(name.to_string(), Some("1".to_string())),
17156                OpType::Set,
17157            )]
17158        };
17159        let cases: Vec<(&str, Issue, &'static ApiKeys, &str)> = vec![
17160            (
17161                "alterPartitionReassignments",
17162                Box::new(move |admin: &KafkaAdminClient| {
17163                    let reassignments =
17164                        HashMap::from([(partition.clone(), Some(NewPartitionReassignment::new(vec![1, 2]).unwrap()))]);
17165                    admin.alter_partition_reassignments_with_options(
17166                        &reassignments,
17167                        AlterPartitionReassignmentsOptions::new(),
17168                    );
17169                }),
17170                &ApiKeys::ALTER_PARTITION_REASSIGNMENTS,
17171                "0",
17172            ),
17173            (
17174                "listPartitionReassignments",
17175                Box::new(|admin: &KafkaAdminClient| {
17176                    admin.list_partition_reassignments_with_options(ListPartitionReassignmentsOptions::new());
17177                }),
17178                &ApiKeys::LIST_PARTITION_REASSIGNMENTS,
17179                "0",
17180            ),
17181            (
17182                "updateFeatures",
17183                Box::new(|admin: &KafkaAdminClient| {
17184                    let updates = HashMap::from([(
17185                        "test_feature".to_string(),
17186                        FeatureUpdate::new(2, UpgradeType::Upgrade).unwrap(),
17187                    )]);
17188                    admin
17189                        .update_features_with_options(&updates, UpdateFeaturesOptions::new())
17190                        .unwrap();
17191                }),
17192                &ApiKeys::UPDATE_FEATURES,
17193                "0",
17194            ),
17195            (
17196                "describeConfigs by node",
17197                Box::new({
17198                    let broker_1 = broker_1.clone();
17199                    move |admin: &KafkaAdminClient| {
17200                        admin.describe_configs_with_options(
17201                            std::slice::from_ref(&broker_1),
17202                            DescribeConfigsOptions::new(),
17203                        );
17204                    }
17205                }),
17206                &ApiKeys::DESCRIBE_CONFIGS,
17207                "1",
17208            ),
17209            (
17210                "incrementalAlterConfigs to a broker logger",
17211                Box::new({
17212                    let configs = HashMap::from([(broker_logger_1, set("kafka.server.KafkaApis"))]);
17213                    move |admin: &KafkaAdminClient| {
17214                        admin.incremental_alter_configs_with_options(&configs, AlterConfigsOptions::new());
17215                    }
17216                }),
17217                &ApiKeys::INCREMENTAL_ALTER_CONFIGS,
17218                "1",
17219            ),
17220            (
17221                // A specific BROKER resource goes to the active controller, not to
17222                // the node it names (`KafkaAdminClient#incrementalAlterConfigs`).
17223                "incrementalAlterConfigs to a broker",
17224                Box::new({
17225                    let configs = HashMap::from([(broker_1, set("log.segment.bytes"))]);
17226                    move |admin: &KafkaAdminClient| {
17227                        admin.incremental_alter_configs_with_options(&configs, AlterConfigsOptions::new());
17228                    }
17229                }),
17230                &ApiKeys::INCREMENTAL_ALTER_CONFIGS,
17231                "0",
17232            ),
17233            (
17234                "describeFeatures with a node id",
17235                Box::new(|admin: &KafkaAdminClient| {
17236                    admin.describe_features_with_options(DescribeFeaturesOptions::new().set_node_id(1));
17237                }),
17238                &ApiKeys::API_VERSIONS,
17239                "1",
17240            ),
17241            (
17242                "describeCluster",
17243                Box::new(|admin: &KafkaAdminClient| {
17244                    admin.describe_cluster_with_options(DescribeClusterOptions::new());
17245                }),
17246                &ApiKeys::DESCRIBE_CLUSTER,
17247                "0",
17248            ),
17249            (
17250                "createAcls",
17251                Box::new(|admin: &KafkaAdminClient| {
17252                    admin.create_acls_with_options(&[acl1()], CreateAclsOptions::new());
17253                }),
17254                &ApiKeys::CREATE_ACLS,
17255                "0",
17256            ),
17257            (
17258                "unregisterController",
17259                Box::new(|admin: &KafkaAdminClient| {
17260                    admin.unregister_controller_with_options(1, UnregisterControllerOptions::new());
17261                }),
17262                &ApiKeys::UNREGISTER_CONTROLLER,
17263                "0",
17264            ),
17265        ];
17266        for (api, issue, api_key, destination) in cases {
17267            let (admin, mut runnable, _time, _nodes) = controller_env();
17268            issue(&admin);
17269            pump(&mut runnable, 5).await;
17270            let requests = runnable.client_mut().requests();
17271            assert_eq!(requests.len(), 1, "{api}");
17272            assert_eq!(requests[0].api_key(), api_key, "{api}");
17273            assert_eq!(requests[0].destination(), destination, "{api}");
17274        }
17275    }
17276
17277    /// `describeCluster` asks a `bootstrap.controllers` client's controllers to
17278    /// describe the CONTROLLER endpoint, and cannot ask them for fenced brokers,
17279    /// as the `createRequest` of `KafkaAdminClient#describeCluster`'s call
17280    /// decides: the `createRequest` failure is wrapped as an internal error, as
17281    /// `sendEligibleCalls` wraps it.
17282    #[tokio::test]
17283    async fn describe_cluster_describes_the_controller_endpoint_in_controller_mode() {
17284        let (admin, mut runnable, _time, _nodes) = controller_env();
17285        let _result = admin.describe_cluster_with_options(DescribeClusterOptions::new());
17286        pump_until_request_queued(&mut runnable).await;
17287        match runnable.client_mut().requests_mut()[0].request_builder_mut().build().unwrap() {
17288            AbstractRequest::DescribeCluster(request) => {
17289                assert_eq!(request.data().endpoint_type, EndpointType::Controller.id());
17290            },
17291            other => panic!("expected a DescribeCluster request, got {other:?}"),
17292        }
17293
17294        let (admin, mut runnable, _time, _nodes) = controller_env();
17295        let result =
17296            admin.describe_cluster_with_options(DescribeClusterOptions::new().set_include_fenced_brokers(true));
17297        pump(&mut runnable, 5).await;
17298        assert!(result.nodes().is_done());
17299        let error = result.nodes().get().await.unwrap_err();
17300        assert!(
17301            error.message().starts_with("Internal error sending listNodes to "),
17302            "got {:?}",
17303            error.message()
17304        );
17305        let cause = error.source().expect("the createRequest failure is the cause");
17306        assert!(matches!(cause, Error::LocalIllegalArgument(_)), "got {cause:?}");
17307        assert_eq!(cause.message(), "Cannot request fenced brokers from controller endpoint");
17308        assert_eq!(runnable.client_mut().request_count(), 0, "nothing is sent");
17309    }
17310
17311    /// `KafkaAdminClient.AdminClientRunnable#makeControllerMetadataCall`: a
17312    /// `bootstrap.controllers` client that only knows its bootstrap address
17313    /// refreshes its metadata with `DescribeCluster` for the CONTROLLER
17314    /// endpoint, takes the controllers it names as its nodes and the active
17315    /// one as its controller, and then sends the waiting call to that
17316    /// controller.
17317    #[tokio::test]
17318    async fn the_controller_metadata_refresh_describes_the_controller_endpoint() {
17319        let (admin, mut runnable, _time, nodes) = bootstrapping_env(true);
17320        let result = admin.describe_cluster_with_options(DescribeClusterOptions::new());
17321
17322        pump_until_request_queued(&mut runnable).await;
17323        {
17324            let requests = runnable.client_mut().requests_mut();
17325            assert_eq!(requests.len(), 1);
17326            match requests[0].request_builder_mut().build().unwrap() {
17327                AbstractRequest::DescribeCluster(request) => {
17328                    assert_eq!(request.data().endpoint_type, EndpointType::Controller.id());
17329                    assert!(!request.data().include_cluster_authorized_operations);
17330                },
17331                other => panic!("expected the DescribeCluster metadata refresh, got {other:?}"),
17332            }
17333        }
17334        runnable.client_mut().respond(prepare_describe_cluster_response(
17335            0,
17336            &nodes,
17337            "mock-cluster",
17338            1,
17339            MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED,
17340            true,
17341        ));
17342
17343        // The waiting `describeCluster` call goes to the active controller.
17344        pump_until_request_queued(&mut runnable).await;
17345        let manager = runnable.metadata_manager();
17346        assert!(manager.is_ready().unwrap());
17347        assert_eq!(manager.controller().map(|node| node.id()), Some(1));
17348        let mut ids: Vec<i32> = manager.updater().fetch_nodes().iter().map(Node::id).collect();
17349        ids.sort_unstable();
17350        assert_eq!(ids, vec![0, 1, 2]);
17351        {
17352            let requests = runnable.client_mut().requests_mut();
17353            assert_eq!(requests.len(), 1);
17354            assert_eq!(requests[0].destination(), "1");
17355            match requests[0].request_builder_mut().build().unwrap() {
17356                AbstractRequest::DescribeCluster(request) => {
17357                    assert_eq!(request.data().endpoint_type, EndpointType::Controller.id());
17358                },
17359                other => panic!("expected the describeCluster call, got {other:?}"),
17360            }
17361        }
17362        runnable.client_mut().respond(prepare_describe_cluster_response(
17363            0,
17364            &nodes,
17365            "mock-cluster",
17366            1,
17367            MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED,
17368            true,
17369        ));
17370        pump(&mut runnable, 3).await;
17371        assert!(result.controller().is_done());
17372        assert_eq!(result.controller().get().await.unwrap().map(|node| node.id()), Some(1));
17373        assert_eq!(result.nodes().get().await.unwrap().len(), 3);
17374    }
17375
17376    /// `KafkaAdminClient.AdminClientRunnable#makeControllerMetadataCall`'s
17377    /// `handleResponse`: a refresh answered by a BROKER
17378    /// endpoint fails with `parseDescribeClusterResponse`'s
17379    /// `MismatchedEndpointTypeException`, which `updateFailed` keeps as fatal
17380    /// (`RequestUtils.isFatalException`), so the waiting call fails with it.
17381    #[tokio::test]
17382    async fn a_broker_endpoint_answer_fails_the_controller_metadata_refresh() {
17383        let (admin, mut runnable, _time, nodes) = bootstrapping_env(true);
17384        let result = admin.describe_cluster_with_options(DescribeClusterOptions::new());
17385        runnable.client_mut().prepare_response_matcher(
17386            controller_metadata_request(),
17387            prepare_describe_cluster_response(
17388                0,
17389                &nodes,
17390                "mock-cluster",
17391                1,
17392                MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED,
17393                false,
17394            ),
17395        );
17396        pump(&mut runnable, 5).await;
17397
17398        let message = "Expected response from CONTROLLER endpoint, but got response from endpoint type 1";
17399        assert!(result.nodes().is_done(), "the waiting call fails");
17400        let error = result.nodes().get().await.unwrap_err();
17401        assert!(matches!(error, Error::MismatchedEndpointType(_)), "got {error:?}");
17402        assert_eq!(error.message(), message);
17403        let error = runnable.metadata_manager().is_ready().unwrap_err();
17404        assert!(matches!(error, Error::MismatchedEndpointType(_)), "got {error:?}");
17405        assert_eq!(runnable.client_mut().request_count(), 0, "nothing else is sent");
17406    }
17407
17408    /// Both metadata calls
17409    /// (`KafkaAdminClient.AdminClientRunnable#makeControllerMetadataCall` and
17410    /// `#makeBrokerMetadataCall`) override `handleUnsupportedVersionException`
17411    /// with `metadataManager.updateFailed(e)`. It matters when the `UnsupportedVersionException` arrives
17412    /// past the call's deadline: `Call.fail` then ends in
17413    /// `handleTimeoutFailure`, whose `TimeoutException` is not fatal, so only the
17414    /// hook keeps the fatal error, and `isReady()` reports it.
17415    #[tokio::test]
17416    async fn a_late_unsupported_version_failure_of_a_metadata_call_is_kept() {
17417        for using_bootstrap_controllers in [false, true] {
17418            let (admin, mut runnable, time, _nodes) = bootstrapping_env(using_bootstrap_controllers);
17419            assert_eq!(
17420                runnable.metadata_manager().using_bootstrap_controllers(),
17421                using_bootstrap_controllers
17422            );
17423            // The response arrives once the default `request.timeout.ms` (the
17424            // metadata call's deadline) has passed.
17425            let advanced = Arc::new(std::sync::atomic::AtomicBool::new(false));
17426            let poll_time = Arc::clone(&time);
17427            runnable
17428                .client_mut()
17429                .advance_time_during_poll(Some(Arc::new(move |_timeout_ms| {
17430                    if !advanced.swap(true, Ordering::AcqRel) {
17431                        poll_time.sleep(30_001);
17432                    }
17433                })));
17434            runnable.client_mut().prepare_unsupported_version_response();
17435            let _result = admin.describe_cluster_with_options(DescribeClusterOptions::new());
17436            pump(&mut runnable, 1).await;
17437
17438            let error = runnable.metadata_manager().is_ready().unwrap_err();
17439            assert!(
17440                matches!(error, Error::UnsupportedVersion(_)),
17441                "controllers {using_bootstrap_controllers}: got {error:?}"
17442            );
17443        }
17444    }
17445
17446    /// `KafkaAdminClient.LeastLoadedBrokerOrActiveKController#provide` returns
17447    /// `metadataManager.controller()` for a `bootstrap.controllers` client:
17448    /// with no known controller the call
17449    /// stays pending, and the provider, unlike `ControllerNodeProvider`, does
17450    /// not request a metadata update for it.
17451    #[tokio::test]
17452    async fn no_known_controller_leaves_the_call_pending_without_a_metadata_refresh() {
17453        let (cluster, _nodes) = mock_cluster(3, -1);
17454        assert!(cluster.controller().is_none());
17455        let (admin, mut runnable, time, _nodes) = controller_env_with_cluster(cluster);
17456        let result = admin.describe_acls_with_options(&filter1(), DescribeAclsOptions::new());
17457        pump(&mut runnable, 5).await;
17458
17459        assert!(!result.values().is_done());
17460        assert_eq!(runnable.client_mut().request_count(), 0, "nothing is sent, not even a refresh");
17461        assert!(
17462            runnable.metadata_manager().metadata_fetch_delay_ms(time.milliseconds()) > 0,
17463            "no metadata update is requested"
17464        );
17465    }
17466
17467    /// A client whose controller (node 0) is throttled, so a call bound to it
17468    /// waits, while a metadata refresh goes to node 1 (`MockClient`'s
17469    /// least-loaded node is the first of its nodes that is not backing off).
17470    /// With `using_bootstrap_controllers` the config also sets
17471    /// `bootstrap.controllers`.
17472    fn throttled_controller_env(
17473        using_bootstrap_controllers: bool,
17474    ) -> (KafkaAdminClient, AdminClientRunnable<MockClient>, Arc<MockTime>, Vec<Node>) {
17475        let time = mock_time(1000);
17476        let (_cluster, nodes) = mock_cluster(3, 0);
17477        let client_nodes = vec![nodes[1].clone(), nodes[2].clone(), nodes[0].clone()];
17478        let cluster = Cluster::with_controller(
17479            Some("mock-cluster".to_string()),
17480            client_nodes.clone(),
17481            Vec::new(),
17482            HashSet::new(),
17483            HashSet::new(),
17484            Some(nodes[0].clone()),
17485        );
17486        let mut client = MockClient::with_static_nodes(client_nodes, Arc::clone(&time) as Arc<dyn Time>);
17487        client.throttle(&nodes[0], 10_000);
17488        let mut props = HashMap::from([(
17489            AdminClientConfig::BOOTSTRAP_SERVERS_CONFIG.to_string(),
17490            "localhost:9092".to_string(),
17491        )]);
17492        if using_bootstrap_controllers {
17493            props.insert(AdminClientConfig::BOOTSTRAP_CONTROLLERS_CONFIG.to_string(), "dummy".to_string());
17494        }
17495        let config = AdminClientConfig::new(&props).unwrap();
17496        let (admin, runnable) =
17497            KafkaAdminClient::create_for_test(client, cluster, &config, Arc::clone(&time) as Arc<dyn Time>);
17498        (admin, runnable, time, nodes)
17499    }
17500
17501    /// Both metadata calls
17502    /// (`KafkaAdminClient.AdminClientRunnable#makeControllerMetadataCall` and
17503    /// `#makeBrokerMetadataCall`) end their `handleResponse` with
17504    /// `unassignUnsentCalls(node -> true)`: a call assigned to a node that is not ready yet goes back to
17505    /// the pending calls, so the refreshed metadata picks its node. The
17506    /// controller-bound call waits on the throttled node 0; the refresh names
17507    /// node 2 the controller, and the call goes there instead of waiting out
17508    /// node 0.
17509    #[tokio::test]
17510    async fn a_metadata_refresh_unassigns_the_unsent_calls() {
17511        for using_bootstrap_controllers in [false, true] {
17512            let mode = if using_bootstrap_controllers {
17513                "controllers"
17514            } else {
17515                "servers"
17516            };
17517            let (admin, mut runnable, _time, nodes) = throttled_controller_env(using_bootstrap_controllers);
17518
17519            // A call bound to the controller: `createAcls` goes to the active
17520            // controller of a `bootstrap.controllers` client, `createTopics` to
17521            // the controller of a broker client.
17522            let done: Box<dyn Fn() -> bool> = if using_bootstrap_controllers {
17523                let result = admin.create_acls_with_options(&[acl1()], CreateAclsOptions::new());
17524                runnable
17525                    .client_mut()
17526                    .prepare_response_from(create_acls_response(vec![create_acls_result_ok()]), &nodes[2]);
17527                Box::new(move || result.all().is_done())
17528            } else {
17529                let result = admin.create_topics_with_options(
17530                    &[NewTopic::with_num_partitions_replication_factor(
17531                        "topic",
17532                        Some(1),
17533                        Some(1),
17534                    )],
17535                    CreateTopicsOptions::new(),
17536                );
17537                runnable.client_mut().prepare_response_from(
17538                    create_response(vec![create_result("topic", Errors::None, None)]),
17539                    &nodes[2],
17540                );
17541                Box::new(move || result.all().is_done())
17542            };
17543            pump(&mut runnable, 2).await;
17544            assert!(!done(), "{mode}: the call waits for the throttled controller");
17545            assert_eq!(runnable.client_mut().request_count(), 0, "{mode}");
17546
17547            // Something asks for fresh metadata; the refresh names node 2.
17548            if using_bootstrap_controllers {
17549                runnable.client_mut().prepare_response_matcher(
17550                    controller_metadata_request(),
17551                    prepare_describe_cluster_response(
17552                        0,
17553                        &nodes,
17554                        "mock-cluster",
17555                        2,
17556                        MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED,
17557                        true,
17558                    ),
17559                );
17560            } else {
17561                runnable.client_mut().prepare_response_matcher(
17562                    Box::new(|request| matches!(request, AbstractRequest::Metadata(_))),
17563                    ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
17564                        &nodes,
17565                        Some("mock-cluster"),
17566                        2,
17567                        Vec::new(),
17568                    )),
17569                );
17570            }
17571            runnable.metadata_manager().request_update();
17572            pump(&mut runnable, 3).await;
17573
17574            assert_eq!(
17575                runnable.metadata_manager().controller().map(|node| node.id()),
17576                Some(2),
17577                "{mode}"
17578            );
17579            assert!(
17580                done(),
17581                "{mode}: the call is sent to the new controller without waiting for node 0"
17582            );
17583        }
17584    }
17585
17586    /// `KafkaAdminClient.AdminClientRunnable#makeControllerMetadataCall`'s
17587    /// `handleResponse` returns right after `handleFailure(e)` when
17588    /// `parseDescribeClusterResponse` throws, before `unassignUnsentCalls`: a call
17589    /// already assigned to a node stays assigned, and keeps waiting for it,
17590    /// instead of failing with the error the failed refresh left behind.
17591    #[tokio::test]
17592    async fn a_failed_controller_metadata_refresh_leaves_the_unsent_calls_assigned() {
17593        let (admin, mut runnable, _time, nodes) = throttled_controller_env(true);
17594        let result = admin.create_acls_with_options(&[acl1()], CreateAclsOptions::new());
17595        pump(&mut runnable, 2).await;
17596
17597        runnable.client_mut().prepare_response_matcher(
17598            controller_metadata_request(),
17599            prepare_describe_cluster_response(
17600                0,
17601                &nodes,
17602                "mock-cluster",
17603                2,
17604                MetadataResponse::AUTHORIZED_OPERATIONS_OMITTED,
17605                false,
17606            ),
17607        );
17608        runnable.metadata_manager().request_update();
17609        pump(&mut runnable, 3).await;
17610
17611        let error = runnable.metadata_manager().is_ready().unwrap_err();
17612        assert!(matches!(error, Error::MismatchedEndpointType(_)), "got {error:?}");
17613        assert!(!result.all().is_done(), "the call still waits for node 0");
17614        assert_eq!(runnable.metadata_manager().controller().map(|node| node.id()), Some(0));
17615    }
17616
17617    /// `bootstrap.controllers` alone builds a client that talks to the
17618    /// controllers (KIP-919): `createInternal` uses the controllers list for
17619    /// the bootstrap cluster and the `NetworkClient`'s bootstrap configuration
17620    /// (`bootstrapAddressesToUse` in `KafkaAdminClient#createInternal`), and fails a
17621    /// call the controllers cannot serve at once.
17622    #[tokio::test]
17623    async fn bootstrap_controllers_alone_builds_a_client() {
17624        let fetched_addresses = |admin: &KafkaAdminClient| -> Vec<(String, i32)> {
17625            admin
17626                .shared
17627                .metadata_manager
17628                .updater()
17629                .fetch_nodes()
17630                .iter()
17631                .map(|node| (node.host().to_string(), node.port()))
17632                .collect()
17633        };
17634
17635        let admin = KafkaAdminClient::new(bootstrap_config(None, Some("127.0.0.1:9093")))
17636            .expect("bootstrap.controllers alone builds a client");
17637        assert!(admin.shared.metadata_manager.using_bootstrap_controllers());
17638        assert_eq!(fetched_addresses(&admin), vec![("127.0.0.1".to_string(), 9093)]);
17639        let error = admin
17640            .list_topics_with_options(ListTopicsOptions::new())
17641            .names()
17642            .get()
17643            .await
17644            .unwrap_err();
17645        assert_unsupported_endpoint_type("listTopics", error);
17646        admin.close_with_timeout(Duration::ZERO).await;
17647
17648        let admin = KafkaAdminClient::new(bootstrap_config(Some("127.0.0.1:9092"), None)).expect("a broker client");
17649        assert!(!admin.shared.metadata_manager.using_bootstrap_controllers());
17650        assert_eq!(fetched_addresses(&admin), vec![("127.0.0.1".to_string(), 9092)]);
17651        admin.close_with_timeout(Duration::ZERO).await;
17652
17653        // `bootstrap.resolve.timeout.ms` > 0 (KIP-909): the `NetworkClient`
17654        // resolves the controllers list itself, on its first poll.
17655        let mut props = HashMap::from([
17656            (
17657                AdminClientConfig::BOOTSTRAP_CONTROLLERS_CONFIG.to_string(),
17658                "127.0.0.1:9093".to_string(),
17659            ),
17660            (
17661                AdminClientConfig::BOOTSTRAP_RESOLVE_TIMEOUT_MS_CONFIG.to_string(),
17662                "10000".to_string(),
17663            ),
17664        ]);
17665        props.insert(AdminClientConfig::RETRY_BACKOFF_MS_CONFIG.to_string(), "10".to_string());
17666        let admin = KafkaAdminClient::new(AdminClientConfig::new(&props).unwrap()).expect("an async-bootstrap client");
17667        tokio::time::timeout(Duration::from_secs(10), async {
17668            while !admin.shared.metadata_manager.is_bootstrapped() {
17669                tokio::time::sleep(Duration::from_millis(10)).await;
17670            }
17671        })
17672        .await
17673        .expect("the NetworkClient bootstraps from the controllers list");
17674        assert_eq!(fetched_addresses(&admin), vec![("127.0.0.1".to_string(), 9093)]);
17675        admin.close_with_timeout(Duration::ZERO).await;
17676    }
17677
17678    /// The bootstrap cluster `new_inner` seeds the manager with, for
17679    /// `bootstrap.servers=localhost:9092` (node id -1).
17680    fn bootstrap_cluster() -> Cluster {
17681        Cluster::bootstrap(&[("localhost".to_string(), "127.0.0.1:9092".parse().unwrap())])
17682    }
17683
17684    /// The node ids the manager hands the `NetworkClient` (`fetchNodes`), sorted.
17685    fn fetched_node_ids(manager: &AdminMetadataManager) -> Vec<i32> {
17686        let mut ids: Vec<i32> = manager.updater().fetch_nodes().iter().map(Node::id).collect();
17687        ids.sort_unstable();
17688        ids
17689    }
17690
17691    /// A broker that answers the `ApiVersions` handshake after `request.timeout.ms`
17692    /// still serves the admin client, as in Java.
17693    ///
17694    /// Java builds the admin `NetworkClient` with a one-hour default request
17695    /// timeout (`KafkaAdminClient#createInternal`), which is the timeout of the
17696    /// handshake. With `request.timeout.ms=5000`, a `listTopics` against a broker
17697    /// that answers the handshake after 8 s succeeds: the bootstrap metadata call
17698    /// times out at 5 s and is retried on the same, still-handshaking connection.
17699    /// With `request.timeout.ms` as the default, the handshake timed out at 5 s,
17700    /// the node was disconnected, and every reconnect hit the same slow answer, so
17701    /// the call failed with "Timed out waiting for a node assignment.".
17702    ///
17703    /// Timeline (mock time, relative to the start):
17704    ///
17705    /// - 0 s: `listTopics` is issued; the bootstrap metadata call connects to
17706    ///   node -1, which sends `ApiVersions`.
17707    /// - 5 s: the metadata call times out and is replaced by a fresh one, but the
17708    ///   handshake survives: `ApiVersions` is still in flight on the same
17709    ///   connection, and the node is not marked as failed.
17710    /// - 8 s: node -1 answers `ApiVersions`; the retried metadata call goes out on
17711    ///   it and discovers broker 0.
17712    /// - then broker 0: `listTopics` connects to it, completes its handshake, sends
17713    ///   its `Metadata` request, and succeeds.
17714    ///
17715    /// Stepped with `run_once` over a `NetworkClient` built by
17716    /// `create_network_client` on a `MockSelector` and mock time. Each stage steps
17717    /// until the condition it is waiting for holds (bounded), so the test does
17718    /// not depend on how many loop passes a stage takes.
17719    #[tokio::test]
17720    async fn a_slow_api_versions_answer_does_not_disconnect_the_admin_client() {
17721        use crate::api_message_type::ListenerType;
17722        use crate::common::network::{MockSelector, NetworkReceive};
17723        use crate::common::requests::{ApiVersionsResponse, RequestTestUtils, ResponseHeader};
17724
17725        type Runnable = AdminClientRunnable<NetworkClient<MockSelector, DefaultHostResolver>>;
17726
17727        let time = mock_time(1000);
17728        let mut props = HashMap::new();
17729        props.insert("bootstrap.servers".to_string(), "localhost:9092".to_string());
17730        props.insert("request.timeout.ms".to_string(), "5000".to_string());
17731        props.insert("default.api.timeout.ms".to_string(), "20000".to_string());
17732        let config = AdminClientConfig::new(&props).unwrap();
17733
17734        let manager = AdminMetadataManager::new(
17735            config.retry_backoff_ms(),
17736            config.metadata_max_age_ms(),
17737            false,
17738            LogContext::empty(),
17739        );
17740        manager.update(bootstrap_cluster(), time.milliseconds());
17741        let api_versions_store = Arc::new(ApiVersions::new());
17742        let mut client = KafkaAdminClient::create_network_client(
17743            &config,
17744            MockSelector::new(),
17745            manager.updater(),
17746            "admin",
17747            Arc::clone(&api_versions_store),
17748            DefaultHostResolver::new(),
17749            LogContext::empty(),
17750        );
17751        client.set_time(Arc::clone(&time) as Arc<dyn Time>);
17752        let (admin, mut runnable) = KafkaAdminClient::build(
17753            client,
17754            manager.clone(),
17755            &config,
17756            "admin".to_string(),
17757            Arc::clone(&time) as Arc<dyn Time>,
17758            LogContext::empty(),
17759        )
17760        .unwrap();
17761
17762        // Delivers a response on `node`'s connection, as the broker would.
17763        fn respond(
17764            runnable: &mut Runnable,
17765            node: &str,
17766            correlation_id: i32,
17767            api_key: ApiKeys,
17768            response: ConcreteResponse,
17769        ) {
17770            let version = api_key.latest_version();
17771            let header = ResponseHeader::with_correlation_id(correlation_id, api_key.response_header_version(version));
17772            let mut response = response;
17773            let bytes = response.serialize_with_header(&header, version).unwrap().into_buffer();
17774            runnable
17775                .client_mut()
17776                .selector_mut()
17777                .complete_receive(NetworkReceive::with_source_buffer(node, bytes));
17778        }
17779        // Runs `processRequests` iterations until `condition` holds, failing with
17780        // `what` after a bound. The mock selector keeps completed sends until
17781        // cleared, where a real selector reports each send once.
17782        async fn step_until(runnable: &mut Runnable, what: &str, mut condition: impl FnMut(&mut Runnable) -> bool) {
17783            const MAX_ITERATIONS: usize = 50;
17784            for _ in 0..MAX_ITERATIONS {
17785                if condition(runnable) {
17786                    return;
17787                }
17788                runnable.run_once().await;
17789                runnable.client_mut().selector_mut().clear_completed_sends();
17790            }
17791            assert!(
17792                condition(runnable),
17793                "condition not met after {MAX_ITERATIONS} run_once iterations: {what}"
17794            );
17795        }
17796        fn api_versions() -> ConcreteResponse {
17797            ConcreteResponse::ApiVersions(ApiVersionsResponse::default_api_versions_response(ListenerType::Broker))
17798        }
17799        let in_flight =
17800            |runnable: &mut Runnable, node: &str| runnable.client_mut().in_flight_request_count_for_node(node);
17801        // The node's handshake has completed and one request — necessarily not
17802        // `ApiVersions` — is in flight on it.
17803        let handshaken_with_one_in_flight = |runnable: &mut Runnable, node: &str| {
17804            api_versions_store.get(node).is_some() && in_flight(runnable, node) == 1
17805        };
17806
17807        let result = admin.list_topics_with_options(ListTopicsOptions::new());
17808
17809        // 0 s: the bootstrap metadata call connects to node -1 and sends ApiVersions.
17810        step_until(&mut runnable, "ApiVersions in flight on node -1", |r| in_flight(r, "-1") == 1).await;
17811        let first_deadline = time.milliseconds() + 5_000;
17812        assert_eq!(
17813            runnable.metadata_call_deadlines_for_test(),
17814            vec![first_deadline],
17815            "one metadata call, bound by request.timeout.ms"
17816        );
17817
17818        // 5 s: past request.timeout.ms the metadata call times out and is replaced,
17819        // but the handshake is still awaited on the same connection.
17820        time.sleep(5_001);
17821        let retried_deadline = time.milliseconds() + 5_000;
17822        step_until(&mut runnable, "the timed-out metadata call was replaced", |r| {
17823            r.metadata_call_deadlines_for_test() == vec![retried_deadline]
17824        })
17825        .await;
17826        assert_eq!(in_flight(&mut runnable, "-1"), 1, "the handshake outlives request.timeout.ms");
17827        assert!(
17828            !runnable
17829                .client_mut()
17830                .connection_failed(&Node::new(-1, "localhost".to_string(), 9092))
17831        );
17832
17833        // 8 s: the broker answers the handshake; the retried metadata call then
17834        // goes out on node -1 and discovers broker 0.
17835        time.sleep(2_999);
17836        respond(&mut runnable, "-1", 0, ApiKeys::API_VERSIONS, api_versions());
17837        step_until(&mut runnable, "the retried metadata call in flight on node -1", |r| {
17838            handshaken_with_one_in_flight(r, "-1")
17839        })
17840        .await;
17841        let broker = Node::new(0, "localhost".to_string(), 9092);
17842        respond(
17843            &mut runnable,
17844            "-1",
17845            1,
17846            ApiKeys::METADATA,
17847            ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
17848                std::slice::from_ref(&broker),
17849                Some("mock-cluster"),
17850                0,
17851                Vec::new(),
17852            )),
17853        );
17854        step_until(&mut runnable, "broker 0 discovered and ApiVersions in flight on it", |r| {
17855            fetched_node_ids(&manager) == vec![0] && in_flight(r, "0") == 1
17856        })
17857        .await;
17858        assert_eq!(fetched_node_ids(&manager), vec![0], "the bootstrap metadata call completed");
17859
17860        // Then broker 0: listTopics completes the handshake, then sends its
17861        // Metadata request.
17862        respond(&mut runnable, "0", 2, ApiKeys::API_VERSIONS, api_versions());
17863        step_until(&mut runnable, "listTopics' Metadata request in flight on broker 0", |r| {
17864            handshaken_with_one_in_flight(r, "0")
17865        })
17866        .await;
17867        respond(
17868            &mut runnable,
17869            "0",
17870            3,
17871            ApiKeys::METADATA,
17872            ConcreteResponse::Metadata(RequestTestUtils::metadata_response(
17873                std::slice::from_ref(&broker),
17874                Some("mock-cluster"),
17875                0,
17876                Vec::new(),
17877            )),
17878        );
17879        let names = result.names();
17880        step_until(&mut runnable, "listTopics completed", |_| names.is_done()).await;
17881        let names = names.get().await.expect("listTopics succeeds");
17882        assert!(names.is_empty());
17883    }
17884
17885    // --- shutdown ------------------------------------------------------------
17886
17887    /// `KafkaAdminClient.AdminClientRunnable#enqueue` accepts a call only while
17888    /// the runnable is not `closing` and otherwise fails it with
17889    /// `TimeoutException("The AdminClient thread has exited.")`. A follow-up a
17890    /// response hook issues goes through it too (`runnable.call(call, now)`), so
17891    /// once the `finally` has set `closing` it fails instead of being queued
17892    /// where no loop iteration will ever drain it.
17893    #[test]
17894    fn a_follow_up_call_after_the_runnable_exited_fails_like_enqueue() {
17895        let (admin, mut runnable, time, _nodes) = env();
17896        let now = time.milliseconds();
17897        let failed = |captured: &Arc<Mutex<Option<Error>>>| {
17898            let captured = Arc::clone(captured);
17899            Call::new(
17900                "createTopics",
17901                now + 60_000,
17902                NodeProvider::LeastLoaded,
17903                Box::new(|_timeout_ms| unreachable!("the call is never sent")),
17904                Box::new(|_response, _now, _cur_node| HandleResult::Done),
17905                Box::new(move |error| *captured.lock().unwrap() = Some(error.clone())),
17906                Box::new(|_| false),
17907            )
17908        };
17909
17910        // While the loop runs, the follow-up is queued.
17911        let captured = Arc::new(Mutex::new(None));
17912        runnable.call(failed(&captured), now);
17913        assert!(captured.lock().unwrap().is_none(), "a live runnable queues the call");
17914        assert!(runnable.has_active_external_calls_for_test());
17915
17916        // After the `finally` has set `closing`, it fails with Java's error.
17917        admin.shared.shutdown.closing.store(true, Ordering::Release);
17918        let captured = Arc::new(Mutex::new(None));
17919        runnable.call(failed(&captured), now);
17920        let error = captured.lock().unwrap().take().expect("the call failed");
17921        assert!(matches!(error, Error::Timeout(_)), "got {error:?}");
17922        assert_eq!(error.message(), "The AdminClient thread has exited.");
17923        assert!(error.is_retriable_error(), "Java's TimeoutException is a RetriableException");
17924    }
17925
17926    /// Java's `threadShouldExit` consults
17927    /// `KafkaAdminClient.AdminClientRunnable#hasActiveExternalCalls(Collection)`,
17928    /// which skips every `Call` with `internal == true`. The metadata refresh
17929    /// (`makeMetadataCall`) is internal and is recreated on every backoff
17930    /// expiry, so counting it would keep the I/O task alive for as long as the
17931    /// bootstrap brokers stay unreachable: `close(timeout)` would block for the
17932    /// whole timeout, and Java's no-argument `Admin.close()` — which passes
17933    /// `Duration.ofMillis(Long.MAX_VALUE)` — would never return at all.
17934    #[tokio::test]
17935    async fn close_exits_the_io_task_while_only_the_internal_metadata_call_is_active() {
17936        let (admin, mut runnable, time, _nodes) = env();
17937        // Force the refresh the production client performs on its own once the
17938        // seeded metadata expires (or fails), then let phase 4 create the
17939        // internal call. The mock has no prepared response, so the call stays
17940        // active indefinitely — exactly the unreachable-broker situation.
17941        admin.shared.metadata_manager.request_update();
17942        time.sleep(1_000);
17943        pump(&mut runnable, 2).await;
17944        assert!(
17945            runnable.has_active_calls_for_test(),
17946            "the internal metadata refresh call should be active"
17947        );
17948        assert!(
17949            !runnable.has_active_external_calls_for_test(),
17950            "the metadata refresh call is internal, so it is not an active external call"
17951        );
17952
17953        // Java's no-argument `Admin.close()`: no reachable hard deadline.
17954        admin
17955            .shared
17956            .shutdown
17957            .hard_shutdown_deadline_ms
17958            .store(i64::MAX, Ordering::Release);
17959
17960        assert!(
17961            runnable.should_exit_for_test(time.milliseconds()),
17962            "close() must not wait on an internal call: the I/O task has to exit at once"
17963        );
17964    }
17965
17966    /// A retriable failure during the `close(timeout)` grace period is retried.
17967    ///
17968    /// Java's `KafkaAdminClient#close(Duration)` only publishes
17969    /// `hardShutdownTimeMs`; `KafkaAdminClient.Call#fail` refuses to retry only
17970    /// once `runnable.closing` is set, and that happens in the I/O thread's
17971    /// `finally` (`KafkaAdminClient.AdminClientRunnable#run`), after
17972    /// `processRequests` has returned. So a `createTopics` whose first attempt is
17973    /// disconnected after `close(30s)` is retried and succeeds, and the loop then
17974    /// exits because no external call is left
17975    /// (`KafkaAdminClient.AdminClientRunnable#threadShouldExit`).
17976    #[tokio::test]
17977    async fn a_retriable_error_during_close_is_retried_within_the_grace_period() {
17978        let (admin, mut runnable, time, _nodes) = env();
17979        let result = admin.create_topics_with_options(
17980            &[NewTopic::with_num_partitions_replication_factor(
17981                "myTopic",
17982                Some(1),
17983                Some(1),
17984            )],
17985            CreateTopicsOptions::new(),
17986        );
17987        // The first attempt is in flight when `close(30s)` is called.
17988        pump_until_request_queued(&mut runnable).await;
17989        assert!(runnable.has_active_external_calls_for_test());
17990
17991        // `close(30s)`. No task was spawned, so this only publishes the deadline;
17992        // the loop is stepped below exactly as `process_requests` steps it.
17993        admin.close_with_timeout(Duration::from_secs(30)).await;
17994
17995        // The in-flight attempt is disconnected; the retry succeeds.
17996        runnable.client_mut().respond_disconnected(create_response(vec![]), true);
17997        runnable
17998            .client_mut()
17999            .prepare_response(create_response(vec![create_result("myTopic", Errors::None, None)]));
18000
18001        let mut exited = false;
18002        for _ in 0..40 {
18003            if runnable.should_exit_for_test(time.milliseconds()) {
18004                exited = true;
18005                break;
18006            }
18007            runnable.run_once().await;
18008            time.sleep(100);
18009        }
18010        assert!(exited, "the loop exits once the retried call completes");
18011        assert!(
18012            time.milliseconds() < 1_000 + 30_000,
18013            "the loop exited before the hard-shutdown deadline"
18014        );
18015        let future = result.values()["myTopic"].clone();
18016        assert!(future.is_done(), "the call completed before the loop exited");
18017        future.get().await.expect("the disconnected attempt is retried during close");
18018        assert_eq!(result.topic_id("myTopic").get().await.unwrap(), Uuid::new(0, 7));
18019    }
18020
18021    /// The other half of the contract: an **external** call does hold the loop
18022    /// open until the hard-shutdown deadline, so `close(timeout)` still gives a
18023    /// user-submitted RPC its chance to finish.
18024    #[tokio::test]
18025    async fn close_waits_for_an_active_external_call_until_the_hard_deadline() {
18026        let (admin, mut runnable, time, _nodes) = env();
18027        let _result = admin.list_topics_with_options(ListTopicsOptions::new());
18028        pump(&mut runnable, 1).await;
18029        assert!(
18030            runnable.has_active_external_calls_for_test(),
18031            "the submitted listTopics call should be an active external call"
18032        );
18033
18034        let now = time.milliseconds();
18035        admin
18036            .shared
18037            .shutdown
18038            .hard_shutdown_deadline_ms
18039            .store(now + 30_000, Ordering::Release);
18040        assert!(
18041            !runnable.should_exit_for_test(now),
18042            "an active external call keeps the I/O task alive until the hard deadline"
18043        );
18044
18045        // Once the hard deadline passes, the task exits and aborts the call.
18046        assert!(runnable.should_exit_for_test(now + 30_000));
18047    }
18048
18049    /// A [`KafkaClient`] wrapper whose `poll` records the timeout it was handed
18050    /// and, once armed, advances the mock clock by that timeout — i.e. it
18051    /// behaves like a real `poll` that finds nothing on the socket and waits the
18052    /// whole budget it was given. That makes the wait the I/O loop *would* have
18053    /// performed observable on the mock clock (`MockClient::poll` ignores its
18054    /// timeout, so no assertion on real elapsed time is possible).
18055    ///
18056    /// Recording the argument mirrors Mockito's
18057    /// `verify(client).poll(captor.capture(), anyLong())`; the consumer tests
18058    /// use the same wrapper shape (`CountingClient` in
18059    /// `consumer/internals/consumer_network_thread.rs`).
18060    struct WaitingClient {
18061        inner: MockClient,
18062        time: Arc<MockTime>,
18063        poll_timeouts: Arc<Mutex<Vec<i64>>>,
18064        advance_clock: Arc<std::sync::atomic::AtomicBool>,
18065        stuck: Arc<std::sync::atomic::AtomicBool>,
18066        park_once: Arc<std::sync::atomic::AtomicBool>,
18067        parked: Arc<Notify>,
18068    }
18069
18070    impl WaitingClient {
18071        fn new(inner: MockClient, time: Arc<MockTime>) -> Self {
18072            Self {
18073                inner,
18074                time,
18075                poll_timeouts: Arc::new(Mutex::new(Vec::new())),
18076                advance_clock: Arc::new(std::sync::atomic::AtomicBool::new(false)),
18077                stuck: Arc::new(std::sync::atomic::AtomicBool::new(false)),
18078                park_once: Arc::new(std::sync::atomic::AtomicBool::new(false)),
18079                parked: Arc::new(Notify::new()),
18080            }
18081        }
18082
18083        /// Once armed, the next `poll` parks until the client's
18084        /// [`wakeup_notify`](KafkaClient::wakeup_notify) handle fires, then
18085        /// behaves normally. That handle is the same `Notify` production
18086        /// `submit()` and `close()` poke (it is what `KafkaAdminClient::build`
18087        /// stores as `Shared::wakeup`), so the park ends exactly when a real
18088        /// selector poll would be woken (DoD #12). Only the first poll after
18089        /// arming parks, so the loop can finish its work afterwards.
18090        fn park_once(&self) -> Arc<std::sync::atomic::AtomicBool> {
18091            Arc::clone(&self.park_once)
18092        }
18093
18094        /// Signalled (with a stored permit) when `poll` has entered the park
18095        /// armed by [`park_once`](Self::park_once).
18096        fn parked(&self) -> Arc<Notify> {
18097            Arc::clone(&self.parked)
18098        }
18099
18100        fn poll_timeouts(&self) -> Arc<Mutex<Vec<i64>>> {
18101            Arc::clone(&self.poll_timeouts)
18102        }
18103
18104        fn advance_clock(&self) -> Arc<std::sync::atomic::AtomicBool> {
18105            Arc::clone(&self.advance_clock)
18106        }
18107
18108        /// Once armed, `poll` never returns, so the I/O loop can never reach
18109        /// `should_exit` again. It stands in for any `await` inside a
18110        /// `process_pending_calls` phase that no shutdown deadline can interrupt — in
18111        /// production the unbounded `socket.connect(...).await` that
18112        /// `send_eligible_calls` reaches through `client.ready(...)`.
18113        fn stuck(&self) -> Arc<std::sync::atomic::AtomicBool> {
18114            Arc::clone(&self.stuck)
18115        }
18116    }
18117
18118    impl KafkaClient for WaitingClient {
18119        fn is_ready(&self, node: &Node, now: i64) -> bool {
18120            self.inner.is_ready(node, now)
18121        }
18122        async fn ready(&mut self, node: &Node, now: i64) -> bool {
18123            self.inner.ready(node, now).await
18124        }
18125        fn connection_delay(&self, node: &Node, now: i64) -> i64 {
18126            self.inner.connection_delay(node, now)
18127        }
18128        fn poll_delay_ms(&self, node: &Node, now: i64) -> i64 {
18129            self.inner.poll_delay_ms(node, now)
18130        }
18131        fn connection_failed(&self, node: &Node) -> bool {
18132            self.inner.connection_failed(node)
18133        }
18134        fn authentication_error(&self, node: &Node) -> Option<Error> {
18135            self.inner.authentication_error(node)
18136        }
18137        fn send(&mut self, request: crate::ClientRequest, now: i64) {
18138            self.inner.send(request, now)
18139        }
18140        async fn poll(&mut self, timeout: i64, now: i64) -> Vec<crate::ClientResponse> {
18141            self.poll_timeouts.lock().unwrap().push(timeout);
18142            if self.stuck.load(Ordering::Acquire) {
18143                std::future::pending::<()>().await;
18144            }
18145            if self.park_once.swap(false, Ordering::AcqRel) {
18146                let wakeup = self.inner.wakeup_notify();
18147                // Created before `parked` is signalled, so a wakeup issued the
18148                // moment the test resumes is not lost: `notify_one` either wakes
18149                // this waiter or leaves a permit it consumes on first poll.
18150                let woken = wakeup.notified();
18151                self.parked.notify_one();
18152                woken.await;
18153            }
18154            let now = if self.advance_clock.load(Ordering::Acquire) {
18155                self.time.sleep(timeout);
18156                self.time.milliseconds()
18157            } else {
18158                now
18159            };
18160            self.inner.poll(timeout, now).await
18161        }
18162        async fn disconnect(&mut self, node_id: &str) {
18163            self.inner.disconnect(node_id).await
18164        }
18165        async fn close_connection(&mut self, node_id: &str) {
18166            self.inner.close_connection(node_id).await
18167        }
18168        fn least_loaded_node(&self, now: i64) -> crate::LeastLoadedNode {
18169            self.inner.least_loaded_node(now)
18170        }
18171        fn in_flight_request_count(&self) -> i32 {
18172            self.inner.in_flight_request_count()
18173        }
18174        fn has_in_flight_requests(&self) -> bool {
18175            self.inner.has_in_flight_requests()
18176        }
18177        fn in_flight_request_count_for_node(&self, node_id: &str) -> usize {
18178            self.inner.in_flight_request_count_for_node(node_id)
18179        }
18180        fn has_in_flight_requests_for_node(&self, node_id: &str) -> bool {
18181            self.inner.has_in_flight_requests_for_node(node_id)
18182        }
18183        fn has_ready_nodes(&self, now: i64) -> bool {
18184            self.inner.has_ready_nodes(now)
18185        }
18186        fn wakeup(&self) {
18187            self.inner.wakeup()
18188        }
18189        fn wakeup_handle(&self) -> Arc<Notify> {
18190            self.inner.wakeup_handle()
18191        }
18192        fn wakeup_notify(&self) -> Arc<Notify> {
18193            self.inner.wakeup_notify()
18194        }
18195        fn new_client_request(
18196            &mut self,
18197            node_id: &str,
18198            request_builder: Box<dyn RequestBuilder>,
18199            created_time_ms: i64,
18200            expect_response: bool,
18201        ) -> crate::ClientRequest {
18202            self.inner
18203                .new_client_request(node_id, request_builder, created_time_ms, expect_response)
18204        }
18205        fn new_client_request_with_timeout(
18206            &mut self,
18207            node_id: &str,
18208            request_builder: Box<dyn RequestBuilder>,
18209            created_time_ms: i64,
18210            expect_response: bool,
18211            request_timeout_ms: i32,
18212            callback: Option<crate::RequestCompletionHandler>,
18213        ) -> crate::ClientRequest {
18214            self.inner.new_client_request_with_timeout(
18215                node_id,
18216                request_builder,
18217                created_time_ms,
18218                expect_response,
18219                request_timeout_ms,
18220                callback,
18221            )
18222        }
18223        fn initiate_close(&self) {
18224            self.inner.initiate_close()
18225        }
18226        fn active(&self) -> bool {
18227            self.inner.active()
18228        }
18229        async fn close(&mut self) {
18230            self.inner.close().await
18231        }
18232    }
18233
18234    /// Java bounds every `client.poll(...)` by the time left until the
18235    /// hard-shutdown deadline once `close()` has been called
18236    /// (`KafkaAdminClient.AdminClientRunnable#processRequests`):
18237    ///
18238    /// ```java
18239    /// long pollTimeout = Math.min(1200000, timeoutProcessor.nextTimeoutMs());
18240    /// if (curHardShutdownTimeMs != INVALID_SHUTDOWN_TIME) {
18241    ///     pollTimeout = Math.min(pollTimeout, curHardShutdownTimeMs - now);
18242    /// }
18243    /// ```
18244    ///
18245    /// Without that clamp an in-flight **external** call keeps `should_exit`
18246    /// false (which is correct — see the test above), while the poll itself
18247    /// waits on the far larger call deadline
18248    /// (`default.api.timeout.ms`) or, in production, on `NetworkClient`'s own
18249    /// `request.timeout.ms` cap. `close(100ms)` would then block for tens of
18250    /// seconds, and because the FFI `close` is a `block_on`, C and Python
18251    /// callers would see the same overrun.
18252    #[tokio::test]
18253    async fn close_bounds_the_poll_timeout_by_the_hard_shutdown_deadline() {
18254        let time = mock_time(1000);
18255        let (cluster, nodes) = mock_cluster(3, 0);
18256        let client = WaitingClient::new(
18257            MockClient::with_static_nodes(nodes.clone(), Arc::clone(&time) as Arc<dyn Time>),
18258            Arc::clone(&time),
18259        );
18260        let poll_timeouts = client.poll_timeouts();
18261        let advance_clock = client.advance_clock();
18262        let config = test_config();
18263        let (admin, mut runnable) =
18264            KafkaAdminClient::create_for_test(client, cluster, &config, Arc::clone(&time) as Arc<dyn Time>);
18265
18266        // Put an external RPC in flight. The mock has no prepared response, so
18267        // the call sits in `correlation_id_to_calls`: `pending_calls` is empty,
18268        // hence no `retry_backoff_ms` floor, and the only contributors left to
18269        // the poll timeout are the call deadline (`default.api.timeout.ms`) and
18270        // `metadata.max.age.ms`.
18271        let _result = admin.list_topics_with_options(ListTopicsOptions::new());
18272        for _ in 0..40 {
18273            if runnable.client_mut().inner.request_count() >= 1 {
18274                break;
18275            }
18276            runnable.run_once().await;
18277        }
18278        assert!(
18279            runnable.client_mut().inner.request_count() >= 1,
18280            "the listTopics request should have been sent"
18281        );
18282        assert!(
18283            runnable.has_active_external_calls_for_test(),
18284            "the in-flight listTopics call should be an active external call"
18285        );
18286
18287        // `close(Duration::from_millis(100))`.
18288        let now = time.milliseconds();
18289        let hard_deadline = now + 100;
18290        admin
18291            .shared
18292            .shutdown
18293            .hard_shutdown_deadline_ms
18294            .store(hard_deadline, Ordering::Release);
18295
18296        // From here on the client waits out every timeout it is given, like a
18297        // real one polling an idle socket.
18298        poll_timeouts.lock().unwrap().clear();
18299        advance_clock.store(true, Ordering::Release);
18300
18301        runnable.run().await;
18302
18303        let timeouts = poll_timeouts.lock().unwrap().clone();
18304        assert!(
18305            !timeouts.is_empty(),
18306            "the run loop should have polled at least once after close()"
18307        );
18308        for timeout in &timeouts {
18309            assert!(
18310                *timeout <= 100,
18311                "every poll after close() must be clamped to the remaining shutdown budget \
18312                 (100 ms), got {timeouts:?}"
18313            );
18314        }
18315        let waited = time.milliseconds() - now;
18316        assert!(
18317            waited <= 100,
18318            "close(100ms) must not overrun its deadline: the I/O task waited {waited}ms"
18319        );
18320    }
18321
18322    /// The deadline clamped in the test above is only a *hint* to the I/O loop.
18323    /// The caller's guarantee is Java's **timed** join at the end of
18324    /// `KafkaAdminClient.close(Duration)`:
18325    ///
18326    /// ```java
18327    /// if (Thread.currentThread() != thread) {
18328    ///     thread.join(waitTimeMs);   // returns after waitTimeMs regardless
18329    /// }
18330    /// ```
18331    ///
18332    /// It matters more in Rust than in Java: Java's `sendEligibleCalls` calls the
18333    /// non-blocking NIO `client.ready(...)` and cannot block, whereas ours awaits
18334    /// `NetworkClient::ready` → `initiate_connect` → `Selector::connect`, which
18335    /// awaits the TCP handshake with no timeout of its own. An unbounded
18336    /// `handle.await` would then hand a `close(50ms)` caller — including the C
18337    /// and Python layers, which `block_on` it — a wait bounded only by the OS
18338    /// connect timeout.
18339    #[tokio::test]
18340    async fn close_returns_within_its_timeout_even_when_the_io_task_cannot_exit() {
18341        let time = mock_time(1000);
18342        let (cluster, nodes) = mock_cluster(3, 0);
18343        let client = WaitingClient::new(
18344            MockClient::with_static_nodes(nodes.clone(), Arc::clone(&time) as Arc<dyn Time>),
18345            Arc::clone(&time),
18346        );
18347        let stuck = client.stuck();
18348        let config = test_config();
18349        let (admin, runnable) =
18350            KafkaAdminClient::create_for_test(client, cluster, &config, Arc::clone(&time) as Arc<dyn Time>);
18351
18352        // From its first poll on, the I/O task is parked forever: it can neither
18353        // finish work nor re-evaluate `should_exit`, so nothing but the timed
18354        // join can end the wait.
18355        stuck.store(true, Ordering::Release);
18356        admin.spawn(runnable);
18357        // An active external call, so `should_exit` could not short-circuit on
18358        // "all work has been completed" even if the task did run again.
18359        let _result = admin.list_topics_with_options(ListTopicsOptions::new());
18360
18361        let started = std::time::Instant::now();
18362        let returned =
18363            tokio::time::timeout(Duration::from_secs(5), admin.close_with_timeout(Duration::from_millis(50))).await;
18364        assert!(
18365            returned.is_ok(),
18366            "close(50ms) must return even though the I/O task can never exit; it was still \
18367             blocked after 5s"
18368        );
18369        let elapsed = started.elapsed();
18370        assert!(
18371            elapsed < Duration::from_secs(1),
18372            "close(50ms) must be bounded by its timeout, but it returned only after {elapsed:?}"
18373        );
18374    }
18375
18376    /// A call submitted just before `close()` must still run. Java's
18377    /// `KafkaAdminClient.AdminClientRunnable#processRequests` drains `newCalls`
18378    /// and checks `threadShouldExit` back to back at the top of every iteration:
18379    ///
18380    /// ```java
18381    /// // Copy newCalls into pendingCalls.
18382    /// drainNewCalls();
18383    ///
18384    /// // Check if the AdminClient thread should shut down.
18385    /// long curHardShutdownTimeMs = hardShutdownTimeMs.get();
18386    /// if ((curHardShutdownTimeMs != INVALID_SHUTDOWN_TIME) && threadShouldExit(now, curHardShutdownTimeMs))
18387    ///     break;
18388    /// ```
18389    ///
18390    /// so a call that arrived while the thread was parked in `client.poll` is in
18391    /// `pendingCalls` — an active external call — when the exit decision is
18392    /// made, and `close(timeout)` waits for it. When the exit check instead ran
18393    /// after the whole iteration (network poll included), the call was still in
18394    /// the submission channel, invisible to `has_active_external_calls`, and
18395    /// `fail_all_remaining` failed it with "The AdminClient thread has exited."
18396    ///
18397    /// The loop is the real spawned `run()`, parked in its network poll on
18398    /// `client.wakeup_notify()` — the `Notify` production `submit()` and
18399    /// `close()` poke — so it wakes exactly as a production selector would.
18400    #[tokio::test]
18401    async fn a_call_submitted_just_before_close_is_completed() {
18402        let time = mock_time(1000);
18403        let (cluster, nodes) = mock_cluster(3, 0);
18404        let client = WaitingClient::new(
18405            MockClient::with_static_nodes(nodes.clone(), Arc::clone(&time) as Arc<dyn Time>),
18406            Arc::clone(&time),
18407        );
18408        let park_once = client.park_once();
18409        let parked = client.parked();
18410        let config = test_config();
18411        let (admin, mut runnable) =
18412            KafkaAdminClient::create_for_test(client, cluster, &config, Arc::clone(&time) as Arc<dyn Time>);
18413        runnable.client_mut().inner.prepare_response(create_response(vec![create_result(
18414            "myTopic",
18415            Errors::None,
18416            None,
18417        )]));
18418
18419        // Park the I/O task in its first network poll, before anything is
18420        // submitted.
18421        park_once.store(true, Ordering::Release);
18422        admin.spawn(runnable);
18423        tokio::time::timeout(Duration::from_secs(5), parked.notified())
18424            .await
18425            .expect("the I/O task should park in its network poll");
18426
18427        // Submitted while the task is parked: the call sits in the submission
18428        // channel until the task next drains it.
18429        let result = admin.create_topics_with_options(
18430            &[NewTopic::with_num_partitions_replication_factor(
18431                "myTopic",
18432                Some(1),
18433                Some(1),
18434            )],
18435            CreateTopicsOptions::new(),
18436        );
18437        tokio::time::timeout(Duration::from_secs(10), admin.close_with_timeout(Duration::from_secs(30)))
18438            .await
18439            .expect("close(30s) should return once the create has completed");
18440
18441        let value = result.values()["myTopic"].get().await;
18442        assert!(
18443            value.is_ok(),
18444            "a createTopics submitted before close() must complete, as in Java; got {value:?}"
18445        );
18446        result
18447            .all()
18448            .get()
18449            .await
18450            .expect("all() of a completed createTopics must succeed");
18451    }
18452
18453    /// Steps `runnable` until exactly one `InitProducerId` request is in flight
18454    /// and returns the number queued, so a `fenceProducers` test can act while
18455    /// the driver holds the next key's fulfillment back.
18456    async fn pump_until_one_init_producer_id_in_flight(runnable: &mut AdminClientRunnable<MockClient>) -> usize {
18457        let count = |runnable: &mut AdminClientRunnable<MockClient>| {
18458            runnable
18459                .client_mut()
18460                .requests()
18461                .iter()
18462                .filter(|r| *r.api_key() == crate::common::protocol::ApiKeys::INIT_PRODUCER_ID)
18463                .count()
18464        };
18465        for _ in 0..40 {
18466            if count(runnable) >= 1 {
18467                break;
18468            }
18469            runnable.run_once().await;
18470        }
18471        // A few more iterations: the driver must NOT issue the second key's
18472        // request while the first is outstanding
18473        // (`org.apache.kafka.clients.admin.internals.AdminApiDriver#collectRequests`).
18474        for _ in 0..5 {
18475            runnable.run_once().await;
18476        }
18477        count(runnable)
18478    }
18479
18480    /// Every key of a driver RPC resolves on `close()`, even
18481    /// one whose fulfillment request had not been issued yet.
18482    ///
18483    /// The driver issues at most one fulfillment request per broker at a time
18484    /// (`AdminApiDriver#collectRequests`), so with one broker `b`'s
18485    /// `InitProducerId` is only created once `a`'s completes or fails. `close(0)`
18486    /// makes the I/O task exit with `a`'s call in flight; the `finally` fails it,
18487    /// and its failure hook asks the driver for the next request. Java routes
18488    /// that through `runnable.call(..)` in `KafkaAdminClient#maybeSendRequests`;
18489    /// `KafkaAdminClient.AdminClientRunnable#call` rejects it once the shutdown
18490    /// deadline is set, so `b` fails with "Cannot accept new calls when
18491    /// AdminClient is closing." Rust used to send it straight into the submission
18492    /// channel after the final drain; the runnable was then dropped with it
18493    /// inside and `b` never resolved.
18494    #[tokio::test]
18495    async fn close_resolves_a_driver_key_whose_fulfillment_was_not_yet_issued() {
18496        let (admin, mut runnable, _time, nodes) = env_nodes_with_props(1, &[]);
18497        let coordinator = &nodes[0];
18498        // One batched lookup maps both transactional ids to the only broker.
18499        runnable
18500            .client_mut()
18501            .prepare_response(find_coordinator_resp(&[("a", coordinator), ("b", coordinator)]));
18502
18503        let result =
18504            admin.fence_producers_with_options(&["a".to_string(), "b".to_string()], FenceProducersOptions::new());
18505        assert_eq!(
18506            pump_until_one_init_producer_id_in_flight(&mut runnable).await,
18507            1,
18508            "exactly one key's InitProducerId must be in flight; the other's is held back"
18509        );
18510
18511        // `close(Duration.ZERO)`: no task was spawned, so this only publishes the
18512        // closing gate and a hard deadline of `now`. The loop then exits at once
18513        // with the in-flight call still outstanding.
18514        admin.close_with_timeout(Duration::ZERO).await;
18515        tokio::time::timeout(Duration::from_secs(10), runnable.run())
18516            .await
18517            .expect("run() must exit once the hard deadline has passed");
18518        // Dropping the runnable drops anything still queued in its channel, as
18519        // the end of the I/O task does in production.
18520        drop(runnable);
18521
18522        let a = result.producer_id("a").expect("a is a requested key");
18523        let b = result.producer_id("b").expect("b is a requested key");
18524        assert!(
18525            a.is_done() && b.is_done(),
18526            "every key must resolve on close(), including the one whose fulfillment was not yet \
18527             issued (a: {}, b: {})",
18528            a.is_done(),
18529            b.is_done()
18530        );
18531
18532        // Which key the driver issued first follows its map order, so identify
18533        // the two outcomes by their errors rather than by name.
18534        let mut messages = vec![
18535            a.get().await.expect_err("close(0) aborts the fence").to_string(),
18536            b.get().await.expect_err("close(0) aborts the fence").to_string(),
18537        ];
18538        messages.sort();
18539        assert_eq!(
18540            messages,
18541            vec![
18542                "LocalIllegalStateError: Cannot accept new calls when AdminClient is closing.".to_string(),
18543                "TimeoutError: The AdminClient thread has exited. Call: fenceProducer(api=INIT_PRODUCER_ID)"
18544                    .to_string(),
18545            ],
18546            "the in-flight key times out with the exiting task; the unissued one is rejected by the \
18547             closing gate with Java's IllegalStateException text"
18548        );
18549    }
18550
18551    /// A driver RPC issued after `close()` fails with Java's
18552    /// `IllegalStateException("Cannot accept new calls when AdminClient is closing.")`
18553    /// (`KafkaAdminClient.AdminClientRunnable#call`, reached through
18554    /// `invokeDriver` → `maybeSendRequests` → `runnable.call`), exactly like a
18555    /// plain call. It used to bypass the gate: with the I/O task gone the
18556    /// channel send failed and the key got a retriable
18557    /// `TimeoutException("The AdminClient thread has exited.")` instead.
18558    #[tokio::test]
18559    async fn a_driver_rpc_issued_after_close_fails_with_the_closing_error() {
18560        let (admin, mut runnable, _time, _nodes) = env();
18561        admin.close_with_timeout(Duration::ZERO).await;
18562        tokio::time::timeout(Duration::from_secs(10), runnable.run())
18563            .await
18564            .expect("with no work the I/O task exits as soon as close() is called");
18565        drop(runnable);
18566
18567        let result = admin.fence_producers_with_options(&["a".to_string()], FenceProducersOptions::new());
18568        let future = result.producer_id("a").expect("a is a requested key");
18569        assert!(future.is_done(), "a call rejected by the closing gate resolves at once");
18570        let error = future.get().await.expect_err("a call issued after close() must fail");
18571        assert!(matches!(error, Error::LocalIllegalState(_)), "got {error:?}");
18572        assert_eq!(error.message(), "Cannot accept new calls when AdminClient is closing.");
18573        assert!(
18574            !error.is_retriable_error(),
18575            "Java's IllegalStateException is not retriable, unlike the TimeoutException it replaced: {error:?}"
18576        );
18577    }
18578
18579    /// A follow-up call issued during the I/O task's
18580    /// shutdown tail resolves instead of hanging, even when the loop ended
18581    /// without `close()` having set the closing gate.
18582    ///
18583    /// Java's `finally` in `KafkaAdminClient.AdminClientRunnable#run` starts with
18584    /// `closing = true`, so `KafkaAdminClient.AdminClientRunnable#enqueue` rejects
18585    /// anything submitted from then on with
18586    /// `TimeoutException("The AdminClient thread has exited.")`. Here the loop ends
18587    /// in a panic, so only that flag can stop the follow-up the driver issues when
18588    /// the `finally` fails the in-flight key: without it the call was queued after
18589    /// the final drain and dropped with the runnable.
18590    #[tokio::test]
18591    async fn a_follow_up_issued_in_the_shutdown_tail_after_a_panic_resolves() {
18592        let (admin, mut runnable, time, nodes) = env_nodes_with_props(1, &[]);
18593        let coordinator = &nodes[0];
18594        runnable
18595            .client_mut()
18596            .prepare_response(find_coordinator_resp(&[("a", coordinator), ("b", coordinator)]));
18597        let result =
18598            admin.fence_producers_with_options(&["a".to_string(), "b".to_string()], FenceProducersOptions::new());
18599        assert_eq!(pump_until_one_init_producer_id_in_flight(&mut runnable).await, 1);
18600
18601        // End the loop with a panic (see `a_panicking_io_task_still_runs_its_finally`):
18602        // an already-expired call whose failure hook panics once.
18603        let now = time.milliseconds();
18604        let fired = Arc::new(std::sync::atomic::AtomicBool::new(false));
18605        let hook_fired = Arc::clone(&fired);
18606        admin.submit(Call::new(
18607            "panicOnPurpose",
18608            now - 1,
18609            NodeProvider::LeastLoaded,
18610            Box::new(|_timeout_ms| unreachable!("the call expires before it is ever sent")),
18611            Box::new(|_response, _now, _cur_node| HandleResult::Done),
18612            Box::new(move |_error| {
18613                if !hook_fired.swap(true, Ordering::AcqRel) {
18614                    panic!("injected panic inside the I/O loop");
18615                }
18616            }),
18617            Box::new(|_| false),
18618        ));
18619        tokio::time::timeout(Duration::from_secs(10), runnable.run())
18620            .await
18621            .expect("run() must reach its finally after a panic");
18622        assert!(fired.load(Ordering::Acquire), "the injected panic must actually have fired");
18623        assert_eq!(
18624            admin.shared.shutdown.hard_shutdown_deadline_ms.load(Ordering::Acquire),
18625            KafkaAdminClient::NO_HARD_SHUTDOWN,
18626            "precondition: close() was never called, so the closing gate is not set"
18627        );
18628        drop(runnable);
18629
18630        let a = result.producer_id("a").expect("a is a requested key");
18631        let b = result.producer_id("b").expect("b is a requested key");
18632        assert!(a.is_done() && b.is_done(), "every key must resolve after the task exits");
18633        // The two keys reach the text by different paths, and the exact messages
18634        // tell them apart: the in-flight key is failed by `fail_all_remaining`
18635        // (with the call rendered after it), while the follow-up is rejected by
18636        // the closed channel (bare, as Java's `enqueue` builds it). A follow-up
18637        // that was queued and failed by a later drain would carry the suffix.
18638        let mut messages = Vec::new();
18639        for future in [a, b] {
18640            let error = future.get().await.expect_err("the task exited before the fence finished");
18641            assert!(error.is_timeout_error(), "got {error:?}");
18642            messages.push(error.message().to_string());
18643        }
18644        messages.sort();
18645        assert_eq!(
18646            messages,
18647            vec![
18648                "The AdminClient thread has exited.".to_string(),
18649                "The AdminClient thread has exited. Call: fenceProducer(api=INIT_PRODUCER_ID)".to_string(),
18650            ]
18651        );
18652    }
18653
18654    /// Regression for COMMENTS.66.md Issue 2: a quota-retry follow-up passes the
18655    /// same `runnable.call` gate as every other new call.
18656    ///
18657    /// Java resubmits the throttled topics with `runnable.call(call, now)` (in
18658    /// `KafkaAdminClient#getCreateTopicsCall`);
18659    /// `KafkaAdminClient.AdminClientRunnable#call` rejects the retry once
18660    /// `close()` has set the hard-shutdown deadline. The retry's `handleFailure`
18661    /// leaves a non-timeout cause alone (`maybeCompleteQuotaExceededException`),
18662    /// so the topic fails with
18663    /// `IllegalStateException("Cannot accept new calls when AdminClient is closing.")`.
18664    /// Rust used to push the retry straight into `pending_calls`, where it kept
18665    /// the loop alive and was sent again during `close()`.
18666    #[tokio::test]
18667    async fn a_quota_retry_during_close_is_rejected_by_the_closing_gate() {
18668        let (admin, mut runnable, _time, _nodes) = env();
18669        let result = admin.create_topics_with_options(
18670            &[NewTopic::with_num_partitions_replication_factor(
18671                "topic1",
18672                Some(1),
18673                Some(1),
18674            )],
18675            CreateTopicsOptions::new().set_retry_on_quota_violation(true),
18676        );
18677        pump_until_request_queued(&mut runnable).await;
18678
18679        // `close(30s)` with the createTopics request in flight. No task was
18680        // spawned, so this only publishes the deadline.
18681        admin.close_with_timeout(Duration::from_secs(30)).await;
18682        // The controller answers with a quota violation, which asks for a retry.
18683        runnable.client_mut().respond(create_response_throttled(
18684            1000,
18685            vec![create_result("topic1", Errors::ThrottlingQuotaExceeded, None)],
18686        ));
18687        runnable.run_once().await;
18688
18689        let future = &result.values()["topic1"];
18690        assert!(
18691            future.is_done(),
18692            "the quota retry must be rejected at once, not queued to be sent again during close()"
18693        );
18694        let error = future.get().await.expect_err("the rejected retry fails the topic");
18695        assert!(matches!(error, Error::LocalIllegalState(_)), "got {error:?}");
18696        assert_eq!(error.message(), "Cannot accept new calls when AdminClient is closing.");
18697        assert!(
18698            !runnable.has_active_external_calls_for_test(),
18699            "the rejected retry must not stay queued"
18700        );
18701    }
18702
18703    /// Java publishes the hard-shutdown deadline through a compare-and-set loop
18704    /// that only ever moves it *earlier* (`KafkaAdminClient.close`: "Hard
18705    /// shutdown time is already earlier than requested"). A plain store would let
18706    /// a later, more relaxed `close()` re-widen the poll budget that `process_pending_calls`
18707    /// reads on every iteration — stretching the wait of a caller already parked
18708    /// in the join above.
18709    #[tokio::test]
18710    async fn close_never_widens_an_existing_hard_shutdown_deadline() {
18711        let (admin, _runnable, time, _nodes) = env();
18712        let now = time.milliseconds();
18713        let deadline = || admin.shared.shutdown.hard_shutdown_deadline_ms.load(Ordering::Acquire);
18714
18715        // No task was spawned, so each `close()` here only publishes the deadline.
18716        admin.close_with_timeout(Duration::from_millis(100)).await;
18717        assert_eq!(deadline(), now + 100, "the first close() installs its own deadline");
18718
18719        admin.close_with_timeout(Duration::from_secs(60)).await;
18720        assert_eq!(
18721            deadline(),
18722            now + 100,
18723            "a later, more relaxed close() must keep the earlier deadline"
18724        );
18725
18726        admin.close_with_timeout(Duration::from_millis(10)).await;
18727        assert_eq!(deadline(), now + 10, "a more urgent close() does move the deadline earlier");
18728    }
18729
18730    /// Java caps the wait at a year ("Limit the timeout to a year"), which also
18731    /// keeps the deadline it derives finite — the no-argument `Admin.close()`
18732    /// passes `Duration.ofMillis(Long.MAX_VALUE)`.
18733    #[tokio::test]
18734    async fn close_clamps_the_wait_to_a_year() {
18735        let (admin, _runnable, time, _nodes) = env();
18736        let now = time.milliseconds();
18737        admin.close_with_timeout(Duration::from_millis(i64::MAX as u64)).await;
18738        assert_eq!(
18739            admin.shared.shutdown.hard_shutdown_deadline_ms.load(Ordering::Acquire),
18740            now + MAX_CLOSE_WAIT_TIME_MS
18741        );
18742    }
18743}