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.

17.3 KB
Raw Blame
use std::net::IpAddr;

use axum::http::{header, HeaderMap, Method};
use axum_client_ip::InsecureClientIp;
use chrono::{DateTime, Utc};
use common_ingestion_warnings::{WarningRequestContext, UNKNOWN_ATTRIBUTION};
use uuid::Uuid;

use crate::token::validate_token;
use crate::v1::constants::*;
use crate::v1::Error;

/// CaptureMode-agnostic request context shared by every v1 capture mode.
/// Product-specific query state lives in a per-mode wrapper (e.g.
/// `v1::analytics::Context`) that carries `raw_query` refined into a typed view.
#[derive(Debug, Clone)]
pub struct RequestContext {
    pub api_token: String,
    pub user_agent: String,
    pub content_type: String,
    pub content_encoding: Option<String>,
    pub sdk_info: String,
    pub attempt: u32,
    pub request_id: Uuid,
    pub client_timestamp: DateTime<Utc>,
    pub client_ip: IpAddr,
    /// Raw, un-parsed request query string. Each capture mode refines this into
    /// its own typed query when wrapping into a product context.
    pub raw_query: Option<String>,
    pub method: Method,
    pub path: &'static str,
    pub server_received_at: DateTime<Utc>,
    pub created_at: Option<String>,
    pub capture_internal: bool,
    pub historical_migration: bool,
    /// AI-gateway provenance signature parsed from the request headers, if present.
    pub gateway_signature: Option<super::gateway_provenance::GatewaySignature>,
}

/// Extracts a required header as &str, assuming presence was already checked.
fn header_str<'a>(headers: &'a HeaderMap, name: &str) -> Result<&'a str, Error> {
    headers
        .get(name)
        .and_then(|v| v.to_str().ok())
        .ok_or_else(|| {
            Error::InvalidHeaderValue(format!("{name} contains non-visible ASCII characters"))
        })
}

impl RequestContext {
    pub fn clock_skew(&self) -> chrono::Duration {
        self.client_timestamp
            .signed_duration_since(self.server_received_at)
    }

    /// Parse `PostHog-Sdk-Info` (`<canonical-$lib-name>/<semver>`, split at
    /// the last '/') into `($lib, $lib_version)`. Returns `None` for malformed
    /// or oversized values — callers skip injection, never inject placeholders.
    pub fn sdk_lib_and_version(&self) -> Option<(&str, &str)> {
        if self.sdk_info.len() > MAX_SDK_INFO_LEN {
            return None;
        }
        let (lib, version) = self.sdk_info.rsplit_once('/')?;
        let (lib, version) = (lib.trim(), version.trim());
        if lib.is_empty() || version.is_empty() {
            return None;
        }
        Some((lib, version))
    }

    /// Attribution stamped onto every ingestion warning this request produces.
    ///
    /// [`Self::sdk_lib_and_version`] is all-or-nothing — the header is a single
    /// `name/version` string — so both fields fall back together. Unlike the
    /// injection callers, a warning always needs both keys present, so this
    /// stamps the unknown placeholder rather than skipping them.
    pub fn warning_context(&self) -> WarningRequestContext {
        let (lib, lib_version) = self
            .sdk_lib_and_version()
            .unwrap_or((UNKNOWN_ATTRIBUTION, UNKNOWN_ATTRIBUTION));
        WarningRequestContext {
            token: self.api_token.clone(),
            lib: lib.to_string(),
            lib_version: lib_version.to_string(),
            path: self.path.to_string(),
        }
    }

    pub fn new(
        headers: &HeaderMap,
        ip: &InsecureClientIp,
        raw_query: Option<String>,
        method: Method,
        path: &'static str,
    ) -> Result<Self, Error> {
        // Authorization checked first — missing auth is 401, not 400
        if headers.get(header::AUTHORIZATION).is_none() {
            return Err(Error::MissingAuthorization);
        }

        // Missing-headers gate: collect all absent required headers at once
        let missing: Vec<String> = REQUIRED_HEADERS
            .iter()
            .filter(|name| headers.get(**name).is_none())
            .map(|name| name.to_string())
            .collect();

        if !missing.is_empty() {
            return Err(Error::MissingRequiredHeaders(missing));
        }

        // All required headers are present — validate each one
        // The Bearer scheme is case-insensitive per RFC 6750 Section 1.1.
        let auth_raw = header_str(headers, header::AUTHORIZATION.as_str())?;
        let token_raw = if auth_raw.len() > 7 && auth_raw[..7].eq_ignore_ascii_case("Bearer ") {
            auth_raw[7..].trim()
        } else {
            return Err(Error::InvalidHeaderValue(
                "Authorization must use Bearer scheme".into(),
            ));
        };
        validate_token(token_raw).map_err(|reason| Error::InvalidApiToken(reason.to_string()))?;
        let api_token = token_raw.to_string();

        let content_type_raw = header_str(headers, "content-type")?;
        let mime_type = content_type_raw
            .split(';')
            .next()
            .unwrap_or("")
            .trim()
            .to_ascii_lowercase();
        if mime_type != "application/json" {
            return Err(Error::UnsupportedContentType(content_type_raw.to_string()));
        }
        let content_type = content_type_raw.to_string();

        let content_encoding = match headers.get("content-encoding") {
            Some(val) => {
                let enc_raw = val.to_str().map_err(|_| {
                    Error::InvalidHeaderValue(
                        "Content-Encoding contains non-visible ASCII characters".into(),
                    )
                })?;
                let enc = enc_raw.to_ascii_lowercase();
                if !SUPPORTED_ENCODINGS.contains(&enc.as_str()) {
                    return Err(Error::UnsupportedEncoding(enc_raw.to_string()));
                }
                Some(enc)
            }
            None => None,
        };

        let request_id_raw = header_str(headers, POSTHOG_REQUEST_ID)?;
        let request_id = Uuid::parse_str(request_id_raw).map_err(|_| {
            Error::InvalidHeaderValue(format!(
                "{POSTHOG_REQUEST_ID} is not a valid UUID: {request_id_raw}"
            ))
        })?;

        let attempt_raw = header_str(headers, POSTHOG_ATTEMPT)?;
        let attempt: u32 = attempt_raw
            .parse::<u32>()
            .ok()
            .filter(|&n| n >= 1)
            .ok_or_else(|| {
                Error::InvalidHeaderValue(format!(
                    "{POSTHOG_ATTEMPT} must be a positive integer: {attempt_raw}"
                ))
            })?;

        let client_ts_raw = header_str(headers, POSTHOG_REQUEST_TIMESTAMP)?;
        let client_timestamp: DateTime<Utc> = DateTime::parse_from_rfc3339(client_ts_raw)
            .map(|dt| dt.with_timezone(&Utc))
            .map_err(|_| {
                Error::InvalidHeaderValue(format!(
                    "{POSTHOG_REQUEST_TIMESTAMP} is not valid RFC 3339: {client_ts_raw}"
                ))
            })?;

        let user_agent = header_str(headers, "user-agent")?.to_string();
        let sdk_info = header_str(headers, POSTHOG_SDK_INFO)?.to_string();

        let gateway_signature = super::gateway_provenance::parse_signature(headers);

        Ok(Self {
            api_token,
            user_agent,
            content_type,
            content_encoding,
            sdk_info,
            attempt,
            request_id,
            client_timestamp,
            client_ip: ip.0,
            raw_query,
            method,
            path,
            server_received_at: Utc::now(),
            created_at: None,
            capture_internal: false,
            historical_migration: false,
            gateway_signature,
        })
    }

    /// Stamp request-level batch metadata. Takes primitives (not an
    /// analytics `Batch`) so the shared context stays CaptureMode-agnostic;
    /// product wrappers extract these from their own batch envelope.
    pub fn set_batch_metadata(
        &mut self,
        created_at: Option<String>,
        capture_internal: bool,
        historical_migration: bool,
    ) {
        self.created_at = created_at;
        self.capture_internal = capture_internal;
        self.historical_migration = historical_migration;
    }
}

#[cfg(test)]
mod tests {
    use std::net::{IpAddr, Ipv4Addr};

    use axum::http::{HeaderMap, HeaderValue, Method};
    use axum_client_ip::InsecureClientIp;
    use uuid::Uuid;

    use super::*;
    use crate::v1::analytics::constants::CAPTURE_V1_PATH;

    fn test_context(headers: &HeaderMap) -> Result<RequestContext, Error> {
        RequestContext::new(
            headers,
            &InsecureClientIp(IpAddr::V4(Ipv4Addr::LOCALHOST)),
            None,
            Method::POST,
            CAPTURE_V1_PATH,
        )
    }

    fn valid_headers() -> HeaderMap {
        let mut h = HeaderMap::new();
        h.insert(
            header::AUTHORIZATION,
            HeaderValue::from_static("Bearer phc_test_token_123"),
        );
        h.insert(
            POSTHOG_SDK_INFO,
            HeaderValue::from_static("posthog-rs/1.0.0"),
        );
        h.insert(POSTHOG_ATTEMPT, HeaderValue::from_static("1"));
        h.insert(
            POSTHOG_REQUEST_ID,
            HeaderValue::from_str(&Uuid::new_v4().to_string()).unwrap(),
        );
        h.insert(
            POSTHOG_REQUEST_TIMESTAMP,
            HeaderValue::from_static("2025-01-15T10:30:00Z"),
        );
        h.insert("content-type", HeaderValue::from_static("application/json"));
        h.insert("user-agent", HeaderValue::from_static("test-agent/1.0"));
        h
    }

    #[test]
    fn all_valid_headers_returns_ok() {
        let headers = valid_headers();
        let ctx = test_context(&headers);
        assert!(ctx.is_ok());
        let ctx = ctx.unwrap();
        assert_eq!(ctx.api_token, "phc_test_token_123");
        assert_eq!(ctx.attempt, 1);
        assert_eq!(ctx.content_type, "application/json");
        assert!(ctx.content_encoding.is_none());
        assert!(ctx.created_at.is_none());
        assert!(!ctx.capture_internal);
        assert!(!ctx.historical_migration);
    }

    #[test]
    fn missing_authorization_returns_401() {
        let mut headers = valid_headers();
        headers.remove(header::AUTHORIZATION.as_str());
        let err = test_context(&headers).unwrap_err();
        assert!(matches!(err, Error::MissingAuthorization));
    }

    #[test]
    fn missing_single_required_header() {
        let mut headers = valid_headers();
        headers.remove("user-agent");
        let err = test_context(&headers).unwrap_err();
        match err {
            Error::MissingRequiredHeaders(names) => {
                assert_eq!(names, vec!["user-agent"]);
            }
            other => panic!("expected MissingRequiredHeaders, got: {other:?}"),
        }
    }

    #[test]
    fn missing_multiple_required_headers() {
        let mut headers = valid_headers();
        headers.remove("user-agent");
        headers.remove("content-type");
        let err = test_context(&headers).unwrap_err();
        match err {
            Error::MissingRequiredHeaders(names) => {
                assert!(names.contains(&"user-agent".to_string()));
                assert!(names.contains(&"content-type".to_string()));
                assert_eq!(names.len(), 2);
            }
            other => panic!("expected MissingRequiredHeaders, got: {other:?}"),
        }
    }

    #[test]
    fn invalid_token_returns_error() {
        let mut headers = valid_headers();
        headers.insert(
            header::AUTHORIZATION,
            HeaderValue::from_static("Bearer phx_personal_key"),
        );
        let err = test_context(&headers).unwrap_err();
        assert!(matches!(err, Error::InvalidApiToken(_)));
    }

    #[test]
    fn bearer_token_whitespace_trimmed() {
        let mut headers = valid_headers();
        headers.insert(
            header::AUTHORIZATION,
            HeaderValue::from_static("Bearer   phc_test_token_123  "),
        );
        let ctx = test_context(&headers).unwrap();
        assert_eq!(ctx.api_token, "phc_test_token_123");
    }

    #[test]
    fn bearer_scheme_case_insensitive() {
        for scheme in &["bearer ", "BEARER ", "beaRER "] {
            let val = format!("{scheme}phc_test_token_123");
            let mut headers = valid_headers();
            headers.insert(header::AUTHORIZATION, HeaderValue::from_str(&val).unwrap());
            let ctx = test_context(&headers).unwrap();
            assert_eq!(
                ctx.api_token, "phc_test_token_123",
                "failed for scheme: {scheme}"
            );
        }
    }

    #[test]
    fn bad_authorization_format() {
        let mut headers = valid_headers();
        headers.insert(
            header::AUTHORIZATION,
            HeaderValue::from_static("Basic abc123"),
        );
        let err = test_context(&headers).unwrap_err();
        assert!(matches!(err, Error::InvalidHeaderValue(_)));
    }

    #[test]
    fn wrong_content_type() {
        let mut headers = valid_headers();
        headers.insert("content-type", HeaderValue::from_static("text/plain"));
        let err = test_context(&headers).unwrap_err();
        assert!(matches!(err, Error::UnsupportedContentType(_)));
    }

    #[test]
    fn content_type_with_charset() {
        let mut headers = valid_headers();
        headers.insert(
            "content-type",
            HeaderValue::from_static("application/json; charset=utf-8"),
        );
        let ctx = test_context(&headers).unwrap();
        assert_eq!(ctx.content_type, "application/json; charset=utf-8");
    }

    #[test]
    fn content_type_case_insensitive() {
        let mut headers = valid_headers();
        headers.insert("content-type", HeaderValue::from_static("Application/JSON"));
        let ctx = test_context(&headers).unwrap();
        assert_eq!(ctx.content_type, "Application/JSON");
    }

    #[test]
    fn bad_content_encoding() {
        let mut headers = valid_headers();
        headers.insert("content-encoding", HeaderValue::from_static("lz4"));
        let err = test_context(&headers).unwrap_err();
        assert!(matches!(err, Error::UnsupportedEncoding(_)));
    }

    #[test]
    fn valid_content_encoding() {
        let mut headers = valid_headers();
        headers.insert("content-encoding", HeaderValue::from_static("gzip"));
        let ctx = test_context(&headers).unwrap();
        assert_eq!(ctx.content_encoding, Some("gzip".to_string()));
    }

    #[test]
    fn invalid_uuid_request_id() {
        let mut headers = valid_headers();
        headers.insert(POSTHOG_REQUEST_ID, HeaderValue::from_static("not-a-uuid"));
        let err = test_context(&headers).unwrap_err();
        assert!(matches!(err, Error::InvalidHeaderValue(_)));
    }

    #[test]
    fn non_numeric_attempt() {
        let mut headers = valid_headers();
        headers.insert(POSTHOG_ATTEMPT, HeaderValue::from_static("abc"));
        let err = test_context(&headers).unwrap_err();
        assert!(matches!(err, Error::InvalidHeaderValue(_)));
    }

    #[test]
    fn zero_attempt_returns_error() {
        let mut headers = valid_headers();
        headers.insert(POSTHOG_ATTEMPT, HeaderValue::from_static("0"));
        let err = test_context(&headers).unwrap_err();
        assert!(matches!(err, Error::InvalidHeaderValue(_)));
    }

    #[test]
    fn sdk_lib_and_version_parses_canonical_format() {
        let headers = valid_headers();
        let ctx = test_context(&headers).unwrap();
        assert_eq!(ctx.sdk_lib_and_version(), Some(("posthog-rs", "1.0.0")));
    }

    #[test]
    fn sdk_lib_and_version_splits_at_last_slash() {
        let mut headers = valid_headers();
        headers.insert(
            POSTHOG_SDK_INFO,
            HeaderValue::from_static("posthog/sub-sdk/2.3.4"),
        );
        let ctx = test_context(&headers).unwrap();
        assert_eq!(
            ctx.sdk_lib_and_version(),
            Some(("posthog/sub-sdk", "2.3.4"))
        );
    }

    #[test]
    fn sdk_lib_and_version_trims_whitespace() {
        let mut headers = valid_headers();
        headers.insert(
            POSTHOG_SDK_INFO,
            HeaderValue::from_static("  posthog-rs / 1.2.3  "),
        );
        let ctx = test_context(&headers).unwrap();
        assert_eq!(ctx.sdk_lib_and_version(), Some(("posthog-rs", "1.2.3")));
    }

    #[test]
    fn sdk_lib_and_version_rejects_oversized_value() {
        let mut headers = valid_headers();
        let long = format!("posthog-rs/{}", "9".repeat(MAX_SDK_INFO_LEN));
        headers.insert(POSTHOG_SDK_INFO, HeaderValue::from_str(&long).unwrap());
        let ctx = test_context(&headers).unwrap();
        assert_eq!(ctx.sdk_lib_and_version(), None);
    }

    #[test]
    fn sdk_lib_and_version_rejects_malformed_values() {
        for bad in &["no-slash", "/1.0.0", "posthog-rs/", "/", "", "   /   "] {
            let mut headers = valid_headers();
            headers.insert(POSTHOG_SDK_INFO, HeaderValue::from_str(bad).unwrap());
            let ctx = test_context(&headers).unwrap();
            assert_eq!(
                ctx.sdk_lib_and_version(),
                None,
                "expected None for sdk_info: {bad:?}"
            );
        }
    }

    #[test]
    fn invalid_rfc3339_timestamp() {
        let mut headers = valid_headers();
        headers.insert(
            POSTHOG_REQUEST_TIMESTAMP,
            HeaderValue::from_static("not-a-timestamp"),
        );
        let err = test_context(&headers).unwrap_err();
        assert!(matches!(err, Error::InvalidHeaderValue(_)));
    }
}