From fd1effbc9581b86c42c7f2e76c5060c1ff84cf6a Mon Sep 17 00:00:00 2001 From: Nguyen Xuan An Date: Tue, 17 Nov 2026 07:10:46 +0700 Subject: [PATCH] Reject a prebuilt addon whose ABI does not match at load time (#62) addonBuildInfo() now also reports the KernelParamsV2 size the kernel reads. loadNativeAddon() throws when the addon lacks the export (v0.1.0 and v0.1.1 prebuilts), or when its version, pack revision or KernelParamsV2 size differs from the package, instead of warning and failing deep inside a trace. --- index.mjs | 33 ++++++++++---------- src/host/session.rs | 2 +- src/lib.rs | 8 ++++- tests/addon-handshake.test.mjs | 46 +++++++++++++--------------- tests/engine.test.mjs | 2 ++ tests/js-surface-validation.test.mjs | 3 +- tests/support/fake-addon.mjs | 12 ++++++++ tools/check-addon-build-info.mjs | 4 +-- 8 files changed, 65 insertions(+), 45 deletions(-) create mode 100644 tests/support/fake-addon.mjs diff --git a/index.mjs b/index.mjs index 69bb452..9322033 100644 --- a/index.mjs +++ b/index.mjs @@ -421,8 +421,6 @@ export function readAdapterCapacity() { return addon.adapterCapacity(); } -const warnedAddonPaths = new Set(); - /** The version the package.json next to this file declares: the addon built from this checkout reports the same one. */ function readPackageVersion() { const packageJsonPath = join(PACKAGE_DIRECTORY, 'package.json'); @@ -430,12 +428,17 @@ function readPackageVersion() { } /** - * Compares what an addon reports about its build (`addonBuildInfo()`) with this package. Returns - * `{ status: 'match' }`, `{ status: 'unknown' }` for an addon that lacks the export (prebuilt v0.1.0 and v0.1.1), or - * `{ status: 'mismatch', differences: [...] }` where each difference says what differs. + * Compares what an addon reports about its build (`addonBuildInfo()`) with this package. Returns `{ status: 'match' }`, or + * `{ status: 'mismatch', differences: [...] }` where each difference says what differs. An addon that lacks the export + * (prebuilt v0.1.0 and v0.1.1) or the KernelParamsV2 size is a mismatch: it is older than this package. */ -export function compareAddonBuildInfo(addonBuildInfo, expected = { version: readPackageVersion(), packRevision: PACK_REVISION }) { - if (typeof addonBuildInfo !== 'function') return { status: 'unknown' }; +export function compareAddonBuildInfo( + addonBuildInfo, + expected = { version: readPackageVersion(), packRevision: PACK_REVISION, kernelParamsBytes: STRUCT_STRIDES_V2.kernelParams } +) { + if (typeof addonBuildInfo !== 'function') { + return { status: 'mismatch', differences: ['the addon does not export addonBuildInfo, so it was built before this package'] }; + } const reported = addonBuildInfo(); const differences = []; if (reported.version !== expected.version) { @@ -444,22 +447,20 @@ export function compareAddonBuildInfo(addonBuildInfo, expected = { version: read if (reported.packRevision !== expected.packRevision) { differences.push(`the addon reads pack revision ${reported.packRevision} and the package writes pack revision ${expected.packRevision}`); } + if (reported.kernelParamsBytes !== expected.kernelParamsBytes) { + differences.push( + `the addon reads KernelParamsV2 blocks of ${reported.kernelParamsBytes ?? 'an unreported number of'} bytes and the package writes ${expected.kernelParamsBytes} bytes` + ); + } return differences.length === 0 ? { status: 'match' } : { status: 'mismatch', differences }; } -/** Throws when the addon was built from other sources than this package; warns once when it cannot tell. */ +/** Throws when the addon was built from other sources than this package, before any trace can fail deep inside the kernel. */ export function verifyAddonBuildInfo(addon, addonPath, expected) { const result = compareAddonBuildInfo(addon.addonBuildInfo, expected); if (result.status === 'mismatch') { throw new Error( - `The native addon at ${JSON.stringify(addonPath)} does not match this package: ${result.differences.join('; ')}. Run \`npx cook fetch-addon\` to download the addon of this version, or \`npm run build\` to compile it from these sources.` - ); - } - if (result.status === 'unknown' && !warnedAddonPaths.has(addonPath)) { - warnedAddonPaths.add(addonPath); - process.emitWarning( - `The native addon at ${JSON.stringify(addonPath)} predates the version check, so Cook cannot tell whether it matches this package. If renders fail oddly, run \`npx cook fetch-addon\` or \`npm run build\`.`, - 'CookAddonWarning' + `The Cook addon at ${JSON.stringify(addonPath)} does not match this package: ${result.differences.join('; ')}. Run \`npx cook fetch-addon\` after a release, or rebuild with \`npm run build\` (node build.mjs).` ); } } diff --git a/src/host/session.rs b/src/host/session.rs index b1caebc..bd00617 100644 --- a/src/host/session.rs +++ b/src/host/session.rs @@ -342,7 +342,7 @@ const SUBSURFACE_OFFSET_BYTE_OFFSET: usize = 60 * 4; const SAMPLE_INDEX_BYTE_OFFSET: u64 = 43 * 4; const SAMPLES_PER_WAIT: u32 = 4; -const KERNEL_PARAMS_V2_BYTES: usize = 336; +pub(crate) const KERNEL_PARAMS_V2_BYTES: usize = 336; const FORMAT_V2_MAGIC: u32 = 0x36375054; const FORMAT_V2_VERSION: u32 = 2; const MATERIAL_RECORD_BYTES: usize = 256; diff --git a/src/lib.rs b/src/lib.rs index d6e69c2..70fcf2a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -55,12 +55,18 @@ pub struct AddonBuildInfo { pub version: String, /// `PACK_REVISION` of pack-input-v2.mjs when the addon was built: the kernel's input layout revision. pub pack_revision: u32, + /// Size in bytes of the KernelParamsV2 block the kernel reads; the JS package must write blocks of the same size. + pub kernel_params_bytes: u32, } /// What this addon was built from. Addons built before this export existed lack it; index.mjs treats that as unknown. #[napi] pub fn addon_build_info() -> AddonBuildInfo { - AddonBuildInfo { version: ADDON_VERSION.to_string(), pack_revision: ADDON_PACK_REVISION } + AddonBuildInfo { + version: ADDON_VERSION.to_string(), + pack_revision: ADDON_PACK_REVISION, + kernel_params_bytes: crate::host::session::KERNEL_PARAMS_V2_BYTES as u32, + } } fn panic_message(payload: &(dyn Any + Send)) -> String { diff --git a/tests/addon-handshake.test.mjs b/tests/addon-handshake.test.mjs index 396c53f..f6e59c3 100644 --- a/tests/addon-handshake.test.mjs +++ b/tests/addon-handshake.test.mjs @@ -2,38 +2,36 @@ import assert from 'node:assert/strict'; import { test } from 'node:test'; import { compareAddonBuildInfo, verifyAddonBuildInfo, PACK_REVISION } from '../index.mjs'; +import { STRUCT_STRIDES_V2 } from '../pack-input-v2.mjs'; -const expected = { version: '1.2.3', packRevision: 4 }; +const expected = { version: '1.2.3', packRevision: 4, kernelParamsBytes: 336 }; test('an addon built from the same version and pack revision matches', () => { - const addonBuildInfo = () => ({ version: '1.2.3', packRevision: 4 }); + const addonBuildInfo = () => ({ version: '1.2.3', packRevision: 4, kernelParamsBytes: 336 }); assert.deepEqual(compareAddonBuildInfo(addonBuildInfo, expected), { status: 'match' }); }); -test('an addon without the export is unknown, not a failure', () => { - assert.deepEqual(compareAddonBuildInfo(undefined, expected), { status: 'unknown' }); - assert.doesNotThrow(() => verifyAddonBuildInfo({}, 'old-unknown-addon.node', expected)); +test('an addon without the export is rejected as older than the package', () => { + const result = compareAddonBuildInfo(undefined, expected); + assert.equal(result.status, 'mismatch'); + assert.throws( + () => verifyAddonBuildInfo({}, 'old-addon.node', expected), + /Cook addon at "old-addon\.node" does not match.*does not export addonBuildInfo.*npx cook fetch-addon.*npm run build/s + ); +}); + +test('a KernelParamsV2 size mismatch names both sizes', () => { + const addon = { addonBuildInfo: () => ({ version: '1.2.3', packRevision: 4, kernelParamsBytes: 320 }) }; + assert.throws(() => verifyAddonBuildInfo(addon, 'a.node', expected), /KernelParamsV2 blocks of 320 bytes and the package writes 336 bytes/); }); -test('an addon without the export warns once per file', () => { - const warnings = []; - const listener = (warning) => warnings.push(warning); - process.on('warning', listener); - verifyAddonBuildInfo({}, 'warned-once.node', expected); - verifyAddonBuildInfo({}, 'warned-once.node', expected); - return new Promise((resolveDone) => { - setImmediate(() => { - process.off('warning', listener); - const ours = warnings.filter((warning) => warning.name === 'CookAddonWarning' && warning.message.includes('warned-once.node')); - assert.equal(ours.length, 1); - assert.match(ours[0].message, /predates the version check/); - resolveDone(); - }); - }); +test('an addon that does not report the KernelParamsV2 size is rejected', () => { + const addon = { addonBuildInfo: () => ({ version: '1.2.3', packRevision: 4 }) }; + assert.throws(() => verifyAddonBuildInfo(addon, 'a.node', expected), /an unreported number of bytes/); }); test('a version mismatch names both versions and what to run', () => { - const addon = { addonBuildInfo: () => ({ version: '1.2.0', packRevision: 4 }) }; + const addon = { addonBuildInfo: () => ({ version: '1.2.0', packRevision: 4, kernelParamsBytes: 336 }) }; assert.throws( () => verifyAddonBuildInfo(addon, 'a.node', expected), /built from version 1\.2\.0 and the package is version 1\.2\.3.*npx cook fetch-addon.*npm run build/s @@ -41,18 +39,18 @@ test('a version mismatch names both versions and what to run', () => { }); test('a pack revision mismatch names both revisions', () => { - const addon = { addonBuildInfo: () => ({ version: '1.2.3', packRevision: 3 }) }; + const addon = { addonBuildInfo: () => ({ version: '1.2.3', packRevision: 3, kernelParamsBytes: 336 }) }; assert.throws(() => verifyAddonBuildInfo(addon, 'a.node', expected), /pack revision 3 and the package writes pack revision 4/); }); test('both differences are reported together', () => { - const result = compareAddonBuildInfo(() => ({ version: '0.0.1', packRevision: 9 }), expected); + const result = compareAddonBuildInfo(() => ({ version: '0.0.1', packRevision: 9, kernelParamsBytes: 336 }), expected); assert.equal(result.status, 'mismatch'); assert.equal(result.differences.length, 2); }); test('the default expectation is this package: its own version and PACK_REVISION match', () => { - const result = compareAddonBuildInfo(() => ({ version: JSON.parse(readPackage()).version, packRevision: PACK_REVISION })); + const result = compareAddonBuildInfo(() => ({ version: JSON.parse(readPackage()).version, packRevision: PACK_REVISION, kernelParamsBytes: STRUCT_STRIDES_V2.kernelParams })); assert.equal(result.status, 'match'); }); diff --git a/tests/engine.test.mjs b/tests/engine.test.mjs index 42dab50..2f6fa25 100644 --- a/tests/engine.test.mjs +++ b/tests/engine.test.mjs @@ -16,6 +16,7 @@ import { import { PACK_REVISION, findNativeAddon, resolveNativeKernel, traceNative } from '../index.mjs'; import { decodePackFile } from '../pack-file.mjs'; import { validatePackOptions } from '../pack-input-v2.mjs'; +import { MATCHING_ADDON_BUILD_INFO_SOURCE } from './support/fake-addon.mjs'; const PACKAGE_DIRECTORY = fileURLToPath(new URL('..', import.meta.url)); const TIME_LIMIT_MESSAGE = 'The native trace passed its time limit of 1 s after 3 of 8 samples.'; @@ -160,6 +161,7 @@ test('traceNative passes an addon time limit error on with its code', () => { const fakeAddon = join(directory, 'fake-addon.cjs'); writeFileSync(fakeAddon, ` module.exports = { + ${MATCHING_ADDON_BUILD_INFO_SOURCE}, traceSceneCycles() { const error = new Error(${JSON.stringify(TIME_LIMIT_MESSAGE)}); error.code = 'GenericFailure'; diff --git a/tests/js-surface-validation.test.mjs b/tests/js-surface-validation.test.mjs index 2c02507..fcbe73f 100644 --- a/tests/js-surface-validation.test.mjs +++ b/tests/js-surface-validation.test.mjs @@ -11,6 +11,7 @@ import { createNativeSession, resolveSessionFrame, traceNative } from '../index. import { decodePackFile, encodePackFile } from '../pack-file.mjs'; import { buildNativeInputV2, createTextureCollector, packMaterialRecordV2, validatePackOptions } from '../pack-input-v2.mjs'; import { buildRoomInput } from '../tools/make-fixture-pack.mjs'; +import { MATCHING_ADDON_BUILD_INFO_SOURCE } from './support/fake-addon.mjs'; const PACKAGE_DIRECTORY = fileURLToPath(new URL('..', import.meta.url)); const CLI_PATH = join(PACKAGE_DIRECTORY, 'bin', 'cook.mjs'); @@ -185,7 +186,7 @@ function partialFilesOf(outputName) { function writeFakeAddon(name, traceBody) { const addonPath = pathInWork(name); - writeFileSync(addonPath, `module.exports = { traceSceneCycles(input, options) { ${traceBody} } };`); + writeFileSync(addonPath, `module.exports = { ${MATCHING_ADDON_BUILD_INFO_SOURCE}, traceSceneCycles(input, options) { ${traceBody} } };`); return addonPath; } diff --git a/tests/support/fake-addon.mjs b/tests/support/fake-addon.mjs new file mode 100644 index 0000000..586cb8f --- /dev/null +++ b/tests/support/fake-addon.mjs @@ -0,0 +1,12 @@ +import { readFileSync } from 'node:fs'; + +import { PACK_REVISION, STRUCT_STRIDES_V2 } from '../../pack-input-v2.mjs'; + +const packageVersion = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version; + +/** CommonJS source of an `addonBuildInfo` export that matches this package, for a fake addon file in a test. */ +export const MATCHING_ADDON_BUILD_INFO_SOURCE = `addonBuildInfo() { return ${JSON.stringify({ + version: packageVersion, + packRevision: PACK_REVISION, + kernelParamsBytes: STRUCT_STRIDES_V2.kernelParams, +})}; }`; diff --git a/tools/check-addon-build-info.mjs b/tools/check-addon-build-info.mjs index 3890fc0..1e5b269 100644 --- a/tools/check-addon-build-info.mjs +++ b/tools/check-addon-build-info.mjs @@ -6,7 +6,7 @@ import { readFileSync } from 'node:fs'; import { dirname, join, resolve } from 'node:path'; import { fileURLToPath } from 'node:url'; -import { PACK_REVISION } from '../pack-input-v2.mjs'; +import { PACK_REVISION, STRUCT_STRIDES_V2 } from '../pack-input-v2.mjs'; const repositoryDirectory = join(dirname(fileURLToPath(import.meta.url)), '..'); const addonPath = resolve(process.argv[2] ?? join(repositoryDirectory, 'build', 'render-native.node')); @@ -19,5 +19,5 @@ assert.equal( 'function', `${addonPath} does not export addonBuildInfo; build it from the current sources.`, ); -assert.deepEqual(addonModule.exports.addonBuildInfo(), { version: packageVersion, packRevision: PACK_REVISION }); +assert.deepEqual(addonModule.exports.addonBuildInfo(), { version: packageVersion, packRevision: PACK_REVISION, kernelParamsBytes: STRUCT_STRIDES_V2.kernelParams }); console.log(`addonBuildInfo matches package.json (${packageVersion}) and PACK_REVISION (${PACK_REVISION})`);