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.

9.2 KB
Raw Blame
use std::path::PathBuf;

use anyhow::{anyhow, Result};
use tracing::info;

use crate::{
    invocation_context::context,
    sourcemaps::{
        args::{ReleaseArgs, ReleaseMode},
        content::SourceMapFile,
        inject::get_release_for_maps,
    },
};

#[derive(clap::Args)]
pub struct CloneArgs {
    /// The path of the minified source map
    #[arg(short, long)]
    pub minified_map_path: PathBuf,

    /// The path of the composed source map
    #[arg(short, long)]
    pub composed_map_path: PathBuf,

    #[clap(flatten)]
    pub release: ReleaseArgs,

    /// How the release is associated with exceptions. `event` is the default. It stamps nothing
    /// and leaves the maps release-independent. Each event then resolves its own release from the
    /// app version and namespace the SDK already sends. The coordinates you pass to
    /// `hermes upload` must match the app's. `symbol-set` stamps the release id into the source
    /// maps instead, so the upload binds the symbol set to that release. Also settable via
    /// `POSTHOG_RELEASE_MODE`.
    #[arg(
        long,
        env = "POSTHOG_RELEASE_MODE",
        value_enum,
        default_value = "event"
    )]
    pub release_mode: ReleaseMode,
}

pub fn clone(args: &CloneArgs) -> Result<()> {
    context().capture_command_invoked("hermes_clone");
    clone_maps(args)
}

fn clone_maps(args: &CloneArgs) -> Result<()> {
    let CloneArgs {
        minified_map_path,
        composed_map_path,
        release,
        release_mode,
    } = args;

    let mut minified_map = SourceMapFile::load(minified_map_path).map_err(|e| {
        anyhow!(
            "Failed to load minified map at '{}': {}",
            minified_map_path.display(),
            e
        )
    })?;

    let mut composed_map = SourceMapFile::load(composed_map_path).map_err(|e| {
        anyhow!(
            "Failed to load composed map at '{}': {}",
            composed_map_path.display(),
            e
        )
    })?;

    // Event mode resolves no release here. `hermes upload` creates the release row that the
    // server resolves an event's app metadata onto. The maps must stay without a release id.
    // A map id comes from the map's own content, so one symbol set serves every release.
    // Without this, a later release collides with the release that uploaded the map first.
    let release_id = match release_mode {
        ReleaseMode::Event => None,
        // Without release flags, a map that already carries a release resolves none, and that
        // release stays. `hermes inject` stamped it, and the upload binds the symbol set to it.
        ReleaseMode::SymbolSet => {
            get_release_for_maps(minified_map_path, release.clone(), [&minified_map])?
                .map(|r| r.id.to_string())
                .or_else(|| minified_map.get_release_id())
        }
    };

    // The flow here differs from plain sourcemap injection a bit - here, we don't ever
    // overwrite the chunk ID, because at this point in the build process, we no longer
    // control what chunk ID is inside the compiled hermes byte code bundle. So, instead,
    // we permit e.g. uploading the same chunk ID's to two different posthog envs with two
    // different release ID's, or arbitrarily re-running the upload command, but if someone
    // tries to run `clone` twice, changing release but not posthog env, we'll error out. The
    // correct way to upload the same set of artefacts to the same posthog env as part of
    // two different releases is, 1, not to, but failing that, 2, to re-run the bundling process
    if minified_map.get_release_id() != release_id {
        minified_map.set_release_id(release_id.clone());
        minified_map.save()?;
    }

    clone_metadata(&minified_map, &mut composed_map);

    composed_map.save()?;
    info!(
        "Successfully cloned metadata to {}",
        composed_map.inner.path.display()
    );

    info!("Finished cloning metadata");
    Ok(())
}

/// Carry the chunk identity and release from the packager map into the hermes-composed map.
/// Expo stamps only a `debugId` on the packager map, so the id must come from the upload
/// fallback — reading the stamped chunk id alone leaves the composed map id-less and the
/// upload silently empty.
pub fn clone_metadata(minified_map: &SourceMapFile, composed_map: &mut SourceMapFile) {
    if let Some(chunk_id) = minified_map.get_upload_chunk_id() {
        composed_map.set_chunk_id(Some(chunk_id));
    }

    // Copy the id even when there is none. A build that changes to event release mode then
    // clears the id a previous run stamped. Without this, the composed map uploads still bound
    // to that release.
    composed_map.set_release_id(minified_map.get_release_id());
}

#[cfg(test)]
mod test {
    use super::{clone_maps, clone_metadata, CloneArgs};
    use crate::sourcemaps::args::{ReleaseArgs, ReleaseMode};
    use crate::sourcemaps::content::SourceMapFile;
    use crate::utils::files::SourceFile;
    use std::path::PathBuf;

    fn map_from(json: serde_json::Value) -> SourceMapFile {
        SourceMapFile {
            inner: SourceFile::new(
                PathBuf::from("main.jsbundle.map"),
                serde_json::from_value(json).unwrap(),
            ),
        }
    }

    #[test]
    fn clone_carries_a_debug_id_only_packager_map_into_the_composed_map() {
        // The Expo metro plugin stamps only `debugId` on the packager map. Clone must land
        // that id on the composed map, or `hermes upload` finds no id and uploads nothing
        // while the build stays green.
        let minified = map_from(serde_json::json!({
            "version": 3,
            "mappings": "AAAA",
            "sources": ["App.js"],
            "names": [],
            "debugId": "c96bfa94-ca84-4f98-8d5e-f15adba692ca",
            "release_id": "11111111-2222-4333-8444-555555555555",
        }));
        let mut composed = map_from(serde_json::json!({
            "version": 3,
            "mappings": "AAAA",
            "sources": ["App.js"],
            "names": [],
            "x_hermes_function_offsets": {},
        }));

        clone_metadata(&minified, &mut composed);

        assert_eq!(
            composed.get_chunk_id().as_deref(),
            Some("c96bfa94-ca84-4f98-8d5e-f15adba692ca")
        );
        assert_eq!(
            composed.get_release_id().as_deref(),
            Some("11111111-2222-4333-8444-555555555555")
        );
    }

    #[test]
    fn clone_clears_a_release_id_the_composed_map_still_carries() {
        // A build that changes to event release mode still has the previous run's release id on
        // the composed map. To copy only the ids that exist would upload it bound to that
        // release. That is the collision event mode prevents.
        let minified = map_from(serde_json::json!({
            "version": 3,
            "mappings": "AAAA",
            "sources": ["App.js"],
            "names": [],
            "debugId": "c96bfa94-ca84-4f98-8d5e-f15adba692ca",
        }));
        let mut composed = map_from(serde_json::json!({
            "version": 3,
            "mappings": "AAAA",
            "sources": ["App.js"],
            "names": [],
            "release_id": "11111111-2222-4333-8444-555555555555",
            "x_hermes_function_offsets": {},
        }));

        clone_metadata(&minified, &mut composed);

        assert_eq!(composed.get_release_id(), None);
    }

    #[test]
    fn symbol_set_clone_without_release_flags_keeps_the_stamped_release() {
        // `hermes inject` stamps the release into the packager map. A clone without release
        // flags resolves none, and must not clear it, or the upload binds to no release.
        let dir = tempfile::tempdir().unwrap();
        let minified_map_path = dir.path().join("main.jsbundle.map");
        let composed_map_path = dir.path().join("main.hbc.map");
        std::fs::write(
            &minified_map_path,
            serde_json::json!({
                "version": 3,
                "mappings": "AAAA",
                "sources": ["App.js"],
                "names": [],
                "chunk_id": "c96bfa94-ca84-4f98-8d5e-f15adba692ca",
                "release_id": "11111111-2222-4333-8444-555555555555",
            })
            .to_string(),
        )
        .unwrap();
        std::fs::write(
            &composed_map_path,
            serde_json::json!({
                "version": 3,
                "mappings": "AAAA",
                "sources": ["App.js"],
                "names": [],
                "x_hermes_function_offsets": {},
            })
            .to_string(),
        )
        .unwrap();

        clone_maps(&CloneArgs {
            minified_map_path: minified_map_path.clone(),
            composed_map_path: composed_map_path.clone(),
            release: ReleaseArgs {
                name: None,
                version: None,
                build: None,
                info_plist: None,
                skip_release_on_fail: true,
            },
            release_mode: ReleaseMode::SymbolSet,
        })
        .unwrap();

        for path in [minified_map_path, composed_map_path] {
            assert_eq!(
                SourceMapFile::load(&path)
                    .unwrap()
                    .get_release_id()
                    .as_deref(),
                Some("11111111-2222-4333-8444-555555555555")
            );
        }
    }
}