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.

Sign up for GitHub

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

Jump to bottom

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

Merged
merged 1 commit into from Apr 6, 2021
Merged

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

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.

jasnell
jasnell approved these changes Apr 1, 2021
View reviewed changes
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

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

@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
Trott
Trott reviewed Apr 4, 2021
View reviewed changes
doc/guides/writing-tests.md
@@ -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:

Trott
Trott approved these changes Apr 4, 2021
View reviewed changes
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.

Sign in to view
@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

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

@bmeck @Trott
doc: internal/test/binding for testing
f52c921 
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.

@BethGriggs BethGriggs mentioned this pull request Apr 12, 2021
Merged
targos pushed a commit that referenced this pull request May 30, 2021
@bmeck @targos
doc: internal/test/binding for testing
1a6ba57 
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
@bmeck @targos
doc: internal/test/binding for testing
ae5a519 
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 targos mentioned this pull request Jun 6, 2021
Merged
targos pushed a commit that referenced this pull request Jun 11, 2021
@bmeck @targos
doc: internal/test/binding for testing
c61f363 
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
Reviewers

@jasnell jasnell jasnell approved these changes

@Trott Trott Trott approved these changes

@cjihrig cjihrig cjihrig approved these changes

@aduh95 aduh95 aduh95 approved these changes

@ljharb ljharb Awaiting requested review from ljharb

Assignees
No one assigned
Labels
needs-ci PRs that need a full CI run.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
7 participants
@bmeck @ljharb @jasnell @nodejs-github-bot @aduh95 @Trott @cjihrig