use std::collections::VecDeque;
use std::io::Read;
use std::path::{Path, PathBuf};
use std::time::Duration;
use std::time::Instant;
use crate::{
AgentControlRequest, AgentSnapshot, DEBUG_PROTOCOL_VERSION, DebugDescriptor, DebugEvent,
DebugProtocolError, DebugResponse, DebugStream, DiagnosticsRequest, JsonRpcId, JsonRpcMessage,
JsonRpcRequest, MCP_PROTOCOL_VERSION, MessageStream, TransportStream, WireMessage,
decode_diagnostics_event_value, decode_response_value, decode_wire_value, encode_agent_request,
encode_diagnostics_request, encode_rpc, peek_value_request_id,
};
use eyre::{Context, Result, bail, eyre};
use std::os::unix::ffi::OsStrExt;
use endpoint_libs::libs::ws::transport::framed::framed_json_neutral;
use endpoint_libs::libs::ws::transport::nagoya::NagoyaStream;
use nagoya::reactor::{Addr, Reactor, TcpStream};
use nagoya::timeout;
const REQUEST_TIMEOUT: Duration = Duration::from_secs(60);
const MAX_QUEUED_EVENTS: usize = 256;
#[derive(Debug)]
pub struct Descriptor {
pub path: PathBuf,
validated_socket_path: PathBuf,
pub descriptor: DebugDescriptor,
pub raw: serde_json::Value,
verified_reachable: bool,
}
fn client_reactor() -> &'static nagoya::reactor::Handle {
static REACTOR: std::sync::OnceLock<(Reactor, nagoya::reactor::Handle)> =
std::sync::OnceLock::new();
let (_, handle) = REACTOR.get_or_init(|| {
let reactor = Reactor::start().expect("inspector reactor could not start");
let handle = reactor.handle();
(reactor, handle)
});
handle
}
impl Descriptor {
pub fn socket_path(&self) -> PathBuf {
self.validated_socket_path.clone()
}
fn is_reachable(&self) -> bool {
let Some(directory) = self.validated_socket_path.parent() else {
return false;
};
let address = format!("unix://{}", self.validated_socket_path.display());
let Ok(socket) = crate::control_directory::validate_socket(directory, &address) else {
return false;
};
std::os::unix::net::UnixStream::connect(socket).is_ok()
}
pub fn warn_if_stale(&self) {
if !self.verified_reachable && !self.is_reachable() {
eprintln!(
"warning: descriptor {} names pid {}, but its control socket is unreachable",
self.path.display(),
self.descriptor.pid
);
}
}
}
pub fn discover(explicit: Option<&str>) -> Result<Descriptor> {
discover_with_paths(
explicit,
Path::new("target/blitz-control.json"),
&crate::control_directory::default_directory(),
)
}
fn discover_with_paths(
explicit: Option<&str>,
pinned: &Path,
root: &Path,
) -> Result<Descriptor> {
if let Some(path) = explicit {
let path = PathBuf::from(path);
if !path.exists() {
bail!(
"descriptor {} does not exist. ps-qa attaches to the descriptor you \
name and to no other; omit --descriptor to discover a running host.",
path.display()
);
}
return read_descriptor(&path);
}
match std::fs::symlink_metadata(pinned) {
Ok(_) => {
let result = read_descriptor(pinned).and_then(|mut descriptor| {
if !descriptor.is_reachable() {
bail!("control socket is unreachable");
}
descriptor.verified_reachable = true;
Ok(descriptor)
});
return result.wrap_err_with(|| {
format!(
"implicit pinned descriptor {} exists but is invalid or unreachable; fix or remove this pin before discovery",
pinned.display()
)
});
}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => {
return Err(error).wrap_err_with(|| {
format!("checking implicit pinned descriptor {}", pinned.display())
});
}
}
let mut found: Vec<(std::time::SystemTime, PathBuf)> =
if crate::control_directory::validate_directory(root).is_ok() {
std::fs::read_dir(root)
.into_iter()
.flatten()
.flatten()
.map(|entry| entry.path())
.filter(|path| path.extension().is_some_and(|ext| ext == "json"))
.filter_map(|path| {
let file = crate::control_directory::open_descriptor(&path).ok()?;
let modified = file.metadata().ok()?.modified().ok()?;
Some((modified, path))
})
.collect()
} else {
Vec::new()
};
found.sort();
for (_, path) in found.iter().rev() {
let Ok(mut descriptor) = read_descriptor(path) else {
continue;
};
if descriptor.is_reachable() {
descriptor.verified_reachable = true;
return Ok(descriptor);
}
}
bail!(
"no reachable inspector descriptor found; is a diagnostics build running?\n\
looked at target/blitz-control.json and {}. Pass --descriptor \
<path> to inspect a specific descriptor.",
root.display()
)
}
fn read_descriptor(path: &Path) -> Result<Descriptor> {
let mut file = crate::control_directory::open_descriptor(path)
.with_context(|| format!("opening private descriptor {}", path.display()))?;
let mut text = String::new();
file.read_to_string(&mut text)
.with_context(|| format!("reading descriptor {}", path.display()))?;
let raw: serde_json::Value = serde_json::from_str(&text)
.with_context(|| format!("parsing descriptor {}", path.display()))?;
let descriptor: DebugDescriptor = serde_json::from_value(raw.clone())
.with_context(|| format!("descriptor {} is not a DebugDescriptor", path.display()))?;
if descriptor.protocol_version != DEBUG_PROTOCOL_VERSION {
bail!(
"descriptor {} uses debug protocol {}, but this client speaks {}; \
use a client built for protocol {} (for ps-qa, build it from the \
blitz-control-protocol release or checkout that the host was built against)",
path.display(),
descriptor.protocol_version,
DEBUG_PROTOCOL_VERSION,
descriptor.protocol_version
);
}
let parent = path
.parent()
.filter(|parent| !parent.as_os_str().is_empty())
.unwrap_or_else(|| Path::new("."));
let directory = crate::control_directory::validate_directory(parent)
.with_context(|| format!("validating descriptor directory {}", parent.display()))?;
let validated_socket_path =
crate::control_directory::validate_socket(&directory, &descriptor.address)
.with_context(|| format!("validating descriptor socket {}", path.display()))?;
Ok(Descriptor {
path: path.to_path_buf(),
validated_socket_path,
descriptor,
raw,
verified_reachable: false,
})
}
pub struct Client {
stream: Box<dyn MessageStream>,
next_id: i64,
request_timeout: Duration,
terminal: Option<TerminalFailure>,
events: VecDeque<DebugEvent>,
notifications: VecDeque<serde_json::Value>,
lost_notifications: u64,
target_options: crate::TargetOptions,
target_context: Option<crate::TargetContext>,
}
#[derive(Clone, Debug)]
enum TerminalFailure {
RequestTimeout {
request_id: String,
phase: &'static str,
timeout: Duration,
},
Disconnected {
request_id: String,
phase: &'static str,
cause: String,
},
}
impl TerminalFailure {
fn report(&self) -> eyre::Report {
match self {
Self::RequestTimeout {
request_id,
phase,
timeout,
} => eyre::Report::new(InspectorRequestTimeout {
request_id: request_id.clone(),
phase,
timeout: *timeout,
}),
Self::Disconnected {
request_id,
phase,
cause,
} => eyre::Report::new(InspectorDisconnected {
request_id: request_id.clone(),
phase,
cause: cause.clone(),
}),
}
}
fn message(&self) -> String {
self.report().to_string()
}
fn is_timeout(&self) -> bool {
matches!(self, Self::RequestTimeout { .. })
}
}
#[derive(Clone, Debug)]
pub struct InspectorRequestTimeout {
pub request_id: String,
pub phase: &'static str,
pub timeout: Duration,
}
impl std::fmt::Display for InspectorRequestTimeout {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
formatter,
"InspectorRequestTimeout: request {} timed out during {} after {:?}",
self.request_id, self.phase, self.timeout
)
}
}
impl std::error::Error for InspectorRequestTimeout {}
#[derive(Clone, Debug)]
pub struct InspectorDisconnected {
pub request_id: String,
pub phase: &'static str,
pub cause: String,
}
impl std::fmt::Display for InspectorDisconnected {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
formatter,
"InspectorDisconnected: request {} failed during {}: {}",
self.request_id, self.phase, self.cause
)
}
}
impl std::error::Error for InspectorDisconnected {}
fn transport_disconnect_cause(error: &endpoint_libs::libs::ws::StreamError) -> String {
if matches!(error, endpoint_libs::libs::ws::StreamError::Closed) {
return "clean connection close".to_owned();
}
let mut source = Some(error as &dyn std::error::Error);
while let Some(cause) = source {
if let Some(io_error) = cause.downcast_ref::<std::io::Error>()
&& matches!(
io_error.kind(),
std::io::ErrorKind::UnexpectedEof
| std::io::ErrorKind::ConnectionReset
| std::io::ErrorKind::BrokenPipe
)
{
return format!("{:?}: {}", io_error.kind(), io_error);
}
source = cause.source();
}
error.to_string()
}
#[derive(Debug)]
struct InspectorResponseError {
code: String,
message: String,
}
impl std::fmt::Display for InspectorResponseError {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
formatter,
"inspector returned {}: {}",
self.code, self.message
)
}
}
impl std::error::Error for InspectorResponseError {}
pub fn is_unsupported(error: &eyre::Report) -> bool {
error
.downcast_ref::<InspectorResponseError>()
.is_some_and(|refusal| refusal.code == "unsupported")
}
pub fn is_pending(error: &eyre::Report) -> bool {
error
.downcast_ref::<InspectorResponseError>()
.is_some_and(|refusal| refusal.code == "pending")
}
pub fn safe_response_code(error: &eyre::Report) -> Option<&'static str> {
let code = error
.downcast_ref::<InspectorResponseError>()?
.code
.as_str();
Some(match code {
"notEditable" => "notEditable",
"unknownNode" => "unknownNode",
"documentUnavailable" => "documentUnavailable",
"unsupportedRequest" => "unsupportedRequest",
_ => "other",
})
}
impl Client {
pub fn select_target(&mut self, target: Option<crate::TargetSelector>) {
self.target_options = crate::TargetOptions {
target,
..Default::default()
};
self.target_context = None;
}
pub fn target_context(&self) -> Option<&crate::TargetContext> {
self.target_context.as_ref()
}
fn target_frame(&self, frame: WireMessage) -> Result<WireMessage> {
let mut value = decode_wire_value(frame).map_err(protocol_error)?;
if value["method"] != "tools/call" {
return Ok(WireMessage::Text(serde_json::to_string(&value)?.into()));
}
let tool = value["params"]["name"]
.as_str()
.unwrap_or_default()
.to_owned();
let arguments = &mut value["params"]["arguments"];
let object = arguments
.as_object_mut()
.ok_or_else(|| eyre!("tool arguments must be an object"))?;
if !object.contains_key("target")
&& object.get("allTargets") != Some(&serde_json::Value::Bool(true))
&& let Some(target) = &self.target_options.target
{
object.insert("target".into(), serde_json::to_value(target)?);
}
let options: crate::TargetOptions = serde_json::from_value(arguments.clone())?;
let command = if tool == crate::AGENT_CONTROL_TOOL {
serde_json::from_value(arguments.clone())
.ok()
.map(crate::TargetCommand::Agent)
} else if tool == crate::DIAGNOSTICS_TOOL {
serde_json::from_value(arguments.clone())
.ok()
.map(crate::TargetCommand::Diagnostics)
} else {
None
};
if options.target == self.target_options.target
&& !options.all_targets
&& let (Some(context), Some(command)) = (&self.target_context, command)
{
let request = crate::TargetRequest { options, command };
if (request.uses_nodes()
|| matches!(
request.command,
crate::TargetCommand::Agent(crate::AgentControlRequest::Act(_))
))
&& matches!(context.target_id, crate::TargetId::Tab(_))
{
let object = arguments.as_object_mut().expect("arguments object");
object
.entry("expectedGeneration")
.or_insert_with(|| context.generation.into());
object
.entry("expectedDocumentId")
.or_insert_with(|| context.document_id.into());
}
}
Ok(WireMessage::Text(serde_json::to_string(&value)?.into()))
}
fn queue_notification(&mut self, value: serde_json::Value) {
if value.get("method").is_none() || value.get("id").is_some() {
return;
}
if self.notifications.len() == MAX_QUEUED_EVENTS {
self.notifications.pop_front();
self.lost_notifications += 1;
}
self.notifications.push_back(value);
}
fn capture_target_context(&mut self, value: &serde_json::Value) {
let Some(context) = value.pointer("/result/structuredContent/context") else {
return;
};
let Ok(context) = serde_json::from_value::<crate::TargetContext>(context.clone()) else {
return;
};
let selected = self
.target_options
.target
.as_ref()
.map_or_else(crate::TargetId::chrome, crate::TargetSelector::id);
if context.target_id == selected {
self.target_context = Some(context);
}
}
fn queue_event(&mut self, event: DebugEvent) {
if self.events.len() == MAX_QUEUED_EVENTS {
self.events.pop_front();
}
self.events.push_back(event);
}
pub async fn connect(socket: &Path) -> Result<Self> {
const CONNECT_DEADLINE: Duration = Duration::from_millis(500);
const RETRY_DELAY: Duration = Duration::from_millis(20);
let started = Instant::now();
let stream = loop {
let addr = Addr::path(socket.as_os_str().as_bytes())
.map_err(|_| std::io::Error::other("socket path is not a valid unix address"))?;
match TcpStream::connect(addr, client_reactor()).await {
Ok(stream) => break stream,
Err(_) if started.elapsed() < CONNECT_DEADLINE => {
nagoya::sleep(RETRY_DELAY).await;
}
Err(error) => {
return Err(error)
.with_context(|| format!("connecting to {}", socket.display()));
}
}
};
Ok(Self {
stream: Box::new(TransportStream::new(framed_json_neutral(
NagoyaStream::new(stream),
))),
next_id: 0,
request_timeout: REQUEST_TIMEOUT,
terminal: None,
events: VecDeque::new(),
notifications: VecDeque::new(),
lost_notifications: 0,
target_options: crate::TargetOptions::default(),
target_context: None,
})
}
pub fn set_request_timeout(&mut self, request_timeout: Duration) {
self.request_timeout = request_timeout;
}
pub fn request_timeout(&self) -> Duration {
self.request_timeout
}
pub fn is_terminal(&self) -> bool {
self.terminal.is_some()
}
pub fn terminal_is_timeout(&self) -> bool {
self.terminal
.as_ref()
.is_some_and(TerminalFailure::is_timeout)
}
pub fn terminal_failure_message(&self) -> Option<String> {
self.terminal.as_ref().map(TerminalFailure::message)
}
fn ensure_available(&self) -> Result<()> {
match &self.terminal {
Some(failure) => Err(failure.report()),
None => Ok(()),
}
}
fn mark_timeout(&mut self, id: &JsonRpcId, phase: &'static str) -> eyre::Report {
let failure = TerminalFailure::RequestTimeout {
request_id: format!("{id:?}"),
phase,
timeout: self.request_timeout,
};
self.terminal = Some(failure.clone());
failure.report()
}
fn mark_disconnected(
&mut self,
id: &JsonRpcId,
phase: &'static str,
cause: String,
) -> eyre::Report {
let failure = TerminalFailure::Disconnected {
request_id: format!("{id:?}"),
phase,
cause,
};
self.terminal = Some(failure.clone());
failure.report()
}
fn next_id(&mut self) -> JsonRpcId {
self.next_id += 1;
JsonRpcId::Number(self.next_id)
}
async fn exchange(
&mut self,
request: WireMessage,
id: &JsonRpcId,
) -> Result<serde_json::Value> {
self.ensure_available()?;
let request = self.target_frame(request)?;
let deadline = Instant::now() + self.request_timeout;
let send_remaining = deadline.saturating_duration_since(Instant::now());
match timeout(send_remaining, self.stream.send(request)).await {
Err(_) => return Err(self.mark_timeout(id, "send")),
Ok(Err(error)) => {
let cause = transport_disconnect_cause(&error);
return Err(self.mark_disconnected(id, "send", cause));
}
Ok(Ok(())) => {}
}
loop {
let remaining = deadline.saturating_duration_since(Instant::now());
if remaining.is_zero() {
return Err(self.mark_timeout(id, "receive"));
}
let message = match timeout(remaining, self.stream.recv()).await {
Err(_) => return Err(self.mark_timeout(id, "receive")),
Ok(None) => {
return Err(self.mark_disconnected(id, "receive", "clean EOF".to_owned()));
}
Ok(Some(Err(error))) => {
let cause = transport_disconnect_cause(&error);
return Err(self.mark_disconnected(id, "receive", cause));
}
Ok(Some(Ok(message))) => message,
};
let value = decode_wire_value(message).map_err(protocol_error)?;
if peek_value_request_id(&value).as_ref() == Some(id) {
self.capture_target_context(&value);
return Ok(value);
}
self.queue_notification(value.clone());
if let Ok(event) = decode_diagnostics_event_value(value) {
self.queue_event(event);
}
}
}
pub async fn raw_request(
&mut self,
method: &str,
params: serde_json::Value,
) -> Result<serde_json::Value> {
let id = self.next_id();
let request = encode_rpc(JsonRpcMessage::Request(JsonRpcRequest::call(
id.clone(),
method,
params,
)))
.map_err(protocol_error)?;
self.exchange(request, &id).await
}
pub async fn initialize(&mut self) -> Result<serde_json::Value> {
self.raw_request(
"initialize",
serde_json::json!({"protocolVersion": MCP_PROTOCOL_VERSION}),
)
.await
}
pub async fn tools_list(&mut self) -> Result<serde_json::Value> {
self.raw_request("tools/list", serde_json::json!({})).await
}
pub async fn agent(&mut self, request: &AgentControlRequest) -> Result<Answer> {
let id = self.next_id();
let frame = encode_agent_request(id.clone(), request).map_err(protocol_error)?;
let value = self.exchange(frame, &id).await?;
Answer::new(value)
}
pub async fn diagnostics(&mut self, request: &DiagnosticsRequest) -> Result<Answer> {
let id = self.next_id();
let frame = encode_diagnostics_request(id.clone(), request).map_err(protocol_error)?;
let value = self.exchange(frame, &id).await?;
Answer::new(value)
}
pub async fn arm_paint_events(&mut self) -> Result<bool> {
self.events
.retain(|event| !matches!(event, DebugEvent::PaintCommitted { .. }));
match self
.diagnostics(&DiagnosticsRequest::Observe {
streams: vec![DebugStream::Paint],
})
.await
{
Ok(_) => Ok(true),
Err(error)
if error
.downcast_ref::<InspectorResponseError>()
.is_some_and(|error| error.code == "streamingUnavailable") =>
{
Ok(false)
}
Err(error) => Err(error),
}
}
pub async fn wait_for_paint(&mut self, within: Duration) -> Result<bool> {
self.ensure_available()?;
if let Some(index) = self
.events
.iter()
.position(|event| matches!(event, DebugEvent::PaintCommitted { .. }))
{
self.events.remove(index);
return Ok(true);
}
let deadline = Instant::now() + within;
loop {
let remaining = deadline.saturating_duration_since(Instant::now());
if remaining.is_zero() {
return Ok(false);
}
let id = JsonRpcId::Number(self.next_id);
let message = match timeout(remaining, self.stream.recv()).await {
Err(_) => return Ok(false),
Ok(None) => {
return Err(self.mark_disconnected(&id, "paint", "clean EOF".to_owned()));
}
Ok(Some(Err(error))) => {
let cause = transport_disconnect_cause(&error);
return Err(self.mark_disconnected(&id, "paint", cause));
}
Ok(Some(Ok(message))) => message,
};
let value = decode_wire_value(message).map_err(protocol_error)?;
self.queue_notification(value.clone());
match decode_diagnostics_event_value(value) {
Ok(DebugEvent::PaintCommitted { .. }) => return Ok(true),
Ok(event) => self.queue_event(event),
Err(_) => {}
}
}
}
pub async fn diagnostics_envelope(
&mut self,
request: &DiagnosticsRequest,
) -> Result<serde_json::Value> {
let id = self.next_id();
let frame = encode_diagnostics_request(id.clone(), request).map_err(protocol_error)?;
self.exchange(frame, &id).await
}
pub async fn agent_envelope(
&mut self,
request: &AgentControlRequest,
) -> Result<serde_json::Value> {
let id = self.next_id();
let frame = encode_agent_request(id.clone(), request).map_err(protocol_error)?;
self.exchange(frame, &id).await
}
pub async fn drain(&mut self, seconds: f64) -> Result<Vec<serde_json::Value>> {
self.ensure_available()?;
let deadline = Instant::now() + Duration::from_secs_f64(seconds);
let mut out: Vec<_> = self.notifications.drain(..).collect();
if self.lost_notifications > 0 {
out.insert(0, serde_json::json!({"method": crate::DIAGNOSTICS_EVENT_NOTIFICATION, "params": {
"event": "clientNotificationOverflow", "value": {"dropped": std::mem::take(&mut self.lost_notifications)}
}}));
}
loop {
let remaining = deadline.saturating_duration_since(Instant::now());
if remaining.is_zero() {
return Ok(out);
}
match timeout(remaining, self.stream.recv()).await {
Err(_) => return Ok(out),
Ok(None) => {
let id = JsonRpcId::Number(self.next_id);
return Err(self.mark_disconnected(&id, "drain", "clean EOF".to_owned()));
}
Ok(Some(Ok(message))) => {
out.push(decode_wire_value(message).map_err(protocol_error)?)
}
Ok(Some(Err(error))) => {
let id = JsonRpcId::Number(self.next_id);
let cause = transport_disconnect_cause(&error);
return Err(self.mark_disconnected(&id, "drain", cause));
}
}
}
}
}
pub async fn inspect(client: &mut Client) -> Result<(AgentSnapshot, f64)> {
inspect_from(client, None).await
}
pub async fn inspect_subtree(client: &mut Client, root: u64) -> Result<(AgentSnapshot, f64)> {
inspect_from(client, Some(root)).await
}
async fn inspect_from(client: &mut Client, root: Option<u64>) -> Result<(AgentSnapshot, f64)> {
let started = Instant::now();
let answer = client
.agent(&AgentControlRequest::Inspect {
root,
max_depth: 40,
})
.await?;
let elapsed = started.elapsed().as_secs_f64() * 1000.0;
match answer.response {
DebugResponse::AgentSnapshot(snapshot) => Ok((snapshot, elapsed)),
other => bail!("asked for a semantic snapshot, got {other:?}"),
}
}
pub struct Answer {
pub response: DebugResponse,
}
impl Answer {
fn new(value: serde_json::Value) -> Result<Self> {
let (_, response) = decode_response_value(value).map_err(protocol_error)?;
let response = match response {
DebugResponse::Targeted(reply) => *reply.response,
response => response,
};
if let DebugResponse::Error(error) = &response {
return Err(eyre::Report::new(InspectorResponseError {
code: error.code.clone(),
message: error.message.clone(),
}));
}
Ok(Self { response })
}
}
fn protocol_error(error: DebugProtocolError) -> eyre::Report {
eyre!("{error}")
}
#[cfg(test)]
mod tests {
use super::*;
use crate::{JsonRpcResponse, encode_diagnostics_event};
use nagoya::reactor::TcpListener;
use std::os::unix::ffi::OsStrExt;
use std::os::unix::fs::{MetadataExt, PermissionsExt, symlink};
use std::os::unix::net::UnixListener as StdUnixListener;
use std::sync::atomic::{AtomicUsize, Ordering};
static PIN_FIXTURE_ID: AtomicUsize = AtomicUsize::new(0);
const PIN_FIXTURE_ROOT_ENV: &str = "PS_OBSERVABILITY_PIN_FIXTURE_ROOT";
const MACOS_SUN_PATH_CAPACITY: usize = 104;
fn default_fixture_root() -> PathBuf {
let base = if cfg!(target_os = "macos") {
PathBuf::from("/tmp")
} else {
std::env::temp_dir()
};
let directory = base.join(format!("pso-{}", rustix::process::geteuid().as_raw()));
match crate::guarded_writer::create_private_dir(&directory) {
Ok(()) => {}
Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {}
Err(error) => panic!("create default fixture root {}: {error}", directory.display()),
}
directory
}
fn fixture_root() -> PathBuf {
let configured = std::env::var_os(PIN_FIXTURE_ROOT_ENV)
.map(PathBuf::from)
.unwrap_or_else(default_fixture_root);
assert!(configured.is_absolute(), "{PIN_FIXTURE_ROOT_ENV} must be an absolute path: {}", configured.display());
let before = std::fs::symlink_metadata(&configured).unwrap_or_else(|error| {
panic!("{PIN_FIXTURE_ROOT_ENV} must name an existing directory ({}): {error}", configured.display())
});
validate_fixture_root_metadata(&configured, &before);
let canonical = configured.canonicalize().unwrap_or_else(|error| {
panic!("cannot resolve {PIN_FIXTURE_ROOT_ENV} directory {}: {error}", configured.display())
});
let after = std::fs::symlink_metadata(&canonical).unwrap_or_else(|error| {
panic!("cannot recheck {PIN_FIXTURE_ROOT_ENV} directory {}: {error}", canonical.display())
});
validate_fixture_root_metadata(&canonical, &after);
assert!(before.dev() == after.dev() && before.ino() == after.ino(), "{PIN_FIXTURE_ROOT_ENV} changed while being validated: {}", configured.display());
canonical
}
fn validate_fixture_root_metadata(path: &Path, metadata: &std::fs::Metadata) {
assert!(!metadata.file_type().is_symlink() && metadata.is_dir(), "{PIN_FIXTURE_ROOT_ENV} must be a real directory, not a symlink: {}", path.display());
assert_eq!(metadata.uid(), rustix::process::geteuid().as_raw(), "{PIN_FIXTURE_ROOT_ENV} must be owned by the current user: {}", path.display());
assert!(metadata.mode() & 0o300 == 0o300, "{PIN_FIXTURE_ROOT_ENV} must be writable and searchable by its owner: {}", path.display());
}
struct PinDiscoveryFixture {
root: PathBuf,
pinned: PathBuf,
pin_directory: PathBuf,
runtime: PathBuf,
listeners: Vec<StdUnixListener>,
}
impl PinDiscoveryFixture {
fn new() -> Self {
let base = fixture_root();
let root = loop {
let sequence = PIN_FIXTURE_ID.fetch_add(1, Ordering::Relaxed);
let nonce = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.expect("system clock is after the epoch")
.as_nanos();
let candidate = base.join(format!("pin-{:x}-{nonce:x}-{sequence:x}", std::process::id()));
match crate::guarded_writer::create_private_dir(&candidate) {
Ok(()) => break candidate,
Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
Err(error) => panic!("create unique private fixture child {} under {}: {error}", candidate.display(), base.display()),
}
};
let pin_directory = root.join("pin");
let runtime = root.join("run");
let setup = (|| -> Result<()> {
crate::guarded_writer::create_private_dir(&pin_directory)?;
crate::guarded_writer::create_private_dir(&runtime)?;
Ok(())
})();
if let Err(error) = setup {
let _ = std::fs::remove_dir_all(&root);
panic!("create fixture directories under {}: {error}", root.display());
}
let pinned = pin_directory.join("blitz-control.json");
Self {
root,
pinned,
pin_directory,
runtime,
listeners: Vec::new(),
}
}
fn descriptor(&mut self, directory: &Path, file: &str, socket_name: &str) -> PathBuf {
let socket = directory.join(socket_name);
assert_socket_path_length(&socket);
let listener = StdUnixListener::bind(&socket).expect("bind private fixture socket");
std::fs::set_permissions(&socket, std::fs::Permissions::from_mode(0o600))
.expect("restrict fixture socket mode");
self.listeners.push(listener);
let descriptor = directory.join(file);
crate::guarded_writer::write_file(
&descriptor,
serde_json::json!({
"protocolVersion": DEBUG_PROTOCOL_VERSION,
"pid": 1,
"instanceId": file,
"address": format!("unix://{}", socket.display()),
"renderer": "fixture",
"rendererRevision": "test"
})
.to_string()
.as_bytes(),
)
.expect("write valid fixture descriptor");
descriptor
}
fn fallback(&mut self) -> PathBuf {
self.descriptor(&self.runtime.clone(), "fallback.json", "f.sock")
}
fn prove_fallback_is_discoverable(&self, fallback: &Path) {
let selected = discover_fixture(self).expect("fallback is discoverable before pin");
assert_eq!(selected.path, fallback);
self.drain_listener("f.sock");
}
fn set_modified(path: &Path, seconds: u64) -> std::time::SystemTime {
let modified = std::time::UNIX_EPOCH + Duration::from_secs(seconds);
let file = std::fs::File::open(path).expect("open fixture descriptor for timestamps");
file.set_times(
std::fs::FileTimes::new().set_modified(modified),
)
.expect("set fixture descriptor timestamp");
std::fs::metadata(path)
.expect("stat timestamped fixture descriptor")
.modified()
.expect("read fixture descriptor timestamp")
}
fn drain_listener(&self, socket_name: &str) {
let path = self.runtime.join(socket_name);
if let Some(listener) = self
.listeners
.iter()
.find(|listener| {
listener
.local_addr()
.ok()
.and_then(|addr| addr.as_pathname().map(Path::to_path_buf))
.as_deref()
== Some(path.as_path())
})
{
listener.set_nonblocking(true).expect("nonblocking fixture listener");
loop {
match listener.accept() {
Ok((stream, _)) => drop(stream),
Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => break,
Err(error) => panic!("drain fallback listener: {error}"),
}
}
}
}
fn assert_no_fallback_connection(&self) {
let path = self.runtime.join("f.sock");
let listener = self
.listeners
.iter()
.find(|listener| {
listener
.local_addr()
.ok()
.and_then(|addr| addr.as_pathname().map(Path::to_path_buf))
.as_deref()
== Some(path.as_path())
})
.expect("fallback listener");
listener.set_nonblocking(true).expect("nonblocking fallback listener");
match listener.accept() {
Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {}
Ok((stream, _)) => {
drop(stream);
panic!("rejected pin connected to fallback host");
}
Err(error) => panic!("check fallback listener: {error}"),
}
}
}
impl Drop for PinDiscoveryFixture {
fn drop(&mut self) {
self.listeners.clear();
let _ = std::fs::remove_dir_all(&self.root);
}
}
fn discover_fixture(fixture: &PinDiscoveryFixture) -> Result<Descriptor> {
discover_with_paths(None, &fixture.pinned, &fixture.runtime)
}
#[test]
fn pinned_discovery_absent_pin_uses_reachable_fallback() {
let mut fixture = PinDiscoveryFixture::new();
let fallback = fixture.fallback();
let selected = discover_fixture(&fixture).expect("fallback is discoverable");
assert_eq!(selected.path, fallback);
fixture.drain_listener("f.sock");
}
#[test]
fn pinned_discovery_absent_pin_keeps_newest_reachable_selection() {
let mut fixture = PinDiscoveryFixture::new();
let oldest = fixture.descriptor(&fixture.runtime.clone(), "older.json", "o.sock");
let newest = fixture.descriptor(&fixture.runtime.clone(), "newest.json", "n.sock");
let unreachable = fixture.descriptor(&fixture.runtime.clone(), "latest.json", "x.sock");
let latest_socket = fixture.runtime.join("x.sock");
drop(fixture.listeners.pop().expect("latest listener"));
assert!(latest_socket.exists(), "closed socket path remains for validation");
let oldest_time = PinDiscoveryFixture::set_modified(&oldest, 1_700_000_000);
let newest_time = PinDiscoveryFixture::set_modified(&newest, 1_700_000_010);
let unreachable_time = PinDiscoveryFixture::set_modified(&unreachable, 1_700_000_020);
assert!(oldest_time < newest_time);
assert!(newest_time < unreachable_time);
let selected = discover_fixture(&fixture).expect("newest reachable descriptor selected");
assert_eq!(selected.path, newest);
fixture.drain_listener("n.sock");
}
#[test]
fn pinned_discovery_rejects_malformed_pin_without_connecting_fallback() {
let mut fixture = PinDiscoveryFixture::new();
let fallback = fixture.fallback();
fixture.prove_fallback_is_discoverable(&fallback);
crate::guarded_writer::write_file(&fixture.pinned, b"{").expect("write malformed pin");
let error = discover_fixture(&fixture).expect_err("invalid existing pin must fail");
assert!(error.to_string().contains(fixture.pinned.to_str().unwrap()));
fixture.assert_no_fallback_connection();
}
#[test]
fn pinned_discovery_rejects_insecure_parent_without_connecting_fallback() {
let mut fixture = PinDiscoveryFixture::new();
let fallback = fixture.fallback();
fixture.prove_fallback_is_discoverable(&fallback);
fixture.descriptor(
&fixture.pin_directory.clone(),
"blitz-control.json",
"p.sock",
);
std::fs::set_permissions(&fixture.pin_directory, std::fs::Permissions::from_mode(0o755))
.expect("make pin parent insecure");
let error = discover_fixture(&fixture).expect_err("insecure pin parent must fail");
let cause = format!("{error:#}");
assert!(cause.contains(fixture.pinned.to_str().unwrap()));
assert!(
cause.contains("validating descriptor directory"),
"insecure-parent case failed for an unexpected reason: {cause}"
);
fixture.assert_no_fallback_connection();
}
#[test]
fn pinned_discovery_rejects_socket_outside_pin_parent_without_fallback() {
let mut fixture = PinDiscoveryFixture::new();
let fallback = fixture.fallback();
fixture.prove_fallback_is_discoverable(&fallback);
let outside = fixture.runtime.join("f.sock");
crate::guarded_writer::write_file(
&fixture.pinned,
serde_json::json!({
"protocolVersion": DEBUG_PROTOCOL_VERSION,
"pid": 1,
"instanceId": "outside",
"address": format!("unix://{}", outside.display()),
"renderer": "fixture",
"rendererRevision": "test"
})
.to_string()
.as_bytes(),
)
.expect("write outside-socket pin");
let error = discover_fixture(&fixture).expect_err("socket outside pin parent must fail");
assert!(error.to_string().contains(fixture.pinned.to_str().unwrap()));
fixture.assert_no_fallback_connection();
}
#[test]
fn pinned_discovery_rejects_unreachable_and_dangling_pins_without_fallback() {
let mut fixture = PinDiscoveryFixture::new();
let fallback = fixture.fallback();
fixture.prove_fallback_is_discoverable(&fallback);
let stale_socket = fixture.pin_directory.join("s.sock");
assert_socket_path_length(&stale_socket);
let stale_listener = StdUnixListener::bind(&stale_socket).expect("bind stale pin socket");
std::fs::set_permissions(&stale_socket, std::fs::Permissions::from_mode(0o600))
.expect("restrict stale socket mode");
drop(stale_listener);
crate::guarded_writer::write_file(
&fixture.pinned,
serde_json::json!({
"protocolVersion": DEBUG_PROTOCOL_VERSION,
"pid": 1,
"instanceId": "stale",
"address": format!("unix://{}", stale_socket.display()),
"renderer": "fixture",
"rendererRevision": "test"
})
.to_string()
.as_bytes(),
)
.expect("write stale pin");
let error = discover_fixture(&fixture).expect_err("unreachable pin must fail");
assert!(error.to_string().contains(fixture.pinned.to_str().unwrap()));
fixture.assert_no_fallback_connection();
std::fs::remove_file(&fixture.pinned).expect("remove stale pin");
symlink(fixture.pin_directory.join("missing.json"), &fixture.pinned)
.expect("create dangling pin symlink");
let error = discover_fixture(&fixture).expect_err("dangling pin must fail");
assert!(error.to_string().contains(fixture.pinned.to_str().unwrap()));
fixture.assert_no_fallback_connection();
}
#[test]
fn pinned_discovery_valid_pin_wins_and_explicit_path_precedes_invalid_pin() {
let mut fixture = PinDiscoveryFixture::new();
let fallback = fixture.fallback();
let pinned = fixture.descriptor(&fixture.pin_directory.clone(), "blitz-control.json", "p.sock");
let selected = discover_fixture(&fixture).expect("reachable pin is authoritative");
assert_eq!(selected.path, pinned);
assert!(selected.verified_reachable);
fixture.assert_no_fallback_connection();
std::fs::remove_file(&fixture.pinned).expect("remove pin file");
crate::guarded_writer::write_file(&fixture.pinned, b"invalid").expect("write bad pin");
let explicit = discover_with_paths(
Some(fallback.to_str().unwrap()),
&fixture.pinned,
&fixture.runtime,
)
.expect("explicit descriptor retains precedence");
assert_eq!(explicit.path, fallback);
assert!(!explicit.verified_reachable);
fixture.assert_no_fallback_connection();
}
#[test]
fn pinned_discovery_explicit_closed_socket_remains_uncached() {
let mut fixture = PinDiscoveryFixture::new();
let explicit = fixture.descriptor(&fixture.pin_directory.clone(), "explicit.json", "e.sock");
drop(fixture.listeners.pop().expect("explicit listener"));
assert!(fixture.pin_directory.join("e.sock").exists());
let selected = discover_with_paths(
Some(explicit.to_str().unwrap()),
&fixture.pinned,
&fixture.runtime,
)
.expect("explicit descriptor read does not add a reachability probe");
assert_eq!(selected.path, explicit);
assert!(!selected.verified_reachable);
assert!(!selected.is_reachable());
}
fn assert_socket_path_length(path: &Path) {
let length = path.as_os_str().as_bytes().len();
assert!(
length < MACOS_SUN_PATH_CAPACITY,
"Unix socket path is {length} bytes; expected fewer than {MACOS_SUN_PATH_CAPACITY}: {}",
path.display()
);
}
#[test]
fn pinned_discovery_empty_runtime_reports_no_host() {
let fixture = PinDiscoveryFixture::new();
let error = discover_fixture(&fixture).expect_err("empty runtime has no host");
assert!(error.to_string().contains("no reachable inspector descriptor found"));
}
#[test]
fn connect_retries_startup_and_exchange_preserves_events() {
nagoya::block_on(async {
let socket = std::env::temp_dir().join(format!(
"ps-qa-transport-{}-{}.sock",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.expect("system clock is after the epoch")
.as_nanos()
));
let server_socket = socket.clone();
let server = async move {
nagoya::sleep(Duration::from_millis(40)).await;
let addr = Addr::path(server_socket.as_os_str().as_bytes()).expect("socket path");
let listener = TcpListener::bind(addr, client_reactor()).expect("bind test socket");
let (stream, _) = listener.accept().await.expect("accept test client");
let mut stream =
TransportStream::new(framed_json_neutral(NagoyaStream::new(stream)));
let _request = stream
.recv()
.await
.expect("client keeps connection open")
.expect("read initialize request");
stream
.send(
encode_diagnostics_event(&DebugEvent::PaintCommitted { revision: 7 })
.expect("encode paint event"),
)
.await
.expect("send paint event");
stream
.send(
encode_rpc(JsonRpcMessage::Response(JsonRpcResponse::result(
Some(JsonRpcId::Number(1)),
serde_json::json!({"protocolVersion": MCP_PROTOCOL_VERSION}),
)))
.expect("encode initialize response"),
)
.await
.expect("send initialize response");
};
let client_socket = socket.clone();
let client = async move {
let mut client = Client::connect(&client_socket)
.await
.expect("client retries until socket is bound");
client.initialize().await.expect("initialize completes");
assert!(
client
.wait_for_paint(Duration::ZERO)
.await
.expect("queued paint remains readable"),
"an event arriving before the response must not steal the response or be discarded"
);
};
nagoya::timeout(
Duration::from_secs(2),
futures::future::join(server, client),
)
.await
.expect("transport fixture watchdog");
let _ = std::fs::remove_file(socket);
});
}
#[test]
fn notifications_do_not_renew_the_request_deadline() {
nagoya::block_on(async {
let socket = std::env::temp_dir().join(format!(
"ps-qa-notification-timeout-{}-{}.sock",
std::process::id(),
Instant::now().elapsed().as_nanos()
));
let server_socket = socket.clone();
let server = async move {
let addr = Addr::path(server_socket.as_os_str().as_bytes()).expect("socket path");
let listener = TcpListener::bind(addr, client_reactor()).expect("bind fixture");
let (stream, _) = listener.accept().await.expect("accept client");
let mut stream =
TransportStream::new(framed_json_neutral(NagoyaStream::new(stream)));
let _request = stream
.recv()
.await
.expect("client stays connected")
.expect("request is readable");
for _ in 0..40 {
let event =
encode_diagnostics_event(&DebugEvent::PaintCommitted { revision: 1 })
.expect("encode notification");
if stream.send(event).await.is_err() {
break;
}
nagoya::sleep(Duration::from_millis(5)).await;
}
};
let client_socket = socket.clone();
let client = async move {
let mut client = Client::connect(&client_socket)
.await
.expect("connect fixture");
client.set_request_timeout(Duration::from_millis(100));
let started = Instant::now();
let error = client
.initialize()
.await
.expect_err("notifications do not answer initialize");
assert!(
error.downcast_ref::<InspectorRequestTimeout>().is_some(),
"expected typed request timeout, got {error}"
);
assert!(started.elapsed() < Duration::from_millis(250));
let started = Instant::now();
let error = client
.tools_list()
.await
.expect_err("a timed out stream is terminal");
assert!(
error.downcast_ref::<InspectorRequestTimeout>().is_some(),
"expected the stored terminal timeout, got {error}"
);
assert!(started.elapsed() < Duration::from_millis(25));
};
nagoya::timeout(
Duration::from_secs(2),
futures::future::join(server, client),
)
.await
.expect("notification fixture watchdog");
let _ = std::fs::remove_file(socket);
});
}
#[test]
fn transport_disconnect_classifies_typed_io_sources() {
for (kind, label) in [
(std::io::ErrorKind::UnexpectedEof, "UnexpectedEof"),
(std::io::ErrorKind::ConnectionReset, "ConnectionReset"),
(std::io::ErrorKind::BrokenPipe, "BrokenPipe"),
] {
let error = endpoint_libs::libs::ws::StreamError::Other(eyre::Report::new(
std::io::Error::from(kind),
));
assert!(
transport_disconnect_cause(&error).contains(label),
"typed I/O source {kind:?} was not preserved"
);
}
}
#[test]
fn descriptor_protocol_mismatch_is_rejected_before_connecting() {
let directory = std::env::temp_dir().join(format!(
"ps-qa-descriptor-version-{}-{}",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.expect("system clock is after the epoch")
.as_nanos()
));
crate::guarded_writer::create_private_dir(&directory)
.expect("scratch directory is created");
let path = directory.join("fixture.json");
crate::guarded_writer::write_file(
&path,
serde_json::json!({
"protocolVersion": DEBUG_PROTOCOL_VERSION + 1,
"pid": 1,
"instanceId": "fixture",
"address": "unix:///tmp/fixture.sock",
"renderer": "fixture",
"rendererRevision": "test"
})
.to_string()
.as_bytes(),
)
.expect("write descriptor fixture");
let error = read_descriptor(&path).expect_err("newer protocol must not be guessed");
assert!(
error.to_string().contains("this client speaks"),
"unexpected error: {error}"
);
let _ = std::fs::remove_file(path);
let _ = std::fs::remove_dir(directory);
}
}