feat(headless): expose negotiated native log observation

This commit is contained in:
2026-11-10 21:57:34 +00:00
parent 09d8778f04
commit c649e02816
17 changed files with 1830 additions and 11 deletions
@@ -106,6 +106,7 @@ fn read_commands<R: BufRead, W: Write>(
) -> io::Result<()> {
let mut initialized = false;
let mut memcard = false;
let mut log_read = false;
loop {
let bytes = match read_line(&mut input, limits.max_command_bytes)? {
Line::Eof => break,
@@ -144,6 +145,16 @@ fn read_commands<R: BufRead, W: Write>(
continue;
}
};
if matches!(command, Command::GetLogs(_)) && !log_read {
output.reply(
Some(&id),
Err(WireError::new(
"unsupported_capability",
"negotiate minor 1.2 and require log_read first",
)),
)?;
continue;
}
if command.needs_memcard() && !memcard {
output.reply(
Some(&id),
@@ -180,12 +191,18 @@ fn read_commands<R: BufRead, W: Write>(
&& params.required_capabilities.iter().any(|c| c == "memcard")
{
Err(WireError::new("incompatible_version", "memcard requires protocol minor >= 1"))
} else if params.protocol_version.minor < 2
&& params.required_capabilities.iter().any(|c| c == "log_read")
{
Err(WireError::new("incompatible_version", "log_read requires protocol minor >= 2"))
} else {
initialized = true;
memcard = params.protocol_version.minor >= 1
&& params.required_capabilities.iter().any(|c| c == "memcard");
log_read = params.protocol_version.minor >= 2
&& params.required_capabilities.iter().any(|c| c == "log_read");
Ok(
json!({"protocolVersion":{"major":1,"minor":params.protocol_version.minor.min(1)},"capabilities":CAPABILITIES}),
json!({"protocolVersion":{"major":1,"minor":params.protocol_version.minor.min(2)},"capabilities":CAPABILITIES}),
)
};
output.reply(Some(&id), result)?;
@@ -281,6 +298,7 @@ fn execute<W: Write>(
}
Command::GetState => Ok(wire::state(host.get_state())),
Command::GetFault => Ok(host.get_fault().as_ref().map(wire::fault).unwrap_or(Value::Null)),
Command::GetLogs(params) => wire::logs(host, params, &output.session),
Command::Capture => host.capture_frame().map_err(wire::host_error).and_then(wire::capture),
Command::Advance(p) => {
let mut result = json!({"requested":p.frames,"completed":0,"stop":"completed"});
@@ -339,7 +357,7 @@ pub fn serve<R: BufRead + Send + 'static, W: Write + Send + 'static>(
let output =
Arc::new(Output { writer: Mutex::new(writer), session, limit: limits.max_response_bytes });
output.send(
json!({"type":"hello","sessionId":output.session,"protocolVersion":{"major":1,"minor":1},
json!({"type":"hello","sessionId":output.session,"protocolVersion":{"major":1,"minor":2},
"runtimeVersion":runtime_version,"capabilities":CAPABILITIES,"limits":limits}),
)?;
let control = Arc::new(Mutex::new(Control::default()));
@@ -476,7 +494,7 @@ mod tests {
"../../../../../devtools/headless-protocol/requests.json"
))
.unwrap();
assert_eq!(requests.len(), 21);
assert!(!requests.is_empty());
for request in requests {
wire::parse(serde_json::from_value(request).unwrap()).unwrap();
}
@@ -22,6 +22,7 @@ pub const CAPABILITIES: &[&str] = &[
"capture",
"get_state",
"get_fault",
"log_read",
"cancel",
"shutdown",
"memcard",
@@ -139,6 +140,19 @@ pub(super) struct Advance {
pub frames: u64,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct GetLogs {
// Explicit deserializer makes the nullable field required, including on first read.
#[serde(deserialize_with = "nullable_cursor")]
pub after_sequence: Option<u64>,
pub limit: u16,
}
fn nullable_cursor<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Option<u64>, D::Error> {
Option::<u64>::deserialize(d)
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct Cancel {
@@ -203,6 +217,7 @@ pub(super) enum Command {
Capture,
GetState,
GetFault,
GetLogs(GetLogs),
Cancel(Cancel),
Shutdown(Teardown),
}
@@ -247,6 +262,13 @@ pub(super) fn parse(req: Request) -> Result<(String, Command), WireError> {
Command::Boot(p)
}
"advance" => Command::Advance(params(req.params)?),
"get_logs" => {
let p: GetLogs = params(req.params)?;
if !(1..=1024).contains(&p.limit) {
return Err(WireError::new("invalid_params", "limit must be 1..1024"));
}
Command::GetLogs(p)
}
"reset" => Command::Reset(params(req.params)?),
"shutdown" => Command::Shutdown(params(req.params)?),
"memcard_mount" => {
@@ -357,6 +379,48 @@ pub(super) fn state(s: HostState) -> Value {
"status":status_name(s.status)})
}
pub(super) fn logs(
host: &crate::HeadlessHost,
params: GetLogs,
session: &str,
) -> Result<Value, WireError> {
let (events, oldest, newest) =
host.log_snapshot(params.after_sequence, usize::from(params.limit));
if params.after_sequence.is_some_and(|after| newest.is_none_or(|newest| after > newest)) {
return Err(WireError::new("invalid_cursor", "afterSequence exceeds the log stream"));
}
let gap = oldest.is_some_and(|oldest| match params.after_sequence {
None => oldest > 0,
Some(after) => after.checked_add(1).is_some_and(|next| next < oldest),
});
let next = events.last().map(|event| event.seq).or(params.after_sequence);
Ok(
json!({"sessionId":session,"logEpoch":0,"events":events.iter().map(log_event).collect::<Vec<_>>(),
"oldestSequence":oldest,"newestSequence":newest,"nextAfterSequence":next,
"gap":gap,"overflow":oldest.is_some_and(|oldest| oldest > 0)}),
)
}
fn log_event(event: &prometeu_hal::log::LogEvent) -> Value {
use prometeu_hal::log::{LogLevel, LogSource};
let level = match event.level {
LogLevel::Trace => "trace",
LogLevel::Debug => "debug",
LogLevel::Info => "info",
LogLevel::Warn => "warn",
LogLevel::Error => "error",
};
let (source, app_id) = match event.source {
LogSource::Pos => ("pos", None),
LogSource::Hub => ("hub", None),
LogSource::Vm => ("vm", None),
LogSource::Fs => ("fs", None),
LogSource::App { app_id } => ("app", Some(app_id)),
};
json!({"sequence":event.seq,"frame":event.frame,"timestampMs":event.ts_ms,
"level":level,"source":source,"appId":app_id,"tag":event.tag,"message":event.msg})
}
pub(super) fn fault(report: &CrashReport) -> Value {
let mut result = json!({"kind":report.kind(),"pc":report.pc(),"summary":report.summary()});
match report {
@@ -402,3 +466,105 @@ pub(super) fn capture(c: CapturedFrame) -> Result<Value, WireError> {
"width":width,"height":height,"stridePixels":frame.stride_pixels,"pixelFormat":"RGBA8888",
"logicalFrameIndex":c.logical_frame_index,"frameId":frame.frame_id.get()}))
}
#[cfg(test)]
mod log_tests {
use super::*;
use prometeu_hal::log::{LogEvent, LogLevel, LogSource};
#[test]
fn oversized_native_event_is_an_error_without_partial_result() {
let event = LogEvent {
seq: 0,
frame: 0,
ts_ms: 0,
level: LogLevel::Error,
source: LogSource::Vm,
tag: 0,
msg: "x".repeat(8192),
};
let output = super::super::Output {
writer: std::sync::Mutex::new(Vec::new()),
session: "session".into(),
limit: 4096,
};
output.reply(Some("logs"), Ok(json!({"events":[log_event(&event)]}))).unwrap();
let bytes = output.writer.into_inner().unwrap();
assert!(bytes.len() <= 4097);
let response: Value = serde_json::from_slice(&bytes).unwrap();
assert_eq!(response["error"]["code"], "response_too_large");
assert_eq!(response["requestId"], "logs");
assert!(response.get("result").is_none());
}
#[test]
fn native_records_preserve_unsigned_maxima_and_typed_sources() {
for (source, name, app_id) in [
(LogSource::Pos, "pos", None),
(LogSource::Hub, "hub", None),
(LogSource::Vm, "vm", None),
(LogSource::Fs, "fs", None),
(LogSource::App { app_id: u32::MAX }, "app", Some(u32::MAX)),
] {
for (level, level_name) in [
(LogLevel::Trace, "trace"),
(LogLevel::Debug, "debug"),
(LogLevel::Info, "info"),
(LogLevel::Warn, "warn"),
(LogLevel::Error, "error"),
] {
let event = LogEvent {
seq: u64::MAX,
frame: u64::MAX,
ts_ms: u64::MAX,
level,
source,
tag: u16::MAX,
msg: "complete native message".into(),
};
let encoded = log_event(&event);
let decoded: Value =
serde_json::from_slice(&serde_json::to_vec(&encoded).unwrap()).unwrap();
for key in ["sequence", "frame", "timestampMs"] {
assert_eq!(decoded[key].as_u64(), Some(u64::MAX));
}
assert_eq!(decoded["level"], level_name);
assert_eq!(decoded["source"], name);
assert_eq!(decoded["appId"], json!(app_id));
assert_eq!(decoded["tag"], u16::MAX);
assert_eq!(decoded["message"], event.msg);
}
}
}
#[test]
fn required_nullable_cursor_and_limit_reject_malformed_values() {
for value in [
json!({"limit":1}),
json!({"afterSequence":null}),
json!({"afterSequence":-1,"limit":1}),
json!({"afterSequence":1.5,"limit":1}),
json!({"afterSequence":"0","limit":1}),
json!({"afterSequence":null,"limit":0}),
json!({"afterSequence":null,"limit":1025}),
json!({"afterSequence":null,"limit":1,"filter":"app"}),
] {
assert!(
parse(Request {
request_id: "logs".into(),
command: "get_logs".into(),
params: value
})
.is_err()
);
}
assert!(
parse(Request {
request_id: "logs".into(),
command: "get_logs".into(),
params: json!({"afterSequence":u64::MAX,"limit":1024})
})
.is_ok()
);
}
}
@@ -178,6 +178,15 @@ impl HeadlessHost {
self.controlled_wall_clock.as_deref()
}
/// Observe native log history without advancing, draining or changing lifecycle.
pub fn log_snapshot(
&self,
after: Option<u64>,
limit: usize,
) -> (Vec<prometeu_hal::log::LogEvent>, Option<u64>, Option<u64>) {
self.firmware.os.log_snapshot(after, limit)
}
/// Load `path` and tick until the firmware is in `GameRunning`.
///
/// The transition into `GameRunning` is the last tick. The first game