Skip to content

Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.

18.8 KB
Raw Blame
// SPDX-License-Identifier: MPL-2.0
//! Pure-Rust client for the local ADB server (`127.0.0.1:5037`) used to detect
//! USB-attached Android devices and set up TCP port forwarding for NectarLink's
//! USB QUIC tunnel.

use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4};

use tokio::{
    io::{AsyncReadExt, AsyncWriteExt},
    net::{TcpListener, TcpStream},
};
use tokio_util::sync::CancellationToken;

/// Default local ADB server address (`127.0.0.1:5037`).
pub const DEFAULT_ADB_ADDR: SocketAddr = SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::LOCALHOST, 5037));

/// Returns `true` if `serial` is non-empty, made only of the characters
/// serials use, and permitted by the optional `NECTARLINK_ADB_ONLY_SERIAL`
/// filter. A USB device names its own serial, and it goes into adb commands
/// as text, so anything else (`;`, spaces, control characters) is refused.
pub fn is_serial_allowed(serial: &str) -> bool {
    let trimmed = serial.trim();
    if trimmed.is_empty()
        || trimmed.len() > 128
        || !trimmed
            .bytes()
            .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b'-' | b':' | b'[' | b']'))
    {
        return false;
    }
    if let Ok(only) = std::env::var("NECTARLINK_ADB_ONLY_SERIAL") {
        let only = only.trim();
        if !only.is_empty() && trimmed != only {
            return false;
        }
    }
    true
}

/// Errors returned by ADB server operations.
#[derive(Debug, thiserror::Error)]
pub enum AdbError {
    #[error("ADB I/O error: {0}")]
    Io(#[from] std::io::Error),
    #[error("ADB server rejected command: {0}")]
    Remote(String),
    #[error("ADB protocol error: {0}")]
    Protocol(String),
    #[error("ADB serial {0} is blocked by safety guard")]
    BlockedSerial(String),
}

/// An Android device reported by the ADB server.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AdbDevice {
    pub serial: String,
    pub state: String,
    pub model: Option<String>,
    pub product: Option<String>,
    pub transport_id: Option<String>,
}

impl AdbDevice {
    /// Whether the device is online and authorized (`state == "device"`).
    pub fn is_online(&self) -> bool {
        self.state == "device"
    }
}

/// Parses the output of `host:devices-l` or `host:track-devices`, filtering out
/// any serial rejected by [`is_serial_allowed`].
pub fn parse_devices_l(input: &str) -> Vec<AdbDevice> {
    let mut devices = Vec::new();
    for line in input.lines() {
        let trimmed = line.trim();
        if trimmed.is_empty() || trimmed.starts_with("List of devices") {
            continue;
        }
        let mut parts = trimmed.split_whitespace();
        let Some(serial) = parts.next() else { continue };
        let Some(state) = parts.next() else { continue };
        if !is_serial_allowed(serial) {
            continue;
        }
        let mut model = None;
        let mut product = None;
        let mut transport_id = None;
        for token in parts {
            if let Some(v) = token.strip_prefix("model:") {
                model = Some(v.to_owned());
            } else if let Some(v) = token.strip_prefix("product:") {
                product = Some(v.to_owned());
            } else if let Some(v) = token.strip_prefix("transport_id:") {
                transport_id = Some(v.to_owned());
            }
        }
        devices.push(AdbDevice {
            serial: serial.to_owned(),
            state: state.to_owned(),
            model,
            product,
            transport_id,
        });
    }
    devices
}

/// Sends a length-prefixed command to the ADB server and reads the 4-byte status.
pub async fn send_command(stream: &mut TcpStream, cmd: &str) -> Result<(), AdbError> {
    let frame = format!("{:04x}{cmd}", cmd.len());
    stream.write_all(frame.as_bytes()).await?;
    stream.flush().await?;
    let mut status = [0u8; 4];
    stream.read_exact(&mut status).await?;
    match &status {
        b"OKAY" => Ok(()),
        b"FAIL" => {
            let reason = read_payload(stream).await.unwrap_or_else(|_| "unknown failure".into());
            Err(AdbError::Remote(reason))
        }
        other => {
            Err(AdbError::Protocol(format!("unexpected ADB status: {}", String::from_utf8_lossy(other))))
        }
    }
}

/// Reads a 4-hex-digit length prefix followed by the UTF-8 payload.
pub async fn read_payload(stream: &mut TcpStream) -> Result<String, AdbError> {
    let mut len_hex = [0u8; 4];
    stream.read_exact(&mut len_hex).await?;
    let len_str =
        std::str::from_utf8(&len_hex).map_err(|_| AdbError::Protocol("invalid hex length".into()))?;
    let len = usize::from_str_radix(len_str, 16)
        .map_err(|_| AdbError::Protocol(format!("invalid hex length: {len_str}")))?;
    let mut buf = vec![0u8; len];
    if len > 0 {
        stream.read_exact(&mut buf).await?;
    }
    String::from_utf8(buf).map_err(|_| AdbError::Protocol("invalid UTF-8 payload".into()))
}

/// Lists attached ADB devices via `host:devices-l`.
pub async fn list_devices(server: SocketAddr) -> Result<Vec<AdbDevice>, AdbError> {
    let mut stream = TcpStream::connect(server).await?;
    send_command(&mut stream, "host:devices-l").await?;
    let payload = read_payload(&mut stream).await?;
    Ok(parse_devices_l(&payload))
}

/// Sets up TCP port forwarding (`adb -s <serial> forward tcp:<local> tcp:<remote>`)
/// and returns the bound local TCP port on `127.0.0.1`.
pub async fn forward_tcp(
    server: SocketAddr,
    serial: &str,
    local_port: u16,
    remote_port: u16,
) -> Result<u16, AdbError> {
    if !is_serial_allowed(serial) {
        return Err(AdbError::BlockedSerial(serial.to_owned()));
    }
    let mut port = if local_port == 0 { free_local_port().await? } else { local_port };
    let mut attempts = 0;
    loop {
        let mut stream = TcpStream::connect(server).await?;
        let cmd = format!("host-serial:{serial}:forward:tcp:{port};tcp:{remote_port}");
        match send_command(&mut stream, &cmd).await {
            Ok(()) => return Ok(port),
            // A port that was free a moment ago can still be taken by the time
            // adb binds it (on WSL the Windows side can hold a port the Linux
            // side just closed). Only then is another port worth trying.
            Err(AdbError::Remote(reason))
                if local_port == 0 && attempts < BIND_RETRIES && is_bind_failure(&reason) =>
            {
                attempts += 1;
                port = free_local_port().await?;
            }
            Err(e) => return Err(e),
        }
    }
}

/// How many other ports [`forward_tcp`] tries when adb can't bind the one it picked.
const BIND_RETRIES: u32 = 4;

/// A local TCP port that is free right now.
async fn free_local_port() -> Result<u16, AdbError> {
    let listener = TcpListener::bind("127.0.0.1:0").await?;
    Ok(listener.local_addr()?.port())
}

/// Whether an adb `FAIL` reason means the local port couldn't be bound,
/// for example "cannot bind listener: Address already in use".
fn is_bind_failure(reason: &str) -> bool {
    let reason = reason.to_ascii_lowercase();
    reason.contains("cannot bind") || reason.contains("already in use")
}

/// Runs `command` in a shell on `serial` (`adb -s <serial> shell <command>`)
/// and returns the connection carrying its output. The command runs as long
/// as the connection stays open; dropping it ends the command.
pub async fn shell(server: SocketAddr, serial: &str, command: &str) -> Result<TcpStream, AdbError> {
    if !is_serial_allowed(serial) {
        return Err(AdbError::BlockedSerial(serial.to_owned()));
    }
    let mut stream = TcpStream::connect(server).await?;
    send_command(&mut stream, &format!("host:transport:{serial}")).await?;
    send_command(&mut stream, &format!("shell:{command}")).await?;
    Ok(stream)
}

/// Removes a TCP port forward (`adb -s <serial> forward --remove tcp:<local>`).
pub async fn kill_forward_tcp(server: SocketAddr, serial: &str, local_port: u16) -> Result<(), AdbError> {
    if !is_serial_allowed(serial) {
        return Err(AdbError::BlockedSerial(serial.to_owned()));
    }
    let mut stream = TcpStream::connect(server).await?;
    let cmd = format!("host-serial:{serial}:killforward:tcp:{local_port}");
    send_command(&mut stream, &cmd).await?;
    Ok(())
}

/// Streams device list changes from `host:track-devices` until `cancel` is
/// triggered or the ADB server closes the connection.
pub async fn track_devices<F>(
    server: SocketAddr,
    cancel: CancellationToken,
    mut on_change: F,
) -> Result<(), AdbError>
where
    F: FnMut(Vec<AdbDevice>),
{
    let mut stream = tokio::select! {
        _ = cancel.cancelled() => return Ok(()),
        res = TcpStream::connect(server) => res?,
    };
    send_command(&mut stream, "host:track-devices").await?;
    loop {
        let payload = tokio::select! {
            _ = cancel.cancelled() => return Ok(()),
            res = read_payload(&mut stream) => res?,
        };
        on_change(parse_devices_l(&payload));
    }
}

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

    #[test]
    fn only_serials_made_of_serial_characters_are_allowed() {
        for serial in [
            "emulator-5554",
            "R5CT20ABCDE",
            "192.168.1.20:5555",
            "adb-R5CT20-abc._adb-tls-connect._tcp",
            "[fe80::1]:5555",
        ] {
            assert!(is_serial_allowed(serial), "{serial}");
        }
        for serial in [
            "",
            "a;b",
            "x:forward:tcp:1;tcp:2",
            "a b",
            "a
b",
            &"a".repeat(129),
        ] {
            assert!(!is_serial_allowed(serial), "{serial:?}");
        }
    }
    use std::sync::{Arc, Mutex};

    #[test]
    fn empty_serial_is_rejected_and_valid_serials_are_allowed() {
        assert!(!is_serial_allowed(""));
        assert!(!is_serial_allowed("   "));
        assert!(is_serial_allowed("emulator-5554"));
        assert!(is_serial_allowed("SYNTH_SERIAL_001"));
    }

    #[test]
    fn parse_devices_l_parses_metadata() {
        let sample = "\
List of devices attached
SYNTH_SERIAL_001       device product:dm1q model:Test_Phone device:dm1q transport_id:1
emulator-5554          device product:sdk_gphone64_x86_64 model:Pixel_9 device:emu64x transport_id:2
192.168.1.40:5555      offline transport_id:3
";
        let devices = parse_devices_l(sample);
        assert_eq!(devices.len(), 3);
        assert_eq!(
            devices[0],
            AdbDevice {
                serial: "SYNTH_SERIAL_001".into(),
                state: "device".into(),
                model: Some("Test_Phone".into()),
                product: Some("dm1q".into()),
                transport_id: Some("1".into()),
            }
        );
        assert!(devices[0].is_online());
        assert_eq!(
            devices[1],
            AdbDevice {
                serial: "emulator-5554".into(),
                state: "device".into(),
                model: Some("Pixel_9".into()),
                product: Some("sdk_gphone64_x86_64".into()),
                transport_id: Some("2".into()),
            }
        );
        assert!(devices[1].is_online());
        assert_eq!(
            devices[2],
            AdbDevice {
                serial: "192.168.1.40:5555".into(),
                state: "offline".into(),
                model: None,
                product: None,
                transport_id: Some("3".into()),
            }
        );
        assert!(!devices[2].is_online());
    }

    #[test]
    fn only_bind_failures_count_as_bind_failures() {
        assert!(is_bind_failure(
            "cannot bind listener: cannot bind to 127.0.0.1:5000: Address already in use (98)"
        ));
        assert!(is_bind_failure("Address already in use"));
        assert!(!is_bind_failure("device offline"));
        assert!(!is_bind_failure("device unauthorized."));
        assert!(!is_bind_failure("more than one device/emulator"));
    }

    /// A mock adb server that answers each `forward` with the next of
    /// `replies` (`None` = OKAY, `Some(reason)` = FAIL) and records the commands.
    async fn forward_server(replies: Vec<Option<&'static str>>) -> (SocketAddr, Arc<Mutex<Vec<String>>>) {
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let commands = Arc::new(Mutex::new(Vec::new()));
        let seen = commands.clone();
        tokio::spawn(async move {
            let mut replies = replies.into_iter();
            while let Ok((mut socket, _)) = listener.accept().await {
                let Ok(cmd) = read_payload(&mut socket).await else { continue };
                seen.lock().unwrap().push(cmd);
                match replies.next().flatten() {
                    None => {
                        let _ = socket.write_all(b"OKAY").await;
                    }
                    Some(reason) => {
                        let frame = format!("FAIL{:04x}{reason}", reason.len());
                        let _ = socket.write_all(frame.as_bytes()).await;
                    }
                }
                let _ = socket.flush().await;
            }
        });
        (addr, commands)
    }

    #[tokio::test]
    async fn forward_tries_another_port_only_when_adb_cannot_bind() {
        let (addr, commands) =
            forward_server(vec![Some("cannot bind listener: Address already in use"), None]).await;
        let port = forward_tcp(addr, "emulator-5554", 0, 53319).await.unwrap();
        let commands = commands.lock().unwrap().clone();
        assert_eq!(commands.len(), 2, "one retry after the bind failure");
        assert!(commands[1].contains(&format!("forward:tcp:{port};tcp:53319")));

        let (addr, commands) = forward_server(vec![Some("device offline")]).await;
        let err = forward_tcp(addr, "emulator-5554", 0, 53319).await.unwrap_err();
        assert!(matches!(err, AdbError::Remote(ref r) if r == "device offline"));
        assert_eq!(commands.lock().unwrap().len(), 1, "other errors are not retried");

        let (addr, commands) = forward_server(vec![Some("cannot bind listener"); 10]).await;
        assert!(forward_tcp(addr, "emulator-5554", 0, 53319).await.is_err());
        assert_eq!(commands.lock().unwrap().len(), 1 + BIND_RETRIES as usize, "retries are bounded");

        let (addr, commands) = forward_server(vec![Some("cannot bind listener")]).await;
        assert!(forward_tcp(addr, "emulator-5554", 5000, 53319).await.is_err());
        assert_eq!(commands.lock().unwrap().len(), 1, "a port the caller chose is not swapped");
    }

    #[tokio::test]
    async fn shell_picks_the_device_then_streams_the_commands_output() {
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let server = tokio::spawn(async move {
            let (mut socket, _) = listener.accept().await.unwrap();
            let transport = read_payload(&mut socket).await.unwrap();
            socket.write_all(b"OKAY").await.unwrap();
            let shell = read_payload(&mut socket).await.unwrap();
            socket.write_all(b"OKAY").await.unwrap();
            socket.write_all(b"ready 41234\n").await.unwrap();
            (transport, shell)
        });
        let mut stream = shell(addr, "R5CT1234", "echo hi").await.unwrap();
        let mut line = String::new();
        tokio::io::AsyncBufReadExt::read_line(&mut tokio::io::BufReader::new(&mut stream), &mut line)
            .await
            .unwrap();
        assert_eq!(line, "ready 41234\n");
        let (transport, shell_cmd) = server.await.unwrap();
        assert_eq!(transport, "host:transport:R5CT1234");
        assert_eq!(shell_cmd, "shell:echo hi");
    }

    #[tokio::test]
    async fn mock_adb_server_forward_killforward_and_track_devices() {
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let commands = Arc::new(Mutex::new(Vec::<String>::new()));
        let commands_srv = commands.clone();

        let srv = tokio::spawn(async move {
            loop {
                let Ok((mut socket, _)) = listener.accept().await else { break };
                let commands_srv = commands_srv.clone();
                tokio::spawn(async move {
                    let Ok(cmd) = read_payload(&mut socket).await else { return };
                    commands_srv.lock().unwrap().push(cmd.clone());
                    if cmd == "host:track-devices" {
                        let _ = socket.write_all(b"OKAY").await;
                        let update1 = "emulator-5554\tdevice\n";
                        let frame1 = format!("{:04x}{update1}", update1.len());
                        let _ = socket.write_all(frame1.as_bytes()).await;
                        let _ = socket.flush().await;
                        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
                    } else if cmd.starts_with("host-serial:") {
                        let _ = socket.write_all(b"OKAY").await;
                        let _ = socket.flush().await;
                    } else if cmd == "host:devices-l" {
                        let _ = socket.write_all(b"OKAY").await;
                        let body =
                            "List of devices attached\nemulator-5554 device model:Pixel_9 transport_id:4\n";
                        let frame = format!("{:04x}{body}", body.len());
                        let _ = socket.write_all(frame.as_bytes()).await;
                        let _ = socket.flush().await;
                    }
                });
            }
        });

        // Empty serial must be rejected before even connecting.
        let blocked_res = forward_tcp(addr, "   ", 0, 53319).await;
        assert!(matches!(blocked_res, Err(AdbError::BlockedSerial(_))));
        let blocked_kill = kill_forward_tcp(addr, "", 12345).await;
        assert!(matches!(blocked_kill, Err(AdbError::BlockedSerial(_))));

        let devs = list_devices(addr).await.unwrap();
        assert_eq!(devs.len(), 1);
        assert_eq!(devs[0].serial, "emulator-5554");

        let port = forward_tcp(addr, "emulator-5554", 0, 53319).await.unwrap();
        assert_ne!(port, 0);
        kill_forward_tcp(addr, "emulator-5554", port).await.unwrap();

        let cancel = CancellationToken::new();
        let cancel_clone = cancel.clone();
        let mut tracked = Vec::new();
        track_devices(addr, cancel_clone, |list| {
            tracked = list;
            cancel.cancel();
        })
        .await
        .unwrap();

        assert_eq!(tracked.len(), 1);
        assert_eq!(tracked[0].serial, "emulator-5554");
        assert!(tracked[0].is_online());

        let recorded = commands.lock().unwrap().clone();
        assert!(recorded.iter().any(|c| c == "host:devices-l"));
        assert!(
            recorded.iter().any(|c| c == &format!("host-serial:emulator-5554:forward:tcp:{port};tcp:53319"))
        );
        assert!(recorded.iter().any(|c| c == &format!("host-serial:emulator-5554:killforward:tcp:{port}")));
        assert!(recorded.iter().any(|c| c == "host:track-devices"));

        srv.abort();
    }
}