libadb 0.9.0

Low-level ADB protocol library for direct TCP and USB communication
Documentation
//! URI parser for ADB transport addresses.
//!
//! Supported schemes:
//!
//! * `tcp://HOST:PORT` — `HOST` may be IPv4, a hostname, or a bracketed
//!   IPv6 address (`tcp://[::1]:5555`). Bare (unbracketed) IPv6 is
//!   rejected to keep the grammar unambiguous. `PORT` is decimal digits
//!   alone, with no sign.
//! * `usb://` — any ADB-capable USB device.
//! * `usb://VID:PID` — USB device matching VID and PID as 4 hex digits
//!   each (case-insensitive).
//! * `usb://serial/SERIAL` — USB device with the given serial number.
//!
//! The parser is zero-copy: the returned [`Uri`] borrows slices of the
//! input string.

#[cfg(test)]
mod tests;

/// A parsed transport address, borrowing from the string it came from.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Uri<'a> {
    /// `tcp://HOST:PORT`.
    Tcp {
        /// IPv4 address, hostname, or IPv6 address without its brackets.
        host: &'a str,
        /// TCP port.
        port: u16,
    },
    /// `usb://…`: the device to open.
    Usb(UsbSelector<'a>),
}

/// Which USB device a `usb://` address picks.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum UsbSelector<'a> {
    /// First available ADB device.
    Any,
    /// Match by USB vendor/product IDs.
    VidPid {
        /// USB vendor ID.
        vid: u16,
        /// USB product ID.
        pid: u16,
    },
    /// Match by serial number string.
    Serial(&'a str),
}

/// Why [`parse`] rejected an address.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum UriError {
    /// No `scheme://` prefix.
    MissingScheme,
    /// Scheme is neither `tcp` nor `usb`.
    UnknownScheme,
    /// Host is empty, malformed, or contains a colon without brackets.
    InvalidHost,
    /// Port is missing, non-numeric, or out of range.
    InvalidPort,
    /// VID/PID is not 4 hex digits or the serial is empty.
    InvalidUsbSelector,
}

impl core::fmt::Display for UriError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            Self::MissingScheme => f.write_str("missing scheme"),
            Self::UnknownScheme => f.write_str("unknown scheme (expected tcp or usb)"),
            Self::InvalidHost => f.write_str("invalid host"),
            Self::InvalidPort => f.write_str("invalid port"),
            Self::InvalidUsbSelector => f.write_str("invalid usb selector"),
        }
    }
}

impl core::error::Error for UriError {}

/// Parse a transport URI.
pub fn parse(s: &str) -> Result<Uri<'_>, UriError> {
    let (scheme, rest) = s.split_once("://").ok_or(UriError::MissingScheme)?;
    match scheme {
        "tcp" => parse_tcp(rest),
        "usb" => parse_usb(rest),
        _ => Err(UriError::UnknownScheme),
    }
}

fn parse_tcp(rest: &str) -> Result<Uri<'_>, UriError> {
    if rest.is_empty() {
        return Err(UriError::InvalidHost);
    }
    if let Some(after_bracket) = rest.strip_prefix('[') {
        let (host, after) = after_bracket.split_once(']').ok_or(UriError::InvalidHost)?;
        if host.is_empty() {
            return Err(UriError::InvalidHost);
        }
        let port_str = after.strip_prefix(':').ok_or(UriError::InvalidPort)?;
        let port = parse_port(port_str)?;
        Ok(Uri::Tcp { host, port })
    } else {
        let (host, port_str) = rest.rsplit_once(':').ok_or(UriError::InvalidPort)?;
        if host.is_empty() {
            return Err(UriError::InvalidHost);
        }
        if host.contains(':') {
            return Err(UriError::InvalidHost);
        }
        let port = parse_port(port_str)?;
        Ok(Uri::Tcp { host, port })
    }
}

fn parse_port(port: &str) -> Result<u16, UriError> {
    if !port.bytes().all(|b| b.is_ascii_digit()) {
        return Err(UriError::InvalidPort);
    }
    port.parse().map_err(|_| UriError::InvalidPort)
}

fn parse_usb(rest: &str) -> Result<Uri<'_>, UriError> {
    if rest.is_empty() {
        return Ok(Uri::Usb(UsbSelector::Any));
    }
    if let Some(serial) = rest.strip_prefix("serial/") {
        if serial.is_empty() {
            return Err(UriError::InvalidUsbSelector);
        }
        return Ok(Uri::Usb(UsbSelector::Serial(serial)));
    }
    let (vid_s, pid_s) = rest.split_once(':').ok_or(UriError::InvalidUsbSelector)?;
    let vid = parse_usb_id(vid_s)?;
    let pid = parse_usb_id(pid_s)?;
    Ok(Uri::Usb(UsbSelector::VidPid { vid, pid }))
}

fn parse_usb_id(id: &str) -> Result<u16, UriError> {
    if id.len() != 4 || !id.bytes().all(|b| b.is_ascii_hexdigit()) {
        return Err(UriError::InvalidUsbSelector);
    }
    u16::from_str_radix(id, 16).map_err(|_| UriError::InvalidUsbSelector)
}