Skip to main content

krabka_client_admin/
configs.rs

1//! Config reads and changes of any config resource, as Kafka's
2//! `Admin.describeConfigs` and `Admin.incrementalAlterConfigs`.
3//!
4//! Both calls route each resource as `KafkaAdminClient` does (`nodeFor`). A
5//! `BROKER` resource that names a broker id, and every `BROKER_LOGGER`
6//! resource, go to that node in a request of their own
7//! (`ConstantNodeIdProvider`). Every other resource, including the empty-name
8//! `BROKER` resource of the cluster-wide defaults, goes in one request on the
9//! client's connection (`LeastLoadedBrokerOrActiveKController`). With a
10//! controller bootstrap (KIP-919), `incrementalAlterConfigs` sends a `BROKER`
11//! resource with the others to the active controller too.
12//!
13//! Each resource gets a result of its own: its config or change, or the
14//! Kafka error of the resource or of the request that carried it.
15
16use std::{
17    collections::{BTreeMap, BTreeSet},
18    fmt,
19};
20
21use krabka_protocol::owned::{
22    describe_configs_request::{DescribeConfigsRequest, DescribeConfigsResource},
23    describe_configs_response::{
24        DescribeConfigsResourceResult, DescribeConfigsResponse, DescribeConfigsResult,
25    },
26    incremental_alter_configs_request::{
27        AlterConfigsResource, AlterableConfig, IncrementalAlterConfigsRequest,
28    },
29    incremental_alter_configs_response::IncrementalAlterConfigsResponse,
30};
31
32use crate::{
33    AdminClient, AdminError, KafkaError, NOT_CONTROLLER,
34    config_resources::{ConfigResource, ConfigResourceType},
35    groups::list_groups_kafka_error,
36    kafka_error_name,
37    log_dirs::{NodeTarget, call_node},
38    retry::{
39        ControllerRetry, CoordinatorRetry, REQUEST_TIMED_OUT, call_timeout_error,
40        is_connection_failure,
41    },
42};
43
44/// `UNKNOWN_SERVER_ERROR`: Kafka's error for an exception that is not an
45/// `ApiException`.
46const UNKNOWN_SERVER_ERROR: i16 = -1;
47/// `NOT_LEADER_OR_FOLLOWER`, which a follower controller gives (KIP-919).
48const NOT_LEADER_OR_FOLLOWER: i16 = 6;
49/// The first `DescribeConfigs` version that carries `IncludeDocumentation`.
50const DESCRIBE_CONFIGS_DOCUMENTATION_VERSION: i16 = 3;
51
52impl ConfigResource {
53    /// The resource of `resource_type` named `name`.
54    #[must_use]
55    pub fn new(resource_type: ConfigResourceType, name: impl Into<String>) -> Self {
56        Self {
57            resource_type,
58            name: name.into(),
59        }
60    }
61
62    /// The topic `name`.
63    #[must_use]
64    pub fn topic(name: impl Into<String>) -> Self {
65        Self::new(ConfigResourceType::Topic, name)
66    }
67
68    /// The broker `broker_id`.
69    #[must_use]
70    pub fn broker(broker_id: i32) -> Self {
71        Self::new(ConfigResourceType::Broker, broker_id.to_string())
72    }
73
74    /// The cluster-wide default broker config: the `BROKER` resource with an
75    /// empty name.
76    #[must_use]
77    pub fn broker_default() -> Self {
78        Self::new(ConfigResourceType::Broker, "")
79    }
80
81    /// The loggers of broker `broker_id`.
82    #[must_use]
83    pub fn broker_logger(broker_id: i32) -> Self {
84        Self::new(ConfigResourceType::BrokerLogger, broker_id.to_string())
85    }
86
87    /// The client-metrics subscription `name` (KIP-714).
88    #[must_use]
89    pub fn client_metrics(name: impl Into<String>) -> Self {
90        Self::new(ConfigResourceType::ClientMetrics, name)
91    }
92
93    /// The group `name` (KIP-848).
94    #[must_use]
95    pub fn group(name: impl Into<String>) -> Self {
96        Self::new(ConfigResourceType::Group, name)
97    }
98
99    /// Whether the resource is a default one, that is has an empty name, as
100    /// Kafka's `ConfigResource.isDefault`.
101    #[must_use]
102    pub fn is_default(&self) -> bool {
103        self.name.is_empty()
104    }
105
106    /// The source of the configs that are set on this resource itself, as
107    /// `kafka-configs --describe` filters them: `DYNAMIC_TOPIC_CONFIG` for a
108    /// topic, `DYNAMIC_BROKER_CONFIG` for a broker,
109    /// `DYNAMIC_DEFAULT_BROKER_CONFIG` for the default broker,
110    /// `DYNAMIC_BROKER_LOGGER_CONFIG` for broker loggers,
111    /// `DYNAMIC_CLIENT_METRICS_CONFIG` and `DYNAMIC_GROUP_CONFIG`. `None` for
112    /// an unknown type.
113    #[must_use]
114    pub fn dynamic_config_source(&self) -> Option<ConfigSource> {
115        match self.resource_type {
116            ConfigResourceType::Topic => Some(ConfigSource::DynamicTopicConfig),
117            ConfigResourceType::Broker if self.is_default() => {
118                Some(ConfigSource::DynamicDefaultBrokerConfig)
119            }
120            ConfigResourceType::Broker => Some(ConfigSource::DynamicBrokerConfig),
121            ConfigResourceType::BrokerLogger => Some(ConfigSource::DynamicBrokerLoggerConfig),
122            ConfigResourceType::ClientMetrics => Some(ConfigSource::DynamicClientMetricsConfig),
123            ConfigResourceType::Group => Some(ConfigSource::DynamicGroupConfig),
124            ConfigResourceType::Unknown => None,
125        }
126    }
127}
128
129/// Where the value of a config comes from, as Kafka's
130/// `ConfigEntry.ConfigSource`.
131#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
132pub enum ConfigSource {
133    /// Set on the topic (wire id 1).
134    DynamicTopicConfig,
135    /// Set on the loggers of the broker (wire id 6).
136    DynamicBrokerLoggerConfig,
137    /// Set on the broker (wire id 2).
138    DynamicBrokerConfig,
139    /// Set as the default of every broker of the cluster (wire id 3).
140    DynamicDefaultBrokerConfig,
141    /// Set on the client-metrics subscription (wire id 7, KIP-714).
142    DynamicClientMetricsConfig,
143    /// Set on the group (wire id 8, KIP-848).
144    DynamicGroupConfig,
145    /// The broker's static config, such as `server.properties` (wire id 4).
146    StaticBrokerConfig,
147    /// The built-in default (wire id 5).
148    DefaultConfig,
149    /// A source that Kafka does not define (wire id 0, or an id above 8).
150    Unknown,
151}
152
153impl ConfigSource {
154    /// The wire id of the source, as `DescribeConfigsResponse.ConfigSource`.
155    #[must_use]
156    pub const fn id(self) -> i8 {
157        match self {
158            Self::Unknown => 0,
159            Self::DynamicTopicConfig => 1,
160            Self::DynamicBrokerConfig => 2,
161            Self::DynamicDefaultBrokerConfig => 3,
162            Self::StaticBrokerConfig => 4,
163            Self::DefaultConfig => 5,
164            Self::DynamicBrokerLoggerConfig => 6,
165            Self::DynamicClientMetricsConfig => 7,
166            Self::DynamicGroupConfig => 8,
167        }
168    }
169
170    /// The source of a wire id, as `DescribeConfigsResponse.ConfigSource.forId`:
171    /// [`Self::Unknown`] for an id above 8, and `None` for a negative id,
172    /// which Kafka refuses.
173    #[must_use]
174    pub const fn from_id(id: i8) -> Option<Self> {
175        Some(match id {
176            i8::MIN..=-1 => return None,
177            1 => Self::DynamicTopicConfig,
178            2 => Self::DynamicBrokerConfig,
179            3 => Self::DynamicDefaultBrokerConfig,
180            4 => Self::StaticBrokerConfig,
181            5 => Self::DefaultConfig,
182            6 => Self::DynamicBrokerLoggerConfig,
183            7 => Self::DynamicClientMetricsConfig,
184            8 => Self::DynamicGroupConfig,
185            _ => Self::Unknown,
186        })
187    }
188}
189
190/// The data type of a config, as Kafka's `ConfigEntry.ConfigType`.
191#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
192pub enum ConfigType {
193    /// Not reported (`DescribeConfigs` below v3) or not defined (wire id 0,
194    /// or an id above 9).
195    Unknown,
196    /// Wire id 1.
197    Boolean,
198    /// Wire id 2.
199    String,
200    /// Wire id 3.
201    Int,
202    /// Wire id 4.
203    Short,
204    /// Wire id 5.
205    Long,
206    /// Wire id 6.
207    Double,
208    /// Wire id 7.
209    List,
210    /// Wire id 8.
211    Class,
212    /// Wire id 9.
213    Password,
214}
215
216impl ConfigType {
217    /// The wire id of the type, as `DescribeConfigsResponse.ConfigType`.
218    #[must_use]
219    pub const fn id(self) -> i8 {
220        match self {
221            Self::Unknown => 0,
222            Self::Boolean => 1,
223            Self::String => 2,
224            Self::Int => 3,
225            Self::Short => 4,
226            Self::Long => 5,
227            Self::Double => 6,
228            Self::List => 7,
229            Self::Class => 8,
230            Self::Password => 9,
231        }
232    }
233
234    /// The type of a wire id, as `DescribeConfigsResponse.ConfigType.forId`:
235    /// [`Self::Unknown`] for an id above 9, and `None` for a negative id,
236    /// which Kafka refuses.
237    #[must_use]
238    pub const fn from_id(id: i8) -> Option<Self> {
239        Some(match id {
240            i8::MIN..=-1 => return None,
241            1 => Self::Boolean,
242            2 => Self::String,
243            3 => Self::Int,
244            4 => Self::Short,
245            5 => Self::Long,
246            6 => Self::Double,
247            7 => Self::List,
248            8 => Self::Class,
249            9 => Self::Password,
250            _ => Self::Unknown,
251        })
252    }
253}
254
255/// One value that a config takes from one source, as Kafka's
256/// `ConfigEntry.ConfigSynonym`.
257#[derive(Debug, Clone, PartialEq, Eq)]
258pub struct ConfigSynonym {
259    /// The name of the config at that source, such as `log.retention.ms`
260    /// for the topic config `retention.ms`.
261    pub name: String,
262    /// The value at that source. `None` when the broker withholds it, as it
263    /// does for a sensitive config.
264    pub value: Option<String>,
265    /// The source.
266    pub source: ConfigSource,
267}
268
269/// One config of a resource, as Kafka's `ConfigEntry`.
270///
271/// `Debug` prints a sensitive value as `Redacted`, as Kafka's `toString`
272/// does.
273#[derive(Clone, PartialEq, Eq)]
274pub struct ConfigEntry {
275    /// The name of the config.
276    pub name: String,
277    /// The value, as the broker gave it. The broker gives `None` for a
278    /// sensitive config and for a config with no value.
279    pub value: Option<String>,
280    /// Where the value comes from.
281    pub source: ConfigSource,
282    /// Whether the config is sensitive, such as a password.
283    pub is_sensitive: bool,
284    /// Whether the config cannot be changed.
285    pub is_read_only: bool,
286    /// The value of the config at each source, most specific first. Empty
287    /// unless [`DescribeConfigsOptions::include_synonyms`] is set.
288    pub synonyms: Vec<ConfigSynonym>,
289    /// The data type. [`ConfigType::Unknown`] below `DescribeConfigs` v3.
290    pub config_type: ConfigType,
291    /// The documentation. `None` unless
292    /// [`DescribeConfigsOptions::include_documentation`] is set.
293    pub documentation: Option<String>,
294}
295
296impl ConfigEntry {
297    /// Whether the value is the built-in default, as Kafka's
298    /// `ConfigEntry.isDefault`.
299    #[must_use]
300    pub fn is_default(&self) -> bool {
301        self.source == ConfigSource::DefaultConfig
302    }
303}
304
305impl fmt::Debug for ConfigEntry {
306    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
307        let value: &dyn fmt::Debug = if self.is_sensitive {
308            &"Redacted"
309        } else {
310            &self.value
311        };
312        f.debug_struct("ConfigEntry")
313            .field("name", &self.name)
314            .field("value", value)
315            .field("source", &self.source)
316            .field("is_sensitive", &self.is_sensitive)
317            .field("is_read_only", &self.is_read_only)
318            .field("synonyms", &self.synonyms)
319            .field("config_type", &self.config_type)
320            .field("documentation", &self.documentation)
321            .finish()
322    }
323}
324
325/// The configs of one resource, as Kafka's `Config`.
326#[derive(Debug, Clone, Default, PartialEq, Eq)]
327pub struct Config {
328    /// Each config by name. A name the broker lists twice keeps its last
329    /// entry, as Kafka's map does.
330    pub entries: BTreeMap<String, ConfigEntry>,
331}
332
333impl Config {
334    /// The config `name`.
335    #[must_use]
336    pub fn get(&self, name: &str) -> Option<&ConfigEntry> {
337        self.entries.get(name)
338    }
339
340    /// The name and value of each config that is set on `resource` itself:
341    /// the entries whose source is [`ConfigResource::dynamic_config_source`]
342    /// and that have a value. This is what `kafka-configs --describe` lists
343    /// without `--all`, less the sensitive configs, whose value the broker
344    /// withholds.
345    #[must_use]
346    pub fn dynamic_overrides(&self, resource: &ConfigResource) -> BTreeMap<String, String> {
347        let Some(source) = resource.dynamic_config_source() else {
348            return BTreeMap::new();
349        };
350        self.entries
351            .values()
352            .filter(|entry| entry.source == source)
353            .filter_map(|entry| Some((entry.name.clone(), entry.value.clone()?)))
354            .collect()
355    }
356}
357
358/// What [`AdminClient::describe_configs`] asks for, as Kafka's
359/// `DescribeConfigsOptions`.
360#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, bon::Builder)]
361pub struct DescribeConfigsOptions {
362    /// Ask for the value of each config at each source
363    /// ([`ConfigEntry::synonyms`]).
364    #[builder(default)]
365    pub include_synonyms: bool,
366    /// Ask for the documentation of each config. Needs `DescribeConfigs` v3.
367    #[builder(default)]
368    pub include_documentation: bool,
369}
370
371/// What an [`AlterConfigOp`] does, as Kafka's `AlterConfigOp.OpType`.
372#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
373pub enum AlterConfigOpType {
374    /// Set the value (wire id 0).
375    Set,
376    /// Revert to the default value (wire id 1).
377    Delete,
378    /// Add the values to a list config (wire id 2).
379    Append,
380    /// Remove the values from a list config (wire id 3).
381    Subtract,
382}
383
384impl AlterConfigOpType {
385    /// The wire id of the operation.
386    #[must_use]
387    pub const fn id(self) -> i8 {
388        match self {
389            Self::Set => 0,
390            Self::Delete => 1,
391            Self::Append => 2,
392            Self::Subtract => 3,
393        }
394    }
395}
396
397/// One change of one config, as Kafka's `AlterConfigOp`.
398#[derive(Debug, Clone, PartialEq, Eq)]
399pub struct AlterConfigOp {
400    /// The name of the config.
401    pub name: String,
402    /// The value that the operation sends. A `Delete` needs none.
403    pub value: Option<String>,
404    /// The operation.
405    pub op_type: AlterConfigOpType,
406}
407
408impl AlterConfigOp {
409    /// Set `name` to `value`.
410    #[must_use]
411    pub fn set(name: impl Into<String>, value: impl Into<String>) -> Self {
412        Self {
413            name: name.into(),
414            value: Some(value.into()),
415            op_type: AlterConfigOpType::Set,
416        }
417    }
418
419    /// Revert `name` to its default value. The operation sends no value.
420    #[must_use]
421    pub fn delete(name: impl Into<String>) -> Self {
422        Self {
423            name: name.into(),
424            value: None,
425            op_type: AlterConfigOpType::Delete,
426        }
427    }
428
429    /// Add the comma-separated `values` to the list config `name`.
430    #[must_use]
431    pub fn append(name: impl Into<String>, values: impl Into<String>) -> Self {
432        Self {
433            name: name.into(),
434            value: Some(values.into()),
435            op_type: AlterConfigOpType::Append,
436        }
437    }
438
439    /// Remove the comma-separated `values` from the list config `name`.
440    #[must_use]
441    pub fn subtract(name: impl Into<String>, values: impl Into<String>) -> Self {
442        Self {
443            name: name.into(),
444            value: Some(values.into()),
445            op_type: AlterConfigOpType::Subtract,
446        }
447    }
448}
449
450/// What [`AdminClient::incremental_alter_configs`] asks for, as Kafka's
451/// `AlterConfigsOptions`.
452#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, bon::Builder)]
453pub struct IncrementalAlterConfigsOptions {
454    /// Validate the changes and apply none.
455    #[builder(default)]
456    pub validate_only: bool,
457}
458
459/// The result of each resource of a [`AdminClient::describe_configs`] call.
460pub type DescribeConfigsResults = BTreeMap<ConfigResource, Result<Config, KafkaError>>;
461
462/// The result of each resource of an
463/// [`AdminClient::incremental_alter_configs`] call.
464pub type AlterConfigsResults = BTreeMap<ConfigResource, Result<(), KafkaError>>;
465
466/// The node that a resource goes to, as `KafkaAdminClient.nodeFor`: the
467/// broker id of a `BROKER` resource with a name and of a `BROKER_LOGGER`
468/// resource, and `None` for every other resource.
469fn node_for(resource: &ConfigResource) -> Result<Option<i32>, AdminError> {
470    let by_id = match resource.resource_type {
471        ConfigResourceType::Broker => !resource.is_default(),
472        ConfigResourceType::BrokerLogger => true,
473        _ => false,
474    };
475    if !by_id {
476        return Ok(None);
477    }
478    resource.name.parse().map(Some).map_err(|_| {
479        AdminError::InvalidArgument(format!(
480            "the name of a {:?} config resource must be a broker id, found {:?}",
481            resource.resource_type, resource.name
482        ))
483    })
484}
485
486/// The Kafka error of a request that failed as a whole. A connection that
487/// fails until the deadline gives `REQUEST_TIMED_OUT` (7), as Kafka's
488/// `Call.handleTimeoutFailure` does.
489fn call_error(api: &str, error: &AdminError) -> KafkaError {
490    if is_connection_failure(error) {
491        return KafkaError {
492            code: REQUEST_TIMED_OUT,
493            name: kafka_error_name(REQUEST_TIMED_OUT),
494            message: Some(format!("{api} timed out: {error}")),
495        };
496    }
497    list_groups_kafka_error(error)
498}
499
500/// `UNKNOWN_SERVER_ERROR` with `message`: Kafka's error for a failure that is
501/// not an `ApiException`.
502fn unknown_server_error(message: String) -> KafkaError {
503    KafkaError {
504        code: UNKNOWN_SERVER_ERROR,
505        name: kafka_error_name(UNKNOWN_SERVER_ERROR),
506        message: Some(message),
507    }
508}
509
510fn describe_request(
511    resources: &BTreeSet<ConfigResource>,
512    options: DescribeConfigsOptions,
513) -> DescribeConfigsRequest {
514    DescribeConfigsRequest {
515        resources: resources
516            .iter()
517            .map(|resource| DescribeConfigsResource {
518                resource_type: resource.resource_type.id(),
519                resource_name: resource.name.clone(),
520                configuration_keys: None,
521                ..Default::default()
522            })
523            .collect(),
524        include_synonyms: options.include_synonyms,
525        include_documentation: options.include_documentation,
526        ..Default::default()
527    }
528}
529
530/// The lowest `DescribeConfigs` version that carries `options`.
531/// `IncludeDocumentation` is not ignorable, so Kafka refuses to send it below
532/// v3.
533fn describe_min_version(options: DescribeConfigsOptions) -> Option<i16> {
534    options
535        .include_documentation
536        .then_some(DESCRIBE_CONFIGS_DOCUMENTATION_VERSION)
537}
538
539/// The source of a wire id, or Kafka's `IllegalArgumentException` message.
540fn source_of(id: i8) -> Result<ConfigSource, String> {
541    ConfigSource::from_id(id).ok_or_else(|| format!("id should be positive, id: {id}"))
542}
543
544/// The config of one resource of a `DescribeConfigs` answer, as Kafka's
545/// `describeConfigResult`. A negative source or type id gives Kafka's
546/// `IllegalArgumentException` message.
547fn config_of(configs: Vec<DescribeConfigsResourceResult>) -> Result<Config, String> {
548    let mut entries = BTreeMap::new();
549    for config in configs {
550        let synonyms = config
551            .synonyms
552            .into_iter()
553            .map(|synonym| {
554                Ok(ConfigSynonym {
555                    name: synonym.name,
556                    value: synonym.value,
557                    source: source_of(synonym.source)?,
558                })
559            })
560            .collect::<Result<_, String>>()?;
561        let entry = ConfigEntry {
562            source: source_of(config.config_source)?,
563            config_type: ConfigType::from_id(config.config_type)
564                .ok_or_else(|| format!("id should be positive, id: {}", config.config_type))?,
565            name: config.name,
566            value: config.value,
567            is_sensitive: config.is_sensitive,
568            is_read_only: config.read_only,
569            synonyms,
570            documentation: config.documentation,
571        };
572        entries.insert(entry.name.clone(), entry);
573    }
574    Ok(Config { entries })
575}
576
577/// The result of each resource of `asked` from the answer to one
578/// `DescribeConfigs` request, as Kafka's `describeConfigs` call handles it:
579///
580/// - A resource with an error code gets that error.
581/// - A resource that the answer does not name gets `UNKNOWN_SERVER_ERROR`
582///   (`completeUnrealizedFutures`). A resource that the request did not name
583///   is skipped.
584/// - A request that failed, an answer that names a resource twice, and an
585///   answer with a negative source or type id fail every resource of the
586///   request, as Kafka's `handleFailure` does.
587fn describe_results(
588    asked: &BTreeSet<ConfigResource>,
589    answer: Result<DescribeConfigsResponse, KafkaError>,
590) -> DescribeConfigsResults {
591    let fail_all = |error: KafkaError| {
592        asked
593            .iter()
594            .map(|resource| (resource.clone(), Err(error.clone())))
595            .collect()
596    };
597    let response = match answer {
598        Ok(response) => response,
599        Err(error) => return fail_all(error),
600    };
601    let mut answered = BTreeMap::<ConfigResource, DescribeConfigsResult>::new();
602    for result in response.results {
603        let resource = ConfigResource::new(
604            ConfigResourceType::from_id(result.resource_type),
605            result.resource_name.clone(),
606        );
607        if answered.insert(resource.clone(), result).is_some() {
608            return fail_all(unknown_server_error(format!(
609                "Duplicate key for config resource {resource:?}"
610            )));
611        }
612    }
613    let mut out = BTreeMap::new();
614    for resource in asked {
615        let result = match answered.remove(resource) {
616            None => Err(unknown_server_error(format!(
617                "The node response did not contain a result for config resource {resource:?}"
618            ))),
619            Some(result) if result.error_code != 0 => Err(KafkaError {
620                code: result.error_code,
621                name: kafka_error_name(result.error_code),
622                message: result.error_message,
623            }),
624            Some(result) => match config_of(result.configs) {
625                Ok(config) => Ok(config),
626                Err(message) => return fail_all(unknown_server_error(message)),
627            },
628        };
629        out.insert(resource.clone(), result);
630    }
631    for resource in answered.into_keys() {
632        tracing::warn!(
633            ?resource,
634            "the DescribeConfigs response names a resource that was not asked for"
635        );
636    }
637    out
638}
639
640fn alter_request(
641    resources: &BTreeMap<ConfigResource, &[AlterConfigOp]>,
642    options: IncrementalAlterConfigsOptions,
643) -> IncrementalAlterConfigsRequest {
644    IncrementalAlterConfigsRequest {
645        resources: resources
646            .iter()
647            .map(|(resource, ops)| AlterConfigsResource {
648                resource_type: resource.resource_type.id(),
649                resource_name: resource.name.clone(),
650                configs: ops
651                    .iter()
652                    .map(|op| AlterableConfig {
653                        name: op.name.clone(),
654                        config_operation: op.op_type.id(),
655                        value: op.value.clone(),
656                        ..Default::default()
657                    })
658                    .collect(),
659                ..Default::default()
660            })
661            .collect(),
662        validate_only: options.validate_only,
663        ..Default::default()
664    }
665}
666
667/// Whether an `IncrementalAlterConfigs` answer makes Kafka find the
668/// controller again and retry (`handleNotControllerError`): any
669/// `NOT_CONTROLLER` (41), or with a controller bootstrap any
670/// `NOT_LEADER_OR_FOLLOWER` (6).
671fn names_not_controller(response: &IncrementalAlterConfigsResponse, controllers: bool) -> bool {
672    response.responses.iter().any(|result| {
673        result.error_code == NOT_CONTROLLER
674            || (controllers && result.error_code == NOT_LEADER_OR_FOLLOWER)
675    })
676}
677
678/// The result of each resource of `asked` from the answer to one
679/// `IncrementalAlterConfigs` request. A resource that the answer does not
680/// name gets `UNKNOWN_SERVER_ERROR`. A request that failed fails every
681/// resource.
682fn alter_results<'a>(
683    asked: impl Iterator<Item = &'a ConfigResource>,
684    answer: Result<IncrementalAlterConfigsResponse, KafkaError>,
685) -> AlterConfigsResults {
686    let response = match answer {
687        Ok(response) => response,
688        Err(error) => {
689            return asked
690                .map(|resource| (resource.clone(), Err(error.clone())))
691                .collect();
692        }
693    };
694    let answered = response
695        .responses
696        .into_iter()
697        .map(|result| {
698            (
699                ConfigResource::new(
700                    ConfigResourceType::from_id(result.resource_type),
701                    result.resource_name,
702                ),
703                (result.error_code, result.error_message),
704            )
705        })
706        .collect::<BTreeMap<_, _>>();
707    asked
708        .map(|resource| {
709            let result = match answered.get(resource) {
710                None => Err(unknown_server_error(format!(
711                    "The node response did not contain a result for config resource {resource:?}"
712                ))),
713                Some((0, _)) => Ok(()),
714                Some((code, message)) => Err(KafkaError {
715                    code: *code,
716                    name: kafka_error_name(*code),
717                    message: message.clone(),
718                }),
719            };
720            (resource.clone(), result)
721        })
722        .collect()
723}
724
725impl AdminClient {
726    /// Describes the configs of each resource of `resources`, as Kafka's
727    /// `describeConfigs` operation does.
728    ///
729    /// The client sends one `DescribeConfigs` request to each broker that a
730    /// `BROKER` resource with a broker id or a `BROKER_LOGGER` resource
731    /// names, and one request with every other resource on its connection,
732    /// all at the same time. Each request asks for every config of its
733    /// resources. The result has one entry for each resource:
734    ///
735    /// - Its [`Config`], or the error the broker gave for it, such as
736    ///   `UNKNOWN_TOPIC_OR_PARTITION` (3).
737    /// - `UNKNOWN_SERVER_ERROR` (-1) when the answer has no result for it.
738    /// - The error of its request when that request fails: `REQUEST_TIMED_OUT`
739    ///   (7) at `default.api.timeout.ms` (60 s), or `UNSUPPORTED_VERSION` (35)
740    ///   when the node does not support `DescribeConfigs` v3 and
741    ///   `include_documentation` is set. A broker is found by id in fresh
742    ///   metadata, and a missing broker or a lost connection is tried again
743    ///   until the deadline, as in [`Self::describe_log_dirs`].
744    ///
745    /// # Errors
746    /// Returns [`AdminError::InvalidArgument`], and sends nothing, when the
747    /// name of a `BROKER` resource is neither empty nor a broker id, or the
748    /// name of a `BROKER_LOGGER` resource is not a broker id, as Kafka's
749    /// `nodeFor` throws a `NumberFormatException`.
750    pub async fn describe_configs(
751        &self,
752        resources: &[ConfigResource],
753        options: DescribeConfigsOptions,
754    ) -> Result<DescribeConfigsResults, AdminError> {
755        let mut by_node = BTreeMap::<Option<i32>, BTreeSet<ConfigResource>>::new();
756        for resource in resources {
757            by_node
758                .entry(node_for(resource)?)
759                .or_default()
760                .insert(resource.clone());
761        }
762        let start = self.retry.start();
763        let min_version = describe_min_version(options);
764        let answers = futures_util::future::join_all(by_node.iter().map(|(node, asked)| {
765            let request = describe_request(asked, options);
766            async move {
767                let answer = if let Some(node_id) = *node {
768                    call_node(
769                        &self.conn,
770                        NodeTarget {
771                            node_id,
772                            supports_controllers: true,
773                            min_version,
774                        },
775                        &self.options,
776                        request,
777                        CoordinatorRetry::from_deadline(start),
778                    )
779                    .await
780                } else {
781                    let retry = ControllerRetry::new("DescribeConfigs", self.retry);
782                    let sent = match min_version {
783                        Some(min_version) => {
784                            retry
785                                .bounded(self.conn.send_at_least(request, min_version))
786                                .await
787                        }
788                        None => retry.bounded(self.conn.send(request)).await,
789                    };
790                    sent.map_err(|error| call_error("DescribeConfigs", &error))
791                };
792                describe_results(asked, answer)
793            }
794        }))
795        .await;
796        Ok(answers.into_iter().flatten().collect())
797    }
798
799    /// Changes the configs of each resource of `configs`, as Kafka's
800    /// `incrementalAlterConfigs` operation does. With
801    /// [`IncrementalAlterConfigsOptions::validate_only`] the broker
802    /// validates the changes and applies none.
803    ///
804    /// A `BROKER` resource with a broker id goes to that broker, and a
805    /// `BROKER_LOGGER` resource to its broker, each in a request of its own.
806    /// With a controller bootstrap only a `BROKER_LOGGER` resource goes to
807    /// its node. Every other resource goes in one request on the client's
808    /// connection. A `NOT_CONTROLLER` (41) answer, or with a controller
809    /// bootstrap a `NOT_LEADER_OR_FOLLOWER` (6) answer, makes the client find
810    /// the controller again and send the request again until the deadline.
811    /// The result has one entry for each resource:
812    ///
813    /// - `Ok(())`, or the error the broker gave for it, such as
814    ///   `INVALID_CONFIG` (40).
815    /// - `UNKNOWN_SERVER_ERROR` (-1) when the answer has no result for it.
816    /// - The error of its request when that request fails, with
817    ///   `REQUEST_TIMED_OUT` (7) at `default.api.timeout.ms` (60 s).
818    ///
819    /// # Errors
820    /// Returns [`AdminError::InvalidArgument`], and sends nothing, for a
821    /// resource name that [`Self::describe_configs`] refuses.
822    pub async fn incremental_alter_configs(
823        &mut self,
824        configs: &BTreeMap<ConfigResource, Vec<AlterConfigOp>>,
825        options: IncrementalAlterConfigsOptions,
826    ) -> Result<AlterConfigsResults, AdminError> {
827        let controllers = self.conn.uses_controller_bootstrap();
828        let mut unified = BTreeMap::new();
829        let mut by_node = Vec::new();
830        for (resource, ops) in configs {
831            let node = node_for(resource)?.filter(|_| {
832                !controllers || resource.resource_type == ConfigResourceType::BrokerLogger
833            });
834            match node {
835                Some(node_id) => by_node.push((node_id, resource, ops.as_slice())),
836                None => {
837                    unified.insert(resource.clone(), ops.as_slice());
838                }
839            }
840        }
841        let start = self.retry.start();
842        let (conn, client_options) = (&self.conn, &self.options);
843        let node_answers =
844            futures_util::future::join_all(by_node.iter().map(|(node_id, resource, ops)| {
845                let request = alter_request(&maplit::btreemap! {
846                    (*resource).clone() => *ops,
847                }, options);
848                let target = NodeTarget {
849                    node_id: *node_id,
850                    supports_controllers: true,
851                    min_version: None,
852                };
853                async move {
854                    let mut deadline = start;
855                    let mut attempts = 1;
856                    let answer = loop {
857                        let answer = call_node(
858                            conn,
859                            target,
860                            client_options,
861                            request.clone(),
862                            CoordinatorRetry::from_deadline(deadline),
863                        )
864                        .await;
865                        if !matches!(&answer, Ok(response) if names_not_controller(response, controllers))
866                        {
867                            break answer;
868                        }
869                        let timed_out = || {
870                            Err(call_timeout_error(
871                                "IncrementalAlterConfigs",
872                                attempts,
873                                "NOT_CONTROLLER",
874                            ))
875                        };
876                        if deadline.exhausted() {
877                            break timed_out();
878                        }
879                        deadline.backoff().await;
880                        if deadline.expired() {
881                            break timed_out();
882                        }
883                        attempts += 1;
884                    };
885                    alter_results(std::iter::once(*resource), answer)
886                }
887            }))
888            .await;
889        let mut out: AlterConfigsResults = node_answers.into_iter().flatten().collect();
890        if !unified.is_empty() {
891            let answer = self.alter_unified(&unified, options, controllers).await;
892            out.extend(alter_results(unified.keys(), answer));
893        }
894        Ok(out)
895    }
896
897    /// The `IncrementalAlterConfigs` request of the resources that go on the
898    /// client's connection, sent again after each `NOT_CONTROLLER` answer
899    /// until the deadline.
900    async fn alter_unified(
901        &mut self,
902        resources: &BTreeMap<ConfigResource, &[AlterConfigOp]>,
903        options: IncrementalAlterConfigsOptions,
904        controllers: bool,
905    ) -> Result<IncrementalAlterConfigsResponse, KafkaError> {
906        const API: &str = "IncrementalAlterConfigs";
907        let request = alter_request(resources, options);
908        let mut retry = ControllerRetry::new(API, self.retry);
909        loop {
910            let response = retry
911                .bounded(self.conn.send(request.clone()))
912                .await
913                .map_err(|error| call_error(API, &error))?;
914            if !names_not_controller(&response, controllers) {
915                return Ok(response);
916            }
917            retry
918                .after_not_controller(self)
919                .await
920                .map_err(|error| call_error(API, &error))?;
921        }
922    }
923}
924
925#[cfg(test)]
926mod tests;