1use 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#[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#[async_trait::async_trait]
177pub trait AdminClientLike: Send {
178 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 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 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 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 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 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 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 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 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 #[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 #[error("invalid admin client configuration: {0}")]
536 InvalidConfig(String),
537 #[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 #[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#[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
617pub struct AdminClient {
629 pub(crate) conn: Arc<RecoveringConnection>,
630 bootstrap_addrs: Vec<String>,
631 options: ConnectionOptions,
635 pub(crate) retry: retry::RetryPolicy,
639 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
655pub(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 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 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 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 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 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 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 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 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 pub async fn connect_controller(bootstrap_controllers: &[String]) -> Result<Self, AdminError> {
1178 Self::connect_controller_secured(bootstrap_controllers, None).await
1179 }
1180
1181 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 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 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 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 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 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
1477pub(crate) const NOT_CONTROLLER: i16 = 41;
1481
1482pub(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 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 }
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 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 #[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}