: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 { 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
}