Skip to main content

glass_dev/development/
remote_view.rs

1//! Loopback-only, token-scoped browser view transport for SSH forwarding.
2
3use super::{DevelopmentError, DevelopmentResult};
4use base64::Engine;
5use futures_util::{SinkExt, StreamExt};
6use serde::{Deserialize, Serialize};
7use std::{net::Ipv4Addr, sync::Arc};
8use tokio::{
9    net::{TcpListener, TcpStream},
10    sync::{Semaphore, mpsc, watch},
11    task::JoinHandle,
12    time::{Duration, timeout},
13};
14use tokio_tungstenite::{accept_async, tungstenite};
15
16const MAX_CLIENTS: usize = 4;
17const MAX_INPUT_BYTES: usize = 16 * 1024;
18const MAX_FRAME_DATA_BYTES: usize = 8 * 1024 * 1024;
19const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(3);
20
21#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
22#[serde(rename_all = "camelCase")]
23pub struct RemoteFrame {
24    pub browser_revision: u64,
25    pub mime_type: String,
26    pub data: String,
27}
28
29#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
30#[serde(tag = "type", rename_all = "camelCase")]
31pub enum RemoteInput {
32    Click {
33        x: f64,
34        y: f64,
35        expected_revision: u64,
36    },
37    Scroll {
38        dx: f64,
39        dy: f64,
40        expected_revision: u64,
41    },
42    Key {
43        key: String,
44        expected_revision: u64,
45    },
46    Text {
47        text: String,
48        expected_revision: u64,
49    },
50}
51
52impl RemoteInput {
53    pub fn expected_revision(&self) -> u64 {
54        match self {
55            Self::Click {
56                expected_revision, ..
57            }
58            | Self::Scroll {
59                expected_revision, ..
60            }
61            | Self::Key {
62                expected_revision, ..
63            }
64            | Self::Text {
65                expected_revision, ..
66            } => *expected_revision,
67        }
68    }
69
70    fn validate(&self) -> DevelopmentResult<()> {
71        match self {
72            Self::Click { x, y, .. }
73                if !x.is_finite()
74                    || !y.is_finite()
75                    || !(0.0..=1.0).contains(x)
76                    || !(0.0..=1.0).contains(y) =>
77            {
78                Err(DevelopmentError::InvalidInput(
79                    "remote click coordinates must be finite normalized values".into(),
80                ))
81            }
82            Self::Scroll { dx, dy, .. }
83                if !dx.is_finite()
84                    || !dy.is_finite()
85                    || dx.abs() > 10_000.0
86                    || dy.abs() > 10_000.0 =>
87            {
88                Err(DevelopmentError::InvalidInput(
89                    "remote scroll delta is outside the bounded range".into(),
90                ))
91            }
92            Self::Key { key, .. } if key.is_empty() || key.len() > 128 => Err(
93                DevelopmentError::InvalidInput("remote key must contain 1 to 128 bytes".into()),
94            ),
95            Self::Text { text, .. } if text.len() > 8 * 1024 => Err(
96                DevelopmentError::InvalidInput("remote text exceeds 8192 bytes".into()),
97            ),
98            _ => Ok(()),
99        }
100    }
101}
102
103/// Running Remote View endpoint. It never owns a browser session: the caller
104/// publishes frames from and applies inputs to its existing session worker.
105pub struct RemoteView {
106    port: u16,
107    token: String,
108    frame: watch::Sender<Option<RemoteFrame>>,
109    inputs: mpsc::Receiver<RemoteInput>,
110    shutdown: watch::Sender<bool>,
111    task: JoinHandle<()>,
112}
113
114impl std::fmt::Debug for RemoteView {
115    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
116        formatter
117            .debug_struct("RemoteView")
118            .field("port", &self.port)
119            .finish_non_exhaustive()
120    }
121}
122
123impl RemoteView {
124    pub async fn bind() -> DevelopmentResult<Self> {
125        let listener = TcpListener::bind((Ipv4Addr::LOCALHOST, 0)).await?;
126        let port = listener.local_addr()?.port();
127        let token = secure_token()?;
128        let (frame, frame_rx) = watch::channel(None);
129        let (input_tx, inputs) = mpsc::channel(64);
130        let (shutdown, shutdown_rx) = watch::channel(false);
131        let task_token = token.clone();
132        let task = tokio::spawn(serve(listener, task_token, frame_rx, input_tx, shutdown_rx));
133        Ok(Self {
134            port,
135            token,
136            frame,
137            inputs,
138            shutdown,
139            task,
140        })
141    }
142
143    pub fn port(&self) -> u16 {
144        self.port
145    }
146
147    pub fn local_url(&self) -> String {
148        format!("http://127.0.0.1:{}/{}/", self.port, self.token)
149    }
150
151    pub fn ssh_forward_hint(&self) -> String {
152        format!("ssh -N -L {0}:127.0.0.1:{0} USER@HOST", self.port)
153    }
154
155    /// Replace the pending frame when it is safe to retain and serve.
156    /// Returns false for an unsupported MIME type or oversized payload.
157    pub fn publish(&self, frame: RemoteFrame) -> bool {
158        if frame.mime_type != "image/png" || frame.data.len() > MAX_FRAME_DATA_BYTES {
159            return false;
160        }
161        self.frame.send_replace(Some(frame));
162        true
163    }
164
165    pub fn try_recv_input(&mut self) -> Result<RemoteInput, mpsc::error::TryRecvError> {
166        self.inputs.try_recv()
167    }
168
169    pub async fn revoke(self) {
170        let _ = self.shutdown.send(true);
171        let _ = self.task.await;
172    }
173}
174
175async fn serve(
176    listener: TcpListener,
177    token: String,
178    frame: watch::Receiver<Option<RemoteFrame>>,
179    inputs: mpsc::Sender<RemoteInput>,
180    mut shutdown: watch::Receiver<bool>,
181) {
182    let clients = Arc::new(Semaphore::new(MAX_CLIENTS));
183    loop {
184        tokio::select! {
185            changed = shutdown.changed() => if changed.is_err() || *shutdown.borrow() { break },
186            accepted = listener.accept() => {
187                let Ok((stream, address)) = accepted else { continue };
188                if !address.ip().is_loopback() { continue; }
189                let Ok(permit) = Arc::clone(&clients).try_acquire_owned() else { continue };
190                let token = token.clone();
191                let frame = frame.clone();
192                let inputs = inputs.clone();
193                let revoked = shutdown.clone();
194                tokio::spawn(async move {
195                    let _permit = permit;
196                    let _ = handle_client(stream, token, frame, inputs, revoked).await;
197                });
198            }
199        }
200    }
201}
202
203async fn handle_client(
204    mut stream: TcpStream,
205    token: String,
206    mut frame: watch::Receiver<Option<RemoteFrame>>,
207    inputs: mpsc::Sender<RemoteInput>,
208    mut revoked: watch::Receiver<bool>,
209) -> DevelopmentResult<()> {
210    let mut peek = [0_u8; 4096];
211    let size = timeout(HANDSHAKE_TIMEOUT, stream.peek(&mut peek))
212        .await
213        .map_err(|_| DevelopmentError::Process("remote view handshake timed out".into()))??;
214    let request = std::str::from_utf8(&peek[..size]).unwrap_or("");
215    let expected_page = format!("GET /{token}/ ");
216    if request.starts_with(&expected_page) {
217        // Consume the request before closing the socket. Windows sends an RST
218        // when a socket is closed with unread inbound bytes, which can discard
219        // an otherwise complete HTTP response at the client.
220        let mut request_bytes = vec![0_u8; size];
221        tokio::io::AsyncReadExt::read_exact(&mut stream, &mut request_bytes).await?;
222        let body = viewer_html(&token);
223        let response = format!(
224            "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{}",
225            body.len(),
226            body
227        );
228        tokio::io::AsyncWriteExt::write_all(&mut stream, response.as_bytes()).await?;
229        tokio::io::AsyncWriteExt::shutdown(&mut stream).await?;
230        return Ok(());
231    }
232    if !request.starts_with(&format!("GET /ws/{token} ")) {
233        tokio::io::AsyncWriteExt::write_all(
234            &mut stream,
235            b"HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\nConnection: close\r\n\r\n",
236        )
237        .await?;
238        return Ok(());
239    }
240    let mut socket = accept_async(stream).await.map_err(|error| {
241        DevelopmentError::Process(format!("remote view handshake failed: {error}"))
242    })?;
243
244    loop {
245        tokio::select! {
246            changed = revoked.changed() => if changed.is_err() || *revoked.borrow() { break },
247            changed = frame.changed() => {
248                if changed.is_err() { break; }
249                let latest = { frame.borrow().clone() };
250                if let Some(value) = latest {
251                    let text = serde_json::to_string(&value)?;
252                    socket.send(tungstenite::Message::Text(text.into())).await.map_err(|error| DevelopmentError::Process(error.to_string()))?;
253                }
254            }
255            message = socket.next() => match message {
256                Some(Ok(tungstenite::Message::Text(text))) if text.len() <= MAX_INPUT_BYTES => {
257                    let input: RemoteInput = serde_json::from_str(&text)?;
258                    input.validate()?;
259                    inputs.try_send(input).map_err(|_| DevelopmentError::Process("remote input queue is full".into()))?;
260                }
261                Some(Ok(tungstenite::Message::Close(_))) | None => break,
262                Some(Ok(_)) => {}
263                Some(Err(error)) => return Err(DevelopmentError::Process(error.to_string())),
264            }
265        }
266    }
267    Ok(())
268}
269
270fn secure_token() -> DevelopmentResult<String> {
271    let mut bytes = [0_u8; 32];
272    getrandom::fill(&mut bytes).map_err(|error| {
273        DevelopmentError::Process(format!("secure token generation failed: {error}"))
274    })?;
275    Ok(base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(bytes))
276}
277
278fn viewer_html(token: &str) -> String {
279    format!(
280        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>"#
281    )
282}
283
284#[cfg(test)]
285mod tests {
286    use super::*;
287
288    #[tokio::test]
289    async fn endpoint_is_loopback_tokenized_and_revocable() {
290        let view = RemoteView::bind().await.unwrap();
291        assert!(view.local_url().starts_with("http://127.0.0.1:"));
292        assert!(!view.local_url().contains("="));
293        assert!(view.ssh_forward_hint().contains("127.0.0.1"));
294        let response = reqwest::get(view.local_url()).await.unwrap();
295        assert!(response.status().is_success());
296        assert!(
297            response.headers()["cache-control"]
298                .to_str()
299                .unwrap()
300                .contains("no-store")
301        );
302        view.revoke().await;
303    }
304
305    #[tokio::test]
306    async fn websocket_delivers_latest_frame_and_revision_bound_input() {
307        let mut view = RemoteView::bind().await.unwrap();
308        let token = view
309            .local_url()
310            .trim_end_matches('/')
311            .rsplit('/')
312            .next()
313            .unwrap()
314            .to_string();
315        let ws_url = format!("ws://127.0.0.1:{}/ws/{token}", view.port());
316        let (mut socket, _) = tokio_tungstenite::connect_async(ws_url).await.unwrap();
317        view.publish(RemoteFrame {
318            browser_revision: 7,
319            mime_type: "image/png".into(),
320            data: "AA==".into(),
321        });
322        let message = timeout(Duration::from_secs(2), socket.next())
323            .await
324            .unwrap()
325            .unwrap()
326            .unwrap();
327        assert!(message.to_text().unwrap().contains("\"browserRevision\":7"));
328        socket
329            .send(tungstenite::Message::Text(
330                serde_json::to_string(&RemoteInput::Key {
331                    key: "Enter".into(),
332                    expected_revision: 7,
333                })
334                .unwrap()
335                .into(),
336            ))
337            .await
338            .unwrap();
339        let input = timeout(Duration::from_secs(2), async {
340            loop {
341                if let Ok(input) = view.try_recv_input() {
342                    break input;
343                }
344                tokio::time::sleep(Duration::from_millis(10)).await;
345            }
346        })
347        .await
348        .unwrap();
349        assert_eq!(input.expected_revision(), 7);
350        view.revoke().await;
351    }
352
353    #[test]
354    fn inputs_are_revision_bound_and_bounded() {
355        let input = RemoteInput::Click {
356            x: 0.5,
357            y: 0.25,
358            expected_revision: 9,
359        };
360        assert_eq!(input.expected_revision(), 9);
361        assert!(input.validate().is_ok());
362        assert!(
363            RemoteInput::Click {
364                x: 2.0,
365                y: 0.0,
366                expected_revision: 9
367            }
368            .validate()
369            .is_err()
370        );
371    }
372
373    #[tokio::test]
374    async fn frame_mailbox_rejects_unsupported_and_oversized_payloads() {
375        let view = RemoteView::bind().await.unwrap();
376        assert!(!view.publish(RemoteFrame {
377            browser_revision: 1,
378            mime_type: "text/html".into(),
379            data: "x".into(),
380        }));
381        assert!(!view.publish(RemoteFrame {
382            browser_revision: 1,
383            mime_type: "image/png".into(),
384            data: "x".repeat(MAX_FRAME_DATA_BYTES + 1),
385        }));
386        view.revoke().await;
387    }
388}