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.

9.0 KB
Raw Blame
use serde::{Deserialize, Serialize};

pub(crate) const ESTIMATED_COMPILED_REGEX_BYTES: usize = 2048;

// Keep in sync with FEATURE_FLAG_SUPPORTED_OPERATORS, defined in
// products/feature_flags/backend/api/filters_schema.py (used there by the filters serializer
// and by the write-path serde guard in feature_flag.py — issue #50084). This enum is
// deliberately a superset: cohort filters don't go through flag-level operator validation,
// so operators the cohort UI allows (between/not_between, and the min/max aliases mirroring
// FEATURE_FLAG_OPERATOR_ALIASES) must deserialize here even though the flag API rejects them.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum OperatorType {
    Exact,
    IsNot,
    Icontains,
    NotIcontains,
    IcontainsMulti,
    NotIcontainsMulti,
    StartsWith,
    NotStartsWith,
    EndsWith,
    NotEndsWith,
    Regex,
    NotRegex,
    Gt,
    Lt,
    #[serde(alias = "min")]
    Gte,
    #[serde(alias = "max")]
    Lte,
    Between,
    NotBetween,
    SemverGt,
    SemverGte,
    SemverLt,
    SemverLte,
    SemverEq,
    SemverNeq,
    SemverTilde,
    SemverCaret,
    SemverWildcard,
    IsSet,
    IsNotSet,
    IsDateExact,
    IsDateAfter,
    IsDateBefore,
    In,
    NotIn,
    FlagEvaluatesTo,
}

#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PropertyType {
    #[default]
    #[serde(rename = "person")]
    Person,
    // Top-level columns on the persons table (e.g. created_at), not the JSON properties blob.
    #[serde(rename = "person_metadata")]
    PersonMetadata,
    #[serde(rename = "cohort")]
    Cohort,
    #[serde(rename = "group")]
    Group,
    // A flag property is compared to another flag evaluation result
    #[serde(rename = "flag")]
    Flag,
}

/// Regex backtrack limit to prevent ReDoS attacks.
/// 10k steps completes in ~1ms worst case, which is acceptable for a hot path.
const REGEX_BACKTRACK_LIMIT: usize = 10_000;

/// Pre-compiled regex state for Regex/NotRegex operators.
/// Populated by `prepare_regex()` at flag-load time.
/// Clone is cheap: fancy_regex::Regex uses Arc<Prog> internally.
#[derive(Clone)]
pub enum CompiledRegex {
    /// Pattern compiled successfully — use this for matching.
    Compiled(fancy_regex::Regex),
    /// Pattern failed to compile — always returns Ok(false), no re-compilation needed.
    InvalidPattern,
}

impl CompiledRegex {
    pub fn new(pattern: &str) -> Self {
        match fancy_regex::RegexBuilder::new(pattern)
            .backtrack_limit(REGEX_BACKTRACK_LIMIT)
            .build()
        {
            Ok(regex) => Self::Compiled(regex),
            Err(_) => Self::InvalidPattern,
        }
    }
}

impl std::fmt::Debug for CompiledRegex {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Compiled(re) => write!(f, "CompiledRegex(/{}/)", re.as_str()),
            Self::InvalidPattern => write!(f, "CompiledRegex(invalid)"),
        }
    }
}

/// Deserializes `PropertyFilter.key` from either a JSON string or a JSON number.
///
/// Flag-dependency keys are flag IDs, and the API has persisted them as raw JSON
/// numbers in some cases (e.g. a flag migration that stored dependency IDs as
/// integers). serde will not coerce a number into a `String`, so without this a
/// single numeric key fails deserialization of the whole team's cached flag
/// payload — taking down flag evaluation for the entire project rather than just
/// the malformed flag. Accept both forms and normalize to a string; the evaluator
/// parses it back to an id at match time (`get_feature_flag_id`).
fn deserialize_key<'de, D>(deserializer: D) -> Result<String, D::Error>
where
    D: serde::Deserializer<'de>,
{
    #[derive(Deserialize)]
    #[serde(untagged)]
    enum StringOrNumber {
        String(String),
        Number(serde_json::Number),
    }

    Ok(match StringOrNumber::deserialize(deserializer)? {
        StringOrNumber::String(s) => s,
        StringOrNumber::Number(n) => n.to_string(),
    })
}

// Runtime Python mirror: products/feature_flags/backend/api/filters_schema.py validates flag
// filter properties against this shape at write time — keep field shapes in sync (issue #50084).
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
pub struct PropertyFilter {
    #[serde(deserialize_with = "deserialize_key")]
    pub key: String,
    // NB: if a property filter is of type is_set or is_not_set, the value isn't used, and if it's a filter made by the API, the value is None.
    pub value: Option<serde_json::Value>,
    pub operator: Option<OperatorType>,
    #[serde(rename = "type")]
    pub prop_type: PropertyType,
    pub negation: Option<bool>,
    pub group_type_index: Option<i32>,
    /// Pre-compiled regex for Regex/NotRegex operators.
    /// `None` means `prepare_regex()` was not called (fallback to on-the-fly compilation).
    /// `Some(Compiled(_))` holds the pre-compiled regex.
    /// `Some(InvalidPattern)` means the pattern failed to compile — returns false immediately.
    #[serde(skip)]
    pub compiled_regex: Option<CompiledRegex>,
    /// Captures unknown JSONB keys so they survive the cache round-trip unchanged.
    /// Without this, runtime annotations like `cohort_name` and `group_key_names`
    /// would be silently dropped on round-trip and the Python `verify_flags_cache`
    /// verifier would report spurious `FIELD_MISMATCH` against the Django JSONB
    /// passthrough. Only unknown-key passthrough is guaranteed here — absent-vs-null
    /// normalization for known optional fields is handled by the Python verifier's
    /// `_strip_null_values` helper.
    /// See plans/verify-flags-cache-loose-comparison.md.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, serde_json::Value>,
}

#[cfg(test)]
#[allow(clippy::needless_update)]
mod mock_impls {
    use super::*;
    use crate::utils::mock::Mock;

    impl Mock for PropertyFilter {
        fn mock() -> Self {
            PropertyFilter {
                key: "test_prop".to_string(),
                value: Some(serde_json::json!("test_value")),
                operator: Some(OperatorType::Exact),
                ..Default::default()
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn deserializes_numeric_key_as_string() {
        // A flag dependency persisted with a numeric `key` (e.g. after a migration
        // that stored dependency IDs as integers) must not fail deserialization —
        // otherwise one bad flag takes down the whole team's cached payload.
        let filter: PropertyFilter = serde_json::from_value(serde_json::json!({
            "key": 226357,
            "value": true,
            "type": "flag",
            "operator": "flag_evaluates_to",
        }))
        .expect("numeric key should deserialize as a string");

        assert_eq!(filter.key, "226357");
        assert_eq!(filter.get_feature_flag_id(), Some(226357));
    }

    #[test]
    fn deserializes_string_key() {
        let filter: PropertyFilter = serde_json::from_value(serde_json::json!({
            "key": "email",
            "value": "[email protected]",
            "type": "person",
            "operator": "exact",
        }))
        .expect("string key should deserialize");

        assert_eq!(filter.key, "email");
    }

    #[test]
    fn deserializes_between_operators_and_min_max_aliases() {
        // Cohort filters can carry operators the flag API rejects (between/not_between)
        // and the legacy min/max aliases that only the flag write path normalizes to
        // gte/lte — all of them must deserialize instead of failing the whole cohort.
        let cases = [
            ("between", OperatorType::Between),
            ("not_between", OperatorType::NotBetween),
            ("min", OperatorType::Gte),
            ("max", OperatorType::Lte),
        ];
        for (wire_name, expected) in cases {
            let operator: OperatorType = serde_json::from_value(serde_json::json!(wire_name))
                .unwrap_or_else(|_| panic!("operator '{wire_name}' should deserialize"));
            assert_eq!(operator, expected, "operator '{wire_name}'");
        }

        // The aliases must not change serialization: a Gte/Lte parsed from "min"/"max"
        // still round-trips as "gte"/"lte" (guards the hypercache verifier contract).
        assert_eq!(
            serde_json::to_value(OperatorType::Gte).unwrap(),
            serde_json::json!("gte")
        );
        assert_eq!(
            serde_json::to_value(OperatorType::Lte).unwrap(),
            serde_json::json!("lte")
        );

        // Between/NotBetween must also round-trip to their own canonical wire names
        // (guards the same hypercache verifier contract for the operators this PR adds).
        assert_eq!(
            serde_json::to_value(OperatorType::Between).unwrap(),
            serde_json::json!("between")
        );
        assert_eq!(
            serde_json::to_value(OperatorType::NotBetween).unwrap(),
            serde_json::json!("not_between")
        );
    }
}