: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, createRouterTransport } from '@connectrpc/connect'
import { DateTime } from 'luxon'
import { PersonHogService } from '~/common/generated/personhog/personhog/service/v1/service_pb'
import { TeamDistinctIdSchema } from '~/common/generated/personhog/personhog/types/v1/common_pb'
import {
GetDistinctIdsForPersonsResponseSchema,
PersonDistinctIdsSchema,
PersonSchema,
PersonWithTeamDistinctIdSchema,
PersonsByDistinctIdsResponseSchema,
PersonsResponseSchema,
} from '~/common/generated/personhog/personhog/types/v1/person_pb'
import { PersonHogClient } from '~/common/personhog/client'
import { PersonHogPersonReadRepository } from '~/common/personhog/personhog-person-read-repository'
import { INVALID_TEAM_ID_KEYS } from '~/tests/helpers/team'
import { PersonsManagerService } from './persons-manager.service'
jest.mock('~/common/utils/logger')
const textEncoder = new TextEncoder()
function jsonBytes(obj: unknown): Uint8Array {
return textEncoder.encode(JSON.stringify(obj))
}
type TestPerson = {
id: string
uuid: string
teamId: number
properties: Record<string, any>
distinctIds: string[]
}
function makeProtoPerson(p: TestPerson) {
return create(PersonSchema, {
id: BigInt(p.id),
uuid: p.uuid,
teamId: BigInt(p.teamId),
properties: jsonBytes(p.properties),
propertiesLastUpdatedAt: jsonBytes({}),
propertiesLastOperation: jsonBytes({}),
createdAt: BigInt(DateTime.fromISO('2024-01-01T00:00:00Z', { zone: 'utc' }).toMillis()),
version: 1n,
isIdentified: true,
})
}
function createTestPersonHogPersonReadRepository(persons: TestPerson[]): PersonHogPersonReadRepository {
const transport = createRouterTransport(({ service }) => {
service(PersonHogService, {
getPersonsByDistinctIds: (req) => {
const results = []
for (const td of req.teamDistinctIds) {
const teamId = Number(td.teamId)
const match = persons.find((p) => p.teamId === teamId && p.distinctIds.includes(td.distinctId))
if (match) {
results.push(
create(PersonWithTeamDistinctIdSchema, {
person: makeProtoPerson(match),
key: create(TeamDistinctIdSchema, {
teamId: td.teamId,
distinctId: td.distinctId,
}),
})
)
}
}
return create(PersonsByDistinctIdsResponseSchema, { results })
},
getPersonsByUuids: (req) => {
const teamId = Number(req.teamId)
const matched = persons.filter((p) => p.teamId === teamId && req.uuids.includes(p.uuid))
return create(PersonsResponseSchema, {
persons: matched.map(makeProtoPerson),
missingIds: [],
})
},
getDistinctIdsForPersons: (req) => {
const teamId = Number(req.teamId)
const personDistinctIds = []
for (const personId of req.personIds) {
const match = persons.find((p) => p.teamId === teamId && p.id === String(personId))
if (match && match.distinctIds.length > 0) {
const limit = req.limitPerPerson ? Number(req.limitPerPerson) : undefined
const ids = limit ? match.distinctIds.slice(0, limit) : match.distinctIds
personDistinctIds.push(
create(PersonDistinctIdsSchema, {
personId,
distinctIds: ids.map((d) => ({ distinctId: d })),
})
)
}
}
return create(GetDistinctIdsForPersonsResponseSchema, { personDistinctIds })
},
})
})
const client = PersonHogClient.fromTransport(transport)
return new PersonHogPersonReadRepository(client, 'test')
}
const TEAM_1 = 1
const TEAM_2 = 2
const TEST_PERSONS: TestPerson[] = [
{
id: '1',
uuid: 'aaaaaaaa-0000-0000-0000-000000000001',
teamId: TEAM_1,
properties: { foo: '1' },
distinctIds: ['distinct_id_A_1', 'distinct_id_A_2', 'distinct_id_A_3'],
},
{
id: '2',
uuid: 'aaaaaaaa-0000-0000-0000-000000000002',
teamId: TEAM_1,
properties: { foo: '2' },
distinctIds: ['distinct_id_B_1'],
},
{
id: '3',
uuid: 'aaaaaaaa-0000-0000-0000-000000000003',
teamId: TEAM_2,
properties: { foo: '3' },
distinctIds: ['distinct_id_A_1'],
},
]
describe('PersonsManagerService', () => {
jest.setTimeout(1000)
const mockTeamManager = {
getTeam: jest.fn().mockImplementation((teamId: number) => {
if (teamId === TEAM_1 || teamId === TEAM_2) {
return Promise.resolve({
id: teamId,
uuid: `team-uuid-${teamId}`,
organization_id: 'org-1',
person_display_name_properties: [],
})
}
return Promise.resolve(null)
}),
hasAvailableFeature: jest.fn().mockResolvedValue(true),
} as any
let repo: PersonHogPersonReadRepository
let manager: PersonsManagerService
beforeEach(() => {
jest.restoreAllMocks()
repo = createTestPersonHogPersonReadRepository(TEST_PERSONS)
manager = new PersonsManagerService(mockTeamManager, repo, 'http://localhost:8000')
})
describe('getCyclotronPerson with distinct_id', () => {
it('returns the persons requested', async () => {
const res = await Promise.all([
manager.getCyclotronPerson(TEAM_1, 'distinct_id_A_1', 'distinct_id'),
manager.getCyclotronPerson(TEAM_1, 'distinct_id_B_1', 'distinct_id'),
])
expect(res).toEqual([
{
id: TEST_PERSONS[0].uuid,
properties: { foo: '1' },
name: 'distinct_id_A_1',
url: `http://localhost:8000/project/${TEAM_1}/person/distinct_id_A_1`,
distinct_id: 'distinct_id_A_1',
},
{
id: TEST_PERSONS[1].uuid,
properties: { foo: '2' },
name: 'distinct_id_B_1',
url: `http://localhost:8000/project/${TEAM_1}/person/distinct_id_B_1`,
distinct_id: 'distinct_id_B_1',
},
])
})
it('handles distinct IDs containing colons', async () => {
const personsWithColons: TestPerson[] = [
...TEST_PERSONS,
{
id: '10',
uuid: 'bbbbbbbb-0000-0000-0000-000000000010',
teamId: TEAM_1,
properties: { foo: 'colon1' },
distinctIds: ['foo:distinct_id_A_1'],
},
{
id: '11',
uuid: 'bbbbbbbb-0000-0000-0000-000000000011',
teamId: TEAM_1,
properties: { foo: 'colon2' },
distinctIds: ['foo:bar:distinct_id_B_1'],
},
]
const colonRepo = createTestPersonHogPersonReadRepository(personsWithColons)
const colonManager = new PersonsManagerService(mockTeamManager, colonRepo, 'http://localhost:8000')
const res = await Promise.all([
colonManager.getCyclotronPerson(TEAM_1, 'foo:distinct_id_A_1', 'distinct_id'),
colonManager.getCyclotronPerson(TEAM_1, 'foo:bar:distinct_id_B_1', 'distinct_id'),
])
expect(res[0]!.distinct_id).toBe('foo:distinct_id_A_1')
expect(res[0]!.url).toBe(`http://localhost:8000/project/${TEAM_1}/person/foo%3Adistinct_id_A_1`)
expect(res[1]!.distinct_id).toBe('foo:bar:distinct_id_B_1')
expect(res[1]!.url).toBe(`http://localhost:8000/project/${TEAM_1}/person/foo%3Abar%3Adistinct_id_B_1`)
})
it('returns different persons for different teams', async () => {
const res = await Promise.all([
manager.getCyclotronPerson(TEAM_1, 'distinct_id_A_1', 'distinct_id'),
manager.getCyclotronPerson(TEAM_2, 'distinct_id_A_1', 'distinct_id'),
])
expect(res[0]!.properties).toEqual({ foo: '1' })
expect(res[1]!.properties).toEqual({ foo: '3' })
})
it('returns the same person for different distinct ids', async () => {
const res = await Promise.all([
manager.getCyclotronPerson(TEAM_1, 'distinct_id_A_1', 'distinct_id'),
manager.getCyclotronPerson(TEAM_1, 'distinct_id_A_2', 'distinct_id'),
])
expect(res[0]!.id).toEqual(res[1]!.id)
expect(res[0]!.properties).toEqual(res[1]!.properties)
})
it('returns null when person does not exist', async () => {
const result = await manager.getCyclotronPerson(TEAM_1, 'nonexistent', 'distinct_id')
expect(result).toBeNull()
})
it('returns null when team does not exist', async () => {
const result = await manager.getCyclotronPerson(99999, 'distinct_id_A_1', 'distinct_id')
expect(result).toBeNull()
})
it('encodes special characters in distinct_id for URL', async () => {
const personsWithEmail: TestPerson[] = [
...TEST_PERSONS,
{
id: '20',
uuid: 'cccccccc-0000-0000-0000-000000000020',
teamId: TEAM_1,
properties: {},
distinctIds: ['[email protected]'],
},
]
const emailRepo = createTestPersonHogPersonReadRepository(personsWithEmail)
const emailManager = new PersonsManagerService(mockTeamManager, emailRepo, 'http://localhost:8000')
const result = await emailManager.getCyclotronPerson(TEAM_1, '[email protected]', 'distinct_id')
expect(result).toBeDefined()
expect(result!.url).toBe(`http://localhost:8000/project/${TEAM_1}/person/user%40example.com`)
})
})
describe('forceFresh', () => {
it('re-reads a cached person, so a write made after it was cached is visible', async () => {
// A hogflow run enrolling just after a person write evaluates its first wait against this
// read. Serving the pre-write cache entry there parks the run with nothing left to wake it.
const cachedRead = await manager.getCyclotronPerson(TEAM_1, 'distinct_id_A_1', 'distinct_id')
expect(cachedRead?.properties).toEqual({ foo: '1' })
jest.spyOn(repo, 'fetchPersonsByDistinctIds').mockResolvedValue([
{
uuid: TEST_PERSONS[0].uuid,
team_id: TEAM_1,
distinct_id: 'distinct_id_A_1',
properties: { foo: 'written-after-caching' },
},
] as any)
expect((await manager.getCyclotronPerson(TEAM_1, 'distinct_id_A_1', 'distinct_id'))?.properties).toEqual({
foo: '1',
})
expect(
(await manager.getCyclotronPerson(TEAM_1, 'distinct_id_A_1', 'distinct_id', { forceFresh: true }))
?.properties
).toEqual({ foo: 'written-after-caching' })
})
})
describe('getCyclotronPerson with person_id', () => {
it('returns a person by UUID and resolves distinct_id', async () => {
const result = await manager.getCyclotronPerson(TEAM_1, TEST_PERSONS[0].uuid, 'person_id')
expect(result).toEqual(
expect.objectContaining({
id: TEST_PERSONS[0].uuid,
properties: { foo: '1' },
distinct_id: 'distinct_id_A_1',
})
)
})
it('returns null for a UUID that does not exist', async () => {
const result = await manager.getCyclotronPerson(TEAM_1, 'zzzzzzzz-0000-0000-0000-000000000000', 'person_id')
expect(result).toBeNull()
})
it('returns the correct person for each team when UUIDs differ', async () => {
const res = await Promise.all([
manager.getCyclotronPerson(TEAM_1, TEST_PERSONS[0].uuid, 'person_id'),
manager.getCyclotronPerson(TEAM_2, TEST_PERSONS[2].uuid, 'person_id'),
])
expect(res).toEqual([
expect.objectContaining({ id: TEST_PERSONS[0].uuid, properties: { foo: '1' } }),
expect.objectContaining({ id: TEST_PERSONS[2].uuid, properties: { foo: '3' } }),
])
})
it('returns null when queried under the wrong team', async () => {
const result = await manager.getCyclotronPerson(TEAM_2, TEST_PERSONS[0].uuid, 'person_id')
expect(result).toBeNull()
})
})
it.each(
INVALID_TEAM_ID_KEYS.flatMap((key) => [
[key, 'distinct_id', 'distinct_id_A_1'] as const,
[key, 'person_id', TEST_PERSONS[0].uuid] as const,
])
)(
'returns null for invalid team id %p by %s without failing the valid team in the same load',
async (key, kind, id) => {
const [valid, invalid] = await Promise.all([
manager.getCyclotronPerson(TEAM_1, id, kind),
manager.getCyclotronPerson(key as unknown as number, id, kind),
])
expect(valid?.properties).toEqual({ foo: '1' })
expect(invalid).toBeNull()
}
)
describe('error handling', () => {
it('propagates errors when personhog is unavailable', async () => {
const failingTransport = createRouterTransport(({ service }) => {
service(PersonHogService, {
getPersonsByDistinctIds: () => {
throw new ConnectError('unavailable', Code.Unavailable)
},
})
})
const failingClient = PersonHogClient.fromTransport(failingTransport)
const failingRepo = new PersonHogPersonReadRepository(failingClient, 'test')
const failingManager = new PersonsManagerService(mockTeamManager, failingRepo, 'http://localhost:8000')
await expect(failingManager.getCyclotronPerson(TEAM_1, 'distinct_id_A_1', 'distinct_id')).rejects.toThrow()
})
})
})