From dc93f1c1fd7b67e2da5af2ffada732b9ddeb2d6a Mon Sep 17 00:00:00 2001 From: Kent Daleng Date: Sun, 17 Aug 2025 16:05:41 +0200 Subject: github wiki replacement / mkdocs-docs (#2147) * Add wiki based on mkdocs * wording fixes * fix github bg color on narrow * Fix left sidebar section headers being bigger than pages * fix hover accent * fix list rendering on fractional layout * fix videos * fix automatic full links * remove redundant commented css * improve dark mode contrast * update pygments for better child node coloring * update logo * remove blank lines * add systemd language hint --------- Co-authored-by: Ivan Molodetskikh --- wiki/IPC.md | 75 ------------------------------------------------------------- 1 file changed, 75 deletions(-) delete mode 100644 wiki/IPC.md (limited to 'wiki/IPC.md') diff --git a/wiki/IPC.md b/wiki/IPC.md deleted file mode 100644 index 813461d6..00000000 --- a/wiki/IPC.md +++ /dev/null @@ -1,75 +0,0 @@ -You can communicate with the running niri instance over an IPC socket. -Check `niri msg --help` for available commands. - -The `--json` flag prints the response in JSON, rather than formatted. -For example, `niri msg --json outputs`. - -> [!TIP] -> If you're getting parsing errors from `niri msg` after upgrading niri, make sure that you've restarted niri itself. -> You might be trying to run a newer `niri msg` against an older `niri` compositor. - -### Event Stream - -Since: 0.1.9 - -While most niri IPC requests return a single response, the event stream request will make niri continuously stream events into the IPC connection until it is closed. -This is useful for implementing various bars and indicators that update as soon as something happens, without continuous polling. - -The event stream IPC is designed to give you the complete current state up-front, then follow up with updates to that state. -This way, your state can never "desync" from niri, and you don't need to make any other IPC information requests. - -Where reasonable, event stream state updates are atomic, though this is not always the case. -For example, a window may end up with a workspace id for a workspace that had already been removed. -This can happen if the corresponding workspaces-changed event arrives before the corresponding window-changed event. - -To get a taste of the events, run `niri msg event-stream`. -Though, this is more of a debug function than anything. -You can get raw events from `niri msg --json event-stream`, or by connecting to the niri socket and requesting an event stream manually. - -You can find the full list of events along with documentation [here](https://yalter.github.io/niri/niri_ipc/enum.Event.html). - -### Programmatic Access - -`niri msg --json` is a thin wrapper over writing and reading to a socket. -When implementing more complex scripts and modules, you're encouraged to access the socket directly. - -Connect to the UNIX domain socket located at `$NIRI_SOCKET` in the filesystem. -Write your request encoded in JSON on a single line, followed by a newline character, or by flushing and shutting down the write end of the connection. -Read the reply as JSON, also on a single line. - -You can use `socat` to test communicating with niri directly: - -```sh -$ socat STDIO "$NIRI_SOCKET" -"FocusedWindow" -{"Ok":{"FocusedWindow":{"id":12,"title":"t socat STDIO /run/u ~","app_id":"Alacritty","workspace_id":6,"is_focused":true}}} -``` - -The reply is an `Ok` or an `Err` wrapping the same JSON object as you get from `niri msg --json`. - -For more complex requests, you can use `socat` to find how `niri msg` formats them: - -```sh -$ socat STDIO UNIX-LISTEN:temp.sock -# then, in a different terminal: -$ env NIRI_SOCKET=./temp.sock niri msg action focus-workspace 2 -# then, look in the socat terminal: -{"Action":{"FocusWorkspace":{"reference":{"Index":2}}}} -``` - -You can find all available requests and response types in the [niri-ipc sub-crate documentation](https://yalter.github.io/niri/niri_ipc/). - -### Backwards Compatibility - -The JSON output *should* remain stable, as in: - -- existing fields and enum variants should not be renamed -- non-optional existing fields should not be removed - -However, new fields and enum variants will be added, so you should handle unknown fields or variants gracefully where reasonable. - -The formatted/human-readable output (i.e. without `--json` flag) is **not** considered stable. -Please prefer the JSON output for scripts, since I reserve the right to make any changes to the human-readable output. - -The `niri-ipc` sub-crate (like other niri sub-crates) is *not* API-stable in terms of the Rust semver; rather, it follows the version of niri itself. -In particular, new struct fields and enum variants will be added. -- cgit