feat(session): the session directory

A session is a directory and its manifest, `session.json`: the host, the
komorebi flavor, the clock anchors, the log segments and the applications seen,
written atomically. komorebi's own log is recorded as the exact byte range
written while recording (`%TEMP%` on Windows, its data directory on a Mac),
together with the version of the komorebi that wrote it. A generated README in
each session says what every file is, quoting paths the way the host's shell
reads them.
This commit is contained in:
LGUG2Z committed 2026-10-27 22:22:56 -07:00
1 parent c748237741
commit 4724d831ba
22 files changed
+4668 -1

No files matched your search

Generated
+205
View File
@@ -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"
+15 -1
View File
@@ -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"
]
]
]
+14
View File
@@ -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 |
+20
View File
@@ -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"
+100
View File
@@ -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 <path>`, 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<dyn std::error::Error>>(())
/// ```
pub fn load(session: &Session, rules: &dyn Rules) -> eyre::Result<(Vec<EventRecord>, Vec<String>)> {
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::<EventRow>(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::<Vec<_>>(),
[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);
}
}
@@ -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!(
+2
View File
@@ -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;
@@ -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<T>(dictionary: &CFDictionary, key: &CFString) -> Option<NonNull<T>> {
// 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<u32, WindowOwner> {
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::<CFDictionary>().as_ref() })
else {
continue;
};
// SAFETY: values under these keys have these types per the CGWindow documentation
let (number, pid, name, layer) = unsafe {
(
dictionary_value::<CFNumber>(dictionary, kCGWindowNumber)
.and_then(|number| number.as_ref().as_i64()),
dictionary_value::<CFNumber>(dictionary, kCGWindowOwnerPID)
.and_then(|pid| pid.as_ref().as_i32()),
dictionary_value::<CFString>(dictionary, kCGWindowOwnerName)
.map(|name| name.as_ref().to_string()),
dictionary_value::<CFNumber>(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
}
@@ -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
@@ -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<dyn std::error::Error>>(())
/// ```
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)
}
+4
View File
@@ -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
@@ -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<u32, WindowOwner> {
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;
+102
View File
@@ -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<String> {
// 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<u32, WindowOwner> {
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<u32, String> = 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()
}
@@ -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
@@ -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
}
+738
View File
@@ -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<i32>,
/// Every komorebi process seen during the recording, in order (it can be restarted).
#[serde(default)]
pub pids: Vec<i32>,
/// The log level komorebi was running at, and how that was found out, for the process in `pid`.
pub log_level: Option<DetectedLevel>,
/// 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<KomorebiVersion>,
/// 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<String>,
/// Levels that actually appear in the recorded slice of komorebi's log.
pub observed_levels: Vec<String>,
/// 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<String>,
}
/// 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<CalibrationSample>,
/// 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<Host>,
/// 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<String>,
/// 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<Anchor>,
/// 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<Moment>,
/// Session video t=0 on the mach clock: the earliest first frame across displays.
pub video_t0_mach_ns: Option<u64>,
/// When video capture was stopped on the mach clock.
pub video_end_mach_ns: Option<u64>,
/// The byte ranges of komorebi's log that were recorded, which together make `komorebi.log`.
pub log_segments: Vec<LogSegment>,
/// The applications that own windows komorebi manages, which each get an OS trace stream of their own on a Mac.
pub apps: Vec<AppRecord>,
/// 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<Calibration>,
/// Things the recorder wants the reader to know about the recording, in words.
pub warnings: Vec<String>,
}
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<Anchor>) -> 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
/// `<komorebi data dir>/recordings/<YYYYmmddTHHMMSSZ>/`.
///
/// # Errors
///
/// Returns an error if the directory already contains a session, or cannot be created.
pub fn create(base: Option<PathBuf>, now: DateTime<Utc>) -> eyre::Result<Self> {
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<PathBuf>) -> eyre::Result<Self> {
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<Path>) -> 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<Manifest> {
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-<displayID>[-<n>].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-<displayID>[-<n>].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/<id>.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 <session> <time> --source recorder`).\n",
);
out.push_str(if host.is_windows() {
"Whether the host clock counts the time a machine sleeps is measured, not assumed: `recorder.jsonl`\n\
says for each sleep how long it was by the wall clock and how far the host clock moved.\n\n"
} else {
"While the machine sleeps the host clock pauses, so video time skips the sleep rather than showing\n\
a gap.\n\n"
});
if manifest.status != STATUS_COMPLETE {
out.push_str("## This session was recovered\n\n");
out.push_str(
"The recorder did not finish normally. Everything that had been written was kept (video is\n\
fragmented so it plays up to the last fragment) and `reindex` rebuilt this session from it.\n\
The end of the recording is approximate and a second or two of video may be missing.\n\n",
);
}
out.push_str("## Clocks\n\n");
out.push_str(if host.is_windows() {
"The master clock is the host performance counter (`QueryPerformanceCounter`, ns). Video frame\n\
timestamps are on it directly, and the OS trace's records carry it as `hostNs`."
} else {
"The master clock is the host monotonic clock (`mach_absolute_time`, ns). Video frame\n\
timestamps and the unified log's `machTimestamp` are on it directly."
});
out.push_str(
" komorebi's log lines\n\
(UTC wall clock) are mapped onto it with the `anchors` in `session.json`. Subscriber events\n\
are stamped on receipt, and komorebi sends them after handling the event, so a stamp is when\n\
the handler *finished*; the start of the handler is in `komorebi.log` (`komorebi-recorder trace`\n\
ties the two together).\n\n",
);
if !manifest.warnings.is_empty() {
out.push_str("## Warnings recorded\n\n");
for warning in &manifest.warnings {
out.push_str(&format!("- {warning}\n"));
}
out.push('\n');
}
out.push_str("## Privacy\n\n");
out.push_str(if host.is_windows() {
"The video contains whatever was on screen, and komorebi's events, state and log contain window\n\
titles and program names. Review this directory before sharing it.\n"
} else {
"The video contains whatever was on screen, and application logs can contain window titles\n\
and URLs. Review this directory before sharing it. `<private>` values in the OS log are\n\
redacted by macOS (no sudo or SIP changes are made by this tool).\n"
});
out
}
/// The OS trace files a session of this host has, as rows of the README's table of files.
fn os_trace_rows(host: &Host) -> &'static str {
if host.is_windows() {
"| `oslog/system.ndjson` | What the OS told komorebi: Windows' WinEvents for every top-level window (shown, hidden, cloaked, focused, moved, renamed, destroyed), repeated moves folded together |\n\
| `oslog/eventlog.ndjson` | The System Event Log: warnings, errors, and the providers that talk about displays, power and the GPU |\n"
} else {
"| `oslog/komorebi.ndjson` | macOS unified log for the komorebi process (system frameworks as the daemon sees them) |\n\
| `oslog/system.ndjson` | macOS unified log: accessibility / HIServices / workspace subsystems |\n\
| `oslog/apps/<exe>-<pid>.ndjson` | macOS unified log for one managed application process |\n"
}
}
/// `value` as one argument to a shell: left alone if it needs no quoting, else in the quotes this
/// machine's shells understand (single quotes in a unix shell and `PowerShell`, which cmd.exe does not
/// read, so double quotes where the host is Windows).
fn shell_quote(value: &str) -> String {
quote_for(cfg!(windows), value)
}
fn quote_for(windows: bool, value: &str) -> String {
let plain = |c: char| {
c.is_ascii_alphanumeric()
|| matches!(c, '/' | '.' | '-' | '_' | ':' | '+')
|| (windows && c == '\\')
};
if value.chars().all(plain) {
value.to_string()
} else if windows {
format!("\"{}\"", value.replace('"', "\\\""))
} else {
format!("'{}'", value.replace('\'', "'\\''"))
}
}
#[cfg(test)]
mod tests {
use super::*;
use chrono::TimeZone;
fn manifest() -> Manifest {
let start = Moment {
mach_ns: 1_000_000_000_000,
wall_us: 1_800_000_000_000_000,
};
Manifest::new(
start,
vec![Anchor {
wall_us: start.wall_us,
mach_ns: start.mach_ns,
}],
)
}
#[test]
fn paths_are_quoted_the_way_the_hosts_shell_reads_them() {
assert_eq!(quote_for(false, "/tmp/a b"), "'/tmp/a b'");
assert_eq!(quote_for(false, "it's"), r"'it'\''s'");
assert_eq!(quote_for(false, "/tmp/plain"), "/tmp/plain");
// cmd.exe does not read single quotes; both it and PowerShell read double ones
assert_eq!(
quote_for(true, r"C:\Users\me\komorebi"),
r"C:\Users\me\komorebi"
);
assert_eq!(
quote_for(true, r"C:\Users\Jane Doe\x"),
r#""C:\Users\Jane Doe\x""#
);
}
#[test]
fn the_readme_describes_the_os_trace_the_hosts_session_has() {
let mut manifest = manifest();
manifest.host = Some(Host {
os: "windows".to_string(),
arch: "x86_64".to_string(),
os_version: Some("10.0.26100".to_string()),
clock: crate::platform::ClockKind::Qpc,
});
let text = readme(Path::new("/tmp/s"), &manifest);
assert!(text.contains("oslog/eventlog.ndjson"));
assert!(text.contains("QueryPerformanceCounter"));
assert!(!text.contains("unified log"), "{text}");
let mac = readme(Path::new("/tmp/s"), &self::tests::manifest());
assert!(mac.contains("macOS unified log"));
}
#[test]
fn a_manifest_from_before_hosts_were_recorded_was_recorded_on_a_mac() {
let mut value = serde_json::to_value(manifest()).expect("serialize");
let object = value.as_object_mut().expect("object");
object.remove("host");
object.insert("macos_version".into(), "26.0".into());
let old: Manifest = serde_json::from_value(value).expect("an old manifest parses");
let host = old.host();
assert!(host.is_macos());
assert_eq!(host.os_version.as_deref(), Some("26.0"));
assert_eq!(host.clock, crate::platform::ClockKind::Mach);
}
#[test]
fn a_new_manifest_records_the_host_it_was_made_on() {
let host = manifest().host();
assert_eq!(host.os, std::env::consts::OS);
assert_eq!(host.clock, crate::platform::clock::KIND);
}
#[test]
fn video_time_is_relative_to_the_first_frame() {
let mut manifest = manifest();
manifest.video_t0_mach_ns = Some(1_002_000_000_000);
assert!((manifest.video_seconds(1_004_500_000_000) - 2.5).abs() < 1e-9);
assert!((manifest.video_seconds(1_001_000_000_000) + 1.0).abs() < 1e-9);
assert_eq!(manifest.mach_at_video_seconds(2.5), 1_004_500_000_000);
}
#[test]
fn video_time_falls_back_to_the_recording_start() {
let manifest = manifest();
assert_eq!(manifest.video_t0(), 1_000_000_000_000);
}
#[test]
fn manifests_roundtrip_through_json() {
let manifest = manifest();
let text = serde_json::to_string_pretty(&manifest).expect("serialize");
let back: Manifest = serde_json::from_str(&text).expect("parse");
assert_eq!(back, manifest);
}
#[test]
fn creates_opens_and_refuses_to_overwrite_a_session() {
let base =
std::env::temp_dir().join(format!("komorebi-recorder-session-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&base);
let now = Utc
.with_ymd_and_hms(2026, 10, 26, 19, 43, 35)
.single()
.expect("time");
let session = Session::create(Some(base.clone()), now).expect("create");
assert!(session.path("oslog/apps").is_dir());
assert!(session.path("states").is_dir());
assert!(Session::open(&base).is_err(), "no manifest yet");
session.write_manifest(&manifest()).expect("write");
assert!(!session.path("session.json.tmp").exists());
assert_eq!(
Session::open(&base)
.expect("open")
.manifest()
.expect("manifest"),
manifest()
);
assert!(
Session::create(Some(base), now).is_err(),
"must not clobber a session"
);
}
#[test]
fn rejects_manifests_from_the_future() {
let base =
std::env::temp_dir().join(format!("komorebi-recorder-future-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&base);
let session = Session::create(Some(base), Utc::now()).expect("create");
let mut future = manifest();
future.schema_version = SCHEMA_VERSION + 1;
session.write_manifest(&future).expect("write");
let error = session.manifest().expect_err("too new").to_string();
assert!(error.contains("newer komorebi-recorder"), "{error}");
}
#[test]
fn the_readme_embeds_the_session_path_and_every_query() {
let text = readme(Path::new("/tmp/a b/session"), &manifest());
assert!(
text.contains("'/tmp/a b/session'"),
"paths with spaces are quoted"
);
for command in [
"at ", "range ", "summary ", "locate ", "frames ", "reindex ", "brief ", "guide",
] {
assert!(
text.contains(&format!("komorebi-recorder {command}")),
"{command}"
);
}
}
#[test]
fn manifests_from_before_segments_and_status_existed_still_load() {
// exactly the shape a pre-segment recorder wrote: no `status`, no segment fields
let mut value = serde_json::to_value(manifest()).expect("value");
let object = value.as_object_mut().expect("object");
object.remove("status");
object.remove("video_end_mach_ns");
object
.get_mut("komorebi")
.and_then(Value::as_object_mut)
.expect("komorebi")
.remove("pids");
let old: Manifest = serde_json::from_value(value).expect("an old manifest parses");
assert_eq!(
old.status, STATUS_COMPLETE,
"an old manifest was a finished recording"
);
assert!(old.komorebi.pids.is_empty());
}
}
@@ -486,6 +486,14 @@ fn write_loop(
let event = value.get_mut("event").map(Value::take);
let state = value.get_mut("state").map(Value::take);
if let Some(pid) = event
.as_ref()
.and_then(crate::sources::managed_apps::event_pid)
&& let Some(discovery) = discovery
{
let _ = discovery.send(Discovery::Pid(pid));
}
if let Some(state) = state
&& previous_state.as_ref() != Some(&state)
{
@@ -0,0 +1,1000 @@
//! Slicing komorebi's own `tracing` log for the duration of a recording.
//!
//! komorebi writes `komorebi_plaintext.log.<YYYY-MM-DD>` rolled daily at **UTC** midnight, so a
//! recording can span two files. komorebi for Mac writes it into its data directory; komorebi for
//! Windows writes it into the temp directory (its README names `%LOCALAPPDATA%`, but its code uses
//! the temp directory), so [`find_log_dir`] looks in both. Despite the name the text is not
//! entirely free of ANSI escape codes: they remain inside the fields of a span
//! (`focus_window{idx=0}`), so readers strip them before parsing. Line prefixes are RFC 3339 UTC
//! timestamps with microsecond precision. The recorder snapshots a byte offset when recording
//! starts ([`snapshot_start`]) and copies exactly the bytes written after it ([`LogTailer`]), so
//! multi-line panics and backtraces (which carry no timestamp of their own) are preserved.
//!
//! # The file written
//!
//! `komorebi.log` in the session directory ([`slice_path`]) is the slice: the bytes komorebi wrote
//! to its log while the recording ran, copied unchanged and in order, across a UTC midnight
//! included. It is plain text in komorebi's `tracing_subscriber::fmt` layout, one event per line:
//!
//! ```text
//! 2026-10-26T00:07:14.370960Z INFO process_event: komorebi::process_event: processing event
//! ```
//!
//! Lines that carry no timestamp (a panic message, the frames of a backtrace) belong to the
//! timestamped line before them; [`index_lines`] gives them that line's time.
//!
//! Which bytes of which rolled file make up the slice is recorded in the manifest
//! (`session.json`, key `log_segments`) as [`LogSegment`]s. The directory they were read from is
//! `komorebi.log_dir` in the manifest when it is not komorebi's data directory.
//!
//! # What is not guaranteed
//!
//! - The slice holds only what komorebi's log level let it write. The recorder never changes that
//! level; [`level_warning`] says when it is too quiet to explain a bug.
//! - A late write to an earlier day's file, made after the next day's file has begun to be
//! copied, is dropped (see [`LogTailer`]).
//!
//! The recorder runs this on both hosts. The only host-dependent part is where the log is looked
//! for ([`log_dir_candidates`], chosen by the [`Flavor`] of the komorebi that is running).
use crate::analysis::flavor::Flavor;
use chrono::DateTime;
use chrono::Duration;
use chrono::NaiveDate;
use chrono::Utc;
use color_eyre::eyre;
use color_eyre::eyre::WrapErr;
use serde::Deserialize;
use serde::Serialize;
use std::collections::BTreeSet;
use std::fs::File;
use std::io::Read;
use std::io::Seek;
use std::io::SeekFrom;
use std::io::Write;
use std::path::Path;
use std::path::PathBuf;
/// The file name prefix of komorebi's plaintext log: the file for a day is `<prefix>.<YYYY-MM-DD>`.
pub const PLAINTEXT_PREFIX: &str = "komorebi_plaintext.log";
/// Returns the file name of the log that tracing's daily roller writes for a given UTC date.
///
/// # Example
///
/// ```rust
/// use chrono::NaiveDate;
/// use komorebi_recorder::sources::komorebi_log::log_file_name;
///
/// let date = NaiveDate::from_ymd_opt(2026, 10, 27).ok_or("not a date")?;
/// assert_eq!(log_file_name(date), "komorebi_plaintext.log.2026-10-27");
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn log_file_name(date: NaiveDate) -> String {
format!("{PLAINTEXT_PREFIX}.{}", date.format("%Y-%m-%d"))
}
/// Returns the directories the komorebi of this flavor may keep its log in, most likely first.
///
/// | flavor | candidates |
/// |---|---|
/// | [`Flavor::Macos`] | `data_dir` |
/// | [`Flavor::Windows`] | `temp_dir`, then `data_dir` |
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::analysis::flavor::Flavor;
/// use komorebi_recorder::sources::komorebi_log::log_dir_candidates;
/// use std::path::{Path, PathBuf};
///
/// let (data, temp) = (Path::new("/data"), Path::new("/temp"));
/// assert_eq!(log_dir_candidates(Flavor::Macos, data, temp), [PathBuf::from("/data")]);
/// assert_eq!(
/// log_dir_candidates(Flavor::Windows, data, temp),
/// [PathBuf::from("/temp"), PathBuf::from("/data")]
/// );
/// ```
#[must_use]
pub fn log_dir_candidates(flavor: Flavor, data_dir: &Path, temp_dir: &Path) -> Vec<PathBuf> {
match flavor {
Flavor::Macos => vec![data_dir.to_path_buf()],
Flavor::Windows => vec![temp_dir.to_path_buf(), data_dir.to_path_buf()],
}
}
fn has_komorebi_log(dir: &Path) -> bool {
std::fs::read_dir(dir).is_ok_and(|entries| {
entries.filter_map(Result::ok).any(|entry| {
entry
.file_name()
.to_string_lossy()
.starts_with(PLAINTEXT_PREFIX)
})
})
}
/// Returns the directory komorebi is logging into: the first of [`log_dir_candidates`] that has a
/// log in it, else the most likely one.
///
/// If there is none, komorebi may not have started yet, and will write its log in the most likely
/// directory when it does. A directory has a log in it if it holds any file whose name starts with
/// [`PLAINTEXT_PREFIX`]. A directory that cannot be read has none.
///
/// # Example
///
/// Where no candidate has a log, the answer is the first candidate, which is where komorebi for
/// Windows will write one:
///
/// ```rust
/// use komorebi_recorder::analysis::flavor::Flavor;
/// use komorebi_recorder::sources::komorebi_log::find_log_dir;
/// use std::path::{Path, PathBuf};
///
/// let dir = find_log_dir(
/// Flavor::Windows,
/// Path::new("/no/such/data-dir"),
/// Path::new("/no/such/temp-dir"),
/// );
/// assert_eq!(dir, PathBuf::from("/no/such/temp-dir"));
/// ```
///
/// The case where a log exists in either directory is covered by
/// `the_log_dir_is_where_a_log_is_else_the_likeliest_place` in this file's unit tests.
#[must_use]
pub fn find_log_dir(flavor: Flavor, data_dir: &Path, temp_dir: &Path) -> PathBuf {
let candidates = log_dir_candidates(flavor, data_dir, temp_dir);
candidates
.iter()
.find(|dir| has_komorebi_log(dir))
.or_else(|| candidates.first())
.cloned()
.unwrap_or_else(|| data_dir.to_path_buf())
}
/// Where in komorebi's log the recording started: the UTC date of the file komorebi was writing
/// and that file's length at that moment.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LogStart {
/// The UTC date of the rolled file that was being written (see [`log_file_name`]).
pub date: NaiveDate,
/// The length in bytes of that file when the recording started: the first byte of the slice.
/// `0` if the file did not exist yet.
pub offset: u64,
}
/// One contiguous byte range of one rolled log file, as the manifest (`log_segments`) records it.
///
/// The slice in `komorebi.log` is the segments' bytes one after the other, in date order.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::komorebi_log::LogSegment;
///
/// let segment = LogSegment {
/// file: "komorebi_plaintext.log.2026-10-26".to_string(),
/// start_offset: 7,
/// end_offset: 25,
/// out_offset: 0,
/// };
/// assert_eq!(segment.len(), 18);
/// assert!(!segment.is_empty());
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LogSegment {
/// The rolled file's name (see [`log_file_name`]), within the directory komorebi logs into.
/// That is komorebi's data directory unless the manifest's `komorebi.log_dir` says otherwise.
pub file: String,
/// The offset in that file of the segment's first byte.
pub start_offset: u64,
/// The offset in that file one past the segment's last byte: how far the file had been copied.
pub end_offset: u64,
/// Where this segment begins inside the session's `komorebi.log`.
pub out_offset: u64,
}
impl LogSegment {
/// Returns the number of bytes in the segment: `end_offset - start_offset`, or `0` if the
/// end is not after the start.
#[must_use]
pub fn len(&self) -> u64 {
self.end_offset.saturating_sub(self.start_offset)
}
/// Returns `true` if and only if the segment holds no bytes.
#[must_use]
pub fn is_empty(&self) -> bool {
self.len() == 0
}
}
fn file_len(path: &Path) -> u64 {
std::fs::metadata(path).map_or(0, |metadata| metadata.len())
}
/// Records the current end of today's (UTC) log file, where `now` says what today is.
///
/// The returned [`LogStart`] has the UTC date of `now` and the length of that day's file in `dir`,
/// or `0` if there is no such file yet.
///
/// # Example
///
/// ```rust
/// use chrono::{TimeZone, Utc};
/// use komorebi_recorder::sources::komorebi_log::snapshot_start;
/// use std::path::Path;
///
/// let now = Utc.with_ymd_and_hms(2026, 10, 27, 12, 0, 0).single().ok_or("not a time")?;
/// let start = snapshot_start(Path::new("/no/such/log-dir"), now);
/// assert_eq!(start.date.to_string(), "2026-10-27");
/// assert_eq!(start.offset, 0);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn snapshot_start(dir: &Path, now: DateTime<Utc>) -> LogStart {
let date = now.date_naive();
LogStart {
date,
offset: file_len(&dir.join(log_file_name(date))),
}
}
/// Works out which byte ranges of which files cover the log from `start` up to `end_now`,
/// including every whole file for any UTC dates in between.
///
/// The first file is read from `start.offset`; later ones from the beginning. A file that does not
/// exist (komorebi was not logging that day), or has nothing new in it, contributes no segment.
/// The segments are in date order and their `out_offset`s are cumulative, so they tile the slice.
/// Segments never start before `start.date`, even if `end_now` is earlier (the clock stepped back).
///
/// # Example
///
/// With no log, there is nothing to copy:
///
/// ```rust
/// use chrono::{TimeZone, Utc};
/// use komorebi_recorder::sources::komorebi_log::{plan_segments, snapshot_start};
/// use std::path::Path;
///
/// let dir = Path::new("/no/such/log-dir");
/// let begin = Utc.with_ymd_and_hms(2026, 10, 27, 12, 0, 0).single().ok_or("not a time")?;
/// let end = Utc.with_ymd_and_hms(2026, 10, 28, 1, 0, 0).single().ok_or("not a time")?;
/// let start = snapshot_start(dir, begin);
/// assert!(plan_segments(dir, &start, end).is_empty());
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
///
/// The cases with files, a recording that crosses a UTC midnight among them, are covered by
/// `follows_across_a_utc_midnight_rollover` and `a_missing_log_yields_no_segments_until_it_appears`
/// in this file's unit tests.
#[must_use]
pub fn plan_segments(dir: &Path, start: &LogStart, end_now: DateTime<Utc>) -> Vec<LogSegment> {
let end_date = end_now.date_naive().max(start.date);
let mut segments = Vec::new();
let mut date = start.date;
let mut out_offset = 0;
while date <= end_date {
let file = log_file_name(date);
let path = dir.join(&file);
let start_offset = if date == start.date { start.offset } else { 0 };
let end_offset = file_len(&path);
// a file that does not exist (komorebi was not logging that day) contributes nothing
if path.exists() && end_offset > start_offset {
let segment = LogSegment {
file,
start_offset,
end_offset,
out_offset,
};
out_offset += segment.len();
segments.push(segment);
}
date += Duration::days(1);
}
segments
}
/// Copies the recording's slice of komorebi's log into the session's `komorebi.log` as it grows,
/// instead of in one go at the end, so a crash loses at most the last moment of it.
///
/// Rolled files are followed in date order. Once a later day's file has begun to be copied,
/// earlier files are frozen: a straggling late write to yesterday's file cannot be appended
/// without scrambling the order of the slice, and it would be a handful of lines at most.
///
/// The tailer copies byte ranges, not lines, and only ever appends to `komorebi.log`. It never
/// reads komorebi's log before the offset in [`LogStart`].
///
/// # Example
///
/// Following a log takes komorebi's log files and a session directory, so this example only
/// compiles. The behavior is covered by these unit tests in this file: `follows_a_file_as_it_grows`,
/// `follows_across_a_utc_midnight_rollover`,
/// `a_straggling_write_to_yesterdays_file_does_not_scramble_the_slice` and
/// `a_missing_log_yields_no_segments_until_it_appears`.
///
/// ```rust,no_run
/// use chrono::Utc;
/// use komorebi_recorder::sources::komorebi_log::{LogTailer, slice_path, snapshot_start};
/// use std::path::Path;
///
/// let log_dir = Path::new("/path/to/komorebi/log-dir");
/// let session = Path::new("session");
///
/// let start = snapshot_start(log_dir, Utc::now());
/// let mut tailer = LogTailer::create(log_dir, start, &slice_path(session))?;
///
/// // ... on a timer while recording ...
/// let appended = tailer.sync(Utc::now())?;
/// println!("{appended} bytes of komorebi's log copied; {} segment(s)", tailer.segments().len());
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub struct LogTailer {
dir: PathBuf,
start: LogStart,
out: File,
out_len: u64,
segments: Vec<LogSegment>,
}
impl LogTailer {
/// Starts following the log in `dir` from `start`, writing the slice to `out`.
///
/// `out` is created, or truncated if it exists. Nothing is read from the log until the first
/// [`sync`](Self::sync).
///
/// # Errors
///
/// Returns an error if `out` cannot be created.
pub fn create(dir: &Path, start: LogStart, out: &Path) -> eyre::Result<Self> {
Ok(Self {
dir: dir.to_path_buf(),
start,
out: File::create(out)
.wrap_err_with(|| format!("could not create {}", out.display()))?,
out_len: 0,
segments: Vec::new(),
})
}
/// Copies whatever komorebi has written since the last sync, and returns the number of bytes
/// appended to `komorebi.log` (`0` if there was nothing new).
///
/// `now` decides which UTC dates' files are in play (see [`plan_segments`]). Every segment that
/// has bytes is flushed before this returns.
///
/// # Errors
///
/// Returns an error if a log file that is to be copied cannot be opened or read, or if
/// `komorebi.log` cannot be written or flushed.
pub fn sync(&mut self, now: DateTime<Utc>) -> eyre::Result<u64> {
let planned = plan_segments(&self.dir, &self.start, now);
let mut appended = 0;
for plan in planned {
let index = match self.segments.iter().position(|seg| seg.file == plan.file) {
Some(index) => index,
None => {
self.segments.push(LogSegment {
file: plan.file.clone(),
start_offset: plan.start_offset,
end_offset: plan.start_offset,
out_offset: self.out_len,
});
self.segments.len() - 1
}
};
// a later file is already being followed: this one is frozen
if index + 1 < self.segments.len() {
continue;
}
let copied_to = self.segments[index].end_offset;
if plan.end_offset <= copied_to {
continue;
}
let path = self.dir.join(&plan.file);
let mut file =
File::open(&path).wrap_err_with(|| format!("could not open {}", path.display()))?;
file.seek(SeekFrom::Start(copied_to))?;
let copied = std::io::copy(&mut file.take(plan.end_offset - copied_to), &mut self.out)?;
self.out.flush()?;
self.segments[index].end_offset = copied_to + copied;
self.out_len += copied;
appended += copied;
}
Ok(appended)
}
/// Returns what has been copied so far, as the segments the manifest records. Each segment's
/// `end_offset` is how far its file has been copied, not the file's current length.
#[must_use]
pub fn segments(&self) -> &[LogSegment] {
&self.segments
}
}
/// Parses the RFC 3339 timestamp that starts a log line, as UTC.
///
/// Returns `None` for a line that does not start with one: a continuation line (a panic message,
/// a backtrace frame) or anything else.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::komorebi_log::parse_timestamp;
///
/// let line = "2026-10-26T00:07:14.370960Z INFO process_event: komorebi::process_event: processing event";
/// let timestamp = parse_timestamp(line).ok_or("no timestamp")?;
/// assert_eq!(timestamp.to_rfc3339(), "2026-10-26T00:07:14.370960+00:00");
///
/// assert_eq!(parse_timestamp(" 0: backtrace::capture"), None);
/// assert_eq!(parse_timestamp("2026-10-26 00:07:14 not rfc3339"), None);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn parse_timestamp(line: &str) -> Option<DateTime<Utc>> {
let token = line.split_whitespace().next()?;
// cheap reject before the real parser: `YYYY-MM-DDT...`
if token.len() < 20
|| token.as_bytes().get(4) != Some(&b'-')
|| token.as_bytes().get(10) != Some(&b'T')
{
return None;
}
DateTime::parse_from_rfc3339(token)
.ok()
.map(|timestamp| timestamp.with_timezone(&Utc))
}
/// Returns the level token of a `tracing_subscriber::fmt` line: its second whitespace-separated
/// token, if that is one of `ERROR`, `WARN`, `INFO`, `DEBUG` or `TRACE`.
///
/// The line is not checked for a timestamp first; [`observed_levels`] does that.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::komorebi_log::parse_level;
///
/// let line = "2026-10-26T00:07:14.370960Z INFO process_event: komorebi::process_event: processing event";
/// assert_eq!(parse_level(line), Some("INFO"));
/// assert_eq!(parse_level(" 0: backtrace::capture"), None);
/// ```
#[must_use]
pub fn parse_level(line: &str) -> Option<&str> {
let level = line.split_whitespace().nth(1)?;
matches!(level, "ERROR" | "WARN" | "INFO" | "DEBUG" | "TRACE").then_some(level)
}
/// A single line of the slice with its place in the file and its (possibly inherited) time.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LogLine {
/// 1-based line number within the slice.
pub number: u64,
/// The byte offset of the line's first byte within the slice.
pub offset: u64,
/// The length of the line in bytes, including its line terminator.
pub len: u64,
/// The line's own timestamp, or the previous timestamped line's for continuation lines.
/// `None` for lines before the first timestamped one.
pub timestamp: Option<DateTime<Utc>>,
/// `true` if the line has no timestamp of its own.
pub is_continuation: bool,
}
/// Splits a slice into lines, giving continuation lines (panic messages, backtraces) the
/// timestamp of the line they follow.
///
/// The lines tile the slice: their lengths add up to its length. A final line with no terminator
/// is included.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::komorebi_log::index_lines;
///
/// let slice = "2026-10-26T00:00:01.000000Z ERROR komorebi: panicked\n 0: frame\n2026-10-26T00:00:02.000000Z INFO next\n";
/// let lines = index_lines(slice.as_bytes());
///
/// assert_eq!(lines.len(), 3);
/// assert!(lines[1].is_continuation);
/// assert_eq!(lines[1].timestamp, lines[0].timestamp, "inherited from the line it follows");
/// assert_ne!(lines[2].timestamp, lines[0].timestamp);
/// assert_eq!(lines.iter().map(|line| line.len).sum::<u64>(), slice.len() as u64);
/// ```
#[must_use]
pub fn index_lines(slice: &[u8]) -> Vec<LogLine> {
let mut lines = Vec::new();
let mut offset = 0_usize;
let mut current: Option<DateTime<Utc>> = None;
for (index, raw) in slice.split_inclusive(|byte| *byte == b'\n').enumerate() {
let number = index as u64 + 1;
let text = String::from_utf8_lossy(raw);
let own = parse_timestamp(&text);
let is_continuation = own.is_none();
if own.is_some() {
current = own;
}
lines.push(LogLine {
number,
offset: offset as u64,
len: raw.len() as u64,
timestamp: current,
is_continuation,
});
offset += raw.len();
}
lines
}
/// Returns the distinct levels that appear in a slice of log text, on lines that start with a
/// timestamp.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::komorebi_log::observed_levels;
///
/// let text = "2026-10-26T00:00:01.000000Z INFO a\n continuation\n2026-10-26T00:00:02.000000Z DEBUG b\n";
/// let levels: Vec<String> = observed_levels(text).into_iter().collect();
/// assert_eq!(levels, ["DEBUG", "INFO"]);
/// ```
#[must_use]
pub fn observed_levels(text: &str) -> BTreeSet<String> {
text.lines()
.filter(|line| parse_timestamp(line).is_some())
.filter_map(parse_level)
.map(str::to_string)
.collect()
}
/// How komorebi's log verbosity was determined, as the manifest (`komorebi.log_level`) records it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, schemars::JsonSchema)]
pub struct DetectedLevel {
/// The level, in lowercase: `error`, `warn`, `info`, `debug` or `trace`. When `RUST_LOG` is
/// set but names no level, its value as it is.
pub level: String,
/// Where the level came from: `RUST_LOG`, `--log-level` or `default`.
pub source: String,
}
/// Works out komorebi's log level from its command line and environment.
///
/// This mirrors the logic in `komorebi/src/main.rs`: `RUST_LOG` wins if it was already set,
/// otherwise `--log-level`, which defaults to `info`. `args` are komorebi's command-line arguments
/// and `environ` its environment as `KEY=VALUE` strings. Of a `RUST_LOG` such as
/// `info,komorebi=debug`, the most verbose level named by any of its comma-separated directives is
/// the level; directives that name no level are ignored.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::komorebi_log::level_from_process;
///
/// let args = ["komorebi".to_string(), "--log-level".to_string(), "info".to_string()];
///
/// // the flag, when the environment says nothing
/// let detected = level_from_process(&args, &[]);
/// assert_eq!((detected.level.as_str(), detected.source.as_str()), ("info", "--log-level"));
///
/// // RUST_LOG wins over the flag, and the most verbose directive wins within it
/// let environ = ["RUST_LOG=warn,komorebi=debug".to_string()];
/// let detected = level_from_process(&args, &environ);
/// assert_eq!((detected.level.as_str(), detected.source.as_str()), ("debug", "RUST_LOG"));
///
/// // neither: komorebi's default
/// assert_eq!(level_from_process(&["komorebi".to_string()], &[]).source, "default");
/// ```
#[must_use]
pub fn level_from_process(args: &[String], environ: &[String]) -> DetectedLevel {
if let Some(value) = environ
.iter()
.find_map(|entry| entry.strip_prefix("RUST_LOG="))
{
// directives look like `komorebi=trace` or `info,komorebi=debug`; the most verbose wins
let level = value
.split(',')
.filter_map(|directive| directive.rsplit('=').next())
.filter_map(normalize_level)
.max_by_key(|level| level_rank(level))
.map_or_else(|| value.to_string(), str::to_string);
return DetectedLevel {
level,
source: "RUST_LOG".to_string(),
};
}
let mut iter = args.iter();
while let Some(arg) = iter.next() {
let value = if let Some(value) = arg.strip_prefix("--log-level=") {
Some(value)
} else if arg == "--log-level" {
iter.next().map(String::as_str)
} else {
None
};
if let Some(level) = value.and_then(normalize_level) {
return DetectedLevel {
level: level.to_string(),
source: "--log-level".to_string(),
};
}
}
DetectedLevel {
level: "info".to_string(),
source: "default".to_string(),
}
}
fn normalize_level(level: &str) -> Option<&'static str> {
match level.to_ascii_lowercase().as_str() {
"error" => Some("error"),
"warn" => Some("warn"),
"info" => Some("info"),
"debug" => Some("debug"),
"trace" => Some("trace"),
_ => None,
}
}
fn level_rank(level: &str) -> u8 {
match level {
"error" => 0,
"warn" => 1,
"info" => 2,
"debug" => 3,
_ => 4,
}
}
/// Returns a user-facing warning if the level is too quiet to explain a bug: anything quieter
/// than `debug` (`error`, `warn` or `info`, in any case). A level that is not recognized gets none.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::komorebi_log::level_warning;
///
/// let warning = level_warning("info").ok_or("no warning")?;
/// assert!(warning.contains("--log-level trace"));
/// assert!(level_warning("debug").is_none());
/// assert!(level_warning("TRACE").is_none());
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn level_warning(level: &str) -> Option<String> {
(level_rank(&level.to_ascii_lowercase()) < level_rank("debug")).then(|| {
format!(
"komorebi is logging at {}; restart it with `--log-level trace` for full detail \
(the recorder never changes komorebi's log level itself)",
level.to_ascii_uppercase()
)
})
}
/// Returns the path of `komorebi.log` inside a session directory: the concatenated slice.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::komorebi_log::slice_path;
/// use std::path::Path;
///
/// assert_eq!(slice_path(Path::new("session")), Path::new("session/komorebi.log"));
/// ```
#[must_use]
pub fn slice_path(session_dir: &Path) -> PathBuf {
session_dir.join("komorebi.log")
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn komorebi_for_mac_logs_in_its_data_dir_and_komorebi_for_windows_in_temp() {
let (data, temp) = (Path::new("/data"), Path::new("/temp"));
assert_eq!(
log_dir_candidates(Flavor::Macos, data, temp),
[PathBuf::from("/data")]
);
assert_eq!(
log_dir_candidates(Flavor::Windows, data, temp),
[PathBuf::from("/temp"), PathBuf::from("/data")]
);
}
#[test]
fn the_log_dir_is_where_a_log_is_else_the_likeliest_place() {
let (data, temp) = (temp_dir("logdir-data"), temp_dir("logdir-temp"));
// nobody has logged yet: where komorebi for Windows will
assert_eq!(find_log_dir(Flavor::Windows, &data, &temp), temp);
// a log in the data dir (the README's old location) is found there
std::fs::write(data.join("komorebi_plaintext.log.2026-10-27"), "x").expect("log");
assert_eq!(find_log_dir(Flavor::Windows, &data, &temp), data);
// but temp wins when both have one: it is where the code writes
std::fs::write(temp.join("komorebi_plaintext.log.2026-10-27"), "x").expect("log");
assert_eq!(find_log_dir(Flavor::Windows, &data, &temp), temp);
// the Mac only ever looks in its data dir
assert_eq!(find_log_dir(Flavor::Macos, &data, &temp), data);
}
use chrono::TimeZone;
fn utc(y: i32, m: u32, d: u32, h: u32, min: u32, s: u32) -> DateTime<Utc> {
Utc.with_ymd_and_hms(y, m, d, h, min, s)
.single()
.expect("valid time")
}
fn temp_dir(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!(
"komorebi-recorder-test-{name}-{}",
std::process::id()
));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).expect("create temp dir");
dir
}
#[test]
fn parses_tracing_timestamps() {
let line = "2026-10-26T00:07:14.370960Z INFO process_event: komorebi::process_event: processing event";
let timestamp = parse_timestamp(line).expect("timestamp");
assert_eq!(
timestamp,
utc(2026, 10, 26, 0, 7, 14) + Duration::microseconds(370_960)
);
assert_eq!(timestamp.to_rfc3339(), "2026-10-26T00:07:14.370960+00:00");
assert_eq!(parse_level(line), Some("INFO"));
}
#[test]
fn rejects_non_timestamped_lines() {
for line in [
"",
" 0: backtrace::capture",
"thread 'main' panicked at src/lib.rs:1:1:",
"2026-10-26 00:07:14 not rfc3339",
] {
assert_eq!(parse_timestamp(line), None, "{line:?}");
}
}
#[test]
fn continuation_lines_inherit_the_previous_timestamp() {
let text = "2026-10-26T00:00:01.000000Z ERROR komorebi: panicked\n 0: frame\n 1: frame\n2026-10-26T00:00:02.000000Z INFO next\n";
let lines = index_lines(text.as_bytes());
assert_eq!(lines.len(), 4);
assert!(!lines[0].is_continuation);
assert!(lines[1].is_continuation && lines[2].is_continuation);
assert_eq!(lines[1].timestamp, lines[0].timestamp);
assert_eq!(lines[2].timestamp, lines[0].timestamp);
assert_ne!(lines[3].timestamp, lines[0].timestamp);
assert_eq!(lines[1].offset, lines[0].len);
assert_eq!(
lines.iter().map(|line| line.len).sum::<u64>(),
text.len() as u64
);
}
#[test]
fn leading_untimestamped_lines_have_no_time() {
let lines = index_lines(b"orphan\n2026-10-26T00:00:02.000000Z INFO x\n");
assert_eq!(lines[0].timestamp, None);
assert!(lines[1].timestamp.is_some());
}
fn slice_text(dir: &Path) -> String {
std::fs::read_to_string(dir.join("komorebi.log")).expect("slice")
}
#[test]
fn follows_a_file_as_it_grows() {
let dir = temp_dir("single");
let path = dir.join(log_file_name(utc(2026, 10, 26, 12, 0, 0).date_naive()));
std::fs::write(&path, "before\n").expect("write");
let start = snapshot_start(&dir, utc(2026, 10, 26, 12, 0, 0));
assert_eq!(start.offset, 7);
let mut tailer = LogTailer::create(&dir, start, &dir.join("komorebi.log")).expect("create");
assert_eq!(
tailer.sync(utc(2026, 10, 26, 12, 0, 1)).expect("sync"),
0,
"nothing new yet"
);
std::fs::write(&path, "before\nduring 1\n").expect("write");
assert_eq!(tailer.sync(utc(2026, 10, 26, 12, 0, 2)).expect("sync"), 9);
assert_eq!(
slice_text(&dir),
"during 1\n",
"what was already there is not part of the slice"
);
std::fs::write(&path, "before\nduring 1\nduring 2\n").expect("write");
tailer.sync(utc(2026, 10, 26, 12, 0, 3)).expect("sync");
tailer
.sync(utc(2026, 10, 26, 12, 0, 4))
.expect("sync again is a no-op");
assert_eq!(slice_text(&dir), "during 1\nduring 2\n");
let segments = tailer.segments();
assert_eq!(segments.len(), 1);
assert_eq!((segments[0].start_offset, segments[0].end_offset), (7, 25));
assert_eq!(segments[0].len(), 18);
}
#[test]
fn follows_across_a_utc_midnight_rollover() {
let dir = temp_dir("rollover");
let day1 = utc(2026, 10, 25, 23, 59, 50);
let day1_path = dir.join(log_file_name(day1.date_naive()));
let day2_path = dir.join(log_file_name(utc(2026, 10, 26, 0, 0, 0).date_naive()));
std::fs::write(&day1_path, "old line\n").expect("write");
let start = snapshot_start(&dir, day1);
let mut tailer = LogTailer::create(&dir, start, &dir.join("komorebi.log")).expect("create");
std::fs::write(&day1_path, "old line\nstart here\n").expect("write");
tailer.sync(utc(2026, 10, 25, 23, 59, 55)).expect("sync");
// komorebi appended to day 1, then rolled to day 2 at midnight UTC
std::fs::write(&day1_path, "old line\nstart here\nlast of day 1\n").expect("write");
std::fs::write(&day2_path, "first of day 2\n").expect("write");
tailer.sync(utc(2026, 10, 26, 0, 0, 1)).expect("sync");
std::fs::write(&day2_path, "first of day 2\nsecond of day 2\n").expect("write");
tailer.sync(utc(2026, 10, 26, 0, 0, 10)).expect("sync");
assert_eq!(
slice_text(&dir),
"start here\nlast of day 1\nfirst of day 2\nsecond of day 2\n"
);
let segments = tailer.segments();
assert_eq!(segments.len(), 2);
assert_eq!(segments[0].file, "komorebi_plaintext.log.2026-10-25");
assert_eq!(segments[1].file, "komorebi_plaintext.log.2026-10-26");
assert_eq!(segments[1].start_offset, 0);
assert_eq!(segments[1].out_offset, segments[0].len());
}
#[test]
fn a_straggling_write_to_yesterdays_file_does_not_scramble_the_slice() {
let dir = temp_dir("straggler");
let day1 = utc(2026, 10, 25, 23, 59, 50);
let day1_path = dir.join(log_file_name(day1.date_naive()));
let day2_path = dir.join(log_file_name(utc(2026, 10, 26, 0, 0, 0).date_naive()));
std::fs::write(&day1_path, "").expect("write");
let start = snapshot_start(&dir, day1);
let mut tailer = LogTailer::create(&dir, start, &dir.join("komorebi.log")).expect("create");
std::fs::write(&day1_path, "a\n").expect("write");
std::fs::write(&day2_path, "b\n").expect("write");
tailer.sync(utc(2026, 10, 26, 0, 0, 1)).expect("sync");
// a late flush lands in day 1 after day 2 was already being followed
std::fs::write(&day1_path, "a\nlate\n").expect("write");
std::fs::write(&day2_path, "b\nc\n").expect("write");
tailer.sync(utc(2026, 10, 26, 0, 0, 2)).expect("sync");
assert_eq!(
slice_text(&dir),
"a\nb\nc\n",
"the late line is dropped, the order is kept"
);
}
#[test]
fn a_missing_log_yields_no_segments_until_it_appears() {
let dir = temp_dir("missing");
let start = snapshot_start(&dir, utc(2026, 10, 26, 12, 0, 0));
assert_eq!(start.offset, 0);
assert!(plan_segments(&dir, &start, utc(2026, 10, 26, 12, 1, 0)).is_empty());
let mut tailer = LogTailer::create(&dir, start, &dir.join("komorebi.log")).expect("create");
assert_eq!(tailer.sync(utc(2026, 10, 26, 12, 0, 30)).expect("sync"), 0);
assert!(tailer.segments().is_empty());
// komorebi starts logging mid-recording
std::fs::write(
dir.join(log_file_name(utc(2026, 10, 26, 12, 0, 0).date_naive())),
"hello\n",
)
.expect("write");
tailer.sync(utc(2026, 10, 26, 12, 1, 0)).expect("sync");
assert_eq!(slice_text(&dir), "hello\n");
}
#[test]
fn detects_levels_from_the_command_line() {
let args = |list: &[&str]| {
list.iter()
.map(|arg| (*arg).to_string())
.collect::<Vec<_>>()
};
let none = args(&[]);
assert_eq!(
level_from_process(&args(&["komorebi"]), &none).level,
"info"
);
assert_eq!(
level_from_process(&args(&["komorebi", "--log-level", "trace"]), &none),
DetectedLevel {
level: "trace".into(),
source: "--log-level".into()
}
);
assert_eq!(
level_from_process(&args(&["komorebi", "--log-level=debug"]), &none).level,
"debug"
);
}
#[test]
fn rust_log_wins_over_the_flag() {
let args = vec![
"komorebi".to_string(),
"--log-level".to_string(),
"info".to_string(),
];
let environ = vec!["HOME=/x".to_string(), "RUST_LOG=komorebi=trace".to_string()];
let detected = level_from_process(&args, &environ);
assert_eq!(
detected,
DetectedLevel {
level: "trace".into(),
source: "RUST_LOG".into()
}
);
let environ = vec!["RUST_LOG=warn,komorebi=debug".to_string()];
assert_eq!(level_from_process(&args, &environ).level, "debug");
}
#[test]
fn warns_only_when_the_level_is_too_quiet() {
assert!(
level_warning("info")
.expect("warning")
.contains("--log-level trace")
);
assert!(level_warning("warn").is_some());
assert!(level_warning("debug").is_none());
assert!(level_warning("TRACE").is_none());
}
#[test]
fn observes_levels_in_a_slice() {
let text = "2026-10-26T00:00:01.000000Z INFO a\n continuation\n2026-10-26T00:00:02.000000Z DEBUG b\n";
let levels = observed_levels(text);
assert!(levels.contains("INFO") && levels.contains("DEBUG"));
assert_eq!(levels.len(), 2);
}
}
@@ -0,0 +1,252 @@
//! Which komorebi was running, so that what the log says can be tied to the right source.
//!
//! komorebi's log names no version and a user's installed binary is often not the checkout that
//! is being debugged. Mapping a log line to a line of source is only honest for the commit that
//! produced it, so the recorder asks the running binary what it is: `komorebi --version` prints
//!
//! ```text
//! komorebi 0.1.0
//! branch:master
//! commit_hash:0cc4ca7f67d79da0d59d603dde2f6b4445fec85b
//! ```
//!
//! [`parse`] reads that text and [`query`] runs the binary. The result is a [`KomorebiVersion`],
//! which the manifest (`session.json`) stores in `komorebi.versions`, one for each komorebi process
//! seen during the recording, in order. The analysis compares the recorded commit with the source
//! it indexes (`analysis::catalog`) to say whether a log line can be mapped to a line of source.
//! The same code runs for both flavors of komorebi, on both hosts.
use serde::Deserialize;
use serde::Serialize;
use std::path::Path;
use std::process::Command;
use std::process::Stdio;
use std::time::Duration;
use std::time::Instant;
/// A running komorebi's identity: which binary, and so which source, produced its log.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, schemars::JsonSchema)]
pub struct KomorebiVersion {
/// The process this was read from. `None` when the version was parsed from text alone.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub pid: Option<i32>,
/// The version number from the first line of the output, e.g. `0.1.0`.
pub version: String,
/// The git branch the binary was built from (the `branch:` line). `None` if the output has no
/// such line.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub branch: Option<String>,
/// The git commit the binary was built from (the `commit_hash:` line), as the binary prints
/// it: a full or an abbreviated hash. `None` if the output has no such line.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub commit: Option<String>,
}
impl KomorebiVersion {
/// Returns whether this binary was built from `commit` (full or abbreviated), or `None` when
/// that cannot be said.
///
/// The two hashes are compared over the length of the shorter. The answer is `None` if this
/// version has no commit, or if the shorter hash has fewer than 7 characters, which is too
/// short to tell commits apart.
///
/// # Panics
///
/// Panics if the shorter length (in bytes) is not a character boundary of the longer string.
/// A git hash is hexadecimal, so this cannot happen for one.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::komorebi_version::parse;
///
/// let version = parse("komorebi 0.1.0\nbranch:master\ncommit_hash:0cc4ca7f67d79da0d59d603dde2f6b4445fec85b\n")
/// .ok_or("not a version")?;
///
/// assert_eq!(version.is_commit("0cc4ca7"), Some(true), "an abbreviation of it");
/// assert_eq!(version.is_commit("bdf1045"), Some(false), "some other commit");
/// assert_eq!(version.is_commit("0cc"), None, "too short to say anything");
///
/// // a binary that prints no commit cannot be compared
/// let bare = parse("komorebi 0.1.0").ok_or("not a version")?;
/// assert_eq!(bare.is_commit("0cc4ca7"), None);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn is_commit(&self, commit: &str) -> Option<bool> {
let mine = self.commit.as_deref()?;
let shorter = mine.len().min(commit.len());
(shorter >= 7).then(|| mine[..shorter] == commit[..shorter])
}
}
/// Reads the output of `komorebi --version`.
///
/// Blank lines are skipped and each line is trimmed. The first remaining line must be `komorebi`
/// followed by the version number. After it, the `branch:` and `commit_hash:` lines are read;
/// any other line is ignored. Returns `None` if the output is not that of komorebi: it is empty,
/// its first line does not start with `komorebi ` (so `komorebic 0.1.0` is not accepted), or the
/// version is empty.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::komorebi_version::parse;
///
/// let version = parse("komorebi 0.1.0\nbranch:master\ncommit_hash:0cc4ca7f67d79da0d59d603dde2f6b4445fec85b\n")
/// .ok_or("not a version")?;
/// assert_eq!(version.version, "0.1.0");
/// assert_eq!(version.branch.as_deref(), Some("master"));
/// assert_eq!(version.commit.as_deref(), Some("0cc4ca7f67d79da0d59d603dde2f6b4445fec85b"));
/// assert_eq!(version.pid, None, "the text does not say which process printed it");
///
/// assert_eq!(parse("komorebic 0.1.0"), None);
/// assert_eq!(parse("error: unknown flag"), None);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn parse(text: &str) -> Option<KomorebiVersion> {
let mut lines = text.lines().map(str::trim).filter(|line| !line.is_empty());
let version = lines.next()?.strip_prefix("komorebi ")?.trim().to_string();
if version.is_empty() {
return None;
}
let mut found = KomorebiVersion {
pid: None,
version,
branch: None,
commit: None,
};
for line in lines {
if let Some(branch) = line.strip_prefix("branch:") {
found.branch = Some(branch.trim().to_string());
} else if let Some(commit) = line.strip_prefix("commit_hash:") {
found.commit = Some(commit.trim().to_string());
}
}
Some(found)
}
/// Asks the binary at `exe` what it is, by running it with `--version`, and reads the answer with
/// [`parse`]. `pid` is stored in the result as the process the binary is running as.
///
/// The binary answers at once; one that has not exited within two seconds is killed and `None` is
/// returned. `None` is also returned if the binary cannot be run or its output is not that of
/// komorebi. The binary's standard input is closed and its standard error is discarded.
///
/// # Example
///
/// A binary that is not there is `None`; the case of a binary that prints a version is covered by
/// `a_binary_that_prints_a_version_is_queried` in this file's unit tests (on unix hosts, where it
/// writes a script to run):
///
/// ```rust
/// use komorebi_recorder::sources::komorebi_version::query;
/// use std::path::Path;
///
/// assert_eq!(query(Path::new("/nonexistent/komorebi"), Some(42)), None);
/// ```
#[must_use]
pub fn query(exe: &Path, pid: Option<i32>) -> Option<KomorebiVersion> {
let mut child = Command::new(exe)
.arg("--version")
.stdin(Stdio::null())
.stdout(Stdio::piped())
.stderr(Stdio::null())
.spawn()
.ok()?;
let deadline = Instant::now() + Duration::from_secs(2);
loop {
match child.try_wait() {
Ok(Some(_)) => break,
Ok(None) if Instant::now() < deadline => {
std::thread::sleep(Duration::from_millis(10));
}
_ => {
let _ = child.kill();
let _ = child.wait();
return None;
}
}
}
let output = child.wait_with_output().ok()?;
let mut version = parse(&String::from_utf8_lossy(&output.stdout))?;
version.pid = pid;
Some(version)
}
#[cfg(test)]
mod tests {
use super::*;
const REAL: &str =
"komorebi 0.1.0\nbranch:master\ncommit_hash:0cc4ca7f67d79da0d59d603dde2f6b4445fec85b\n";
#[test]
fn the_real_output_is_read() {
let version = parse(REAL).expect("version");
assert_eq!(version.version, "0.1.0");
assert_eq!(version.branch.as_deref(), Some("master"));
assert_eq!(
version.commit.as_deref(),
Some("0cc4ca7f67d79da0d59d603dde2f6b4445fec85b")
);
}
#[test]
fn a_binary_that_says_less_is_still_a_version() {
let version = parse("komorebi 0.1.0").expect("version");
assert_eq!(version.commit, None);
assert_eq!(version.is_commit("0cc4ca7"), None);
}
#[test]
fn something_else_is_not_a_komorebi_version() {
for text in ["", "komorebi", "komorebic 0.1.0", "error: unknown flag"] {
assert_eq!(parse(text), None, "{text:?}");
}
}
#[test]
fn commits_compare_by_the_shorter_of_the_two() {
let version = parse(REAL).expect("version");
assert_eq!(version.is_commit("0cc4ca7"), Some(true));
assert_eq!(
version.is_commit("0cc4ca7f67d79da0d59d603dde2f6b4445fec85b"),
Some(true)
);
assert_eq!(version.is_commit("bdf1045"), Some(false));
// too short to say anything
assert_eq!(version.is_commit("0cc"), None);
}
#[test]
fn a_missing_binary_is_none() {
assert_eq!(query(Path::new("/nonexistent/komorebi"), None), None);
}
#[cfg(unix)]
#[test]
fn a_binary_that_prints_a_version_is_queried() {
use std::os::unix::fs::PermissionsExt;
let dir = std::env::temp_dir().join(format!("komorebi-version-{}", std::process::id()));
std::fs::create_dir_all(&dir).expect("dir");
let script = dir.join("komorebi");
std::fs::write(
&script,
"#!/bin/sh\nprintf 'komorebi 9.9.9\\nbranch:x\\ncommit_hash:abcdef1234567\\n'\n",
)
.expect("script");
std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).expect("chmod");
let version = query(&script, Some(42)).expect("version");
assert_eq!(version.version, "9.9.9");
assert_eq!(version.pid, Some(42));
assert_eq!(version.commit.as_deref(), Some("abcdef1234567"));
}
}
@@ -0,0 +1,825 @@
//! Finding out which processes komorebi is managing, so each one can get its own OS trace.
//!
//! komorebi's `State` JSON deliberately carries no process id: a `Window` serializes only its
//! `id`, `rect` and `details { title, exe, role, subrole, icon_path }`. So the recorder walks the
//! state generically for window ids and resolves id -> owning pid itself with the OS window list
//! (see [`crate::platform::apps`]; on macOS `CGWindowListCopyWindowInfo(OptionAll, ...)`, where
//! `OptionAll` matters because komorebi's own wrapper only lists on-screen windows, which would
//! miss everything on other workspaces and spaces).
//!
//! The steps, each a pure function except the window list:
//!
//! 1. [`collect_windows`] reads the windows out of a `State`.
//! 2. [`window_owners`] asks the OS which process owns each window id.
//! 3. [`resolve`] joins the two into [`ManagedApp`]s.
//! 4. An [`AppTracker`] folds what is found over the whole recording and reports each process once,
//! so the recorder starts one OS-trace stream per process.
//!
//! [`event_pid`] short-cuts this for a new process: a window manager event names the process id,
//! so the recorder need not wait for the next `State`. [`gui_app_pids`] finds every application
//! with a window, for the mode that traces all of them rather than only the managed ones.
//!
//! # Host and flavor
//!
//! The shapes read here are komorebi for Mac's: a window is an object with a numeric `id` and a
//! `details` object, and a window manager event carries the process id as `content[1]`. A
//! komorebi for Windows `State` holds windows as `{hwnd, title, exe, class, rect}` and its events
//! carry a window object instead of a process id, so on a Windows session [`collect_windows`] finds
//! no windows and [`event_pid`] returns `None`. Per-process traces exist only on macOS (the Windows
//! OS trace is one stream for every window, see `wintrace`), so nothing needs the result there.
use crate::clock;
use serde::Deserialize;
use serde::Serialize;
use serde_json::Value;
use std::collections::BTreeMap;
use std::collections::BTreeSet;
use std::collections::HashMap;
use std::collections::btree_map::Entry;
/// A window found in a komorebi `State`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StateWindow {
/// The window's `id` in the `State`: the same number the window server uses for it on a Mac.
pub id: u32,
/// `details.exe`: the application's name as komorebi reports it (`Slack`). `None` if the
/// window has none.
pub exe: Option<String>,
/// `details.title`. `None` if the window has none.
pub title: Option<String>,
}
/// Collects every window in a `State` without depending on its exact nesting.
///
/// Any object with a numeric `id` and a `details` object counts. Tiled containers, the monocle
/// container, a maximized window and floating windows are all found, and so are layouts that do
/// not exist yet.
///
/// Each window is returned once, in ascending order of `id`; a window that appears twice keeps the
/// first reading. An object whose `id` is not an integer that fits in `u32`, or that has no
/// `details` object, is not a window.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::managed_apps::collect_windows;
///
/// let state: serde_json::Value = serde_json::from_str(r#"{
/// "layout": {"deeply": {"nested": [
/// {"id": 1, "details": {"exe": "A", "title": "one"}},
/// {"monocle_container": {"windows": {"elements": [{"id": 2, "details": {"exe": "B"}}]}}},
/// {"maximized_window": {"id": 3, "details": {"exe": "C"}}},
/// {"id": "not-a-window-id", "details": {"exe": "D"}},
/// {"id": 4, "no_details": true}
/// ]}},
/// "floating_windows": {"elements": [{"id": 5, "details": {"exe": "E"}}]}
/// }"#)?;
///
/// let windows = collect_windows(&state);
/// let ids: Vec<u32> = windows.iter().map(|window| window.id).collect();
/// assert_eq!(ids, [1, 2, 3, 5]);
/// assert_eq!(windows[0].exe.as_deref(), Some("A"));
/// assert_eq!(windows[0].title.as_deref(), Some("one"));
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[must_use]
pub fn collect_windows(state: &Value) -> Vec<StateWindow> {
fn walk(value: &Value, out: &mut BTreeMap<u32, StateWindow>) {
match value {
Value::Object(map) => {
if let (Some(id), Some(Value::Object(details))) =
(map.get("id").and_then(Value::as_u64), map.get("details"))
&& let Ok(id) = u32::try_from(id)
{
let text =
|key: &str| details.get(key).and_then(Value::as_str).map(str::to_string);
out.entry(id).or_insert_with(|| StateWindow {
id,
exe: text("exe"),
title: text("title"),
});
}
for child in map.values() {
walk(child, out);
}
}
Value::Array(items) => {
for item in items {
walk(item, out);
}
}
_ => {}
}
}
let mut windows = BTreeMap::new();
walk(state, &mut windows);
windows.into_values().collect()
}
/// The process that owns a window, as reported by the OS.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WindowOwner {
/// The owning process id. [`gui_app_pids`] and [`resolve`] ignore a pid that is not positive.
pub pid: i32,
/// The owning application's name as the OS reports it: the window server's owner name on a
/// Mac, the program's file name without `.exe` on Windows. Empty if the OS gave none.
pub name: String,
/// The window's layer: `0` for an ordinary application window, higher for things like the menu
/// bar and the Dock. Always `0` on Windows, which reports none.
pub layer: i64,
}
/// Returns every window the OS knows about (all spaces or virtual desktops, visible or not),
/// keyed by window id.
///
/// This asks the OS each time it is called, through [`crate::platform::apps::window_owners`]; see
/// there for how the hosts differ. The map is empty if the OS cannot be asked.
///
/// This depends on the machine it runs on, so it has no doctest. It is covered by
/// `window_server_listing_works` in this file's unit tests, which skips itself where no window
/// server is reachable.
#[must_use]
pub fn window_owners() -> HashMap<u32, WindowOwner> {
crate::platform::apps::window_owners()
}
/// Returns every process that owns at least one ordinary (layer 0) window, i.e. the apps a user
/// can see.
///
/// Each is returned with the owner name of one of its windows. Processes with a pid that is not
/// positive are left out.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::managed_apps::{WindowOwner, gui_app_pids};
/// use std::collections::HashMap;
///
/// let owners = HashMap::from([
/// (1, WindowOwner { pid: 10, name: "App".into(), layer: 0 }),
/// (2, WindowOwner { pid: 20, name: "Dock".into(), layer: 20 }),
/// ]);
///
/// let apps = gui_app_pids(&owners);
/// assert_eq!(apps.len(), 1);
/// assert_eq!(apps.get(&10).map(String::as_str), Some("App"));
/// ```
#[must_use]
pub fn gui_app_pids(owners: &HashMap<u32, WindowOwner>) -> BTreeMap<i32, String> {
owners
.values()
.filter(|owner| owner.layer == 0 && owner.pid > 0)
.map(|owner| (owner.pid, owner.name.clone()))
.collect()
}
/// How a window's owning process was found. Serialized in the manifest as `window_id` or
/// `owner_name`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Resolution {
/// The window id was found in the window server's list.
WindowId,
/// The window id was not listed, but exactly one process has a matching owner name.
OwnerName,
}
/// A process komorebi manages windows of.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ManagedApp {
/// The process id, always positive.
pub pid: i32,
/// The process's name: the owner name the OS gave it.
pub name: String,
/// The ids of this process's windows in the `State`.
pub window_ids: BTreeSet<u32>,
/// How the process was found, for the first of its windows that was resolved.
pub resolution: Resolution,
}
/// The outcome of resolving a state's windows to processes.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Resolved {
/// The processes found, one entry each, in ascending order of process id.
pub apps: Vec<ManagedApp>,
/// Windows in the state that could not be tied to any process.
pub unresolved: Vec<StateWindow>,
}
/// Resolves state windows to owning processes.
///
/// A window is resolved by its id when `owners` has it. Otherwise, if it has an `exe`, it is
/// resolved by name, but only when exactly one process in `owners` has that owner name: an
/// ambiguous or unknown name leaves the window unresolved. Windows of one process are gathered
/// into one [`ManagedApp`].
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::managed_apps::{Resolution, StateWindow, WindowOwner, resolve};
/// use std::collections::HashMap;
///
/// let owner = |pid, name: &str| WindowOwner { pid, name: name.into(), layer: 0 };
/// let owners = HashMap::from([
/// (1, owner(100, "Ghostty")),
/// (2, owner(200, "Dup")),
/// (3, owner(300, "Dup")),
/// ]);
/// let window = |id, exe: &str| StateWindow { id, exe: Some(exe.into()), title: None };
///
/// let resolved = resolve(
/// &[window(1, "Ghostty"), window(99, "Ghostty"), window(98, "Dup"), window(97, "Nope")],
/// &owners,
/// );
///
/// // window 1 is listed; 99 is not, but only one process is called Ghostty
/// assert_eq!(resolved.apps.len(), 1);
/// assert_eq!(resolved.apps[0].pid, 100);
/// assert_eq!(resolved.apps[0].resolution, Resolution::WindowId);
/// assert_eq!(resolved.apps[0].window_ids.iter().copied().collect::<Vec<_>>(), [1, 99]);
///
/// // two processes are called Dup, and nobody is called Nope
/// let unresolved: Vec<u32> = resolved.unresolved.iter().map(|window| window.id).collect();
/// assert_eq!(unresolved, [98, 97]);
/// ```
#[must_use]
pub fn resolve(windows: &[StateWindow], owners: &HashMap<u32, WindowOwner>) -> Resolved {
let mut by_name: HashMap<&str, BTreeSet<i32>> = HashMap::new();
for owner in owners.values() {
by_name
.entry(owner.name.as_str())
.or_default()
.insert(owner.pid);
}
let mut apps: BTreeMap<i32, ManagedApp> = BTreeMap::new();
let mut unresolved = Vec::new();
for window in windows {
let found = owners
.get(&window.id)
.map(|owner| (owner.pid, owner.name.clone(), Resolution::WindowId))
.or_else(|| {
let exe = window.exe.as_deref()?;
let pids = by_name.get(exe)?;
// only trust a name match when it is unambiguous
(pids.len() == 1).then(|| {
(
*pids.iter().next().unwrap_or(&0),
exe.to_string(),
Resolution::OwnerName,
)
})
});
match found {
Some((pid, name, resolution)) if pid > 0 => {
apps.entry(pid)
.or_insert_with(|| ManagedApp {
pid,
name,
window_ids: BTreeSet::new(),
resolution,
})
.window_ids
.insert(window.id);
}
_ => unresolved.push(window.clone()),
}
}
Resolved {
apps: apps.into_values().collect(),
unresolved,
}
}
const WINDOW_MANAGER_EVENTS: &[&str] = &[
"FocusChange",
"Show",
"Destroy",
"Minimize",
"Restore",
"Manage",
"Unmanage",
"MoveStart",
"MoveEnd",
"ResizeStart",
"ResizeEnd",
];
/// Returns the process id carried by a window manager event notification (`content[1]`), if the
/// event is one. Used to notice a new process with no polling delay.
///
/// `event` is the `event` value of a notification (see
/// [`EventRow::event`](crate::sources::komorebi_events::EventRow::event)). The result is `None`
/// unless the event's `type` is one of `FocusChange`, `Show`, `Destroy`, `Minimize`, `Restore`,
/// `Manage`, `Unmanage`, `MoveStart`, `MoveEnd`, `ResizeStart` and `ResizeEnd` and `content[1]` is
/// a positive integer that fits in `i32`: commands and monitor events, and the events a Mac sends
/// with no real process (a negative id), have none.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::managed_apps::event_pid;
/// use serde_json::json;
///
/// let focus = json!({"type": "FocusChange", "content": [{"type": "Accessibility", "content": "AXMainWindowChanged"}, 20934, 3395]});
/// assert_eq!(event_pid(&focus), Some(20934));
///
/// // a command is not a window manager event
/// assert_eq!(event_pid(&json!({"type": "FocusWindow", "content": "Left"})), None);
/// // a negative process id is not a process
/// assert_eq!(event_pid(&json!({"type": "Show", "content": [{"type": "AppKitWorkspace", "content": "x"}, -1]})), None);
/// ```
#[must_use]
pub fn event_pid(event: &Value) -> Option<i32> {
let kind = event.get("type")?.as_str()?;
if !WINDOW_MANAGER_EVENTS.contains(&kind) {
return None;
}
let pid = event.get("content")?.as_array()?.get(1)?.as_i64()?;
i32::try_from(pid).ok().filter(|pid| *pid > 0)
}
/// A managed process as tracked across a whole recording, as the manifest (`session.json`, key
/// `apps`) records it.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct AppRecord {
/// The process id.
pub pid: i32,
/// The process's name (`Brave Beta`), as the recorder learned it. It also names the process's
/// stream file.
pub exe: String,
/// The ids of the process's windows in komorebi's `State`, in the order they were first seen.
pub window_ids: Vec<u32>,
/// When the recorder first noticed this process, on the host's master monotonic clock in
/// nanoseconds; its OS trace starts no earlier than this.
pub first_seen_mach_ns: u64,
/// How the process came to be traced: `state` (found in a `State`), `event` (named by a window
/// manager event), `all-gui` (every application, `--oslog-apps all-gui`) or `explicit`
/// (named by `--trace-process`).
pub origin: String,
/// How the process was resolved from a window of the `State`. `None` for a process that was
/// not found through one of its windows.
pub resolution: Option<Resolution>,
/// The process's OS-trace file relative to the session directory
/// (`oslog/apps/<exe>-<pid>.ndjson`). `None` if no stream was started for it.
pub stream_file: Option<String>,
/// Unified-log events captured for this process.
#[serde(default)]
pub events: u64,
/// Bytes of unified-log records captured for this process.
#[serde(default)]
pub bytes: u64,
}
/// Tracks the distinct managed processes seen over a recording, and the windows that could not be
/// tied to a process.
///
/// # Example
///
/// ```rust
/// use komorebi_recorder::sources::managed_apps::{AppTracker, StateWindow, WindowOwner, resolve};
/// use std::collections::HashMap;
///
/// let owners = HashMap::from([
/// (1, WindowOwner { pid: 100, name: "A".into(), layer: 0 }),
/// (2, WindowOwner { pid: 100, name: "A".into(), layer: 0 }),
/// ]);
/// let window = |id| StateWindow { id, exe: None, title: None };
///
/// let mut tracker = AppTracker::default();
///
/// // the first time a process is seen, it is returned (the caller starts its stream) ...
/// let fresh = tracker.observe(resolve(&[window(1)], &owners), "state");
/// assert_eq!(fresh.len(), 1);
///
/// // ... and never again, though a new window of it is merged in
/// let fresh = tracker.observe(resolve(&[window(1), window(2)], &owners), "state");
/// assert!(fresh.is_empty());
/// assert_eq!(tracker.records()[0].window_ids, [1, 2]);
///
/// // a process named directly is tracked once too
/// assert!(tracker.observe_pid(300, "C".into(), "event").is_some());
/// assert!(tracker.observe_pid(300, "C".into(), "event").is_none());
/// ```
#[derive(Debug, Default)]
pub struct AppTracker {
apps: BTreeMap<i32, AppRecord>,
unresolved: BTreeMap<u32, StateWindow>,
}
impl AppTracker {
/// Folds a resolution into the tracker, returning the records for processes seen for the
/// first time (the caller spawns a stream for each).
///
/// A process already tracked only gains any new window ids. Windows that could not be
/// resolved are remembered until a later resolution ties them to a process. `origin` is stored
/// as the [`AppRecord::origin`] of each new record.
pub fn observe(&mut self, resolved: Resolved, origin: &str) -> Vec<AppRecord> {
let mut fresh = Vec::new();
for app in resolved.apps {
match self.apps.entry(app.pid) {
Entry::Vacant(slot) => {
let record = AppRecord {
pid: app.pid,
exe: app.name,
window_ids: app.window_ids.into_iter().collect(),
first_seen_mach_ns: clock::mono_now_ns(),
origin: origin.to_string(),
resolution: Some(app.resolution),
..AppRecord::default()
};
fresh.push(record.clone());
slot.insert(record);
}
Entry::Occupied(mut slot) => {
let record = slot.get_mut();
for id in app.window_ids {
if !record.window_ids.contains(&id) {
record.window_ids.push(id);
}
}
}
}
}
for window in resolved.unresolved {
self.unresolved.insert(window.id, window);
}
// a window that resolved later is no longer unresolved
let known: BTreeSet<u32> = self
.apps
.values()
.flat_map(|app| app.window_ids.iter().copied())
.collect();
self.unresolved.retain(|id, _| !known.contains(id));
fresh
}
/// Tracks a process the recorder was told about directly (an event pid, a `--trace-process`
/// name, `all-gui`).
///
/// Returns the new record, or `None` if the process was already tracked. The record has no
/// windows and no [`Resolution`].
pub fn observe_pid(&mut self, pid: i32, name: String, origin: &str) -> Option<AppRecord> {
if self.apps.contains_key(&pid) {
return None;
}
let record = AppRecord {
pid,
exe: name,
window_ids: Vec::new(),
first_seen_mach_ns: clock::mono_now_ns(),
origin: origin.to_string(),
resolution: None,
..AppRecord::default()
};
self.apps.insert(pid, record.clone());
Some(record)
}
/// Records the path of the OS-trace file started for process `pid`, relative to the session
/// directory. Does nothing if the process is not tracked.
pub fn set_stream_file(&mut self, pid: i32, file: &str) {
if let Some(app) = self.apps.get_mut(&pid) {
app.stream_file = Some(file.to_string());
}
}
/// Returns `true` if and only if process `pid` is already tracked.
#[must_use]
pub fn contains(&self, pid: i32) -> bool {
self.apps.contains_key(&pid)
}
/// Returns a copy of every tracked process's record, in ascending order of process id.
#[must_use]
pub fn records(&self) -> Vec<AppRecord> {
self.apps.values().cloned().collect()
}
/// Returns the windows seen so far that no process has been tied to, in ascending order of
/// window id.
#[must_use]
pub fn unresolved(&self) -> Vec<StateWindow> {
self.unresolved.values().cloned().collect()
}
}
#[cfg(test)]
mod tests {
use super::*;
/// A real komorebi `State` (window titles sanitised), captured while reproducing a bug.
const STATE_REPRO: &str = include_str!("../../tests/fixtures/state.json");
fn state() -> Value {
serde_json::from_str(STATE_REPRO).expect("the repro state parses")
}
#[test]
fn walks_every_window_in_a_real_state() {
let windows = collect_windows(&state());
let ids: Vec<u32> = windows.iter().map(|window| window.id).collect();
// spot-check ids from different workspaces
for id in [59, 61, 8310, 107, 3395, 6293, 8550] {
assert!(ids.contains(&id), "window {id} missing from {ids:?}");
}
let slack = windows
.iter()
.find(|window| window.id == 59)
.expect("slack");
assert_eq!(slack.exe.as_deref(), Some("Slack"));
assert!(windows.len() >= 17, "found {}", windows.len());
// ids are unique
let unique: BTreeSet<u32> = ids.iter().copied().collect();
assert_eq!(unique.len(), ids.len());
}
#[test]
fn finds_windows_wherever_they_are_nested() {
let state: Value = serde_json::from_str(
r#"{
"layout": {"deeply": {"nested": [
{"id": 1, "details": {"exe": "A", "title": "one"}},
{"monocle_container": {"windows": {"elements": [{"id": 2, "details": {"exe": "B"}}]}}},
{"maximized_window": {"id": 3, "details": {"exe": "C"}}},
{"id": "not-a-window-id", "details": {"exe": "D"}},
{"id": 4, "no_details": true}
]}},
"floating_windows": {"elements": [{"id": 5, "details": {"exe": "E"}}]}
}"#,
)
.expect("json");
let ids: Vec<u32> = collect_windows(&state)
.iter()
.map(|window| window.id)
.collect();
assert_eq!(ids, vec![1, 2, 3, 5]);
}
#[test]
fn resolves_windows_by_id_across_spaces() {
let owners = HashMap::from([
(
59,
WindowOwner {
pid: 100,
name: "Slack".into(),
layer: 0,
},
),
(
61,
WindowOwner {
pid: 200,
name: "Brave".into(),
layer: 0,
},
),
(
8310,
WindowOwner {
pid: 200,
name: "Brave".into(),
layer: 0,
},
),
]);
let windows: Vec<StateWindow> = [59, 61, 8310]
.into_iter()
.map(|id| StateWindow {
id,
exe: None,
title: None,
})
.collect();
let resolved = resolve(&windows, &owners);
assert!(resolved.unresolved.is_empty());
assert_eq!(resolved.apps.len(), 2);
let brave = resolved
.apps
.iter()
.find(|app| app.pid == 200)
.expect("brave");
assert_eq!(brave.name, "Brave");
assert_eq!(brave.window_ids, BTreeSet::from([61, 8310]));
}
#[test]
fn falls_back_to_an_unambiguous_owner_name() {
let owners = HashMap::from([
(
1,
WindowOwner {
pid: 100,
name: "Ghostty".into(),
layer: 0,
},
),
(
2,
WindowOwner {
pid: 200,
name: "Dup".into(),
layer: 0,
},
),
(
3,
WindowOwner {
pid: 300,
name: "Dup".into(),
layer: 0,
},
),
]);
let windows = vec![
StateWindow {
id: 99,
exe: Some("Ghostty".into()),
title: None,
},
StateWindow {
id: 98,
exe: Some("Dup".into()),
title: None,
},
StateWindow {
id: 97,
exe: Some("Nope".into()),
title: None,
},
];
let resolved = resolve(&windows, &owners);
assert_eq!(resolved.apps.len(), 1);
assert_eq!(resolved.apps[0].pid, 100);
assert_eq!(resolved.apps[0].resolution, Resolution::OwnerName);
assert_eq!(
resolved.unresolved.len(),
2,
"ambiguous and unknown names stay unresolved"
);
}
#[test]
fn extracts_pids_from_window_manager_events() {
let event: Value = serde_json::from_str(
r#"{"type":"FocusChange","content":[{"type":"Accessibility","content":"AXMainWindowChanged"},20934,3395]}"#,
)
.expect("json");
assert_eq!(event_pid(&event), Some(20934));
let socket: Value =
serde_json::from_str(r#"{"type":"FocusWindow","content":"Left"}"#).expect("json");
assert_eq!(event_pid(&socket), None);
let space: Value = serde_json::from_str(
r#"{"type":"Show","content":[{"type":"AppKitWorkspace","content":"x"},-1]}"#,
)
.expect("json");
assert_eq!(event_pid(&space), None, "negative pids are not processes");
}
#[test]
fn tracker_reports_each_process_once() {
let owners = HashMap::from([
(
1,
WindowOwner {
pid: 100,
name: "A".into(),
layer: 0,
},
),
(
2,
WindowOwner {
pid: 100,
name: "A".into(),
layer: 0,
},
),
(
3,
WindowOwner {
pid: 200,
name: "B".into(),
layer: 0,
},
),
]);
let window = |id| StateWindow {
id,
exe: None,
title: None,
};
let mut tracker = AppTracker::default();
let fresh = tracker.observe(resolve(&[window(1), window(3)], &owners), "state");
assert_eq!(fresh.len(), 2);
// the same state again discovers nothing new, but a new window of a known app is merged
let fresh = tracker.observe(
resolve(&[window(1), window(2), window(3)], &owners),
"state",
);
assert!(fresh.is_empty());
let records = tracker.records();
assert_eq!(
records
.iter()
.find(|app| app.pid == 100)
.expect("a")
.window_ids,
vec![1, 2]
);
assert!(tracker.observe_pid(100, "A".into(), "event").is_none());
assert!(tracker.observe_pid(300, "C".into(), "event").is_some());
assert!(tracker.contains(300));
}
#[test]
fn unresolved_windows_are_reported_until_they_resolve() {
let mut tracker = AppTracker::default();
let window = StateWindow {
id: 7,
exe: Some("Ghost".into()),
title: None,
};
tracker.observe(
resolve(std::slice::from_ref(&window), &HashMap::new()),
"state",
);
assert_eq!(tracker.unresolved().len(), 1);
let owners = HashMap::from([(
7,
WindowOwner {
pid: 5,
name: "Ghost".into(),
layer: 0,
},
)]);
tracker.observe(resolve(std::slice::from_ref(&window), &owners), "state");
assert!(tracker.unresolved().is_empty());
}
#[test]
fn gui_apps_are_layer_zero_owners() {
let owners = HashMap::from([
(
1,
WindowOwner {
pid: 10,
name: "App".into(),
layer: 0,
},
),
(
2,
WindowOwner {
pid: 20,
name: "Dock".into(),
layer: 20,
},
),
]);
let gui = gui_app_pids(&owners);
assert_eq!(gui.len(), 1);
assert_eq!(gui.get(&10).map(String::as_str), Some("App"));
}
/// Against the real window server: the call must work and see windows. Sandboxed builds may
/// have no window server to ask, in which case there is nothing to assert.
#[test]
fn window_server_listing_works() {
let owners = window_owners();
if owners.is_empty() {
eprintln!("skipping: no window server is reachable from this environment");
return;
}
assert!(owners.values().all(|owner| owner.pid > 0));
}
}
+6
View File
@@ -10,6 +10,9 @@
//! | module | files it writes | recorded on |
//! |---|---|---|
//! | [`komorebi_events`] | `events.jsonl` (one JSON object per line), `states/<id>.json` | both hosts |
//! | `komorebi_log` | `komorebi.log` (a byte-for-byte slice of komorebi's own log) | both hosts |
//! | `komorebi_version` | no file: asks komorebi's binary what it is, for the manifest | both hosts |
//! | `managed_apps` | no file: decides which processes get a trace of their own | macOS |
//!
//! The types that a source reports about itself to the manifest (`session.json`) are defined
//! beside it: `EventSummary`, `LogSegment`, `StreamInfo`, `KomorebiVersion` and `AppRecord`.
@@ -32,3 +35,6 @@
//! `host.clock` says which clock that was.
pub mod komorebi_events;
pub mod komorebi_log;
pub mod komorebi_version;
pub mod managed_apps;
File diff suppressed because it is too large. Load diff