From 1006ec2570b6799809870fe7a81c68ede87ea2cb Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Tue, 27 Oct 2026 06:14:33 -0700 Subject: [PATCH] feat(timeline): index a session `timeline.jsonl` is a merged, time-sorted index that points into the raw files by byte range, so the raw files are never rewritten and the index can be rebuilt at any time. It places komorebi's log, events, the OS trace and the recorder's own incidents on one timeline, and answers what was around a video time and where in the video a log line or event is. `frames` extracts PNG frames from the recorded video with ffmpeg, which is never used to capture. --- Cargo.lock | 49 + dependencies.json | 9 + docs/ARCHITECTURE.md | 4 + komorebi-recorder/Cargo.toml | 1 + komorebi-recorder/src/frames.rs | 273 ++++ komorebi-recorder/src/lib.rs | 3 + komorebi-recorder/src/timeline.rs | 2008 +++++++++++++++++++++++++++++ 7 files changed, 2347 insertions(+) create mode 100644 komorebi-recorder/src/frames.rs create mode 100644 komorebi-recorder/src/timeline.rs diff --git a/Cargo.lock b/Cargo.lock index 87c905ce..0fb5ee19 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -233,6 +233,15 @@ version = "0.8.7" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" +[[package]] +name = "crc32fast" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511" +dependencies = [ + "cfg-if", +] + [[package]] name = "crossbeam-channel" version = "0.5.15" @@ -319,12 +328,31 @@ version = "2.4.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6" +[[package]] +name = "fdeflate" +version = "0.3.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c" +dependencies = [ + "simd-adler32", +] + [[package]] name = "find-msvc-tools" version = "0.1.9" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582" +[[package]] +name = "flate2" +version = "1.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c" +dependencies = [ + "crc32fast", + "miniz_oxide", +] + [[package]] name = "foldhash" version = "0.1.5" @@ -498,6 +526,7 @@ dependencies = [ "objc2-foundation", "objc2-screen-capture-kit", "parking_lot", + "png", "schemars", "serde", "serde_json_lenient", @@ -575,6 +604,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316" dependencies = [ "adler2", + "simd-adler32", ] [[package]] @@ -789,6 +819,19 @@ version = "0.2.17" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" +[[package]] +name = "png" +version = "0.18.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61" +dependencies = [ + "bitflags", + "crc32fast", + "fdeflate", + "flate2", + "miniz_oxide", +] + [[package]] name = "prettyplease" version = "0.2.37" @@ -1012,6 +1055,12 @@ version = "1.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64" +[[package]] +name = "simd-adler32" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "703d5c7ef118737c72f1af64ad2f6f8c5e1921f818cdcb97b8fe6fc69bf66214" + [[package]] name = "slab" version = "0.4.12" diff --git a/dependencies.json b/dependencies.json index 192f8b6c..b8efaa19 100644 --- a/dependencies.json +++ b/dependencies.json @@ -29,6 +29,7 @@ "color-spantrace 0.3.0 registry+https://github.com/rust-lang/crates.io-index", "colorchoice 1.0.5 registry+https://github.com/rust-lang/crates.io-index", "core-foundation-sys 0.8.7 registry+https://github.com/rust-lang/crates.io-index", + "crc32fast 1.5.0 registry+https://github.com/rust-lang/crates.io-index", "crossbeam-channel 0.5.15 registry+https://github.com/rust-lang/crates.io-index", "crossbeam-utils 0.8.21 registry+https://github.com/rust-lang/crates.io-index", "dirs 6.0.0 registry+https://github.com/rust-lang/crates.io-index", @@ -38,6 +39,8 @@ "errno 0.3.14 registry+https://github.com/rust-lang/crates.io-index", "eyre 0.6.12 registry+https://github.com/rust-lang/crates.io-index", "fastrand 2.4.1 registry+https://github.com/rust-lang/crates.io-index", + "fdeflate 0.3.7 registry+https://github.com/rust-lang/crates.io-index", + "flate2 1.1.9 registry+https://github.com/rust-lang/crates.io-index", "getrandom 0.4.2 registry+https://github.com/rust-lang/crates.io-index", "gimli 0.32.3 registry+https://github.com/rust-lang/crates.io-index", "heck 0.5.0 registry+https://github.com/rust-lang/crates.io-index", @@ -62,6 +65,7 @@ "parking_lot 0.12.5 registry+https://github.com/rust-lang/crates.io-index", "parking_lot_core 0.9.12 registry+https://github.com/rust-lang/crates.io-index", "pin-project-lite 0.2.17 registry+https://github.com/rust-lang/crates.io-index", + "png 0.18.1 registry+https://github.com/rust-lang/crates.io-index", "proc-macro2 1.0.106 registry+https://github.com/rust-lang/crates.io-index", "quote 1.0.45 registry+https://github.com/rust-lang/crates.io-index", "ref-cast 1.0.25 registry+https://github.com/rust-lang/crates.io-index", @@ -145,6 +149,7 @@ "color-spantrace 0.3.0 registry+https://github.com/rust-lang/crates.io-index", "colorchoice 1.0.5 registry+https://github.com/rust-lang/crates.io-index", "core-foundation-sys 0.8.7 registry+https://github.com/rust-lang/crates.io-index", + "crc32fast 1.5.0 registry+https://github.com/rust-lang/crates.io-index", "crossbeam-channel 0.5.15 registry+https://github.com/rust-lang/crates.io-index", "crossbeam-utils 0.8.21 registry+https://github.com/rust-lang/crates.io-index", "dirs 6.0.0 registry+https://github.com/rust-lang/crates.io-index", @@ -154,6 +159,8 @@ "errno 0.3.14 registry+https://github.com/rust-lang/crates.io-index", "eyre 0.6.12 registry+https://github.com/rust-lang/crates.io-index", "fastrand 2.4.1 registry+https://github.com/rust-lang/crates.io-index", + "fdeflate 0.3.7 registry+https://github.com/rust-lang/crates.io-index", + "flate2 1.1.9 registry+https://github.com/rust-lang/crates.io-index", "getrandom 0.4.2 registry+https://github.com/rust-lang/crates.io-index", "gimli 0.32.3 registry+https://github.com/rust-lang/crates.io-index", "heck 0.5.0 registry+https://github.com/rust-lang/crates.io-index", @@ -184,6 +191,7 @@ "parking_lot 0.12.5 registry+https://github.com/rust-lang/crates.io-index", "parking_lot_core 0.9.12 registry+https://github.com/rust-lang/crates.io-index", "pin-project-lite 0.2.17 registry+https://github.com/rust-lang/crates.io-index", + "png 0.18.1 registry+https://github.com/rust-lang/crates.io-index", "proc-macro2 1.0.106 registry+https://github.com/rust-lang/crates.io-index", "quote 1.0.45 registry+https://github.com/rust-lang/crates.io-index", "ref-cast 1.0.25 registry+https://github.com/rust-lang/crates.io-index", @@ -200,6 +208,7 @@ "serde_json 1.0.149 registry+https://github.com/rust-lang/crates.io-index", "serde_json_lenient 0.2.4 registry+https://github.com/rust-lang/crates.io-index", "sharded-slab 0.1.7 registry+https://github.com/rust-lang/crates.io-index", + "simd-adler32 0.3.9 registry+https://github.com/rust-lang/crates.io-index", "smallvec 1.15.1 registry+https://github.com/rust-lang/crates.io-index", "strsim 0.11.1 registry+https://github.com/rust-lang/crates.io-index", "syn 2.0.117 registry+https://github.com/rust-lang/crates.io-index", diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 33316dae..9e6db737 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -77,6 +77,9 @@ only when they changed), and what happened to the recording itself (`recorder.js The OS trace is under `oslog/`, one file per stream. Each display's video is `video-[-].mp4` with a `frames-[-].csv` beside it holding every frame's timestamp, one segment to a file: a display that is unplugged and returns starts a new segment instead of extending the old one. +`timeline.jsonl` is the only derived file: a time-sorted index of every record that points into the raw files by byte +range. Anything that happens to the recorder leaves the raw files readable, and the index is rebuilt from them with +`reindex`. The file formats are specified on the `session` and `timeline` modules. ## Recording @@ -101,3 +104,4 @@ backend that docks and undocks without hardware. | A running recorder can be told from one that died | the OS: an exclusive lock on `recorder.lock`, held for as long as the recorder runs and dropped by the OS when the process ends however it ends | | A manifest from a newer build is not read | a runtime error when the manifest is read, covered by `rejects_manifests_from_the_future` | | A manifest is never half-written | write to a temporary file and rename | +| The raw files are never rewritten | convention: the index only references them, and `reindex` rebuilds the index from them | diff --git a/komorebi-recorder/Cargo.toml b/komorebi-recorder/Cargo.toml index 2b8c6bbc..8a8d8ada 100644 --- a/komorebi-recorder/Cargo.toml +++ b/komorebi-recorder/Cargo.toml @@ -12,6 +12,7 @@ color-eyre = { workspace = true } crossbeam-channel = { workspace = true } dirs = { workspace = true } parking_lot = { workspace = true } +png = "0.18" schemars = { workspace = true } serde = { workspace = true } serde_json = { workspace = true } diff --git a/komorebi-recorder/src/frames.rs b/komorebi-recorder/src/frames.rs new file mode 100644 index 00000000..aef4988f --- /dev/null +++ b/komorebi-recorder/src/frames.rs @@ -0,0 +1,273 @@ +//! Extracting still frames from a session's video so the exact moment can be looked at. +//! +//! `ffmpeg` is used to extract stills, here, and by the self-test to read its clock strip; it is +//! never used for capture or for playback. Frames in the mp4 only exist where the screen +//! changed, so the frame returned for a timecode is the most recent one at or before it - which +//! is exactly what was on screen at that moment. +//! +//! This is the `frames` command: [`extract`] picks, for each time asked for, the segment of each +//! display that has video then (see [`crate::session::Manifest::segment_at`]), seeks to the right +//! place in that segment's file, and writes a PNG into the session's `frames/` directory. A display +//! with no video at that moment (unplugged, asleep, between segments) is reported, not an error. +//! +//! Nothing here is specific to a host or a komorebi flavor: the video is an mp4 either way, and +//! `ffmpeg` reads it. What differs by OS is only how to get `ffmpeg` ([`ffmpeg_install_hint`]). + +use crate::session::Manifest; +use crate::session::Session; +use crate::timecode; +use color_eyre::eyre; +use color_eyre::eyre::WrapErr; +use serde::Serialize; +use std::path::PathBuf; +use std::process::Command; + +/// A still frame that [`extract`] wrote. +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct ExtractedFrame { + /// The id of the display the frame is of. + pub display: u32, + /// The time that was asked for, in seconds of video time. + pub video_s: f64, + /// The time within the display's own file. + pub file_s: f64, + /// Where the PNG was written: [`frame_path`] of the display and `video_s`. + pub path: PathBuf, +} + +/// Returns where the frame for `video_s` on `display` goes: `frames/frame--t.png` +/// in the session directory. +/// +/// The time is written in seconds with three decimals, zero padded to nine characters, so the +/// names of one display's frames sort in time order for any time below 100,000 seconds. The time +/// is the one asked for, not the time of the frame ffmpeg found. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::frames::frame_path; +/// use komorebi_recorder::session::Session; +/// use std::path::PathBuf; +/// +/// let session = Session { dir: PathBuf::from("/s") }; +/// let earlier = frame_path(&session, 2, 9.5); +/// let later = frame_path(&session, 2, 12.25); +/// assert_eq!(later, PathBuf::from("/s/frames/frame-2-t00012.250.png")); +/// assert!(earlier < later); +/// ``` +#[must_use] +pub fn frame_path(session: &Session, display: u32, video_s: f64) -> PathBuf { + session.path(format!("frames/frame-{display}-t{video_s:09.3}.png")) +} + +/// Returns how to get `ffmpeg` on this OS, as a fragment to put in a sentence: `winget` or `scoop` +/// on Windows, `brew` or the `nix develop` shell on macOS, and the package manager elsewhere. +#[must_use] +pub fn ffmpeg_install_hint() -> &'static str { + if cfg!(windows) { + "e.g. `winget install Gyan.FFmpeg` or `scoop install ffmpeg`" + } else if cfg!(target_os = "macos") { + "e.g. `brew install ffmpeg`, or use `nix develop`, which provides it" + } else { + "with your package manager" + } +} + +/// Returns true if and only if `ffmpeg` can be run: `ffmpeg -version` is found on `PATH` and +/// succeeds. +#[must_use] +pub fn ffmpeg_available() -> bool { + Command::new("ffmpeg") + .arg("-version") + .output() + .is_ok_and(|output| output.status.success()) +} + +/// A display that was asked for but had no video at the requested moment. +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct Skipped { + /// The id of the display. + pub display: u32, + /// The time that was asked for, in seconds of video time. + pub video_s: f64, + /// Why there was no video, as a sentence. + pub reason: String, +} + +/// What [`extract`] produced: the frames it wrote and the displays it had to leave out. +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct Extraction { + /// The frames written, in the order of the times asked for and, within a time, of the displays' + /// ids. + pub frames: Vec, + /// The displays that had no video at a time asked for. A time at which every display was + /// skipped is an error, so each time asked for has at least one frame in `frames`. + pub skipped: Vec, +} + +/// Extracts a frame at each of `times` from every display (or just `display`) that has video then. +/// +/// A display that was unplugged, asleep or between segments at that moment is reported in +/// `skipped` rather than failing the others. +/// +/// `times` are in seconds of video time (see [`crate::timecode`]). For each, and each display +/// wanted, the segment with video at that time is found with +/// [`Manifest::segment_at`](crate::session::Manifest::segment_at), which allows 50 ms either side +/// of a segment's span. `ffmpeg` is asked for one frame at that time in the segment's file +/// (`file_s`, never below zero), and writes it to [`frame_path`]. Because the video has frames only +/// where the screen changed, that frame is the latest one at or before the time. An existing frame +/// at the same path is overwritten. +/// +/// `display` limits the extraction to one display id; `None` is every display recorded. +/// +/// # Errors +/// +/// Returns an error if +/// +/// * `ffmpeg` cannot be run (the message says how to install it for this OS); +/// * the session has no recorded video, or none for `display`; +/// * a time is before the first frame or more than half a second after the end of the recorded +/// video (the message gives the span); +/// * no display has video at a time (the message names the displays); +/// * the `frames/` directory cannot be created, or `ffmpeg` fails or writes no file (the message +/// has what `ffmpeg` said). +/// +/// Frames already written for earlier times stay on disk when a later time fails. +/// +/// # Example +/// +/// ```rust,no_run +/// use komorebi_recorder::frames::extract; +/// use komorebi_recorder::session::Session; +/// +/// let session = Session::open("/path/to/recordings/20261026T120000Z")?; +/// let manifest = session.manifest()?; +/// +/// // what was on screen at 12.5 s and at 14 s, on every display that had video then +/// let extraction = extract(&session, &manifest, &[12.5, 14.0], None)?; +/// for frame in &extraction.frames { +/// println!("display {} at {:.3} s into its file: {}", frame.display, frame.file_s, frame.path.display()); +/// } +/// # Ok::<(), Box>(()) +/// ``` +/// +/// This needs `ffmpeg` and a recorded session, so it is not run, and no test covers it: the +/// `frames` command is the check. What it can be checked against without video is the file name +/// ([`frame_path`], and the test `frame_paths_sort_chronologically`) and the segment lookup +/// (`Manifest::segment_at`, in the tests of `timeline`). +pub fn extract( + session: &Session, + manifest: &Manifest, + times: &[f64], + display: Option, +) -> eyre::Result { + if !ffmpeg_available() { + eyre::bail!( + "ffmpeg was not found on PATH; install it ({}) to extract frames", + ffmpeg_install_hint() + ); + } + + let ids: Vec = manifest + .display_ids() + .into_iter() + .filter(|id| display.is_none_or(|wanted| wanted == *id)) + .collect(); + + if ids.is_empty() { + eyre::bail!(match display { + Some(id) => format!("display {id} has no recorded video in this session"), + None => "this session has no recorded video".to_string(), + }); + } + + std::fs::create_dir_all(session.path("frames"))?; + let (_, duration) = manifest.video_span(); + let mut extraction = Extraction { + frames: Vec::new(), + skipped: Vec::new(), + }; + + for &video_s in times { + if video_s < 0.0 || video_s > duration + 0.5 { + eyre::bail!( + "{} is outside the recorded video (00:00.000 to {})", + timecode::format(video_s), + timecode::format(duration) + ); + } + + let before = extraction.frames.len(); + for &id in &ids { + let Some(entry) = manifest.segment_at(id, video_s) else { + extraction.skipped.push(Skipped { + display: id, + video_s, + reason: "no video for this display at that moment (it was unplugged, asleep, \ + or its stream had stopped)" + .to_string(), + }); + continue; + }; + + let file_s = (video_s - entry.offset_s).max(0.0); + let path = frame_path(session, id, video_s); + let output = Command::new("ffmpeg") + .args(["-y", "-v", "error", "-ss", &format!("{file_s:.3}"), "-i"]) + .arg(session.path(&entry.result.file)) + .args(["-frames:v", "1"]) + .arg(&path) + .output() + .wrap_err("could not run ffmpeg")?; + + if !output.status.success() || !path.is_file() { + eyre::bail!( + "ffmpeg could not extract a frame at {} from {}: {}", + timecode::format(file_s), + entry.result.file, + String::from_utf8_lossy(&output.stderr).trim() + ); + } + + extraction.frames.push(ExtractedFrame { + display: id, + video_s, + file_s, + path, + }); + } + + if extraction.frames.len() == before { + eyre::bail!( + "no display has video at {}: {}", + timecode::format(video_s), + extraction + .skipped + .iter() + .filter(|skipped| skipped.video_s == video_s) + .map(|skipped| format!("display {}", skipped.display)) + .collect::>() + .join(", ") + ); + } + } + + Ok(extraction) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn frame_paths_sort_chronologically() { + let session = Session { + dir: PathBuf::from("/s"), + }; + let a = frame_path(&session, 2, 9.5); + let b = frame_path(&session, 2, 12.25); + assert_eq!(a, PathBuf::from("/s/frames/frame-2-t00009.500.png")); + assert_eq!(b, PathBuf::from("/s/frames/frame-2-t00012.250.png")); + assert!(a < b); + } +} diff --git a/komorebi-recorder/src/lib.rs b/komorebi-recorder/src/lib.rs index 010c2a38..046fa955 100644 --- a/komorebi-recorder/src/lib.rs +++ b/komorebi-recorder/src/lib.rs @@ -50,6 +50,7 @@ //! | [`session`] | the session directory and its manifest | //! | [`capture`] | capturing the screen into segments of video | //! | [`power`] and [`system_state`] | sleep, wake, lock and display changes | +//! | [`timeline`] and [`frames`] | the time-sorted index of a session and the frame times of its video | //! //! # What is not supported //! @@ -65,6 +66,7 @@ pub mod analysis; pub mod capture; pub mod clock; +pub mod frames; pub mod incidents; pub mod komorebi_link; pub mod lock; @@ -74,3 +76,4 @@ pub mod session; pub mod sources; pub mod system_state; pub mod timecode; +pub mod timeline; diff --git a/komorebi-recorder/src/timeline.rs b/komorebi-recorder/src/timeline.rs new file mode 100644 index 00000000..82776086 --- /dev/null +++ b/komorebi-recorder/src/timeline.rs @@ -0,0 +1,2008 @@ +//! The merged, sorted index over every raw file in a session, and the queries on top of it. +//! +//! `timeline.jsonl` holds one line per record: its time on every clock plus a *reference* +//! (`file`, `offset`, `len`) into a raw file. Raw data is never copied or rewritten, so the index +//! can be rebuilt at any time (`reindex`) and the streams stay separate. +//! +//! Queries binary-search the sorted file by byte offset, so asking about one second of a +//! multi-gigabyte session does not load the index into memory. +//! +//! # The pieces +//! +//! | Item | Does | +//! |---|---| +//! | [`build`] | reads the raw files and the manifest, and writes `timeline.jsonl` | +//! | [`query`] | the records whose time is in a range of video time, optionally narrowed by a [`Filter`] | +//! | [`summary`] | a per-bucket digest of the whole recording ([`Bucket`]) | +//! | [`locate`] | the reverse: a [`Locator`] (a UTC time, a log line, an event) to its video time ([`Located`]) | +//! | [`render`], [`strip_ansi`], [`format_wall_us`] | pure formatting of a record, of text, and of a time | +//! +//! This module reads a session and is the same on every host and for either komorebi flavor. The +//! host that recorded it shows only in what is in the raw files (the OS trace of a Mac, or of +//! Windows) and in the tick size of the manifest's timebase. Which komorebi produced the log and +//! events is not looked at here: it is a matter for `analysis`. +//! +//! # The file: `timeline.jsonl` +//! +//! The index is UTF-8, one JSON object per line ([`TimelineEntry`]), each line ending in `\n`, and +//! is sorted by `mach_ns`, ascending. Records with the same `mach_ns` are ordered by the order in +//! which their source was first met while building (`komorebi-log`, `events`, `recorder`, then the +//! OS trace files in order of path), then by file, then by `offset`. [`build`] writes it to +//! `timeline.jsonl.tmp` and renames that over `timeline.jsonl`, so a reader never sees a +//! half-written index. +//! +//! | Field | JSON | Is | +//! |---|---|---| +//! | `video_s` | number | the record's time in video time: seconds since the first captured frame, negative before it. It is the manifest's `video_seconds` of `mach_ns` as the manifest was when the index was built | +//! | `mach_ns` | integer | the record's time on the master clock, in nanoseconds (see [`crate::clock`]) | +//! | `wall_utc` | string or `null` | the same time as RFC 3339 UTC with microseconds, `2027-01-15T08:00:02.000000Z`, worked out from the manifest's anchors. `null` if that cannot be done, which is if the manifest has none | +//! | `source` | string | which stream the record is from, see below | +//! | `pid` | integer, left out if unknown | the process the record is about: an OS trace record's `processID`, or the process id a window manager event carries | +//! | `file` | string | the raw file, relative to the session directory, always with `/` separators | +//! | `offset` | integer | the byte offset in `file` of the start of the record | +//! | `len` | integer | how many bytes the record is, including its line terminator | +//! | `line` | integer | the record's 1-based line number in `file` | +//! | `seq` | integer, left out for all but events | the subscriber event sequence number | +//! +//! `file`, `offset` and `len` are the reference: the raw record is `len` bytes at `offset` of +//! `file`, with a trailing `\n` or `\r\n` removed when it is shown. Nothing but the reference +//! points into the raw files, so a raw file edited by hand needs a `reindex`, and an index older +//! than its raw files can point into the wrong bytes. +//! +//! # The sources +//! +//! | `source` | Raw file | Time of a record | +//! |---|---|---| +//! | `komorebi-log` ([`SOURCE_KOMOREBI_LOG`]) | `komorebi.log` | the line's UTC time, through the manifest's anchors ([`crate::clock::ClockMap`]) | +//! | `events` ([`SOURCE_EVENTS`]) | `events.jsonl` | `recv_mach_ns`, stamped on the master clock when the recorder received it | +//! | `recorder` ([`SOURCE_RECORDER`]) | `recorder.jsonl` | the incident's `mach_ns` (see [`crate::incidents`]) | +//! | `oslog:komorebi`, `oslog:system`, `oslog:eventlog`, `oslog:all`, `oslog:app:` | every `.ndjson` file in `oslog/` and `oslog/apps/` | `hostNs` if the line has one (the Windows OS trace), else its `machTimestamp` ticks converted with the manifest's timebase | +//! +//! The OS trace sources keep the `oslog:` prefix on every host, though on Windows it is not the +//! unified log. A file's source is the one the manifest lists for it; for a file it does not list, +//! such as one added by hand, it comes from the file's name: `komorebi.ndjson` and +//! `komorebi-.ndjson` are `oslog:komorebi`, `system.ndjson`, `eventlog.ndjson` and +//! `all.ndjson` are `oslog:system`, `oslog:eventlog` and `oslog:all`, and any other is +//! `oslog:app:`, with a trailing `-` taken off. +//! +//! A line is left out of the index if it has no time: a line of `komorebi.log` before the first +//! timestamped one, and every line of it if the manifest has no anchors; a row of `events.jsonl` +//! or `recorder.jsonl` that is not valid JSON of the right shape, such as one cut short by a crash; +//! an OS trace line with neither `hostNs` nor `machTimestamp`. Continuation lines of +//! `komorebi.log` (a panic message, a backtrace) are in the index, with the time of the line they +//! follow. +//! +//! # Cost +//! +//! [`build`] holds one compact record per index entry in memory while it sorts, and reads +//! `komorebi.log` whole. [`query`] does not load the index: it finds its starting place by binary +//! search on byte offsets, and reads only the lines in the range. [`summary`] reads the whole +//! index, one line at a time. [`locate`] does not use the index at all: it reads `komorebi.log` or +//! `events.jsonl`, and the manifest. +//! +//! # Example +//! +//! Building the index of a small session, and asking it questions: +//! +//! ```rust +//! use chrono::Utc; +//! use komorebi_recorder::clock::Anchor; +//! use komorebi_recorder::session::{Manifest, Moment, Session, TIMELINE_FILE}; +//! use komorebi_recorder::timeline::{self, Filter, Locator, TimelineEntry}; +//! +//! let dir = std::env::temp_dir().join(format!("komorebi-recorder-doc-timeline-{}", std::process::id())); +//! let _ = std::fs::remove_dir_all(&dir); +//! let session = Session::create(Some(dir.clone()), Utc::now())?; +//! +//! // the wall clock read 2027-01-15T08:00:00Z when the master clock read 100 s, which is also +//! // when the first video frame was captured: video time 0 is master clock time 100 s +//! let anchor = Anchor { wall_us: 1_800_000_000_000_000, mach_ns: 100_000_000_000 }; +//! let start = Moment { mach_ns: anchor.mach_ns, wall_us: anchor.wall_us }; +//! let mut manifest = Manifest::new(start, vec![anchor]); +//! manifest.video_t0_mach_ns = Some(anchor.mach_ns); +//! manifest.video_end_mach_ns = Some(110_000_000_000); +//! session.write_manifest(&manifest)?; +//! +//! // komorebi's log is stamped with the wall clock: this line is 2 s into the video +//! std::fs::write( +//! session.path("komorebi.log"), +//! "2027-01-15T08:00:02.000000Z INFO komorebi::process_event: processing event: Show\n", +//! )?; +//! // an event is stamped with the master clock when it is received, 10 ms later +//! std::fs::write( +//! session.path("events.jsonl"), +//! concat!( +//! r#"{"seq":1,"recv_wall_us":1800000002010000,"recv_mach_ns":102010000000,"#, +//! r#""event":{"type":"Show","content":[{"type":"Accessibility","content":"AXWindowCreated"},111,7]}}"#, +//! "\n", +//! ), +//! )?; +//! +//! let stats = timeline::build(&session)?; +//! assert_eq!(stats.entries, 2); +//! assert_eq!(stats.by_source["komorebi-log"], 1); +//! assert_eq!(stats.by_source["events"], 1); +//! +//! // the index: one entry per record, sorted by time, pointing into the raw files +//! let index = std::fs::read_to_string(session.path(TIMELINE_FILE))?; +//! let entries: Vec = index +//! .lines() +//! .map(serde_json::from_str) +//! .collect::>()?; +//! assert_eq!(entries[0].source, "komorebi-log"); +//! assert_eq!(entries[0].video_s, 2.0); +//! assert_eq!(entries[0].wall_utc.as_deref(), Some("2027-01-15T08:00:02.000000Z")); +//! assert_eq!((entries[0].file.as_str(), entries[0].offset, entries[0].line), ("komorebi.log", 0, 1)); +//! assert_eq!(entries[1].source, "events"); +//! assert_eq!(entries[1].pid, Some(111)); +//! assert_eq!(entries[1].seq, Some(1)); +//! +//! // what happened between 1.5 s and 2.5 s into the video? +//! let records = timeline::query(&session, &manifest, 1.5, 2.5, &Filter::default())?; +//! assert_eq!(records.len(), 2); +//! assert!(records[0].text.ends_with("processing event: Show")); +//! assert!(records[1].text.starts_with("#1 {")); +//! +//! // only the events +//! let only_events = Filter { sources: vec!["events".to_string()], ..Filter::default() }; +//! assert_eq!(timeline::query(&session, &manifest, 0.0, 10.0, &only_events)?.len(), 1); +//! +//! // and the reverse: where in the video is line 1 of komorebi's log? +//! let located = timeline::locate(&session, &manifest, &Locator::LogLine(1))?; +//! assert_eq!(located.video_s, 2.0); +//! assert!(located.in_video); +//! # std::fs::remove_dir_all(&dir)?; +//! # Ok::<(), Box>(()) +//! ``` + +use crate::clock::ClockMap; +use crate::incidents::INCIDENTS_FILE; +use crate::incidents::Incident; +use crate::session::Manifest; +use crate::session::Session; +use crate::session::TIMELINE_FILE; +use crate::sources::komorebi_events::EventRow; +use crate::sources::komorebi_log; +use crate::sources::managed_apps; +use crate::sources::oslog; +use crate::sources::oslog::OsLogRecord; +use chrono::DateTime; +use chrono::Utc; +use color_eyre::eyre; +use color_eyre::eyre::WrapErr; +use serde::Deserialize; +use serde::Serialize; +use std::collections::BTreeMap; +use std::collections::HashMap; +use std::fs::File; +use std::io::BufRead; +use std::io::BufReader; +use std::io::BufWriter; +use std::io::Read; +use std::io::Seek; +use std::io::SeekFrom; +use std::io::Write; + +/// The timeline source of komorebi's log: `komorebi-log`. +pub const SOURCE_KOMOREBI_LOG: &str = "komorebi-log"; +/// The timeline source of the subscriber's events: `events`. +pub const SOURCE_EVENTS: &str = "events"; +/// The timeline source of incidents: `recorder` (see [`crate::incidents`]). +pub use crate::incidents::SOURCE_RECORDER; + +/// One line of `timeline.jsonl`: a record's time on every clock, and where the record is. +/// +/// The fields are written in the order they are declared here. The format of the file, with what +/// each field means, is in the [module docs](self#the-file-timelinejsonl). +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::timeline::TimelineEntry; +/// +/// // `pid` and `seq` are left out when there is none, and `wall_utc` is `null` when unknown +/// let entry = TimelineEntry { +/// video_s: 2.5, +/// mach_ns: 102_500_000_000, +/// wall_utc: None, +/// source: "recorder".to_string(), +/// pid: None, +/// file: "recorder.jsonl".to_string(), +/// offset: 120, +/// len: 98, +/// line: 2, +/// seq: None, +/// }; +/// assert_eq!( +/// serde_json::to_string(&entry)?, +/// r#"{"video_s":2.5,"mach_ns":102500000000,"wall_utc":null,"source":"recorder","file":"recorder.jsonl","offset":120,"len":98,"line":2}"# +/// ); +/// +/// // and a line reads back as it was written +/// let back: TimelineEntry = serde_json::from_str(&serde_json::to_string(&entry)?)?; +/// assert_eq!(back, entry); +/// # Ok::<(), serde_json::Error>(()) +/// ``` +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct TimelineEntry { + /// Seconds since the first video frame (negative before it). + pub video_s: f64, + /// The record's time on the master clock, in nanoseconds. + pub mach_ns: u64, + /// RFC 3339 UTC with microseconds. + pub wall_utc: Option, + /// Which stream the record is from: `komorebi-log`, `events`, `recorder`, or an OS trace + /// source starting `oslog:`. + pub source: String, + /// The process the record is about, where it has one: an OS trace record's `processID`, or the + /// process id carried by a window manager event. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub pid: Option, + /// Raw file, relative to the session directory. + pub file: String, + /// The byte offset of the start of the record in `file`. + pub offset: u64, + /// How many bytes the record is in `file`, including its line terminator. + pub len: u64, + /// 1-based line number in the raw file. + pub line: u64, + /// The subscriber event sequence number, for `events` records. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub seq: Option, +} + +/// A timeline entry together with the raw text it points at. +/// +/// A query returns these. Serialized, a record is its entry's fields followed by `text`. +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct Record { + /// The index entry. + #[serde(flatten)] + pub entry: TimelineEntry, + /// The raw record, rendered for reading (see [`render`]). + pub text: String, +} + +/// Compact in-memory form used only while building. +struct Pending { + mach_ns: u64, + source: u32, + file: u32, + pid: Option, + offset: u64, + len: u64, + line: u64, + seq: Option, +} + +#[derive(Default)] +struct Interner { + names: Vec, + ids: HashMap, +} + +impl Interner { + fn id(&mut self, name: &str) -> u32 { + if let Some(id) = self.ids.get(name) { + return *id; + } + + let id = self.names.len() as u32; + self.names.push(name.to_string()); + self.ids.insert(name.to_string(), id); + id + } +} + +/// What [`build`] put in the index. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct BuildStats { + /// How many entries the index has. + pub entries: u64, + /// How many of those are from each source, by source name. A source with no entries is not + /// listed. + pub by_source: BTreeMap, +} + +fn wall_utc(clock: &ClockMap, mach_ns: u64) -> Option { + let wall_us = clock.mach_to_wall(mach_ns)?; + format_wall_us(wall_us) +} + +/// Returns a wall clock time as RFC 3339 UTC with microseconds and a `Z`, or `None` if it is +/// beyond what can be represented as a date. +/// +/// The argument is in microseconds since the Unix epoch, as `wall_us` is throughout a session. This +/// is the form of `wall_utc` in the index. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::timeline::format_wall_us; +/// +/// assert_eq!( +/// format_wall_us(1_800_000_000_250_000).as_deref(), +/// Some("2027-01-15T08:00:00.250000Z") +/// ); +/// assert_eq!(format_wall_us(0).as_deref(), Some("1970-01-01T00:00:00.000000Z")); +/// assert_eq!(format_wall_us(i64::MAX), None); +/// ``` +#[must_use] +pub fn format_wall_us(wall_us: i64) -> Option { + DateTime::::from_timestamp_micros(wall_us) + .map(|time| time.format("%Y-%m-%dT%H:%M:%S%.6fZ").to_string()) +} + +/// Which timeline source an unknown file under `oslog/` belongs to, from its name alone. Used for +/// hand-added files and when the manifest does not list a stream. +fn source_for_oslog_file(relative: &str) -> String { + let name = relative.strip_prefix("oslog/").unwrap_or(relative); + match name { + "komorebi.ndjson" => "oslog:komorebi".to_string(), + _ if name.starts_with("komorebi-") && name.ends_with(".ndjson") => { + "oslog:komorebi".to_string() + } + "system.ndjson" => "oslog:system".to_string(), + "eventlog.ndjson" => "oslog:eventlog".to_string(), + "all.ndjson" => "oslog:all".to_string(), + _ => { + let stem = name + .strip_prefix("apps/") + .unwrap_or(name) + .trim_end_matches(".ndjson"); + let exe = stem.rsplit_once('-').map_or(stem, |(exe, _pid)| exe); + format!("oslog:app:{exe}") + } + } +} + +fn list_oslog_files(session: &Session) -> Vec { + let mut files = Vec::new(); + for sub in ["oslog", "oslog/apps"] { + let Ok(entries) = std::fs::read_dir(session.path(sub)) else { + continue; + }; + + for entry in entries.flatten() { + let name = entry.file_name().to_string_lossy().into_owned(); + if name.ends_with(".ndjson") { + files.push(format!("{sub}/{name}")); + } + } + } + + files.sort(); + files +} + +/// Builds `timeline.jsonl` from the raw files and the manifest. +/// +/// Every raw file the session has is read (see the sources in the [module docs](self#the-sources)), +/// each record is given its time on the master clock, and the entries are written sorted, replacing +/// any existing index. A raw file the session does not have is skipped, so a session with no +/// events, say, has no `events` entries. The raw files are only read. The index is written to +/// `timeline.jsonl.tmp` and renamed over `timeline.jsonl`, so the old index stays whole until the +/// new one is. +/// +/// Building twice from the same raw files and manifest gives the same index (the test +/// `reindex_is_idempotent_and_recovers_a_deleted_timeline`). +/// +/// # Errors +/// +/// Returns an error if +/// +/// * the manifest cannot be read (see [`Session::manifest`]); +/// * a raw file that exists cannot be read; +/// * `timeline.jsonl.tmp` cannot be created or written; +/// * the finished file cannot be renamed over `timeline.jsonl`. +/// +/// # Example +/// +/// See the [module example](self#example), which builds the index of a session and reads it back. +pub fn build(session: &Session) -> eyre::Result { + let manifest = session.manifest()?; + let clock = ClockMap::new(manifest.anchors.clone()); + let mut sources = Interner::default(); + let mut files = Interner::default(); + let mut pending: Vec = Vec::new(); + + // komorebi's own log: UTC wall clock -> mach via the anchors + let log_path = session.path("komorebi.log"); + if log_path.is_file() { + let bytes = std::fs::read(&log_path)?; + let source = sources.id(SOURCE_KOMOREBI_LOG); + let file = files.id("komorebi.log"); + for line in komorebi_log::index_lines(&bytes) { + let Some(timestamp) = line.timestamp else { + continue; + }; + let Some(mach_ns) = clock.wall_to_mach(timestamp.timestamp_micros()) else { + continue; + }; + + pending.push(Pending { + mach_ns, + source, + file, + pid: None, + offset: line.offset, + len: line.len, + line: line.number, + seq: None, + }); + } + } + + // subscriber events: stamped on the mach clock at receipt + let events_path = session.path("events.jsonl"); + if events_path.is_file() { + let source = sources.id(SOURCE_EVENTS); + let file = files.id("events.jsonl"); + let mut reader = BufReader::new(File::open(&events_path)?); + let mut buffer = String::new(); + let (mut offset, mut number) = (0_u64, 0_u64); + loop { + buffer.clear(); + let read = reader.read_line(&mut buffer)?; + if read == 0 { + break; + } + + number += 1; + if let Ok(row) = serde_json::from_str::(&buffer) { + pending.push(Pending { + mach_ns: row.recv_mach_ns, + source, + file, + pid: row + .event + .as_ref() + .and_then(managed_apps::event_pid) + .map(i64::from), + offset, + len: read as u64, + line: number, + seq: Some(row.seq), + }); + } + + offset += read as u64; + } + } + + // incidents (display changes, sleep/wake, restarts): stamped on the mach clock when noticed + let incidents_path = session.path(INCIDENTS_FILE); + if incidents_path.is_file() { + let source = sources.id(SOURCE_RECORDER); + let file = files.id(INCIDENTS_FILE); + let mut reader = BufReader::new(File::open(&incidents_path)?); + let mut buffer = String::new(); + let (mut offset, mut number) = (0_u64, 0_u64); + loop { + buffer.clear(); + let read = reader.read_line(&mut buffer)?; + if read == 0 { + break; + } + + number += 1; + if let Ok(incident) = serde_json::from_str::(&buffer) { + pending.push(Pending { + mach_ns: incident.mach_ns, + source, + file, + pid: None, + offset, + len: read as u64, + line: number, + seq: None, + }); + } + + offset += read as u64; + } + } + + // unified log streams: already on the mach clock + let manifest_sources: HashMap<&str, &str> = manifest + .oslog + .iter() + .map(|info| (info.spec.file.as_str(), info.spec.source.as_str())) + .collect(); + + for relative in list_oslog_files(session) { + let source_name = manifest_sources.get(relative.as_str()).map_or_else( + || source_for_oslog_file(&relative), + |source| (*source).to_string(), + ); + let source = sources.id(&source_name); + let file = files.id(&relative); + + let mut reader = BufReader::with_capacity(256 * 1024, File::open(session.path(&relative))?); + let mut buffer = Vec::new(); + let (mut offset, mut number) = (0_u64, 0_u64); + loop { + buffer.clear(); + let read = reader.read_until(b'\n', &mut buffer)?; + if read == 0 { + break; + } + + number += 1; + // converted with the session's own timebase, not this machine's: a session recorded on + // one OS is read on another + if let Some(mach_ns) = oslog::extract_time_ns(&buffer, manifest.timebase) { + pending.push(Pending { + mach_ns, + source, + file, + pid: extract_pid(&buffer), + offset, + len: read as u64, + line: number, + seq: None, + }); + } + + offset += read as u64; + } + } + + pending.sort_by_key(|entry| (entry.mach_ns, entry.source, entry.file, entry.offset)); + + let path = session.path(TIMELINE_FILE); + let temporary = session.path(format!("{TIMELINE_FILE}.tmp")); + let mut writer = BufWriter::new( + File::create(&temporary) + .wrap_err_with(|| format!("could not create {}", temporary.display()))?, + ); + + let mut stats = BuildStats::default(); + for entry in &pending { + let source = &sources.names[entry.source as usize]; + let row = TimelineEntry { + video_s: manifest.video_seconds(entry.mach_ns), + mach_ns: entry.mach_ns, + wall_utc: wall_utc(&clock, entry.mach_ns), + source: source.clone(), + pid: entry.pid, + file: files.names[entry.file as usize].clone(), + offset: entry.offset, + len: entry.len, + line: entry.line, + seq: entry.seq, + }; + + writeln!(writer, "{}", serde_json::to_string(&row)?)?; + stats.entries += 1; + *stats.by_source.entry(source.clone()).or_default() += 1; + } + + writer.flush()?; + drop(writer); + std::fs::rename(&temporary, &path)?; + Ok(stats) +} + +/// Pull `"processID":` out of a raw ndjson line. +fn extract_pid(line: &[u8]) -> Option { + const KEY: &[u8] = b"\"processID\":"; + let start = line.windows(KEY.len()).position(|window| window == KEY)? + KEY.len(); + let digits: Vec = line[start..] + .iter() + .copied() + .take_while(|byte| byte.is_ascii_digit() || *byte == b'-') + .collect(); + + std::str::from_utf8(&digits).ok()?.parse().ok() +} + +/// Narrowing for queries: which sources, and which application, to keep. +/// +/// The default keeps every record. When both fields are set, a record must pass both. +/// +/// # Example +/// +/// The two fields combine, and `app` keeps an application's OS trace records only, never the +/// komorebi log or events that merely mention it: +/// +/// ```rust +/// use komorebi_recorder::timeline::Filter; +/// +/// // the OS trace of one application, by exe name (any case) or by process id +/// let ghostty = Filter { app: Some("ghostty".to_string()), sources: vec![] }; +/// let by_pid = Filter { app: Some("111".to_string()), ..Filter::default() }; +/// +/// // two sources: komorebi's log, and the OS trace of the komorebi process +/// let two = Filter { +/// sources: vec!["komorebi-log".to_string(), "oslog:komorebi".to_string()], +/// ..Filter::default() +/// }; +/// # let _ = (ghostty, by_pid, two); +/// ``` +/// +/// The behavior is covered by the tests `source_filter_supports_prefixes` and +/// `app_filter_returns_only_that_apps_records`. +#[derive(Debug, Clone, Default)] +pub struct Filter { + /// An app's exe name (case-insensitive) or a pid. + /// + /// Keeps only OS trace records (sources starting `oslog:`) of that app: those with its process + /// id, or whose source is `oslog:app:`. A name is looked up in the manifest's apps to + /// find its process ids. + pub app: Option, + /// Sources to keep: `komorebi-log`, `events`, `oslog` (all OS trace), `oslog:komorebi`, + /// `oslog:system`, `oslog:app` (all apps) or `oslog:app:`. Empty keeps everything. + /// + /// A name matches a source if it equals it, ignoring case, or is a prefix of it that ends + /// where the source has a `:`. So `oslog` keeps `oslog:system`, but `osl` keeps nothing. + pub sources: Vec, +} + +fn source_matches(source: &str, wanted: &str) -> bool { + source.eq_ignore_ascii_case(wanted) + || source.get(..wanted.len()).is_some_and(|prefix| { + prefix.eq_ignore_ascii_case(wanted) + && source.as_bytes().get(wanted.len()) == Some(&b':') + }) +} + +/// The pids and source labels an `--app` argument refers to, using the manifest's app list. +fn resolve_app(manifest: &Manifest, app: &str) -> (Vec, String) { + if let Ok(pid) = app.parse::() { + return (vec![pid], String::new()); + } + + let pids = manifest + .apps + .iter() + .filter(|record| record.exe.eq_ignore_ascii_case(app)) + .map(|record| i64::from(record.pid)) + .collect(); + + (pids, format!("oslog:app:{app}")) +} + +impl Filter { + fn accepts(&self, entry: &TimelineEntry, app: Option<&(Vec, String)>) -> bool { + if !self.sources.is_empty() + && !self + .sources + .iter() + .any(|wanted| source_matches(&entry.source, wanted)) + { + return false; + } + + if let Some((pids, source)) = app { + let by_pid = entry.pid.is_some_and(|pid| pids.contains(&pid)); + let by_source = !source.is_empty() && entry.source.eq_ignore_ascii_case(source); + // `--app` is "only this app's records": the komorebi log and events are not that + // app's, even though events may mention its pid + let is_app_data = entry.source.starts_with("oslog:"); + return is_app_data && (by_pid || by_source); + } + + true + } +} + +fn read_entry_line( + reader: &mut BufReader, + buffer: &mut String, +) -> eyre::Result> { + buffer.clear(); + let read = reader.read_line(buffer)?; + if read == 0 { + return Ok(None); + } + + let entry: TimelineEntry = serde_json::from_str(buffer.trim_end()) + .wrap_err("timeline.jsonl contains an invalid line; run `reindex`")?; + Ok(Some((entry, read as u64))) +} + +/// The byte offset of the first line whose `mach_ns` is `>= target`, or the file length. +fn lower_bound(file: &mut BufReader, size: u64, target: u64) -> eyre::Result { + let mut buffer = String::new(); + + // the first line start at or after `position` + let line_start_at_or_after = |file: &mut BufReader, position: u64| -> eyre::Result { + if position == 0 { + return Ok(0); + } + + file.seek(SeekFrom::Start(position - 1))?; + let mut skipped = Vec::new(); + let read = file.read_until(b'\n', &mut skipped)?; + Ok(position - 1 + read as u64) + }; + + let (mut low, mut high) = (0_u64, size); + while low < high { + let middle = low + (high - low) / 2; + let start = line_start_at_or_after(file, middle)?; + if start >= high { + high = middle; + continue; + } + + file.seek(SeekFrom::Start(start))?; + match read_entry_line(file, &mut buffer)? { + Some((entry, length)) => { + if entry.mach_ns < target { + low = start + length; + } else { + high = start; + } + } + None => high = middle, + } + } + + Ok(low) +} + +/// Raw files opened on demand while rendering records. +struct RawFiles<'a> { + session: &'a Session, + open: HashMap, +} + +impl<'a> RawFiles<'a> { + fn new(session: &'a Session) -> Self { + Self { + session, + open: HashMap::new(), + } + } + + fn read(&mut self, entry: &TimelineEntry) -> eyre::Result { + if !self.open.contains_key(&entry.file) { + let path = self.session.path(&entry.file); + let file = + File::open(&path).wrap_err_with(|| format!("could not open {}", path.display()))?; + self.open.insert(entry.file.clone(), file); + } + + let file = self + .open + .get_mut(&entry.file) + .ok_or_else(|| eyre::Report::msg("raw file vanished"))?; + file.seek(SeekFrom::Start(entry.offset))?; + let mut bytes = vec![0_u8; entry.len as usize]; + file.read_exact(&mut bytes)?; + Ok(String::from_utf8_lossy(&bytes) + .trim_end_matches(['\n', '\r']) + .to_string()) + } +} + +const EVENT_TEXT_LIMIT: usize = 400; + +/// Renders a raw record for reading: one line of text for the entry `entry`, whose raw text is +/// `raw`. +/// +/// What it does depends on the entry's source: +/// +/// | Source | Rendered as | +/// |---|---| +/// | `komorebi-log` | the raw line with ANSI escapes removed ([`strip_ansi`]) | +/// | `recorder` | `: ` | +/// | `events` | `# `, then ` state=states/.json` if the event stored a state (the id is zero padded to 6 digits) | +/// | anything else, the OS trace | `