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.

13.5 KB
Raw Blame
import { create } from '@bufbuild/protobuf'
import { Client, Code, ConnectError } from '@connectrpc/connect'

import { PersonHogService } from '~/common/generated/personhog/personhog/service/v1/service_pb'
import { TeamDistinctIdSchema } from '~/common/generated/personhog/personhog/types/v1/common_pb'
import {
    GetDistinctIdsForPersonsRequestSchema,
    GetPersonRequestSchema,
    GetPersonsByDistinctIdsRequestSchema,
    GetPersonsByUuidsRequestSchema,
    UpdatePersonPropertiesRequestSchema,
} from '~/common/generated/personhog/personhog/types/v1/person_pb'
import type { Person as ProtoPerson } from '~/common/generated/personhog/personhog/types/v1/person_pb'
import { InternalPersonWithDistinctId } from '~/common/persons/repositories/person-repository'
import { NoRowsUpdatedError } from '~/common/utils/utils'
import { Properties } from '~/plugin-scaffold'
import { InternalPerson } from '~/types'

import { epochMsToDateTime, eventualReadOptions, parseJsonBytes, strongReadOptions } from './client'
import type { HandledVerdict } from './grpc-retry'

const textEncoder = new TextEncoder()

export function encodeJsonBytes(value: object): Uint8Array {
    return Object.keys(value).length === 0 ? new Uint8Array(0) : textEncoder.encode(JSON.stringify(value))
}

/** Set by the leader on any write refused because a lifecycle op holds the person. */
const FENCED_METADATA_KEY = 'x-person-fenced'
/** Carries the holding operation's id on that refusal. */
const FENCED_OP_ID_METADATA_KEY = 'x-person-fenced-op-id'
/**
 * The leader rejected an update at the person-properties size ceiling;
 * callers re-wrap it into their own error vocabulary.
 */
export class PersonhogPropertiesSizeError extends Error {
    constructor(
        message: string,
        public readonly teamId: number,
        public readonly personId: string
    ) {
        super(message)
        this.name = 'PersonhogPropertiesSizeError'
    }
}

/**
 * The leader knows no such person: deleted, or merged into another. The
 * persons store redirects the ops to the survivor, so the retry layer files
 * this under handled verdicts rather than terminal errors. Still a
 * NoRowsUpdatedError for the callers that branch on that.
 */
export class PersonhogPersonNotFoundError extends NoRowsUpdatedError implements HandledVerdict {
    readonly handledVerdict = 'person_not_found'

    constructor(
        message: string,
        public readonly personId: string
    ) {
        super(message)
        this.name = 'PersonhogPersonNotFoundError'
    }
}

/**
 * The leader refused a write because a lifecycle operation holds the
 * person; the holder's op id and creator travel for attribution.
 */
export class PersonhogFencedError extends Error {
    constructor(
        message: string,
        public readonly personId: string,
        public readonly fencingOpId: string | undefined
    ) {
        super(message)
        this.name = 'PersonhogFencedError'
    }
}

/** A folded person-property update, resolved by the leader under the per-person lock. */
export interface FoldedPersonUpdate {
    teamId: number
    /** InternalPerson.id — the bigint row id as a string. */
    personId: string
    /** Representative event name; must not be one the leader's denylist filters out. */
    eventName: string
    setProperties: Properties
    /** Unresolved: the leader applies these only where the key is absent in authoritative state. */
    setOnceProperties: Properties
    unsetProperties: string[]
    /** OR-merged server-side; send true only — false and absence are equivalent no-ops. */
    isIdentified?: boolean
    /** Epoch milliseconds; max-merged server-side. */
    lastSeenAtMs?: number
    /** The event's force flag; the leader writes filtered-only changes under it. */
    forceUpdate?: boolean
}

export function protoPersonToDomain(proto: ProtoPerson): InternalPerson {
    return {
        id: String(proto.id),
        uuid: proto.uuid,
        team_id: Number(proto.teamId),
        properties: parseJsonBytes(proto.properties) ?? {},
        properties_last_updated_at: parseJsonBytes(proto.propertiesLastUpdatedAt) ?? {},
        properties_last_operation: parseJsonBytes(proto.propertiesLastOperation) ?? null,
        created_at: epochMsToDateTime(proto.createdAt),
        version: Number(proto.version),
        is_identified: proto.isIdentified,
        is_user_id: proto.isUserId != null ? (proto.isUserId ? 1 : 0) : null,
        last_seen_at: proto.lastSeenAt != null ? epochMsToDateTime(proto.lastSeenAt) : null,
    }
}

/** An identity answer: no properties, because the partition leader owns them. */
export type PersonIdentity = Omit<
    InternalPerson,
    'properties' | 'properties_last_updated_at' | 'properties_last_operation'
>

export function protoPersonToIdentity(proto: ProtoPerson): PersonIdentity {
    return {
        id: String(proto.id),
        uuid: proto.uuid,
        team_id: Number(proto.teamId),
        created_at: epochMsToDateTime(proto.createdAt),
        version: Number(proto.version),
        is_identified: proto.isIdentified,
        is_user_id: proto.isUserId != null ? (proto.isUserId ? 1 : 0) : null,
        last_seen_at: proto.lastSeenAt != null ? epochMsToDateTime(proto.lastSeenAt) : null,
    }
}

const PERSONHOG_BATCH_SIZE = 250

export class PersonHogPersonOperations {
    constructor(private client: Client<typeof PersonHogService>) {}

    async fetchPersonsByDistinctIds(
        teamPersons: { teamId: number; distinctId: string }[],
        callerTag?: string
    ): Promise<InternalPersonWithDistinctId[]> {
        if (teamPersons.length === 0) {
            return []
        }

        const results: InternalPersonWithDistinctId[] = []
        for (let i = 0; i < teamPersons.length; i += PERSONHOG_BATCH_SIZE) {
            const batch = teamPersons.slice(i, i + PERSONHOG_BATCH_SIZE)
            const response = await this.client.getPersonsByDistinctIds(
                create(GetPersonsByDistinctIdsRequestSchema, {
                    teamDistinctIds: batch.map(({ teamId, distinctId }) =>
                        create(TeamDistinctIdSchema, {
                            teamId: BigInt(teamId),
                            distinctId,
                        })
                    ),
                    readOptions: eventualReadOptions(),
                }),
                callerTag ? { headers: { 'x-caller-tag': callerTag } } : undefined
            )

            for (const result of response.results) {
                if (result.person && result.key) {
                    const person = protoPersonToDomain(result.person) as InternalPersonWithDistinctId
                    person.distinct_id = result.key.distinctId
                    results.push(person)
                }
            }
        }
        return results
    }

    /**
     * Fetch up to ``limitPerPerson`` distinct_ids for each given int person_id.
     * Returns a record keyed by the int person_id (as a string, matching InternalPerson.id).
     * Callers that hold UUIDs should first convert via fetchPersonsByPersonIds to get int IDs.
     */
    async getDistinctIdsForPersons(
        teamId: number,
        personIntIds: string[],
        limitPerPerson?: number,
        callerTag?: string
    ): Promise<Record<string, string[]>> {
        if (personIntIds.length === 0) {
            return {}
        }

        const response = await this.client.getDistinctIdsForPersons(
            create(GetDistinctIdsForPersonsRequestSchema, {
                teamId: BigInt(teamId),
                personIds: personIntIds.map((id) => BigInt(id)),
                limitPerPerson: limitPerPerson != null ? BigInt(limitPerPerson) : undefined,
                readOptions: eventualReadOptions(),
            }),
            callerTag ? { headers: { 'x-caller-tag': callerTag } } : undefined
        )

        const result: Record<string, string[]> = {}
        for (const pd of response.personDistinctIds) {
            result[String(pd.personId)] = pd.distinctIds.map((d) => d.distinctId)
        }
        return result
    }

    /**
     * Person state by id. Eventual reads go to the replica; strong reads
     * are routed to the partition's leader, whose cache the primary lags
     * by writer apply lag, so a caller that must observe its own writes
     * asks for strong. Returns null for a person that does not exist
     * (deleted, or merged away).
     */
    async fetchPersonById(
        teamId: number,
        personId: string,
        callerTag?: string,
        options?: { consistency?: 'strong' | 'eventual' }
    ): Promise<InternalPerson | null> {
        try {
            const response = await this.client.getPerson(
                create(GetPersonRequestSchema, {
                    teamId: BigInt(teamId),
                    personId: BigInt(personId),
                    readOptions: options?.consistency === 'strong' ? strongReadOptions() : eventualReadOptions(),
                }),
                callerTag ? { headers: { 'x-caller-tag': callerTag } } : undefined
            )
            return response.person ? protoPersonToDomain(response.person) : null
        } catch (error) {
            if (error instanceof ConnectError && error.code === Code.NotFound) {
                return null
            }
            throw error
        }
    }

    /**
     * Apply a folded property update to one person. The leader merges the
     * diffs into authoritative state under the per-person lock and returns
     * the person as written, so the caller can publish it downstream.
     * Returns null person when the response carries none.
     */
    async updatePersonProperties(
        update: FoldedPersonUpdate,
        callerTag?: string
    ): Promise<{ person: InternalPerson | null; updated: boolean }> {
        try {
            const response = await this.client.updatePersonProperties(
                create(UpdatePersonPropertiesRequestSchema, {
                    teamId: BigInt(update.teamId),
                    personId: BigInt(update.personId),
                    eventName: update.eventName,
                    setProperties: encodeJsonBytes(update.setProperties),
                    setOnceProperties: encodeJsonBytes(update.setOnceProperties),
                    unsetProperties: update.unsetProperties,
                    isIdentified: update.isIdentified,
                    lastSeenAt: update.lastSeenAtMs != null ? BigInt(update.lastSeenAtMs) : undefined,
                    forceUpdate: update.forceUpdate ?? false,
                }),
                callerTag ? { headers: { 'x-caller-tag': callerTag } } : undefined
            )
            return {
                person: response.person ? protoPersonToDomain(response.person) : null,
                updated: response.updated,
            }
        } catch (error) {
            // Translate the personhog contract into domain errors here so
            // callers never handle gRPC codes: a missing person (deleted, or
            // merged away) surfaces as NoRowsUpdatedError, and the leader's
            // only InvalidArgument for a well-formed request is the
            // property-size ceiling. Everything else propagates untouched.
            if (error instanceof ConnectError) {
                if (error.code === Code.NotFound) {
                    throw new PersonhogPersonNotFoundError(
                        `Person ${update.personId} not found by personhog (deleted or merged)`,
                        update.personId
                    )
                }
                if (error.code === Code.InvalidArgument && error.rawMessage.includes('size limit')) {
                    throw new PersonhogPropertiesSizeError(error.rawMessage, update.teamId, update.personId)
                }
                // Keyed on the metadata rather than the status code: the
                // leader answers FAILED_PRECONDITION while the router hands
                // back its own UNAVAILABLE with these keys carried forward.
                if (error.metadata.has(FENCED_METADATA_KEY)) {
                    throw new PersonhogFencedError(
                        error.rawMessage,
                        update.personId,
                        error.metadata.get(FENCED_OP_ID_METADATA_KEY) ?? undefined
                    )
                }
            }
            throw error
        }
    }

    async fetchPersonsByPersonIds(
        teamPersons: { teamId: number; personId: string }[],
        callerTag?: string
    ): Promise<InternalPerson[]> {
        if (teamPersons.length === 0) {
            return []
        }

        const byTeam = new Map<number, string[]>()
        for (const { teamId, personId } of teamPersons) {
            const uuids = byTeam.get(teamId) ?? []
            uuids.push(personId)
            byTeam.set(teamId, uuids)
        }

        const allPersons = await Promise.all(
            [...byTeam].map(async ([teamId, uuids]) => {
                const batchResults: InternalPerson[] = []
                for (let i = 0; i < uuids.length; i += PERSONHOG_BATCH_SIZE) {
                    const batch = uuids.slice(i, i + PERSONHOG_BATCH_SIZE)
                    const response = await this.client.getPersonsByUuids(
                        create(GetPersonsByUuidsRequestSchema, {
                            teamId: BigInt(teamId),
                            uuids: batch,
                            readOptions: eventualReadOptions(),
                        }),
                        callerTag ? { headers: { 'x-caller-tag': callerTag } } : undefined
                    )
                    batchResults.push(...response.persons.map(protoPersonToDomain))
                }
                return batchResults
            })
        )
        return allPersons.flat()
    }
}