: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 serde::{Deserialize, Deserializer, Serialize, Serializer};
use serde_json::value::RawValue;
use serde_json::{Map, Value};
use std::sync::Arc;
use crate::api::errors::FlagError;
use crate::flags::config_v2;
use crate::flags::feature_flag_list::UndecodableDocument;
use crate::flags::flag_models::FlagFilters;
use crate::metrics::consts::FLAG_V2_PARSE_COUNTER;
use crate::utils::python_truthiness::is_falsy;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ConfigFormat {
V1,
V2,
Unsupported,
}
impl ConfigFormat {
fn from_number(number: Option<f64>) -> Self {
match number {
Some(1.0) => Self::V1,
Some(2.0) => Self::V2,
_ => Self::Unsupported,
}
}
}
struct FilterDocument<const BUILD_DOCUMENT: bool> {
format: ConfigFormat,
document: Map<String, Value>,
}
impl<'de, const BUILD_DOCUMENT: bool> Deserialize<'de> for FilterDocument<BUILD_DOCUMENT> {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
struct DocumentVisitor<const BUILD_DOCUMENT: bool>;
impl<'de, const BUILD_DOCUMENT: bool> serde::de::Visitor<'de> for DocumentVisitor<BUILD_DOCUMENT> {
type Value = FilterDocument<BUILD_DOCUMENT>;
fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str("a filters object")
}
fn visit_map<A: serde::de::MapAccess<'de>>(
self,
mut map: A,
) -> Result<Self::Value, A::Error> {
let mut format = ConfigFormat::V1;
let mut document = Map::new();
while let Some(key) = map.next_key::<String>()? {
if key == "version" {
let raw: &RawValue = map.next_value()?;
// Python rounds JSON numbers correctly; serde's default Value
// parser can round a nearby non-1 discriminator to 1 instead.
format = ConfigFormat::from_number(raw.get().parse::<f64>().ok());
if BUILD_DOCUMENT {
let mut version =
serde_json::from_str(raw.get()).unwrap_or(Value::Null);
// serialize_filters writes this normalized value back to the cache.
if format == ConfigFormat::V1 && version.as_f64() != Some(1.0) {
version = serde_json::json!(1.0);
}
document.insert(key, version);
}
} else if BUILD_DOCUMENT {
document.insert(key, map.next_value()?);
} else {
map.next_value::<serde::de::IgnoredAny>()?;
}
}
Ok(FilterDocument { format, document })
}
}
// Require an object: derived Deserialize also accepts positional arrays
// and would interpret [2] as a non-v1 document with version 2.
deserializer.deserialize_map(DocumentVisitor::<BUILD_DOCUMENT>)
}
}
impl FlagFilters {
pub(crate) fn is_v1(&self) -> bool {
self.non_v1.is_none()
}
pub(crate) fn require_v1(&self) -> Result<(), FlagError> {
if self.is_v1() {
Ok(())
} else {
Err(Self::unsupported_format())
}
}
pub(crate) fn supported_v2(&self) -> Option<&config_v2::Config> {
self.non_v1.as_ref()?.parsed_v2.as_ref()?.as_ref().ok()
}
pub(crate) fn is_supported(&self) -> bool {
self.is_v1() || self.supported_v2().is_some()
}
pub(crate) fn require_supported(&self) -> Result<(), FlagError> {
if self.is_supported() {
Ok(())
} else {
Err(Self::unsupported_format())
}
}
fn unsupported_format() -> FlagError {
FlagError::flag_data_parsing("unsupported feature flag configuration format")
}
}
#[derive(Debug, thiserror::Error)]
#[error("{error}")]
pub(crate) struct FilterDecodeError {
pub(crate) error: serde_json::Error,
pub(crate) document: UndecodableDocument,
}
#[cfg(test)]
pub(crate) fn decode_filters(value: Value) -> Result<FlagFilters, FilterDecodeError> {
let raw = serde_json::value::to_raw_value(&value).expect("a Value always serializes");
decode_raw_filters(raw)
}
pub(crate) fn decode_raw_filters(raw: Box<RawValue>) -> Result<FlagFilters, FilterDecodeError> {
let (format, document) = match serde_json::from_str::<FilterDocument<true>>(raw.get()) {
Ok(decoded) => (decoded.format, Ok(decoded.document)),
Err(error) => {
// An unrepresentable number must stay a per-flag v2 failure. Only
// failed Value reads need another scan to recover the discriminator.
let probe =
serde_json::from_str::<FilterDocument<false>>(raw.get()).map_err(|error| {
FilterDecodeError {
error,
document: UndecodableDocument::NotAnObject,
}
})?;
(probe.format, Err(error))
}
};
if format == ConfigFormat::V1 {
document
.and_then(|document| serde_json::from_value(Value::Object(document)))
.map_err(|error| FilterDecodeError {
error,
document: classify_undecodable_v1(&raw),
})
} else {
let parsed_v2 = (format == ConfigFormat::V2).then(|| {
config_v2::validate_raw_document(&raw)?;
let document = document.map_err(|_| config_v2::ParseError::Malformed("filters"))?;
config_v2::Config::parse(&document)
});
if let Some(parsed) = &parsed_v2 {
let outcome = match parsed {
Ok(_) => "success",
Err(config_v2::ParseError::Malformed(_)) => "malformed",
Err(config_v2::ParseError::Unsupported(_)) => "unsupported",
Err(config_v2::ParseError::LimitExceeded(_)) => "limit_exceeded",
};
metrics::counter!(FLAG_V2_PARSE_COUNTER, "outcome" => outcome).increment(1);
}
Ok(FlagFilters {
non_v1: Some(Arc::new(config_v2::NonV1Config {
parsed_v2,
document: raw,
})),
..Default::default()
})
}
}
fn classify_undecodable_v1(raw: &RawValue) -> UndecodableDocument {
// This read fails on a number that serde cannot represent, or on nesting deeper than
// serde's recursion limit. Python's JSON reader accepts both, so the document counts
// as one that Python's builder can read.
let Ok(document) = serde_json::from_str::<Value>(raw.get()) else {
return UndecodableDocument::UnreadableV1Object;
};
if python_reads_conditions(&document) {
UndecodableDocument::UnreadableV1Object
} else {
UndecodableDocument::MalformedV1Groups
}
}
/// Python's builder reads only the conditions of a v1 document, as `references()` in
/// `products/feature_flags/backend/facade/references.py` does. It iterates `groups or []`
/// and each group's `properties or []`, and calls `.get` on every element. Returns false
/// where that read raises.
fn python_reads_conditions(document: &Value) -> bool {
let Some(groups) = python_list(document.get("groups")) else {
return false;
};
groups.iter().all(|group| {
group
.as_object()
.and_then(|group| python_list(group.get("properties")))
.is_some_and(|properties| properties.iter().all(Value::is_object))
})
}
/// The elements Python iterates in `value or []`. Returns `None` for a truthy value that is
/// not an array, because Python either cannot iterate it or yields elements that are not
/// objects.
fn python_list(value: Option<&Value>) -> Option<&[Value]> {
match value {
Some(Value::Array(items)) => Some(items),
Some(value) if !is_falsy(value) => None,
_ => Some(&[]),
}
}
pub(crate) fn deserialize_filters<'de, D>(deserializer: D) -> Result<FlagFilters, D::Error>
where
D: Deserializer<'de>,
{
decode_raw_filters(Box::<RawValue>::deserialize(deserializer)?)
.map_err(serde::de::Error::custom)
}
/// Derived serialization adds v1 fields to opaque documents, so those keep their raw JSON.
pub(crate) fn serialize_filters<S>(filters: &FlagFilters, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
match &filters.non_v1 {
Some(config) => config.document.serialize(serializer),
None => filters.serialize(serializer),
}
}
#[cfg(test)]
mod tests;