mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-16 13:51:19 +01:00
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:
1 parent
c748237741
commit
4724d831ba
22 files changed
+4668
-1
No files matched your search
Generated
+205
@@ -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
@@ -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"
|
||||
]
|
||||
]
|
||||
]
|
||||
|
||||
@@ -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 |
|
||||
@@ -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"
|
||||
|
||||
@@ -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!(
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
@@ -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;
|
||||
|
||||
@@ -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
|
||||
}
|
||||
@@ -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));
|
||||
}
|
||||
}
|
||||
@@ -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;
|
||||
+1133
File diff suppressed because it is too large.
Load diff
Reference in new issue
Block a user