ErrorKind: replace Transient with Unexpected; replace most uses of Un…

…available

src/error.rs

@@ -18,11 +18,10 @@ use std::error::Error as stdError;
 /// Error kind which can be matched over.
 #[derive(PartialEq, Eq, Debug, Copy, Clone)]
 pub enum ErrorKind {
-    /// Permanent failure: likely not recoverable without user action.
+    /// Feature is not available; not recoverable.
     Unavailable,
-    /// Temporary failure: recommended to retry a few times, but may also be
-    /// irrecoverable.
-    Transient,
+    /// Unexpected failure; there is a slim chance of recovery on retry.
+    Unexpected,
     /// Not ready yet: recommended to try again a little later.
     NotReady,
     /// Uncategorised error
@@ -37,7 +36,7 @@ impl ErrorKind {
     /// See also `should_wait()`.
     pub fn should_retry(self) -> bool {
         match self {
-            ErrorKind::Transient | ErrorKind::NotReady => true,
+            ErrorKind::Unexpected | ErrorKind::NotReady => true,
             _ => false,
         }
     }
@@ -52,10 +51,10 @@ impl ErrorKind {
     /// A description of this error kind
     pub fn description(self) -> &'static str {
         match self {
-            ErrorKind::Unavailable => "permanent failure",
-            ErrorKind::Transient => "transient failure",
+            ErrorKind::Unavailable => "permanently unavailable",
+            ErrorKind::Unexpected => "unexpected failure",
             ErrorKind::NotReady => "not ready yet",
-            ErrorKind::Other => "uncategorised",
+            ErrorKind::Other => "uncategorised error",
             ErrorKind::__Nonexhaustive => unreachable!(),
         }
     }

src/jitter.rs

@@ -145,6 +145,8 @@ impl ::std::error::Error for TimerError {
 
 impl From<TimerError> for Error {
     fn from(err: TimerError) -> Error {
+        // Timer check is already quite permissive of failures so we can assume
+        // any errors reported are irrecoverable.
         Error::with_cause(ErrorKind::Unavailable,
                               "timer jitter failed basic quality tests", err)
     }

src/os.rs

@@ -83,7 +83,7 @@ impl RngCore for OsRng {
                 }
 
                 match e.kind() {
-                    ErrorKind::Transient => {
+                    ErrorKind::Unexpected => {
                         if !error_logged {
                             warn!("OsRng failed; retrying up to {} times. Error: {}",
                                     TRANSIENT_RETRIES, e);
@@ -148,7 +148,7 @@ impl ReadRng {
         if (*guard).is_none() {
             info!("OsRng: opening random device {}", path.as_ref().display());
             let file = File::open(path).map_err(|err| Error::with_cause(
-                    ErrorKind::Unavailable,
+                    ErrorKind::Unexpected,
                     "error opening random device",
                     err
             ))?;
@@ -169,7 +169,7 @@ impl ReadRng {
         let mut file = (*guard).as_mut().unwrap();
         // Use `std::io::read_exact`, which retries on `ErrorKind::Interrupted`.
         file.read_exact(dest).map_err(|err| {
-            Error::with_cause(ErrorKind::Unavailable, "error reading random device", err)
+            Error::with_cause(ErrorKind::Unexpected, "error reading random device", err)
         })
     }
 }
@@ -250,7 +250,7 @@ mod imp {
                     ));
                 } else {
                     return Err(Error::with_cause(
-                        ErrorKind::Unavailable,
+                        ErrorKind::Unexpected,
                         "unexpected getrandom error",
                         err,
                     ));
@@ -353,7 +353,7 @@ mod imp {
                 // Cloudlibc provides its own `strerror` implementation so we
                 // can use `from_raw_os_error` here.
                 Err(Error::with_cause(
-                    ErrorKind::Unavailable,
+                    ErrorKind::Unexpected,
                     "random_get() system call failed",
                     io::Error::from_raw_os_error(errno),
                 ))
@@ -396,7 +396,7 @@ mod imp {
             };
             if ret == -1 {
                 Err(Error::with_cause(
-                    ErrorKind::Unavailable,
+                    ErrorKind::Unexpected,
                     "couldn't generate random bytes",
                     io::Error::last_os_error()))
             } else {
@@ -434,7 +434,7 @@ mod imp {
                 };
                 if ret == -1 || s_len != s.len() {
                     return Err(Error::with_cause(
-                        ErrorKind::Unavailable,
+                        ErrorKind::Unexpected,
                         "kern.arandom sysctl failed",
                         io::Error::last_os_error()));
                 }
@@ -468,7 +468,7 @@ mod imp {
                 };
                 if ret == -1 {
                     return Err(Error::with_cause(
-                        ErrorKind::Unavailable,
+                        ErrorKind::Unexpected,
                         "getentropy failed",
                         io::Error::last_os_error()));
                 }
@@ -523,7 +523,7 @@ mod imp {
                         Ok(actual) => filled += actual,
                         Err(e) => {
                             return Err(Error::with_cause(
-                                ErrorKind::Unavailable,
+                                ErrorKind::Unexpected,
                                 "cprng_draw failed",
                                 e));
                         }
@@ -564,7 +564,7 @@ mod imp {
                 };
                 if ret == 0 {
                     return Err(Error::with_cause(
-                        ErrorKind::Unavailable,
+                        ErrorKind::Unexpected,
                         "couldn't generate random bytes",
                         io::Error::last_os_error()));
                 }

src/read.rs

@@ -62,7 +62,7 @@ impl<R: Read> RngCore for ReadRng<R> {
         if dest.len() == 0 { return Ok(()); }
         // Use `std::io::read_exact`, which retries on `ErrorKind::Interrupted`.
         self.reader.read_exact(dest).map_err(|err| {
-            Error::with_cause(ErrorKind::Unavailable, "ReadRng: read error", err)
+            Error::with_cause(ErrorKind::Unexpected, "ReadRng: read error", err)
         })
     }
 }

src/reseeding.rs

@@ -121,7 +121,7 @@ impl<R: RngCore + SeedableRng, Rsdr: RngCore> ReseedingRng<R, Rsdr> {
     /// If reseeding fails, return an error with the original cause. Note that
     /// if the cause has a permanent failure, we report a transient error and
     /// skip reseeding; this means that only two error kinds can be reported
-    /// from this method: `ErrorKind::Transient` and `ErrorKind::NotReady`.
+    /// from this method: `ErrorKind::Unexpected` and `ErrorKind::NotReady`.
     #[inline(never)]
     pub fn try_reseed(&mut self) -> Result<(), Error> {
         trace!("Reseeding RNG after {} generated bytes",
@@ -130,10 +130,10 @@ impl<R: RngCore + SeedableRng, Rsdr: RngCore> ReseedingRng<R, Rsdr> {
                           .map(|result| self.rng = result) {
             let newkind = match err.kind() {
                 a @ ErrorKind::NotReady => a,
-                b @ ErrorKind::Transient => b,
+                b @ ErrorKind::Unexpected => b,
                 _ => {
                     self.bytes_until_reseed = self.threshold; // skip reseeding
-                    ErrorKind::Transient
+                    ErrorKind::Unexpected
                 }
             };
             return Err(Error::with_cause(newkind, "reseeding failed", err));