Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions doc/api/single-executable-applications.md
Original file line number Diff line number Diff line change
Expand Up @@ -317,6 +317,75 @@ with `"vfsArchive"`: `--build-sea` rejects it in `"execArgv"`, and the
executable rejects it at startup when it comes from `--node-options` or from
the `execArgv` of a worker.

#### 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 and code caching limitations

`"useVfs": true` cannot be used together with `"useSnapshot": true` or
Expand Down Expand Up @@ -804,10 +873,14 @@ 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
[`module.findSourceMap()`]: module.md#modulefindsourcemappath
[`node:zlib`]: zlib.md
[`process.execPath`]: process.md#processexecpath
[`require()`]: modules.md#requireid
Expand Down
15 changes: 15 additions & 0 deletions test/fixtures/sea/vfs-sourcemap/original.js
Original file line number Diff line number Diff line change
@@ -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();
10 changes: 10 additions & 0 deletions test/fixtures/sea/vfs-sourcemap/sea-config.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
16 changes: 16 additions & 0 deletions test/fixtures/sea/vfs-sourcemap/sea.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 12 additions & 0 deletions test/fixtures/sea/vfs-sourcemap/sea.js.map

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

15 changes: 15 additions & 0 deletions test/fixtures/sea/vfs-zip-sourcemap/original.js
Original file line number Diff line number Diff line change
@@ -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();
7 changes: 7 additions & 0 deletions test/fixtures/sea/vfs-zip-sourcemap/sea-config.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"main": "sea.js",
"output": "sea-prep.blob",
"useVfs": true,
"vfsArchive": "assets.zip",
"execArgv": ["--enable-source-maps"]
}
16 changes: 16 additions & 0 deletions test/fixtures/sea/vfs-zip-sourcemap/sea.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 12 additions & 0 deletions test/fixtures/sea/vfs-zip-sourcemap/sea.js.map

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

71 changes: 71 additions & 0 deletions test/sea/test-single-executable-application-vfs-sourcemap.js
Original file line number Diff line number Diff line change
@@ -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}`);
}
},
},
);
91 changes: 91 additions & 0 deletions test/sea/test-single-executable-application-vfs-zip-sourcemap.js
Original file line number Diff line number Diff line change
@@ -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,
},
);
}));
Loading