holt 0.1.0

An adaptive-radix-tree metadata storage engine for path-shaped keys, with per-blob concurrency and crash-safe persistence.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# Contributing to holt

Thanks for your interest. This document spells out the build / test /
review loop so you can land a change with confidence.

## Build & test

```bash
# clone
git clone https://github.com/feichai0017/holt.git
cd holt

# everything CI runs:
cargo build  --workspace --all-targets
cargo test   --workspace --all-targets
cargo test   --workspace --doc
cargo fmt    --all --check
cargo clippy --workspace --all-targets -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps
```

The CI matrix runs on **ubuntu-latest** and **macos-latest**.
Persistent-backend tests rely on `O_DIRECT` (Linux) / `F_NOCACHE`
(macOS); both work out of the box under the `tempfile` crate that
the integration tests use.

**Minimum supported Rust version: 1.82.** Bump it consciously — the
`msrv` CI job (which builds the library only — dev-dependencies
routinely require a newer toolchain) will fail otherwise.

## Examples

Each example demonstrates a real workload shape:

```bash
cargo run --example basic_kv
cargo run --example filesystem_meta
cargo run --example session_store
cargo run --example s3_metadata
```

All four are in-memory by default so they don't litter your cwd.

## Benchmarks

```bash
cargo bench --bench main                       # ~3 min full sweep
cargo bench --bench main -- --quick --noplot   # ~1 min smoke
cargo bench --bench main -- kv_get             # a single scenario
```

Results land in `target/criterion/`. See `benches/README.md` for the
methodology and the apples-to-apples ground rules vs RocksDB.

## Conventions

### Code

- **Edition: 2021. MSRV: 1.82.**
- **Module layout** follows logical layers: `layout < store < engine
  < journal < api`. New abstractions should slot into the right
  layer, not span them.
- **`#![warn(clippy::pedantic)]`** is on. The vetted noise-allow list
  in [`src/lib.rs`](src/lib.rs) documents which categories we silence
  and why; before adding a new entry, try the local fix first.
- **No `unsafe` outside the `store` and `engine` layers** without a
  written justification. Every `unsafe` block in the crate has a
  `// SAFETY: ...` comment naming the invariant it relies on.
- **Compile-time-pinned layout offsets** — every `#[repr(C)]` layout
  struct in `src/layout/` has `const _: () = assert!(offset_of!(...))`
  blocks. Don't move fields; drift breaks the build, which is the
  point.
- **Walker submodule split** (`engine/walker/{types,readers,writers,
  lookup,insert,erase,spillover,migrate}`) keeps each file under ~700
  lines. Help us keep it that way — if a single file outgrows that,
  carve out a new submodule.

### Tests

- **One test per behaviour.** Tests are documentation; a unit test
  failing should immediately tell you which invariant broke.
- **Property tests** (`tests/properties.rs`) cross-check the tree
  against a `HashMap` oracle. Adding a new op variant? Extend the
  generator + oracle in lockstep.
- **WAL integration tests** (`tests/wal_round_trip.rs`,
  `tests/wal_tree_integration.rs`) cover the crash-and-replay
  invariants. The `durable_cfg` helper enables `wal_sync_on_commit`
  for tests that simulate a crash without a checkpoint.

### Commits

- **One commit per logical change.** No "fix typo + rewrite scheduler
  + bump dep" mega-commits.
- **Subject line ≤ 70 chars**, imperative mood
  (`feat: add WAL group-commit auto-flush`, not "Added a thing").
- **Body wraps at ~72 chars** and answers *why*, not *what*. Diffs
  already show *what*.
- **Prefix tags we use**:
  `feat:` / `perf:` / `fix:` / `refactor:` / `docs:` / `chore:` /
  `test:`. Mixed-purpose commits split.
- **Commit attribution**: don't add tooling co-author trailers; the
  `Co-Authored-By` lines surface in the GitHub UI and crowd out the
  human authorship.

## Filing issues

If you've hit a bug, please include:

- The shortest reproducer you can manage (a failing test is ideal).
- The output of `rustc --version --verbose`.
- Whether you saw it on memory or persistent storage, and the
  config diff from the defaults if any.

For design discussions / "should we add X" questions, open an
issue rather than a PR — the architecture is still being shaped and
direction conversations beat surprise patches.

## Licence

holt is **MIT** licensed. By contributing, you agree your
contribution is licensed under the MIT licence. See
[`LICENSE`](LICENSE) for the legal text.