Skip to main content

krabka_client_admin/
lib.rs

1//! Admin client for Krabka operators and control-plane services.
2//!
3//! The client targets the active controller and retries selected RPCs on a
4//! refreshed controller connection when the broker returns `NOT_CONTROLLER`.
5//! It supports plaintext by default and the same client-side TLS/SASL security
6//! surface as [`krabka_client_core`] through [`AdminClient::connect_secured`].
7//!
8//! The client is built on `krabka_client_core::Connection`'s typed
9//! `send::<R: ProtocolRequest>`, so request-version negotiation is automatic
10//! through the `ApiVersionTable` that connect time populates. The public
11//! modules cover topic CRUD, listing and description, partition expansion,
12//! config changes and config-resource listing, SCRAM user credentials, ACLs,
13//! client quotas, delegation tokens, metadata-quorum voters, and log-dir
14//! inspection.
15
16use std::{
17    any::Any,
18    collections::BTreeMap,
19    sync::{Arc, Mutex},
20};
21
22#[cfg(test)]
23use krabka_client_core::{ClientDnsTimeout, MockBroker};
24use krabka_client_core::{
25    ClientError, Connection, ConnectionOptions, MetadataRecoveryRebootstrapTrigger,
26    MetadataRecoveryStrategy, ProtocolRequest as _, connection_target_host, security,
27    telemetry::{
28        ClientMetrics, ClientTelemetry, ClientTelemetryConfig, NetworkMetrics, TelemetryClientType,
29        TelemetryTiming,
30    },
31    transport,
32};
33use krabka_protocol::owned::{metadata_request, metadata_response};
34use krabka_units::{Time, convert::TimeExt as _};
35use thiserror::Error;
36
37pub mod brokers;
38pub mod cluster;
39mod config;
40pub mod config_resources;
41pub mod configs;
42pub mod consumer_group_listings;
43pub mod delegation_tokens;
44pub mod elections;
45pub mod features;
46mod group_coordinators;
47pub mod group_deletions;
48pub mod group_descriptions;
49pub mod groups;
50pub mod log_dirs;
51pub mod offsets;
52mod partition_leaders;
53pub mod quorum;
54pub mod quotas;
55mod retry;
56pub mod share_group_offsets;
57mod telemetry;
58pub mod topic_descriptions;
59pub mod topics;
60pub mod transactions;
61
62#[cfg(test)]
63#[macro_export]
64macro_rules! encode_test_struct_field {
65    ($encoder:ident, $response:ident, $field:ident, $value:expr, $version:expr, $flexible:expr $(,)?) => {
66        $encoder(
67            &$response {
68                $field: $value,
69                ..Default::default()
70            },
71            $version,
72            $flexible,
73        )
74    };
75}
76
77#[cfg(test)]
78#[macro_export]
79macro_rules! encode_test_struct_fields {
80    ($encoder:ident, $response:ident, { $($field:ident: $value:expr),+ $(,)? }, $version:expr, $flexible:expr $(,)?) => {
81        $encoder(
82            &$response {
83                $($field: $value,)+
84                ..Default::default()
85            },
86            $version,
87            $flexible,
88        )
89    };
90}
91pub mod users;
92
93/// Result of applying a `metadata.version` feature update.
94#[derive(Debug, Clone, PartialEq, Eq)]
95pub struct MetadataVersionUpdate {
96    pub level: i16,
97}
98
99pub use cluster::{ClusterDescription, ClusterNode, DescribeClusterOptions};
100pub use config::{
101    AdminClientConfig, DEFAULT_ADMIN_CONNECTIONS_MAX_IDLE, DEFAULT_ADMIN_REQUEST_TIMEOUT,
102    DEFAULT_API_TIMEOUT, DEFAULT_ENABLE_METRICS_PUSH, DEFAULT_RETRY_BACKOFF,
103    DEFAULT_RETRY_BACKOFF_MAX, DEFAULT_SOCKET_CONNECTION_SETUP_TIMEOUT,
104    DEFAULT_SOCKET_CONNECTION_SETUP_TIMEOUT_MAX,
105};
106pub use config_resources::{ConfigResource, ConfigResourceType};
107pub use configs::{
108    AlterConfigOp, AlterConfigOpType, AlterConfigsResults, Config, ConfigEntry, ConfigSource,
109    ConfigSynonym, ConfigType, DescribeConfigsOptions, DescribeConfigsResults,
110    IncrementalAlterConfigsOptions,
111};
112pub use consumer_group_listings::{
113    ConsumerGroupListing, ListConsumerGroupsOptions, ListConsumerGroupsResult,
114};
115pub use delegation_tokens::{
116    CreateDelegationTokenOptions, DelegationToken, DescribeDelegationTokenOptions,
117    ExpireDelegationTokenOptions, RenewDelegationTokenOptions,
118};
119pub use elections::{ElectionResults, ElectionType};
120pub use features::{
121    DescribeFeaturesOptions, FeatureMetadata, FeatureRange, FeatureUpdate, UpdateFeaturesOptions,
122    UpdateFeaturesResults, UpgradeType,
123};
124pub use group_deletions::GroupDeletions;
125pub use group_descriptions::{
126    ClassicGroupDescription, ConsumerGroupDescription, DescribeGroupsOptions, GroupDescriptions,
127    MemberDescription, ShareGroupDescription, StreamsGroupDescription,
128};
129pub use groups::{
130    ConsumerGroupOffsetOutcome, MemberToRemove, RemoveMembersOptions, RemovedMember, RemovedMembers,
131};
132pub use log_dirs::{
133    BrokerResult, LogDirInfo, LogDirPartitionInfo, LogDirTopicInfo, ReplicaLogDir,
134    ReplicaLogDirInfo, TopicPartitionReplica,
135};
136pub use offsets::{IsolationLevel, ListedOffset, OffsetSpec};
137pub use quorum::{MetadataQuorum, QuorumNode, QuorumReplica, RaftVoterEndpoint};
138pub use quotas::{
139    ClientQuotaAlteration, ClientQuotaEntity, ClientQuotaFilter, ClientQuotaFilterComponent,
140    ClientQuotaMatch, ClientQuotas, ENTITY_CLIENT_ID, ENTITY_IP, ENTITY_USER, QuotaOp,
141    UserQuotaConfig, diff_user_quotas,
142};
143pub use share_group_offsets::{
144    ListShareGroupOffsetsSpec, ShareGroupOffsets, SharePartitionOffsetInfo,
145};
146pub use topic_descriptions::{
147    DescribeTopicsOptions, ListTopicsOptions, TopicDescription, TopicDescriptions, TopicListing,
148    TopicPartitionInfo,
149};
150pub use topics::{
151    AlterPartitionReassignmentsOptions, CreatePartitionsOp, CreatePartitionsOutcome,
152    CreateTopicOutcome, CreateTopicSpec, DeleteRecordsOp, DeleteRecordsOutcome, DeleteTopicOutcome,
153    PartitionAssignment, PartitionAssignmentOutcome, TopicMetadata, TopicMetadataEntry,
154    TopicMutationOptions, TopicReplicationStatus,
155};
156pub use transactions::{
157    AbortTransactionSpec, ListTransactionsFilter, ProducerStateInfo, TransactionDescription,
158    TransactionListing,
159};
160pub use users::{
161    AclEntry, AclEntryFilter, AclOperation, CreateAclOutcome, DEFAULT_SCRAM_ITERATIONS,
162    DeleteAclFilterOutcome, MAX_SCRAM_ITERATIONS, MIN_SCRAM_ITERATIONS, PatternType,
163    PermissionType, ResourceType, ScramDeletion, ScramIterations, ScramUpsertion, ScramUserOutcome,
164    UserScramCredential, UserScramCredentials,
165};
166
167/// Test seam for `AdminClient`.
168///
169/// The operator's reconcile only needs dynamic dispatch through this trait.
170/// Production code wraps a concrete `AdminClient`, and tests substitute a
171/// fake.
172///
173/// Methods take `&mut self` because the underlying `AdminClient`'s
174/// `NOT_CONTROLLER` retry path reconnects the inner `Connection` in place,
175/// which needs unique access.
176#[async_trait::async_trait]
177pub trait AdminClientLike: Send {
178    /// Finalize `metadata.version` at `level` with `upgrade_type`, as
179    /// [`AdminClient::update_metadata_version`] does.
180    async fn update_metadata_version(
181        &mut self,
182        _level: i16,
183        _upgrade_type: UpgradeType,
184        _timeout: Time,
185    ) -> Result<MetadataVersionUpdate, AdminError> {
186        Err(AdminError::Protocol(
187            "UpdateFeatures is not implemented by this admin client".into(),
188        ))
189    }
190    /// Read committed metadata-quorum membership.
191    async fn describe_metadata_quorum(&mut self) -> Result<MetadataQuorum, AdminError> {
192        Err(AdminError::Protocol(
193            "DescribeQuorum is not implemented by this admin client".into(),
194        ))
195    }
196    /// Remove one exact metadata-quorum voter identity. `cluster_id` is
197    /// Kafka's `RemoveRaftVoterOptions.clusterId`.
198    async fn remove_raft_voter(
199        &mut self,
200        _cluster_id: Option<&str>,
201        _node_id: i32,
202        _directory_id: uuid::Uuid,
203    ) -> Result<(), AdminError> {
204        Err(AdminError::Protocol(
205            "RemoveRaftVoter is not implemented by this admin client".into(),
206        ))
207    }
208    async fn metadata(&mut self, topics: &[&str]) -> Result<TopicMetadata, AdminError>;
209    async fn reconcile_topic_replication_factor(
210        &mut self,
211        topic: &str,
212        replication_factor: i32,
213        timeout: Time,
214    ) -> Result<TopicReplicationStatus, AdminError>;
215    /// Read exact replica membership without changing broker state.
216    async fn describe_partition_assignments(
217        &mut self,
218        _topics: &[&str],
219    ) -> Result<Vec<PartitionAssignment>, AdminError> {
220        Err(AdminError::Protocol(
221            "Describe partition assignments is not implemented by this admin client".into(),
222        ))
223    }
224    /// List active reassignments for the selected partitions.
225    async fn list_partition_reassignments(
226        &mut self,
227        _partitions: &BTreeMap<String, Vec<i32>>,
228        _timeout: Time,
229    ) -> Result<Vec<PartitionAssignment>, AdminError> {
230        Err(AdminError::Protocol(
231            "ListPartitionReassignments is not implemented by this admin client".into(),
232        ))
233    }
234    /// Submit exact replica assignments, or cancel them with `None`.
235    async fn alter_partition_assignments(
236        &mut self,
237        _assignments: &BTreeMap<(String, i32), Option<Vec<i32>>>,
238        _timeout: Time,
239    ) -> Result<Vec<PartitionAssignmentOutcome>, AdminError> {
240        Err(AdminError::Protocol(
241            "AlterPartitionReassignments is not implemented by this admin client".into(),
242        ))
243    }
244    /// Remove a broker registration through the active controller.
245    async fn unregister_broker(&mut self, _broker_id: i32) -> Result<(), AdminError> {
246        Err(AdminError::Protocol(
247            "UnregisterBroker is not implemented by this admin client".into(),
248        ))
249    }
250    async fn create_topics(
251        &mut self,
252        specs: &[CreateTopicSpec],
253        options: TopicMutationOptions,
254    ) -> Result<Vec<CreateTopicOutcome>, AdminError>;
255    async fn delete_topics(
256        &mut self,
257        names: &[&str],
258        options: TopicMutationOptions,
259    ) -> Result<Vec<DeleteTopicOutcome>, AdminError>;
260    async fn create_partitions(
261        &mut self,
262        ops: &[CreatePartitionsOp],
263        options: TopicMutationOptions,
264    ) -> Result<Vec<CreatePartitionsOutcome>, AdminError>;
265    async fn delete_records(
266        &mut self,
267        ops: &[DeleteRecordsOp],
268        timeout: Time,
269    ) -> Result<Vec<DeleteRecordsOutcome>, AdminError>;
270    async fn describe_configs(
271        &mut self,
272        resources: &[ConfigResource],
273        options: DescribeConfigsOptions,
274    ) -> Result<DescribeConfigsResults, AdminError>;
275    async fn incremental_alter_configs(
276        &mut self,
277        configs: &BTreeMap<ConfigResource, Vec<AlterConfigOp>>,
278        options: IncrementalAlterConfigsOptions,
279    ) -> Result<AlterConfigsResults, AdminError>;
280    async fn alter_user_scram_credentials_sha512(
281        &mut self,
282        upsertions: &[ScramUpsertion],
283        deletions: &[ScramDeletion],
284    ) -> Result<Vec<ScramUserOutcome>, AdminError>;
285    /// SCRAM-SHA-256 sibling of
286    /// [`Self::alter_user_scram_credentials_sha512`]. The operator
287    /// calls this when a `KafkaUser.spec.authentication.type ==
288    /// scram-sha-256`.
289    async fn alter_user_scram_credentials_sha256(
290        &mut self,
291        upsertions: &[ScramUpsertion],
292        deletions: &[ScramDeletion],
293    ) -> Result<Vec<ScramUserOutcome>, AdminError>;
294    async fn describe_acls(&mut self, filter: &AclEntryFilter)
295    -> Result<Vec<AclEntry>, AdminError>;
296    async fn create_acls(
297        &mut self,
298        creations: &[AclEntry],
299    ) -> Result<Vec<CreateAclOutcome>, AdminError>;
300    async fn delete_acls(
301        &mut self,
302        filters: &[AclEntryFilter],
303    ) -> Result<Vec<DeleteAclFilterOutcome>, AdminError>;
304    async fn describe_user_quotas(&mut self, username: &str)
305    -> Result<UserQuotaConfig, AdminError>;
306    async fn alter_user_quotas(
307        &mut self,
308        username: &str,
309        ops: &[QuotaOp],
310        validate_only: bool,
311    ) -> Result<Option<KafkaError>, AdminError>;
312
313    // ── delegation-token RPCs (KIP-48) ────────────────────────────────
314    //
315    // Each method mirrors the inherent method of the same name in
316    // `delegation_tokens.rs`.
317    async fn create_delegation_token(
318        &mut self,
319        options: &CreateDelegationTokenOptions,
320    ) -> Result<DelegationToken, AdminError>;
321    async fn renew_delegation_token(
322        &mut self,
323        hmac: &[u8],
324        options: RenewDelegationTokenOptions,
325    ) -> Result<i64, AdminError>;
326    async fn expire_delegation_token(
327        &mut self,
328        hmac: &[u8],
329        options: ExpireDelegationTokenOptions,
330    ) -> Result<i64, AdminError>;
331    async fn describe_delegation_token(
332        &mut self,
333        options: &DescribeDelegationTokenOptions,
334    ) -> Result<Vec<DelegationToken>, AdminError>;
335}
336
337#[async_trait::async_trait]
338impl AdminClientLike for AdminClient {
339    async fn update_metadata_version(
340        &mut self,
341        level: i16,
342        upgrade_type: UpgradeType,
343        timeout: Time,
344    ) -> Result<MetadataVersionUpdate, AdminError> {
345        AdminClient::update_metadata_version(self, level, upgrade_type, timeout).await
346    }
347
348    async fn describe_metadata_quorum(&mut self) -> Result<MetadataQuorum, AdminError> {
349        AdminClient::describe_metadata_quorum(self).await
350    }
351
352    async fn remove_raft_voter(
353        &mut self,
354        cluster_id: Option<&str>,
355        node_id: i32,
356        directory_id: uuid::Uuid,
357    ) -> Result<(), AdminError> {
358        AdminClient::remove_raft_voter(self, cluster_id, node_id, directory_id).await
359    }
360
361    async fn metadata(&mut self, topics: &[&str]) -> Result<TopicMetadata, AdminError> {
362        AdminClient::metadata(self, topics).await
363    }
364    async fn reconcile_topic_replication_factor(
365        &mut self,
366        topic: &str,
367        replication_factor: i32,
368        timeout: Time,
369    ) -> Result<TopicReplicationStatus, AdminError> {
370        AdminClient::reconcile_topic_replication_factor(self, topic, replication_factor, timeout)
371            .await
372    }
373    async fn describe_partition_assignments(
374        &mut self,
375        topics: &[&str],
376    ) -> Result<Vec<PartitionAssignment>, AdminError> {
377        AdminClient::describe_partition_assignments(self, topics).await
378    }
379    async fn list_partition_reassignments(
380        &mut self,
381        partitions: &BTreeMap<String, Vec<i32>>,
382        timeout: Time,
383    ) -> Result<Vec<PartitionAssignment>, AdminError> {
384        AdminClient::list_partition_reassignments(self, partitions, timeout).await
385    }
386    async fn alter_partition_assignments(
387        &mut self,
388        assignments: &BTreeMap<(String, i32), Option<Vec<i32>>>,
389        timeout: Time,
390    ) -> Result<Vec<PartitionAssignmentOutcome>, AdminError> {
391        AdminClient::alter_partition_assignments(self, assignments, timeout).await
392    }
393    async fn unregister_broker(&mut self, broker_id: i32) -> Result<(), AdminError> {
394        AdminClient::unregister_broker(self, broker_id).await
395    }
396    async fn create_topics(
397        &mut self,
398        specs: &[CreateTopicSpec],
399        options: TopicMutationOptions,
400    ) -> Result<Vec<CreateTopicOutcome>, AdminError> {
401        AdminClient::create_topics(self, specs, options).await
402    }
403    async fn delete_topics(
404        &mut self,
405        names: &[&str],
406        options: TopicMutationOptions,
407    ) -> Result<Vec<DeleteTopicOutcome>, AdminError> {
408        AdminClient::delete_topics(self, names, options).await
409    }
410    async fn create_partitions(
411        &mut self,
412        ops: &[CreatePartitionsOp],
413        options: TopicMutationOptions,
414    ) -> Result<Vec<CreatePartitionsOutcome>, AdminError> {
415        AdminClient::create_partitions(self, ops, options).await
416    }
417    async fn delete_records(
418        &mut self,
419        ops: &[DeleteRecordsOp],
420        timeout: Time,
421    ) -> Result<Vec<DeleteRecordsOutcome>, AdminError> {
422        AdminClient::delete_records(self, ops, timeout).await
423    }
424    async fn describe_configs(
425        &mut self,
426        resources: &[ConfigResource],
427        options: DescribeConfigsOptions,
428    ) -> Result<DescribeConfigsResults, AdminError> {
429        AdminClient::describe_configs(self, resources, options).await
430    }
431    async fn incremental_alter_configs(
432        &mut self,
433        configs: &BTreeMap<ConfigResource, Vec<AlterConfigOp>>,
434        options: IncrementalAlterConfigsOptions,
435    ) -> Result<AlterConfigsResults, AdminError> {
436        AdminClient::incremental_alter_configs(self, configs, options).await
437    }
438    async fn alter_user_scram_credentials_sha512(
439        &mut self,
440        upsertions: &[ScramUpsertion],
441        deletions: &[ScramDeletion],
442    ) -> Result<Vec<ScramUserOutcome>, AdminError> {
443        AdminClient::alter_user_scram_credentials_sha512(self, upsertions, deletions).await
444    }
445    async fn alter_user_scram_credentials_sha256(
446        &mut self,
447        upsertions: &[ScramUpsertion],
448        deletions: &[ScramDeletion],
449    ) -> Result<Vec<ScramUserOutcome>, AdminError> {
450        AdminClient::alter_user_scram_credentials_sha256(self, upsertions, deletions).await
451    }
452    async fn describe_acls(
453        &mut self,
454        filter: &AclEntryFilter,
455    ) -> Result<Vec<AclEntry>, AdminError> {
456        AdminClient::describe_acls(self, filter).await
457    }
458    async fn create_acls(
459        &mut self,
460        creations: &[AclEntry],
461    ) -> Result<Vec<CreateAclOutcome>, AdminError> {
462        AdminClient::create_acls(self, creations).await
463    }
464    async fn delete_acls(
465        &mut self,
466        filters: &[AclEntryFilter],
467    ) -> Result<Vec<DeleteAclFilterOutcome>, AdminError> {
468        AdminClient::delete_acls(self, filters).await
469    }
470    async fn describe_user_quotas(
471        &mut self,
472        username: &str,
473    ) -> Result<UserQuotaConfig, AdminError> {
474        AdminClient::describe_user_quotas(self, username).await
475    }
476    async fn alter_user_quotas(
477        &mut self,
478        username: &str,
479        ops: &[QuotaOp],
480        validate_only: bool,
481    ) -> Result<Option<KafkaError>, AdminError> {
482        AdminClient::alter_user_quotas(self, username, ops, validate_only).await
483    }
484
485    async fn create_delegation_token(
486        &mut self,
487        options: &CreateDelegationTokenOptions,
488    ) -> Result<DelegationToken, AdminError> {
489        AdminClient::create_delegation_token(self, options).await
490    }
491    async fn renew_delegation_token(
492        &mut self,
493        hmac: &[u8],
494        options: RenewDelegationTokenOptions,
495    ) -> Result<i64, AdminError> {
496        AdminClient::renew_delegation_token(self, hmac, options).await
497    }
498    async fn expire_delegation_token(
499        &mut self,
500        hmac: &[u8],
501        options: ExpireDelegationTokenOptions,
502    ) -> Result<i64, AdminError> {
503        AdminClient::expire_delegation_token(self, hmac, options).await
504    }
505    async fn describe_delegation_token(
506        &mut self,
507        options: &DescribeDelegationTokenOptions,
508    ) -> Result<Vec<DelegationToken>, AdminError> {
509        AdminClient::describe_delegation_token(self, options).await
510    }
511}
512
513#[derive(Debug, Error)]
514pub enum AdminError {
515    /// No bootstrap address gave a usable connection. `source` holds the
516    /// error from the last address tried, and is `None` only when the list
517    /// was empty. Match it to tell an unreachable or silent broker
518    /// ([`ClientError::Connect`] or [`ClientError::Timeout`]) from a TLS or
519    /// SASL failure with no verdict from the peer ([`ClientError::Tls`] or
520    /// [`ClientError::Sasl`]).
521    ///
522    /// A rejected authentication does not give this error. The client stops
523    /// at the first address that rejects it and returns
524    /// `AdminError::Transport(ClientError::Authentication { .. })`, as Kafka's
525    /// `AdminMetadataManager` makes an `AuthenticationException` fatal.
526    #[error("no bootstrap address connected: tried {tried}{cause}",
527            cause = .source.as_ref().map(|e| format!("; last error: {e}")).unwrap_or_default())]
528    Connect {
529        tried: usize,
530        #[source]
531        source: Option<Box<AdminError>>,
532    },
533    /// A setting of [`AdminClientConfig`] is invalid, as Kafka raises a
534    /// `ConfigException` when it builds the admin client.
535    #[error("invalid admin client configuration: {0}")]
536    InvalidConfig(String),
537    /// An argument of a call is invalid, as Kafka's admin types throw an
538    /// `IllegalArgumentException` before anything is sent.
539    #[error("invalid argument: {0}")]
540    InvalidArgument(String),
541    #[error("broker returned error: api={api} code={code} ({name}){detail}",
542            detail = .message.as_deref().map(|m| format!(" {m:?}")).unwrap_or_default())]
543    Broker {
544        api: &'static str,
545        code: i16,
546        name: &'static str,
547        message: Option<String>,
548    },
549    #[error("client-core: {0}")]
550    Transport(#[from] ClientError),
551    #[error("protocol: {0}")]
552    Protocol(String),
553}
554
555impl AdminError {
556    /// Whether a peer rejected authentication. Kafka's admin client fails the
557    /// call with the `AuthenticationException` and does not retry
558    /// (`KafkaAdminClient` `handleResponses`, `AdminMetadataManager.updateFailed`).
559    #[must_use]
560    pub const fn is_authentication_failure(&self) -> bool {
561        matches!(self, Self::Transport(error) if error.is_authentication_failure())
562    }
563}
564
565/// A Kafka-level error attached to a single per-resource outcome.
566#[derive(Debug, Clone, PartialEq, Eq)]
567pub struct KafkaError {
568    pub code: i16,
569    pub name: &'static str,
570    pub message: Option<String>,
571}
572
573pub(crate) fn kafka_error_if(code: i16, message: Option<String>) -> Option<KafkaError> {
574    if code == 0 {
575        None
576    } else {
577        Some(KafkaError {
578            code,
579            name: kafka_error_name(code),
580            message,
581        })
582    }
583}
584
585async fn lookup_first<F, I>(
586    host_port: &str,
587    dns_timeout: krabka_client_core::ClientDnsTimeout,
588    lookup: F,
589) -> Result<std::net::SocketAddr, AdminError>
590where
591    F: std::future::Future<Output = std::io::Result<I>>,
592    I: IntoIterator<Item = std::net::SocketAddr>,
593{
594    let addrs = tokio::time::timeout(dns_timeout.time().to_std(), lookup)
595        .await
596        .map_err(|_| {
597            AdminError::Protocol(format!(
598                "DNS lookup {host_port} timed out after {} ms",
599                dns_timeout.milliseconds(),
600            ))
601        })?
602        .map_err(|error| AdminError::Protocol(format!("DNS lookup {host_port}: {error}")))?;
603    addrs
604        .into_iter()
605        .next()
606        .ok_or_else(|| AdminError::Protocol(format!("no addresses for {host_port}")))
607}
608
609fn format_host_port(host: &str, port: i32) -> String {
610    if host.contains(':') && !host.starts_with('[') {
611        format!("[{host}]:{port}")
612    } else {
613        format!("{host}:{port}")
614    }
615}
616
617/// Short-lived admin client that targets one cluster's controller. It can
618/// negotiate TLS/SASL through [`AdminClient::connect_secured`].
619///
620/// As Kafka's admin client with `enable.metrics.push` on (the default), it
621/// pushes the client metrics that a broker's client metrics subscription
622/// names (KIP-714) on its bootstrap connection, and its connections count in
623/// the `admin-client-metrics` network metrics.
624/// [`AdminClientConfig::enable_metrics_push`] turns this off. The
625/// constructors without an [`AdminClientConfig`] keep Kafka's default.
626/// [`close`](Self::close) sends the terminating push and waits for it;
627/// dropping the client sends it in the background.
628pub struct AdminClient {
629    pub(crate) conn: Arc<RecoveringConnection>,
630    bootstrap_addrs: Vec<String>,
631    /// Full connection template carried forward so reconnects preserve
632    /// caller-supplied identity, security, and timeouts. With metrics push
633    /// on, it carries the network metrics that each new connection counts in.
634    options: ConnectionOptions,
635    /// The deadline, backoff and retry count of each call
636    /// (`default.api.timeout.ms`, `retry.backoff.ms`, `retry.backoff.max.ms`,
637    /// `retries`).
638    pub(crate) retry: retry::RetryPolicy,
639    /// The KIP-714 reporter, `None` with `enable_metrics_push` off. Dropping
640    /// it starts the terminating push.
641    telemetry: Option<ClientTelemetry>,
642}
643
644#[derive(Clone, Copy, Debug, Eq, PartialEq)]
645enum BootstrapTarget {
646    Brokers,
647    Controllers,
648}
649
650struct ConnectedTarget {
651    connection: Connection,
652    discovered_addrs: Vec<String>,
653}
654
655/// One controller connection with KIP-919/KIP-1102 bootstrap recovery.
656pub(crate) struct RecoveringConnection {
657    inner: tokio::sync::RwLock<Arc<Connection>>,
658    bootstrap_addrs: Vec<String>,
659    options: ConnectionOptions,
660    strategy: MetadataRecoveryStrategy,
661    trigger: MetadataRecoveryRebootstrapTrigger,
662    target: BootstrapTarget,
663    known_addrs: Mutex<Vec<String>>,
664    first_metadata_attempt: Mutex<Option<tokio::time::Instant>>,
665}
666
667impl RecoveringConnection {
668    fn new(
669        connection: Connection,
670        bootstrap_addrs: Vec<String>,
671        options: ConnectionOptions,
672        strategy: MetadataRecoveryStrategy,
673        trigger: MetadataRecoveryRebootstrapTrigger,
674        target: BootstrapTarget,
675        known_addrs: Vec<String>,
676    ) -> Self {
677        Self {
678            inner: tokio::sync::RwLock::new(Arc::new(connection)),
679            bootstrap_addrs,
680            options,
681            strategy,
682            trigger,
683            target,
684            known_addrs: Mutex::new(known_addrs),
685            first_metadata_attempt: Mutex::new(None),
686        }
687    }
688
689    pub(crate) async fn send<R>(&self, request: R) -> Result<R::Response, AdminError>
690    where
691        R: krabka_protocol::ProtocolRequest + Clone,
692        R::Response: 'static,
693    {
694        self.send_with_min_version(request, None).await
695    }
696
697    pub(crate) async fn send_at_least<R>(
698        &self,
699        request: R,
700        min_version: i16,
701    ) -> Result<R::Response, AdminError>
702    where
703        R: krabka_protocol::ProtocolRequest + Clone,
704        R::Response: 'static,
705    {
706        self.send_with_min_version(request, Some(min_version)).await
707    }
708
709    async fn send_with_min_version<R>(
710        &self,
711        request: R,
712        min_version: Option<i16>,
713    ) -> Result<R::Response, AdminError>
714    where
715        R: krabka_protocol::ProtocolRequest + Clone,
716        R::Response: 'static,
717    {
718        self.require_advertised_controller_api::<R>().await?;
719        self.begin_metadata_attempt::<R>();
720        let first = self.send_current(request.clone(), min_version).await;
721        match first {
722            Ok(response) if Self::response_requires_rebootstrap(&response) => {
723                if self.strategy == MetadataRecoveryStrategy::None {
724                    return Err(AdminError::Transport(ClientError::Server {
725                        error_code: 129,
726                    }));
727                }
728                self.send_after_rebootstrap(request, min_version).await
729            }
730            Ok(response) if self.metadata_attempt_timed_out(&response) => {
731                self.send_after_rebootstrap(request, min_version).await
732            }
733            Ok(response) => {
734                self.observe_cluster_endpoints(&response);
735                self.complete_metadata_attempt(&response);
736                Ok(response)
737            }
738            Err(error) if AdminClient::is_retriable_transport_error(&error) => {
739                match self
740                    .send_after_current_metadata(request.clone(), min_version)
741                    .await
742                {
743                    Ok(response) => Ok(response),
744                    Err(retry_error) if retry_error.is_authentication_failure() => Err(retry_error),
745                    Err(_) if self.strategy == MetadataRecoveryStrategy::Rebootstrap => {
746                        self.send_after_rebootstrap(request, min_version).await
747                    }
748                    Err(_) => Err(AdminError::from(error)),
749                }
750            }
751            Err(error) => Err(AdminError::from(error)),
752        }
753    }
754
755    async fn replace(&self, connection: Connection) {
756        *self.inner.write().await = Arc::new(connection);
757    }
758
759    async fn send_current<R>(
760        &self,
761        request: R,
762        min_version: Option<i16>,
763    ) -> Result<R::Response, ClientError>
764    where
765        R: krabka_protocol::ProtocolRequest,
766    {
767        let connection = self.inner.read().await;
768        if let Some(min_version) = min_version {
769            return send_connection_at_least(&connection, request, min_version).await;
770        }
771        connection.send(request).await
772    }
773
774    async fn send_after_rebootstrap<R>(
775        &self,
776        request: R,
777        min_version: Option<i16>,
778    ) -> Result<R::Response, AdminError>
779    where
780        R: krabka_protocol::ProtocolRequest,
781        R::Response: 'static,
782    {
783        self.rebootstrap().await?;
784        self.require_advertised_controller_api::<R>().await?;
785        self.begin_metadata_attempt::<R>();
786        let response = self.send_current(request, min_version).await?;
787        if Self::response_requires_rebootstrap(&response) {
788            return Err(AdminError::Transport(ClientError::Server {
789                error_code: 129,
790            }));
791        }
792        self.observe_cluster_endpoints(&response);
793        self.complete_metadata_attempt(&response);
794        Ok(response)
795    }
796
797    async fn send_after_current_metadata<R>(
798        &self,
799        request: R,
800        min_version: Option<i16>,
801    ) -> Result<R::Response, AdminError>
802    where
803        R: krabka_protocol::ProtocolRequest + Clone,
804        R::Response: 'static,
805    {
806        self.reconnect_current_metadata().await?;
807        self.require_advertised_controller_api::<R>().await?;
808        let response = self.send_current(request.clone(), min_version).await?;
809        if Self::response_requires_rebootstrap(&response) {
810            if self.strategy == MetadataRecoveryStrategy::Rebootstrap {
811                return self.send_after_rebootstrap(request, min_version).await;
812            }
813            return Err(AdminError::Transport(ClientError::Server {
814                error_code: 129,
815            }));
816        }
817        if self.metadata_attempt_timed_out(&response) {
818            return self.send_after_rebootstrap(request, min_version).await;
819        }
820        self.observe_cluster_endpoints(&response);
821        self.complete_metadata_attempt(&response);
822        Ok(response)
823    }
824
825    async fn require_advertised_controller_api<R>(&self) -> Result<(), AdminError>
826    where
827        R: krabka_protocol::ProtocolRequest,
828    {
829        const UNSUPPORTED_ENDPOINT_TYPE: i16 = 115;
830        if self.target == BootstrapTarget::Controllers
831            && self
832                .inner
833                .read()
834                .await
835                .advertised_api_range(R::API_KEY)
836                .is_none()
837        {
838            return Err(AdminError::Broker {
839                api: "ControllerEndpoint",
840                code: UNSUPPORTED_ENDPOINT_TYPE,
841                name: kafka_error_name(UNSUPPORTED_ENDPOINT_TYPE),
842                message: Some(format!(
843                    "api_key {} is not supported by the controller listener",
844                    R::API_KEY
845                )),
846            });
847        }
848        Ok(())
849    }
850
851    pub(crate) async fn rebootstrap(&self) -> Result<(), AdminError> {
852        let mut last_error = None;
853        for host_port in &self.bootstrap_addrs {
854            match AdminClient::connect_target_one_with_discovery(
855                host_port,
856                self.options.clone(),
857                self.target,
858            )
859            .await
860            {
861                Ok(connected) => {
862                    self.replace(connected.connection).await;
863                    self.replace_known_addrs(if connected.discovered_addrs.is_empty() {
864                        self.bootstrap_addrs.clone()
865                    } else {
866                        connected.discovered_addrs
867                    });
868                    self.clear_metadata_attempt();
869                    return Ok(());
870                }
871                Err(error) if error.is_authentication_failure() => return Err(error),
872                Err(error) => last_error = Some(Box::new(error)),
873            }
874        }
875        Err(AdminError::Connect {
876            tried: self.bootstrap_addrs.len(),
877            source: last_error,
878        })
879    }
880
881    async fn reconnect_current_metadata(&self) -> Result<(), AdminError> {
882        let known_addrs = self
883            .known_addrs
884            .lock()
885            .unwrap_or_else(std::sync::PoisonError::into_inner)
886            .clone();
887        let mut last_error = None;
888        for host_port in &known_addrs {
889            match AdminClient::connect_target_one_with_discovery(
890                host_port,
891                self.options.clone(),
892                self.target,
893            )
894            .await
895            {
896                Ok(connected) => {
897                    self.replace(connected.connection).await;
898                    if !connected.discovered_addrs.is_empty() {
899                        self.replace_known_addrs(connected.discovered_addrs);
900                    }
901                    return Ok(());
902                }
903                Err(error) if error.is_authentication_failure() => return Err(error),
904                Err(error) => last_error = Some(Box::new(error)),
905            }
906        }
907        Err(AdminError::Connect {
908            tried: known_addrs.len(),
909            source: last_error,
910        })
911    }
912
913    fn replace_known_addrs(&self, addrs: Vec<String>) {
914        *self
915            .known_addrs
916            .lock()
917            .unwrap_or_else(std::sync::PoisonError::into_inner) = addrs;
918    }
919
920    fn observe_cluster_endpoints<T: Any>(&self, response: &T) {
921        if let Some(metadata) =
922            (response as &dyn Any).downcast_ref::<metadata_response::MetadataResponse>()
923        {
924            let endpoints = metadata
925                .brokers
926                .iter()
927                .filter(|broker| !broker.host.is_empty() && broker.port > 0)
928                .map(|broker| format_host_port(&broker.host, broker.port))
929                .collect::<Vec<_>>();
930            if !endpoints.is_empty() {
931                self.replace_known_addrs(endpoints);
932            }
933            return;
934        }
935        if self.target == BootstrapTarget::Controllers
936            && let Some(cluster) = (response as &dyn Any).downcast_ref::<
937                krabka_protocol::owned::describe_cluster_response::DescribeClusterResponse,
938            >()
939        {
940            let endpoints = cluster
941                .brokers
942                .iter()
943                .filter(|controller| !controller.host.is_empty() && controller.port > 0)
944                .map(|controller| format_host_port(&controller.host, controller.port))
945                .collect::<Vec<_>>();
946            if !endpoints.is_empty() {
947                self.replace_known_addrs(endpoints);
948            }
949        }
950    }
951
952    pub(crate) fn uses_controller_bootstrap(&self) -> bool {
953        self.target == BootstrapTarget::Controllers
954    }
955
956    /// The `(min, max)` versions of `api_key` that the current peer
957    /// advertised, or `None` when it did not advertise the API.
958    pub(crate) async fn advertised_api_range(&self, api_key: i16) -> Option<(i16, i16)> {
959        self.inner.read().await.advertised_api_range(api_key)
960    }
961
962    fn begin_metadata_attempt<R: krabka_protocol::ProtocolRequest>(&self) {
963        if R::API_KEY != metadata_request::MetadataRequest::API_KEY
964            || self.strategy == MetadataRecoveryStrategy::None
965        {
966            return;
967        }
968        self.first_metadata_attempt
969            .lock()
970            .unwrap_or_else(std::sync::PoisonError::into_inner)
971            .get_or_insert_with(tokio::time::Instant::now);
972    }
973
974    fn response_requires_rebootstrap<T: Any>(response: &T) -> bool {
975        (response as &dyn Any)
976            .downcast_ref::<metadata_response::MetadataResponse>()
977            .is_some_and(|metadata| metadata.error_code == 129)
978    }
979
980    fn metadata_attempt_timed_out<T: Any>(&self, response: &T) -> bool {
981        if self.strategy == MetadataRecoveryStrategy::None {
982            return false;
983        }
984        let Some(metadata) =
985            (response as &dyn Any).downcast_ref::<metadata_response::MetadataResponse>()
986        else {
987            return false;
988        };
989        metadata.brokers.is_empty()
990            && self
991                .first_metadata_attempt
992                .lock()
993                .unwrap_or_else(std::sync::PoisonError::into_inner)
994                .is_some_and(|started| started.elapsed() >= self.trigger.time().to_std())
995    }
996
997    fn complete_metadata_attempt<T: Any>(&self, response: &T) {
998        let has_brokers = (response as &dyn Any)
999            .downcast_ref::<metadata_response::MetadataResponse>()
1000            .is_some_and(|metadata| !metadata.brokers.is_empty());
1001        if has_brokers {
1002            self.clear_metadata_attempt();
1003        }
1004    }
1005
1006    fn clear_metadata_attempt(&self) {
1007        *self
1008            .first_metadata_attempt
1009            .lock()
1010            .unwrap_or_else(std::sync::PoisonError::into_inner) = None;
1011    }
1012}
1013
1014async fn send_connection_at_least<R>(
1015    connection: &Connection,
1016    request: R,
1017    min_version: i16,
1018) -> Result<R::Response, ClientError>
1019where
1020    R: krabka_protocol::ProtocolRequest,
1021{
1022    let (broker_min, broker_max) = connection
1023        .advertised_api_range(R::API_KEY)
1024        .unwrap_or((0, 0));
1025    let client_min = R::MIN_VERSION.max(min_version);
1026    let chosen = R::LATEST_STABLE_VERSION.min(broker_max);
1027    if chosen < client_min || chosen < broker_min {
1028        return Err(ClientError::IncompatibleVersion {
1029            api_key: R::API_KEY,
1030            broker_min,
1031            broker_max,
1032            client_min,
1033            client_max: R::LATEST_STABLE_VERSION,
1034        });
1035    }
1036    connection.send(request).await
1037}
1038
1039impl AdminClient {
1040    /// The connection options of Kafka's admin client defaults with the
1041    /// supplied security policy and a generated `adminclient-<n>` client id.
1042    fn opts(security: Option<security::ClientSecurity>) -> ConnectionOptions {
1043        AdminClientConfig {
1044            security,
1045            ..AdminClientConfig::default()
1046        }
1047        .resolve()
1048        .expect("the default admin client configuration is valid")
1049        .connection
1050    }
1051
1052    /// Connects with Kafka's `AdminClientConfig` settings. Each call of the
1053    /// client uses the call deadline, retry backoff and retry count of
1054    /// `config`.
1055    ///
1056    /// # Errors
1057    /// Returns [`AdminError::InvalidConfig`] for invalid settings, and
1058    /// [`AdminError::Connect`] with the last cause if no bootstrap address
1059    /// connects.
1060    pub async fn connect_with_config(
1061        bootstrap_addrs: &[String],
1062        config: AdminClientConfig,
1063    ) -> Result<Self, AdminError> {
1064        let resolved = config.resolve()?;
1065        Self::connect_with_metadata_recovery_target(
1066            bootstrap_addrs,
1067            resolved.connection,
1068            resolved.retry,
1069            (
1070                resolved.metadata_recovery_strategy,
1071                resolved.metadata_recovery_rebootstrap_trigger,
1072            ),
1073            BootstrapTarget::Brokers,
1074            resolved.enable_metrics_push,
1075        )
1076        .await
1077    }
1078
1079    /// Controller-bootstrap variant of [`Self::connect_with_config`]
1080    /// (KIP-919).
1081    ///
1082    /// # Errors
1083    /// Returns [`AdminError::InvalidConfig`] for invalid settings, or a
1084    /// connection, protocol, or broker error when no controller bootstrap
1085    /// endpoint can identify and connect to the active controller.
1086    pub async fn connect_controller_with_config(
1087        bootstrap_controllers: &[String],
1088        config: AdminClientConfig,
1089    ) -> Result<Self, AdminError> {
1090        let resolved = config.resolve()?;
1091        Self::connect_with_metadata_recovery_target(
1092            bootstrap_controllers,
1093            resolved.connection,
1094            resolved.retry,
1095            (
1096                resolved.metadata_recovery_strategy,
1097                resolved.metadata_recovery_rebootstrap_trigger,
1098            ),
1099            BootstrapTarget::Controllers,
1100            resolved.enable_metrics_push,
1101        )
1102        .await
1103    }
1104
1105    /// Connects and applies optional client security. `None` means plaintext,
1106    /// which is identical to [`AdminClient::connect`].
1107    ///
1108    /// # Errors
1109    /// Returns [`AdminError::Connect`] if no bootstrap address accepted the
1110    /// (optionally secured) connection. Its `source` holds the last cause.
1111    pub async fn connect_secured(
1112        bootstrap_addrs: &[String],
1113        security: Option<security::ClientSecurity>,
1114    ) -> Result<Self, AdminError> {
1115        Self::connect_with_options(bootstrap_addrs, Self::opts(security)).await
1116    }
1117
1118    /// Connects with the supplied security and DNS deadline, and keeps the
1119    /// standard admin identity, TCP-connect timeout, and request timeout.
1120    ///
1121    /// # Errors
1122    /// Returns [`AdminError::Connect`] with the last cause if no bootstrap
1123    /// address connects.
1124    pub async fn connect_secured_with_dns_timeout(
1125        bootstrap_addrs: &[String],
1126        security: Option<security::ClientSecurity>,
1127        dns_timeout: krabka_client_core::ClientDnsTimeout,
1128    ) -> Result<Self, AdminError> {
1129        let mut options = Self::opts(security);
1130        options.dns_timeout = dns_timeout;
1131        Self::connect_with_options(bootstrap_addrs, options).await
1132    }
1133
1134    /// Connects with the standard plaintext admin policy and a custom DNS
1135    /// deadline.
1136    ///
1137    /// # Errors
1138    /// Returns [`AdminError::Connect`] with the last cause if no bootstrap
1139    /// address connects.
1140    pub async fn connect_with_dns_timeout(
1141        bootstrap_addrs: &[String],
1142        dns_timeout: krabka_client_core::ClientDnsTimeout,
1143    ) -> Result<Self, AdminError> {
1144        Self::connect_secured_with_dns_timeout(bootstrap_addrs, None, dns_timeout).await
1145    }
1146
1147    /// Connects with a complete connection-options template.
1148    ///
1149    /// # Errors
1150    /// Returns [`AdminError::Connect`] with the last cause if no bootstrap
1151    /// address accepted the connection.
1152    pub async fn connect_with_options(
1153        bootstrap_addrs: &[String],
1154        options: ConnectionOptions,
1155    ) -> Result<Self, AdminError> {
1156        let retry = config::retry_for_connection_options(&options);
1157        Self::connect_with_metadata_recovery_target(
1158            bootstrap_addrs,
1159            options,
1160            retry,
1161            (
1162                MetadataRecoveryStrategy::default(),
1163                krabka_client_core::DEFAULT_METADATA_RECOVERY_REBOOTSTRAP_TRIGGER,
1164            ),
1165            BootstrapTarget::Brokers,
1166            DEFAULT_ENABLE_METRICS_PUSH,
1167        )
1168        .await
1169    }
1170
1171    /// Connects through KIP-919 controller bootstrap addresses rather than
1172    /// broker bootstrap addresses.
1173    ///
1174    /// # Errors
1175    /// Returns a connection, protocol, or broker error when no controller
1176    /// bootstrap endpoint can identify and connect to the active controller.
1177    pub async fn connect_controller(bootstrap_controllers: &[String]) -> Result<Self, AdminError> {
1178        Self::connect_controller_secured(bootstrap_controllers, None).await
1179    }
1180
1181    /// Controller-bootstrap variant of [`Self::connect_secured`].
1182    ///
1183    /// # Errors
1184    /// Returns a connection, protocol, or broker error when no controller
1185    /// bootstrap endpoint can identify and connect to the active controller.
1186    pub async fn connect_controller_secured(
1187        bootstrap_controllers: &[String],
1188        security: Option<security::ClientSecurity>,
1189    ) -> Result<Self, AdminError> {
1190        Self::connect_controller_with_options(bootstrap_controllers, Self::opts(security)).await
1191    }
1192
1193    /// Controller-bootstrap variant of [`Self::connect_with_options`].
1194    ///
1195    /// # Errors
1196    /// Returns a connection, protocol, or broker error when no controller
1197    /// bootstrap endpoint can identify and connect to the active controller.
1198    pub async fn connect_controller_with_options(
1199        bootstrap_controllers: &[String],
1200        options: ConnectionOptions,
1201    ) -> Result<Self, AdminError> {
1202        let retry = config::retry_for_connection_options(&options);
1203        Self::connect_with_metadata_recovery_target(
1204            bootstrap_controllers,
1205            options,
1206            retry,
1207            (
1208                MetadataRecoveryStrategy::default(),
1209                krabka_client_core::DEFAULT_METADATA_RECOVERY_REBOOTSTRAP_TRIGGER,
1210            ),
1211            BootstrapTarget::Controllers,
1212            DEFAULT_ENABLE_METRICS_PUSH,
1213        )
1214        .await
1215    }
1216
1217    /// Connect with explicit KIP-1102 metadata recovery settings.
1218    ///
1219    /// # Errors
1220    /// Returns an invalid-configuration error for a negative or fractional
1221    /// millisecond trigger, or a connection error when no bootstrap endpoint
1222    /// is reachable.
1223    pub async fn connect_with_metadata_recovery(
1224        bootstrap_addrs: &[String],
1225        options: ConnectionOptions,
1226        strategy: MetadataRecoveryStrategy,
1227        rebootstrap_trigger: Time,
1228    ) -> Result<Self, AdminError> {
1229        let retry = config::retry_for_connection_options(&options);
1230        Self::connect_with_metadata_recovery_target(
1231            bootstrap_addrs,
1232            options,
1233            retry,
1234            (strategy, rebootstrap_trigger),
1235            BootstrapTarget::Brokers,
1236            DEFAULT_ENABLE_METRICS_PUSH,
1237        )
1238        .await
1239    }
1240
1241    async fn connect_with_metadata_recovery_target(
1242        bootstrap_addrs: &[String],
1243        mut options: ConnectionOptions,
1244        retry: retry::RetryPolicy,
1245        (strategy, rebootstrap_trigger): (MetadataRecoveryStrategy, Time),
1246        target: BootstrapTarget,
1247        enable_metrics_push: bool,
1248    ) -> Result<Self, AdminError> {
1249        let trigger = MetadataRecoveryRebootstrapTrigger::new(rebootstrap_trigger)
1250            .map_err(AdminError::Protocol)?;
1251        // Kafka's `CommonClientConfigs.telemetryReporter`: a reporter only
1252        // with `enable.metrics.push`. Every connection of the client counts
1253        // in its network metrics.
1254        let metrics = enable_metrics_push.then(ClientMetrics::new);
1255        options.network_metrics = metrics.as_ref().map(|metrics| {
1256            NetworkMetrics::register(metrics, TelemetryClientType::Admin.metric_group())
1257        });
1258        let mut last_error = None;
1259        for host_port in bootstrap_addrs {
1260            match Self::connect_target_one_with_discovery(host_port, options.clone(), target).await
1261            {
1262                Ok(connected) => {
1263                    let known_addrs = if connected.discovered_addrs.is_empty() {
1264                        bootstrap_addrs.to_vec()
1265                    } else {
1266                        connected.discovered_addrs
1267                    };
1268                    let conn = Arc::new(RecoveringConnection::new(
1269                        connected.connection,
1270                        bootstrap_addrs.to_vec(),
1271                        options.clone(),
1272                        strategy,
1273                        trigger,
1274                        target,
1275                        known_addrs,
1276                    ));
1277                    let telemetry = metrics.map(|metrics| {
1278                        ClientTelemetry::start(
1279                            telemetry::AdminTelemetryConnection(Arc::clone(&conn)),
1280                            &ClientTelemetryConfig::admin(),
1281                            metrics,
1282                            TelemetryTiming {
1283                                request_timeout: options.request_timeout.to_std(),
1284                                reconnect_backoff: options.reconnect_backoff.to_std(),
1285                            },
1286                        )
1287                    });
1288                    return Ok(Self {
1289                        conn,
1290                        bootstrap_addrs: bootstrap_addrs.to_vec(),
1291                        options,
1292                        retry,
1293                        telemetry,
1294                    });
1295                }
1296                Err(e) if e.is_authentication_failure() => return Err(e),
1297                Err(e) => {
1298                    tracing::debug!(
1299                        target: "krabka_client_admin",
1300                        addr = %host_port,
1301                        error = %e,
1302                        "bootstrap connect failed",
1303                    );
1304                    last_error = Some(e);
1305                }
1306            }
1307        }
1308        match (target, last_error) {
1309            (BootstrapTarget::Controllers, Some(error)) => Err(error),
1310            (_, last_error) => Err(AdminError::Connect {
1311                tried: bootstrap_addrs.len(),
1312                source: last_error.map(Box::new),
1313            }),
1314        }
1315    }
1316
1317    /// Tries each bootstrap address in order.
1318    ///
1319    /// Each entry is `host:port`, which
1320    /// [`krabka_client_core::transport::resolve`] resolves.
1321    /// The first successful connect wins. Returns
1322    /// [`AdminError::Connect`] with the last cause if none responded. The connection is
1323    /// plaintext. See [`AdminClient::connect_secured`].
1324    ///
1325    /// # Errors
1326    /// Returns an error when configuration is invalid, protocol encoding fails, the broker rejects the request, or transport I/O fails.
1327    pub async fn connect(bootstrap_addrs: &[String]) -> Result<Self, AdminError> {
1328        Self::connect_secured(bootstrap_addrs, None).await
1329    }
1330
1331    async fn connect_one(
1332        host_port: &str,
1333        mut opts: ConnectionOptions,
1334    ) -> Result<Connection, AdminError> {
1335        if let Some(security) = opts.security.as_mut() {
1336            **security = security.for_target_host(connection_target_host(host_port));
1337        }
1338        let addr = lookup_first(host_port, opts.dns_timeout, transport::resolve(host_port)).await?;
1339        Connection::connect_with_options(addr, opts)
1340            .await
1341            .map_err(AdminError::from)
1342    }
1343
1344    #[cfg(test)]
1345    async fn connect_target_one(
1346        host_port: &str,
1347        options: ConnectionOptions,
1348        target: BootstrapTarget,
1349    ) -> Result<Connection, AdminError> {
1350        Self::connect_target_one_with_discovery(host_port, options, target)
1351            .await
1352            .map(|connected| connected.connection)
1353    }
1354
1355    async fn connect_target_one_with_discovery(
1356        host_port: &str,
1357        options: ConnectionOptions,
1358        target: BootstrapTarget,
1359    ) -> Result<ConnectedTarget, AdminError> {
1360        match target {
1361            BootstrapTarget::Brokers => Ok(ConnectedTarget {
1362                connection: Self::connect_one(host_port, options).await?,
1363                discovered_addrs: Vec::new(),
1364            }),
1365            BootstrapTarget::Controllers => {
1366                Self::connect_controller_one_with_discovery(host_port, options).await
1367            }
1368        }
1369    }
1370
1371    async fn connect_controller_one_with_discovery(
1372        host_port: &str,
1373        options: ConnectionOptions,
1374    ) -> Result<ConnectedTarget, AdminError> {
1375        use krabka_protocol::owned::describe_cluster_request::DescribeClusterRequest;
1376
1377        const ENDPOINT_TYPE_CONTROLLERS: i8 = 2;
1378        let bootstrap = Self::connect_one(host_port, options.clone()).await?;
1379        let response = send_connection_at_least(
1380            &bootstrap,
1381            DescribeClusterRequest {
1382                endpoint_type: ENDPOINT_TYPE_CONTROLLERS,
1383                ..Default::default()
1384            },
1385            1,
1386        )
1387        .await?;
1388        if response.error_code != 0 {
1389            return Err(AdminError::Broker {
1390                api: "DescribeCluster",
1391                code: response.error_code,
1392                name: kafka_error_name(response.error_code),
1393                message: response.error_message,
1394            });
1395        }
1396        if response.endpoint_type != ENDPOINT_TYPE_CONTROLLERS {
1397            return Err(AdminError::Protocol(format!(
1398                "DescribeCluster returned endpoint_type={}, expected CONTROLLERS",
1399                response.endpoint_type
1400            )));
1401        }
1402        let discovered_addrs = response
1403            .brokers
1404            .iter()
1405            .filter(|controller| !controller.host.is_empty() && controller.port > 0)
1406            .map(|controller| format_host_port(&controller.host, controller.port))
1407            .collect::<Vec<_>>();
1408        let controller = response
1409            .brokers
1410            .into_iter()
1411            .find(|controller| controller.broker_id == response.controller_id)
1412            .ok_or_else(|| {
1413                AdminError::Protocol(format!(
1414                    "DescribeCluster omitted controller_id={} from controller endpoints",
1415                    response.controller_id
1416                ))
1417            })?;
1418        if controller.host.is_empty() || controller.port <= 0 {
1419            return Err(AdminError::Protocol(format!(
1420                "DescribeCluster returned invalid controller endpoint {}:{}",
1421                controller.host, controller.port
1422            )));
1423        }
1424        let endpoint = format_host_port(&controller.host, controller.port);
1425        Ok(ConnectedTarget {
1426            connection: Self::connect_one(&endpoint, options).await?,
1427            discovered_addrs,
1428        })
1429    }
1430
1431    /// Replaces the underlying connection. The `NOT_CONTROLLER` retry path
1432    /// uses it internally to reconnect to the current controller.
1433    pub(crate) async fn reconnect(&mut self, host_port: &str) -> Result<(), AdminError> {
1434        let opts = self.options.clone();
1435        self.conn
1436            .replace(Self::connect_one(host_port, opts).await?)
1437            .await;
1438        Ok(())
1439    }
1440
1441    #[cfg(test)]
1442    pub(crate) async fn reconnect_bootstrap(&mut self) -> Result<(), AdminError> {
1443        let opts = self.options.clone();
1444        let mut last_error = None;
1445        for host_port in &self.bootstrap_addrs {
1446            match Self::connect_target_one(host_port, opts.clone(), self.conn.target).await {
1447                Ok(conn) => {
1448                    self.conn.replace(conn).await;
1449                    return Ok(());
1450                }
1451                Err(error) if error.is_authentication_failure() => return Err(error),
1452                Err(error) => {
1453                    tracing::debug!(
1454                        target: "krabka_client_admin",
1455                        addr = %host_port,
1456                        error = %error,
1457                        "bootstrap reconnect failed",
1458                    );
1459                    last_error = Some(Box::new(error));
1460                }
1461            }
1462        }
1463        Err(AdminError::Connect {
1464            tried: self.bootstrap_addrs.len(),
1465            source: last_error,
1466        })
1467    }
1468
1469    pub(crate) fn is_retriable_transport_error(error: &ClientError) -> bool {
1470        matches!(
1471            error,
1472            ClientError::Timeout(_) | ClientError::Disconnected | ClientError::Io(_)
1473        )
1474    }
1475}
1476
1477/// Kafka error code: the broker is not the controller (KIP-129). The
1478/// admin client refreshes its controller endpoint and retries until the call
1479/// deadline.
1480pub(crate) const NOT_CONTROLLER: i16 = 41;
1481
1482/// Maps a Kafka error code to the name of its `Errors` constant, for
1483/// human-friendly `AdminError::Broker` output.
1484///
1485/// The table holds every code of Apache Kafka's
1486/// `org.apache.kafka.common.protocol.Errors` enum at apache/kafka@3eb0b8c.
1487/// A code that Kafka does not define gives `"UNKNOWN"`.
1488pub(crate) fn kafka_error_name(code: i16) -> &'static str {
1489    match code {
1490        -1 => "UNKNOWN_SERVER_ERROR",
1491        0 => "NONE",
1492        1 => "OFFSET_OUT_OF_RANGE",
1493        2 => "CORRUPT_MESSAGE",
1494        3 => "UNKNOWN_TOPIC_OR_PARTITION",
1495        4 => "INVALID_FETCH_SIZE",
1496        5 => "LEADER_NOT_AVAILABLE",
1497        6 => "NOT_LEADER_OR_FOLLOWER",
1498        7 => "REQUEST_TIMED_OUT",
1499        8 => "BROKER_NOT_AVAILABLE",
1500        9 => "REPLICA_NOT_AVAILABLE",
1501        10 => "MESSAGE_TOO_LARGE",
1502        11 => "STALE_CONTROLLER_EPOCH",
1503        12 => "OFFSET_METADATA_TOO_LARGE",
1504        13 => "NETWORK_EXCEPTION",
1505        14 => "COORDINATOR_LOAD_IN_PROGRESS",
1506        15 => "COORDINATOR_NOT_AVAILABLE",
1507        16 => "NOT_COORDINATOR",
1508        17 => "INVALID_TOPIC_EXCEPTION",
1509        18 => "RECORD_LIST_TOO_LARGE",
1510        19 => "NOT_ENOUGH_REPLICAS",
1511        20 => "NOT_ENOUGH_REPLICAS_AFTER_APPEND",
1512        21 => "INVALID_REQUIRED_ACKS",
1513        22 => "ILLEGAL_GENERATION",
1514        23 => "INCONSISTENT_GROUP_PROTOCOL",
1515        24 => "INVALID_GROUP_ID",
1516        25 => "UNKNOWN_MEMBER_ID",
1517        26 => "INVALID_SESSION_TIMEOUT",
1518        27 => "REBALANCE_IN_PROGRESS",
1519        28 => "INVALID_COMMIT_OFFSET_SIZE",
1520        29 => "TOPIC_AUTHORIZATION_FAILED",
1521        30 => "GROUP_AUTHORIZATION_FAILED",
1522        31 => "CLUSTER_AUTHORIZATION_FAILED",
1523        32 => "INVALID_TIMESTAMP",
1524        33 => "UNSUPPORTED_SASL_MECHANISM",
1525        34 => "ILLEGAL_SASL_STATE",
1526        35 => "UNSUPPORTED_VERSION",
1527        36 => "TOPIC_ALREADY_EXISTS",
1528        37 => "INVALID_PARTITIONS",
1529        38 => "INVALID_REPLICATION_FACTOR",
1530        39 => "INVALID_REPLICA_ASSIGNMENT",
1531        40 => "INVALID_CONFIG",
1532        41 => "NOT_CONTROLLER",
1533        42 => "INVALID_REQUEST",
1534        43 => "UNSUPPORTED_FOR_MESSAGE_FORMAT",
1535        44 => "POLICY_VIOLATION",
1536        45 => "OUT_OF_ORDER_SEQUENCE_NUMBER",
1537        46 => "DUPLICATE_SEQUENCE_NUMBER",
1538        47 => "INVALID_PRODUCER_EPOCH",
1539        48 => "INVALID_TXN_STATE",
1540        49 => "INVALID_PRODUCER_ID_MAPPING",
1541        50 => "INVALID_TRANSACTION_TIMEOUT",
1542        51 => "CONCURRENT_TRANSACTIONS",
1543        52 => "TRANSACTION_COORDINATOR_FENCED",
1544        53 => "TRANSACTIONAL_ID_AUTHORIZATION_FAILED",
1545        54 => "SECURITY_DISABLED",
1546        55 => "OPERATION_NOT_ATTEMPTED",
1547        56 => "KAFKA_STORAGE_ERROR",
1548        57 => "LOG_DIR_NOT_FOUND",
1549        58 => "SASL_AUTHENTICATION_FAILED",
1550        59 => "UNKNOWN_PRODUCER_ID",
1551        60 => "REASSIGNMENT_IN_PROGRESS",
1552        61 => "DELEGATION_TOKEN_AUTH_DISABLED",
1553        62 => "DELEGATION_TOKEN_NOT_FOUND",
1554        63 => "DELEGATION_TOKEN_OWNER_MISMATCH",
1555        64 => "DELEGATION_TOKEN_REQUEST_NOT_ALLOWED",
1556        65 => "DELEGATION_TOKEN_AUTHORIZATION_FAILED",
1557        66 => "DELEGATION_TOKEN_EXPIRED",
1558        67 => "INVALID_PRINCIPAL_TYPE",
1559        68 => "NON_EMPTY_GROUP",
1560        69 => "GROUP_ID_NOT_FOUND",
1561        70 => "FETCH_SESSION_ID_NOT_FOUND",
1562        71 => "INVALID_FETCH_SESSION_EPOCH",
1563        72 => "LISTENER_NOT_FOUND",
1564        73 => "TOPIC_DELETION_DISABLED",
1565        74 => "FENCED_LEADER_EPOCH",
1566        75 => "UNKNOWN_LEADER_EPOCH",
1567        76 => "UNSUPPORTED_COMPRESSION_TYPE",
1568        77 => "STALE_BROKER_EPOCH",
1569        78 => "OFFSET_NOT_AVAILABLE",
1570        79 => "MEMBER_ID_REQUIRED",
1571        80 => "PREFERRED_LEADER_NOT_AVAILABLE",
1572        81 => "GROUP_MAX_SIZE_REACHED",
1573        82 => "FENCED_INSTANCE_ID",
1574        83 => "ELIGIBLE_LEADERS_NOT_AVAILABLE",
1575        84 => "ELECTION_NOT_NEEDED",
1576        85 => "NO_REASSIGNMENT_IN_PROGRESS",
1577        86 => "GROUP_SUBSCRIBED_TO_TOPIC",
1578        87 => "INVALID_RECORD",
1579        88 => "UNSTABLE_OFFSET_COMMIT",
1580        89 => "THROTTLING_QUOTA_EXCEEDED",
1581        90 => "PRODUCER_FENCED",
1582        91 => "RESOURCE_NOT_FOUND",
1583        92 => "DUPLICATE_RESOURCE",
1584        93 => "UNACCEPTABLE_CREDENTIAL",
1585        94 => "INCONSISTENT_VOTER_SET",
1586        95 => "INVALID_UPDATE_VERSION",
1587        96 => "FEATURE_UPDATE_FAILED",
1588        97 => "PRINCIPAL_DESERIALIZATION_FAILURE",
1589        98 => "SNAPSHOT_NOT_FOUND",
1590        99 => "POSITION_OUT_OF_RANGE",
1591        100 => "UNKNOWN_TOPIC_ID",
1592        101 => "DUPLICATE_BROKER_REGISTRATION",
1593        102 => "BROKER_ID_NOT_REGISTERED",
1594        103 => "INCONSISTENT_TOPIC_ID",
1595        104 => "INCONSISTENT_CLUSTER_ID",
1596        105 => "TRANSACTIONAL_ID_NOT_FOUND",
1597        106 => "FETCH_SESSION_TOPIC_ID_ERROR",
1598        107 => "INELIGIBLE_REPLICA",
1599        108 => "NEW_LEADER_ELECTED",
1600        109 => "OFFSET_MOVED_TO_TIERED_STORAGE",
1601        110 => "FENCED_MEMBER_EPOCH",
1602        111 => "UNRELEASED_INSTANCE_ID",
1603        112 => "UNSUPPORTED_ASSIGNOR",
1604        113 => "STALE_MEMBER_EPOCH",
1605        114 => "MISMATCHED_ENDPOINT_TYPE",
1606        115 => "UNSUPPORTED_ENDPOINT_TYPE",
1607        116 => "UNKNOWN_CONTROLLER_ID",
1608        117 => "UNKNOWN_SUBSCRIPTION_ID",
1609        118 => "TELEMETRY_TOO_LARGE",
1610        119 => "INVALID_REGISTRATION",
1611        120 => "TRANSACTION_ABORTABLE",
1612        121 => "INVALID_RECORD_STATE",
1613        122 => "SHARE_SESSION_NOT_FOUND",
1614        123 => "INVALID_SHARE_SESSION_EPOCH",
1615        124 => "FENCED_STATE_EPOCH",
1616        125 => "INVALID_VOTER_KEY",
1617        126 => "DUPLICATE_VOTER",
1618        127 => "VOTER_NOT_FOUND",
1619        128 => "INVALID_REGULAR_EXPRESSION",
1620        129 => "REBOOTSTRAP_REQUIRED",
1621        130 => "STREAMS_INVALID_TOPOLOGY",
1622        131 => "STREAMS_INVALID_TOPOLOGY_EPOCH",
1623        132 => "STREAMS_TOPOLOGY_FENCED",
1624        133 => "SHARE_SESSION_LIMIT_REACHED",
1625        134 => "GROUP_DELETION_FAILED",
1626        135 => "STREAMS_TOPOLOGY_DESCRIPTION_UPDATE_FAILED",
1627        136 => "CONTROLLER_ID_NOT_REGISTERED",
1628        _ => "UNKNOWN",
1629    }
1630}
1631
1632#[cfg(test)]
1633mod tests {
1634    use std::{
1635        sync::{
1636            Arc, Mutex,
1637            atomic::{AtomicU16, AtomicUsize, Ordering},
1638        },
1639        time::Duration,
1640    };
1641
1642    use bytes::{BufMut, BytesMut};
1643    use krabka_protocol::{
1644        Decode, Encode,
1645        owned::{
1646            api_versions_request,
1647            api_versions_response::{ApiVersion, ApiVersionsResponse},
1648            describe_cluster_request::{self, DescribeClusterRequest},
1649            describe_cluster_response::{DescribeClusterBroker, DescribeClusterResponse},
1650            metadata_request,
1651            metadata_response::{
1652                FLEXIBLE_MIN as METADATA_FLEXIBLE_MIN, MetadataResponse, MetadataResponseBroker,
1653            },
1654            sasl_authenticate_request,
1655            sasl_authenticate_response::SaslAuthenticateResponse,
1656            sasl_handshake_request,
1657            sasl_handshake_response::SaslHandshakeResponse,
1658        },
1659    };
1660    use krabka_security::ListenerProtocol;
1661    use krabka_units::secs;
1662    use security::{ClientSecurity, SaslCredentials};
1663    use tokio::{
1664        io::{AsyncReadExt, AsyncWriteExt},
1665        net::TcpListener,
1666    };
1667    use tokio_util::sync::CancellationToken;
1668
1669    use super::*;
1670
1671    struct ObservedAdminBroker {
1672        addr: std::net::SocketAddr,
1673        shutdown: CancellationToken,
1674        connections: Arc<AtomicUsize>,
1675        sasl_handshakes: Arc<AtomicUsize>,
1676        client_ids: Arc<Mutex<Vec<String>>>,
1677    }
1678
1679    impl ObservedAdminBroker {
1680        async fn start(api_versions_delay: Duration) -> Self {
1681            let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
1682            let addr = listener.local_addr().unwrap();
1683            let shutdown = CancellationToken::new();
1684            let connections = Arc::new(AtomicUsize::new(0));
1685            let sasl_handshakes = Arc::new(AtomicUsize::new(0));
1686            let client_ids = Arc::new(Mutex::new(Vec::new()));
1687            let task_shutdown = shutdown.clone();
1688            let task_connections = Arc::clone(&connections);
1689            let task_sasl_handshakes = Arc::clone(&sasl_handshakes);
1690            let task_client_ids = Arc::clone(&client_ids);
1691
1692            tokio::spawn(async move {
1693                loop {
1694                    let Ok((mut stream, _)) = listener.accept().await else {
1695                        break;
1696                    };
1697                    if task_shutdown.is_cancelled() {
1698                        break;
1699                    }
1700                    task_connections.fetch_add(1, Ordering::SeqCst);
1701                    let conn_sasl_handshakes = Arc::clone(&task_sasl_handshakes);
1702                    let conn_client_ids = Arc::clone(&task_client_ids);
1703                    tokio::spawn(async move {
1704                        while let Ok(frame_len) = stream.read_u32().await {
1705                            let mut request = vec![0_u8; frame_len as usize];
1706                            if stream.read_exact(&mut request).await.is_err() || request.len() < 10
1707                            {
1708                                break;
1709                            }
1710                            let api_key = i16::from_be_bytes([request[0], request[1]]);
1711                            let correlation_id =
1712                                i32::from_be_bytes(request[4..8].try_into().unwrap());
1713                            let client_id_len =
1714                                usize::from(u16::from_be_bytes([request[8], request[9]]));
1715                            if request.len() < 10 + client_id_len {
1716                                break;
1717                            }
1718                            conn_client_ids.lock().unwrap().push(
1719                                String::from_utf8_lossy(&request[10..10 + client_id_len]).into(),
1720                            );
1721
1722                            let (body, flexible_header) = match api_key {
1723                                sasl_handshake_request::API_KEY => {
1724                                    conn_sasl_handshakes.fetch_add(1, Ordering::SeqCst);
1725                                    let mut body = BytesMut::new();
1726                                    SaslHandshakeResponse {
1727                                        error_code: 0,
1728                                        ..Default::default()
1729                                    }
1730                                    .encode(&mut body, 1)
1731                                    .unwrap();
1732                                    (body, false)
1733                                }
1734                                sasl_authenticate_request::API_KEY => {
1735                                    let mut body = BytesMut::new();
1736                                    SaslAuthenticateResponse {
1737                                        error_code: 0,
1738                                        ..Default::default()
1739                                    }
1740                                    .encode(&mut body, 2)
1741                                    .unwrap();
1742                                    (body, true)
1743                                }
1744                                api_versions_request::API_KEY => {
1745                                    tokio::time::sleep(api_versions_delay).await;
1746                                    let mut body = BytesMut::new();
1747                                    ApiVersionsResponse {
1748                                        error_code: 0,
1749                                        api_keys: vec![
1750                                            ApiVersion {
1751                                                api_key: api_versions_request::API_KEY,
1752                                                min_version: 0,
1753                                                max_version: 3,
1754                                                ..Default::default()
1755                                            },
1756                                            ApiVersion {
1757                                                api_key: metadata_request::API_KEY,
1758                                                min_version: 0,
1759                                                max_version: 12,
1760                                                ..Default::default()
1761                                            },
1762                                            ApiVersion {
1763                                                api_key: sasl_handshake_request::API_KEY,
1764                                                min_version: 0,
1765                                                max_version: 1,
1766                                                ..Default::default()
1767                                            },
1768                                            ApiVersion {
1769                                                api_key: sasl_authenticate_request::API_KEY,
1770                                                min_version: 0,
1771                                                max_version: 2,
1772                                                ..Default::default()
1773                                            },
1774                                        ],
1775                                        ..Default::default()
1776                                    }
1777                                    .encode(&mut body, 0)
1778                                    .unwrap();
1779                                    (body, false)
1780                                }
1781                                _ => continue,
1782                            };
1783                            let mut response = BytesMut::new();
1784                            response.put_i32(correlation_id);
1785                            if flexible_header {
1786                                response.put_u8(0);
1787                            }
1788                            response.extend_from_slice(&body);
1789                            if stream
1790                                .write_u32(u32::try_from(response.len()).unwrap())
1791                                .await
1792                                .is_err()
1793                                || stream.write_all(&response).await.is_err()
1794                            {
1795                                break;
1796                            }
1797                        }
1798                    });
1799                }
1800            });
1801
1802            Self {
1803                addr,
1804                shutdown,
1805                connections,
1806                sasl_handshakes,
1807                client_ids,
1808            }
1809        }
1810
1811        fn observed_custom_security_and_id(&self) -> bool {
1812            self.sasl_handshakes.load(Ordering::SeqCst) > 0
1813                && self
1814                    .client_ids
1815                    .lock()
1816                    .unwrap()
1817                    .iter()
1818                    .any(|client_id| client_id == "custom-admin")
1819        }
1820
1821        fn stop(self) {
1822            self.shutdown.cancel();
1823        }
1824    }
1825
1826    struct ObservedController {
1827        addr: std::net::SocketAddr,
1828        connections: Arc<AtomicUsize>,
1829        endpoint_types: Arc<Mutex<Vec<i8>>>,
1830    }
1831
1832    impl ObservedController {
1833        async fn start(describe_cluster_max_version: i16) -> Self {
1834            let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
1835            let addr = listener.local_addr().unwrap();
1836            let connections = Arc::new(AtomicUsize::new(0));
1837            let endpoint_types = Arc::new(Mutex::new(Vec::new()));
1838            let task_connections = Arc::clone(&connections);
1839            let task_endpoint_types = Arc::clone(&endpoint_types);
1840
1841            tokio::spawn(async move {
1842                while let Ok((mut stream, _)) = listener.accept().await {
1843                    task_connections.fetch_add(1, Ordering::SeqCst);
1844                    let endpoint_types = Arc::clone(&task_endpoint_types);
1845                    tokio::spawn(async move {
1846                        while let Ok(frame_len) = stream.read_u32().await {
1847                            let mut request = vec![0_u8; frame_len as usize];
1848                            if stream.read_exact(&mut request).await.is_err() || request.len() < 10
1849                            {
1850                                break;
1851                            }
1852                            let api_key = i16::from_be_bytes([request[0], request[1]]);
1853                            let api_version = i16::from_be_bytes([request[2], request[3]]);
1854                            let correlation_id =
1855                                i32::from_be_bytes(request[4..8].try_into().unwrap());
1856                            let client_id_len =
1857                                usize::from(u16::from_be_bytes([request[8], request[9]]));
1858                            let header_len = 10 + client_id_len;
1859                            if request.len() < header_len {
1860                                break;
1861                            }
1862
1863                            let (body, flexible_header) = match api_key {
1864                                api_versions_request::API_KEY => {
1865                                    let mut body = BytesMut::new();
1866                                    ApiVersionsResponse {
1867                                        api_keys: vec![
1868                                            ApiVersion {
1869                                                api_key: api_versions_request::API_KEY,
1870                                                min_version: 0,
1871                                                max_version: 4,
1872                                                ..Default::default()
1873                                            },
1874                                            ApiVersion {
1875                                                api_key: describe_cluster_request::API_KEY,
1876                                                min_version: 0,
1877                                                max_version: describe_cluster_max_version,
1878                                                ..Default::default()
1879                                            },
1880                                        ],
1881                                        ..Default::default()
1882                                    }
1883                                    .encode(&mut body, 0)
1884                                    .unwrap();
1885                                    (body, false)
1886                                }
1887                                describe_cluster_request::API_KEY => {
1888                                    let mut encoded = &request[header_len + 1..];
1889                                    let decoded =
1890                                        DescribeClusterRequest::decode(&mut encoded, api_version)
1891                                            .unwrap();
1892                                    endpoint_types.lock().unwrap().push(decoded.endpoint_type);
1893                                    let mut body = BytesMut::new();
1894                                    DescribeClusterResponse {
1895                                        endpoint_type: 2,
1896                                        cluster_id: "controller-test".into(),
1897                                        controller_id: 1,
1898                                        brokers: vec![DescribeClusterBroker {
1899                                            broker_id: 1,
1900                                            host: addr.ip().to_string(),
1901                                            port: i32::from(addr.port()),
1902                                            ..Default::default()
1903                                        }],
1904                                        ..Default::default()
1905                                    }
1906                                    .encode(&mut body, api_version)
1907                                    .unwrap();
1908                                    (body, true)
1909                                }
1910                                _ => continue,
1911                            };
1912                            let mut response = BytesMut::new();
1913                            response.put_i32(correlation_id);
1914                            if flexible_header {
1915                                response.put_u8(0);
1916                            }
1917                            response.extend_from_slice(&body);
1918                            if stream
1919                                .write_u32(u32::try_from(response.len()).unwrap())
1920                                .await
1921                                .is_err()
1922                                || stream.write_all(&response).await.is_err()
1923                            {
1924                                break;
1925                            }
1926                        }
1927                    });
1928                }
1929            });
1930
1931            Self {
1932                addr,
1933                connections,
1934                endpoint_types,
1935            }
1936        }
1937    }
1938
1939    fn custom_admin_options() -> ConnectionOptions {
1940        ConnectionOptions {
1941            dns_timeout: ClientDnsTimeout::default(),
1942            client_id: "custom-admin".into(),
1943            socket_connection_setup_timeout: krabka_units::millis(100),
1944            request_timeout: krabka_units::millis(150),
1945            dispatch_queue_capacity: krabka_client_core::ConnectionDispatchQueueCapacity::new(7)
1946                .unwrap(),
1947            frame_max: krabka_client_core::ClientFrameMax::try_from(krabka_units::kibibytes(32))
1948                .unwrap(),
1949            security: Some(Box::new(ClientSecurity {
1950                protocol: ListenerProtocol::SaslPlaintext,
1951                tls: None,
1952                sasl: Some(SaslCredentials::Plain {
1953                    username: "u".into(),
1954                    password: "p".into(),
1955                }),
1956                sasl_host: Some("broker.example".into()),
1957            })),
1958            ..ConnectionOptions::default()
1959        }
1960    }
1961
1962    async fn metadata_times_out_with_custom_request_timeout(admin: &mut AdminClient) {
1963        let result = tokio::time::timeout(Duration::from_secs(2), admin.metadata(&[]))
1964            .await
1965            .expect("custom request timeout fires");
1966        assert2::assert!(result.is_err());
1967    }
1968
1969    fn assert_custom_connect_timeout_is_stored(admin: &AdminClient) {
1970        assert2::assert!(
1971            admin.options.socket_connection_setup_timeout == krabka_units::millis(100)
1972        );
1973        assert2::assert!(admin.options.dispatch_queue_capacity.get() == 7);
1974        assert2::assert!(admin.options.frame_max.size() == krabka_units::kibibytes(32));
1975    }
1976
1977    fn metadata_mock_response(version: i16, broker_id: i32, port: u16) -> Vec<u8> {
1978        let response = MetadataResponse {
1979            brokers: vec![MetadataResponseBroker {
1980                node_id: broker_id,
1981                host: "127.0.0.1".into(),
1982                port: i32::from(port),
1983                ..Default::default()
1984            }],
1985            ..Default::default()
1986        };
1987        let mut bytes = BytesMut::new();
1988        if version >= METADATA_FLEXIBLE_MIN {
1989            bytes.put_u8(0);
1990        }
1991        response.encode(&mut bytes, version).unwrap();
1992        bytes.to_vec()
1993    }
1994
1995    fn admin_mock_api_versions() -> Vec<u8> {
1996        let response = ApiVersionsResponse {
1997            api_keys: vec![
1998                ApiVersion {
1999                    api_key: api_versions_request::API_KEY,
2000                    min_version: 0,
2001                    max_version: 3,
2002                    ..Default::default()
2003                },
2004                ApiVersion {
2005                    api_key: metadata_request::API_KEY,
2006                    min_version: 0,
2007                    max_version: 13,
2008                    ..Default::default()
2009                },
2010            ],
2011            ..Default::default()
2012        };
2013        let mut bytes = BytesMut::new();
2014        response.encode(&mut bytes, 0).unwrap();
2015        bytes.to_vec()
2016    }
2017
2018    fn admin_mock_api_versions_with_describe_cluster(max_version: i16) -> Vec<u8> {
2019        let response = ApiVersionsResponse {
2020            api_keys: vec![
2021                ApiVersion {
2022                    api_key: api_versions_request::API_KEY,
2023                    min_version: 0,
2024                    max_version: 3,
2025                    ..Default::default()
2026                },
2027                ApiVersion {
2028                    api_key: describe_cluster_request::API_KEY,
2029                    min_version: 0,
2030                    max_version,
2031                    ..Default::default()
2032                },
2033            ],
2034            ..Default::default()
2035        };
2036        let mut bytes = BytesMut::new();
2037        response.encode(&mut bytes, 0).unwrap();
2038        bytes.to_vec()
2039    }
2040
2041    async fn wait_for_admin_mock_closed(addr: std::net::SocketAddr) {
2042        tokio::time::timeout(Duration::from_secs(10), async {
2043            while tokio::net::TcpStream::connect(addr).await.is_ok() {
2044                tokio::task::yield_now().await;
2045            }
2046        })
2047        .await
2048        .expect("mock broker listener closes");
2049    }
2050
2051    #[test]
2052    fn error_names_match_the_codes_that_apache_kafka_defines() {
2053        // Every constant of Apache Kafka's `Errors` enum at
2054        // apache/kafka@3eb0b8c, in code order, as `Errors.values()` prints
2055        // `code()` and `name()`. The list is exhaustive on purpose: a sampled
2056        // table lets a deleted arm pass unnoticed, and a wrong name sends an
2057        // operator to the wrong cause.
2058        let cases: [(i16, &str); 138] = [
2059            (-1, "UNKNOWN_SERVER_ERROR"),
2060            (0, "NONE"),
2061            (1, "OFFSET_OUT_OF_RANGE"),
2062            (2, "CORRUPT_MESSAGE"),
2063            (3, "UNKNOWN_TOPIC_OR_PARTITION"),
2064            (4, "INVALID_FETCH_SIZE"),
2065            (5, "LEADER_NOT_AVAILABLE"),
2066            (6, "NOT_LEADER_OR_FOLLOWER"),
2067            (7, "REQUEST_TIMED_OUT"),
2068            (8, "BROKER_NOT_AVAILABLE"),
2069            (9, "REPLICA_NOT_AVAILABLE"),
2070            (10, "MESSAGE_TOO_LARGE"),
2071            (11, "STALE_CONTROLLER_EPOCH"),
2072            (12, "OFFSET_METADATA_TOO_LARGE"),
2073            (13, "NETWORK_EXCEPTION"),
2074            (14, "COORDINATOR_LOAD_IN_PROGRESS"),
2075            (15, "COORDINATOR_NOT_AVAILABLE"),
2076            (16, "NOT_COORDINATOR"),
2077            (17, "INVALID_TOPIC_EXCEPTION"),
2078            (18, "RECORD_LIST_TOO_LARGE"),
2079            (19, "NOT_ENOUGH_REPLICAS"),
2080            (20, "NOT_ENOUGH_REPLICAS_AFTER_APPEND"),
2081            (21, "INVALID_REQUIRED_ACKS"),
2082            (22, "ILLEGAL_GENERATION"),
2083            (23, "INCONSISTENT_GROUP_PROTOCOL"),
2084            (24, "INVALID_GROUP_ID"),
2085            (25, "UNKNOWN_MEMBER_ID"),
2086            (26, "INVALID_SESSION_TIMEOUT"),
2087            (27, "REBALANCE_IN_PROGRESS"),
2088            (28, "INVALID_COMMIT_OFFSET_SIZE"),
2089            (29, "TOPIC_AUTHORIZATION_FAILED"),
2090            (30, "GROUP_AUTHORIZATION_FAILED"),
2091            (31, "CLUSTER_AUTHORIZATION_FAILED"),
2092            (32, "INVALID_TIMESTAMP"),
2093            (33, "UNSUPPORTED_SASL_MECHANISM"),
2094            (34, "ILLEGAL_SASL_STATE"),
2095            (35, "UNSUPPORTED_VERSION"),
2096            (36, "TOPIC_ALREADY_EXISTS"),
2097            (37, "INVALID_PARTITIONS"),
2098            (38, "INVALID_REPLICATION_FACTOR"),
2099            (39, "INVALID_REPLICA_ASSIGNMENT"),
2100            (40, "INVALID_CONFIG"),
2101            (41, "NOT_CONTROLLER"),
2102            (42, "INVALID_REQUEST"),
2103            (43, "UNSUPPORTED_FOR_MESSAGE_FORMAT"),
2104            (44, "POLICY_VIOLATION"),
2105            (45, "OUT_OF_ORDER_SEQUENCE_NUMBER"),
2106            (46, "DUPLICATE_SEQUENCE_NUMBER"),
2107            (47, "INVALID_PRODUCER_EPOCH"),
2108            (48, "INVALID_TXN_STATE"),
2109            (49, "INVALID_PRODUCER_ID_MAPPING"),
2110            (50, "INVALID_TRANSACTION_TIMEOUT"),
2111            (51, "CONCURRENT_TRANSACTIONS"),
2112            (52, "TRANSACTION_COORDINATOR_FENCED"),
2113            (53, "TRANSACTIONAL_ID_AUTHORIZATION_FAILED"),
2114            (54, "SECURITY_DISABLED"),
2115            (55, "OPERATION_NOT_ATTEMPTED"),
2116            (56, "KAFKA_STORAGE_ERROR"),
2117            (57, "LOG_DIR_NOT_FOUND"),
2118            (58, "SASL_AUTHENTICATION_FAILED"),
2119            (59, "UNKNOWN_PRODUCER_ID"),
2120            (60, "REASSIGNMENT_IN_PROGRESS"),
2121            (61, "DELEGATION_TOKEN_AUTH_DISABLED"),
2122            (62, "DELEGATION_TOKEN_NOT_FOUND"),
2123            (63, "DELEGATION_TOKEN_OWNER_MISMATCH"),
2124            (64, "DELEGATION_TOKEN_REQUEST_NOT_ALLOWED"),
2125            (65, "DELEGATION_TOKEN_AUTHORIZATION_FAILED"),
2126            (66, "DELEGATION_TOKEN_EXPIRED"),
2127            (67, "INVALID_PRINCIPAL_TYPE"),
2128            (68, "NON_EMPTY_GROUP"),
2129            (69, "GROUP_ID_NOT_FOUND"),
2130            (70, "FETCH_SESSION_ID_NOT_FOUND"),
2131            (71, "INVALID_FETCH_SESSION_EPOCH"),
2132            (72, "LISTENER_NOT_FOUND"),
2133            (73, "TOPIC_DELETION_DISABLED"),
2134            (74, "FENCED_LEADER_EPOCH"),
2135            (75, "UNKNOWN_LEADER_EPOCH"),
2136            (76, "UNSUPPORTED_COMPRESSION_TYPE"),
2137            (77, "STALE_BROKER_EPOCH"),
2138            (78, "OFFSET_NOT_AVAILABLE"),
2139            (79, "MEMBER_ID_REQUIRED"),
2140            (80, "PREFERRED_LEADER_NOT_AVAILABLE"),
2141            (81, "GROUP_MAX_SIZE_REACHED"),
2142            (82, "FENCED_INSTANCE_ID"),
2143            (83, "ELIGIBLE_LEADERS_NOT_AVAILABLE"),
2144            (84, "ELECTION_NOT_NEEDED"),
2145            (85, "NO_REASSIGNMENT_IN_PROGRESS"),
2146            (86, "GROUP_SUBSCRIBED_TO_TOPIC"),
2147            (87, "INVALID_RECORD"),
2148            (88, "UNSTABLE_OFFSET_COMMIT"),
2149            (89, "THROTTLING_QUOTA_EXCEEDED"),
2150            (90, "PRODUCER_FENCED"),
2151            (91, "RESOURCE_NOT_FOUND"),
2152            (92, "DUPLICATE_RESOURCE"),
2153            (93, "UNACCEPTABLE_CREDENTIAL"),
2154            (94, "INCONSISTENT_VOTER_SET"),
2155            (95, "INVALID_UPDATE_VERSION"),
2156            (96, "FEATURE_UPDATE_FAILED"),
2157            (97, "PRINCIPAL_DESERIALIZATION_FAILURE"),
2158            (98, "SNAPSHOT_NOT_FOUND"),
2159            (99, "POSITION_OUT_OF_RANGE"),
2160            (100, "UNKNOWN_TOPIC_ID"),
2161            (101, "DUPLICATE_BROKER_REGISTRATION"),
2162            (102, "BROKER_ID_NOT_REGISTERED"),
2163            (103, "INCONSISTENT_TOPIC_ID"),
2164            (104, "INCONSISTENT_CLUSTER_ID"),
2165            (105, "TRANSACTIONAL_ID_NOT_FOUND"),
2166            (106, "FETCH_SESSION_TOPIC_ID_ERROR"),
2167            (107, "INELIGIBLE_REPLICA"),
2168            (108, "NEW_LEADER_ELECTED"),
2169            (109, "OFFSET_MOVED_TO_TIERED_STORAGE"),
2170            (110, "FENCED_MEMBER_EPOCH"),
2171            (111, "UNRELEASED_INSTANCE_ID"),
2172            (112, "UNSUPPORTED_ASSIGNOR"),
2173            (113, "STALE_MEMBER_EPOCH"),
2174            (114, "MISMATCHED_ENDPOINT_TYPE"),
2175            (115, "UNSUPPORTED_ENDPOINT_TYPE"),
2176            (116, "UNKNOWN_CONTROLLER_ID"),
2177            (117, "UNKNOWN_SUBSCRIPTION_ID"),
2178            (118, "TELEMETRY_TOO_LARGE"),
2179            (119, "INVALID_REGISTRATION"),
2180            (120, "TRANSACTION_ABORTABLE"),
2181            (121, "INVALID_RECORD_STATE"),
2182            (122, "SHARE_SESSION_NOT_FOUND"),
2183            (123, "INVALID_SHARE_SESSION_EPOCH"),
2184            (124, "FENCED_STATE_EPOCH"),
2185            (125, "INVALID_VOTER_KEY"),
2186            (126, "DUPLICATE_VOTER"),
2187            (127, "VOTER_NOT_FOUND"),
2188            (128, "INVALID_REGULAR_EXPRESSION"),
2189            (129, "REBOOTSTRAP_REQUIRED"),
2190            (130, "STREAMS_INVALID_TOPOLOGY"),
2191            (131, "STREAMS_INVALID_TOPOLOGY_EPOCH"),
2192            (132, "STREAMS_TOPOLOGY_FENCED"),
2193            (133, "SHARE_SESSION_LIMIT_REACHED"),
2194            (134, "GROUP_DELETION_FAILED"),
2195            (135, "STREAMS_TOPOLOGY_DESCRIPTION_UPDATE_FAILED"),
2196            (136, "CONTROLLER_ID_NOT_REGISTERED"),
2197        ];
2198
2199        let names = cases
2200            .iter()
2201            .map(|(code, _)| (*code, kafka_error_name(*code)))
2202            .collect::<Vec<_>>();
2203        assert2::assert!(names == cases.to_vec());
2204        // Kafka's codes are contiguous from -1, so every code outside the
2205        // table is one Kafka does not define.
2206    }
2207
2208    #[yare::parameterized(
2209        minimum = { i16::MIN },
2210        negative = { -2 },
2211        beyond_table = { 137 },
2212        maximum = { i16::MAX },
2213    )]
2214    fn kafka_error_name_unknown_codes_are_unknown(code: i16) {
2215        assert2::assert!(kafka_error_name(code) == "UNKNOWN", "code {code}");
2216    }
2217
2218    #[yare::parameterized(
2219        success = { 0, "NONE" },
2220        topic_exists = { 36, "TOPIC_ALREADY_EXISTS" },
2221        not_controller = { 41, "NOT_CONTROLLER" },
2222    )]
2223    fn kafka_error_name_known_codes(code: i16, want: &str) {
2224        assert2::assert!(kafka_error_name(code) == want);
2225    }
2226
2227    #[yare::parameterized(
2228        cluster_authorization = { 31, "CLUSTER_AUTHORIZATION_FAILED" },
2229        unsupported_sasl = { 33, "UNSUPPORTED_SASL_MECHANISM" },
2230        unsupported_version = { 35, "UNSUPPORTED_VERSION" },
2231        delegation_token_expired = { 66, "DELEGATION_TOKEN_EXPIRED" },
2232        eligible_leaders_unavailable = { 83, "ELIGIBLE_LEADERS_NOT_AVAILABLE" },
2233        election_unnecessary = { 84, "ELECTION_NOT_NEEDED" },
2234        resource_not_found = { 91, "RESOURCE_NOT_FOUND" },
2235        duplicate_resource = { 92, "DUPLICATE_RESOURCE" },
2236        unacceptable_credential = { 93, "UNACCEPTABLE_CREDENTIAL" },
2237    )]
2238    fn users_kafka_error_name_includes_scram_describe_codes(code: i16, want: &str) {
2239        assert2::assert!(kafka_error_name(code) == want);
2240    }
2241
2242    #[test]
2243    fn users_kafka_error_name_includes_ineligible_replica() {
2244        assert2::assert!(kafka_error_name(107) == "INELIGIBLE_REPLICA");
2245    }
2246
2247    #[test]
2248    fn kafka_error_name_unknown_returns_unknown() {
2249        assert2::assert!(kafka_error_name(9999) == "UNKNOWN");
2250    }
2251
2252    #[test]
2253    fn kafka_error_if_zero_code_is_none() {
2254        assert2::assert!(kafka_error_if(0, None).is_none());
2255    }
2256
2257    #[test]
2258    fn kafka_error_if_nonzero_carries_name() {
2259        let e = kafka_error_if(36, Some("dup".into())).unwrap();
2260        assert2::assert!(
2261            e == KafkaError {
2262                code: 36,
2263                name: "TOPIC_ALREADY_EXISTS",
2264                message: Some("dup".to_string()),
2265            }
2266        );
2267    }
2268
2269    #[tokio::test]
2270    async fn connect_secured_threads_security_and_fails_to_closed_port() {
2271        use krabka_security::ListenerProtocol;
2272        use security::{ClientSecurity, SaslCredentials};
2273
2274        let security = ClientSecurity {
2275            protocol: ListenerProtocol::SaslPlaintext,
2276            tls: None,
2277            sasl: Some(SaslCredentials::Plain {
2278                username: "u".into(),
2279                password: "p".into(),
2280            }),
2281            sasl_host: None,
2282        };
2283        // 127.0.0.1:1 has no listener; the secured connect must fail —
2284        // proving the security arg is threaded (not a type error).
2285        let res = AdminClient::connect_secured(&["127.0.0.1:1".to_string()], Some(security)).await;
2286        assert2::assert!(res.is_err());
2287    }
2288
2289    #[tokio::test(start_paused = true)]
2290    async fn dns_lookup_stops_at_connection_option_deadline() {
2291        let timeout = ClientDnsTimeout::new(Time::from_millis(37)).expect("positive timeout");
2292        let started = tokio::time::Instant::now();
2293        let pending =
2294            std::future::pending::<std::io::Result<std::vec::IntoIter<std::net::SocketAddr>>>();
2295
2296        let result = lookup_first("broker.invalid:9092", timeout, pending).await;
2297
2298        assert2::assert!(result.is_err());
2299        assert2::assert!(started.elapsed() == Duration::from_millis(37));
2300    }
2301
2302    #[tokio::test]
2303    async fn custom_options_are_observable_on_initial_dial() {
2304        let live = ObservedAdminBroker::start(Duration::ZERO).await;
2305        let mut admin =
2306            AdminClient::connect_with_options(&[live.addr.to_string()], custom_admin_options())
2307                .await
2308                .unwrap();
2309
2310        assert2::assert!(live.observed_custom_security_and_id());
2311        assert_custom_connect_timeout_is_stored(&admin);
2312        metadata_times_out_with_custom_request_timeout(&mut admin).await;
2313
2314        let slow = ObservedAdminBroker::start(Duration::from_millis(300)).await;
2315        let result = tokio::time::timeout(
2316            Duration::from_secs(1),
2317            AdminClient::connect_with_options(&[slow.addr.to_string()], custom_admin_options()),
2318        )
2319        .await
2320        .expect("ApiVersions obeys the stored connect timeout");
2321        assert2::assert!(result.is_err());
2322
2323        live.stop();
2324        slow.stop();
2325    }
2326
2327    /// `connect_with_config` and `connect_controller_with_config` take the
2328    /// settings of `AdminClientConfig` onto the connection and the retry
2329    /// policy of the client, and an invalid setting stops the connect.
2330    #[tokio::test]
2331    async fn connect_with_config_carries_the_settings_and_refuses_an_invalid_one() {
2332        let live = ObservedAdminBroker::start(Duration::ZERO).await;
2333        let config = || AdminClientConfig {
2334            client_id: Some("tool-a".to_owned()),
2335            request_timeout: secs(45),
2336            default_api_timeout: Some(secs(90)),
2337            retries: 4,
2338            retry_backoff: Time::from_millis(30),
2339            retry_backoff_max: Time::from_millis(300),
2340            ..AdminClientConfig::default()
2341        };
2342
2343        let admin = AdminClient::connect_with_config(&[live.addr.to_string()], config())
2344            .await
2345            .expect("admin connects");
2346
2347        assert2::assert!(admin.options.client_id == "tool-a");
2348        assert2::assert!(admin.options.request_timeout == secs(45));
2349        assert2::assert!(
2350            admin.retry
2351                == retry::RetryPolicy {
2352                    timeout: Duration::from_secs(90),
2353                    initial_backoff: Duration::from_millis(30),
2354                    max_backoff: Duration::from_millis(300),
2355                    jitter: admin.retry.jitter,
2356                    max_retries: 4,
2357                }
2358        );
2359        live.stop();
2360
2361        let controller = ObservedController::start(2).await;
2362        let on_controller =
2363            AdminClient::connect_controller_with_config(&[controller.addr.to_string()], config())
2364                .await
2365                .expect("controller admin connects");
2366
2367        assert2::assert!(on_controller.conn.uses_controller_bootstrap());
2368        assert2::assert!(on_controller.options.client_id == "tool-a");
2369        assert2::assert!(on_controller.retry.max_retries == 4);
2370
2371        let refused = AdminClient::connect_with_config(
2372            &["127.0.0.1:1".to_owned()],
2373            AdminClientConfig {
2374                request_timeout: secs(90),
2375                default_api_timeout: Some(secs(60)),
2376                ..AdminClientConfig::default()
2377            },
2378        )
2379        .await;
2380
2381        assert2::assert!(matches!(refused, Err(AdminError::InvalidConfig(_))));
2382    }
2383
2384    #[tokio::test]
2385    async fn connect_with_dns_timeout_preserves_admin_defaults() {
2386        let live = ObservedAdminBroker::start(Duration::ZERO).await;
2387        let timeout = ClientDnsTimeout::new(Time::from_millis(37)).expect("positive timeout");
2388        let admin = AdminClient::connect_with_dns_timeout(&[live.addr.to_string()], timeout)
2389            .await
2390            .expect("admin connects");
2391
2392        assert2::assert!(admin.options.dns_timeout == timeout);
2393        assert2::assert!(admin.options.client_id.starts_with("adminclient-"));
2394        assert2::assert!(admin.options.socket_connection_setup_timeout == secs(10));
2395        assert2::assert!(admin.options.request_timeout == secs(30));
2396        live.stop();
2397    }
2398
2399    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
2400    async fn admin_metadata_uses_a_learned_broker_after_the_only_seed_retires() {
2401        let healthy_port = Arc::new(AtomicU16::new(0));
2402        let healthy_calls = Arc::new(AtomicUsize::new(0));
2403        let h_port = healthy_port.clone();
2404        let h_calls = healthy_calls.clone();
2405        let healthy = MockBroker::start(move |api_key, version, _correlation_id, _body| {
2406            if api_key == api_versions_request::API_KEY {
2407                return Some(admin_mock_api_versions());
2408            }
2409            if api_key == metadata_request::API_KEY {
2410                h_calls.fetch_add(1, Ordering::SeqCst);
2411                return Some(metadata_mock_response(
2412                    version,
2413                    7,
2414                    h_port.load(Ordering::SeqCst),
2415                ));
2416            }
2417            None
2418        })
2419        .await;
2420        healthy_port.store(healthy.addr.port(), Ordering::SeqCst);
2421
2422        let advertised_port = healthy_port.clone();
2423        let seed = MockBroker::start(move |api_key, version, _correlation_id, _body| {
2424            if api_key == api_versions_request::API_KEY {
2425                return Some(admin_mock_api_versions());
2426            }
2427            (api_key == metadata_request::API_KEY)
2428                .then(|| metadata_mock_response(version, 7, advertised_port.load(Ordering::SeqCst)))
2429        })
2430        .await;
2431        let admin = AdminClient::connect(&[seed.addr.to_string()])
2432            .await
2433            .expect("admin connects to its seed");
2434        let first = admin
2435            .conn
2436            .send(metadata_request::MetadataRequest::default())
2437            .await
2438            .expect("seed provides last-known broker metadata");
2439        assert2::assert!(first.brokers[0].node_id == 7);
2440
2441        let seed_addr = seed.addr;
2442        seed.stop();
2443        wait_for_admin_mock_closed(seed_addr).await;
2444
2445        let refreshed = admin
2446            .conn
2447            .send(metadata_request::MetadataRequest::default())
2448            .await
2449            .expect("admin refreshes through the learned broker");
2450        assert2::assert!(refreshed.brokers[0].node_id == 7);
2451        assert2::assert!(
2452            healthy_calls.load(Ordering::SeqCst) >= 1,
2453            "recovery must issue metadata through the learned broker"
2454        );
2455    }
2456
2457    #[tokio::test]
2458    async fn recovering_connection_enforces_required_api_version() {
2459        let broker = MockBroker::start(|api_key, _version, _correlation_id, _body| {
2460            (api_key == api_versions_request::API_KEY)
2461                .then(|| admin_mock_api_versions_with_describe_cluster(1))
2462        })
2463        .await;
2464        let admin = AdminClient::connect(&[broker.addr.to_string()])
2465            .await
2466            .expect("admin connects");
2467
2468        let result = admin
2469            .conn
2470            .send_at_least(DescribeClusterRequest::default(), 2)
2471            .await;
2472
2473        assert2::assert!(matches!(
2474            result,
2475            Err(AdminError::Transport(ClientError::IncompatibleVersion {
2476                api_key: describe_cluster_request::API_KEY,
2477                broker_max: 1,
2478                client_min: 2,
2479                ..
2480            }))
2481        ));
2482        broker.stop();
2483    }
2484
2485    #[tokio::test]
2486    async fn controller_bootstrap_discovers_and_connects_active_controller() {
2487        let controller = ObservedController::start(2).await;
2488
2489        let admin = AdminClient::connect_controller(&[controller.addr.to_string()])
2490            .await
2491            .unwrap_or_else(|error| {
2492                panic!(
2493                    "controller bootstrap: {error}; connections={}; endpoint_types={:?}",
2494                    controller.connections.load(Ordering::SeqCst),
2495                    controller.endpoint_types.lock().unwrap(),
2496                )
2497            });
2498
2499        assert2::assert!(admin.conn.uses_controller_bootstrap());
2500        assert2::assert!(controller.connections.load(Ordering::SeqCst) == 2);
2501        assert2::assert!(*controller.endpoint_types.lock().unwrap() == vec![2]);
2502    }
2503
2504    #[tokio::test]
2505    async fn controller_bootstrap_requires_endpoint_type_version() {
2506        let controller = ObservedController::start(0).await;
2507
2508        let result = AdminClient::connect_controller(&[controller.addr.to_string()]).await;
2509
2510        assert2::assert!(matches!(
2511            result,
2512            Err(AdminError::Transport(ClientError::IncompatibleVersion {
2513                api_key: describe_cluster_request::API_KEY,
2514                broker_max: 0,
2515                client_min: 1,
2516                ..
2517            }))
2518        ));
2519        assert2::assert!(controller.endpoint_types.lock().unwrap().is_empty());
2520    }
2521
2522    #[tokio::test]
2523    async fn secured_dns_timeout_preserves_security_and_admin_defaults() {
2524        let live = ObservedAdminBroker::start(Duration::ZERO).await;
2525        let timeout = ClientDnsTimeout::new(Time::from_millis(37)).expect("positive timeout");
2526        let security = ClientSecurity {
2527            protocol: ListenerProtocol::SaslPlaintext,
2528            tls: None,
2529            sasl: Some(SaslCredentials::Plain {
2530                username: "u".into(),
2531                password: "p".into(),
2532            }),
2533            sasl_host: Some("broker.example".into()),
2534        };
2535        let admin = AdminClient::connect_secured_with_dns_timeout(
2536            &[live.addr.to_string()],
2537            Some(security),
2538            timeout,
2539        )
2540        .await
2541        .expect("secured admin connects");
2542
2543        assert2::assert!(admin.options.dns_timeout == timeout);
2544        assert2::assert!(admin.options.security.is_some());
2545        assert2::assert!(admin.options.client_id.starts_with("adminclient-"));
2546        assert2::assert!(admin.options.socket_connection_setup_timeout == secs(10));
2547        assert2::assert!(admin.options.request_timeout == secs(30));
2548        live.stop();
2549    }
2550
2551    #[tokio::test]
2552    async fn custom_options_are_observable_on_controller_reconnect() {
2553        let bootstrap = ObservedAdminBroker::start(Duration::ZERO).await;
2554        let controller = ObservedAdminBroker::start(Duration::ZERO).await;
2555        let slow = ObservedAdminBroker::start(Duration::from_millis(300)).await;
2556        let mut admin = AdminClient::connect_with_options(
2557            &[bootstrap.addr.to_string()],
2558            custom_admin_options(),
2559        )
2560        .await
2561        .unwrap();
2562
2563        admin.reconnect(&controller.addr.to_string()).await.unwrap();
2564        assert2::assert!(controller.observed_custom_security_and_id());
2565        assert_custom_connect_timeout_is_stored(&admin);
2566        metadata_times_out_with_custom_request_timeout(&mut admin).await;
2567        let result = tokio::time::timeout(
2568            Duration::from_secs(1),
2569            admin.reconnect(&slow.addr.to_string()),
2570        )
2571        .await
2572        .expect("reconnected ApiVersions obeys the stored request timeout");
2573        assert2::assert!(result.is_err());
2574
2575        bootstrap.stop();
2576        controller.stop();
2577        slow.stop();
2578    }
2579
2580    #[tokio::test]
2581    async fn custom_options_are_observable_on_bootstrap_reconnect() {
2582        let slow = ObservedAdminBroker::start(Duration::from_millis(300)).await;
2583        let live = ObservedAdminBroker::start(Duration::ZERO).await;
2584        let bootstrap = [slow.addr.to_string(), live.addr.to_string()];
2585        let mut admin = tokio::time::timeout(
2586            Duration::from_secs(1),
2587            AdminClient::connect_with_options(&bootstrap, custom_admin_options()),
2588        )
2589        .await
2590        .expect("custom initial timeout advances to next bootstrap")
2591        .unwrap();
2592
2593        tokio::time::timeout(Duration::from_secs(1), admin.reconnect_bootstrap())
2594            .await
2595            .expect("custom reconnect timeout advances to next bootstrap")
2596            .unwrap();
2597        assert2::assert!(live.connections.load(Ordering::SeqCst) == 2);
2598        assert2::assert!(live.observed_custom_security_and_id());
2599        assert_custom_connect_timeout_is_stored(&admin);
2600        metadata_times_out_with_custom_request_timeout(&mut admin).await;
2601
2602        slow.stop();
2603        live.stop();
2604    }
2605
2606    #[test]
2607    fn existing_connectors_keep_admin_defaults() {
2608        let options = AdminClient::opts(None);
2609
2610        assert2::assert!(options.client_id.starts_with("adminclient-"));
2611        assert2::assert!(options.socket_connection_setup_timeout == secs(10));
2612        assert2::assert!(options.connections_max_idle == krabka_units::minutes(5));
2613        assert2::assert!(options.request_timeout == secs(30));
2614        assert2::assert!(options.security.is_none());
2615    }
2616
2617    #[test]
2618    fn evacuation_methods_are_available_on_trait_objects() {
2619        fn compile_calls(client: &mut dyn AdminClientLike) {
2620            drop(client.describe_partition_assignments(&["orders"]));
2621            drop(client.list_partition_reassignments(&BTreeMap::new(), secs(30)));
2622            drop(client.alter_partition_assignments(&BTreeMap::new(), secs(30)));
2623            drop(client.unregister_broker(7));
2624        }
2625
2626        std::hint::black_box(compile_calls as fn(&mut dyn AdminClientLike));
2627    }
2628}