doc: how to expose primordials when using --expose-internals

[bmeck]

This exposes primordials as a global property when using --expose-internals.

This allows efforts like #21128 to follow general core robustness using primordials while potentially being developed outside of the core repo itself. Without such a repo using primordials it would not be easy to vendor in while maintaining such rigor without various duplications.

The --expose-internals flag is not currently documented in the main docs and I didn't add a note about this because of that.

[ljharb]

Seems fine; it might be nice to have the primordials exposed as a core module always, too.

[bmeck]

@ljharb primordials are not immune to tampering right now. Would prefer it only be exposed if it couldn't be mutated since the point is to have a robust set of intrinsics (not to have the most modern intrinsics).

[ljharb]

Ah, I’d say that’s a requirement. In that case tho, is it even good to expose them with this flag?

[bmeck]

@ljharb I'd say the benefit of developing internal packages in different repos likely outweighs the problems. Using --expose-internals in general makes core wildly unstable if you start modifying internals that were exposed.

[jasnell]

--expose-internals is problematic on it's own but there's really no great alternative, and it's super useful for testing so I'm +1 on this.

[bmeck]

@jasnell I do think moving --expose-internals to something less likely to cause issues or be exploitable in the wild would best be a different PR.

[jasnell]

Agreed

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/37098/

[aduh95]

FWIW you can achieve this already since 983e922:

node --expose-internals -r internal/test/binding lib/fs.js

Doesn't this cover your use-case already?

[bmeck]

@aduh95 maybe we could just add this to testing docs then?

[aduh95]

@aduh95 maybe we could just add this to testing docs then?

Yes definitely, the fact that you don't know about this shows that it's not documented well enough. Do you want me to open a new PR or would you like to re-purpose this one?

[bmeck]

I can repurpose this one in a bit

[Trott]

Suggested change

	`internalBinding()`. You can do so using
	`internalBinding()`. You can do so using:

[Trott]

LGTM with or without my trivial suggestion.

[bmeck]

updated title

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/37157/

[Trott]

Landed in f52c921.

@bmeck If it saves you a little time in the future, doc-only changes don't need to be run on Jenkins. You can rely on the GitHub Actions results for those. (The one possible exception would be the docs for addons. The C++ code in the examples are extracted and compiled to make sure they are all valid. I'm not sure if that happens on GitHub Actions or not. But everything else...doc-only changes don't need Jenkins.)

[bmeck]

@Trott I tried to re-read collaborator guide for that but guess I missed it.

[Trott]

@Trott I tried to re-read collaborator guide for that but guess I missed it.

Understandable considering how overwhelming the guide is. You are now inspiring me to open a pull request to remove non-essential content.