diff --git a/Cargo.lock b/Cargo.lock index 3e2d3efb..5e1629d0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -733,7 +733,9 @@ name = "komorebi" version = "0.1.0" dependencies = [ "clap", + "color-eyre", "komorebi-layouts", + "parking_lot", "schemars 1.2.3", "serde", "serde_json_lenient", @@ -820,6 +822,15 @@ version = "0.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae" +[[package]] +name = "lock_api" +version = "0.4.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965" +dependencies = [ + "scopeguard", +] + [[package]] name = "log" version = "0.4.34" @@ -892,6 +903,29 @@ version = "4.4.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "13c45bb4a6ae1280ec0803b1ef9d3455eb50f01efbbe1447ab020f1d54fba9d8" +[[package]] +name = "parking_lot" +version = "0.12.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a" +dependencies = [ + "lock_api", + "parking_lot_core", +] + +[[package]] +name = "parking_lot_core" +version = "0.9.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1" +dependencies = [ + "cfg-if", + "libc", + "redox_syscall", + "smallvec", + "windows-link", +] + [[package]] name = "percent-encoding" version = "2.3.2" @@ -964,6 +998,15 @@ version = "6.0.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" +[[package]] +name = "redox_syscall" +version = "0.5.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d" +dependencies = [ + "bitflags 2.13.2", +] + [[package]] name = "ref-cast" version = "1.0.27" @@ -1052,6 +1095,12 @@ dependencies = [ "syn 3.0.9", ] +[[package]] +name = "scopeguard" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" + [[package]] name = "serde" version = "1.0.229" diff --git a/README.md b/README.md index 8bc7172c..4439ddc5 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,10 @@ without a checkout of the toolchain. ## Crates - [`komorebi`](komorebi): the daemon, and the library behind it. The library has - the vocabulary the window manager is written in (`core`), the `Ring` that - holds monitors, workspaces and containers, and the lists in which some - elements are locked in place. + the vocabulary the window manager is written in (`core`), the `Backend` trait + through which it reaches a compositor and the in-memory desktop the tests use + (`backend`), the `Ring` that holds monitors, workspaces and containers, and the + lists in which some elements are locked in place. - [`version`](version): the version string every binary reports. The layouts, which turn a work area and a number of containers into a rectangle @@ -45,10 +46,20 @@ The VM tests boot NixOS with Plasma and run a real KWin. `just vm NAME` runs one; [`docs/dev/vm-tests.md`](docs/dev/vm-tests.md) has the details, including how to run them on a Mac. +## How it fits together + +The daemon decides where every window goes and asks the compositor to put it +there. Everything it needs from the compositor is behind one trait, `Backend`, +so the window manager logic runs against a real compositor and against an +in-memory fake desktop alike. [`docs/dev/ARCHITECTURE.md`](docs/dev/ARCHITECTURE.md) +describes the trait and where each of its rules is enforced. + ## Documentation `cargo doc --workspace --no-deps --open` builds the API documentation. -[`CONTRIBUTING.md`](CONTRIBUTING.md) says how to work on the code, and +[`CONTRIBUTING.md`](CONTRIBUTING.md) says how to work on the code. +[`docs/dev/ARCHITECTURE.md`](docs/dev/ARCHITECTURE.md) describes the model, +[`docs/dev/DESIGN.md`](docs/dev/DESIGN.md) says why it is built that way, and [`docs/dev/vm-tests.md`](docs/dev/vm-tests.md) how the VM tests work. ## License diff --git a/docs/dev/ARCHITECTURE.md b/docs/dev/ARCHITECTURE.md new file mode 100644 index 00000000..90ba1c37 --- /dev/null +++ b/docs/dev/ARCHITECTURE.md @@ -0,0 +1,99 @@ +# Architecture + +komorebi is a tiling window manager. It decides where every window goes and asks a +compositor to put it there. Everything it needs from the compositor is behind one trait, +[`Backend`](../../komorebi/src/backend/mod.rs), so the window manager is written, and +tested, without one. + +This page describes that trait, who implements and calls it, and where each of its rules +is enforced. It grows with the code: each part of the daemon that is added has its place +here. + +## Vocabulary + +- **Window**: a top-level surface a client has asked the compositor for, named by the + compositor's `u32` id. +- **Monitor**: a connected output, with its bounds and its work area (its bounds minus + the panels). +- **Compositor**: the program that owns the screen and the windows. On KDE Plasma it is + KWin. +- **Backend**: the implementation of the [`Backend`](../../komorebi/src/backend/mod.rs) + trait that talks to a compositor. +- **Fake**: [`FakeBackend`](../../komorebi/src/backend/fake.rs), the in-memory backend + the tests use. + +## Design + +The window manager reads the desktop and changes it through [`Backend`] and through +nothing else. A real backend answers from a table that compositor events keep up to date, +and sends commands to the compositor. The fake answers from a table the test fills in, and +records the commands. The window manager cannot tell them apart, which is the point: +the same logic runs against both. The reasons are in +[DESIGN.md](DESIGN.md#why-is-everything-the-window-manager-needs-behind-one-trait). + +## The model + +The desktop, as the window manager sees it, is two lists and a pointer: + +- **Windows**, each a [`WindowInfo`]: its id, process, title, `app_id`, executable, frame, + whether it is minimized, whether it is a normal application window (as opposed to a + dialog, a splash screen or a dock), and whether it is alive. A window that has been + destroyed stays in the table for a short time with `alive` false, so that the event that + mentions it can still be logged. +- **Monitors**, each a [`MonitorInfo`]: its id, name, an identity that survives a + hot-plug, its bounds and its work area. +- **The pointer**, a position if the compositor says where it is, and the **focus**, the id + of the window that has it. + +A command is one of: move and resize a window, focus it, raise it, minimize it or bring it +back, close it, and put the pointer in the middle of a rectangle. + +## The parts + +- [`backend`](../../komorebi/src/backend/mod.rs): the trait, the two data types, and the + process-wide handle ([`set_backend`], [`backend`], [`with_backend`]). +- [`backend::fake`](../../komorebi/src/backend/fake.rs): the fake. + +The handle is a process-wide singleton so that a window can be a small `Copy` value +that carries only its id, and ask the backend for what it needs. A test replaces it for +its own thread with [`with_backend`], which puts the previous one back when the test is +done, also if it panics. + +## Traits and roles + +**[`Backend`] is the compositor.** It is implemented once for each compositor and once for +the fake. The window manager is its only caller, through [`backend`]. The contract: + +- Queries (`windows`, `window`, `foreground_window`, `cursor_pos`) answer from the + backend's own table and never wait for the compositor. `monitors` may fail. +- A command returns once the compositor has accepted it, not once the client has acted on + it. The frame a window ends up with is what `window_rect` says afterwards, because a + client may refuse a size. +- A command about a window that does not exist, or is no longer alive, is an error. It + never panics. +- `shutdown`, `is_window`, `window_rect` and `monitor_from_point` have defaults, written in + terms of the queries. An implementor should not need to override them, except `shutdown` + when it created something in the compositor that has to be given up. + +## What is guaranteed, and by what + +| Rule | Enforced by | Proof | Escape hatch | +|---|---|---|---| +| A backend implements every query and command | type system: the methods have no defaults | `compile_fail,E0046` on [`Backend`] | none | +| A backend can be shared between threads | type system: `Backend: Send + Sync + 'static` | `compile_fail,E0277` on [`Backend`] | none | +| The window manager asks for a backend that was never installed | runtime error: [`backend`] panics, naming [`set_backend`] and [`with_backend`] | `# Panics` on [`backend`] | none | +| A test's backend does not outlive the test | framework path: [`with_backend`] restores the previous one on drop | `with_backend_puts_the_previous_backend_back_when_the_closure_panics` | none | +| A command about a missing window is an error, not a panic | test | `a_command_about_a_window_nobody_opened_is_an_error` and `a_command_about_a_closed_window_is_an_error`, against the fake only | none | +| Queries never block on the compositor | convention only | none | none | +| Only the backend module reaches the compositor | convention only | none | none | + +The last two rows are rules nothing checks. A real backend that waits inside a query +breaks the first, and a module that talks to D-Bus directly breaks the second. + +## Where to look in the code + +- [`komorebi/src/backend/mod.rs`](../../komorebi/src/backend/mod.rs): the trait. +- [`komorebi/src/backend/fake.rs`](../../komorebi/src/backend/fake.rs): the fake and its + tests. +- [`komorebi/src/core`](../../komorebi/src/core/mod.rs): the vocabulary the rest is written + in. diff --git a/docs/dev/DESIGN.md b/docs/dev/DESIGN.md new file mode 100644 index 00000000..c51507cf --- /dev/null +++ b/docs/dev/DESIGN.md @@ -0,0 +1,50 @@ +# Design + +This document explains why komorebi for KDE is built the way it is, one decision at a time. +It is opinionated: these are the reasons behind the code, and reasonable people may disagree +with them. Where a reason was not written down, the entry says that it needs one. + +It grows with the code: a decision is added in the commit that makes it. + +## What is komorebi for KDE the port of? + +komorebi has a Windows implementation, the original, and a macOS one. The Windows one is +the reference. I used it as the reference for what to adapt, and I prefer what KDE and +Wayland do natively over a workaround that the other two platforms need. The events the +window manager reacts to follow the Windows ones (a window is shown, destroyed, focused, +minimized, moved, resized), and a window is a small `Copy` handle, as there. + +## Why is everything the window manager needs behind one trait? + +So that the window manager can be tested without a compositor. A test that needs a real +KWin has to boot a virtual machine, which takes a minute or more and needs QEMU with a +hypervisor ([vm-tests.md](vm-tests.md)); a test against an in-memory desktop takes +milliseconds and runs anywhere. The logic (which window goes where, what happens when one +closes, how a stack cycles) is tested with the second kind, and the VM tests are kept for +what only KWin can tell. + +The cost is that a second implementation has to be kept honest. A fake that does what it +is told is not KWin: a real client may refuse a size, a compositor may report an event the +fake never raises, and a fake that is too permissive hides a bug that a compositor would +show. The fake is therefore written to be strict where KWin is (a command about a window +that no longer exists is an error) and to clamp where a real client does (a window with a +minimum size keeps to it). + +## Why is the backend a process-wide singleton? + +So that a window can be a small `Copy` value that carries only its id. A window that +had to hold a reference to its backend would not be `Copy`, and every function that +moves, focuses or hides one would take a context argument as well. That is a lot of +plumbing for a thing that never changes while the daemon runs. + +The cost is a global. A test that wants a private desktop overrides it for its own thread +with `with_backend`, which restores the previous one afterwards, also on a panic. + +## Why does a backend answer from a table instead of asking the compositor? + +A query that waits for the compositor can wait for a long time, and the window manager +asks a lot of questions: every move of a container is followed by a look at where each +window ended up. A backend keeps a table that the compositor's events update, so a query +is a lookup. The trade-off is that the table can be a moment behind the compositor, which +is why a command returns when it has been accepted and not when the client has acted, and +why the frame a window really has is read back afterwards. diff --git a/komorebi/Cargo.toml b/komorebi/Cargo.toml index 31244095..bc455c9c 100644 --- a/komorebi/Cargo.toml +++ b/komorebi/Cargo.toml @@ -9,6 +9,8 @@ komorebi-layouts = { workspace = true } version = { path = "../version" } clap = { workspace = true } +color-eyre = { workspace = true } +parking_lot = "0.12" schemars = { workspace = true, optional = true } serde = { workspace = true } serde_with = { version = "3", features = ["schemars_1"] } diff --git a/komorebi/src/backend/fake.rs b/komorebi/src/backend/fake.rs new file mode 100644 index 00000000..8e2ee60f --- /dev/null +++ b/komorebi/src/backend/fake.rs @@ -0,0 +1,513 @@ +//! An in-memory desktop, so that window manager logic can be tested without a compositor. +//! +//! A [`FakeBackend`] does what it is told, at once and exactly: a window asked to move to a +//! rectangle is at that rectangle, unless it was given a minimum size, which it then keeps to the +//! way a GTK4 client does. Every command is recorded, so that a test can assert on what the window +//! manager asked for, and a test can do what a user does (move a window, close it, change which +//! one has the focus) without the window manager having asked. +//! +//! # Example +//! +//! ```rust +//! use komorebi::backend::Backend; +//! use komorebi::backend::fake::Command; +//! use komorebi::backend::fake::FakeBackend; +//! use komorebi::core::Rect; +//! +//! let fake = FakeBackend::with_one_monitor(); +//! fake.open_window(1, "foot", "foot", "a terminal"); +//! +//! let tile = Rect { left: 0, top: 0, right: 960, bottom: 1050 }; +//! fake.set_rect(1, &tile)?; +//! +//! assert_eq!(fake.rect_of(1), Some(tile)); +//! assert_eq!(fake.commands(), [Command::SetRect(1, tile)]); +//! # Ok::<(), color_eyre::eyre::Report>(()) +//! ``` + +#![deny(missing_docs)] + +use super::Backend; +use super::MonitorInfo; +use super::WindowInfo; +use crate::core::Rect; +use color_eyre::eyre; +use parking_lot::Mutex; +use std::collections::HashMap; + +/// A command the window manager sent to the backend. +#[derive(Clone, Debug, PartialEq)] +pub enum Command { + /// [`Backend::set_rect`]: the window and the rectangle it was asked to take. + SetRect(u32, Rect), + /// [`Backend::focus`]: the window, and whether the pointer was to follow. + Focus(u32, bool), + /// [`Backend::raise`]. + Raise(u32), + /// [`Backend::minimize`]. + Minimize(u32), + /// [`Backend::unminimize`]. + Unminimize(u32), + /// [`Backend::close`]. + Close(u32), + /// [`Backend::center_cursor_in`]. + CenterCursor(Rect), +} + +#[derive(Default)] +struct State { + /// When set, a command about a window nobody opened creates that window first (see + /// [`FakeBackend::permissive`]). + permissive: bool, + windows: HashMap, + min_sizes: HashMap, + monitors: Vec, + foreground: Option, + cursor: Option<(i32, i32)>, + commands: Vec, +} + +/// An in-memory [`Backend`]. +/// +/// It has no windows and no monitors until a test adds them. The window manager reaches it through +/// [`crate::backend::backend`], installed with [`crate::backend::with_backend`]. +#[derive(Default)] +pub struct FakeBackend { + state: Mutex, +} + +impl FakeBackend { + /// Returns a fake with no monitors and no windows. + pub fn new() -> Self { + Self::default() + } + + /// Returns a fake that never refuses: a command about a window nobody opened creates it. + /// + /// The crate's own unit tests get one by default, so that a test of pure window manager logic, + /// which moves and focuses windows it never opened, needs no set-up. + pub fn permissive() -> Self { + let fake = Self::with_one_monitor(); + fake.state.lock().permissive = true; + fake + } + + /// Returns a fake with one 1920x1080 monitor, named `Virtual-0`, whose work area leaves 30 + /// pixels at the bottom for a panel. + pub fn with_one_monitor() -> Self { + let fake = Self::new(); + fake.add_monitor( + 1, + "Virtual-0", + Rect { + left: 0, + top: 0, + right: 1920, + bottom: 1080, + }, + Rect { + left: 0, + top: 0, + right: 1920, + bottom: 1050, + }, + ); + fake + } + + /// Adds a monitor. Its serial number identity is its name. + pub fn add_monitor(&self, id: u32, name: &str, size: Rect, work_area: Rect) { + self.state.lock().monitors.push(MonitorInfo { + id, + name: name.to_string(), + serial_number_id: name.to_string(), + size, + work_area, + }); + } + + /// Opens a window of an application. It starts at 800x600 at (100, 100), a normal window with + /// no focus. + pub fn open_window(&self, id: u32, exe: &str, class: &str, title: &str) { + self.state.lock().windows.insert( + id, + WindowInfo { + id, + pid: i32::try_from(id).unwrap_or_default() + 1000, + title: title.to_string(), + class: class.to_string(), + exe: exe.to_string(), + path: format!("/usr/bin/{exe}"), + rect: Rect { + left: 100, + top: 100, + right: 800, + bottom: 600, + }, + minimized: false, + normal: true, + alive: true, + }, + ); + } + + /// Destroys a window, as the user closing it does: the window manager is not asked. If it had + /// the focus, nothing has it now. + pub fn close_window_now(&self, id: u32) { + let mut state = self.state.lock(); + if let Some(window) = state.windows.get_mut(&id) { + window.alive = false; + } + if state.foreground == Some(id) { + state.foreground = None; + } + } + + /// Marks a window as a dialog, a splash screen, a utility window or the like, or as a normal + /// one again. + pub fn set_normal(&self, id: u32, normal: bool) { + if let Some(w) = self.state.lock().windows.get_mut(&id) { + w.normal = normal; + } + } + + /// Puts a window somewhere without the window manager having asked, as a user dragging it + /// does. + pub fn move_window_by_user(&self, id: u32, rect: Rect) { + if let Some(w) = self.state.lock().windows.get_mut(&id) { + w.rect = rect; + } + } + + /// Gives a window a minimum size. A [`Backend::set_rect`] for something smaller leaves it at + /// the minimum, which is how a GTK4 client answers. + pub fn set_min_size(&self, id: u32, width: i32, height: i32) { + self.state.lock().min_sizes.insert(id, (width, height)); + } + + /// Changes a window's title. + pub fn set_title(&self, id: u32, title: &str) { + if let Some(w) = self.state.lock().windows.get_mut(&id) { + w.title = title.to_string(); + } + } + + /// Changes which window has the focus, as the user does, without the window manager asking. + pub fn set_foreground(&self, id: Option) { + self.state.lock().foreground = id; + } + + /// Puts the pointer somewhere. + pub fn set_cursor(&self, x: i32, y: i32) { + self.state.lock().cursor = Some((x, y)); + } + + /// Returns where a window is, if it was ever opened. + pub fn rect_of(&self, id: u32) -> Option { + self.state.lock().windows.get(&id).map(|w| w.rect) + } + + /// Returns every command received so far, oldest first. + pub fn commands(&self) -> Vec { + self.state.lock().commands.clone() + } + + /// Forgets the commands received so far. + pub fn clear_commands(&self) { + self.state.lock().commands.clear(); + } + + fn record( + &self, + id: u32, + command: Command, + f: impl FnOnce(&mut State) -> T, + ) -> eyre::Result { + let mut state = self.state.lock(); + state.commands.push(command); + if state.permissive && !state.windows.contains_key(&id) { + state.windows.insert(id, permissive_window(id)); + } + match state.windows.get(&id) { + Some(w) if w.alive => Ok(f(&mut state)), + _ => eyre::bail!("no such window: {id}"), + } + } +} + +fn permissive_window(id: u32) -> WindowInfo { + WindowInfo { + id, + pid: i32::try_from(id).unwrap_or_default() + 1000, + title: format!("window {id}"), + class: format!("class.{id}"), + exe: format!("exe{id}"), + path: format!("/usr/bin/exe{id}"), + rect: Rect::default(), + minimized: false, + normal: true, + alive: true, + } +} + +impl Backend for FakeBackend { + fn windows(&self) -> Vec { + let state = self.state.lock(); + let mut windows: Vec<_> = state + .windows + .values() + .filter(|w| w.alive) + .cloned() + .collect(); + windows.sort_by_key(|w| w.id); + windows + } + + fn window(&self, id: u32) -> Option { + let mut state = self.state.lock(); + if state.permissive && !state.windows.contains_key(&id) { + state.windows.insert(id, permissive_window(id)); + } + state.windows.get(&id).cloned() + } + + fn foreground_window(&self) -> Option { + self.state.lock().foreground + } + + fn monitors(&self) -> eyre::Result> { + Ok(self.state.lock().monitors.clone()) + } + + fn cursor_pos(&self) -> Option<(i32, i32)> { + self.state.lock().cursor + } + + fn set_rect(&self, id: u32, rect: &Rect) -> eyre::Result<()> { + let rect = *rect; + self.record(id, Command::SetRect(id, rect), |state| { + let (min_w, min_h) = state.min_sizes.get(&id).copied().unwrap_or((0, 0)); + if let Some(w) = state.windows.get_mut(&id) { + w.rect = Rect { + left: rect.left, + top: rect.top, + right: rect.right.max(min_w), + bottom: rect.bottom.max(min_h), + }; + } + }) + } + + fn focus(&self, id: u32, mouse_follows_focus: bool) -> eyre::Result<()> { + self.record(id, Command::Focus(id, mouse_follows_focus), |state| { + state.foreground = Some(id); + if mouse_follows_focus && let Some(w) = state.windows.get(&id) { + state.cursor = Some(( + w.rect.left + w.rect.right / 2, + w.rect.top + w.rect.bottom / 2, + )); + } + }) + } + + fn raise(&self, id: u32) -> eyre::Result<()> { + self.record(id, Command::Raise(id), |_| ()) + } + + fn minimize(&self, id: u32) -> eyre::Result<()> { + self.record(id, Command::Minimize(id), |state| { + if let Some(w) = state.windows.get_mut(&id) { + w.minimized = true; + } + }) + } + + fn unminimize(&self, id: u32) -> eyre::Result<()> { + self.record(id, Command::Unminimize(id), |state| { + if let Some(w) = state.windows.get_mut(&id) { + w.minimized = false; + } + }) + } + + fn close(&self, id: u32) -> eyre::Result<()> { + self.record(id, Command::Close(id), |state| { + if let Some(w) = state.windows.get_mut(&id) { + w.alive = false; + } + }) + } + + fn center_cursor_in(&self, rect: &Rect) -> eyre::Result<()> { + let mut state = self.state.lock(); + state.commands.push(Command::CenterCursor(*rect)); + state.cursor = Some((rect.left + rect.right / 2, rect.top + rect.bottom / 2)); + Ok(()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn tile(left: i32, width: i32) -> Rect { + Rect { + left, + top: 0, + right: width, + bottom: 1050, + } + } + + fn fake_with(ids: &[u32]) -> FakeBackend { + let fake = FakeBackend::with_one_monitor(); + for id in ids { + fake.open_window(*id, "foot", "foot", &format!("window {id}")); + } + fake + } + + #[test] + fn a_window_asked_to_move_is_where_it_was_asked() -> eyre::Result<()> { + let fake = fake_with(&[1]); + + fake.set_rect(1, &tile(10, 500))?; + + assert_eq!(fake.rect_of(1), Some(tile(10, 500))); + Ok(()) + } + + #[test] + fn a_window_keeps_to_its_minimum_size() -> eyre::Result<()> { + let fake = fake_with(&[1]); + fake.set_min_size(1, 600, 400); + + fake.set_rect(1, &tile(0, 300))?; + + let rect = fake.rect_of(1).expect("window 1 was opened"); + assert_eq!((rect.right, rect.bottom), (600, 1050)); + Ok(()) + } + + #[test] + fn every_command_is_recorded_in_order() -> eyre::Result<()> { + let fake = fake_with(&[1, 2]); + + fake.focus(1, false)?; + fake.raise(2)?; + fake.minimize(1)?; + fake.unminimize(1)?; + fake.close(2)?; + + assert_eq!( + fake.commands(), + [ + Command::Focus(1, false), + Command::Raise(2), + Command::Minimize(1), + Command::Unminimize(1), + Command::Close(2), + ] + ); + fake.clear_commands(); + assert!(fake.commands().is_empty()); + Ok(()) + } + + #[test] + fn a_command_about_a_window_nobody_opened_is_an_error() { + let fake = fake_with(&[1]); + + let error = fake.focus(9, false).expect_err("window 9 does not exist"); + + assert_eq!(error.to_string(), "no such window: 9"); + } + + #[test] + fn a_command_about_a_closed_window_is_an_error() { + let fake = fake_with(&[1]); + fake.close_window_now(1); + + assert!(fake.raise(1).is_err()); + } + + #[test] + fn a_permissive_fake_creates_the_windows_it_is_asked_about() -> eyre::Result<()> { + let fake = FakeBackend::permissive(); + + fake.focus(77, false)?; + + assert!(fake.is_window(77)); + assert_eq!(fake.foreground_window(), Some(77)); + Ok(()) + } + + #[test] + fn focusing_with_the_mouse_following_puts_the_pointer_in_the_middle_of_the_window() + -> eyre::Result<()> { + let fake = fake_with(&[1]); + fake.set_rect(1, &tile(100, 200))?; + + fake.focus(1, true)?; + + assert_eq!(fake.cursor_pos(), Some((200, 525))); + Ok(()) + } + + #[test] + fn focusing_without_the_mouse_following_leaves_the_pointer_alone() -> eyre::Result<()> { + let fake = fake_with(&[1]); + fake.set_cursor(5, 5); + + fake.focus(1, false)?; + + assert_eq!(fake.cursor_pos(), Some((5, 5))); + Ok(()) + } + + #[test] + fn closing_the_window_with_the_focus_leaves_nothing_focused() { + let fake = fake_with(&[1]); + fake.set_foreground(Some(1)); + + fake.close_window_now(1); + + assert_eq!(fake.foreground_window(), None); + } + + #[test] + fn what_the_user_does_is_not_a_command() { + let fake = fake_with(&[1]); + + fake.move_window_by_user(1, tile(300, 300)); + fake.set_title(1, "renamed"); + fake.set_normal(1, false); + + assert!(fake.commands().is_empty()); + assert_eq!(fake.rect_of(1), Some(tile(300, 300))); + let window = fake.window(1).expect("window 1 was opened"); + assert_eq!(window.title, "renamed"); + assert!(!window.normal); + } + + #[test] + fn windows_are_listed_by_id_and_a_destroyed_one_is_left_out() { + let fake = fake_with(&[3, 1, 2]); + fake.close_window_now(2); + + let ids: Vec<_> = fake.windows().iter().map(|w| w.id).collect(); + + assert_eq!(ids, [1, 3]); + } + + #[test] + fn the_cursor_can_be_centered_in_a_rectangle() -> eyre::Result<()> { + let fake = FakeBackend::new(); + + fake.center_cursor_in(&tile(0, 400))?; + + assert_eq!(fake.cursor_pos(), Some((200, 525))); + assert_eq!(fake.commands(), [Command::CenterCursor(tile(0, 400))]); + Ok(()) + } +} diff --git a/komorebi/src/backend/mod.rs b/komorebi/src/backend/mod.rs new file mode 100644 index 00000000..15de867f --- /dev/null +++ b/komorebi/src/backend/mod.rs @@ -0,0 +1,380 @@ +//! Everything the window manager needs from the desktop, behind one trait. +//! +//! The window manager logic (windows, containers, workspaces, monitors) never talks to KWin, to +//! `/proc` or to D-Bus. It talks to a [`Backend`]. A real backend asks the compositor; the one the +//! tests use is [`fake::FakeBackend`], an in-memory desktop that does what it is told and records +//! what it was asked. +//! +//! # The backend is process-wide +//! +//! The backend is a singleton, like the other globals of this crate, so that a window can be a +//! small `Copy` handle that carries only its id: `window.set_position(..)` needs no context passed +//! to it. [`set_backend`] installs it once at startup, and [`backend`] returns it. A test that needs +//! a private desktop uses [`with_backend`], which overrides the backend for the current thread +//! only and puts the previous one back afterwards, so tests cannot leak a desktop into each other. +//! +//! # Queries and commands +//! +//! Queries are answered from the backend's own table, which compositor events keep up to date, so +//! they never wait for the compositor. A window that has just been closed stays queryable for a +//! short time, with [`WindowInfo::alive`] false, so that the event that mentions it can still be +//! logged. Commands return once the compositor has accepted them, not once the client has acted on +//! them, and an implementation may batch them. + +#![deny(missing_docs)] + +use crate::core::Rect; +use color_eyre::eyre; +use parking_lot::RwLock; +use std::cell::RefCell; +use std::sync::Arc; + +pub mod fake; + +/// What the compositor currently knows about one window. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct WindowInfo { + /// The compositor's id for the window, which is how every other part of komorebi names it. + pub id: u32, + /// The id of the process that owns the window. + pub pid: i32, + /// The window's title. + pub title: String, + /// The Wayland `app_id` (the X11 `WM_CLASS` for a client that runs on XWayland). + pub class: String, + /// The file name of the executable, read from `/proc//exe`. + pub exe: String, + /// The full path of the executable. + pub path: String, + /// The window's frame. + pub rect: Rect, + /// Whether the window is minimized. + pub minimized: bool, + /// Whether the compositor considers this a normal application window, as opposed to a dialog, + /// a splash screen, a utility window, a dock and so on. + pub normal: bool, + /// False once the window has been destroyed. + pub alive: bool, +} + +/// A connected monitor, in logical pixels. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct MonitorInfo { + /// The compositor's id for the monitor. + pub id: u32, + /// The name of the output (`DP-1`, `Virtual-0`). + pub name: String, + /// An identity for the monitor that stays the same across a hot-plug and a restart. + pub serial_number_id: String, + /// The monitor's bounds. + pub size: Rect, + /// `size` minus the panels and other areas the compositor reserves. + pub work_area: Rect, +} + +/// The desktop, as the window manager sees it. +/// +/// This is the **only** way the window manager reaches the compositor. Everything else in the crate +/// is testable without one. +/// +/// # Who implements it, who calls it +/// +/// A backend is implemented once per compositor, and by the in-memory [`fake::FakeBackend`]. It is +/// called by the window manager, through [`backend`]; nothing else should hold a reference to it. +/// +/// # Contract +/// +/// - Queries never block on the compositor and never fail, except [`Backend::monitors`], which may +/// fail when the compositor cannot say. +/// - A command about a window that does not exist, or is no longer alive, returns an error. It does +/// not panic. +/// - A backend is `Send + Sync`: the window manager calls it from several threads. +/// +/// The compiler enforces the first and last parts of the contract that it can see. A backend that +/// leaves out a method does not compile: +/// +/// ```rust,compile_fail,E0046 +/// use komorebi::backend::Backend; +/// +/// struct Nothing; +/// +/// impl Backend for Nothing {} +/// ``` +/// +/// And neither does one that cannot be shared between threads: +/// +/// ```rust,compile_fail,E0277 +/// # use std::rc::Rc; +/// # use color_eyre::eyre; +/// # use komorebi::backend::{Backend, MonitorInfo, WindowInfo}; +/// # use komorebi::core::Rect; +/// struct NotShareable(Rc); +/// +/// # impl Backend for NotShareable { +/// # fn windows(&self) -> Vec { vec![] } +/// # fn window(&self, _: u32) -> Option { None } +/// # fn foreground_window(&self) -> Option { None } +/// # fn monitors(&self) -> eyre::Result> { Ok(vec![]) } +/// # fn cursor_pos(&self) -> Option<(i32, i32)> { None } +/// # fn set_rect(&self, _: u32, _: &Rect) -> eyre::Result<()> { Ok(()) } +/// # fn focus(&self, _: u32, _: bool) -> eyre::Result<()> { Ok(()) } +/// # fn raise(&self, _: u32) -> eyre::Result<()> { Ok(()) } +/// # fn minimize(&self, _: u32) -> eyre::Result<()> { Ok(()) } +/// # fn unminimize(&self, _: u32) -> eyre::Result<()> { Ok(()) } +/// # fn close(&self, _: u32) -> eyre::Result<()> { Ok(()) } +/// # fn center_cursor_in(&self, _: &Rect) -> eyre::Result<()> { Ok(()) } +/// # } +/// ``` +pub trait Backend: Send + Sync + 'static { + // ---- queries ------------------------------------------------------------------------------- + + /// Returns every window on the desktop that is a candidate for management, ordered by id. + fn windows(&self) -> Vec; + + /// Returns what is known about the window, or `None` if the compositor has never heard of it. + fn window(&self, id: u32) -> Option; + + /// Returns the id of the window that has the focus, if any window does. + fn foreground_window(&self) -> Option; + + /// Returns every connected monitor. + /// + /// # Errors + /// + /// When the compositor cannot report its outputs. + fn monitors(&self) -> eyre::Result>; + + /// Returns where the pointer is, if the compositor says. + fn cursor_pos(&self) -> Option<(i32, i32)>; + + // ---- commands ------------------------------------------------------------------------------ + + /// Moves and resizes the window to `rect`, a position and a size. + /// + /// A client may refuse the size (a minimum size, for one), so the frame the window ends up with + /// is [`Backend::window_rect`], not `rect`. + /// + /// # Errors + /// + /// When the window does not exist or is no longer alive. + fn set_rect(&self, id: u32, rect: &Rect) -> eyre::Result<()>; + + /// Gives the window the focus, and, if `mouse_follows_focus`, puts the pointer in its middle. + /// + /// # Errors + /// + /// When the window does not exist or is no longer alive. + fn focus(&self, id: u32, mouse_follows_focus: bool) -> eyre::Result<()>; + + /// Raises the window above the others. + /// + /// # Errors + /// + /// When the window does not exist or is no longer alive. + fn raise(&self, id: u32) -> eyre::Result<()>; + + /// Minimizes the window. + /// + /// # Errors + /// + /// When the window does not exist or is no longer alive. + fn minimize(&self, id: u32) -> eyre::Result<()>; + + /// Brings a minimized window back. + /// + /// # Errors + /// + /// When the window does not exist or is no longer alive. + fn unminimize(&self, id: u32) -> eyre::Result<()>; + + /// Asks the window to close. + /// + /// # Errors + /// + /// When the window does not exist or is no longer alive. + fn close(&self, id: u32) -> eyre::Result<()>; + + /// Puts the pointer in the middle of `rect`. + /// + /// # Errors + /// + /// When the compositor refuses to move the pointer. + fn center_cursor_in(&self, rect: &Rect) -> eyre::Result<()>; + + // ---- provided ------------------------------------------------------------------------------ + + /// Called once as komorebi exits, after the window manager has put back what it moved, so that + /// the backend can give up whatever it created itself. + /// + /// The default does nothing. Implementors should not need to override it unless they created + /// something in the compositor. + fn shutdown(&self) {} + + /// Returns true if and only if the compositor has a live window with this id. + fn is_window(&self, id: u32) -> bool { + self.window(id).is_some_and(|w| w.alive) + } + + /// Returns the window's frame, if the compositor knows the window. + fn window_rect(&self, id: u32) -> Option { + self.window(id).map(|w| w.rect) + } + + /// Returns the id of the monitor whose bounds contain the point. + fn monitor_from_point(&self, x: i32, y: i32) -> Option { + self.monitors().ok()?.into_iter().find_map(|m| { + let (l, t) = (m.size.left, m.size.top); + let (r, b) = (l + m.size.right, t + m.size.bottom); + (x >= l && x < r && y >= t && y < b).then_some(m.id) + }) + } +} + +static BACKEND: RwLock>> = RwLock::new(None); + +thread_local! { + static OVERRIDE: RefCell>> = const { RefCell::new(None) }; +} + +/// Installs the process-wide backend. Called once at startup. +pub fn set_backend(backend: Arc) { + *BACKEND.write() = Some(backend); +} + +/// Returns the backend for this thread: the thread's override if there is one, else the +/// process-wide one. +/// +/// # Panics +/// +/// If no backend has been installed. That is a bug in the order of start-up, not a condition at +/// run time. Install one with [`set_backend`], or with [`with_backend`] in a test. +pub fn backend() -> Arc { + OVERRIDE + .with(|o| o.borrow().clone()) + .or_else(|| BACKEND.read().clone()) + .or_else(test_default) + .expect( + "no backend installed: call backend::set_backend (or backend::with_backend in tests)", + ) +} + +/// The crate's own unit tests get a private, permissive fake per thread when they install nothing, +/// so that a test of pure window manager logic needs no set-up. Everything else gets no default. +#[cfg(test)] +fn test_default() -> Option> { + OVERRIDE.with(|o| { + let backend: Arc = Arc::new(fake::FakeBackend::permissive()); + *o.borrow_mut() = Some(backend.clone()); + Some(backend) + }) +} + +#[cfg(not(test))] +fn test_default() -> Option> { + None +} + +/// Runs `f` with `backend` as this thread's backend, and puts the previous override back +/// afterwards, also when `f` panics. +/// +/// # Example +/// +/// ```rust +/// use std::sync::Arc; +/// +/// use komorebi::backend::Backend; +/// use komorebi::backend::backend; +/// use komorebi::backend::fake::FakeBackend; +/// use komorebi::backend::with_backend; +/// +/// let fake = Arc::new(FakeBackend::with_one_monitor()); +/// fake.open_window(7, "foot", "foot", "a terminal"); +/// +/// let titles = with_backend(fake.clone(), || { +/// backend().windows().into_iter().map(|w| w.title).collect::>() +/// }); +/// +/// assert_eq!(titles, ["a terminal"]); +/// ``` +pub fn with_backend(backend: Arc, f: impl FnOnce() -> R) -> R { + struct Restore(Option>); + impl Drop for Restore { + fn drop(&mut self) { + OVERRIDE.with(|o| *o.borrow_mut() = self.0.take()); + } + } + + let _restore = Restore(OVERRIDE.with(|o| o.borrow_mut().replace(backend))); + f() +} + +#[cfg(test)] +mod tests { + use super::*; + use fake::FakeBackend; + + #[test] + fn a_thread_that_installs_nothing_gets_a_permissive_fake_in_unit_tests() { + let id = 41; + + assert!(backend().window(id).is_some()); + } + + #[test] + fn with_backend_overrides_the_backend_and_puts_the_previous_one_back() { + let outer = Arc::new(FakeBackend::with_one_monitor()); + outer.open_window(1, "outer", "outer", "outer"); + let inner = Arc::new(FakeBackend::with_one_monitor()); + inner.open_window(2, "inner", "inner", "inner"); + + with_backend(outer, || { + with_backend(inner, || { + assert!(backend().is_window(2)); + assert!(!backend().is_window(1)); + }); + + assert!(backend().is_window(1)); + assert!(!backend().is_window(2)); + }); + } + + #[test] + fn with_backend_puts_the_previous_backend_back_when_the_closure_panics() { + let outer = Arc::new(FakeBackend::with_one_monitor()); + outer.open_window(1, "outer", "outer", "outer"); + + with_backend(outer, || { + let inner = Arc::new(FakeBackend::with_one_monitor()); + let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { + with_backend(inner, || panic!("a test")) + })); + + assert!(result.is_err()); + assert!(backend().is_window(1)); + }); + } + + #[test] + fn the_provided_methods_are_answered_from_the_queries() { + let fake = FakeBackend::with_one_monitor(); + fake.open_window(5, "foot", "foot", "a terminal"); + + assert!(fake.is_window(5)); + assert!(!fake.is_window(6)); + assert_eq!(fake.window_rect(5), fake.rect_of(5)); + assert_eq!(fake.monitor_from_point(10, 10), Some(1)); + assert_eq!(fake.monitor_from_point(5000, 10), None); + } + + #[test] + fn a_destroyed_window_is_no_longer_a_window_but_can_still_be_asked_about() { + let fake = FakeBackend::with_one_monitor(); + fake.open_window(5, "foot", "foot", "a terminal"); + + fake.close_window_now(5); + + assert!(!fake.is_window(5)); + assert!(fake.window(5).is_some_and(|w| !w.alive)); + assert!(fake.windows().is_empty()); + } +} diff --git a/komorebi/src/lib.rs b/komorebi/src/lib.rs index b42ba833..fc7953b2 100644 --- a/komorebi/src/lib.rs +++ b/komorebi/src/lib.rs @@ -4,5 +4,6 @@ #[macro_use] pub mod ring; +pub mod backend; pub mod core; pub mod lockable_sequence;