Skip to main content

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;