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.

4.1 KB
Raw Blame
import { HogVMErrorKind, HogVMException } from '@posthog/hogvm'

/**
 * Who has to act on a failed filter or input.
 *
 * - `data`: the program fits the runtime and this event did not fit the program. Another event may
 *   pass, so nothing is broken and nobody needs to act.
 * - `legacy`: the program asks the runtime for something it does not have, and was saved before the
 *   compiler checked that. The owner has to fix the function; replaying the event cannot.
 * - `drift`: the same, but the program was compiled against an older runtime, so a change on our side
 *   broke it. Replay after the runtime or the compiler is fixed.
 * - `bug`: the same, but compiled against this runtime, so the compiler and the VM disagree about
 *   what exists. Ours to fix.
 * - `limit`: the program ran out of time, memory or stack. Replay would run out again, so it is the
 *   owner's to fix. Many functions hitting it at once is a different story, and the label shows that.
 * - `config`: the function points at something the owner removed, such as a deleted integration.
 *   The owner has to fix the function; replaying the event cannot.
 * - `platform`: a JavaScript error the VM let through, or something that is not an error at all.
 *   Ours to look at.
 */
export type HogErrorClass = 'data' | 'legacy' | 'drift' | 'bug' | 'limit' | 'config' | 'platform'

export class HogConfigurationError extends Error {}

export type HogErrorContract = {
    /** The stamp on the bytecode that ran, from `filters.bytecode_contract`. Absent on older bytecode. */
    bytecodeContract?: string
    /** The stamp of the runtime that ran it, from `currentRuntimeContractHash()`. */
    runtimeContract: string
}

type KindedError = { kind: HogVMErrorKind }

const KINDS: ReadonlySet<string> = new Set<HogVMErrorKind>(['contract', 'data', 'limit'])

export const isHogVMErrorKind = (value: unknown): value is HogVMErrorKind =>
    typeof value === 'string' && KINDS.has(value)

// By shape rather than instanceof: the error can come from another realm or an older build of the VM.
const isHogVMException = (error: object): error is KindedError =>
    error instanceof HogVMException || isHogVMErrorKind((error as Partial<KindedError>).kind)

/**
 * The first VM error in the cause chain. Callers wrap the VM's error to add the field or the
 * function it happened in, and the wrapper carries no kind of its own.
 */
function findHogVMException(error: unknown): KindedError | undefined {
    let current: unknown = error
    for (let depth = 0; depth < 10 && typeof current === 'object' && current !== null; depth++) {
        if (isHogVMException(current)) {
            return current
        }
        current = (current as { cause?: unknown }).cause
    }
    return undefined
}

const BYTECODE_CONTRACT = 'bytecodeContract'

/**
 * Attaches the stamp of the bytecode that threw to the error, so the catch block that classifies it
 * knows which runtime the program was compiled against. The message is untouched.
 */
export function withBytecodeContract<T>(error: T, bytecodeContract: string | undefined): T {
    if (bytecodeContract !== undefined && typeof error === 'object' && error !== null) {
        Object.defineProperty(error, BYTECODE_CONTRACT, { value: bytecodeContract, enumerable: false })
    }
    return error
}

export function bytecodeContractOf(error: unknown): string | undefined {
    if (typeof error !== 'object' || error === null) {
        return undefined
    }
    const value = (error as Record<string, unknown>)[BYTECODE_CONTRACT]
    return typeof value === 'string' ? value : undefined
}

export function classifyHogError(error: unknown, contract: HogErrorContract): HogErrorClass {
    if (error instanceof HogConfigurationError) {
        return 'config'
    }
    const vmError = findHogVMException(error)
    if (!vmError) {
        return 'platform'
    }
    switch (vmError.kind) {
        case 'data':
            return 'data'
        case 'limit':
            return 'limit'
        case 'contract':
            if (!contract.bytecodeContract) {
                return 'legacy'
            }
            return contract.bytecodeContract === contract.runtimeContract ? 'bug' : 'drift'
    }
}