@desklink/host 0.1.0

package/engine/src/portal.rs

@@ -0,0 +1,115 @@
+//! Portal (XDG Desktop Portal ScreenCast) session negotiation.
+//!
+//! The portal is the only capture path this engine asks the compositor for: it
+//! is what carries the user's consent, works across Wayland compositors, and
+//! hands back a PipeWire remote that [`crate::capture`] consumes. No
+//! compositor-private protocol is used.
+
+use anyhow::{Context, Result};
+use ashpd::desktop::screencast::{CursorMode, Screencast, SourceType};
+use ashpd::desktop::PersistMode;
+use ashpd::enumflags2::BitFlags;
+use std::os::fd::OwnedFd;
+
+/// What the portal gave us: a PipeWire remote plus the identity of the selected
+/// source. `width`/`height` are the source's logical size in the compositor's
+/// own scale; `position` is its origin in the desktop layout.
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct SelectedSource {
+    pub node_id: u32,
+    pub width: i32,
+    pub height: i32,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub position: Option<(i32, i32)>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source_type: Option<String>,
+    /// Absolute origin of the selected source in the desktop layout. Reported
+    /// for diagnostics and for geometry consumers only: input is applied in the
+    /// source's own pixels, and nothing here is added to a converted
+    /// coordinate.
+    pub origin_x: i32,
+    pub origin_y: i32,
+}
+
+pub struct PortalSession {
+    pub fd: OwnedFd,
+    pub source: SelectedSource,
+    pub restore_token: Option<String>,
+}
+
+/// Ask the portal for a screen cast session.
+///
+/// `restore_token` is a token from an earlier session; supplying it lets a
+/// backend skip the picker when its policy allows it. The returned token must be
+/// persisted by the consumer and is single-use.
+pub async fn open(restore_token: Option<&str>) -> Result<PortalSession> {
+    let proxy = Screencast::new()
+        .await
+        .context("compositor has no ScreenCast portal")?;
+
+    if proxy
+        .available_source_types()
+        .await
+        .is_ok_and(|types| !types.contains(SourceType::Monitor))
+    {
+        anyhow::bail!("ScreenCast portal advertises no monitor source");
+    }
+
+    let session = proxy
+        .create_session()
+        .await
+        .context("ScreenCast.CreateSession failed")?;
+
+    proxy
+        .select_sources(
+            &session,
+            // The cursor is part of the picture the user drives; hiding it would
+            // make precise placement impossible.
+            CursorMode::Embedded,
+            BitFlags::from(SourceType::Monitor),
+            false,
+            restore_token,
+            // Request a durable grant, not one tied to this engine process.
+            // The portal still owns consent and may decline persistence.
+            PersistMode::ExplicitlyRevoked,
+        )
+        .await
+        .context("ScreenCast.SelectSources failed")?
+        .response()
+        .context("ScreenCast.SelectSources was cancelled")?;
+
+    // `Start` is what the compositor uses to present its consent UI.
+    let streams = proxy
+        .start(&session, None)
+        .await
+        .context("ScreenCast.Start failed")?
+        .response()
+        .context("screen capture was not granted")?;
+
+    let stream = streams
+        .streams()
+        .first()
+        .context("portal returned no capture stream")?;
+
+    let (width, height) = stream.size().context("portal stream has no logical size")?;
+    let position = stream.position();
+
+    let fd = proxy
+        .open_pipe_wire_remote(&session)
+        .await
+        .context("OpenPipeWireRemote failed")?;
+
+    Ok(PortalSession {
+        fd,
+        source: SelectedSource {
+            node_id: stream.pipe_wire_node_id(),
+            width,
+            height,
+            position,
+            source_type: stream.source_type().map(|t| format!("{t:?}")),
+            origin_x: position.map(|(x, _)| x).unwrap_or(0),
+            origin_y: position.map(|(_, y)| y).unwrap_or(0),
+        },
+        restore_token: streams.restore_token().map(str::to_owned),
+    })
+}

package/engine/src/protocol.rs

@@ -0,0 +1,331 @@
+//! Wire types for the local control protocol and for the session's control
+//! channel. Documented in `docs/PROTOCOL.md`; this module is the definition.
+
+use serde::{Deserialize, Serialize};
+
+pub const PROTOCOL_VERSION: u32 = 2;
+
+/// A request from the consumer to the engine.
+#[derive(Debug, Deserialize)]
+pub struct Request {
+    #[serde(default)]
+    pub id: Option<u64>,
+    pub method: String,
+    #[serde(default)]
+    pub params: serde_json::Value,
+}
+
+/// A reply to one request. Exactly one of `result`/`error` is set.
+#[derive(Debug, Serialize)]
+pub struct Response {
+    pub id: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub result: Option<serde_json::Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error: Option<ErrorBody>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ErrorBody {
+    pub code: String,
+    pub message: String,
+}
+
+impl ErrorBody {
+    pub fn new(code: &str, message: impl Into<String>) -> Self {
+        Self {
+            code: code.to_owned(),
+            message: message.into(),
+        }
+    }
+}
+
+/// A notification the engine sends on its own.
+#[derive(Debug, Serialize)]
+pub struct Event {
+    pub event: String,
+    pub params: serde_json::Value,
+}
+
+#[derive(Debug, Default, Deserialize)]
+pub struct HelloParams {
+    #[serde(default)]
+    pub protocol: u32,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Permission {
+    View,
+    Control,
+    Clipboard,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct IceServerParam {
+    #[serde(default)]
+    pub urls: Vec<String>,
+    #[serde(default)]
+    pub username: Option<String>,
+    #[serde(default)]
+    pub credential: Option<String>,
+}
+
+/// Which desktop to capture.
+///
+/// The portal is the default because on a Wayland desktop it is what carries the
+/// user's consent. An explicit X display is the other supported backend: a
+/// machine with no working screen-cast portal, a headless X server, or a remote
+/// X session. Asking for one is a deployment choice, not a test switch.
+#[derive(Debug, Clone, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum SourceRequest {
+    Portal,
+    X11 {
+        #[serde(default)]
+        display: Option<String>,
+    },
+}
+
+#[derive(Debug, Deserialize)]
+pub struct OpenParams {
+    /// Absent means "the portal, with the user's consent".
+    #[serde(default)]
+    pub source: Option<SourceRequest>,
+    #[serde(default)]
+    pub permissions: Vec<Permission>,
+    #[serde(default = "default_max_width")]
+    pub max_width: usize,
+    #[serde(default = "default_max_height")]
+    pub max_height: usize,
+    #[serde(default = "default_bitrate")]
+    pub bitrate_kbps: u32,
+    #[serde(default = "default_fps")]
+    pub max_fps: u32,
+    #[serde(default)]
+    pub ice_servers: Vec<IceServerParam>,
+    #[serde(default)]
+    pub restore_token: Option<String>,
+    #[serde(default)]
+    pub ttl_seconds: Option<u64>,
+    /// Also listen for ICE over TCP on this computer's loopback, for a client
+    /// whose only way here is a local forward (an SSH tunnel).
+    #[serde(default)]
+    pub loopback_tcp: bool,
+}
+
+/// The encode box when the consumer names none: a desktop's own pixels up to
+/// 4K, because a phone zooms into the picture and text has to survive that.
+fn default_max_width() -> usize {
+    3840
+}
+fn default_max_height() -> usize {
+    2160
+}
+/// Zero asks the engine to size the rate to the encoded surface.
+fn default_bitrate() -> u32 {
+    0
+}
+fn default_fps() -> u32 {
+    30
+}
+
+#[derive(Debug, Deserialize)]
+pub struct SessionRef {
+    pub session_id: String,
+    #[serde(default)]
+    pub generation: Option<u64>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct DescriptionParams {
+    pub session_id: String,
+    #[serde(default)]
+    pub generation: Option<u64>,
+    pub description: RtcDescription,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct RtcDescription {
+    #[serde(rename = "type")]
+    pub kind: String,
+    pub sdp: String,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct CandidateParams {
+    pub session_id: String,
+    #[serde(default)]
+    pub generation: Option<u64>,
+    pub candidate: String,
+    #[serde(default)]
+    pub sdp_mid: Option<String>,
+    #[serde(default, rename = "sdpMLineIndex", alias = "sdp_m_line_index")]
+    pub sdp_m_line_index: Option<u16>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct ClipboardParams {
+    pub session_id: String,
+    #[serde(default)]
+    pub mime: Option<String>,
+    #[serde(default)]
+    pub text: Option<String>,
+}
+
+/// Messages the client sends on the session's control channel.
+///
+/// `seq` is the client's own ordering. The engine refuses a repeat or a lower
+/// value rather than re-applying an action, so a replayed frame cannot move the
+/// pointer twice.
+#[derive(Debug, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum ControlMessage {
+    Pointer {
+        phase: PointerPhase,
+        x: i64,
+        y: i64,
+        #[serde(default = "left_button")]
+        button: i64,
+        #[serde(default)]
+        seq: u64,
+    },
+    /// Detents; fractions scroll smoothly where the desktop supports it.
+    Wheel {
+        #[serde(default)]
+        dx: f64,
+        #[serde(default)]
+        dy: f64,
+        #[serde(default)]
+        seq: u64,
+    },
+    Key {
+        #[serde(default)]
+        name: Option<String>,
+        #[serde(default)]
+        character: Option<String>,
+        down: bool,
+        #[serde(default)]
+        modifiers: Vec<String>,
+        #[serde(default)]
+        seq: u64,
+    },
+    Text {
+        text: String,
+        #[serde(default)]
+        seq: u64,
+    },
+    ReleaseAll {
+        #[serde(default)]
+        seq: u64,
+    },
+    ClipboardRead {
+        request: String,
+        #[serde(default)]
+        seq: u64,
+    },
+    ClipboardWrite {
+        request: String,
+        text: String,
+        #[serde(default)]
+        seq: u64,
+    },
+}
+
+fn left_button() -> i64 {
+    1
+}
+
+impl ControlMessage {
+    pub fn seq(&self) -> u64 {
+        match self {
+            Self::Pointer { seq, .. }
+            | Self::Wheel { seq, .. }
+            | Self::Key { seq, .. }
+            | Self::Text { seq, .. }
+            | Self::ReleaseAll { seq }
+            | Self::ClipboardRead { seq, .. }
+            | Self::ClipboardWrite { seq, .. } => *seq,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PointerPhase {
+    Move,
+    Down,
+    Up,
+    Cancel,
+}
+
+/// Messages the engine sends back on the control channel.
+#[derive(Debug, Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum ControlReply<'a> {
+    Hello {
+        protocol: u32,
+        geometry: serde_json::Value,
+    },
+    Ack {
+        seq: u64,
+    },
+    Rejected {
+        seq: u64,
+        code: &'a str,
+        message: &'a str,
+    },
+    Clipboard {
+        request: &'a str,
+        text: String,
+        truncated: bool,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        error: Option<&'a str>,
+    },
+    Revoked {
+        reason: &'a str,
+    },
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_pointer_message_round_trips_with_its_sequence() {
+        let parsed: ControlMessage =
+            serde_json::from_str(r#"{"kind":"pointer","phase":"down","x":10,"y":20,"seq":3}"#)
+                .unwrap();
+        match parsed {
+            ControlMessage::Pointer {
+                phase,
+                x,
+                y,
+                seq,
+                button,
+            } => {
+                assert!(matches!(phase, PointerPhase::Down));
+                assert_eq!((x, y, seq, button), (10, 20, 3, 1));
+            }
+            other => panic!("wrong variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn an_unknown_action_is_refused_rather_than_ignored() {
+        assert!(serde_json::from_str::<ControlMessage>(r#"{"kind":"teleport"}"#).is_err());
+    }
+
+    #[test]
+    fn open_defaults_keep_the_desktops_own_pixels_up_to_4k() {
+        let params: OpenParams =
+            serde_json::from_str(r#"{"permissions":["view","control"]}"#).unwrap();
+        assert_eq!(params.max_width, 3840);
+        assert_eq!(params.max_height, 2160);
+        assert_eq!(
+            params.bitrate_kbps, 0,
+            "the engine sizes the rate to the surface"
+        );
+        assert_eq!(params.max_fps, 30);
+    }
+}