: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
//! Endpoint-level coverage for AI event routing on analytics deployments:
//! HTTP request -> router state -> `process_events` -> sink. The pipeline
//! tests in `events::analytics` exercise `process_events` directly, so they
//! cannot catch a regression in the router wiring (capture mode or the AI
//! limiter not reaching the pipeline) or in the endpoint-level batch handling
//! of mixed AI / non-AI payloads.
#[path = "common/integration_utils.rs"]
mod integration_utils;
use async_trait::async_trait;
use axum::http::StatusCode;
use axum::Router;
use axum_test_helper::TestClient;
use capture::api::CaptureError;
use capture::config::CaptureMode;
use capture::outputs::{OutputRegistry, PreparedEvent, PublishEvents, PublishPrepared};
use capture::quota_limiters::CaptureQuotaLimiter;
use capture::router::router;
use capture::sinks::sink::SinkResult;
use capture::time::TimeSource;
use capture::v0_request::{DataType, OverflowReason, ProcessedEvent};
use chrono::{DateTime, Utc};
use common_redis::MockRedisClient;
use integration_utils::{test_lifecycle_handlers, DEFAULT_CONFIG, DEFAULT_TEST_TIME};
use limiters::overflow::OverflowLimiter;
use limiters::token_dropper::TokenDropper;
use rstest::rstest;
use serde_json::json;
use std::num::NonZeroU32;
use std::sync::Arc;
use std::time::Duration;
const TOKEN: &str = "phc_ai_routing_test_token";
const DISTINCT_ID: &str = "test_user";
struct FixedTime {
pub time: DateTime<Utc>,
}
impl TimeSource for FixedTime {
fn current_time(&self) -> DateTime<Utc> {
self.time
}
}
#[derive(Clone)]
struct CapturingSink {
events: Arc<tokio::sync::Mutex<Vec<ProcessedEvent>>>,
}
impl CapturingSink {
fn new() -> Self {
Self {
events: Arc::new(tokio::sync::Mutex::new(Vec::new())),
}
}
async fn get_events(&self) -> Vec<ProcessedEvent> {
self.events.lock().await.clone()
}
}
#[async_trait]
impl PublishEvents for CapturingSink {
async fn publish_events(&self, events: Vec<ProcessedEvent>) -> Result<(), CaptureError> {
self.events.lock().await.extend(events);
Ok(())
}
}
#[async_trait]
impl PublishPrepared for CapturingSink {
async fn publish_prepared(&self, _events: Vec<PreparedEvent>) -> Vec<SinkResult> {
unreachable!("v0 endpoints publish events")
}
}
fn setup_analytics_router(
overflow_limiter: Option<Arc<OverflowLimiter>>,
ai_events_overflow_limiter: Option<Arc<OverflowLimiter>>,
) -> (Router, CapturingSink) {
setup_router_for_mode(
CaptureMode::Events,
overflow_limiter,
ai_events_overflow_limiter,
)
}
fn setup_router_for_mode(
capture_mode: CaptureMode,
overflow_limiter: Option<Arc<OverflowLimiter>>,
ai_events_overflow_limiter: Option<Arc<OverflowLimiter>>,
) -> (Router, CapturingSink) {
let (readiness, liveness, _monitor) = test_lifecycle_handlers();
let sink = CapturingSink::new();
let sink_clone = sink.clone();
let timesource = FixedTime {
time: DateTime::parse_from_rfc3339(DEFAULT_TEST_TIME)
.expect("Invalid fixed time format")
.with_timezone(&Utc),
};
let redis = Arc::new(MockRedisClient::new());
let mut cfg = DEFAULT_CONFIG.clone();
cfg.capture_mode = capture_mode;
let quota_limiter =
CaptureQuotaLimiter::new(&cfg, redis.clone(), Duration::from_secs(60 * 60 * 24 * 7));
let router = router(
timesource,
readiness,
liveness,
Arc::new(OutputRegistry::single(sink)),
redis,
None, // global_rate_limiter_token_distinctid
quota_limiter,
TokenDropper::default(),
None, // event_restriction_service
None, // recorder_handle
capture_mode,
None,
25 * 1024 * 1024,
false,
1_i64,
false,
0.0_f32,
26_214_400,
983_040, // ai_max_event_bytes (960KB)
None,
256, // body_read_chunk_size_kb
10 * 1024 * 1024, // capture_v1_max_compressed_body_bytes
50 * 1024 * 1024, // capture_v1_max_decompressed_body_bytes
overflow_limiter,
ai_events_overflow_limiter,
None, // ai_byte_rate_limiter
None, // replay_overflow_limiter
8, // capture_v1_scatter_gather_min_batch
None, // ai_gateway_signing_secret
None, // ingestion_warning_emitter
);
(router, sink_clone)
}
fn mixed_batch_payload() -> String {
json!({
"api_key": TOKEN,
"batch": [
{
"event": "$ai_generation",
"distinct_id": DISTINCT_ID,
"properties": {"$ai_model": "gpt-4"}
},
{
"event": "$pageview",
"distinct_id": DISTINCT_ID,
"properties": {}
}
]
})
.to_string()
}
// Two AI event names. capture-ai rejects a batch carrying anything
// else, so its lane-assignment coverage has to use an all-AI batch.
fn ai_only_batch_payload() -> String {
json!({
"api_key": TOKEN,
"batch": [
{
"event": "$ai_generation",
"distinct_id": DISTINCT_ID,
"properties": {"$ai_model": "gpt-4"}
},
{
"event": "$ai_span",
"distinct_id": DISTINCT_ID,
"properties": {}
}
]
})
.to_string()
}
// The same mixed batch flagged as a historical migration — the only kind of
// batch Import mode accepts.
fn historical_mixed_batch_payload() -> String {
json!({
"api_key": TOKEN,
"historical_migration": true,
"batch": [
{
"event": "$ai_generation",
"distinct_id": DISTINCT_ID,
"properties": {"$ai_model": "gpt-4"}
},
{
"event": "$pageview",
"distinct_id": DISTINCT_ID,
"properties": {}
}
]
})
.to_string()
}
async fn post_batch(client: &TestClient, payload: String) {
let response = client
.post("/batch")
.header("Content-Type", "application/json")
.header("X-Forwarded-For", "127.0.0.1")
.body(payload)
.send()
.await;
assert_eq!(response.status(), StatusCode::OK);
}
#[rstest]
#[case("/e")]
#[case("/batch")]
#[tokio::test]
async fn legacy_routes_strip_forged_gateway_properties(#[case] path: &str) {
let (router, sink) = setup_analytics_router(None, None);
let client = TestClient::new(router);
let event = json!({
"event": "$ai_span",
"distinct_id": DISTINCT_ID,
"properties": {
"$ai_gateway_verified": true,
"$ai_gateway_relay": true,
"$ai_gateway_request_id": "forged",
"$ai_trace_id": "trace-1"
}
});
let payload = if path == "/batch" {
json!({"api_key": TOKEN, "batch": [event]}).to_string()
} else {
json!({
"api_key": TOKEN,
"event": "$ai_span",
"distinct_id": DISTINCT_ID,
"properties": event["properties"].clone()
})
.to_string()
};
let response = client
.post(path)
.header("Content-Type", "application/json")
.header("X-Forwarded-For", "127.0.0.1")
.body(payload)
.send()
.await;
assert_eq!(response.status(), StatusCode::OK);
let events = sink.get_events().await;
let data: serde_json::Value = serde_json::from_str(&events[0].event.data).unwrap();
assert_eq!(data["properties"]["$ai_trace_id"], "trace-1");
assert!(data["properties"].get("$ai_gateway_verified").is_none());
assert!(data["properties"].get("$ai_gateway_relay").is_none());
assert!(data["properties"].get("$ai_gateway_request_id").is_none());
}
/// A mixed batch must split lanes: AI events divert to the AI lane on
/// analytics deployments, and the `$pageview` stays on the analytics lane.
#[tokio::test]
async fn mixed_batch_diverts_only_ai_events() {
let (router, sink) = setup_analytics_router(None, None);
let client = TestClient::new(router);
post_batch(&client, mixed_batch_payload()).await;
let events = sink.get_events().await;
assert_eq!(events.len(), 2);
let ai_event = events
.iter()
.find(|e| e.metadata.event_name == "$ai_generation")
.expect("$ai_generation must reach the sink");
assert_eq!(ai_event.metadata.data_type, DataType::AiEvents);
assert_eq!(
ai_event.metadata.overflow_reason, None,
"no limiter is configured, so nothing may stamp overflow"
);
let pageview = events
.iter()
.find(|e| e.metadata.event_name == "$pageview")
.expect("$pageview must reach the sink");
assert_eq!(pageview.metadata.data_type, DataType::AnalyticsMain);
}
/// Capture mode does not change lane assignment: an Ai-mode deployment stamps
/// `AiEvents` exactly like an analytics one. Pins the invariant end-to-end, so
/// a deployment can never silently rejoin AI events to the analytics lane and
/// slip past every AI-lane gate (byte limiter, ai restrictions, AI overflow).
///
/// The batch is all-AI because capture-ai refuses anything else; the mixed-batch
/// half of the old version of this test now lives below.
#[tokio::test]
async fn ai_mode_diverts_ai_events_like_every_other_mode() {
let (router, sink) = setup_router_for_mode(CaptureMode::Ai, None, None);
let client = TestClient::new(router);
let response = client
.post("/i/v0/ai/batch")
.header("Content-Type", "application/json")
.header("X-Forwarded-For", "127.0.0.1")
.body(ai_only_batch_payload())
.send()
.await;
assert_eq!(response.status(), StatusCode::OK);
let events = sink.get_events().await;
assert_eq!(events.len(), 2);
assert!(
events
.iter()
.all(|e| e.metadata.data_type == DataType::AiEvents),
"every AI event must land on the AI lane under Ai mode"
);
}
/// Any `$ai_`-prefixed name lands on the AI lane, end to end through `/batch`.
#[tokio::test]
async fn any_ai_prefixed_name_diverts_to_the_ai_lane() {
let (router, sink) = setup_router_for_mode(CaptureMode::Events, None, None);
let client = TestClient::new(router);
let payload = json!({
"api_key": TOKEN,
"batch": [
{"event": "$ai_generation", "distinct_id": DISTINCT_ID, "properties": {"$ai_model": "gpt-4"}},
{"event": "$ai_custom_step", "distinct_id": DISTINCT_ID, "properties": {}},
{"event": "$pageview", "distinct_id": DISTINCT_ID, "properties": {}}
]
})
.to_string();
post_batch(&client, payload).await;
let events = sink.get_events().await;
assert_eq!(events.len(), 3);
let lane_of = |name: &str| {
events
.iter()
.find(|e| e.metadata.event_name == name)
.unwrap_or_else(|| panic!("{name} must reach the sink"))
.metadata
.data_type
};
assert_eq!(lane_of("$ai_generation"), DataType::AiEvents);
assert_eq!(lane_of("$ai_custom_step"), DataType::AiEvents);
assert_eq!(lane_of("$pageview"), DataType::AnalyticsMain);
}
/// The endpoint-level half of the AI-lane gate. The unit tests in
/// `events::analytics` call `process_events` directly, so only this proves the
/// rejection is reachable through the router and surfaces as a 400.
#[tokio::test]
async fn ai_mode_rejects_a_mixed_batch_through_the_endpoint() {
let (router, sink) = setup_router_for_mode(CaptureMode::Ai, None, None);
let client = TestClient::new(router);
let response = client
.post("/i/v0/ai/batch")
.header("Content-Type", "application/json")
.header("X-Forwarded-For", "127.0.0.1")
.body(mixed_batch_payload())
.send()
.await;
assert_eq!(response.status(), StatusCode::BAD_REQUEST);
assert!(
sink.get_events().await.is_empty(),
"rejecting the batch must not publish the AI event ahead of the offender"
);
}
fn force_keyed_limiter() -> Arc<OverflowLimiter> {
let hot_key = format!("{TOKEN}:{DISTINCT_ID}");
Arc::new(OverflowLimiter::new(
NonZeroU32::new(1_000).unwrap(),
NonZeroU32::new(1_000).unwrap(),
Some(hot_key),
false, // preserve_locality
))
}
#[rstest]
#[case::limiter_present(true, Some(OverflowReason::ForceLimited))]
#[case::limiter_absent(false, None)]
#[tokio::test]
async fn ai_lane_limiter_overflow_follows_the_ai_limiter(
#[case] ai_limiter_present: bool,
#[case] expected_ai_reason: Option<OverflowReason>,
) {
let (router, sink) = setup_analytics_router(
Some(force_keyed_limiter()),
ai_limiter_present.then(force_keyed_limiter),
);
let client = TestClient::new(router);
post_batch(&client, mixed_batch_payload()).await;
let events = sink.get_events().await;
assert_eq!(events.len(), 2);
let ai_event = events
.iter()
.find(|e| e.metadata.event_name == "$ai_generation")
.expect("$ai_generation must reach the sink");
assert_eq!(ai_event.metadata.data_type, DataType::AiEvents);
assert_eq!(ai_event.metadata.overflow_reason, expected_ai_reason);
let pageview = events
.iter()
.find(|e| e.metadata.event_name == "$pageview")
.expect("$pageview must reach the sink");
assert_eq!(pageview.metadata.data_type, DataType::AnalyticsMain);
assert_eq!(
pageview.metadata.overflow_reason,
Some(OverflowReason::ForceLimited),
"the analytics lane must keep overflowing regardless of the AI limiter"
);
}
/// The two lanes consult separate limiter instances end-to-end: a key that
/// the analytics limiter force-routes must not drag the same key's diverted
/// AI event into AI overflow (and the pageview must still stamp).
/// Catches the router wiring one limiter instance into both slots.
#[tokio::test]
async fn ai_lane_overflow_isolated_from_analytics_limiter() {
let clean_ai_limiter = Arc::new(OverflowLimiter::new(
NonZeroU32::new(1_000).unwrap(),
NonZeroU32::new(1_000).unwrap(),
None,
false, // preserve_locality
));
let (router, sink) =
setup_analytics_router(Some(force_keyed_limiter()), Some(clean_ai_limiter));
let client = TestClient::new(router);
post_batch(&client, mixed_batch_payload()).await;
let events = sink.get_events().await;
assert_eq!(events.len(), 2);
let ai_event = events
.iter()
.find(|e| e.metadata.event_name == "$ai_generation")
.expect("$ai_generation must reach the sink");
assert_eq!(ai_event.metadata.data_type, DataType::AiEvents);
assert_eq!(
ai_event.metadata.overflow_reason, None,
"the analytics limiter's force-routed key must not stamp the AI lane"
);
let pageview = events
.iter()
.find(|e| e.metadata.event_name == "$pageview")
.expect("$pageview must reach the sink");
assert_eq!(
pageview.metadata.overflow_reason,
Some(OverflowReason::ForceLimited)
);
}
#[tokio::test]
async fn import_mode_historical_batch_never_overflows() {
let (router, sink) =
setup_router_for_mode(CaptureMode::Import, Some(force_keyed_limiter()), None);
let client = TestClient::new(router);
post_batch(&client, historical_mixed_batch_payload()).await;
let events = sink.get_events().await;
assert_eq!(
events.len(),
2,
"both historical events must reach the sink"
);
for event in &events {
let expected = if event.metadata.event_name == "$ai_generation" {
DataType::AiEvents
} else {
DataType::AnalyticsHistorical
};
assert_eq!(
event.metadata.data_type, expected,
"unexpected lane for {}",
event.metadata.event_name,
);
assert_eq!(
event.metadata.overflow_reason, None,
"no lane may overflow in Import mode ({})",
event.metadata.event_name,
);
}
}