diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 1dda543d..33316dae 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -83,6 +83,11 @@ one segment to a file: a display that is unplugged and returns starts a new segm The recorder starts its sources in an order that makes the sources that are not video a superset of the video's span (the clock anchor, the OS trace streams, the subscription to komorebi and its first `State`, komorebi's log offset, and last the video), and stops them in the reverse order. +While it runs, the machine is docked, undocked, put to sleep, woken with the lid opened and locked, and none of that may +lose what was already captured. A tracker turns what the OS says (or, on a Mac, what the two clocks disagree about) into +reactions: a display that is gone has its video finalized at once, one that returns starts a new segment, and every +stream is started afresh after a wake. The capture backend is a trait, so that these policies are tested with a scripted +backend that docks and undocks without hardware. ## Rules and the layer that enforces them diff --git a/docs/PLATFORM.md b/docs/PLATFORM.md index e6a16bf4..267cc2f1 100644 --- a/docs/PLATFORM.md +++ b/docs/PLATFORM.md @@ -46,6 +46,18 @@ Video frame times and the OS trace are on the master clock already on both hosts `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). +### Noticing sleep, wake, lock and display changes + +| | macOS | Windows | +|---|---|---| +| a sleep | found afterwards: the master clock pauses while the wall clock does not, which the recording loop sees by comparing the two many times a second | heard as it happens, from a hidden window on a thread of its own that receives suspend and resume; the lid, the displays' power state and session lock are registered for | +| the screen locked | polled: CoreGraphics' session dictionary | polled: being refused the input desktop means a lock screen or a UAC prompt, and the screen cannot be captured then either way | +| displays added, removed, resized | polled: `CGGetActiveDisplayList` and `CGDisplayIsAsleep`, which are cheap and need no permission | polled, and heard as a display-change message | + +Windows is told when the lock happens as well as polling for it. What is done about each of these, on both hosts, is the +same: a display that is gone has its video finalized at once, a display that returns starts a new segment, and every +stream is started afresh after a wake instead of trusting the old one. + ### Capturing the screen | | macOS | Windows | diff --git a/komorebi-recorder/src/lib.rs b/komorebi-recorder/src/lib.rs index f042f9ba..010c2a38 100644 --- a/komorebi-recorder/src/lib.rs +++ b/komorebi-recorder/src/lib.rs @@ -49,6 +49,7 @@ //! | [`sources`] | the sources that write raw files into the session | //! | [`session`] | the session directory and its manifest | //! | [`capture`] | capturing the screen into segments of video | +//! | [`power`] and [`system_state`] | sleep, wake, lock and display changes | //! //! # What is not supported //! @@ -68,6 +69,8 @@ pub mod incidents; pub mod komorebi_link; pub mod lock; pub mod platform; +pub mod power; pub mod session; pub mod sources; +pub mod system_state; pub mod timecode; diff --git a/komorebi-recorder/src/platform/macos/mod.rs b/komorebi-recorder/src/platform/macos/mod.rs index af1b6d0e..cc5d08da 100644 --- a/komorebi-recorder/src/platform/macos/mod.rs +++ b/komorebi-recorder/src/platform/macos/mod.rs @@ -17,7 +17,9 @@ pub mod apps; pub mod capture; pub mod clock; +pub mod power; pub mod process; +pub mod session; pub mod shell; pub mod trace; diff --git a/komorebi-recorder/src/platform/macos/power.rs b/komorebi-recorder/src/platform/macos/power.rs new file mode 100644 index 00000000..cae16cd1 --- /dev/null +++ b/komorebi-recorder/src/platform/macos/power.rs @@ -0,0 +1,42 @@ +//! Hearing about sleep, wake, the lid, the displays and the session as they happen: not on macOS. +//! +//! macOS has no power watcher: a sleep is found by the host clock pausing while the wall clock does +//! not (see [`crate::clock::JumpDetector`]). [`start`] returns no [`Watcher`], and the recording +//! loop works from the clocks alone. +//! +//! On Windows a watcher listens to a hidden window and hands the recording loop a +//! [`PowerEvent`] for each thing it hears. + +use crate::power::PowerEvent; + +/// Listens for power events and holds what it heard until it is drained. Never constructed on this +/// host: [`start`] returns `None`. +pub struct Watcher; + +impl Watcher { + /// Returns what has been heard since the last call, oldest first. Always empty on this host. + #[must_use] + pub fn drain(&self) -> Vec { + Vec::new() + } +} + +/// Starts listening for power events. There is nothing to listen to on a Mac, so this returns +/// `Ok(None)` and the recording loop finds a sleep from the clocks. +/// +/// # Errors +/// +/// Never fails on this host. (On Windows it fails if the watcher's window cannot be made.) +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::platform::power; +/// +/// // a Mac has nothing to listen to: the recording loop works from the clocks +/// assert!(power::start()?.is_none()); +/// # Ok::<(), Box>(()) +/// ``` +pub fn start() -> color_eyre::eyre::Result> { + Ok(None) +} diff --git a/komorebi-recorder/src/platform/macos/session.rs b/komorebi-recorder/src/platform/macos/session.rs new file mode 100644 index 00000000..a563cc34 --- /dev/null +++ b/komorebi-recorder/src/platform/macos/session.rs @@ -0,0 +1,44 @@ +//! Whether the session is locked, and whether it is the one at the console, from the CoreGraphics +//! session dictionary. +//! +//! Locking the screen and fast user switching change what the capture API can see and can kill its +//! streams. [`read`] is cheap enough to poll, which is how the recorder notices (see +//! [`crate::system_state`]). The same function exists on Windows, which reads the state from the +//! input desktop. + +use crate::system_state::SessionState; +use objc2_core_foundation::CFBoolean; +use objc2_core_foundation::CFDictionary; +use objc2_core_foundation::CFString; +use objc2_core_graphics::CGSessionCopyCurrentDictionary; +use std::ptr::NonNull; + +fn flag(dictionary: &CFDictionary, key: &'static str) -> Option { + let key = CFString::from_static_str(key); + // SAFETY: `key` is a valid CFString and the dictionary is live + let value = unsafe { CFDictionary::value(dictionary, NonNull::from(&*key).as_ptr().cast()) }; + NonNull::new(value.cast_mut()).map(|value| { + // SAFETY: the session dictionary stores these flags as CFBoolean + unsafe { value.cast::().as_ref() }.as_bool() + }) +} + +/// Returns the current session state, or the default (unlocked, on console) if it cannot be read. +/// +/// `locked` is the session dictionary's `CGSSessionScreenIsLocked` and `on_console` its +/// `kCGSSessionOnConsoleKey`; a flag the dictionary does not carry reads as unlocked, or on the +/// console. Never fails. +/// +/// This reads the machine it runs on, so it has no doctest. It is covered by +/// `reading_the_real_session_works_in_any_state` in the unit tests of [`crate::system_state`]. +#[must_use] +pub fn read() -> SessionState { + let Some(dictionary) = CGSessionCopyCurrentDictionary() else { + return SessionState::default(); + }; + + SessionState { + locked: flag(&dictionary, "CGSSessionScreenIsLocked").unwrap_or(false), + on_console: flag(&dictionary, "kCGSSessionOnConsoleKey").unwrap_or(true), + } +} diff --git a/komorebi-recorder/src/platform/mod.rs b/komorebi-recorder/src/platform/mod.rs index 3cc62b46..aba19573 100644 --- a/komorebi-recorder/src/platform/mod.rs +++ b/komorebi-recorder/src/platform/mod.rs @@ -11,6 +11,8 @@ //! | [`process`] | stopping a child process | //! | [`trace`] | streaming the OS trace into the session | //! | [`capture`] | can we capture, which displays exist, the real [`CaptureBackend`], a video's duration | +//! | [`power`] | hearing about sleep, wake, lock and display changes as they happen | +//! | [`session`] | is the screen locked, is this user's session in front | //! //! 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. @@ -53,7 +55,9 @@ pub use imp::capture; pub use imp::clock; #[cfg(windows)] pub use imp::media; +pub use imp::power; pub use imp::process; +pub use imp::session; pub use imp::shell; pub use imp::trace; diff --git a/komorebi-recorder/src/platform/unsupported.rs b/komorebi-recorder/src/platform/unsupported.rs index c047084e..4048758c 100644 --- a/komorebi-recorder/src/platform/unsupported.rs +++ b/komorebi-recorder/src/platform/unsupported.rs @@ -134,6 +134,31 @@ pub mod clock { } } +/// Power events, which this host cannot hear. +pub mod power { + use crate::power::PowerEvent; + + /// Never constructed on this host. + pub struct Watcher; + + impl Watcher { + /// Returns nothing: there is no power watcher. + #[must_use] + pub fn drain(&self) -> Vec { + Vec::new() + } + } + + /// Returns no watcher: this host has nothing to listen to. + /// + /// # Errors + /// + /// Never returns an error. + pub fn start() -> color_eyre::eyre::Result> { + Ok(None) + } +} + /// The OS trace, which this host does not have. pub mod trace { use crate::sources::wintrace::TraceStream; @@ -178,6 +203,17 @@ pub mod process { } } +/// Whether the session is locked, which this host cannot tell. +pub mod session { + use crate::system_state::SessionState; + + /// Returns the default state: unlocked and on the console. + #[must_use] + pub fn read() -> SessionState { + SessionState::default() + } +} + /// Showing a folder, asking for one, and naming the OS, with what this host can offer. pub mod shell { use std::path::Path; diff --git a/komorebi-recorder/src/platform/win/mod.rs b/komorebi-recorder/src/platform/win/mod.rs index cfc9566d..ba9f95d9 100644 --- a/komorebi-recorder/src/platform/win/mod.rs +++ b/komorebi-recorder/src/platform/win/mod.rs @@ -25,7 +25,9 @@ pub mod apps; pub mod capture; pub mod clock; pub mod media; +pub mod power; pub mod process; +pub mod session; pub mod shell; pub mod trace; diff --git a/komorebi-recorder/src/platform/win/power.rs b/komorebi-recorder/src/platform/win/power.rs new file mode 100644 index 00000000..3a424d53 --- /dev/null +++ b/komorebi-recorder/src/platform/win/power.rs @@ -0,0 +1,323 @@ +//! Hearing about sleep, wake, the lid, the displays and the session from Windows as they happen. +//! +//! A hidden window on a thread of its own, the way komorebi for Windows listens for the same +//! things: Windows sends suspend and resume (and display changes) to every top-level window, and +//! the lid, the displays' power and session lock are registered for. Each message is stamped with a +//! clock anchor on arrival and handed to the recording loop over a channel; nothing is done on the +//! window's thread but that. +//! +//! [`start`] makes a [`Watcher`], which the recording loop drains with [`Watcher::drain`] and +//! hands to [`PowerTracker`](crate::power::PowerTracker). What Windows says becomes a +//! [`PowerKind`]: +//! +//! | Windows says | becomes | +//! |---|---| +//! | `PBT_APMSUSPEND` | `Suspend` | +//! | `PBT_APMRESUMEAUTOMATIC` or `PBT_APMRESUMESUSPEND` (woken by a timer, or by the user) | `Resume` | +//! | the lid switch changed to closed, or to opened | `LidClosed`, `LidOpened` | +//! | the console display turned off, or on (dimmed is ignored) | `DisplaysOff`, `DisplaysOn` | +//! | this session was locked, or unlocked (`WM_WTSSESSION_CHANGE`) | `SessionLocked`, `SessionUnlocked` | +//! | a display was added or removed, or changed size or scale (`WM_DISPLAYCHANGE`) | `DisplaysChanged` | +//! +//! A machine with no lid says so when the watcher registers for it, and the rest still works. +//! +//! macOS has no watcher: [`crate::platform::power`] there starts none, and the recording loop finds +//! a sleep from the clocks. Nothing tests this module automatically; the logic that reads its +//! events is tested through [`PowerTracker`](crate::power::PowerTracker), and the window itself is +//! checked on a real machine (see `docs/dev/windows-checkpoints.md`). + +use crate::clock::Anchor; +use crate::power::PowerEvent; +use crate::power::PowerKind; +use color_eyre::eyre; +use color_eyre::eyre::WrapErr; +use crossbeam_channel::Receiver; +use crossbeam_channel::Sender; +use std::sync::mpsc; +use std::thread::JoinHandle; +use windows::Win32::Foundation::HANDLE; +use windows::Win32::Foundation::HWND; +use windows::Win32::Foundation::LPARAM; +use windows::Win32::Foundation::LRESULT; +use windows::Win32::Foundation::WPARAM; +use windows::Win32::System::LibraryLoader::GetModuleHandleW; +use windows::Win32::System::Power::POWERBROADCAST_SETTING; +use windows::Win32::System::Power::RegisterPowerSettingNotification; +use windows::Win32::System::Power::UnregisterPowerSettingNotification; +use windows::Win32::System::RemoteDesktop::WTSRegisterSessionNotification; +use windows::Win32::System::RemoteDesktop::WTSUnRegisterSessionNotification; +use windows::Win32::System::SystemServices::GUID_CONSOLE_DISPLAY_STATE; +use windows::Win32::System::SystemServices::GUID_LIDSWITCH_STATE_CHANGE; +use windows::Win32::UI::WindowsAndMessaging::CW_USEDEFAULT; +use windows::Win32::UI::WindowsAndMessaging::CreateWindowExW; +use windows::Win32::UI::WindowsAndMessaging::DefWindowProcW; +use windows::Win32::UI::WindowsAndMessaging::DestroyWindow; +use windows::Win32::UI::WindowsAndMessaging::DispatchMessageW; +use windows::Win32::UI::WindowsAndMessaging::GWLP_USERDATA; +use windows::Win32::UI::WindowsAndMessaging::GetMessageW; +use windows::Win32::UI::WindowsAndMessaging::GetWindowLongPtrW; +use windows::Win32::UI::WindowsAndMessaging::MSG; +use windows::Win32::UI::WindowsAndMessaging::PBT_APMRESUMEAUTOMATIC; +use windows::Win32::UI::WindowsAndMessaging::PBT_APMRESUMESUSPEND; +use windows::Win32::UI::WindowsAndMessaging::PBT_APMSUSPEND; +use windows::Win32::UI::WindowsAndMessaging::PBT_POWERSETTINGCHANGE; +use windows::Win32::UI::WindowsAndMessaging::PostMessageW; +use windows::Win32::UI::WindowsAndMessaging::PostQuitMessage; +use windows::Win32::UI::WindowsAndMessaging::REGISTER_NOTIFICATION_FLAGS; +use windows::Win32::UI::WindowsAndMessaging::RegisterClassW; +use windows::Win32::UI::WindowsAndMessaging::SetWindowLongPtrW; +use windows::Win32::UI::WindowsAndMessaging::TranslateMessage; +use windows::Win32::UI::WindowsAndMessaging::WM_CLOSE; +use windows::Win32::UI::WindowsAndMessaging::WM_DESTROY; +use windows::Win32::UI::WindowsAndMessaging::WM_DISPLAYCHANGE; +use windows::Win32::UI::WindowsAndMessaging::WM_POWERBROADCAST; +use windows::Win32::UI::WindowsAndMessaging::WM_WTSSESSION_CHANGE; +use windows::Win32::UI::WindowsAndMessaging::WNDCLASSW; +use windows::Win32::UI::WindowsAndMessaging::WS_DISABLED; +use windows::Win32::UI::WindowsAndMessaging::WS_EX_NOACTIVATE; +use windows::Win32::UI::WindowsAndMessaging::WTS_SESSION_LOCK; +use windows::Win32::UI::WindowsAndMessaging::WTS_SESSION_UNLOCK; +use windows::core::w; + +/// `WTSRegisterSessionNotification`: only this session's lock and unlock. +const NOTIFY_FOR_THIS_SESSION: u32 = 0; + +/// What `GUID_CONSOLE_DISPLAY_STATE` reports in its one byte of data. +const DISPLAY_OFF: u8 = 0; +const DISPLAY_ON: u8 = 1; +/// And `GUID_LIDSWITCH_STATE_CHANGE`. +const LID_CLOSED: u8 = 0; +const LID_OPENED: u8 = 1; + +/// Listens for power events until dropped, and holds what it heard until it is drained. +/// +/// Dropping a watcher asks its window to close and waits for the thread to finish. +pub struct Watcher { + events: Receiver, + window: isize, + thread: Option>, +} + +impl Watcher { + /// Returns what has been heard since the last call, oldest first. Each [`PowerEvent`] carries + /// the clock [`Anchor`] sampled when the message arrived. + #[must_use] + pub fn drain(&self) -> Vec { + self.events.try_iter().collect() + } +} + +impl Drop for Watcher { + fn drop(&mut self) { + // ask the window to close itself on its own thread, which ends the message loop + // SAFETY: posting to a window handle that is at worst already gone + let _ = unsafe { + PostMessageW( + Some(HWND(self.window as *mut std::ffi::c_void)), + WM_CLOSE, + WPARAM(0), + LPARAM(0), + ) + }; + if let Some(thread) = self.thread.take() { + let _ = thread.join(); + } + } +} + +fn emit(window: HWND, kind: PowerKind) { + // SAFETY: the user data is either null or the `Sender` boxed by `run` for this window, which + // outlives every message the window is sent + let sender = unsafe { GetWindowLongPtrW(window, GWLP_USERDATA) } as *const Sender; + // SAFETY: see above + if let Some(sender) = unsafe { sender.as_ref() } { + let _ = sender.send(PowerEvent { + kind, + anchor: Anchor::sample(), + }); + } +} + +unsafe extern "system" fn callback( + window: HWND, + message: u32, + wparam: WPARAM, + lparam: LPARAM, +) -> LRESULT { + match message { + WM_POWERBROADCAST => { + match wparam.0 as u32 { + PBT_APMSUSPEND => emit(window, PowerKind::Suspend), + // woken by itself (a timer) or by the user: either way, awake + PBT_APMRESUMEAUTOMATIC | PBT_APMRESUMESUSPEND => emit(window, PowerKind::Resume), + PBT_POWERSETTINGCHANGE => { + // SAFETY: for this message `lparam` points at a POWERBROADCAST_SETTING whose + // `DataLength` bytes of data follow it; only the first byte is read + let setting = unsafe { (lparam.0 as *const POWERBROADCAST_SETTING).as_ref() }; + if let Some(setting) = setting + && setting.DataLength >= 1 + { + let value = setting.Data[0]; + if setting.PowerSetting == GUID_LIDSWITCH_STATE_CHANGE { + match value { + LID_CLOSED => emit(window, PowerKind::LidClosed), + LID_OPENED => emit(window, PowerKind::LidOpened), + _ => {} + } + } else if setting.PowerSetting == GUID_CONSOLE_DISPLAY_STATE { + match value { + DISPLAY_OFF => emit(window, PowerKind::DisplaysOff), + DISPLAY_ON => emit(window, PowerKind::DisplaysOn), + // dimmed: still showing + _ => {} + } + } + } + } + _ => {} + } + LRESULT(1) + } + WM_WTSSESSION_CHANGE => { + match wparam.0 as u32 { + WTS_SESSION_LOCK => emit(window, PowerKind::SessionLocked), + WTS_SESSION_UNLOCK => emit(window, PowerKind::SessionUnlocked), + _ => {} + } + LRESULT(0) + } + // a display was added or removed, or changed size or scale + WM_DISPLAYCHANGE => { + emit(window, PowerKind::DisplaysChanged); + LRESULT(0) + } + WM_CLOSE => { + // SAFETY: closing our own window on its own thread + let _ = unsafe { DestroyWindow(window) }; + LRESULT(0) + } + WM_DESTROY => { + // SAFETY: ends this thread's message loop + unsafe { PostQuitMessage(0) }; + LRESULT(0) + } + // SAFETY: the defaults for everything else + _ => unsafe { DefWindowProcW(window, message, wparam, lparam) }, + } +} + +/// The window's thread: make the window, register for what it should hear, pump messages. +fn run(ready: &mpsc::Sender>, events: Sender) { + let setup = || -> eyre::Result<(HWND, Box>)> { + // SAFETY: plain Win32 calls with the arguments they document; the boxed sender is stored + // in the window's user data and freed after the loop ends, when no message can arrive + unsafe { + let instance = GetModuleHandleW(None).wrap_err("GetModuleHandleW")?; + let class = WNDCLASSW { + hInstance: instance.into(), + lpszClassName: w!("komorebi-recorder-power"), + lpfnWndProc: Some(callback), + ..Default::default() + }; + // a second watcher in the same process finds the class already registered + RegisterClassW(&raw const class); + + // never shown, and disabled and unactivatable besides: a window only to be sent to + let window = CreateWindowExW( + WS_EX_NOACTIVATE, + w!("komorebi-recorder-power"), + w!("komorebi-recorder-power"), + WS_DISABLED, + CW_USEDEFAULT, + CW_USEDEFAULT, + CW_USEDEFAULT, + CW_USEDEFAULT, + None, + None, + Some(instance.into()), + None, + ) + .wrap_err("could not create the power window")?; + + let sender = Box::new(events); + SetWindowLongPtrW(window, GWLP_USERDATA, &raw const *sender as isize); + Ok((window, sender)) + } + }; + + let (window, sender) = match setup() { + Ok(made) => made, + Err(error) => { + let _ = ready.send(Err(error)); + return; + } + }; + + // SAFETY: registrations against the window just made, undone below + let (lid, display, session) = unsafe { + ( + RegisterPowerSettingNotification( + HANDLE(window.0), + &GUID_LIDSWITCH_STATE_CHANGE, + REGISTER_NOTIFICATION_FLAGS(0), + ), + RegisterPowerSettingNotification( + HANDLE(window.0), + &GUID_CONSOLE_DISPLAY_STATE, + REGISTER_NOTIFICATION_FLAGS(0), + ), + WTSRegisterSessionNotification(window, NOTIFY_FOR_THIS_SESSION), + ) + }; + // a machine with no lid says so here; the rest still works + let _ = ready.send(Ok(window.0 as isize)); + + let mut message = MSG::default(); + // SAFETY: the standard message loop for this thread's window + unsafe { + while GetMessageW(&raw mut message, None, 0, 0).as_bool() { + let _ = TranslateMessage(&raw const message); + DispatchMessageW(&raw const message); + } + } + + // SAFETY: undoing the registrations above + unsafe { + if let Ok(lid) = lid { + let _ = UnregisterPowerSettingNotification(lid); + } + if let Ok(display) = display { + let _ = UnregisterPowerSettingNotification(display); + } + if session.is_ok() { + let _ = WTSUnRegisterSessionNotification(window); + } + } + drop(sender); +} + +/// Starts listening, and returns the watcher. It is always `Some` on Windows: the `Option` is the +/// facade's, shared with hosts that have no watcher. +/// +/// # Errors +/// +/// Returns an error if the module handle cannot be read or the hidden window cannot be made, or if +/// the thread cannot be started or ends before it was ready. Failing to register for the lid, the +/// displays or the session lock is not an error: those messages are then not heard. +pub fn start() -> eyre::Result> { + let (events_tx, events_rx) = crossbeam_channel::unbounded(); + let (ready_tx, ready_rx) = mpsc::channel(); + let thread = std::thread::Builder::new() + .name("komorebi-recorder-power".to_string()) + .spawn(move || run(&ready_tx, events_tx))?; + + let window = ready_rx + .recv() + .wrap_err("the power watcher thread ended before it was ready")??; + + Ok(Some(Watcher { + events: events_rx, + window, + thread: Some(thread), + })) +} diff --git a/komorebi-recorder/src/platform/win/session.rs b/komorebi-recorder/src/platform/win/session.rs new file mode 100644 index 00000000..513af19a --- /dev/null +++ b/komorebi-recorder/src/platform/win/session.rs @@ -0,0 +1,58 @@ +//! Whether the session is locked, and whether it is the one at the console. +//! +//! The lock screen runs on a desktop of its own that an ordinary process cannot open, so being +//! refused the input desktop is how a process outside it can tell. (A UAC prompt is the same kind +//! of desktop and reads the same; either way the screen cannot be captured then.) This is a poll, +//! not a notification: the power watcher ([`crate::platform::power`]) hears about lock and unlock +//! as they happen, and the recording loop reads [`read`] when it does. See +//! [`crate::system_state`] for what is done with it. +//! +//! The same function exists on macOS, which reads the CoreGraphics session dictionary. + +use crate::system_state::SessionState; +use windows::Win32::System::RemoteDesktop::ProcessIdToSessionId; +use windows::Win32::System::RemoteDesktop::WTSGetActiveConsoleSessionId; +use windows::Win32::System::StationsAndDesktops::CloseDesktop; +use windows::Win32::System::StationsAndDesktops::DESKTOP_CONTROL_FLAGS; +use windows::Win32::System::StationsAndDesktops::DESKTOP_SWITCHDESKTOP; +use windows::Win32::System::StationsAndDesktops::OpenInputDesktop; +use windows::Win32::System::Threading::GetCurrentProcessId; + +/// `WTSGetActiveConsoleSessionId` when no session is at the console. +const NO_SESSION: u32 = 0xFFFF_FFFF; + +/// Returns the current session state, or the default (unlocked, on console) if it cannot be read. +/// +/// `locked` is `true` if and only if the input desktop cannot be opened, which is also so while a +/// UAC prompt is up. `on_console` is `true` if there is no active console session, if this +/// process's session cannot be found out, or if this process is in the console session; it is +/// `false` while another user's session is in front. Never fails. +/// +/// This reads the machine it runs on, so it has no doctest. It is covered by +/// `reading_the_real_session_works_in_any_state` in the unit tests of [`crate::system_state`], +/// which reads the real session on whichever host it runs on and asserts nothing about the state +/// itself: nothing checks either read against a known lock state. +#[must_use] +pub fn read() -> SessionState { + // SAFETY: plain queries; the desktop handle is closed again + let locked = unsafe { + match OpenInputDesktop(DESKTOP_CONTROL_FLAGS(0), false, DESKTOP_SWITCHDESKTOP) { + Ok(desktop) => { + let _ = CloseDesktop(desktop); + false + } + Err(_) => true, + } + }; + + // SAFETY: plain queries with a valid out pointer + let on_console = unsafe { + let console = WTSGetActiveConsoleSessionId(); + let mut ours = 0_u32; + console == NO_SESSION + || ProcessIdToSessionId(GetCurrentProcessId(), &raw mut ours).is_err() + || console == ours + }; + + SessionState { locked, on_console } +} diff --git a/komorebi-recorder/src/power.rs b/komorebi-recorder/src/power.rs new file mode 100644 index 00000000..542879a8 --- /dev/null +++ b/komorebi-recorder/src/power.rs @@ -0,0 +1,396 @@ +//! The machine sleeping, waking, its lid closing, its displays going dark, the session locking: what +//! the OS says about them, and what a recording does about each. +//! +//! On a Mac a sleep announces itself by the host clock pausing while the wall clock does not, so +//! the recording loop finds it by comparing the two (see [`crate::clock::JumpDetector`]). Whether +//! the performance counter does the same on Windows is something to be measured +//! (`doctor --probe clock`), and even if it does, hearing about a sleep when it happens beats +//! inferring it afterwards. So where the OS can say so, a watcher listens +//! ([`crate::platform::power`]), stamps each thing it hears with a clock anchor the moment it hears +//! it, and this module turns them into what a recording should do about them: incidents, anchors +//! that map the wall clock to the host clock on either side of a sleep, and whether captures must +//! be replaced or the displays and the session looked at again at once. +//! +//! # The requirement +//! +//! komorebi bugs show up mostly when a laptop is docked, undocked or woken. A recording that died +//! or lost its video in exactly those moments would be useless, so a recording has to ride out +//! monitors connecting and disconnecting, sleep, lock, unlock and wake without losing data. For +//! power, that comes to four things, which [`PowerTracker`] asks of the recording loop: +//! +//! * nothing is trusted across a sleep: every capture is finalized and replaced on waking, because +//! a stream can stall across a sleep without saying so; +//! * the manifest is checkpointed before the machine sleeps, because it may not come back; +//! * the wall clock is anchored to the host clock on either side of a sleep, so komorebi's log +//! keeps lining up with the video; +//! * the displays and the session are looked at at once, not at the next poll. +//! +//! # The pieces +//! +//! | Type | Is | +//! |---|---| +//! | [`PowerKind`] | what the OS said: a suspend, a resume, the lid, the displays' power, a lock | +//! | [`PowerEvent`] | one such thing, with the clock [`Anchor`] sampled when it was heard | +//! | [`PowerTracker`] | the state machine that turns each [`PowerEvent`] into a [`Reaction`] | +//! | [`Reaction`] | what the recording loop is to do: incidents to write, anchors to add, and what to do now | +//! +//! [`PowerTracker`] does no I/O and reads no clock: it is given everything it needs in the event, +//! so every transition can be tested with made-up times. The recording loop (in the `recorder` +//! module) applies each [`Reaction`]. On hosts with no power watcher (macOS, and the `unsupported` +//! host) no [`PowerEvent`] is ever produced, and a sleep is found from the clocks alone. +//! +//! A sleep that the OS announced is not recorded a second time when the clocks show it too: the +//! recording loop keeps the two anchors of that second finding, and nothing else. +//! +//! # What each event asks for +//! +//! | [`PowerKind`] | incidents | anchors | replace captures | poll displays | poll session | checkpoint | +//! |---|---|---|---|---|---|---| +//! | `Suspend` | `suspend` | the event's | | | | yes | +//! | `Resume` | `wake` | the event's | yes | yes | yes | | +//! | `LidClosed` | `lid-closed` | | | yes | | | +//! | `LidOpened` | `lid-opened` | | | yes | | | +//! | `DisplaysOff` | `display-asleep` | | | yes | | | +//! | `DisplaysOn` | `display-awake` | | | yes | | | +//! | `SessionLocked`, `SessionUnlocked` | none | | | | yes | | +//! | `DisplaysChanged` | none | | | yes | | | +//! +//! A lock writes no incident because [`crate::system_state::SessionTracker`] writes it when it +//! sees the state change; the event only makes the session be looked at now. +//! +//! # Example +//! +//! ```rust +//! use komorebi_recorder::clock::Anchor; +//! use komorebi_recorder::incidents::kind; +//! use komorebi_recorder::power::{PowerEvent, PowerKind, PowerTracker}; +//! +//! let event = |kind: PowerKind, wall_s: i64, mach_s: u64| PowerEvent { +//! kind, +//! anchor: Anchor { wall_us: wall_s * 1_000_000, mach_ns: mach_s * 1_000_000_000 }, +//! }; +//! +//! let mut tracker = PowerTracker::default(); +//! +//! // the machine is about to sleep: bracket it, say so, and save the manifest +//! let suspend = tracker.observe(event(PowerKind::Suspend, 1_000, 100)); +//! assert_eq!(suspend.anchors.len(), 1); +//! assert!(suspend.checkpoint); +//! assert!(!suspend.replace_captures); +//! assert_eq!(suspend.incidents[0].kind, kind::SUSPEND); +//! +//! // it wakes 10 minutes later by the wall clock, and the host clock moved 1 second: it paused +//! let resume = tracker.observe(event(PowerKind::Resume, 1_600, 101)); +//! assert!(resume.replace_captures && resume.poll_displays && resume.poll_session); +//! assert_eq!(resume.incidents[0].kind, kind::WAKE); +//! assert!(resume.incidents[0].detail.contains("600.0 s asleep")); +//! assert!(resume.incidents[0].detail.contains("skips the sleep")); +//! +//! // a resume with no suspend before it still replaces the captures +//! let again = tracker.observe(event(PowerKind::Resume, 5_000, 900)); +//! assert!(again.replace_captures); +//! assert!(again.incidents[0].detail.contains("was not seen")); +//! ``` + +use crate::clock::Anchor; +use crate::incidents::Draft; +use crate::incidents::kind; + +/// What the OS said about the machine's power or session. +/// +/// A watcher produces these where the OS announces them (Windows, in `platform::power`); on a Mac +/// none is produced. They are what [`PowerTracker::observe`] is fed. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum PowerKind { + /// The machine is about to sleep or hibernate. + Suspend, + /// The machine woke, by itself (a timer) or because the user did. A `Resume` with no + /// [`Suspend`](PowerKind::Suspend) before it is possible, and is handled. + Resume, + /// The laptop lid was closed. + LidClosed, + /// The laptop lid was opened. + LidOpened, + /// The displays were turned off (not the machine put to sleep). + DisplaysOff, + /// The displays were turned on. + DisplaysOn, + /// The session was locked. + SessionLocked, + /// The session was unlocked. + SessionUnlocked, + /// Displays were added or removed, or changed size or scale. + DisplaysChanged, +} + +/// Something the OS said, and when, on both clocks. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct PowerEvent { + /// What the OS said. + pub kind: PowerKind, + /// Sampled the moment the message was received. + pub anchor: Anchor, +} + +/// What to do about what was heard: what [`PowerTracker::observe`] returns, for the recording loop +/// to apply. +/// +/// The default reaction asks for nothing. Each field is a request, and the loop decides how to +/// carry it out; see the table in the [module docs](self) for what each [`PowerKind`] asks for. +#[derive(Debug, Default, PartialEq)] +pub struct Reaction { + /// Incidents to write, each dated when the OS said it, not when it was handled. + pub incidents: Vec, + /// Anchors to add to the clock map: either side of a sleep. + pub anchors: Vec, + /// The machine slept: replace every capture rather than trust it. + pub replace_captures: bool, + /// Look at the displays now rather than at the next poll. + pub poll_displays: bool, + /// Look at the session's lock state now. + pub poll_session: bool, + /// Write the manifest now: a machine about to sleep may not come back. + pub checkpoint: bool, +} + +/// Turns what the OS says into reactions, remembering the suspend that a resume answers. +/// +/// A state machine with one piece of state: the anchor of the last [`PowerKind::Suspend`] that has +/// not been answered by a [`PowerKind::Resume`]. A suspend sets it, and a resume reads it, to say +/// how long the machine slept, and clears it. No other event reads or changes it. A new tracker +/// has seen no suspend. +/// +/// The transitions, in the table of the [module docs](self), are covered by the tests in this +/// module; the example there walks through a sleep. +/// +/// # Example: a second resume has no suspend to answer +/// +/// ```rust +/// use komorebi_recorder::clock::Anchor; +/// use komorebi_recorder::power::{PowerEvent, PowerKind, PowerTracker}; +/// +/// let at = |kind: PowerKind, wall_s: i64, mach_s: u64| PowerEvent { +/// kind, +/// anchor: Anchor { wall_us: wall_s * 1_000_000, mach_ns: mach_s * 1_000_000_000 }, +/// }; +/// +/// let mut tracker = PowerTracker::default(); +/// tracker.observe(at(PowerKind::Suspend, 1_000, 100)); +/// let first = tracker.observe(at(PowerKind::Resume, 1_100, 101)); +/// assert!(first.incidents[0].detail.contains("100.0 s asleep")); +/// +/// // the suspend was used up by the first resume +/// let second = tracker.observe(at(PowerKind::Resume, 5_000, 900)); +/// assert!(second.incidents[0].detail.contains("was not seen")); +/// +/// // the host clock counted the sleep (it moved as far as the wall clock): a gap, not a skip +/// tracker.observe(at(PowerKind::Suspend, 6_000, 1_000)); +/// let counted = tracker.observe(at(PowerKind::Resume, 6_600, 1_600)); +/// assert!(counted.incidents[0].detail.contains("includes it as a gap")); +/// ``` +#[derive(Debug, Default)] +pub struct PowerTracker { + suspended_at: Option, +} + +impl PowerTracker { + /// Returns what the recording should do about `event`, and updates what the tracker + /// remembers. + /// + /// The reaction depends only on the event and on whether a suspend is waiting for its resume. + /// For a [`PowerKind::Resume`], the `wake` incident says how long the machine slept by the + /// wall clock and how far the host clock moved over the same time, and so whether video time + /// skips the sleep (the host clock moved less than half as far as the wall clock) or includes + /// it as a gap with no frames. With no suspend waiting, it says that the moment the machine + /// went to sleep was not seen, and the captures are replaced all the same. + pub fn observe(&mut self, event: PowerEvent) -> Reaction { + let mut reaction = Reaction::default(); + let at = event.anchor.mach_ns; + + match event.kind { + PowerKind::Suspend => { + self.suspended_at = Some(event.anchor); + reaction.anchors.push(event.anchor); + reaction.checkpoint = true; + reaction.incidents.push( + Draft::new( + kind::SUSPEND, + "the machine is going to sleep; nothing is recorded until it wakes", + ) + .at(at), + ); + } + PowerKind::Resume => { + reaction.anchors.push(event.anchor); + reaction.replace_captures = true; + reaction.poll_displays = true; + reaction.poll_session = true; + reaction + .incidents + .push(Draft::new(kind::WAKE, self.woke(event.anchor)).at(at)); + self.suspended_at = None; + } + PowerKind::LidClosed => { + reaction.poll_displays = true; + reaction + .incidents + .push(Draft::new(kind::LID_CLOSED, "the laptop lid was closed").at(at)); + } + PowerKind::LidOpened => { + reaction.poll_displays = true; + reaction + .incidents + .push(Draft::new(kind::LID_OPENED, "the laptop lid was opened").at(at)); + } + PowerKind::DisplaysOff => { + reaction.poll_displays = true; + reaction.incidents.push( + Draft::new( + kind::DISPLAY_ASLEEP, + "the displays were turned off; their video pauses until they are back", + ) + .at(at), + ); + } + PowerKind::DisplaysOn => { + reaction.poll_displays = true; + reaction + .incidents + .push(Draft::new(kind::DISPLAY_AWAKE, "the displays were turned on").at(at)); + } + PowerKind::SessionLocked | PowerKind::SessionUnlocked => { + // `SessionTracker` writes the incident when it sees the state change; this makes + // it look now rather than up to half a second from now + reaction.poll_session = true; + } + PowerKind::DisplaysChanged => { + reaction.poll_displays = true; + } + } + + reaction + } + + /// What to say about waking: how long the machine slept, by the wall clock and by the host + /// clock, which is what tells whether the host clock counts a sleep. + fn woke(&self, resumed: Anchor) -> String { + let Some(suspended) = self.suspended_at else { + return "the machine woke from sleep (the moment it went to sleep was not seen)" + .to_string(); + }; + + let wall_s = (resumed.wall_us - suspended.wall_us) as f64 / 1e6; + let host_s = resumed.mach_ns.saturating_sub(suspended.mach_ns) as f64 / 1e9; + format!( + "the machine woke after about {wall_s:.1} s asleep by the wall clock; the host clock \ + moved {host_s:.1} s over the same time, so video time {}", + if host_s < wall_s * 0.5 { + "skips the sleep" + } else { + "includes it as a gap with no frames" + } + ) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn at(wall_s: i64, mach_s: u64, kind: PowerKind) -> PowerEvent { + PowerEvent { + kind, + anchor: Anchor { + wall_us: wall_s * 1_000_000, + mach_ns: mach_s * 1_000_000_000, + }, + } + } + + #[test] + fn a_sleep_is_bracketed_by_anchors_and_everything_is_replaced_on_waking() { + let mut tracker = PowerTracker::default(); + + let suspend = tracker.observe(at(1000, 100, PowerKind::Suspend)); + assert_eq!(suspend.anchors.len(), 1); + assert!( + suspend.checkpoint, + "a machine about to sleep may not come back" + ); + assert!(!suspend.replace_captures); + assert_eq!(suspend.incidents[0].kind, kind::SUSPEND); + assert_eq!(suspend.incidents[0].mach_ns, Some(100_000_000_000)); + + let resume = tracker.observe(at(1600, 101, PowerKind::Resume)); + assert_eq!(resume.anchors.len(), 1); + assert!(resume.replace_captures && resume.poll_displays && resume.poll_session); + assert_eq!(resume.incidents[0].kind, kind::WAKE); + let detail = &resume.incidents[0].detail; + assert!(detail.contains("600.0 s asleep"), "{detail}"); + assert!(detail.contains("moved 1.0 s"), "{detail}"); + assert!(detail.contains("skips the sleep"), "{detail}"); + } + + #[test] + fn a_host_clock_that_counted_the_sleep_is_said_to_have_a_gap_instead() { + let mut tracker = PowerTracker::default(); + tracker.observe(at(1000, 100, PowerKind::Suspend)); + let resume = tracker.observe(at(1600, 700, PowerKind::Resume)); + let detail = &resume.incidents[0].detail; + assert!(detail.contains("includes it as a gap"), "{detail}"); + } + + #[test] + fn waking_with_no_suspend_seen_still_replaces_the_captures() { + let mut tracker = PowerTracker::default(); + let resume = tracker.observe(at(1600, 700, PowerKind::Resume)); + assert!(resume.replace_captures); + assert!(resume.incidents[0].detail.contains("was not seen")); + } + + #[test] + fn a_second_wake_does_not_reuse_the_first_suspend() { + let mut tracker = PowerTracker::default(); + tracker.observe(at(1000, 100, PowerKind::Suspend)); + tracker.observe(at(1100, 101, PowerKind::Resume)); + let again = tracker.observe(at(5000, 900, PowerKind::Resume)); + assert!(again.incidents[0].detail.contains("was not seen")); + } + + #[test] + fn lid_and_display_power_are_incidents_that_make_the_displays_be_looked_at() { + let mut tracker = PowerTracker::default(); + for (event, expected) in [ + (PowerKind::LidClosed, kind::LID_CLOSED), + (PowerKind::LidOpened, kind::LID_OPENED), + (PowerKind::DisplaysOff, kind::DISPLAY_ASLEEP), + (PowerKind::DisplaysOn, kind::DISPLAY_AWAKE), + ] { + let reaction = tracker.observe(at(1, 1, event)); + assert!(reaction.poll_displays, "{event:?}"); + assert_eq!(reaction.incidents[0].kind, expected, "{event:?}"); + assert!(!reaction.replace_captures, "{event:?}"); + } + } + + #[test] + fn a_lock_makes_the_session_be_looked_at_without_writing_an_incident_twice() { + let mut tracker = PowerTracker::default(); + for event in [PowerKind::SessionLocked, PowerKind::SessionUnlocked] { + let reaction = tracker.observe(at(1, 1, event)); + assert!(reaction.poll_session); + assert!( + reaction.incidents.is_empty(), + "{event:?}: SessionTracker reports it" + ); + } + } + + #[test] + fn a_display_change_only_makes_the_displays_be_looked_at() { + let reaction = PowerTracker::default().observe(at(1, 1, PowerKind::DisplaysChanged)); + assert!(reaction.poll_displays); + assert!(reaction.incidents.is_empty()); + assert!(reaction.anchors.is_empty()); + } +} diff --git a/komorebi-recorder/src/system_state.rs b/komorebi-recorder/src/system_state.rs new file mode 100644 index 00000000..dd815a7e --- /dev/null +++ b/komorebi-recorder/src/system_state.rs @@ -0,0 +1,215 @@ +//! Whether the user's session is locked or switched away. +//! +//! Locking the screen and fast user switching change what the capture API can see and can kill +//! its streams. We cannot subscribe to those transitions without a run loop, but the session +//! state is cheap to read (see [`crate::platform::session`]), so the recorder polls it and logs +//! each transition as an incident, next to whatever the video and the logs did at the same moment. +//! +//! | Item | Does | +//! |---|---| +//! | [`SessionState`] | what the session looks like at one moment: locked or not, at the console or not | +//! | [`read`] | reads it now, from the OS (see [`crate::platform::session`]) | +//! | [`SessionTracker`] | compares successive readings, and turns each change into an incident | +//! +//! The host decides how the state is read: from the CoreGraphics session dictionary on macOS, and +//! on Windows from whether the input desktop can be opened (the lock screen runs on a desktop that +//! an ordinary process may not open) and from which session is at the console. The tracker is the +//! same on both. On Windows a power watcher also reports a lock as it happens (see +//! [`crate::power::PowerKind::SessionLocked`]), which only makes the poll happen sooner: the +//! incident is still written here, once, when the poll sees the change. +//! +//! # Example +//! +//! ```rust +//! use komorebi_recorder::incidents::kind; +//! use komorebi_recorder::system_state::{SessionState, SessionTracker}; +//! +//! let mut tracker = SessionTracker::default(); +//! assert!(tracker.capturable()); +//! +//! // the screen locks: one incident, and the session cannot be captured +//! let drafts = tracker.observe(SessionState { locked: true, on_console: true }); +//! assert_eq!(drafts.len(), 1); +//! assert_eq!(drafts[0].kind, kind::SCREEN_LOCKED); +//! assert!(!tracker.capturable()); +//! +//! // still locked: nothing new to say +//! assert!(tracker.observe(SessionState { locked: true, on_console: true }).is_empty()); +//! ``` + +use crate::incidents::Draft; +use crate::incidents::kind; + +/// The state of the user's session at one moment: whether it is locked, and whether it is the one +/// in front. +/// +/// The default is the session as it is when nothing is wrong: unlocked and at the console. That +/// is also what [`read`] falls back to where the host gives no answer. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct SessionState { + /// Whether the screen is locked. On Windows this is also true while a prompt on the secure + /// desktop is up (a UAC prompt reads the same way): the screen cannot be captured then either. + pub locked: bool, + /// `false` while another user's session is in front (fast user switching). + pub on_console: bool, +} + +impl Default for SessionState { + fn default() -> Self { + Self { + locked: false, + on_console: true, + } + } +} + +/// Returns the current session state, or the default (unlocked, on console) if it cannot be read. +/// +/// This asks the OS each time ([`crate::platform::session`]): it is cheap, needs no permission, +/// and never fails. It reflects the machine it is run on, so a test cannot assume either state; +/// the test `reading_the_real_session_works_in_any_state` only checks that the reading and a +/// [`SessionTracker`] agree. +#[must_use] +pub fn read() -> SessionState { + crate::platform::session::read() +} + +/// Turns successive [`SessionState`]s into incidents. +/// +/// A state machine whose only state is the last [`SessionState`] it saw, which starts as the +/// default (unlocked, at the console). Each change from it is reported once. +/// +/// # Example: both flags change at once +/// +/// ```rust +/// use komorebi_recorder::incidents::kind; +/// use komorebi_recorder::system_state::{SessionState, SessionTracker}; +/// +/// let mut tracker = SessionTracker::default(); +/// +/// // fast user switching away: another user's session is in front +/// let drafts = tracker.observe(SessionState { locked: false, on_console: false }); +/// assert_eq!(drafts[0].kind, kind::SESSION_INACTIVE); +/// assert!(!tracker.capturable()); +/// +/// // this user comes back, to a locked screen: both changes are reported, the lock first +/// let drafts = tracker.observe(SessionState { locked: true, on_console: true }); +/// let kinds: Vec<_> = drafts.iter().map(|draft| draft.kind).collect(); +/// assert_eq!(kinds, [kind::SCREEN_LOCKED, kind::SESSION_ACTIVE]); +/// ``` +#[derive(Debug, Default)] +pub struct SessionTracker { + last: SessionState, +} + +impl SessionTracker { + /// Compares `now` with the last state seen, makes `now` the last state, and returns an + /// incident for each change. + /// + /// A change of `locked` gives [`screen-locked`](kind::SCREEN_LOCKED) or + /// [`screen-unlocked`](kind::SCREEN_UNLOCKED), and a change of `on_console` gives + /// [`session-active`](kind::SESSION_ACTIVE) or + /// [`session-inactive`](kind::SESSION_INACTIVE); when both change, the lock comes first. So + /// the result has at most two drafts, and none while the state stays the same. The drafts are + /// undated: they are dated when they are recorded, which is the poll that saw the change. + /// + /// The first observation is compared with the default state. A recording that begins with the + /// screen locked sees a `screen-locked` incident from it unless the caller makes a first + /// observation to set the starting state and drops its drafts, as the recorder does. + pub fn observe(&mut self, now: SessionState) -> Vec { + let mut drafts = Vec::new(); + + if now.locked != self.last.locked { + drafts.push(if now.locked { + Draft::new( + kind::SCREEN_LOCKED, + "the screen was locked; video may pause or restart until it is unlocked", + ) + } else { + Draft::new(kind::SCREEN_UNLOCKED, "the screen was unlocked") + }); + } + + if now.on_console != self.last.on_console { + drafts.push(if now.on_console { + Draft::new( + kind::SESSION_ACTIVE, + "this user's session is in front again", + ) + } else { + Draft::new( + kind::SESSION_INACTIVE, + "another user's session is in front; this one is in the background", + ) + }); + } + + self.last = now; + drafts + } + + /// Returns true if and only if the session can currently be captured at all: the last state + /// seen was unlocked and at the console. + #[must_use] + pub fn capturable(&self) -> bool { + !self.last.locked && self.last.on_console + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn state(locked: bool, on_console: bool) -> SessionState { + SessionState { locked, on_console } + } + + #[test] + fn transitions_are_reported_once_each() { + let mut tracker = SessionTracker::default(); + assert!(tracker.observe(state(false, true)).is_empty()); + + let drafts = tracker.observe(state(true, true)); + assert_eq!(drafts.len(), 1); + assert_eq!(drafts[0].kind, kind::SCREEN_LOCKED); + assert!(!tracker.capturable()); + + assert!( + tracker.observe(state(true, true)).is_empty(), + "no repeat while it stays locked" + ); + + let drafts = tracker.observe(state(false, true)); + assert_eq!(drafts[0].kind, kind::SCREEN_UNLOCKED); + assert!(tracker.capturable()); + } + + #[test] + fn fast_user_switching_is_tracked_separately_from_locking() { + let mut tracker = SessionTracker::default(); + let drafts = tracker.observe(state(false, false)); + assert_eq!(drafts.len(), 1); + assert_eq!(drafts[0].kind, kind::SESSION_INACTIVE); + assert!(!tracker.capturable()); + + // both change at once: both are reported + let drafts = tracker.observe(state(true, true)); + let kinds: Vec<_> = drafts.iter().map(|draft| draft.kind).collect(); + assert_eq!(kinds, vec![kind::SCREEN_LOCKED, kind::SESSION_ACTIVE]); + } + + /// Against the real session: it must be readable, whatever state it is in. Whether the screen + /// happens to be locked while the tests run (a developer who stepped away, a CI machine under + /// a screensaver) is not something to assert on. + #[test] + fn reading_the_real_session_works_in_any_state() { + let state = read(); + + let mut tracker = SessionTracker::default(); + let drafts = tracker.observe(state); + + // the tracker agrees with what was read, and reports at most one change per flag + assert_eq!(tracker.capturable(), !state.locked && state.on_console); + assert!(drafts.len() <= 2); + } +}