openlatch-client 0.5.2

//! Crash reporting — Rust panics as PostHog `$exception` events.
//!
//! Scope is deliberately narrow: panics only, scrubbed by `src/core/privacy/` before
//! transport, never active in `openlatch-hook`, and sent through `core::egress` like
//! every other outbound request in the product. There is no second HTTP client here, and
//! nothing may introduce one.
//!
//! The wire shape lives in [`payload`]; the module list and the `debug_id` derivation in
//! [`images`]; the backtrace conversion in [`frames`]; the privacy adapter in [`scrub`].
//!
//! This module owns the whole crash path: consent, the process scope tags, the panic
//! hook and the send. `core::crash_report` is gone.

pub mod frames;
pub mod images;
pub mod payload;
pub mod scrub;

use std::panic::Location;
use std::path::Path;
use std::sync::Arc;
use std::time::Duration;

use arc_swap::ArcSwapOption;
use serde_json::{Map, Value};

use self::payload::{DebugImage, Exception, Mechanism, Stacktrace};
use super::consent::{resolve_crash, CrashResolved};
use super::network::{environment, key_is_present, posthog_host, posthog_key, release};

/// How long the dying process will wait for its own crash report.
///
/// A crash report that misses its window is an acceptable loss; a CLI that hangs on an
/// unreachable ingest host is not.
const CRASH_POST_TIMEOUT: Duration = Duration::from_secs(3);

/// The environment string a debug build — or a release build with no baked project key —
/// reports as. See `network::environment`, which owns both halves of that condition.
pub const ENV_DEVELOPMENT: &str = "development";

/// Everything [`capture_panic`] and [`send_blocking`] need, resolved once at
/// hook-install time. Built by [`CrashConfig::resolve`], which is where consent is
/// asked and the answer turned into "send" or "do not install a hook at all".
pub struct CrashConfig {
    /// Resolved egress route. Shared with the async telemetry client, so a crash report
    /// takes the same proxy, the same CA bundle and the same TLS posture as everything
    /// else.
    pub egress: crate::egress::EgressConfig,
    /// The PostHog project token.
    pub project_key: String,
    /// Ingest host. Runtime env beats baked, which is what lets a test point at a mock.
    pub host: String,
    /// The agent id, as every other client event uses.
    pub distinct_id: String,
    /// `"production"` or `"development"`.
    pub environment: &'static str,
    /// The baked git sha.
    pub release: &'static str,
    /// Private so it can only be built through [`CrashConfig::new`]: a config with no
    /// filter would send an unscrubbed panic message.
    filter: crate::privacy::PrivacyFilter,
}

impl CrashConfig {
    /// Build a config with a fresh privacy filter.
    ///
    /// The filter is private to this subsystem rather than the global `privacy::FILTER`,
    /// which may not be initialised yet: the hook installs before daemon config load.
    pub fn new(
        egress: crate::egress::EgressConfig,
        project_key: String,
        host: String,
        distinct_id: String,
        environment: &'static str,
        release: &'static str,
    ) -> Self {
        Self {
            egress,
            project_key,
            host,
            distinct_id,
            environment,
            release,
            filter: crate::privacy::PrivacyFilter::new(&[]),
        }
    }

    pub fn filter(&self) -> &crate::privacy::PrivacyFilter {
        &self.filter
    }

    /// Build the config this process will report with, or `None` when consent says no.
    ///
    /// `openlatch_dir` is the data directory; `[crashreport]` is read from the
    /// `config.toml` inside it.
    pub fn resolve(openlatch_dir: &Path, egress: crate::egress::EgressConfig) -> Option<Self> {
        let decision = current_state(openlatch_dir);
        if !decision.enabled() {
            return None;
        }
        Some(Self::new(
            egress,
            posthog_key().to_string(),
            posthog_host(),
            crate::config::sniff_agent_id(openlatch_dir)
                .unwrap_or_else(|| "agt_unknown".to_string()),
            environment(),
            release(),
        ))
    }
}

/// The crash-reporting consent decision, without initialising anything.
///
/// `openlatch doctor` and the daemon's startup log both report this.
pub fn current_state(openlatch_dir: &Path) -> CrashResolved {
    resolve_crash(&openlatch_dir.join("config.toml"), key_is_present())
}

/// Whether this build links any crash-reporting code at all. Always `true` when the
/// module compiles; `openlatch doctor` prints "not compiled in" from the `cfg`'d-out
/// branch at its call site.
pub const fn build_includes_crash_report() -> bool {
    true
}

/// Properties describing WHICH process this is, merged into every crash report.
///
/// Replaces the previous crash reporter's Hub scope, and must reproduce its semantics:
/// **the LAST writer wins.** That API's `set_tag` overwrote, and the daemon depends on
/// it. The real call order inside one process is
///
/// 1. `main()` tags `cli` before dispatching, and
/// 2. `daemon start --foreground` — which re-enters that same `main()` — then tags
///    `daemon`.
///
/// A first-writer-wins cell (a `OnceLock`) would therefore discard step 2 silently and
/// label every daemon panic `process_type = cli`, with no `port` and no `pid`. That is
/// the bug this type exists to not have.
///
/// `ArcSwapOption` rather than a lock because the reader is a panic hook: a `Mutex` held
/// by the thread that is panicking would deadlock the crash report instead of sending
/// it.
static PROCESS_SCOPE: ArcSwapOption<Map<String, Value>> = ArcSwapOption::const_empty();

/// Tag this process as a CLI invocation.
pub fn set_cli_scope(command: &str) {
    let mut props = Map::new();
    props.insert("process_type".into(), Value::from("cli"));
    props.insert("command".into(), Value::from(command));
    set_process_scope(props);
}

/// Tag this process as a detached daemon, replacing the `cli` tag `main` set earlier.
pub fn set_daemon_scope(port: u16, pid: u32) {
    let mut props = Map::new();
    props.insert("process_type".into(), Value::from("daemon"));
    props.insert("port".into(), Value::from(port));
    props.insert("pid".into(), Value::from(pid));
    set_process_scope(props);
}

/// Install the process scope, replacing whatever was there.
fn set_process_scope(props: Map<String, Value>) {
    PROCESS_SCOPE.store(Some(Arc::new(props)));
}

fn process_scope() -> Option<Arc<Map<String, Value>>> {
    PROCESS_SCOPE.load_full()
}

/// Guards [`install_panic_hook`] against installing twice. Two chained copies of this
/// hook would send two `$exception` events for one panic.
static HOOK_INSTALLED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);

/// Install the panic hook. Returns false when a hook is already installed.
///
/// MUST run before any tokio runtime is built and before clap parses arguments —
/// otherwise a panic during runtime construction or arg parsing is not captured.
///
/// The previous hook is CHAINED, not replaced: the default hook is what prints the panic
/// message to stderr, and a user who sees nothing on a crash is worse off than one with
/// no telemetry.
pub fn install_panic_hook(cfg: CrashConfig) -> bool {
    use std::sync::atomic::Ordering;
    if HOOK_INSTALLED.swap(true, Ordering::SeqCst) {
        return false;
    }
    let previous = std::panic::take_hook();
    std::panic::set_hook(Box::new(move |info| {
        // PRINT FIRST. The previous hook is the one that puts the panic message on
        // stderr, and everything below it — resolving a backtrace, enumerating modules,
        // and up to CRASH_POST_TIMEOUT of HTTP — is time the user's terminal would
        // otherwise sit silent on a crash. Nothing in this binary installs a hook that
        // fails to return: under `panic = "abort"` the runtime aborts *after* the hook
        // chain, not inside it. If a future hook ever does abort, the trade is that its
        // crash report is lost, which is the cheaper of the two.
        previous(info);
        capture_panic(info, &cfg);
    }));
    true
}

/// Build and send the `$exception` for one panic.
///
/// EVERY OPERATION BELOW MUST BE INFALLIBLE. No `unwrap`, no `expect`, no slice indexing,
/// no `panic!` on any path — including inside the scrubber and the payload builders.
///
/// The guarantee stops at the crate boundary, and honestly so: `reqwest::blocking`'s
/// internal handle carries its own `expect`s on a poisoned runtime thread. Those are
/// pathological rather than reachable in normal operation, but this module cannot promise
/// what it does not own, and a panic raised inside a panic hook ABORTS.
///
/// There is deliberately NO `catch_unwind` here, and reaching for one would be worse than
/// useless: std aborts on a panic raised while the panic hook is running, before
/// unwinding begins, so `catch_unwind` never observes it. A wrapper would buy nothing and
/// would document a guarantee it does not provide — the next reader would then write
/// fallible code inside it believing it was caught.
///
/// A failure that *can* be handled (a client that will not build, a POST that fails) is
/// swallowed silently: telemetry about telemetry is the one thing this path must never
/// produce.
fn capture_panic(info: &std::panic::PanicHookInfo<'_>, cfg: &CrashConfig) {
    // The gate leads, so a build that will send nothing pays nothing: no backtrace
    // resolution, no module enumeration, no allocation. That is every developer build.
    if !should_send(cfg) {
        tracing::debug!("crash report suppressed: development build, no host override");
        return;
    }

    let message = payload_message(info);
    let location = info.location();

    // Resolved eagerly. The process is dying; the cost does not matter and the symbols
    // are unavailable once it has.
    let bt = backtrace::Backtrace::new();
    let modules = images::collect_loaded_modules();
    let captured = frames::build_frames(&bt, &modules);

    let mut exception = Exception {
        exception_type: "panic".to_string(),
        value: message,
        mechanism: Some(Mechanism::panic()),
        thread_id: None,
        stacktrace: Stacktrace::Raw { frames: captured },
    };
    scrub::scrub_exception(&mut exception, cfg.filter());

    let debug_images = images::referenced_images(&modules, exception.stacktrace.frames());

    send_blocking(cfg, exception, debug_images, location);
}

/// The panic message, however it was raised.
///
/// `panic!("…")` produces a `&str` or a `String`; `panic_any` can produce anything, and
/// there is nothing honest to say about a payload we cannot read.
fn payload_message(info: &std::panic::PanicHookInfo<'_>) -> String {
    let payload = info.payload();
    if let Some(s) = payload.downcast_ref::<&str>() {
        (*s).to_string()
    } else if let Some(s) = payload.downcast_ref::<String>() {
        s.clone()
    } else {
        "Box<dyn Any>".to_string()
    }
}

/// Whether this build may send a crash report at all.
///
/// THE DEVELOPMENT GATE. This surface has no `before_send`, so there is no shared hook to
/// carry it — the gate lives at the send choke point or it does not exist. Consent alone
/// is not enough: a developer who exports a project key gets a debug build with a key
/// present, which satisfies the consent chain and would then report
/// `environment = development` into a shared project.
///
/// THE `OPENLATCH_POSTHOG_HOST` CARVE-OUT IS LOAD-BEARING, NOT A LOOPHOLE. `environment`
/// is derived from the BAKED key, and no CI job bakes one, so every binary the e2e suite
/// runs resolves `development`. Without this clause the gate would make the suite's
/// crash-report test unreachable: the mock would never receive a POST.
///
/// The carve-out fires on ANY explicit runtime host, not just a loopback one. That is
/// deliberate rather than an oversight: the override exists so a harness can aim this
/// path somewhere, and a loopback-only rule would silently break the first e2e topology
/// that names its mock rather than addressing it. The consequence to hold in mind is
/// that a developer who exports the production host does send a `development`-tagged
/// event — which takes exporting the production host on purpose.
fn should_send(cfg: &CrashConfig) -> bool {
    // NON-EMPTY, to match what `network::posthog_host` actually honours. Asking
    // `is_some()` here would open the gate on `OPENLATCH_POSTHOG_HOST=""` — the shell's
    // usual way of neutralising a variable — while the resolver fell through to the
    // BAKED production host, turning an operator's attempt to silence this path into a
    // `development`-tagged event posted to production.
    should_send_with(
        cfg.environment,
        std::env::var_os("OPENLATCH_POSTHOG_HOST").is_some_and(|v| !v.is_empty()),
    )
}

/// The gate's logic, with the environment read hoisted out so it can be tested without
/// mutating process-global state that `telemetry::network` also reads.
fn should_send_with(environment: &str, host_override: bool) -> bool {
    environment != ENV_DEVELOPMENT || host_override
}

/// The `/capture/` request body for one panic.
///
/// Split out from [`send_blocking`] so the shape can be asserted without a transport.
fn build_request_body(
    cfg: &CrashConfig,
    exception: &Exception,
    images: &[DebugImage],
    loc: Option<&Location<'_>>,
) -> serde_json::Value {
    let mut properties = Map::new();
    // No SDK sets this for us — a level absent here is a level absent in PostHog.
    properties.insert("$exception_level".into(), Value::from("fatal"));
    properties.insert(
        "$exception_list".into(),
        serde_json::to_value([exception]).unwrap_or(Value::Null),
    );
    // Event level, NOT inside the frame list.
    properties.insert(
        "$debug_images".into(),
        serde_json::to_value(images).unwrap_or(Value::Null),
    );
    // OMITTED, not null, when there is no location. PostHog shows a property that was
    // sent as null, so three explicit nulls on every panic without a location would be
    // three empty columns rather than three absent ones.
    if let Some(loc) = loc {
        properties.insert("$exception_panic_file".into(), Value::from(loc.file()));
        properties.insert("$exception_panic_line".into(), Value::from(loc.line()));
        properties.insert("$exception_panic_column".into(), Value::from(loc.column()));
    }
    properties.insert("environment".into(), Value::from(cfg.environment));
    properties.insert("release".into(), Value::from(cfg.release));

    // Which process this is: `process_type`, `command` for a CLI, `port`/`pid` for the
    // daemon. Absent when nothing tagged the process, which is a panic before either
    // call site ran.
    if let Some(scope) = process_scope() {
        for (k, v) in scope.iter() {
            properties.insert(k.clone(), v.clone());
        }
    }

    serde_json::json!({
        "api_key": cfg.project_key,
        "event": "$exception",
        "distinct_id": cfg.distinct_id,
        "properties": properties,
    })
}

/// POST one `$exception` event, synchronously.
///
/// BLOCKING ON PURPOSE. `telemetry/client.rs` batches asynchronously with a background
/// task; a panic that queued there would be lost when the process exits moments later.
/// The transport config is shared (same `EgressConfig`, so the same proxy, the same CA
/// bundle) — only the send path differs.
fn send_blocking(
    cfg: &CrashConfig,
    exception: Exception,
    images: Vec<DebugImage>,
    loc: Option<&Location<'_>>,
) {
    // The gate lives HERE, at the send choke point, because that is where it is a
    // guarantee rather than an optimisation: `capture_panic` checks it first only to
    // avoid paying for a payload it will throw away. Any future caller that reaches this
    // function by another route is still gated.
    if !should_send(cfg) {
        tracing::debug!("crash report suppressed: development build, no host override");
        return;
    }

    // `build_blocking_client_with` exists for this call. The two-argument
    // `build_blocking_client` applies the consumer preset unconditionally, and
    // `Consumer::Telemetry`'s preset is `connect: None, total: None` — i.e. no timeout at
    // all. A panic on a host that cannot reach PostHog would hang the user's terminal
    // indefinitely, which is the exact outcome CRASH_POST_TIMEOUT exists to prevent.
    let Ok(client) = crate::egress::build_blocking_client_with(
        crate::egress::Consumer::Telemetry,
        &cfg.egress,
        crate::egress::Timeouts::total(CRASH_POST_TIMEOUT),
    ) else {
        return;
    };

    let body = build_request_body(cfg, &exception, &images, loc);
    let url = format!("{}/capture/", cfg.host.trim_end_matches('/'));
    let _ = client.post(url).json(&body).send();
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::sync::Mutex;

    // SAFETY: env vars are process-global; serialize every test that touches them.
    static ENV_LOCK: Mutex<()> = Mutex::new(());

    fn config(environment: &'static str) -> CrashConfig {
        CrashConfig::new(
            crate::egress::EgressConfig::direct(),
            "phc_test_public".to_string(),
            "http://127.0.0.1:9".to_string(),
            "agt_test".to_string(),
            environment,
            "deadbeef",
        )
    }

    fn exception(message: &str) -> Exception {
        Exception {
            exception_type: "panic".into(),
            value: message.to_string(),
            mechanism: Some(Mechanism::panic()),
            thread_id: None,
            stacktrace: Stacktrace::Raw {
                frames: vec![payload::Frame::address_only(
                    Some("0x1000".into()),
                    Some("0x1000".into()),
                )],
            },
        }
    }

    /// The whole gate, as pure logic. Kept out of the environment because
    /// `telemetry::network::posthog_host` reads the same variable at runtime, so a test
    /// that exports it is a test that can change another test's answer.
    #[test]
    fn the_gate_admits_production_and_an_explicit_host_override_only() {
        assert!(
            !should_send_with(ENV_DEVELOPMENT, false),
            "a development build with no override must send nothing"
        );
        assert!(
            should_send_with(ENV_DEVELOPMENT, true),
            "the override is what keeps the e2e suite's crash test reachable"
        );
        assert!(should_send_with("production", false));
        assert!(should_send_with("production", true));
    }

    /// The awkward case the gate exists for: a project key present satisfies the consent
    /// chain on its own, so consent alone would let a debug build report into a shared
    /// project. The environment, not the key, is what decides.
    #[test]
    fn a_key_being_present_does_not_open_the_development_gate() {
        let cfg = config(ENV_DEVELOPMENT);
        assert!(!cfg.project_key.is_empty());
        assert!(!should_send_with(cfg.environment, false));
    }

    /// The one test that touches the environment, so the variable NAME is pinned rather
    /// than only the logic behind it.
    #[test]
    fn the_gate_reads_openlatch_posthog_host() {
        let _guard = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
        // SAFETY: serialized via ENV_LOCK.
        unsafe {
            std::env::set_var("OPENLATCH_POSTHOG_HOST", "http://127.0.0.1:8123");
        }
        let with_override = should_send(&config(ENV_DEVELOPMENT));
        // SAFETY: serialized via ENV_LOCK.
        unsafe {
            std::env::remove_var("OPENLATCH_POSTHOG_HOST");
        }
        let without_override = should_send(&config(ENV_DEVELOPMENT));
        assert!(with_override);
        assert!(!without_override);
    }

    /// The protected keys must survive scrubbing byte-identically. They hold by
    /// construction today — the scrubber walks only the exception value and the frame
    /// fields — but "by construction" is what a refactor breaks.
    #[test]
    fn api_key_and_distinct_id_round_trip_unscrubbed() {
        let cfg = config("production");
        // Synthetic pattern-matching fixtures, not real credentials.
        let fake_secret = format!("{}{}", "sk_live_", "0123456789abcdefghijklmn"); // gitleaks:allow
        let mut exc = exception(&format!("boom {fake_secret} for alice@example.com"));
        scrub::scrub_exception(&mut exc, cfg.filter());

        let body = build_request_body(&cfg, &exc, &[], None);
        assert_eq!(body["api_key"], "phc_test_public");
        assert_eq!(body["distinct_id"], "agt_test");

        let rendered = body.to_string();
        assert!(
            !rendered.contains(&fake_secret),
            "the panic message reached the wire unscrubbed"
        );
    }

    /// No SDK sets `$exception_level`, so this module does. An absent level is an event
    /// PostHog cannot triage by severity.
    #[test]
    fn the_request_body_carries_the_level_release_and_environment() {
        let cfg = config("production");
        let body = build_request_body(&cfg, &exception("boom"), &[], None);
        assert_eq!(body["event"], "$exception");
        let props = &body["properties"];
        assert_eq!(props["$exception_level"], "fatal");
        assert_eq!(props["environment"], "production");
        assert_eq!(props["release"], "deadbeef");
        assert!(props["$exception_list"].is_array());
        assert!(props["$debug_images"].is_array());
        assert_eq!(props["$exception_list"][0]["type"], "panic");
        assert_eq!(props["$exception_list"][0]["stacktrace"]["type"], "raw");
    }

    #[test]
    fn the_panic_location_rides_its_own_properties() {
        let cfg = config("production");
        let loc = Location::caller();
        let body = build_request_body(&cfg, &exception("boom"), &[], Some(loc));
        let props = &body["properties"];
        assert_eq!(props["$exception_panic_file"], loc.file());
        assert_eq!(props["$exception_panic_line"], loc.line());
        assert_eq!(props["$exception_panic_column"], loc.column());
    }

    /// THE REGRESSION THIS PINS: a first-writer-wins cell here would silently label
    /// every daemon panic `cli`, because `main()` always tags `cli` before dispatching
    /// and the daemon re-enters that same `main()`. Ordering is the whole test.
    #[test]
    fn the_daemon_scope_replaces_the_cli_scope_main_set_first() {
        let _guard = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());

        set_cli_scope("daemon");
        let after_cli = process_scope().expect("cli scope installed");
        assert_eq!(after_cli["process_type"], "cli");
        assert_eq!(after_cli["command"], "daemon");

        set_daemon_scope(7443, 4242);
        let after_daemon = process_scope().expect("daemon scope installed");
        assert_eq!(after_daemon["process_type"], "daemon");
        assert_eq!(after_daemon["port"], 7443);
        assert_eq!(after_daemon["pid"], 4242);
        assert!(
            !after_daemon.contains_key("command"),
            "the daemon scope replaces the cli one rather than merging into it"
        );

        // And the tags actually reach the wire, which is the point of setting them.
        let cfg = config("production");
        let body = build_request_body(&cfg, &exception("boom"), &[], None);
        let props = &body["properties"];
        assert_eq!(props["process_type"], "daemon");
        assert_eq!(props["port"], 7443);
        assert_eq!(props["pid"], 4242);
    }

    /// The end-to-end shape, built the way `capture_panic` builds it: a real backtrace,
    /// real modules, scrubbed, trimmed.
    ///
    /// The COUNT assertions matter as much as the shape ones. The failure this module
    /// exists to avoid is a well-formed event that never symbolicates, and both routes to
    /// it — no frame acquiring an `image_addr`, or every module coming back with an empty
    /// `debug_id` — produce a payload that passes every per-element check while carrying
    /// nothing to match a symbol set against.
    #[test]
    fn a_captured_payload_is_well_formed_end_to_end() {
        let cfg = config("production");
        let bt = backtrace::Backtrace::new();
        let modules = images::collect_loaded_modules();
        assert!(
            !modules.is_empty(),
            "a running process always has at least its own executable mapped"
        );
        let captured = frames::build_frames(&bt, &modules);
        assert!(
            captured.iter().any(|f| f.image_addr.is_some()),
            "no frame matched any module: find_module or the module ranges are wrong"
        );
        let mut exc = Exception {
            exception_type: "panic".into(),
            value: "boom".into(),
            mechanism: Some(Mechanism::panic()),
            thread_id: None,
            stacktrace: Stacktrace::Raw { frames: captured },
        };
        scrub::scrub_exception(&mut exc, cfg.filter());
        let debug_images = images::referenced_images(&modules, exc.stacktrace.frames());

        let body = build_request_body(&cfg, &exc, &debug_images, None);
        let frames_json = &body["properties"]["$exception_list"][0]["stacktrace"]["frames"];
        let frames_json = frames_json.as_array().expect("frames is an array");
        assert!(!frames_json.is_empty());
        for frame in frames_json {
            let obj = frame.as_object().expect("frame is an object");
            assert!(obj.contains_key("in_app"), "in_app missing: {frame}");
            assert_eq!(obj["platform"], "native");
        }
        let images_json = body["properties"]["$debug_images"]
            .as_array()
            .expect("images is an array");
        assert!(
            !images_json.is_empty(),
            "every referenced module came back with no debug id — nothing here can ever \
             symbolicate, and an empty array is exactly what that looks like"
        );
        for image in images_json {
            assert!(
                image["debug_id"].as_str().is_some_and(|s| !s.is_empty()),
                "an image with no debug id can match no symbol set: {image}"
            );
            assert!(
                image["image_addr"].as_str().is_some_and(|s| !s.is_empty()),
                "image_addr is required for the address match: {image}"
            );
        }
    }
}