diff --git a/doc/api/single-executable-applications.md b/doc/api/single-executable-applications.md index 6bedb213b8ae..1be8bf4aba58 100644 --- a/doc/api/single-executable-applications.md +++ b/doc/api/single-executable-applications.md @@ -357,6 +357,75 @@ against its source, so it is used by the executable whenever the modules are loaded from the VFS, and ignored if they changed. The cache is platform-specific, like the code cache of the main script. +#### Source maps in the VFS + +[Source Map v3][] maps work in a SEA using `"useVfs": true` exactly as they do +on the real file system, provided the maps are bundled as assets (or inside +the `"vfsArchive"` archive) and source map support is enabled in the generated +executable. The `.map` file is read from inside the mount point, and the +`"sources"` of the map and the original sources are resolved against the mount +point too. As a result, [`module.findSourceMap()`][], source-mapped stack +traces, and the source line shown above an uncaught error all resolve against +the bundled assets rather than the real file system. + +Source maps are enabled in a SEA the same way as in a regular Node.js process +with [`--enable-source-maps`][]. The flag is not consumed when it is +passed as a command-line argument to the executable: with the default +`"execArgvExtension": "env"`, command-line arguments are handed to the +application. Set it in `"execArgv"` (or in [`NODE_OPTIONS`][]) instead: + +```json +{ + "main": "sea.js", + "output": "sea", + "useVfs": true, + "execArgv": ["--enable-source-maps"], + "assets": { + "sea.js.map": "dist/sea.js.map", + "original.js": "src/original.js" + } +} +``` + +The bundled source must end with a `sourceMappingURL` magic comment that points +at the map. A relative path resolves against the location of the script inside +the mount, so no mount-point path needs to be hard-coded: + +```cjs +// sea.js +'use strict'; + +function boom() { + throw new Error('boom from the original source'); +} + +boom(); +//# sourceMappingURL=sea.js.map +``` + +If the map embeds `sourcesContent`, the original source lines are taken from +the map itself. Otherwise the original sources must also be bundled (as +assets, or as entries in the `"vfsArchive"` archive) so that the error source +preview can be read back through the VFS, as in the configuration above. With +`--enable-source-maps` enabled, throwing the error above maps the stack frame +back to `original.js` and shows the original source line: + +```text +…/vfs/1/original.js:5 + throw new Error('boom from the original source'); + ^ + +Error: boom from the original source + at boom (…/vfs/1/original.js:5:5) +``` + +The `…` stands in for the reserved mount point, which is chosen at runtime and +cannot exist on the real file system. When the application is transpiled, the +bundler typically emits the map next to the bundled file; make sure to bundle +it with `"assets"` (or include it in the `"vfsArchive"` archive), because the +VFS never shadows the real file system and the `.map` file must therefore be +reachable inside the mount. + #### Snapshot limitations `"useVfs": true` cannot be used together with `"useSnapshot": true`. @@ -844,11 +913,15 @@ to help us document them. [Generating single executable preparation blobs]: #1-generating-single-executable-preparation-blobs [Mach-O]: https://en.wikipedia.org/wiki/Mach-O [PE]: https://en.wikipedia.org/wiki/Portable_Executable +[Source Map v3]: https://tc39.es/ecma426/ [Using native addons in the injected main script]: #using-native-addons-in-the-injected-main-script [VFS documentation]: vfs.md [Windows SDK]: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/ +[`--enable-source-maps`]: cli.md#--enable-source-maps [`--vfs-load`]: cli.md#--vfs-loadsource +[`NODE_OPTIONS`]: cli.md#node_optionsoptions [`Worker`]: worker_threads.md#class-worker +[`module.findSourceMap()`]: module.md#modulefindsourcemappath [`node:zlib`]: zlib.md [`process.execPath`]: process.md#processexecpath [`require()`]: modules.md#requireid diff --git a/test/fixtures/sea/vfs-sourcemap/original.js b/test/fixtures/sea/vfs-sourcemap/original.js new file mode 100644 index 000000000000..5d0c8cfbcb97 --- /dev/null +++ b/test/fixtures/sea/vfs-sourcemap/original.js @@ -0,0 +1,15 @@ +'use strict'; + +const { findSourceMap } = require('module'); + +const sm = findSourceMap(__filename); +if (sm === undefined) { + throw new Error('source map was not loaded from the SEA VFS'); +} +console.log('source map loaded from the SEA VFS:', sm.payload.sources[0]); + +function boom() { + throw new Error('boom from the original source'); +} + +boom(); diff --git a/test/fixtures/sea/vfs-sourcemap/sea-config.json b/test/fixtures/sea/vfs-sourcemap/sea-config.json new file mode 100644 index 000000000000..bf4c11610fb4 --- /dev/null +++ b/test/fixtures/sea/vfs-sourcemap/sea-config.json @@ -0,0 +1,10 @@ +{ + "main": "sea.js", + "output": "sea-prep.blob", + "useVfs": true, + "execArgv": ["--enable-source-maps"], + "assets": { + "sea.js.map": "sea.js.map", + "original.js": "original.js" + } +} diff --git a/test/fixtures/sea/vfs-sourcemap/sea.js b/test/fixtures/sea/vfs-sourcemap/sea.js new file mode 100644 index 000000000000..91e395e46eb5 --- /dev/null +++ b/test/fixtures/sea/vfs-sourcemap/sea.js @@ -0,0 +1,16 @@ +'use strict'; + +const { findSourceMap } = require('module'); + +const sm = findSourceMap(__filename); +if (sm === undefined) { + throw new Error('source map was not loaded from the SEA VFS'); +} +console.log('source map loaded from the SEA VFS:', sm.payload.sources[0]); + +function boom() { + throw new Error('boom from the original source'); +} + +boom(); +//# sourceMappingURL=sea.js.map diff --git a/test/fixtures/sea/vfs-sourcemap/sea.js.map b/test/fixtures/sea/vfs-sourcemap/sea.js.map new file mode 100644 index 000000000000..92f8dd817613 --- /dev/null +++ b/test/fixtures/sea/vfs-sourcemap/sea.js.map @@ -0,0 +1,12 @@ +{ + "version": 3, + "file": "sea.js", + "sources": [ + "original.js" + ], + "names": [ + "boom" + ], + "mappings": "AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACI;FACJ;AACA;AACA;AACA", + "sourceRoot": "" +} \ No newline at end of file diff --git a/test/fixtures/sea/vfs-zip-sourcemap/original.js b/test/fixtures/sea/vfs-zip-sourcemap/original.js new file mode 100644 index 000000000000..5d0c8cfbcb97 --- /dev/null +++ b/test/fixtures/sea/vfs-zip-sourcemap/original.js @@ -0,0 +1,15 @@ +'use strict'; + +const { findSourceMap } = require('module'); + +const sm = findSourceMap(__filename); +if (sm === undefined) { + throw new Error('source map was not loaded from the SEA VFS'); +} +console.log('source map loaded from the SEA VFS:', sm.payload.sources[0]); + +function boom() { + throw new Error('boom from the original source'); +} + +boom(); diff --git a/test/fixtures/sea/vfs-zip-sourcemap/sea-config.json b/test/fixtures/sea/vfs-zip-sourcemap/sea-config.json new file mode 100644 index 000000000000..d42121169ef3 --- /dev/null +++ b/test/fixtures/sea/vfs-zip-sourcemap/sea-config.json @@ -0,0 +1,7 @@ +{ + "main": "sea.js", + "output": "sea-prep.blob", + "useVfs": true, + "vfsArchive": "assets.zip", + "execArgv": ["--enable-source-maps"] +} diff --git a/test/fixtures/sea/vfs-zip-sourcemap/sea.js b/test/fixtures/sea/vfs-zip-sourcemap/sea.js new file mode 100644 index 000000000000..91e395e46eb5 --- /dev/null +++ b/test/fixtures/sea/vfs-zip-sourcemap/sea.js @@ -0,0 +1,16 @@ +'use strict'; + +const { findSourceMap } = require('module'); + +const sm = findSourceMap(__filename); +if (sm === undefined) { + throw new Error('source map was not loaded from the SEA VFS'); +} +console.log('source map loaded from the SEA VFS:', sm.payload.sources[0]); + +function boom() { + throw new Error('boom from the original source'); +} + +boom(); +//# sourceMappingURL=sea.js.map diff --git a/test/fixtures/sea/vfs-zip-sourcemap/sea.js.map b/test/fixtures/sea/vfs-zip-sourcemap/sea.js.map new file mode 100644 index 000000000000..92f8dd817613 --- /dev/null +++ b/test/fixtures/sea/vfs-zip-sourcemap/sea.js.map @@ -0,0 +1,12 @@ +{ + "version": 3, + "file": "sea.js", + "sources": [ + "original.js" + ], + "names": [ + "boom" + ], + "mappings": "AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACI;FACJ;AACA;AACA;AACA", + "sourceRoot": "" +} \ No newline at end of file diff --git a/test/sea/test-single-executable-application-vfs-sourcemap.js b/test/sea/test-single-executable-application-vfs-sourcemap.js new file mode 100644 index 000000000000..e54b4c60e796 --- /dev/null +++ b/test/sea/test-single-executable-application-vfs-sourcemap.js @@ -0,0 +1,71 @@ +'use strict'; + +// This tests that source maps are correctly loaded from a Single Executable +// Application when "useVfs" is enabled. The `.map` file and the original +// sources are bundled as `"assets"` and served from inside the read-only +// virtual file system mounted by the SEA, so `findSourceMap()` and the +// source-mapped stack trace must resolve against the mount point instead of +// the real file system. +// +// The fixture (`test/fixtures/sea/vfs-sourcemap/`) enables source maps through +// `execArgv` (`--enable-source-maps`), verifies that `module.findSourceMap()` +// finds the bundled map, and then throws an error. This test asserts that: +// 1. the mapped stack trace for the throw frame references the ORIGINAL +// source (`original.js`) rather than the generated `sea.js`, and +// 2. the original source line shown above the error is read back from the +// VFS (it carries the original 4-space indentation, not the 2-space +// indentation of the generated `sea.js`). +// +// The fixture's `sea.js.map` is a source-map-v3 identity mapping that is tied +// to the current content of `sea.js` and `original.js`: most lines are mapped +// one-to-one, and the `throw` line maps its column from 2 (the generated +// 2-space indentation) to 4 (the original 4-space indentation). If either +// fixture source is edited, regenerate the map so the columns stay in sync. + +require('../common'); + +const { + buildSEA, + skipIfBuildSEAIsNotSupported, +} = require('../common/sea'); + +skipIfBuildSEAIsNotSupported(); + +const tmpdir = require('../common/tmpdir'); +const { spawnSyncAndAssert } = require('../common/child_process'); +const fixtures = require('../common/fixtures'); + +tmpdir.refresh(); +const outputFile = buildSEA(fixtures.path('sea', 'vfs-sourcemap')); + +spawnSyncAndAssert( + outputFile, + { + env: { + ...process.env, + NODE_DEBUG_NATIVE: undefined, + }, + }, + { + // The SEA main script throws an uncaught error to produce the + // source-mapped stack trace. + status: 1, + stdout: /source map loaded from the SEA VFS: .*\/original\.js/, + stderr(stderr) { + // The throw frame must be remapped to the original source bundled in + // the VFS. Its column (5) matches the original 4-space indentation. + if (!/at boom \(.*\/original\.js:\d+:\d+\)/.test(stderr)) { + throw new Error(`the boom() frame was not source-mapped:\n${stderr}`); + } + // It must not still point at the generated sea.js. + if (/at boom \(.*\/sea\.js:\d+:\d+\)/.test(stderr)) { + throw new Error(`the boom() frame was not remapped to original.js:\n${stderr}`); + } + // The original source line is read from the VFS, so it shows the + // original 4-space indentation (the generated sea.js uses 2 spaces). + if (!/^ {4}throw new Error\('boom from the original source'\);$/m.test(stderr)) { + throw new Error(`the original source line was not read from the VFS:\n${stderr}`); + } + }, + }, +); diff --git a/test/sea/test-single-executable-application-vfs-zip-sourcemap.js b/test/sea/test-single-executable-application-vfs-zip-sourcemap.js new file mode 100644 index 000000000000..f9e6eed46a00 --- /dev/null +++ b/test/sea/test-single-executable-application-vfs-zip-sourcemap.js @@ -0,0 +1,91 @@ +'use strict'; + +// This tests that source maps are correctly loaded from a Single Executable +// Application when the assets are served from a ZIP archive mounted through +// the VFS (`"vfsArchive"`). The `.map` file and the original sources live in +// the archive and are served from the mount point, so `findSourceMap()` and +// the source-mapped stack trace must resolve against the mount point instead +// of the real file system. +// +// The fixture (`test/fixtures/sea/vfs-zip-sourcemap/`) enables source maps +// through `execArgv` (`--enable-source-maps`), verifies that +// `module.findSourceMap()` finds the bundled map, and then throws an error. +// This test asserts that the throw frame is remapped to the ORIGINAL source +// (`original.js`) in the archive and that the original source line (with its +// original 4-space indentation) is read back from the VFS. +// +// The fixture's `sea.js.map` is a source-map-v3 identity mapping that is tied +// to the current content of `sea.js` and `original.js`: most lines are mapped +// one-to-one, and the `throw` line maps its column from 2 (the generated +// 2-space indentation) to 4 (the original 4-space indentation). If either +// fixture source is edited, regenerate the map so the columns stay in sync. + +const common = require('../common'); + +const { + buildSEA, + skipIfBuildSEAIsNotSupported, +} = require('../common/sea'); + +skipIfBuildSEAIsNotSupported(); + +const tmpdir = require('../common/tmpdir'); +const { spawnSyncAndAssert } = require('../common/child_process'); +const fixtures = require('../common/fixtures'); +const { createWriteStream } = require('fs'); +const { pipeline } = require('stream/promises'); +const { zipFiles } = require('zlib'); + +// Asserts that the SEA stderr contains a source-mapped stack trace for an +// error thrown in `boom()`. +function assertSourceMappedStderr(stderr) { + // The throw frame must be remapped to the original source in the VFS. + if (!/at boom \(.*\/original\.js:\d+:\d+\)/.test(stderr)) { + throw new Error(`the boom() frame was not source-mapped:\n${stderr}`); + } + // It must not still point at the generated sea.js. + if (/at boom \(.*\/sea\.js:\d+:\d+\)/.test(stderr)) { + throw new Error(`the boom() frame was not remapped to original.js:\n${stderr}`); + } + // The original source line is read from the VFS, so it shows the original + // 4-space indentation (the generated sea.js uses 2 spaces). + if (!/^ {4}throw new Error\('boom from the original source'\);$/m.test(stderr)) { + throw new Error(`the original source line was not read from the VFS:\n${stderr}`); + } +} + +async function main() { + tmpdir.refresh(); + + // Build the assets archive with the ZIP support of node:zlib. This is what + // "vfsArchive" users do themselves before running --build-sea. + const fixture = (...args) => fixtures.path('sea', 'vfs-zip-sourcemap', ...args); + await pipeline( + zipFiles([ + [fixture('sea.js.map'), 'sea.js.map'], + [fixture('original.js'), 'original.js'], + ]), + createWriteStream(tmpdir.resolve('assets.zip')), + ); +} + +main().then(common.mustCall(() => { + const outputFile = buildSEA(fixtures.path('sea', 'vfs-zip-sourcemap')); + + spawnSyncAndAssert( + outputFile, + { + env: { + ...process.env, + NODE_DEBUG_NATIVE: undefined, + }, + }, + { + // The SEA main script throws an uncaught error to produce the + // source-mapped stack trace. + status: 1, + stdout: /source map loaded from the SEA VFS: .*\/original\.js/, + stderr: assertSourceMappedStderr, + }, + ); +}));