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.

8.6 KB
Raw Blame
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;