Skip to main content

krabka_client_admin/
brokers.rs

1//! Broker and controller registration administration.
2
3use krabka_protocol::owned::{
4    unregister_broker_request::UnregisterBrokerRequest,
5    unregister_controller_request::UnregisterControllerRequest,
6};
7
8use crate::{
9    AdminClient, AdminError, kafka_error_name,
10    retry::{ControllerRetry, REQUEST_TIMED_OUT, RetryPolicy},
11};
12
13impl AdminClient {
14    /// Unregisters one broker from the active `KRaft` controller.
15    ///
16    /// Kafka's `KafkaAdminClient.unregisterBroker` retries
17    /// `REQUEST_TIMED_OUT` (7) with the retry backoff until the call deadline
18    /// (`default.api.timeout.ms`, 60 s), and fails at once on every other
19    /// code, `NOT_CONTROLLER` (41) too. This call does the same.
20    ///
21    /// # Errors
22    /// Returns a transport, protocol, or broker error. At the deadline it
23    /// gives `REQUEST_TIMED_OUT` (7).
24    pub async fn unregister_broker(&mut self, broker_id: i32) -> Result<(), AdminError> {
25        self.unregister_broker_with_retry(broker_id, self.retry)
26            .await
27    }
28
29    /// Unregisters one controller from the active `KRaft` controller, with
30    /// an `UnregisterController` request (API key 94).
31    ///
32    /// This is Kafka's `Admin.unregisterController`. Like
33    /// `KafkaAdminClient.unregisterBroker`, it goes to a broker of a broker
34    /// connection or to the active controller of a controller connection. It
35    /// retries `REQUEST_TIMED_OUT` (7) with the retry backoff until the call
36    /// deadline, and fails at once on every other code: `NOT_CONTROLLER`
37    /// (41), `INVALID_REQUEST` (42) for a controller in the voter set, and
38    /// `CONTROLLER_ID_NOT_REGISTERED` (136).
39    ///
40    /// # Errors
41    /// Returns a transport, protocol, or broker error. At the deadline it
42    /// gives `REQUEST_TIMED_OUT` (7).
43    pub async fn unregister_controller(&mut self, controller_id: i32) -> Result<(), AdminError> {
44        self.unregister_controller_with_retry(controller_id, self.retry)
45            .await
46    }
47
48    async fn unregister_broker_with_retry(
49        &mut self,
50        broker_id: i32,
51        policy: RetryPolicy,
52    ) -> Result<(), AdminError> {
53        let request = UnregisterBrokerRequest {
54            broker_id,
55            ..Default::default()
56        };
57        let mut retry = ControllerRetry::new("UnregisterBroker", policy);
58        loop {
59            let response = retry.bounded(self.conn.send(request.clone())).await?;
60            if response.error_code != REQUEST_TIMED_OUT {
61                return unregister_error(
62                    "UnregisterBroker",
63                    response.error_code,
64                    response.error_message,
65                );
66            }
67            retry.after_retriable("REQUEST_TIMED_OUT").await?;
68        }
69    }
70
71    async fn unregister_controller_with_retry(
72        &mut self,
73        controller_id: i32,
74        policy: RetryPolicy,
75    ) -> Result<(), AdminError> {
76        let request = UnregisterControllerRequest {
77            controller_id,
78            ..Default::default()
79        };
80        let mut retry = ControllerRetry::new("UnregisterController", policy);
81        loop {
82            let response = retry.bounded(self.conn.send(request.clone())).await?;
83            if response.error_code != REQUEST_TIMED_OUT {
84                return unregister_error(
85                    "UnregisterController",
86                    response.error_code,
87                    response.error_message,
88                );
89            }
90            retry.after_retriable("REQUEST_TIMED_OUT").await?;
91        }
92    }
93}
94
95fn unregister_error(
96    api: &'static str,
97    code: i16,
98    message: Option<String>,
99) -> Result<(), AdminError> {
100    if code == 0 {
101        Ok(())
102    } else {
103        Err(AdminError::Broker {
104            api,
105            code,
106            name: kafka_error_name(code),
107            message,
108        })
109    }
110}
111
112#[cfg(test)]
113mod tests {
114    use std::{
115        sync::{
116            Arc, Mutex,
117            atomic::{AtomicUsize, Ordering},
118        },
119        time::Duration,
120    };
121
122    use assert2::assert;
123    use bytes::BytesMut;
124    use krabka_client_core::MockBroker;
125    use krabka_protocol::{
126        Encode,
127        owned::{
128            api_versions_request,
129            api_versions_response::{ApiVersion, ApiVersionsResponse},
130            unregister_broker_request,
131            unregister_broker_response::UnregisterBrokerResponse,
132            unregister_controller_request,
133            unregister_controller_response::UnregisterControllerResponse,
134        },
135    };
136
137    use super::*;
138    use crate::partition_leaders::test_support::decode_request;
139
140    #[test]
141    fn unregister_error_names_the_api_and_the_code() {
142        for (api, code, message, expected) in [
143            ("UnregisterBroker", 0, None, None),
144            ("UnregisterController", 0, None, None),
145            (
146                "UnregisterBroker",
147                42,
148                Some("stale"),
149                Some(("UnregisterBroker", 42, "INVALID_REQUEST", Some("stale"))),
150            ),
151            (
152                "UnregisterController",
153                136,
154                None,
155                Some((
156                    "UnregisterController",
157                    136,
158                    "CONTROLLER_ID_NOT_REGISTERED",
159                    None,
160                )),
161            ),
162        ] {
163            let actual = match unregister_error(api, code, message.map(str::to_owned)) {
164                Ok(()) => None,
165                Err(AdminError::Broker {
166                    api,
167                    code,
168                    name,
169                    message,
170                }) => Some((api, code, name, message)),
171                Err(other) => panic!("unexpected error {other:?}"),
172            };
173            let actual = actual
174                .as_ref()
175                .map(|(api, code, name, message)| (*api, *code, *name, message.as_deref()));
176            assert!(actual == expected, "{api} {code}");
177        }
178    }
179
180    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
181    enum Call {
182        Broker,
183        Controller,
184    }
185
186    /// One unregister request that the mock broker decoded.
187    #[derive(Debug, Clone, PartialEq, Eq)]
188    enum Sent {
189        Broker(UnregisterBrokerRequest),
190        Controller(UnregisterControllerRequest),
191    }
192
193    /// A mock broker that advertises only `ApiVersions` and the API of
194    /// `call`, answers each request of that API with the next code of
195    /// `codes`, repeating the last, and records each request in `sent`.
196    async fn unregister_mock(
197        call: Call,
198        codes: Vec<i16>,
199        sent: Arc<Mutex<Vec<Sent>>>,
200    ) -> MockBroker {
201        let requests = AtomicUsize::new(0);
202        let api_key = match call {
203            Call::Broker => unregister_broker_request::API_KEY,
204            Call::Controller => unregister_controller_request::API_KEY,
205        };
206        MockBroker::start(move |key, version, _, request_body| {
207            let mut body = BytesMut::new();
208            if key == api_versions_request::API_KEY {
209                ApiVersionsResponse {
210                    api_keys: vec![
211                        ApiVersion {
212                            api_key: api_versions_request::API_KEY,
213                            ..Default::default()
214                        },
215                        ApiVersion {
216                            api_key,
217                            ..Default::default()
218                        },
219                    ],
220                    ..Default::default()
221                }
222                .encode(&mut body, 0)
223                .unwrap();
224                return Some(body.to_vec());
225            }
226            if key != api_key {
227                return None;
228            }
229            let error_code = codes[requests.fetch_add(1, Ordering::SeqCst).min(codes.len() - 1)];
230            // Both APIs are flexible from v0: a tagged-field byte follows the
231            // correlation id of the response header.
232            body.extend_from_slice(&[0]);
233            match call {
234                Call::Broker => {
235                    sent.lock().unwrap().push(Sent::Broker(decode_request(
236                        request_body,
237                        version,
238                        true,
239                    )));
240                    UnregisterBrokerResponse {
241                        error_code,
242                        ..Default::default()
243                    }
244                    .encode(&mut body, version)
245                    .unwrap();
246                }
247                Call::Controller => {
248                    sent.lock().unwrap().push(Sent::Controller(decode_request(
249                        request_body,
250                        version,
251                        true,
252                    )));
253                    UnregisterControllerResponse {
254                        error_code,
255                        ..Default::default()
256                    }
257                    .encode(&mut body, version)
258                    .unwrap();
259                }
260            }
261            Some(body.to_vec())
262        })
263        .await
264    }
265
266    /// Kafka's `unregisterBroker` and `unregisterController` retry
267    /// `REQUEST_TIMED_OUT` (7) until the deadline and fail at once on
268    /// `NOT_CONTROLLER` (41) and every other code.
269    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
270    async fn unregister_retries_request_timed_out_as_kafka_does() {
271        const LONG: Duration = Duration::from_secs(5);
272        const SHORT: Duration = Duration::from_millis(300);
273        for call in [Call::Broker, Call::Controller] {
274            for (name, codes, timeout, expected_result, expected_requests) in [
275                ("success", vec![0], LONG, Ok(()), 1),
276                (
277                    "request timed out, then success",
278                    vec![7, 7, 0],
279                    LONG,
280                    Ok(()),
281                    3,
282                ),
283                ("not controller is final", vec![41], LONG, Err(41), 1),
284                ("invalid request is final", vec![42], LONG, Err(42), 1),
285                (
286                    "controller id not registered is final",
287                    vec![136],
288                    LONG,
289                    Err(136),
290                    1,
291                ),
292                (
293                    "request timed out past the deadline",
294                    vec![7],
295                    SHORT,
296                    Err(7),
297                    1,
298                ),
299            ] {
300                let sent = Arc::new(Mutex::new(Vec::new()));
301                let broker = unregister_mock(call, codes, Arc::clone(&sent)).await;
302                let mut admin = AdminClient::connect(&[broker.addr.to_string()])
303                    .await
304                    .expect("admin connects");
305                let backoff = if timeout == LONG {
306                    Duration::from_millis(1)
307                } else {
308                    timeout
309                };
310                let policy = RetryPolicy {
311                    timeout,
312                    initial_backoff: backoff,
313                    max_backoff: backoff,
314                    jitter: 0.0,
315                    max_retries: u32::MAX,
316                };
317
318                let (result, expected_request) = match call {
319                    Call::Broker => (
320                        admin.unregister_broker_with_retry(9, policy).await,
321                        Sent::Broker(UnregisterBrokerRequest {
322                            broker_id: 9,
323                            ..Default::default()
324                        }),
325                    ),
326                    Call::Controller => (
327                        admin.unregister_controller_with_retry(9, policy).await,
328                        Sent::Controller(UnregisterControllerRequest {
329                            controller_id: 9,
330                            ..Default::default()
331                        }),
332                    ),
333                };
334                let result = result.map_err(|error| match error {
335                    AdminError::Broker { code, .. } => code,
336                    other => panic!("case {call:?} {name}: unexpected error {other:?}"),
337                });
338
339                broker.stop();
340                let sent = sent.lock().unwrap().clone();
341                assert!(
342                    (result, sent) == (expected_result, vec![expected_request; expected_requests]),
343                    "case {call:?} {name}"
344                );
345            }
346        }
347    }
348}