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.

29.4 KB
Raw Blame
#![allow(dead_code)]

use std::net::{IpAddr, Ipv4Addr};

use axum::http::Method;
use chrono::{DateTime, Utc};
use serde_json::value::RawValue;
use uuid::Uuid;

use crate::outputs::PreparedEvent;
use crate::v1::analytics::constants::CAPTURE_V1_PATH;
use crate::v1::analytics::context::Context as AnalyticsContext;
use crate::v1::analytics::query::Query;
use crate::v1::analytics::types::{Event, EventResult, Options, RawOptions, WrappedEvent};
use crate::v1::context::RequestContext;
use crate::v1::types::{Destination, Publishable};

/// Serialize publishable events into `PreparedEvent`s for driving outputs in
/// tests. Accepts `&[&dyn Publishable]` (integration) or `&[&ConcreteType]` (unit)
/// via `?Sized`.
pub fn prepared<E: Publishable + ?Sized>(
    events: &[&E],
    ctx: &RequestContext,
) -> Vec<PreparedEvent> {
    events
        .iter()
        .filter(|e| e.should_publish())
        .map(|e| PreparedEvent {
            uuid: e.uuid(),
            address: e.destination().address(),
            payload: e.serialize(ctx).expect("test payload must serialize"),
            headers: e.headers(ctx),
            partition_key: e.partition_key(ctx),
            ordering: e.ordering(),
        })
        .collect()
}

pub fn raw_obj(s: &str) -> Box<RawValue> {
    RawValue::from_string(s.to_owned()).unwrap()
}

pub fn test_context() -> RequestContext {
    RequestContext {
        api_token: "phc_test_token".to_string(),
        user_agent: "test-agent/1.0".to_string(),
        content_type: "application/json".to_string(),
        content_encoding: None,
        sdk_info: "posthog-rs/1.0.0".to_string(),
        attempt: 1,
        request_id: Uuid::new_v4(),
        client_timestamp: Utc::now(),
        client_ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
        raw_query: None,
        method: Method::POST,
        path: CAPTURE_V1_PATH,
        server_received_at: Utc::now(),
        created_at: Some("2026-03-19T14:30:00.000Z".to_string()),
        capture_internal: false,
        historical_migration: false,
        gateway_signature: None,
    }
}

/// Analytics-mode context wrapping [`test_context`] for tests that drive
/// `process_batch` (which takes `&mut analytics::Context`).
pub fn test_analytics_context() -> AnalyticsContext {
    AnalyticsContext {
        req: test_context(),
        query: Query::default(),
    }
}

pub fn valid_event() -> Event {
    Event {
        event: "$pageview".to_string(),
        uuid: Uuid::new_v4().to_string(),
        distinct_id: "user-42".to_string(),
        timestamp: "2026-03-19T14:29:58.123Z".to_string(),
        session_id: None,
        window_id: None,
        options: RawOptions::default(),
        properties: raw_obj("{}"),
    }
}

pub fn wrapped_event(event_name: &str, distinct_id: &str) -> WrappedEvent {
    let uuid = Uuid::new_v4();
    WrappedEvent {
        event: Event {
            event: event_name.to_string(),
            uuid: uuid.to_string(),
            distinct_id: distinct_id.to_string(),
            timestamp: "2026-03-19T14:29:58.123Z".to_string(),
            session_id: None,
            window_id: None,
            options: RawOptions::default(),
            properties: raw_obj("{}"),
        },
        uuid,
        options: Options::default(),
        adjusted_timestamp: Some(
            DateTime::parse_from_rfc3339("2026-03-19T14:29:58.123Z")
                .unwrap()
                .with_timezone(&Utc),
        ),
        result: EventResult::Ok,
        details: None,
        destination: Destination::default(),
        force_disable_person_processing: false,
        spread_partitions: false,
        is_gateway_verified: false,
    }
}

pub fn malformed_wrapped_event() -> WrappedEvent {
    let uuid = Uuid::new_v4();
    WrappedEvent {
        event: Event {
            event: String::new(),
            uuid: uuid.to_string(),
            distinct_id: "user-1".to_string(),
            timestamp: "bad".to_string(),
            session_id: None,
            window_id: None,
            options: RawOptions::default(),
            properties: raw_obj("{}"),
        },
        uuid,
        options: Options::default(),
        adjusted_timestamp: None,
        result: EventResult::Drop,
        details: Some("missing_event_name"),
        destination: Destination::default(),
        force_disable_person_processing: false,
        spread_partitions: false,
        is_gateway_verified: false,
    }
}

pub fn find_by_did<'a>(events: &'a [WrappedEvent], distinct_id: &str) -> &'a WrappedEvent {
    events
        .iter()
        .find(|e| e.event.distinct_id == distinct_id)
        .unwrap()
}

/// The outputs v1 test states publish to, one distinct topic per output.
pub fn test_outputs_config() -> crate::config::OutputsConfig {
    let env: HashMap<String, String> = [
        ("CAPTURE_OUTPUT_ANALYTICS_MAIN_TOPIC", "events_main"),
        ("CAPTURE_OUTPUT_ANALYTICS_HISTORICAL_TOPIC", "events_hist"),
        ("CAPTURE_OUTPUT_ANALYTICS_OVERFLOW_TOPIC", "events_overflow"),
        ("CAPTURE_OUTPUT_DLQ_TOPIC", "events_dlq"),
        (
            "CAPTURE_OUTPUT_ERROR_TRACKING_TOPIC",
            "error_tracking_events",
        ),
        ("CAPTURE_OUTPUT_HEATMAPS_TOPIC", "heatmaps_ingestion"),
        (
            "CAPTURE_OUTPUT_CLIENT_WARNINGS_TOPIC",
            "events_plugin_ingestion",
        ),
        ("CAPTURE_OUTPUT_AI_MAIN_TOPIC", "ai_events"),
        ("CAPTURE_OUTPUT_AI_OVERFLOW_TOPIC", "ai_events_overflow"),
    ]
    .into_iter()
    .map(|(k, v)| (k.to_string(), v.to_string()))
    .collect();
    envconfig::Envconfig::init_from_hashmap(&env).expect("test outputs config")
}

// ---------------------------------------------------------------------------
// Realistic fixture builders
// ---------------------------------------------------------------------------

/// A realistic $pageview event with typical posthog-js properties.
pub fn realistic_pageview(distinct_id: &str) -> WrappedEvent {
    let uuid = Uuid::new_v4();
    WrappedEvent {
        event: Event {
            event: "$pageview".to_string(),
            uuid: uuid.to_string(),
            distinct_id: distinct_id.to_string(),
            timestamp: "2026-03-19T14:29:58.123Z".to_string(),
            session_id: Some("01jq9abc-def0-1234-5678-9abcdef01234".to_string()),
            window_id: Some("01jq9xyz-0000-4321-8765-fedcba987654".to_string()),
            options: RawOptions(serde_json::json!({
                "cookieless_mode": false,
                "process_person_profile": true
            })),
            properties: raw_obj(
                r#"{"$current_url":"https://app.example.com/dashboard","$referrer":"https://google.com","$browser":"Chrome","$browser_version":"120.0","$os":"Mac OS X","$lib":"posthog-js","$lib_version":"1.150.0","custom_prop":42}"#,
            ),
        },
        uuid,
        options: Options {
            cookieless_mode: Some(false),
            disable_skew_correction: None,
            product_tour_id: None,
            process_person_profile: Some(true),
        },
        adjusted_timestamp: Some(
            DateTime::parse_from_rfc3339("2026-03-19T14:29:53.123Z")
                .unwrap()
                .with_timezone(&Utc),
        ),
        result: EventResult::Ok,
        details: None,
        destination: Destination::AnalyticsMain,
        force_disable_person_processing: false,
        spread_partitions: false,
        is_gateway_verified: false,
    }
}

/// A realistic $identify event.
pub fn realistic_identify(distinct_id: &str) -> WrappedEvent {
    let uuid = Uuid::new_v4();
    WrappedEvent {
        event: Event {
            event: "$identify".to_string(),
            uuid: uuid.to_string(),
            distinct_id: distinct_id.to_string(),
            timestamp: "2026-03-19T14:30:01.000Z".to_string(),
            session_id: Some("01jq9abc-def0-1234-5678-9abcdef01234".to_string()),
            window_id: None,
            options: RawOptions(serde_json::json!({
                "process_person_profile": true
            })),
            properties: raw_obj(
                r#"{"$set":{"email":"[email protected]","name":"Test User"},"$set_once":{"created_at":"2026-01-01"},"$browser":"Safari","$os":"iOS"}"#,
            ),
        },
        uuid,
        options: Options {
            cookieless_mode: None,
            disable_skew_correction: None,
            product_tour_id: None,
            process_person_profile: Some(true),
        },
        adjusted_timestamp: Some(
            DateTime::parse_from_rfc3339("2026-03-19T14:29:56.000Z")
                .unwrap()
                .with_timezone(&Utc),
        ),
        result: EventResult::Ok,
        details: None,
        destination: Destination::AnalyticsMain,
        force_disable_person_processing: false,
        spread_partitions: false,
        is_gateway_verified: false,
    }
}

/// A realistic custom event.
pub fn realistic_custom(distinct_id: &str, event_name: &str) -> WrappedEvent {
    let uuid = Uuid::new_v4();
    WrappedEvent {
        event: Event {
            event: event_name.to_string(),
            uuid: uuid.to_string(),
            distinct_id: distinct_id.to_string(),
            timestamp: "2026-03-19T14:30:05.500Z".to_string(),
            session_id: Some("01jq9abc-def0-1234-5678-9abcdef01234".to_string()),
            window_id: Some("01jq9xyz-0000-4321-8765-fedcba987654".to_string()),
            options: RawOptions(serde_json::json!({
                "process_person_profile": true
            })),
            properties: raw_obj(
                r#"{"button_id":"cta-signup","$current_url":"https://app.example.com/pricing"}"#,
            ),
        },
        uuid,
        options: Options {
            cookieless_mode: None,
            disable_skew_correction: None,
            product_tour_id: None,
            process_person_profile: Some(true),
        },
        adjusted_timestamp: Some(
            DateTime::parse_from_rfc3339("2026-03-19T14:30:00.500Z")
                .unwrap()
                .with_timezone(&Utc),
        ),
        result: EventResult::Ok,
        details: None,
        destination: Destination::AnalyticsMain,
        force_disable_person_processing: false,
        spread_partitions: false,
        is_gateway_verified: false,
    }
}

/// A realistic 3-event batch for round-trip tests.
pub fn realistic_batch() -> Vec<WrappedEvent> {
    vec![
        realistic_pageview("user-42"),
        realistic_identify("user-42"),
        realistic_custom("user-42", "button_clicked"),
    ]
}

/// 6-event batch with `user-pos-{0..5}` distinct_ids and per-slot state:
/// 0=Ok/Main, 1=Drop, 2=Ok/Main, 3=Warning, 4=Ok/Overflow, 5=Ok/Historical.
pub fn realistic_ordered_mixed_batch() -> Vec<WrappedEvent> {
    let pageview_ok = realistic_pageview("user-pos-0");

    let mut malformed = realistic_pageview("user-pos-1");
    malformed.event.event = String::new();
    malformed.event.timestamp = "bad".to_string();
    malformed.adjusted_timestamp = None;
    malformed.result = EventResult::Drop;
    malformed.details = Some("missing_event_name");

    let identify_ok = realistic_identify("user-pos-2");

    let mut exception_warning = realistic_custom("user-pos-3", "$exception");
    exception_warning.result = EventResult::Warning;
    exception_warning.details = Some("exceptions_over_quota");

    let click_overflow = realistic_custom("user-pos-4", "button_clicked")
        .with_destination(Destination::AnalyticsOverflow);

    let pageview_historical =
        realistic_pageview("user-pos-5").with_destination(Destination::AnalyticsHistorical);

    vec![
        pageview_ok,
        malformed,
        identify_ok,
        exception_warning,
        click_overflow,
        pageview_historical,
    ]
}

/// Two distinct `Event`s sharing one UUID — for the dup-uuid bail.
pub fn realistic_dup_uuid_pair() -> (Event, Event) {
    let shared_uuid = Uuid::new_v4().to_string();
    let first = Event {
        event: "$pageview".to_string(),
        uuid: shared_uuid.clone(),
        distinct_id: "user-dup-A".to_string(),
        timestamp: "2026-03-19T14:29:58.123Z".to_string(),
        session_id: Some("01jq9abc-def0-1234-5678-9abcdef01234".to_string()),
        window_id: Some("01jq9xyz-0000-4321-8765-fedcba987654".to_string()),
        options: RawOptions(serde_json::json!({
            "cookieless_mode": false,
            "process_person_profile": true
        })),
        properties: raw_obj(r#"{"$current_url":"https://app.example.com/dashboard"}"#),
    };
    let second = Event {
        event: "$identify".to_string(),
        uuid: shared_uuid,
        distinct_id: "user-dup-B".to_string(),
        timestamp: "2026-03-19T14:30:01.000Z".to_string(),
        session_id: Some("01jq9abc-def0-1234-5678-9abcdef01234".to_string()),
        window_id: None,
        options: RawOptions::default(),
        properties: raw_obj(r#"{"$set":{"email":"[email protected]"}}"#),
    };
    (first, second)
}

/// One Ok event per analytics destination plus Dlq and Custom, and one
/// pre-marked Drop.
pub fn realistic_spread_destinations() -> Vec<WrappedEvent> {
    let main = realistic_pageview("user-dest-0").with_destination(Destination::AnalyticsMain);
    let historical =
        realistic_pageview("user-dest-1").with_destination(Destination::AnalyticsHistorical);
    let overflow =
        realistic_pageview("user-dest-2").with_destination(Destination::AnalyticsOverflow);
    let dlq = realistic_pageview("user-dest-3").with_destination(Destination::Dlq);
    let custom = realistic_pageview("user-dest-4")
        .with_destination(Destination::Custom("custom_topic".to_string()));
    let dropped = realistic_pageview("user-dest-5")
        .with_result(EventResult::Drop, Some("missing_event_name"));
    vec![main, historical, overflow, dlq, custom, dropped]
}

/// Builder for mutating a WrappedEvent after creation.
pub trait WrappedEventMut {
    fn with_destination(self, d: Destination) -> Self;
    fn with_force_disable_person_processing(self, v: bool) -> Self;
    fn with_result(self, r: EventResult, details: Option<&'static str>) -> Self;
    fn with_properties(self, raw: &str) -> Self;
}

impl WrappedEventMut for WrappedEvent {
    fn with_destination(mut self, d: Destination) -> Self {
        self.destination = d;
        self
    }

    fn with_force_disable_person_processing(mut self, v: bool) -> Self {
        self.force_disable_person_processing = v;
        self
    }

    fn with_result(mut self, r: EventResult, details: Option<&'static str>) -> Self {
        self.result = r;
        self.details = details;
        self
    }

    fn with_properties(mut self, raw: &str) -> Self {
        self.event.properties = raw_obj(raw);
        self
    }
}

/// Assert that a serialized WrappedEvent round-trips through CapturedEvent
/// and its inner data field round-trips through RawEvent.
pub fn assert_round_trip(
    wrapped: &WrappedEvent,
    ctx: &RequestContext,
) -> (common_types::CapturedEvent, common_types::RawEvent) {
    use crate::v1::types::Publishable;

    let buf = wrapped.serialize(ctx).expect("serialize failed");
    let captured: common_types::CapturedEvent =
        serde_json::from_slice(&buf).expect("v1 output must deserialize as CapturedEvent");
    let data: common_types::RawEvent =
        serde_json::from_str(&captured.data).expect("data field must deserialize as RawEvent");

    assert_eq!(captured.uuid, wrapped.uuid);
    assert_eq!(captured.distinct_id, wrapped.event.distinct_id);
    assert_eq!(captured.event, wrapped.event.event);

    (captured, data)
}

// ---------------------------------------------------------------------------
// Payload generators for batch-level tests
// ---------------------------------------------------------------------------

/// A non-historical batch wrapping `events`, the shape `process_batch` takes.
pub fn valid_batch(events: Vec<Event>) -> crate::v1::analytics::types::Batch {
    crate::v1::analytics::types::Batch {
        created_at: "2026-03-19T14:30:00.000Z".to_string(),
        historical_migration: false,
        capture_internal: None,
        batch: events,
    }
}

/// Serialize a list of Events into a valid V1 batch JSON payload.
pub fn batch_payload(events: &[Event]) -> Vec<u8> {
    let batch_json = serde_json::json!({
        "created_at": "2026-03-19T14:30:00.000Z",
        "batch": events.iter().map(|e| {
            let mut obj = serde_json::json!({
                "event": e.event,
                "uuid": e.uuid,
                "distinct_id": e.distinct_id,
                "timestamp": e.timestamp,
                "options": e.options,
            });
            obj.as_object_mut().unwrap().insert(
                "properties".to_string(),
                serde_json::from_str(e.properties.get()).unwrap(),
            );
            if let Some(ref sid) = e.session_id {
                obj.as_object_mut().unwrap().insert(
                    "session_id".to_string(),
                    serde_json::Value::String(sid.clone()),
                );
            }
            if let Some(ref wid) = e.window_id {
                obj.as_object_mut().unwrap().insert(
                    "window_id".to_string(),
                    serde_json::Value::String(wid.clone()),
                );
            }
            obj
        }).collect::<Vec<_>>(),
    });
    serde_json::to_vec(&batch_json).unwrap()
}

/// Compress raw bytes using the given encoding.
/// Supported: "gzip", "deflate", "br", "zstd"
#[cfg(test)]
pub fn compressed_payload(data: &[u8], encoding: &str) -> Vec<u8> {
    match encoding {
        "gzip" => {
            use flate2::write::GzEncoder;
            use flate2::Compression;
            use std::io::Write;
            let mut encoder = GzEncoder::new(Vec::new(), Compression::fast());
            encoder.write_all(data).unwrap();
            encoder.finish().unwrap()
        }
        "deflate" => {
            use flate2::write::DeflateEncoder;
            use flate2::Compression;
            use std::io::Write;
            let mut encoder = DeflateEncoder::new(Vec::new(), Compression::fast());
            encoder.write_all(data).unwrap();
            encoder.finish().unwrap()
        }
        "br" => {
            let mut output = Vec::new();
            let params = brotli::enc::BrotliEncoderParams::default();
            brotli::BrotliCompress(&mut std::io::Cursor::new(data), &mut output, &params).unwrap();
            output
        }
        "zstd" => zstd::encode_all(std::io::Cursor::new(data), 1).unwrap(),
        other => panic!("unsupported encoding for test: {other}"),
    }
}

/// Event with all options populated.
pub fn event_with_all_options() -> Event {
    Event {
        event: "$pageview".to_string(),
        uuid: Uuid::new_v4().to_string(),
        distinct_id: "user-all-opts".to_string(),
        timestamp: "2026-03-19T14:29:58.123Z".to_string(),
        session_id: Some("sess-all".to_string()),
        window_id: Some("win-all".to_string()),
        options: RawOptions(serde_json::json!({
            "cookieless_mode": true,
            "disable_skew_correction": true,
            "product_tour_id": "tour-v2",
            "process_person_profile": false
        })),
        properties: raw_obj(r#"{"existing":"prop"}"#),
    }
}

/// Event with empty `options: {}`.
pub fn event_with_empty_options() -> Event {
    Event {
        event: "$pageview".to_string(),
        uuid: Uuid::new_v4().to_string(),
        distinct_id: "user-empty-opts".to_string(),
        timestamp: "2026-03-19T14:29:58.123Z".to_string(),
        session_id: None,
        window_id: None,
        options: RawOptions::default(),
        properties: raw_obj("{}"),
    }
}

// ---------------------------------------------------------------------------
// TestStateBuilder — builds a router::State for V1 pipeline integration tests
// ---------------------------------------------------------------------------

use std::collections::HashMap;
use std::num::NonZeroU32;
use std::sync::Arc;
use std::time::Duration;

use common_redis::MockRedisClient;
use limiters::overflow::OverflowLimiter;
use limiters::redis::{QuotaResource, QUOTA_LIMITER_CACHE_KEY};
use limiters::token_dropper::TokenDropper;

use crate::config::CaptureMode;
use crate::event_restrictions::EventRestrictionService;
use crate::global_rate_limiter::GlobalRateLimiter;
use crate::outputs::OutputRegistry;
use crate::quota_limiters::CaptureQuotaLimiter;
use crate::router::{self, HistoricalConfig};
use crate::sinks::kafka::KafkaSinkBase;
use crate::sinks::producer::MockKafkaProducer;
use crate::sinks::registry::OutputTable;
use crate::time::TimeSource;

/// Result of building a test state — gives access to both the `router::State`
/// and the `MockKafkaProducer` behind its outputs, so tests can inspect sent
/// records.
pub struct TestState {
    pub state: router::State,
    pub mock_producer: MockKafkaProducer,
}

/// Builder for `router::State` with configurable mock services.
pub struct TestStateBuilder {
    quota_limited: bool,
    overflow_limiter: Option<(NonZeroU32, NonZeroU32)>,
    overflow_preserve_locality: bool,
    overflow_forced_key: Option<String>,
    ai_events_overflow_limiter: Option<(NonZeroU32, NonZeroU32)>,
    historical_threshold_days: Option<i64>,
    restriction_service: Option<EventRestrictionService>,
    global_rate_limiter: Option<Arc<GlobalRateLimiter>>,
    ai_byte_rate_limiter: Option<Arc<GlobalRateLimiter>>,
    mock_producer: Option<MockKafkaProducer>,
    ai_gateway_signing_secret: Option<String>,
    ingestion_warning_emitter: Option<Arc<dyn common_ingestion_warnings::WarningEmitter>>,
    capture_mode: CaptureMode,
    ai_max_event_bytes: u64,
}

impl Default for TestStateBuilder {
    fn default() -> Self {
        Self::new()
    }
}

impl TestStateBuilder {
    pub fn new() -> Self {
        Self {
            quota_limited: false,
            overflow_limiter: None,
            overflow_preserve_locality: false,
            overflow_forced_key: None,
            ai_events_overflow_limiter: None,
            historical_threshold_days: None,
            restriction_service: None,
            global_rate_limiter: None,
            ai_byte_rate_limiter: None,
            mock_producer: None,
            ai_gateway_signing_secret: None,
            ingestion_warning_emitter: None,
            capture_mode: CaptureMode::Events,
            ai_max_event_bytes: 0,
        }
    }

    /// Configure quota limiter to reject all events for any token.
    pub fn with_quota_limited(mut self) -> Self {
        self.quota_limited = true;
        self
    }

    /// Set the AI-gateway HMAC signing secret used by provenance verification.
    pub fn with_ai_gateway_signing_secret(mut self, secret: impl Into<String>) -> Self {
        self.ai_gateway_signing_secret = Some(secret.into());
        self
    }

    /// Add an in-process overflow limiter with the given rate and burst.
    pub fn with_overflow_limiter(mut self, per_second: u32, burst: u32) -> Self {
        self.overflow_limiter = Some((
            NonZeroU32::new(per_second).expect("per_second must be > 0"),
            NonZeroU32::new(burst).expect("burst must be > 0"),
        ));
        self
    }

    /// Keep partition keys when rerouting to overflow, as prod-US does via
    /// `OVERFLOW_PRESERVE_PARTITION_LOCALITY`. Applies to both lanes' limiters
    /// because production derives both from that one setting.
    pub fn with_overflow_preserve_locality(mut self) -> Self {
        self.overflow_preserve_locality = true;
        self
    }

    /// Force-route this key outright, as an ops-configured hot key does.
    pub fn with_overflow_forced_key(mut self, key: impl Into<String>) -> Self {
        self.overflow_forced_key = Some(key.into());
        self
    }

    pub fn with_ai_events_overflow_limiter(mut self, per_second: u32, burst: u32) -> Self {
        self.ai_events_overflow_limiter = Some((
            NonZeroU32::new(per_second).expect("per_second must be > 0"),
            NonZeroU32::new(burst).expect("burst must be > 0"),
        ));
        self
    }

    /// Enable historical rerouting with the given threshold in days.
    pub fn with_historical_rerouting(mut self, threshold_days: i64) -> Self {
        self.historical_threshold_days = Some(threshold_days);
        self
    }

    /// Add a restriction service.
    pub fn with_restriction_service(mut self, service: EventRestrictionService) -> Self {
        self.restriction_service = Some(service);
        self
    }

    /// Add a global rate limiter.
    pub fn with_global_rate_limiter(mut self, limiter: Arc<GlobalRateLimiter>) -> Self {
        self.global_rate_limiter = Some(limiter);
        self
    }

    /// Add the AI lane's byte-budget limiter.
    pub fn with_ai_byte_rate_limiter(mut self, limiter: Arc<GlobalRateLimiter>) -> Self {
        self.ai_byte_rate_limiter = Some(limiter);
        self
    }

    /// Supply a pre-configured producer (e.g. for error injection).
    pub fn with_mock_producer(mut self, producer: MockKafkaProducer) -> Self {
        self.mock_producer = Some(producer);
        self
    }

    /// Supply an ingestion warnings emitter (e.g. a `CollectingEmitter`).
    pub fn with_ingestion_warning_emitter(
        mut self,
        emitter: Arc<dyn common_ingestion_warnings::WarningEmitter>,
    ) -> Self {
        self.ingestion_warning_emitter = Some(emitter);
        self
    }

    /// Set the deployment capture mode (defaults to `Events`).
    pub fn with_capture_mode(mut self, mode: CaptureMode) -> Self {
        self.capture_mode = mode;
        self
    }

    /// Set the per-event AI ceiling (defaults to `0`, which disables it).
    pub fn with_ai_max_event_bytes(mut self, bytes: u64) -> Self {
        self.ai_max_event_bytes = bytes;
        self
    }

    pub fn build(self) -> TestState {
        let redis: Arc<dyn common_redis::Client + Send + Sync> = if self.quota_limited {
            let mut mock = MockRedisClient::new();
            for resource in &[
                QuotaResource::Events,
                QuotaResource::Recordings,
                QuotaResource::Exceptions,
                QuotaResource::Surveys,
                QuotaResource::LLMEvents,
            ] {
                let key = format!("{}{}", QUOTA_LIMITER_CACHE_KEY, resource.as_str());
                // Return a wildcard token so every token is limited
                mock = mock.zrangebyscore_ret(&key, vec!["*".to_string()]);
            }
            Arc::new(mock)
        } else {
            Arc::new(MockRedisClient::new())
        };

        // CaptureQuotaLimiter needs a Config — build a minimal one via envconfig
        let cfg_env: HashMap<String, String> = [
            ("REDIS_URL", "redis://localhost:6379/"),
            ("CAPTURE_MODE", "events"),
            (
                "CAPTURE_OUTPUT_ANALYTICS_MAIN_TOPIC",
                "events_plugin_ingestion",
            ),
        ]
        .into_iter()
        .map(|(k, v)| (k.to_string(), v.to_string()))
        .collect();
        let cfg: crate::config::Config =
            envconfig::Envconfig::init_from_hashmap(&cfg_env).expect("failed to build test Config");

        let quota_limiter = CaptureQuotaLimiter::new(&cfg, redis.clone(), Duration::from_secs(60));

        let historical_cfg = match self.historical_threshold_days {
            Some(days) => HistoricalConfig::new(true, days),
            None => HistoricalConfig::new(false, 1),
        };

        let overflow_limiter = self.overflow_limiter.map(|(per_sec, burst)| {
            Arc::new(OverflowLimiter::new(
                per_sec,
                burst,
                self.overflow_forced_key.clone(),
                self.overflow_preserve_locality,
            ))
        });

        let ai_events_overflow_limiter = self.ai_events_overflow_limiter.map(|(per_sec, burst)| {
            Arc::new(OverflowLimiter::new(
                per_sec,
                burst,
                self.overflow_forced_key.clone(),
                self.overflow_preserve_locality,
            ))
        });

        let mock_producer = self.mock_producer.unwrap_or_default();
        let outputs = Arc::new(OutputRegistry::single(KafkaSinkBase::with_producer(
            mock_producer.clone(),
            OutputTable::new(
                &test_outputs_config(),
                self.capture_mode.has_ai_overflow_lane(),
            ),
        )));

        let timesource: Arc<dyn TimeSource + Send + Sync> = Arc::new(crate::time::SystemTime {});

        let state = router::State {
            outputs,
            timesource,
            redis,
            global_rate_limiter_token_distinctid: self.global_rate_limiter,
            quota_limiter: Arc::new(quota_limiter),
            token_dropper: Arc::new(TokenDropper::default()),
            event_restriction_service: self.restriction_service,
            event_payload_size_limit: 20 * 1024 * 1024,
            historical_cfg,
            is_mirror_deploy: false,
            verbose_sample_percent: 0.0,
            ai_max_sum_of_parts_bytes: 100 * 1024 * 1024,
            ai_max_event_bytes: self.ai_max_event_bytes,
            body_chunk_read_timeout: None,
            body_read_chunk_size_kb: 64,
            capture_v1_max_compressed_body_bytes: 2 * 1024 * 1024,
            capture_v1_max_decompressed_body_bytes: 20 * 1024 * 1024,
            overflow_limiter,
            ai_events_overflow_limiter,
            ai_byte_rate_limiter: self.ai_byte_rate_limiter,
            replay_overflow_limiter: None,
            capture_v1_scatter_gather_min_batch: 8,
            ai_gateway_signing_secret: self.ai_gateway_signing_secret,
            ingestion_warning_emitter: self.ingestion_warning_emitter,
            capture_mode: self.capture_mode,
        };

        TestState {
            state,
            mock_producer,
        }
    }
}