1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![doc = include_str!("../README.md")]
3#![allow(renamed_and_removed_lints)] #![allow(unknown_lints)] #![warn(missing_docs)]
7#![warn(noop_method_call)]
8#![warn(unreachable_pub)]
9#![warn(clippy::all)]
10#![deny(clippy::await_holding_lock)]
11#![deny(clippy::cargo_common_metadata)]
12#![deny(clippy::cast_lossless)]
13#![deny(clippy::checked_conversions)]
14#![allow(clippy::cognitive_complexity)] #![deny(clippy::debug_assert_with_mut_call)]
16#![deny(clippy::exhaustive_enums)]
17#![deny(clippy::exhaustive_structs)]
18#![deny(clippy::expl_impl_clone_on_copy)]
19#![deny(clippy::fallible_impl_from)]
20#![deny(clippy::implicit_clone)]
21#![deny(clippy::large_stack_arrays)]
22#![warn(clippy::manual_ok_or)]
23#![deny(clippy::missing_docs_in_private_items)]
24#![warn(clippy::needless_borrow)]
25#![warn(clippy::needless_pass_by_value)]
26#![warn(clippy::option_option)]
27#![warn(clippy::or_fun_call)]
28#![deny(clippy::print_stderr)]
29#![deny(clippy::print_stdout)]
30#![warn(clippy::rc_buffer)]
31#![deny(clippy::ref_option_ref)]
32#![warn(clippy::semicolon_if_nothing_returned)]
33#![warn(clippy::trait_duplication_in_bounds)]
34#![deny(clippy::unchecked_time_subtraction)]
35#![deny(clippy::unnecessary_wraps)]
36#![warn(clippy::unseparated_literal_suffix)]
37#![deny(clippy::unwrap_used)]
38#![deny(clippy::mod_module_files)]
39#![allow(clippy::let_unit_value)] #![allow(clippy::uninlined_format_args)]
41#![allow(clippy::significant_drop_in_scrutinee)] #![allow(clippy::result_large_err)] #![allow(clippy::needless_raw_string_hashes)] #![allow(clippy::needless_lifetimes)] #![allow(mismatched_lifetime_syntaxes)] #![allow(clippy::collapsible_if)] #![deny(clippy::unused_async)]
48#![deny(clippy::string_slice)] #![allow(recursion_depth_exceeding_limit)] #![warn(unnameable_types)]
54
55use std::error::Error;
56use std::fmt::{self, Debug, Display, Error as FmtError, Formatter};
57use std::iter;
58use std::time::{Duration, SystemTime};
59
60#[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
61use web_time::Instant;
62
63#[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
64use std::time::Instant;
65
66#[derive(Debug, Clone)]
78pub struct RetryError<E> {
79 doing: String,
81 errors: Vec<(Attempt, E, Instant)>,
83 n_errors: usize,
88 first_error_at: Option<SystemTime>,
102}
103
104#[derive(Debug, Clone)]
106enum Attempt {
107 Single(usize),
109 Range(usize, usize),
111}
112
113impl<E: Debug + AsRef<dyn Error>> Error for RetryError<E> {}
116
117impl<E> RetryError<E> {
118 pub fn in_attempt_to<T: Into<String>>(doing: T) -> Self {
129 RetryError {
130 doing: doing.into(),
131 errors: Vec::new(),
132 n_errors: 0,
133 first_error_at: None,
134 }
135 }
136 pub fn push_timed<T>(&mut self, err: T, instant: Instant, wall_clock: Option<SystemTime>)
158 where
159 T: Into<E>,
160 {
161 if self.n_errors < usize::MAX {
162 self.n_errors += 1;
163 let attempt = Attempt::Single(self.n_errors);
164
165 if self.first_error_at.is_none() {
166 self.first_error_at = wall_clock;
167 }
168
169 self.errors.push((attempt, err.into(), instant));
170 }
171 }
172
173 pub fn push<T>(&mut self, err: T)
182 where
183 T: Into<E>,
184 {
185 self.push_timed(err, current_instant(), Some(current_system_time()));
186 }
187
188 pub fn sources(&self) -> impl Iterator<Item = &E> {
191 self.errors.iter().map(|(.., e, _)| e)
192 }
193
194 pub fn len(&self) -> usize {
196 self.errors.len()
197 }
198
199 pub fn is_empty(&self) -> bool {
201 self.errors.is_empty()
202 }
203
204 #[allow(clippy::disallowed_methods)] pub fn extend<T>(&mut self, iter: impl IntoIterator<Item = T>)
219 where
220 T: Into<E>,
221 {
222 for item in iter {
223 self.push(item);
224 }
225 }
226
227 pub fn dedup_by<F>(&mut self, same_err: F)
232 where
233 F: Fn(&E, &E) -> bool,
234 {
235 let mut old_errs = Vec::new();
236 std::mem::swap(&mut old_errs, &mut self.errors);
237
238 for (attempt, err, timestamp) in old_errs {
239 if let Some((last_attempt, last_err, ..)) = self.errors.last_mut() {
240 if same_err(last_err, &err) {
241 last_attempt.grow(attempt.count());
242 } else {
243 self.errors.push((attempt, err, timestamp));
244 }
245 } else {
246 self.errors.push((attempt, err, timestamp));
247 }
248 }
249 }
250
251 pub fn extend_from_retry_error(&mut self, other: RetryError<E>) {
257 if self.first_error_at.is_none() {
258 self.first_error_at = other.first_error_at;
259 }
260
261 for (attempt, err, timestamp) in other.errors {
262 let Some(new_n_errors) = self.n_errors.checked_add(attempt.count()) else {
263 break;
264 };
265
266 let new_attempt = match attempt {
267 Attempt::Single(_) => Attempt::Single(new_n_errors),
268 Attempt::Range(_, _) => Attempt::Range(self.n_errors + 1, new_n_errors),
269 };
270
271 self.errors.push((new_attempt, err, timestamp));
272 self.n_errors = new_n_errors;
273 }
274 }
275}
276
277impl<E: PartialEq<E>> RetryError<E> {
278 pub fn dedup(&mut self) {
281 self.dedup_by(PartialEq::eq);
282 }
283}
284
285impl Attempt {
286 fn grow(&mut self, count: usize) {
288 *self = match *self {
289 Attempt::Single(idx) => Attempt::Range(idx, idx + count),
290 Attempt::Range(first, last) => Attempt::Range(first, last + count),
291 };
292 }
293
294 fn count(&self) -> usize {
296 match *self {
297 Attempt::Single(_) => 1,
298 Attempt::Range(first, last) => last - first + 1,
299 }
300 }
301}
302
303impl<E> IntoIterator for RetryError<E> {
304 type Item = E;
305 type IntoIter = std::vec::IntoIter<E>;
306 #[allow(clippy::needless_collect)]
307 fn into_iter(self) -> Self::IntoIter {
312 self.errors
313 .into_iter()
314 .map(|(.., e, _)| e)
315 .collect::<Vec<_>>()
316 .into_iter()
317 }
318}
319
320impl Display for Attempt {
321 fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), FmtError> {
322 match self {
323 Attempt::Single(idx) => write!(f, "Attempt {}", idx),
324 Attempt::Range(first, last) => write!(f, "Attempts {}..{}", first, last),
325 }
326 }
327}
328
329impl<E: AsRef<dyn Error>> Display for RetryError<E> {
330 fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), FmtError> {
331 let show_timestamps = f.alternate();
332
333 match self.n_errors {
334 0 => write!(f, "Unable to {}. (No errors given)", self.doing),
335 1 => {
336 write!(f, "Unable to {}", self.doing)?;
337
338 if show_timestamps {
339 if let (Some((.., timestamp)), Some(first_at)) =
340 (self.errors.first(), self.first_error_at)
341 {
342 write!(
343 f,
344 " at {} ({})",
345 humantime::format_rfc3339(first_at),
346 FormatTimeAgo(timestamp.elapsed())
347 )?;
348 }
349 }
350
351 write!(f, ": ")?;
352 fmt_error_with_sources(self.errors[0].1.as_ref(), f)
353 }
354 n => {
355 write!(
356 f,
357 "Tried to {} {} times, but all attempts failed",
358 self.doing, n
359 )?;
360
361 if show_timestamps {
362 if let (Some(first_at), Some((.., first_ts)), Some((.., last_ts))) =
363 (self.first_error_at, self.errors.first(), self.errors.last())
364 {
365 let duration = last_ts.saturating_duration_since(*first_ts);
366
367 write!(f, " (from {} ", humantime::format_rfc3339(first_at))?;
368
369 if duration.as_secs() > 0 {
370 write!(f, "to {}", humantime::format_rfc3339(first_at + duration))?;
371 }
372
373 write!(f, ", {})", FormatTimeAgo(last_ts.elapsed()))?;
374 }
375 }
376
377 let first_ts = self.errors.first().map(|(.., ts)| ts);
378 for (attempt, e, timestamp) in &self.errors {
379 write!(f, "\n{}", attempt)?;
380
381 if show_timestamps {
382 if let Some(first_ts) = first_ts {
383 let offset = timestamp.saturating_duration_since(*first_ts);
384 if offset.as_secs() > 0 {
385 write!(f, " (+{})", FormatDuration(offset))?;
386 }
387 }
388 }
389
390 write!(f, ": ")?;
391 fmt_error_with_sources(e.as_ref(), f)?;
392 }
393 Ok(())
394 }
395 }
396 }
397}
398
399struct FormatDuration(Duration);
404
405impl Display for FormatDuration {
406 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
407 fmt_duration_impl(self.0, f)
408 }
409}
410
411struct FormatTimeAgo(Duration);
413
414impl Display for FormatTimeAgo {
415 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
416 let secs = self.0.as_secs();
417 let millis = self.0.as_millis();
418
419 if secs == 0 && millis == 0 {
421 return write!(f, "just now");
422 }
423
424 fmt_duration_impl(self.0, f)?;
425 write!(f, " ago")
426 }
427}
428
429fn fmt_duration_impl(duration: Duration, f: &mut Formatter<'_>) -> fmt::Result {
434 let secs = duration.as_secs();
435
436 if secs == 0 {
437 let millis = duration.as_millis();
438 if millis == 0 {
439 write!(f, "0s")
440 } else {
441 write!(f, "{}ms", millis)
442 }
443 } else if secs < 60 {
444 write!(f, "{}s", secs)
445 } else if secs < 3600 {
446 let mins = secs / 60;
447 let rem_secs = secs % 60;
448 if rem_secs == 0 {
449 write!(f, "{}m", mins)
450 } else {
451 write!(f, "{}m {}s", mins, rem_secs)
452 }
453 } else {
454 let hours = secs / 3600;
455 let mins = (secs % 3600) / 60;
456 if mins == 0 {
457 write!(f, "{}h", hours)
458 } else {
459 write!(f, "{}h {}m", hours, mins)
460 }
461 }
462}
463
464pub fn fmt_error_with_sources(mut e: &dyn Error, f: &mut fmt::Formatter) -> fmt::Result {
505 let mut last = String::new();
510 let mut sep = iter::once("").chain(iter::repeat(": "));
511
512 loop {
516 let this = e.to_string();
517 if !last.contains(&this) {
518 write!(f, "{}{}", sep.next().expect("repeat ended"), this)?;
519 }
520 last = this;
521
522 if let Some(ne) = e.source() {
523 e = ne;
524 } else {
525 break;
526 }
527 }
528 Ok(())
529}
530
531#[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
535fn current_system_time() -> SystemTime {
536 use web_time::web::SystemTimeExt as _;
537 web_time::SystemTime::now().to_std()
538}
539
540#[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
544fn current_system_time() -> SystemTime {
545 #![allow(clippy::disallowed_methods)]
546 SystemTime::now()
547}
548
549fn current_instant() -> Instant {
553 #![allow(clippy::disallowed_methods)]
554 Instant::now()
555}
556
557#[cfg(test)]
558mod test {
559 #![allow(clippy::bool_assert_comparison)]
561 #![allow(clippy::clone_on_copy)]
562 #![allow(clippy::dbg_macro)]
563 #![allow(clippy::mixed_attributes_style)]
564 #![allow(clippy::print_stderr)]
565 #![allow(clippy::print_stdout)]
566 #![allow(clippy::single_char_pattern)]
567 #![allow(clippy::unwrap_used)]
568 #![allow(clippy::unchecked_time_subtraction)]
569 #![allow(clippy::useless_vec)]
570 #![allow(clippy::needless_pass_by_value)]
571 #![allow(clippy::string_slice)] #![allow(clippy::disallowed_methods)]
574 use super::*;
575 use derive_more::From;
576
577 #[test]
578 fn bad_parse1() {
579 let mut err: RetryError<anyhow::Error> = RetryError::in_attempt_to("convert some things");
580 if let Err(e) = "maybe".parse::<bool>() {
581 err.push(e);
582 }
583 if let Err(e) = "a few".parse::<u32>() {
584 err.push(e);
585 }
586 if let Err(e) = "the_g1b50n".parse::<std::net::IpAddr>() {
587 err.push(e);
588 }
589
590 let disp = format!("{}", err);
591 assert_eq!(
592 disp,
593 "\
594Tried to convert some things 3 times, but all attempts failed
595Attempt 1: provided string was not `true` or `false`
596Attempt 2: invalid digit found in string
597Attempt 3: invalid IP address syntax"
598 );
599
600 let disp_alt = format!("{:#}", err);
601 assert!(disp_alt.contains("Tried to convert some things 3 times, but all attempts failed"));
602 assert!(disp_alt.contains("(from 20")); }
604
605 #[test]
606 fn no_problems() {
607 let empty: RetryError<anyhow::Error> =
608 RetryError::in_attempt_to("immanentize the eschaton");
609 let disp = format!("{}", empty);
610 assert_eq!(
611 disp,
612 "Unable to immanentize the eschaton. (No errors given)"
613 );
614 }
615
616 #[test]
617 fn one_problem() {
618 let mut err: RetryError<anyhow::Error> =
619 RetryError::in_attempt_to("connect to torproject.org");
620 if let Err(e) = "the_g1b50n".parse::<std::net::IpAddr>() {
621 err.push(e);
622 }
623 let disp = format!("{}", err);
624 assert_eq!(
625 disp,
626 "Unable to connect to torproject.org: invalid IP address syntax"
627 );
628
629 let disp_alt = format!("{:#}", err);
630 assert!(disp_alt.contains("Unable to connect to torproject.org at 20")); assert!(disp_alt.contains("invalid IP address syntax"));
632 }
633
634 #[test]
635 fn operations() {
636 use std::num::ParseIntError;
637
638 #[derive(From, Clone, Debug, Eq, PartialEq)]
639 struct Wrapper(ParseIntError);
640
641 impl AsRef<dyn Error + 'static> for Wrapper {
642 fn as_ref(&self) -> &(dyn Error + 'static) {
643 &self.0
644 }
645 }
646
647 let mut err: RetryError<Wrapper> = RetryError::in_attempt_to("parse some integers");
648 assert!(err.is_empty());
649 assert_eq!(err.len(), 0);
650 err.extend(
651 vec!["not", "your", "number"]
652 .iter()
653 .filter_map(|s| s.parse::<u16>().err())
654 .map(Wrapper),
655 );
656 assert!(!err.is_empty());
657 assert_eq!(err.len(), 3);
658
659 let cloned = err.clone();
660 for (s1, s2) in err.sources().zip(cloned.sources()) {
661 assert_eq!(s1, s2);
662 }
663
664 err.dedup();
665
666 let disp = format!("{}", err);
667 assert_eq!(
668 disp,
669 "\
670Tried to parse some integers 3 times, but all attempts failed
671Attempts 1..3: invalid digit found in string"
672 );
673
674 let disp_alt = format!("{:#}", err);
675 assert!(disp_alt.contains("Tried to parse some integers 3 times, but all attempts failed"));
676 assert!(disp_alt.contains("(from 20")); }
678
679 #[test]
680 fn overflow() {
681 use std::num::ParseIntError;
682 let mut err: RetryError<ParseIntError> =
683 RetryError::in_attempt_to("parse too many integers");
684 assert!(err.is_empty());
685 let mut errors: Vec<ParseIntError> = vec!["no", "numbers"]
686 .iter()
687 .filter_map(|s| s.parse::<u16>().err())
688 .collect();
689 err.n_errors = usize::MAX;
690 err.errors.push((
691 Attempt::Range(1, err.n_errors),
692 errors.pop().expect("parser did not fail"),
693 Instant::now(),
694 ));
695 assert!(err.n_errors == usize::MAX);
696 assert!(err.len() == 1);
697
698 err.push(errors.pop().expect("parser did not fail"));
699 assert!(err.n_errors == usize::MAX);
700 assert!(err.len() == 1);
701 }
702
703 #[test]
704 fn extend_from_retry_preserve_timestamps() {
705 let n1 = Instant::now();
706 let n2 = n1 + Duration::from_secs(10);
707 let n3 = n1 + Duration::from_secs(20);
708
709 let mut err1: RetryError<anyhow::Error> = RetryError::in_attempt_to("do first thing");
710 let mut err2: RetryError<anyhow::Error> = RetryError::in_attempt_to("do second thing");
711
712 err2.push_timed(anyhow::Error::msg("e1"), n1, None);
713 err2.push_timed(anyhow::Error::msg("e2"), n2, None);
714
715 assert!(err1.first_error_at.is_none());
717
718 err1.extend_from_retry_error(err2);
719
720 assert_eq!(err1.len(), 2);
721 assert_eq!(err1.errors[0].2, n1);
723 assert_eq!(err1.errors[1].2, n2);
724
725 err1.push_timed(anyhow::Error::msg("e3"), n3, None);
727 assert_eq!(err1.len(), 3);
728 assert_eq!(err1.errors[2].2, n3);
729 }
730
731 #[test]
732 fn extend_from_retry_preserve_ranges() {
733 let n1 = Instant::now();
734 let mut err1: RetryError<anyhow::Error> = RetryError::in_attempt_to("do thing 1");
735
736 err1.push(anyhow::Error::msg("e1"));
738 err1.push(anyhow::Error::msg("e2"));
739 assert_eq!(err1.n_errors, 2);
740
741 let mut err2: RetryError<anyhow::Error> = RetryError::in_attempt_to("do thing 2");
742 err2.push_timed(anyhow::Error::msg("repeated"), n1, None);
744 err2.push_timed(anyhow::Error::msg("repeated"), n1, None);
745 err2.push_timed(anyhow::Error::msg("repeated"), n1, None);
746
747 err2.dedup_by(|e1, e2| e1.to_string() == e2.to_string());
749 assert_eq!(err2.len(), 1); match err2.errors[0].0 {
751 Attempt::Range(1, 3) => {}
752 _ => panic!("Expected range 1..3"),
753 }
754
755 err1.extend_from_retry_error(err2);
757
758 assert_eq!(err1.len(), 3); assert_eq!(err1.n_errors, 5); match err1.errors[2].0 {
763 Attempt::Range(3, 5) => {}
764 ref x => panic!("Expected range 3..5, got {:?}", x),
765 }
766 }
767
768 #[test]
769 fn dedup_after_extend_same_doing() {
770 let doing = "do thing";
771 let message = "error";
772 let n1 = Instant::now();
773 let mut err1: RetryError<anyhow::Error> = RetryError::in_attempt_to(doing);
774
775 err1.push(anyhow::Error::msg(message));
777 assert_eq!(err1.n_errors, 1);
778
779 let mut err2: RetryError<anyhow::Error> = RetryError::in_attempt_to(doing);
780 err2.push_timed(anyhow::Error::msg(message), n1, None);
782 err2.push_timed(anyhow::Error::msg(message), n1, None);
783
784 err2.dedup_by(|e1, e2| e1.to_string() == e2.to_string());
786 assert_eq!(err2.len(), 1); match err2.errors[0].0 {
788 Attempt::Range(1, 2) => {}
789 _ => panic!("Expected range 1..2"),
790 }
791
792 err1.extend_from_retry_error(err2);
794 assert_eq!(err1.len(), 2); assert_eq!(err1.n_errors, 3); err1.dedup_by(|e1, e2| e1.to_string() == e2.to_string());
799 assert_eq!(err1.len(), 1); assert_eq!(err1.n_errors, 3); match err1.errors[0].0 {
804 Attempt::Range(1, 3) => {}
805 ref x => panic!("Expected range 1..3, got {:?}", x),
806 }
807 }
808}