Project
Contributing
Thank you for your interest in contributing to Storine! Storine is built with strict performance, memory footprint, and safety invariants. Please review the guidelines below before opening an issue or pull request.
1. Core Engineering Invariants#
To keep Storine sub-microsecond, zero-copy, and crash-safe, every contribution must adhere to the following rules (detailed further in docs/RULES.md):
- Zero External Runtime Crates:
- All workspace crates compile using only the Rust standard library (
std,core,alloc) and OS-native system calls (Win32on Windows,libc/POSIX syscalls on Unix). Do not add external crates toCargo.tomldependencies without prior discussion.
- All workspace crates compile using only the Rust standard library (
- Strict
unsafeIsolation (RULE-SAFE-01):#![forbid(unsafe_code)]is enforced on all high-level crates (storage-types,storage-wal,storage-index,storage-graph,storage-core,storage-server,storage-cli).unsafeblocks are permitted only insidestorage-codec(zero-copy pointer casts and hardware SSE4.2 intrinsics) andstorage-mmap(OSmmap/CreateFileMappingWFFI), and everyunsafeblock must have an explicit// SAFETY:justification comment (#![deny(clippy::undocumented_unsafe_blocks)]).- Archived record types implement
storage_codec::ArchivePodonly viastorage_codec::impl_archive_pod!(ArchivedFoo { field: Type, ... }), which proves the no-padding / all-fields-pod contract at compile time. Never hand-writeunsafe impl ArchivePodoutsidestorage-codec. - Safe accessors over archived bytes must stay sound on hostile input: bounds-, alignment- and UTF-8-check, return empty/zeroed values, never panic.
- Zero Heap Allocations on Hot Read Paths (
RULE-MEM-01):StorageEngine::with_refandStorageEngine::get_refmust execute with0.00heap allocations per operation when reading clean memory-mapped records.- This is automatically verified by the
TrackingAllocatorgate inbenches/src/main.rs.
- No Panics or Poisoned Lock Crashes in Production Code:
- Never call
.unwrap()or.expect()on fallible I/O, network sockets, user inputs, or untrusted bytes. Always propagate a descriptiveStorageError. - Always recover from poisoned
Mutex/RwLockguards via.unwrap_or_else(|poisoned| poisoned.into_inner()).
- Never call
- Build-Independent On-Disk Formats (
RULE-SAFE-05):- Checksums and encodings must produce identical bytes on every build and platform; a hardware fast path must be bit-identical to its portable fallback and covered by a golden-value test.
- 64-Byte Cache-Line Alignment:
- All on-disk and in-memory record frames must remain 64-byte aligned (
RecordHeaderis exactly 64 bytes), and shared concurrent shard tables (PrimaryIndex,StripedLockTable) must remain cache-line padded (#[repr(align(64))]) to prevent false sharing.
- All on-disk and in-memory record frames must remain 64-byte aligned (
2. Development Workflow#
Prerequisites#
- Rust stable toolchain (
1.82+,2021edition; enforced byrust-versioninCargo.toml)
Building the Workspace#
cargo build --workspaceRunning the Full Test Suite#
Run all unit, integration, concurrency, corruption, and chaos crash-recovery tests (including a real process-kill test) across all crates:
cargo test --workspaceRunning the Zero-Allocation & Latency Benchmark Suite#
Verify that hot-read zero-allocation gates (0.00 Allocs/Op) and p50/p99/p99.9 latency targets pass:
cargo run --release -p storage-benchesOn a shared or busy machine, compare against the baseline by interleaving runs (baseline, candidate, baseline, candidate) rather than trusting a single run.
Running Lints#
Ensure there are zero compiler or Clippy warnings:
cargo clippy --workspace --all-targets3. Submitting a Pull Request#
- Fork & Branch: Create a descriptive feature or bugfix branch from
main(e.g.,feat/arena-prefetchorfix/wal-truncation). - Add Tests:
- Any bug fix or new capability should include a unit or integration test.
- Changes touching on-disk formats (
RecordHeader,STGEIDX2, orWAL1) must include corruption/bit-flip detection tests.
- Verify Benchmarks: If your change touches
storage-codec,storage-mmap,storage-index,storage-core, orstorage-server, runcargo run --release -p storage-benchesand include the before/after throughput andp50/p99numbers in your PR description. - Commit Messages: Use clear, descriptive commit messages following Conventional Commits (
feat: ...,fix: ...,perf: ...,docs: ...,test: ...).
4. License Agreement#
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Storine by you shall be dual-licensed under the MIT License (LICENSE) and Apache License, Version 2.0 (LICENSE-APACHE), without any additional terms or conditions.