feat(wm): subscribe to notifications

A program such as a status bar has to follow the window manager, and so far it
could only ask: komorebi on Windows and on macOS sends notifications for that.
The daemon now keeps subscribers, each a Unix socket in its data directory that
a program listens on, and after each event and each message it handles, it
connects to every subscriber and writes the event or the message with the state
after it.

A subscriber can ask to be sent only what changed the state; a window that is
shown and a new subscription are always sent, so a subscriber has the state as
soon as it subscribes. A subscriber that cannot be connected to is dropped with
its socket file and not tried again, and a stopping daemon closes an empty
connection to each one.

komorebic gains subscribe-socket and unsubscribe-socket, and komorebi-client
subscribe and subscribe_with_options, which bind the socket and subscribe. The
tests subscribe through real sockets against the fake desktop: a shown window is
sent with the state that has it, a subscriber that filters is not sent a
question that changed nothing, and one that is gone is dropped.
This commit is contained in:
LGUG2Z committed 2026-10-28 07:20:37 -07:00
1 parent 6f657e53e3
commit e2d757bbb0
20 files changed
+1078 -25

No files matched your search

+14
View File
@@ -0,0 +1,14 @@
```text
Subscribe to komorebi events using a Unix Domain Socket
Usage: subscribe-socket <SOCKET>
Arguments:
<SOCKET>
Name of the socket to send event notifications to
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```text
Unsubscribe from komorebi events
Usage: unsubscribe-socket <SOCKET>
Arguments:
<SOCKET>
Name of the socket to stop sending event notifications to
Options:
-h, --help
Print help
```
+61 -5
View File
@@ -7,8 +7,9 @@ tested, without one.
This page describes that trait, who implements and calls it, where each of its rules is
enforced, the model of the desktop the window manager tiles, the backend that reaches KWin,
how an event about a window becomes a tile, and how a message on the daemon's socket is
answered. It grows with the code: each part of the daemon that is added has its place here.
how an event about a window becomes a tile, how a message on the daemon's socket is
answered, and how subscribers are notified of both. It grows with the code: each part of the
daemon that is added has its place here.
## Vocabulary
@@ -28,6 +29,10 @@ answered. It grows with the code: each part of the daemon that is added has its
(retile, stop) or a question (the state, the monitors, one [`StateQuery`]).
- **State**: the window manager's monitors, workspaces, containers and windows, and its
settings, as the daemon answers a `State` message with them ([`State`]).
- **Subscriber**: a program that listens on a socket of its own in [`DATA_DIR`] and has
asked the daemon, by the name of that socket, to send it notifications.
- **Notification**: what a subscriber is sent after each event and each message the window
manager handles: the event or the message, and the state after it ([`Notification`]).
- **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)
@@ -191,6 +196,37 @@ connection close with no answer.
what it set up in the compositor (the KWin backend unloads the bridge), and exits with
status 0. `SIGINT` and `SIGTERM` do the same from `main.rs`, with the exit status 130.
## Notifications
A subscriber binds a socket in [`DATA_DIR`] and sends `AddSubscriberSocket` with its name,
or `AddSubscriberSocketWithOptions` with its name and [`SubscribeOptions`]
([`subscribe`], [`subscribe_with_options`], `komorebic subscribe-socket`).
[`WindowManager::process_command`] records it in [`SUBSCRIPTION_SOCKETS`], and its options in
[`SUBSCRIPTION_SOCKET_OPTIONS`]. `RemoveSubscriberSocket` takes it out again. The
subscribers are kept in memory only, and a daemon that restarts has none.
At the end of [`WindowManager::process_event`] and of [`WindowManager::process_command`],
the window manager calls [`notify_subscribers`] with a [`Notification`]: the event or the
message ([`NotificationEvent`]), and the [`State`] after it. A [`State`] made before the event
or the message is compared with the window manager after it ([`State::has_been_modified`]);
the monitors are compared down to the windows, and a window by its id only. An event about a
window komorebi does not manage, and a message that fails, return before this and are not
notified.
[`notify_subscribers`] serializes the notification once, and for each subscriber connects to
its socket, writes the JSON and closes the connection, all on the thread that handled the
event or the message, with the window manager still locked. A subscriber with
`filter_state_changes` is skipped when the state did not change, unless the notification is
about a window being shown or a subscriber being added. A subscriber that cannot be
connected to is removed, with its socket file, after the loop. Writing to a subscriber that
was connected to has no timeout, and a failed write returns an error from the call that
handled the event or the message. A subscriber that stops reading therefore holds the window
manager, and with it the thread that handles events: the backend's events wait in the
channel of [`window_manager_event_listener`], and past 20 the backend drops them.
When the daemon stops ([`WindowManager::stop`], or `SIGINT` and `SIGTERM` in `main.rs`), it
connects to each subscriber and shuts the connection down without writing anything.
## The parts
- [`backend`](../../komorebi/src/backend/mod.rs): the trait, the two data types, and the
@@ -220,9 +256,13 @@ status 0. `SIGINT` and `SIGTERM` do the same from `main.rs`, with the exit statu
[`bridge.js`](../../komorebi/src/kwin/bridge.js), the bridge.
- [`process_command`](../../komorebi/src/process_command.rs): the thread that listens on the
socket, and what the window manager does with each message.
- [`state`](../../komorebi/src/state.rs): the [`State`] a `State` message is answered with.
- [`state`](../../komorebi/src/state.rs): the [`State`] a `State` message is answered with,
and whether an event or a message changed it.
- [`lib.rs`](../../komorebi/src/lib.rs): the subscribers, the [`Notification`], and
[`notify_subscribers`].
- [`komorebi-client`](../../komorebi-client/src/lib.rs): a library that writes messages on
the socket and reads the answers, for programs that talk to the daemon.
the socket and reads the answers, and subscribes to notifications, for programs that talk
to the daemon.
- [`komorebic`](../../komorebic/src/main.rs): the command line. A subcommand that asks
something of the daemon is one message, sent with `komorebi-client`; `start` runs the
daemon, `log` follows its log file in [`LOG_DIR`], and the hidden `docgen` writes
@@ -282,6 +322,7 @@ the fake. The window manager is its only caller, through [`backend`]. The contra
| Messages are handled one at a time, and in order on one connection | framework path: [`read_commands_uds`] reads a connection line by line and handles each message with the window manager locked | `the_messages_on_one_connection_are_handled_in_order` | none |
| A socket left behind by a daemon that did not stop cleanly does not keep the next one from starting | framework path: [`WindowManager::new`] removes the file before it binds | `a_socket_file_left_behind_is_replaced` | none |
| A daemon that is told to stop leaves no socket behind | framework path: [`WindowManager::stop`] removes it before it exits | `the_daemon_answers_on_its_socket_and_stops_when_it_is_told_to` | `SIGKILL` |
| A subscriber that is gone is dropped, not retried | test | `a_subscriber_that_is_gone_is_dropped_and_not_tried_again` | none |
| The bridge holds no window manager logic | convention, with every decision about an event in the table, which the `kwin::state` unit tests pin | the unit tests in `komorebi/src/kwin/state.rs` | none |
| What the bridge sends is what the table reads | type checker: the JSDoc types of the messages in [`bridge.js`]; tests: the events of [`fixtures`] are what the bridge's tests check it sends and what the table's tests feed it | `what the bridge sends for a session is what the daemon's tests read`, `the_bridges_events_for_a_session_are_the_window_events_komorebi_expects` | none |
| What the backend sends is what the bridge carries out | tests: the commands of [`fixtures`] are what the backend's tests check it sends and what the bridge's tests answer it with, checking what KWin is asked to do for each | `the_commands_of_a_session_go_to_the_bridge_as_the_bridges_tests_answer_it`, `what the bridge sends for a session is what the daemon's tests read`, `a command for a window KWin no longer has is given back, and the rest are carried out` | none |
@@ -326,6 +367,9 @@ A window is shown, and ends up on a tile:
`focus`, and the pointer follows it (on KWin, through its "Move Mouse to Focus"
shortcut).
8. The index is rebuilt again, so the next event finds the window.
9. [`notify_subscribers`] sends every subscriber a [`Notification`] of the `Show`, with the
state that now has the window. A `Show` is sent to a subscriber with
`filter_state_changes` too, whether or not it changed the state.
## One message, end to end
@@ -341,7 +385,8 @@ A window is shown, and ends up on a tile:
every monitor with its workspaces, containers and windows. Each window is serialized
with what the backend reports about it now: its frame, title, executable, class and path.
5. The state is written to the connection as pretty-printed JSON, and the index of managed
windows is rebuilt, as after every message.
windows is rebuilt, as after every message. The subscribers are sent a notification of
the `State` message, except those with `filter_state_changes`: it changed nothing.
6. There are no more lines, so `read_commands_uds` returns and the connection is closed.
`send_query` has read to the end, and returns the JSON, which `komorebic` prints.
@@ -362,6 +407,8 @@ A window is shown, and ends up on a tile:
each message does, and the tests that send messages through a real socket.
- [`komorebi-client/src/lib.rs`](../../komorebi-client/src/lib.rs): the client side of the
socket.
- [`komorebi-client/tests/subscribe.rs`](../../komorebi-client/tests/subscribe.rs):
subscribers and the notifications they are sent, through real sockets.
- [`komorebic/src/main.rs`](../../komorebic/src/main.rs): the subcommands, and
[`komorebic/tests/cli.rs`](../../komorebic/tests/cli.rs), what each writes on the socket.
- [`komorebi/src/kwin/mod.rs`](../../komorebi/src/kwin/mod.rs): the KWin backend, its D-Bus
@@ -421,6 +468,13 @@ A window is shown, and ends up on a tile:
[`SocketMessage`]: ../../komorebi/src/core/mod.rs
[`StateQuery`]: ../../komorebi/src/core/mod.rs
[`State`]: ../../komorebi/src/state.rs
[`State::has_been_modified`]: ../../komorebi/src/state.rs
[`SubscribeOptions`]: ../../komorebi/src/core/mod.rs
[`Notification`]: ../../komorebi/src/lib.rs
[`NotificationEvent`]: ../../komorebi/src/lib.rs
[`notify_subscribers`]: ../../komorebi/src/lib.rs
[`SUBSCRIPTION_SOCKETS`]: ../../komorebi/src/lib.rs
[`SUBSCRIPTION_SOCKET_OPTIONS`]: ../../komorebi/src/lib.rs
[`WindowManager::new`]: ../../komorebi/src/window_manager.rs
[`WindowManager::stop`]: ../../komorebi/src/window_manager.rs
[`WindowManager::process_command`]: ../../komorebi/src/process_command.rs
@@ -429,3 +483,5 @@ A window is shown, and ends up on a tile:
[`send_query`]: ../../komorebi-client/src/lib.rs
[`send_message`]: ../../komorebi-client/src/lib.rs
[`send_batch`]: ../../komorebi-client/src/lib.rs
[`subscribe`]: ../../komorebi-client/src/lib.rs
[`subscribe_with_options`]: ../../komorebi-client/src/lib.rs
+11
View File
@@ -171,3 +171,14 @@ Because the daemon takes no input but its socket. `komorebic` turns a command li
message on the socket and, for a question, prints the answer. A key binding, a script and a
person at a terminal all drive komorebi the same way, by running `komorebic` (the design
notes of komorebi for Mac, linked above).
## Why does komorebi send notifications to subscribers?
So that a program such as a status bar can follow the window manager. The README of komorebi
for Windows demonstrates a custom status bar integrated through its notifications
([Window Manager Event Subscriptions](https://github.com/LGUG2Z/komorebi#window-manager-event-subscriptions)),
and komorebi for Mac sends the same notifications to Unix sockets, which is also how
`komorebic` talks to its daemon
([its README](https://github.com/LGUG2Z/komorebi-for-mac#window-manager-event-subscriptions)).
A subscriber here is a Unix socket, as on macOS. The named pipes that komorebi on Windows
sends notifications to are not ported, since the socket subscribers do the same.
+5 -4
View File
@@ -89,10 +89,10 @@ an owner again; the VM test `vm-kwin-restart` restarts KWin twice under a runnin
#### What komorebi leaves behind
When it is stopped with `SIGINT`, `SIGTERM` or a `Stop` message on its socket, it asks KWin
to unload the script and removes the socket. The file `bridge.js` stays in the runtime
directory, which is removed at logout. A daemon that is killed leaves the script running in
KWin, reporting to nobody, and the socket file in the runtime directory, until the next start
replaces both or the session ends.
to unload the script, closes an empty connection to each subscriber, and removes the socket.
The file `bridge.js` stays in the runtime directory, which is removed at logout. A daemon
that is killed leaves the script running in KWin, reporting to nobody, and the socket file in
the runtime directory, until the next start replaces both or the session ends.
### A headless KWin
@@ -144,6 +144,7 @@ What komorebi calls:
|---|---|---|
| `$XDG_RUNTIME_DIR/komorebi/bridge.js` | the script KWin loads, with its configuration (the D-Bus names and the hold time of `Poll`) on its first line | written at every start; the directory is removed at logout |
| `$XDG_RUNTIME_DIR/komorebi/komorebi.sock` | the command socket | bound once the daemon is connected to KWin, after a file left there is removed; removed when the daemon stops |
| `$XDG_RUNTIME_DIR/komorebi/NAME` | the socket of a subscriber, which the subscriber binds and names in its subscription | removed by the daemon, with the subscriber, when it cannot connect to it |
| `$XDG_DATA_HOME/komorebi/komorebi.log.YYYY-MM-DD` | the daemon's log, with colors, which `komorebic log` follows | a file a day (the UTC date), never removed by komorebi |
| `$XDG_DATA_HOME/komorebi/komorebi_plaintext.log.YYYY-MM-DD` | the same log without colors | as above |
+4 -2
View File
@@ -29,8 +29,10 @@ key bindings --------> komorebic <------> komorebi
## Getting started
[Running komorebi](usage/running-komorebi.md) explains how to get the two programs, start and
stop the daemon, ask it what it is doing and read its log. The [CLI reference](cli/start.md)
has a page for every `komorebic` command, generated from its help.
stop the daemon, ask it what it is doing and read its log.
[Subscribing to notifications](usage/subscribing-to-notifications.md) explains how a program
such as a status bar follows what komorebi does. The [CLI reference](cli/start.md) has a page
for every `komorebic` command, generated from its help.
## Community
+3
View File
@@ -66,6 +66,9 @@ a window that was moved by hand back on its tile.
When the daemon is not running, these commands fail: there is no socket to write to.
A program that wants to know what komorebi does without asking can subscribe to its
notifications instead ([Subscribing to notifications](subscribing-to-notifications.md)).
## The socket and the data directory
The daemon listens on `komorebi.sock` in its data directory, `$XDG_RUNTIME_DIR/komorebi`
@@ -0,0 +1,83 @@
# Subscribing to notifications
A program such as a status bar, a widget or a script can follow what komorebi does by
subscribing to its notifications. After each event the window manager handles (a window
was shown, closed, focused, minimized or restored) and each message it takes on its socket,
the daemon sends every subscriber a notification: the event or the message, and the state
of the window manager after it.
## Subscribing
A subscriber listens on a Unix socket of its own in the daemon's data directory,
`$XDG_RUNTIME_DIR/komorebi` (on NixOS and most systemd distributions,
`/run/user/<uid>/komorebi`), and tells the daemon the name of the socket with
[`komorebic subscribe-socket`](../cli/subscribe-socket.md). The socket has to exist before
it subscribes: the daemon sends the notification of the subscription at once, and removes a
subscriber it cannot connect to.
With [socat](http://www.dest-unreach.org/socat/), a shell can subscribe and print every
notification:
```sh
socat -u UNIX-LISTEN:"$XDG_RUNTIME_DIR/komorebi/bar.sock",fork STDOUT &
komorebic subscribe-socket bar.sock
```
[`komorebic unsubscribe-socket bar.sock`](../cli/unsubscribe-socket.md) stops the
notifications.
## Notifications
The daemon sends each notification on a new connection to the subscriber's socket: it
connects, writes one JSON object, and closes the connection. There is no newline after the
object. The first notification a subscriber receives is the one of its subscription.
A notification has two fields:
- `event`: the event or the message. An event is a window event, with the signal it came
from and the window, such as
`{"type":"Show","content":[{"type":"KWin","content":"WindowAdded"},{"id":...}]}`. A
message is written the way a client writes it on the daemon's socket, such as
`{"type":"Retile"}`.
- `state`: the state of the window manager after it, with the same fields as what
[`komorebic state`](../cli/state.md) prints, on one line.
An event about a window that komorebi does not manage, and a message that fails, are not
sent.
## Only when something changed
A subscriber can ask to be sent a notification only when the event or the message changed
the state, with the `filter_state_changes` option. It is still sent the notification of a
window that is shown and of every new subscription, so it receives the state as soon as it
subscribes. `komorebic subscribe-socket` has no option for it; a program writes the message
on the daemon's socket itself:
```sh
printf '%s' '{"type":"AddSubscriberSocketWithOptions","content":["bar.sock",{"filter_state_changes":true}]}' |
socat - UNIX-CONNECT:"$XDG_RUNTIME_DIR/komorebi/komorebi.sock"
```
## When a subscriber goes away
A subscriber that the daemon cannot connect to, because its program has exited or its
socket was removed, is removed at the next notification, and its socket file with it. The
daemon does not try it again: a program that wants notifications again subscribes again.
The daemon keeps its subscribers only while it runs, so after a restart every program has
to subscribe again.
When the daemon stops, it connects to each subscriber and closes the connection without
writing anything.
A subscriber should accept and read every connection as it comes. The daemon writes each
notification while the window manager is locked, and waits when the socket's buffer is
full, so a subscriber that stops reading can hold up the window manager. While it is held
up, the window events KWin reports wait for it, and once 20 are waiting the daemon drops
the ones that come after them.
## In Rust
The `komorebi-client` crate has `subscribe` and `subscribe_with_options`, which listen on
the socket, subscribe, and return the listener: each connection on it is one
`Notification`. `cargo doc --package komorebi-client --open` shows their documentation,
with an example.