: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
import { create } from '@bufbuild/protobuf'
import { Code, ConnectError, type ServiceImpl, createClient, createRouterTransport } from '@connectrpc/connect'
import { PersonHogService } from '~/common/generated/personhog/personhog/service/v1/service_pb'
import { PersonSchema } from '~/common/generated/personhog/personhog/types/v1/person_pb'
import type {
GetPersonsByDistinctIdsRequest,
GetPersonsByUuidsRequest,
UpdatePersonPropertiesRequest,
} from '~/common/generated/personhog/personhog/types/v1/person_pb'
import { parseJSON } from '~/common/utils/json-parse'
import { NoRowsUpdatedError } from '~/common/utils/utils'
import {
PersonHogPersonOperations,
PersonhogFencedError,
PersonhogPersonNotFoundError,
PersonhogPropertiesSizeError,
} from './persons'
const textEncoder = new TextEncoder()
function jsonBytes(obj: unknown): Uint8Array {
return textEncoder.encode(JSON.stringify(obj))
}
function makeProtoPerson(id: number, uuid: string, teamId: number) {
return create(PersonSchema, {
id: BigInt(id),
uuid,
teamId: BigInt(teamId),
properties: jsonBytes({ name: `person-${id}` }),
propertiesLastUpdatedAt: jsonBytes({}),
propertiesLastOperation: jsonBytes({}),
createdAt: BigInt(Date.now()),
version: 1n,
isIdentified: true,
})
}
const SERVICE_DEFAULTS: ServiceImpl<typeof PersonHogService> = {
getGroup: () => ({}),
getGroups: () => ({ groups: [], missingGroups: [] }),
getGroupsBatch: () => ({ results: [] }),
listGroups: () => ({ groups: [], hasMore: false }),
getGroupTypeMappingsByTeamId: () => ({ mappings: [] }),
getGroupTypeMappingsByTeamIds: () => ({ results: [] }),
getGroupTypeMappingsByProjectId: () => ({ mappings: [] }),
getGroupTypeMappingsByProjectIds: () => ({ results: [] }),
getGroupTypeMappingByDashboardId: () => ({}),
countGroupTypeMappings: () => ({ counts: [] }),
createGroup: () => ({}),
updateGroup: () => ({ updated: false }),
deleteGroupsBatchForTeam: () => ({ deletedCount: 0n }),
updateGroupTypeMapping: () => ({}),
deleteGroupTypeMapping: () => ({ deleted: false }),
deleteGroupTypeMappingsBatchForTeam: () => ({ deletedCount: 0n }),
getPerson: () => ({}),
getPersons: () => ({ persons: [] }),
getPersonByUuid: () => ({}),
getPersonsByUuids: () => ({ persons: [] }),
getPersonByDistinctId: () => ({}),
getPersonsByDistinctIdsInTeam: () => ({ results: [] }),
getPersonsByDistinctIds: () => ({ results: [] }),
getDistinctIdsForPerson: () => ({ distinctIds: [] }),
getDistinctIdsForPersons: () => ({ personDistinctIds: [] }),
getHashKeyOverrideContext: () => ({ results: [] }),
upsertHashKeyOverrides: () => ({}),
deleteHashKeyOverridesByTeams: () => ({}),
checkCohortMembership: () => ({ memberships: [] }),
countCohortMembers: () => ({ count: 0n }),
deleteCohortMember: () => ({ deleted: false }),
deleteCohortMembersBulk: () => ({ deletedCount: 0n }),
insertCohortMembers: () => ({ insertedCount: 0n }),
listCohortMemberIds: () => ({ personIds: [], nextCursor: 0n }),
updatePersonProperties: () => ({}),
deletePersons: () => ({ deletedCount: 0n }),
deletePersonsBatchForTeam: () => ({ deletedCount: 0n }),
deleteTombstonedPersons: () => ({
deletedCount: 0n,
skippedLiveCount: 0n,
blockedPersonUuids: [],
pendingPersonUuids: [],
rowsDeleted: 0n,
}),
getPersonTombstones: () => ({ tombstones: [] }),
ackPersonTombstones: () => ({ clearedCount: 0n }),
listPersonTombstoneQueue: () => ({ entries: [] }),
splitPerson: () => ({ splits: [] }),
setPersonDistinctIdVersionFloor: () => ({}),
setPersonVersionFloor: () => ({ updated: false }),
ensurePersonVersionFloors: () => ({ results: [] }),
getDistinctIdRows: () => ({ rows: [] }),
listPersonsForTeam: () => ({ persons: [] }),
raisePersonVersionFloors: () => ({ results: [] }),
restorePersons: () => ({ results: [] }),
writeDistinctIds: () => ({ results: [] }),
fencePerson: () => ({}),
fencePersons: () => ({}),
releaseFence: () => ({}),
releaseFences: () => ({}),
foldPersonDocument: () => ({}),
raisePersonVersion: () => ({ raised: false }),
}
function createOperations(overrides: Partial<ServiceImpl<typeof PersonHogService>> = {}): {
ops: PersonHogPersonOperations
handlers: { getPersonsByDistinctIds: jest.Mock; getPersonsByUuids: jest.Mock }
} {
const handlers = {
getPersonsByDistinctIds: jest.fn(() => ({ results: [] })),
getPersonsByUuids: jest.fn(() => ({ persons: [] })),
}
const transport = createRouterTransport(({ service }) => {
service(PersonHogService, {
...SERVICE_DEFAULTS,
...handlers,
...overrides,
})
})
const client = createClient(PersonHogService, transport)
const ops = new PersonHogPersonOperations(client)
return { ops, handlers }
}
describe('PersonHogPersonOperations', () => {
describe.each([
{
method: 'fetchPersonsByDistinctIds' as const,
handler: 'getPersonsByDistinctIds' as const,
makeItem: (i: number) => ({ teamId: 1, distinctId: `d-${i}` }),
},
{
method: 'fetchPersonsByPersonIds' as const,
handler: 'getPersonsByUuids' as const,
makeItem: (i: number) => ({ teamId: 1, personId: `uuid-${i}` }),
},
])('$method batching', ({ method, handler, makeItem }) => {
const invoke = (ops: PersonHogPersonOperations, count: number): Promise<any> =>
(ops[method] as any)(Array.from({ length: count }, (_, i) => makeItem(i)))
it('sends a single RPC when under the batch limit', async () => {
const { ops, handlers } = createOperations()
await invoke(ops, 10)
expect(handlers[handler]).toHaveBeenCalledTimes(1)
})
it('splits into multiple RPCs when over the batch limit', async () => {
const { ops, handlers } = createOperations()
await invoke(ops, 400)
expect(handlers[handler]).toHaveBeenCalledTimes(2)
})
it('handles exact batch boundary without duplicating or dropping', async () => {
const { ops, handlers } = createOperations()
await invoke(ops, 250)
expect(handlers[handler]).toHaveBeenCalledTimes(1)
})
})
describe('fetchPersonsByDistinctIds', () => {
it('merges results from multiple batches', async () => {
const handler = jest.fn()
let callCount = 0
handler.mockImplementation((req: GetPersonsByDistinctIdsRequest) => {
callCount++
return {
results: req.teamDistinctIds.map((td) => ({
key: { teamId: td.teamId, distinctId: td.distinctId },
person: makeProtoPerson(
callCount * 1000 + Number(td.teamId),
`uuid-${td.distinctId}`,
Number(td.teamId)
),
})),
}
})
const { ops } = createOperations({ getPersonsByDistinctIds: handler })
const items = Array.from({ length: 300 }, (_, i) => ({ teamId: 1, distinctId: `d-${i}` }))
const results = await ops.fetchPersonsByDistinctIds(items)
expect(handler).toHaveBeenCalledTimes(2)
expect(results).toHaveLength(300)
})
})
describe('fetchPersonsByPersonIds', () => {
it('merges results from multiple batches across teams', async () => {
const handler = jest.fn()
handler.mockImplementation((req: GetPersonsByUuidsRequest) => ({
persons: req.uuids.map((uuid, i) => makeProtoPerson(i, uuid, Number(req.teamId))),
}))
const { ops } = createOperations({ getPersonsByUuids: handler })
const items = [
...Array.from({ length: 300 }, (_, i) => ({ teamId: 1, personId: `uuid-t1-${i}` })),
...Array.from({ length: 100 }, (_, i) => ({ teamId: 2, personId: `uuid-t2-${i}` })),
]
const results = await ops.fetchPersonsByPersonIds(items)
// team 1: 2 batches (250 + 50), team 2: 1 batch (100)
expect(handler).toHaveBeenCalledTimes(3)
expect(results).toHaveLength(400)
})
})
describe('updatePersonProperties', () => {
it('maps each op onto its own proto field and decodes the response person', async () => {
const handler = jest.fn()
handler.mockImplementation((req: UpdatePersonPropertiesRequest) => ({
person: makeProtoPerson(Number(req.personId), 'uuid-42', Number(req.teamId)),
updated: true,
}))
const { ops } = createOperations({ updatePersonProperties: handler })
const result = await ops.updatePersonProperties({
teamId: 7,
personId: '42',
eventName: '$folded_person_update',
setProperties: { plan: 'pro' },
setOnceProperties: { first_seen: '2024-01-01' },
unsetProperties: ['stale'],
isIdentified: true,
lastSeenAtMs: 1700000000000,
})
const req = handler.mock.calls[0][0] as UpdatePersonPropertiesRequest
expect(req.teamId).toBe(7n)
expect(req.personId).toBe(42n)
expect(req.eventName).toBe('$folded_person_update')
expect(parseJSON(new TextDecoder().decode(req.setProperties))).toEqual({ plan: 'pro' })
expect(parseJSON(new TextDecoder().decode(req.setOnceProperties))).toEqual({
first_seen: '2024-01-01',
})
expect(req.unsetProperties).toEqual(['stale'])
expect(req.isIdentified).toBe(true)
expect(req.lastSeenAt).toBe(1700000000000n)
expect(result.updated).toBe(true)
expect(result.person?.id).toBe('42')
expect(result.person?.uuid).toBe('uuid-42')
})
it('sends empty ops as empty bytes and absent scalars as unset fields', async () => {
const handler = jest.fn((_req: UpdatePersonPropertiesRequest) => ({
person: makeProtoPerson(1, 'u', 1),
updated: false,
}))
const { ops } = createOperations({ updatePersonProperties: handler })
await ops.updatePersonProperties({
teamId: 1,
personId: '1',
eventName: '$folded_person_update',
setProperties: {},
setOnceProperties: {},
unsetProperties: [],
})
const req = handler.mock.calls[0][0]
expect(req.setProperties).toHaveLength(0)
expect(req.setOnceProperties).toHaveLength(0)
expect(req.isIdentified).toBeUndefined()
expect(req.lastSeenAt).toBeUndefined()
})
it('maps the personhog contract onto domain errors', async () => {
const foldedUpdate = {
teamId: 7,
personId: '42',
eventName: '$folded_person_update',
setProperties: { a: '1' },
setOnceProperties: {},
unsetProperties: [],
}
const { ops: notFoundOps } = createOperations({
updatePersonProperties: () => {
throw new ConnectError('person 42 not found', Code.NotFound)
},
})
const notFoundError = await notFoundOps.updatePersonProperties(foldedUpdate).catch((e) => e)
expect(notFoundError).toBeInstanceOf(PersonhogPersonNotFoundError)
expect(notFoundError).toBeInstanceOf(NoRowsUpdatedError)
expect(notFoundError.handledVerdict).toBe('person_not_found')
expect(notFoundError.personId).toBe('42')
const { ops: tooBigOps } = createOperations({
updatePersonProperties: () => {
throw new ConnectError(
'person properties update would exceed the size limit: 700000 bytes',
Code.InvalidArgument
)
},
})
const sizeError = await tooBigOps.updatePersonProperties(foldedUpdate).catch((e) => e)
expect(sizeError).toBeInstanceOf(PersonhogPropertiesSizeError)
expect(sizeError.teamId).toBe(7)
expect(sizeError.personId).toBe('42')
// Codes without a domain meaning pass through untouched for the
// caller's generic retry handling.
const { ops: unavailableOps } = createOperations({
updatePersonProperties: () => {
throw new ConnectError('leader unreachable', Code.Unavailable)
},
})
const passthrough = await unavailableOps.updatePersonProperties(foldedUpdate).catch((e) => e)
expect(passthrough).toBeInstanceOf(ConnectError)
expect(passthrough.code).toBe(Code.Unavailable)
})
// The leader raises FAILED_PRECONDITION, but the router that
// ingestion actually dials substitutes UNAVAILABLE after its
// retries while forwarding the fence metadata. Keying on the status
// code would read the routed shape as a generic outage.
it.each([
['the leader answers directly', Code.FailedPrecondition],
['the router substitutes its own status after exhausting retries', Code.Unavailable],
])('reads a fence refusal as a fence when %s', async (_case, code) => {
const { ops } = createOperations({
updatePersonProperties: () => {
const metadata = new Headers()
metadata.set('x-person-fenced', 'true')
metadata.set('x-person-fenced-op-id', 'merge:op-77')
throw new ConnectError('person 42 is held by a lifecycle operation', code, metadata)
},
})
const error = await ops
.updatePersonProperties({
teamId: 7,
personId: '42',
eventName: '$folded_person_update',
setProperties: { a: '1' },
setOnceProperties: {},
unsetProperties: [],
})
.catch((e) => e)
expect(error).toBeInstanceOf(PersonhogFencedError)
expect(error.personId).toBe('42')
expect(error.fencingOpId).toBe('merge:op-77')
})
})
})