: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
//! The gRPC service surface. This module is dispatch-only: each RPC family
//! lives in its own submodule (get_or_create and the merge entrance today;
//! resolution, claims, and splits will follow the same pattern). [`merge`]
//! carries MergePersons' identity work — validation, resolution,
//! classification, inline settlement.
pub mod error;
pub mod get_or_create;
pub mod merge;
pub mod validation;
use std::sync::Arc;
use tonic::{Request, Response, Status};
use personhog_proto::personhog::identity::v1::person_hog_identity_server::PersonHogIdentity;
use personhog_proto::personhog::identity::v1::{
GetDistinctIdsForPersonsRequest, GetDistinctIdsForPersonsResponse,
GetOrCreatePersonByDistinctIdRequest, GetOrCreatePersonByDistinctIdResponse,
GetOrCreatePersonResult, GetOrCreatePersonsByDistinctIdsRequest,
GetOrCreatePersonsByDistinctIdsResponse, GetPersonByDistinctIdResult,
GetPersonsByDistinctIdsRequest, GetPersonsByDistinctIdsResponse, MergePersonsRequest,
MergePersonsResponse,
};
use personhog_proto::personhog::types::v1::{
DistinctIdWithVersion, Person as ProtoPerson, PersonDistinctIds,
};
use crate::leader::PropertyWriter;
use crate::service::merge::MergeEntrance;
use crate::service::validation::{
validate_batch_size, validate_entry, validate_team_id, RequestLimits,
};
use crate::storage::IdentityStorage;
const RESOLVE_KEYS_PER_CALL: &str = "personhog_identity_resolve_keys_per_call";
pub struct PersonHogIdentityService {
pub(crate) storage: Arc<dyn IdentityStorage>,
pub(crate) property_writer: Arc<dyn PropertyWriter>,
pub(crate) limits: RequestLimits,
pub(crate) property_write_concurrency: usize,
merge: MergeEntrance,
}
impl PersonHogIdentityService {
pub fn new(
storage: Arc<dyn IdentityStorage>,
property_writer: Arc<dyn PropertyWriter>,
limits: RequestLimits,
merge: MergeEntrance,
property_write_concurrency: usize,
) -> Self {
Self {
storage,
property_writer,
limits,
// Clamped to 1: a zero-width buffered stream never polls.
property_write_concurrency: property_write_concurrency.max(1),
merge,
}
}
}
#[tonic::async_trait]
impl PersonHogIdentity for PersonHogIdentityService {
async fn get_or_create_person_by_distinct_id(
&self,
request: Request<GetOrCreatePersonByDistinctIdRequest>,
) -> Result<Response<GetOrCreatePersonByDistinctIdResponse>, Status> {
let entry = request
.into_inner()
.entry
.ok_or_else(|| Status::invalid_argument("entry is required"))?;
validate_entry(&self.limits, &entry)?;
let mut results = self.get_or_create_entries(vec![entry]).await?;
let (person, created) = results.pop().expect("one entry yields one result")?;
Ok(Response::new(GetOrCreatePersonByDistinctIdResponse {
person: Some(person),
created,
}))
}
async fn get_or_create_persons_by_distinct_ids(
&self,
request: Request<GetOrCreatePersonsByDistinctIdsRequest>,
) -> Result<Response<GetOrCreatePersonsByDistinctIdsResponse>, Status> {
let entries = request.into_inner().entries;
validate_batch_size(&self.limits, entries.len())?;
let identifiers: Vec<(i64, String)> = entries
.iter()
.map(|entry| (entry.team_id, entry.distinct_id.clone()))
.collect();
let outcomes = self.get_or_create_entries(entries).await?;
let results = identifiers
.into_iter()
.zip(outcomes)
.map(|((team_id, distinct_id), outcome)| match outcome {
Ok((person, created)) => GetOrCreatePersonResult {
team_id,
distinct_id,
person: Some(person),
created,
error: None,
},
Err(status) => GetOrCreatePersonResult {
team_id,
distinct_id,
person: None,
created: false,
error: Some(format!("{:?}: {}", status.code(), status.message())),
},
})
.collect();
Ok(Response::new(GetOrCreatePersonsByDistinctIdsResponse {
results,
}))
}
async fn get_persons_by_distinct_ids(
&self,
request: Request<GetPersonsByDistinctIdsRequest>,
) -> Result<Response<GetPersonsByDistinctIdsResponse>, Status> {
let request = request.into_inner();
let keys = request.keys;
common_metrics::histogram(RESOLVE_KEYS_PER_CALL, &[], keys.len() as f64);
validate_batch_size(&self.limits, keys.len())?;
for key in &keys {
validate_team_id(key.team_id)?;
}
let identifiers: Vec<(i64, String)> = keys
.iter()
.map(|key| (key.team_id, key.distinct_id.clone()))
.collect();
let resolved: std::collections::HashMap<(i64, String), ProtoPerson> = if request.ids_only {
self.storage
.resolve_person_ids(&identifiers)
.await
.map_err(|e| crate::service::error::log_and_convert_error(e, "resolve_person_ids"))?
.into_iter()
.map(|((team_id, distinct_id), id)| {
let person = ProtoPerson {
id,
team_id,
..Default::default()
};
((team_id, distinct_id), person)
})
.collect()
} else {
self.storage
.resolve_distinct_ids(&identifiers)
.await
.map_err(|e| {
crate::service::error::log_and_convert_error(e, "resolve_distinct_ids")
})?
.into_iter()
.map(|(key, person)| (key, person.into()))
.collect()
};
let results = identifiers
.into_iter()
.map(|(team_id, distinct_id)| {
// Look up rather than consume: a key repeated in one
// request must resolve on every occurrence.
let person = resolved.get(&(team_id, distinct_id.clone())).cloned();
GetPersonByDistinctIdResult {
team_id,
distinct_id,
person,
}
})
.collect();
Ok(Response::new(GetPersonsByDistinctIdsResponse { results }))
}
async fn get_distinct_ids_for_persons(
&self,
request: Request<GetDistinctIdsForPersonsRequest>,
) -> Result<Response<GetDistinctIdsForPersonsResponse>, Status> {
let req = request.into_inner();
validate_team_id(req.team_id)?;
validate_batch_size(&self.limits, req.person_ids.len())?;
// Dedupe: the response groups by person, so a repeated id adds
// nothing — but the limited query's UNNEST + LATERAL runs per
// occurrence, and duplicated rows would merge into one group
// that exceeds the advertised per-person limit.
let mut person_ids = req.person_ids;
person_ids.sort_unstable();
person_ids.dedup();
let mappings = self
.storage
.get_distinct_ids_for_persons(req.team_id, &person_ids, req.limit_per_person)
.await
.map_err(|e| {
crate::service::error::log_and_convert_error(e, "get_distinct_ids_for_persons")
})?;
let mut by_person: std::collections::HashMap<i64, Vec<DistinctIdWithVersion>> =
std::collections::HashMap::new();
for mapping in mappings {
by_person
.entry(mapping.person_id)
.or_default()
.push(DistinctIdWithVersion {
distinct_id: mapping.distinct_id,
version: mapping.version,
id: None,
});
}
let person_distinct_ids = by_person
.into_iter()
.map(|(person_id, distinct_ids)| PersonDistinctIds {
person_id,
distinct_ids,
})
.collect();
Ok(Response::new(GetDistinctIdsForPersonsResponse {
person_distinct_ids,
}))
}
async fn merge_persons(
&self,
request: Request<MergePersonsRequest>,
) -> Result<Response<MergePersonsResponse>, Status> {
Ok(Response::new(
self.merge.handle(request.into_inner()).await?,
))
}
}