Open source Loom alternative. Beautiful, shareable screen recordings.
Rust appcapcossloommacnextjsnextjs15open-sourceossreactrecordrustscreen-capturescreen-recorderscreenshotsolidjstauritauri-apptypescriptvite
//! The Feedback page's Diagnostic Report.
//!
//! Two halves, and they run very differently.
//!
//! The A/V sync self-test runs as a **subprocess** -- the `cap` CLI, shipped
//! inside `Cap.app` as the `cap-cli` sidecar. It cannot run in-process:
//! `cap selftest av-sync` builds its own winit `EventLoop` for the flashing
//! test pattern and needs the process main thread, which gpui owns for the
//! whole life of the app. So this module resolves the binary, drives its
//! `--progress-json` NDJSON stream, and hands the final report back as raw
//! JSON.
//!
//! Around it sits the environment snapshot from `cap_recording::diagnostics`.
//! [`collect_report`] probes displays and disk mounts and can block for the
//! better part of a minute (display enumeration alone is ~37s without screen
//! recording permission), so every entry point here is written to be called
//! from a background thread and never from the UI one.
use std::{
io::{BufRead as _, BufReader},
path::{Path, PathBuf},
process::{Command, Stdio},
sync::{
Arc, Mutex,
atomic::{AtomicBool, AtomicU64, Ordering},
},
time::{Duration, SystemTime, UNIX_EPOCH},
};
use serde_json::{Value, json};
use crate::{permissions, store};
/// The rolling log file's prefix. Deliberately *not* the Tauri app's
/// `cap-desktop.log`: both apps write into the same directory on macOS, and a
/// shared prefix would interleave two processes' lines into one file and make
/// either app's "newest log" lookup pick up the other's.
pub const LOG_FILE_PREFIX: &str = "cap-gpui.log";
/// `MAX_SIZE` in `src-tauri/src/logging.rs`.
/// How much of the self-test's stderr is kept for a failure message.
const STDERR_TAIL_BYTES: usize = 8 * 1024;
/// How many diagnostic reports stay on disk.
const KEEP_REPORTS: usize = 5;
/// Seconds of test pattern. The CLI's own default is shorter; 20s is long
/// enough for the drift term to mean something without making the flashing
/// window feel endless.
pub const DEFAULT_DURATION_SECS: u64 = 20;
/// `CAP_GPUI_SELFTEST_BIN`: an explicit path to the `cap` binary, which wins
/// over every probe below. The verification harness sets it; nothing else does.
const SELFTEST_BIN_ENV: &str = "CAP_GPUI_SELFTEST_BIN";
/// The shipping app. The gpui binary is unbundled in dev and carries no
/// sidecar of its own, so it borrows the installed app's -- the same fallback
/// the editor's wallpaper lookup makes.
const INSTALLED_APP: &str = "/Applications/Cap.app";
// ---------------------------------------------------------------------------
// Log file
// ---------------------------------------------------------------------------
/// Where the rolling file log lives.
///
/// macOS uses `~/Library/Logs/so.cap.desktop` -- the same directory the Tauri
/// app writes into, so a user handing over "the Cap logs folder" hands over
/// both apps' logs -- and every other platform uses
/// `<local data>/so.cap.desktop/logs`, matching `main.rs` over there.
pub fn logs_dir() -> PathBuf {
if let Ok(directory) = std::env::var("CAP_GPUI_LOG_DIR")
&& !directory.trim().is_empty()
{
return PathBuf::from(directory);
}
#[cfg(target_os = "macos")]
{
dirs::home_dir()
.unwrap_or_else(|| PathBuf::from("."))
.join("Library/Logs")
.join("so.cap.desktop")
}
#[cfg(not(target_os = "macos"))]
{
dirs::data_local_dir()
.unwrap_or_else(|| PathBuf::from("."))
.join("so.cap.desktop")
.join("logs")
}
}
pub fn log_tail() -> cap_utils::log_upload::LogBundle {
cap_utils::log_upload::collect(&logs_dir(), LOG_FILE_PREFIX)
}
// ---------------------------------------------------------------------------
// The self-test sidecar
// ---------------------------------------------------------------------------
fn selftest_bin_name() -> &'static str {
if cfg!(windows) {
"cap-cli.exe"
} else {
"cap-cli"
}
}
fn cap_bin_name() -> &'static str {
if cfg!(windows) { "cap.exe" } else { "cap" }
}
/// The triple Tauri suffixes the un-bundled sidecar with, spelled the way
/// `src-tauri/src/export.rs` spells it.
fn current_target_triple() -> Option<&'static str> {
if cfg!(all(
target_os = "windows",
target_arch = "x86_64",
target_env = "msvc"
)) {
Some("x86_64-pc-windows-msvc")
} else if cfg!(all(
target_os = "windows",
target_arch = "aarch64",
target_env = "msvc"
)) {
Some("aarch64-pc-windows-msvc")
} else if cfg!(all(target_os = "macos", target_arch = "aarch64")) {
Some("aarch64-apple-darwin")
} else if cfg!(all(target_os = "macos", target_arch = "x86_64")) {
Some("x86_64-apple-darwin")
} else {
None
}
}
/// Every place the `cap` CLI could be, newest-context first.
///
/// 1. Next to this executable, which is where the sidecar sits when the gpui
/// app is staged inside `Cap.app` (`Contents/Resources/gpui/`) *and* where
/// a dev `cargo build` leaves it.
/// 2. `../MacOS` and `../Resources` relative to the executable -- the two
/// places a Tauri bundle puts an `externalBin`.
/// 3. The installed `/Applications/Cap.app`. The gpui dev binary is unbundled
/// and has no sidecar of its own, so it borrows the installed app's, the
/// same way the editor's wallpaper lookup borrows its assets.
/// 4. `target/{debug,release}/cap`, walking up from the working directory --
/// the dev checkout, where the CLI is just another workspace binary.
fn selftest_binary_candidates(
exe_dir: Option<&Path>,
installed_app: Option<&Path>,
cwd: Option<&Path>,
) -> Vec<PathBuf> {
let triple = current_target_triple();
let mut candidates = Vec::new();
let mut push_dir = |dir: &Path| {
candidates.push(dir.join(selftest_bin_name()));
if let Some(triple) = triple {
candidates.push(dir.join(format!("cap-cli-{triple}{}", std::env::consts::EXE_SUFFIX)));
}
candidates.push(dir.join(cap_bin_name()));
};
if let Some(dir) = exe_dir {
push_dir(dir);
for sibling in ["../Resources", "../MacOS"] {
push_dir(&dir.join(sibling));
}
}
if let Some(bundle) = installed_app {
for sibling in ["Contents/Resources", "Contents/MacOS"] {
push_dir(&bundle.join(sibling));
}
}
// The dev checkout: `apps/desktop-gpui` is two levels below the repo root
// and has a `target/` of its own, so every ancestor gets a look.
//
// Debug builds only, matching how `src-tauri/src/export.rs` gates its own
// target/ probes: this walks the working directory, so in a shipped build
// it would let anyone who can pick the process's cwd -- a shared temp
// directory, a downloaded folder -- place a `target/debug/cap` for us to
// execute. A release build has its sidecar next to it or in the bundle.
if cfg!(debug_assertions)
&& let Some(cwd) = cwd
{
for ancestor in cwd.ancestors() {
for profile in ["debug", "release"] {
candidates.push(ancestor.join("target").join(profile).join(cap_bin_name()));
}
}
}
candidates
}
/// The first candidate that exists, or `None`. Callers must degrade: a build
/// with no sidecar next to it still collects an environment report, it just
/// cannot run the sync test.
pub fn resolve_selftest_binary() -> Option<PathBuf> {
let override_path = std::env::var_os(SELFTEST_BIN_ENV)
.map(PathBuf::from)
.filter(|path| !path.as_os_str().is_empty());
let exe_dir = std::env::current_exe()
.ok()
.and_then(|exe| exe.parent().map(Path::to_path_buf));
let installed = cfg!(target_os = "macos").then(|| Path::new(INSTALLED_APP));
let cwd = std::env::current_dir().ok();
resolve_selftest_binary_in(override_path, exe_dir.as_deref(), installed, cwd.as_deref())
}
/// [`resolve_selftest_binary`] with everything it reads off the machine lifted
/// into parameters, so the probe order is testable without mutating
/// process-global state -- and without the tests' answers depending on whether
/// this machine happens to have Cap installed.
fn resolve_selftest_binary_in(
override_path: Option<PathBuf>,
exe_dir: Option<&Path>,
installed_app: Option<&Path>,
cwd: Option<&Path>,
) -> Option<PathBuf> {
if let Some(path) = override_path {
// An override that does not exist is a configuration mistake worth
// surfacing, not something to silently fall back from.
return path.is_file().then_some(path);
}
selftest_binary_candidates(exe_dir, installed_app, cwd)
.into_iter()
.find(|path| path.is_file())
}
// ---------------------------------------------------------------------------
// Running it
// ---------------------------------------------------------------------------
/// `--mode`: which recording pipelines the test exercises.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SyncMode {
Studio,
Instant,
Both,
}
impl SyncMode {
pub const ALL: &'static [Self] = &[Self::Studio, Self::Instant, Self::Both];
/// The `--mode` value, which is also the `mode` field in every progress
/// line.
pub fn flag(self) -> &'static str {
match self {
Self::Studio => "studio",
Self::Instant => "instant",
Self::Both => "both",
}
}
pub fn label(self) -> &'static str {
match self {
Self::Studio => "Studio",
Self::Instant => "Instant",
Self::Both => "Both",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SyncTestOptions {
pub mode: SyncMode,
/// `--mic`: also records the default microphone and checks that it hears
/// the beeps in time. Studio leg only.
pub microphone: bool,
pub duration_secs: u64,
}
impl Default for SyncTestOptions {
fn default() -> Self {
Self {
mode: SyncMode::Both,
microphone: false,
duration_secs: DEFAULT_DURATION_SECS,
}
}
}
/// `--discard-recordings` is not optional here: this app surfaces the report
/// and never the recording, and the CLI otherwise keeps the recorded project
/// for every non-pass verdict -- including the common `inconclusive` one --
/// with nothing on this side to reveal or delete it.
fn sync_test_args(options: &SyncTestOptions) -> Vec<String> {
let mut args = vec![
"selftest".to_string(),
"av-sync".to_string(),
"--progress-json".to_string(),
"--discard-recordings".to_string(),
"--mode".to_string(),
options.mode.flag().to_string(),
"--duration".to_string(),
options.duration_secs.to_string(),
];
if options.microphone {
args.push("--mic".to_string());
}
args
}
/// Only one diagnostic can run at a time, process-wide: the sync test takes
/// over the screen and the audio device, so a second run would measure the
/// first one. This has to be global rather than per-window -- Settings builds a
/// fresh page state every time it opens, while the run itself is a detached
/// background task that outlives the window.
///
/// The Tauri app guards the same way (`DIAGNOSTIC_RUNNING` in
/// `src-tauri/src/diagnostics.rs`).
static DIAGNOSTIC_RUNNING: AtomicBool = AtomicBool::new(false);
/// Held for the length of one diagnostic run; releases on every exit path,
/// including a dropped run future.
pub struct RunGuard;
impl RunGuard {
pub fn acquire() -> Result<Self, String> {
DIAGNOSTIC_RUNNING
.compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
.map(|_| Self)
.map_err(|_| ALREADY_RUNNING.to_string())
}
}
impl Drop for RunGuard {
fn drop(&mut self) {
DIAGNOSTIC_RUNNING.store(false, Ordering::Release);
}
}
pub const ALREADY_RUNNING: &str = "A diagnostic is already running.";
/// Kills the self-test if it is dropped before the run's own kill/wait
/// sequence. `std::process::Child` does not kill on drop, and an orphaned
/// self-test owns the screen with a fullscreen flashing window while it is
/// midway through a recording.
struct ChildGuard(std::process::Child);
impl Drop for ChildGuard {
fn drop(&mut self) {
// Both are no-ops once the run has already waited on the child.
let _ = self.0.kill();
let _ = self.0.wait();
}
}
/// One `{"type":"Stage",..}` line.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Stage {
pub stage: String,
pub mode: Option<String>,
}
/// A line off the self-test's stdout.
#[derive(Debug, Clone, PartialEq)]
pub enum ProgressLine {
Stage {
stage: String,
mode: Option<String>,
},
Report(Value),
Error(String),
/// Anything else: a blank line, a log line that escaped stderr, a message
/// type added after this build. Never fatal -- the stream is forward
/// compatible by being ignorable.
Unknown,
}
pub fn parse_progress_line(line: &str) -> ProgressLine {
let Ok(value) = serde_json::from_str::<Value>(line) else {
return ProgressLine::Unknown;
};
match value.get("type").and_then(Value::as_str) {
Some("Stage") => match value.get("stage").and_then(Value::as_str) {
Some(stage) => ProgressLine::Stage {
stage: stage.to_string(),
mode: value
.get("mode")
.and_then(Value::as_str)
.map(str::to_string),
},
None => ProgressLine::Unknown,
},
Some("Report") => match value.get("report") {
Some(report) => ProgressLine::Report(report.clone()),
None => ProgressLine::Unknown,
},
Some("Error") => match value.get("error").and_then(Value::as_str) {
Some(error) => ProgressLine::Error(error.to_string()),
None => ProgressLine::Unknown,
},
_ => ProgressLine::Unknown,
}
}
/// The three stages the app emits for itself around the subprocess. Not CLI
/// stage names -- the CLI never sends these.
pub const START_STAGE: &str = "starting";
pub const COLLECT_STAGE: &str = "collecting-report";
pub const CANCEL_STAGE: &str = "cancelling";
/// The user-facing words for a stage. The CLI's stage names are stable API but
/// they are not sentences.
pub fn stage_label(stage: &str, mode: Option<&str>) -> String {
let leg = match mode {
Some("studio") => " studio",
Some("instant") => " instant",
_ => "",
};
match stage {
"collecting" => format!("Preparing the{leg} test..."),
"recording" => format!("Recording the{leg} test..."),
"pattern-run" => format!("Playing the test pattern{leg}..."),
"remuxing" => format!("Finalizing the{leg} recording..."),
"analyzing" => format!("Analyzing the{leg} recording..."),
"exporting" => format!("Exporting the{leg} recording..."),
"done" => "Wrapping up the sync test...".to_string(),
START_STAGE => "Starting the diagnostic...".to_string(),
COLLECT_STAGE => "Collecting system information...".to_string(),
CANCEL_STAGE => "Cancelling...".to_string(),
other => format!("{other}..."),
}
}
fn trim_to_tail(text: &mut String, max_bytes: usize) {
if text.len() <= max_bytes {
return;
}
let mut start = text.len() - max_bytes;
while start < text.len() && !text.is_char_boundary(start) {
start += 1;
}
let start = match text[start..].find('\n') {
Some(offset) => start + offset + 1,
None => start,
};
text.drain(..start);
}
/// Run `cap selftest av-sync --progress-json` and return the final report.
///
/// **Never call this without the user having asked for it**: the self-test
/// takes the screen over with a fullscreen flashing window and plays 1kHz
/// beeps at output volume.
///
/// The process exits non-zero for a `fail` or `inconclusive` verdict, so the
/// exit status is deliberately not consulted -- a report that arrived is a
/// successful run whatever the code was. `cancel` is polled by a watchdog
/// thread rather than between stdout lines, because a recording leg can go
/// twenty-odd seconds without emitting anything and a Cancel button that takes
/// twenty seconds is not a Cancel button.
pub fn run_sync_test(
binary: &Path,
options: &SyncTestOptions,
cancel: &Arc<AtomicBool>,
mut on_stage: impl FnMut(Stage),
) -> Result<Value, String> {
if cancel.load(Ordering::Relaxed) {
return Err(CANCELLED.to_string());
}
// Wrapped before anything else can fail: every early return from here on
// has to take the child with it.
let mut child = ChildGuard(
Command::new(binary)
.args(sync_test_args(options))
.stdin(Stdio::null())
.stdout(Stdio::piped())
.stderr(Stdio::piped())
.spawn()
.map_err(|error| format!("Failed to start {}: {error}", binary.display()))?,
);
let stdout = child
.0
.stdout
.take()
.ok_or_else(|| "The self-test produced no output stream".to_string())?;
let stderr = child.0.stderr.take();
let stderr_tail = Arc::new(Mutex::new(String::new()));
let stderr_reader = stderr.map(|stderr| {
let tail = Arc::clone(&stderr_tail);
std::thread::spawn(move || {
for line in BufReader::new(stderr).lines().map_while(Result::ok) {
if let Ok(mut tail) = tail.lock() {
tail.push_str(&line);
tail.push('\n');
trim_to_tail(&mut tail, STDERR_TAIL_BYTES);
}
}
})
});
let child = Arc::new(Mutex::new(child));
let finished = Arc::new(AtomicBool::new(false));
let watchdog = std::thread::spawn({
let child = Arc::clone(&child);
let cancel = Arc::clone(cancel);
let finished = Arc::clone(&finished);
move || {
while !finished.load(Ordering::Relaxed) {
if cancel.load(Ordering::Relaxed) {
if let Ok(mut child) = child.lock() {
let _ = child.0.kill();
}
return;
}
std::thread::sleep(Duration::from_millis(100));
}
}
});
let mut report = None;
let mut error_line = None;
for line in BufReader::new(stdout).lines().map_while(Result::ok) {
match parse_progress_line(&line) {
ProgressLine::Stage { stage, mode } => on_stage(Stage { stage, mode }),
ProgressLine::Report(value) => report = Some(value),
ProgressLine::Error(error) => error_line = Some(error),
ProgressLine::Unknown => {}
}
}
// stdout is at EOF, so the child is on its way out either way; releasing
// the watchdog before touching the lock keeps the two off each other.
finished.store(true, Ordering::Relaxed);
let _ = watchdog.join();
if let Some(reader) = stderr_reader {
let _ = reader.join();
}
let status = child
.lock()
.map_err(|_| "The self-test process handle was poisoned".to_string())
.and_then(|mut child| child.0.wait().map_err(|error| error.to_string()));
if cancel.load(Ordering::Relaxed) {
return Err(CANCELLED.to_string());
}
if let Some(report) = report {
return Ok(report);
}
let tail = stderr_tail
.lock()
.map(|tail| tail.trim().to_string())
.unwrap_or_default();
let status = match status {
Ok(status) => format!("The self-test exited with {status}"),
Err(error) => format!("The self-test could not be waited on: {error}"),
};
Err(
[Some(status), error_line, (!tail.is_empty()).then_some(tail)]
.into_iter()
.flatten()
.collect::<Vec<_>>()
.join("\n"),
)
}
pub const CANCELLED: &str = "The diagnostic was cancelled.";
// ---------------------------------------------------------------------------
// The environment report
// ---------------------------------------------------------------------------
/// `permission_status_str` in `src-tauri/src/logging.rs` -- the same four wire
/// strings, so a gpui report and a Tauri one read identically. `NotDetermined`
/// is Tauri's `Empty`, which it spells `not_requested`.
fn permission_status_str(status: permissions::OSPermissionStatus) -> &'static str {
match status {
permissions::OSPermissionStatus::NotNeeded => "not_needed",
permissions::OSPermissionStatus::NotDetermined => "not_requested",
permissions::OSPermissionStatus::Granted => "granted",
permissions::OSPermissionStatus::Denied => "denied",
}
}
fn permissions_snapshot() -> Value {
let check = permissions::classify(
permissions::check_raw(),
permissions::AttemptedFlags::default(),
);
json!({
"screenRecording": permission_status_str(check.screen_recording),
"camera": permission_status_str(check.camera),
"microphone": permission_status_str(check.microphone),
"accessibility": permission_status_str(check.accessibility),
})
}
/// `redact_url_credentials` in `src-tauri/src/diagnostics.rs`.
fn redact_url_credentials(url: &str) -> String {
let Some((scheme, rest)) = url.split_once("://") else {
return url.to_string();
};
let authority_end = rest.find('/').unwrap_or(rest.len());
let (authority, path) = rest.split_at(authority_end);
match authority.rsplit_once('@') {
Some((_, host)) => format!("{scheme}://***@{host}{path}"),
None => url.to_string(),
}
}
/// The same fields `settings_snapshot` picks in the Tauri app, read off the
/// store the two apps share. Paths are redacted to `~/..`, and the instance id
/// is read rather than minted -- opening a diagnostic must not write to the
/// shared store.
fn settings_snapshot() -> Value {
use cap_recording::diagnostics::redact_home_paths;
use store::SettingsEnum as _;
let settings = store::GeneralSettings::load();
let instance_id = store::store_section(store::GENERAL_SETTINGS)
.get("instanceId")
.and_then(Value::as_str)
.map(str::to_string);
json!({
"maxFps": settings.max_fps,
"instantModeMaxResolution": settings.instant_mode_max_resolution,
"studioRecordingQuality": settings.studio_recording_quality.as_json(),
"customCursorCapture": settings.custom_cursor_capture,
"outOfProcessMuxer": settings.out_of_process_muxer,
"crashRecoveryRecording": settings.crash_recovery_recording,
"enableNativeCameraPreview": settings.enable_native_camera_preview,
"recordingsPath": settings.recordings_path.as_deref().map(redact_home_paths),
"previousRecordingsPaths": settings
.previous_recordings_paths
.iter()
.map(|path| redact_home_paths(path))
.collect::<Vec<_>>(),
"updateChannel": settings.update_channel.as_json(),
"serverUrl": redact_url_credentials(&settings.server_url),
"instanceId": instance_id,
"enableTelemetry": settings.enable_telemetry,
"editorPreviewQuality": settings.editor_preview_quality.as_json(),
"captureKeyboardEvents": settings.capture_keyboard_events,
})
}
/// The whole environment snapshot, with an already-run sync test folded in.
///
/// **Blocking, for tens of seconds.** Background executor only.
pub fn collect_report(sync_test: Option<Value>, sync_test_error: Option<String>) -> Value {
let settings = store::GeneralSettings::load();
let recordings_dir = crate::recording::recordings_dir();
let app_version = env!("CARGO_PKG_VERSION");
let report = cap_recording::diagnostics::collect_report(
cap_recording::diagnostics::DiagnosticReportArgs {
flavor: "gpui",
app_version,
settings: Some(settings_snapshot()),
permissions: Some(permissions_snapshot()),
recordings_dir: Some(recordings_dir.as_path()),
configured_max_fps: Some(settings.max_fps),
fragmented_recording: settings.crash_recovery_recording,
sync_test,
sync_test_error,
},
);
serde_json::to_value(&report).unwrap_or_else(|error| {
tracing::warn!("serializing the diagnostic report: {error}");
Value::Null
})
}
/// The `diagnostics` form field: the older, narrower shape
/// `/api/desktop/logs` formats into the Discord message. Derived from an
/// already-collected report so nothing is probed twice.
pub fn log_diagnostics_from_report(report: &Value) -> Value {
let names = |key: &str, field: &str| {
report
.get(key)
.and_then(Value::as_array)
.map(|entries| {
entries
.iter()
.filter_map(|entry| entry.get(field).and_then(Value::as_str))
.map(str::to_string)
.collect::<Vec<_>>()
})
.unwrap_or_default()
};
json!({
"system": report.get("system").cloned().unwrap_or(Value::Null),
"cameras": names("cameras", "displayName"),
"microphones": names("microphones", "name"),
"permissions": report.get("permissions").cloned().unwrap_or(Value::Null),
})
}
/// The same shape for the plain "Upload Logs" path, which has no report to
/// derive from. Deliberately narrower than [`collect_report`]: this is the
/// exact set of keys the server validates, and it skips the display and disk
/// probes that make the full report take the better part of a minute.
///
/// Still blocking (device enumeration); background executor only.
pub fn collect_log_diagnostics() -> Value {
let check = permissions::classify(
permissions::check_raw(),
permissions::AttemptedFlags::default(),
);
let cameras = if check.camera.permitted() {
cap_recording::diagnostics::collect_cameras()
.into_iter()
.map(|camera| camera.display_name)
.collect::<Vec<_>>()
} else {
Vec::new()
};
let microphones = if check.microphone.permitted() {
cap_recording::diagnostics::collect_microphones()
.into_iter()
.map(|mic| mic.name)
.collect::<Vec<_>>()
} else {
Vec::new()
};
json!({
"system": serde_json::to_value(cap_recording::diagnostics::collect_diagnostics())
.unwrap_or(Value::Null),
"cameras": cameras,
"microphones": microphones,
"permissions": permissions_snapshot(),
})
}
// ---------------------------------------------------------------------------
// Saving
// ---------------------------------------------------------------------------
pub fn reports_dir() -> PathBuf {
store::app_data_dir().join("diagnostics")
}
/// Distinguishes reports written within the same second; paired with the
/// process id in the file name so a fresh launch cannot reuse a number.
static REPORT_SEQUENCE: AtomicU64 = AtomicU64::new(0);
/// Unix seconds parsed out of one of *our* file names, if it is one.
///
/// Returns `None` for anything else in the directory -- crucially the Tauri
/// app's reports, which share this folder but are stamped `%Y%m%d-%H%M%S`.
/// Those parse as a plain integer (`20260821`) that is three orders of
/// magnitude below a real Unix timestamp, so treating them as a stamp would
/// sort every one of them last and delete them first.
fn report_file_stamp(name: &str) -> Option<u64> {
let stamp = name
.strip_prefix("cap-diagnostic-")?
.strip_suffix(".json")?
// `<secs>-<pid>-<counter>`: only the seconds order the file.
.split('-')
.next()?;
// A `%Y%m%d` stamp is 8 digits; ours is 10 and will be until 2286.
if stamp.len() < 10 {
return None;
}
stamp.parse().ok()
}
/// Falls back to modification time for files we cannot date from their name,
/// so a foreign report is ordered honestly instead of being pruned first.
fn report_sort_key(name: &str, path: &Path) -> u64 {
report_file_stamp(name).unwrap_or_else(|| {
std::fs::metadata(path)
.and_then(|meta| meta.modified())
.ok()
.and_then(|time| time.duration_since(UNIX_EPOCH).ok())
.map(|since| since.as_secs())
.unwrap_or(0)
})
}
/// Keep the newest `keep` reports. Ordered by the timestamp in the file name
/// rather than by mtime: two reports written in the same second have
/// indistinguishable mtimes on some filesystems, and the name is the thing
/// that actually orders them.
fn prune_reports(dir: &Path, keep: usize) {
let Ok(entries) = std::fs::read_dir(dir) else {
return;
};
let mut reports: Vec<_> = entries
.filter_map(|entry| {
let path = entry.ok()?.path();
let name = path.file_name()?.to_str()?;
if !path.is_file() || !name.starts_with("cap-diagnostic-") || !name.ends_with(".json") {
return None;
}
Some((report_sort_key(name, &path), name.to_string(), path))
})
.collect();
reports.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| b.1.cmp(&a.1)));
for (_, _, path) in reports.into_iter().skip(keep) {
if let Err(error) = std::fs::remove_file(&path) {
tracing::warn!(path = %path.display(), "pruning an old diagnostic report: {error}");
}
}
}
/// Write the report next to the store, prune, and hand back the path.
pub fn write_report(report: &Value) -> Result<PathBuf, String> {
write_report_into(&reports_dir(), report)
}
/// [`write_report`] with the directory lifted into a parameter, so the naming
/// and pruning are testable without writing into the real store.
fn write_report_into(dir: &Path, report: &Value) -> Result<PathBuf, String> {
let stamp = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|since| since.as_secs())
.unwrap_or(0);
write_report_at(dir, report, stamp)
}
fn write_report_at(dir: &Path, report: &Value, stamp: u64) -> Result<PathBuf, String> {
std::fs::create_dir_all(dir)
.map_err(|error| format!("Failed to create the diagnostics folder: {error}"))?;
// A run with no sidecar finishes in well under a second, so two of them
// would otherwise write the same name and the second would overwrite the
// first. The prefix and suffix stay exactly as the pruning filter expects.
let sequence = REPORT_SEQUENCE.fetch_add(1, Ordering::Relaxed);
let path = dir.join(format!(
"cap-diagnostic-{stamp}-{}-{sequence}.json",
std::process::id()
));
let json = serde_json::to_string_pretty(report)
.map_err(|error| format!("Failed to serialize the report: {error}"))?;
std::fs::write(&path, json)
.map_err(|error| format!("Failed to write {}: {error}", path.display()))?;
prune_reports(dir, KEEP_REPORTS);
Ok(path)
}
// ---------------------------------------------------------------------------
// Upload
// ---------------------------------------------------------------------------
/// POST the log (and, when there is one, the report) to
/// `/api/desktop/logs`.
///
/// Auth is optional on that route, so a signed-out user can still send a
/// diagnostic -- the bearer token is attached only when there is one, and its
/// absence is not an error.
pub async fn upload_report(
server_url: String,
token: Option<String>,
log: cap_utils::log_upload::LogBundle,
report: Option<String>,
diagnostics: Option<String>,
) -> Result<(), String> {
let context = serde_json::json!({
"schemaVersion": 1,
"app": {
"flavor": "gpui",
"version": env!("CARGO_PKG_VERSION"),
"os": std::env::consts::OS,
"binaryArchitecture": std::env::consts::ARCH,
"debugBuild": cfg!(debug_assertions),
"sourceRevision": option_env!("CAP_BUILD_REVISION"),
"sourceDirty": option_env!("CAP_BUILD_DIRTY").and_then(|value| value.parse::<bool>().ok()),
},
"operations": cap_utils::operation_diagnostics::snapshot(),
"logCoverage": &log,
"environmentCollectedAt": "upload_time",
"mediaIncluded": false,
});
// Everything leaving the machine goes through the redactor. Logs record
// whole URLs on failure (reqwest's Display and Debug both append the URL),
// and an upload failure logs a presigned S3 PUT, whose query string is a
// live write credential for up to an hour.
use cap_recording::log_redaction::scrub_log_text;
let upload = cap_utils::log_upload::prepare_upload(
log,
context,
diagnostics.as_deref(),
report.as_deref(),
scrub_log_text,
);
let mut form = reqwest::multipart::Form::new()
.text("log", upload.log)
.text("os", std::env::consts::OS)
.text("version", env!("CARGO_PKG_VERSION"))
.text("context", upload.context);
if let Some(report) = upload.report {
form = form.text("report", report);
}
if let Some(diagnostics) = upload.diagnostics {
form = form.text("diagnostics", diagnostics);
}
let mut request = reqwest::Client::new()
.post(format!("{server_url}/api/desktop/logs"))
.multipart(form);
if let Some(token) = token {
request = request.bearer_auth(token);
}
let response = request
.send()
.await
.map_err(|error| format!("Failed to upload logs: {error}"))?;
if !response.status().is_success() {
return Err(format!("Upload failed with status: {}", response.status()));
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
fn temp_dir(tag: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!(
"cap-gpui-diagnostics-{tag}-{}-{:?}",
std::process::id(),
SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap()
.as_nanos()
));
std::fs::create_dir_all(&dir).unwrap();
dir
}
#[test]
fn progress_lines_parse_into_their_four_shapes() {
assert_eq!(
parse_progress_line(r#"{"type":"Stage","stage":"recording","mode":"studio"}"#),
ProgressLine::Stage {
stage: "recording".to_string(),
mode: Some("studio".to_string()),
}
);
// The final stage carries a null mode.
assert_eq!(
parse_progress_line(r#"{"type":"Stage","stage":"done","mode":null}"#),
ProgressLine::Stage {
stage: "done".to_string(),
mode: None,
}
);
assert_eq!(
parse_progress_line(r#"{"type":"Report","report":{"verdict":"pass"}}"#),
ProgressLine::Report(json!({ "verdict": "pass" }))
);
assert_eq!(
parse_progress_line(r#"{"type":"Error","error":"no display"}"#),
ProgressLine::Error("no display".to_string())
);
}
/// Nothing on that pipe is allowed to be fatal: a blank line, a stray log
/// line, a message type from a newer CLI, or a required field missing.
#[test]
fn unparseable_progress_lines_are_ignored_not_fatal() {
for line in [
"",
" ",
"INFO recording started",
"{not json",
r#"{"type":"Heartbeat","at":1}"#,
r#"{"stage":"recording"}"#,
// Required fields missing or of the wrong type.
r#"{"type":"Stage","mode":"studio"}"#,
r#"{"type":"Stage","stage":7}"#,
r#"{"type":"Report"}"#,
r#"{"type":"Error"}"#,
r#"{"type":"Error","error":{"message":"x"}}"#,
] {
assert_eq!(
parse_progress_line(line),
ProgressLine::Unknown,
"expected {line:?} to be ignored"
);
}
}
#[test]
fn the_cli_arguments_follow_the_options() {
assert_eq!(
sync_test_args(&SyncTestOptions::default()),
[
"selftest",
"av-sync",
"--progress-json",
"--discard-recordings",
"--mode",
"both",
"--duration",
"20"
]
);
assert_eq!(
sync_test_args(&SyncTestOptions {
mode: SyncMode::Instant,
microphone: true,
duration_secs: 5,
}),
[
"selftest",
"av-sync",
"--progress-json",
"--discard-recordings",
"--mode",
"instant",
"--duration",
"5",
"--mic"
]
);
}
/// The app never surfaces the recorded project, so every run asks the CLI
/// to discard it; without this a non-pass verdict leaves a full screen
/// recording in temp that nothing here ever cleans up.
#[test]
fn every_run_discards_the_recording() {
for mode in SyncMode::ALL {
let args = sync_test_args(&SyncTestOptions {
mode: *mode,
..SyncTestOptions::default()
});
assert!(
args.iter().any(|arg| arg == "--discard-recordings"),
"{mode:?} did not discard its recording"
);
}
}
/// Two runs must not be able to overlap: the second would take the screen
/// and the audio device out from under the first.
#[test]
fn the_run_guard_admits_one_diagnostic_at_a_time() {
let first = RunGuard::acquire().expect("the first run takes the guard");
assert_eq!(RunGuard::acquire().err().as_deref(), Some(ALREADY_RUNNING));
drop(first);
// Released on drop, including the drop of an abandoned run future.
let second = RunGuard::acquire().expect("the guard is free once released");
drop(second);
assert!(RunGuard::acquire().is_ok());
}
/// The override wins over every probe, and an override pointing at
/// nothing resolves to nothing rather than silently falling through to
/// some other build's binary.
#[test]
fn the_sidecar_override_wins_and_does_not_fall_through() {
let dir = temp_dir("override");
let binary = dir.join("cap");
std::fs::write(&binary, b"#!/bin/sh\n").unwrap();
// A bundle whose sidecar would otherwise win.
let bundle = dir.join("Cap.app");
std::fs::create_dir_all(bundle.join("Contents/MacOS")).unwrap();
std::fs::write(
bundle.join("Contents/MacOS").join(selftest_bin_name()),
b"installed",
)
.unwrap();
assert_eq!(
resolve_selftest_binary_in(Some(binary.clone()), None, Some(&bundle), None),
Some(binary)
);
assert_eq!(
resolve_selftest_binary_in(Some(dir.join("missing")), None, Some(&bundle), None),
None
);
// Nothing anywhere is `None`, not a panic and not a guess.
let empty = dir.join("empty");
std::fs::create_dir_all(&empty).unwrap();
assert_eq!(
resolve_selftest_binary_in(None, Some(&empty), None, Some(&empty)),
None
);
std::fs::remove_dir_all(&dir).ok();
}
/// The order the run has to follow: the binary shipped next to this build,
/// then the installed app, then the dev checkout. `cap-cli` beats a
/// bare `cap` inside the same directory.
#[test]
fn the_sidecar_probe_walks_from_this_build_outwards() {
let root = temp_dir("probe");
let exe_dir = root.join("Cap.app/Contents/Resources/gpui");
let bundle = root.join("Installed.app");
let installed = bundle.join("Contents/MacOS");
let target = root.join("target/debug");
for dir in [&exe_dir, &installed, &target] {
std::fs::create_dir_all(dir).unwrap();
}
// Only the dev checkout has one.
std::fs::write(target.join(cap_bin_name()), b"dev").unwrap();
assert_eq!(
resolve_selftest_binary_in(None, Some(&exe_dir), Some(&bundle), Some(&root)),
cfg!(debug_assertions).then(|| target.join(cap_bin_name()))
);
// The installed app beats the dev checkout.
std::fs::write(installed.join(selftest_bin_name()), b"installed").unwrap();
assert_eq!(
resolve_selftest_binary_in(None, Some(&exe_dir), Some(&bundle), Some(&root)),
Some(installed.join(selftest_bin_name()))
);
// A binary next to this build beats both, and the sidecar name beats
// the bare `cap` in the same folder.
std::fs::write(exe_dir.join(cap_bin_name()), b"adjacent").unwrap();
assert_eq!(
resolve_selftest_binary_in(None, Some(&exe_dir), Some(&bundle), Some(&root)),
Some(exe_dir.join(cap_bin_name()))
);
std::fs::write(exe_dir.join(selftest_bin_name()), b"sidecar").unwrap();
assert_eq!(
resolve_selftest_binary_in(None, Some(&exe_dir), Some(&bundle), Some(&root)),
Some(exe_dir.join(selftest_bin_name()))
);
std::fs::remove_dir_all(&root).ok();
}
/// The bundle layout: an app-staged build finds the sidecar one directory
/// up, in `Contents/MacOS`, where Tauri puts an `externalBin`.
#[test]
fn the_sidecar_probe_looks_into_the_bundle_siblings() {
let root = temp_dir("bundle");
let contents = root.join("Cap.app/Contents");
let exe_dir = contents.join("Resources");
let macos = contents.join("MacOS");
std::fs::create_dir_all(&exe_dir).unwrap();
std::fs::create_dir_all(&macos).unwrap();
std::fs::write(macos.join(selftest_bin_name()), b"sidecar").unwrap();
assert_eq!(
resolve_selftest_binary_in(None, Some(&exe_dir), None, None),
Some(exe_dir.join("../MacOS").join(selftest_bin_name()))
);
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn only_the_five_newest_reports_survive() {
let dir = temp_dir("prune");
// Real unix-second stamps: a shorter number is not one of ours, and
// `report_file_stamp` deliberately declines to read it as seconds.
for stamp in [1_755_780_000_u64, 1_755_780_001, 1_755_780_002] {
std::fs::write(dir.join(format!("cap-diagnostic-{stamp}.json")), b"{}").unwrap();
}
for stamp in [
1_755_780_003_u64,
1_755_780_004,
1_755_780_005,
1_755_780_006,
] {
std::fs::write(dir.join(format!("cap-diagnostic-{stamp}.json")), b"{}").unwrap();
}
// Files that are not reports are never touched.
std::fs::write(dir.join("notes.txt"), b"keep me").unwrap();
prune_reports(&dir, KEEP_REPORTS);
let mut left: Vec<_> = std::fs::read_dir(&dir)
.unwrap()
.map(|entry| entry.unwrap().file_name().to_string_lossy().to_string())
.collect();
left.sort();
assert_eq!(
left,
[
"cap-diagnostic-1755780002.json",
"cap-diagnostic-1755780003.json",
"cap-diagnostic-1755780004.json",
"cap-diagnostic-1755780005.json",
"cap-diagnostic-1755780006.json",
"notes.txt",
]
);
std::fs::remove_dir_all(&dir).ok();
}
/// Reports written in the same second get different names, and the
/// uniquifier does not disturb the ordering the pruning reads off the name.
#[test]
fn reports_in_the_same_second_do_not_collide() {
let dir = temp_dir("collide");
let at = 1_792_431_796;
let first = write_report_at(&dir, &json!({ "first": true }), at).unwrap();
let second = write_report_at(&dir, &json!({ "second": true }), at).unwrap();
assert_ne!(first, second);
assert!(first.exists() && second.exists());
for path in [&first, &second] {
let name = path.file_name().unwrap().to_str().unwrap();
assert!(name.starts_with("cap-diagnostic-") && name.ends_with(".json"));
}
// Both parse back to the same second, so pruning still orders by time
// first and falls back to the name.
let stamp = |path: &Path| report_file_stamp(path.file_name().unwrap().to_str().unwrap());
assert_eq!(stamp(&first), Some(at));
assert_eq!(stamp(&second), Some(at));
std::fs::remove_dir_all(&dir).ok();
}
/// The Tauri app writes its reports into this same folder with a
/// `%Y%m%d-%H%M%S` stamp. Parsed as an integer that is `20260821` -- three
/// orders of magnitude below a real Unix timestamp -- so treating it as
/// one would sort every Tauri report last and prune it first.
#[test]
fn the_other_apps_reports_are_not_pruned_first() {
let dir = temp_dir("foreign");
let foreign = dir.join("cap-diagnostic-20260821-143000.json");
std::fs::write(&foreign, "{}").unwrap();
let ours = write_report_into(&dir, &json!({ "ours": true })).unwrap();
assert_eq!(
report_file_stamp("cap-diagnostic-20260821-143000.json"),
None,
"a foreign stamp must not be read as unix seconds"
);
let foreign_key = report_sort_key("cap-diagnostic-20260821-143000.json", &foreign);
let ours_key = report_sort_key(ours.file_name().unwrap().to_str().unwrap(), &ours);
assert!(
foreign_key.abs_diff(ours_key) < 60,
"a foreign report falls back to mtime and sorts alongside ours, \
not at the bottom (foreign {foreign_key}, ours {ours_key})"
);
prune_reports(&dir, KEEP_REPORTS);
assert!(foreign.exists(), "pruning deleted the other app's report");
std::fs::remove_dir_all(&dir).ok();
}
#[test]
fn stage_labels_read_as_sentences() {
assert_eq!(
stage_label("recording", Some("studio")),
"Recording the studio test..."
);
assert_eq!(
stage_label("analyzing", Some("instant")),
"Analyzing the instant recording..."
);
assert_eq!(stage_label("done", None), "Wrapping up the sync test...");
assert_eq!(stage_label(START_STAGE, None), "Starting the diagnostic...");
assert_eq!(
stage_label(COLLECT_STAGE, None),
"Collecting system information..."
);
assert_eq!(stage_label(CANCEL_STAGE, Some("studio")), "Cancelling...");
// An unknown stage still says something rather than nothing.
assert_eq!(stage_label("uploading", None), "uploading...");
}
#[test]
fn urls_keep_their_host_and_lose_their_credentials() {
assert_eq!(
redact_url_credentials("https://cap.so"),
"https://cap.so".to_string()
);
assert_eq!(
redact_url_credentials("https://user:[email protected]/api"),
"https://***@cap.so/api".to_string()
);
}
#[test]
fn the_upload_diagnostics_are_derived_from_the_report() {
let report = json!({
"system": { "macosVersion": { "displayName": "macOS 26.0" } },
"cameras": [{ "displayName": "FaceTime HD" }, { "deviceId": "x" }],
"microphones": [{ "name": "MacBook Pro Microphone" }],
"permissions": { "screenRecording": "granted" },
});
assert_eq!(
log_diagnostics_from_report(&report),
json!({
"system": { "macosVersion": { "displayName": "macOS 26.0" } },
"cameras": ["FaceTime HD"],
"microphones": ["MacBook Pro Microphone"],
"permissions": { "screenRecording": "granted" },
})
);
// A report missing every key still produces the shape the server
// validates.
assert_eq!(
log_diagnostics_from_report(&json!({})),
json!({
"system": null,
"cameras": [],
"microphones": [],
"permissions": null,
})
);
}
}