Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+This guide explains all configuration parameters available in ApexStore. All settings can be configured via environment variables without recompilation.
+# 1. Copy the example configuration
+cp .env.example .env
+
+# 2. Edit values as needed
+nano .env
+
+# 3. Run the server
+cargo run --release --features api --bin apexstore-server
+The server will load .env automatically and display all active configuration on startup.
| Variable | Default | Description |
|---|---|---|
HOST | 0.0.0.0 | Server bind address (0.0.0.0 = all interfaces) |
PORT | 8080 | Server port |
| Variable | Default | Description |
|---|---|---|
MAX_JSON_PAYLOAD_SIZE | 52428800 (50MB) | Maximum JSON request/response size |
MAX_RAW_PAYLOAD_SIZE | 52428800 (50MB) | Maximum raw payload size |
Recommendations:
+| Variable | Default | Description |
|---|---|---|
SERVER_WORKERS | 0 (CPU cores) | Number of worker threads |
SERVER_KEEP_ALIVE | 75 | Keep-alive timeout (seconds) |
SERVER_CLIENT_TIMEOUT | 60 | Client request timeout (seconds) |
SERVER_SHUTDOWN_TIMEOUT | 30 | Graceful shutdown timeout (seconds) |
SERVER_BACKLOG | 2048 | Maximum pending connections |
SERVER_MAX_CONNECTIONS | 25000 | Max concurrent connections per worker |
Recommendations:
+SERVER_WORKERS to 8-16SERVER_KEEP_ALIVE to 5-15SERVER_MAX_CONNECTIONS to 5000-10000| Variable | Default | Description |
|---|---|---|
DATA_DIR | ./.lsm_data | Data storage directory path |
| Variable | Default | Description |
|---|---|---|
MEMTABLE_MAX_SIZE | 4194304 (4MB) | Size threshold before flush to disk |
Impact:
+Recommendations:
+| Variable | Default | Description |
|---|---|---|
BLOCK_SIZE | 4096 (4KB) | Block size for SSTables |
BLOCK_CACHE_SIZE_MB | 64 | In-memory cache for blocks (MB) |
SPARSE_INDEX_INTERVAL | 16 | Blocks between index entries |
Block Size Impact:
+Cache Size Recommendations:
+Sparse Index:
+| Variable | Default | Description |
|---|---|---|
BLOOM_FALSE_POSITIVE_RATE | 0.01 (1%) | False positive probability |
Impact:
+Recommendations:
+| Variable | Default | Description |
|---|---|---|
MAX_WAL_RECORD_SIZE | 33554432 (32MB) | Maximum single record size |
WAL_BUFFER_SIZE | 65536 (64KB) | Write buffer size |
WAL_SYNC_MODE | always | Fsync strategy |
Sync Modes:
+always: Safest, slowest (every write synced)every_second: Balanced (1s of data loss possible)manual: Fastest, least safe (crash = data loss)Recommendations:
+alwaysevery_secondmanual| Variable | Default | Description |
|---|---|---|
COMPACTION_STRATEGY | lazy_leveling | Compaction algorithm |
SIZE_RATIO | 10 | Size ratio between levels |
LEVEL0_COMPACTION_THRESHOLD | 4 | L0 file count trigger |
MAX_LEVEL_COUNT | 7 | Maximum LSM tree levels |
COMPACTION_THREADS | 2 | Background compaction threads |
Compaction Strategies:
+leveled: Best read performancetiered: Best write performancelazy_leveling: Balanced (default)Recommendations:
+leveled, SIZE_RATIO=4-6tiered, SIZE_RATIO=15-20| Variable | Default | Description |
|---|---|---|
FEATURE_CACHE_TTL | 10 | Cache TTL in seconds |
High Memory → High Performance:
+MEMTABLE_MAX_SIZE=16777216 # 16MB
+BLOCK_CACHE_SIZE_MB=512 # 512MB
+BLOOM_FALSE_POSITIVE_RATE=0.001 # 0.1%
+SPARSE_INDEX_INTERVAL=8 # Dense
+
+Low Memory → Acceptable Performance:
+MEMTABLE_MAX_SIZE=2097152 # 2MB
+BLOCK_CACHE_SIZE_MB=32 # 32MB
+BLOOM_FALSE_POSITIVE_RATE=0.05 # 5%
+SPARSE_INDEX_INTERVAL=32 # Sparse
+Low Latency:
+BLOCK_SIZE=2048 # 2KB
+WAL_SYNC_MODE=every_second
+SERVER_KEEP_ALIVE=5
+
+High Throughput:
+BLOCK_SIZE=8192 # 8KB
+MEMTABLE_MAX_SIZE=16777216 # 16MB
+COMPACTION_THREADS=8
+WAL_BUFFER_SIZE=262144 # 256KB
+MAX_JSON_PAYLOAD_SIZE=104857600 # 100MB
+MAX_RAW_PAYLOAD_SIZE=104857600
+MEMTABLE_MAX_SIZE=16777216 # 16MB
+BLOCK_SIZE=8192
+BLOCK_CACHE_SIZE_MB=256
+WAL_SYNC_MODE=every_second
+COMPACTION_THREADS=4
+MEMTABLE_MAX_SIZE=8388608 # 8MB
+BLOCK_SIZE=8192
+BLOOM_FALSE_POSITIVE_RATE=0.05
+WAL_SYNC_MODE=every_second
+WAL_BUFFER_SIZE=262144 # 256KB
+COMPACTION_THREADS=4
+LEVEL0_COMPACTION_THRESHOLD=8
+COMPACTION_STRATEGY=tiered
+BLOCK_CACHE_SIZE_MB=512
+BLOOM_FALSE_POSITIVE_RATE=0.001
+SPARSE_INDEX_INTERVAL=8
+COMPACTION_STRATEGY=leveled
+SIZE_RATIO=4
+MEMTABLE_MAX_SIZE=2097152 # 2MB
+BLOCK_CACHE_SIZE_MB=32
+BLOOM_FALSE_POSITIVE_RATE=0.05
+SPARSE_INDEX_INTERVAL=32
+SERVER_MAX_CONNECTIONS=5000
+COMPACTION_THREADS=1
+MEMTABLE_MAX_SIZE=4194304 # 4MB
+BLOCK_SIZE=4096
+BLOCK_CACHE_SIZE_MB=128
+BLOOM_FALSE_POSITIVE_RATE=0.01
+WAL_SYNC_MODE=always
+COMPACTION_THREADS=2
+SERVER_WORKERS=4
+SERVER_MAX_CONNECTIONS=10000
+MEMTABLE_MAX_SIZEBLOCK_CACHE_SIZE_MBBLOOM_FALSE_POSITIVE_RATESPARSE_INDEX_INTERVALSERVER_MAX_CONNECTIONSMEMTABLE_MAX_SIZEWAL_SYNC_MODE to every_secondWAL_BUFFER_SIZECOMPACTION_THREADSCOMPACTION_STRATEGY=tieredBLOCK_CACHE_SIZE_MBBLOOM_FALSE_POSITIVE_RATESPARSE_INDEX_INTERVALCOMPACTION_STRATEGY=leveledSIZE_RATIOMAX_JSON_PAYLOAD_SIZEMAX_RAW_PAYLOAD_SIZEulimit -n 65536MAX_LEVEL_COUNTLEVEL0_COMPACTION_THRESHOLDSIZE_RATIO# Enable detailed logging
+RUST_LOG=debug cargo run --features api --bin apexstore-server
+
+# Watch server startup for configuration values
+# The server prints all active config on startup
+
+# Monitor metrics via /stats endpoint
+curl http://localhost:8080/stats/all
+/stats/all endpointRUST_LOG=debug
+MAX_JSON_PAYLOAD_SIZE=104857600
+WAL_SYNC_MODE=manual
+RUST_LOG=info
+MAX_JSON_PAYLOAD_SIZE=52428800
+WAL_SYNC_MODE=every_second
+RUST_LOG=warn
+MAX_JSON_PAYLOAD_SIZE=10485760
+WAL_SYNC_MODE=always
+SERVER_WORKERS=8
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+First off, thank you for considering contributing to ApexStore! 🎉
+This document provides guidelines and instructions for contributing to the project. Following these guidelines helps maintain code quality and makes the review process smoother.
+We are committed to providing a welcoming and inspiring community for all. We pledge to:
+Rust Toolchain (1.70 or later)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+Git
+# Ubuntu/Debian
+sudo apt-get install git
+
+# macOS
+brew install git
+Code Editor (Recommended: VS Code with rust-analyzer)
+Fork the Repository
+Clone Your Fork
+git clone https://github.com/YOUR_USERNAME/ApexStore.git
+cd ApexStore
+Add Upstream Remote
+git remote add upstream https://github.com/ElioNeto/ApexStore.git
+Install Dependencies
+cargo build
+Run Tests
+cargo test
+For detailed setup instructions, see SETUP.md.
+ApexStore uses GitHub Actions to automate the development workflow:
+develop + run testsmainSee WORKFLOWS.md for complete documentation.
+# Update your fork
+git checkout main
+git pull upstream main
+
+# Create a new branch from main
+git checkout -b feature/your-feature-name
+Branch Naming Conventions:
+feature/ - New features (e.g., feature/compaction-strategy)fix/ - Bug fixes (e.g., fix/wal-corruption)docs/ - Documentation changes (e.g., docs/api-guide)refactor/ - Code refactoring (e.g., refactor/codec-interface)test/ - Test additions/improvements (e.g., test/integration-suite)perf/ - Performance improvements (e.g., perf/bloom-filter-optimization)# Make changes to the code
+vim src/core/engine.rs
+
+# Test your changes
+cargo test --all-features
+
+# Format code
+cargo fmt
+
+# Check for issues
+cargo clippy --all-features -- -D warnings
+git add .
+git commit -m "feat: add compaction strategy interface (#55)"
+Important: Reference issues in commit messages using #issue_number for automatic tracking.
See Commit Messages for formatting guidelines.
+git push origin feature/your-feature-name
+What Happens Next:
+develop branchOnce the automated PR is created:
+develop once approvedNote: You don’t need to manually create PRs - the workflow handles this automatically!
+We follow the Rust API Guidelines and Rust Style Guide.
+Key Principles:
+Use cargo fmt - All code must be formatted
cargo fmt --all
+Pass cargo clippy - Zero warnings policy
cargo clippy --all-features -- -D warnings
+Write Documentation - Public APIs must have doc comments
+#![allow(unused)]
+fn main() {
+/// Retrieves a value from the store by key.
+///
+/// # Arguments
+///
+/// * `key` - The key to look up
+///
+/// # Returns
+///
+/// * `Ok(Some(value))` - Key found
+/// * `Ok(None)` - Key not found
+/// * `Err(e)` - Error occurred
+///
+/// # Example
+///
+/// ```
+/// let value = engine.get(b"user:123")?;
+/// ```
+pub fn get(&self, key: &[u8]) -> Result<Option<String>> {
+ // Implementation
+}
+}This project follows SOLID principles:
+Example:
+#![allow(unused)]
+fn main() {
+// ✅ Good - depends on trait
+pub struct LsmEngine<W: WriteAheadLog> {
+ wal: W,
+}
+
+// ❌ Bad - depends on concrete type
+pub struct LsmEngine {
+ wal: FileBasedWal,
+}
+}Use Result<T, LsmError> for fallible operations
#![allow(unused)]
+fn main() {
+pub fn put(&mut self, key: &[u8], value: &str) -> Result<()> {
+ self.wal.append(key, value)?;
+ self.memtable.insert(key, value);
+ Ok(())
+}
+}Provide Context with error types
+#![allow(unused)]
+fn main() {
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum LsmError {
+ #[error("WAL corruption at offset {0}")]
+ WalCorruption(u64),
+
+ #[error("Key too large: {size} bytes (max: {max})")]
+ KeyTooLarge { size: usize, max: usize },
+}
+}Don’t Panic in library code (use Result instead)
Minimize Allocations
+#![allow(unused)]
+fn main() {
+// ✅ Good - reuse buffer
+let mut buffer = Vec::with_capacity(1024);
+for item in items {
+ buffer.clear();
+ serialize_into(&mut buffer, item)?;
+}
+
+// ❌ Bad - allocate each iteration
+for item in items {
+ let buffer = serialize(item)?;
+}
+}Use Appropriate Data Structures
+BTreeMap for sorted dataHashMap for fast lookupsVec for sequential accessBenchmark Changes
+cargo bench
+Unit Tests - Test individual functions/modules
+#![allow(unused)]
+fn main() {
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn test_memtable_insert() {
+ let mut memtable = MemTable::new();
+ memtable.insert(b"key", "value");
+ assert_eq!(memtable.get(b"key"), Some("value".to_string()));
+ }
+}
+}Integration Tests - Test component interactions
+#![allow(unused)]
+fn main() {
+// tests/integration_test.rs
+#[test]
+fn test_engine_recovery() {
+ let config = LsmConfig::default();
+ let mut engine = LsmEngine::new(config).unwrap();
+
+ engine.put(b"key", "value").unwrap();
+ drop(engine);
+
+ let engine = LsmEngine::new(config).unwrap();
+ assert_eq!(engine.get(b"key").unwrap(), Some("value".to_string()));
+}
+}Property Tests - Test invariants (optional, using proptest)
#![allow(unused)]
+fn main() {
+#[test]
+fn test_get_returns_none_for_nonexistent_key() { /* ... */ }
+}# Run all tests
+cargo test --all-features
+
+# Run specific test
+cargo test test_memtable_insert
+
+# Run with output
+cargo test -- --nocapture
+
+# Run integration tests only
+cargo test --test '*'
+
+# Run with coverage (requires tarpaulin)
+cargo tarpaulin --out Html
+We follow the Conventional Commits specification.
+<type>(<scope>): <subject> (#issue)
+
+<body>
+
+<footer>
+feat - New featurefix - Bug fixdocs - Documentation changesstyle - Code style changes (formatting, etc.)refactor - Code refactoringperf - Performance improvementstest - Test additions/modificationschore - Build process, dependencies, toolingci - CI/CD changesSimple commit:
+feat: add bloom filter to SSTable reader
+With scope and issue:
+fix(wal): prevent corruption on unclean shutdown (#42)
+With body:
+feat(compaction): implement leveled compaction strategy (#47)
+
+Adds a new LeveledCompaction struct that implements the Compaction
+trait. This strategy reduces read amplification by maintaining
+sorted levels with exponentially increasing sizes.
+
+Closes #47
+Breaking change:
+feat(api)!: change SSTable format to V2
+
+BREAKING CHANGE: SSTable V2 is incompatible with V1.
+Migration tool will be provided in v1.4.
+Referencing Issues:
+#123 - Reference issuefixes #123, closes #123 - Will auto-close issue when PR mergesresolves #123 - Alternative close syntaxcargo test --all-features)cargo clippy --all-features -- -D warnings)cargo fmt)When you push to a feature/* or fix/* branch:
develop branchIf you need to create a PR manually:
+develop as the base branchWhen creating a PR manually, use this template:
+## Description
+
+Brief description of changes.
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Related Issues
+
+Closes #123
+Related to #456
+
+## Testing
+
+Describe how you tested your changes:
+- [ ] Unit tests added
+- [ ] Integration tests added
+- [ ] Manual testing performed
+
+## Checklist
+
+- [ ] Code compiles
+- [ ] Tests pass
+- [ ] Clippy checks pass
+- [ ] Code is formatted
+- [ ] Documentation updated
+
+## Screenshots (if applicable)
+
+## Additional Notes
+developApexStore/
+├── src/
+│ ├── core/ # Core domain logic
+│ │ ├── engine.rs # LSM engine orchestration
+│ │ ├── memtable.rs # In-memory storage
+│ │ └── log_record.rs # Data model
+│ ├── storage/ # Persistence layer
+│ │ ├── wal.rs # Write-ahead log
+│ │ ├── sstable.rs # SSTable reader
+│ │ └── builder.rs # SSTable writer
+│ ├── infra/ # Infrastructure
+│ │ ├── codec.rs # Serialization
+│ │ ├── error.rs # Error types
+│ │ └── config.rs # Configuration
+│ ├── api/ # HTTP API (feature-gated)
+│ ├── cli/ # CLI interface
+│ └── features/ # Feature flags
+├── tests/ # Integration tests
+├── benches/ # Benchmarks
+└── docs/ # Documentation
+core/ - Domain logic, no external dependenciesstorage/ - File I/O, persistenceinfra/ - Cross-cutting concernsapi/ - External interfaces (feature-gated)CI/CD Testing Pipeline (#55)
+Compaction Implementation (#47)
+Efficient Iterators (#21, #22, #23)
+Benchmarking Suite (#48)
+CLI Command Equalization (#65)
+Checksums & Integrity (#25)
+Add More Tests
+Binary Search Optimization (#37)
+Documentation Improvements
+Replication Support
+Snapshot Isolation
+mainThank you for contributing! 🎉
+Last updated: March 2026
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+This guide will help you set up a development environment for ApexStore.
+# Install Rust using rustup (recommended)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# Follow the prompts, then reload your shell
+source $HOME/.cargo/env
+# Check Rust version (should be 1.70+)
+rustc --version
+# Output: rustc 1.75.0 (or higher)
+
+# Check Cargo version
+cargo --version
+# Output: cargo 1.75.0 (or higher)
+# Install Clippy (linter)
+rustup component add clippy
+
+# Install rustfmt (formatter)
+rustup component add rustfmt
+
+# Install rust-src (for IDE support)
+rustup component add rust-src
+sudo apt-get update
+sudo apt-get install git
+# Using Homebrew
+brew install git
+
+# Or install Xcode Command Line Tools
+xcode-select --install
+Download from git-scm.com
+git --version
+# Output: git version 2.x.x
+# Ubuntu/Debian
+sudo snap install code --classic
+
+# macOS
+brew install --cask visual-studio-code
+Essential:
+rust-analyzer - Rust language support
+rust-lang.rust-analyzerCodeLLDB (optional) - Debugging support
+vadimcn.vscode-lldbRecommended: +3. Better TOML - TOML syntax highlighting
+bungcip.better-tomlError Lens - Inline error highlighting
+usernamehw.errorlenscrates - Cargo.toml dependency management
+serayuzgur.cratesCreate .vscode/settings.json in project root:
{
+ "rust-analyzer.checkOnSave.command": "clippy",
+ "rust-analyzer.cargo.features": "all",
+ "editor.formatOnSave": true,
+ "[rust]": {
+ "editor.defaultFormatter": "rust-lang.rust-analyzer"
+ }
+}
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/ApexStore.git
+cd ApexStore
+
+# Add upstream remote
+git remote add upstream https://github.com/ElioNeto/ApexStore.git
+
+# Verify remotes
+git remote -v
+# Debug build (faster compilation)
+cargo build
+
+# Release build (optimized)
+cargo build --release
+
+# Build with API feature
+cargo build --release --features api
+First build may take 5-10 minutes as Cargo downloads and compiles dependencies.
+# Run all tests
+cargo test
+
+# Run tests with output
+cargo test -- --nocapture
+
+# Run specific test
+cargo test test_memtable_insert
+# Copy environment template
+cp .env.example .env
+
+# Edit configuration (optional)
+nano .env
+Example Development Configuration (.env):
# Server
+HOST=127.0.0.1
+PORT=8080
+
+# LSM Engine
+DATA_DIR=.lsm_data_dev
+MEMTABLE_MAX_SIZE=2097152 # 2MB for faster flushing in dev
+BLOCK_CACHE_SIZE_MB=32
+
+# Logging
+RUST_LOG=debug
+ENABLE_METRICS=true
+# Debug mode
+cargo run
+
+# Release mode (faster)
+cargo run --release
+Available REPL Commands:
+> help # Show available commands
+> put key value # Insert or update key
+> get key # Retrieve value
+> delete key # Delete key (tombstone)
+> stats # Show statistics
+> exit # Exit REPL
+# Debug mode
+cargo run --features api --bin apexstore-server
+
+# Release mode
+cargo run --release --features api --bin apexstore-server
+
+# With custom port
+PORT=3000 cargo run --release --features api --bin apexstore-server
+Testing the API:
+# Insert a key
+curl -X POST http://localhost:8080/keys \
+ -H "Content-Type: application/json" \
+ -d '{"key": "user:1", "value": "Alice"}'
+
+# Get a key
+curl http://localhost:8080/keys/user:1
+
+# Get statistics
+curl http://localhost:8080/stats/all
+# Format code
+cargo fmt
+
+# Check formatting (CI mode)
+cargo fmt -- --check
+
+# Run Clippy linter
+cargo clippy
+
+# Clippy with strict mode (CI mode)
+cargo clippy -- -D warnings
+
+# Check for unused dependencies
+cargo machete # Requires: cargo install cargo-machete
+# Install criterion
+cargo install cargo-criterion
+
+# Run all benchmarks
+cargo bench
+
+# Run specific benchmark
+cargo bench memtable_insert
+
+# Generate HTML report
+open target/criterion/report/index.html
+# Build production image
+docker build -t apexstore:dev .
+
+# Run in development mode with volume mount
+docker run -d \
+ --name apexstore-dev \
+ -p 8080:8080 \
+ -v $(pwd)/data:/data \
+ -v $(pwd)/.env:/app/.env \
+ apexstore:dev
+# Start services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f apexstore
+
+# Restart after code changes
+docker-compose restart
+
+# Stop services
+docker-compose down
+.vscode/launch.json:{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "type": "lldb",
+ "request": "launch",
+ "name": "Debug CLI",
+ "cargo": {
+ "args": ["build", "--bin=apexstore"]
+ },
+ "args": [],
+ "cwd": "${workspaceFolder}"
+ },
+ {
+ "type": "lldb",
+ "request": "launch",
+ "name": "Debug Server",
+ "cargo": {
+ "args": ["build", "--features", "api", "--bin=apexstore-server"]
+ },
+ "args": [],
+ "cwd": "${workspaceFolder}"
+ },
+ {
+ "type": "lldb",
+ "request": "launch",
+ "name": "Debug Test",
+ "cargo": {
+ "args": ["test", "--no-run", "--lib"]
+ },
+ "args": ["test_memtable_insert"],
+ "cwd": "${workspaceFolder}"
+ }
+ ]
+}
+F5 to start debuggingprintln! Debugging#![allow(unused)]
+fn main() {
+// In your code
+pub fn put(&mut self, key: &[u8], value: &str) -> Result<()> {
+ println!("[DEBUG] Inserting key: {:?}", String::from_utf8_lossy(key));
+ self.wal.append(key, value)?;
+ println!("[DEBUG] WAL append successful");
+ self.memtable.insert(key, value);
+ Ok(())
+}
+}Run with:
+cargo run -- 2>&1 | grep DEBUG
+RUST_LOG# Set log level
+export RUST_LOG=debug
+
+# Or inline
+RUST_LOG=trace cargo run
+
+# Filter by module
+RUST_LOG=apexstore::core::engine=debug cargo run
+# Install flamegraph
+cargo install flamegraph
+
+# Generate flamegraph
+sudo cargo flamegraph --bin apexstore-server
+
+# Open flamegraph.svg in browser
+firefox flamegraph.svg
+# Using valgrind (Linux)
+valgrind --leak-check=full --track-origins=yes \
+ ./target/debug/apexstore
+
+# Using heaptrack (Linux)
+heaptrack ./target/debug/apexstore
+heaptrack_gui heaptrack.apexstore.*.gz
+# Profile specific benchmark
+cargo bench --bench memtable_bench -- --profile-time=10
+
+# With flamegraph
+cargo flamegraph --bench memtable_bench
+# Run all unit tests
+cargo test --lib
+
+# Run tests in specific module
+cargo test --lib core::memtable
+
+# Run single test
+cargo test test_memtable_insert
+# Run all integration tests
+cargo test --test '*'
+
+# Run specific integration test file
+cargo test --test recovery_test
+# Install tarpaulin (Linux only)
+cargo install cargo-tarpaulin
+
+# Generate coverage report
+cargo tarpaulin --out Html
+
+# Open report
+firefox tarpaulin-report.html
+# Create stress test script
+cat > stress_test.sh << 'EOF'
+#!/bin/bash
+for i in {1..10000}; do
+ curl -X POST http://localhost:8080/keys \
+ -H "Content-Type: application/json" \
+ -d "{\"key\": \"key_$i\", \"value\": \"value_$i\"}" &
+done
+wait
+EOF
+
+chmod +x stress_test.sh
+
+# Run stress test
+./stress_test.sh
+# Generate and open docs
+cargo doc --open
+
+# Include private items
+cargo doc --document-private-items --open
+
+# Generate for all features
+cargo doc --all-features --open
+All public APIs should have documentation:
+#![allow(unused)]
+fn main() {
+/// Brief description (appears in summary).
+///
+/// Longer description with more details.
+///
+/// # Arguments
+///
+/// * `key` - Description of key parameter
+/// * `value` - Description of value parameter
+///
+/// # Returns
+///
+/// Description of return value
+///
+/// # Errors
+///
+/// Description of possible errors
+///
+/// # Examples
+///
+/// ```
+/// let engine = LsmEngine::new(config)?;
+/// engine.put(b"key", "value")?;
+/// ```
+///
+/// # Panics
+///
+/// Description of panic conditions (if any)
+///
+/// # Safety
+///
+/// Description of safety requirements (for unsafe functions)
+pub fn put(&mut self, key: &[u8], value: &str) -> Result<()> {
+ // Implementation
+}
+}# Clean build artifacts
+cargo clean
+
+# Update dependencies
+cargo update
+
+# Rebuild
+cargo build
+# Run tests serially (not in parallel)
+cargo test -- --test-threads=1
+# Find process using port 8080
+lsof -i :8080 # macOS/Linux
+
+# Kill process
+kill -9 <PID>
+
+# Or use different port
+PORT=3000 cargo run --features api --bin apexstore-server
+# Clean target directory (safe, can be rebuilt)
+rm -rf target/
+
+# Clean cargo cache
+cargo cache --autoclean
+# Use faster linker (Linux)
+sudo apt-get install lld
+export RUSTFLAGS="-C link-arg=-fuse-ld=lld"
+
+# Or use mold (even faster)
+cargo install mold
+export RUSTFLAGS="-C link-arg=-fuse-ld=mold"
+
+# Enable incremental compilation (in Cargo.toml)
+[profile.dev]
+incremental = true
+cargo doc --openHappy Coding! 🦀
+Last updated: March 2026
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+This guide explains all configuration parameters available in ApexStore. All settings can be configured via environment variables without recompilation.
+# 1. Copy the example configuration
+cp .env.example .env
+
+# 2. Edit values as needed
+nano .env
+
+# 3. Run the server
+cargo run --release --features api --bin apexstore-server
+The server will load .env automatically and display all active configuration on startup.
| Variable | Default | Description |
|---|---|---|
HOST | 0.0.0.0 | Server bind address (0.0.0.0 = all interfaces) |
PORT | 8080 | Server port |
| Variable | Default | Description |
|---|---|---|
MAX_JSON_PAYLOAD_SIZE | 52428800 (50MB) | Maximum JSON request/response size |
MAX_RAW_PAYLOAD_SIZE | 52428800 (50MB) | Maximum raw payload size |
Recommendations:
+| Variable | Default | Description |
|---|---|---|
SERVER_WORKERS | 0 (CPU cores) | Number of worker threads |
SERVER_KEEP_ALIVE | 75 | Keep-alive timeout (seconds) |
SERVER_CLIENT_TIMEOUT | 60 | Client request timeout (seconds) |
SERVER_SHUTDOWN_TIMEOUT | 30 | Graceful shutdown timeout (seconds) |
SERVER_BACKLOG | 2048 | Maximum pending connections |
SERVER_MAX_CONNECTIONS | 25000 | Max concurrent connections per worker |
Recommendations:
+SERVER_WORKERS to 8-16SERVER_KEEP_ALIVE to 5-15SERVER_MAX_CONNECTIONS to 5000-10000| Variable | Default | Description |
|---|---|---|
DATA_DIR | ./.lsm_data | Data storage directory path |
| Variable | Default | Description |
|---|---|---|
MEMTABLE_MAX_SIZE | 4194304 (4MB) | Size threshold before flush to disk |
Impact:
+Recommendations:
+| Variable | Default | Description |
|---|---|---|
BLOCK_SIZE | 4096 (4KB) | Block size for SSTables |
BLOCK_CACHE_SIZE_MB | 64 | In-memory cache for blocks (MB) |
SPARSE_INDEX_INTERVAL | 16 | Blocks between index entries |
Block Size Impact:
+Cache Size Recommendations:
+Sparse Index:
+| Variable | Default | Description |
|---|---|---|
BLOOM_FALSE_POSITIVE_RATE | 0.01 (1%) | False positive probability |
Impact:
+Recommendations:
+| Variable | Default | Description |
|---|---|---|
MAX_WAL_RECORD_SIZE | 33554432 (32MB) | Maximum single record size |
WAL_BUFFER_SIZE | 65536 (64KB) | Write buffer size |
WAL_SYNC_MODE | always | Fsync strategy |
Sync Modes:
+always: Safest, slowest (every write synced)every_second: Balanced (1s of data loss possible)manual: Fastest, least safe (crash = data loss)Recommendations:
+alwaysevery_secondmanual| Variable | Default | Description |
|---|---|---|
COMPACTION_STRATEGY | lazy_leveling | Compaction algorithm |
SIZE_RATIO | 10 | Size ratio between levels |
LEVEL0_COMPACTION_THRESHOLD | 4 | L0 file count trigger |
MAX_LEVEL_COUNT | 7 | Maximum LSM tree levels |
COMPACTION_THREADS | 2 | Background compaction threads |
Compaction Strategies:
+leveled: Best read performancetiered: Best write performancelazy_leveling: Balanced (default)Recommendations:
+leveled, SIZE_RATIO=4-6tiered, SIZE_RATIO=15-20| Variable | Default | Description |
|---|---|---|
FEATURE_CACHE_TTL | 10 | Cache TTL in seconds |
High Memory → High Performance:
+MEMTABLE_MAX_SIZE=16777216 # 16MB
+BLOCK_CACHE_SIZE_MB=512 # 512MB
+BLOOM_FALSE_POSITIVE_RATE=0.001 # 0.1%
+SPARSE_INDEX_INTERVAL=8 # Dense
+
+Low Memory → Acceptable Performance:
+MEMTABLE_MAX_SIZE=2097152 # 2MB
+BLOCK_CACHE_SIZE_MB=32 # 32MB
+BLOOM_FALSE_POSITIVE_RATE=0.05 # 5%
+SPARSE_INDEX_INTERVAL=32 # Sparse
+Low Latency:
+BLOCK_SIZE=2048 # 2KB
+WAL_SYNC_MODE=every_second
+SERVER_KEEP_ALIVE=5
+
+High Throughput:
+BLOCK_SIZE=8192 # 8KB
+MEMTABLE_MAX_SIZE=16777216 # 16MB
+COMPACTION_THREADS=8
+WAL_BUFFER_SIZE=262144 # 256KB
+MAX_JSON_PAYLOAD_SIZE=104857600 # 100MB
+MAX_RAW_PAYLOAD_SIZE=104857600
+MEMTABLE_MAX_SIZE=16777216 # 16MB
+BLOCK_SIZE=8192
+BLOCK_CACHE_SIZE_MB=256
+WAL_SYNC_MODE=every_second
+COMPACTION_THREADS=4
+MEMTABLE_MAX_SIZE=8388608 # 8MB
+BLOCK_SIZE=8192
+BLOOM_FALSE_POSITIVE_RATE=0.05
+WAL_SYNC_MODE=every_second
+WAL_BUFFER_SIZE=262144 # 256KB
+COMPACTION_THREADS=4
+LEVEL0_COMPACTION_THRESHOLD=8
+COMPACTION_STRATEGY=tiered
+BLOCK_CACHE_SIZE_MB=512
+BLOOM_FALSE_POSITIVE_RATE=0.001
+SPARSE_INDEX_INTERVAL=8
+COMPACTION_STRATEGY=leveled
+SIZE_RATIO=4
+MEMTABLE_MAX_SIZE=2097152 # 2MB
+BLOCK_CACHE_SIZE_MB=32
+BLOOM_FALSE_POSITIVE_RATE=0.05
+SPARSE_INDEX_INTERVAL=32
+SERVER_MAX_CONNECTIONS=5000
+COMPACTION_THREADS=1
+MEMTABLE_MAX_SIZE=4194304 # 4MB
+BLOCK_SIZE=4096
+BLOCK_CACHE_SIZE_MB=128
+BLOOM_FALSE_POSITIVE_RATE=0.01
+WAL_SYNC_MODE=always
+COMPACTION_THREADS=2
+SERVER_WORKERS=4
+SERVER_MAX_CONNECTIONS=10000
+MEMTABLE_MAX_SIZEBLOCK_CACHE_SIZE_MBBLOOM_FALSE_POSITIVE_RATESPARSE_INDEX_INTERVALSERVER_MAX_CONNECTIONSMEMTABLE_MAX_SIZEWAL_SYNC_MODE to every_secondWAL_BUFFER_SIZECOMPACTION_THREADSCOMPACTION_STRATEGY=tieredBLOCK_CACHE_SIZE_MBBLOOM_FALSE_POSITIVE_RATESPARSE_INDEX_INTERVALCOMPACTION_STRATEGY=leveledSIZE_RATIOMAX_JSON_PAYLOAD_SIZEMAX_RAW_PAYLOAD_SIZEulimit -n 65536MAX_LEVEL_COUNTLEVEL0_COMPACTION_THRESHOLDSIZE_RATIO# Enable detailed logging
+RUST_LOG=debug cargo run --features api --bin apexstore-server
+
+# Watch server startup for configuration values
+# The server prints all active config on startup
+
+# Monitor metrics via /stats endpoint
+curl http://localhost:8080/stats/all
+/stats/all endpointRUST_LOG=debug
+MAX_JSON_PAYLOAD_SIZE=104857600
+WAL_SYNC_MODE=manual
+RUST_LOG=info
+MAX_JSON_PAYLOAD_SIZE=52428800
+WAL_SYNC_MODE=every_second
+RUST_LOG=warn
+MAX_JSON_PAYLOAD_SIZE=10485760
+WAL_SYNC_MODE=always
+SERVER_WORKERS=8
+This guide will help you set up a development environment for ApexStore.
+# Install Rust using rustup (recommended)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# Follow the prompts, then reload your shell
+source $HOME/.cargo/env
+# Check Rust version (should be 1.70+)
+rustc --version
+# Output: rustc 1.75.0 (or higher)
+
+# Check Cargo version
+cargo --version
+# Output: cargo 1.75.0 (or higher)
+# Install Clippy (linter)
+rustup component add clippy
+
+# Install rustfmt (formatter)
+rustup component add rustfmt
+
+# Install rust-src (for IDE support)
+rustup component add rust-src
+sudo apt-get update
+sudo apt-get install git
+# Using Homebrew
+brew install git
+
+# Or install Xcode Command Line Tools
+xcode-select --install
+Download from git-scm.com
+git --version
+# Output: git version 2.x.x
+# Ubuntu/Debian
+sudo snap install code --classic
+
+# macOS
+brew install --cask visual-studio-code
+Essential:
+rust-analyzer - Rust language support
+rust-lang.rust-analyzerCodeLLDB (optional) - Debugging support
+vadimcn.vscode-lldbRecommended: +3. Better TOML - TOML syntax highlighting
+bungcip.better-tomlError Lens - Inline error highlighting
+usernamehw.errorlenscrates - Cargo.toml dependency management
+serayuzgur.cratesCreate .vscode/settings.json in project root:
{
+ "rust-analyzer.checkOnSave.command": "clippy",
+ "rust-analyzer.cargo.features": "all",
+ "editor.formatOnSave": true,
+ "[rust]": {
+ "editor.defaultFormatter": "rust-lang.rust-analyzer"
+ }
+}
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/ApexStore.git
+cd ApexStore
+
+# Add upstream remote
+git remote add upstream https://github.com/ElioNeto/ApexStore.git
+
+# Verify remotes
+git remote -v
+# Debug build (faster compilation)
+cargo build
+
+# Release build (optimized)
+cargo build --release
+
+# Build with API feature
+cargo build --release --features api
+First build may take 5-10 minutes as Cargo downloads and compiles dependencies.
+# Run all tests
+cargo test
+
+# Run tests with output
+cargo test -- --nocapture
+
+# Run specific test
+cargo test test_memtable_insert
+# Copy environment template
+cp .env.example .env
+
+# Edit configuration (optional)
+nano .env
+Example Development Configuration (.env):
# Server
+HOST=127.0.0.1
+PORT=8080
+
+# LSM Engine
+DATA_DIR=.lsm_data_dev
+MEMTABLE_MAX_SIZE=2097152 # 2MB for faster flushing in dev
+BLOCK_CACHE_SIZE_MB=32
+
+# Logging
+RUST_LOG=debug
+ENABLE_METRICS=true
+# Debug mode
+cargo run
+
+# Release mode (faster)
+cargo run --release
+Available REPL Commands:
+> help # Show available commands
+> put key value # Insert or update key
+> get key # Retrieve value
+> delete key # Delete key (tombstone)
+> stats # Show statistics
+> exit # Exit REPL
+# Debug mode
+cargo run --features api --bin apexstore-server
+
+# Release mode
+cargo run --release --features api --bin apexstore-server
+
+# With custom port
+PORT=3000 cargo run --release --features api --bin apexstore-server
+Testing the API:
+# Insert a key
+curl -X POST http://localhost:8080/keys \
+ -H "Content-Type: application/json" \
+ -d '{"key": "user:1", "value": "Alice"}'
+
+# Get a key
+curl http://localhost:8080/keys/user:1
+
+# Get statistics
+curl http://localhost:8080/stats/all
+# Format code
+cargo fmt
+
+# Check formatting (CI mode)
+cargo fmt -- --check
+
+# Run Clippy linter
+cargo clippy
+
+# Clippy with strict mode (CI mode)
+cargo clippy -- -D warnings
+
+# Check for unused dependencies
+cargo machete # Requires: cargo install cargo-machete
+# Install criterion
+cargo install cargo-criterion
+
+# Run all benchmarks
+cargo bench
+
+# Run specific benchmark
+cargo bench memtable_insert
+
+# Generate HTML report
+open target/criterion/report/index.html
+# Build production image
+docker build -t apexstore:dev .
+
+# Run in development mode with volume mount
+docker run -d \
+ --name apexstore-dev \
+ -p 8080:8080 \
+ -v $(pwd)/data:/data \
+ -v $(pwd)/.env:/app/.env \
+ apexstore:dev
+# Start services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f apexstore
+
+# Restart after code changes
+docker-compose restart
+
+# Stop services
+docker-compose down
+.vscode/launch.json:{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "type": "lldb",
+ "request": "launch",
+ "name": "Debug CLI",
+ "cargo": {
+ "args": ["build", "--bin=apexstore"]
+ },
+ "args": [],
+ "cwd": "${workspaceFolder}"
+ },
+ {
+ "type": "lldb",
+ "request": "launch",
+ "name": "Debug Server",
+ "cargo": {
+ "args": ["build", "--features", "api", "--bin=apexstore-server"]
+ },
+ "args": [],
+ "cwd": "${workspaceFolder}"
+ },
+ {
+ "type": "lldb",
+ "request": "launch",
+ "name": "Debug Test",
+ "cargo": {
+ "args": ["test", "--no-run", "--lib"]
+ },
+ "args": ["test_memtable_insert"],
+ "cwd": "${workspaceFolder}"
+ }
+ ]
+}
+F5 to start debuggingprintln! Debugging#![allow(unused)]
+fn main() {
+// In your code
+pub fn put(&mut self, key: &[u8], value: &str) -> Result<()> {
+ println!("[DEBUG] Inserting key: {:?}", String::from_utf8_lossy(key));
+ self.wal.append(key, value)?;
+ println!("[DEBUG] WAL append successful");
+ self.memtable.insert(key, value);
+ Ok(())
+}
+}Run with:
+cargo run -- 2>&1 | grep DEBUG
+RUST_LOG# Set log level
+export RUST_LOG=debug
+
+# Or inline
+RUST_LOG=trace cargo run
+
+# Filter by module
+RUST_LOG=apexstore::core::engine=debug cargo run
+# Install flamegraph
+cargo install flamegraph
+
+# Generate flamegraph
+sudo cargo flamegraph --bin apexstore-server
+
+# Open flamegraph.svg in browser
+firefox flamegraph.svg
+# Using valgrind (Linux)
+valgrind --leak-check=full --track-origins=yes \
+ ./target/debug/apexstore
+
+# Using heaptrack (Linux)
+heaptrack ./target/debug/apexstore
+heaptrack_gui heaptrack.apexstore.*.gz
+# Profile specific benchmark
+cargo bench --bench memtable_bench -- --profile-time=10
+
+# With flamegraph
+cargo flamegraph --bench memtable_bench
+# Run all unit tests
+cargo test --lib
+
+# Run tests in specific module
+cargo test --lib core::memtable
+
+# Run single test
+cargo test test_memtable_insert
+# Run all integration tests
+cargo test --test '*'
+
+# Run specific integration test file
+cargo test --test recovery_test
+# Install tarpaulin (Linux only)
+cargo install cargo-tarpaulin
+
+# Generate coverage report
+cargo tarpaulin --out Html
+
+# Open report
+firefox tarpaulin-report.html
+# Create stress test script
+cat > stress_test.sh << 'EOF'
+#!/bin/bash
+for i in {1..10000}; do
+ curl -X POST http://localhost:8080/keys \
+ -H "Content-Type: application/json" \
+ -d "{\"key\": \"key_$i\", \"value\": \"value_$i\"}" &
+done
+wait
+EOF
+
+chmod +x stress_test.sh
+
+# Run stress test
+./stress_test.sh
+# Generate and open docs
+cargo doc --open
+
+# Include private items
+cargo doc --document-private-items --open
+
+# Generate for all features
+cargo doc --all-features --open
+All public APIs should have documentation:
+#![allow(unused)]
+fn main() {
+/// Brief description (appears in summary).
+///
+/// Longer description with more details.
+///
+/// # Arguments
+///
+/// * `key` - Description of key parameter
+/// * `value` - Description of value parameter
+///
+/// # Returns
+///
+/// Description of return value
+///
+/// # Errors
+///
+/// Description of possible errors
+///
+/// # Examples
+///
+/// ```
+/// let engine = LsmEngine::new(config)?;
+/// engine.put(b"key", "value")?;
+/// ```
+///
+/// # Panics
+///
+/// Description of panic conditions (if any)
+///
+/// # Safety
+///
+/// Description of safety requirements (for unsafe functions)
+pub fn put(&mut self, key: &[u8], value: &str) -> Result<()> {
+ // Implementation
+}
+}# Clean build artifacts
+cargo clean
+
+# Update dependencies
+cargo update
+
+# Rebuild
+cargo build
+# Run tests serially (not in parallel)
+cargo test -- --test-threads=1
+# Find process using port 8080
+lsof -i :8080 # macOS/Linux
+
+# Kill process
+kill -9 <PID>
+
+# Or use different port
+PORT=3000 cargo run --features api --bin apexstore-server
+# Clean target directory (safe, can be rebuilt)
+rm -rf target/
+
+# Clean cargo cache
+cargo cache --autoclean
+# Use faster linker (Linux)
+sudo apt-get install lld
+export RUSTFLAGS="-C link-arg=-fuse-ld=lld"
+
+# Or use mold (even faster)
+cargo install mold
+export RUSTFLAGS="-C link-arg=-fuse-ld=mold"
+
+# Enable incremental compilation (in Cargo.toml)
+[profile.dev]
+incremental = true
+cargo doc --openHappy Coding! 🦀
+Last updated: March 2026
+ +First off, thank you for considering contributing to ApexStore! 🎉
+This document provides guidelines and instructions for contributing to the project. Following these guidelines helps maintain code quality and makes the review process smoother.
+We are committed to providing a welcoming and inspiring community for all. We pledge to:
+Rust Toolchain (1.70 or later)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+Git
+# Ubuntu/Debian
+sudo apt-get install git
+
+# macOS
+brew install git
+Code Editor (Recommended: VS Code with rust-analyzer)
+Fork the Repository
+Clone Your Fork
+git clone https://github.com/YOUR_USERNAME/ApexStore.git
+cd ApexStore
+Add Upstream Remote
+git remote add upstream https://github.com/ElioNeto/ApexStore.git
+Install Dependencies
+cargo build
+Run Tests
+cargo test
+For detailed setup instructions, see SETUP.md.
+ApexStore uses GitHub Actions to automate the development workflow:
+develop + run testsmainSee WORKFLOWS.md for complete documentation.
+# Update your fork
+git checkout main
+git pull upstream main
+
+# Create a new branch from main
+git checkout -b feature/your-feature-name
+Branch Naming Conventions:
+feature/ - New features (e.g., feature/compaction-strategy)fix/ - Bug fixes (e.g., fix/wal-corruption)docs/ - Documentation changes (e.g., docs/api-guide)refactor/ - Code refactoring (e.g., refactor/codec-interface)test/ - Test additions/improvements (e.g., test/integration-suite)perf/ - Performance improvements (e.g., perf/bloom-filter-optimization)# Make changes to the code
+vim src/core/engine.rs
+
+# Test your changes
+cargo test --all-features
+
+# Format code
+cargo fmt
+
+# Check for issues
+cargo clippy --all-features -- -D warnings
+git add .
+git commit -m "feat: add compaction strategy interface (#55)"
+Important: Reference issues in commit messages using #issue_number for automatic tracking.
See Commit Messages for formatting guidelines.
+git push origin feature/your-feature-name
+What Happens Next:
+develop branchOnce the automated PR is created:
+develop once approvedNote: You don’t need to manually create PRs - the workflow handles this automatically!
+We follow the Rust API Guidelines and Rust Style Guide.
+Key Principles:
+Use cargo fmt - All code must be formatted
cargo fmt --all
+Pass cargo clippy - Zero warnings policy
cargo clippy --all-features -- -D warnings
+Write Documentation - Public APIs must have doc comments
+#![allow(unused)]
+fn main() {
+/// Retrieves a value from the store by key.
+///
+/// # Arguments
+///
+/// * `key` - The key to look up
+///
+/// # Returns
+///
+/// * `Ok(Some(value))` - Key found
+/// * `Ok(None)` - Key not found
+/// * `Err(e)` - Error occurred
+///
+/// # Example
+///
+/// ```
+/// let value = engine.get(b"user:123")?;
+/// ```
+pub fn get(&self, key: &[u8]) -> Result<Option<String>> {
+ // Implementation
+}
+}This project follows SOLID principles:
+Example:
+#![allow(unused)]
+fn main() {
+// ✅ Good - depends on trait
+pub struct LsmEngine<W: WriteAheadLog> {
+ wal: W,
+}
+
+// ❌ Bad - depends on concrete type
+pub struct LsmEngine {
+ wal: FileBasedWal,
+}
+}Use Result<T, LsmError> for fallible operations
#![allow(unused)]
+fn main() {
+pub fn put(&mut self, key: &[u8], value: &str) -> Result<()> {
+ self.wal.append(key, value)?;
+ self.memtable.insert(key, value);
+ Ok(())
+}
+}Provide Context with error types
+#![allow(unused)]
+fn main() {
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum LsmError {
+ #[error("WAL corruption at offset {0}")]
+ WalCorruption(u64),
+
+ #[error("Key too large: {size} bytes (max: {max})")]
+ KeyTooLarge { size: usize, max: usize },
+}
+}Don’t Panic in library code (use Result instead)
Minimize Allocations
+#![allow(unused)]
+fn main() {
+// ✅ Good - reuse buffer
+let mut buffer = Vec::with_capacity(1024);
+for item in items {
+ buffer.clear();
+ serialize_into(&mut buffer, item)?;
+}
+
+// ❌ Bad - allocate each iteration
+for item in items {
+ let buffer = serialize(item)?;
+}
+}Use Appropriate Data Structures
+BTreeMap for sorted dataHashMap for fast lookupsVec for sequential accessBenchmark Changes
+cargo bench
+Unit Tests - Test individual functions/modules
+#![allow(unused)]
+fn main() {
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn test_memtable_insert() {
+ let mut memtable = MemTable::new();
+ memtable.insert(b"key", "value");
+ assert_eq!(memtable.get(b"key"), Some("value".to_string()));
+ }
+}
+}Integration Tests - Test component interactions
+#![allow(unused)]
+fn main() {
+// tests/integration_test.rs
+#[test]
+fn test_engine_recovery() {
+ let config = LsmConfig::default();
+ let mut engine = LsmEngine::new(config).unwrap();
+
+ engine.put(b"key", "value").unwrap();
+ drop(engine);
+
+ let engine = LsmEngine::new(config).unwrap();
+ assert_eq!(engine.get(b"key").unwrap(), Some("value".to_string()));
+}
+}Property Tests - Test invariants (optional, using proptest)
#![allow(unused)]
+fn main() {
+#[test]
+fn test_get_returns_none_for_nonexistent_key() { /* ... */ }
+}# Run all tests
+cargo test --all-features
+
+# Run specific test
+cargo test test_memtable_insert
+
+# Run with output
+cargo test -- --nocapture
+
+# Run integration tests only
+cargo test --test '*'
+
+# Run with coverage (requires tarpaulin)
+cargo tarpaulin --out Html
+We follow the Conventional Commits specification.
+<type>(<scope>): <subject> (#issue)
+
+<body>
+
+<footer>
+feat - New featurefix - Bug fixdocs - Documentation changesstyle - Code style changes (formatting, etc.)refactor - Code refactoringperf - Performance improvementstest - Test additions/modificationschore - Build process, dependencies, toolingci - CI/CD changesSimple commit:
+feat: add bloom filter to SSTable reader
+With scope and issue:
+fix(wal): prevent corruption on unclean shutdown (#42)
+With body:
+feat(compaction): implement leveled compaction strategy (#47)
+
+Adds a new LeveledCompaction struct that implements the Compaction
+trait. This strategy reduces read amplification by maintaining
+sorted levels with exponentially increasing sizes.
+
+Closes #47
+Breaking change:
+feat(api)!: change SSTable format to V2
+
+BREAKING CHANGE: SSTable V2 is incompatible with V1.
+Migration tool will be provided in v1.4.
+Referencing Issues:
+#123 - Reference issuefixes #123, closes #123 - Will auto-close issue when PR mergesresolves #123 - Alternative close syntaxcargo test --all-features)cargo clippy --all-features -- -D warnings)cargo fmt)When you push to a feature/* or fix/* branch:
develop branchIf you need to create a PR manually:
+develop as the base branchWhen creating a PR manually, use this template:
+## Description
+
+Brief description of changes.
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Related Issues
+
+Closes #123
+Related to #456
+
+## Testing
+
+Describe how you tested your changes:
+- [ ] Unit tests added
+- [ ] Integration tests added
+- [ ] Manual testing performed
+
+## Checklist
+
+- [ ] Code compiles
+- [ ] Tests pass
+- [ ] Clippy checks pass
+- [ ] Code is formatted
+- [ ] Documentation updated
+
+## Screenshots (if applicable)
+
+## Additional Notes
+developApexStore/
+├── src/
+│ ├── core/ # Core domain logic
+│ │ ├── engine.rs # LSM engine orchestration
+│ │ ├── memtable.rs # In-memory storage
+│ │ └── log_record.rs # Data model
+│ ├── storage/ # Persistence layer
+│ │ ├── wal.rs # Write-ahead log
+│ │ ├── sstable.rs # SSTable reader
+│ │ └── builder.rs # SSTable writer
+│ ├── infra/ # Infrastructure
+│ │ ├── codec.rs # Serialization
+│ │ ├── error.rs # Error types
+│ │ └── config.rs # Configuration
+│ ├── api/ # HTTP API (feature-gated)
+│ ├── cli/ # CLI interface
+│ └── features/ # Feature flags
+├── tests/ # Integration tests
+├── benches/ # Benchmarks
+└── docs/ # Documentation
+core/ - Domain logic, no external dependenciesstorage/ - File I/O, persistenceinfra/ - Cross-cutting concernsapi/ - External interfaces (feature-gated)CI/CD Testing Pipeline (#55)
+Compaction Implementation (#47)
+Efficient Iterators (#21, #22, #23)
+Benchmarking Suite (#48)
+CLI Command Equalization (#65)
+Checksums & Integrity (#25)
+Add More Tests
+Binary Search Optimization (#37)
+Documentation Improvements
+Replication Support
+Snapshot Isolation
+mainThank you for contributing! 🎉
+Last updated: March 2026
+ +