Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

8.0 KB
Raw Blame
//! Registry of ingestion warning types emitted by Rust services.
//!
//! The `WarningType` enum — every registered type with its `as_str()` tag and
//! registry-declared `category()`/`severity()` — is generated at build time (see
//! `build.rs`) from `warning_types.generated.json`, which mirrors the whole
//! Node.js registry, the single source of truth for the warning taxonomy
//! (`nodejs/src/ingestion/common/ingestion-warning-types.ts`). The taxonomy is
//! producer-agnostic: which service emits which type is not registry data — each
//! producer references the variants it emits, and the message's `source` field
//! records who said it.
//!
//! `from_tag` is a hand-written allowlist mapping capture error tags to warning
//! types: only tags registered here ever produce a warning. Unknown or
//! deliberately excluded tags (auth/transport/server errors, intentional drops
//! like `dropped_performance_event`) map to `None` and emit nothing. The
//! allowlist's domain is welded by test to the registry's `captureProduced`
//! flags — the Node consumer's trust allowlist for the capture envelope —
//! since skew in either direction silently drops warnings: a flagged type
//! without an arm is never emitted, and an arm without the flag is emitted
//! but rejected at the consumer. An arm for a type removed from the registry
//! stops compiling.

// Brings in `pub enum WarningType` with `ALL`, `as_str`, `category`, and
// `severity`.
include!(concat!(env!("OUT_DIR"), "/warning_types.rs"));

impl WarningType {
    /// Types capture emits directly, with no error tag behind them.
    ///
    /// The tag route only reaches conditions capture already models as an
    /// `Error` or a per-event drop detail. Two kinds of warning sit outside it:
    ///
    /// * Ones that aren't failures at all. A rate-limited event is ingested
    ///   (degraded, not dropped), so there is no tag to map and inventing one
    ///   would mean inventing an error that never gets returned.
    /// * Ones from a pipeline that has no tag vocabulary. The AI endpoints
    ///   reject via their own typed conditions, not `v1::Error`, so their tags
    ///   would be strings no `Error` ever produces. The replay endpoint is the
    ///   same case from the other direction: its conditions are `CaptureError`
    ///   variants v1 analytics never returns, so no `Error::tag()` names them.
    ///
    /// Emit sites for these name the variant directly.
    ///
    /// This list exists so the trust-allowlist invariant below can still be
    /// airtight: `captureProduced` must equal "reachable by one of capture's two
    /// emit routes", and without this the direct route would be invisible to it.
    pub const DIRECT_EMIT: [Self; 9] = [
        Self::HighVolumeDistinctId,
        Self::DistinctIdTruncated,
        Self::InvalidAiEvent,
        Self::InvalidAiPayload,
        Self::NoAiSpansIngested,
        Self::MisroutedEvent,
        Self::MissingSessionId,
        Self::InvalidSessionId,
        Self::MissingSnapshotData,
    ];

    /// Map a capture error tag (`v1::Error::tag()` / per-event drop detail) to a
    /// registered warning type. Returns `None` for anything not on the allowlist —
    /// callers emit nothing in that case. Direct-emit types are deliberately
    /// absent: see [`WarningType::DIRECT_EMIT`].
    pub fn from_tag(tag: &str) -> Option<Self> {
        match tag {
            "missing_event_name" => Some(Self::MissingEventName),
            "event_name_too_long" => Some(Self::EventNameTooLong),
            "missing_distinct_id" => Some(Self::MissingDistinctId),
            "distinct_id_too_large" => Some(Self::DistinctIdTooLarge),
            "invalid_event_timestamp" => Some(Self::InvalidEventTimestamp),
            "malformed_event_properties" => Some(Self::MalformedEventProperties),
            "invalid_options" => Some(Self::InvalidOptions),
            "empty_batch" => Some(Self::EmptyBatch),
            "invalid_batch" => Some(Self::InvalidBatch),
            "missing_event_uuid" => Some(Self::MissingEventUuid),
            "invalid_event_uuid" => Some(Self::InvalidEventUuid),
            "duplicate_event_uuid" => Some(Self::DuplicateEventUuid),
            "message_size_too_large" => Some(Self::MessageSizeTooLarge),
            // The v1 AI lane's per-event ceiling. v0 reports the same condition
            // as `CaptureError::AiEventTooBig`, which already maps here, so
            // moving AI traffic onto the v1 endpoint keeps the warning a
            // project owner already sees for an oversized event. An alias, not
            // a second route: `MessageSizeTooLarge` stays tag-derived, so the
            // one-route-per-type invariant below is untouched.
            "ai_event_too_big" => Some(Self::MessageSizeTooLarge),
            _ => None,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use rstest::rstest;

    #[test]
    fn capture_emit_routes_equal_the_capture_trust_allowlist() {
        // Two hand-maintained answers to "which types does capture emit?" must
        // stay equal: capture's emit routes here (`from_tag` plus
        // `DIRECT_EMIT`) and the registry's `captureProduced` flags (the Node
        // consumer's trust allowlist, carried through the artifact). Skew fails
        // silently in production in either direction — a flagged type on
        // neither route is never emitted; a type on a route without the flag is
        // emitted and then rejected at the consumer's trust check.
        //
        // Comparing the variant itself (not just presence) pins each `from_tag`
        // arm to the right type, so a mis-mapped tag can't hide behind an
        // unrelated `Some`.
        for warning in WarningType::ALL {
            let tag_derived = WarningType::from_tag(warning.as_str()) == Some(warning);
            let direct = WarningType::DIRECT_EMIT.contains(&warning);

            assert_eq!(
                tag_derived || direct,
                warning.capture_produced(),
                "{}: emit routes and captureProduced flag disagree — add the missing side",
                warning.as_str()
            );

            // One route per type. Both would mean a warning capture can produce
            // two ways, with the tag route silently winning wherever a tag is
            // available, so its details would differ by call path.
            assert!(
                !(tag_derived && direct),
                "{}: on both emit routes — pick one",
                warning.as_str()
            );
        }
    }

    // Excluded on purpose: intentional drops, auth/transport/server errors, and
    // ops-imposed drops are not data-quality signals for the v2 surface.
    //
    // "Post-validation" is not itself the test -- customer-actionable is.
    // `event_restriction` is excluded because the operator caused it and the
    // project owner cannot act on it; `ai_event_too_big` is included, after the
    // same stage, because the customer sent an oversized event and v0 already
    // tells them so.
    #[rstest]
    #[case::intentional_drop("dropped_performance_event")]
    #[case::auth("invalid_api_token")]
    #[case::auth_missing("missing_authorization")]
    #[case::transport("payload_too_large")]
    #[case::transport_decoding("request_decoding_error")]
    #[case::transport_parsing("request_parsing_error")]
    #[case::transport_encoding("unsupported_content_encoding")]
    #[case::timeout("request_timeout")]
    #[case::server("internal_error")]
    #[case::server_unavailable("service_unavailable")]
    #[case::billing("billing_limit_exceeded")]
    #[case::post_validation("event_restriction")]
    #[case::sink("rejected")]
    #[case::unknown("some_future_tag")]
    #[case::empty("")]
    // Direct-emit types must stay off the tag route even though their name reads
    // like a tag, or they'd be reachable both ways.
    #[case::direct_emit("high_volume_distinct_id")]
    fn from_tag_rejects_unregistered_tags(#[case] tag: &str) {
        assert_eq!(
            WarningType::from_tag(tag),
            None,
            "tag {tag:?} must not emit"
        );
    }
}