Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

7.3 KB
Raw Blame
use std::io::Cursor;
use std::{
    fs,
    path::{Path, PathBuf},
};

use anyhow::{Context, Result};
use clap::Subcommand;
use posthog_symbol_data::{
    read_symbol_data, AppleDsym, ElfDebugInfo, HermesMap, ProguardMapping, SourceAndMap,
    SymbolDataError,
};
use tracing::info;

use crate::{api::symbol_sets, invocation_context::context};

#[derive(Subcommand)]
pub enum SymbolSetsSubcommand {
    /// Upload native debug symbols from a directory. ELF executables, shared
    /// libraries, and `objcopy --only-keep-debug` companions with debug info are
    /// uploaded, as are Apple `.dSYM` bundles (macOS only — needs `dwarfdump`
    /// from Xcode); other files are reported and skipped.
    Upload(crate::debug_symbols::upload::Args),
    /// Download and extract a symbol set (sourcemap, hermes, proguard, or dSYM)
    Download(DownloadArgs),
    /// Extract a local symbol set binary file (decompress and split)
    Extract(ExtractArgs),
}

#[derive(clap::Args, Clone)]
pub struct DownloadArgs {
    /// Symbol set ID to download
    #[arg(long, required_unless_present = "ref")]
    pub id: Option<String>,

    /// Symbol set ref to download (looked up by ref)
    #[arg(long = "ref", required_unless_present = "id")]
    pub r#ref: Option<String>,

    /// Output directory for extracted files
    #[arg(short, long, default_value = ".")]
    pub output: PathBuf,
}

#[derive(clap::Args, Clone)]
pub struct ExtractArgs {
    /// Path to the symbol set binary file
    pub file: PathBuf,

    /// Output directory for extracted files
    #[arg(short, long, default_value = ".")]
    pub output: PathBuf,
}

pub fn download(args: &DownloadArgs) -> Result<()> {
    context().capture_command_invoked("symbolset_download");

    let (id, base_name) = match (&args.id, &args.r#ref) {
        (Some(id), _) => (id.clone(), id.clone()),
        (_, Some(r)) => {
            info!("Resolving ref: {r}");
            let id = symbol_sets::resolve_ref(r)?;
            let base_name = derive_base_name(r);
            (id, base_name)
        }
        _ => anyhow::bail!("Either --id or --ref must be provided"),
    };

    info!("Downloading symbol set {id}");
    let data = symbol_sets::download_bytes(&id)?;
    info!("Downloaded {} bytes", data.len());

    extract_symbol_data(&data, &base_name, &args.output)
}

pub fn extract(args: &ExtractArgs) -> Result<()> {
    let data =
        fs::read(&args.file).context(format!("Failed to read file {}", args.file.display()))?;
    info!("Read {} bytes from {}", data.len(), args.file.display());

    let base_name = derive_base_name(
        args.file
            .file_name()
            .and_then(|n| n.to_str())
            .unwrap_or("symbol_set"),
    );
    extract_symbol_data(&data, &base_name, &args.output)
}

fn extract_symbol_data(data: &[u8], base_name: &str, output: &Path) -> Result<()> {
    fs::create_dir_all(output).context("Failed to create output directory")?;

    // Try each type — read_symbol_data returns InvalidDataType when the
    // header type field doesn't match, so we use that to fall through.
    if let Ok(parsed) = read_symbol_data::<SourceAndMap>(data) {
        let source_path = output.join(format!("{base_name}.js"));
        fs::write(&source_path, &parsed.minified_source).context("Failed to write source file")?;
        info!("Wrote {}", source_path.display());

        let map_path = output.join(format!("{base_name}.js.map"));
        fs::write(&map_path, &parsed.sourcemap).context("Failed to write sourcemap file")?;
        info!("Wrote {}", map_path.display());

        crate::safe_println!("Extracted source and sourcemap to {}", output.display());
        return Ok(());
    }

    if let Ok(parsed) = read_symbol_data::<HermesMap>(data) {
        let map_path = output.join(format!("{base_name}.hbc.map"));
        fs::write(&map_path, &parsed.sourcemap).context("Failed to write hermes sourcemap")?;
        info!("Wrote {}", map_path.display());

        crate::safe_println!("Extracted hermes sourcemap to {}", output.display());
        return Ok(());
    }

    if let Ok(parsed) = read_symbol_data::<ProguardMapping>(data) {
        let map_path = output.join(format!("{base_name}.txt"));
        fs::write(&map_path, &parsed.content).context("Failed to write proguard mapping")?;
        info!("Wrote {}", map_path.display());

        crate::safe_println!("Extracted proguard mapping to {}", output.display());
        return Ok(());
    }

    if let Ok(parsed) = read_symbol_data::<ElfDebugInfo>(data) {
        // Same ZIP layout as dSYM uploads: the binary as `dwarf` at the root
        // plus an optional `__source/` bundle.
        extract_dsym_zip(&parsed.data, base_name, output)?;
        return Ok(());
    }

    match read_symbol_data::<AppleDsym>(data) {
        Ok(parsed) => {
            extract_dsym_zip(&parsed.data, base_name, output)?;
            Ok(())
        }
        Err(SymbolDataError::InvalidDataType(actual, _)) => {
            anyhow::bail!("Unknown symbol data type: {actual}")
        }
        Err(e) => {
            anyhow::bail!("Failed to parse symbol set: {e}")
        }
    }
}

/// Extract a dSYM ZIP archive (DWARF binary + optional source files).
fn extract_dsym_zip(zip_data: &[u8], base_name: &str, output: &Path) -> Result<()> {
    use std::path::Component;

    let dsym_dir = output.join(base_name);
    fs::create_dir_all(&dsym_dir).context("Failed to create dSYM output directory")?;

    let reader = Cursor::new(zip_data);
    let mut archive = zip::ZipArchive::new(reader).context("Failed to read dSYM ZIP archive")?;

    for i in 0..archive.len() {
        let mut file = archive.by_index(i).context("Failed to read ZIP entry")?;

        // Sanitize: keep only Normal components, stripping .., ., and root prefixes
        let safe_name: PathBuf = std::path::Path::new(file.name())
            .components()
            .filter_map(|c| match c {
                Component::Normal(part) => Some(part),
                _ => None,
            })
            .collect();

        if safe_name.as_os_str().is_empty() {
            continue;
        }

        let out_path = dsym_dir.join(&safe_name);

        if let Some(parent) = out_path.parent() {
            fs::create_dir_all(parent)?;
        }

        let mut out_file = fs::File::create(&out_path)
            .context(format!("Failed to create {}", out_path.display()))?;
        std::io::copy(&mut file, &mut out_file)?;
        info!("Wrote {}", out_path.display());
    }

    crate::safe_println!(
        "Extracted dSYM ({} files) to {}",
        archive.len(),
        dsym_dir.display()
    );
    Ok(())
}

/// Extract a reasonable base filename from the symbol set ref.
fn derive_base_name(ref_str: &str) -> String {
    let name = std::path::Path::new(ref_str)
        .file_name()
        .and_then(|n| n.to_str())
        .unwrap_or(ref_str);
    let name = if name == ".." || name == "." {
        "symbol_set"
    } else {
        name
    };
    // Strip common extensions so we can re-add the correct ones
    let name = name
        .strip_suffix(".js.map")
        .or_else(|| name.strip_suffix(".hbc.map"))
        .or_else(|| name.strip_suffix(".map"))
        .or_else(|| name.strip_suffix(".js"))
        .or_else(|| name.strip_suffix(".txt"))
        .or_else(|| name.strip_suffix(".dSYM"))
        .unwrap_or(name);

    if name.is_empty() {
        "symbol_set".to_string()
    } else {
        name.to_string()
    }
}