feat: introduce the recoverable crate (#18)

Add a new `recoverable` crate that provides standardized types for
classifying
error conditions as recoverable or non-recoverable, enabling consistent
retry
behavior across different error types and resilience middleware.

Core features:
- `RecoveryInfo` type for classifying errors with recovery metadata
- `Recoverable` trait for types that can determine their recoverability
- `RecoveryKind` enum distinguishing between retry, outage, never, and
unknown
- Support for explicit retry delays via `delay()` method
- Service outage detection with optional recovery hints

Author: martintmk

.spelling

@@ -1,4 +1,4 @@
-294
+297
 0.X.Y
 100k
 10k
@@ -22,6 +22,7 @@ Async
 auditable
 backend
 backends
+backoff
 backtrace
 backtraces
 Backtraces
@@ -149,6 +150,7 @@ metadata
 Metas
 Microservices
 microsoft.com
+middleware
 mimalloc
 Mimalloc
 miri
@@ -197,6 +199,8 @@ Proc
 profiler
 PullRequest
 RDME
+recoverability
+recoverable
 Redis
 reentrancy
 relocations
@@ -292,4 +296,4 @@ workflows
 workspace
 w.r.t.
 Xamarin
-xxH3
+xxH3

CHANGELOG.md

@@ -12,6 +12,7 @@ Please see each crate's change log below:
 - [`fundle_macros_impl`](./crates/fundle_macros_impl/CHANGELOG.md)
 - [`ohno`](./crates/ohno/CHANGELOG.md)
 - [`ohno_macros`](./crates/ohno_macros/CHANGELOG.md)
+- [`recoverable`](./crates/recoverable/CHANGELOG.md)
 - [`thread_aware`](./crates/thread_aware/CHANGELOG.md)
 - [`thread_aware_macros`](./crates/thread_aware_macros/CHANGELOG.md)
 - [`thread_aware_macros_impl`](./crates/thread_aware_macros_impl/CHANGELOG.md)

Cargo.lock

@@ -34,6 +34,7 @@ fundle_macros = { path = "crates/fundle_macros", default-features = false, versi
 fundle_macros_impl = { path = "crates/fundle_macros_impl", default-features = false, version = "0.3.0" }
 ohno = { path = "crates/ohno", default-features = false, version = "0.2.0" }
 ohno_macros = { path = "crates/ohno_macros", default-features = false, version = "0.2.0" }
+recoverable = { path = "crates/recoverable", default-features = false, version = "0.1.0" }
 testing_aids = { path = "crates/testing_aids", default-features = false }
 thread_aware = { path = "crates/thread_aware", default-features = false, version = "0.6.0" }
 thread_aware_macros = { path = "crates/thread_aware_macros", default-features = false, version = "0.6.0" }

Cargo.toml

@@ -34,6 +34,7 @@ These are the crates built out of this repo:
 - [`fundle_macros_impl`](crates/fundle_macros_impl/README.md) - Macros for the `fundle` crate.
 - [`ohno`](./crates/ohno/README.md) - High-quality Rust error handling.
 - [`ohno_macros`](./crates/ohno_macros/README.md) - Macros for the `ohno` crate.
+- [`recoverable`](./crates/recoverable/README.md) - Recovery information and classification for resilience patterns.
 - [`thread_aware`](./crates/thread_aware/README.md) - Facilities to support thread-isolated state.
 - [`thread_aware_macros`](./crates/thread_aware_macros/README.md) - Macros for the `thread_aware` crate.
 - [`thread_aware_macros_impl`](./crates/thread_aware_macros_impl/README.md) - Macros for the `thread_aware` crate.

README.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [0.1.0] - 2025-12-30
+
+- ✨ Features
+
+  - introduce the recoverable crate

crates/recoverable/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+[package]
+name = "recoverable"
+description = "Recovery information and classification for resilience patterns."
+version = "0.1.0"
+readme = "README.md"
+keywords = ["oxidizer", "resilience", "metadata", "classification", "oxidizer"]
+categories = ["data-structures"]
+
+edition.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+
+[package.metadata.docs.rs]
+all-features = true
+
+[dependencies]
+
+[dev-dependencies]
+ohno.workspace = true
+static_assertions.workspace = true
+
+[lints]
+workspace = true

crates/recoverable/Cargo.toml

@@ -0,0 +1,97 @@
+<div align="center">
+ <img src="./logo.png" alt="Recoverable Logo" width="96">
+
+# Recoverable
+
+[![crate.io](https://img.shields.io/crates/v/recoverable.svg)](https://crates.io/crates/recoverable)
+[![docs.rs](https://docs.rs/recoverable/badge.svg)](https://docs.rs/recoverable)
+[![MSRV](https://img.shields.io/crates/msrv/recoverable)](https://crates.io/crates/recoverable)
+[![CI](https://github.com/microsoft/oxidizer/actions/workflows/main.yml/badge.svg?event=push)](https://github.com/microsoft/oxidizer/actions/workflows/main.yml)
+[![Coverage](https://codecov.io/gh/microsoft/oxidizer/graph/badge.svg?token=FCUG0EL5TI)](https://codecov.io/gh/microsoft/oxidizer)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+<a href="../.."><img src="../../logo.svg" alt="This crate was developed as part of the Oxidizer project" width="20"></a>
+
+</div>
+
+Recovery information and classification for resilience patterns.
+
+## Why
+
+This crate provides types for classifying conditions based on their **recoverability state**,
+enabling consistent recovery behavior across different error types and resilience middleware.
+
+## Recovery Information
+
+The recovery information describes whether recovering from an operation might help, not whether
+the operation succeeded or failed. Both successful operations and permanent failures
+should use [`RecoveryInfo::never`][__link0] since recovery is not necessary or desirable.
+
+## Core Types
+
+* [`RecoveryInfo`][__link1]: Classifies conditions as recoverable (transient) or non-recoverable (permanent/successful).
+* [`Recovery`][__link2]: A trait for types that can determine their recoverability.
+* [`RecoveryKind`][__link3]: An enum representing the kind of recovery that can be attempted.
+
+## Examples
+
+### Recovery Error
+
+```rust
+use recoverable::{Recovery, RecoveryInfo, RecoveryKind};
+
+#[derive(Debug)]
+enum DatabaseError {
+    ConnectionTimeout,
+    InvalidCredentials,
+    TableNotFound,
+}
+
+impl Recovery for DatabaseError {
+    fn recovery(&self) -> RecoveryInfo {
+        match self {
+            // Transient failure - might succeed if retried
+            DatabaseError::ConnectionTimeout => RecoveryInfo::retry(),
+            // Permanent failures - retrying won't help
+            DatabaseError::InvalidCredentials => RecoveryInfo::never(),
+            DatabaseError::TableNotFound => RecoveryInfo::never(),
+        }
+    }
+}
+
+let error = DatabaseError::ConnectionTimeout;
+assert_eq!(error.recovery().kind(), RecoveryKind::Retry);
+
+// For successful operations, also use never() since retry is unnecessary
+let success_result: Result<(), DatabaseError> = Ok(());
+// If we had a wrapper type for success, it would also return RecoveryInfo::never()
+```
+
+### Retry Delay
+
+You can specify when to retry an operation using the `delay` method:
+
+```rust
+use std::time::Duration;
+use recoverable::{RecoveryInfo, RecoveryKind};
+
+// Retry with a 30-second delay (e.g., from a Retry-After header)
+let recovery = RecoveryInfo::retry().delay(Duration::from_secs(30));
+assert_eq!(recovery.kind(), RecoveryKind::Retry);
+assert_eq!(recovery.get_delay(), Some(Duration::from_secs(30)));
+
+// Immediate retry
+let immediate = RecoveryInfo::retry().delay(Duration::ZERO);
+assert_eq!(immediate.get_delay(), Some(Duration::ZERO));
+```
+
+
+<hr/>
+<sub>
+This crate was developed as part of <a href="../..">The Oxidizer Project</a>. Browse this crate's <a href="https://github.com/microsoft/oxidizer/tree/main/crates/recoverable">source code</a>.
+</sub>
+
+ [__cargo_doc2readme_dependencies_info]: ggGkYW0CYXSEGy4k8ldDFPOhG2VNeXtD5nnKG6EPY6OfW5wBG8g18NOFNdxpYXKEG4cFLMVQymhvG3_1rzbl1X55G-vZhEWC9_13GwjdQK0PrVchYWSBgmtyZWNvdmVyYWJsZWUwLjEuMA
+ [__link0]: https://docs.rs/recoverable/0.1.0/recoverable/?search=RecoveryInfo::never
+ [__link1]: https://docs.rs/recoverable/0.1.0/recoverable/struct.RecoveryInfo.html
+ [__link2]: https://docs.rs/recoverable/0.1.0/recoverable/trait.Recovery.html
+ [__link3]: https://docs.rs/recoverable/0.1.0/recoverable/enum.RecoveryKind.html

crates/recoverable/README.md

@@ -0,0 +1,75 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! Example demonstrating how to use the `Recovery` trait with error types.
+//!
+//! This example shows how to implement the `Recovery` trait for custom error types
+//! and use `RecoveryInfo` to classify errors as transient or permanent.
+
+use std::error::Error;
+use std::fmt::Display;
+use std::time::Duration;
+
+use recoverable::{Recovery, RecoveryInfo, RecoveryKind};
+
+fn main() {
+    handle_network_error(&NetworkError::DnsResolutionFailed);
+    handle_network_error(&NetworkError::InvalidUrl);
+    handle_network_error(&NetworkError::ServiceUnavailable { retry_after: None });
+}
+
+/// A network error type demonstrating different recovery scenarios.
+#[derive(Debug)]
+enum NetworkError {
+    /// DNS resolution failed - might be transient
+    DnsResolutionFailed,
+    /// Invalid URL format - permanent error
+    InvalidUrl,
+    /// Service is unavailable, for example circuit breaker is open
+    ServiceUnavailable { retry_after: Option<Duration> },
+}
+
+impl Recovery for NetworkError {
+    fn recovery(&self) -> RecoveryInfo {
+        match self {
+            Self::DnsResolutionFailed => RecoveryInfo::retry(),
+            Self::InvalidUrl => RecoveryInfo::never(),
+            Self::ServiceUnavailable { retry_after: Some(after) } => RecoveryInfo::unavailable().delay(*after),
+            Self::ServiceUnavailable { retry_after: None } => RecoveryInfo::unavailable(),
+        }
+    }
+}
+
+impl Display for NetworkError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::DnsResolutionFailed => write!(f, "DNS resolution failed"),
+            Self::InvalidUrl => write!(f, "invalid URL format"),
+            Self::ServiceUnavailable { retry_after } => {
+                if let Some(after) = retry_after {
+                    write!(f, "service unavailable, retry after {after:?}")
+                } else {
+                    write!(f, "service unavailable")
+                }
+            }
+        }
+    }
+}
+
+impl Error for NetworkError {}
+
+/// Demonstrates handling network errors.
+fn handle_network_error(error: &NetworkError) {
+    let recovery = error.recovery();
+
+    println!("\nError: {error}");
+    println!("Recovery strategy: {recovery}");
+
+    match recovery.kind() {
+        RecoveryKind::Retry => println!("→ transient network issue, retry recommended"),
+        RecoveryKind::Unavailable => println!("→ service appears to be down"),
+        RecoveryKind::Never => println!("→ configuration or code change needed"),
+        RecoveryKind::Unknown => println!("→ unknown recovery status"),
+        _ => println!("→ unhandled recovery kind"),
+    }
+}

crates/recoverable/examples/recoverable_error.rs

@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! Example demonstrating how to use implement `Recovery` trait
+//! for errors implemented using the `ohno` crate.
+
+use recoverable::{Recovery, RecoveryInfo, RecoveryKind};
+
+fn main() {
+    handle_network_error(&NetworkError::dns_resolution_failed());
+    handle_network_error(&NetworkError::invalid_url());
+    handle_network_error(&NetworkError::service_unavailable());
+}
+
+/// A transparent network error type demonstrating different recovery scenarios.
+#[ohno::error]
+struct NetworkError {
+    recovery_info: RecoveryInfo,
+}
+
+impl NetworkError {
+    fn dns_resolution_failed() -> Self {
+        Self::caused_by(RecoveryInfo::retry(), "DNS resolution failed")
+    }
+
+    fn invalid_url() -> Self {
+        Self::caused_by(RecoveryInfo::never(), "invalid URL format")
+    }
+
+    fn service_unavailable() -> Self {
+        Self::caused_by(RecoveryInfo::unavailable(), "service unavailable")
+    }
+}
+
+impl Recovery for NetworkError {
+    fn recovery(&self) -> RecoveryInfo {
+        self.recovery_info.clone()
+    }
+}
+
+/// Demonstrates handling network errors.
+fn handle_network_error(error: &NetworkError) {
+    let recovery = error.recovery();
+
+    println!("\nError: {error}");
+    println!("Recovery strategy: {recovery}");
+
+    match recovery.kind() {
+        RecoveryKind::Retry => println!("→ transient network issue, retry recommended"),
+        RecoveryKind::Unavailable => println!("→ service appears to be down"),
+        RecoveryKind::Never => println!("→ configuration or code change needed"),
+        RecoveryKind::Unknown => println!("→ unknown recovery status"),
+        _ => println!("→ unhandled recovery kind"),
+    }
+}