Document High Level Architecture

[bbb651]

I'm working on xdg activation support, and when starting it took me a while to understand how the different components go together and what server and client referred to in this context, and I had to draw myself this to understand it:

flowchart TD
    W[niri] -->|Wayland| XWS
    XWS[xwayland-satellite] -->|Wayland| XW[Xwayland]
    XW -->|X11| X1[X client]
    XW -->|X11| X2[X client]
    XW -->|X11| X3[X client]

Loading

(I don't like mermaid but github has native support for it and it's readable without rendering, alternatively this could be svg or ascii)
I think it would be nice to include this somewhere to make it a bit more approachable to contribute, it's a very low-cost high-value piece of documentation.

I'm not sure where this should go, in the README or somewhere else specifically for contributors. In general I think something like a ARCHITECTURE.md is a good idea.

[Supreeeme]

Yeah, good idea.

[bbb651]

I started working on this and I would love some guidance, I've never used xlib before and after a bunch of searching I stumbled across the XRes extension which allows to get the pid and get XDG_ACTIVATION_TOKEN from /proc/{pid}/environ, it seems to work for flatpak as well (this should only ran for new clients not per new window, also this shouldn't use read_to_string because other environment variables might not be valid utf-8):

diff --git a/src/xstate/mod.rs b/src/xstate/mod.rs
index e4e39c46f2..e0f7f66c96 100644
--- a/src/xstate/mod.rs
+++ b/src/xstate/mod.rs
@@ -302,7 +303,33 @@
                     } else {
                         Some(parent)
                     };
-                    server_state.new_window(e.window(), e.override_redirect(), (&e).into(), parent);
+                    let pid = self
+                        .connection
+                        .wait_for_reply(self.connection.send_request(&xcb::res::QueryClientIds {
+                            specs: &[xcb::res::ClientIdSpec {
+                                client: e.window().resource_id(),
+                                mask: xcb::res::ClientIdMask::LOCAL_CLIENT_PID,
+                            }],
+                        }))
+                        .map(|reply| reply.ids().next().unwrap().value()[0]);
+                    let activation_token = if let Ok(pid) = pid {
+                        let environ =
+                            std::fs::read_to_string(format!("/proc/{pid}/environ")).unwrap();
+                        environ
+                            .split('\0')
+                            .find_map(|line| line.strip_prefix("XDG_ACTIVATION_TOKEN="))
+                            .map(ToString::to_string)
+                    } else {
+                        None
+                    };
+                    dbg!(&activation_token);
+                    server_state.new_window(
+                        e.window(),
+                        e.override_redirect(),
+                        (&e).into(),
+                        parent,
+                        activation_token,
+                    );
                 }
                 xcb::Event::X(x::Event::ReparentNotify(e)) => {
                     debug!("reparent event: {e:?}");

but then I got completely lost in the event code, I'm not sure which type of delegation I should use in the server dispatch, ObjectKey or ClientGlobalWrapper<_>, what is simple_event_shunt!, global_dispatch_no_events! or global_dispatch_with_events, on the clientside push_event! or push_or_queue_events!... there's a lot going, what we want to do is:

• When a window is created from a new process, use XDG_ACTIVATION_TOKEN to activate xwayland-satellite
• When focus changes in x11 and xwayland-satellite has focus, create an activation token on the previously focused wayland window and activate it on the newly focused wayland window (if xwayland-satellite doesn't have focus I think we should do this? But that's less urgent, pun intended)

So I think the nested server doesn't need to implement the protocol, just the xwayland-satellite client.

[Supreeeme]

So I think the nested server doesn't need to implement the protocol, just the xwayland-satellite client.

Correct - this would only be useful if Xwayland itself utilized the protocol.

A lot of the machinery with the clientside/serverside dance is for sending event data directly from the client side (from the host compositor) to xwayland. However, since Xwayland doesn't use the activation protocol at all (to my knowledge - I could be wrong), this ends up being a purely Wayland client side affair. In this case, you will want to look more at what was done for the wl_data_device (clipboard) support in ServerState.

You will also likely want to use the xdg activation helpers from smithay client toolkit. The clipboard stuff uses sctk helpers as well, so it should be a decent reference.

[Supreeeme]

I just added an ARCHITECTURE.md: https://github.com/Supreeeme/xwayland-satellite/blob/main/ARCHITECTURE.md

Feel free to propose any changes/clarifications.