Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Apr 6, 2021

Conversation

bmeck
Copy link
Member

@bmeck bmeck commented Apr 1, 2021

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.

@bmeck bmeck requested review from ljharb and jasnell April 1, 2021 15:06
@nodejs-github-bot nodejs-github-bot added the needs-ci PRs that need a full CI run. label Apr 1, 2021
@ljharb
Copy link
Member

ljharb commented Apr 1, 2021

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

@bmeck
Copy link
Member Author

bmeck commented Apr 1, 2021

@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
Copy link
Member

ljharb commented Apr 1, 2021

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

@bmeck
Copy link
Member Author

bmeck commented Apr 1, 2021

@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.

Copy link
Member

@jasnell jasnell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--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
Copy link
Member Author

bmeck commented Apr 1, 2021

@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
Copy link
Member

jasnell commented Apr 1, 2021

Agreed

@nodejs-github-bot
Copy link
Collaborator

@aduh95
Copy link
Contributor

aduh95 commented Apr 1, 2021

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
Copy link
Member Author

bmeck commented Apr 2, 2021

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

@aduh95
Copy link
Contributor

aduh95 commented Apr 2, 2021

@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
Copy link
Member Author

bmeck commented Apr 2, 2021

I can repurpose this one in a bit

@bmeck bmeck force-pushed the expose-internals-primordials branch from efb5dd8 to 2facf36 Compare April 2, 2021 19:26
@bmeck bmeck requested a review from aduh95 April 2, 2021 19:26
@@ -286,6 +286,15 @@ const assert = require('assert');
const freelist = require('internal/freelist');
```

In specific scenarios it may be useful to get a hold of `primordials` or
`internalBinding()`. You can do so using
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

@Trott Trott left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM with or without my trivial suggestion.

@ljharb

This comment has been minimized.

@bmeck bmeck changed the title lib: expose primordials when using --expose-internals doc: how to expose primordials when using --expose-internals Apr 5, 2021
@bmeck
Copy link
Member Author

bmeck commented Apr 5, 2021

updated title

@nodejs-github-bot
Copy link
Collaborator

PR-URL: nodejs#38026
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
@Trott Trott force-pushed the expose-internals-primordials branch from 2facf36 to f52c921 Compare April 6, 2021 01:14
@Trott Trott merged commit f52c921 into nodejs:master Apr 6, 2021
@Trott
Copy link
Member

Trott commented Apr 6, 2021

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
Copy link
Member Author

bmeck commented Apr 6, 2021

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

@Trott
Copy link
Member

Trott commented Apr 6, 2021

@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.

targos pushed a commit that referenced this pull request May 30, 2021
PR-URL: #38026
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
targos pushed a commit that referenced this pull request Jun 5, 2021
PR-URL: #38026
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
targos pushed a commit that referenced this pull request Jun 11, 2021
PR-URL: #38026
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
@bmeck bmeck deleted the expose-internals-primordials branch February 3, 2022 21:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
needs-ci PRs that need a full CI run.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants