kevy_vlog/lib.rs
1//! kevy-vlog — the disposable value log under transparent tiering.
2//!
3//! An append-only spill area for cold VALUES: keys and metadata stay
4//! in RAM; a demoted value's bytes live here and are read back with
5//! one `read_at`.
6//! Three properties are load-bearing:
7//!
8//! - **Disposable.** The vlog is NOT durability — the AOF remains the sole
9//! durable truth. [`Vlog::open`] deletes any leftover vlog files; every
10//! boot starts empty and refills during replay. There is deliberately no
11//! fsync, no recovery scan, no torn-write healing: a record that fails
12//! its CRC on read-back is a bug in this process, not corruption to
13//! repair, and surfaces as an error.
14//! - **Pinned readers.** A reader that must survive compaction (a snapshot
15//! view, an AOF rewrite, a replication ship) holds an [`Arc<VlogFile>`]
16//! from [`Vlog::pin`]. A compacted file is unlinked only when the last
17//! pin drops ([`VlogFile`]'s `Drop`), so a pinned view's offsets stay
18//! valid for its whole life. All file IO is positional
19//! (`read_at`/`write_at`, `&File`), so pinned reads are thread-safe.
20//! - **Owner-driven compaction.** Records carry their key, so a file is
21//! self-describing; but only the owner (the store's cold refs) knows
22//! which records are live. [`Vlog::compact_below`] scans, asks the owner
23//! ([`CompactOwner::is_live`]), re-appends survivors, and hands the new
24//! ref back ([`CompactOwner::moved`]). Every compaction bumps
25//! [`Vlog::epoch`] — the O(1) "did my ColdRef move?" check.
26//!
27//! ```
28//! use kevy_vlog::Vlog;
29//!
30//! let dir = kevy_tmpdir::TmpDir::new("vlog-crate-doc");
31//! let mut log = Vlog::open(dir.path(), 1 << 20)?;
32//! let at = log.append(b"user:1", b"a cold value")?;
33//! assert_eq!(log.read(at)?, (b"user:1".to_vec(), b"a cold value".to_vec()));
34//! // the owner overwrote or deleted the key: its bytes are now dead weight
35//! log.note_dead(at);
36//! assert_eq!(log.stats().live_bytes, 0);
37//! # Ok::<(), std::io::Error>(())
38//! ```
39//!
40//! Record layout: `[body_len u32-LE][crc32c u32-LE][key_len u32-LE][key]
41//! [payload]`, CRC over the body (everything after the 8-byte header).
42//! A [`VlogRef`] names `(file_id, header offset, body_len)`.
43//!
44//! **The payload is a `kevy-compress` frame.** Values from one keyspace
45//! land together, so the file is a corpus: each file carries a
46//! dictionary trained on a sample of its predecessor's raw payloads
47//! (same population, already real bytes — no cold-start window), and
48//! records encode against it on append, reaching the cross-value
49//! redundancy a per-datum compressor cannot see. The frame lives
50//! INSIDE the body, so on-disk framing does not move and the CRC
51//! covers exactly the stored bytes. The dictionary lives in the
52//! [`VlogFile`] it serves and dies with it — the vlog is disposable,
53//! so its dictionaries are too, and no format-compatibility burden
54//! ever exists. Incompressible payloads store raw inside the frame
55//! (never expanded past the 6-byte frame header).
56
57//! Every public item here is documented, and the lint keeps it that
58//! way: kevy-vlog is the value log, and `[workspace.lints.rust] warnings = "deny"`
59//! turns a new gap into a compile error rather than a number that
60//! drifts. Closed from 65 sites (store) and 7 (vlog) in v6.
61// Best-effort removal, on paths where the file is being abandoned.
62// A file that will not delete is a stray the next sweep collects,
63// and refusing here would abandon the rest of the cleanup.
64#![expect(clippy::let_underscore_must_use, reason = "removing what is already meant to be gone")]
65#![warn(missing_docs)]
66// The checksum comes from the one public front, not a private copy of it.
67// `kevy_sys::checksum`'s own docstring names this crate as a consumer and
68// says why: "one public front so every consumer (AOF envelope, vlog
69// records, immutable segments) speaks the same checksum without re-owning
70// the fallback." kevy-seg already did that; this crate carried 73 lines
71// saying it could not, because it could not depend on kevy-persist — true,
72// and beside the point, since kevy-sys was already an unconditional
73// dependency here and this crate never builds for wasm32 (kevy-store gates
74// the tier backend off it). Verified byte-identical over 3,075 inputs
75// before the copy was removed: it is an on-disk format.
76use kevy_sys::checksum::crc32c;
77
78#[cfg(test)]
79mod tests;
80
81use std::fs::{self, OpenOptions};
82use std::io;
83use std::os::unix::fs::FileExt;
84use std::path::{Path, PathBuf};
85use std::sync::Arc;
86use std::sync::atomic::AtomicBool;
87
88/// Default rotation threshold for the active file (RFC §7: 256 MiB).
89///
90/// ```
91/// let dir = kevy_tmpdir::TmpDir::new("vlog-default-rotate");
92/// let v = kevy_vlog::Vlog::open(dir.path(), kevy_vlog::DEFAULT_ROTATE_BYTES)?;
93/// assert_eq!(kevy_vlog::DEFAULT_ROTATE_BYTES, 256 * 1024 * 1024);
94/// assert_eq!(v.stats().files, 1);
95/// # Ok::<(), std::io::Error>(())
96/// ```
97pub const DEFAULT_ROTATE_BYTES: u64 = 256 << 20;
98
99/// Per-record header: `body_len u32-LE | crc32c u32-LE`.
100const HEADER: u64 = 8;
101
102/// Refuse absurd bodies (mirrors the AOF envelope's `MAX_RECORD` bound).
103const MAX_BODY: u32 = 1 << 30;
104
105pub(crate) fn bad(msg: String) -> io::Error {
106 io::Error::new(io::ErrorKind::InvalidData, msg)
107}
108
109/// Split a verified body into `(key, payload)`.
110pub(crate) fn split_body(body: Vec<u8>) -> io::Result<(Vec<u8>, Vec<u8>)> {
111 if body.len() < 4 {
112 return Err(bad("vlog: body shorter than its key header".into()));
113 }
114 let key_len =
115 u32::from_le_bytes(body[..4].try_into().expect("the body.len() < 4 return above")) as usize;
116 if 4 + key_len > body.len() {
117 return Err(bad("vlog: key overruns body".into()));
118 }
119 let payload = body[4 + key_len..].to_vec();
120 let mut key = body;
121 key.drain(..4);
122 key.truncate(key_len);
123 Ok((key, payload))
124}
125
126mod accounting;
127mod record;
128mod stats;
129pub use accounting::CompressionStats;
130pub use record::{CompactOwner, VlogFile, VlogRef, verify_image};
131pub use stats::VlogStats;
132
133// Send and Sync are part of the public contract: a change that loses
134// either fails to compile here rather than in a caller.
135const _: () = {
136 const fn send_sync<T: Send + Sync>() {}
137 send_sync::<Vlog>();
138 send_sync::<VlogFile>();
139 send_sync::<VlogRef>();
140 send_sync::<VlogStats>();
141 send_sync::<CompressionStats>();
142};
143
144/// Owner-side per-file accounting (bytes are header-inclusive).
145#[derive(Debug)]
146struct FileState {
147 handle: Arc<VlogFile>,
148 bytes: u64,
149 live: u64,
150 compression: CompressionStats,
151}
152
153/// One shard's value log. Single owner (`&mut` appends, the shard
154/// thread); concurrent readers go through [`Vlog::pin`].
155///
156/// ```
157/// use kevy_vlog::Vlog;
158/// let dir = kevy_tmpdir::TmpDir::new("vlog-type");
159/// let mut v = Vlog::open(dir.path(), 1 << 20)?;
160/// let r = v.append(b"k", b"cold bytes")?;
161/// let file = v.pin(r.file_id).expect("the active file");
162/// assert_eq!(file.read(r)?.1, b"cold bytes");
163/// # Ok::<(), std::io::Error>(())
164/// ```
165#[derive(Debug)]
166pub struct Vlog {
167 dir: PathBuf,
168 rotate_bytes: u64,
169 /// Sorted by id; the last entry is the active (append) file.
170 files: Vec<FileState>,
171 next_id: u32,
172 epoch: u64,
173 /// In-progress incremental compaction. `Some` = a victim file is
174 /// being drained a bounded batch at a time; it stays IN `files`
175 /// (readable, pin-safe) until fully drained, so a partly-compacted
176 /// file is always consistent: moved records point to their new home,
177 /// unmoved ones still read from the victim.
178 compaction: Option<CompactCursor>,
179 /// Raw payload samples from the ACTIVE file — the training corpus
180 /// for the NEXT file's dictionary (rotation seeding, RFC §7.2).
181 samples: Vec<Vec<u8>>,
182 sample_bytes: usize,
183}
184
185/// Cap on retained training samples per file. Enough to fill a
186/// dictionary several times over; sampling stops once full, so a
187/// 256 MiB file never hoards its whole body.
188const SAMPLE_BUDGET: usize = 256 << 10;
189
190impl Vlog {
191 /// Open a fresh vlog under `dir`, DELETING any leftover vlog files —
192 /// the log is per-boot disposable (the AOF is the durability truth).
193 /// # Examples
194 ///
195 /// ```
196 /// use kevy_vlog::Vlog;
197 /// let dir = kevy_tmpdir::TmpDir::new("vlog-open");
198 /// // 1 MiB before the active file rotates.
199 /// let v = Vlog::open(dir.path(), 1 << 20).unwrap();
200 /// // A fresh log starts with exactly one file and nothing live in it.
201 /// assert_eq!(v.stats().files, 1);
202 /// assert_eq!(v.stats().live_bytes, 0);
203 /// ```
204 pub fn open(dir: impl AsRef<Path>, rotate_bytes: u64) -> io::Result<Self> {
205 let dir = dir.as_ref();
206 fs::create_dir_all(dir)?;
207 for entry in fs::read_dir(dir)? {
208 let entry = entry?;
209 if entry.file_name().to_string_lossy().starts_with("vlog-") {
210 let _ = fs::remove_file(entry.path());
211 }
212 }
213 let mut v = Vlog {
214 dir: dir.to_path_buf(),
215 rotate_bytes: rotate_bytes.max(1),
216 files: Vec::new(),
217 next_id: 0,
218 epoch: 0,
219 compaction: None,
220 samples: Vec::new(),
221 sample_bytes: 0,
222 };
223 v.open_next_file(Vec::new())?;
224 Ok(v)
225 }
226
227 fn open_next_file(&mut self, dict: Vec<u8>) -> io::Result<()> {
228 let compression = CompressionStats { dict_bytes: dict.len() as u64, ..Default::default() };
229 let id = self.next_id;
230 self.next_id += 1;
231 let path = self.dir.join(format!("vlog-{id:08}.dat"));
232 let file = OpenOptions::new().read(true).write(true).create_new(true).open(&path)?;
233 self.files.push(FileState {
234 handle: Arc::new(VlogFile {
235 id,
236 path,
237 file,
238 delete_on_drop: AtomicBool::new(false),
239 parsed: kevy_compress::Dict::new(&dict),
240 }),
241 bytes: 0,
242 live: 0,
243 compression,
244 });
245 Ok(())
246 }
247
248 /// Rotate: train the new file's dictionary from the outgoing file's
249 /// raw samples — same keyspace, same population, already real bytes
250 /// (RFC §7.2's rotation seeding; there is no cold-start window in
251 /// which records meet an empty model, except the first file's).
252 fn rotate(&mut self) -> io::Result<()> {
253 let refs: Vec<&[u8]> = self.samples.iter().map(|s| s.as_slice()).collect();
254 let dict = kevy_compress::train(&refs, kevy_compress::MAX_OFFSET);
255 self.samples.clear();
256 self.sample_bytes = 0;
257 self.open_next_file(dict)
258 }
259
260 /// Append one record; returns its address. Rotates the active file
261 /// past the threshold FIRST, so a record never spans files.
262 /// # Examples
263 ///
264 /// ```
265 /// use kevy_vlog::Vlog;
266 /// let dir = kevy_tmpdir::TmpDir::new("vlog-append");
267 /// let mut v = Vlog::open(dir.path(), 1 << 20).unwrap();
268 ///
269 /// let r = v.append(b"user:1", b"the cold value").unwrap();
270 /// // The ref is the address a cold stub keeps; reading it back gives
271 /// // the key alongside the payload, so a stub can be re-checked.
272 /// assert_eq!(v.read(r).unwrap(), (b"user:1".to_vec(), b"the cold value".to_vec()));
273 /// ```
274 pub fn append(&mut self, key: &[u8], payload: &[u8]) -> io::Result<VlogRef> {
275 self.append_level(key, payload, false)
276 }
277
278 /// [`Self::append`] with the compaction level: literals
279 /// entropy-coded when that wins (strictly smallest-wins, so it can
280 /// only shrink). Compaction rewrites through here — a record that
281 /// survived to compaction has earned the more expensive encoding
282 /// (the RFC's two-stage trade riding a scan that already exists).
283 pub(crate) fn append_high(&mut self, key: &[u8], payload: &[u8]) -> io::Result<VlogRef> {
284 self.append_level(key, payload, true)
285 }
286
287 fn append_level(&mut self, key: &[u8], payload: &[u8], high: bool) -> io::Result<VlogRef> {
288 if 4 + key.len() + payload.len() > MAX_BODY as usize {
289 return Err(bad(format!(
290 "vlog: record too large ({} B)",
291 4 + key.len() + payload.len()
292 )));
293 }
294 if self.active().bytes >= self.rotate_bytes {
295 self.rotate()?;
296 }
297 // Raw bytes are the population the NEXT file's dictionary
298 // models; sample before encoding.
299 if self.sample_bytes < SAMPLE_BUDGET && !payload.is_empty() {
300 self.sample_bytes += payload.len();
301 self.samples.push(payload.to_vec());
302 }
303 // The file's dictionary, parsed and seeded once at rotation.
304 // Taking it per call re-hashed all 65,532 of its positions for
305 // every record, which made encode time flat in input size — an
306 // 8-byte value cost more than a 6 KiB one.
307 let dict = &self.active().handle.parsed;
308 let frame = if high { dict.encode_high(payload) } else { dict.encode(payload) };
309 let body_len = 4 + key.len() + frame.len();
310 let mut body = Vec::with_capacity(body_len);
311 body.extend_from_slice(&(key.len() as u32).to_le_bytes());
312 body.extend_from_slice(key);
313 body.extend_from_slice(&frame);
314 let mut record = Vec::with_capacity(HEADER as usize + body_len);
315 record.extend_from_slice(&(body_len as u32).to_le_bytes());
316 record.extend_from_slice(&crc32c(&body).to_le_bytes());
317 record.extend_from_slice(&body);
318
319 let state = self.files.last_mut().expect("active file");
320 let offset = state.bytes;
321 state.handle.file.write_all_at(&record, offset)?;
322 state.bytes += record.len() as u64;
323 state.live += record.len() as u64;
324 state.compression.add_record(payload.len(), frame.len());
325 Ok(VlogRef { file_id: state.handle.id, offset, len: body_len as u32 })
326 }
327
328 fn active(&self) -> &FileState {
329 self.files.last().expect("active file")
330 }
331
332 fn state_of(&mut self, file_id: u32) -> Option<&mut FileState> {
333 self.files.iter_mut().find(|s| s.handle.id == file_id)
334 }
335
336 /// Read `(key, payload)` for a ref. For readers that outlive the
337 /// owner's borrow (serializer threads), use [`Vlog::pin`] instead.
338 ///
339 /// ```
340 /// let dir = kevy_tmpdir::TmpDir::new("vlog-read");
341 /// let mut v = kevy_vlog::Vlog::open(dir.path(), 1 << 20)?;
342 /// let r = v.append(b"k", b"v")?;
343 /// assert_eq!(v.read(r)?, (b"k".to_vec(), b"v".to_vec()));
344 /// let stale = kevy_vlog::VlogRef::new(99, r.offset, r.len);
345 /// assert!(v.read(stale).is_err(), "a file this log never had");
346 /// # Ok::<(), std::io::Error>(())
347 /// ```
348 pub fn read(&self, r: VlogRef) -> io::Result<(Vec<u8>, Vec<u8>)> {
349 match self.files.iter().find(|s| s.handle.id == r.file_id) {
350 Some(s) => s.handle.read(r),
351 None => Err(bad(format!("vlog: file {} is gone (stale ref?)", r.file_id))),
352 }
353 }
354
355 /// Pin a file for concurrent / long-lived reading: the returned Arc
356 /// keeps the file on disk across compaction until dropped.
357 ///
358 /// ```
359 /// let dir = kevy_tmpdir::TmpDir::new("vlog-pin-one");
360 /// let mut v = kevy_vlog::Vlog::open(dir.path(), 1 << 20)?;
361 /// let r = v.append(b"k", b"v")?;
362 /// let file = v.pin(r.file_id).expect("the file r names");
363 /// assert_eq!(file.id(), r.file_id);
364 /// # Ok::<(), std::io::Error>(())
365 /// ```
366 pub fn pin(&self, file_id: u32) -> Option<Arc<VlogFile>> {
367 self.files.iter().find(|s| s.handle.id == file_id).map(|s| Arc::clone(&s.handle))
368 }
369
370 /// Pin EVERY current file — a point-in-time reader (snapshot view /
371 /// AOF rewrite / replication ship) captures this alongside its
372 /// frozen refs: any ref frozen at the same instant can only name a
373 /// file that exists now, so the whole set keeps the view readable
374 /// across compaction for its entire life.
375 /// # Examples
376 ///
377 /// ```
378 /// use kevy_vlog::Vlog;
379 /// let dir = kevy_tmpdir::TmpDir::new("vlog-pin");
380 /// let mut v = Vlog::open(dir.path(), 1 << 20).unwrap();
381 /// v.append(b"k", b"v").unwrap();
382 ///
383 /// // Pinned files survive compaction for as long as the handle lives —
384 /// // this is how a snapshot reads a cold value without blocking the
385 /// // shard that owns the log.
386 /// let pinned = v.pin_all();
387 /// assert_eq!(pinned.len(), v.stats().files);
388 /// ```
389 pub fn pin_all(&self) -> Vec<Arc<VlogFile>> {
390 self.files.iter().map(|s| Arc::clone(&s.handle)).collect()
391 }
392
393 /// The owner overwrote / deleted / promoted the record at `r`: its
394 /// bytes are dead, feeding the compaction trigger.
395 ///
396 /// ```
397 /// let dir = kevy_tmpdir::TmpDir::new("vlog-note-dead");
398 /// let mut v = kevy_vlog::Vlog::open(dir.path(), 1 << 20)?;
399 /// let r = v.append(b"k", b"v")?;
400 /// v.note_dead(r);
401 /// assert_eq!(v.stats().live_bytes, 0);
402 /// // accounting only: the bytes stay readable until compaction
403 /// assert_eq!(v.read(r)?.1, b"v");
404 /// # Ok::<(), std::io::Error>(())
405 /// ```
406 pub fn note_dead(&mut self, r: VlogRef) {
407 if let Some(s) = self.state_of(r.file_id) {
408 s.live = s.live.saturating_sub(HEADER + u64::from(r.len));
409 }
410 }
411
412 /// The owner dropped its entire cold-ref universe in one stroke
413 /// (`FLUSHALL`): every record in every file is now dead. O(files),
414 /// no IO — sealed files become full-dead (dropped by the next
415 /// [`Self::compact_below`] without a scan); the active file's
416 /// garbage bytes fall out at its own retirement.
417 ///
418 /// ```
419 /// let dir = kevy_tmpdir::TmpDir::new("vlog-mark-all-dead");
420 /// let mut v = kevy_vlog::Vlog::open(dir.path(), 1)?;
421 /// v.append(b"a", b"1")?;
422 /// v.append(b"b", b"2")?;
423 /// v.mark_all_dead();
424 /// assert_eq!(v.stats().live_bytes, 0);
425 /// assert!(v.compaction_pending(50), "the sealed file is now all dead");
426 /// # Ok::<(), std::io::Error>(())
427 /// ```
428 pub fn mark_all_dead(&mut self) {
429 for s in &mut self.files {
430 s.live = 0;
431 }
432 }
433
434 /// Monotone compaction counter — bumped once per retired file. A
435 /// reader holding `(epoch, VlogRef)` can verify in O(1) that no
436 /// compaction has run (so its ref cannot have moved).
437 /// # Examples
438 ///
439 /// ```
440 /// use kevy_vlog::Vlog;
441 /// let dir = kevy_tmpdir::TmpDir::new("vlog-epoch");
442 /// let v = Vlog::open(dir.path(), 1 << 20).unwrap();
443 /// // A ref taken while the epoch reads N stays valid until it changes.
444 /// assert_eq!(v.epoch(), v.stats().epoch);
445 /// ```
446 pub fn epoch(&self) -> u64 {
447 self.epoch
448 }
449
450 /// A snapshot of the gauges INFO reads. Cheap: the byte totals are
451 /// summed over the file list, which is one entry per file rather than
452 /// per record.
453 /// # Examples
454 ///
455 /// ```
456 /// use kevy_vlog::Vlog;
457 /// let dir = kevy_tmpdir::TmpDir::new("vlog-stats");
458 /// let mut v = Vlog::open(dir.path(), 1 << 20).unwrap();
459 /// let r = v.append(b"k", b"payload").unwrap();
460 ///
461 /// let before = v.stats();
462 /// assert!(before.live_bytes > 0);
463 ///
464 /// // Telling the log a stub is gone moves bytes from live to dead;
465 /// // nothing is reclaimed until compaction runs.
466 /// v.note_dead(r);
467 /// let after = v.stats();
468 /// assert_eq!(after.live_bytes, 0);
469 /// assert_eq!(after.bytes, before.bytes);
470 /// ```
471 pub fn stats(&self) -> VlogStats {
472 VlogStats {
473 files: self.files.len(),
474 bytes: self.files.iter().map(|s| s.bytes).sum(),
475 live_bytes: self.files.iter().map(|s| s.live).sum(),
476 epoch: self.epoch,
477 }
478 }
479
480 /// Where the value bytes went, over the files still on disk: see
481 /// [`CompressionStats`].
482 /// # Examples
483 ///
484 /// ```
485 /// use kevy_vlog::Vlog;
486 /// let dir = kevy_tmpdir::TmpDir::new("vlog-compression-fn");
487 /// let mut v = Vlog::open(dir.path(), 1 << 20).unwrap();
488 /// assert_eq!(v.compression().raw_bytes, 0);
489 /// v.append(b"k", b"value").unwrap();
490 /// // a 5-byte value: one tag byte and one length byte of frame header
491 /// assert_eq!(v.compression().raw_bytes, 5);
492 /// assert_eq!(v.compression().frame_header_bytes, 2);
493 /// ```
494 pub fn compression(&self) -> CompressionStats {
495 self.files.iter().fold(CompressionStats::default(), |a, s| a.sum(s.compression))
496 }
497}
498
499mod compact;
500pub(crate) use compact::CompactCursor;