Fetch remote server trace reports

Cargo.lock

@@ -436,7 +436,7 @@ dependencies = [
 
 [[package]]
 name = "dosh"
-version = "1.0.0-rc26"
+version = "1.0.0-rc34"
 dependencies = [
  "anyhow",
  "base64",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "dosh"
-version = "1.0.0-rc26"
+version = "1.0.0-rc34"
 edition = "2024"
 license = "MIT"
 

README.md

@@ -68,6 +68,31 @@ dosh restart HOST
 Agent forwarding is opt-in with `-A` and must also be enabled on the server.
 File copy must be enabled by the server config.
 
+## Tracing
+
+For terminal/reconnect bugs, run a client with:
+
+```sh
+dosh trace HOST
+```
+
+The client log path is printed before the session starts. To choose it:
+
+```sh
+dosh trace --client-log /tmp/dosh-client.log HOST
+```
+
+Summarize collected traces with:
+
+```sh
+dosh trace report HOST --client-log /tmp/dosh-client.log
+```
+
+When `HOST` is given, Dosh fetches `/tmp/dosh-server.log` over SSH before
+building the report. Set `DOSH_TRACE=/tmp/dosh-server.log` on `dosh-server` for
+matching server events. Trace byte prefixes are enabled for `dosh trace`, so use
+it only for short reproductions.
+
 ## VS Code
 
 Dosh can carry VS Code Remote-SSH through its transport:

src/bin/dosh-server.rs

@@ -67,6 +67,15 @@ static AGENT_SOCK_COUNTER: AtomicU64 = AtomicU64::new(0);
 /// before it is swept by the cleanup task.
 const NATIVE_HANDSHAKE_TTL_SECS: u64 = 30;
 
+fn hex_id(id: [u8; 16]) -> String {
+    let mut out = String::with_capacity(32);
+    for byte in id {
+        use std::fmt::Write as _;
+        let _ = write!(&mut out, "{byte:02x}");
+    }
+    out
+}
+
 #[derive(Debug, Parser)]
 #[command(
     name = "dosh-server",
@@ -1602,9 +1611,22 @@ async fn handle_resume(
     peer: SocketAddr,
     packet: &protocol::Packet,
 ) -> Result<()> {
+    dosh::trace::event(
+        "server.resume_start",
+        &[
+            ("peer", peer.to_string()),
+            ("client", hex_id(packet.header.conn_id)),
+            ("seq", packet.header.seq.to_string()),
+            ("ack", packet.header.ack.to_string()),
+        ],
+    );
     let (key, session_name) = match find_client_decrypt_key(state, &packet.header) {
         Ok(found) => found,
         Err(_) => {
+            dosh::trace::event(
+                "server.resume_unknown_client",
+                &[("client", hex_id(packet.header.conn_id))],
+            );
             return send_reject_to_client(socket, peer, packet.header.conn_id, "unknown client")
                 .await;
         }
@@ -1623,8 +1645,25 @@ async fn handle_resume(
                 .get_mut(&packet.header.conn_id)
                 .ok_or_else(|| anyhow!("unknown client"))?;
             if !client.replay.accept(packet.header.seq) {
+                dosh::trace::event(
+                    "server.resume_replay_drop",
+                    &[
+                        ("session", req.session.clone()),
+                        ("seq", packet.header.seq.to_string()),
+                    ],
+                );
                 return Ok(());
             }
+            if client.endpoint != peer {
+                dosh::trace::event(
+                    "server.resume_roam",
+                    &[
+                        ("session", req.session.clone()),
+                        ("from", client.endpoint.to_string()),
+                        ("to", peer.to_string()),
+                    ],
+                );
+            }
             client.endpoint = peer;
             client.last_acked = req.last_rendered_seq;
             client.cols = req.cols;
@@ -1662,6 +1701,14 @@ async fn handle_resume(
         &body,
     )?;
     let _ = send_udp(socket, &out, peer).await?;
+    dosh::trace::event(
+        "server.resume_ok",
+        &[
+            ("session", frame.session),
+            ("output_seq", frame.output_seq.to_string()),
+            ("bytes", frame.bytes.len().to_string()),
+        ],
+    );
     Ok(())
 }
 
@@ -1673,6 +1720,7 @@ async fn handle_input(
     let (key, session_name) = find_client_decrypt_key(state, &packet.header)?;
     let body = protocol::decrypt_body(packet, &key, CLIENT_TO_SERVER)?;
     let input: Input = protocol::from_body(&body)?;
+    let input_summary = dosh::trace::bytes_summary(&input.bytes);
     let mut locked = state.lock().expect("server state poisoned");
     let session = locked
         .sessions
@@ -1683,13 +1731,37 @@ async fn handle_input(
         .get_mut(&packet.header.conn_id)
         .ok_or_else(|| anyhow!("unknown client"))?;
     if !client.replay.accept(packet.header.seq) {
+        dosh::trace::event(
+            "server.input_replay_drop",
+            &[
+                ("session", session_name.clone()),
+                ("seq", packet.header.seq.to_string()),
+                ("summary", input_summary),
+            ],
+        );
         return Ok(());
     }
     if client.endpoint != peer {
+        dosh::trace::event(
+            "server.input_roam",
+            &[
+                ("session", session_name.clone()),
+                ("from", client.endpoint.to_string()),
+                ("to", peer.to_string()),
+            ],
+        );
         client.endpoint = peer;
     }
     client.last_seen = Instant::now();
     if !mode_allows_terminal_updates(&client.mode) {
+        dosh::trace::event(
+            "server.input_rejected_mode",
+            &[
+                ("session", session_name),
+                ("mode", client.mode.clone()),
+                ("summary", input_summary),
+            ],
+        );
         return Ok(());
     }
     session
@@ -1697,6 +1769,14 @@ async fn handle_input(
         .as_ref()
         .context("terminal session has no pty")?
         .write_all(&input.bytes)?;
+    dosh::trace::event(
+        "server.pty_write",
+        &[
+            ("session", session_name),
+            ("seq", packet.header.seq.to_string()),
+            ("summary", input_summary),
+        ],
+    );
     Ok(())
 }
 
@@ -2681,6 +2761,46 @@ async fn handle_file_request(
             send_file_response_to_client(state, socket, client_id, stream_id, FileResponse::Ok)
                 .await
         }
+        FileRequest::Readlink { path } => {
+            let path = clean_remote_path(&path, home)?;
+            let target =
+                fs::read_link(&path).with_context(|| format!("readlink {}", path.display()))?;
+            let target = target
+                .to_str()
+                .ok_or_else(|| anyhow!("symlink target is not valid UTF-8"))?
+                .to_string();
+            send_file_response_to_client(
+                state,
+                socket,
+                client_id,
+                stream_id,
+                FileResponse::LinkTarget { target },
+            )
+            .await
+        }
+        FileRequest::Symlink {
+            path,
+            target,
+            overwrite,
+        } => {
+            let path = clean_remote_path(&path, home)?;
+            if let Some(parent) = path.parent() {
+                fs::create_dir_all(parent)
+                    .with_context(|| format!("create {}", parent.display()))?;
+            }
+            if let Ok(metadata) = fs::symlink_metadata(&path) {
+                anyhow::ensure!(overwrite, "destination exists: {}", path.display());
+                anyhow::ensure!(
+                    !metadata.is_dir(),
+                    "destination is a directory: {}",
+                    path.display()
+                );
+                fs::remove_file(&path).with_context(|| format!("remove {}", path.display()))?;
+            }
+            create_symlink(&target, &path)?;
+            send_file_response_to_client(state, socket, client_id, stream_id, FileResponse::Ok)
+                .await
+        }
         FileRequest::Remove { path, recursive } => {
             let path = clean_remote_path(&path, home)?;
             let metadata =
@@ -3065,6 +3185,17 @@ fn set_mode(path: &Path, mode: u32) -> Result<()> {
     fs::set_permissions(path, permissions).with_context(|| format!("chmod {}", path.display()))
 }
 
+#[cfg(unix)]
+fn create_symlink(target: &str, path: &Path) -> Result<()> {
+    std::os::unix::fs::symlink(target, path)
+        .with_context(|| format!("symlink {} -> {}", path.display(), target))
+}
+
+#[cfg(not(unix))]
+fn create_symlink(_target: &str, _path: &Path) -> Result<()> {
+    bail!("symlink creation is not supported on this server platform")
+}
+
 fn upload_temp_path(final_path: &Path, stream_id: u64) -> PathBuf {
     let name = final_path
         .file_name()

src/file_transfer.rs

@@ -18,6 +18,14 @@ pub enum FileRequest {
         path: String,
         mode: Option<u32>,
     },
+    Readlink {
+        path: String,
+    },
+    Symlink {
+        path: String,
+        target: String,
+        overwrite: bool,
+    },
     Remove {
         path: String,
         recursive: bool,
@@ -56,6 +64,9 @@ pub enum FileResponse {
     List {
         entries: Vec<FileEntry>,
     },
+    LinkTarget {
+        target: String,
+    },
     Start {
         meta: FileMeta,
         offset: u64,

src/lib.rs

@@ -22,5 +22,6 @@ pub mod protocol;
 pub mod pty;
 pub mod server;
 pub mod ssh_agent;
+pub mod trace;
 pub mod transport;
 pub mod udp;

src/trace.rs

@@ -0,0 +1,161 @@
+use std::fs::{File, OpenOptions};
+use std::io::Write;
+use std::path::PathBuf;
+use std::sync::{Mutex, OnceLock};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+static TRACE_FILE: OnceLock<Option<Mutex<File>>> = OnceLock::new();
+static TRACE_BYTES: OnceLock<bool> = OnceLock::new();
+
+pub fn enabled() -> bool {
+    TRACE_FILE.get_or_init(open_trace_file).is_some()
+}
+
+pub fn bytes_enabled() -> bool {
+    *TRACE_BYTES.get_or_init(|| truthy_env("DOSH_TRACE_BYTES"))
+}
+
+pub fn event(name: &str, fields: &[(&str, String)]) {
+    let Some(file) = TRACE_FILE.get_or_init(open_trace_file) else {
+        return;
+    };
+    let now = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|duration| duration.as_millis())
+        .unwrap_or(0);
+    let mut line = format!(
+        "ts_ms={} pid={} event={}",
+        now,
+        std::process::id(),
+        shell_escape(name)
+    );
+    for (key, value) in fields {
+        line.push(' ');
+        line.push_str(key);
+        line.push('=');
+        line.push_str(&shell_escape(value));
+    }
+    line.push('\n');
+    if let Ok(mut file) = file.lock() {
+        let _ = file.write_all(line.as_bytes());
+        let _ = file.flush();
+    }
+}
+
+pub fn bytes_summary(bytes: &[u8]) -> String {
+    let mut parts = vec![
+        format!("len={}", bytes.len()),
+        format!(
+            "esc={}",
+            contains_byte(bytes, 0x1b) || contains_byte(bytes, 0x9b)
+        ),
+        format!("focus={}", has_focus_report(bytes)),
+        format!("mouseish={}", looks_mouseish(bytes)),
+        format!("printable={}", printable_count(bytes)),
+    ];
+    if bytes_enabled() {
+        parts.push(format!("hex={}", hex_prefix(bytes, 160)));
+    }
+    parts.join(",")
+}
+
+fn open_trace_file() -> Option<Mutex<File>> {
+    let raw = std::env::var_os("DOSH_TRACE")?;
+    let normalized = raw.to_string_lossy().to_ascii_lowercase();
+    if normalized.is_empty() || matches!(normalized.as_str(), "0" | "false" | "off") {
+        return None;
+    }
+    let path = if matches!(normalized.as_str(), "1" | "true" | "on") {
+        default_trace_path()
+    } else {
+        PathBuf::from(raw)
+    };
+    if let Some(parent) = path.parent() {
+        let _ = std::fs::create_dir_all(parent);
+    }
+    OpenOptions::new()
+        .create(true)
+        .append(true)
+        .open(&path)
+        .ok()
+        .map(Mutex::new)
+}
+
+fn default_trace_path() -> PathBuf {
+    let root = dirs::cache_dir()
+        .unwrap_or_else(std::env::temp_dir)
+        .join("dosh")
+        .join("trace");
+    let exe = std::env::current_exe()
+        .ok()
+        .and_then(|path| {
+            path.file_stem()
+                .map(|stem| stem.to_string_lossy().to_string())
+        })
+        .unwrap_or_else(|| "dosh".to_string());
+    root.join(format!("{}-{}.log", exe, std::process::id()))
+}
+
+fn truthy_env(name: &str) -> bool {
+    std::env::var_os(name).is_some_and(|value| {
+        let normalized = value.to_string_lossy().to_ascii_lowercase();
+        !normalized.is_empty() && !matches!(normalized.as_str(), "0" | "false" | "off")
+    })
+}
+
+fn shell_escape(value: &str) -> String {
+    if value.bytes().all(|byte| {
+        byte.is_ascii_alphanumeric()
+            || matches!(byte, b'.' | b'-' | b'_' | b':' | b'/' | b',' | b'=')
+    }) {
+        return value.to_string();
+    }
+    let mut out = String::from("'");
+    for ch in value.chars() {
+        if ch == '\'' {
+            out.push_str("'\\''");
+        } else {
+            out.push(ch);
+        }
+    }
+    out.push('\'');
+    out
+}
+
+fn contains_byte(bytes: &[u8], needle: u8) -> bool {
+    bytes.contains(&needle)
+}
+
+fn has_focus_report(bytes: &[u8]) -> bool {
+    bytes
+        .windows(3)
+        .any(|window| matches!(window, b"\x1b[I" | b"\x1b[O"))
+        || bytes
+            .windows(2)
+            .any(|window| matches!(window, b"\x9bI" | b"\x9bO"))
+}
+
+fn looks_mouseish(bytes: &[u8]) -> bool {
+    bytes.windows(3).any(|window| window == b"\x1b[<")
+        || bytes.windows(2).any(|window| window == b"\x9b<")
+        || bytes.iter().filter(|byte| **byte == b';').take(3).count() >= 2
+}
+
+fn printable_count(bytes: &[u8]) -> usize {
+    bytes
+        .iter()
+        .filter(|byte| byte.is_ascii_graphic() || **byte == b' ')
+        .count()
+}
+
+fn hex_prefix(bytes: &[u8], max: usize) -> String {
+    let mut out = String::with_capacity(bytes.len().min(max) * 2);
+    for byte in bytes.iter().take(max) {
+        use std::fmt::Write as _;
+        let _ = write!(&mut out, "{byte:02x}");
+    }
+    if bytes.len() > max {
+        out.push_str("...");
+    }
+    out
+}

tests/integration_smoke.rs

@@ -1003,6 +1003,8 @@ fn native_file_copy_recursive_round_trip() {
     fs::create_dir_all(src.join("nested")).unwrap();
     fs::write(src.join("root.txt"), b"root file\n").unwrap();
     fs::write(src.join("nested/child.txt"), b"child file\n").unwrap();
+    std::os::unix::fs::symlink("root.txt", src.join("root-link")).unwrap();
+    std::os::unix::fs::symlink("nested/child.txt", src.join("child-link")).unwrap();
 
     let client_bin = env!("CARGO_BIN_EXE_dosh-client");
     let upload = Command::new(client_bin)
@@ -1108,6 +1110,14 @@ fn native_file_copy_recursive_round_trip() {
         fs::read_to_string(downloaded.join("nested/child.txt")).unwrap(),
         "child file\n"
     );
+    assert_eq!(
+        fs::read_link(downloaded.join("root-link")).unwrap(),
+        PathBuf::from("root.txt")
+    );
+    assert_eq!(
+        fs::read_link(downloaded.join("child-link")).unwrap(),
+        PathBuf::from("nested/child.txt")
+    );
 
     let remove = Command::new(client_bin)
         .arg("--dosh-host")