use std::net::{IpAddr, Ipv4Addr, SocketAddr, TcpListener};
use std::time::Duration;
use serde::{Deserialize, Serialize};
const PROBE_TIMEOUT: Duration = Duration::from_millis(750);
const MAX_DISCOVERY_BYTES: usize = 512 * 1024;
const MAX_TARGETS: usize = 64;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EndpointClassification {
Free,
CompatibleBrowser,
UnrelatedService,
Unknown,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DiscoveredTarget {
pub id: String,
pub title: String,
pub origin: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct EndpointProbe {
pub port: u16,
pub classification: EndpointClassification,
pub product: Option<String>,
pub targets: Vec<DiscoveredTarget>,
pub detail: String,
}
pub async fn probe_local_endpoint(port: u16) -> EndpointProbe {
let address = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), port);
match tokio::time::timeout(PROBE_TIMEOUT, tokio::net::TcpStream::connect(address)).await {
Ok(Ok(stream)) => drop(stream),
Ok(Err(error)) => {
if wait_until_bindable(address).await {
return probe(port, EndpointClassification::Free, "port is available");
}
return probe(
port,
EndpointClassification::Unknown,
format!("TCP probe failed: {error}"),
);
}
Err(_) => {
if wait_until_bindable(address).await {
return probe(port, EndpointClassification::Free, "port is available");
}
return probe(port, EndpointClassification::Unknown, "TCP probe timed out");
}
}
let client = match reqwest::Client::builder().timeout(PROBE_TIMEOUT).build() {
Ok(client) => client,
Err(error) => {
return probe(
port,
EndpointClassification::Unknown,
format!("HTTP probe setup failed: {error}"),
);
}
};
let version = match bounded_json(&client, port, "/json/version").await {
Ok(value) => value,
Err(error) => {
return probe(port, EndpointClassification::UnrelatedService, error);
}
};
let Some(websocket) = version
.get("webSocketDebuggerUrl")
.and_then(serde_json::Value::as_str)
else {
return probe(
port,
EndpointClassification::UnrelatedService,
"missing CDP browser WebSocket URL",
);
};
if !websocket.starts_with(&format!("ws://127.0.0.1:{port}/devtools/browser/"))
&& !websocket.starts_with(&format!("ws://localhost:{port}/devtools/browser/"))
{
return probe(
port,
EndpointClassification::Unknown,
"CDP endpoint advertised a non-loopback or mismatched WebSocket URL",
);
}
let product = version
.get("Browser")
.and_then(serde_json::Value::as_str)
.map(ToOwned::to_owned);
let targets = match bounded_json(&client, port, "/json/list").await {
Ok(serde_json::Value::Array(values)) => values
.into_iter()
.take(MAX_TARGETS)
.filter(|value| value.get("type").and_then(serde_json::Value::as_str) == Some("page"))
.filter_map(project_target)
.collect(),
Ok(_) => Vec::new(),
Err(_) => Vec::new(),
};
EndpointProbe {
port,
classification: EndpointClassification::CompatibleBrowser,
product,
targets,
detail: "verified Chrome DevTools discovery endpoint".to_string(),
}
}
async fn wait_until_bindable(address: SocketAddr) -> bool {
for attempt in 0..10 {
if let Ok(listener) = TcpListener::bind(address) {
drop(listener);
return true;
}
if attempt < 9 {
tokio::time::sleep(Duration::from_millis(25)).await;
}
}
false
}
pub fn reserve_loopback_port() -> std::io::Result<(u16, TcpListener)> {
let listener = TcpListener::bind((Ipv4Addr::LOCALHOST, 0))?;
let port = listener.local_addr()?.port();
Ok((port, listener))
}
async fn bounded_json(
client: &reqwest::Client,
port: u16,
path: &str,
) -> Result<serde_json::Value, String> {
let response = client
.get(format!("http://127.0.0.1:{port}{path}"))
.send()
.await
.map_err(|error| format!("HTTP discovery failed: {error}"))?;
if !response.status().is_success() {
return Err(format!("HTTP discovery returned {}", response.status()));
}
let bytes = response
.bytes()
.await
.map_err(|error| format!("HTTP discovery body failed: {error}"))?;
if bytes.len() > MAX_DISCOVERY_BYTES {
return Err("HTTP discovery response exceeded the bounded limit".to_string());
}
serde_json::from_slice(&bytes).map_err(|error| format!("invalid discovery JSON: {error}"))
}
fn project_target(value: serde_json::Value) -> Option<DiscoveredTarget> {
let id = value.get("id")?.as_str()?;
if id.is_empty() || id.len() > 256 {
return None;
}
let id = id.to_string();
let title = value
.get("title")
.and_then(serde_json::Value::as_str)
.unwrap_or("Untitled")
.chars()
.take(80)
.collect();
let origin = value
.get("url")
.and_then(serde_json::Value::as_str)
.and_then(url_origin)
.unwrap_or_else(|| "opaque".to_string());
Some(DiscoveredTarget { id, title, origin })
}
fn url_origin(url: &str) -> Option<String> {
let parsed = reqwest::Url::parse(url).ok()?;
let host = parsed.host_str()?;
Some(match parsed.port() {
Some(port) => format!("{}://{host}:{port}", parsed.scheme()),
None => format!("{}://{host}", parsed.scheme()),
})
}
fn probe(
port: u16,
classification: EndpointClassification,
detail: impl Into<String>,
) -> EndpointProbe {
EndpointProbe {
port,
classification,
product: None,
targets: Vec::new(),
detail: detail.into(),
}
}
#[cfg(test)]
mod tests {
use super::*;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
#[test]
fn target_projection_drops_paths_queries_and_fragments() {
let target = project_target(serde_json::json!({
"id": "page-1",
"type": "page",
"title": "Account",
"url": "https://example.test:8443/private?token=secret#card"
}))
.unwrap();
assert_eq!(target.origin, "https://example.test:8443");
assert!(!target.origin.contains("secret"));
}
#[test]
fn port_reservation_is_loopback_and_nonzero() {
let (port, listener) = reserve_loopback_port().unwrap();
assert_ne!(port, 0);
assert!(listener.local_addr().unwrap().ip().is_loopback());
}
#[tokio::test]
async fn unused_port_is_classified_free() {
let (port, listener) = reserve_loopback_port().unwrap();
drop(listener);
let result = probe_local_endpoint(port).await;
assert_eq!(result.classification, EndpointClassification::Free);
}
#[tokio::test]
async fn verified_cdp_is_compatible_and_projects_targets() {
let listener = tokio::net::TcpListener::bind((Ipv4Addr::LOCALHOST, 0))
.await
.unwrap();
let port = listener.local_addr().unwrap().port();
let server = tokio::spawn(async move {
for _ in 0..3 {
let (mut stream, _) = listener.accept().await.unwrap();
let mut request = vec![0_u8; 2048];
let size = stream.read(&mut request).await.unwrap();
if size == 0 {
continue;
}
let request = String::from_utf8_lossy(&request[..size]);
let body = if request.starts_with("GET /json/version") {
format!(
r#"{{"Browser":"Chrome/Test","webSocketDebuggerUrl":"ws://127.0.0.1:{port}/devtools/browser/owned"}}"#
)
} else {
r#"[{"id":"p1","type":"page","title":"Private","url":"https://example.test/path?token=secret"}]"#.into()
};
let response = format!(
"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
body.len()
);
stream.write_all(response.as_bytes()).await.unwrap();
}
});
let result = probe_local_endpoint(port).await;
assert_eq!(
result.classification,
EndpointClassification::CompatibleBrowser
);
assert_eq!(result.targets[0].origin, "https://example.test");
assert!(!serde_json::to_string(&result).unwrap().contains("secret"));
server.await.unwrap();
}
#[tokio::test]
async fn unrelated_http_service_never_becomes_attach_authority() {
let listener = tokio::net::TcpListener::bind((Ipv4Addr::LOCALHOST, 0))
.await
.unwrap();
let port = listener.local_addr().unwrap().port();
let server = tokio::spawn(async move {
for _ in 0..2 {
let (mut stream, _) = listener.accept().await.unwrap();
let mut request = [0_u8; 512];
if stream.read(&mut request).await.unwrap() == 0 {
continue;
}
stream.write_all(b"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: 13\r\nConnection: close\r\n\r\n{\"app\":\"x\"}").await.unwrap();
}
});
let result = probe_local_endpoint(port).await;
assert_eq!(
result.classification,
EndpointClassification::UnrelatedService
);
server.abort();
}
}