: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 { Interceptor, Transport, createClient } from '@connectrpc/connect'
import { Http2SessionManager, createGrpcTransport } from '@connectrpc/connect-node'
import { DateTime } from 'luxon'
import { PersonHogService } from '~/common/generated/personhog/personhog/service/v1/service_pb'
import { ConsistencyLevel, ReadOptionsSchema } from '~/common/generated/personhog/personhog/types/v1/common_pb'
import { parseJSON } from '~/common/utils/json-parse'
import { ConnectionWindowSessionManager } from './connection-window-session-manager'
import { PersonHogGroupOperations } from './groups'
import { PersonHogPersonOperations } from './persons'
import { SessionStateMonitor } from './session-state-monitor'
const textDecoder = new TextDecoder()
export function parseJsonBytes(bytes: Uint8Array): any {
if (bytes.length === 0) {
return null
}
return parseJSON(textDecoder.decode(bytes))
}
export function epochMsToDateTime(epochMs: bigint): DateTime {
return DateTime.fromMillis(Number(epochMs), { zone: 'utc' })
}
export function shouldUseGrpc(percentage: number): boolean {
return Math.random() * 100 < percentage
}
/**
* Team ID-aware rollout check. If rolloutTeamIds is non-empty, routes based on
* team membership (ignoring percentage). Otherwise falls back to percentage.
*/
export function shouldUseGrpcForTeam(rolloutTeamIds: ReadonlySet<number>, teamId: number, percentage: number): boolean {
if (rolloutTeamIds.size > 0) {
return rolloutTeamIds.has(teamId)
}
return shouldUseGrpc(percentage)
}
/**
* Batch variant: returns true only if ALL provided team IDs are in the rollout set.
* When rolloutTeamIds is empty, falls back to percentage-based sampling.
* Zero-allocation: iterates the array directly with O(1) Set lookups.
*/
export function shouldUseGrpcForTeams(
rolloutTeamIds: ReadonlySet<number>,
teamIds: number[],
percentage: number
): boolean {
if (rolloutTeamIds.size > 0) {
if (teamIds.length === 0) {
return false
}
for (const id of teamIds) {
if (!rolloutTeamIds.has(id)) {
return false
}
}
return true
}
return shouldUseGrpc(percentage)
}
/**
* Like shouldUseGrpcForTeams but accepts an array of objects with a teamId field,
* avoiding the intermediate .map() allocation.
*/
export function shouldUseGrpcForTeamItems<T extends { teamId: number }>(
rolloutTeamIds: ReadonlySet<number>,
items: T[],
percentage: number
): boolean {
if (rolloutTeamIds.size > 0) {
if (items.length === 0) {
return false
}
for (const item of items) {
if (!rolloutTeamIds.has(item.teamId)) {
return false
}
}
return true
}
return shouldUseGrpc(percentage)
}
/** Parse a comma-separated string of team IDs into a Set. */
export function parseRolloutTeamIds(raw: string): Set<number> {
if (!raw.trim()) {
return new Set()
}
const ids = new Set<number>()
for (const part of raw.split(',')) {
const n = parseInt(part.trim(), 10)
if (!isNaN(n)) {
ids.add(n)
}
}
return ids
}
export function eventualReadOptions() {
return create(ReadOptionsSchema, { consistency: ConsistencyLevel.EVENTUAL })
}
/** Routes through the partition's leader for read-your-writes consistency. */
export function strongReadOptions() {
return create(ReadOptionsSchema, { consistency: ConsistencyLevel.STRONG })
}
export function resolveConsistencyHeader(message: unknown): 'strong' | 'eventual' {
const msg = message as Record<string, unknown> | undefined
const readOptions = msg?.readOptions as { consistency?: ConsistencyLevel } | undefined
return readOptions?.consistency === ConsistencyLevel.STRONG ? 'strong' : 'eventual'
}
/** Methods the router always forwards to the owning partition's leader. */
const LEADER_ROUTED_METHODS = new Set(['UpdatePersonProperties', 'FencePerson', 'ReleaseFence', 'FoldPersonDocument'])
/**
* The person routing key for a leader-bound call, or null when the call is
* replica-bound. The router hashes this key out of the request headers and
* never decodes the body, so a leader-bound call that omits it is rejected
* with InvalidArgument rather than routed. Replica-bound reads must travel
* without the key, which is why `GetPerson` carries it only under strong
* consistency, the one case the router sends to a leader.
*/
export function resolvePersonRoutingKey(
methodName: string,
message: unknown
): { teamId: bigint; personId: bigint } | null {
const leaderBound =
LEADER_ROUTED_METHODS.has(methodName) ||
(methodName === 'GetPerson' && resolveConsistencyHeader(message) === 'strong')
if (!leaderBound) {
return null
}
const { teamId, personId } = message as { teamId: bigint; personId: bigint }
return { teamId, personId }
}
export interface PersonHogClientConfig {
/** Host and port of the personhog gRPC server, e.g. "localhost:50051". */
addr: string
/** Identifier sent in the x-client-name header so the server can distinguish callers. */
clientName?: string
/** Use TLS (https) for the HTTP/2 connection. Default: false. */
useTls?: boolean
// -- Request limits --
/** Per-request timeout in milliseconds. Default: 1 000. */
timeoutMs?: number
/** Maximum inbound message size in bytes. Default: 128 MiB. */
readMaxBytes?: number
/** Maximum outbound message size in bytes. Default: 4 MiB. */
writeMaxBytes?: number
// -- HTTP/2 keepalive (maps to gRPC keepalive concepts) --
/**
* Interval between HTTP/2 PING frames to keep the connection alive.
* The interval resets whenever a stream receives data. If a PING is not
* answered within pingTimeoutMs the connection is closed.
* Equivalent to GRPC_ARG_KEEPALIVE_TIME_MS. Default: 30 000.
*/
pingIntervalMs?: number
/**
* How long to wait for a PING response before treating the connection as
* dead. Equivalent to GRPC_ARG_KEEPALIVE_TIMEOUT_MS. Default: 5 000.
*/
pingTimeoutMs?: number
/**
* Send PING frames even when no streams are open. Keeps idle connections
* alive so they don't get silently dropped by load balancers or proxies.
* Equivalent to GRPC_ARG_KEEPALIVE_PERMIT_WITHOUT_CALLS. Default: true.
*/
pingIdleConnection?: boolean
/**
* Close the HTTP/2 connection after this many milliseconds of no open
* streams. A new connection is created transparently on the next request.
* Equivalent to GRPC_ARG_CLIENT_IDLE_TIMEOUT_MS. Default: 15 minutes.
*/
idleConnectionTimeoutMs?: number
initialStreamWindowBytes?: number
initialConnectionWindowBytes?: number
// -- Attribution --
/** Identifies the code path / feature area within this service (e.g., "ingestion/event-processing"). */
callerTag?: string
// -- Observability --
/**
* How often (ms) to poll the Http2SessionManager state for connection
* state transition metrics. Lower values detect async transitions (idle
* timeouts, ping failures) faster but add minor CPU overhead.
* Default: 5 000.
*/
stateMonitorPollIntervalMs?: number
}
export class PersonHogClient {
readonly groups: PersonHogGroupOperations
readonly persons: PersonHogPersonOperations
private stateMonitor: SessionStateMonitor | undefined
private constructor(transport: Transport, stateMonitor?: SessionStateMonitor) {
const client = createClient(PersonHogService, transport)
this.groups = new PersonHogGroupOperations(client)
this.persons = new PersonHogPersonOperations(client)
this.stateMonitor = stateMonitor
}
static fromTransport(transport: Transport): PersonHogClient {
return new PersonHogClient(transport)
}
static fromConfig(config: PersonHogClientConfig): PersonHogClient {
const { transport, stateMonitor } = createPersonhogTransport(config)
return new PersonHogClient(transport, stateMonitor)
}
close(): void {
this.stateMonitor?.close()
}
}
export const MAX_HTTP2_WINDOW_BYTES = 2 ** 31 - 1
function windowBytes(value: number | undefined, name: string): number | undefined {
if (value === undefined || value === 0) {
return undefined
}
if (!Number.isInteger(value) || value < 0 || value > MAX_HTTP2_WINDOW_BYTES) {
throw new Error(`${name} must be an integer between 0 and ${MAX_HTTP2_WINDOW_BYTES}, got ${value}`)
}
return value
}
/**
* The transport every personhog gRPC client shares: caller headers,
* consistency and routing-key stamping, and an HTTP/2 session kept alive
* and monitored.
* The identity server's clients build on it too, so the wire behavior
* cannot drift between endpoints.
*/
export function createPersonhogTransport(config: PersonHogClientConfig): {
transport: Transport
stateMonitor: SessionStateMonitor
} {
{
const scheme = config.useTls ? 'https' : 'http'
const interceptors: Interceptor[] = []
if (config.clientName) {
const clientName = config.clientName
interceptors.push((next) => async (req) => {
req.header.set('x-client-name', clientName)
return await next(req)
})
}
if (config.callerTag) {
const callerTag = config.callerTag
interceptors.push((next) => async (req) => {
if (!req.header.has('x-caller-tag')) {
req.header.set('x-caller-tag', callerTag)
}
return await next(req)
})
}
interceptors.push((next) => async (req) => {
req.header.set('x-read-consistency', resolveConsistencyHeader(req.message))
return await next(req)
})
interceptors.push((next) => async (req) => {
const routingKey = resolvePersonRoutingKey(req.method.name, req.message)
if (routingKey) {
req.header.set('x-team-id', routingKey.teamId.toString())
req.header.set('x-person-id', routingKey.personId.toString())
}
return await next(req)
})
const streamWindowBytes = windowBytes(config.initialStreamWindowBytes, 'initialStreamWindowBytes')
const connectionWindowBytes = windowBytes(config.initialConnectionWindowBytes, 'initialConnectionWindowBytes')
const sessionManager = new Http2SessionManager(
`${scheme}://${config.addr}`,
{
pingIntervalMs: config.pingIntervalMs ?? 30_000,
pingTimeoutMs: config.pingTimeoutMs ?? 5_000,
pingIdleConnection: config.pingIdleConnection ?? true,
idleConnectionTimeoutMs: config.idleConnectionTimeoutMs,
},
streamWindowBytes === undefined ? undefined : { settings: { initialWindowSize: streamWindowBytes } }
)
const stateMonitor = new SessionStateMonitor(
sessionManager,
config.clientName ?? 'unknown',
config.stateMonitorPollIntervalMs ?? 5_000
)
const transport = createGrpcTransport({
baseUrl: `${scheme}://${config.addr}`,
defaultTimeoutMs: config.timeoutMs ?? 1_000,
readMaxBytes: config.readMaxBytes ?? 128 * 1024 * 1024,
writeMaxBytes: config.writeMaxBytes ?? 4 * 1024 * 1024,
sessionManager:
connectionWindowBytes === undefined
? stateMonitor
: new ConnectionWindowSessionManager(stateMonitor, connectionWindowBytes),
interceptors,
})
return { transport, stateMonitor }
}
}