Commit 42800b60d33 for nodejs
commit 42800b60d33ffa7c8331307418272bdda63fbc5f
Author: Vlad Frangu <me@vladfrangu.dev>
Date: Mon Apr 28 10:51:26 2025 +0300
os: expose `guessFileDescriptorType`
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: https://github.com/nodejs/node/issues/57603
Signed-off-by: Vlad Frangu <me@vladfrangu.dev>
PR-URL: https://github.com/nodejs/node/pull/58060
Reviewed-By: Ethan Arrowood <ethan@arrowood.dev>
Reviewed-By: Aviv Keller <me@aviv.sh>
diff --git a/doc/api/os.md b/doc/api/os.md
index a2592a2f20c..dca23066974 100644
--- a/doc/api/os.md
+++ b/doc/api/os.md
@@ -504,6 +504,33 @@ On POSIX systems, the operating system release is determined by calling
available, `GetVersionExW()` will be used. See
<https://en.wikipedia.org/wiki/Uname#Examples> for more information.
+## `os.guessFileDescriptorType(fd)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `fd` {integer} The file descriptor number to try and guess the type of.
+
+* Returns: {string}
+
+Returns the type of the file descriptor passed in. If `fd` is not a non-negative
+32-bit integer, an [`ERR_INVALID_FD`][] error is thrown. If `fd` does not refer
+to an open file descriptor, `'UNKNOWN'` is returned.
+A common use case for this function is checking whether standard input is passed into your process,
+and if it is, if it can be consumed by the process. For example, on Unix systems, if the type is `TTY`, it means
+you can prompt the user for new data while the process is running, and if it's `FILE` or `PIPE`, it means there is data
+available, but you shouldn't try to prompt for more.
+
+Currently, the following types for a file descriptor can be returned:
+
+* `'TCP'`
+* `'TTY'`
+* `'UDP'`
+* `'FILE'`
+* `'PIPE'`
+* `'UNKNOWN'`
+
## OS constants
The following constants are exported by `os.constants`.
@@ -1370,6 +1397,7 @@ The following process scheduling constants are exported by
[Android building]: https://github.com/nodejs/node/blob/HEAD/BUILDING.md#android
[EUID]: https://en.wikipedia.org/wiki/User_identifier#Effective_user_ID
+[`ERR_INVALID_FD`]: errors.md#err_invalid_fd
[`SystemError`]: errors.md#class-systemerror
[`process.arch`]: process.md#processarch
[`process.platform`]: process.md#processplatform
diff --git a/lib/internal/util.js b/lib/internal/util.js
index 81aa9f6f45d..57da765aac7 100644
--- a/lib/internal/util.js
+++ b/lib/internal/util.js
@@ -50,6 +50,7 @@ const {
const {
codes: {
+ ERR_INVALID_FD,
ERR_NO_CRYPTO,
ERR_NO_TYPESCRIPT,
ERR_UNKNOWN_SIGNAL,
@@ -861,7 +862,12 @@ function getCIDR(address, netmask, family) {
}
const handleTypes = ['TCP', 'TTY', 'UDP', 'FILE', 'PIPE', 'UNKNOWN'];
+
function guessHandleType(fd) {
+ if (typeof fd !== 'number' || fd >> 0 !== fd || fd < 0) {
+ throw new ERR_INVALID_FD(fd);
+ }
+
const type = _guessHandleType(fd);
return handleTypes[type];
}
diff --git a/lib/os.js b/lib/os.js
index 5e53879bd6d..34b228c4edb 100644
--- a/lib/os.js
+++ b/lib/os.js
@@ -40,7 +40,7 @@ const {
},
hideStackFrames,
} = require('internal/errors');
-const { getCIDR } = require('internal/util');
+const { getCIDR, guessHandleType: guessFileDescriptorType } = require('internal/util');
const { validateInt32 } = require('internal/validators');
const {
@@ -329,6 +329,7 @@ module.exports = {
uptime: getUptime,
version: getOSVersion,
machine: getMachine,
+ guessFileDescriptorType,
};
ObjectFreeze(constants.signals);
diff --git a/src/node_util.cc b/src/node_util.cc
index a8f4188b4db..f49c3414d10 100644
--- a/src/node_util.cc
+++ b/src/node_util.cc
@@ -209,7 +209,9 @@ static uint32_t GetUVHandleTypeCode(const uv_handle_type type) {
case UV_UNKNOWN_HANDLE:
return 5;
default:
- ABORT();
+ // The type is known by libuv, just not exposed to JS land, so report it
+ // as `UNKNOWN`.
+ return 5;
}
}
diff --git a/test/pseudo-tty/test-os-guessFileDescriptorType.js b/test/pseudo-tty/test-os-guessFileDescriptorType.js
new file mode 100644
index 00000000000..0efb4780aa9
--- /dev/null
+++ b/test/pseudo-tty/test-os-guessFileDescriptorType.js
@@ -0,0 +1,28 @@
+'use strict';
+
+require('../common');
+const assert = require('node:assert');
+const { guessFileDescriptorType } = require('os');
+
+assert.strictEqual(guessFileDescriptorType(0), 'TTY');
+assert.strictEqual(guessFileDescriptorType(1), 'TTY');
+assert.strictEqual(guessFileDescriptorType(2), 'TTY');
+
+assert.strictEqual(guessFileDescriptorType(55555), 'UNKNOWN');
+assert.strictEqual(guessFileDescriptorType(2 ** 31 - 1), 'UNKNOWN');
+
+[
+ -1,
+ 1.1,
+ '1',
+ [],
+ {},
+ () => {},
+ 2 ** 31,
+ true,
+ false,
+ 1n,
+ Symbol(),
+ undefined,
+ null,
+].forEach((val) => assert.throws(() => guessFileDescriptorType(val), { code: 'ERR_INVALID_FD' }));
diff --git a/test/pseudo-tty/test-os-guessFileDescriptorType.out b/test/pseudo-tty/test-os-guessFileDescriptorType.out
new file mode 100644
index 00000000000..e69de29bb2d