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.

14.2 KB
Raw Blame
use std::hash::Hash;
use std::sync::Arc;

use foyer::{Cache, CacheBuilder, Event, EventListener};
use metrics::counter;
use personhog_proto::personhog::types::v1::Person;

use super::codec::PropertiesCodec;
use super::stored::StoredPerson;

/// Key for person cache lookups: (team_id, person_id).
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct PersonCacheKey {
    pub team_id: i64,
    pub person_id: i64,
}

/// Cached person state, with properties held in serialized JSON form.
///
/// Serialized rather than parsed for memory accounting: the cache weighs
/// entries by byte length, and holding the bytes makes the charged
/// weight the real allocation. Readers that need the map parse on
/// access via [`CachedPerson::parse_properties`]; readers that need the
/// wire form (proto responses, changelog records) take the bytes as
/// they are.
#[derive(Debug, Clone)]
pub struct CachedPerson {
    pub id: i64,
    pub uuid: String,
    pub team_id: i64,
    /// Properties as serialized JSON, validated at construction.
    pub properties: Vec<u8>,
    pub created_at: i64,
    pub version: i64,
    pub is_identified: bool,
    /// True when this entry is a recovered death document: the person was
    /// destroyed and this version closes its stream. Cached while its
    /// dirty mark stands (the writer may not have tombstoned the PG row
    /// yet); the prune-time settle drops it, and PG answers after.
    pub is_deleted: bool,
    /// Epoch milliseconds of the person's last observed activity, when
    /// known (matching `created_at`'s unit). Max-merged on update — the
    /// value only ever advances — and deliberately not a change by itself.
    pub last_seen_at: Option<i64>,
    // TODO: Add properties_last_updated_at and properties_last_operation
}

impl CachedPerson {
    /// Parse the stored properties into a JSON value. Construction
    /// validates the bytes, so a failure here means the cache holds a
    /// document no constructor produced.
    pub fn parse_properties(&self) -> serde_json::Result<serde_json::Value> {
        if self.properties.is_empty() {
            return Ok(serde_json::Value::Object(serde_json::Map::new()));
        }
        serde_json::from_slice(&self.properties)
    }
}

/// Decodes a changelog `Person` record into cache form. The only fallible
/// step is validating the properties JSON — validated without building
/// the tree, and stored as the record's own bytes.
impl TryFrom<Person> for CachedPerson {
    type Error = serde_json::Error;

    fn try_from(person: Person) -> Result<Self, Self::Error> {
        if !person.properties.is_empty() {
            serde_json::from_slice::<serde::de::IgnoredAny>(&person.properties)?;
        }
        Ok(Self {
            id: person.id,
            uuid: person.uuid,
            team_id: person.team_id,
            properties: person.properties,
            created_at: person.created_at,
            version: person.version,
            is_identified: person.is_identified,
            is_deleted: person.is_deleted,
            last_seen_at: person.last_seen_at,
        })
    }
}

#[derive(Debug, Clone, Copy)]
pub struct CachedVersion {
    pub version: i64,
    pub is_deleted: bool,
}

/// Counts entries leaving the cache, by reason. Evictions are the
/// operationally interesting ones: evicting a recently written person is
/// exactly what the dirty index + changelog recovery exist to make safe,
/// and a sustained eviction rate is the early signal that the configured
/// capacity is undersized for the working set.
struct CacheEventMetrics;

impl EventListener for CacheEventMetrics {
    type Key = PersonCacheKey;
    type Value = StoredPerson;

    fn on_leave(&self, reason: Event, _key: &Self::Key, _value: &Self::Value) {
        let reason = match reason {
            Event::Evict => "evict",
            Event::Remove => "remove",
            Event::Clear => "clear",
            // Every successful update overwrites its cache entry, so
            // Replace fires once per write — pure hot-path noise that
            // would drown the signal this metric exists for.
            Event::Replace => return,
        };
        counter!("personhog_leader_cache_entries_left_total", "reason" => reason).increment(1);
    }
}

/// In-memory person cache backed by Foyer.
///
/// Foyer evicts freely under capacity pressure; that is safe because the
/// service's miss path never trusts a stale source. Persons in the dirty
/// index (acked but not yet applied to PG by the writer) recover from
/// their changelog record; everyone else's PG fallback row is current.
/// A hybrid (disk+memory) tier remains a possible capacity optimization
/// by switching to `HybridCache`.
pub struct PersonCache {
    inner: Cache<PersonCacheKey, StoredPerson>,
    codec: Arc<PropertiesCodec>,
}

impl PersonCache {
    /// `capacity_bytes` bounds the cache by the entries' byte weights
    /// (see `StoredPerson::weight`), not their count. Person documents
    /// vary by orders of magnitude and grow in place across writes, so
    /// an entry-count bound cannot bound memory.
    pub(super) fn new(capacity_bytes: usize, codec: Arc<PropertiesCodec>) -> Self {
        let cache = CacheBuilder::new(capacity_bytes)
            .with_weighter(|_key: &PersonCacheKey, value: &StoredPerson| value.weight())
            .with_event_listener(Arc::new(CacheEventMetrics))
            .build();
        Self {
            inner: cache,
            codec,
        }
    }

    pub fn get(&self, key: &PersonCacheKey) -> Option<CachedPerson> {
        let person = self.lookup(key);
        match person {
            Some(_) => counter!("personhog_leader_cache_hits_total").increment(1),
            None => counter!("personhog_leader_cache_misses_total").increment(1),
        }
        person
    }

    /// A read for bookkeeping passes such as the death-document settle.
    /// It skips the hit/miss counters and does not copy or decompress the
    /// properties. It still promotes the entry's recency, which is
    /// harmless for those passes.
    pub fn peek(&self, key: &PersonCacheKey) -> Option<CachedVersion> {
        self.inner
            .get(key)
            .map(|entry| entry.value().cached_version())
    }

    /// An entry that fails to decode is dropped and reads as absent.
    fn lookup(&self, key: &PersonCacheKey) -> Option<CachedPerson> {
        let entry = self.inner.get(key)?;
        match entry.value().to_cached(&self.codec) {
            Ok(person) => Some(person),
            Err(reason) => {
                // Safe to drop: the miss path recovers from the changelog or Postgres.
                counter!("personhog_leader_cache_decode_failures_total").increment(1);
                tracing::error!(
                    team_id = key.team_id,
                    person_id = key.person_id,
                    reason,
                    "dropping cache entry whose properties failed to decode"
                );
                self.inner.remove(key);
                None
            }
        }
    }

    pub fn put(&self, key: PersonCacheKey, person: CachedPerson) {
        let stored = StoredPerson::new(person, &self.codec);
        let properties = stored.properties();
        counter!("personhog_leader_cache_properties_put_bytes_total", "form" => "raw")
            .increment(properties.raw_len() as u64);
        counter!("personhog_leader_cache_properties_put_bytes_total", "form" => "stored")
            .increment(properties.stored_len() as u64);
        self.inner.insert(key, stored);
    }

    pub fn remove(&self, key: &PersonCacheKey) {
        self.inner.remove(key);
    }

    /// Resident weight in bytes: the sum of entries' weights as foyer
    /// accounts it against the capacity.
    pub fn usage_bytes(&self) -> usize {
        self.inner.usage()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::cache::codec::tests::{person_properties, trained_codec};

    /// Proto3 encodes an absent bytes field as empty, and every leader
    /// write path serializes at least `{}` — so empty properties can
    /// only arrive from records that predate this store, and rejecting
    /// them would fail the warm over a document that is simply
    /// property-less. This pins the lenient reading in both directions:
    /// decode accepts, and parse yields the empty map.
    #[test]
    fn empty_properties_bytes_read_as_the_empty_map() {
        let record = Person {
            uuid: "00000000-0000-0000-0000-000000000001".to_string(),
            properties: Vec::new(),
            ..Default::default()
        };
        let cached = CachedPerson::try_from(record).expect("empty properties decode");
        assert!(cached.properties.is_empty());
        assert_eq!(
            cached.parse_properties().unwrap(),
            serde_json::Value::Object(serde_json::Map::new())
        );
    }

    fn test_person() -> CachedPerson {
        CachedPerson {
            id: 1,
            uuid: "abc-123".to_string(),
            team_id: 42,
            properties: serde_json::to_vec(&serde_json::json!({"email": "[email protected]"}))
                .unwrap(),
            created_at: 1700000000,
            version: 1,
            is_identified: false,
            is_deleted: false,
            last_seen_at: None,
        }
    }

    /// An entry-count capacity cannot bound memory: documents grow in
    /// place and vary by orders of magnitude. This pins the byte
    /// denomination — sustained inserts whose combined weight far
    /// exceeds the byte capacity must evict most, but not all, of them.
    /// Foyer splits capacity across eight shards and evicts lazily on
    /// later inserts to the same shard, so entries are sized well under
    /// the per-shard budget (admission must succeed for eviction to be
    /// what's under test) and the bound is asserted with per-shard
    /// slack rather than exactly.
    #[test]
    fn byte_weights_evict_under_capacity_pressure() {
        // 64 KiB capacity → ~8 KiB per shard; ~2 KiB entries fit a
        // shard several times over, and 128 of them (~224 KiB) overrun
        // the total capacity by more than 3x.
        let cache = PersonCache::new(64 * 1024, Arc::new(PropertiesCodec::disabled()));
        let blob = "x".repeat(1536);
        for person_id in 0..128 {
            let mut person = test_person();
            person.id = person_id;
            person.properties =
                serde_json::to_vec(&serde_json::json!({ "blob": blob.clone() })).unwrap();
            cache.put(
                PersonCacheKey {
                    team_id: 42,
                    person_id,
                },
                person,
            );
        }
        let resident = (0..128)
            .filter(|id| {
                cache
                    .get(&PersonCacheKey {
                        team_id: 42,
                        person_id: *id,
                    })
                    .is_some()
            })
            .count();
        assert!(
            resident > 0,
            "every entry fits its shard several times over, so admission must retain some"
        );
        assert!(
            resident <= 64,
            "224KiB of inserts against a 64KiB byte capacity retained {resident} \
             of 128 entries — byte weights are not driving eviction"
        );
    }

    #[test]
    fn cache_put_get_roundtrip() {
        let cache = PersonCache::new(1 << 20, Arc::new(PropertiesCodec::disabled()));
        let key = PersonCacheKey {
            team_id: 42,
            person_id: 1,
        };

        assert!(cache.get(&key).is_none());

        cache.put(key.clone(), test_person());

        let cached = cache.get(&key).unwrap();
        assert_eq!(cached.id, 1);
        assert_eq!(cached.uuid, "abc-123");
        assert_eq!(cached.team_id, 42);
        assert_eq!(
            cached.parse_properties().unwrap()["email"],
            "[email protected]"
        );
    }

    #[test]
    fn compressed_entries_read_back_whole_and_weigh_less() {
        let key = PersonCacheKey {
            team_id: 42,
            person_id: 1,
        };
        let mut person = test_person();
        person.properties = person_properties(10_001);
        let raw = PersonCache::new(1 << 20, Arc::new(PropertiesCodec::disabled()));
        let compressed = PersonCache::new(1 << 20, Arc::new(trained_codec()));

        for cache in [&raw, &compressed] {
            cache.put(key.clone(), person.clone());
            assert_eq!(cache.get(&key).unwrap().properties, person.properties);
        }
        assert!(compressed.usage_bytes() < raw.usage_bytes());
    }

    #[test]
    fn an_entry_that_fails_to_decode_reads_as_a_miss_and_leaves_the_cache() {
        let cache = PersonCache::new(1 << 20, Arc::new(PropertiesCodec::disabled()));
        let key = PersonCacheKey {
            team_id: 42,
            person_id: 1,
        };
        let mut person = test_person();
        person.properties = person_properties(10_001);
        // A codec without a dictionary cannot decode a compressed frame, which stands in for a corrupt entry.
        cache
            .inner
            .insert(key.clone(), StoredPerson::new(person, &trained_codec()));

        assert!(cache.get(&key).is_none());
        assert!(cache.peek(&key).is_none());
    }

    #[test]
    fn cache_remove() {
        let cache = PersonCache::new(1 << 20, Arc::new(PropertiesCodec::disabled()));
        let key = PersonCacheKey {
            team_id: 42,
            person_id: 1,
        };

        cache.put(key.clone(), test_person());
        assert!(cache.get(&key).is_some());

        cache.remove(&key);
        assert!(cache.get(&key).is_none());
    }

    #[test]
    fn cache_overwrite() {
        let cache = PersonCache::new(1 << 20, Arc::new(PropertiesCodec::disabled()));
        let key = PersonCacheKey {
            team_id: 42,
            person_id: 1,
        };

        cache.put(key.clone(), test_person());

        let mut updated = test_person();
        updated.version = 2;
        updated.properties =
            serde_json::to_vec(&serde_json::json!({"email": "[email protected]"})).unwrap();
        cache.put(key.clone(), updated);

        let cached = cache.get(&key).unwrap();
        assert_eq!(cached.version, 2);
        assert_eq!(
            cached.parse_properties().unwrap()["email"],
            "[email protected]"
        );
    }
}