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.

5.2 KB
Raw Blame
import { createHash } from 'crypto'

import { logger } from '~/common/utils/logger'

import { KNOWN_BOT_IP_LIST, KNOWN_BOT_UA_LIST } from './bots/bots'

/**
 * Shared access to the `@posthog/hogvm-node` napi addon (the Rust HogVM). The addon is optional —
 * when it isn't built for this environment, `loadHogvmNodeModule` returns null and callers fall
 * back to the Node VM.
 */

// The Rust VM budgets steps, not wall-clock time; generous so it never trips before the Node VM's
// timeout would.
export const RUST_MAX_STEPS = 1_000_000

// Error formats that mean "the Rust VM can't run this program" rather than "the program failed".
// All four are contracts with the Rust side, pinned by tests there, so change both sides together:
// the binding's ext_fns fail unimplemented host functions with the `unsupported_ext_fn:` prefix
// (rust/common/hogvm/node/src/ext_fns.rs `unsupported()`); the hogvm crate reports calls to
// functions it doesn't know at all as `Unknown function <name>`, unresolvable global chains as
// `Unknown Global <chain>`, and an opcode or input shape it has no implementation for as
// `Not implemented: <what>`.
export const UNSUPPORTED_EXT_FN_ERROR = 'unsupported_ext_fn:'
export const UNKNOWN_FUNCTION_ERROR_PREFIX = 'Unknown function '
export const UNKNOWN_GLOBAL_ERROR_PREFIX = 'Unknown Global '
export const NOT_IMPLEMENTED_ERROR_PREFIX = 'Not implemented: '

// A batch event whose globals couldn't cross the napi boundary (e.g. NaN/Infinity) never
// executed; like a boundary throw on the sync path, that event falls back to the Node VM
// (rust/common/hogvm/node/src/exec.rs `MARSHAL_ERROR_PREFIX`).
export const MARSHAL_ERROR_PREFIX = 'marshal_error:'

/**
 * True when the error means the Rust VM can't run this program (the Node VM can). The executor
 * uses this to hand the invocation to the Node VM. Real execution errors must never match — the
 * caller would otherwise run the program twice.
 */
export function isUnsupportedByRustVm(error: string): boolean {
    return (
        error.includes(UNSUPPORTED_EXT_FN_ERROR) ||
        error.startsWith(UNKNOWN_FUNCTION_ERROR_PREFIX) ||
        error.startsWith(UNKNOWN_GLOBAL_ERROR_PREFIX) ||
        error.startsWith(NOT_IMPLEMENTED_ERROR_PREFIX)
    )
}

const programKeys = new WeakMap<unknown[], string>()

/**
 * Content hash of a bytecode array, cached per instance (the hog function manager hands out one
 * array per function). Every team has its own copy of a template, and keying by content is what
 * lets those copies share a batch and a registration.
 */
export function programKey(bytecode: unknown[]): string {
    let key = programKeys.get(bytecode)
    if (key === undefined) {
        key = createHash('sha256').update(JSON.stringify(bytecode)).digest('base64')
        programKeys.set(bytecode, key)
    }
    return key
}

export interface RustExecResult {
    result?: unknown
    error?: string
    durationUs: number
    /** Messages from print() calls, in call order, capped at 24 entries. */
    logs?: string[]
    /** True when print() was called past the cap and messages were dropped. */
    logsTruncated?: boolean
}

export interface HogvmNodeModule {
    init(options: { mmdbPath?: string; knownBotUaList?: string[]; knownBotIpList?: string[] }): void
    executeSync(program: unknown[], globals: unknown, options?: { maxSteps?: number }): RustExecResult
    executeBatch(
        program: unknown[],
        events: unknown[],
        options?: { parallel?: boolean; maxSteps?: number }
    ): Promise<RustExecResult[]>
    /**
     * The registry bindings are optional: the addon is a separately built native binary, and a
     * deployment can run one that predates them. Callers feature-check and fall back to the
     * unregistered calls above instead of throwing on every invocation.
     */
    registerProgram?(program: unknown[]): number
    releaseProgram?(handle: number): void
    executeRegisteredSync?(handle: number, globals: unknown, options?: { maxSteps?: number }): RustExecResult
    executeRegisteredBatch?(
        handle: number,
        events: unknown[],
        options?: { parallel?: boolean; maxSteps?: number }
    ): Promise<RustExecResult[]>
}

let cachedModule: HogvmNodeModule | null | undefined = undefined

/**
 * Load and initialize the native addon once per process (`init` is idempotent on the Rust side).
 * Returns null when the addon isn't built for this environment. `options` only take effect on the
 * first call in the process — later callers always get the module as first configured.
 */
export function loadHogvmNodeModule(options: { mmdbPath: string }): HogvmNodeModule | null {
    if (cachedModule !== undefined) {
        return cachedModule
    }
    try {
        const module_: HogvmNodeModule = require('@posthog/hogvm-node')
        module_.init({
            mmdbPath: options.mmdbPath,
            knownBotUaList: KNOWN_BOT_UA_LIST,
            knownBotIpList: KNOWN_BOT_IP_LIST,
        })
        cachedModule = module_
    } catch (error) {
        cachedModule = null
        logger.warn('🦀', 'Rust HogVM native module unavailable', { error: String(error) })
    }
    return cachedModule
}

export function resetHogvmNodeModuleCacheForTests(): void {
    cachedModule = undefined
}