: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
//! Typed rejection conditions for the AI events endpoint (`/i/v0/ai`).
//!
//! The handler used to return a bare
//! [`CaptureError::RequestParsingError`](crate::api::CaptureError) for ~25
//! unrelated conditions, all carrying a free-form message. That is fine for an
//! HTTP response but useless for deciding which ingestion warning a customer
//! should see: telling "sent a non-AI event name" apart from "sent an unknown
//! multipart field" would mean matching on message strings.
//!
//! So the rejection reasons are an enum. [`AiRejection::message`] reproduces the
//! exact wire message each condition produced before, and
//! [`From<AiRejection>`](CaptureError) picks the same `CaptureError` variant, so
//! status codes and bodies are unchanged. The warning mapping then matches
//! variants, which the compiler checks.
use std::fmt;
use crate::api::CaptureError;
use crate::v0_request::AI_LANE_NAME_PREFIX;
/// Which `CaptureError` a rejection becomes, and so which HTTP status the client
/// sees. Preserved per-condition from before the enum existed.
enum ErrorKind {
/// 400, transport-level: the request framing itself is wrong.
Decoding,
/// 400, content-level: the framing parsed but the contents are unusable.
Parsing,
/// 413.
TooBig,
}
/// A request the AI endpoint refused because of something the customer sent.
///
/// Server-side failures (Kafka, event serialization) are deliberately absent:
/// they stay `CaptureError`, since they are ours to fix and must never surface
/// as customer warnings.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AiRejection {
// Request framing
NotMultipart,
InvalidBoundary(String),
MultipartParseFailed(String),
FieldDataUnreadable(String),
MissingEventPart,
FirstPartNotEvent(String),
DuplicateEventPart,
UnknownField(String),
// Event part
EventPartNotUtf8,
EventPartNotJson,
EventNotObject,
// Properties
PropertiesPartNotUtf8,
PropertiesPartNotJson,
ConflictingProperties,
EventMissingProperties,
// Size limits
EventPartTooBig { size: usize, max: usize },
EventAndPropertiesTooBig { size: usize, max: usize },
// Event identity
EventMissingName,
EventNameRequired,
EventNameEmpty,
EventMissingDistinctId,
DistinctIdRequired,
DistinctIdEmpty,
EventUuidRequired,
EventUuidInvalid(String),
// AI-specific validation.
EventNameNotAiPrefixed(String),
AiModelMissing,
AiModelNotString,
AiModelEmpty,
}
impl AiRejection {
/// The message this condition puts on the wire. Unchanged from when each
/// site built its `CaptureError` inline, so clients see the same bodies.
pub fn message(&self) -> String {
match self {
Self::NotMultipart => "Content-Type must be multipart/form-data".to_string(),
Self::InvalidBoundary(e) => format!("Invalid boundary in Content-Type: {e}"),
Self::MultipartParseFailed(e) => format!("Multipart parsing failed: {e}"),
Self::FieldDataUnreadable(e) => format!("Failed to read field data: {e}"),
Self::MissingEventPart => {
"Missing required 'event' part in multipart data".to_string()
}
Self::FirstPartNotEvent(field_name) => {
format!("First part must be 'event', got '{field_name}'")
}
Self::DuplicateEventPart => "Duplicate 'event' part found".to_string(),
Self::UnknownField(field_name) => format!(
"Unknown multipart field: '{field_name}'. Expected 'event' or 'event.properties'"
),
Self::EventPartNotUtf8 => "Event part must be valid UTF-8".to_string(),
Self::EventPartNotJson => "Event part must be valid JSON".to_string(),
Self::EventNotObject => "Event must be a JSON object".to_string(),
Self::PropertiesPartNotUtf8 => "Properties part must be valid UTF-8".to_string(),
Self::PropertiesPartNotJson => "Properties part must be valid JSON".to_string(),
Self::ConflictingProperties => {
"Event cannot have both embedded properties and a separate 'event.properties' part"
.to_string()
}
Self::EventMissingProperties => "Event missing 'properties' field".to_string(),
Self::EventPartTooBig { size, max } => format!(
"Event part size ({size} bytes) exceeds maximum allowed size ({max} bytes)"
),
Self::EventAndPropertiesTooBig { size, max } => format!(
"Combined event and properties size ({size} bytes) exceeds maximum allowed size ({max} bytes)"
),
Self::EventMissingName => "Event missing 'event' field".to_string(),
Self::EventNameRequired => "Event name is required".to_string(),
Self::EventNameEmpty => "Event name cannot be empty".to_string(),
Self::EventMissingDistinctId => "Event missing 'distinct_id' field".to_string(),
Self::DistinctIdRequired => "distinct_id is required".to_string(),
Self::DistinctIdEmpty => "distinct_id cannot be empty".to_string(),
Self::EventUuidRequired => "Event UUID is required".to_string(),
Self::EventUuidInvalid(e) => format!("Invalid UUID format: {e}"),
Self::EventNameNotAiPrefixed(event_name) => format!(
"Event name must start with '{AI_LANE_NAME_PREFIX}', got '{event_name}'"
),
Self::AiModelMissing => "Event properties must contain '$ai_model'".to_string(),
Self::AiModelNotString => "$ai_model must be a string".to_string(),
Self::AiModelEmpty => "$ai_model cannot be empty".to_string(),
}
}
fn kind(&self) -> ErrorKind {
match self {
// Framing problems the multipart layer itself reports.
Self::NotMultipart
| Self::InvalidBoundary(_)
| Self::MultipartParseFailed(_)
| Self::FieldDataUnreadable(_) => ErrorKind::Decoding,
Self::EventPartTooBig { .. } | Self::EventAndPropertiesTooBig { .. } => {
ErrorKind::TooBig
}
Self::MissingEventPart
| Self::FirstPartNotEvent(_)
| Self::DuplicateEventPart
| Self::UnknownField(_)
| Self::EventPartNotUtf8
| Self::EventPartNotJson
| Self::EventNotObject
| Self::PropertiesPartNotUtf8
| Self::PropertiesPartNotJson
| Self::ConflictingProperties
| Self::EventMissingProperties
| Self::EventMissingName
| Self::EventNameRequired
| Self::EventNameEmpty
| Self::EventMissingDistinctId
| Self::DistinctIdRequired
| Self::DistinctIdEmpty
| Self::EventUuidRequired
| Self::EventUuidInvalid(_)
| Self::EventNameNotAiPrefixed(_)
| Self::AiModelMissing
| Self::AiModelNotString
| Self::AiModelEmpty => ErrorKind::Parsing,
}
}
}
impl fmt::Display for AiRejection {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.message())
}
}
/// Every variant with the exact message it puts on the wire.
///
/// The single list of all variants in the crate. Variants carry `String`s so it
/// can't be a const like `WarningType::ALL`, and it lives here rather than in a
/// test module because two of them need it: the parity check below and the
/// warning mapping in `ingestion_warnings::ai`. Two hand-maintained copies would
/// drift, leaving a new variant silently untested by both.
#[cfg(test)]
pub(crate) fn all_variants_with_messages() -> Vec<(AiRejection, &'static str)> {
vec![
(
AiRejection::NotMultipart,
"Content-Type must be multipart/form-data",
),
(
AiRejection::InvalidBoundary("bad".to_string()),
"Invalid boundary in Content-Type: bad",
),
(
AiRejection::MultipartParseFailed("boom".to_string()),
"Multipart parsing failed: boom",
),
(
AiRejection::FieldDataUnreadable("io".to_string()),
"Failed to read field data: io",
),
(
AiRejection::MissingEventPart,
"Missing required 'event' part in multipart data",
),
(
AiRejection::FirstPartNotEvent("blob".to_string()),
"First part must be 'event', got 'blob'",
),
(
AiRejection::DuplicateEventPart,
"Duplicate 'event' part found",
),
(
AiRejection::UnknownField("nope".to_string()),
"Unknown multipart field: 'nope'. Expected 'event' or 'event.properties'",
),
(
AiRejection::EventPartNotUtf8,
"Event part must be valid UTF-8",
),
(
AiRejection::EventPartNotJson,
"Event part must be valid JSON",
),
(AiRejection::EventNotObject, "Event must be a JSON object"),
(
AiRejection::PropertiesPartNotUtf8,
"Properties part must be valid UTF-8",
),
(
AiRejection::PropertiesPartNotJson,
"Properties part must be valid JSON",
),
(
AiRejection::ConflictingProperties,
"Event cannot have both embedded properties and a separate 'event.properties' part",
),
(
AiRejection::EventMissingProperties,
"Event missing 'properties' field",
),
(
AiRejection::EventPartTooBig {
size: 40_000,
max: 32_768,
},
"Event part size (40000 bytes) exceeds maximum allowed size (32768 bytes)",
),
(
AiRejection::EventAndPropertiesTooBig {
size: 1_000_000,
max: 983_040,
},
"Combined event and properties size (1000000 bytes) exceeds maximum allowed size (983040 bytes)",
),
(
AiRejection::EventMissingName,
"Event missing 'event' field",
),
(AiRejection::EventNameRequired, "Event name is required"),
(AiRejection::EventNameEmpty, "Event name cannot be empty"),
(
AiRejection::EventMissingDistinctId,
"Event missing 'distinct_id' field",
),
(AiRejection::DistinctIdRequired, "distinct_id is required"),
(AiRejection::DistinctIdEmpty, "distinct_id cannot be empty"),
(AiRejection::EventUuidRequired, "Event UUID is required"),
(
AiRejection::EventUuidInvalid("invalid length".to_string()),
"Invalid UUID format: invalid length",
),
(
AiRejection::EventNameNotAiPrefixed("$pageview".to_string()),
"Event name must start with '$ai_', got '$pageview'",
),
(
AiRejection::AiModelMissing,
"Event properties must contain '$ai_model'",
),
(AiRejection::AiModelNotString, "$ai_model must be a string"),
(AiRejection::AiModelEmpty, "$ai_model cannot be empty"),
]
}
/// [`all_variants_with_messages`] without the messages, for callers that only
/// need to walk every variant.
#[cfg(test)]
pub(crate) fn all_variants() -> Vec<AiRejection> {
all_variants_with_messages()
.into_iter()
.map(|(rejection, _)| rejection)
.collect()
}
impl From<AiRejection> for CaptureError {
fn from(rejection: AiRejection) -> Self {
let message = rejection.message();
match rejection.kind() {
ErrorKind::Decoding => CaptureError::RequestDecodingError(message),
ErrorKind::Parsing => CaptureError::RequestParsingError(message),
ErrorKind::TooBig => CaptureError::EventTooBig(message),
}
}
}
/// Why an AI request failed: something the customer sent, or something on our
/// side.
///
/// Splitting these is what lets the handler emit a warning for the first kind
/// and stay silent for the second, while both still become a `CaptureError` for
/// the response. `From` impls in both directions keep `?` working unchanged at
/// every existing call site.
#[derive(Debug)]
pub enum AiFailure {
Rejected(AiRejection),
Other(CaptureError),
}
impl From<AiRejection> for AiFailure {
fn from(rejection: AiRejection) -> Self {
Self::Rejected(rejection)
}
}
impl From<CaptureError> for AiFailure {
fn from(err: CaptureError) -> Self {
Self::Other(err)
}
}
impl From<AiFailure> for CaptureError {
fn from(failure: AiFailure) -> Self {
match failure {
AiFailure::Rejected(rejection) => rejection.into(),
AiFailure::Other(err) => err,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use axum::response::IntoResponse;
use rstest::rstest;
/// The regression guard for the refactor that introduced this enum: the ~30
/// conditions it replaced each has to keep putting the same thing on the
/// wire, and a reviewer can't verify that many inline `format!`s by eye.
///
/// The pre-existing tests in `tests/integration_ai_endpoint.rs` are the
/// end-to-end half of the same proof; they pass unmodified.
#[test]
fn every_rejection_keeps_its_original_wire_message() {
for (rejection, expected) in all_variants_with_messages() {
assert_eq!(rejection.message(), expected, "message for {rejection:?}");
// Display and message must not drift apart; callers use both.
assert_eq!(rejection.to_string(), expected);
}
}
// `all_variants_with_messages` is hand-written, so it can fall behind the
// enum. Counting arms in the exhaustive `message` match is the cheapest way
// to notice: a new variant compiles there but is missing here.
#[test]
fn the_variant_list_covers_every_variant() {
let listed = all_variants();
let unique: std::collections::HashSet<_> =
listed.iter().map(std::mem::discriminant).collect();
assert_eq!(
unique.len(),
listed.len(),
"all_variants lists the same variant twice"
);
assert_eq!(
listed.len(),
29,
"variant count changed — add the new variant to all_variants_with_messages \
and update this expected count"
);
}
// The response body is the message, so a CaptureError variant swap would
// silently change a 400 into a 413 or vice versa.
#[rstest]
#[case::not_multipart(AiRejection::NotMultipart, 400)]
#[case::boundary(AiRejection::InvalidBoundary("x".to_string()), 400)]
#[case::multipart_parse(AiRejection::MultipartParseFailed("x".to_string()), 400)]
#[case::field_read(AiRejection::FieldDataUnreadable("x".to_string()), 400)]
#[case::missing_event_part(AiRejection::MissingEventPart, 400)]
#[case::unknown_field(AiRejection::UnknownField("x".to_string()), 400)]
#[case::event_not_json(AiRejection::EventPartNotJson, 400)]
#[case::event_name_not_ai_prefixed(AiRejection::EventNameNotAiPrefixed("$pageview".to_string()), 400)]
#[case::ai_model_missing(AiRejection::AiModelMissing, 400)]
#[case::event_part_too_big(AiRejection::EventPartTooBig { size: 1, max: 0 }, 413)]
#[case::combined_too_big(AiRejection::EventAndPropertiesTooBig { size: 1, max: 0 }, 413)]
fn rejections_keep_their_status_code(#[case] rejection: AiRejection, #[case] expected: u16) {
let err: CaptureError = rejection.into();
let status = err.into_response().status().as_u16();
assert_eq!(status, expected);
}
#[test]
fn message_survives_the_round_trip_through_ai_failure() {
let rejection = AiRejection::EventNameNotAiPrefixed("$pageview".to_string());
let expected = rejection.message();
let failure: AiFailure = rejection.into();
let err: CaptureError = failure.into();
assert!(matches!(err, CaptureError::RequestParsingError(ref m) if *m == expected));
}
#[test]
fn server_side_errors_pass_through_unchanged() {
let failure: AiFailure = CaptureError::NonRetryableSinkError.into();
assert!(matches!(failure, AiFailure::Other(_)));
let err: CaptureError = failure.into();
assert!(matches!(err, CaptureError::NonRetryableSinkError));
}
}