: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
use crate::{
api::symbol_sets::SymbolSetUpload,
sourcemaps::{
args::ReleaseMode,
content::{get_injected_release_id, MinifiedSourceFile, SourceMapContent, SourceMapFile},
},
utils::files::content_hash,
};
use anyhow::{anyhow, Context, Result};
use posthog_symbol_data::{write_symbol_data, SourceAndMap};
use serde_json::Value;
use std::borrow::Cow;
use tracing::{debug, info, warn};
use walkdir::DirEntry;
#[derive(Debug)]
// Source pairs are the fundamental unit of a frontend symbol set
pub struct SourcePair {
pub source: MinifiedSourceFile,
pub sourcemap: SourceMapFile,
}
impl SourcePair {
pub fn has_chunk_id(&self) -> bool {
// Minified chunks are the source of truth for their ID's, not sourcemaps,
// because sometimes sourcemaps are shared across multiple chunks.
self.get_chunk_id().is_some()
}
pub fn get_chunk_id(&self) -> Option<String> {
self.source.get_chunk_id()
}
/// Debug id already present in the pair, if any. The chunk's comment is authoritative
/// (sourcemaps can be shared across chunks); the sourcemap's field is only a fallback.
pub fn get_debug_id(&self) -> Option<String> {
let source_debug_id = self.source.get_debug_id();
let sourcemap_debug_id = self.sourcemap.get_debug_id();
if let (Some(source_id), Some(map_id)) = (&source_debug_id, &sourcemap_debug_id) {
if source_id != map_id {
warn!(
"debug id mismatch for {}: chunk has {}, sourcemap has {} — using the chunk's",
self.source.inner.path.display(),
source_id,
map_id
);
}
}
source_debug_id.or(sourcemap_debug_id)
}
pub fn has_release_id(&self) -> bool {
self.sourcemap.has_release_id()
}
pub fn get_release_id(&self) -> Option<String> {
self.sourcemap.get_release_id()
}
/// The release id embedded in the source's injected snippet (event release mode),
/// as opposed to `get_release_id`, which reads the one stamped into the sourcemap.
pub fn get_injected_release_id(&self) -> Option<String> {
let chunk_id = self.get_chunk_id()?;
get_injected_release_id(&self.source.inner.content, &chunk_id)
}
pub fn remove_chunk_id(&mut self, chunk_id: String) -> Result<()> {
if self.get_chunk_id().as_ref() != Some(&chunk_id) {
return Err(anyhow!("Chunk ID mismatch"));
}
let adjustment = self.source.remove_chunk_id(chunk_id)?;
self.sourcemap.apply_adjustment(adjustment)?;
self.sourcemap.set_chunk_id(None);
Ok(())
}
pub fn update_chunk_id(
&mut self,
previous_chunk_id: String,
new_chunk_id: String,
) -> Result<()> {
self.remove_chunk_id(previous_chunk_id)?;
self.add_chunk_id(new_chunk_id, None)?;
Ok(())
}
pub fn add_chunk_id(&mut self, chunk_id: String, release_id: Option<&str>) -> Result<()> {
if self.has_chunk_id() {
return Err(anyhow!("Chunk ID already set"));
}
let adjustment = self.source.set_chunk_id(&chunk_id, release_id)?;
// In cases where sourcemaps are shared across multiple chunks,
// we should only apply the adjustment if the sourcemap doesn't
// have a chunk ID set (since otherwise, it's already been adjusted)
if self.sourcemap.get_chunk_id().is_none() {
self.sourcemap.apply_adjustment(adjustment)?;
self.sourcemap.set_chunk_id(Some(chunk_id));
}
Ok(())
}
pub fn set_release_id(&mut self, release_id: Option<String>) {
self.sourcemap.set_release_id(release_id);
}
pub fn save(&self) -> Result<()> {
self.source.save()?;
self.sourcemap.save()?;
Ok(())
}
}
pub fn read_pairs(
selection: impl Iterator<Item = DirEntry>,
prefix: &Option<String>,
) -> Vec<SourcePair> {
let mut seen_paths = std::collections::HashSet::new();
let pairs = selection
.filter_map(|entry| {
let path = entry.path();
let entry_path = path
.canonicalize()
.context("failed to canonicalize path")
.map_err(|e| warn!("skip: {e:?}"))
.ok()?;
// Overlapping selection roots yield the same file more than once; a second
// pass would stamp a fresh chunk id over the first and upload a stale copy.
if !seen_paths.insert(entry_path.clone()) {
return None;
}
let source = MinifiedSourceFile::load(&entry_path)
.context("failed to read source")
.map_err(|e| warn!("skip: {e:?}"))
.ok()?;
let sourcemap_path = source
.get_sourcemap_path(prefix)
.context("no sourcemap found")
.map_err(|e| info!("skip: {e:?}"))
.ok()
.flatten()?;
let sourcemap = SourceMapFile::load(&sourcemap_path)
.context("failed to read sourcemap")
.map_err(|e| warn!("skip: {e:?}"))
.ok()?;
debug!("adding pair for {}", entry_path.display());
Some(SourcePair { source, sourcemap })
})
.collect::<Vec<SourcePair>>();
info!("found {} pairs", pairs.len());
pairs
}
// The control characters keep the token from matching anything a bundler writes.
const FILE_PATH_TOKEN: &str = "\u{1}file-path\u{1}";
/// Replace every script file path in `text` with one token, for the event-mode content hash.
/// With content-hashed file names every release renames every chunk, because each chunk carries
/// the release id, and the names appear inside chunks: imports, `sourceMappingURL` and the map's
/// `file`. A path is a run of path characters that ends in `.js`, `.mjs` or `.cjs` with no
/// identifier character after it. The result depends only on `text`, so one chunk hashes the same
/// way in every upload.
///
/// A stored symbol set that this lets the server keep resolves frames the same way: the hash still
/// covers the mappings, so a path that changes length changes the hash. A function named after a
/// run, such as `{"one.js"(){}}`, could only go stale if one chunk id covered two builds whose code
/// differs inside a run. No chunk id does: `@posthog/rollup-plugin` derives its ids before imports
/// become file names, and every other chunk id covers the final content.
fn without_file_paths(text: &str) -> Cow<'_, str> {
let bytes = text.as_bytes();
let mut normalized = String::new();
let mut copied = 0;
let mut searched = 0;
while let Some(found) = text[searched..].find("js") {
let js = searched + found;
let end = js + 2;
searched = end;
let extension = if js >= 1 && bytes[js - 1] == b'.' {
js - 1
} else if js >= 2 && matches!(bytes[js - 1], b'm' | b'c') && bytes[js - 2] == b'.' {
js - 2
} else {
continue;
};
if text[end..].chars().next().is_some_and(is_identifier_char) {
continue;
}
// Walking back stops at what was already replaced, which keeps the scan linear.
let Some(start) = text[copied..extension]
.char_indices()
.rev()
.take_while(|(_, c)| is_path_char(*c))
.last()
.map(|(offset, _)| copied + offset)
else {
continue;
};
if normalized.is_empty() {
normalized.reserve(text.len());
}
normalized.push_str(&text[copied..start]);
normalized.push_str(FILE_PATH_TOKEN);
copied = end;
}
if normalized.is_empty() {
return Cow::Borrowed(text);
}
normalized.push_str(&text[copied..]);
Cow::Owned(normalized)
}
fn is_identifier_char(c: char) -> bool {
c.is_alphanumeric() || matches!(c, '_' | '$')
}
fn is_path_char(c: char) -> bool {
is_identifier_char(c) || matches!(c, '-' | '.' | '/' | '\\' | '~' | '@' | '+')
}
/// Replace the file path in the map's `file` field, the only field that names the chunk rather
/// than its sources.
fn without_file_path_in_file_field(map: &mut SourceMapContent) {
if let Some(Value::String(file)) = map.fields.get_mut("file") {
if let Cow::Owned(normalized) = without_file_paths(file) {
*file = normalized;
}
}
}
impl SourcePair {
/// Turn the pair into an upload payload. The payload always carries the injected artifact;
/// only the content hash depends on the mode.
///
/// In event mode the hash is computed over the pair with the injection undone (snippet and
/// chunk-id comment removed, sourcemap adjustment reversed), because the embedded release id
/// changes every release while the chunk id does not. The server keys its skip-or-conflict
/// decision on this hash per chunk id, so hashing the embedded id would re-upload every chunk
/// on every release.
///
/// The hash does cover which snippet variant is embedded. The release variant is longer, so it
/// shifts every generated column in the uploaded sourcemap. Two builds of one unchanged chunk,
/// one before a release could be resolved and one after, therefore ship different maps. Equal
/// hashes would make the server keep the first map and resolve later frames to the wrong
/// source positions.
///
/// The hash also leaves out script file paths, which change with every release when the
/// bundler names chunks by content (see `without_file_paths`).
///
/// In symbol-set mode no hash is set and the upload layer hashes the raw payload, matching
/// the hashes the server already stores for previous uploads.
pub fn into_upload(mut self, release_mode: ReleaseMode) -> Result<SymbolSetUpload> {
let injected_chunk_id = self.get_chunk_id();
let chunk_id = injected_chunk_id.clone().or_else(|| self.get_debug_id()).ok_or_else(|| {
anyhow!(
"Chunk ID or debug ID not found in {}. Run 'sourcemap inject' before 'sourcemap upload', enable native debug IDs in the bundler, or use 'sourcemap process' to do both.",
self.source.inner.path.display()
)
})?;
let release_id = self.sourcemap.get_release_id();
let source_content = self.source.inner.content.clone();
let sourcemap_content = serde_json::to_string(&self.sourcemap.inner.content)?;
let content_hash = match release_mode {
ReleaseMode::Event => {
let identity_variant: &[u8] = if injected_chunk_id.is_some() {
// Read the variant before the removal, which erases the evidence.
let snippet_variant: &[u8] = if self.source.has_release_snippet(&chunk_id) {
b"with-release"
} else {
b"chunk-id-only"
};
self.remove_chunk_id(chunk_id.clone())?;
snippet_variant
} else {
b"native-debug-id"
};
without_file_path_in_file_field(&mut self.sourcemap.inner.content);
let pristine_map = serde_json::to_string(&self.sourcemap.inner.content)?;
let pristine_source = without_file_paths(&self.source.inner.content);
// JSON serialization never contains a raw NUL, so it unambiguously separates
// the parts (same framing as `stable_chunk_id`).
Some(content_hash([
pristine_source.as_bytes(),
b"\0".as_slice(),
pristine_map.as_bytes(),
b"\0".as_slice(),
identity_variant,
]))
}
ReleaseMode::SymbolSet => None,
};
let data = SourceAndMap {
minified_source: source_content,
sourcemap: sourcemap_content,
};
let data = write_symbol_data(data)?;
Ok(SymbolSetUpload {
chunk_id,
data,
release_id,
content_hash,
})
}
}
#[cfg(test)]
mod tests {
use super::*;
fn normalize(text: &str) -> String {
without_file_paths(text).replace(FILE_PATH_TOKEN, "<path>")
}
#[test]
fn replaces_script_file_paths() {
assert_eq!(
normalize(
r#"import("./one-BrAf3own.js");const d=["assets/one-BrAf3own.js","https://cdn.example.com/a/b-X_1.mjs"];
//# sourceMappingURL=index-C3e2Htc9.js.map"#
),
r#"import("<path>");const d=["<path>","https:<path>"];
//# sourceMappingURL=<path>.map"#
);
}
#[test]
fn replaces_directory_names_with_the_path() {
assert_eq!(
normalize(r#"import("../Bx9_a1c2/one.cjs")"#),
r#"import("<path>")"#
);
assert_eq!(
normalize(r#"require("C:\\ci\\Bx9_a1c2\\one.js")"#),
normalize(r#"require("C:\\ci\\Zq0_w9e8\\one.js")"#)
);
}
#[test]
fn leaves_other_extensions_and_bare_extensions_alone() {
let text = r#"["index.json","index.jsx","a.js_b",".js",x.jsonp,"js"]"#;
assert_eq!(normalize(text), text);
assert!(matches!(without_file_paths(text), Cow::Borrowed(_)));
}
#[test]
fn handles_repeated_extensions_and_multibyte_text() {
assert_eq!(normalize("a.jsx.js x.js.map"), "<path> <path>.map");
assert_eq!(normalize("é日.js 😀 é.mjs"), "<path> 😀 <path>");
// An emoji is not a path character, so the path starts after it.
assert_eq!(normalize("😀js.js"), "😀<path>");
}
#[test]
fn replaces_only_the_file_field_of_a_map() {
// A source can share a chunk's name, and frames resolve to it, so it stays.
let mut map: SourceMapContent = serde_json::from_value(serde_json::json!({
"version": 3,
"file": "assets/index.js",
"sources": ["../src/index.js"],
"mappings": "AAAA",
}))
.expect("Failed to build SourceMapContent");
without_file_path_in_file_field(&mut map);
assert_eq!(map.fields["file"], FILE_PATH_TOKEN);
assert_eq!(
map.fields["sources"],
serde_json::json!(["../src/index.js"])
);
}
}