feat(power): ride out sleep, lock and display changes

Docking, sleep and lock are where komorebi bugs show up, so the recording
carries on through them. On Windows a hidden window hears suspend, resume, the
lid, the displays and session lock as Windows delivers them; on a Mac a sleep is
found because the host clock pauses while the wall clock does not, and the lock
is polled on both hosts. A tracker turns these 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 instead of trusting the old one.
This commit is contained in:
LGUG2Z committed 2026-10-27 22:22:56 -07:00
1 parent fb11cb2db9
commit 383cc3c3db
13 files changed
+1142

No files matched your search

+5
View File
@@ -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
+12
View File
@@ -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 |
+3
View File
@@ -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;
@@ -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;
@@ -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<PowerEvent> {
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<dyn std::error::Error>>(())
/// ```
pub fn start() -> color_eyre::eyre::Result<Option<Watcher>> {
Ok(None)
}
@@ -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<bool> {
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::<CFBoolean>().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),
}
}
+4
View File
@@ -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;
@@ -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<PowerEvent> {
Vec::new()
}
}
/// Returns no watcher: this host has nothing to listen to.
///
/// # Errors
///
/// Never returns an error.
pub fn start() -> color_eyre::eyre::Result<Option<Watcher>> {
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;
@@ -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;
+323
View File
@@ -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<PowerEvent>,
window: isize,
thread: Option<JoinHandle<()>>,
}
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<PowerEvent> {
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<PowerEvent>;
// 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<eyre::Result<isize>>, events: Sender<PowerEvent>) {
let setup = || -> eyre::Result<(HWND, Box<Sender<PowerEvent>>)> {
// 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<Option<Watcher>> {
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),
}))
}
@@ -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 }
}
+396
View File
@@ -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<Draft>,
/// Anchors to add to the clock map: either side of a sleep.
pub anchors: Vec<Anchor>,
/// 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<Anchor>,
}
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());
}
}
+215
View File
@@ -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<Draft> {
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);
}
}