# Randomio Project Guide
## Project Overview
**Randomio** is a Rust library that defines minimal capability traits for asynchronous, offset-addressable I/O. The core implementation is complete with comprehensive testing.
The project defines:
> "Can this device read/write bytes at arbitrary offsets asynchronously?"
### Design Philosophy
- **Zero policy**: No buffering, batching, or scheduling opinions
- **Zero-cost abstraction**: No allocation, dynamic dispatch, or `async_trait` macros
- **Device agnostic**: Works for files, block devices, object stores, network storage, io_uring, WASM
- **Capability, not policy**: Traits describe what backends CAN do, not how callers SHOULD use them
## Technology Stack
- **Language**: Rust (Edition 2021)
- **Version**: 0.4.0 (working toward 1.0.0 API freeze)
## Project Structure
```
randomio/
├── Cargo.toml # Package manifest
├── Cargo.lock # Dependency lock file
├── .gitignore # Ignores /target directory
├── AGENTS.md # This file
├── src/ # Source directory
│ ├── lib.rs # Library root
│ ├── io.rs # I/O error types (no_std compatible)
│ ├── block/ # Block type
│ ├── range/ # Range type
│ └── traits/ # Core traits
├── fuzz/ # Fuzz testing
│ ├── mem_backend/ # Reference implementation
│ ├── fuzz_targets/ # Fuzz harnesses
│ └── README.md # Fuzz documentation
├── docs/
│ ├── primitive.md # Core specification (v1.0)
│ └── API.md.bak # Older comprehensive spec
└── target/ # Build artifacts
```
## Build Commands
```bash
# Build the project
cargo build
# Build for release
cargo build --release
# Run tests
cargo test
# Run tests with no-default-features
cargo test --no-default-features
# Format
cargo fmt
# Lint
cargo clippy
# Run fuzz tests
cargo install cargo-fuzz
for target in write_model read_write_consistency cancellation overlap; do
cargo fuzz run $target -- -max_total_time=10
done
# Clean build artifacts
cargo clean
```
## Code Style Guidelines
### From the Specification (docs/primitive.md)
1. **Poll-based APIs only**: `async fn` is forbidden in core traits. Use `poll_*` methods:
```rust
fn poll_write_at(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
offset: u64,
buf: &[u8],
) -> Poll<io::Result<()>>;
```
2. **Trait requirements**:
- Traits require `Send`
- Traits do NOT require `Sync`
- Backends may assume exclusive mutable read (`&mut self`)
3. **Zero-allocation**: APIs must:
- Allocate nothing
- Avoid dynamic dispatch
- Be inlineable
- Match OS primitives closely
4. **Naming conventions**:
- `AsyncRandomWrite` — Core write capability
- `AsyncRandomRead` — Optional read capability
- `poll_*` prefix for poll-based methods
## Core Types and Traits
### Types (Frozen for 1.x)
```rust
/// Half-open byte interval [start, end)
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct Range {
pub start: u64,
pub end: u64,
}
/// Data block at specific offset
pub struct Block<B = bytes::Bytes> {
pub offset: u64,
pub data: B,
}
```
### Traits (Frozen for 1.x)
**AsyncRandomWrite** — Core write capability:
```rust
pub trait AsyncRandomWrite {
fn poll_write_at(/* ... */) -> Poll<io::Result<()>>;
fn poll_flush(/* ... */) -> Poll<io::Result<()>>;
fn poll_sync(/* ... */) -> Poll<io::Result<()>>;
}
```
**AsyncRandomRead** — Optional read capability:
```rust
pub trait AsyncRandomRead {
fn poll_read_at(/* ... */) -> Poll<io::Result<()>>;
}
```
## Testing Strategy
The project includes comprehensive test coverage:
### Unit Tests
- All core types (`Range`, `Block`)
- I/O error types (all 19 `ErrorKind` variants)
- Edge cases (u64::MAX boundaries, zero values)
- Feature-specific tests (bytes feature, std/no_std)
### Fuzz Testing
Production-grade fuzz targets testing:
- **write_model**: Write correctness using MemDevice oracle
- **read_write_consistency**: write_at → read_at consistency
- **cancellation**: Async cancellation safety (Poll → Pending → Drop → Retry)
- **overlap**: Deterministic overlapping writes
### Test Execution
```bash
# Unit tests
cargo test
cargo test --no-default-features
# Fuzz tests
for target in write_model read_write_consistency cancellation overlap; do
cargo fuzz run $target -- -max_total_time=10
done
# With sanitizers
RUSTFLAGS="-Zsanitizer=address" cargo test
```
See `fuzz/README.md` for detailed fuzzing architecture.
## Stability Policy
### Frozen Forever (1.x)
- Trait method signatures
- Trait semantics
- `Block` struct
- `Range` struct
### Additive Only
- New traits
- New structs
- Extension traits
- Feature flags
- Additional implementations
## What This Crate Does NOT Provide
Per the specification, the following are explicitly out of scope:
- ❌ Buffering
- ❌ Batching
- ❌ Ordering guarantees
- ❌ Durability tracking beyond OS
- ❌ Scheduling
- ❌ Sink/Stream adapters
- ❌ Runtime abstractions
- ❌ Device detection
- ❌ Filesystem helpers
- ❌ `async fn` wrappers in core traits
## Recommended Architecture (Future)
```
randomio-core ← traits only (this crate, frozen)
randomio-sink ← buffering/commit/durable ranges
randomio-uring ← io_uring backend
randomio-tokio ← tokio adapters
randomio-mem ← testing backend
randomio-wal ← write-ahead log runtime
```
## Key Documentation Files
| `docs/primitive.md` | **Current** core specification — start here for implementation |
| `docs/API.md.bak` | Older comprehensive spec with additional context (superseded) |
## Security Considerations
1. **Buffer ownership**: Submitting a `Block` transfers `Bytes` ownership to the sink
2. **No drop commit**: Dropping a sink does NOT call `commit()` — explicit call required
3. **Cancellation**: In-flight writes may be partially completed on task cancellation
4. **Thread safety**: `Send` but not `Sync` — callers must provide external synchronization
## Development Status
- **Current**: Core implementation complete, comprehensive testing in place
- **Version**: 0.4.0
- **Goal**: 1.0.0 API freeze with minimal frozen surface
- **Completed**:
- Core types (`Range`, `Block`, `Error`, `Result`)
- Core traits (`AsyncRandomWrite`, `AsyncRandomRead`)
- Unit tests (38 tests)
- Fuzz tests (4 production-grade targets)
- no_std support