diff --git a/Cargo.lock b/Cargo.lock index e4217cf2..6a2abfd5 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -17,6 +17,15 @@ version = "2.0.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa" +[[package]] +name = "android_system_properties" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311" +dependencies = [ + "libc", +] + [[package]] name = "anstream" version = "1.0.0" @@ -100,12 +109,41 @@ version = "2.11.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3" +[[package]] +name = "bumpalo" +version = "3.20.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb" + +[[package]] +name = "cc" +version = "1.2.61" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d16d90359e986641506914ba71350897565610e87ce0ad9e6f28569db3dd5c6d" +dependencies = [ + "find-msvc-tools", + "shlex", +] + [[package]] name = "cfg-if" version = "1.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" +[[package]] +name = "chrono" +version = "0.4.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c673075a2e0e5f4a1dde27ce9dee1ea4558c7ffe648f576438a20ca1d2acc4b0" +dependencies = [ + "iana-time-zone", + "js-sys", + "num-traits", + "wasm-bindgen", + "windows-link", +] + [[package]] name = "clap" version = "4.6.1" @@ -180,6 +218,12 @@ version = "1.0.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570" +[[package]] +name = "core-foundation-sys" +version = "0.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" + [[package]] name = "crossbeam-channel" version = "0.5.15" @@ -254,12 +298,42 @@ version = "2.4.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6" +[[package]] +name = "find-msvc-tools" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582" + [[package]] name = "foldhash" version = "0.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2" +[[package]] +name = "futures-core" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d" + +[[package]] +name = "futures-task" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393" + +[[package]] +name = "futures-util" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6" +dependencies = [ + "futures-core", + "futures-task", + "pin-project-lite", + "slab", +] + [[package]] name = "getrandom" version = "0.2.17" @@ -311,6 +385,30 @@ version = "0.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" +[[package]] +name = "iana-time-zone" +version = "0.1.65" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470" +dependencies = [ + "android_system_properties", + "core-foundation-sys", + "iana-time-zone-haiku", + "js-sys", + "log", + "wasm-bindgen", + "windows-core", +] + +[[package]] +name = "iana-time-zone-haiku" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f" +dependencies = [ + "cc", +] + [[package]] name = "id-arena" version = "2.3.0" @@ -347,15 +445,30 @@ version = "1.0.18" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" +[[package]] +name = "js-sys" +version = "0.3.97" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a1840c94c045fbcf8ba2812c95db44499f7c64910a912551aaaa541decebcacf" +dependencies = [ + "cfg-if", + "futures-util", + "once_cell", + "wasm-bindgen", +] + [[package]] name = "komorebi-recorder" version = "0.1.0" dependencies = [ + "chrono", "clap", "color-eyre", "crossbeam-channel", "dirs", "libc", + "objc2-core-foundation", + "objc2-core-graphics", "schemars", "serde", "serde_json_lenient", @@ -426,6 +539,35 @@ dependencies = [ "adler2", ] +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", +] + +[[package]] +name = "objc2-core-foundation" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536" +dependencies = [ + "bitflags", +] + +[[package]] +name = "objc2-core-graphics" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807" +dependencies = [ + "bitflags", + "libc", + "objc2-core-foundation", +] + [[package]] name = "object" version = "0.37.3" @@ -549,6 +691,12 @@ dependencies = [ "windows-sys 0.52.0", ] +[[package]] +name = "rustversion" +version = "1.0.22" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d" + [[package]] name = "ryu" version = "1.0.23" @@ -661,6 +809,18 @@ dependencies = [ "lazy_static", ] +[[package]] +name = "shlex" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64" + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + [[package]] name = "strsim" version = "0.11.1" @@ -830,6 +990,51 @@ dependencies = [ "wit-bindgen 0.51.0", ] +[[package]] +name = "wasm-bindgen" +version = "0.2.120" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df52b6d9b87e0c74c9edfa1eb2d9bf85e5d63515474513aa50fa181b3c4f5db1" +dependencies = [ + "cfg-if", + "once_cell", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.120" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78b1041f495fb322e64aca85f5756b2172e35cd459376e67f2a6c9dffcedb103" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.120" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9dcd0ff20416988a18ac686d4d4d0f6aae9ebf08a389ff5d29012b05af2a1b41" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.120" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "49757b3c82ebf16c57d69365a142940b384176c24df52a087fb748e2085359ea" +dependencies = [ + "unicode-ident", +] + [[package]] name = "wasm-encoder" version = "0.244.0" diff --git a/dependencies.json b/dependencies.json index e5d20f62..d95fe1eb 100644 --- a/dependencies.json +++ b/dependencies.json @@ -20,6 +20,7 @@ "backtrace 0.3.76 registry+https://github.com/rust-lang/crates.io-index", "bitflags 2.11.1 registry+https://github.com/rust-lang/crates.io-index", "cfg-if 1.0.4 registry+https://github.com/rust-lang/crates.io-index", + "chrono 0.4.44 registry+https://github.com/rust-lang/crates.io-index", "clap 4.6.1 registry+https://github.com/rust-lang/crates.io-index", "clap_builder 4.6.0 registry+https://github.com/rust-lang/crates.io-index", "clap_derive 4.6.1 registry+https://github.com/rust-lang/crates.io-index", @@ -27,6 +28,7 @@ "color-eyre 0.6.5 registry+https://github.com/rust-lang/crates.io-index", "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", "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,12 +40,16 @@ "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", + "iana-time-zone 0.1.65 registry+https://github.com/rust-lang/crates.io-index", "indenter 0.3.4 registry+https://github.com/rust-lang/crates.io-index", "is_terminal_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index", "itoa 1.0.18 registry+https://github.com/rust-lang/crates.io-index", "lazy_static 1.5.0 registry+https://github.com/rust-lang/crates.io-index", "libc 0.2.186 registry+https://github.com/rust-lang/crates.io-index", "miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index", + "num-traits 0.2.19 registry+https://github.com/rust-lang/crates.io-index", + "objc2-core-foundation 0.3.2 registry+https://github.com/rust-lang/crates.io-index", + "objc2-core-graphics 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "object 0.37.3 registry+https://github.com/rust-lang/crates.io-index", "once_cell 1.21.4 registry+https://github.com/rust-lang/crates.io-index", "once_cell_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index", @@ -119,6 +125,7 @@ "backtrace 0.3.76 registry+https://github.com/rust-lang/crates.io-index", "bitflags 2.11.1 registry+https://github.com/rust-lang/crates.io-index", "cfg-if 1.0.4 registry+https://github.com/rust-lang/crates.io-index", + "chrono 0.4.44 registry+https://github.com/rust-lang/crates.io-index", "clap 4.6.1 registry+https://github.com/rust-lang/crates.io-index", "clap_builder 4.6.0 registry+https://github.com/rust-lang/crates.io-index", "clap_derive 4.6.1 registry+https://github.com/rust-lang/crates.io-index", @@ -126,6 +133,7 @@ "color-eyre 0.6.5 registry+https://github.com/rust-lang/crates.io-index", "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", "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", @@ -137,6 +145,7 @@ "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", + "iana-time-zone 0.1.65 registry+https://github.com/rust-lang/crates.io-index", "indenter 0.3.4 registry+https://github.com/rust-lang/crates.io-index", "is_terminal_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index", "itoa 1.0.18 registry+https://github.com/rust-lang/crates.io-index", @@ -145,6 +154,9 @@ "memchr 2.8.0 registry+https://github.com/rust-lang/crates.io-index", "memoffset 0.9.1 registry+https://github.com/rust-lang/crates.io-index", "miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index", + "num-traits 0.2.19 registry+https://github.com/rust-lang/crates.io-index", + "objc2-core-foundation 0.3.2 registry+https://github.com/rust-lang/crates.io-index", + "objc2-core-graphics 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "object 0.37.3 registry+https://github.com/rust-lang/crates.io-index", "once_cell 1.21.4 registry+https://github.com/rust-lang/crates.io-index", "once_cell_polyfill 1.70.2 registry+https://github.com/rust-lang/crates.io-index", @@ -219,7 +231,9 @@ [ "Zlib", [ - "miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index" + "miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index", + "objc2-core-foundation 0.3.2 registry+https://github.com/rust-lang/crates.io-index", + "objc2-core-graphics 0.3.2 registry+https://github.com/rust-lang/crates.io-index" ] ] ] diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 7db49510..45b48568 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -63,6 +63,18 @@ refuses an implementor that misses one. A method with a default is a question mo doc of each says what the default is. `Rules::verified` is how a flavor says that its rules were written from komorebi's source and have not been checked against a recording of it: an analysis that reads such a session says so. +## The session + +A session is a directory. Its manifest, `session.json`, is the one file everything else is read through: the host and the +flavor, the clock anchors, the komorebi processes that were seen and how each was logging, the byte ranges of komorebi's +log that were recorded and the applications that were traced. It is written to a temporary file and renamed, so a reader +or a crash never sees half of one, and its `schema_version` is checked on every read: a manifest written by a newer +build is refused with an error that says so, rather than read wrongly. + +The files beside it are the raw records, and they are written as the data arrives and never rewritten: komorebi's log +(`komorebi.log`, the exact byte range recorded), its events (`events.jsonl`, with full `State` snapshots in `states/` +only when they changed), and what happened to the recording itself (`recorder.jsonl`). + ## Rules and the layer that enforces them | Rule | Enforced by | @@ -73,3 +85,5 @@ source and have not been checked against a recording of it: an analysis that rea | Code that reads komorebi's output asks `Rules` and does not match on `Flavor` | convention only | | Rules that were not checked against a recording of komorebi say so | the framework path: an analysis that reads such a session adds a warning | | 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 | diff --git a/komorebi-recorder/Cargo.toml b/komorebi-recorder/Cargo.toml index 072b9166..9373c315 100644 --- a/komorebi-recorder/Cargo.toml +++ b/komorebi-recorder/Cargo.toml @@ -6,6 +6,7 @@ edition.workspace = true repository.workspace = true [dependencies] +chrono = { workspace = true } clap = { workspace = true } color-eyre = { workspace = true } crossbeam-channel = { workspace = true } @@ -16,6 +17,25 @@ serde_json = { workspace = true } [target.'cfg(target_os = "macos")'.dependencies] libc = "0.2" +objc2-core-foundation = { version = "0.3", default-features = false, features = [ + "std", + "CFArray", + "CFDictionary", + "CFNumber", + "CFString", + "CFCGTypes", +] } +objc2-core-graphics = { version = "0.3", default-features = false, features = [ + "std", + "libc", + "CGDirectDisplay", + "CGDisplayConfiguration", + "CGError", + "CGGeometry", + "CGRemoteOperation", + "CGSession", + "CGWindow", +] } [target.'cfg(windows)'.dependencies] uds_windows = "1" diff --git a/komorebi-recorder/src/analysis/events.rs b/komorebi-recorder/src/analysis/events.rs index eb621225..744c5986 100644 --- a/komorebi-recorder/src/analysis/events.rs +++ b/komorebi-recorder/src/analysis/events.rs @@ -20,7 +20,10 @@ //! that produced it is done by `blocks::pair`. Both read the events this module returns. use super::flavor::Rules; +use crate::session::Session; use crate::sources::komorebi_events::EventRow; +use color_eyre::eyre; +use color_eyre::eyre::WrapErr; use schemars::JsonSchema; use serde::Serialize; use serde_json::Value; @@ -234,3 +237,100 @@ impl EventRecord { } } } + +/// Returns every event of a session, in the order they were received, with the warnings from +/// reading them. +/// +/// The events are the lines of the session's `events.jsonl`, read with `rules` and sorted by +/// `recv_mach_ns`, then by `seq`. A session with no `events.jsonl` has no events, which is not an +/// error. A line that is not a valid row (as opposed to a row whose notification could not be +/// parsed, which is kept as an unreadable event) is skipped, and the warnings say how many were: +/// `N unreadable lines of events.jsonl were skipped`. Blank lines are ignored silently. +/// +/// # Errors +/// +/// Returns an error if `events.jsonl` exists and cannot be read: `could not read `, with +/// the I/O error as its cause. A missing file is not one of those cases. +/// +/// # Example +/// +/// Reading a session needs a session directory on disk, so this example is only compiled. It is +/// covered by `loading_sorts_by_receipt_and_skips_what_it_cannot_read` in this module's tests. +/// +/// ```rust,no_run +/// use komorebi_recorder::analysis::events; +/// use komorebi_recorder::analysis::flavor::Flavor; +/// use komorebi_recorder::session::Session; +/// +/// let session = Session::open("/path/to/session")?; +/// let (records, warnings) = events::load(&session, Flavor::Macos.rules())?; +/// for record in &records { +/// println!("#{} {}", record.seq, record.info.summary()); +/// } +/// assert!(warnings.is_empty()); +/// # Ok::<(), Box>(()) +/// ``` +pub fn load(session: &Session, rules: &dyn Rules) -> eyre::Result<(Vec, Vec)> { + let path = session.path("events.jsonl"); + let text = match std::fs::read_to_string(&path) { + Ok(text) => text, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + return Ok((Vec::new(), Vec::new())); + } + Err(error) => { + return Err(error).wrap_err_with(|| format!("could not read {}", path.display())); + } + }; + + let mut records = Vec::new(); + let mut skipped = 0_usize; + for line in text.lines().filter(|line| !line.trim().is_empty()) { + match serde_json::from_str::(line) { + Ok(row) => records.push(EventRecord::from_row(&row, rules)), + Err(_) => skipped += 1, + } + } + + records.sort_by_key(|record| (record.recv_mach_ns, record.seq)); + let warnings = if skipped > 0 { + vec![format!( + "{skipped} unreadable lines of events.jsonl were skipped" + )] + } else { + Vec::new() + }; + Ok((records, warnings)) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::analysis::flavor::Flavor; + + #[test] + fn loading_sorts_by_receipt_and_skips_what_it_cannot_read() { + let dir = + std::env::temp_dir().join(format!("komorebi-recorder-events-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + let session = Session::create(Some(dir.clone()), chrono::Utc::now()).expect("create"); + std::fs::write( + session.path("events.jsonl"), + concat!( + "{\"seq\":2,\"recv_wall_us\":0,\"recv_mach_ns\":20,\"event\":{\"type\":\"Retile\"}}\n", + "garbage\n", + "{\"seq\":1,\"recv_wall_us\":0,\"recv_mach_ns\":10,\"state_id\":4}\n", + ), + ) + .expect("events"); + + let (records, warnings) = load(&session, Flavor::Macos.rules()).expect("load"); + assert_eq!( + records.iter().map(|record| record.seq).collect::>(), + [1, 2] + ); + assert_eq!(records[0].state_id, Some(4)); + assert_eq!(records[0].info.family, Family::Unknown); + assert_eq!(records[1].info.name, "Retile"); + assert_eq!(warnings.len(), 1); + } +} diff --git a/komorebi-recorder/src/analysis/flavor/mod.rs b/komorebi-recorder/src/analysis/flavor/mod.rs index a4ea7a19..e7fab16a 100644 --- a/komorebi-recorder/src/analysis/flavor/mod.rs +++ b/komorebi-recorder/src/analysis/flavor/mod.rs @@ -484,6 +484,15 @@ pub trait Rules: Sync { mod tests { use super::*; + #[test] + fn a_session_with_no_flavor_recorded_is_komorebi_for_mac() { + let info: crate::session::KomorebiInfo = serde_json::from_str( + r#"{"running":false,"pid":null,"observed_levels":[],"data_dir":""}"#, + ) + .expect("an old manifest's komorebi section"); + assert_eq!(info.flavor, Flavor::Macos); + } + #[test] fn flavors_are_spelled_in_lowercase_and_the_host_has_one() { assert_eq!( diff --git a/komorebi-recorder/src/lib.rs b/komorebi-recorder/src/lib.rs index 3fc0f631..b6fed000 100644 --- a/komorebi-recorder/src/lib.rs +++ b/komorebi-recorder/src/lib.rs @@ -47,6 +47,7 @@ //! | [`incidents`] | what happened to the recording itself, as a log of its own | //! | [`lock`] | telling a running recorder from one that died | //! | [`sources`] | the sources that write raw files into the session | +//! | [`session`] | the session directory and its manifest | //! //! # What is not supported //! @@ -65,5 +66,6 @@ pub mod incidents; pub mod komorebi_link; pub mod lock; pub mod platform; +pub mod session; pub mod sources; pub mod timecode; diff --git a/komorebi-recorder/src/platform/macos/apps.rs b/komorebi-recorder/src/platform/macos/apps.rs new file mode 100644 index 00000000..c5a62530 --- /dev/null +++ b/komorebi-recorder/src/platform/macos/apps.rs @@ -0,0 +1,95 @@ +//! Which process owns a window id, from the window server. +//! +//! [`window_owners`] calls `CGWindowListCopyWindowInfo(OptionAll, ...)`. `OptionAll` matters: +//! komorebi's own wrapper only lists on-screen windows, which would miss every window on another +//! space. +//! +//! The same function exists on Windows, where it enumerates top-level windows and a window id is a +//! window handle; see [`window_owners`] for how they differ. + +use crate::sources::managed_apps::WindowOwner; +use objc2_core_foundation::CFArray; +use objc2_core_foundation::CFDictionary; +use objc2_core_foundation::CFNumber; +use objc2_core_foundation::CFString; +use objc2_core_graphics::CGWindowListCopyWindowInfo; +use objc2_core_graphics::CGWindowListOption; +use objc2_core_graphics::kCGNullWindowID; +use objc2_core_graphics::kCGWindowLayer; +use objc2_core_graphics::kCGWindowNumber; +use objc2_core_graphics::kCGWindowOwnerName; +use objc2_core_graphics::kCGWindowOwnerPID; +use std::collections::HashMap; +use std::ptr::NonNull; + +fn dictionary_value(dictionary: &CFDictionary, key: &CFString) -> Option> { + // SAFETY: `key` is a valid CFString and the dictionary is live + let value = unsafe { CFDictionary::value(dictionary, NonNull::from(key).as_ptr().cast()) }; + NonNull::new(value.cast_mut()).map(NonNull::cast) +} + +/// Returns every window the window server knows about (all spaces, on-screen or not), keyed by +/// window id, with the process that owns each. +/// +/// The key is the window server's window number, which is what komorebi for Mac calls a window's +/// `id`. Each [`WindowOwner`] has the owning process id (`kCGWindowOwnerPID`), the owner's name +/// (`kCGWindowOwnerName`, empty if the window server gave none) and the window's layer +/// (`kCGWindowLayer`, `0` for an ordinary application window). A window with no number or no owning +/// process id is left out. The map is empty if the window server cannot be asked, as in a sandboxed +/// build with no window server. +/// +/// # Host differences +/// +/// On Windows the keys are window handles (`HWND` values), the name is the owning program's file +/// name without `.exe`, and the layer is always `0`. On a host that can only investigate a session +/// the map is always empty. +/// +/// This asks the machine it runs on, so it has no doctest. It is covered by +/// `window_server_listing_works` in the unit tests of `crate::sources::managed_apps`. +#[must_use] +pub fn window_owners() -> HashMap { + let mut owners = HashMap::new(); + let Some(list) = CGWindowListCopyWindowInfo(CGWindowListOption::OptionAll, kCGNullWindowID) + else { + return owners; + }; + + let list: &CFArray = &list; + for index in 0..list.count() { + // SAFETY: every element of the window list is a CFDictionary, and `index` is in bounds + let Some(dictionary) = + (unsafe { list.value_at_index(index).cast::().as_ref() }) + else { + continue; + }; + + // SAFETY: values under these keys have these types per the CGWindow documentation + let (number, pid, name, layer) = unsafe { + ( + dictionary_value::(dictionary, kCGWindowNumber) + .and_then(|number| number.as_ref().as_i64()), + dictionary_value::(dictionary, kCGWindowOwnerPID) + .and_then(|pid| pid.as_ref().as_i32()), + dictionary_value::(dictionary, kCGWindowOwnerName) + .map(|name| name.as_ref().to_string()), + dictionary_value::(dictionary, kCGWindowLayer) + .and_then(|layer| layer.as_ref().as_i64()), + ) + }; + + if let (Some(number), Some(pid)) = (number, pid) + && let Ok(number) = u32::try_from(number) + { + owners.insert( + number, + WindowOwner { + pid, + name: name.unwrap_or_default(), + layer: layer.unwrap_or_default(), + }, + ); + } + } + + owners +} diff --git a/komorebi-recorder/src/platform/macos/mod.rs b/komorebi-recorder/src/platform/macos/mod.rs index 89dd8331..cc43b9cc 100644 --- a/komorebi-recorder/src/platform/macos/mod.rs +++ b/komorebi-recorder/src/platform/macos/mod.rs @@ -14,7 +14,9 @@ //! Nothing here is public API except through the facade: this module is private, and the facade //! re-exports its submodules under the same names on every host. +pub mod apps; pub mod clock; +pub mod process; pub mod shell; /// Does nothing: a Mac needs nothing done once at the start of `main`. (Windows makes the process diff --git a/komorebi-recorder/src/platform/macos/process.rs b/komorebi-recorder/src/platform/macos/process.rs new file mode 100644 index 00000000..f0902661 --- /dev/null +++ b/komorebi-recorder/src/platform/macos/process.rs @@ -0,0 +1,58 @@ +//! Starting and stopping child processes the way macOS wants it. +//! +//! The recorder runs `log stream` children (`crate::sources::oslog`) and, from the recorder window, +//! the viewer. [`isolate`] starts one so that a terminal's Ctrl-C reaches only the recorder, +//! [`terminate`] asks it to stop and [`was_terminated`] tells a child that was asked to stop from +//! one that failed. The same three functions exist on Windows, where the means differ. + +use std::process::Child; +use std::process::Command; +use std::process::ExitStatus; + +/// Puts the child in its own process group, so a terminal Ctrl-C reaches only the recorder, which +/// can then drain and stop these children in order instead of losing their tail. +/// +/// This must be called before the child is spawned. It returns `command` for chaining. On Windows +/// the child also gets no console window of its own. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::platform::process::{isolate, terminate, was_terminated}; +/// use std::process::Command; +/// +/// let mut command = Command::new("sleep"); +/// command.arg("30"); +/// let mut child = isolate(&mut command).spawn()?; +/// +/// // asked to stop with SIGTERM, which `was_terminated` recognizes +/// terminate(&mut child); +/// let status = child.wait()?; +/// assert!(!status.success()); +/// assert!(was_terminated(&status)); +/// # Ok::<(), Box>(()) +/// ``` +pub fn isolate(command: &mut Command) -> &mut Command { + std::os::unix::process::CommandExt::process_group(command, 0) +} + +/// Asks a child to stop, as politely as the OS allows (`SIGTERM`), so it flushes what it buffered. +/// +/// This only sends the signal: it does not wait for the child, so the caller must `wait` for it, +/// and does not report a failure to signal it. On Windows there is no polite signal, and the child +/// is killed. +pub fn terminate(child: &mut Child) { + // SAFETY: signalling a child process we spawned and still own + unsafe { + libc::kill(child.id() as i32, libc::SIGTERM); + } +} + +/// Returns `true` if and only if the child ended because [`terminate`] asked it to (it was +/// killed by `SIGTERM`), which is not a failure. +/// +/// On Windows this is always `false`: Windows reports no signal, so it cannot tell. +#[must_use] +pub fn was_terminated(status: &ExitStatus) -> bool { + std::os::unix::process::ExitStatusExt::signal(status) == Some(libc::SIGTERM) +} diff --git a/komorebi-recorder/src/platform/mod.rs b/komorebi-recorder/src/platform/mod.rs index 0f1ebf38..ed39d858 100644 --- a/komorebi-recorder/src/platform/mod.rs +++ b/komorebi-recorder/src/platform/mod.rs @@ -7,6 +7,8 @@ //! |---|---| //! | [`clock`] | the master monotonic clock and its tick size | //! | [`shell`] | the OS version, and (for the recorder window) showing a folder and asking for one | +//! | [`apps`] | which process owns a window id | +//! | [`process`] | stopping a child process | //! //! A third host, `unsupported`, builds on anything else so that the investigation commands (which //! only read a session directory) still work on a Linux agent box; recording there says so. @@ -42,7 +44,9 @@ mod win; #[cfg(windows)] use win as imp; +pub use imp::apps; pub use imp::clock; +pub use imp::process; pub use imp::shell; /// Things the OS wants done once, first thing in `main`: on Windows, becoming DPI aware so that diff --git a/komorebi-recorder/src/platform/unsupported.rs b/komorebi-recorder/src/platform/unsupported.rs index 28f79691..b23f88f5 100644 --- a/komorebi-recorder/src/platform/unsupported.rs +++ b/komorebi-recorder/src/platform/unsupported.rs @@ -4,6 +4,18 @@ /// Nothing to do first. pub fn init() {} +/// Which process owns a window: nothing is known on this host. +pub mod apps { + use crate::sources::managed_apps::WindowOwner; + use std::collections::HashMap; + + /// Returns no windows: this host has no window server to ask. + #[must_use] + pub fn window_owners() -> HashMap { + HashMap::new() + } +} + /// The master clock, which here is Rust's monotonic [`Instant`]. pub mod clock { use crate::clock::Timebase; @@ -35,6 +47,29 @@ pub mod clock { } } +/// Starting and stopping child processes, with nothing host-specific to do. +pub mod process { + use std::process::Child; + use std::process::Command; + use std::process::ExitStatus; + + /// Returns `command` as it is: there is nothing to isolate it with. + pub fn isolate(command: &mut Command) -> &mut Command { + command + } + + /// Kills `child`. + pub fn terminate(child: &mut Child) { + let _ = child.kill(); + } + + /// Returns `false`: this host reports no signal. + #[must_use] + pub fn was_terminated(_status: &ExitStatus) -> bool { + false + } +} + /// Showing a folder, asking for one, and naming the OS, with what this host can offer. pub mod shell { use std::path::Path; diff --git a/komorebi-recorder/src/platform/win/apps.rs b/komorebi-recorder/src/platform/win/apps.rs new file mode 100644 index 00000000..bc170c9b --- /dev/null +++ b/komorebi-recorder/src/platform/win/apps.rs @@ -0,0 +1,102 @@ +//! Which process owns a window id: `GetWindowThreadProcessId` on its handle. +//! +//! komorebi for Windows identifies a window by its handle, so unlike on macOS the window list is +//! only needed to find out who owns each handle and what that process is called. [`window_owners`] +//! is the same function that macOS provides. + +use crate::sources::managed_apps::WindowOwner; +use std::collections::HashMap; +use windows::Win32::Foundation::CloseHandle; +use windows::Win32::Foundation::HWND; +use windows::Win32::Foundation::LPARAM; +use windows::Win32::System::Threading::OpenProcess; +use windows::Win32::System::Threading::PROCESS_NAME_WIN32; +use windows::Win32::System::Threading::PROCESS_QUERY_LIMITED_INFORMATION; +use windows::Win32::System::Threading::QueryFullProcessImageNameW; +use windows::Win32::UI::WindowsAndMessaging::EnumWindows; +use windows::Win32::UI::WindowsAndMessaging::GetWindowThreadProcessId; +use windows::core::BOOL; +use windows::core::PWSTR; + +/// The file name of the program a process is running, without `.exe`. +pub(crate) fn process_name(pid: u32) -> Option { + // SAFETY: the handle is closed again, and the buffer outlives the call that fills it + unsafe { + let process = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, false, pid).ok()?; + let mut buffer = [0_u16; 1024]; + let mut length = buffer.len() as u32; + let queried = QueryFullProcessImageNameW( + process, + PROCESS_NAME_WIN32, + PWSTR(buffer.as_mut_ptr()), + &raw mut length, + ); + let _ = CloseHandle(process); + queried.ok()?; + + let path = String::from_utf16_lossy(&buffer[..length as usize]); + let file = path.rsplit(['\\', '/']).next()?; + Some( + file.strip_suffix(".exe") + .or_else(|| file.strip_suffix(".EXE")) + .unwrap_or(file) + .to_string(), + ) + } +} + +unsafe extern "system" fn collect(window: HWND, found: LPARAM) -> BOOL { + // SAFETY: `found` is the address of the vector `window_owners` passed to `EnumWindows` + let found = unsafe { &mut *(found.0 as *mut Vec<(u32, u32)>) }; + let mut pid = 0_u32; + // SAFETY: `window` is a handle `EnumWindows` just gave us + let thread = unsafe { GetWindowThreadProcessId(window, Some(&raw mut pid)) }; + if thread != 0 && pid != 0 { + // a window handle is a 32-bit value even in a 64-bit process + found.push((window.0 as usize as u32, pid)); + } + + BOOL(1) +} + +/// Returns every top-level window that `EnumWindows` reports, keyed by its handle, with the process +/// that owns each. +/// +/// The key is the window handle (`HWND`) as a `u32`: a handle holds a 32-bit value even in a +/// 64-bit process, and it is the number komorebi for Windows calls a window's `hwnd`. Each +/// [`WindowOwner`] has the owning process id (`0` if it does not fit in an `i32`), the program's +/// file name without `.exe` (empty if the process cannot be opened for a query) and the layer, +/// which is always `0`. A window whose owner cannot be found is left out. The program's name is +/// looked up once for each process. +/// +/// # Host differences +/// +/// On macOS the keys are the window server's window numbers, the name is the owner name the window +/// server gives, the layer is the window's real layer, and windows on other spaces are included. +/// +/// This asks the machine it runs on, so it has no doctest; nothing tests it automatically. +#[must_use] +pub fn window_owners() -> HashMap { + let mut found: Vec<(u32, u32)> = Vec::new(); + // SAFETY: `found` outlives the call and `collect` only touches it during it + let _ = unsafe { EnumWindows(Some(collect), LPARAM(&raw mut found as isize)) }; + + let mut names: HashMap = HashMap::new(); + found + .into_iter() + .map(|(handle, pid)| { + let name = names + .entry(pid) + .or_insert_with(|| process_name(pid).unwrap_or_default()) + .clone(); + ( + handle, + WindowOwner { + pid: i32::try_from(pid).unwrap_or(0), + name, + layer: 0, + }, + ) + }) + .collect() +} diff --git a/komorebi-recorder/src/platform/win/mod.rs b/komorebi-recorder/src/platform/win/mod.rs index bffd4cbe..1c946bfe 100644 --- a/komorebi-recorder/src/platform/win/mod.rs +++ b/komorebi-recorder/src/platform/win/mod.rs @@ -21,7 +21,9 @@ //! `just check-windows`, and the checklist for running it on a real machine is //! `docs/dev/windows-checkpoints.md`. +pub mod apps; pub mod clock; +pub mod process; pub mod shell; /// Does what Windows needs once, first thing in `main`: makes the process per-monitor DPI aware diff --git a/komorebi-recorder/src/platform/win/process.rs b/komorebi-recorder/src/platform/win/process.rs new file mode 100644 index 00000000..1c49c698 --- /dev/null +++ b/komorebi-recorder/src/platform/win/process.rs @@ -0,0 +1,43 @@ +//! Starting and stopping child processes the way Windows wants it. +//! +//! The recorder window launches the viewer, and ffmpeg is run for some video work. [`isolate`] +//! starts a child so that a terminal's Ctrl-C reaches only the recorder and no console window +//! flashes, [`terminate`] stops it and [`was_terminated`] tells a child that was stopped from one +//! that failed. The same three functions exist on macOS, where a child can be asked to stop. + +use std::os::windows::process::CommandExt; +use std::process::Child; +use std::process::Command; +use std::process::ExitStatus; + +const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200; +const CREATE_NO_WINDOW: u32 = 0x0800_0000; + +/// Starts the child in its own process group, so a terminal Ctrl-C reaches only the recorder, and +/// without a console window of its own, so that the recorder window launching `ffmpeg` does not +/// flash one. +/// +/// This must be called before the child is spawned (it sets the creation flags +/// `CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW`, replacing any set before). It returns `command` +/// for chaining. +pub fn isolate(command: &mut Command) -> &mut Command { + command.creation_flags(CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW) +} + +/// Stops a child, without giving it a chance to flush. +/// +/// Windows has no polite signal for a process without a window, so this is `TerminateProcess`: +/// whatever the child had buffered is lost. A failure to stop it is not reported. On macOS the +/// child is sent `SIGTERM` and can flush. +pub fn terminate(child: &mut Child) { + let _ = child.kill(); +} + +/// Returns `true` if and only if the child ended because [`terminate`] asked it to. +/// +/// Windows reports no signal, so this cannot tell, and always returns `false`. On macOS it is +/// `true` for a child that was stopped by the signal [`terminate`] sends. +#[must_use] +pub fn was_terminated(_status: &ExitStatus) -> bool { + false +} diff --git a/komorebi-recorder/src/session.rs b/komorebi-recorder/src/session.rs new file mode 100644 index 00000000..11250b9f --- /dev/null +++ b/komorebi-recorder/src/session.rs @@ -0,0 +1,738 @@ +//! The on-disk session directory and its manifest (`session.json`). +//! +//! Raw data is never duplicated or rewritten: `timeline.jsonl` only *references* byte ranges in +//! the raw files, so streams stay separate and can be reconciled or re-indexed later. + +use crate::analysis::flavor::Flavor; +use crate::clock::Anchor; +use crate::clock::Timebase; +use crate::platform::Host; +use crate::sources::komorebi_events::EventSummary; +use crate::sources::komorebi_log::DetectedLevel; +use crate::sources::komorebi_log::LogSegment; +use crate::sources::komorebi_version::KomorebiVersion; +use crate::sources::managed_apps::AppRecord; +use chrono::DateTime; +use chrono::Utc; +use color_eyre::eyre; +use color_eyre::eyre::WrapErr; +use serde::Deserialize; +use serde::Serialize; +#[cfg(test)] +use serde_json::Value; +use std::path::Path; +use std::path::PathBuf; + +/// The version of the manifest format this build writes and the newest it reads. [`Session::manifest`] refuses a +/// manifest with a greater one. +pub const SCHEMA_VERSION: u32 = 1; + +/// The recorder is (or died while) recording; the manifest is a checkpoint. +pub const STATUS_RECORDING: &str = "recording"; +/// Stopped normally and fully indexed. +pub const STATUS_COMPLETE: &str = "complete"; +/// The recorder died; `reindex` rebuilt the session from what was on disk. +pub const STATUS_RECOVERED: &str = "recovered"; + +fn complete_status() -> String { + STATUS_COMPLETE.to_string() +} +/// The name of the manifest in a session's directory. +pub const MANIFEST_FILE: &str = "session.json"; +/// The name of the time-sorted index of every record in a session. It points into the raw files, which it never +/// replaces, so it can be rebuilt from them. +pub const TIMELINE_FILE: &str = "timeline.jsonl"; + +/// A point in time on both clocks. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub struct Moment { + /// Nanoseconds on the master clock. + /// + pub mach_ns: u64, + /// Microseconds since the Unix epoch on the wall clock, read together with `mach_ns`. + pub wall_us: i64, +} + +impl Moment { + #[must_use] + /// Returns the current time on both clocks, read together as one [`Anchor`]. + pub fn now() -> Self { + let anchor = Anchor::sample(); + Self { + mach_ns: anchor.mach_ns, + wall_us: anchor.wall_us, + } + } +} + +/// What the recorder knew about komorebi: which one it was, whether and as which process it ran, and how it was +/// logging. +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +pub struct KomorebiInfo { + /// Which komorebi this was: they differ in what their events and log say. Sessions from + /// before this was recorded were all of komorebi for Mac. + #[serde(default)] + pub flavor: Flavor, + /// Whether a komorebi process was found, when the recording started or later in it. + pub running: bool, + /// The komorebi process seen most recently, if any. + pub pid: Option, + /// Every komorebi process seen during the recording, in order (it can be restarted). + #[serde(default)] + pub pids: Vec, + /// The log level komorebi was running at, and how that was found out, for the process in `pid`. + pub log_level: Option, + /// Which komorebi each of `pids` was, as its binary reported: what a log line means depends on + /// the source it was built from. + #[serde(default)] + pub versions: Vec, + /// The name this recorder registered as with komorebi; komorebi's DEBUG log names it when it + /// pushes each notification, which ties an event to its handler exactly. + #[serde(default)] + pub subscriber: Option, + /// Levels that actually appear in the recorded slice of komorebi's log. + pub observed_levels: Vec, + /// komorebi's data directory, where its sockets are. + pub data_dir: String, + /// The directory komorebi's plaintext log was read from, where that is not `data_dir` (komorebi + /// for Windows logs into the temp directory). + #[serde(default, skip_serializing_if = "Option::is_none")] + pub log_dir: Option, +} + +/// The outcome of the self-test that checks the video against the clocks. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct Calibration { + /// How the readings were taken. + pub method: String, + /// The readings the result is computed from. + pub samples: Vec, + /// The largest absolute error among the samples, in milliseconds. + pub max_abs_error_ms: f64, + /// The largest error that still passes, in milliseconds. + pub tolerance_ms: f64, + /// Whether there were samples and `max_abs_error_ms` is within `tolerance_ms`. + pub passed: bool, +} + +/// One reading of the on-screen clock: where in the video it was taken, and what the clock showed against what the +/// session predicted. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct CalibrationSample { + /// Where in the video the reading was taken, in seconds. + pub video_s: f64, + /// The master-clock time the session predicts for that moment, at millisecond resolution. + pub predicted_mach_ns: u64, + /// The master-clock time the on-screen clock showed in that frame, at millisecond resolution. + pub observed_mach_ns: u64, + /// Observed minus predicted, in milliseconds, wrapped to the period of the on-screen clock. + pub error_ms: f64, +} + +/// The manifest of a session (`session.json`): everything the other files in the directory need to be read, and the +/// summary of what the recording was. +/// +/// A manifest is written when a recording starts and rewritten at checkpoints while it runs, so one with `status` +/// [`STATUS_RECORDING`] is either a recording in progress or one whose recorder died. [`Manifest::host`] says what it was +/// recorded on, and `komorebi.flavor` which komorebi it recorded. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::clock::Anchor; +/// use komorebi_recorder::session::Manifest; +/// use komorebi_recorder::session::Moment; +/// +/// let anchor = Anchor::sample(); +/// let start = Moment { mach_ns: anchor.mach_ns, wall_us: anchor.wall_us }; +/// let manifest = Manifest::new(start, vec![anchor]); +/// +/// // the first frame was captured a second after the recording started +/// let mut manifest = manifest; +/// manifest.video_t0_mach_ns = Some(start.mach_ns + 1_000_000_000); +/// assert_eq!(manifest.video_seconds(start.mach_ns + 3_500_000_000), 2.5); +/// assert_eq!(manifest.mach_at_video_seconds(2.5), start.mach_ns + 3_500_000_000); +/// ``` +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct Manifest { + /// The version of this format ([`SCHEMA_VERSION`]) the manifest was written with. + pub schema_version: u32, + /// `recording`, `complete` or `recovered`. + #[serde(default = "complete_status")] + pub status: String, + /// The version of `komorebi-recorder` that wrote the session. + pub recorder_version: String, + /// What the session was recorded on. Absent in sessions from before Windows support, which + /// were all recorded on a Mac: use [`Manifest::host`], which knows that. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub host: Option, + /// The macOS version of a Mac host. Superseded by `host.os_version`; still written on a Mac so + /// that older builds of the tool read the session, and read from sessions that only have it. + #[serde(default)] + pub macos_version: Option, + /// The komorebi that was recorded. + pub komorebi: KomorebiInfo, + /// What one tick of the host clock is worth (`numer / denom` nanoseconds). + pub timebase: Timebase, + /// Paired readings of the wall and master clocks taken while recording, which map komorebi's log lines onto the + /// master clock (see [`crate::clock::ClockMap`]). + pub anchors: Vec, + /// When the recording started. + pub start: Moment, + /// When the recording stopped, if it did: `None` while it runs and in a session whose recorder died before + /// `reindex` recovered it. + pub stop: Option, + /// Session video t=0 on the mach clock: the earliest first frame across displays. + pub video_t0_mach_ns: Option, + /// When video capture was stopped on the mach clock. + pub video_end_mach_ns: Option, + /// The byte ranges of komorebi's log that were recorded, which together make `komorebi.log`. + pub log_segments: Vec, + /// The applications that own windows komorebi manages, which each get an OS trace stream of their own on a Mac. + pub apps: Vec, + /// What was recorded of komorebi's subscriber events. + pub events: EventSummary, + /// `host-clock` when frame timestamps were verified to be on the mach clock. + pub sync_quality: String, + /// The result of `selftest`, if it was run on this session. + pub calibration: Option, + /// Things the recorder wants the reader to know about the recording, in words. + pub warnings: Vec, +} + +impl Manifest { + #[must_use] + /// Returns the manifest of a recording that has just started, on this host: its host and komorebi flavor are the + /// ones this process runs on, its status is [`STATUS_RECORDING`] and it has nothing recorded yet. + pub fn new(start: Moment, anchors: Vec) -> Self { + let host = Host::current(); + Self { + schema_version: SCHEMA_VERSION, + status: STATUS_RECORDING.to_string(), + recorder_version: env!("CARGO_PKG_VERSION").to_string(), + macos_version: host.is_macos().then(|| host.os_version.clone()).flatten(), + host: Some(host), + komorebi: KomorebiInfo { + flavor: Flavor::of_host(), + ..KomorebiInfo::default() + }, + timebase: crate::clock::timebase(), + anchors, + start, + stop: None, + video_t0_mach_ns: None, + video_end_mach_ns: None, + log_segments: Vec::new(), + apps: Vec::new(), + events: EventSummary::default(), + sync_quality: "host-clock".to_string(), + calibration: None, + warnings: Vec::new(), + } + } + + /// What this session was recorded on. + #[must_use] + pub fn host(&self) -> Host { + self.host + .clone() + .unwrap_or_else(|| Host::legacy_macos(self.macos_version.clone())) + } + + /// The master clock value that is `t = 0` in video time. Falls back to the recording start if + /// no frame was ever captured, so timelines remain usable for the non-video sources. + #[must_use] + pub fn video_t0(&self) -> u64 { + self.video_t0_mach_ns.unwrap_or(self.start.mach_ns) + } + + #[must_use] + /// Returns the video time, in seconds, of a master-clock time. It is negative before the first frame. + pub fn video_seconds(&self, mach_ns: u64) -> f64 { + (i128::from(mach_ns) - i128::from(self.video_t0())) as f64 / 1e9 + } + + #[must_use] + /// Returns the master-clock time of `video_s` seconds into the video, which is zero for a time before the clock + /// started. + pub fn mach_at_video_seconds(&self, video_s: f64) -> u64 { + let ns = i128::from(self.video_t0()) + (video_s * 1e9).round() as i128; + ns.max(0) as u64 + } + + /// The span of video time covered by the recording, `(0, duration)`. The end is the moment + /// video capture stopped (frames are variable-rate, so the last frame can be earlier). + #[must_use] + pub fn video_span(&self) -> (f64, f64) { + let end = self + .video_end_mach_ns + .or(self.stop.map(|stop| stop.mach_ns)) + .map_or(0.0, |end| self.video_seconds(end)); + + (0.0, end.max(0.0)) + } +} + +/// A session directory on disk. +#[derive(Debug, Clone)] +pub struct Session { + /// The directory the session is in. + pub dir: PathBuf, +} + +/// The default parent of session directories: komorebi's data dir, under `recordings/`. +#[must_use] +pub fn default_recordings_dir() -> PathBuf { + crate::komorebi_link::data_dir().join("recordings") +} + +impl Session { + /// Creates a fresh session directory: `base` if given, otherwise + /// `/recordings//`. + /// + /// # Errors + /// + /// Returns an error if the directory already contains a session, or cannot be created. + pub fn create(base: Option, now: DateTime) -> eyre::Result { + let dir = base.unwrap_or_else(|| { + default_recordings_dir().join(now.format("%Y%m%dT%H%M%SZ").to_string()) + }); + + if dir.join(MANIFEST_FILE).exists() { + eyre::bail!( + "{} already contains a session; choose a different --out", + dir.display() + ); + } + + for sub in ["oslog/apps", "states"] { + std::fs::create_dir_all(dir.join(sub)) + .wrap_err_with(|| format!("could not create {}", dir.join(sub).display()))?; + } + + Ok(Self { dir }) + } + + /// Opens the session in `dir`. + /// + /// # Errors + /// + /// Returns an error if `dir` has no manifest: it is not a session. + pub fn open(dir: impl Into) -> eyre::Result { + let dir = dir.into(); + if !dir.join(MANIFEST_FILE).is_file() { + eyre::bail!( + "{} is not a recording session (no {MANIFEST_FILE})", + dir.display() + ); + } + + Ok(Self { dir }) + } + + #[must_use] + /// Returns `relative` inside the session's directory. + pub fn path(&self, relative: impl AsRef) -> PathBuf { + self.dir.join(relative) + } + + /// Reads the session's manifest. + /// + /// # Errors + /// + /// Returns an error if the manifest cannot be read, is not a valid manifest, or was written by a newer + /// `komorebi-recorder` than this one ([`SCHEMA_VERSION`] is greater than what this build reads). + pub fn manifest(&self) -> eyre::Result { + let path = self.path(MANIFEST_FILE); + let text = std::fs::read_to_string(&path) + .wrap_err_with(|| format!("could not read {}", path.display()))?; + let manifest: Manifest = serde_json::from_str(&text) + .wrap_err_with(|| format!("{} is not a valid session manifest", path.display()))?; + + if manifest.schema_version > SCHEMA_VERSION { + eyre::bail!( + "{} was written by a newer komorebi-recorder (schema {}, this build reads up to {})", + path.display(), + manifest.schema_version, + SCHEMA_VERSION + ); + } + + Ok(manifest) + } + + /// Writes the manifest. It is written to a temporary file and renamed over the old one, so a reader or a crash never + /// sees a half-written manifest. + /// + /// # Errors + /// + /// Returns an error if the manifest cannot be serialized or the files cannot be written. + pub fn write_manifest(&self, manifest: &Manifest) -> eyre::Result<()> { + let path = self.path(MANIFEST_FILE); + let temporary = self.path(format!("{MANIFEST_FILE}.tmp")); + std::fs::write(&temporary, serde_json::to_string_pretty(manifest)?)?; + // rename so a reader (or a crash) never sees a half-written manifest + std::fs::rename(&temporary, &path)?; + Ok(()) + } + + /// Writes the generated `README.md` for this session (see [`readme`]). + /// + /// # Errors + /// + /// Returns an error if the file cannot be written. + pub fn write_readme(&self, manifest: &Manifest) -> eyre::Result<()> { + std::fs::write(self.path("README.md"), readme(&self.dir, manifest))?; + Ok(()) + } +} + +/// The generated `README.md`: what every file is and the exact commands to query this session. +#[must_use] +pub fn readme(dir: &Path, manifest: &Manifest) -> String { + let session = shell_quote(&dir.display().to_string()); + let host = manifest.host(); + let (_, duration) = manifest.video_span(); + let mut out = String::new(); + + out.push_str("# komorebi-recorder session\n\n"); + out.push_str(&format!( + "Recorded with komorebi-recorder {} on {}.\nVideo duration: about {:.1}s. Video time `00:00.000` is the first captured frame.\n\n", + manifest.recorder_version, + manifest.host().describe(), + duration + )); + + out.push_str("## Investigating a bug\n\n"); + out.push_str(&format!( + "Start with what the user marked and described, then what the recording shows around it:\n\n\ + ```sh\n\ + komorebi-recorder brief {session}\n\ + komorebi-recorder guide # how to investigate, step by step\n\ + komorebi-recorder view {session} # the same, in a window you can play and scrub\n\ + ```\n\n\ + Every command takes `--json`. `annotate` adds a bug region (a start, an end and what is wrong)\n\ + to `annotations.jsonl`; `state`, `diff`, `events`, `trace`, `window`, `code`, `search`,\n\ + `changes` and `sheet` dig in.\n\n" + )); + + out.push_str("## How to read it\n\n"); + out.push_str( + "Every second of video maps to the exact records from every other source. Use the\n\ + `komorebi-recorder` CLI from this binary (this directory is self-contained):\n\n", + ); + out.push_str(&format!( + "```sh\n\ + # what happened around 12.5s into the video? (komorebi log + events + OS trace, +-1s)\n\ + komorebi-recorder at {session} 12.5 --window 1s\n\ + # narrow to one app's OS trace, or one source\n\ + komorebi-recorder at {session} 00:12.500 --app Ghostty\n\ + komorebi-recorder at {session} 12.5 --source events\n\ + # a span\n\ + komorebi-recorder range {session} 10 15\n\ + # a per-second digest of the whole recording\n\ + komorebi-recorder summary {session}\n\ + # reverse: a log line / event / UTC time -> video timecode\n\ + komorebi-recorder locate {session} --log-line 120\n\ + komorebi-recorder locate {session} --event-seq 7\n\ + komorebi-recorder locate {session} --utc 2026-10-26T19:43:35.062613Z\n\ + # extract PNG frames to look at (needs ffmpeg)\n\ + komorebi-recorder frames {session} 12.5 14.0\n\ + # rebuild timeline.jsonl from the raw files\n\ + komorebi-recorder reindex {session}\n\ + ```\n\n\ + Add `--json` to any query for machine-readable output.\n\n" + )); + + out.push_str("## Files\n\n"); + out.push_str("| File | What it is |\n|---|---|\n"); + out.push_str("| `session.json` | Manifest: versions, displays, clock anchors, log segments, OS-trace streams and apps, warnings |\n"); + out.push_str("| `video-[-].mp4` | Screen recording of one display. Variable frame rate: frames only exist when the screen changed. A display that was unplugged, whose stream stopped, or that changed resolution has several numbered segments, each a complete file; `session.json` lists every segment with its time span |\n"); + out.push_str("| `frames-[-].csv` | Every frame's host-clock timestamp (`pts_mach_ns`) and when it was received |\n"); + out.push_str("| `annotations.jsonl` | Bug regions (a start, an end and what is wrong), notes and findings, appended by the viewer and `annotate`. Never rewritten |\n"); + out.push_str("| `recorder.jsonl` | What happened to the recording environment: displays connected/disconnected, sleep/wake, screen lock, restarts of log streams or komorebi. Shown as the `recorder` source |\n"); + out.push_str("| `komorebi.log` | The exact byte slice of komorebi's own log for this recording (UTC timestamps) |\n"); + out.push_str("| `events.jsonl` | Every komorebi subscriber notification: `{seq, recv_wall_us, recv_mach_ns, event, state_id}` |\n"); + out.push_str("| `states/.json` | Full komorebi `State`, stored only when it changed (referenced by `state_id`) |\n"); + out.push_str( + "| `state-start.json`, `state-end.json` | `State` when recording started / stopped |\n", + ); + out.push_str(os_trace_rows(&host)); + out.push_str("| `timeline.jsonl` | Merged index of every record, sorted by time, pointing into the raw files |\n\n"); + + out.push_str("## Gaps are expected\n\n"); + out.push_str( + "Docking, undocking, sleep, wake and screen lock change what can be recorded. The recorder keeps\n\ + going through all of them: a display that disappears has its video finalized on the spot and a new\n\ + segment starts when it returns, and a `log stream` or komorebi that goes away is picked up again.\n\ + Whatever happened is in `recorder.jsonl` (`komorebi-recorder at