Problems building with `--without-ssl` and openssl-related options in `NODE_OPTIONS`

[jasnell]

Just opening this to not forget.

There are a handful of command line arguments (like --use-openssl-ca) that are only defined when Node.js is being built with openssl enabled. These CLI flags, however, are allowed in NODE_OPTIONS which may be set generally for a user. When NODE_OPTIONS=--use-openssl-ca and we ./configure --without-ssl, the build will fail with an obscure and unhelpful error in the node_mksnapshot step:

FAILED: gen/node_snapshot.cc 
cd ../../; /home/jsnell/projects/node/node/out/Release/node_mksnapshot /home/jsnell/projects/node/node/out/Release/gen/node_snapshot.cc

  #  /home/jsnell/projects/node/node/out/Release/node_mksnapshot[675255]: int BuildSnapshot(int, char **) at ../../tools/snapshot/node_mksnapshot.cc:69
  #  Assertion failed: !result->early_return()

----- Native stack trace -----

 1: 0x5bb18fce856a node::Assert(node::AssertionInfo const&) [/home/jsnell/projects/node/node/out/Release/node_mksnapshot]
 2: 0x5bb18ff5f423 BuildSnapshot(int, char**) [/home/jsnell/projects/node/node/out/Release/node_mksnapshot]
 3: 0x735750429d90  [/lib/x86_64-linux-gnu/libc.so.6]
 4: 0x735750429e40 __libc_start_main [/lib/x86_64-linux-gnu/libc.so.6]
 5: 0x5bb18fd2ef05 _start [/home/jsnell/projects/node/node/out/Release/node_mksnapshot]
Aborted (core dumped)
ninja: build stopped: subcommand failed.
make: *** [Makefile:151: node] Error 1

It's probably a good idea to have node_mksnapshot either ignore NODE_OPTIONS or print more helpful error messages; or, alternatively, allow openssl-related options like --use-openssl-ca to be a defined non-op when building with --without-ssl

/cc @joyeecheung

[joyeecheung]

I think it makes sense to just copy the handling from

node/src/node.cc

Lines 1494 to 1499 in 0bbe7c3

	for (const std::string& error : result->errors()) {
	FPrintF(stderr, "%s: %s\n", result->args().at(0), error);
	}
	if (result->early_return()) {
	return result->exit_code_enum();
	}

over to

node/tools/snapshot/node_mksnapshot.cc

Lines 69 to 70 in c5cfdd4

	CHECK(!result->early_return());
	CHECK_EQ(result->exit_code(), 0);

[jasnell]

Well, that would certainly help but that output still is rather obscure. I think there are several things that would be significant improvements. For one, much of the code around this area is almost entirely undocumented. It's extremely difficult to know what it happening in here and what failure conditions may apply. Failures in the node_mksnapshot process are extremely difficult to debug. Even some basic explanations in the code about what the possible failure conditions are would be helpful, so I think when I'm able to I'll come back and try to add some documentation.

But just in general it is counter-intuitive that the NODE_OPTIONS env var would impact the build of node itself. Would there be any issues with enabling the kDisableNodeOptionsEnv flag when initializing the platform in node_mksnapshot?

[jasnell]

PR: #59437

[joyeecheung]

For one, much of the code around this area is almost entirely undocumented.

Are you looking for https://github.com/nodejs/node/blob/main/tools/snapshot/README.md?

Would there be any issues with enabling the kDisableNodeOptionsEnv flag when initializing the platform in node_mksnapshot?

If this gets serializad into/accessed JS land in anyway, it will be. For example, if the custom snapshot is used and the snapshot script uses the runtime options, or checks https://nodejs.org/api/process.html#processallowednodeenvironmentflags

[joyeecheung]

From #59437, it doesn't look like a bug, more like a DX issue - node_mksnapshot could've printed the errors then exiting more gracefully instead of just asserting and crashing, but since it's a build tool, asserting is also correct, just that the DX is less nice.

As for the documentation, there's already one in https://github.com/nodejs/node/blob/main/tools/snapshot/README.md - not sure how to make that more visible to people looking for documentation, over the last collaboration summit some people suggested to use LLM tools to deal with the "there might have been a documentation, but I don't know how to find it" problem. If you are looking for specific debugging commands, this was documented in src/README.md.

node/src/README.md

Line 531 in 4eeb78b

$ lldb -- out/Release/node_mksnapshot out/Release/gen/node_snapshot.cc

I suggest using this command to look for the documentation, not just for snapshot but it also works for any keyword (personally I use a similar search setting in vscode whenever I try to find docs as well).

grep -rni "snapshot" . --include="*.md" --exclude-dir=deps --exclude-dir=./doc/api --exclude-dir=./doc/changelogs --exclude-dir=out