lib: expose primordials object

[aduh95]

Provide a way to expose the primordials on the global object. This is useful to run Node.js internals modules to help with Node.js core development.

$ node --expose-internals -r internal/test/binding lib/fs.js
(node:5299) internal/test/binding: These APIs are for internal testing only. Do not use them.
(Use `node --trace-warnings ...` to show where the warning was created)

[devsnek]

Can you move this to lib/internal/test/binding.js? That way we get the warning and it's neatly wrapped up with --expose-internals.

[aduh95]

Can you move this to lib/internal/test/binding.js? That way we get the warning and it's neatly wrapped up with --expose-internals.

@devsnek Note that the current implementation requires to use two flags: --expose-internals and --expose-primordials. You are suggesting to remove --expose-primordials flag and keep --expose-internals only, correct? Or do you mean something else?

[targos]

I don't really like this solution for the referenced issue. The fact that we use built-in functions like Date.now somewhere in core is an implementation detail and should never be relied on by userland modules

[bmeck]

A lot of the purpose in making the slow migration to primordials is exactly to prevent userland mutation of core behaviors through side channels like this. I would be fine exposing primordials somehow since things like the demand to move mime from #21128 relies on being able to use them from a 3rd party. For now it seems the goal of the linked issue is just to alter what the generated Date header is. I think this just means that we need to expose a way to solve that issue, not to make primordials mutable and user accessible.

[bmeck]

primordials was introduced exactly to prevent mutating the internals of node core and to allow robustness in the core. I don't think this approach to solve the referenced issue is the way we should approach it.

[bmeck]

It looks like @sinonjs/fake-timers is in the 4M+ weekly downloads range, I think we should just solve the needed use case as exposing this flag would definitely not be niche in light of that size of usage and thus somewhat invalidate core's robustness goals.

[addaleax]

@bmeck is right – this PR would basically make having primordials pointless (which, yay, I think removing them would be a great idea, but I don’t think that’s happening). However, I’m commenting because I saw the issue title and thought “hey, maybe this is just exposing the deep-frozen object as-is”, which I think I’d like because it would help with Node.js core development (it answers questions like “What is in the primordials object” and “What happens when I run this piece of Node.js core source code”) and wouldn’t really hurt anyone.

[ExE-Boss]

Actually, this won’t work the way it’s intended due to the way the primordials object is used.

---

This is because all code that uses the primordials object destructures the primordials from the primordials object.

[aduh95]

Thank you everyone for the reviews, I've rolled back the "altering primordials" part, this PR is now only exposing the primordials object on the global scope as @addaleax suggested. PTAL.

Note to whoever lands this: the commit message will need to be amended before landing to remove the reference to sinonjs/fake-timers#344.

[bmeck]

I do think we can address the timer issue somewhere else; even if we didn't use primordials, early destructuring would have broken that as well like @ExE-Boss points out.

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[aduh95]

Based on feedback shared by several persons, I've updated this PR to remove the --expose-primordials flag. Instead, this add an export to the existing internal/test/binding module to access the primordials object, and, when the module is preloaded with --require flag, expose the internal objects to the global. PTAL!

The intended use of this feature is to use --expose-internals in conjunction with --require internal/test/binding to be able to run an internal module.

$ node lib/fs.js
…/node/lib/fs.js:51
} = primordials;
    ^

ReferenceError: primordials is not defined
    at Object.<anonymous> (…/node/lib/fs.js:51:5)
    at Module._compile (node:internal/modules/cjs/loader:1108:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1137:10)
    at Module.load (node:internal/modules/cjs/loader:973:32)
    at Function.Module._load (node:internal/modules/cjs/loader:813:14)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:76:12)
    at node:internal/main/run_main_module:17:47
$ node --expose-internals -r internal/test/binding lib/fs.js
(node:5299) internal/test/binding: These APIs are for internal testing only. Do not use them.
(Use `node --trace-warnings ...` to show where the warning was created)

[aduh95]

On a side note, we might want to rename internal/test/binding to something else, but I can't think of a good name. If you have any, please throw them out there :)

[nodejs-github-bot]

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

[mscdex]

Where do we use the --require/global feature? Shouldn't it be enough to require() the internal module from within tests?

[aduh95]

Where do we use the --require/global feature?

Not sure what you mean, module.isPreloading has been introduced in v15.4.0, so it's a rather new pattern.

Shouldn't it be enough to require() the internal module from within tests?

The idea is to give the ability for a node binary to run an internal module without modifying it. require still works as the module still exports the object, and if you prefer to use that, go for it.

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[aduh95]

Landed in 983e922