: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
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(_)));
}
}