: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::collections::HashMap;
use axum::http::{header, HeaderValue, StatusCode};
use axum::response::IntoResponse;
use serde::ser::{SerializeMap, SerializeStruct};
use serde::Serialize;
use uuid::Uuid;
use super::constants::{CAPTURE_V1_BATCH_OUTCOMES, DEFAULT_RETRY_AFTER_SECS};
use super::types::{EventResult, WrappedEvent};
use crate::v1::context::RequestContext;
// ---------------------------------------------------------------------------
// BatchEntryStatus
// ---------------------------------------------------------------------------
/// Per-event outcome communicated to the SDK in the 200 response body.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BatchEntryStatus {
pub result: EventResult,
pub details: Option<&'static str>,
/// Later events in the request with this uuid; capture dropped them and kept this one.
pub duplicates_dropped: u32,
}
impl Serialize for BatchEntryStatus {
fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
let field_count =
1 + usize::from(self.details.is_some()) + usize::from(self.duplicates_dropped > 0);
let mut state = serializer.serialize_struct("BatchEntryStatus", field_count)?;
state.serialize_field("result", &self.result)?;
if let Some(detail) = self.details {
state.serialize_field("details", detail)?;
}
if self.duplicates_dropped > 0 {
state.serialize_field("duplicates_dropped", &self.duplicates_dropped)?;
}
state.end()
}
}
// ---------------------------------------------------------------------------
// BatchResponse
// ---------------------------------------------------------------------------
/// 200 OK response for the V1 analytics batch endpoint.
///
/// Preserves event insertion order via a Vec (events arrive in batch-index
/// order and are never reordered during processing).
#[derive(Debug)]
pub struct BatchResponse {
pub has_retry: bool,
entries: Vec<(Uuid, BatchEntryStatus)>,
}
impl BatchResponse {
/// Build the response from a processed batch of WrappedEvents.
/// Call this after publishing and result merging are complete.
pub fn build(ctx: &RequestContext, events: &[WrappedEvent]) -> Self {
let mut has_retry = false;
let entries: Vec<(Uuid, BatchEntryStatus)> = events
.iter()
.map(|ev| {
if ev.result == EventResult::Retry {
has_retry = true;
}
(
ev.uuid,
BatchEntryStatus {
result: ev.result,
details: ev.details,
duplicates_dropped: 0,
},
)
})
.collect();
if let Some(outcome) = classify_batch(events) {
metrics::counter!(CAPTURE_V1_BATCH_OUTCOMES, "outcome" => outcome, "path" => ctx.path)
.increment(1);
}
Self { has_retry, entries }
}
pub fn with_duplicates_dropped(mut self, dropped: &HashMap<Uuid, u32>) -> Self {
for (uuid, status) in self.entries.iter_mut() {
if let Some(count) = dropped.get(uuid) {
status.duplicates_dropped = *count;
}
}
self
}
pub fn entries(&self) -> &[(Uuid, BatchEntryStatus)] {
&self.entries
}
}
/// Classify the outcome mix of a processed batch for the
/// `capture_v1_batch_outcomes` counter. `Warning` counts toward "all_ok"
/// (the event was still accepted). Returns `None` for an empty batch.
fn classify_batch(events: &[WrappedEvent]) -> Option<&'static str> {
if events.is_empty() {
return None;
}
let all_ok_or_warn = events
.iter()
.all(|e| matches!(e.result, EventResult::Ok | EventResult::Warning));
let all_drop = events.iter().all(|e| e.result == EventResult::Drop);
let all_retry = events.iter().all(|e| e.result == EventResult::Retry);
Some(if all_ok_or_warn {
"all_ok"
} else if all_drop {
"all_drop"
} else if all_retry {
"all_retry"
} else {
"partial_failure"
})
}
/// Wrapper for serializing the response body as `{"results": {uuid: status, ...}}`.
struct ResponseBody<'a>(&'a [(Uuid, BatchEntryStatus)]);
impl Serialize for ResponseBody<'_> {
fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
let mut outer = serializer.serialize_struct("ResponseBody", 1)?;
outer.serialize_field("results", &ResultsMap(self.0))?;
outer.end()
}
}
struct ResultsMap<'a>(&'a [(Uuid, BatchEntryStatus)]);
impl Serialize for ResultsMap<'_> {
fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
let mut map = serializer.serialize_map(Some(self.0.len()))?;
for (uuid, status) in self.0 {
map.serialize_entry(&uuid.to_string(), status)?;
}
map.end()
}
}
impl IntoResponse for BatchResponse {
fn into_response(self) -> axum::response::Response {
let body = serde_json::to_vec(&ResponseBody(&self.entries))
.expect("BatchResponse serialization cannot fail");
let mut response = (StatusCode::OK, body).into_response();
let headers = response.headers_mut();
headers.insert(
header::CONTENT_TYPE,
HeaderValue::from_static("application/json"),
);
if self.has_retry {
headers.insert(header::RETRY_AFTER, DEFAULT_RETRY_AFTER_SECS);
}
response
}
}
// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------
#[cfg(test)]
mod tests {
use axum::body::to_bytes;
use axum::response::IntoResponse;
use chrono::Utc;
use rstest::rstest;
use serde_json::Value;
use uuid::Uuid;
use super::*;
use crate::v1::analytics::types::{Event, EventResult, Options, RawOptions, WrappedEvent};
use crate::v1::test_utils;
use crate::v1::types::Destination;
fn make_wrapped(result: EventResult, details: Option<&'static str>) -> WrappedEvent {
let uuid = Uuid::new_v4();
WrappedEvent {
event: Event {
event: "$pageview".to_string(),
uuid: uuid.to_string(),
distinct_id: "user-1".to_string(),
timestamp: "2026-03-19T14:29:58.123Z".to_string(),
session_id: None,
window_id: None,
options: RawOptions::default(),
properties: serde_json::value::RawValue::from_string("{}".to_owned()).unwrap(),
},
uuid,
options: Options::default(),
adjusted_timestamp: Some(Utc::now()),
result,
details,
destination: Destination::AnalyticsMain,
force_disable_person_processing: false,
spread_partitions: false,
is_gateway_verified: false,
}
}
#[rstest]
#[case::ok(EventResult::Ok, None, 0, r#"{"result":"ok"}"#)]
#[case::retry_with_details(
EventResult::Retry,
Some("not_persisted"),
0,
r#"{"result":"retry","details":"not_persisted"}"#
)]
#[case::drop_with_details(
EventResult::Drop,
Some("billing_limit_exceeded"),
0,
r#"{"result":"drop","details":"billing_limit_exceeded"}"#
)]
#[case::warning_with_details(
EventResult::Warning,
Some("person_processing_disabled"),
0,
r#"{"result":"warning","details":"person_processing_disabled"}"#
)]
#[case::ok_with_duplicates(
EventResult::Ok,
None,
2,
r#"{"result":"ok","duplicates_dropped":2}"#
)]
#[case::drop_with_details_and_duplicates(
EventResult::Drop,
Some("invalid_options"),
1,
r#"{"result":"drop","details":"invalid_options","duplicates_dropped":1}"#
)]
fn batch_entry_status_serialize(
#[case] result: EventResult,
#[case] details: Option<&'static str>,
#[case] duplicates_dropped: u32,
#[case] expected: &str,
) {
let status = BatchEntryStatus {
result,
details,
duplicates_dropped,
};
assert_eq!(serde_json::to_string(&status).unwrap(), expected);
}
#[test]
fn classify_batch_all_ok() {
let events = vec![
make_wrapped(EventResult::Ok, None),
make_wrapped(EventResult::Ok, None),
];
assert_eq!(classify_batch(&events), Some("all_ok"));
}
#[test]
fn classify_batch_ok_and_warning_counts_as_all_ok() {
let events = vec![
make_wrapped(EventResult::Ok, None),
make_wrapped(EventResult::Warning, Some("person_processing_disabled")),
];
assert_eq!(classify_batch(&events), Some("all_ok"));
}
#[test]
fn classify_batch_all_drop() {
let events = vec![
make_wrapped(EventResult::Drop, Some("billing_limit_exceeded")),
make_wrapped(EventResult::Drop, Some("billing_limit_exceeded")),
];
assert_eq!(classify_batch(&events), Some("all_drop"));
}
#[test]
fn classify_batch_all_retry() {
let events = vec![
make_wrapped(EventResult::Retry, Some("not_persisted")),
make_wrapped(EventResult::Retry, Some("not_persisted")),
];
assert_eq!(classify_batch(&events), Some("all_retry"));
}
#[test]
fn classify_batch_ok_and_drop_is_partial_failure() {
let events = vec![
make_wrapped(EventResult::Ok, None),
make_wrapped(EventResult::Drop, Some("billing_limit_exceeded")),
];
assert_eq!(classify_batch(&events), Some("partial_failure"));
}
#[test]
fn classify_batch_drop_and_retry_is_partial_failure() {
let events = vec![
make_wrapped(EventResult::Drop, Some("billing_limit_exceeded")),
make_wrapped(EventResult::Retry, Some("not_persisted")),
];
assert_eq!(classify_batch(&events), Some("partial_failure"));
}
#[test]
fn classify_batch_empty_is_none() {
assert_eq!(classify_batch(&[]), None);
}
#[test]
fn batch_response_build_all_ok() {
let ctx = test_utils::test_context();
let events = vec![
make_wrapped(EventResult::Ok, None),
make_wrapped(EventResult::Ok, None),
];
let resp = BatchResponse::build(&ctx, &events);
assert!(!resp.has_retry);
assert_eq!(resp.entries().len(), 2);
for (uuid, status) in resp.entries() {
assert_eq!(status.result, EventResult::Ok);
assert!(status.details.is_none());
assert_ne!(*uuid, Uuid::nil());
}
}
#[test]
fn batch_response_build_mixed() {
let ctx = test_utils::test_context();
let events = vec![
make_wrapped(EventResult::Ok, None),
make_wrapped(EventResult::Drop, Some("billing_limit_exceeded")),
make_wrapped(EventResult::Warning, Some("person_processing_disabled")),
make_wrapped(EventResult::Retry, Some("not_persisted")),
];
let resp = BatchResponse::build(&ctx, &events);
assert!(resp.has_retry);
assert_eq!(resp.entries().len(), 4);
assert_eq!(resp.entries()[0].1.result, EventResult::Ok);
assert_eq!(resp.entries()[1].1.result, EventResult::Drop);
assert_eq!(resp.entries()[2].1.result, EventResult::Warning);
assert_eq!(resp.entries()[3].1.result, EventResult::Retry);
}
#[test]
fn batch_response_has_retry_false_when_no_retry() {
let ctx = test_utils::test_context();
let events = vec![
make_wrapped(EventResult::Ok, None),
make_wrapped(EventResult::Drop, Some("billing")),
make_wrapped(EventResult::Warning, Some("pp_disabled")),
];
let resp = BatchResponse::build(&ctx, &events);
assert!(!resp.has_retry);
}
#[test]
fn batch_response_preserves_insertion_order() {
let ctx = test_utils::test_context();
let events = vec![
make_wrapped(EventResult::Ok, None),
make_wrapped(EventResult::Retry, Some("not_persisted")),
make_wrapped(EventResult::Ok, None),
];
let uuids: Vec<Uuid> = events.iter().map(|e| e.uuid).collect();
let resp = BatchResponse::build(&ctx, &events);
let resp_uuids: Vec<Uuid> = resp.entries().iter().map(|(u, _)| *u).collect();
assert_eq!(resp_uuids, uuids);
}
#[tokio::test]
async fn into_response_status_200() {
let ctx = test_utils::test_context();
let events = vec![make_wrapped(EventResult::Ok, None)];
let resp = BatchResponse::build(&ctx, &events).into_response();
assert_eq!(resp.status(), StatusCode::OK);
}
#[tokio::test]
async fn into_response_content_type_json() {
let ctx = test_utils::test_context();
let events = vec![make_wrapped(EventResult::Ok, None)];
let resp = BatchResponse::build(&ctx, &events).into_response();
assert_eq!(
resp.headers().get(header::CONTENT_TYPE).unwrap(),
"application/json"
);
}
#[tokio::test]
async fn into_response_retry_after_present_when_retry() {
let ctx = test_utils::test_context();
let events = vec![make_wrapped(EventResult::Retry, Some("not_persisted"))];
let resp = BatchResponse::build(&ctx, &events).into_response();
let hdr = resp
.headers()
.get(header::RETRY_AFTER)
.expect("Retry-After header should be present");
assert_eq!(hdr.to_str().unwrap(), "1");
}
#[tokio::test]
async fn into_response_retry_after_absent_when_no_retry() {
let ctx = test_utils::test_context();
let events = vec![make_wrapped(EventResult::Ok, None)];
let resp = BatchResponse::build(&ctx, &events).into_response();
assert!(resp.headers().get(header::RETRY_AFTER).is_none());
}
#[tokio::test]
async fn into_response_body_json_shape() {
let ctx = test_utils::test_context();
let events = vec![
make_wrapped(EventResult::Ok, None),
make_wrapped(EventResult::Drop, Some("billing_limit_exceeded")),
];
let uuids: Vec<String> = events.iter().map(|e| e.uuid.to_string()).collect();
let resp = BatchResponse::build(&ctx, &events).into_response();
let body_bytes = to_bytes(resp.into_body(), usize::MAX).await.unwrap();
let body: Value = serde_json::from_slice(&body_bytes).unwrap();
let results = body.get("results").expect("results key must exist");
assert!(results.is_object());
let first = results.get(&uuids[0]).unwrap();
assert_eq!(first["result"], "ok");
assert!(!first.as_object().unwrap().contains_key("details"));
let second = results.get(&uuids[1]).unwrap();
assert_eq!(second["result"], "drop");
assert_eq!(second["details"], "billing_limit_exceeded");
}
}