: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
//! 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<Version>,
}
/// 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<Vec<LibRule>> = 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<LibRule> = 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<Version> {
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<WireOrderFix> {
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<ExceptionList> {
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<ExceptionList> {
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<AnyEvent>`). 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<String> {
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<Frame>| 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::<ExceptionList>(value).is_err());
}
}