1use std::collections::BTreeMap;
4
5use krabka_client_core::ConnectionOptions;
6use krabka_protocol::owned::{
7 list_offsets_request::{self, ListOffsetsPartition, ListOffsetsRequest, ListOffsetsTopic},
8 list_offsets_response::ListOffsetsResponse,
9};
10
11use crate::{
12 AdminClient, AdminError, KafkaError, kafka_error_name,
13 partition_leaders::{PartitionKey, PartitionResults, complete_results},
14};
15
16const UNSUPPORTED_VERSION: i16 = 35;
18const CONSUMER_REPLICA_ID: i32 = -1;
20
21#[derive(Debug, Clone, Copy, PartialEq, Eq)]
23pub enum OffsetSpec {
24 Earliest,
26 Latest,
29 MaxTimestamp,
32 EarliestLocal,
35 LatestTiered,
38 EarliestPendingUpload,
42 ForTimestamp(i64),
45}
46
47impl OffsetSpec {
48 const fn wire_timestamp(self) -> i64 {
51 match self {
52 Self::Earliest => -2,
53 Self::Latest => -1,
54 Self::MaxTimestamp => -3,
55 Self::EarliestLocal => -4,
56 Self::LatestTiered => -5,
57 Self::EarliestPendingUpload => -6,
58 Self::ForTimestamp(timestamp) => timestamp,
59 }
60 }
61
62 const fn min_version(self) -> i16 {
66 match self {
67 Self::Earliest | Self::Latest | Self::ForTimestamp(_) => 1,
68 Self::MaxTimestamp => 7,
69 Self::EarliestLocal => 8,
70 Self::LatestTiered => 9,
71 Self::EarliestPendingUpload => 11,
72 }
73 }
74}
75
76#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
78pub enum IsolationLevel {
79 #[default]
81 ReadUncommitted,
82 ReadCommitted,
84}
85
86impl IsolationLevel {
87 const fn wire(self) -> i8 {
88 match self {
89 Self::ReadUncommitted => 0,
90 Self::ReadCommitted => 1,
91 }
92 }
93
94 const fn min_version(self) -> i16 {
95 match self {
96 Self::ReadUncommitted => 1,
97 Self::ReadCommitted => 2,
98 }
99 }
100}
101
102#[derive(Debug, Clone, Copy, PartialEq, Eq)]
105pub struct ListedOffset {
106 pub offset: i64,
108 pub timestamp_ms: i64,
111 pub leader_epoch: Option<i32>,
114}
115
116fn list_offsets_request(
119 keys: &[PartitionKey],
120 specs: &BTreeMap<PartitionKey, OffsetSpec>,
121 isolation_level: IsolationLevel,
122 timeout_ms: i32,
123) -> ListOffsetsRequest {
124 let mut by_topic = BTreeMap::<&str, Vec<ListOffsetsPartition>>::new();
125 for key in keys {
126 let spec = specs.get(key).copied().unwrap_or(OffsetSpec::Latest);
127 by_topic
128 .entry(key.0.as_str())
129 .or_default()
130 .push(ListOffsetsPartition {
131 partition_index: key.1,
132 timestamp: spec.wire_timestamp(),
133 ..Default::default()
134 });
135 }
136 ListOffsetsRequest {
137 replica_id: CONSUMER_REPLICA_ID,
138 isolation_level: isolation_level.wire(),
139 topics: by_topic
140 .into_iter()
141 .map(|(name, partitions)| ListOffsetsTopic {
142 name: name.to_owned(),
143 partitions,
144 ..Default::default()
145 })
146 .collect(),
147 timeout_ms,
148 ..Default::default()
149 }
150}
151
152fn list_offsets_results(
154 keys: &[PartitionKey],
155 response: ListOffsetsResponse,
156) -> PartitionResults<ListedOffset> {
157 let mut out = BTreeMap::new();
158 for topic in response.topics {
159 for partition in topic.partitions {
160 let result = if partition.error_code == 0 {
161 Ok(ListedOffset {
162 offset: partition.offset,
163 timestamp_ms: partition.timestamp,
164 leader_epoch: (partition.leader_epoch != -1).then_some(partition.leader_epoch),
165 })
166 } else {
167 Err(KafkaError {
168 code: partition.error_code,
169 name: kafka_error_name(partition.error_code),
170 message: None,
171 })
172 };
173 out.insert((topic.name.clone(), partition.partition_index), result);
174 }
175 }
176 complete_results("ListOffsets", keys, out)
177}
178
179const fn list_offsets_retry_code(code: i16) -> bool {
186 matches!(
187 code,
188 2 | 3 | 5 | 6 | 7
191 | 9 | 13 | 14 | 15 | 16
193 | 19 | 20 | 41
195 | 51 | 56
197 | 70 | 71 | 72 | 74 | 75
200 | 78 | 80 | 83 | 88
203 | 100 | 103
205 )
206}
207
208const fn required_version(spec: OffsetSpec, isolation_level: IsolationLevel) -> i16 {
211 let spec_version = spec.min_version();
212 let isolation_version = isolation_level.min_version();
213 if spec_version > isolation_version {
214 spec_version
215 } else {
216 isolation_version
217 }
218}
219
220fn split_supported(
225 keys: Vec<PartitionKey>,
226 specs: &BTreeMap<PartitionKey, OffsetSpec>,
227 isolation_level: IsolationLevel,
228 max_version: i16,
229) -> (Vec<PartitionKey>, PartitionResults<ListedOffset>) {
230 let mut supported = Vec::new();
231 let mut unsupported = BTreeMap::new();
232 for key in keys {
233 let spec = specs.get(&key).copied().unwrap_or(OffsetSpec::Latest);
234 let needed = required_version(spec, isolation_level);
235 if needed <= max_version {
236 supported.push(key);
237 } else {
238 unsupported.insert(
239 key,
240 Err(KafkaError {
241 code: UNSUPPORTED_VERSION,
242 name: kafka_error_name(UNSUPPORTED_VERSION),
243 message: Some(format!(
244 "the leader supports ListOffsets up to v{max_version}, and {spec:?} with \
245 {isolation_level:?} needs v{needed}"
246 )),
247 }),
248 );
249 }
250 }
251 (supported, unsupported)
252}
253
254async fn list_offsets_on_leader(
256 address: String,
257 options: ConnectionOptions,
258 keys: Vec<PartitionKey>,
259 specs: &BTreeMap<PartitionKey, OffsetSpec>,
260 isolation_level: IsolationLevel,
261 timeout_ms: i32,
262) -> Result<PartitionResults<ListedOffset>, AdminError> {
263 let connection = AdminClient::connect_one(&address, options).await?;
264 let max_version = connection
265 .advertised_api_range(list_offsets_request::API_KEY)
266 .map_or(-1, |(_, max)| {
267 max.min(list_offsets_request::LATEST_STABLE_VERSION)
268 });
269 let (supported, mut out) = split_supported(keys, specs, isolation_level, max_version);
270 if !supported.is_empty() {
271 let request = list_offsets_request(&supported, specs, isolation_level, timeout_ms);
272 let response = connection.send(request).await?;
273 out.extend(list_offsets_results(&supported, response));
274 }
275 Ok(out)
276}
277
278impl AdminClient {
279 pub async fn list_offsets(
308 &self,
309 specs: &BTreeMap<(String, i32), OffsetSpec>,
310 isolation_level: IsolationLevel,
311 ) -> BTreeMap<(String, i32), Result<ListedOffset, KafkaError>> {
312 let keys = specs.keys().cloned().collect::<Vec<_>>();
313 let timeout_ms = i32::try_from(self.retry.timeout.as_millis()).unwrap_or(i32::MAX);
314 self.call_partition_leaders(
315 "ListOffsets",
316 &keys,
317 list_offsets_retry_code,
318 |address, keys| {
319 list_offsets_on_leader(
320 address,
321 self.options.clone(),
322 keys,
323 specs,
324 isolation_level,
325 timeout_ms,
326 )
327 },
328 )
329 .await
330 }
331}
332
333#[cfg(test)]
334mod tests {
335 use std::sync::{Arc, Mutex};
336
337 use krabka_protocol::owned::list_offsets_response::{
338 ListOffsetsPartitionResponse, ListOffsetsTopicResponse,
339 };
340
341 use super::*;
342 use crate::partition_leaders::test_support::{
343 ApiVersionRange, Seen, decode_request, encode_response, fast_admin, leader_broker,
344 refused_address,
345 };
346
347 fn key(partition: i32) -> PartitionKey {
348 ("orders".to_owned(), partition)
349 }
350
351 #[test]
352 fn request_carries_each_spec_as_kafka_encodes_it() {
353 let specs = maplit::btreemap! {
354 key(0) => OffsetSpec::Earliest,
355 key(1) => OffsetSpec::Latest,
356 key(2) => OffsetSpec::MaxTimestamp,
357 key(3) => OffsetSpec::EarliestLocal,
358 key(4) => OffsetSpec::LatestTiered,
359 key(5) => OffsetSpec::EarliestPendingUpload,
360 ("audit".to_owned(), 0) => OffsetSpec::ForTimestamp(1_700_000_000_000),
361 };
362 let keys = specs.keys().cloned().collect::<Vec<_>>();
363 let partition = |partition_index, timestamp| ListOffsetsPartition {
364 partition_index,
365 timestamp,
366 ..Default::default()
367 };
368
369 assert2::assert!(
370 list_offsets_request(&keys, &specs, IsolationLevel::ReadCommitted, 30_000)
371 == ListOffsetsRequest {
372 replica_id: -1,
373 isolation_level: 1,
374 topics: vec![
375 ListOffsetsTopic {
376 name: "audit".to_owned(),
377 partitions: vec![partition(0, 1_700_000_000_000)],
378 ..Default::default()
379 },
380 ListOffsetsTopic {
381 name: "orders".to_owned(),
382 partitions: vec![
383 partition(0, -2),
384 partition(1, -1),
385 partition(2, -3),
386 partition(3, -4),
387 partition(4, -5),
388 partition(5, -6),
389 ],
390 ..Default::default()
391 },
392 ],
393 timeout_ms: 30_000,
394 ..Default::default()
395 }
396 );
397 }
398
399 #[test]
400 fn required_version_matches_kafka_for_consumer() {
401 for (spec, isolation_level, expected) in [
402 (OffsetSpec::Latest, IsolationLevel::ReadUncommitted, 1),
403 (
404 OffsetSpec::ForTimestamp(5),
405 IsolationLevel::ReadUncommitted,
406 1,
407 ),
408 (OffsetSpec::Earliest, IsolationLevel::ReadCommitted, 2),
409 (OffsetSpec::MaxTimestamp, IsolationLevel::ReadCommitted, 7),
410 (
411 OffsetSpec::EarliestLocal,
412 IsolationLevel::ReadUncommitted,
413 8,
414 ),
415 (OffsetSpec::LatestTiered, IsolationLevel::ReadUncommitted, 9),
416 (
417 OffsetSpec::EarliestPendingUpload,
418 IsolationLevel::ReadUncommitted,
419 11,
420 ),
421 ] {
422 assert2::assert!(
423 required_version(spec, isolation_level) == expected,
424 "{spec:?} {isolation_level:?}"
425 );
426 }
427 }
428
429 #[test]
430 fn results_map_offsets_and_errors_of_each_partition() {
431 let response = ListOffsetsResponse {
432 topics: vec![ListOffsetsTopicResponse {
433 name: "orders".to_owned(),
434 partitions: vec![
435 ListOffsetsPartitionResponse {
436 partition_index: 0,
437 timestamp: 1_700_000_000_000,
438 offset: 42,
439 leader_epoch: 3,
440 ..Default::default()
441 },
442 ListOffsetsPartitionResponse {
443 partition_index: 1,
444 offset: 7,
445 ..Default::default()
446 },
447 ListOffsetsPartitionResponse {
448 partition_index: 2,
449 error_code: 3,
450 ..Default::default()
451 },
452 ],
453 ..Default::default()
454 }],
455 ..Default::default()
456 };
457
458 assert2::assert!(
459 list_offsets_results(&[key(0), key(1), key(2)], response)
460 == maplit::btreemap! {
461 key(0) => Ok(ListedOffset {
462 offset: 42,
463 timestamp_ms: 1_700_000_000_000,
464 leader_epoch: Some(3),
465 }),
466 key(1) => Ok(ListedOffset {
467 offset: 7,
468 timestamp_ms: -1,
469 leader_epoch: None,
470 }),
471 key(2) => Err(KafkaError {
472 code: 3,
473 name: "UNKNOWN_TOPIC_OR_PARTITION",
474 message: None,
475 }),
476 }
477 );
478 }
479
480 fn offsets_answer(request: &ListOffsetsRequest, orders_1_code: i16) -> ListOffsetsResponse {
483 ListOffsetsResponse {
484 topics: request
485 .topics
486 .iter()
487 .map(|topic| ListOffsetsTopicResponse {
488 name: topic.name.clone(),
489 partitions: topic
490 .partitions
491 .iter()
492 .map(|partition| {
493 let (error_code, offset) = if partition.partition_index == 0 {
494 (0, 100)
495 } else {
496 (orders_1_code, 200)
497 };
498 ListOffsetsPartitionResponse {
499 partition_index: partition.partition_index,
500 error_code,
501 offset,
502 leader_epoch: 4,
503 ..Default::default()
504 }
505 })
506 .collect(),
507 ..Default::default()
508 })
509 .collect(),
510 ..Default::default()
511 }
512 }
513
514 struct Case {
516 name: &'static str,
517 max_version: i16,
519 leaders: Vec<Option<std::net::SocketAddr>>,
521 orders_1_codes: Vec<i16>,
523 orders_1_spec: OffsetSpec,
525 expected: Result<ListedOffset, KafkaError>,
527 metadata_requests: usize,
529 requests: Vec<Vec<PartitionKey>>,
531 }
532
533 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
539 async fn list_offsets_retries_and_fails_each_partition_as_kafka_does() {
540 let offset_200 = || {
541 Ok(ListedOffset {
542 offset: 200,
543 timestamp_ms: -1,
544 leader_epoch: Some(4),
545 })
546 };
547 let refused = refused_address().await;
548 let cases = [
549 Case {
550 name: "success",
551 max_version: 11,
552 leaders: vec![None],
553 orders_1_codes: vec![0],
554 orders_1_spec: OffsetSpec::MaxTimestamp,
555 expected: offset_200(),
556 metadata_requests: 1,
557 requests: vec![vec![key(0), key(1)]],
558 },
559 Case {
560 name: "not leader or follower finds the leader again",
561 max_version: 11,
562 leaders: vec![None],
563 orders_1_codes: vec![6, 0],
564 orders_1_spec: OffsetSpec::Earliest,
565 expected: offset_200(),
566 metadata_requests: 2,
567 requests: vec![vec![key(0), key(1)], vec![key(1)]],
568 },
569 Case {
570 name: "leader not available finds the leader again",
571 max_version: 11,
572 leaders: vec![None],
573 orders_1_codes: vec![5, 0],
574 orders_1_spec: OffsetSpec::Earliest,
575 expected: offset_200(),
576 metadata_requests: 2,
577 requests: vec![vec![key(0), key(1)], vec![key(1)]],
578 },
579 Case {
580 name: "a refused connection finds the leader again",
581 max_version: 11,
582 leaders: vec![Some(refused), None],
583 orders_1_codes: vec![0],
584 orders_1_spec: OffsetSpec::Latest,
585 expected: offset_200(),
586 metadata_requests: 2,
587 requests: vec![vec![key(0), key(1)]],
588 },
589 Case {
590 name: "topic authorization failed is final",
591 max_version: 11,
592 leaders: vec![None],
593 orders_1_codes: vec![29],
594 orders_1_spec: OffsetSpec::Latest,
595 expected: Err(KafkaError {
596 code: 29,
597 name: "TOPIC_AUTHORIZATION_FAILED",
598 message: None,
599 }),
600 metadata_requests: 1,
601 requests: vec![vec![key(0), key(1)]],
602 },
603 Case {
604 name: "max timestamp below v7 fails only its partition",
605 max_version: 6,
606 leaders: vec![None],
607 orders_1_codes: vec![0],
608 orders_1_spec: OffsetSpec::MaxTimestamp,
609 expected: Err(KafkaError {
610 code: UNSUPPORTED_VERSION,
611 name: "UNSUPPORTED_VERSION",
612 message: Some(
613 "the leader supports ListOffsets up to v6, and MaxTimestamp with \
614 ReadUncommitted needs v7"
615 .to_owned(),
616 ),
617 }),
618 metadata_requests: 1,
619 requests: vec![vec![key(0)]],
620 },
621 ];
622 for case in cases {
623 let seen = Arc::new(Mutex::new(Seen::default()));
624 let codes = case.orders_1_codes.clone();
625 let broker = leader_broker(
626 vec![
627 ApiVersionRange::builder()
628 .api_key(list_offsets_request::API_KEY)
629 .min_version(1)
630 .max_version(case.max_version)
631 .build(),
632 ],
633 list_offsets_request::API_KEY,
634 case.leaders.clone(),
635 Arc::clone(&seen),
636 move |n, version, body| {
637 let flexible = version >= list_offsets_request::FLEXIBLE_MIN;
638 let request: ListOffsetsRequest = decode_request(body, version, flexible);
639 let code = codes[n.min(codes.len() - 1)];
640 encode_response(&offsets_answer(&request, code), version, flexible)
641 },
642 )
643 .await;
644 let admin = fast_admin(broker.addr, krabka_units::secs(5)).await;
645 let specs = maplit::btreemap! {
646 key(0) => OffsetSpec::Latest,
647 key(1) => case.orders_1_spec,
648 };
649
650 let result = admin
651 .list_offsets(&specs, IsolationLevel::ReadUncommitted)
652 .await;
653
654 broker.stop();
655 let seen = seen.lock().expect("seen lock");
656 let requests = seen
657 .requests
658 .iter()
659 .map(|(version, body)| {
660 let flexible = *version >= list_offsets_request::FLEXIBLE_MIN;
661 decode_request::<ListOffsetsRequest>(body, *version, flexible)
662 })
663 .collect::<Vec<_>>();
664 let expected_requests = case
665 .requests
666 .iter()
667 .map(|keys| {
668 let timeout_ms = if case.max_version >= 10 { 5_000 } else { 0 };
670 list_offsets_request(keys, &specs, IsolationLevel::ReadUncommitted, timeout_ms)
671 })
672 .collect::<Vec<_>>();
673 assert2::assert!(
674 (result, seen.metadata_requests, requests)
675 == (
676 maplit::btreemap! {
677 key(0) => Ok(ListedOffset {
678 offset: 100,
679 timestamp_ms: -1,
680 leader_epoch: Some(4),
681 }),
682 key(1) => case.expected,
683 },
684 case.metadata_requests,
685 expected_requests,
686 ),
687 "case {}",
688 case.name
689 );
690 }
691 }
692
693 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
696 async fn list_offsets_times_out_a_partition_that_never_gets_a_leader() {
697 let seen = Arc::new(Mutex::new(Seen::default()));
698 let broker = leader_broker(
699 vec![
700 ApiVersionRange::builder()
701 .api_key(list_offsets_request::API_KEY)
702 .min_version(1)
703 .max_version(11)
704 .build(),
705 ],
706 list_offsets_request::API_KEY,
707 vec![None],
708 Arc::clone(&seen),
709 |_, _, _| Vec::new(),
710 )
711 .await;
712 let admin = fast_admin(broker.addr, krabka_units::millis(300)).await;
713
714 let result = admin
715 .list_offsets(
716 &maplit::btreemap! {
717 ("missing".to_owned(), 0) => OffsetSpec::Latest,
718 },
719 IsolationLevel::ReadUncommitted,
720 )
721 .await;
722
723 broker.stop();
724 let codes = result
725 .into_iter()
726 .map(|(key, result)| (key, result.map_err(|error| error.code)))
727 .collect::<Vec<_>>();
728 let seen = seen.lock().expect("seen lock");
729 assert2::assert!(codes == vec![(("missing".to_owned(), 0), Err(7))]);
730 assert2::assert!(seen.metadata_requests > 1);
731 assert2::assert!(seen.requests.is_empty());
732 }
733}