|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +BackON is a Rust retry library that provides a fluent API for implementing retry logic with various backoff strategies. The library supports both synchronous and asynchronous operations, with cross-platform support including WASM and no_std environments. |
| 8 | + |
| 9 | +## Core Architecture |
| 10 | + |
| 11 | +- **Backoff Strategies** (`backon/src/backoff/`): Different retry timing strategies |
| 12 | + - `ExponentialBackoff`: Exponential backoff with optional jitter |
| 13 | + - `ConstantBackoff`: Fixed delay between retries |
| 14 | + - `FibonacciBackoff`: Fibonacci sequence-based delays |
| 15 | + - All implement the `Backoff` trait defined in `api.rs` |
| 16 | + |
| 17 | +- **Sleep Implementations** (`backon/src/sleep.rs`, `backon/src/blocking_sleep.rs`): Platform-specific sleep implementations |
| 18 | + - Async sleepers: `TokioSleeper`, `GlooTimersSleep`, `FutureTimerSleep`, `EmbassySleeper` |
| 19 | + - Blocking sleepers: `StdSleeper` |
| 20 | + - All sleepers implement `Sleeper` or `BlockingSleeper` traits |
| 21 | + |
| 22 | +- **Retry Logic** (`backon/src/retry.rs`, `backon/src/blocking_retry.rs`): Core retry functionality |
| 23 | + - `Retryable` trait for async functions |
| 24 | + - `BlockingRetryable` trait for sync functions |
| 25 | + - `RetryableWithContext` for functions that need mutable context |
| 26 | + |
| 27 | +- **Features**: Conditional compilation based on target and enabled features |
| 28 | + - Default features enable common sleepers for different platforms |
| 29 | + - WASM-specific implementations using `gloo-timers` |
| 30 | + - Embassy support for embedded environments |
| 31 | + |
| 32 | +## Development Commands |
| 33 | + |
| 34 | +```bash |
| 35 | +# Check code for errors |
| 36 | +cargo check |
| 37 | + |
| 38 | +# Build the project |
| 39 | +cargo build |
| 40 | + |
| 41 | +# Run linting (clippy) |
| 42 | +cargo clippy |
| 43 | + |
| 44 | +# Run tests |
| 45 | +cargo test |
| 46 | + |
| 47 | +# Run benchmarks |
| 48 | +cargo bench |
| 49 | + |
| 50 | +# Format code |
| 51 | +cargo fmt |
| 52 | +``` |
| 53 | + |
| 54 | +## Testing |
| 55 | + |
| 56 | +- Unit tests are in each module alongside the implementation |
| 57 | +- Integration tests demonstrate real-world usage patterns |
| 58 | +- WASM tests use `wasm-bindgen-test` |
| 59 | +- Platform-specific tests are gated by target architecture |
| 60 | + |
| 61 | +## Key Patterns |
| 62 | + |
| 63 | +- Builder pattern for backoff strategies (e.g., `ExponentialBuilder::default()`) |
| 64 | +- Trait-based design for extensibility (`Backoff`, `Sleeper`, `Retryable`) |
| 65 | +- Feature-gated implementations for different platforms |
| 66 | +- Zero-cost abstractions with compile-time feature selection |
| 67 | +- No-std compatibility with optional std features |
0 commit comments