Skip to content

os: expose guessFileDescriptorType - #58060

Closed
vladfrangu wants to merge 16 commits into
nodejs:mainfrom
vladfrangu:feat/expose-guessHandleType-on-os
Closed

vladfrangu wants to merge 16 commits into
nodejs:mainfrom
vladfrangu:feat/expose-guessHandleType-on-os

Conversation

@vladfrangu

Copy link
Copy Markdown
Contributor

Exposes the internal guessHandleType function, which can be used to see if a handle has a specific type, regardless of the OS it is on.

This helps out with detecting, for example, if standard input is piped into the process, instead of relying on file system calls.

Refs: #57603

@nodejs-github-bot nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. needs-ci PRs that need a full CI run. os Issues and PRs related to the os subsystem. util Issues and PRs related to the built-in util module. labels Apr 28, 2025
Comment thread doc/api/os.md Resolved
Comment thread lib/internal/util.js Resolved
@vladfrangu

Copy link
Copy Markdown
Contributor Author

I'll rebase to fix the first commit message after the CI passes! Should I also squash the PR or leave the rest as is?

@aduh95

aduh95 commented Apr 29, 2025

Copy link
Copy Markdown
Contributor

Should I also squash the PR or leave the rest as is?

As you prefer, in any case it will get squashed upon merging.

@codecov

codecov Bot commented Apr 29, 2025 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 61.53846% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.13%. Comparing base (54b4e37) to head (ad060cc).
⚠️ Report is 1499 commits behind head on main.

Files with missing lines Patch % Lines
src/node_util.cc 0.00% 3 Missing and 1 partial ⚠️
lib/internal/util.js 85.71% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #58060      +/-   ##
==========================================
- Coverage   90.13%   90.13%   -0.01%     
==========================================
  Files         751      751              
  Lines      253635   253643       +8     
  Branches    47786    47798      +12     
==========================================
+ Hits       228615   228621       +6     
- Misses      16268    16270       +2     
  Partials     8752     8752              
Files with missing lines Coverage Δ
lib/os.js 98.61% <100.00%> (+<0.01%) ⬆️
lib/internal/util.js 98.80% <85.71%> (-0.10%) ⬇️
src/node_util.cc 81.15% <0.00%> (-0.24%) ⬇️

... and 24 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@vladfrangu
vladfrangu force-pushed the feat/expose-guessHandleType-on-os branch from b88d406 to f3d0b71 Compare April 29, 2025 15:37
Comment thread doc/api/os.md Outdated
added: REPLACEME
-->

* `handle` {integer} The handle number to try and guess the type of.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This should really specify that "handle" means "file descriptor". In fact, given that the fs docs almost exclusively use "file descriptor" and "fd", I would also adopt that terminology here.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Then I could also rename the function to guessFileDescriptorType? Or should I leave it as is?

And will apply the changes to fd/file descriptor in a few

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Yeah, I'd probably do that. In the context of libuv, guessHandleType makes more sense, because it returns a value that actually corresponds to the types of libuv handles, which wrap around fds.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done! Let me know if I've also done the rebase correctly 🤞

@vladfrangu vladfrangu changed the title os: expose guessHandleType os: expose guessFileDescriptorType May 2, 2025
@vladfrangu
vladfrangu force-pushed the feat/expose-guessHandleType-on-os branch from f3d0b71 to 0c33ea7 Compare May 2, 2025 21:18
@vladfrangu
vladfrangu force-pushed the feat/expose-guessHandleType-on-os branch from 0c33ea7 to 93dc673 Compare May 12, 2025 15:54
Comment thread doc/api/os.md Resolved
Comment thread lib/internal/util.js Resolved
Comment thread lib/os.js Resolved
Comment thread lib/os.js Resolved
Comment thread src/node_util.cc Outdated
proxy->GetTarget(),
proxy->GetHandler()
};
Local<Value> ret[] = {proxy->GetTarget(), proxy->GetHandler()};

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

There are a large number of unrelated changes in here. Were these manually edited or did the format tool do these?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

All of the formatting changes were done by saving the file (after configuring vscode with the settings example provided by the contributing guide). Not sure exactly why so many changes happened, but running the cpp formatter through make also didn't revert it. I can manually revert it if desired

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Please do, making PRs easier to review gives them the best chance to actually land, and it avoids polluting git blame

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

So, I did revert these changes, and staged them, but after running make format-cpp, the file was reformatted to how it is on this PR. I'll push the non-formatted change but not sure if I should open a PR after formatting the file or just leave it be

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yet running CLANG_FORMAT_START=main make format-cpp changes nothing, confusing.. I'll leave that be for now

@vladfrangu
vladfrangu requested a review from jasnell May 16, 2025 07:44
@vladfrangu
vladfrangu force-pushed the feat/expose-guessHandleType-on-os branch from d803730 to 15f0bda Compare June 2, 2025 09:10
@vladfrangu
vladfrangu force-pushed the feat/expose-guessHandleType-on-os branch from 15f0bda to a65ced5 Compare June 20, 2025 13:01
Comment thread doc/api/os.md Outdated
* Returns: {string|null}

Returns the type of the file descriptor passed in, or `null` if the provided file descriptor
is invalid.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Nit: some expanded explanation about why this is useful would probably be helpful. It's rather obscure.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I tried to improve the documentation, but I'm not sure if this is good 😅

Comment thread src/node_util.cc
// For an unhandled handle type, we want to return `UNKNOWN` instead of
// `null` since the type is "known" by UV, just not exposed further to
// JS land
return 5;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Nit... for later... not something to do in this PR... these really ought to be defined in an enum

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I would do it if I knew how 😅, and there is a TODO for that already in the function

Comment thread lib/internal/util.js Resolved
@vladfrangu
vladfrangu force-pushed the feat/expose-guessHandleType-on-os branch from 52dd182 to 520693d Compare April 9, 2026 11:09
@vladfrangu

Copy link
Copy Markdown
Contributor Author

I've rebased the PR, let me know if I should also squash it (for the signed off message) or such 🙏

vladfrangu and others added 14 commits November 18, 2026 17:27
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
Co-authored-by: James M Snell <jasnell@gmail.com>
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
Tested with `require('internal/test/binding').internalBinding('util').guessHandleType(2**31)` (not sure if there was a better way, but it works so)

Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
Invalid file descriptors already throw ERR_INVALID_FD in JS land, so
the native binding can never return null. Restore the CHECK in the
binding, drop the dead fallback and document that the function throws
on invalid input and returns 'UNKNOWN' for descriptors that are not
open.

Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
@vladfrangu
vladfrangu force-pushed the feat/expose-guessHandleType-on-os branch from bc5cabb to c67a781 Compare November 18, 2026 15:31
@vladfrangu

vladfrangu commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Yeah, your agent was accurate. Since I added more assertions on JS side, null is an impossible case now except for direct usage of the cpp binding (so I also reverted part of the changes in node_util.cc)

I'll run tests and linting locally again, but should be good

@vladfrangu

Copy link
Copy Markdown
Contributor Author

Hmm, coverage failing, do I need another rebase or something else? 😓

@github-actions github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Nov 18, 2026
@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

@Renegade334

Copy link
Copy Markdown
Member

Hmm, coverage failing, do I need another rebase or something else? 😓

The GHA failure would be fixed by a rebase, but given there's already a Jenkins run going (and the issues with CI capacity at the moment) I suggest this just be landed manually once Jenkins is green.

@Ethan-Arrowood

Copy link
Copy Markdown
Contributor

CI is all good, I'm going to land this manually now.

Ethan-Arrowood pushed a commit that referenced this pull request Nov 19, 2026
Exposes the internal `guessHandleType` function as
`guessFileDescriptorType`, which can be used to see if a handle has a
specific type, regardless of the OS it is on.

This helps out with detecting, for example, if standard input is piped
into the process, instead of relying on file system calls.

Refs: #57603
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
PR-URL: #58060
Reviewed-By: Ethan Arrowood <ethan@arrowood.dev>
Reviewed-By: Aviv Keller <me@aviv.sh>
@Ethan-Arrowood

Copy link
Copy Markdown
Contributor

Landed in 42800b6

aduh95 pushed a commit that referenced this pull request Nov 20, 2026
Exposes the internal `guessHandleType` function as
`guessFileDescriptorType`, which can be used to see if a handle has a
specific type, regardless of the OS it is on.

This helps out with detecting, for example, if standard input is piped
into the process, instead of relying on file system calls.

Refs: #57603
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
PR-URL: #58060
Reviewed-By: Ethan Arrowood <ethan@arrowood.dev>
Reviewed-By: Aviv Keller <me@aviv.sh>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

c++ Issues and PRs that require attention from people who are familiar with C++. commit-queue-squash PRs the Commit Queue should land as one squashed commit. needs-ci PRs that need a full CI run. os Issues and PRs related to the os subsystem. semver-minor PRs that contain new features and should be released in the next minor version. util Issues and PRs related to the built-in util module.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants