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.

6.1 KB
Raw Blame
use std::time::Instant;

use metrics::{counter, histogram};
use personhog_common::properties::rewrite_out_of_range_numbers;
use sqlx::pool::PoolConnection;
use sqlx::postgres::PgPool;
use sqlx::{Postgres, Row};

use crate::cache::{CachedPerson, PersonCacheKey};

/// A configured PG fallback: the pool and the table it reads. The table
/// must be the one the writer maintains (see FALLBACK_TABLE in
/// config.rs for the pairing rule), so a fallback cannot be constructed
/// without deciding it.
#[derive(Clone)]
pub struct PgFallback {
    pub pool: PgPool,
    pub table: String,
    pub lifecycle: LifecycleTables,
}

/// The saga tables the fence checks read. Must be the pair identity
/// writes its marks to, or every committed release fails closed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LifecycleTables {
    pub op: String,
    pub op_person: String,
}

impl LifecycleTables {
    pub fn new(op: &str, op_person: &str) -> Self {
        Self {
            op: op.to_string(),
            op_person: op_person.to_string(),
        }
    }
}

/// Take a fallback-pool connection, recording the wait: the pool is small
/// and shared by cache-miss loads and the sagas' mark checks.
pub async fn acquire_timed(
    pool: &PgPool,
    caller: &'static str,
) -> Result<PoolConnection<Postgres>, sqlx::Error> {
    let start = Instant::now();
    let conn = pool.acquire().await;
    histogram!("personhog_leader_fallback_pool_acquire_ms", "caller" => caller)
        .record(start.elapsed().as_secs_f64() * 1000.0);
    conn
}

/// Validate a configured table identifier before it is interpolated into
/// SQL (identifiers cannot be bound as parameters).
pub fn validate_table_name(table: &str) -> Result<(), String> {
    if table.is_empty() || !table.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') {
        return Err(format!("invalid fallback table name: {table:?}"));
    }
    Ok(())
}

/// Reads a person from the configured fallback table — the table the
/// writer maintains. Used as a fallback when the leader's cache doesn't
/// have the person.
pub async fn load_person_from_pg(
    pool: &PgPool,
    table: &str,
    key: &PersonCacheKey,
) -> Result<Option<CachedPerson>, sqlx::Error> {
    let start = Instant::now();
    let mut conn = acquire_timed(pool, "load_person").await?;

    let team_id_i32 = i32::try_from(key.team_id)
        .map_err(|_| sqlx::Error::Protocol(format!("team_id {} exceeds i32 range", key.team_id)))?;

    // properties comes back as text and is parsed here rather than through
    // sqlx's jsonb decode: rows written by other services can hold numerics
    // whose PG-expanded rendering serde_json rejects, and the leniency
    // lives in our parse step (see below). The cost is identical — sqlx's
    // jsonb decode parses the same text under the hood.
    // A tombstoned person must not be re-served on a cache miss; not-found
    // is the truthful answer for a deleted person.
    let row = sqlx::query(&format!(
        "SELECT id, team_id, uuid::text, properties::text AS properties, created_at, version, \
         is_identified, last_seen_at
         FROM {table}
         WHERE team_id = $1 AND id = $2 AND is_deleted = false",
    ))
    .bind(team_id_i32)
    .bind(key.person_id)
    .fetch_optional(&mut *conn)
    .await?;
    // The row is owned; parsing its properties must not hold the pool slot.
    drop(conn);

    histogram!("personhog_leader_pg_fallback_duration_ms")
        .record(start.elapsed().as_secs_f64() * 1000.0);

    let Some(row) = row else {
        counter!("personhog_leader_pg_fallback_total", "outcome" => "not_found").increment(1);
        return Ok(None);
    };

    let id: i64 = row.get("id");
    let team_id: i32 = row.get("team_id");
    let uuid: String = row.get("uuid");
    // Borrowed from the row buffer — no copy; parse cost matches what
    // sqlx's own jsonb decode would spend on the same bytes.
    let properties_text: &str = row.get("properties");
    let created_at: chrono::DateTime<chrono::Utc> = row.get("created_at");
    let version: Option<i64> = row.get("version");
    let is_identified: bool = row.get("is_identified");
    let last_seen_at: Option<chrono::DateTime<chrono::Utc>> = row.get("last_seen_at");

    let properties: serde_json::Value = match serde_json::from_str(properties_text) {
        Ok(value) => value,
        // Out-of-range numerics from other writers: rewrite to what
        // JSON.parse would read (rounding, clamping beyond f64) instead
        // of leaving the person permanently unloadable. Admission's
        // sanitizer persists the healed form on the next write-through.
        Err(strict_err) => {
            match serde_json::from_str(&rewrite_out_of_range_numbers(properties_text)) {
                Ok(value) => {
                    counter!("personhog_leader_pg_properties_rewritten_total").increment(1);
                    tracing::warn!(
                        team_id,
                        person_id = id,
                        "rewrote out-of-range numerics in stored person properties"
                    );
                    value
                }
                Err(rewritten_err) => {
                    return Err(sqlx::Error::Protocol(format!(
                        "person properties unparseable (team_id={team_id}, person_id={id}): \
                     {strict_err}; after numeric rewrite: {rewritten_err}"
                    )));
                }
            }
        }
    };

    counter!("personhog_leader_pg_fallback_total", "outcome" => "found").increment(1);

    let properties_bytes = serde_json::to_vec(&properties).map_err(|e| {
        sqlx::Error::Protocol(format!(
            "person properties reserialize failed (team_id={team_id}, person_id={id}): {e}"
        ))
    })?;
    Ok(Some(CachedPerson {
        id,
        uuid,
        team_id: team_id as i64,
        properties: properties_bytes,
        created_at: created_at.timestamp_millis(),
        version: version.unwrap_or(0),
        is_identified,
        // The query filters is_deleted = false; a tombstoned row is
        // answered as not-found above, never loaded.
        is_deleted: false,
        last_seen_at: last_seen_at.map(|t| t.timestamp_millis()),
    }))
}