use std::collections::BTreeSet;
use std::time::Duration;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use super::{DebuggerArtifact, DebuggerManager, DebuggerReplay, now_ms};
const EVIDENCE_TRACE_SCHEMA_VERSION: u32 = 1;
const MAX_TRACE_ITEMS: usize = 20_000;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum DebuggerEvidenceTraceStatus {
Recording,
Complete,
Imported,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct DebuggerTraceCursor {
pub trace_id: String,
pub kind: String,
pub item_id: String,
pub at: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct DebuggerEvidenceTrace {
pub id: String,
pub name: String,
pub session_id: String,
pub execution_id: Option<String>,
pub recording_id: Option<String>,
pub status: DebuggerEvidenceTraceStatus,
pub cursor: Option<DebuggerTraceCursor>,
pub started_at: u64,
pub stopped_at: Option<u64>,
pub updated_at: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct DebuggerTraceItem {
pub kind: String,
pub id: String,
pub at: u64,
pub label: String,
pub details: Value,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct DebuggerEvidenceTraceView {
pub trace: DebuggerEvidenceTrace,
pub items: Vec<DebuggerTraceItem>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct DebuggerTraceReplayResult {
pub trace: DebuggerEvidenceTrace,
pub cursor: Option<DebuggerTraceCursor>,
pub browser_replay: Option<DebuggerReplay>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct DebuggerTraceExport {
pub trace_id: String,
pub artifact: DebuggerArtifact,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct DebuggerTraceImport {
pub trace: DebuggerEvidenceTrace,
pub artifact: DebuggerArtifact,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct DebuggerTraceGc {
pub kept: usize,
pub removed: Vec<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
struct DebuggerTraceBundle {
schema_version: u32,
trace: DebuggerEvidenceTrace,
items: Vec<DebuggerTraceItem>,
}
impl DebuggerManager {
pub async fn evidence_trace_start(
&self,
session_id: &str,
name: String,
) -> Result<DebuggerEvidenceTrace, String> {
if name.trim().is_empty() {
return Err("Evidence trace name cannot be empty".to_string());
}
if self
.store
.active_debugger_evidence_trace(session_id)?
.is_some()
{
return Err(format!(
"Debugger session \"{session_id}\" already has an active evidence trace"
));
}
let session = self.status(session_id).await?;
let recording_id = self
.store
.active_debugger_recording(session_id)?
.map(|recording| recording.id);
let at = now_ms();
let trace = DebuggerEvidenceTrace {
id: uuid::Uuid::now_v7().to_string(),
name,
session_id: session_id.to_string(),
execution_id: session.execution_id,
recording_id,
status: DebuggerEvidenceTraceStatus::Recording,
cursor: None,
started_at: at,
stopped_at: None,
updated_at: at,
};
self.store.put_debugger_evidence_trace(&trace)?;
Ok(trace)
}
pub fn evidence_trace_stop(&self, session_id: &str) -> Result<DebuggerEvidenceTrace, String> {
let mut trace = self
.store
.active_debugger_evidence_trace(session_id)?
.ok_or_else(|| format!("Debugger session \"{session_id}\" has no active trace"))?;
let at = now_ms();
trace.status = DebuggerEvidenceTraceStatus::Complete;
trace.stopped_at = Some(at);
trace.updated_at = at;
self.store.put_debugger_evidence_trace(&trace)?;
Ok(trace)
}
pub fn evidence_trace_list(&self) -> Result<Vec<DebuggerEvidenceTrace>, String> {
self.store.debugger_evidence_traces()
}
pub fn evidence_trace_show(&self, trace_id: &str) -> Result<DebuggerEvidenceTraceView, String> {
let trace = self.require_evidence_trace(trace_id)?;
let items = self.evidence_trace_items(&trace)?;
Ok(DebuggerEvidenceTraceView { trace, items })
}
pub fn evidence_trace_use(
&self,
actor: String,
trace_id: &str,
) -> Result<DebuggerEvidenceTrace, String> {
let trace = self.require_evidence_trace(trace_id)?;
self.store
.put_debugger_evidence_trace_selection(&actor, &trace.id)?;
Ok(trace)
}
pub fn evidence_trace_cursor(
&self,
actor: &str,
trace_id: Option<&str>,
) -> Result<Option<DebuggerTraceCursor>, String> {
let trace = self.resolve_evidence_trace(actor, trace_id)?;
Ok(trace.cursor)
}
pub async fn evidence_trace_replay(
&self,
actor: String,
trace_id: &str,
at: Option<&str>,
) -> Result<DebuggerTraceReplayResult, String> {
let mut trace = self.require_evidence_trace(trace_id)?;
let items = self.evidence_trace_items(&trace)?;
let selected = if let Some(anchor) = at {
let (kind, id) = split_anchor(anchor).ok_or_else(|| {
format!("Invalid evidence trace anchor \"{anchor}\"; expected KIND:ID")
})?;
Some(
items
.iter()
.find(|item| item.kind == kind && item.id == id)
.ok_or_else(|| format!("Evidence trace item \"{anchor}\" was not found"))?,
)
} else {
items.last()
};
trace.cursor = selected.map(|item| cursor_for(&trace.id, item));
trace.updated_at = now_ms();
self.store.put_debugger_evidence_trace(&trace)?;
self.store
.put_debugger_evidence_trace_selection(&actor, &trace.id)?;
let browser_replay = if let Some(item) = selected.filter(|item| item.kind == "capture") {
self.recording_replay(&trace.session_id, &item.id, Duration::from_secs(30))
.await
.ok()
} else {
None
};
Ok(DebuggerTraceReplayResult {
cursor: trace.cursor.clone(),
trace,
browser_replay,
})
}
pub fn evidence_trace_move(
&self,
actor: &str,
direction: &str,
count: usize,
kind: Option<&str>,
) -> Result<DebuggerTraceCursor, String> {
let mut trace = self.resolve_evidence_trace(actor, None)?;
let items = self
.evidence_trace_items(&trace)?
.into_iter()
.filter(|item| kind.is_none_or(|kind| kind == "any" || item.kind == kind))
.collect::<Vec<_>>();
if items.is_empty() {
return Err(format!(
"Evidence trace has no {} items",
kind.unwrap_or("matching")
));
}
let count = count.max(1);
let current = trace.cursor.as_ref().and_then(|cursor| {
items
.iter()
.position(|item| item.kind == cursor.kind && item.id == cursor.item_id)
});
let index = match direction {
"back" | "prev" => {
let base = current
.map(|index| index.saturating_sub(1))
.unwrap_or(items.len() - 1);
base.saturating_sub(count - 1)
}
"forward" | "next" => {
let base = current.map(|index| index.saturating_add(1)).unwrap_or(0);
base.saturating_add(count - 1).min(items.len() - 1)
}
other => return Err(format!("Unknown trace direction \"{other}\"")),
};
let cursor = cursor_for(&trace.id, &items[index]);
trace.cursor = Some(cursor.clone());
trace.updated_at = now_ms();
self.store.put_debugger_evidence_trace(&trace)?;
Ok(cursor)
}
pub fn evidence_trace_export(&self, trace_id: &str) -> Result<DebuggerTraceExport, String> {
let view = self.evidence_trace_show(trace_id)?;
let bundle = DebuggerTraceBundle {
schema_version: EVIDENCE_TRACE_SCHEMA_VERSION,
trace: view.trace.clone(),
items: view.items,
};
let bytes = serde_json::to_vec_pretty(&bundle).map_err(|error| error.to_string())?;
let artifact = self.store.put_debugger_artifact(
&view.trace.session_id,
view.trace.execution_id.as_deref(),
"debugger_evidence_trace",
"application/json",
&bytes,
)?;
Ok(DebuggerTraceExport {
trace_id: view.trace.id,
artifact,
})
}
pub fn evidence_trace_import(&self, path: &str) -> Result<DebuggerTraceImport, String> {
let bytes = std::fs::read(path)
.map_err(|error| format!("Could not read evidence trace {path}: {error}"))?;
if bytes.len() > 256 * 1024 * 1024 {
return Err("Evidence trace import exceeds 256 MiB".to_string());
}
let bundle: DebuggerTraceBundle =
serde_json::from_slice(&bytes).map_err(|error| format!("Invalid trace: {error}"))?;
if bundle.schema_version != EVIDENCE_TRACE_SCHEMA_VERSION {
return Err(format!(
"Unsupported evidence trace schema {}",
bundle.schema_version
));
}
if self
.store
.debugger_evidence_trace(&bundle.trace.id)?
.is_some()
{
return Err(format!(
"Evidence trace \"{}\" already exists",
bundle.trace.id
));
}
let mut trace = bundle.trace;
trace.status = DebuggerEvidenceTraceStatus::Imported;
trace.cursor = None;
trace.stopped_at = trace.stopped_at.or(Some(now_ms()));
trace.updated_at = now_ms();
self.store.put_debugger_evidence_trace(&trace)?;
self.store
.put_debugger_trace_import_items(&trace.id, &bundle.items)?;
let artifact = self.store.put_debugger_artifact(
&trace.session_id,
trace.execution_id.as_deref(),
"debugger_evidence_trace_import",
"application/json",
&bytes,
)?;
Ok(DebuggerTraceImport { trace, artifact })
}
pub fn evidence_trace_gc(&self, keep: usize) -> Result<DebuggerTraceGc, String> {
let traces = self.store.debugger_evidence_traces()?;
let keep = keep.max(1);
let mut retained = 0;
let mut removed = Vec::new();
for trace in traces {
if trace.status == DebuggerEvidenceTraceStatus::Recording || retained < keep {
retained += 1;
continue;
}
self.store.delete_debugger_evidence_trace(&trace.id)?;
removed.push(trace.id);
}
Ok(DebuggerTraceGc {
kept: retained,
removed,
})
}
fn require_evidence_trace(&self, trace_id: &str) -> Result<DebuggerEvidenceTrace, String> {
self.store
.debugger_evidence_trace(trace_id)?
.ok_or_else(|| format!("Evidence trace \"{trace_id}\" not found"))
}
fn resolve_evidence_trace(
&self,
actor: &str,
trace_id: Option<&str>,
) -> Result<DebuggerEvidenceTrace, String> {
if let Some(trace_id) = trace_id {
return self.require_evidence_trace(trace_id);
}
let trace_id = self
.store
.debugger_evidence_trace_selection(actor)?
.ok_or_else(|| "No evidence trace selected; use trace use first".to_string())?;
self.require_evidence_trace(&trace_id)
}
fn evidence_trace_items(
&self,
trace: &DebuggerEvidenceTrace,
) -> Result<Vec<DebuggerTraceItem>, String> {
if trace.status == DebuggerEvidenceTraceStatus::Imported {
return self.store.debugger_trace_import_items(&trace.id);
}
let until = trace.stopped_at.unwrap_or_else(now_ms);
let mut items = Vec::new();
let mut after = 0;
for _ in 0..20 {
let events = self
.store
.debugger_events(&trace.session_id, after, 1_000)?;
if events.is_empty() {
break;
}
after = events.last().map_or(after, |event| event.sequence);
let page_full = events.len() == 1_000;
items.extend(
events
.into_iter()
.filter(|event| event.at >= trace.started_at && event.at <= until)
.map(|event| DebuggerTraceItem {
kind: debugger_event_kind(&event.kind),
id: event.id,
at: event.at,
label: event.kind,
details: event.details,
}),
);
if !page_full {
break;
}
}
if let Some(recording_id) = trace.recording_id.as_deref() {
items.extend(
self.store
.debugger_captures(recording_id)?
.into_iter()
.filter(|capture| capture.at >= trace.started_at && capture.at <= until)
.map(|capture| DebuggerTraceItem {
kind: "capture".to_string(),
id: capture.id,
at: capture.at,
label: capture.reason,
details: json!({"sequence":capture.sequence,"url":capture.url,"artifact":capture.screenshot.artifact}),
}),
);
items.extend(
self.store
.debugger_marks(recording_id)?
.into_iter()
.filter(|mark| mark.at >= trace.started_at && mark.at <= until)
.map(|mark| DebuggerTraceItem {
kind: "mark".to_string(),
id: mark.id,
at: mark.at,
label: mark.name,
details: json!({"capture_id":mark.capture_id}),
}),
);
items.extend(
self.store
.debugger_afters(recording_id)?
.into_iter()
.filter(|after| after.at >= trace.started_at && after.at <= until)
.map(|after| DebuggerTraceItem {
kind: "diff".to_string(),
id: after.id,
at: after.at,
label: format!("{:.3}% pixels changed", after.diff_percent),
details: json!({"report":after.report,"region":after.region}),
}),
);
}
for tap in self.store.debugger_taps(&trace.session_id)? {
items.extend(
self.store
.debugger_tap_hits(&tap.id, 1_000)?
.into_iter()
.filter(|hit| hit.at >= trace.started_at && hit.at <= until)
.map(|hit| DebuggerTraceItem {
kind: "tap".to_string(),
id: hit.id,
at: hit.at,
label: hit.value.clone(),
details: json!({"tap_id":hit.tap_id,"value":hit.value}),
}),
);
}
for watch in self.store.debugger_watches(&trace.session_id)? {
items.extend(
self.store
.debugger_watch_hits(&watch.id, 1_000)?
.into_iter()
.filter(|hit| hit.at >= trace.started_at && hit.at <= until)
.map(|hit| DebuggerTraceItem {
kind: "watch".to_string(),
id: hit.id,
at: hit.at,
label: hit
.new_value
.clone()
.or_else(|| hit.error.clone())
.unwrap_or_default(),
details: json!({"watch_id":hit.watch_id,"old":hit.old_value,"new":hit.new_value,"error":hit.error}),
}),
);
}
for flow in self
.store
.debugger_flows()?
.into_iter()
.filter(|flow| flow.session_id == trace.session_id)
{
items.extend(
self.store
.debugger_flow_steps(&flow.id)?
.into_iter()
.filter(|step| step.at >= trace.started_at && step.at <= until)
.map(|step| DebuggerTraceItem {
kind: "flow_step".to_string(),
id: step.id,
at: step.at,
label: step.kind,
details: json!({"flow_id":step.flow_id,"sequence":step.sequence,"selector":step.selector,"value":step.value}),
}),
);
}
let mut seen = BTreeSet::new();
items.sort_by(|left, right| {
left.at
.cmp(&right.at)
.then_with(|| left.kind.cmp(&right.kind))
.then_with(|| left.id.cmp(&right.id))
});
items.retain(|item| seen.insert((item.kind.clone(), item.id.clone())));
if items.len() > MAX_TRACE_ITEMS {
items.drain(..items.len() - MAX_TRACE_ITEMS);
}
Ok(items)
}
}
fn cursor_for(trace_id: &str, item: &DebuggerTraceItem) -> DebuggerTraceCursor {
DebuggerTraceCursor {
trace_id: trace_id.to_string(),
kind: item.kind.clone(),
item_id: item.id.clone(),
at: item.at,
}
}
fn split_anchor(anchor: &str) -> Option<(&str, &str)> {
let (kind, id) = anchor.split_once(':')?;
(!kind.is_empty() && !id.is_empty()).then_some((kind, id))
}
fn debugger_event_kind(kind: &str) -> String {
if kind.contains("error") || kind.contains("failed") || kind.contains("exception") {
"error".to_string()
} else if kind.contains("network") {
"network".to_string()
} else {
"event".to_string()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn anchors_split_only_when_both_parts_are_present() {
assert_eq!(split_anchor("capture:one"), Some(("capture", "one")));
assert!(split_anchor("capture").is_none());
assert!(split_anchor(":one").is_none());
}
#[test]
fn debugger_failures_become_error_timeline_items() {
assert_eq!(debugger_event_kind("debugger.run.failed"), "error");
assert_eq!(debugger_event_kind("debugger.paused"), "event");
}
}