: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, 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")
);
}
}