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.

44.9 KB
Raw Blame
use serde::de::{self, Deserializer};
use serde::ser::{SerializeMap, Serializer};
use serde::{Deserialize, Serialize};
use std::collections::{HashMap, HashSet};
use std::sync::Arc;

use crate::cohorts::cohort_models::Cohort;
use crate::flags::feature_flag_list::PreparedFlags;
use crate::properties::property_models::{PropertyFilter, ESTIMATED_COMPILED_REGEX_BYTES};

// NOTE: The `evaluation_tags` field was renamed to `evaluation_contexts` in the Python
// serializer (PR #52186). The Rust field keeps the old name for internal compatibility,
// but uses `#[serde(rename = "evaluation_contexts")]` to match the JSON key.

/// Deserializes a JSON object with string keys into `HashMap<i32, HashSet<i32>>`.
/// JSON only supports string keys, so Python serializes `{1: [2, 3]}` as `{"1": [2, 3]}`.
fn deserialize_string_keyed_i32_map<'de, D>(
    deserializer: D,
) -> Result<HashMap<i32, HashSet<i32>>, D::Error>
where
    D: Deserializer<'de>,
{
    let raw: HashMap<String, Vec<i32>> = HashMap::deserialize(deserializer)?;
    raw.into_iter()
        .map(|(k, v)| {
            let id = k.parse::<i32>().map_err(de::Error::custom)?;
            Ok((id, v.into_iter().collect()))
        })
        .collect()
}

/// Serializes `HashMap<i32, HashSet<i32>>` back to JSON with string keys.
fn serialize_string_keyed_i32_map<S>(
    map: &HashMap<i32, HashSet<i32>>,
    serializer: S,
) -> Result<S::Ok, S::Error>
where
    S: Serializer,
{
    let mut ser_map = serializer.serialize_map(Some(map.len()))?;
    let mut keys: Vec<&i32> = map.keys().collect();
    keys.sort_unstable();
    for k in keys {
        let v = &map[k];
        let sorted: Vec<i32> = {
            let mut s: Vec<i32> = v.iter().copied().collect();
            s.sort_unstable();
            s
        };
        ser_map.serialize_entry(&k.to_string(), &sorted)?;
    }
    ser_map.end()
}

/// Deserializes a field into `Option<Option<T>>` to distinguish "absent" from "null":
/// - Field absent → `None` (outer)
/// - Field present, value `null` → `Some(None)`
/// - Field present, value `v` → `Some(Some(v))`
fn deserialize_double_option<'de, T, D>(deserializer: D) -> Result<Option<Option<T>>, D::Error>
where
    T: Deserialize<'de>,
    D: Deserializer<'de>,
{
    // When serde calls this, the field was present in JSON. Absent fields
    // never reach the deserializer — #[serde(default)] yields None instead.
    Ok(Some(Option::deserialize(deserializer)?))
}

/// Pre-computed dependency metadata, built by Django at cache-write time.
/// Shipped as a top-level field alongside the flags array in the hypercache.
#[derive(Debug, Clone, Default, PartialEq, Deserialize, Serialize)]
pub struct EvaluationMetadata {
    /// Flag IDs grouped by evaluation stage. Stage 0 (no deps) first.
    pub dependency_stages: Vec<Vec<i32>>,
    /// Flag IDs with missing, cyclic, or transitively broken dependencies.
    pub flags_with_missing_deps: Vec<i32>,
    /// Flag ID → transitive dependency flag IDs.
    #[serde(
        deserialize_with = "deserialize_string_keyed_i32_map",
        serialize_with = "serialize_string_keyed_i32_map"
    )]
    pub transitive_deps: HashMap<i32, HashSet<i32>>,
    /// True when the serving read skipped a cached flag that it could not parse, or the
    /// PostgreSQL fallback omitted a flag that Python's builder can read.
    /// The response then sets `errorsWhileComputingFlags`, so an SDK merges the
    /// response into its stored flags and keeps the skipped flag's last value.
    #[serde(skip)]
    pub has_unparseable_flags: bool,
}

impl EvaluationMetadata {
    /// Builds metadata that places all flags in a single evaluation stage
    /// with no dependency ordering. Used when `compute_flag_dependencies` returns an error.
    pub fn single_stage(flags: &[FeatureFlag]) -> Self {
        Self {
            dependency_stages: vec![flags.iter().map(|f| f.id).collect()],
            transitive_deps: flags.iter().map(|f| (f.id, HashSet::new())).collect(),
            ..Default::default()
        }
    }

    /// Drops every reference to a flag outside `kept_flag_ids`, and marks a kept
    /// flag that depends on a dropped one as missing a dependency, so it fails
    /// closed like any other flag whose dependency Django cannot resolve.
    /// Changes nothing when `kept_flag_ids` holds every flag id that the metadata names.
    pub fn retain_flags(&mut self, kept_flag_ids: &HashSet<i32>) {
        self.flags_with_missing_deps
            .retain(|id| kept_flag_ids.contains(id));
        self.flags_with_missing_deps.extend(
            self.transitive_deps
                .iter()
                .filter(|(id, deps)| kept_flag_ids.contains(id) && !deps.is_subset(kept_flag_ids))
                .map(|(id, _)| *id),
        );
        self.flags_with_missing_deps.sort_unstable();
        self.flags_with_missing_deps.dedup();

        self.transitive_deps
            .retain(|id, _| kept_flag_ids.contains(id));
        for deps in self.transitive_deps.values_mut() {
            deps.retain(|dep| kept_flag_ids.contains(dep));
        }
        for stage in &mut self.dependency_stages {
            stage.retain(|id| kept_flag_ids.contains(id));
        }
        self.dependency_stages.retain(|stage| !stage.is_empty());
    }
}

/// Wrapper struct for deserializing hypercache format:
/// `{"flags": [...], "evaluation_metadata": {...}, "cohorts": [...] | null}`.
///
/// `evaluation_metadata` is always present in cache entries (written by Django).
/// The PG fallback path computes it from the loaded flags with
/// `compute_flag_dependencies_or_single_stage()`.
///
/// HYPERCACHE CONTRACT: These fields must match the top-level keys returned by
/// `_get_feature_flags_for_service()` in products/feature_flags/backend/flags_cache.py.
/// Field changes must follow the expand-and-contract pattern — see contract tests in
/// products/feature_flags/backend/test/test_flags_cache.py.
///
/// `F` is the flags array type. The serving read uses
/// [`LenientFlags`](crate::flags::feature_flag_list::LenientFlags) to skip a flag it cannot read.
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct HypercacheFlagsWrapper<F = Vec<FeatureFlag>> {
    pub flags: F,
    pub evaluation_metadata: EvaluationMetadata,
    /// Cohort definitions referenced by flags (including transitive deps).
    /// Precomputed by Django at cache-write time so the Rust service can skip
    /// the separate CohortCacheManager PG query.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cohorts: Option<Vec<Cohort>>,
}

/// New holdout format: `{"id": 42, "exclusion_percentage": 10}`.
/// Replaces the legacy `holdout_groups` array which reused `FlagPropertyGroup` with
/// confusing semantics (rollout_percentage meant exclusion, variant was just "holdout-{id}").
/// See holdout-migration-plan.md for the full migration plan.
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
pub struct Holdout {
    pub id: i64,
    pub exclusion_percentage: f64,
    #[serde(flatten)]
    pub extra: serde_json::Map<String, serde_json::Value>,
}

impl Holdout {
    /// `exclusion_percentage` clamped to a valid 0-100 range, guarding against an out-of-range
    /// stored value.
    pub fn exclusion_percentage_clamped(&self) -> f64 {
        self.exclusion_percentage.clamp(0.0, 100.0)
    }
}

#[derive(Debug, Clone, Deserialize, Serialize, Default)]
pub struct FlagPropertyGroup {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub properties: Option<Vec<PropertyFilter>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rollout_percentage: Option<f64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub variant: Option<String>,
    /// Per-condition-set aggregation group type index. The outer Option distinguishes
    /// "field absent" (legacy flags, should fall back to flag-level) from "field
    /// present but null" (explicit person aggregation). When the inner Option holds
    /// a value, the condition uses that group type for hashing and property evaluation.
    ///
    /// `skip_serializing_if = "Option::is_none"` preserves the absent/null distinction
    /// on round-trip: outer `None` (absent) serializes as no key; `Some(None)` (explicit
    /// null) serializes as `null`; `Some(Some(idx))` serializes as the integer. Without
    /// this, both `None` and `Some(None)` would serialize identically as `null`, silently
    /// converting absent → null and changing matcher behavior on cache-warmed flags.
    #[serde(
        default,
        deserialize_with = "deserialize_double_option",
        skip_serializing_if = "Option::is_none"
    )]
    pub aggregation_group_type_index: Option<Option<i32>>,
    /// Captures unknown JSONB keys so they survive the cache round-trip unchanged.
    /// Without this, frontend leaks (`description`, `sort_key`), runtime annotations
    /// (`cohort_name`, `group_key_names`), and field typos 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. The known optional fields
    /// (`properties`, `rollout_percentage`, `variant`) carry
    /// `skip_serializing_if = "Option::is_none"` so an absent source key stays
    /// absent on cache-write rather than re-emitting as `null`.
    /// See plans/verify-flags-cache-loose-comparison.md and
    /// plans/rust-flag-models-skip-serializing-if-sweep.md.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, serde_json::Value>,
}

#[derive(Debug, Clone, Default, Deserialize, Serialize)]
pub struct MultivariateFlagVariant {
    pub key: String,
    pub name: Option<String>,
    pub rollout_percentage: f64,
    #[serde(flatten)]
    pub extra: serde_json::Map<String, serde_json::Value>,
}

#[derive(Debug, Clone, Default, Deserialize, Serialize)]
pub struct MultivariateFlagOptions {
    pub variants: Vec<MultivariateFlagVariant>,
    #[serde(flatten)]
    pub extra: serde_json::Map<String, serde_json::Value>,
}

// Runtime Python mirror: products/feature_flags/backend/api/filters_schema.py validates
// filters against these shapes at write time — keep field shapes in sync (issue #50084).
//
// V1 `filters` is customer-writable JSONB that Django stores unvalidated, so each v1
// struct reachable from here must carry `#[serde(flatten)] extra` and be weighed in
// `estimate_filters_size`. Skipping either drops customer keys, or hides their bytes.
#[derive(Clone, Deserialize, Serialize, Default)]
pub struct FlagFilters {
    #[serde(skip)]
    pub non_v1: Option<Arc<super::config_v2::NonV1Config>>,
    #[serde(default)]
    pub groups: Vec<FlagPropertyGroup>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub multivariate: Option<MultivariateFlagOptions>,
    /// The group type index is used to determine which group type to use for the flag.
    ///
    /// Typical group type mappings are:
    /// - 0 → "project"
    /// - 1 → "organization"
    /// - 2 → "instance"
    /// - 3 → "customer"
    /// - 4 → "team"
    ///
    /// `skip_serializing_if = "Option::is_none"` so absent JSONB stays absent on
    /// cache-write round-trip. Unlike `FlagPropertyGroup.aggregation_group_type_index`
    /// (which is `Option<Option<i32>>`), the filters-level field does not preserve
    /// the absent/null distinction on deserialize — but Rust still shouldn't fabricate
    /// a `null` key when the source had no key, since the Python verifier compares
    /// against Django's JSONB passthrough and a fabricated null shows up as drift.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub aggregation_group_type_index: Option<i32>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub payloads: Option<serde_json::Value>,
    /// Early access feature enrollment. When `true`, the flag is evaluated against the
    /// person property `$feature_enrollment/{flag_key}`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub feature_enrollment: Option<bool>,
    /// Holdout format: `{"id": 42, "exclusion_percentage": 10}`.
    /// Defines a set of users intentionally excluded from a test or experiment.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub holdout: Option<Holdout>,
    /// Flag-level toggle: when true, condition evaluation stops at the first
    /// matching group rather than continuing to evaluate subsequent groups.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub early_exit: Option<bool>,
    /// Captures unknown JSONB keys so they survive the cache round-trip unchanged.
    /// Without this, legacy filter keys (`holdout_groups`), top-level stray keys,
    /// and field typos (`multivariant` for `multivariate`, `payload` for
    /// `payloads`) 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. The known optional fields (`multivariate`, `payloads`,
    /// `feature_enrollment`, `holdout`, `early_exit`,
    /// `aggregation_group_type_index`) carry
    /// `skip_serializing_if = "Option::is_none"` so an absent source key stays
    /// absent on cache-write. Keys that only ever travel through `extra` (e.g.
    /// `super_groups`, the legacy `holdout_groups`) are emitted only when present.
    /// See plans/verify-flags-cache-loose-comparison.md and
    /// plans/rust-flag-models-skip-serializing-if-sweep.md.
    #[serde(flatten)]
    pub extra: serde_json::Map<String, serde_json::Value>,
}

impl std::fmt::Debug for FlagFilters {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let Self {
            non_v1,
            groups,
            multivariate,
            aggregation_group_type_index,
            payloads,
            feature_enrollment,
            holdout,
            early_exit,
            extra,
        } = self;
        if !self.is_v1() {
            return f
                .debug_struct("FlagFilters")
                .field("non_v1", non_v1)
                .finish_non_exhaustive();
        }
        f.debug_struct("FlagFilters")
            .field("non_v1", non_v1)
            .field("groups", groups)
            .field("multivariate", multivariate)
            .field("aggregation_group_type_index", aggregation_group_type_index)
            .field("payloads", payloads)
            .field("feature_enrollment", feature_enrollment)
            .field("holdout", holdout)
            .field("early_exit", early_exit)
            .field("extra", extra)
            .finish()
    }
}

pub type FeatureFlagId = i32;

/// Defines which identifier is used for bucketing users into rollout and variants
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BucketingIdentifier {
    DistinctId,
    DeviceId,
}

// TODO: see if you can combine these two structs, like we do with cohort models
// this will require not deserializing on read and instead doing it lazily, on-demand
// (which, tbh, is probably a better idea)
///
/// HYPERCACHE CONTRACT: These fields are deserialized from JSON written by Python's
/// MinimalFeatureFlagSerializer (products/feature_flags/backend/api/feature_flag.py). Field changes must
/// follow the expand-and-contract pattern. Golden fixture contract test:
///   cargo test -p feature-flags test_hypercache_contract
///
/// Encrypted-payload flags are excluded at the Python query layer, so this struct
/// has no field for `has_encrypted_payloads`.
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
pub struct FeatureFlag {
    pub id: FeatureFlagId,
    pub team_id: i32,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    pub key: String,
    // Check the format before reading v1 fields; non-v1 documents retain their raw JSON.
    #[serde(
        deserialize_with = "crate::flags::config_format::deserialize_filters",
        serialize_with = "crate::flags::config_format::serialize_filters"
    )]
    pub filters: FlagFilters,
    #[serde(default)]
    pub deleted: bool,
    #[serde(default)]
    pub active: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ensure_experience_continuity: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub version: Option<i32>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub evaluation_runtime: Option<String>,
    /// Evaluation context tags for this flag. JSON key is `evaluation_contexts`,
    /// but Rust field remains `evaluation_tags` for internal compatibility.
    #[serde(
        default,
        rename = "evaluation_contexts",
        skip_serializing_if = "Option::is_none"
    )]
    pub evaluation_tags: Option<Vec<String>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub bucketing_identifier: Option<String>,
    /// True if the flag has at least one non-deleted linked experiment. Surfaced to
    /// SDKs via FlagDetailsMetadata so they can decide whether to keep or strip
    /// $feature_flag_called event properties.
    ///
    /// Defaults to `true` (rather than the usual `#[serde(default)]` bool false) so cache
    /// entries written by older Django without the field over-preserve properties instead of
    /// stripping them. A spurious `true` only wastes bytes; a spurious `false` would strip
    /// unrecoverable experiment-exposure data. The panic fallback shares this default via
    /// `default_has_experiment()`; the PG fallback query computes the real value.
    #[serde(default = "default_has_experiment")]
    pub has_experiment: bool,
}

/// Default for `FeatureFlag::has_experiment` when experiment linkage is unknowable — an
/// older-Django cache payload missing the field, or the panic fallback that can't compute
/// it. See the field doc for why this is `true` rather than `false`.
pub(crate) fn default_has_experiment() -> bool {
    true
}

impl FeatureFlag {
    /// Returns the bucketing identifier for this flag.
    /// Defaults to DistinctId if not specified or if an invalid value is provided.
    pub fn get_bucketing_identifier(&self) -> BucketingIdentifier {
        match self.bucketing_identifier.as_deref() {
            Some("device_id") => BucketingIdentifier::DeviceId,
            _ => BucketingIdentifier::DistinctId,
        }
    }
}

/// Row struct for PostgreSQL queries via sqlx. The `evaluation_tags` column is
/// always named `evaluation_tags` in the SQL query, so no alias is needed.
#[derive(Default, Serialize, sqlx::FromRow)]
pub struct FeatureFlagRow<F = serde_json::Value> {
    pub id: i32,
    pub team_id: i32,
    pub name: Option<String>,
    pub key: String,
    pub filters: F,
    pub deleted: bool,
    pub active: bool,
    pub ensure_experience_continuity: Option<bool>,
    pub version: Option<i32>,
    #[serde(default)]
    pub evaluation_runtime: Option<String>,
    #[serde(default)]
    pub evaluation_tags: Option<Vec<String>>,
    #[serde(default)]
    pub bucketing_identifier: Option<String>,
    /// Populated by the from_pg fallback query via a correlated EXISTS over posthog_experiment.
    #[serde(default)]
    pub has_experiment: bool,
}

impl<F> std::fmt::Debug for FeatureFlagRow<F> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let Self {
            id,
            team_id,
            name,
            key,
            filters: _,
            deleted,
            active,
            ensure_experience_continuity,
            version,
            evaluation_runtime,
            evaluation_tags,
            bucketing_identifier,
            has_experiment,
        } = self;
        f.debug_struct("FeatureFlagRow")
            .field("id", id)
            .field("team_id", team_id)
            .field("name", name)
            .field("key", key)
            .field("filters", &"<redacted>")
            .field("deleted", deleted)
            .field("active", active)
            .field("ensure_experience_continuity", ensure_experience_continuity)
            .field("version", version)
            .field("evaluation_runtime", evaluation_runtime)
            .field("evaluation_tags", evaluation_tags)
            .field("bucketing_identifier", bucketing_identifier)
            .field("has_experiment", has_experiment)
            .finish()
    }
}

/// Request-scoped view of flag definitions plus the per-request filter set.
/// All shared fields are `Arc`-backed so `clone()` is a refcount bump rather
/// than a deep copy.
#[derive(Clone, Debug, Default)]
pub struct FeatureFlagList {
    pub flags: PreparedFlags,
    /// Flag IDs to skip during evaluation: inactive, deleted, survey-excluded,
    /// runtime-mismatched, or tag-filtered. Recomputed per request, so it
    /// isn't part of the cached value.
    pub filtered_out_flag_ids: HashSet<i32>,
    /// Pre-computed dependency metadata from Django's hypercache.
    pub evaluation_metadata: Arc<EvaluationMetadata>,
    /// Cohort definitions referenced by flags (including transitive deps),
    /// precomputed by Django. When present, the matcher uses these instead of
    /// querying `CohortCacheManager`. `None` for PG-fallback or pre-cohort-bake
    /// teams.
    pub cohorts: Option<Arc<[Cohort]>>,
}

/// Immutable, pre-compiled flag definitions cached across requests. The
/// outer `Arc<PreparedFlagDefinitions>` is shared per team; each inner field
/// is independently reference-counted so a request-scoped `FeatureFlagList`
/// can share any subset without copying.
#[derive(Clone, Debug)]
pub struct PreparedFlagDefinitions {
    pub flags: PreparedFlags,
    pub evaluation_metadata: Arc<EvaluationMetadata>,
    pub cohorts: Option<Arc<[Cohort]>>,
}

/// Estimates the heap bytes a flag's deserialized `filters` JSONB occupies.
/// Every `extra` passthrough map in the subtree has to be weighed here, or oversized
/// unknown keys bypass the cache's byte budget.
fn estimate_filters_size(filters: &FlagFilters) -> usize {
    use crate::utils::json_size::{estimate_json_map_size, estimate_json_size};

    // A compiled regex costs ~2KB for the DFA/NFA automata inside fancy_regex::Regex, and
    // the `value` payload can dominate for cohort/group filters, so walk it.
    let properties_size = |props: &[PropertyFilter]| -> usize {
        props
            .iter()
            .map(|p| {
                std::mem::size_of::<PropertyFilter>()
                    + p.key.len()
                    + p.value.as_ref().map_or(0, estimate_json_size)
                    + if p.compiled_regex.is_some() {
                        ESTIMATED_COMPILED_REGEX_BYTES
                    } else {
                        0
                    }
                    + estimate_json_map_size(&p.extra)
            })
            .sum()
    };
    let groups_size: usize = filters
        .groups
        .iter()
        .map(|g| {
            g.properties
                .as_ref()
                .map_or(0, |props| properties_size(props))
                + estimate_json_map_size(&g.extra)
        })
        .sum();
    let multivariate_size = filters.multivariate.as_ref().map_or(0, |m| {
        estimate_json_map_size(&m.extra)
            + m.variants
                .iter()
                .map(|v| {
                    std::mem::size_of::<MultivariateFlagVariant>()
                        + v.key.len()
                        + v.name.as_ref().map_or(0, |n| n.len())
                        + estimate_json_map_size(&v.extra)
                })
                .sum::<usize>()
    });
    let holdout_size = filters
        .holdout
        .as_ref()
        .map_or(0, |h| estimate_json_map_size(&h.extra));

    groups_size
        + filters
            .non_v1
            .as_ref()
            .map_or(0, |config| config.estimated_heap_bytes())
        + estimate_json_map_size(&filters.extra)
        + multivariate_size
        + holdout_size
        + filters.payloads.as_ref().map_or(0, estimate_json_size)
}

impl PreparedFlagDefinitions {
    /// Estimates the heap memory footprint of this struct in bytes.
    /// Used by moka's weight-based eviction to enforce cache capacity limits.
    pub fn estimated_size_bytes(&self) -> usize {
        let base = std::mem::size_of::<Self>();

        let flags_size: usize = self
            .flags
            .iter()
            .map(|f| {
                let struct_size = std::mem::size_of::<FeatureFlag>();
                let key_size = f.key.len();
                let name_size = f.name.as_ref().map_or(0, |n| n.len());
                let runtime_size = f.evaluation_runtime.as_ref().map_or(0, |r| r.len());
                let tags_size = f
                    .evaluation_tags
                    .as_ref()
                    .map_or(0, |tags| tags.iter().map(|t| t.len() + 24).sum());
                let bucketing_size = f.bucketing_identifier.as_ref().map_or(0, |b| b.len());

                struct_size
                    + key_size
                    + name_size
                    + runtime_size
                    + tags_size
                    + bucketing_size
                    + estimate_filters_size(&f.filters)
            })
            .sum();

        let metadata_size = self.evaluation_metadata.dependency_stages.len() * 24
            + self.evaluation_metadata.transitive_deps.len() * 48;

        let cohorts_size = self.cohorts.as_ref().map_or(0, |cohorts| {
            cohorts
                .iter()
                .map(|c| c.estimated_size_bytes())
                .sum::<usize>()
        });

        base + flags_size + metadata_size + cohorts_size
    }
}

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

    impl Mock for FeatureFlag {
        fn mock() -> Self {
            FeatureFlag {
                id: 1,
                team_id: 1,
                name: Some("Test Flag".to_string()),
                key: "test_flag".to_string(),
                filters: Mock::mock(),
                active: true,
                ensure_experience_continuity: Some(false),
                version: Some(1),
                evaluation_runtime: Some("all".to_string()),
                ..Default::default()
            }
        }
    }

    impl Mock for FeatureFlagRow {
        fn mock() -> Self {
            FeatureFlagRow {
                team_id: 1,
                name: Some("Test Flag".to_string()),
                key: "test_flag".to_string(),
                filters: serde_json::json!({
                    "groups": [{
                        "properties": [],
                        "rollout_percentage": 100
                    }]
                }),
                active: true,
                ensure_experience_continuity: Some(false),
                version: Some(1),
                evaluation_runtime: Some("all".to_string()),
                ..Default::default()
            }
        }
    }

    impl Mock for FlagFilters {
        fn mock() -> Self {
            FlagFilters {
                groups: vec![Mock::mock()],
                ..Default::default()
            }
        }
    }

    impl Mock for FlagPropertyGroup {
        fn mock() -> Self {
            FlagPropertyGroup {
                properties: Some(vec![]),
                rollout_percentage: Some(100.0),
                ..Default::default()
            }
        }
    }

    impl Mock for Holdout {
        fn mock() -> Self {
            Holdout {
                id: 1,
                exclusion_percentage: 10.0,
                ..Default::default()
            }
        }
    }

    impl Mock for MultivariateFlagVariant {
        fn mock() -> Self {
            MultivariateFlagVariant {
                key: "control".to_string(),
                name: Some("Control".to_string()),
                rollout_percentage: 100.0,
                ..Default::default()
            }
        }
    }

    impl MockFrom<FeatureFlag> for FeatureFlagRow {
        fn mock_from(flag: FeatureFlag) -> Self {
            let filters = crate::flags::config_format::serialize_filters(
                &flag.filters,
                serde_json::value::Serializer,
            )
            .expect("Mock: failed to serialize FeatureFlag.filters to JSON");
            FeatureFlagRow {
                id: flag.id,
                team_id: flag.team_id,
                name: flag.name,
                key: flag.key,
                filters,
                deleted: flag.deleted,
                active: flag.active,
                ensure_experience_continuity: flag.ensure_experience_continuity,
                version: flag.version,
                evaluation_runtime: flag.evaluation_runtime,
                evaluation_tags: flag.evaluation_tags,
                bucketing_identifier: flag.bucketing_identifier,
                ..Default::default()
            }
        }
    }

    impl MockFrom<PropertyFilter> for FlagFilters {
        fn mock_from(property: PropertyFilter) -> Self {
            MockFrom::mock_from(vec![property])
        }
    }

    impl MockFrom<Vec<PropertyFilter>> for FlagFilters {
        fn mock_from(properties: Vec<PropertyFilter>) -> Self {
            FlagFilters {
                groups: vec![FlagPropertyGroup {
                    properties: Some(properties),
                    rollout_percentage: Some(100.0),
                    ..Default::default()
                }],
                ..Default::default()
            }
        }
    }

    impl Mock for FeatureFlagList {
        fn mock() -> Self {
            FeatureFlagList {
                flags: PreparedFlags::seal(vec![<FeatureFlag as Mock>::mock()]),
                ..Default::default()
            }
        }
    }

    impl Mock for MultivariateFlagOptions {
        fn mock() -> Self {
            MultivariateFlagOptions {
                variants: vec![
                    MultivariateFlagVariant {
                        key: "control".to_string(),
                        name: Some("Control".to_string()),
                        rollout_percentage: 50.0,
                        ..Default::default()
                    },
                    MultivariateFlagVariant {
                        key: "test".to_string(),
                        name: Some("Test".to_string()),
                        rollout_percentage: 50.0,
                        ..Default::default()
                    },
                ],
                ..Default::default()
            }
        }
    }

    impl Mock for EvaluationMetadata {
        fn mock() -> Self {
            EvaluationMetadata {
                dependency_stages: vec![],
                flags_with_missing_deps: vec![],
                transitive_deps: HashMap::new(),
                ..Default::default()
            }
        }
    }

    impl MockFrom<Vec<FeatureFlag>> for FeatureFlagList {
        fn mock_from(flags: Vec<FeatureFlag>) -> Self {
            let evaluation_metadata = Arc::new(EvaluationMetadata::single_stage(&flags));
            FeatureFlagList {
                flags: PreparedFlags::seal(flags),
                evaluation_metadata,
                ..Default::default()
            }
        }
    }
}

#[cfg(test)]
mod unknown_key_passthrough_tests {
    //! Verify that unknown JSONB keys round-trip through deserialize/serialize
    //! unchanged via the `extra` field on every struct reachable from `FlagFilters`.
    //!
    //! Without this passthrough, the Python `verify_flags_cache` verifier reports
    //! spurious `FIELD_MISMATCH` against the Django JSONB passthrough because Rust
    //! drops keys its structs don't enumerate (frontend leaks like `description`
    //! and `sort_key`, runtime annotations like `cohort_name`, legacy keys like
    //! `holdout_groups`, and field typos). See
    //! plans/verify-flags-cache-loose-comparison.md.
    use super::*;

    fn round_trip<T: serde::de::DeserializeOwned + Serialize>(
        json: serde_json::Value,
    ) -> serde_json::Value {
        let value: T = serde_json::from_value(json).expect("should deserialize with flatten extra");
        serde_json::to_value(&value).expect("should serialize")
    }

    #[test]
    fn flag_property_group_preserves_unknown_keys() {
        let input = serde_json::json!({
            "properties": [],
            "rollout_percentage": 100,
            "variant": null,
            "description": "rollout to enterprise",
            "sort_key": "abc-123"
        });

        let output = round_trip::<FlagPropertyGroup>(input);

        assert_eq!(output["description"], "rollout to enterprise");
        assert_eq!(output["sort_key"], "abc-123");
    }

    #[test]
    fn flag_filters_preserves_holdout_groups_legacy_key() {
        let input = serde_json::json!({
            "groups": [{"properties": [], "rollout_percentage": 100}],
            "holdout_groups": [
                {"properties": [], "rollout_percentage": 5, "variant": "holdout-42"}
            ]
        });

        let output = round_trip::<FlagFilters>(input);

        let holdout_groups = output
            .get("holdout_groups")
            .expect("holdout_groups must survive the round-trip");
        assert!(holdout_groups.is_array());
        assert_eq!(holdout_groups[0]["variant"], "holdout-42");
    }

    #[test]
    fn property_filter_preserves_cohort_name_annotation() {
        let input = serde_json::json!({
            "key": "id",
            "value": 5,
            "type": "cohort",
            "operator": "in",
            "cohort_name": "QA users"
        });

        let output = round_trip::<PropertyFilter>(input);

        assert_eq!(output["cohort_name"], "QA users");
    }

    #[test]
    fn multivariate_flag_variant_preserves_unknown_keys() {
        let input = serde_json::json!({
            "key": "control",
            "name": "Control",
            "rollout_percentage": 50,
            "payload": {"color": "blue"},
            "split_percent": 25
        });

        let output = round_trip::<MultivariateFlagVariant>(input);

        assert_eq!(output["payload"], serde_json::json!({"color": "blue"}));
        assert_eq!(output["split_percent"], 25);
    }

    #[test]
    fn multivariate_flag_options_preserves_unknown_keys() {
        let input = serde_json::json!({
            "variants": [{"key": "control", "name": "Control", "rollout_percentage": 100}],
            "payload": {"control": "blue"}
        });

        let output = round_trip::<MultivariateFlagOptions>(input);

        assert_eq!(output["payload"], serde_json::json!({"control": "blue"}));
        assert_eq!(output["variants"][0]["key"], "control");
    }

    #[test]
    fn holdout_preserves_unknown_keys() {
        let input = serde_json::json!({
            "id": 42,
            "exclusion_percentage": 10,
            "split_percent": 5
        });

        let output = round_trip::<Holdout>(input);

        assert_eq!(output["split_percent"], 5);
    }

    #[test]
    fn aggregation_group_type_index_null_survives_flatten() {
        // Serde processes declared fields before `#[serde(flatten)]`, so the
        // explicit-null marker on the inner Option<Option<i32>> must round-trip
        // cleanly even with the new `extra` field in place. The matcher relies
        // on this distinction ("field present but null" = explicit person
        // aggregation; "field absent" = fall back to flag-level).
        let input = serde_json::json!({
            "properties": [],
            "rollout_percentage": 100,
            "aggregation_group_type_index": null
        });

        let group: FlagPropertyGroup = serde_json::from_value(input.clone())
            .expect("FlagPropertyGroup should deserialize cleanly");

        assert_eq!(
            group.aggregation_group_type_index,
            Some(None),
            "explicit null must deserialize as Some(None), not None"
        );
        // The flatten extra must not capture aggregation_group_type_index.
        assert!(!group.extra.contains_key("aggregation_group_type_index"));

        let output =
            serde_json::to_value(&group).expect("FlagPropertyGroup should serialize cleanly");

        assert!(
            output["aggregation_group_type_index"].is_null(),
            "explicit null must survive the round-trip, not be dropped or moved into extra"
        );
    }

    #[test]
    fn aggregation_group_type_index_absent_survives_flatten() {
        // The absent state must round-trip as absent, not be promoted to null.
        // `skip_serializing_if = "Option::is_none"` on the outer Option preserves
        // this distinction; without it, the matcher would treat legacy
        // (field-absent) flags as if they had explicit person aggregation.
        let input = serde_json::json!({
            "properties": [],
            "rollout_percentage": 100
        });

        let group: FlagPropertyGroup =
            serde_json::from_value(input).expect("FlagPropertyGroup should deserialize cleanly");

        assert_eq!(
            group.aggregation_group_type_index, None,
            "absent field must deserialize as None, not Some(None)"
        );

        let output =
            serde_json::to_value(&group).expect("FlagPropertyGroup should serialize cleanly");

        let map = output
            .as_object()
            .expect("serialized FlagPropertyGroup should be a JSON object");
        assert!(
            !map.contains_key("aggregation_group_type_index"),
            "absent field must survive the round-trip as absent, not be promoted to null"
        );
    }

    #[test]
    fn flag_filters_aggregation_group_type_index_absent_stays_absent() {
        // The filters-level field is plain `Option<i32>` (not the group-level
        // `Option<Option<i32>>`), so we cannot recover an explicit-null marker on
        // deserialize. But we can still avoid fabricating one on serialize:
        // `skip_serializing_if = "Option::is_none"` keeps the cache-write shape
        // aligned with the Django JSONB passthrough when the source has no key.
        // Without this, the Python verifier reports spurious FIELD_MISMATCH for
        // every team whose flag has the field absent in Postgres.
        let input = serde_json::json!({"groups": []});

        let filters: FlagFilters =
            serde_json::from_value(input).expect("FlagFilters should deserialize cleanly");

        assert_eq!(
            filters.aggregation_group_type_index, None,
            "absent field must deserialize as None"
        );

        let output = serde_json::to_value(&filters).expect("FlagFilters should serialize cleanly");

        let map = output
            .as_object()
            .expect("serialized FlagFilters should be a JSON object");
        assert!(
            !map.contains_key("aggregation_group_type_index"),
            "absent field must survive the round-trip as absent, not be promoted to null"
        );
    }

    #[test]
    fn flag_filters_aggregation_group_type_index_value_round_trips() {
        // Sanity check: real integer values still serialize, only `None` is skipped.
        let input = serde_json::json!({"groups": [], "aggregation_group_type_index": 2});

        let filters: FlagFilters =
            serde_json::from_value(input).expect("FlagFilters should deserialize cleanly");
        assert_eq!(filters.aggregation_group_type_index, Some(2));

        let output = serde_json::to_value(&filters).expect("FlagFilters should serialize cleanly");
        assert_eq!(output["aggregation_group_type_index"], 2);
    }
}

#[cfg(test)]
mod skip_serializing_if_tests {
    //! Verify the `skip_serializing_if = "Option::is_none"` sweep across the
    //! cache-write structs. For every swept `Option<T>` field:
    //! - Absent input round-trips as absent (no fabricated `null` key on serialize).
    //! - A real value round-trips unchanged (no happy-path regression).
    //!
    //! Fabricating `"field": null` on cache write diverges from the Django JSONB
    //! passthrough and shows up as drift against the Python `verify_flags_cache`
    //! verifier. See plans/rust-flag-models-skip-serializing-if-sweep.md.
    use super::*;

    /// Asserts a key is absent from a serialized JSON object.
    fn assert_absent(value: &serde_json::Value, key: &str) {
        let map = value
            .as_object()
            .expect("serialized value should be an object");
        assert!(
            !map.contains_key(key),
            "absent field `{key}` must not be promoted to a null key on serialize"
        );
    }

    #[test]
    fn flag_property_group_absent_options_stay_absent() {
        let group: FlagPropertyGroup = serde_json::from_value(serde_json::json!({})).unwrap();
        let output = serde_json::to_value(&group).unwrap();
        assert_absent(&output, "properties");
        assert_absent(&output, "rollout_percentage");
        assert_absent(&output, "variant");
    }

    #[test]
    fn flag_property_group_values_round_trip() {
        let input = serde_json::json!({
            "properties": [],
            "rollout_percentage": 50.0,
            "variant": "control"
        });
        let group: FlagPropertyGroup = serde_json::from_value(input).unwrap();
        let output = serde_json::to_value(&group).unwrap();
        assert!(output["properties"].is_array());
        assert_eq!(output["rollout_percentage"], 50.0);
        assert_eq!(output["variant"], "control");
    }

    #[test]
    fn flag_filters_absent_options_stay_absent() {
        let filters: FlagFilters = serde_json::from_value(serde_json::json!({})).unwrap();
        let output = serde_json::to_value(&filters).unwrap();
        assert_absent(&output, "multivariate");
        assert_absent(&output, "aggregation_group_type_index");
        assert_absent(&output, "payloads");
        assert_absent(&output, "feature_enrollment");
        assert_absent(&output, "holdout");
        assert_absent(&output, "early_exit");
    }

    #[test]
    fn flag_filters_values_round_trip() {
        let input = serde_json::json!({
            "groups": [],
            "multivariate": {"variants": []},
            "aggregation_group_type_index": 2,
            "payloads": {"true": "p"},
            "feature_enrollment": true,
            "holdout": {"id": 42, "exclusion_percentage": 10.0},
            "early_exit": true
        });
        let filters: FlagFilters = serde_json::from_value(input).unwrap();
        let output = serde_json::to_value(&filters).unwrap();
        assert!(output["multivariate"].is_object());
        assert_eq!(output["aggregation_group_type_index"], 2);
        assert_eq!(output["payloads"]["true"], "p");
        assert_eq!(output["feature_enrollment"], true);
        assert_eq!(output["holdout"]["id"], 42);
        assert_eq!(output["early_exit"], true);
    }

    #[test]
    fn feature_flag_absent_options_stay_absent() {
        let input = serde_json::json!({
            "id": 1,
            "team_id": 1,
            "key": "k",
            "filters": {"groups": []}
        });
        let flag: FeatureFlag = serde_json::from_value(input).unwrap();
        let output = serde_json::to_value(&flag).unwrap();
        assert_absent(&output, "name");
        assert_absent(&output, "ensure_experience_continuity");
        assert_absent(&output, "version");
        assert_absent(&output, "evaluation_runtime");
        // `evaluation_tags` serializes under the `evaluation_contexts` JSON key.
        assert_absent(&output, "evaluation_contexts");
        assert_absent(&output, "evaluation_tags");
        assert_absent(&output, "bucketing_identifier");
    }

    #[test]
    fn feature_flag_values_round_trip() {
        let input = serde_json::json!({
            "id": 1,
            "team_id": 1,
            "key": "k",
            "filters": {"groups": []},
            "name": "My Flag",
            "ensure_experience_continuity": true,
            "version": 3,
            "evaluation_runtime": "all",
            "evaluation_contexts": ["docs"],
            "bucketing_identifier": "device_id"
        });
        let flag: FeatureFlag = serde_json::from_value(input).unwrap();
        let output = serde_json::to_value(&flag).unwrap();
        assert_eq!(output["name"], "My Flag");
        assert_eq!(output["ensure_experience_continuity"], true);
        assert_eq!(output["version"], 3);
        assert_eq!(output["evaluation_runtime"], "all");
        assert_eq!(output["evaluation_contexts"], serde_json::json!(["docs"]));
        assert_eq!(output["bucketing_identifier"], "device_id");
    }

    #[test]
    fn hypercache_wrapper_absent_cohorts_stays_absent() {
        let input = serde_json::json!({
            "flags": [],
            "evaluation_metadata": {
                "dependency_stages": [],
                "flags_with_missing_deps": [],
                "transitive_deps": {}
            }
        });
        let wrapper: HypercacheFlagsWrapper = serde_json::from_value(input).unwrap();
        let output = serde_json::to_value(&wrapper).unwrap();
        assert_absent(&output, "cohorts");
    }

    #[test]
    fn hypercache_wrapper_cohorts_round_trip() {
        let input = serde_json::json!({
            "flags": [],
            "evaluation_metadata": {
                "dependency_stages": [],
                "flags_with_missing_deps": [],
                "transitive_deps": {}
            },
            "cohorts": []
        });
        let wrapper: HypercacheFlagsWrapper = serde_json::from_value(input).unwrap();
        let output = serde_json::to_value(&wrapper).unwrap();
        assert!(output["cohorts"].is_array());
    }
}