glass-dev 0.3.14

Glass terminal-native development and browser workspace
Documentation
//! Loopback-only, token-scoped browser view transport for SSH forwarding.

use super::{DevelopmentError, DevelopmentResult};
use base64::Engine;
use futures_util::{SinkExt, StreamExt};
use serde::{Deserialize, Serialize};
use std::{net::Ipv4Addr, sync::Arc};
use tokio::{
    net::{TcpListener, TcpStream},
    sync::{Semaphore, mpsc, watch},
    task::JoinHandle,
    time::{Duration, timeout},
};
use tokio_tungstenite::{accept_async, tungstenite};

const MAX_CLIENTS: usize = 4;
const MAX_INPUT_BYTES: usize = 16 * 1024;
const MAX_FRAME_DATA_BYTES: usize = 8 * 1024 * 1024;
const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(3);

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct RemoteFrame {
    pub browser_revision: u64,
    pub mime_type: String,
    pub data: String,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(tag = "type", rename_all = "camelCase")]
pub enum RemoteInput {
    Click {
        x: f64,
        y: f64,
        expected_revision: u64,
    },
    Scroll {
        dx: f64,
        dy: f64,
        expected_revision: u64,
    },
    Key {
        key: String,
        expected_revision: u64,
    },
    Text {
        text: String,
        expected_revision: u64,
    },
}

impl RemoteInput {
    pub fn expected_revision(&self) -> u64 {
        match self {
            Self::Click {
                expected_revision, ..
            }
            | Self::Scroll {
                expected_revision, ..
            }
            | Self::Key {
                expected_revision, ..
            }
            | Self::Text {
                expected_revision, ..
            } => *expected_revision,
        }
    }

    fn validate(&self) -> DevelopmentResult<()> {
        match self {
            Self::Click { x, y, .. }
                if !x.is_finite()
                    || !y.is_finite()
                    || !(0.0..=1.0).contains(x)
                    || !(0.0..=1.0).contains(y) =>
            {
                Err(DevelopmentError::InvalidInput(
                    "remote click coordinates must be finite normalized values".into(),
                ))
            }
            Self::Scroll { dx, dy, .. }
                if !dx.is_finite()
                    || !dy.is_finite()
                    || dx.abs() > 10_000.0
                    || dy.abs() > 10_000.0 =>
            {
                Err(DevelopmentError::InvalidInput(
                    "remote scroll delta is outside the bounded range".into(),
                ))
            }
            Self::Key { key, .. } if key.is_empty() || key.len() > 128 => Err(
                DevelopmentError::InvalidInput("remote key must contain 1 to 128 bytes".into()),
            ),
            Self::Text { text, .. } if text.len() > 8 * 1024 => Err(
                DevelopmentError::InvalidInput("remote text exceeds 8192 bytes".into()),
            ),
            _ => Ok(()),
        }
    }
}

/// Running Remote View endpoint. It never owns a browser session: the caller
/// publishes frames from and applies inputs to its existing session worker.
pub struct RemoteView {
    port: u16,
    token: String,
    frame: watch::Sender<Option<RemoteFrame>>,
    inputs: mpsc::Receiver<RemoteInput>,
    shutdown: watch::Sender<bool>,
    task: JoinHandle<()>,
}

impl std::fmt::Debug for RemoteView {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("RemoteView")
            .field("port", &self.port)
            .finish_non_exhaustive()
    }
}

impl RemoteView {
    pub async fn bind() -> DevelopmentResult<Self> {
        let listener = TcpListener::bind((Ipv4Addr::LOCALHOST, 0)).await?;
        let port = listener.local_addr()?.port();
        let token = secure_token()?;
        let (frame, frame_rx) = watch::channel(None);
        let (input_tx, inputs) = mpsc::channel(64);
        let (shutdown, shutdown_rx) = watch::channel(false);
        let task_token = token.clone();
        let task = tokio::spawn(serve(listener, task_token, frame_rx, input_tx, shutdown_rx));
        Ok(Self {
            port,
            token,
            frame,
            inputs,
            shutdown,
            task,
        })
    }

    pub fn port(&self) -> u16 {
        self.port
    }

    pub fn local_url(&self) -> String {
        format!("http://127.0.0.1:{}/{}/", self.port, self.token)
    }

    pub fn ssh_forward_hint(&self) -> String {
        format!("ssh -N -L {0}:127.0.0.1:{0} USER@HOST", self.port)
    }

    /// Replace the pending frame when it is safe to retain and serve.
    /// Returns false for an unsupported MIME type or oversized payload.
    pub fn publish(&self, frame: RemoteFrame) -> bool {
        if frame.mime_type != "image/png" || frame.data.len() > MAX_FRAME_DATA_BYTES {
            return false;
        }
        self.frame.send_replace(Some(frame));
        true
    }

    pub fn try_recv_input(&mut self) -> Result<RemoteInput, mpsc::error::TryRecvError> {
        self.inputs.try_recv()
    }

    pub async fn revoke(self) {
        let _ = self.shutdown.send(true);
        let _ = self.task.await;
    }
}

async fn serve(
    listener: TcpListener,
    token: String,
    frame: watch::Receiver<Option<RemoteFrame>>,
    inputs: mpsc::Sender<RemoteInput>,
    mut shutdown: watch::Receiver<bool>,
) {
    let clients = Arc::new(Semaphore::new(MAX_CLIENTS));
    loop {
        tokio::select! {
            changed = shutdown.changed() => if changed.is_err() || *shutdown.borrow() { break },
            accepted = listener.accept() => {
                let Ok((stream, address)) = accepted else { continue };
                if !address.ip().is_loopback() { continue; }
                let Ok(permit) = Arc::clone(&clients).try_acquire_owned() else { continue };
                let token = token.clone();
                let frame = frame.clone();
                let inputs = inputs.clone();
                let revoked = shutdown.clone();
                tokio::spawn(async move {
                    let _permit = permit;
                    let _ = handle_client(stream, token, frame, inputs, revoked).await;
                });
            }
        }
    }
}

async fn handle_client(
    mut stream: TcpStream,
    token: String,
    mut frame: watch::Receiver<Option<RemoteFrame>>,
    inputs: mpsc::Sender<RemoteInput>,
    mut revoked: watch::Receiver<bool>,
) -> DevelopmentResult<()> {
    let mut peek = [0_u8; 4096];
    let size = timeout(HANDSHAKE_TIMEOUT, stream.peek(&mut peek))
        .await
        .map_err(|_| DevelopmentError::Process("remote view handshake timed out".into()))??;
    let request = std::str::from_utf8(&peek[..size]).unwrap_or("");
    let expected_page = format!("GET /{token}/ ");
    if request.starts_with(&expected_page) {
        // Consume the request before closing the socket. Windows sends an RST
        // when a socket is closed with unread inbound bytes, which can discard
        // an otherwise complete HTTP response at the client.
        let mut request_bytes = vec![0_u8; size];
        tokio::io::AsyncReadExt::read_exact(&mut stream, &mut request_bytes).await?;
        let body = viewer_html(&token);
        let response = format!(
            "HTTP/1.1 200 OK\r\nContent-Type: text/html; charset=utf-8\r\nCache-Control: no-store\r\nContent-Security-Policy: default-src 'self'; img-src 'self' data:; script-src 'unsafe-inline'; connect-src 'self'\r\nX-Frame-Options: DENY\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
            body.len(),
            body
        );
        tokio::io::AsyncWriteExt::write_all(&mut stream, response.as_bytes()).await?;
        tokio::io::AsyncWriteExt::shutdown(&mut stream).await?;
        return Ok(());
    }
    if !request.starts_with(&format!("GET /ws/{token} ")) {
        tokio::io::AsyncWriteExt::write_all(
            &mut stream,
            b"HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\nConnection: close\r\n\r\n",
        )
        .await?;
        return Ok(());
    }
    let mut socket = accept_async(stream).await.map_err(|error| {
        DevelopmentError::Process(format!("remote view handshake failed: {error}"))
    })?;

    loop {
        tokio::select! {
            changed = revoked.changed() => if changed.is_err() || *revoked.borrow() { break },
            changed = frame.changed() => {
                if changed.is_err() { break; }
                let latest = { frame.borrow().clone() };
                if let Some(value) = latest {
                    let text = serde_json::to_string(&value)?;
                    socket.send(tungstenite::Message::Text(text.into())).await.map_err(|error| DevelopmentError::Process(error.to_string()))?;
                }
            }
            message = socket.next() => match message {
                Some(Ok(tungstenite::Message::Text(text))) if text.len() <= MAX_INPUT_BYTES => {
                    let input: RemoteInput = serde_json::from_str(&text)?;
                    input.validate()?;
                    inputs.try_send(input).map_err(|_| DevelopmentError::Process("remote input queue is full".into()))?;
                }
                Some(Ok(tungstenite::Message::Close(_))) | None => break,
                Some(Ok(_)) => {}
                Some(Err(error)) => return Err(DevelopmentError::Process(error.to_string())),
            }
        }
    }
    Ok(())
}

fn secure_token() -> DevelopmentResult<String> {
    let mut bytes = [0_u8; 32];
    getrandom::fill(&mut bytes).map_err(|error| {
        DevelopmentError::Process(format!("secure token generation failed: {error}"))
    })?;
    Ok(base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(bytes))
}

fn viewer_html(token: &str) -> String {
    format!(
        r#"<!doctype html><meta name=viewport content="width=device-width,initial-scale=1,viewport-fit=cover"><title>Glass Remote View</title><style>html,body{{margin:0;background:#101418;color:#eef;font:14px system-ui}}header{{padding:10px}}img{{display:block;width:100%;height:auto;touch-action:none}}input{{box-sizing:border-box;width:100%;padding:12px;background:#172231;color:#eef;border:1px solid #39485d}}</style><header>Glass Remote View ยท loopback session</header><img id=v tabindex=0 alt="Browser frame"><input id=t autocomplete=off placeholder="Type into focused browser control, then press Enter"><script>const v=document.querySelector('#v'),t=document.querySelector('#t');let r=0;const send=o=>{{if(w.readyState===1)w.send(JSON.stringify({{...o,expectedRevision:r}}))}},w=new WebSocket(`ws://${{location.host}}/ws/{token}`);w.onmessage=e=>{{const f=JSON.parse(e.data);r=f.browserRevision;v.src=`data:${{f.mimeType}};base64,${{f.data}}`}};v.onclick=e=>{{const b=v.getBoundingClientRect();send({{type:'click',x:(e.clientX-b.left)/b.width,y:(e.clientY-b.top)/b.height}});v.focus()}};v.onwheel=e=>{{e.preventDefault();send({{type:'scroll',dx:e.deltaX,dy:e.deltaY}})}};window.onkeydown=e=>{{if(e.target!==t){{e.preventDefault();send({{type:'key',key:e.key}})}}}};t.onkeydown=e=>{{if(e.key==='Enter'&&t.value){{send({{type:'text',text:t.value}});t.value='';e.preventDefault()}}}};</script>"#
    )
}

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn endpoint_is_loopback_tokenized_and_revocable() {
        let view = RemoteView::bind().await.unwrap();
        assert!(view.local_url().starts_with("http://127.0.0.1:"));
        assert!(!view.local_url().contains("="));
        assert!(view.ssh_forward_hint().contains("127.0.0.1"));
        let response = reqwest::get(view.local_url()).await.unwrap();
        assert!(response.status().is_success());
        assert!(
            response.headers()["cache-control"]
                .to_str()
                .unwrap()
                .contains("no-store")
        );
        view.revoke().await;
    }

    #[tokio::test]
    async fn websocket_delivers_latest_frame_and_revision_bound_input() {
        let mut view = RemoteView::bind().await.unwrap();
        let token = view
            .local_url()
            .trim_end_matches('/')
            .rsplit('/')
            .next()
            .unwrap()
            .to_string();
        let ws_url = format!("ws://127.0.0.1:{}/ws/{token}", view.port());
        let (mut socket, _) = tokio_tungstenite::connect_async(ws_url).await.unwrap();
        view.publish(RemoteFrame {
            browser_revision: 7,
            mime_type: "image/png".into(),
            data: "AA==".into(),
        });
        let message = timeout(Duration::from_secs(2), socket.next())
            .await
            .unwrap()
            .unwrap()
            .unwrap();
        assert!(message.to_text().unwrap().contains("\"browserRevision\":7"));
        socket
            .send(tungstenite::Message::Text(
                serde_json::to_string(&RemoteInput::Key {
                    key: "Enter".into(),
                    expected_revision: 7,
                })
                .unwrap()
                .into(),
            ))
            .await
            .unwrap();
        let input = timeout(Duration::from_secs(2), async {
            loop {
                if let Ok(input) = view.try_recv_input() {
                    break input;
                }
                tokio::time::sleep(Duration::from_millis(10)).await;
            }
        })
        .await
        .unwrap();
        assert_eq!(input.expected_revision(), 7);
        view.revoke().await;
    }

    #[test]
    fn inputs_are_revision_bound_and_bounded() {
        let input = RemoteInput::Click {
            x: 0.5,
            y: 0.25,
            expected_revision: 9,
        };
        assert_eq!(input.expected_revision(), 9);
        assert!(input.validate().is_ok());
        assert!(
            RemoteInput::Click {
                x: 2.0,
                y: 0.0,
                expected_revision: 9
            }
            .validate()
            .is_err()
        );
    }

    #[tokio::test]
    async fn frame_mailbox_rejects_unsupported_and_oversized_payloads() {
        let view = RemoteView::bind().await.unwrap();
        assert!(!view.publish(RemoteFrame {
            browser_revision: 1,
            mime_type: "text/html".into(),
            data: "x".into(),
        }));
        assert!(!view.publish(RemoteFrame {
            browser_revision: 1,
            mime_type: "image/png".into(),
            data: "x".repeat(MAX_FRAME_DATA_BYTES + 1),
        }));
        view.revoke().await;
    }
}