1use std::sync::atomic::{AtomicU32, Ordering};
4
5use krabka_client_core::{
6 ClientDnsLookup, ClientDnsTimeout, ClientFrameMax, ConnectionDispatchQueueCapacity,
7 ConnectionOptions, DEFAULT_METADATA_RECOVERY_REBOOTSTRAP_TRIGGER, MetadataRecoveryStrategy,
8 security::ClientSecurity,
9};
10use krabka_units::{
11 ByteSize, Time,
12 convert::{ByteSizeExt as _, TimeExt as _},
13 millis, secs,
14};
15
16use crate::{AdminError, retry::RetryPolicy};
17
18pub const DEFAULT_ADMIN_REQUEST_TIMEOUT: Time = secs(30);
20pub const DEFAULT_API_TIMEOUT: Time = secs(60);
22pub const DEFAULT_RETRY_BACKOFF: Time = millis(100);
24pub const DEFAULT_RETRY_BACKOFF_MAX: Time = secs(1);
26pub const DEFAULT_SOCKET_CONNECTION_SETUP_TIMEOUT: Time = secs(10);
28pub const DEFAULT_SOCKET_CONNECTION_SETUP_TIMEOUT_MAX: Time = secs(30);
30pub const DEFAULT_ADMIN_CONNECTIONS_MAX_IDLE: Time = krabka_units::minutes(5);
32pub const DEFAULT_ENABLE_METRICS_PUSH: bool = true;
34
35const RETRY_BACKOFF_JITTER: f64 = 0.2;
37
38static ADMIN_CLIENT_ID_SEQUENCE: AtomicU32 = AtomicU32::new(1);
42
43#[derive(Clone, Debug)]
49pub struct AdminClientConfig {
50 pub client_id: Option<String>,
53 pub request_timeout: Time,
55 pub default_api_timeout: Option<Time>,
59 pub retries: u32,
62 pub retry_backoff: Time,
64 pub retry_backoff_max: Time,
66 pub socket_connection_setup_timeout: Time,
69 pub socket_connection_setup_timeout_max: Time,
72 pub connections_max_idle: Time,
75 pub dns_timeout: ClientDnsTimeout,
77 pub client_dns_lookup: ClientDnsLookup,
79 pub reconnect_backoff: Time,
81 pub reconnect_backoff_max: Time,
83 pub send_buffer: Option<ByteSize>,
85 pub receive_buffer: Option<ByteSize>,
87 pub dispatch_queue_capacity: ConnectionDispatchQueueCapacity,
89 pub frame_max: ClientFrameMax,
91 pub security: Option<ClientSecurity>,
94 pub metadata_recovery_strategy: MetadataRecoveryStrategy,
96 pub metadata_recovery_rebootstrap_trigger: Time,
98 pub enable_metrics_push: bool,
104}
105
106impl Default for AdminClientConfig {
107 fn default() -> Self {
108 Self {
109 client_id: None,
110 request_timeout: DEFAULT_ADMIN_REQUEST_TIMEOUT,
111 default_api_timeout: None,
112 retries: u32::MAX,
113 retry_backoff: DEFAULT_RETRY_BACKOFF,
114 retry_backoff_max: DEFAULT_RETRY_BACKOFF_MAX,
115 socket_connection_setup_timeout: DEFAULT_SOCKET_CONNECTION_SETUP_TIMEOUT,
116 socket_connection_setup_timeout_max: DEFAULT_SOCKET_CONNECTION_SETUP_TIMEOUT_MAX,
117 connections_max_idle: DEFAULT_ADMIN_CONNECTIONS_MAX_IDLE,
118 dns_timeout: ClientDnsTimeout::default(),
119 client_dns_lookup: ClientDnsLookup::default(),
120 reconnect_backoff: krabka_client_core::DEFAULT_RECONNECT_BACKOFF,
121 reconnect_backoff_max: krabka_client_core::DEFAULT_RECONNECT_BACKOFF_MAX,
122 send_buffer: Some(krabka_client_core::DEFAULT_SEND_BUFFER),
123 receive_buffer: Some(krabka_client_core::DEFAULT_RECEIVE_BUFFER),
124 dispatch_queue_capacity: ConnectionDispatchQueueCapacity::default(),
125 frame_max: ClientFrameMax::default(),
126 security: None,
127 metadata_recovery_strategy: MetadataRecoveryStrategy::default(),
128 metadata_recovery_rebootstrap_trigger: DEFAULT_METADATA_RECOVERY_REBOOTSTRAP_TRIGGER,
129 enable_metrics_push: DEFAULT_ENABLE_METRICS_PUSH,
130 }
131 }
132}
133
134#[derive(Clone, Debug)]
136pub(crate) struct ResolvedAdminConfig {
137 pub(crate) connection: ConnectionOptions,
138 pub(crate) retry: RetryPolicy,
139 pub(crate) metadata_recovery_strategy: MetadataRecoveryStrategy,
140 pub(crate) metadata_recovery_rebootstrap_trigger: Time,
141 pub(crate) enable_metrics_push: bool,
142}
143
144impl AdminClientConfig {
145 fn validate_transport(&self) -> Result<(), AdminError> {
146 for (name, value) in [
147 ("reconnect_backoff", self.reconnect_backoff),
148 ("reconnect_backoff_max", self.reconnect_backoff_max),
149 ] {
150 if !value.secs_f64().is_finite() || value < Time::ZERO {
151 return Err(AdminError::InvalidConfig(format!(
152 "{name} must be finite and nonnegative"
153 )));
154 }
155 }
156 if self.reconnect_backoff_max < self.reconnect_backoff {
157 return Err(AdminError::InvalidConfig(
158 "reconnect_backoff_max is below reconnect_backoff".into(),
159 ));
160 }
161 for (name, value) in [
162 ("send_buffer", self.send_buffer),
163 ("receive_buffer", self.receive_buffer),
164 ] {
165 if let Some(value) = value {
166 let bytes = value.bytes_f64();
167 if !bytes.is_finite()
168 || bytes < 1.0
169 || bytes.fract() != 0.0
170 || bytes > f64::from(i32::MAX)
171 {
172 return Err(AdminError::InvalidConfig(format!(
173 "{name} must contain positive whole int32 bytes"
174 )));
175 }
176 }
177 }
178 Ok(())
179 }
180
181 pub(crate) fn resolve(self) -> Result<ResolvedAdminConfig, AdminError> {
190 for (name, value) in [
191 ("request_timeout", self.request_timeout),
192 (
193 "socket_connection_setup_timeout",
194 self.socket_connection_setup_timeout,
195 ),
196 (
197 "socket_connection_setup_timeout_max",
198 self.socket_connection_setup_timeout_max,
199 ),
200 ] {
201 if !value.secs_f64().is_finite() || value <= Time::ZERO {
202 return Err(AdminError::InvalidConfig(format!(
203 "{name} must be positive and finite"
204 )));
205 }
206 }
207 if let Some(value) = self.default_api_timeout
208 && (!value.secs_f64().is_finite() || value <= Time::ZERO)
209 {
210 return Err(AdminError::InvalidConfig(
211 "default_api_timeout must be positive and finite".to_owned(),
212 ));
213 }
214 for (name, value) in [
215 ("connections_max_idle", self.connections_max_idle),
216 ("retry_backoff", self.retry_backoff),
217 ("retry_backoff_max", self.retry_backoff_max),
218 ] {
219 if !value.secs_f64().is_finite() || value < Time::ZERO {
220 return Err(AdminError::InvalidConfig(format!(
221 "{name} must be finite and not negative"
222 )));
223 }
224 }
225 self.validate_transport()?;
226 if self.socket_connection_setup_timeout_max < self.socket_connection_setup_timeout
227 || self.retry_backoff_max < self.retry_backoff
228 {
229 return Err(AdminError::InvalidConfig(
230 "maximum delay is below initial delay".into(),
231 ));
232 }
233 let api_timeout = default_api_timeout(self.request_timeout, self.default_api_timeout)?;
234 let client_id = match self.client_id {
235 Some(id) if !id.is_empty() => id,
236 _ => generate_client_id(),
237 };
238 let connection = ConnectionOptions {
239 client_id,
240 dns_timeout: self.dns_timeout,
241 client_dns_lookup: self.client_dns_lookup,
242 reconnect_backoff: self.reconnect_backoff,
243 reconnect_backoff_max: self.reconnect_backoff_max,
244 send_buffer: self.send_buffer,
245 receive_buffer: self.receive_buffer,
246 dispatch_queue_capacity: self.dispatch_queue_capacity,
247 frame_max: self.frame_max,
248 socket_connection_setup_timeout: self.socket_connection_setup_timeout,
249 socket_connection_setup_timeout_max: self.socket_connection_setup_timeout_max,
250 connections_max_idle: self.connections_max_idle,
251 request_timeout: self.request_timeout,
252 security: self.security.map(Box::new),
253 ..ConnectionOptions::default()
254 };
255 connection.validate().map_err(AdminError::InvalidConfig)?;
256 Ok(ResolvedAdminConfig {
257 connection,
258 retry: RetryPolicy {
259 timeout: api_timeout.to_std(),
260 initial_backoff: self.retry_backoff.to_std(),
261 max_backoff: self.retry_backoff_max.to_std(),
262 jitter: RETRY_BACKOFF_JITTER,
263 max_retries: self.retries,
264 },
265 metadata_recovery_strategy: self.metadata_recovery_strategy,
266 metadata_recovery_rebootstrap_trigger: self.metadata_recovery_rebootstrap_trigger,
267 enable_metrics_push: self.enable_metrics_push,
268 })
269 }
270}
271
272fn generate_client_id() -> String {
274 format!(
275 "adminclient-{}",
276 ADMIN_CLIENT_ID_SEQUENCE.fetch_add(1, Ordering::Relaxed)
277 )
278}
279
280fn default_api_timeout(request_timeout: Time, explicit: Option<Time>) -> Result<Time, AdminError> {
284 match explicit {
285 Some(api_timeout) if api_timeout < request_timeout => Err(AdminError::InvalidConfig(
286 "default_api_timeout must be no smaller than request_timeout".to_owned(),
287 )),
288 Some(api_timeout) => Ok(api_timeout),
289 None if DEFAULT_API_TIMEOUT < request_timeout => {
290 tracing::warn!(
291 request_timeout_ms = request_timeout.millis_i64(),
292 "overriding the default of default.api.timeout.ms (60000) with the configured \
293 request timeout"
294 );
295 Ok(request_timeout)
296 }
297 None => Ok(DEFAULT_API_TIMEOUT),
298 }
299}
300
301pub(crate) fn retry_for_connection_options(options: &ConnectionOptions) -> RetryPolicy {
304 let timeout = if options.request_timeout > DEFAULT_API_TIMEOUT {
305 options.request_timeout
306 } else {
307 DEFAULT_API_TIMEOUT
308 };
309 RetryPolicy {
310 timeout: timeout.to_std(),
311 initial_backoff: DEFAULT_RETRY_BACKOFF.to_std(),
312 max_backoff: DEFAULT_RETRY_BACKOFF_MAX.to_std(),
313 jitter: RETRY_BACKOFF_JITTER,
314 max_retries: u32::MAX,
315 }
316}
317
318#[cfg(test)]
319mod tests {
320 use std::{
321 sync::{
322 Arc, Mutex,
323 atomic::{AtomicUsize, Ordering},
324 },
325 time::Duration,
326 };
327
328 use assert2::{assert, check};
329 use bytes::{Buf, BytesMut};
330 use krabka_client_core::MockBroker;
331 use krabka_protocol::{
332 Encode,
333 owned::{
334 api_versions_request,
335 api_versions_response::{ApiVersion, ApiVersionsResponse},
336 unregister_broker_request,
337 unregister_broker_response::UnregisterBrokerResponse,
338 },
339 };
340
341 use super::*;
342 use crate::AdminClient;
343
344 #[derive(Debug, PartialEq)]
347 struct Observed {
348 client_id: String,
349 request_timeout: Time,
350 setup_timeouts: (Time, Time),
351 connections_max_idle: Time,
352 retry: RetryPolicy,
353 }
354
355 fn observe(config: AdminClientConfig) -> Result<Observed, String> {
356 config
357 .resolve()
358 .map(|resolved| Observed {
359 client_id: if resolved.connection.client_id.starts_with("adminclient-") {
361 "adminclient-<n>".to_owned()
362 } else {
363 resolved.connection.client_id
364 },
365 request_timeout: resolved.connection.request_timeout,
366 setup_timeouts: (
367 resolved.connection.socket_connection_setup_timeout,
368 resolved.connection.socket_connection_setup_timeout_max,
369 ),
370 connections_max_idle: resolved.connection.connections_max_idle,
371 retry: resolved.retry,
372 })
373 .map_err(|error| error.to_string())
374 }
375
376 fn retry(timeout: Duration) -> RetryPolicy {
377 RetryPolicy {
378 timeout,
379 initial_backoff: Duration::from_millis(100),
380 max_backoff: Duration::from_secs(1),
381 jitter: 0.2,
382 max_retries: u32::MAX,
383 }
384 }
385
386 #[test]
389 fn settings_resolve_as_kafka_admin_client_config() {
390 let defaults = || Observed {
391 client_id: "adminclient-<n>".into(),
392 request_timeout: secs(30),
393 setup_timeouts: (secs(10), secs(30)),
394 connections_max_idle: krabka_units::minutes(5),
395 retry: retry(Duration::from_mins(1)),
396 };
397 for (name, config, expected) in [
398 ("defaults", AdminClientConfig::default(), Ok(defaults())),
399 (
400 "request timeout 90 s raises the default api timeout",
401 AdminClientConfig {
402 request_timeout: secs(90),
403 ..AdminClientConfig::default()
404 },
405 Ok(Observed {
406 request_timeout: secs(90),
407 retry: retry(Duration::from_secs(90)),
408 ..defaults()
409 }),
410 ),
411 (
412 "api timeout below the request timeout is an error",
413 AdminClientConfig {
414 request_timeout: secs(90),
415 default_api_timeout: Some(secs(60)),
416 ..AdminClientConfig::default()
417 },
418 Err(
419 "invalid admin client configuration: default_api_timeout must be no smaller \
420 than request_timeout"
421 .to_owned(),
422 ),
423 ),
424 (
425 "api timeout equal to the request timeout",
426 AdminClientConfig {
427 default_api_timeout: Some(secs(30)),
428 ..AdminClientConfig::default()
429 },
430 Ok(Observed {
431 retry: retry(Duration::from_secs(30)),
432 ..defaults()
433 }),
434 ),
435 (
436 "explicit client id",
437 AdminClientConfig {
438 client_id: Some("tool-a".into()),
439 ..AdminClientConfig::default()
440 },
441 Ok(Observed {
442 client_id: "tool-a".into(),
443 ..defaults()
444 }),
445 ),
446 (
447 "empty client id is generated",
448 AdminClientConfig {
449 client_id: Some(String::new()),
450 ..AdminClientConfig::default()
451 },
452 Ok(defaults()),
453 ),
454 (
455 "retries, backoff and setup timeout",
456 AdminClientConfig {
457 retries: 3,
458 retry_backoff: millis(50),
459 retry_backoff_max: secs(2),
460 socket_connection_setup_timeout: secs(5),
461 socket_connection_setup_timeout_max: secs(20),
462 connections_max_idle: secs(60),
463 ..AdminClientConfig::default()
464 },
465 Ok(Observed {
466 setup_timeouts: (secs(5), secs(20)),
467 connections_max_idle: secs(60),
468 retry: RetryPolicy {
469 initial_backoff: Duration::from_millis(50),
470 max_backoff: Duration::from_secs(2),
471 max_retries: 3,
472 ..retry(Duration::from_mins(1))
473 },
474 ..defaults()
475 }),
476 ),
477 (
478 "zero request timeout is an error",
479 AdminClientConfig {
480 request_timeout: Time::ZERO,
481 ..AdminClientConfig::default()
482 },
483 Err(
484 "invalid admin client configuration: request_timeout must be positive and \
485 finite"
486 .to_owned(),
487 ),
488 ),
489 (
490 "infinite request timeout is an error",
491 AdminClientConfig {
492 request_timeout: Time::from_secs_f64(f64::INFINITY),
493 ..AdminClientConfig::default()
494 },
495 Err(
496 "invalid admin client configuration: request_timeout must be positive and \
497 finite"
498 .to_owned(),
499 ),
500 ),
501 (
502 "NaN api timeout is an error",
503 AdminClientConfig {
504 default_api_timeout: Some(Time::from_secs_f64(f64::NAN)),
505 ..AdminClientConfig::default()
506 },
507 Err(
508 "invalid admin client configuration: default_api_timeout must be positive \
509 and finite"
510 .to_owned(),
511 ),
512 ),
513 (
514 "NaN retry backoff is an error",
515 AdminClientConfig {
516 retry_backoff: Time::from_secs_f64(f64::NAN),
517 ..AdminClientConfig::default()
518 },
519 Err(
520 "invalid admin client configuration: retry_backoff must be finite and not \
521 negative"
522 .to_owned(),
523 ),
524 ),
525 ] {
526 check!(observe(config) == expected, "{name}");
527 }
528 }
529
530 #[test]
531 fn generated_client_ids_follow_a_process_wide_sequence() {
532 let id = || {
533 AdminClientConfig::default()
534 .resolve()
535 .expect("defaults resolve")
536 .connection
537 .client_id
538 };
539 let number = |id: String| {
540 id.strip_prefix("adminclient-")
541 .and_then(|number| number.parse::<u32>().ok())
542 .expect("adminclient-<n>")
543 };
544 let first = number(id());
545 let second = number(id());
546 assert!(second > first);
547 assert!(first >= 1);
548 }
549
550 async fn timing_out_broker(
553 requests: Arc<AtomicUsize>,
554 client_ids: Arc<Mutex<Vec<String>>>,
555 ) -> MockBroker {
556 MockBroker::start(move |api_key, version, _, request| {
557 let mut header = request;
558 let client_id_len = usize::try_from(header.get_i16()).expect("client id length");
559 client_ids
560 .lock()
561 .expect("client ids lock")
562 .push(String::from_utf8_lossy(&header[..client_id_len]).into_owned());
563 let mut body = BytesMut::new();
564 match api_key {
565 api_versions_request::API_KEY => ApiVersionsResponse {
566 api_keys: vec![
567 ApiVersion {
568 api_key: api_versions_request::API_KEY,
569 ..Default::default()
570 },
571 ApiVersion {
572 api_key: unregister_broker_request::API_KEY,
573 ..Default::default()
574 },
575 ],
576 ..Default::default()
577 }
578 .encode(&mut body, 0)
579 .unwrap(),
580 unregister_broker_request::API_KEY => {
581 requests.fetch_add(1, Ordering::SeqCst);
582 body.extend_from_slice(&[0]);
583 UnregisterBrokerResponse {
584 error_code: 7,
585 ..Default::default()
586 }
587 .encode(&mut body, version)
588 .unwrap();
589 }
590 _ => return None,
591 }
592 Some(body.to_vec())
593 })
594 .await
595 }
596
597 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
601 async fn a_client_uses_its_client_id_call_deadline_and_retries() {
602 for (name, config, expected_requests) in [
603 (
604 "no retries",
605 AdminClientConfig {
606 client_id: Some("tool-a".into()),
607 retries: 0,
608 ..AdminClientConfig::default()
609 },
610 1..=1,
611 ),
612 (
613 "two retries",
614 AdminClientConfig {
615 client_id: Some("tool-a".into()),
616 retries: 2,
617 retry_backoff: millis(1),
618 retry_backoff_max: millis(1),
619 ..AdminClientConfig::default()
620 },
621 3..=3,
622 ),
623 (
624 "the call deadline stops the retries",
625 AdminClientConfig {
626 client_id: Some("tool-a".into()),
627 request_timeout: millis(100),
628 default_api_timeout: Some(millis(400)),
629 retry_backoff: millis(100),
630 retry_backoff_max: millis(100),
631 ..AdminClientConfig::default()
632 },
633 2..=6,
634 ),
635 ] {
636 let requests = Arc::new(AtomicUsize::new(0));
637 let client_ids = Arc::new(Mutex::new(Vec::new()));
638 let broker = timing_out_broker(Arc::clone(&requests), Arc::clone(&client_ids)).await;
639 let mut admin = AdminClient::connect_with_config(&[broker.addr.to_string()], config)
640 .await
641 .expect("admin connects");
642
643 let started = tokio::time::Instant::now();
644 let result = admin.unregister_broker(1).await;
645 let elapsed = started.elapsed();
646
647 broker.stop();
648 let code = match result {
649 Err(crate::AdminError::Broker { code, .. }) => Some(code),
650 _ => None,
651 };
652 let requests = requests.load(Ordering::SeqCst);
653 let client_ids = client_ids.lock().expect("client ids lock").clone();
654 check!(code == Some(7), "{name}");
655 check!(
656 expected_requests.contains(&requests),
657 "{name}: {requests} requests"
658 );
659 check!(elapsed < Duration::from_secs(5), "{name}");
660 check!(
661 client_ids.iter().all(|id| id == "tool-a") && !client_ids.is_empty(),
662 "{name}: {client_ids:?}"
663 );
664 }
665 }
666}
667
668#[cfg(test)]
669mod transport_configuration_tests {
670 use assert2::assert;
671 use krabka_client_core::{ClientDnsLookup, ClientFrameMax, ConnectionDispatchQueueCapacity};
672 use krabka_units::{
673 convert::{ByteSizeExt as _, TimeExt as _},
674 kibibytes, mebibytes, millis,
675 };
676
677 use super::AdminClientConfig;
678
679 #[test]
680 fn admin_resolves_transport_resources_without_losing_retry_policy() {
681 let config = AdminClientConfig {
682 client_dns_lookup: ClientDnsLookup::ResolveCanonicalBootstrapServersOnly,
683 reconnect_backoff: millis(27),
684 reconnect_backoff_max: millis(127),
685 send_buffer: None,
686 receive_buffer: Some(kibibytes(19)),
687 dispatch_queue_capacity: ConnectionDispatchQueueCapacity::new(7).expect("capacity"),
688 frame_max: ClientFrameMax::try_from(mebibytes(2)).expect("frame"),
689 retry_backoff: millis(37),
690 ..Default::default()
691 };
692 let resolved = config.resolve().expect("valid config");
693 let options = resolved.connection;
694 assert!(
695 (
696 options.client_dns_lookup,
697 options.reconnect_backoff,
698 options.reconnect_backoff_max,
699 options.send_buffer,
700 options.receive_buffer,
701 options.dispatch_queue_capacity.get(),
702 options.frame_max.size()
703 ) == (
704 ClientDnsLookup::ResolveCanonicalBootstrapServersOnly,
705 millis(27),
706 millis(127),
707 None,
708 Some(kibibytes(19)),
709 7,
710 mebibytes(2)
711 )
712 );
713 assert!(resolved.retry.initial_backoff == std::time::Duration::from_millis(37));
714 let invalid = AdminClientConfig {
715 reconnect_backoff: millis(2000),
716 ..Default::default()
717 };
718 assert!(invalid.resolve().is_err());
719 }
720
721 #[test]
722 fn admin_rejects_invalid_transport_bounds_and_socket_sizes() {
723 let invalid_backoff = AdminClientConfig {
724 reconnect_backoff: krabka_units::Time::from_secs_f64(f64::NAN),
725 ..Default::default()
726 };
727 assert!(invalid_backoff.resolve().is_err());
728
729 let fractional_socket_buffer = AdminClientConfig {
730 send_buffer: Some(krabka_units::ByteSize::from_bytes_f64(0.5)),
731 ..Default::default()
732 };
733 assert!(fractional_socket_buffer.resolve().is_err());
734
735 let inverted_setup_bounds = AdminClientConfig {
736 socket_connection_setup_timeout_max: krabka_units::millis(1),
737 ..Default::default()
738 };
739 assert!(inverted_setup_bounds.resolve().is_err());
740 }
741}