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.

11.7 KB
Raw Blame
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 }
    }
}