From d5eacecef8d80af9d1c3aee0d9d75da960764792 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Tue, 27 Oct 2026 06:14:07 -0700 Subject: [PATCH] feat(clock): the master clock Every record in a session is stamped on one monotonic clock: `mach_absolute_time` on macOS and `QueryPerformanceCounter` on Windows, behind a `platform` facade with a third `unsupported` host that builds anywhere. Anchors pair that clock with the wall clock, a map interpolates between them, and a jump detector notices sleep and clock steps by comparing how far each moved. Video timecodes are parsed and printed here too. `Host` and `ClockKind` say what a session was recorded on. --- Cargo.lock | 449 +++++++++ README.md | 2 + dependencies.json | 111 +- docs/ARCHITECTURE.md | 51 + docs/PLATFORM.md | 66 ++ komorebi-recorder/Cargo.toml | 47 + komorebi-recorder/src/clock.rs | 949 ++++++++++++++++++ komorebi-recorder/src/lib.rs | 49 + komorebi-recorder/src/platform/macos/clock.rs | 112 +++ komorebi-recorder/src/platform/macos/mod.rs | 22 + komorebi-recorder/src/platform/macos/shell.rs | 72 ++ komorebi-recorder/src/platform/mod.rs | 181 ++++ komorebi-recorder/src/platform/unsupported.rs | 62 ++ komorebi-recorder/src/platform/win/clock.rs | 83 ++ komorebi-recorder/src/platform/win/mod.rs | 33 + komorebi-recorder/src/platform/win/shell.rs | 111 ++ komorebi-recorder/src/timecode.rs | 277 +++++ 17 files changed, 2676 insertions(+), 1 deletion(-) create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/PLATFORM.md create mode 100644 komorebi-recorder/src/clock.rs create mode 100644 komorebi-recorder/src/platform/macos/clock.rs create mode 100644 komorebi-recorder/src/platform/macos/mod.rs create mode 100644 komorebi-recorder/src/platform/macos/shell.rs create mode 100644 komorebi-recorder/src/platform/mod.rs create mode 100644 komorebi-recorder/src/platform/unsupported.rs create mode 100644 komorebi-recorder/src/platform/win/clock.rs create mode 100644 komorebi-recorder/src/platform/win/mod.rs create mode 100644 komorebi-recorder/src/platform/win/shell.rs create mode 100644 komorebi-recorder/src/timecode.rs diff --git a/Cargo.lock b/Cargo.lock index 5ca549ce..ee8a0abd 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2,6 +2,21 @@ # It is not intended for manual editing. version = 4 +[[package]] +name = "addr2line" +version = "0.25.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1b5d307320b3181d6d7954e663bd7c774a838b8220fe0593c86d9fb09f498b4b" +dependencies = [ + "gimli", +] + +[[package]] +name = "adler2" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa" + [[package]] name = "anstream" version = "1.0.0" @@ -52,12 +67,33 @@ dependencies = [ "windows-sys 0.60.2", ] +[[package]] +name = "backtrace" +version = "0.3.76" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bb531853791a215d7c62a30daf0dde835f381ab5de4589cfe7c649d2cbe92bd6" +dependencies = [ + "addr2line", + "cfg-if", + "libc", + "miniz_oxide", + "object", + "rustc-demangle", + "windows-link", +] + [[package]] name = "bitflags" version = "2.11.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3" +[[package]] +name = "cfg-if" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" + [[package]] name = "clap" version = "4.6.1" @@ -99,12 +135,45 @@ version = "1.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9" +[[package]] +name = "color-eyre" +version = "0.6.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5920befb47832a6d61ee3a3a846565cfa39b331331e68a3b1d1116630f2f26d" +dependencies = [ + "backtrace", + "color-spantrace", + "eyre", + "indenter", + "once_cell", + "owo-colors", + "tracing-error", +] + +[[package]] +name = "color-spantrace" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8b88ea9df13354b55bc7234ebcce36e6ef896aca2e42a15de9e10edce01b427" +dependencies = [ + "once_cell", + "owo-colors", + "tracing-core", + "tracing-error", +] + [[package]] name = "colorchoice" version = "1.0.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570" +[[package]] +name = "dyn-clone" +version = "1.0.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555" + [[package]] name = "errno" version = "0.3.14" @@ -115,25 +184,65 @@ dependencies = [ "windows-sys 0.52.0", ] +[[package]] +name = "eyre" +version = "0.6.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7cd915d99f24784cdc19fd37ef22b97e3ff0ae756c7e492e9fbfe897d61e2aec" +dependencies = [ + "indenter", + "once_cell", +] + +[[package]] +name = "gimli" +version = "0.32.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e629b9b98ef3dd8afe6ca2bd0f89306cec16d43d907889945bc5d6687f2f13c7" + [[package]] name = "heck" version = "0.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" +[[package]] +name = "indenter" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "964de6e86d545b246d84badc0fef527924ace5134f30641c203ef52ba83f58d5" + [[package]] name = "is_terminal_polyfill" version = "1.70.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695" +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + [[package]] name = "komorebi-recorder" version = "0.1.0" dependencies = [ "clap", + "color-eyre", + "libc", + "schemars", + "serde", + "serde_json_lenient", + "windows", ] +[[package]] +name = "lazy_static" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe" + [[package]] name = "libc" version = "0.2.186" @@ -146,12 +255,54 @@ version = "0.12.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53" +[[package]] +name = "memchr" +version = "2.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79" + +[[package]] +name = "miniz_oxide" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316" +dependencies = [ + "adler2", +] + +[[package]] +name = "object" +version = "0.37.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff76201f031d8863c38aa7f905eca4f53abbfa15f609db4277d44cd8938f33fe" +dependencies = [ + "memchr", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + [[package]] name = "once_cell_polyfill" version = "1.70.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe" +[[package]] +name = "owo-colors" +version = "4.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d211803b9b6b570f68772237e415a029d5a50c65d382910b879fb19d3271f94d" + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + [[package]] name = "proc-macro2" version = "1.0.106" @@ -170,6 +321,32 @@ dependencies = [ "proc-macro2", ] +[[package]] +name = "ref-cast" +version = "1.0.25" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f354300ae66f76f1c85c5f84693f0ce81d747e2c3f21a45fef496d89c960bf7d" +dependencies = [ + "ref-cast-impl", +] + +[[package]] +name = "ref-cast-impl" +version = "1.0.25" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b7186006dcb21920990093f30e3dea63b7d6e977bf1256be20c3563a5db070da" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "rustc-demangle" +version = "0.1.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b50b8869d9fc858ce7266cce0194bd74df58b9d0e3f6df3a9fc8eb470d95c09d" + [[package]] name = "rustix" version = "1.1.4" @@ -183,6 +360,112 @@ dependencies = [ "windows-sys 0.52.0", ] +[[package]] +name = "ryu" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f" + +[[package]] +name = "schemars" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2b42f36aa1cd011945615b92222f6bf73c599a102a300334cd7f8dbeec726cc" +dependencies = [ + "dyn-clone", + "ref-cast", + "schemars_derive", + "serde", + "serde_json", +] + +[[package]] +name = "schemars_derive" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7d115b50f4aaeea07e79c1912f645c7513d81715d0420f8bc77a18c6260b307f" +dependencies = [ + "proc-macro2", + "quote", + "serde_derive_internals", + "syn", +] + +[[package]] +name = "serde" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_derive_internals" +version = "0.29.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "18d26a20a969b9e3fdf2fc2d9f21eda6c40e2de84c9408bb5d3b05d499aae711" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.149" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "serde_json_lenient" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0e033097bf0d2b59a62b42c18ebbb797503839b26afdda2c4e1415cb6c813540" +dependencies = [ + "itoa", + "memchr", + "ryu", + "serde", +] + +[[package]] +name = "sharded-slab" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f40ca3c46823713e0d4209592e8d6e826aa57e928f09752619fc696c499637f6" +dependencies = [ + "lazy_static", +] + [[package]] name = "strsim" version = "0.11.1" @@ -210,6 +493,56 @@ dependencies = [ "windows-sys 0.59.0", ] +[[package]] +name = "thread_local" +version = "1.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f60246a4944f24f6e018aa17cdeffb7818b76356965d03b07d6a9886e8962185" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "tracing" +version = "0.1.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100" +dependencies = [ + "pin-project-lite", + "tracing-core", +] + +[[package]] +name = "tracing-core" +version = "0.1.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a" +dependencies = [ + "once_cell", + "valuable", +] + +[[package]] +name = "tracing-error" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8b1581020d7a273442f5b45074a6a57d5757ad0a47dac0e9f0bd57b81936f3db" +dependencies = [ + "tracing", + "tracing-subscriber", +] + +[[package]] +name = "tracing-subscriber" +version = "0.3.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319" +dependencies = [ + "sharded-slab", + "thread_local", + "tracing-core", +] + [[package]] name = "unicode-ident" version = "1.0.24" @@ -222,12 +555,113 @@ version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" +[[package]] +name = "valuable" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65" + +[[package]] +name = "windows" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580" +dependencies = [ + "windows-collections", + "windows-core", + "windows-future", + "windows-numerics", +] + +[[package]] +name = "windows-collections" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610" +dependencies = [ + "windows-core", +] + +[[package]] +name = "windows-core" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb" +dependencies = [ + "windows-implement", + "windows-interface", + "windows-link", + "windows-result", + "windows-strings", +] + +[[package]] +name = "windows-future" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb" +dependencies = [ + "windows-core", + "windows-link", + "windows-threading", +] + +[[package]] +name = "windows-implement" +version = "0.60.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "windows-interface" +version = "0.59.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + [[package]] name = "windows-link" version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" +[[package]] +name = "windows-numerics" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26" +dependencies = [ + "windows-core", + "windows-link", +] + +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-strings" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091" +dependencies = [ + "windows-link", +] + [[package]] name = "windows-sys" version = "0.52.0" @@ -288,6 +722,15 @@ dependencies = [ "windows_x86_64_msvc 0.53.1", ] +[[package]] +name = "windows-threading" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37" +dependencies = [ + "windows-link", +] + [[package]] name = "windows_aarch64_gnullvm" version = "0.52.6" @@ -383,3 +826,9 @@ name = "windows_x86_64_msvc" version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650" + +[[package]] +name = "zmij" +version = "1.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa" diff --git a/README.md b/README.md index 1d842d83..e980eb28 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,8 @@ Two things vary independently: the _host_ the recorder runs on (macOS or Windows records (komorebi for Mac or komorebi for Windows). A session records both, so one recorded on Windows can be investigated on a Mac. Every record in a session is stamped on one monotonic clock, and the files in it are never rewritten after they are written. +[Architecture](docs/ARCHITECTURE.md) explains the model and which layer enforces each rule; +[Platform](docs/PLATFORM.md) answers the same questions for each host. ## Crates diff --git a/dependencies.json b/dependencies.json index a0e3e2d7..1276c738 100644 --- a/dependencies.json +++ b/dependencies.json @@ -1,36 +1,80 @@ { "licenses": [ + [ + "0BSD", + [ + "adler2 2.0.1 registry+https://github.com/rust-lang/crates.io-index" + ] + ], [ "Apache-2.0", [ + "addr2line 0.25.1 registry+https://github.com/rust-lang/crates.io-index", + "adler2 2.0.1 registry+https://github.com/rust-lang/crates.io-index", "anstream 1.0.0 registry+https://github.com/rust-lang/crates.io-index", "anstyle 1.0.14 registry+https://github.com/rust-lang/crates.io-index", "anstyle-parse 1.0.0 registry+https://github.com/rust-lang/crates.io-index", "anstyle-query 1.1.5 registry+https://github.com/rust-lang/crates.io-index", "anstyle-wincon 3.0.11 registry+https://github.com/rust-lang/crates.io-index", + "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", "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", "clap_lex 1.1.0 registry+https://github.com/rust-lang/crates.io-index", + "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", + "dyn-clone 1.0.20 registry+https://github.com/rust-lang/crates.io-index", "errno 0.3.14 registry+https://github.com/rust-lang/crates.io-index", + "eyre 0.6.12 registry+https://github.com/rust-lang/crates.io-index", + "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", + "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", + "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", + "pin-project-lite 0.2.17 registry+https://github.com/rust-lang/crates.io-index", "proc-macro2 1.0.106 registry+https://github.com/rust-lang/crates.io-index", "quote 1.0.45 registry+https://github.com/rust-lang/crates.io-index", + "ref-cast 1.0.25 registry+https://github.com/rust-lang/crates.io-index", + "ref-cast-impl 1.0.25 registry+https://github.com/rust-lang/crates.io-index", + "rustc-demangle 0.1.27 registry+https://github.com/rust-lang/crates.io-index", "rustix 1.1.4 registry+https://github.com/rust-lang/crates.io-index", + "ryu 1.0.23 registry+https://github.com/rust-lang/crates.io-index", + "serde 1.0.228 registry+https://github.com/rust-lang/crates.io-index", + "serde_core 1.0.228 registry+https://github.com/rust-lang/crates.io-index", + "serde_derive 1.0.228 registry+https://github.com/rust-lang/crates.io-index", + "serde_derive_internals 0.29.1 registry+https://github.com/rust-lang/crates.io-index", + "serde_json 1.0.149 registry+https://github.com/rust-lang/crates.io-index", + "serde_json_lenient 0.2.4 registry+https://github.com/rust-lang/crates.io-index", "syn 2.0.117 registry+https://github.com/rust-lang/crates.io-index", "terminal_size 0.4.4 registry+https://github.com/rust-lang/crates.io-index", + "thread_local 1.1.9 registry+https://github.com/rust-lang/crates.io-index", "unicode-ident 1.0.24 registry+https://github.com/rust-lang/crates.io-index", "utf8parse 0.2.2 registry+https://github.com/rust-lang/crates.io-index", + "windows 0.62.2 registry+https://github.com/rust-lang/crates.io-index", + "windows-collections 0.3.2 registry+https://github.com/rust-lang/crates.io-index", + "windows-core 0.62.2 registry+https://github.com/rust-lang/crates.io-index", + "windows-future 0.3.2 registry+https://github.com/rust-lang/crates.io-index", + "windows-implement 0.60.2 registry+https://github.com/rust-lang/crates.io-index", + "windows-interface 0.59.3 registry+https://github.com/rust-lang/crates.io-index", + "windows-link 0.2.1 registry+https://github.com/rust-lang/crates.io-index", + "windows-numerics 0.3.1 registry+https://github.com/rust-lang/crates.io-index", + "windows-result 0.4.1 registry+https://github.com/rust-lang/crates.io-index", + "windows-strings 0.5.1 registry+https://github.com/rust-lang/crates.io-index", "windows-sys 0.52.0 registry+https://github.com/rust-lang/crates.io-index", "windows-sys 0.59.0 registry+https://github.com/rust-lang/crates.io-index", "windows-sys 0.60.2 registry+https://github.com/rust-lang/crates.io-index", "windows-targets 0.52.6 registry+https://github.com/rust-lang/crates.io-index", "windows-targets 0.53.5 registry+https://github.com/rust-lang/crates.io-index", + "windows-threading 0.2.1 registry+https://github.com/rust-lang/crates.io-index", "windows_x86_64_msvc 0.52.6 registry+https://github.com/rust-lang/crates.io-index", "windows_x86_64_msvc 0.53.1 registry+https://github.com/rust-lang/crates.io-index" ] @@ -41,6 +85,12 @@ "rustix 1.1.4 registry+https://github.com/rust-lang/crates.io-index" ] ], + [ + "BSL-1.0", + [ + "ryu 1.0.23 registry+https://github.com/rust-lang/crates.io-index" + ] + ], [ "LicenseRef-Komorebi-2.0", [ @@ -50,37 +100,84 @@ [ "MIT", [ + "addr2line 0.25.1 registry+https://github.com/rust-lang/crates.io-index", + "adler2 2.0.1 registry+https://github.com/rust-lang/crates.io-index", "anstream 1.0.0 registry+https://github.com/rust-lang/crates.io-index", "anstyle 1.0.14 registry+https://github.com/rust-lang/crates.io-index", "anstyle-parse 1.0.0 registry+https://github.com/rust-lang/crates.io-index", "anstyle-query 1.1.5 registry+https://github.com/rust-lang/crates.io-index", "anstyle-wincon 3.0.11 registry+https://github.com/rust-lang/crates.io-index", + "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", "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", "clap_lex 1.1.0 registry+https://github.com/rust-lang/crates.io-index", + "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", + "dyn-clone 1.0.20 registry+https://github.com/rust-lang/crates.io-index", "errno 0.3.14 registry+https://github.com/rust-lang/crates.io-index", + "eyre 0.6.12 registry+https://github.com/rust-lang/crates.io-index", + "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", + "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", + "memchr 2.8.0 registry+https://github.com/rust-lang/crates.io-index", + "miniz_oxide 0.8.9 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", + "owo-colors 4.3.0 registry+https://github.com/rust-lang/crates.io-index", + "pin-project-lite 0.2.17 registry+https://github.com/rust-lang/crates.io-index", "proc-macro2 1.0.106 registry+https://github.com/rust-lang/crates.io-index", "quote 1.0.45 registry+https://github.com/rust-lang/crates.io-index", + "ref-cast 1.0.25 registry+https://github.com/rust-lang/crates.io-index", + "ref-cast-impl 1.0.25 registry+https://github.com/rust-lang/crates.io-index", + "rustc-demangle 0.1.27 registry+https://github.com/rust-lang/crates.io-index", "rustix 1.1.4 registry+https://github.com/rust-lang/crates.io-index", + "schemars 1.2.1 registry+https://github.com/rust-lang/crates.io-index", + "schemars_derive 1.2.1 registry+https://github.com/rust-lang/crates.io-index", + "serde 1.0.228 registry+https://github.com/rust-lang/crates.io-index", + "serde_core 1.0.228 registry+https://github.com/rust-lang/crates.io-index", + "serde_derive 1.0.228 registry+https://github.com/rust-lang/crates.io-index", + "serde_derive_internals 0.29.1 registry+https://github.com/rust-lang/crates.io-index", + "serde_json 1.0.149 registry+https://github.com/rust-lang/crates.io-index", + "serde_json_lenient 0.2.4 registry+https://github.com/rust-lang/crates.io-index", + "sharded-slab 0.1.7 registry+https://github.com/rust-lang/crates.io-index", "strsim 0.11.1 registry+https://github.com/rust-lang/crates.io-index", "syn 2.0.117 registry+https://github.com/rust-lang/crates.io-index", "terminal_size 0.4.4 registry+https://github.com/rust-lang/crates.io-index", + "thread_local 1.1.9 registry+https://github.com/rust-lang/crates.io-index", + "tracing 0.1.44 registry+https://github.com/rust-lang/crates.io-index", + "tracing-core 0.1.36 registry+https://github.com/rust-lang/crates.io-index", + "tracing-error 0.2.1 registry+https://github.com/rust-lang/crates.io-index", + "tracing-subscriber 0.3.23 registry+https://github.com/rust-lang/crates.io-index", "unicode-ident 1.0.24 registry+https://github.com/rust-lang/crates.io-index", "utf8parse 0.2.2 registry+https://github.com/rust-lang/crates.io-index", + "windows 0.62.2 registry+https://github.com/rust-lang/crates.io-index", + "windows-collections 0.3.2 registry+https://github.com/rust-lang/crates.io-index", + "windows-core 0.62.2 registry+https://github.com/rust-lang/crates.io-index", + "windows-future 0.3.2 registry+https://github.com/rust-lang/crates.io-index", + "windows-implement 0.60.2 registry+https://github.com/rust-lang/crates.io-index", + "windows-interface 0.59.3 registry+https://github.com/rust-lang/crates.io-index", + "windows-link 0.2.1 registry+https://github.com/rust-lang/crates.io-index", + "windows-numerics 0.3.1 registry+https://github.com/rust-lang/crates.io-index", + "windows-result 0.4.1 registry+https://github.com/rust-lang/crates.io-index", + "windows-strings 0.5.1 registry+https://github.com/rust-lang/crates.io-index", "windows-sys 0.52.0 registry+https://github.com/rust-lang/crates.io-index", "windows-sys 0.59.0 registry+https://github.com/rust-lang/crates.io-index", "windows-sys 0.60.2 registry+https://github.com/rust-lang/crates.io-index", "windows-targets 0.52.6 registry+https://github.com/rust-lang/crates.io-index", "windows-targets 0.53.5 registry+https://github.com/rust-lang/crates.io-index", + "windows-threading 0.2.1 registry+https://github.com/rust-lang/crates.io-index", "windows_x86_64_msvc 0.52.6 registry+https://github.com/rust-lang/crates.io-index", - "windows_x86_64_msvc 0.53.1 registry+https://github.com/rust-lang/crates.io-index" + "windows_x86_64_msvc 0.53.1 registry+https://github.com/rust-lang/crates.io-index", + "zmij 1.0.21 registry+https://github.com/rust-lang/crates.io-index" ] ], [ @@ -88,6 +185,18 @@ [ "unicode-ident 1.0.24 registry+https://github.com/rust-lang/crates.io-index" ] + ], + [ + "Unlicense", + [ + "memchr 2.8.0 registry+https://github.com/rust-lang/crates.io-index" + ] + ], + [ + "Zlib", + [ + "miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index" + ] ] ] } diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 00000000..3261fc18 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,51 @@ +# Architecture + +`komorebi-recorder` connects three things that do not know about each other: komorebi, which says what it is doing in +a log and in events on a socket; the operating system, which says what it is doing in its own trace and shows it on a +screen; and the person or agent who has to work out why they disagreed. It records all of them on one clock into a +session directory, and reads that directory back. + +Two things about it vary independently, and everything below is arranged so that neither leaks into the other. + +| axis | what varies | where the variation lives | what a session records | +|---|---|---|---| +| host | the OS the recorder runs on: macOS or Windows (a third `unsupported` host builds anywhere) | [`platform`](../komorebi-recorder/src/platform/mod.rs), selected by `cfg` | `host` in the manifest | + +## The master clock + +Everything in a session is stamped on one clock: the host's monotonic clock, in nanoseconds. That is +`mach_absolute_time` on macOS and `QueryPerformanceCounter` on Windows. Video frames and the OS trace are already on it. +komorebi's log lines carry UTC wall-clock time, so they are mapped onto it: the recorder samples a paired reading of +both clocks (an `Anchor`) at the start, every few seconds and at every sleep, and a `ClockMap` interpolates between +them. A `JumpDetector` notices sleep and clock steps by comparing how far each clock moved between two observations, +and the anchors on either side of the jump are what make the mapping right on both sides of it. + +Three things are worth knowing before reading a session: + +- The field names ending in `_mach_ns` keep their historical spelling. They hold master-clock nanoseconds on whichever + host recorded the session; the manifest's `host.clock` says which clock that was (`mach`, `qpc` or `std`). A name that + changed would stop older sessions being readable by newer builds and the reverse. +- The master clock is not the wall clock. On macOS it pauses while the machine sleeps, so video time skips a sleep + instead of showing a hole. Whether the performance counter counts a suspend on Windows is measured, not assumed. +- A timestamp is a plain `u64` of nanoseconds. Nothing in the type system says which clock it is on: that is held by + convention, and by the tests that place records at known times. + +## The platform facade + +The rest of the crate never names a system API. [`platform`](../komorebi-recorder/src/platform/mod.rs) is a facade of +small modules (`clock`, `shell` and, as the recorder grows, `capture`, `power`, `session`, `trace`, `process`, `apps` +and `window`), and `cfg` selects the directory behind it: `platform/macos/`, `platform/win/` or `platform/unsupported.rs`. +Each host provides the same names with the same signatures. A missing or mismatched function is a compile error on the +host being built, and on no other, so the Windows host is built from a Mac by `just check-windows` and by CI, and +`unsupported` (which exists so that the commands that only read a session directory work on a Linux agent box) is built +only on a third OS. + +Where one host has no analogue of something, the facade function exists on both and one answers "nothing": `trace::start` +on the `unsupported` host returns no taps and a line saying so, and `power::start` returns no watcher. + +## Rules and the layer that enforces them + +| Rule | Enforced by | +|---|---| +| Every host provides the same functions with the same signatures | the compiler, for the host being built; `just check-windows` and CI build the Windows host from a Mac; nothing builds `unsupported` | +| A timestamp in a session is on the master clock | convention, and the tests that place records at known times: the type is a plain `u64` | diff --git a/docs/PLATFORM.md b/docs/PLATFORM.md new file mode 100644 index 00000000..1c7f9cb3 --- /dev/null +++ b/docs/PLATFORM.md @@ -0,0 +1,66 @@ +# Platform support + +This document gathers, in one place, what differs by operating system. Most of the details are written down on the items +that implement them; here the same questions are answered once per host, so that someone who has to run the recorder on +a machine, or change it for one, does not have to read the code to find out. + +The recorder is built for macOS and Windows. A third host, `unsupported`, builds on anything else so that the commands +that only read a session directory work on a Linux agent box; recording there says that it cannot. + +## Status + +| host | built | run | +|---|---|---| +| macOS (Apple silicon) | yes | yes: written and run on macOS 26 | +| Windows x86_64 | yes, natively on `windows-latest` and cross-compiled from a Mac | no: type-checked and cross-built only | +| Windows ARM64 | yes, cross-built on an x86_64 runner | no | +| anything else | the `unsupported` host builds | nothing records | + +Nothing that touches a real Windows desktop has been seen running: the Windows host was written from the Windows API +documentation and komorebi for Windows' source, and every claim below about Windows says what the code does, not what +was observed. + +## Vocabulary + +- **Host**: the OS the recorder runs on. It decides how the screen is captured, which clock is read, how the OS says it + is going to sleep and what the OS trace is made of. +- **Flavor**: which komorebi is being recorded. There is one per OS, and a recorder watches the one on its own host, but + a session records its flavor, so a session from either can be read on either host. +- **Master clock**: the host's monotonic clock, in nanoseconds, on which every record in a session is stamped. +- **Session**: the directory a recording is written to. +- **Segment**: one contiguous stretch of one display's video, a file of its own. A display that is unplugged and plugged + in again has two. + +## The same questions, per host + +### The master clock + +| | macOS | Windows | unsupported | +|---|---|---|---| +| clock | `mach_absolute_time`, scaled by `mach_timebase_info` | `QueryPerformanceCounter`, scaled by `QueryPerformanceFrequency` (10 MHz when Windows will not say) | the time since the first reading in the process, plus one second so that no reading is zero | +| `host.clock` in the manifest | `mach` | `qpc` | `std` | +| counts the time the machine sleeps | no | not known: measured, not assumed | no | +| other clocks read beside it | `mach_continuous_time`, which counts sleep | `QueryInterruptTime`, which counts sleep, and `QueryUnbiasedInterruptTimePrecise`, which does not | none | + +Video frame times and the OS trace are on the master clock already on both hosts (ScreenCaptureKit and the unified log's +`machTimestamp` on a Mac; Windows.Graphics.Capture on Windows). The field names ending in `_mach_ns` are spelled that way +on every host: see [the architecture](ARCHITECTURE.md#the-master-clock). + +## Degraded modes + +- `record --no-video` records everything but the screen, on the same clock. It asks the system nothing about displays and + needs no permission. +- `record --no-komorebi` skips touching komorebi altogether, and `--no-oslog` skips the OS trace. +- A komorebi that is not running when a recording starts is not an error: it is noted, and the recorder subscribes when + it appears. +- The `unsupported` host investigates sessions and refuses to record. + +## Advice by audience + +- **Recording on macOS.** Grant Screen Recording to the terminal, and start komorebi with `--log-level trace`. +- **Recording on Windows.** There is nothing to grant. Use `komorebi-recorder.exe` for commands, since the GUI build + prints nowhere, and start komorebi with `--log-level debug` and `RUST_LOG=komorebi=debug`. +- **Investigating on any host.** A session is read the same everywhere. `ffmpeg` is needed only for `frames` and + `selftest`. +- **Changing code that has a host-specific part.** Provide the function on every host, and run `just check-windows` from a + Mac: it type-checks every `cfg(windows)` line, tests included. diff --git a/komorebi-recorder/Cargo.toml b/komorebi-recorder/Cargo.toml index 2f21686b..30a1ac9d 100644 --- a/komorebi-recorder/Cargo.toml +++ b/komorebi-recorder/Cargo.toml @@ -7,3 +7,50 @@ repository.workspace = true [dependencies] clap = { workspace = true } +color-eyre = { workspace = true } +schemars = { workspace = true } +serde = { workspace = true } +serde_json = { workspace = true } + +[target.'cfg(target_os = "macos")'.dependencies] +libc = "0.2" + +[target.'cfg(windows)'.dependencies] +windows = { version = "0.62", features = [ + "Foundation", + "Graphics", + "Graphics_Capture", + "Graphics_DirectX", + "Graphics_DirectX_Direct3D11", + "Wdk_System_SystemServices", + "Win32_Foundation", + "Win32_Graphics_Direct3D", + "Win32_Graphics_Direct3D11", + "Win32_Graphics_Dwm", + "Win32_Graphics_Dxgi", + "Win32_Graphics_Dxgi_Common", + "Win32_Graphics_Gdi", + "Win32_Media", + "Win32_Media_MediaFoundation", + "Win32_System_Com", + "Win32_System_Com_StructuredStorage", + "Win32_System_EventLog", + "Win32_System_LibraryLoader", + "Win32_System_Performance", + "Win32_System_Power", + "Win32_System_RemoteDesktop", + "Win32_System_StationsAndDesktops", + "Win32_System_SystemInformation", + "Win32_System_SystemServices", + "Win32_System_Threading", + "Win32_System_Variant", + "Win32_System_WinRT", + "Win32_System_WinRT_Direct3D11", + "Win32_System_WinRT_Graphics_Capture", + "Win32_System_WindowsProgramming", + "Win32_UI_Accessibility", + "Win32_UI_HiDpi", + "Win32_UI_Shell", + "Win32_UI_Shell_Common", + "Win32_UI_WindowsAndMessaging", +] } diff --git a/komorebi-recorder/src/clock.rs b/komorebi-recorder/src/clock.rs new file mode 100644 index 00000000..9c3e6863 --- /dev/null +++ b/komorebi-recorder/src/clock.rs @@ -0,0 +1,949 @@ +//! The master clock: the one monotonic clock every record in a session is stamped on, and the +//! conversions between it, the wall clock and video time. +//! +//! Every source in a recording is expressed in nanoseconds on one host monotonic clock: capture +//! frame timestamps, the OS trace, komorebi's subscriber events, incidents. komorebi's own log +//! lines are the exception. They carry a UTC wall clock time, and are mapped +//! onto the master clock with the [`Anchor`]s sampled while recording. +//! +//! # Which clock is the master clock +//! +//! [`mono_now_ns`] reads it, through [`crate::platform::clock`], and [`Host::clock`] names it: the +//! field holds the [`ClockKind`] the session was recorded with, which the manifest stores as +//! `host.clock`. It does not name the wall clock, or any [`ReferenceClock`]. +//! +//! | [`ClockKind`] | `host.clock` | read with | +//! |---|---|---| +//! | [`Mach`](crate::platform::ClockKind::Mach) | `mach` | `mach_absolute_time`, on macOS | +//! | [`Qpc`](crate::platform::ClockKind::Qpc) | `qpc` | `QueryPerformanceCounter`, on Windows | +//! | [`Std`](crate::platform::ClockKind::Std) | `std` | [`std::time::Instant`] since the first reading in the process, plus one second so that it is never zero, on a host with no capture | +//! +//! `mach_absolute_time` pauses while the machine sleeps. Whether the Windows counter does is not +//! assumed: `doctor --probe clock` measures it, and where the OS can announce a sleep the +//! recorder listens for it (`platform::power`) rather than inferring it from the clocks alone. +//! +//! The `*_mach_ns` field names throughout a session are historical: they mean "master monotonic +//! nanoseconds", whichever clock that was, and keeping them means a session written by any build +//! is readable by any other. `host.clock` is what says which clock the numbers are on. +//! +//! # The four scales +//! +//! | Scale | Unit | Where it appears | Converted with | +//! |---|---|---|---| +//! | host ticks | ticks of the OS counter | raw counter reads, the unified log's `machTimestamp` | [`Timebase`] | +//! | master clock | nanoseconds, `u64` | every `*_mach_ns` field | (the scale the others convert to and from) | +//! | wall time | microseconds since the Unix epoch, `i64`, UTC | komorebi's log lines, every `wall_us` field | [`ClockMap`] | +//! | video time | seconds, `f64`, since the first captured frame | timecodes (see [`crate::timecode`]), `video_s` fields | subtracting the master clock time of video `t = 0` | +//! +//! Video `t = 0` is the master clock time of the earliest first frame across displays, recorded in +//! the manifest as `video_t0_mach_ns`; with no frame at all it is the recording's start. A time +//! before the first frame is negative. The session manifest's `video_seconds` and +//! `mach_at_video_seconds` do that subtraction in each direction. +//! +//! # How the pieces relate +//! +//! * [`Timebase`] says what one host tick is worth. It is read from the OS once ([`timebase`]), +//! and stored in the manifest, so that a session recorded on one machine is read on another with +//! the tick size of the machine that recorded it. +//! * [`Anchor`] pairs one wall clock reading with the master clock time at which it was made. +//! The recording loop samples one about every 5 seconds, and one on either side of every sleep. +//! * [`ClockMap`] is built from a session's anchors, and maps between wall time and the master +//! clock by interpolating between them. +//! * [`JumpDetector`] compares the wall clock with the master clock over each loop iteration, and +//! reports a [`Jump`] when they disagree. The two anchors of a [`Jump`] are the pair of anchors +//! [`ClockMap`] needs to treat a sleep as a step, rather than as drift. +//! * [`ReferenceClock`] is another host clock, read next to the master clock so that a probe can +//! say what the master clock does across a sleep. +//! +//! # Example: ticks, master clock, wall time and video time +//! +//! ```rust +//! use komorebi_recorder::clock::{Anchor, ClockMap, Timebase}; +//! +//! // a counter that ticks at 24 MHz, which is 125/3 nanoseconds a tick +//! let timebase = Timebase::from_frequency(24_000_000); +//! assert_eq!(timebase, Timebase { numer: 125, denom: 3 }); +//! +//! // host ticks -> master clock nanoseconds +//! let mach_ns = timebase.ticks_to_ns(2_400_000_000); +//! assert_eq!(mach_ns, 100_000_000_000); +//! +//! // two anchors taken 5 seconds apart, as the recorder does +//! let map = ClockMap::new(vec![ +//! Anchor { wall_us: 1_800_000_000_000_000, mach_ns: 100_000_000_000 }, +//! Anchor { wall_us: 1_800_000_005_000_000, mach_ns: 105_000_000_000 }, +//! ]); +//! +//! // master clock -> wall time, and back +//! let wall_us = map.mach_to_wall(102_500_000_000).expect("the map has anchors"); +//! assert_eq!(wall_us, 1_800_000_002_500_000); +//! assert_eq!(map.wall_to_mach(wall_us), Some(102_500_000_000)); +//! +//! // master clock -> video time, for a first frame that was captured at 101 s on the master clock +//! let video_t0_mach_ns = 101_000_000_000_i128; +//! let video_s = (102_500_000_000_i128 - video_t0_mach_ns) as f64 / 1e9; +//! assert_eq!(video_s, 1.5); +//! +//! // and back, from video time to the master clock +//! assert_eq!(video_t0_mach_ns + (video_s * 1e9).round() as i128, 102_500_000_000); +//! +//! // a time before the first frame is negative in video time +//! assert_eq!((100_500_000_000_i128 - video_t0_mach_ns) as f64 / 1e9, -0.5); +//! ``` +//! +//! [`Host::clock`]: crate::platform::Host::clock +//! [`ClockKind`]: crate::platform::ClockKind + +use crate::platform; +use serde::Deserialize; +use serde::Serialize; +use std::time::SystemTime; +use std::time::UNIX_EPOCH; + +/// The size of one tick of the host clock: `numer / denom` nanoseconds. +/// +/// It is read from the OS once ([`timebase`]) and stored in a session's manifest as `timebase`, so +/// that a session recorded on one machine is converted with the tick size of the machine that +/// recorded it, and not with the reader's. The unified log's `machTimestamp` is in ticks of this +/// size, and the manifest's timebase is what converts it. +/// +/// A timebase this crate produces has a non-zero `numer` and `denom`. The fields are public and +/// are read back from `session.json`, so a hand-edited manifest can hold zeros, which make +/// [`ticks_to_ns`](Timebase::ticks_to_ns) and [`ns_to_ticks`](Timebase::ns_to_ticks) panic. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::clock::Timebase; +/// +/// // Apple silicon's counter: 24 MHz, so 125/3 nanoseconds a tick +/// let timebase = Timebase { numer: 125, denom: 3 }; +/// assert_eq!(timebase.ticks_to_ns(24_000_000), 1_000_000_000); +/// assert_eq!(timebase.ns_to_ticks(1_000_000_000), 24_000_000); +/// ``` +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub struct Timebase { + /// The numerator of the nanoseconds a tick is worth. + pub numer: u32, + /// The denominator of the nanoseconds a tick is worth. + pub denom: u32, +} + +impl Timebase { + /// Returns the timebase of a counter that ticks `hertz` times a second, as + /// `QueryPerformanceCounter` does. + /// + /// One tick is `1e9 / hertz` nanoseconds. The fraction is reduced, so a 10 MHz counter is + /// `100/1`, not `1000000000/10000000`. A counter faster than about 4.29 GHz has a reduced + /// denominator that does not fit in a `u32`: both parts are then halved until they do, which + /// keeps the ratio approximately. A `hertz` of zero is treated as one. + /// + /// The result always has a non-zero `numer` and `denom`. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::clock::Timebase; + /// + /// // the usual `QueryPerformanceFrequency`: 10 MHz, which is 100 ns a tick + /// assert_eq!(Timebase::from_frequency(10_000_000), Timebase { numer: 100, denom: 1 }); + /// + /// // Apple silicon's counter + /// assert_eq!(Timebase::from_frequency(24_000_000), Timebase { numer: 125, denom: 3 }); + /// + /// // a nanosecond counter, and a nonsense zero, are both fine + /// assert_eq!(Timebase::from_frequency(1_000_000_000), Timebase { numer: 1, denom: 1 }); + /// assert_eq!(Timebase::from_frequency(0).ticks_to_ns(5), 5_000_000_000); + /// ``` + #[must_use] + pub fn from_frequency(hertz: u64) -> Self { + fn gcd(a: u64, b: u64) -> u64 { + if b == 0 { a } else { gcd(b, a % b) } + } + + let hertz = hertz.max(1); + let divisor = gcd(1_000_000_000, hertz); + let (mut numer, mut denom) = (1_000_000_000 / divisor, hertz / divisor); + while numer > u64::from(u32::MAX) || denom > u64::from(u32::MAX) { + numer = (numer / 2).max(1); + denom = (denom / 2).max(1); + } + + Self { + numer: numer as u32, + denom: denom as u32, + } + } + + /// Returns `ticks` host clock ticks as nanoseconds: `ticks * numer / denom`. + /// + /// The product is computed in 128 bits, so it cannot overflow, and the quotient is truncated + /// toward zero. A result that does not fit in a `u64` is truncated to its low 64 bits. + /// + /// # Panics + /// + /// Panics if `denom` is zero. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::clock::Timebase; + /// + /// let timebase = Timebase { numer: 125, denom: 3 }; + /// assert_eq!(timebase.ticks_to_ns(24_000_000), 1_000_000_000); + /// + /// // one tick is 41.67 ns, truncated + /// assert_eq!(timebase.ticks_to_ns(1), 41); + /// ``` + #[must_use] + pub fn ticks_to_ns(self, ticks: u64) -> u64 { + (u128::from(ticks) * u128::from(self.numer) / u128::from(self.denom)) as u64 + } + + /// Returns `ns` nanoseconds as host clock ticks: `ns * denom / numer`. + /// + /// The product is computed in 128 bits, so it cannot overflow, and the quotient is truncated + /// toward zero. A result that does not fit in a `u64` is truncated to its low 64 bits. + /// + /// # Panics + /// + /// Panics if `numer` is zero. + /// + /// # Example: a round trip can lose a tick + /// + /// Both directions truncate, so a tick count that goes to nanoseconds and back comes back + /// equal only when the nanoseconds were exact: + /// + /// ```rust + /// use komorebi_recorder::clock::Timebase; + /// + /// let timebase = Timebase { numer: 125, denom: 3 }; + /// assert_eq!(timebase.ns_to_ticks(timebase.ticks_to_ns(24_000_000)), 24_000_000); + /// assert_eq!(timebase.ns_to_ticks(timebase.ticks_to_ns(1)), 0); + /// ``` + #[must_use] + pub fn ns_to_ticks(self, ns: u64) -> u64 { + (u128::from(ns) * u128::from(self.denom) / u128::from(self.numer)) as u64 + } +} + +/// Returns what one tick of the host clock is worth in nanoseconds. +/// +/// It is the host's own: from `mach_timebase_info` on macOS (125/3 on Apple silicon, and 1/1 if the +/// OS reports an unusable one), from [`Timebase::from_frequency`] of `QueryPerformanceFrequency` on +/// Windows (10 MHz if that cannot be read), and 1/1 on a host with no capture, whose clock already +/// counts nanoseconds. A session records the timebase it was written with in its manifest; use that +/// one, not this, to convert a recorded session's ticks. +#[must_use] +pub fn timebase() -> Timebase { + platform::clock::timebase() +} + +/// Another clock the host has, read alongside the master clock to find out what the master clock +/// does while the machine sleeps. +/// +/// A reference clock is never used to stamp a record. `doctor` reads each one together with the +/// master clock and the wall clock, and reports how far each moved across a sleep. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, schemars::JsonSchema)] +pub struct ReferenceClock { + /// The name of the OS clock, as the OS spells it (`mach_continuous_time`). + pub name: String, + /// Whether it keeps counting while the machine is suspended. + pub counts_sleep: bool, + /// Its reading, in nanoseconds from an origin that the clock chooses: only differences between + /// two readings of the same clock mean anything. + pub ns: u64, +} + +/// Returns a reading of each of the host's other clocks (see [`ReferenceClock`]). +/// +/// On macOS that is `mach_continuous_time`, which counts the time the machine sleeps. On Windows +/// it is `QueryInterruptTime`, which counts it, and `QueryUnbiasedInterruptTimePrecise`, which +/// does not. A host with no capture has none. +#[must_use] +pub fn reference_clocks() -> Vec { + platform::clock::reference_clocks() +} + +/// Returns the master clock in nanoseconds: the host monotonic clock every record in a session is +/// on. +/// +/// On macOS this is `mach_absolute_time`, which pauses while the machine sleeps; on Windows it is +/// `QueryPerformanceCounter`. The `*_mach_ns` fields in a session keep their historical names and +/// hold this value; the manifest's `host.clock` says which clock it was. +/// +/// The origin is chosen by the OS, so a reading means something only next to another reading of the +/// same clock. The clock is monotonic: it does not go backwards, and `doctor` reports whether it +/// did while it was read. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::clock::mono_now_ns; +/// +/// let first = mono_now_ns(); +/// let second = mono_now_ns(); +/// assert!(second >= first); +/// ``` +#[must_use] +pub fn mono_now_ns() -> u64 { + platform::clock::now_ns() +} + +/// Returns the wall clock in microseconds since the Unix epoch (UTC). +/// +/// Unlike [`mono_now_ns`], the wall clock can be stepped, forwards or backwards, by the user or by +/// time synchronization, and keeps counting while the machine sleeps. A time before 1970, which +/// means the clock is badly wrong, is returned as a negative number rather than as an error. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::clock::wall_now_us; +/// +/// // after 2020-01-01 and before 2100-01-01 +/// let now = wall_now_us(); +/// assert!(now > 1_577_836_800_000_000); +/// assert!(now < 4_102_444_800_000_000); +/// ``` +#[must_use] +pub fn wall_now_us() -> i64 { + match SystemTime::now().duration_since(UNIX_EPOCH) { + Ok(since) => since.as_micros() as i64, + // before 1970: the clock is badly wrong, but a negative time is still a time + Err(before) => -(before.duration().as_micros() as i64), + } +} + +/// A paired reading of the wall clock and the master clock: the master clock time at which the +/// wall clock read `wall_us`. +/// +/// An anchor is the only link between komorebi's log, which is stamped with the wall clock, and +/// everything else, which is on the master clock. A session keeps a series of them in its manifest +/// (`anchors`), and [`ClockMap`] interpolates between them. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::clock::{wall_now_us, Anchor}; +/// +/// let anchor = Anchor::sample(); +/// // the wall clock was read a moment ago +/// assert!((wall_now_us() - anchor.wall_us).abs() < 1_000_000); +/// ``` +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub struct Anchor { + /// The wall clock, in microseconds since the Unix epoch (UTC). + pub wall_us: i64, + /// The master clock, in nanoseconds, at the same moment. + pub mach_ns: u64, +} + +impl Anchor { + /// Takes a tight paired reading: several back-to-back samples, keeping the one whose wall read + /// was bracketed by the narrowest pair of mach reads, which bounds the pairing error to the + /// duration of a couple of syscalls. + /// + /// Seven samples are taken. The `mach_ns` of the one kept is the midpoint of the two master + /// clock reads around its wall clock read. + #[must_use] + pub fn sample() -> Self { + let mut best: Option<(u64, Anchor)> = None; + for _ in 0..7 { + let before = mono_now_ns(); + let wall_us = wall_now_us(); + let after = mono_now_ns(); + let width = after.saturating_sub(before); + let anchor = Anchor { + wall_us, + mach_ns: before + width / 2, + }; + + if best.is_none_or(|(best_width, _)| width < best_width) { + best = Some((width, anchor)); + } + } + + best.map(|(_, anchor)| anchor).unwrap_or_else(|| Anchor { + wall_us: wall_now_us(), + mach_ns: mono_now_ns(), + }) + } + + /// The wall clock minus the mach clock, in microseconds. + fn offset_us(self) -> i128 { + i128::from(self.wall_us) - i128::from(self.mach_ns / 1_000) + } +} + +/// How far the wall clock must outrun the mach clock between two close observations for it to +/// count as a jump. Observations are made every ~50 ms, so ordinary drift is microseconds. +const JUMP_THRESHOLD_NS: i128 = 1_000_000_000; + +/// A discontinuity between the wall clock and the master clock, as [`JumpDetector::observe`] +/// reports it. +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct Jump { + /// How far the wall clock moved beyond the master clock, in seconds. Positive: the machine + /// slept (mach time pauses while asleep, wall time does not) or the clock stepped forward. + /// Negative: the wall clock was stepped back. + pub seconds: f64, + /// The last good pairing before the jump: the previous observation. + pub before: Anchor, + /// The first pairing after the jump: the observation that found it. + pub after: Anchor, +} + +/// Notices sleep/wake and clock steps by watching both clocks. +/// +/// Feed it a fresh [`Anchor`] every loop iteration. When the two clocks disagree about how much +/// time passed since the previous observation, the machine was suspended (or the clock was +/// stepped), and the two anchors on either side of the discontinuity are exactly what +/// [`ClockMap`] needs to map wall time to mach time correctly on both sides of it. +/// +/// The detector is a state machine with one piece of state, the previous observation. It reports a +/// [`Jump`] when the wall clock and the master clock moved by amounts that differ by 1 second or +/// more since then. Observations are expected about every 50 ms, so ordinary drift is +/// microseconds, and a process that was merely descheduled for a long time is not a jump, because +/// both clocks moved together. A suspension shorter than 1 second is not reported. +/// +/// On a host whose master clock keeps counting through a sleep, the two clocks do not disagree and +/// a sleep is not noticed this way: see the module docs, and `PowerTracker` for the OS's own +/// announcement of a sleep. +/// +/// # Example: noticing a sleep, and mapping time across it +/// +/// ```rust +/// use komorebi_recorder::clock::{Anchor, ClockMap, JumpDetector}; +/// +/// // wall time 2000 s and master clock time 1000 s are the same moment +/// let start = Anchor { wall_us: 2_000_000_000, mach_ns: 1_000_000_000_000 }; +/// let mut detector = JumpDetector::new(start); +/// +/// // 50 ms later on both clocks: nothing to report +/// let before = Anchor { wall_us: 2_000_050_000, mach_ns: 1_000_050_000_000 }; +/// assert_eq!(detector.observe(before), None); +/// +/// // the lid is closed for an hour: the wall clock moves on, the master clock barely does +/// let after = Anchor { +/// wall_us: 2_000_100_000 + 3_600_000_000, +/// mach_ns: 1_000_100_000_000, +/// }; +/// let jump = detector.observe(after).expect("the clocks disagree by an hour"); +/// assert!((jump.seconds - 3_600.0).abs() < 0.01); +/// assert_eq!((jump.before, jump.after), (before, after)); +/// +/// // with both anchors in the map, wall time maps correctly on either side of the sleep +/// let map = ClockMap::new(vec![jump.before, jump.after]); +/// assert_eq!(map.wall_to_mach(2_000_050_000), Some(1_000_050_000_000)); +/// let two_seconds_after_waking = after.wall_us + 2_000_000; +/// assert_eq!(map.wall_to_mach(two_seconds_after_waking), Some(1_002_100_000_000)); +/// +/// // the detector carries on from the new position +/// let later = Anchor { wall_us: after.wall_us + 50_000, mach_ns: after.mach_ns + 50_000_000 }; +/// assert_eq!(detector.observe(later), None); +/// ``` +#[derive(Debug, Clone, Copy)] +pub struct JumpDetector { + last: Anchor, +} + +impl JumpDetector { + /// Returns a detector whose previous observation is `first`. + #[must_use] + pub fn new(first: Anchor) -> Self { + Self { last: first } + } + + /// Compares `now` with the previous observation, and makes `now` the previous observation. + /// + /// Returns a [`Jump`] if the wall clock and the master clock moved by amounts that differ by + /// at least 1 second, in either direction, and `None` otherwise. The observation is recorded + /// either way, so one discontinuity is reported once. + pub fn observe(&mut self, now: Anchor) -> Option { + let wall_ns = (i128::from(now.wall_us) - i128::from(self.last.wall_us)) * 1_000; + let mach_ns = i128::from(now.mach_ns) - i128::from(self.last.mach_ns); + let difference = wall_ns - mach_ns; + let before = std::mem::replace(&mut self.last, now); + + (difference.abs() >= JUMP_THRESHOLD_NS).then_some(Jump { + seconds: difference as f64 / 1e9, + before, + after: now, + }) + } +} + +/// Segments whose wall and mach durations disagree by more than this are treated as a clock step +/// (an NTP jump, or the machine sleeping while the mach clock was paused) rather than as drift. +const STEP_THRESHOLD_NS: i128 = 20_000_000; + +/// A two-way map between wall clock time and the master clock, built by piecewise-linear +/// interpolation between the anchors sampled during a recording. +/// +/// A map is built from a session's anchors (the manifest's `anchors`) and answers in both +/// directions: [`wall_to_mach`] turns a wall clock time, such as one of komorebi's log lines, into +/// the master clock, and [`mach_to_wall`] does the reverse, to show a master clock time as UTC. +/// +/// Each pair of neighboring anchors, ordered by master clock time, is a segment. The wall clock +/// and the master clock tick at slightly different rates, so inside a segment a time is +/// interpolated linearly. If the two clocks moved by amounts that differ by more than 20 ms over a +/// segment, the segment holds a step rather than drift: the machine slept while the master clock +/// was paused, or the wall clock was stepped. Where in the segment the step happened is not +/// known, so a time inside it is taken from the nearer of the segment's two anchors, using that +/// anchor's offset between the clocks. Outside the first and last anchors, a time is taken +/// from the nearer end in the same way. With a single anchor, the map is a constant offset. +/// +/// Both directions return `None` if, and only if, the map has no anchors. +/// +/// A sleep inside a segment is placed at the nearer anchor, which is why the recorder adds an +/// anchor on either side of every sleep it finds (see [`JumpDetector`]). +/// +/// The anchors of a map are guaranteed to be sorted by master clock time, with no two at the same +/// time, because [`ClockMap::new`] is the only way to make one that has any: the field is private. +/// +/// ```rust,compile_fail,E0451 +/// use komorebi_recorder::clock::{Anchor, ClockMap}; +/// +/// // an unsorted list of anchors, which `ClockMap::new` would put in order +/// let anchors = vec![ +/// Anchor { wall_us: 2_005_000_000, mach_ns: 1_005_000_000_000 }, +/// Anchor { wall_us: 2_000_000_000, mach_ns: 1_000_000_000_000 }, +/// ]; +/// let _map = ClockMap { anchors }; +/// ``` +/// +/// # Example: a clock step +/// +/// ```rust +/// use komorebi_recorder::clock::{Anchor, ClockMap}; +/// +/// let at = |wall_s: i64, mach_s: u64| Anchor { +/// wall_us: wall_s * 1_000_000, +/// mach_ns: mach_s * 1_000_000_000, +/// }; +/// +/// // the wall clock jumps forward 30 s between the second and third anchors, while the master +/// // clock moves 5 s: the machine slept, or the clock was stepped +/// let map = ClockMap::new(vec![at(2000, 1000), at(2005, 1005), at(2040, 1010)]); +/// +/// // before the step, the clocks are 1000 s apart +/// assert_eq!(map.wall_to_mach(2_001_000_000), Some(1_001_000_000_000)); +/// // after it, 1030 s apart +/// assert_eq!(map.wall_to_mach(2_039_000_000), Some(1_009_000_000_000)); +/// // and the other direction agrees on both sides +/// assert_eq!(map.mach_to_wall(1_001_000_000_000), Some(2_001_000_000)); +/// assert_eq!(map.mach_to_wall(1_009_000_000_000), Some(2_039_000_000)); +/// +/// // an empty map has no answer +/// assert_eq!(ClockMap::default().wall_to_mach(1), None); +/// ``` +/// +/// [`wall_to_mach`]: ClockMap::wall_to_mach +/// [`mach_to_wall`]: ClockMap::mach_to_wall +#[derive(Debug, Clone, Default)] +pub struct ClockMap { + anchors: Vec, +} + +impl ClockMap { + /// Returns a map over `anchors`, which may be given in any order. + /// + /// The anchors are sorted by master clock time, and of several with the same master clock time + /// only the first given is kept. + #[must_use] + pub fn new(mut anchors: Vec) -> Self { + anchors.sort_by_key(|anchor| anchor.mach_ns); + anchors.dedup_by_key(|anchor| anchor.mach_ns); + Self { anchors } + } + + /// Returns the anchors the map was built from, ascending by master clock time, with no two + /// sharing a master clock time. + #[must_use] + pub fn anchors(&self) -> &[Anchor] { + &self.anchors + } + + /// Returns true if and only if the map has no anchors, in which case every lookup returns + /// `None`. + #[must_use] + pub fn is_empty(&self) -> bool { + self.anchors.is_empty() + } + + /// Whether the segment between two anchors contains a clock step rather than plain drift. + fn is_step(a: Anchor, b: Anchor) -> bool { + let wall_ns = (i128::from(b.wall_us) - i128::from(a.wall_us)) * 1_000; + let mach_ns = i128::from(b.mach_ns) - i128::from(a.mach_ns); + (wall_ns - mach_ns).abs() > STEP_THRESHOLD_NS + } + + /// Returns the master clock time, in nanoseconds, of the wall clock time `wall_us` + /// (microseconds since the Unix epoch), or `None` if the map has no anchors. + /// + /// The result is never negative: a time that maps before the origin of the master clock is + /// returned as zero. If the wall clock was stepped back, two segments can contain the same wall + /// clock time; the segment earlier in master clock time is used. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::clock::{Anchor, ClockMap}; + /// + /// // wall = master + 1000 s, with the wall clock running slightly fast between the anchors + /// let map = ClockMap::new(vec![ + /// Anchor { wall_us: 2_000_000_000, mach_ns: 1_000_000_000_000 }, + /// Anchor { wall_us: 2_005_000_500, mach_ns: 1_005_000_000_000 }, + /// ]); + /// + /// // halfway between them, interpolated + /// assert_eq!(map.wall_to_mach(2_002_500_250), Some(1_002_500_000_000)); + /// + /// // outside them, extended from the nearer end at a constant offset + /// assert_eq!(map.wall_to_mach(1_999_000_000), Some(999_000_000_000)); + /// assert_eq!(map.wall_to_mach(2_010_000_500), Some(1_010_000_000_000)); + /// ``` + #[must_use] + pub fn wall_to_mach(&self, wall_us: i64) -> Option { + let (first, last) = (*self.anchors.first()?, *self.anchors.last()?); + let extrapolate = |anchor: Anchor| { + let mach = i128::from(wall_us) - anchor.offset_us(); + (mach * 1_000).max(0) as u64 + }; + + if self.anchors.len() == 1 { + return Some(extrapolate(first)); + } + + for pair in self.anchors.windows(2) { + let (a, b) = (pair[0], pair[1]); + let (lo, hi) = (a.wall_us.min(b.wall_us), a.wall_us.max(b.wall_us)); + if wall_us < lo || wall_us > hi { + continue; + } + + if Self::is_step(a, b) { + // we cannot know when inside the segment the step happened, so trust whichever + // end is closer in wall time + let nearest = if (wall_us - a.wall_us).abs() <= (wall_us - b.wall_us).abs() { + a + } else { + b + }; + return Some(extrapolate(nearest)); + } + + let wall_span = i128::from(b.wall_us) - i128::from(a.wall_us); + if wall_span == 0 { + return Some(a.mach_ns); + } + + let mach_span = i128::from(b.mach_ns) - i128::from(a.mach_ns); + let into = i128::from(wall_us) - i128::from(a.wall_us); + return Some((i128::from(a.mach_ns) + into * mach_span / wall_span).max(0) as u64); + } + + // outside every segment: extend from whichever end is nearest in wall time + let nearest = if (wall_us - first.wall_us).abs() <= (wall_us - last.wall_us).abs() { + first + } else { + last + }; + Some(extrapolate(nearest)) + } + + /// Returns the wall clock time, in microseconds since the Unix epoch, of the master clock time + /// `mach_ns`, or `None` if the map has no anchors. + /// + /// The master clock has a resolution finer than a microsecond, and the result is truncated to + /// whole microseconds. Within a segment that holds no step, a wall clock time taken through + /// [`wall_to_mach`](ClockMap::wall_to_mach) and back comes back within 1 microsecond (the test + /// `roundtrips_within_a_microsecond`); that is not guaranteed across a step. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::clock::{Anchor, ClockMap}; + /// + /// let map = ClockMap::new(vec![ + /// Anchor { wall_us: 2_000_000_000, mach_ns: 1_000_000_000_000 }, + /// Anchor { wall_us: 2_005_000_000, mach_ns: 1_005_000_000_000 }, + /// ]); + /// + /// let wall_us = map.mach_to_wall(1_002_345_678_000).expect("the map has anchors"); + /// assert_eq!(wall_us, 2_002_345_678); + /// + /// let back = map.wall_to_mach(wall_us).expect("the map has anchors"); + /// assert_eq!(back, 1_002_345_678_000); + /// ``` + #[must_use] + pub fn mach_to_wall(&self, mach_ns: u64) -> Option { + let (first, last) = (*self.anchors.first()?, *self.anchors.last()?); + let extrapolate = |anchor: Anchor| { + let wall = i128::from(mach_ns / 1_000) + anchor.offset_us(); + wall as i64 + }; + + if mach_ns <= first.mach_ns { + return Some(extrapolate(first)); + } + + if mach_ns >= last.mach_ns { + return Some(extrapolate(last)); + } + + for pair in self.anchors.windows(2) { + let (a, b) = (pair[0], pair[1]); + if mach_ns < a.mach_ns || mach_ns > b.mach_ns { + continue; + } + + if Self::is_step(a, b) { + let nearest = if mach_ns - a.mach_ns <= b.mach_ns - mach_ns { + a + } else { + b + }; + return Some(extrapolate(nearest)); + } + + let mach_span = i128::from(b.mach_ns) - i128::from(a.mach_ns); + let wall_span = i128::from(b.wall_us) - i128::from(a.wall_us); + let into = i128::from(mach_ns) - i128::from(a.mach_ns); + return Some((i128::from(a.wall_us) + into * wall_span / mach_span) as i64); + } + + Some(extrapolate(last)) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn anchor(wall_s: i64, mach_s: u64) -> Anchor { + Anchor { + wall_us: wall_s * 1_000_000, + mach_ns: mach_s * 1_000_000_000, + } + } + + #[test] + fn a_counters_frequency_is_a_timebase() { + // the usual QueryPerformanceFrequency: 10 MHz, 100 ns a tick + let ten_mhz = Timebase::from_frequency(10_000_000); + assert_eq!( + ten_mhz, + Timebase { + numer: 100, + denom: 1 + } + ); + assert_eq!(ten_mhz.ticks_to_ns(10_000_000), 1_000_000_000); + assert_eq!(ten_mhz.ns_to_ticks(1_000_000_000), 10_000_000); + + // one that does not divide evenly + let odd = Timebase::from_frequency(3_579_545); + let one_second = odd.ns_to_ticks(1_000_000_000); + assert!( + (3_579_544..=3_579_546).contains(&one_second), + "{one_second}" + ); + + // a nanosecond counter, and a nonsense zero, are both fine + assert_eq!( + Timebase::from_frequency(1_000_000_000), + Timebase { numer: 1, denom: 1 } + ); + assert_eq!(Timebase::from_frequency(0).ticks_to_ns(5), 5_000_000_000); + + // faster than u32 can hold: still close + let fast = Timebase::from_frequency(10_000_000_000); + assert!(fast.ticks_to_ns(10_000_000_000).abs_diff(1_000_000_000) < 10_000_000); + } + + #[test] + fn timebase_roundtrip() { + let tb = Timebase { + numer: 125, + denom: 3, + }; + let ns = tb.ticks_to_ns(24_000_000); + assert_eq!(ns, 1_000_000_000); + assert_eq!(tb.ns_to_ticks(ns), 24_000_000); + } + + #[test] + fn mach_is_monotonic_and_wall_is_sane() { + let a = mono_now_ns(); + let b = mono_now_ns(); + assert!(b >= a); + // after 2020 and before 2100 + assert!(wall_now_us() > 1_577_836_800_000_000); + assert!(wall_now_us() < 4_102_444_800_000_000); + } + + #[test] + fn anchor_sample_is_close_to_now() { + let anchor = Anchor::sample(); + let now = wall_now_us(); + assert!((now - anchor.wall_us).abs() < 50_000); + } + + #[test] + fn interpolates_between_anchors() { + // wall = mach + 1000s, with the wall clock running 100ppm fast over the segment + let a = anchor(2000, 1000); + let b = Anchor { + wall_us: 2005 * 1_000_000 + 500, + mach_ns: 1005 * 1_000_000_000, + }; + let map = ClockMap::new(vec![a, b]); + + let mach = map.wall_to_mach(2_002_500_000 + 250).expect("mach"); + assert_eq!(mach, 1_002_500_000_000); + + let wall = map.mach_to_wall(1_002_500_000_000).expect("wall"); + assert_eq!(wall, 2_002_500_000 + 250); + } + + #[test] + fn roundtrips_within_a_microsecond() { + let map = ClockMap::new(vec![ + anchor(2000, 1000), + anchor(2005, 1005), + anchor(2010, 1010), + ]); + for wall in [2_000_123_456, 2_004_999_999, 2_007_777_777, 2_009_000_001] { + let mach = map.wall_to_mach(wall).expect("mach"); + let back = map.mach_to_wall(mach).expect("wall"); + assert!((back - wall).abs() <= 1, "{wall} -> {mach} -> {back}"); + } + } + + #[test] + fn extrapolates_outside_the_anchor_range() { + let map = ClockMap::new(vec![anchor(2000, 1000), anchor(2005, 1005)]); + assert_eq!( + map.wall_to_mach(1_999_000_000), + Some(999_000_000_000), + "before the first anchor" + ); + assert_eq!( + map.wall_to_mach(2_010_000_000), + Some(1_010_000_000_000), + "after the last anchor" + ); + } + + #[test] + fn handles_a_clock_step() { + // the wall clock jumps forward 30s between the second and third anchors (an NTP step, or + // the machine slept while mach time was paused) + let map = ClockMap::new(vec![ + anchor(2000, 1000), + anchor(2005, 1005), + anchor(2040, 1010), + ]); + + // before the step the offset is 1000s + assert_eq!(map.wall_to_mach(2_001_000_000), Some(1_001_000_000_000)); + // after the step the offset is 1030s + assert_eq!(map.wall_to_mach(2_039_000_000), Some(1_009_000_000_000)); + // and mach -> wall agrees on both sides + assert_eq!(map.mach_to_wall(1_001_000_000_000), Some(2_001_000_000)); + assert_eq!(map.mach_to_wall(1_009_000_000_000), Some(2_039_000_000)); + } + + #[test] + fn single_anchor_is_a_constant_offset() { + let map = ClockMap::new(vec![anchor(2000, 1000)]); + assert_eq!(map.wall_to_mach(2_003_000_000), Some(1_003_000_000_000)); + assert_eq!(map.mach_to_wall(1_003_000_000_000), Some(2_003_000_000)); + } + + #[test] + fn the_jump_detector_ignores_ordinary_time_passing() { + let mut detector = JumpDetector::new(anchor(2000, 1000)); + // 50 ms later on both clocks, with a little drift + let tick = |wall_us: i64, mach_ns: u64| Anchor { wall_us, mach_ns }; + assert_eq!( + detector.observe(tick(2_000_050_010, 1_000_050_000_000)), + None + ); + // a long but consistent interval (the process was merely descheduled) + assert_eq!( + detector.observe(tick(2_030_050_010, 1_030_050_000_000)), + None + ); + } + + #[test] + fn the_jump_detector_notices_sleep_and_brackets_it() { + let mut detector = JumpDetector::new(anchor(2000, 1000)); + let before = Anchor { + wall_us: 2_000_050_000, + mach_ns: 1_000_050_000_000, + }; + assert_eq!(detector.observe(before), None); + + // the lid is closed for 3600 s: wall time moves on, mach time barely does + let after = Anchor { + wall_us: 2_000_100_000 + 3_600_000_000, + mach_ns: 1_000_100_000_000, + }; + let jump = detector.observe(after).expect("a jump"); + assert!((jump.seconds - 3_600.0).abs() < 0.01, "{}", jump.seconds); + assert_eq!( + jump.before, before, + "the last good pairing before the sleep" + ); + assert_eq!(jump.after, after); + + // and with those two anchors the map is right on both sides of the sleep + let map = ClockMap::new(vec![jump.before, jump.after]); + assert_eq!(map.wall_to_mach(2_000_050_000), Some(1_000_050_000_000)); + assert_eq!( + map.wall_to_mach(2_000_100_000 + 3_600_000_000), + Some(1_000_100_000_000) + ); + assert_eq!( + map.wall_to_mach(2_000_100_000 + 3_600_000_000 + 2_000_000), + Some(1_000_100_000_000 + 2_000_000_000), + "two seconds after waking" + ); + + // the detector carries on from the new position + assert_eq!( + detector.observe(Anchor { + wall_us: after.wall_us + 50_000, + mach_ns: after.mach_ns + 50_000_000 + }), + None + ); + } + + #[test] + fn the_jump_detector_notices_the_clock_stepping_back() { + let mut detector = JumpDetector::new(anchor(2000, 1000)); + let jump = detector + .observe(Anchor { + wall_us: 2_000_050_000 - 30_000_000, + mach_ns: 1_000_050_000_000, + }) + .expect("a jump"); + assert!( + jump.seconds < -29.0 && jump.seconds > -31.0, + "{}", + jump.seconds + ); + } + + #[test] + fn empty_map_has_no_answer() { + let map = ClockMap::default(); + assert_eq!(map.wall_to_mach(1), None); + assert_eq!(map.mach_to_wall(1), None); + } +} diff --git a/komorebi-recorder/src/lib.rs b/komorebi-recorder/src/lib.rs index a6d80956..a095a17d 100644 --- a/komorebi-recorder/src/lib.rs +++ b/komorebi-recorder/src/lib.rs @@ -8,3 +8,52 @@ //! This crate is the library behind the `komorebi-recorder` command. A reader who wants to run it should start with the //! [README](https://github.com/LGUG2Z/komorebi-recorder#readme); this documentation is for someone who is changing it, //! or reading a session directory from a program of their own. +//! +//! # The model +//! +//! Two things vary independently. The _host_ is the OS the recorder runs on, and everything that differs by it is behind +//! [`platform`]. The _flavor_ is the komorebi being recorded, komorebi for Mac or komorebi for Windows, and everything +//! that differs by it is behind a trait in the analysis. A session records both, so a session recorded on one host can +//! be read on the other. +//! +//! Every record in a session is stamped on one monotonic clock, the _master clock_ ([`clock`]). Video frames and the OS +//! trace are already on it; komorebi's log lines carry wall-clock time and are mapped onto it with paired readings of +//! both clocks. For example, a log line stamped five seconds after the first of two anchors that are ten seconds apart +//! is five seconds after it on the master clock too: +//! +//! ```rust +//! use komorebi_recorder::clock::Anchor; +//! use komorebi_recorder::clock::ClockMap; +//! +//! let map = ClockMap::new(vec![ +//! Anchor { wall_us: 1_000_000, mach_ns: 5_000_000_000 }, +//! Anchor { wall_us: 11_000_000, mach_ns: 15_000_000_000 }, +//! ]); +//! +//! assert_eq!(map.wall_to_mach(6_000_000), Some(10_000_000_000)); +//! ``` +//! +//! # Where to start +//! +//! The modules, from the ones everything else uses to the ones that use everything: +//! +//! | module | what it is | +//! |---|---| +//! | [`timecode`] | parsing and printing video timecodes | +//! | [`clock`] | the master clock, anchors and the map between the wall clock and the master clock | +//! | [`platform`] | everything that differs by host, behind one facade | +//! +//! # What is not supported +//! +//! The recorder does not change komorebi's log level or lifecycle, it does not need `sudo` and changes no SIP setting on +//! a Mac, and it does not trace system calls. A session records what komorebi, the OS trace and the screen said, and +//! nothing from before the recording began. +//! +//! # Platform support +//! +//! The Windows host is type-checked and cross-built from a Mac and built on Windows in CI, and has never been run. See +//! [`platform`] for what each host provides. + +pub mod clock; +pub mod platform; +pub mod timecode; diff --git a/komorebi-recorder/src/platform/macos/clock.rs b/komorebi-recorder/src/platform/macos/clock.rs new file mode 100644 index 00000000..e913b387 --- /dev/null +++ b/komorebi-recorder/src/platform/macos/clock.rs @@ -0,0 +1,112 @@ +//! The master clock on macOS: `mach_absolute_time`, the clock `ScreenCaptureKit` and the unified +//! log already use. +//! +//! Every time in a session is nanoseconds on this clock (see [`crate::clock`]). It counts ticks of +//! a size the OS reports ([`timebase`]) and pauses while the machine sleeps, so a sleep shows up as +//! the wall clock moving on while this one does not. [`reference_clocks`] reads the clock that does +//! keep counting through a sleep. +//! +//! The same items exist on Windows, where the clock is `QueryPerformanceCounter`. + +use crate::clock::Timebase; +use crate::platform::ClockKind; +use std::sync::OnceLock; + +/// Which clock the master clock is: [`ClockKind::Mach`], recorded as `host.clock` in the manifest. +pub const KIND: ClockKind = ClockKind::Mach; + +#[repr(C)] +struct MachTimebaseInfo { + numer: u32, + denom: u32, +} + +// `libc` marks its mach bindings deprecated in favour of the `mach2` crate; these two symbols +// are all we need from libSystem, so declare them directly instead of adding a dependency +unsafe extern "C" { + fn mach_absolute_time() -> u64; + fn mach_continuous_time() -> u64; + fn mach_timebase_info(info: *mut MachTimebaseInfo) -> i32; +} + +/// Returns what one tick of [`now_ticks`] is worth, as `numer / denom` nanoseconds. +/// +/// It is read from `mach_timebase_info` once and kept. If the OS reports no usable timebase (which +/// a Mac that can run this always does), it is `1 / 1`. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::platform::clock::{now_ns, now_ticks, timebase}; +/// +/// // the master clock is the tick count scaled by the timebase, and never goes backwards +/// let ns = timebase().ticks_to_ns(now_ticks()); +/// assert!(now_ns() >= ns); +/// ``` +#[must_use] +pub fn timebase() -> Timebase { + static TIMEBASE: OnceLock = OnceLock::new(); + *TIMEBASE.get_or_init(|| { + let mut info = MachTimebaseInfo { numer: 0, denom: 0 }; + // SAFETY: `info` is a valid out pointer for the duration of the call + let status = unsafe { mach_timebase_info(&raw mut info) }; + if status != 0 || info.denom == 0 { + // every Mac that can run this has a valid timebase; 1/1 is the safe identity + return Timebase { numer: 1, denom: 1 }; + } + + Timebase { + numer: info.numer, + denom: info.denom, + } + }) +} + +/// Returns the raw tick count of `mach_absolute_time`, which pauses while the machine sleeps. +#[must_use] +pub fn now_ticks() -> u64 { + // SAFETY: no preconditions + unsafe { mach_absolute_time() } +} + +/// Returns nanoseconds on the host monotonic clock: the master clock every record in a session is +/// on. It is [`now_ticks`] scaled by [`timebase`], so it pauses while the machine sleeps. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::platform::clock::now_ns; +/// +/// let first = now_ns(); +/// let second = now_ns(); +/// assert!(second >= first); +/// ``` +#[must_use] +pub fn now_ns() -> u64 { + timebase().ticks_to_ns(now_ticks()) +} + +/// Returns the host's other clocks, to be read beside the master clock: one, +/// `mach_continuous_time`, which counts the time the machine spends asleep, unlike the master +/// clock. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::platform::clock::reference_clocks; +/// +/// let clocks = reference_clocks(); +/// assert_eq!(clocks.len(), 1); +/// assert_eq!(clocks[0].name, "mach_continuous_time"); +/// assert!(clocks[0].counts_sleep); +/// ``` +#[must_use] +pub fn reference_clocks() -> Vec { + // SAFETY: no preconditions + let ticks = unsafe { mach_continuous_time() }; + vec![crate::clock::ReferenceClock { + name: "mach_continuous_time".to_string(), + counts_sleep: true, + ns: timebase().ticks_to_ns(ticks), + }] +} diff --git a/komorebi-recorder/src/platform/macos/mod.rs b/komorebi-recorder/src/platform/macos/mod.rs new file mode 100644 index 00000000..89dd8331 --- /dev/null +++ b/komorebi-recorder/src/platform/macos/mod.rs @@ -0,0 +1,22 @@ +//! The macOS host: what the [`platform`](crate::platform) facade is made of on a Mac. +//! +//! | module | built on | +//! |---|---| +//! | `apps` | the window server's window list (`CGWindowListCopyWindowInfo`) | +//! | `capture` | `ScreenCaptureKit` and `AVFoundation` (in `crate::capture::sck`) | +//! | `clock` | `mach_absolute_time` | +//! | `power` | nothing: a Mac's sleep is found from the clocks, so there is no watcher | +//! | `process` | process groups and `SIGTERM` | +//! | `session` | the CoreGraphics session dictionary | +//! | `shell` | `open`, `osascript` and `sw_vers` | +//! | `trace` | nothing: the OS trace is `log stream` children (`crate::sources::oslog`), not taps | +//! +//! 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 clock; +pub mod shell; + +/// Does nothing: a Mac needs nothing done once at the start of `main`. (Windows makes the process +/// DPI aware.) +pub fn init() {} diff --git a/komorebi-recorder/src/platform/macos/shell.rs b/komorebi-recorder/src/platform/macos/shell.rs new file mode 100644 index 00000000..102de6b0 --- /dev/null +++ b/komorebi-recorder/src/platform/macos/shell.rs @@ -0,0 +1,72 @@ +//! Showing a folder, asking for one, and naming the OS. +//! +//! The recorder window offers to show a finished session in the file manager, the viewer asks for +//! a session folder, and the manifest records the OS version. On macOS these are `open`, +//! `osascript` and `sw_vers`; the same items exist on Windows. + +use std::path::Path; +use std::path::PathBuf; +use std::process::Command; + +/// What the OS calls its file manager, for button labels: `Finder`. +pub const FILE_MANAGER: &str = "Finder"; + +/// Returns the OS version as `sw_vers -productVersion` prints it, e.g. `26.0`, or `None` if that +/// cannot be run or prints nothing. On Windows it is `major.minor.build`. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::platform::shell::{FILE_MANAGER, os_version}; +/// +/// assert_eq!(FILE_MANAGER, "Finder"); +/// if let Some(version) = os_version() { +/// assert!(version.chars().all(|c| c.is_ascii_digit() || c == '.'), "{version}"); +/// } +/// ``` +#[must_use] +pub fn os_version() -> Option { + let output = Command::new("/usr/bin/sw_vers") + .arg("-productVersion") + .output() + .ok()?; + let version = String::from_utf8(output.stdout).ok()?.trim().to_string(); + (!version.is_empty()).then_some(version) +} + +/// Shows `path` in the file manager. +/// +/// This runs `open path` and does not wait for it, and a failure to start it is not reported. A +/// folder opens in Finder. A file opens in its default application, not selected in Finder (`open +/// -R` would select it); the recorder only passes folders. On Windows a file is selected in its +/// folder. +/// +/// This starts another program, so it has no doctest. +pub fn reveal(path: &Path) { + let _ = Command::new("open").arg(path).spawn(); +} + +/// Asks the user for a folder with the system's own dialog, and blocks until they answer. +/// +/// Returns the folder they chose, or `None` if they canceled, the dialog could not be shown, or +/// the path came back empty. `prompt` is the dialog's prompt text. It is not escaped: it is placed +/// inside an `AppleScript` string, so it should not contain `"` or `\`. +/// +/// This shows a dialog, so it has no doctest. +#[must_use] +pub fn pick_folder(prompt: &str) -> Option { + let output = Command::new("osascript") + .args([ + "-e", + &format!("POSIX path of (choose folder with prompt \"{prompt}\")"), + ]) + .output() + .ok()?; + + output + .status + .success() + .then(|| String::from_utf8_lossy(&output.stdout).trim().to_string()) + .filter(|path| !path.is_empty()) + .map(PathBuf::from) +} diff --git a/komorebi-recorder/src/platform/mod.rs b/komorebi-recorder/src/platform/mod.rs new file mode 100644 index 00000000..bb531186 --- /dev/null +++ b/komorebi-recorder/src/platform/mod.rs @@ -0,0 +1,181 @@ +//! Everything that differs by the OS the recorder runs on. +//! +//! The rest of the crate never names a system API. It asks this module for the handful of things +//! that are not portable, and each host provides them: +//! +//! | module | what it answers | +//! |---|---| +//! | [`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 | +//! +//! 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. +//! +//! # The host axis +//! +//! This is the *host* axis: what the recorder is running on. +//! Which komorebi produced a session is a separate axis, the *flavor*: a session recorded on +//! Windows can be investigated on a Mac, and the [`Host`] a session was recorded on is part of its +//! manifest. +//! +//! # Adding a function +//! +//! A function that the rest of the crate calls as `platform::::` has to exist, with +//! the same signature, in `macos/.rs`, `win/.rs` and `unsupported.rs`. The +//! compiler enforces that for the host being built, and for no other: the Windows host is built +//! from a Mac by `just check-windows` and by CI, and `unsupported` is built only on a third OS, +//! where nothing in CI builds it. + +#[cfg(target_os = "macos")] +mod macos; +#[cfg(target_os = "macos")] +use macos as imp; + +#[cfg(not(any(target_os = "macos", windows)))] +mod unsupported; +#[cfg(not(any(target_os = "macos", windows)))] +use unsupported as imp; + +// not `windows`: that would be ambiguous with the `windows` crate in every `use` of this module +#[cfg(windows)] +mod win; +#[cfg(windows)] +use win as imp; + +pub use imp::clock; +pub use imp::shell; + +/// Things the OS wants done once, first thing in `main`: on Windows, becoming DPI aware so that +/// sizes and positions are in physical pixels. Nothing on other hosts. +pub fn init() { + imp::init(); +} + +use schemars::JsonSchema; +use serde::Deserialize; +use serde::Serialize; + +/// Which master clock a session's `*_mach_ns` values are on. +/// +/// The field names keep their historical `mach_` spelling so that sessions stay readable by every +/// build of the tool; what they hold is "nanoseconds on the host's monotonic clock", and this says +/// which clock that was. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +#[serde(rename_all = "lowercase")] +pub enum ClockKind { + /// `mach_absolute_time`: pauses while the machine sleeps. + Mach, + /// `QueryPerformanceCounter`. + Qpc, + /// A host with no capture, which still needs some monotonic clock to run on. + Std, +} + +/// What a session was recorded on. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::platform::ClockKind; +/// use komorebi_recorder::platform::Host; +/// +/// // a session from before hosts were recorded can only have been recorded on a Mac +/// let host = Host::legacy_macos(Some("26.0".to_string())); +/// assert!(host.is_macos() && !host.is_windows()); +/// assert_eq!(host.clock, ClockKind::Mach); +/// assert_eq!(host.describe(), "macOS 26.0"); +/// ``` +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +pub struct Host { + /// `macos`, `windows`, ... + pub os: String, + /// The CPU architecture, as Rust names it (`aarch64`, `x86_64`). + pub arch: String, + /// The OS version, if the host could say (`26.0` on macOS, `10.0.26100` on Windows). + pub os_version: Option, + /// Which clock the session's `*_mach_ns` values are on. + pub clock: ClockKind, +} + +impl Host { + /// The machine this process is running on. + #[must_use] + pub fn current() -> Self { + Self { + os: std::env::consts::OS.to_string(), + arch: std::env::consts::ARCH.to_string(), + os_version: shell::os_version(), + clock: clock::KIND, + } + } + + /// What a session from before hosts were recorded was recorded on: it can only have been a Mac. + #[must_use] + pub fn legacy_macos(os_version: Option) -> Self { + Self { + os: "macos".to_string(), + arch: "aarch64".to_string(), + os_version, + clock: ClockKind::Mach, + } + } + + #[must_use] + /// Returns `true` if and only if this is macOS. + pub fn is_macos(&self) -> bool { + self.os == "macos" + } + + #[must_use] + /// Returns `true` if and only if this is Windows. + pub fn is_windows(&self) -> bool { + self.os == "windows" + } + + /// `macOS 26.0`, `windows 10.0.26100`: for prose. + #[must_use] + pub fn describe(&self) -> String { + let os = match self.os.as_str() { + "macos" => "macOS", + "windows" => "Windows", + other => other, + }; + match &self.os_version { + Some(version) => format!("{os} {version}"), + None => os.to_string(), + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_host_reads_back_what_it_wrote() { + let host = Host::current(); + let text = serde_json::to_string(&host).expect("serialize"); + let back: Host = serde_json::from_str(&text).expect("parse"); + assert_eq!(back, host); + } + + #[test] + fn the_clock_kind_is_spelled_in_lowercase() { + assert_eq!( + serde_json::to_string(&ClockKind::Qpc).expect("serialize"), + r#""qpc""# + ); + assert_eq!( + serde_json::to_string(&ClockKind::Mach).expect("serialize"), + r#""mach""# + ); + } + + #[test] + fn a_session_from_before_hosts_were_recorded_was_a_mac() { + let host = Host::legacy_macos(Some("26.0".into())); + assert!(host.is_macos()); + assert_eq!(host.describe(), "macOS 26.0"); + assert_eq!(host.clock, ClockKind::Mach); + } +} diff --git a/komorebi-recorder/src/platform/unsupported.rs b/komorebi-recorder/src/platform/unsupported.rs new file mode 100644 index 00000000..28f79691 --- /dev/null +++ b/komorebi-recorder/src/platform/unsupported.rs @@ -0,0 +1,62 @@ +//! Any other OS: enough to build and to investigate a session directory that was recorded +//! elsewhere (the commands that only read files), but not to record one. + +/// Nothing to do first. +pub fn init() {} + +/// The master clock, which here is Rust's monotonic [`Instant`]. +pub mod clock { + use crate::clock::Timebase; + use crate::platform::ClockKind; + use std::sync::OnceLock; + use std::time::Instant; + + /// The clock a session recorded here is on: Rust's [`Instant`]. + pub const KIND: ClockKind = ClockKind::Std; + + /// Returns the identity timebase: [`now_ns`] is already in nanoseconds. + #[must_use] + pub fn timebase() -> Timebase { + Timebase { numer: 1, denom: 1 } + } + + /// Returns no other clocks. + #[must_use] + pub fn reference_clocks() -> Vec { + Vec::new() + } + + /// Nanoseconds since the first reading in this process, offset so that none is ever zero + /// (zero means "not yet" in the capture counters). + #[must_use] + pub fn now_ns() -> u64 { + static START: OnceLock = OnceLock::new(); + START.get_or_init(Instant::now).elapsed().as_nanos() as u64 + 1_000_000_000 + } +} + +/// Showing a folder, asking for one, and naming the OS, with what this host can offer. +pub mod shell { + use std::path::Path; + use std::path::PathBuf; + + /// What this host calls its file manager, for button labels. + pub const FILE_MANAGER: &str = "file manager"; + + /// Returns `None`: this host cannot say which version it is. + #[must_use] + pub fn os_version() -> Option { + None + } + + /// Asks `xdg-open` to show `path`. + pub fn reveal(path: &Path) { + let _ = std::process::Command::new("xdg-open").arg(path).spawn(); + } + + /// Returns `None`: this host has no dialog to ask with. + #[must_use] + pub fn pick_folder(_prompt: &str) -> Option { + None + } +} diff --git a/komorebi-recorder/src/platform/win/clock.rs b/komorebi-recorder/src/platform/win/clock.rs new file mode 100644 index 00000000..1320ab50 --- /dev/null +++ b/komorebi-recorder/src/platform/win/clock.rs @@ -0,0 +1,83 @@ +//! The master clock on Windows: `QueryPerformanceCounter`, the clock Windows.Graphics.Capture frame +//! times are on. +//! +//! Every time in a session is nanoseconds on this clock (see [`crate::clock`]). It counts ticks of +//! a size the OS reports ([`timebase`]). Whether it keeps counting while the machine sleeps is not +//! assumed: `doctor --probe clock` measures it, using the two clocks of [`reference_clocks`], and +//! the power watcher (`crate::platform::power`) says when a sleep happens either way. +//! +//! The same items exist on macOS, where the clock is `mach_absolute_time`. + +use crate::clock::Timebase; +use crate::platform::ClockKind; +use std::sync::OnceLock; +use windows::Win32::System::Performance::QueryPerformanceCounter; +use windows::Win32::System::Performance::QueryPerformanceFrequency; +use windows::Win32::System::WindowsProgramming::QueryInterruptTime; +use windows::Win32::System::WindowsProgramming::QueryUnbiasedInterruptTimePrecise; + +/// Which clock the master clock is: [`ClockKind::Qpc`], recorded as `host.clock` in the manifest. +pub const KIND: ClockKind = ClockKind::Qpc; + +/// Returns what one tick of [`now_ticks`] is worth, as `numer / denom` nanoseconds. +/// +/// It is made from `QueryPerformanceFrequency` once and kept. If that cannot be read, which it +/// cannot do on any Windows that runs this, the frequency is taken to be 10 MHz, which is what it +/// is nearly everywhere. +#[must_use] +pub fn timebase() -> Timebase { + static TIMEBASE: OnceLock = OnceLock::new(); + *TIMEBASE.get_or_init(|| { + let mut frequency = 0_i64; + // SAFETY: `frequency` is a valid out pointer for the duration of the call + let known = unsafe { QueryPerformanceFrequency(&raw mut frequency) }.is_ok(); + // it cannot fail on any Windows that runs this; 10 MHz is what it says nearly everywhere + Timebase::from_frequency(if known && frequency > 0 { + frequency as u64 + } else { + 10_000_000 + }) + }) +} + +/// Returns the raw `QueryPerformanceCounter` tick count. A negative reading, which does not +/// happen, is `0`. +#[must_use] +pub fn now_ticks() -> u64 { + let mut ticks = 0_i64; + // SAFETY: `ticks` is a valid out pointer for the duration of the call + let _ = unsafe { QueryPerformanceCounter(&raw mut ticks) }; + ticks.max(0) as u64 +} + +/// Returns nanoseconds on the host monotonic clock: the master clock every record in a session is +/// on. It is [`now_ticks`] scaled by [`timebase`]. +#[must_use] +pub fn now_ns() -> u64 { + timebase().ticks_to_ns(now_ticks()) +} + +/// Returns the host's other clocks, to be read beside the master clock: the two interrupt-time +/// clocks. +/// +/// `QueryInterruptTime` counts the time the machine is suspended and +/// `QueryUnbiasedInterruptTimePrecise` does not. Both are read in 100 ns units and returned in +/// nanoseconds. Which of them the performance counter behaves like is what decides how a sleep +/// can be noticed. +#[must_use] +pub fn reference_clocks() -> Vec { + // SAFETY: no preconditions + let (biased, unbiased) = unsafe { (QueryInterruptTime(), QueryUnbiasedInterruptTimePrecise()) }; + vec![ + crate::clock::ReferenceClock { + name: "QueryInterruptTime".to_string(), + counts_sleep: true, + ns: biased.saturating_mul(100), + }, + crate::clock::ReferenceClock { + name: "QueryUnbiasedInterruptTimePrecise".to_string(), + counts_sleep: false, + ns: unbiased.saturating_mul(100), + }, + ] +} diff --git a/komorebi-recorder/src/platform/win/mod.rs b/komorebi-recorder/src/platform/win/mod.rs new file mode 100644 index 00000000..bffd4cbe --- /dev/null +++ b/komorebi-recorder/src/platform/win/mod.rs @@ -0,0 +1,33 @@ +//! The Windows host: what the [`platform`](crate::platform) facade is made of on Windows. +//! +//! | module | built on | +//! |---|---| +//! | `apps` | `EnumWindows` and `GetWindowThreadProcessId` | +//! | `capture` | monitor enumeration and per-monitor DPI; the capture itself is Windows.Graphics.Capture (in `crate::capture::wgc`) | +//! | `clock` | `QueryPerformanceCounter` | +//! | `media` | Windows Runtime and Media Foundation start-up, shared by the capture and the decoder | +//! | `power` | a hidden window that is sent suspend, resume, lid, display and session messages | +//! | `process` | process creation flags and `TerminateProcess` | +//! | `session` | whether the input desktop can be opened | +//! | `shell` | Explorer, the folder dialog and `RtlGetVersion` | +//! | `trace` | a `WinEvent` hook and Event Log subscriptions (see `crate::sources::wintrace`) | +//! | `window` | this program's own windows and the reads about any window | +//! +//! Nothing here is public API except through the facade: this module is private, and the facade +//! re-exports its submodules (all but `window`, which the shared `platform::window` calls) under the +//! same names as on the other hosts. +//! +//! This code is compiled only for Windows. From another host it is type-checked and linted with +//! `just check-windows`, and the checklist for running it on a real machine is +//! `docs/dev/windows-checkpoints.md`. + +pub mod clock; +pub mod shell; + +/// Does what Windows needs once, first thing in `main`: makes the process per-monitor DPI aware +/// ([`capture::become_per_monitor_dpi_aware`]), so that every size and position it reads is in +/// physical pixels, as komorebi's are. A Mac needs nothing here. +pub fn init() { + // Without this Windows lies to us about sizes: a display scaled to 150 % reads as smaller than + // it is, and komorebi's rects (which are physical pixels) would not match ours. +} diff --git a/komorebi-recorder/src/platform/win/shell.rs b/komorebi-recorder/src/platform/win/shell.rs new file mode 100644 index 00000000..bd75dc55 --- /dev/null +++ b/komorebi-recorder/src/platform/win/shell.rs @@ -0,0 +1,111 @@ +//! Showing a folder, asking for one, and naming the OS. +//! +//! The recorder window offers to show a finished session in the file manager, the viewer asks for +//! a session folder, and the manifest records the OS version. On Windows these are Explorer, the +//! common file dialog and `RtlGetVersion`; the same items exist on macOS. + +use std::path::Path; +use std::path::PathBuf; +use std::process::Command; +use windows::Wdk::System::SystemServices::RtlGetVersion; +use windows::Win32::System::Com::CLSCTX_INPROC_SERVER; +use windows::Win32::System::Com::COINIT_APARTMENTTHREADED; +use windows::Win32::System::Com::CoCreateInstance; +use windows::Win32::System::Com::CoInitializeEx; +use windows::Win32::System::Com::CoTaskMemFree; +use windows::Win32::System::Com::CoUninitialize; +use windows::Win32::System::SystemInformation::OSVERSIONINFOW; +use windows::Win32::UI::Shell::FOS_FORCEFILESYSTEM; +use windows::Win32::UI::Shell::FOS_PICKFOLDERS; +use windows::Win32::UI::Shell::FileOpenDialog; +use windows::Win32::UI::Shell::IFileOpenDialog; +use windows::Win32::UI::Shell::SIGDN_FILESYSPATH; +use windows::core::PCWSTR; + +/// What the OS calls its file manager, for button labels: `Explorer`. +pub const FILE_MANAGER: &str = "Explorer"; + +/// Returns the Windows version as `major.minor.build`, e.g. `10.0.26100`, or `None` if it cannot be +/// read. On macOS it is the product version, e.g. `26.0`. +/// +/// This is `RtlGetVersion`, because the documented `GetVersionEx` lies to a program without a +/// manifest saying which Windows it was made for. +#[must_use] +pub fn os_version() -> Option { + let mut info = OSVERSIONINFOW { + dwOSVersionInfoSize: size_of::() as u32, + ..Default::default() + }; + // SAFETY: `info` is a valid, correctly sized out structure + let status = unsafe { RtlGetVersion(&raw mut info) }; + status.is_ok().then(|| { + format!( + "{}.{}.{}", + info.dwMajorVersion, info.dwMinorVersion, info.dwBuildNumber + ) + }) +} + +/// Shows `path` in the file manager: a folder is opened, a file is selected in its folder. +/// +/// This starts `explorer` and does not wait for it; Explorer exits with status 1 even when it +/// worked, so only starting it is checked, and a failure to start it is not reported. On macOS a +/// file is opened in its default application instead of being selected. +pub fn reveal(path: &Path) { + let mut command = Command::new("explorer"); + if path.is_file() { + let mut select = std::ffi::OsString::from("/select,"); + select.push(path); + command.arg(select); + } else { + command.arg(path); + } + + // explorer exits with 1 even when it worked; only starting it matters + let _ = command.spawn(); +} + +/// Asks the user for a folder with the system's own dialog, and blocks until they answer. +/// +/// Returns the folder they chose, or `None` if they canceled, the dialog could not be shown, or +/// the path came back empty. `prompt` is the dialog's title. The dialog is made on the calling +/// thread, which is given a COM apartment for the duration unless it already has one. +#[must_use] +pub fn pick_folder(prompt: &str) -> Option { + // SAFETY: COM is initialised for this thread for the duration of the dialog and released after + // (unless some other code had initialised it differently, in which case it is theirs to release) + unsafe { + let initialised = CoInitializeEx(None, COINIT_APARTMENTTHREADED).is_ok(); + let chosen = pick(prompt); + if initialised { + CoUninitialize(); + } + chosen + } +} + +/// # Safety +/// COM must be initialized on the calling thread. +unsafe fn pick(prompt: &str) -> Option { + // SAFETY: the caller initialised COM; every pointer below is owned by a COM wrapper or freed + unsafe { + let dialog: IFileOpenDialog = + CoCreateInstance(&FileOpenDialog, None, CLSCTX_INPROC_SERVER).ok()?; + let options = dialog.GetOptions().ok()?; + dialog + .SetOptions(options | FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM) + .ok()?; + + let title: Vec = prompt.encode_utf16().chain(Some(0)).collect(); + dialog.SetTitle(PCWSTR(title.as_ptr())).ok()?; + + // cancelling is an error as far as COM is concerned + dialog.Show(None).ok()?; + + let item = dialog.GetResult().ok()?; + let name = item.GetDisplayName(SIGDN_FILESYSPATH).ok()?; + let path = name.to_string().ok(); + CoTaskMemFree(Some(name.0.cast_const().cast())); + path.filter(|path| !path.is_empty()).map(PathBuf::from) + } +} diff --git a/komorebi-recorder/src/timecode.rs b/komorebi-recorder/src/timecode.rs new file mode 100644 index 00000000..78a41bce --- /dev/null +++ b/komorebi-recorder/src/timecode.rs @@ -0,0 +1,277 @@ +//! Parsing and formatting of video timecodes: the way a position in a recording is typed on a +//! command line and shown back. +//! +//! A timecode is a number of seconds of video time, an `f64`, counted from the first captured +//! frame of a session (video `00:00.000`). A time before the first frame is negative. +//! +//! | Function | Does | +//! |---|---| +//! | [`parse`] | reads a timecode into seconds | +//! | [`parse_span`] | reads a duration (`500ms`, `2m`) into seconds | +//! | [`format()`] | writes seconds as a timecode | +//! +//! Accepted by [`parse`]: `12.5` (seconds), `12`, `00:12.500`, `1:02`, `1:02:03` and `1:02:03.25`. +//! A leading `-` is accepted so that offsets before the start of the video can be expressed. +//! [`format()`] writes `MM:SS.mmm`, or `H:MM:SS.mmm` from one hour on, and [`parse`] reads back +//! what it writes. +//! +//! This module has no idea what a recording is: it converts between text and a number of seconds, +//! and places nothing on a clock. Turning video seconds into a time on the master clock is the +//! session manifest's `mach_at_video_seconds`, and the reverse its `video_seconds`. +//! +//! # Example +//! +//! ```rust +//! use komorebi_recorder::timecode; +//! +//! assert_eq!(timecode::parse("00:12.500")?, 12.5); +//! assert_eq!(timecode::parse("1:02:03")?, 3723.0); +//! assert_eq!(timecode::parse("-1.5")?, -1.5); +//! +//! assert_eq!(timecode::format(12.5), "00:12.500"); +//! assert_eq!(timecode::format(3723.25), "1:02:03.250"); +//! +//! // a span is a length of time, not a position +//! assert_eq!(timecode::parse_span("500ms")?, 0.5); +//! assert_eq!(timecode::parse_span("2m")?, 120.0); +//! # Ok::<(), Box>(()) +//! ``` + +use color_eyre::eyre; + +/// Parses a timecode into seconds. +/// +/// The forms are `[[H:]M:]S[.fraction]`, optionally preceded by `-`, with surrounding whitespace +/// ignored: `12.5`, `12`, `00:12.500`, `1:02`, `1:02:03` and `1:02:03.25`. The hours and minutes +/// are whole numbers, and the seconds are any non-negative number Rust reads as an `f64`. The +/// parts are not range checked, so `1:75` is `135` seconds and `90:00` is `5400`. A `-` negates +/// the whole timecode, and is only accepted once, at the start. +/// +/// # Errors +/// +/// Returns an error if the input +/// +/// * is empty (after trimming, and after a leading `-`): `empty timecode`; +/// * has more than three `:`-separated parts: `expected [[H:]M:]S[.fraction]`; +/// * has an hours or minutes part that is not an unsigned whole number (`1.5:30`, `1:-2:30`); +/// * has a seconds part, the last one, that is not a number, or is negative, `NaN` or infinite +/// (`abc`, `--1`, `1:-2`, `nan`, `inf`). +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::timecode::parse; +/// +/// assert_eq!(parse("12.5")?, 12.5); +/// assert_eq!(parse("1:02")?, 62.0); +/// assert_eq!(parse("1:02:03.25")?, 3723.25); +/// assert_eq!(parse("-0:01.500")?, -1.5); +/// +/// // the parts are not range checked +/// assert_eq!(parse("1:75")?, 135.0); +/// +/// let error = parse("1:2:3:4").unwrap_err(); +/// assert_eq!(error.to_string(), "invalid timecode '1:2:3:4': expected [[H:]M:]S[.fraction]"); +/// assert_eq!(parse("").unwrap_err().to_string(), "empty timecode"); +/// assert!(parse("nan").is_err()); +/// # Ok::<(), Box>(()) +/// ``` +pub fn parse(input: &str) -> eyre::Result { + let trimmed = input.trim(); + let (negative, body) = match trimmed.strip_prefix('-') { + Some(rest) => (true, rest), + None => (false, trimmed), + }; + + if body.is_empty() { + eyre::bail!("empty timecode"); + } + + let parts: Vec<&str> = body.split(':').collect(); + if parts.len() > 3 { + eyre::bail!("invalid timecode '{input}': expected [[H:]M:]S[.fraction]"); + } + + let mut seconds = 0.0_f64; + for (index, part) in parts.iter().enumerate() { + let is_last = index == parts.len() - 1; + let invalid = || eyre::Report::msg(format!("invalid timecode '{input}'")); + let value: f64 = if is_last { + part.parse().map_err(|_| invalid())? + } else { + f64::from(part.parse::().map_err(|_| invalid())?) + }; + + if !value.is_finite() || value < 0.0 { + eyre::bail!("invalid timecode '{input}'"); + } + + seconds = seconds * 60.0 + value; + } + + Ok(if negative { -seconds } else { seconds }) +} + +/// Parses a duration such as `1s`, `500ms`, `1.5` (seconds) or `2m` into seconds. +/// +/// A number followed by `ms` (milliseconds), `s` (seconds) or `m` (minutes), with nothing after it +/// meaning seconds. Whitespace around the input, and between the number and its unit, is ignored. +/// Hours are not a unit: use minutes, or a timecode with [`parse`]. +/// +/// # Errors +/// +/// Returns an error if the number is not a number Rust reads as an `f64` (`soon`, or an empty +/// string), or if it is negative, `NaN` or infinite: a span cannot be negative. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::timecode::parse_span; +/// +/// assert_eq!(parse_span("1s")?, 1.0); +/// assert_eq!(parse_span("500ms")?, 0.5); +/// assert_eq!(parse_span("1.5")?, 1.5); +/// assert_eq!(parse_span("2m")?, 120.0); +/// +/// assert!(parse_span("-1s").is_err()); +/// assert!(parse_span("soon").is_err()); +/// assert_eq!( +/// parse_span("soon").unwrap_err().to_string(), +/// "invalid duration 'soon': expected e.g. 1s, 500ms or 1.5" +/// ); +/// # Ok::<(), Box>(()) +/// ``` +pub fn parse_span(input: &str) -> eyre::Result { + let trimmed = input.trim(); + let (number, scale) = if let Some(rest) = trimmed.strip_suffix("ms") { + (rest, 0.001) + } else if let Some(rest) = trimmed.strip_suffix('s') { + (rest, 1.0) + } else if let Some(rest) = trimmed.strip_suffix('m') { + (rest, 60.0) + } else { + (trimmed, 1.0) + }; + + let value: f64 = number.trim().parse().map_err(|_| { + eyre::Report::msg(format!( + "invalid duration '{input}': expected e.g. 1s, 500ms or 1.5" + )) + })?; + + if !value.is_finite() || value < 0.0 { + eyre::bail!("invalid duration '{input}': must be a non-negative number"); + } + + Ok(value * scale) +} + +/// Returns `seconds` as a timecode: `MM:SS.mmm`, or `H:MM:SS.mmm` from one hour on. +/// +/// The value is rounded to the nearest millisecond. Minutes and seconds are two digits and +/// milliseconds three; hours have as many digits as they need. A negative value is written with a +/// leading `-`, which a value that rounds to zero keeps (`-00:00.000`). The result is not +/// specified for a `NaN` or infinite `seconds`. +/// +/// [`parse`] reads back what this writes: a value that is a whole number of milliseconds comes +/// back equal, to within floating point error (the test `format_parse_roundtrip`). +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::timecode::{format, parse}; +/// +/// assert_eq!(format(0.0), "00:00.000"); +/// assert_eq!(format(12.5), "00:12.500"); +/// assert_eq!(format(62.0), "01:02.000"); +/// assert_eq!(format(3723.25), "1:02:03.250"); +/// assert_eq!(format(-1.5), "-00:01.500"); +/// +/// // rounded to the millisecond +/// assert_eq!(format(1.2346), "00:01.235"); +/// +/// assert!((parse(&format(7322.125))? - 7322.125).abs() < 1e-9); +/// # Ok::<(), Box>(()) +/// ``` +#[must_use] +pub fn format(seconds: f64) -> String { + let sign = if seconds < 0.0 { "-" } else { "" }; + let total_ms = (seconds.abs() * 1_000.0).round() as u64; + let ms = total_ms % 1_000; + let total_s = total_ms / 1_000; + let s = total_s % 60; + let m = (total_s / 60) % 60; + let h = total_s / 3_600; + + if h > 0 { + format!("{sign}{h}:{m:02}:{s:02}.{ms:03}") + } else { + format!("{sign}{m:02}:{s:02}.{ms:03}") + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn close(a: f64, b: f64) -> bool { + (a - b).abs() < 1e-9 + } + + #[test] + fn parses_plain_seconds() { + assert!(close(parse("12.5").unwrap(), 12.5)); + assert!(close(parse("12").unwrap(), 12.0)); + assert!(close(parse("0.04").unwrap(), 0.04)); + } + + #[test] + fn parses_clock_forms() { + assert!(close(parse("00:12.500").unwrap(), 12.5)); + assert!(close(parse("1:02").unwrap(), 62.0)); + assert!(close(parse("1:02:03").unwrap(), 3723.0)); + assert!(close(parse("1:02:03.25").unwrap(), 3723.25)); + } + + #[test] + fn parses_negative_offsets() { + assert!(close(parse("-1.5").unwrap(), -1.5)); + assert!(close(parse("-0:01.500").unwrap(), -1.5)); + } + + #[test] + fn rejects_garbage() { + for bad in [ + "", "abc", "1:2:3:4", "1.5:30", "::", "1:-2", "--1", "nan", "inf", + ] { + assert!(parse(bad).is_err(), "{bad:?} should not parse"); + } + } + + #[test] + fn parses_spans() { + assert!(close(parse_span("1s").unwrap(), 1.0)); + assert!(close(parse_span("500ms").unwrap(), 0.5)); + assert!(close(parse_span("1.5").unwrap(), 1.5)); + assert!(close(parse_span("2m").unwrap(), 120.0)); + assert!(parse_span("-1s").is_err()); + assert!(parse_span("soon").is_err()); + assert!(parse_span("").is_err()); + } + + #[test] + fn formats() { + assert_eq!(format(12.5), "00:12.500"); + assert_eq!(format(0.0), "00:00.000"); + assert_eq!(format(62.0), "01:02.000"); + assert_eq!(format(3723.25), "1:02:03.250"); + assert_eq!(format(-1.5), "-00:01.500"); + } + + #[test] + fn format_parse_roundtrip() { + for value in [0.0, 0.001, 12.5, 59.999, 3600.0, 7322.125] { + assert!(close(parse(&format(value)).unwrap(), value)); + } + } +}