//! Wire-order normalization for incoming exception payloads. //! //! Different PostHog SDKs historically disagreed on the order of two things: //! //! - `stacktrace.frames`: the canonical wire order is bottom-up, i.e. //! `frames[0]` is the entry point (e.g. `main`) and the last frame is the //! crash site. Some SDKs send crash-first (crash site first, entry point //! last) and need their frames reversed at ingest. //! - `$exception_list`: the canonical wire order is caught/outermost exception //! first, root cause last. One SDK sends the list root-cause-first and needs //! the list reversed. //! //! The cross-SDK standardization effort (sdk-specs#11) is flipping SDKs to emit //! the canonical order directly. Until an SDK ships that flip, cymbal //! normalizes its payloads here, keyed on `$lib` and gated on `$lib_version`. //! //! To retire normalization for an SDK once it ships the canonical order, set //! that entry's cutoff to `Some(version)`: payloads at or above the cutoff are //! left untouched, payloads below it (or with an unparseable version) are still //! normalized. A `None` cutoff means the SDK has not flipped yet, so everything //! is normalized. //! //! The module also normalizes legacy untagged payloads ([`normalize_legacy_tags`]): //! SDKs from before the stacktrace `type` and frame `platform` tags existed need //! those tags added before typed parsing. use std::sync::OnceLock; use semver::Version; use serde_json::Value; use crate::types::ExceptionList; /// Which parts of a payload a given `$lib` needs reversed to reach canonical /// wire order. #[derive(Debug, Clone, Copy)] struct WireOrderFix { /// Reverse each exception's `stacktrace.frames` (crash-first -> bottom-up). reverse_frames: bool, /// Reverse `$exception_list` (root-cause-first -> outermost-first). reverse_exception_list: bool, } impl WireOrderFix { const FRAMES: Self = Self { reverse_frames: true, reverse_exception_list: false, }; const EXCEPTION_LIST: Self = Self { reverse_frames: false, reverse_exception_list: true, }; } /// A single SDK's normalization rule. struct LibRule { /// The `$lib` value this rule matches. lib: &'static str, /// What to reverse. fix: WireOrderFix, /// The version at which the SDK started emitting canonical order. `None` /// means it has not flipped yet, so always normalize. `Some(v)` means /// normalize only for versions strictly below `v`. canonical_since: Option, } /// The normalization table, keyed on `$lib`. /// /// A `None` cutoff means the SDK has not shipped the canonical-order flip yet. /// When an SDK ships it, change its `canonical_since` to the release version /// and leave everything else alone — legacy payloads keep normalizing, new /// payloads pass through. The cutoff must be merged and deployed BEFORE the /// SDK release it names exists, and that release must be the flip: an /// unrelated release claiming the version would ship crash-first payloads the /// gate no longer fixes. /// /// Built lazily because `semver::Version` is not `const`-constructible; cached /// for the process lifetime since this is consulted for every ingested event. fn lib_rules() -> &'static [LibRule] { static RULES: OnceLock> = OnceLock::new(); RULES.get_or_init(|| { // Crash-first frames: entry point last, crash site first on the wire. let crash_first_frames = [ "posthog-android", "posthog-flutter", "posthog-php", "posthog-go", "posthog-rs", "posthog-elixir", // Java: `posthog-server` is the current java server SDK identifier // (module in the posthog-android repo, shares the android coercer); // `posthog-java` is the tombstoned legacy SDK, included defensively. // Both are crash-first. "posthog-java", "posthog-server", ]; let mut rules: Vec = crash_first_frames .into_iter() .map(|lib| LibRule { lib, fix: WireOrderFix::FRAMES, canonical_since: match lib { // posthog-rs ships the flip in 0.19.0 (PostHog/posthog-rs#176). "posthog-rs" => Some(Version::new(0, 19, 0)), // posthog-php ships the flip in 4.11.0 (PostHog/posthog-php#200). "posthog-php" => Some(Version::new(4, 11, 0)), // posthog-go ships the flip in 1.20.0 (PostHog/posthog-go#254). "posthog-go" => Some(Version::new(1, 20, 0)), // android + the java server SDK flip together (shared // coercer, one release train: PostHog/posthog-android#603), // but each module reports its own version stream. "posthog-android" => Some(Version::new(3, 56, 0)), "posthog-server" => Some(Version::new(2, 9, 0)), // posthog-elixir ships the flip in 2.13.0 (PostHog/posthog-elixir#160). "posthog-elixir" => Some(Version::new(2, 13, 0)), // posthog-flutter ships its Dart flip in 5.33.0 and raises // its Android SDK floor to the canonical 3.56.0 release. "posthog-flutter" => Some(Version::new(5, 33, 0)), // `posthog-java` is the tombstoned legacy SDK: it will // never ship the flip, so no cutoff, ever. _ => None, }, }) .collect(); // Root-cause-first `$exception_list`: python sends chained exceptions with // the root cause first. Its frames are already canonical (bottom-up). rules.push(LibRule { lib: "posthog-python", fix: WireOrderFix::EXCEPTION_LIST, // posthog-python ships the flip in 7.31.0 (PostHog/posthog-python#728). canonical_since: Some(Version::new(7, 31, 0)), }); rules }) } /// Parses a `$lib_version` leniently. `semver` rejects things like a bare /// `1.2` or a leading `v`, both of which SDKs emit, so we coerce common shapes /// before parsing. An unparseable version is treated as "old" by the caller /// (i.e. normalization still applies), so `None` here is a normalize signal. fn parse_lenient(version: &str) -> Option { let trimmed = version.trim().trim_start_matches(['v', 'V']); if let Ok(v) = Version::parse(trimmed) { return Some(v); } // Split off any pre-release/build metadata, then pad the numeric core to // three components so `1` and `1.2` parse. let core = trimmed.split(['-', '+']).next().unwrap_or(trimmed); let mut parts: Vec<&str> = core.split('.').collect(); if parts.is_empty() || parts.len() > 3 { return None; } while parts.len() < 3 { parts.push("0"); } if parts .iter() .any(|p| p.is_empty() || !p.bytes().all(|b| b.is_ascii_digit())) { return None; } Version::parse(&parts.join(".")).ok() } /// Decides whether a payload from `lib_version` still needs normalizing, given /// the version at which its SDK started emitting canonical order. /// /// - `None` cutoff: the SDK has not flipped yet, so always normalize. /// - `Some(cutoff)`: normalize only versions strictly below the cutoff. A /// version at/above the cutoff is left alone; an unparseable version is /// treated as old, so it still normalizes. /// /// The cutoff path deliberately does no work for post-flip payloads. It does /// not need to: a flipped SDK's canonical events fingerprint identically to the /// pre-flip legacy events this normalizer already reorders. While the cutoff is /// `None` (the normalization window), those legacy events are aliased so the /// canonical fingerprint already maps to the pre-flip issue, so the first /// post-flip canonical event hits the fast `load_by_fingerprint` path and joins /// the same issue with no split. fn should_normalize(canonical_since: Option<&Version>, lib_version: Option<&str>) -> bool { let Some(cutoff) = canonical_since else { return true; }; match lib_version.and_then(parse_lenient) { Some(v) => v < *cutoff, None => true, } } /// Returns the fix to apply for `lib`/`lib_version`, or `None` if the payload /// already carries canonical order (or the SDK is unknown). fn fix_for(lib: &str, lib_version: Option<&str>) -> Option { let rule = lib_rules().iter().find(|r| r.lib == lib)?; should_normalize(rule.canonical_since.as_ref(), lib_version).then_some(rule.fix) } /// Normalizes `exception_list` to canonical wire order in place, keyed on /// `$lib`/`$lib_version`. Returns the pre-normalization (legacy-order) list when /// a reversal was applied, so the caller can compute the legacy fingerprint for /// issue continuity, or `None` when nothing changed. /// /// This must run before fingerprinting/resolution: fingerprints are computed /// over stored frame/exception order, so normalizing here keeps grouping /// consistent across SDKs. /// /// Note on the no-in-app fingerprint fallback: when an exception has no in-app /// frames, fingerprinting hashes `frames.first()`. After normalization that is /// the entry frame rather than the crash site — but that is already how /// natively-canonical SDKs (web, node, ...) fingerprint such stacks today, so /// this brings crash-first SDKs into line rather than introducing new /// divergence. Improving that fallback (e.g. keying on the crash-site frame) is /// a cross-SDK fingerprinting change out of scope for wire-order normalization. pub fn normalize_wire_order( exception_list: &mut ExceptionList, lib: Option<&str>, lib_version: Option<&str>, ) -> Option { let fix = fix_for(lib?, lib_version)?; // Snapshot only once we know a reversal is coming — the common (canonical) // path pays no clone. let legacy = exception_list.clone(); apply_fix(exception_list, fix); Some(legacy) } fn apply_fix(exception_list: &mut ExceptionList, fix: WireOrderFix) { if fix.reverse_exception_list { exception_list.reverse(); } if fix.reverse_frames { for exception in exception_list.iter_mut() { if let Some(stack) = exception.stack.as_mut() { match stack { crate::types::Stacktrace::Raw { frames } => frames.reverse(), crate::types::Stacktrace::Resolved { frames } => frames.reverse(), } } } } } /// Reconstructs `lib`'s legacy wire order from a canonical-order list, /// regardless of `$lib_version` or cutoff — each fix is its own inverse, so /// applying it to a canonical list recovers the pre-flip order. /// /// This is how legacy fingerprint versions keep pre-normalization issues /// addressable after an SDK ships the flip: the cutoff stops the reordering, /// but must not stop legacy hashing. Reconstruction is exact except where /// resolution reshaped the list (inline expansion, remapping) — those hashes /// can only be reproduced from the pre-flip snapshot, which post-flip events /// no longer carry. pub fn legacy_wire_order( lib: Option<&str>, exception_list: &ExceptionList, ) -> Option { let lib = lib?; let rule = lib_rules().iter().find(|r| r.lib == lib)?; let mut legacy = exception_list.clone(); apply_fix(&mut legacy, rule.fix); Some(legacy) } // Keys only python frames carry on the wire. posthog-python < 3.8.0 sent frames without // a platform tag, so any of these keys is what identifies such a frame. The list mirrors // the serde field names of `RawPythonFrame` (core/types/langs/python.rs) — keep in sync. const LEGACY_PYTHON_FRAME_KEYS: &[&str] = &[ "abs_path", "context_line", "module", "pre_context", "post_context", ]; /// Tags legacy untagged payloads in place, on the raw `$exception_list` JSON before /// typed parsing. posthog-python only added the `"type": "raw"` stacktrace tag and the /// frame `platform` tag in 3.8.0; `Stacktrace` and `RawFrame` parse both as serde-tagged /// enums, so an untagged payload would otherwise fail with a missing-field error and /// never become an issue. An untagged stacktrace is tagged raw. An untagged frame in a /// raw stacktrace is tagged python only when a python-only key identifies it — other /// frame shapes overlap too much to classify safely, so any other untagged frame keeps /// failing typed parsing. /// /// This runs once, at the processing-ingest boundary (`TryFrom`). Every other /// parse site of these types consumes cymbal-serialized JSON, which always carries the /// tags. pub fn normalize_legacy_tags(exception_list: &mut Value) { let Some(exceptions) = exception_list.as_array_mut() else { return; }; for exception in exceptions { let Some(stacktrace) = exception .get_mut("stacktrace") .and_then(Value::as_object_mut) else { continue; }; if !stacktrace.contains_key("type") { stacktrace.insert("type".to_string(), Value::String("raw".to_string())); } // Only raw stacktraces can carry untagged legacy frames. Resolved frames // legitimately carry keys like `module`, and must not get a platform tag. if stacktrace.get("type").and_then(Value::as_str) != Some("raw") { continue; } let Some(frames) = stacktrace.get_mut("frames").and_then(Value::as_array_mut) else { continue; }; for frame in frames { let Some(frame) = frame.as_object_mut() else { continue; }; if !frame.contains_key("platform") && LEGACY_PYTHON_FRAME_KEYS .iter() .any(|key| frame.contains_key(*key)) { frame.insert("platform".to_string(), Value::String("python".to_string())); } } } } #[cfg(test)] mod test { use super::*; use crate::frames::RawFrame; use crate::types::{Exception, Stacktrace}; fn py_frame(function: &str) -> RawFrame { // Deserialize a minimal python frame so we don't have to hand-build the // full raw-frame struct; only the function name matters for ordering. let json = serde_json::json!({ "platform": "python", "function": function, "filename": "app.py", "in_app": true, }); serde_json::from_value(json).expect("valid python frame") } fn frame_names(exception: &Exception) -> Vec { match exception.stack.as_ref().unwrap() { Stacktrace::Raw { frames } => frames .iter() .map(|f| match f { RawFrame::Python(p) => p.function.clone(), _ => panic!("expected python frame"), }) .collect(), _ => panic!("expected raw stacktrace"), } } fn exception_with_frames(exc_type: &str, functions: &[&str]) -> Exception { Exception { exception_id: None, exception_type: exc_type.to_string(), exception_message: String::new(), mechanism: None, module: None, thread_id: None, stack: Some(Stacktrace::Raw { frames: functions.iter().map(|f| py_frame(f)).collect(), }), } } #[test] fn legacy_wire_order_reconstructs_pre_flip_order() { // Frames: reconstruction re-applies the reversal, independent of // `$lib_version` — this is what keeps legacy fingerprint versions // computable after an SDK ships the flip and its cutoff is set. let canonical: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = legacy_wire_order(Some("posthog-go"), &canonical).expect("go is in the table"); assert_eq!(frame_names(&legacy[0]), vec!["boom", "main"]); // Exception list: python's fix reverses the list, not the frames. let canonical: ExceptionList = vec![ exception_with_frames("Outer", &["main", "wrap"]), exception_with_frames("RootCause", &["main", "boom"]), ] .into(); let legacy = legacy_wire_order(Some("posthog-python"), &canonical).expect("python is in the table"); assert_eq!(legacy[0].exception_type, "RootCause"); assert_eq!(frame_names(&legacy[0]), vec!["main", "boom"]); // Natively-canonical SDKs have no legacy order. assert!(legacy_wire_order(Some("posthog-node"), &canonical).is_none()); assert!(legacy_wire_order(None, &canonical).is_none()); } #[test] fn python_cutoff_gates_exception_list_normalization_by_version() { // Python's fix reverses the exception list (root-cause-first -> // outermost-first), not frames — the gate must key on the same fix. let make_list = || -> ExceptionList { vec![ exception_with_frames("RootCause", &["main", "boom"]), exception_with_frames("Wrapper", &["main", "wrap"]), ] .into() }; for version in [Some("7.30.1"), Some("7.30.0"), Some("garbage"), None] { let mut list = make_list(); let legacy = normalize_wire_order(&mut list, Some("posthog-python"), version); assert!(legacy.is_some(), "{version:?} should normalize"); assert_eq!(list[0].exception_type, "Wrapper", "list reversed"); assert_eq!( frame_names(&list[0]), vec!["main", "wrap"], "frames untouched" ); } // Post-flip senders emit canonical order: outermost wrapper first. let make_canonical_list = || -> ExceptionList { vec![ exception_with_frames("Wrapper", &["main", "wrap"]), exception_with_frames("RootCause", &["main", "boom"]), ] .into() }; for version in ["7.31.0", "7.31.1", "7.32.0", "8.0.0"] { let mut list = make_canonical_list(); let legacy = normalize_wire_order(&mut list, Some("posthog-python"), Some(version)); assert!(legacy.is_none(), "{version} should pass through"); assert_eq!( list[0].exception_type, "Wrapper", "canonical list untouched" ); } // Legacy hashing still reconstructs the pre-flip (root-cause-first) // list order from the canonical stored order post-cutoff. let canonical = make_canonical_list(); let legacy = legacy_wire_order(Some("posthog-python"), &canonical) .expect("reconstruction must ignore the cutoff"); assert_eq!(legacy[0].exception_type, "RootCause"); assert_eq!(frame_names(&legacy[0]), vec!["main", "boom"]); } #[test] fn elixir_cutoff_gates_normalization_by_version() { for version in [Some("2.12.1"), Some("2.1.0"), Some("garbage"), None] { let mut list: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = normalize_wire_order(&mut list, Some("posthog-elixir"), version); assert!(legacy.is_some(), "{version:?} should normalize"); assert_eq!(frame_names(&list[0]), vec!["boom", "main"]); } for version in ["2.13.0", "2.13.1", "2.14.0", "3.0.0"] { let mut list: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = normalize_wire_order(&mut list, Some("posthog-elixir"), Some(version)); assert!(legacy.is_none(), "{version} should pass through"); assert_eq!(frame_names(&list[0]), vec!["main", "boom"]); } // Legacy hashing still reconstructs pre-flip order post-cutoff. let canonical: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = legacy_wire_order(Some("posthog-elixir"), &canonical) .expect("reconstruction must ignore the cutoff"); assert_eq!(frame_names(&legacy[0]), vec!["boom", "main"]); } #[test] fn android_server_and_flutter_cutoffs_gate_normalization_by_version() { // Android and server flip in one release train; Flutter follows with // its own wrapper release. Each gate keys on its reported version. for (lib, below, at) in [ ("posthog-android", "3.55.2", "3.56.0"), ("posthog-server", "2.8.1", "2.9.0"), ("posthog-flutter", "5.32.1", "5.33.0"), ] { for version in [Some(below), Some("1.0.0"), Some("garbage"), None] { let mut list: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = normalize_wire_order(&mut list, Some(lib), version); assert!(legacy.is_some(), "{lib} {version:?} should normalize"); assert_eq!(frame_names(&list[0]), vec!["boom", "main"]); } let mut list: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = normalize_wire_order(&mut list, Some(lib), Some(at)); assert!(legacy.is_none(), "{lib} {at} should pass through"); assert_eq!(frame_names(&list[0]), vec!["main", "boom"]); // Legacy hashing still reconstructs pre-flip order post-cutoff. let canonical: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = legacy_wire_order(Some(lib), &canonical) .expect("reconstruction must ignore the cutoff"); assert_eq!(frame_names(&legacy[0]), vec!["boom", "main"]); } // The tombstoned java SDK keeps normalizing at any version. let mut list: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = normalize_wire_order(&mut list, Some("posthog-java"), Some("99.0.0")); assert!(legacy.is_some(), "posthog-java has no cutoff"); assert_eq!(frame_names(&list[0]), vec!["boom", "main"]); } #[test] fn go_cutoff_gates_normalization_by_version() { // Below the 1.20.0 cutoff (and unparseable versions): crash-first on // the wire, frames reverse, legacy snapshot returned. for version in [Some("1.19.0"), Some("1.2.3"), Some("devel"), None] { let mut list: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = normalize_wire_order(&mut list, Some("posthog-go"), version); assert!(legacy.is_some(), "{version:?} should normalize"); assert_eq!(frame_names(&list[0]), vec!["boom", "main"]); } // At/above the cutoff: canonical on the wire, untouched. for version in ["1.20.0", "1.20.1", "1.21.0", "2.0.0"] { let mut list: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = normalize_wire_order(&mut list, Some("posthog-go"), Some(version)); assert!(legacy.is_none(), "{version} should pass through"); assert_eq!(frame_names(&list[0]), vec!["main", "boom"]); } // Legacy hashing still reconstructs pre-flip order post-cutoff. let canonical: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = legacy_wire_order(Some("posthog-go"), &canonical) .expect("reconstruction must ignore the cutoff"); assert_eq!(frame_names(&legacy[0]), vec!["boom", "main"]); } #[test] fn php_cutoff_gates_normalization_by_version() { // Below the 4.11.0 cutoff (and unparseable versions): crash-first on // the wire, frames reverse, legacy snapshot returned. for version in [Some("4.10.0"), Some("4.9.0"), Some("dev-main"), None] { let mut list: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = normalize_wire_order(&mut list, Some("posthog-php"), version); assert!(legacy.is_some(), "{version:?} should normalize"); assert_eq!(frame_names(&list[0]), vec!["boom", "main"]); } // At/above the cutoff: canonical on the wire, untouched. for version in ["4.11.0", "4.11.1", "4.12.0", "5.0.0"] { let mut list: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = normalize_wire_order(&mut list, Some("posthog-php"), Some(version)); assert!(legacy.is_none(), "{version} should pass through"); assert_eq!(frame_names(&list[0]), vec!["main", "boom"]); } // Legacy hashing still reconstructs pre-flip order post-cutoff. let canonical: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = legacy_wire_order(Some("posthog-php"), &canonical) .expect("reconstruction must ignore the cutoff"); assert_eq!(frame_names(&legacy[0]), vec!["boom", "main"]); } #[test] fn rs_cutoff_gates_normalization_by_version() { // Below the 0.19.0 cutoff (and for unparseable versions): still // crash-first on the wire, so frames reverse and a legacy snapshot is // returned. for version in [Some("0.18.0"), Some("0.3.7"), Some("garbage"), None] { let mut list: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = normalize_wire_order(&mut list, Some("posthog-rs"), version); assert!(legacy.is_some(), "{version:?} should normalize"); assert_eq!(frame_names(&list[0]), vec!["boom", "main"]); } // At/above the cutoff: canonical on the wire, untouched. for version in ["0.19.0", "0.19.1", "0.20.0", "1.0.0"] { let mut list: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = normalize_wire_order(&mut list, Some("posthog-rs"), Some(version)); assert!(legacy.is_none(), "{version} should pass through"); assert_eq!(frame_names(&list[0]), vec!["main", "boom"]); } // Post-flip events still reconstruct the legacy order for the legacy // fingerprint versions — the cutoff stops reordering, not legacy // hashing. let canonical: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = legacy_wire_order(Some("posthog-rs"), &canonical) .expect("reconstruction must ignore the cutoff"); assert_eq!(frame_names(&legacy[0]), vec!["boom", "main"]); } #[test] fn java_server_libs_both_normalize() { // Java server SDK sends crash-first frames under both the current // (`posthog-server`) and legacy tombstoned (`posthog-java`) identifiers. for lib in ["posthog-java", "posthog-server"] { let mut list: ExceptionList = vec![exception_with_frames("Boom", &["main", "boom"])].into(); let legacy = normalize_wire_order(&mut list, Some(lib), Some("1.0.0")); assert!(legacy.is_some(), "{lib} should normalize"); assert_eq!(frame_names(&list[0]), vec!["boom", "main"]); } } #[test] fn crash_first_lib_reverses_frames_only() { // posthog-go sends crash-first frames; the list order is left alone. let mut list: ExceptionList = vec![ exception_with_frames("Outer", &["main", "handler", "boom"]), exception_with_frames("Inner", &["a", "b"]), ] .into(); let legacy = normalize_wire_order(&mut list, Some("posthog-go"), Some("1.2.3")); assert!(legacy.is_some()); assert_eq!(frame_names(&list[0]), vec!["boom", "handler", "main"]); assert_eq!(frame_names(&list[1]), vec!["b", "a"]); // List order unchanged. assert_eq!(list[0].exception_type, "Outer"); assert_eq!(list[1].exception_type, "Inner"); // The returned legacy snapshot preserves the original (pre-reversal) order. let legacy = legacy.unwrap(); assert_eq!(frame_names(&legacy[0]), vec!["main", "handler", "boom"]); } #[test] fn python_reverses_exception_list_only() { // posthog-python sends the list root-cause-first; frames stay put. let mut list: ExceptionList = vec![ exception_with_frames("RootCause", &["main", "boom"]), exception_with_frames("Wrapper", &["main", "wrap"]), ] .into(); let legacy = normalize_wire_order(&mut list, Some("posthog-python"), Some("3.0.0")); assert!(legacy.is_some()); // List reversed: outermost (Wrapper) now first. assert_eq!(list[0].exception_type, "Wrapper"); assert_eq!(list[1].exception_type, "RootCause"); // Frames unchanged. assert_eq!(frame_names(&list[0]), vec!["main", "wrap"]); } #[test] fn canonical_lib_is_untouched() { // web already sends canonical order; nothing should change. let mut list: ExceptionList = vec![exception_with_frames("Error", &["main", "boom"])].into(); let legacy = normalize_wire_order(&mut list, Some("web"), Some("1.170.1")); assert!(legacy.is_none()); assert_eq!(frame_names(&list[0]), vec!["main", "boom"]); } #[test] fn unknown_lib_is_untouched() { let mut list: ExceptionList = vec![exception_with_frames("Error", &["main", "boom"])].into(); assert!(normalize_wire_order(&mut list, Some("posthog-martian"), None).is_none()); assert_eq!(frame_names(&list[0]), vec!["main", "boom"]); } #[test] fn missing_lib_is_untouched() { let mut list: ExceptionList = vec![exception_with_frames("Error", &["main", "boom"])].into(); assert!(normalize_wire_order(&mut list, None, Some("1.0.0")).is_none()); assert_eq!(frame_names(&list[0]), vec!["main", "boom"]); } #[test] fn version_cutoff_skips_new_and_normalizes_old() { // Exercise the version gate directly (the shipped table is all-`None` // today, so no live rule has a cutoff yet). let cutoff = Version::parse("2.0.0").unwrap(); let since = Some(&cutoff); // At/above cutoff: canonical order already, don't normalize. assert!(!should_normalize(since, Some("2.0.0"))); assert!(!should_normalize(since, Some("2.5.1"))); // Below cutoff: still legacy order, normalize. assert!(should_normalize(since, Some("1.9.9"))); // Unparseable or missing version -> treat as old -> normalize. assert!(should_normalize(since, Some("not-a-version"))); assert!(should_normalize(since, None)); // No cutoff -> SDK hasn't flipped -> always normalize. assert!(should_normalize(None, Some("99.0.0"))); } #[test] fn normalized_crash_first_matches_native_canonical_fingerprint() { use crate::fingerprinting::Fingerprint; use crate::frames::Frame; use common_types::error_tracking::FrameId; let resolved = |name: &str| Frame { frame_id: FrameId::new(String::new(), 1, 0), mangled_name: name.to_string(), line: Some(1), column: None, source: Some(format!("{name}.rs")), in_app: true, resolved_name: Some(name.to_string()), lang: "rust".to_string(), resolved: true, resolve_failure: None, synthetic: false, suspicious: false, junk_drawer: None, code_variables: None, context: None, module: None, }; let exception = |frames: Vec| Exception { exception_id: None, exception_type: "Boom".to_string(), exception_message: "boom".to_string(), mechanism: None, module: None, thread_id: None, stack: Some(Stacktrace::Resolved { frames }), }; // A crash-first SDK sends [crash, mid, entry]; a canonical SDK sends the // reverse. After normalization the crash-first payload must fingerprint // identically to the canonical one, so both group into one issue. let canonical: ExceptionList = vec![exception(vec![ resolved("entry"), resolved("mid"), resolved("crash"), ])] .into(); let mut crash_first: ExceptionList = vec![exception(vec![ resolved("crash"), resolved("mid"), resolved("entry"), ])] .into(); let canonical_fp = Fingerprint::from_exception_list(&canonical).value; let pre_norm_fp = Fingerprint::from_exception_list(&crash_first).value; assert_ne!( canonical_fp, pre_norm_fp, "crash-first order should fingerprint differently before normalization" ); assert!(normalize_wire_order(&mut crash_first, Some("posthog-rs"), None).is_some()); let post_norm_fp = Fingerprint::from_exception_list(&crash_first).value; assert_eq!( canonical_fp, post_norm_fp, "normalized crash-first order should match canonical fingerprint" ); } #[test] fn lenient_version_parsing() { assert_eq!( parse_lenient("1.2.3"), Some(Version::parse("1.2.3").unwrap()) ); assert_eq!(parse_lenient("1.2"), Some(Version::parse("1.2.0").unwrap())); assert_eq!(parse_lenient("1"), Some(Version::parse("1.0.0").unwrap())); assert_eq!( parse_lenient("v1.2.3"), Some(Version::parse("1.2.3").unwrap()) ); assert_eq!( parse_lenient("1.2.3-beta.1"), Some(Version::parse("1.2.3-beta.1").unwrap()) ); assert_eq!(parse_lenient("garbage"), None); assert_eq!(parse_lenient(""), None); } // The shape posthog-python < 3.8.0 emits: no "type" on the stacktrace and no // "platform" on the frames. Written fresh, not copied from captured data. const LEGACY_PYTHON_EXCEPTION_LIST: &str = r#"[ { "type": "ConnectionError", "value": "connection refused", "stacktrace": { "frames": [ { "abs_path": "/app/example/service.py", "context_line": " connect()", "filename": "example/service.py", "function": "start", "lineno": 12, "module": "example.service", "pre_context": [], "post_context": [], "in_app": true } ] } } ]"#; #[test] fn tags_a_legacy_python_exception_list_so_it_parses() { let mut value: Value = serde_json::from_str(LEGACY_PYTHON_EXCEPTION_LIST).unwrap(); normalize_legacy_tags(&mut value); let list: ExceptionList = serde_json::from_value(value).unwrap(); let Some(Stacktrace::Raw { frames }) = &list[0].stack else { panic!("expected a raw stacktrace"); }; assert!(matches!(frames.as_slice(), [RawFrame::Python(_)])); // Serialization must write the tags back: downstream consumers (resolution, // notifications) re-parse cymbal-serialized stacktraces and rely on them. let serialized = serde_json::to_value(&list).unwrap(); assert_eq!(serialized[0]["stacktrace"]["type"], "raw"); assert_eq!( serialized[0]["stacktrace"]["frames"][0]["platform"], "python" ); } #[test] fn leaves_resolved_stacktrace_frames_untouched() { let raw = r#"[ { "type": "Error", "value": "boom", "stacktrace": { "type": "resolved", "frames": [{"module": "example.service", "function": "start"}] } } ]"#; let mut value: Value = serde_json::from_str(raw).unwrap(); normalize_legacy_tags(&mut value); assert_eq!(value[0]["stacktrace"]["frames"][0].get("platform"), None); } #[test] fn leaves_untagged_frames_without_python_markers_unclassified() { let raw = r#"[ { "type": "Error", "value": "boom", "stacktrace": { "frames": [{"filename": "app.js", "function": "main", "lineno": 3, "colno": 7}] } } ]"#; let mut value: Value = serde_json::from_str(raw).unwrap(); normalize_legacy_tags(&mut value); assert!(serde_json::from_value::(value).is_err()); } }