Skip to main content

krabka_client_admin/
features.rs

1//! Cluster feature administration, as Kafka's `Admin.describeFeatures` and
2//! `Admin.updateFeatures`.
3
4use std::{collections::BTreeMap, time::Duration};
5
6use krabka_protocol::owned::{
7    api_versions_request::ApiVersionsRequest,
8    api_versions_response::ApiVersionsResponse,
9    update_features_request::{FeatureUpdateKey, UpdateFeaturesRequest},
10    update_features_response::UpdateFeaturesResponse,
11};
12use krabka_units::{Time, convert::TimeExt as _};
13
14use crate::{
15    AdminClient, AdminError, KafkaError, MetadataVersionUpdate, NOT_CONTROLLER, kafka_error_if,
16    kafka_error_name,
17    log_dirs::{NodeTarget, call_node},
18    retry::{ControllerRetry, CoordinatorRetry, RetryPolicy},
19};
20
21const METADATA_VERSION_FEATURE: &str = "metadata.version";
22
23/// `UNKNOWN_SERVER_ERROR`: Kafka's code for a plain `ApiException`.
24const UNKNOWN_SERVER_ERROR: i16 = -1;
25
26/// The lowest `ApiVersions` version whose response carries features.
27const FEATURES_API_VERSIONS_MIN_VERSION: i16 = 3;
28
29/// The lowest `UpdateFeatures` version with `UpgradeType` and `ValidateOnly`.
30/// Kafka's generated `UpdateFeaturesRequestData` refuses to write either
31/// field at a non-default value at v0, where neither exists.
32const UPGRADE_TYPE_MIN_VERSION: i16 = 1;
33
34#[derive(Debug, Clone, PartialEq, Eq)]
35pub struct FeatureRange {
36    pub name: String,
37    pub min_version: i16,
38    pub max_version: i16,
39}
40
41/// The features that one node reports, as Kafka's `FeatureMetadata`.
42#[derive(Debug, Clone, PartialEq, Eq)]
43pub struct FeatureMetadata {
44    pub supported: Vec<FeatureRange>,
45    pub finalized: Vec<FeatureRange>,
46    /// The epoch of the finalized features. `None` when the node reports a
47    /// negative epoch, as Kafka's `finalizedFeaturesEpoch` is empty then.
48    pub finalized_features_epoch: Option<i64>,
49}
50
51/// What kind of change a [`FeatureUpdate`] asks for, as Kafka's
52/// `FeatureUpdate.UpgradeType`.
53#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
54pub enum UpgradeType {
55    /// Raise the finalized level only.
56    Upgrade,
57    /// Lower the finalized level, or delete the feature, only where no
58    /// metadata is lost.
59    SafeDowngrade,
60    /// Lower the finalized level, or delete the feature, even where metadata
61    /// is lost.
62    UnsafeDowngrade,
63}
64
65impl UpgradeType {
66    /// The `UpgradeType` code of the wire request: 1, 2 or 3.
67    #[must_use]
68    pub const fn code(self) -> i8 {
69        match self {
70            Self::Upgrade => 1,
71            Self::SafeDowngrade => 2,
72            Self::UnsafeDowngrade => 3,
73        }
74    }
75}
76
77/// One finalized-feature change, as Kafka's `FeatureUpdate`. The feature name
78/// is the key of the map that [`AdminClient::update_features`] takes.
79#[derive(Debug, Clone, Copy, PartialEq, Eq)]
80pub struct FeatureUpdate {
81    max_version_level: i16,
82    upgrade_type: UpgradeType,
83}
84
85impl FeatureUpdate {
86    /// A change of the feature to `max_version_level`. Level 0 deletes the
87    /// feature and needs a downgrade type.
88    ///
89    /// # Errors
90    /// Returns [`AdminError::InvalidArgument`] for level 0 with
91    /// [`UpgradeType::Upgrade`] and for a negative level, as Kafka's
92    /// constructor throws `IllegalArgumentException`.
93    pub fn new(max_version_level: i16, upgrade_type: UpgradeType) -> Result<Self, AdminError> {
94        if max_version_level == 0 && upgrade_type == UpgradeType::Upgrade {
95            return Err(AdminError::InvalidArgument(format!(
96                "The upgradeType flag should be set to SAFE_DOWNGRADE or UNSAFE_DOWNGRADE when \
97                 the provided maxVersionLevel:{max_version_level} is < 1."
98            )));
99        }
100        if max_version_level < 0 {
101            return Err(AdminError::InvalidArgument(
102                "Cannot specify a negative version level.".into(),
103            ));
104        }
105        Ok(Self {
106            max_version_level,
107            upgrade_type,
108        })
109    }
110
111    /// The new maximum finalized level.
112    #[must_use]
113    pub const fn max_version_level(&self) -> i16 {
114        self.max_version_level
115    }
116
117    /// The kind of change.
118    #[must_use]
119    pub const fn upgrade_type(&self) -> UpgradeType {
120        self.upgrade_type
121    }
122}
123
124/// Options of [`AdminClient::update_features`], as Kafka's
125/// `UpdateFeaturesOptions`.
126#[derive(Debug, Clone, Copy, Default, PartialEq, bon::Builder)]
127pub struct UpdateFeaturesOptions {
128    /// The deadline of the call, including retries. Each request carries the
129    /// time that remains as its `timeout_ms`. `None` uses the client's
130    /// `default.api.timeout.ms`.
131    #[builder(with = |millis: i64| Time::from_millis(millis))]
132    pub timeout: Option<Time>,
133    /// Ask the controller to validate the updates and apply none. Needs
134    /// `UpdateFeatures` v1.
135    #[builder(default)]
136    pub validate_only: bool,
137}
138
139/// Options of [`AdminClient::describe_features`], as Kafka's
140/// `DescribeFeaturesOptions`.
141#[derive(Debug, Clone, Copy, Default, PartialEq, bon::Builder)]
142pub struct DescribeFeaturesOptions {
143    /// The deadline of the call, including retries. `None` uses the client's
144    /// `default.api.timeout.ms`.
145    #[builder(with = |millis: i64| Time::from_millis(millis))]
146    pub timeout: Option<Time>,
147    /// The node to ask. `None` asks the node of the client's connection, as
148    /// Kafka's `LeastLoadedBrokerOrActiveKController` picks one. A node id
149    /// goes to that broker, or to that controller with a controller
150    /// bootstrap, as Kafka's `ConstantNodeIdProvider` does.
151    pub node_id: Option<i32>,
152}
153
154/// The result of each feature of an [`AdminClient::update_features`] call,
155/// as Kafka's `UpdateFeaturesResult.values`.
156pub type UpdateFeaturesResults = BTreeMap<String, Result<(), KafkaError>>;
157
158/// `base` with the call deadline `timeout`, when set.
159fn call_policy(timeout: Option<Time>, base: RetryPolicy) -> RetryPolicy {
160    match timeout {
161        Some(timeout) => RetryPolicy {
162            timeout: Duration::from_millis(u64::try_from(timeout.millis_i64()).unwrap_or(0)),
163            ..base
164        },
165        None => base,
166    }
167}
168
169/// The `UpdateFeatures` request of `updates`, as `KafkaAdminClient`'s
170/// `updateFeatures` builds it. It sets `UpgradeType` and never the v0
171/// `AllowDowngrade`, which stays `false`.
172fn update_request(
173    updates: &BTreeMap<String, FeatureUpdate>,
174    options: UpdateFeaturesOptions,
175    timeout_ms: i32,
176) -> UpdateFeaturesRequest {
177    UpdateFeaturesRequest {
178        timeout_ms,
179        feature_updates: updates
180            .iter()
181            .map(|(feature, update)| FeatureUpdateKey {
182                feature: feature.clone(),
183                max_version_level: update.max_version_level,
184                upgrade_type: update.upgrade_type.code(),
185                ..Default::default()
186            })
187            .collect(),
188        validate_only: options.validate_only,
189        ..Default::default()
190    }
191}
192
193/// The lowest `UpdateFeatures` version that can carry `updates` and
194/// `options`. Kafka's v0 serializer throws `UnsupportedVersionException` for
195/// a non-default `UpgradeType` or `ValidateOnly`, so a downgrade or a
196/// validate-only call needs v1.
197fn update_min_version(
198    updates: &BTreeMap<String, FeatureUpdate>,
199    options: UpdateFeaturesOptions,
200) -> i16 {
201    let needs_v1 = options.validate_only
202        || updates
203            .values()
204            .any(|update| update.upgrade_type != UpgradeType::Upgrade);
205    if needs_v1 {
206        UPGRADE_TYPE_MIN_VERSION
207    } else {
208        0
209    }
210}
211
212impl AdminClient {
213    /// Returns the supported and cluster-finalized feature ranges of one node,
214    /// as Kafka's `describeFeatures`.
215    ///
216    /// # Errors
217    /// Returns a transport, protocol, or broker error. With a node id, a node
218    /// that the metadata does not name, or that does not answer, is retried
219    /// until the deadline and then gives `REQUEST_TIMED_OUT` (7).
220    pub async fn describe_features(
221        &self,
222        options: DescribeFeaturesOptions,
223    ) -> Result<FeatureMetadata, AdminError> {
224        let request = ApiVersionsRequest {
225            client_software_name: "krabka-client-rs".into(),
226            client_software_version: env!("CARGO_PKG_VERSION").into(),
227            ..Default::default()
228        };
229        let policy = call_policy(options.timeout, self.retry);
230        let response = if let Some(node_id) = options.node_id {
231            call_node(
232                &self.conn,
233                NodeTarget {
234                    node_id,
235                    supports_controllers: true,
236                    min_version: Some(FEATURES_API_VERSIONS_MIN_VERSION),
237                },
238                &self.options,
239                request,
240                CoordinatorRetry::new(policy),
241            )
242            .await
243            .map_err(|error| AdminError::Broker {
244                api: "ApiVersions",
245                code: error.code,
246                name: error.name,
247                message: error.message,
248            })?
249        } else {
250            ControllerRetry::new("ApiVersions", policy)
251                .bounded(
252                    self.conn
253                        .send_at_least(request, FEATURES_API_VERSIONS_MIN_VERSION),
254                )
255                .await?
256        };
257        parse_feature_metadata(response)
258    }
259
260    /// Applies finalized-feature updates through `UpdateFeatures` on the
261    /// active controller, as Kafka's `updateFeatures`.
262    ///
263    /// Every feature of `updates` gets a result. A top-level error of the
264    /// controller fails every feature with it. A v2 response with no
265    /// per-feature results and no error succeeds every feature, and a
266    /// feature that a v0/v1 response leaves out fails with
267    /// `UNKNOWN_SERVER_ERROR`, as Kafka does.
268    ///
269    /// # Errors
270    /// Returns [`AdminError::InvalidArgument`], and sends nothing, for no
271    /// updates or a blank feature name, as Kafka throws
272    /// `IllegalArgumentException`. Returns
273    /// [`krabka_client_core::ClientError::IncompatibleVersion`] before
274    /// sending when a downgrade or [`UpdateFeaturesOptions::validate_only`]
275    /// meets a controller with only v0, as Kafka's request serializer throws
276    /// `UnsupportedVersionException`. A `NOT_CONTROLLER` answer is retried
277    /// after controller discovery until the deadline, then gives
278    /// `REQUEST_TIMED_OUT` (7). Transport errors are returned as they are.
279    pub async fn update_features(
280        &mut self,
281        updates: &BTreeMap<String, FeatureUpdate>,
282        options: UpdateFeaturesOptions,
283    ) -> Result<UpdateFeaturesResults, AdminError> {
284        if updates.is_empty() {
285            return Err(AdminError::InvalidArgument(
286                "Feature updates can not be null or empty.".into(),
287            ));
288        }
289        if updates.keys().any(|feature| feature.trim().is_empty()) {
290            return Err(AdminError::InvalidArgument(
291                "Provided feature can not be empty.".into(),
292            ));
293        }
294        let min_version = update_min_version(updates, options);
295        let mut retry =
296            ControllerRetry::new("UpdateFeatures", call_policy(options.timeout, self.retry));
297        loop {
298            let request = update_request(updates, options, retry.remaining_millis());
299            let response = retry
300                .bounded(self.conn.send_at_least(request, min_version))
301                .await?;
302            if response.error_code != NOT_CONTROLLER {
303                return Ok(update_results(updates, response));
304            }
305            retry.after_not_controller(self).await?;
306        }
307    }
308
309    /// Finalize `metadata.version` at `level` through `UpdateFeatures`.
310    ///
311    /// # Errors
312    /// Returns a transport, protocol, or broker error when Kafka rejects the
313    /// requested level.
314    pub async fn update_metadata_version(
315        &mut self,
316        level: i16,
317        upgrade_type: UpgradeType,
318        timeout: Time,
319    ) -> Result<MetadataVersionUpdate, AdminError> {
320        let updates = maplit::btreemap! {
321            METADATA_VERSION_FEATURE.to_owned() => FeatureUpdate::new(level, upgrade_type)?,
322        };
323        let results = self
324            .update_features(
325                &updates,
326                UpdateFeaturesOptions::builder()
327                    .timeout(timeout.millis_i64())
328                    .validate_only(false)
329                    .build(),
330            )
331            .await?;
332        if let Some(Err(error)) = results.into_values().next() {
333            return Err(AdminError::Broker {
334                api: "UpdateFeatures",
335                code: error.code,
336                name: error.name,
337                message: error.message,
338            });
339        }
340        Ok(MetadataVersionUpdate { level })
341    }
342}
343
344fn parse_feature_metadata(response: ApiVersionsResponse) -> Result<FeatureMetadata, AdminError> {
345    if response.error_code != 0 {
346        return Err(AdminError::Broker {
347            api: "ApiVersions",
348            code: response.error_code,
349            name: kafka_error_name(response.error_code),
350            message: None,
351        });
352    }
353    Ok(FeatureMetadata {
354        supported: response
355            .supported_features
356            .into_iter()
357            .map(|feature| FeatureRange {
358                name: feature.name,
359                min_version: feature.min_version,
360                max_version: feature.max_version,
361            })
362            .collect(),
363        finalized: response
364            .finalized_features
365            .into_iter()
366            .map(|feature| FeatureRange {
367                name: feature.name,
368                min_version: feature.min_version_level,
369                max_version: feature.max_version_level,
370            })
371            .collect(),
372        finalized_features_epoch: (response.finalized_features_epoch >= 0)
373            .then_some(response.finalized_features_epoch),
374    })
375}
376
377/// The result of each feature of `updates` from `response`, as
378/// `KafkaAdminClient`'s `updateFeatures` completes its futures.
379fn update_results(
380    updates: &BTreeMap<String, FeatureUpdate>,
381    response: UpdateFeaturesResponse,
382) -> UpdateFeaturesResults {
383    if let Some(error) = kafka_error_if(response.error_code, response.error_message) {
384        return updates
385            .keys()
386            .map(|feature| (feature.clone(), Err(error.clone())))
387            .collect();
388    }
389    if response.results.is_empty() {
390        return updates
391            .keys()
392            .map(|feature| (feature.clone(), Ok(())))
393            .collect();
394    }
395    let mut results = BTreeMap::new();
396    for result in response.results {
397        if !updates.contains_key(&result.feature) {
398            tracing::warn!(
399                feature = %result.feature,
400                "server response mentioned unknown feature"
401            );
402            continue;
403        }
404        let outcome = match kafka_error_if(result.error_code, result.error_message) {
405            Some(error) => Err(error),
406            None => Ok(()),
407        };
408        results.insert(result.feature, outcome);
409    }
410    for feature in updates.keys() {
411        results.entry(feature.clone()).or_insert_with(|| {
412            Err(KafkaError {
413                code: UNKNOWN_SERVER_ERROR,
414                name: kafka_error_name(UNKNOWN_SERVER_ERROR),
415                message: Some(format!(
416                    "The controller response did not contain a result for feature {feature}"
417                )),
418            })
419        });
420    }
421    results
422}
423
424#[cfg(test)]
425mod tests {
426    use std::{
427        net::SocketAddr,
428        sync::{Arc, Mutex},
429    };
430
431    use krabka_client_core::{ClientError, MockBroker, MockReply};
432    use krabka_protocol::owned::{
433        api_versions_request,
434        api_versions_response::{ApiVersion, FinalizedFeatureKey, SupportedFeatureKey},
435        metadata_request,
436        metadata_response::{MetadataResponse, MetadataResponseBroker},
437        update_features_request,
438        update_features_response::UpdatableFeatureResult,
439    };
440
441    use super::*;
442    use crate::partition_leaders::test_support::{
443        ApiVersionRange, api_versions, decode_request, encode_response, fast_admin,
444    };
445
446    fn update(level: i16, upgrade_type: UpgradeType) -> FeatureUpdate {
447        FeatureUpdate::new(level, upgrade_type).expect("valid update")
448    }
449
450    fn key(feature: &str, max_version_level: i16, upgrade_type: i8) -> FeatureUpdateKey {
451        FeatureUpdateKey {
452            feature: feature.into(),
453            max_version_level,
454            upgrade_type,
455            ..Default::default()
456        }
457    }
458
459    fn error(code: i16, message: Option<&str>) -> KafkaError {
460        KafkaError {
461            code,
462            name: kafka_error_name(code),
463            message: message.map(Into::into),
464        }
465    }
466
467    #[test]
468    fn feature_update_refuses_what_kafka_refuses() {
469        for (name, level, upgrade_type, ok) in [
470            ("upgrade to 1", 1, UpgradeType::Upgrade, true),
471            ("safe delete", 0, UpgradeType::SafeDowngrade, true),
472            ("unsafe delete", 0, UpgradeType::UnsafeDowngrade, true),
473            ("upgrade to 0", 0, UpgradeType::Upgrade, false),
474            ("negative level", -1, UpgradeType::SafeDowngrade, false),
475        ] {
476            let result = FeatureUpdate::new(level, upgrade_type);
477            match (ok, result) {
478                (true, Ok(update)) => assert2::assert!(
479                    (update.max_version_level(), update.upgrade_type()) == (level, upgrade_type),
480                    "case {name}"
481                ),
482                (false, Err(AdminError::InvalidArgument(_))) => {}
483                (_, other) => panic!("case {name}: {other:?}"),
484            }
485        }
486    }
487
488    #[test]
489    fn upgrade_type_codes_match_kafka() {
490        assert2::assert!(
491            [
492                UpgradeType::Upgrade.code(),
493                UpgradeType::SafeDowngrade.code(),
494                UpgradeType::UnsafeDowngrade.code(),
495            ] == [1, 2, 3]
496        );
497    }
498
499    #[test]
500    fn describe_features_preserves_supported_finalized_and_epoch() {
501        for (name, epoch, expected_epoch) in
502            [("finalized", 7, Some(7)), ("no finalized epoch", -1, None)]
503        {
504            let metadata = parse_feature_metadata(ApiVersionsResponse {
505                supported_features: vec![SupportedFeatureKey {
506                    name: "kraft.version".into(),
507                    min_version: 0,
508                    max_version: 1,
509                    ..Default::default()
510                }],
511                finalized_features: vec![FinalizedFeatureKey {
512                    name: "kraft.version".into(),
513                    min_version_level: 1,
514                    max_version_level: 1,
515                    ..Default::default()
516                }],
517                finalized_features_epoch: epoch,
518                ..Default::default()
519            })
520            .unwrap();
521            assert2::assert!(
522                metadata
523                    == FeatureMetadata {
524                        supported: vec![FeatureRange {
525                            name: "kraft.version".into(),
526                            min_version: 0,
527                            max_version: 1,
528                        }],
529                        finalized: vec![FeatureRange {
530                            name: "kraft.version".into(),
531                            min_version: 1,
532                            max_version: 1,
533                        }],
534                        finalized_features_epoch: expected_epoch,
535                    },
536                "case {name}"
537            );
538        }
539    }
540
541    #[test]
542    fn update_results_complete_every_feature_as_kafka_does() {
543        let updates = maplit::btreemap! {
544            "group.version".to_owned() => update(1, UpgradeType::Upgrade),
545            "metadata.version".to_owned() => update(20, UpgradeType::Upgrade),
546        };
547        let row = |feature: &str, error_code, message: Option<&str>| UpdatableFeatureResult {
548            feature: feature.into(),
549            error_code,
550            error_message: message.map(Into::into),
551            ..Default::default()
552        };
553        let missing = "The controller response did not contain a result for feature \
554                       metadata.version";
555        for (name, response, expected) in [
556            (
557                "v2 success has no rows",
558                UpdateFeaturesResponse::default(),
559                [Ok(()), Ok(())],
560            ),
561            (
562                "top-level error fails every feature",
563                UpdateFeaturesResponse {
564                    error_code: 95,
565                    error_message: Some("bad".into()),
566                    ..Default::default()
567                },
568                [Err(error(95, Some("bad"))), Err(error(95, Some("bad")))],
569            ),
570            (
571                "per-feature rows, one missing, one unknown",
572                UpdateFeaturesResponse {
573                    results: vec![
574                        row("group.version", 95, Some("no")),
575                        row("other.version", 0, None),
576                    ],
577                    ..Default::default()
578                },
579                [
580                    Err(error(95, Some("no"))),
581                    Err(error(UNKNOWN_SERVER_ERROR, Some(missing))),
582                ],
583            ),
584        ] {
585            let [group, metadata] = expected;
586            assert2::assert!(
587                update_results(&updates, response)
588                    == maplit::btreemap! {
589                        "group.version".to_owned() => group,
590                        "metadata.version".to_owned() => metadata,
591                    },
592                "case {name}"
593            );
594        }
595    }
596
597    /// A broker that advertises `UpdateFeatures` v0 up to `max_version`,
598    /// records each `UpdateFeatures` request with its version, and answers
599    /// with no error.
600    async fn update_features_broker(
601        max_version: i16,
602        seen: Arc<Mutex<Vec<(i16, UpdateFeaturesRequest)>>>,
603    ) -> MockBroker {
604        MockBroker::start(move |api_key, version, _, body| match api_key {
605            api_versions_request::API_KEY => Some(
606                api_versions()
607                    .apis(vec![
608                        ApiVersionRange::builder()
609                            .api_key(update_features_request::API_KEY)
610                            .max_version(max_version)
611                            .build(),
612                    ])
613                    .call(),
614            ),
615            update_features_request::API_KEY => {
616                let mut request: UpdateFeaturesRequest = decode_request(body, version, true);
617                // The deadline that remains differs between runs.
618                request.timeout_ms = 0;
619                seen.lock().expect("seen lock").push((version, request));
620                Some(encode_response(
621                    &UpdateFeaturesResponse::default(),
622                    version,
623                    true,
624                ))
625            }
626            _ => None,
627        })
628        .await
629    }
630
631    /// The whole `UpdateFeatures` request that reaches the controller, for
632    /// each version the controller advertises, each upgrade type and each
633    /// `validate_only`. A downgrade or a validate-only call is refused
634    /// before sending against a v0-only controller, as Kafka's v0 serializer
635    /// throws `UnsupportedVersionException` for a non-default `UpgradeType`
636    /// or `ValidateOnly`. `AllowDowngrade` is never set, as Kafka never sets
637    /// it.
638    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
639    async fn update_features_sends_kafkas_request_per_version() {
640        let upgrade_types = [
641            UpgradeType::Upgrade,
642            UpgradeType::SafeDowngrade,
643            UpgradeType::UnsafeDowngrade,
644        ];
645        for max_version in 0..=2 {
646            for upgrade_type in upgrade_types {
647                for validate_only in [false, true] {
648                    let name = format!("v{max_version} {upgrade_type:?} validate={validate_only}");
649                    let seen = Arc::new(Mutex::new(Vec::new()));
650                    let broker = update_features_broker(max_version, Arc::clone(&seen)).await;
651                    let mut admin = AdminClient::connect(&[broker.addr.to_string()])
652                        .await
653                        .expect("admin connects");
654                    let level = if upgrade_type == UpgradeType::Upgrade {
655                        7
656                    } else {
657                        0
658                    };
659                    let updates = maplit::btreemap! {
660                        "group.version".to_owned() => update(1, upgrade_type),
661                        "share.version".to_owned() => update(level, upgrade_type),
662                    };
663
664                    let result = admin
665                        .update_features(
666                            &updates,
667                            UpdateFeaturesOptions::builder()
668                                .validate_only(validate_only)
669                                .build(),
670                        )
671                        .await;
672                    broker.stop();
673
674                    let sendable = max_version >= 1
675                        || (upgrade_type == UpgradeType::Upgrade && !validate_only);
676                    if !sendable {
677                        assert2::assert!(
678                            matches!(
679                                result,
680                                Err(AdminError::Transport(ClientError::IncompatibleVersion {
681                                    api_key: update_features_request::API_KEY,
682                                    client_min: 1,
683                                    ..
684                                }))
685                            ),
686                            "case {name}: {result:?}"
687                        );
688                        assert2::assert!(seen.lock().unwrap().is_empty(), "case {name}");
689                        continue;
690                    }
691                    let code = upgrade_type.code();
692                    // v0 carries neither field, so it decodes as the defaults.
693                    let (wire_code, wire_validate) = if max_version == 0 {
694                        (1, false)
695                    } else {
696                        (code, validate_only)
697                    };
698                    assert2::assert!(
699                        result.expect("update succeeds")
700                            == maplit::btreemap! {
701                                "group.version".to_owned() => Ok(()),
702                                "share.version".to_owned() => Ok(()),
703                            },
704                        "case {name}"
705                    );
706                    assert2::assert!(
707                        *seen.lock().unwrap()
708                            == vec![(
709                                max_version,
710                                UpdateFeaturesRequest {
711                                    timeout_ms: 0,
712                                    feature_updates: vec![
713                                        key("group.version", 1, wire_code),
714                                        key("share.version", level, wire_code),
715                                    ],
716                                    validate_only: wire_validate,
717                                    ..Default::default()
718                                }
719                            )],
720                        "case {name}"
721                    );
722                }
723            }
724        }
725    }
726
727    #[tokio::test]
728    async fn update_features_refuses_empty_or_blank_features_before_sending() {
729        let broker = MockBroker::start(|api_key, _, _, _| {
730            (api_key == api_versions_request::API_KEY).then(|| {
731                api_versions()
732                    .apis(vec![
733                        ApiVersionRange::builder()
734                            .api_key(update_features_request::API_KEY)
735                            .max_version(2)
736                            .build(),
737                    ])
738                    .call()
739            })
740        })
741        .await;
742        let mut admin = AdminClient::connect(&[broker.addr.to_string()])
743            .await
744            .expect("admin connects");
745        for (name, updates) in [
746            ("empty", BTreeMap::new()),
747            (
748                "blank",
749                maplit::btreemap! {
750                    " ".to_owned() => update(1, UpgradeType::Upgrade),
751                },
752            ),
753        ] {
754            let result = admin
755                .update_features(&updates, UpdateFeaturesOptions::builder().build())
756                .await;
757            assert2::assert!(
758                matches!(result, Err(AdminError::InvalidArgument(_))),
759                "case {name}"
760            );
761        }
762        broker.stop();
763    }
764
765    /// A broker `node_id` that answers `ApiVersions` with `supported` as its
766    /// one supported feature, and `Metadata` with `nodes`.
767    async fn feature_node(
768        supported: &'static str,
769        nodes: Arc<Mutex<Vec<(i32, SocketAddr)>>>,
770    ) -> MockBroker {
771        MockBroker::start_with_replies(move |api_key, version, _, _| match api_key {
772            api_versions_request::API_KEY => MockReply::Respond(encode_response(
773                &ApiVersionsResponse {
774                    api_keys: vec![
775                        ApiVersion {
776                            api_key: api_versions_request::API_KEY,
777                            min_version: 0,
778                            max_version: 4,
779                            ..Default::default()
780                        },
781                        ApiVersion {
782                            api_key: metadata_request::API_KEY,
783                            min_version: 12,
784                            max_version: 12,
785                            ..Default::default()
786                        },
787                    ],
788                    supported_features: vec![SupportedFeatureKey {
789                        name: supported.into(),
790                        min_version: 0,
791                        max_version: 1,
792                        ..Default::default()
793                    }],
794                    finalized_features_epoch: 3,
795                    ..Default::default()
796                },
797                version,
798                false,
799            )),
800            metadata_request::API_KEY => MockReply::Respond(encode_response(
801                &MetadataResponse {
802                    controller_id: 1,
803                    brokers: nodes
804                        .lock()
805                        .expect("nodes lock")
806                        .iter()
807                        .map(|(node_id, addr)| MetadataResponseBroker {
808                            node_id: *node_id,
809                            host: addr.ip().to_string(),
810                            port: i32::from(addr.port()),
811                            ..Default::default()
812                        })
813                        .collect(),
814                    ..Default::default()
815                },
816                version,
817                true,
818            )),
819            _ => MockReply::Silent,
820        })
821        .await
822    }
823
824    /// `describe_features` asks the node of the client's connection, or the
825    /// node that `node_id` names, as Kafka's `describeFeatures` with a
826    /// `DescribeFeaturesOptions.nodeId` does for `kafka-features describe
827    /// --node-id`.
828    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
829    async fn describe_features_asks_the_named_node() {
830        let nodes = Arc::new(Mutex::new(Vec::new()));
831        let first = feature_node("on.node.1", Arc::clone(&nodes)).await;
832        let second = feature_node("on.node.2", Arc::clone(&nodes)).await;
833        *nodes.lock().unwrap() = vec![(1, first.addr), (2, second.addr)];
834        let admin = fast_admin(first.addr, krabka_units::secs(5)).await;
835
836        for (name, node_id, feature) in [
837            ("any node", None, "on.node.1"),
838            ("node 1", Some(1), "on.node.1"),
839            ("node 2", Some(2), "on.node.2"),
840        ] {
841            let metadata = admin
842                .describe_features(
843                    DescribeFeaturesOptions::builder()
844                        .maybe_node_id(node_id)
845                        .build(),
846                )
847                .await
848                .expect("describe succeeds");
849            assert2::assert!(
850                metadata
851                    == FeatureMetadata {
852                        supported: vec![FeatureRange {
853                            name: feature.into(),
854                            min_version: 0,
855                            max_version: 1,
856                        }],
857                        finalized: Vec::new(),
858                        finalized_features_epoch: Some(3),
859                    },
860                "case {name}"
861            );
862        }
863
864        let unknown = admin
865            .describe_features(
866                DescribeFeaturesOptions::builder()
867                    .timeout(50)
868                    .node_id(9)
869                    .build(),
870            )
871            .await;
872        assert2::assert!(
873            matches!(
874                unknown,
875                Err(AdminError::Broker {
876                    code: crate::retry::REQUEST_TIMED_OUT,
877                    ..
878                })
879            ),
880            "{unknown:?}"
881        );
882        first.stop();
883        second.stop();
884    }
885
886    #[tokio::test]
887    async fn update_metadata_version_surfaces_the_feature_error() {
888        let broker = MockBroker::start(|api_key, version, _, _| match api_key {
889            api_versions_request::API_KEY => Some(
890                api_versions()
891                    .apis(vec![
892                        ApiVersionRange::builder()
893                            .api_key(update_features_request::API_KEY)
894                            .max_version(1)
895                            .build(),
896                    ])
897                    .call(),
898            ),
899            update_features_request::API_KEY => Some(encode_response(
900                &UpdateFeaturesResponse {
901                    results: vec![UpdatableFeatureResult {
902                        feature: METADATA_VERSION_FEATURE.into(),
903                        error_code: 95,
904                        error_message: Some("not supported by every broker".into()),
905                        ..Default::default()
906                    }],
907                    ..Default::default()
908                },
909                version,
910                true,
911            )),
912            _ => None,
913        })
914        .await;
915        let mut admin = AdminClient::connect(&[broker.addr.to_string()])
916            .await
917            .expect("admin connects");
918        let result = admin
919            .update_metadata_version(15, UpgradeType::SafeDowngrade, krabka_units::secs(5))
920            .await;
921        broker.stop();
922        assert2::assert!(
923            matches!(
924                result,
925                Err(AdminError::Broker {
926                    api: "UpdateFeatures",
927                    code: 95,
928                    ..
929                })
930            ),
931            "{result:?}"
932        );
933    }
934}