: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
//! Recording (session replay) payload handling
//!
//! This module contains optimized payload processing logic for recording events.
//! Unlike analytics events, recording payloads are deserialized directly to
//! Vec<RawRecording> to avoid the overhead of going through RawRequest.
use axum::body::Body;
use axum::extract::{MatchedPath, State};
use axum::http::{HeaderMap, Method};
use axum_client_ip::InsecureClientIp;
use metrics::counter;
use tracing::{info, instrument, Span};
use crate::{
api::CaptureError,
debug_or_info,
events::recordings::RawRecording,
extractors::extract_body_with_timeout,
ingestion_warnings::replay::attribution_from_event,
payload::{decompress_payload, extract_and_record_metadata, extract_payload_bytes, EventQuery},
router,
token::validate_token,
v0_request::ProcessingContext,
};
/// Helper enum to deserialize either a single recording or an array
#[derive(Debug, serde::Deserialize)]
#[serde(untagged)]
enum RecordingPayload {
Array(Vec<RawRecording>),
One(Box<RawRecording>),
}
impl RecordingPayload {
fn into_vec(self) -> Vec<RawRecording> {
match self {
RecordingPayload::Array(events) => events,
RecordingPayload::One(event) => vec![*event],
}
}
}
/// handle_recording_payload processes recording (session replay) payloads
/// This is optimized to avoid the double serialization that would occur
/// if we went through RawRequest -> Vec<RawEvent> -> process
#[instrument(skip_all, fields(batch_size, params_compression))]
#[allow(clippy::too_many_arguments)]
pub async fn handle_recording_payload(
state: &State<router::State>,
InsecureClientIp(ip): &InsecureClientIp,
query_params: &mut EventQuery,
headers: &HeaderMap,
method: &Method,
path: &MatchedPath,
wire_limit: Option<router::WireBodyLimit>,
body: Body,
) -> Result<(ProcessingContext, Vec<RawRecording>), CaptureError> {
let chatty_debug_enabled = headers.get("X-CAPTURE-DEBUG").is_some();
debug_or_info!(chatty_debug_enabled, headers=?headers, "entering handle_recording_payload");
// Extract body with optional chunk timeout
// Wire limit governs the streamed body; event_payload_size_limit is the
// larger budget for what that body decompresses into.
let wire_limit = wire_limit
.map(|l| l.0)
.unwrap_or(state.event_payload_size_limit);
let body = extract_body_with_timeout(
body,
wire_limit,
state.body_chunk_read_timeout,
state.body_read_chunk_size_kb,
path.as_str(),
)
.await?;
debug_or_info!(chatty_debug_enabled, headers=?headers, "streamed payload body");
// Extract request metadata using shared helper
let metadata = extract_and_record_metadata(headers, path.as_str(), state.is_mirror_deploy);
debug_or_info!(chatty_debug_enabled, metadata=?metadata, "extracted metadata");
// Extract payload bytes and metadata using shared helper
let (data, compression) = extract_payload_bytes(query_params, headers, method, body)?;
Span::current().record("compression", format!("{compression}"));
debug_or_info!(chatty_debug_enabled, metadata=?metadata, compression=?compression, "extracted payload");
// Decompress the payload
let payload = decompress_payload(
data,
compression,
state.event_payload_size_limit,
path.as_str(),
)?;
debug_or_info!(chatty_debug_enabled, metadata=?metadata, compression=?compression, "decompressed payload");
// Deserialize to RecordingPayload (handles both single event and array)
let recording_payload: RecordingPayload = serde_json::from_str(&payload)?;
let mut events = recording_payload.into_vec();
debug_or_info!(chatty_debug_enabled, metadata=?metadata, event_count=?events.len(), "hydrated events");
if events.is_empty() {
info!(metadata = ?metadata, "rejected empty recording batch");
return Err(CaptureError::EmptyBatch);
}
Span::current().record("batch_size", events.len());
// Extract token from first event
let token = events[0]
.extract_token()
.ok_or(CaptureError::NoTokenError)?;
validate_token(&token)?;
Span::current().record("token", &token);
counter!("capture_events_received_total").increment(events.len() as u64);
let now = state.timesource.current_time();
let sent_at = events[0].sent_at().or_else(|| query_params.sent_at());
let context = ProcessingContext {
sent_at,
token,
now,
client_ip: ip.to_string(),
request_id: metadata.request_id.to_string(),
path: path.as_str().to_string(),
is_mirror_deploy: metadata.is_mirror_deploy,
historical_migration: false, // recordings don't support historical migration
user_agent: Some(metadata.user_agent.to_string()),
chatty_debug_enabled,
capture_mode: state.capture_mode,
ai_max_event_bytes: 0,
sdk_attribution: attribution_from_event(&events[0], metadata.user_agent),
};
// Apply all billing limit quotas and drop partial or whole
// payload if any are exceeded for this token (team)
debug_or_info!(chatty_debug_enabled, context=?context, event_count=?events.len(), "evaluating quota limits");
events = state
.quota_limiter
.check_and_filter(&context.token, events)
.await?;
debug_or_info!(chatty_debug_enabled, context=?context, event_count=?events.len(), "processing complete");
Ok((context, events))
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
#[test]
fn test_recording_payload_single_event() {
let json = json!({
"event": "$snapshot",
"distinct_id": "user123",
"properties": {
"$session_id": "session-abc",
"$snapshot_data": [{"type": 1}]
}
});
let payload: RecordingPayload = serde_json::from_value(json).unwrap();
let events = payload.into_vec();
assert_eq!(events.len(), 1);
assert_eq!(events[0].event, "$snapshot");
}
#[test]
fn test_recording_payload_array_of_events() {
let json = json!([
{
"event": "$snapshot",
"distinct_id": "user123",
"properties": {
"$session_id": "session-abc",
"$snapshot_data": [{"type": 1}]
}
},
{
"event": "$snapshot",
"distinct_id": "user123",
"properties": {
"$session_id": "session-abc",
"$snapshot_data": [{"type": 2}]
}
}
]);
let payload: RecordingPayload = serde_json::from_value(json).unwrap();
let events = payload.into_vec();
assert_eq!(events.len(), 2);
assert_eq!(events[0].event, "$snapshot");
assert_eq!(events[1].event, "$snapshot");
}
#[test]
fn test_recording_payload_into_vec_does_not_copy() {
// This test verifies that into_vec() moves the data rather than copying
let json = json!([
{
"event": "$snapshot",
"distinct_id": "user123",
"properties": {
"$session_id": "session-abc",
"$snapshot_data": [{"type": 1}]
}
}
]);
let payload: RecordingPayload = serde_json::from_value(json).unwrap();
let events = payload.into_vec();
// If this compiles and runs, it proves into_vec() took ownership
assert_eq!(events.len(), 1);
}
}