feat(error): stabilize error classification priority

src/error.rs

@@ -11,6 +11,7 @@ use magnus::{
 use tokio::sync::mpsc::error::SendError;
 
 const ERROR_PREDICATES_IVAR: &str = "wreq_error_predicates";
+type ErrorPredicateBits = u64;
 
 const RACE_CONDITION_ERROR_MSG: &str = r#"Due to Rust's memory management with borrowing,
 you cannot use certain instances multiple times as they may be consumed.
@@ -47,7 +48,7 @@ macro_rules! initialize_exception {
 macro_rules! define_error_mapping {
     ($($predicate:ident: $method:ident => $class:ident $(($ruby_name:literal))?),+ $(,)?) => {
         /// Native predicates ordered by Ruby exception class priority.
-        #[derive(Clone, Copy)]
+        #[derive(Clone, Copy, Debug, PartialEq, Eq)]
         #[repr(u8)]
         enum ErrorPredicate {
             $($predicate),+
@@ -57,8 +58,8 @@ macro_rules! define_error_mapping {
             const CLASSIFICATION_ORDER: &'static [Self] = &[$(Self::$predicate),+];
 
             /// Return this predicate's position in the compact Ruby metadata.
-            const fn mask(self) -> u16 {
-                1_u16 << (self as u8)
+            const fn mask(self) -> ErrorPredicateBits {
+                1 << (self as u8)
             }
 
             /// Evaluate this predicate before the native error is consumed.
@@ -77,7 +78,7 @@ macro_rules! define_error_mapping {
         }
 
         const _: () =
-            assert!(ErrorPredicate::CLASSIFICATION_ORDER.len() <= u16::BITS as usize);
+            assert!(ErrorPredicate::CLASSIFICATION_ORDER.len() <= ErrorPredicateBits::BITS as usize);
 
         $(
             $(define_exception!($class, $ruby_name, exception_runtime_error);)?
@@ -131,16 +132,16 @@ define_error_mapping! {
 
 /// Native predicates retained after consuming a wreq error.
 #[derive(Clone, Copy, Default)]
-struct ErrorPredicates(u16);
+struct ErrorPredicates(ErrorPredicateBits);
 
 impl ErrorPredicates {
     /// Restore predicates from compact Ruby metadata.
-    const fn from_bits(bits: u16) -> Self {
+    const fn from_bits(bits: ErrorPredicateBits) -> Self {
         Self(bits)
     }
 
     /// Return the compact representation stored on the Ruby exception.
-    const fn bits(self) -> u16 {
+    const fn bits(self) -> ErrorPredicateBits {
         self.0
     }
 
@@ -157,6 +158,23 @@ impl ErrorPredicates {
         }
         self
     }
+
+    /// Return the first matching predicate by classification order.
+    const fn primary(self) -> Option<ErrorPredicate> {
+        let mut index = 0;
+
+        while index < ErrorPredicate::CLASSIFICATION_ORDER.len() {
+            let predicate = ErrorPredicate::CLASSIFICATION_ORDER[index];
+
+            if self.contains(predicate) {
+                return Some(predicate);
+            }
+
+            index += 1;
+        }
+
+        None
+    }
 }
 
 impl From<&wreq::Error> for ErrorPredicates {
@@ -327,10 +345,8 @@ pub fn type_error(ruby: &Ruby, message: impl Into<Cow<'static, str>>) -> MagnusE
 
 /// Select the most specific Ruby exception class for native predicates.
 fn wreq_error_class(ruby: &Ruby, predicates: ErrorPredicates) -> ExceptionClass {
-    for &predicate in ErrorPredicate::CLASSIFICATION_ORDER {
-        if predicates.contains(predicate) {
-            return ruby.get_inner(predicate.error_class());
-        }
+    if let Some(predicate) = predicates.primary() {
+        return ruby.get_inner(predicate.error_class());
     }
 
     ruby.get_inner(&WREQ_ERROR)
@@ -339,7 +355,7 @@ fn wreq_error_class(ruby: &Ruby, predicates: ErrorPredicates) -> ExceptionClass
 /// Read one native predicate from a Ruby error, defaulting to false.
 fn error_has_predicate(rb_self: RObject, predicate: ErrorPredicate) -> Result<bool, MagnusError> {
     rb_self
-        .ivar_get::<_, Option<u16>>(ERROR_PREDICATES_IVAR)
+        .ivar_get::<_, Option<ErrorPredicateBits>>(ERROR_PREDICATES_IVAR)
         .map(|bits| bits.is_some_and(|bits| ErrorPredicates::from_bits(bits).contains(predicate)))
 }
 
@@ -436,4 +452,47 @@ mod tests {
             assert!(restored.contains(predicate));
         }
     }
+
+    #[test]
+    fn error_predicates_stabilize_primary_classification() {
+        let timeout_with_request = ErrorPredicate::CLASSIFICATION_ORDER
+            .iter()
+            .copied()
+            .filter(|predicate| matches!(predicate, ErrorPredicate::Timeout | ErrorPredicate::Request))
+            .fold(ErrorPredicates::default(), |predicates, predicate| {
+                predicates.include_if(predicate, true)
+            });
+        assert_eq!(Some(ErrorPredicate::Timeout), timeout_with_request.primary());
+
+        let connect_with_timeout_and_request = ErrorPredicate::CLASSIFICATION_ORDER
+            .iter()
+            .copied()
+            .filter(|predicate| {
+                matches!(
+                    predicate,
+                    ErrorPredicate::Connect | ErrorPredicate::Timeout | ErrorPredicate::Request
+                )
+            })
+            .fold(ErrorPredicates::default(), |predicates, predicate| {
+                predicates.include_if(predicate, true)
+            });
+        assert_eq!(Some(ErrorPredicate::Connect), connect_with_timeout_and_request.primary());
+
+        let body_with_timeout_and_request = ErrorPredicate::CLASSIFICATION_ORDER
+            .iter()
+            .copied()
+            .filter(|predicate| {
+                matches!(
+                    predicate,
+                    ErrorPredicate::Body | ErrorPredicate::Timeout | ErrorPredicate::Request
+                )
+            })
+            .fold(ErrorPredicates::default(), |predicates, predicate| {
+                predicates.include_if(predicate, true)
+            });
+        assert_eq!(Some(ErrorPredicate::Body), body_with_timeout_and_request.primary());
+
+        let no_predicates = ErrorPredicates::default();
+        assert!(no_predicates.primary().is_none());
+    }
 }