11// Copyright (c) Microsoft Corporation.
22// Licensed under the MIT License.
33
4+ #![ allow( dead_code, reason = "need to work across many combinations of features, let's just allow it" ) ]
5+
46use std:: fmt:: Display ;
57
68/// Attribute key for the attempt index.
7- #[ cfg( any( feature = "metrics" , test) ) ]
89pub ( crate ) const ATTEMPT_INDEX : & str = "resilience.attempt.index" ;
910
1011/// Attribute key for whether this is the last attempt.
11- #[ cfg( any( feature = "metrics" , test) ) ]
1212pub ( crate ) const ATTEMPT_IS_LAST : & str = "resilience.attempt.is_last" ;
1313
1414/// Attribute key for the recovery kind that triggered the attempt.
15- #[ cfg( any( feature = "metrics" , test) ) ]
1615pub ( crate ) const ATTEMPT_RECOVERY_KIND : & str = "resilience.attempt.recovery.kind" ;
1716
18- /// Represents a single attempt in a resilience operation.
17+ /// Tracks the current attempt within a resilience operation.
18+ ///
19+ /// Resilience middleware creates an `Attempt` for each execution of the inner service and
20+ /// passes it to user-provided callbacks. You can use the attempt information to vary behavior
21+ /// per attempt - for example, routing to a different endpoint or injecting the attempt into
22+ /// request extensions for downstream observability.
23+ ///
24+ /// # Default
1925///
20- /// This struct tracks the current attempt index, and it provides methods to check if this is the
21- /// first or last attempt.
26+ /// The [`Default`] value represents a single-shot operation with no retries:
2227///
23- /// The default attempt has:
28+ /// - [`index()`](Self::index): `0` (first attempt, zero-based)
29+ /// - [`is_first()`](Self::is_first): `true`
30+ /// - [`is_last()`](Self::is_last): `true`
2431///
25- /// - `attempt`: 0 (first attempt, 0-based indexing)
26- /// - `is_first`: true
27- /// - `is_last`: true
32+ /// # Display
2833///
29- /// This represents a single-shot operation with no retries, where the first
30- /// attempt is also the final attempt .
34+ /// The [`Display`] implementation writes the attempt [`index()`](Self::index) as a decimal
35+ /// number, which is useful for logging and diagnostics .
3136///
3237/// # Examples
3338///
3439/// ```
35- /// use seatbelt::retry:: Attempt;
40+ /// use seatbelt::Attempt;
3641///
37- /// // Create the first attempt (attempt 0 )
42+ /// // First attempt of several (more attempts may follow )
3843/// let attempt = Attempt::new(0, false);
3944/// assert!(attempt.is_first());
4045/// assert!(!attempt.is_last());
4146/// assert_eq!(attempt.index(), 0);
4247///
43- /// // Create the last attempt (attempt 2 )
48+ /// // Final attempt (no further retries will be made )
4449/// let last_attempt = Attempt::new(2, true);
4550/// assert!(!last_attempt.is_first());
4651/// assert!(last_attempt.is_last());
4752/// assert_eq!(last_attempt.index(), 2);
4853///
49- /// // Use the default attempt ( single-shot operation)
54+ /// // Default: single-shot, no retries
5055/// let default_attempt = Attempt::default();
5156/// assert_eq!(default_attempt.index(), 0);
5257/// assert!(default_attempt.is_first());
@@ -65,27 +70,29 @@ impl Default for Attempt {
6570}
6671
6772impl Attempt {
68- /// Creates a new attempt with the given attempt index and maximum attempts.
73+ /// Creates a new attempt with the given zero-based `index` and a flag indicating whether
74+ /// this is the last attempt the middleware will make.
6975///
7076/// # Examples
7177///
7278/// ```
73- /// use seatbelt::retry:: Attempt;
79+ /// use seatbelt::Attempt;
7480///
7581/// let attempt = Attempt::new(0, false);
7682/// assert_eq!(attempt.index(), 0);
83+ /// assert!(!attempt.is_last());
7784/// ```
7885#[ must_use]
7986 pub fn new ( index : u32 , is_last : bool ) -> Self {
8087 Self { index, is_last }
8188 }
8289
83- /// Returns true if this is the first attempt (attempt 0 ).
90+ /// Returns ` true` if this is the first attempt (`index == 0` ).
8491///
8592/// # Examples
8693///
8794/// ```
88- /// use seatbelt::retry:: Attempt;
95+ /// use seatbelt::Attempt;
8996///
9097/// let first_attempt = Attempt::new(0, false);
9198/// assert!(first_attempt.is_first());
@@ -98,12 +105,12 @@ impl Attempt {
98105 self . index == 0
99106 }
100107
101- /// Returns true if this is the last allowed attempt .
108+ /// Returns ` true` if no further attempts will be made after this one .
102109///
103110/// # Examples
104111///
105112/// ```
106- /// use seatbelt::retry:: Attempt;
113+ /// use seatbelt::Attempt;
107114///
108115/// let not_last = Attempt::new(1, false);
109116/// assert!(!not_last.is_last());
@@ -121,7 +128,7 @@ impl Attempt {
121128/// # Examples
122129///
123130/// ```
124- /// use seatbelt::retry:: Attempt;
131+ /// use seatbelt::Attempt;
125132///
126133/// let attempt = Attempt::new(3, false);
127134/// assert_eq!(attempt.index(), 3);
0 commit comments