use std::fs::File;
use std::path::{Path, PathBuf};
use base64::Engine as _;
use incurs_codemode::ArtifactStore as _;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use super::{DebuggerArtifact, DebuggerManager, now_ms};
use crate::model::{Execution, ExecutionArtifactRef};
use crate::run::RunLogs;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum RrTraceStatus {
Recording,
Complete,
Failed,
Imported,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum RrBackend {
Native,
Isolated { image: String },
}
impl Default for RrBackend {
fn default() -> Self {
if cfg!(target_os = "macos") {
Self::Isolated {
image: "local".to_string(),
}
} else {
Self::Native
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RrTrace {
pub id: String,
pub name: String,
pub status: RrTraceStatus,
pub command: Vec<String>,
pub execution_id: Option<String>,
pub latest_replay_execution_id: Option<String>,
pub trace_dir: Option<String>,
pub artifact: Option<DebuggerArtifact>,
pub error: Option<String>,
pub started_at: u64,
pub completed_at: Option<u64>,
pub updated_at: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RrExecutionResult {
pub trace: RrTrace,
pub execution: Execution,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct RrProcessStatus {
pub trace: RrTrace,
pub execution: Execution,
pub logs: RunLogs,
}
impl DebuggerManager {
pub fn rr_prepare_record(&self, name: String, command: Vec<String>) -> Result<RrTrace, String> {
if name.trim().is_empty() {
return Err("rr trace name cannot be empty".to_string());
}
if command.is_empty() {
return Err("rr record requires exact command argv".to_string());
}
let at = now_ms();
let trace = RrTrace {
id: uuid::Uuid::now_v7().to_string(),
name,
status: RrTraceStatus::Recording,
command,
execution_id: None,
latest_replay_execution_id: None,
trace_dir: None,
artifact: None,
error: None,
started_at: at,
completed_at: None,
updated_at: at,
};
self.store.put_rr_trace(&trace)?;
if let Err(error) = std::fs::create_dir_all(self.rr_recording_parent(&trace.id)) {
let error = error.to_string();
let _ = self.rr_finish_record(&trace.id, false, Some(error.clone()));
return Err(error);
}
Ok(trace)
}
pub fn rr_recording_parent(&self, trace_id: &str) -> PathBuf {
self.rr_root().join("recordings").join(trace_id)
}
pub fn rr_set_execution(
&self,
trace_id: &str,
execution_id: String,
) -> Result<RrTrace, String> {
let mut trace = self.rr_require(trace_id)?;
trace.execution_id = Some(execution_id);
trace.updated_at = now_ms();
self.store.put_rr_trace(&trace)?;
Ok(trace)
}
pub fn rr_set_replay_execution(
&self,
trace_id: &str,
execution_id: String,
) -> Result<RrTrace, String> {
let mut trace = self.rr_require(trace_id)?;
trace.latest_replay_execution_id = Some(execution_id);
trace.updated_at = now_ms();
self.store.put_rr_trace(&trace)?;
Ok(trace)
}
pub fn rr_finish_record(
&self,
trace_id: &str,
succeeded: bool,
execution_error: Option<String>,
) -> Result<RrTrace, String> {
let mut trace = self.rr_require(trace_id)?;
if trace.status != RrTraceStatus::Recording {
return Ok(trace);
}
let terminal_at = now_ms();
if !succeeded {
trace.status = RrTraceStatus::Failed;
trace.error = execution_error.or_else(|| Some("rr record failed".to_string()));
trace.completed_at = Some(terminal_at);
trace.updated_at = terminal_at;
self.store.put_rr_trace(&trace)?;
return Ok(trace);
}
let retained = newest_trace_directory(&self.rr_recording_parent(trace_id))
.and_then(|source| self.rr_archive_and_materialize(&trace, &source));
match retained {
Ok((artifact, trace_dir)) => {
trace.status = RrTraceStatus::Complete;
trace.trace_dir = Some(trace_dir.to_string_lossy().into_owned());
trace.artifact = Some(artifact);
trace.error = None;
}
Err(error) => {
trace.status = RrTraceStatus::Failed;
trace.error = Some(format!("Could not retain rr trace: {error}"));
}
}
trace.completed_at = Some(terminal_at);
trace.updated_at = terminal_at;
self.store.put_rr_trace(&trace)?;
Ok(trace)
}
pub async fn rr_finish_isolated_record(
&self,
trace_id: &str,
execution_id: &str,
exported: &ExecutionArtifactRef,
) -> Result<RrTrace, String> {
let mut trace = self.rr_require(trace_id)?;
if trace.status != RrTraceStatus::Recording {
return Ok(trace);
}
if exported.name != "rr-trace" || exported.media_type != "application/x-tar" {
return Err(format!(
"Isolated rr execution returned an invalid trace export: {} ({})",
exported.name, exported.media_type
));
}
let envelope = self
.store
.get(execution_id, &exported.id)
.await?
.ok_or_else(|| {
format!(
"Isolated rr trace artifact {} is missing for execution {execution_id}",
exported.id
)
})?;
let encoded = envelope
.get("data_base64")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| "Isolated rr trace artifact has no encoded archive".to_string())?;
let bytes = base64::engine::general_purpose::STANDARD
.decode(encoded)
.map_err(|error| format!("Could not decode isolated rr trace archive: {error}"))?;
if bytes.len() as u64 != exported.bytes {
return Err(format!(
"Isolated rr trace archive length mismatch: expected {}, received {}",
exported.bytes,
bytes.len()
));
}
let artifact = self.store.put_debugger_artifact(
&format!("rr:{}", trace.id),
Some(execution_id),
"rr_trace_archive",
"application/x-tar",
&bytes,
)?;
let trace_dir = self.rr_materialize_artifact(&trace, &artifact, "value")?;
let at = now_ms();
trace.status = RrTraceStatus::Complete;
trace.trace_dir = Some(trace_dir.to_string_lossy().into_owned());
trace.artifact = Some(artifact);
trace.error = None;
trace.completed_at = Some(at);
trace.updated_at = at;
self.store.put_rr_trace(&trace)?;
Ok(trace)
}
pub fn rr_import(&self, path: &str, name: Option<String>) -> Result<RrTrace, String> {
let source = std::fs::canonicalize(path)
.map_err(|error| format!("Could not resolve rr trace directory {path}: {error}"))?;
if !source.is_dir() {
return Err(format!("rr trace import path is not a directory: {path}"));
}
if name.as_deref().is_some_and(|name| name.trim().is_empty()) {
return Err("rr trace name cannot be empty".to_string());
}
let at = now_ms();
let mut trace = RrTrace {
id: uuid::Uuid::now_v7().to_string(),
name: name.unwrap_or_else(|| {
source
.file_name()
.and_then(|value| value.to_str())
.unwrap_or("rr-trace")
.to_string()
}),
status: RrTraceStatus::Imported,
command: Vec::new(),
execution_id: None,
latest_replay_execution_id: None,
trace_dir: None,
artifact: None,
error: None,
started_at: at,
completed_at: Some(at),
updated_at: at,
};
let (artifact, trace_dir) = self.rr_archive_and_materialize(&trace, &source)?;
trace.artifact = Some(artifact);
trace.trace_dir = Some(trace_dir.to_string_lossy().into_owned());
self.store.put_rr_trace(&trace)?;
Ok(trace)
}
pub fn rr_list(&self) -> Result<Vec<RrTrace>, String> {
self.store.rr_traces()
}
pub fn rr_show(&self, trace_id: &str) -> Result<RrTrace, String> {
self.rr_require(trace_id)
}
pub fn rr_recording_traces(&self) -> Result<Vec<RrTrace>, String> {
self.store.rr_traces_by_status(RrTraceStatus::Recording)
}
fn rr_require(&self, trace_id: &str) -> Result<RrTrace, String> {
self.store
.rr_trace(trace_id)?
.ok_or_else(|| format!("rr trace \"{trace_id}\" not found"))
}
fn rr_archive_and_materialize(
&self,
trace: &RrTrace,
source: &Path,
) -> Result<(DebuggerArtifact, PathBuf), String> {
let temporary_directory = self.rr_root().join("tmp");
std::fs::create_dir_all(&temporary_directory).map_err(|error| error.to_string())?;
let archive_path =
temporary_directory.join(format!("{}.{}.tar", trace.id, uuid::Uuid::now_v7()));
let archive_file = File::create(&archive_path).map_err(|error| error.to_string())?;
let mut builder = tar::Builder::new(archive_file);
builder.follow_symlinks(false);
builder
.append_dir_all("trace", source)
.map_err(|error| error.to_string())?;
builder.finish().map_err(|error| error.to_string())?;
drop(builder);
let artifact = self.store.put_debugger_artifact_file(
&format!("rr:{}", trace.id),
trace.execution_id.as_deref(),
"rr_trace_archive",
"application/x-tar",
&archive_path,
)?;
let _ = std::fs::remove_file(&archive_path);
let trace_dir = self.rr_materialize_artifact(trace, &artifact, "trace")?;
Ok((artifact, trace_dir))
}
fn rr_materialize_artifact(
&self,
trace: &RrTrace,
artifact: &DebuggerArtifact,
archive_root: &str,
) -> Result<PathBuf, String> {
let trace_root = self.rr_root().join("traces").join(&trace.id);
if trace_root.exists() {
return Err(format!(
"Managed rr trace directory already exists: {}",
trace_root.display()
));
}
let temporary_root = self.rr_root().join("traces").join(format!(
".{}.{}.tmp",
trace.id,
uuid::Uuid::now_v7()
));
std::fs::create_dir_all(&temporary_root).map_err(|error| error.to_string())?;
let file = File::open(&artifact.path).map_err(|error| error.to_string())?;
let mut archive = tar::Archive::new(file);
if let Err(error) = archive.unpack(&temporary_root) {
let _ = std::fs::remove_dir_all(&temporary_root);
return Err(error.to_string());
}
let materialized = temporary_root.join(archive_root);
if !materialized.is_dir() {
let _ = std::fs::remove_dir_all(&temporary_root);
return Err(format!(
"rr trace archive did not contain a {archive_root} directory"
));
}
if let Some(parent) = trace_root.parent() {
std::fs::create_dir_all(parent).map_err(|error| error.to_string())?;
}
std::fs::rename(&temporary_root, &trace_root).map_err(|error| error.to_string())?;
let materialized = trace_root.join(archive_root);
make_rr_trace_readable(&materialized)?;
Ok(materialized)
}
fn rr_root(&self) -> PathBuf {
self.store
.path()
.parent()
.unwrap_or_else(|| Path::new("."))
.join("rr")
}
}
#[cfg(unix)]
fn make_rr_trace_readable(root: &Path) -> Result<(), String> {
use std::os::unix::fs::PermissionsExt;
let metadata = std::fs::symlink_metadata(root).map_err(|error| error.to_string())?;
if metadata.file_type().is_symlink() {
return Err(format!(
"rr trace materialization contains a symlink: {}",
root.display()
));
}
if metadata.is_dir() {
std::fs::set_permissions(root, std::fs::Permissions::from_mode(0o755))
.map_err(|error| error.to_string())?;
for entry in std::fs::read_dir(root).map_err(|error| error.to_string())? {
make_rr_trace_readable(&entry.map_err(|error| error.to_string())?.path())?;
}
} else if metadata.is_file() {
std::fs::set_permissions(root, std::fs::Permissions::from_mode(0o444))
.map_err(|error| error.to_string())?;
} else {
return Err(format!(
"rr trace materialization contains a non-file entry: {}",
root.display()
));
}
Ok(())
}
#[cfg(not(unix))]
fn make_rr_trace_readable(_root: &Path) -> Result<(), String> {
Ok(())
}
fn newest_trace_directory(parent: &Path) -> Result<PathBuf, String> {
let mut directories = std::fs::read_dir(parent)
.map_err(|error| error.to_string())?
.filter_map(Result::ok)
.filter(|entry| entry.file_type().is_ok_and(|kind| kind.is_dir()))
.map(|entry| {
let modified = entry
.metadata()
.and_then(|metadata| metadata.modified())
.unwrap_or(std::time::UNIX_EPOCH);
(modified, entry.path())
})
.collect::<Vec<_>>();
directories.sort_by(|left, right| right.0.cmp(&left.0).then_with(|| right.1.cmp(&left.1)));
directories
.into_iter()
.next()
.map(|(_, path)| path)
.ok_or_else(|| {
format!(
"rr did not create a trace directory under {}",
parent.display()
)
})
}
#[cfg(test)]
mod tests {
use super::*;
use crate::store::Store;
use std::sync::Arc;
use tempfile::tempdir;
#[test]
fn rr_import_owns_a_content_addressed_archive_and_materialized_copy() {
let root = tempdir().unwrap();
let source = root.path().join("source");
std::fs::create_dir_all(source.join("nested")).unwrap();
std::fs::write(source.join("version"), b"rr trace v1").unwrap();
std::fs::write(source.join("nested/events"), b"events").unwrap();
let store = Arc::new(Store::open(root.path().join("state/apoc.sqlite3")).unwrap());
let manager = DebuggerManager::new(store);
let trace = manager
.rr_import(source.to_str().unwrap(), Some("imported".to_string()))
.unwrap();
assert_eq!(trace.status, RrTraceStatus::Imported);
assert_eq!(trace.name, "imported");
let artifact = trace.artifact.unwrap();
assert!(artifact.id.starts_with("sha256:"));
assert!(Path::new(&artifact.path).is_file());
let trace_dir = PathBuf::from(trace.trace_dir.unwrap());
assert_ne!(trace_dir, source);
assert_eq!(
std::fs::read(trace_dir.join("version")).unwrap(),
b"rr trace v1"
);
assert_eq!(
std::fs::read(trace_dir.join("nested/events")).unwrap(),
b"events"
);
}
#[test]
fn rr_record_does_not_infer_success_without_trace_output() {
let root = tempdir().unwrap();
let store = Arc::new(Store::open(root.path().join("state/apoc.sqlite3")).unwrap());
let manager = DebuggerManager::new(store);
let trace = manager
.rr_prepare_record("missing".to_string(), vec!["target".to_string()])
.unwrap();
let terminal = manager.rr_finish_record(&trace.id, true, None).unwrap();
assert_eq!(terminal.status, RrTraceStatus::Failed);
assert!(
terminal
.error
.as_deref()
.unwrap()
.contains("did not create a trace directory")
);
assert!(terminal.artifact.is_none());
assert!(terminal.trace_dir.is_none());
}
#[tokio::test]
async fn rr_isolated_record_adopts_the_verified_execution_export() {
let root = tempdir().unwrap();
let store = Arc::new(Store::open(root.path().join("state/apoc.sqlite3")).unwrap());
let manager = DebuggerManager::new(Arc::clone(&store));
let trace = manager
.rr_prepare_record("isolated".to_string(), vec!["target".to_string()])
.unwrap();
let trace_source = root.path().join("export/value");
std::fs::create_dir_all(&trace_source).unwrap();
std::fs::write(trace_source.join("version"), b"rr trace v1").unwrap();
let mut archive = Vec::new();
{
let mut builder = tar::Builder::new(&mut archive);
builder.append_dir_all("value", &trace_source).unwrap();
builder.finish().unwrap();
}
let envelope = serde_json::json!({
"kind":"isolated_export",
"name":"rr-trace",
"source":"/tmp/apoc-rr/trace",
"media_type":"application/x-tar",
"guest_sha256":"sha256:fixture",
"data_base64":base64::engine::general_purpose::STANDARD.encode(&archive),
});
let stored = store.put("execution-1", &envelope).await.unwrap();
let exported = ExecutionArtifactRef {
name: "rr-trace".to_string(),
source: "/tmp/apoc-rr/trace".to_string(),
id: stored.id,
bytes: archive.len() as u64,
guest_sha256: "sha256:fixture".to_string(),
media_type: "application/x-tar".to_string(),
};
let completed = manager
.rr_finish_isolated_record(&trace.id, "execution-1", &exported)
.await
.unwrap();
assert_eq!(completed.status, RrTraceStatus::Complete);
assert_eq!(completed.artifact.unwrap().kind, "rr_trace_archive");
assert_eq!(
std::fs::read(PathBuf::from(completed.trace_dir.unwrap()).join("version")).unwrap(),
b"rr trace v1"
);
}
}