Skip to main content

krabka_client_admin/
elections.rs

1//! Leader elections (`ElectLeaders`, KIP-183 and KIP-460), as Kafka's
2//! `Admin.electLeaders`.
3
4use std::collections::BTreeMap;
5
6use krabka_protocol::owned::{
7    elect_leaders_request::{ElectLeadersRequest, TopicPartitions},
8    elect_leaders_response::ElectLeadersResponse,
9};
10
11use crate::{
12    AdminClient, AdminError, KafkaError, NOT_CONTROLLER, kafka_error_name, retry::ControllerRetry,
13};
14
15/// Which replica an election makes the leader, as Kafka's `ElectionType`.
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub enum ElectionType {
18    /// The preferred replica, the first of the assignment, when it is in
19    /// sync (KIP-183).
20    Preferred,
21    /// Any live replica, even one that is out of sync, when no in-sync
22    /// replica is live (KIP-460). Needs `ElectLeaders` v1.
23    Unclean,
24}
25
26impl ElectionType {
27    const fn wire(self) -> i8 {
28        match self {
29            Self::Preferred => 0,
30            Self::Unclean => 1,
31        }
32    }
33}
34
35/// The election result of each `(topic, partition)`, as Kafka's
36/// `ElectLeadersResult.partitions`: `Ok` for an elected leader, or the
37/// partition's error.
38pub type ElectionResults = BTreeMap<(String, i32), Result<(), KafkaError>>;
39
40/// The `ElectLeaders` request of `partitions`, grouped by topic, as Kafka's
41/// `ElectLeadersRequest.Builder` builds it. `None` asks for every partition
42/// of the cluster (a null `topic_partitions`).
43fn elect_leaders_request(
44    election_type: ElectionType,
45    partitions: Option<&[(String, i32)]>,
46    timeout_ms: i32,
47) -> ElectLeadersRequest {
48    let topic_partitions = partitions.map(|partitions| {
49        let mut by_topic = BTreeMap::<&str, Vec<i32>>::new();
50        for (topic, partition) in partitions {
51            let entry = by_topic.entry(topic.as_str()).or_default();
52            if !entry.contains(partition) {
53                entry.push(*partition);
54            }
55        }
56        by_topic
57            .into_iter()
58            .map(|(topic, partitions)| TopicPartitions {
59                topic: topic.to_owned(),
60                partitions,
61                ..Default::default()
62            })
63            .collect()
64    });
65    ElectLeadersRequest {
66        election_type: election_type.wire(),
67        topic_partitions,
68        timeout_ms,
69        ..Default::default()
70    }
71}
72
73/// Whether Kafka's `handleNotControllerError` finds the controller again
74/// after this answer: its top-level code or a partition code is
75/// `NOT_CONTROLLER`.
76fn names_not_controller(response: &ElectLeadersResponse) -> bool {
77    response.error_code == NOT_CONTROLLER
78        || response
79            .replica_election_results
80            .iter()
81            .flat_map(|topic| &topic.partition_result)
82            .any(|partition| partition.error_code == NOT_CONTROLLER)
83}
84
85/// Maps an `ElectLeaders` answer to the result of each partition, as Kafka's
86/// `ElectLeadersResponse.electLeadersResult` does. A top-level error fails
87/// the whole call.
88fn elect_leaders_results(response: ElectLeadersResponse) -> Result<ElectionResults, AdminError> {
89    if response.error_code != 0 {
90        return Err(AdminError::Broker {
91            api: "ElectLeaders",
92            code: response.error_code,
93            name: kafka_error_name(response.error_code),
94            message: None,
95        });
96    }
97    Ok(response
98        .replica_election_results
99        .into_iter()
100        .flat_map(|topic| {
101            let name = topic.topic;
102            topic.partition_result.into_iter().map(move |partition| {
103                let result = if partition.error_code == 0 {
104                    Ok(())
105                } else {
106                    Err(KafkaError {
107                        code: partition.error_code,
108                        name: kafka_error_name(partition.error_code),
109                        message: partition.error_message,
110                    })
111                };
112                ((name.clone(), partition.partition_id), result)
113            })
114        })
115        .collect())
116}
117
118impl AdminClient {
119    /// Elects a leader for each partition of `partitions`, or of every
120    /// partition of the cluster for `None`, as Kafka's `electLeaders`
121    /// operation does.
122    ///
123    /// The client sends `ElectLeaders` to the controller connection, as
124    /// Kafka's `KafkaAdminClient` sends it with a `ControllerNodeProvider`,
125    /// with the time left before the call deadline as its `timeout_ms`.
126    /// [`ElectionType::Unclean`] needs `ElectLeaders` v1, so the client
127    /// negotiates v1 or higher for it, as Kafka's builder refuses v0.
128    ///
129    /// `NOT_CONTROLLER` (41), top-level or on any partition, makes the
130    /// client find the controller again and resend the request with the
131    /// backoff, until Kafka's default `default.api.timeout.ms` (60 s).
132    ///
133    /// The result has an entry for each partition that the controller
134    /// answered for. A partition that needed no election gets
135    /// `ELECTION_NOT_NEEDED` (84), as Kafka gives an
136    /// `ElectionNotNeededException`.
137    ///
138    /// # Errors
139    ///
140    /// Returns [`AdminError::Broker`] for a top-level error, such as
141    /// `CLUSTER_AUTHORIZATION_FAILED` (31), and with `REQUEST_TIMED_OUT` (7)
142    /// at the deadline. Returns [`AdminError::Transport`] when the
143    /// connection fails, or when the controller does not support the
144    /// `ElectLeaders` version that `election_type` needs.
145    pub async fn elect_leaders(
146        &mut self,
147        election_type: ElectionType,
148        partitions: Option<&[(String, i32)]>,
149    ) -> Result<ElectionResults, AdminError> {
150        let mut retry = ControllerRetry::new("ElectLeaders", self.retry);
151        loop {
152            let request =
153                elect_leaders_request(election_type, partitions, retry.remaining_millis());
154            let response = match election_type {
155                ElectionType::Preferred => retry.bounded(self.conn.send(request)).await?,
156                ElectionType::Unclean => retry.bounded(self.conn.send_at_least(request, 1)).await?,
157            };
158            if !names_not_controller(&response) {
159                return elect_leaders_results(response);
160            }
161            retry.after_not_controller(self).await?;
162        }
163    }
164}
165
166#[cfg(test)]
167mod tests {
168    use std::sync::{
169        Arc, Mutex,
170        atomic::{AtomicU16, Ordering},
171    };
172
173    use krabka_client_core::MockBroker;
174    use krabka_protocol::owned::{
175        api_versions_request, elect_leaders_request,
176        elect_leaders_response::{PartitionResult, ReplicaElectionResult},
177        metadata_request,
178    };
179
180    use super::*;
181    use crate::partition_leaders::test_support::{
182        ApiVersionRange, api_versions, decode_request, encode_response, fast_admin, orders_metadata,
183    };
184
185    fn orders(partitions: &[i32]) -> Vec<(String, i32)> {
186        partitions
187            .iter()
188            .map(|partition| ("orders".to_owned(), *partition))
189            .collect()
190    }
191
192    #[test]
193    fn request_groups_partitions_by_topic_or_asks_for_all() {
194        let keys = vec![
195            ("orders".to_owned(), 1),
196            ("audit".to_owned(), 0),
197            ("orders".to_owned(), 0),
198            ("orders".to_owned(), 1),
199        ];
200        for (name, election_type, partitions, expected) in [
201            (
202                "preferred for listed partitions",
203                ElectionType::Preferred,
204                Some(keys.as_slice()),
205                ElectLeadersRequest {
206                    election_type: 0,
207                    topic_partitions: Some(vec![
208                        TopicPartitions {
209                            topic: "audit".to_owned(),
210                            partitions: vec![0],
211                            ..Default::default()
212                        },
213                        TopicPartitions {
214                            topic: "orders".to_owned(),
215                            partitions: vec![1, 0],
216                            ..Default::default()
217                        },
218                    ]),
219                    timeout_ms: 30_000,
220                    ..Default::default()
221                },
222            ),
223            (
224                "unclean for every partition",
225                ElectionType::Unclean,
226                None,
227                ElectLeadersRequest {
228                    election_type: 1,
229                    topic_partitions: None,
230                    timeout_ms: 30_000,
231                    ..Default::default()
232                },
233            ),
234        ] {
235            assert2::assert!(
236                elect_leaders_request(election_type, partitions, 30_000) == expected,
237                "case {name}"
238            );
239        }
240    }
241
242    /// An `ElectLeaders` answer with `top_code` and `code` on `orders`-0.
243    fn election_answer(top_code: i16, code: i16) -> ElectLeadersResponse {
244        ElectLeadersResponse {
245            error_code: top_code,
246            replica_election_results: vec![ReplicaElectionResult {
247                topic: "orders".to_owned(),
248                partition_result: vec![PartitionResult {
249                    partition_id: 0,
250                    error_code: code,
251                    error_message: (code != 0).then(|| "no election".to_owned()),
252                    ..Default::default()
253                }],
254                ..Default::default()
255            }],
256            ..Default::default()
257        }
258    }
259
260    /// Kafka's `electLeaders` maps each partition code to its own result,
261    /// fails the call on a top-level code, and finds the controller again
262    /// after `NOT_CONTROLLER`.
263    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
264    async fn elect_leaders_retries_not_controller_and_maps_each_partition() {
265        let not_needed = Err(KafkaError {
266            code: 84,
267            name: "ELECTION_NOT_NEEDED",
268            message: Some("no election".to_owned()),
269        });
270        for (name, election_type, answers, expected) in [
271            (
272                "success",
273                ElectionType::Preferred,
274                vec![(0, 0)],
275                (
276                    Ok(maplit::btreemap! {
277                        ("orders".to_owned(), 0) => Ok(()),
278                    }),
279                    1,
280                ),
281            ),
282            (
283                "election not needed is a partition result",
284                ElectionType::Unclean,
285                vec![(0, 84)],
286                (
287                    Ok(maplit::btreemap! {
288                        ("orders".to_owned(), 0) => not_needed,
289                    }),
290                    1,
291                ),
292            ),
293            (
294                "not controller finds the controller again",
295                ElectionType::Preferred,
296                vec![(41, 0), (0, NOT_CONTROLLER), (0, 0)],
297                (
298                    Ok(maplit::btreemap! {
299                        ("orders".to_owned(), 0) => Ok(()),
300                    }),
301                    3,
302                ),
303            ),
304            (
305                "cluster authorization failed is final",
306                ElectionType::Preferred,
307                vec![(31, 0)],
308                (Err(("ElectLeaders", 31)), 1),
309            ),
310        ] {
311            let requests = Arc::new(Mutex::new(Vec::<(i16, ElectLeadersRequest)>::new()));
312            let handler_requests = Arc::clone(&requests);
313            let port = Arc::new(AtomicU16::new(0));
314            let handler_port = Arc::clone(&port);
315            let broker = MockBroker::start(move |api_key, version, _, body| {
316                let own = std::net::SocketAddr::from((
317                    [127, 0, 0, 1],
318                    handler_port.load(Ordering::SeqCst),
319                ));
320                match api_key {
321                    api_versions_request::API_KEY => Some(
322                        api_versions()
323                            .apis(vec![
324                                ApiVersionRange::builder()
325                                    .api_key(elect_leaders_request::API_KEY)
326                                    .max_version(2)
327                                    .build(),
328                            ])
329                            .call(),
330                    ),
331                    metadata_request::API_KEY => {
332                        Some(encode_response(&orders_metadata(own), version, true))
333                    }
334                    elect_leaders_request::API_KEY => {
335                        let flexible = version >= elect_leaders_request::FLEXIBLE_MIN;
336                        let mut requests = handler_requests.lock().expect("requests lock");
337                        let (top, code) = answers[requests.len().min(answers.len() - 1)];
338                        requests.push((version, decode_request(body, version, flexible)));
339                        Some(encode_response(
340                            &election_answer(top, code),
341                            version,
342                            flexible,
343                        ))
344                    }
345                    _ => None,
346                }
347            })
348            .await;
349            port.store(broker.addr.port(), Ordering::SeqCst);
350            let mut admin = fast_admin(broker.addr, krabka_units::secs(5)).await;
351
352            let result = admin
353                .elect_leaders(election_type, Some(&orders(&[0])))
354                .await
355                .map_err(|error| match error {
356                    AdminError::Broker { api, code, .. } => (api, code),
357                    other => panic!("case {name}: unexpected error {other:?}"),
358                });
359
360            broker.stop();
361            let requests = requests.lock().expect("requests lock");
362            let shapes = requests
363                .iter()
364                .map(|(version, request)| {
365                    (
366                        *version,
367                        ElectLeadersRequest {
368                            timeout_ms: 0,
369                            ..request.clone()
370                        },
371                    )
372                })
373                .collect::<Vec<_>>();
374            let expected_shape = (
375                2,
376                elect_leaders_request(election_type, Some(&orders(&[0])), 0),
377            );
378            assert2::assert!(
379                (result, shapes) == (expected.0, vec![expected_shape; expected.1]),
380                "case {name}"
381            );
382            assert2::assert!(
383                requests
384                    .iter()
385                    .all(|(_, request)| (1..=5_000).contains(&request.timeout_ms)),
386                "case {name}: the timeout is the time left of the call"
387            );
388        }
389    }
390
391    /// Kafka's `ElectLeadersRequest.Builder` refuses an unclean election
392    /// below v1, so a controller with v0 only fails the call before it sends
393    /// anything.
394    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
395    async fn unclean_election_needs_elect_leaders_v1() {
396        let requests = Arc::new(Mutex::new(0_usize));
397        let handler_requests = Arc::clone(&requests);
398        let broker = MockBroker::start(move |api_key, version, _, _| match api_key {
399            api_versions_request::API_KEY => Some(
400                api_versions()
401                    .apis(vec![
402                        ApiVersionRange::builder()
403                            .api_key(elect_leaders_request::API_KEY)
404                            .build(),
405                    ])
406                    .call(),
407            ),
408            elect_leaders_request::API_KEY => {
409                *handler_requests.lock().expect("requests lock") += 1;
410                Some(encode_response(&election_answer(0, 0), version, false))
411            }
412            _ => None,
413        })
414        .await;
415        let mut admin = fast_admin(broker.addr, krabka_units::secs(5)).await;
416
417        let result = admin
418            .elect_leaders(ElectionType::Unclean, Some(&orders(&[0])))
419            .await;
420
421        broker.stop();
422        assert2::assert!(matches!(
423            result,
424            Err(AdminError::Transport(
425                krabka_client_core::ClientError::IncompatibleVersion { .. }
426            ))
427        ));
428        assert2::assert!(*requests.lock().expect("requests lock") == 0);
429    }
430}