os: expose guessHandleType

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

Author: vladfrangu

doc/api/os.md

@@ -509,6 +509,48 @@ 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.guessHandleType(handle)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `handle` {integer} The handle number to try and guess the type of.
+
+* Returns: {string}
+
+Returns the type of the handle passed in, or `'INVALID'` if the provided handle
+is invalid.
+
+Currently, the following types for a handle can be returned:
+
+<table>
+  <tr>
+    <th>Constant</th>
+  </tr>
+  <tr>
+    <td><code>TCP</code></td>
+  </tr>
+  <tr>
+    <td><code>TTY</code></td>
+  </tr>
+  <tr>
+    <td><code>UDP</code></td>
+  </tr>
+  <tr>
+    <td><code>FILE</code></td>
+  </tr>
+  <tr>
+    <td><code>PIPE</code></td>
+  </tr>
+  <tr>
+    <td><code>UNKNOWN</code></td>
+  </tr>
+  <tr>
+    <td><code>INVALID</code></td>
+  </tr>
+</table>
+
 ## OS constants
 
 The following constants are exported by `os.constants`.

lib/internal/util.js

@@ -864,6 +864,8 @@ function getCIDR(address, netmask, family) {
 }
 
 const handleTypes = ['TCP', 'TTY', 'UDP', 'FILE', 'PIPE', 'UNKNOWN'];
+handleTypes[-1] = 'INVALID';
+
 function guessHandleType(fd) {
   const type = _guessHandleType(fd);
   return handleTypes[type];

lib/os.js

@@ -39,7 +39,7 @@ const {
   },
   hideStackFrames,
 } = require('internal/errors');
-const { getCIDR } = require('internal/util');
+const { getCIDR, guessHandleType: _guessHandleType } = require('internal/util');
 const { validateInt32 } = require('internal/validators');
 
 const {
@@ -328,6 +328,7 @@ module.exports = {
   uptime: getUptime,
   version: getOSVersion,
   machine: getMachine,
+  guessHandleType: _guessHandleType,
 };
 
 ObjectDefineProperties(module.exports, {

src/node_util.cc

@@ -49,8 +49,7 @@ CHAR_TEST(16, IsUnicodeSurrogate, (ch & 0xF800) == 0xD800)
 // If a UTF-16 surrogate is a low/trailing one.
 CHAR_TEST(16, IsUnicodeSurrogateTrail, (ch & 0x400) != 0)
 
-static void GetOwnNonIndexProperties(
-    const FunctionCallbackInfo<Value>& args) {
+static void GetOwnNonIndexProperties(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   Local<Context> context = env->context();
 
@@ -62,20 +61,20 @@ static void GetOwnNonIndexProperties(
   Local<Array> properties;
 
   PropertyFilter filter =
-    static_cast<PropertyFilter>(args[1].As<Uint32>()->Value());
-
-  if (!object->GetPropertyNames(
-        context, KeyCollectionMode::kOwnOnly,
-        filter,
-        IndexFilter::kSkipIndices)
-          .ToLocal(&properties)) {
+      static_cast<PropertyFilter>(args[1].As<Uint32>()->Value());
+
+  if (!object
+           ->GetPropertyNames(context,
+                              KeyCollectionMode::kOwnOnly,
+                              filter,
+                              IndexFilter::kSkipIndices)
+           .ToLocal(&properties)) {
     return;
   }
   args.GetReturnValue().Set(properties);
 }
 
-static void GetConstructorName(
-    const FunctionCallbackInfo<Value>& args) {
+static void GetConstructorName(const FunctionCallbackInfo<Value>& args) {
   CHECK(args[0]->IsObject());
 
   Local<Object> object = args[0].As<Object>();
@@ -84,8 +83,7 @@ static void GetConstructorName(
   args.GetReturnValue().Set(name);
 }
 
-static void GetExternalValue(
-    const FunctionCallbackInfo<Value>& args) {
+static void GetExternalValue(const FunctionCallbackInfo<Value>& args) {
   CHECK(args[0]->IsExternal());
   Isolate* isolate = args.GetIsolate();
   Local<External> external = args[0].As<External>();
@@ -98,15 +96,14 @@ static void GetExternalValue(
 
 static void GetPromiseDetails(const FunctionCallbackInfo<Value>& args) {
   // Return undefined if it's not a Promise.
-  if (!args[0]->IsPromise())
-    return;
+  if (!args[0]->IsPromise()) return;
 
   auto isolate = args.GetIsolate();
 
   Local<Promise> promise = args[0].As<Promise>();
 
   int state = promise->State();
-  Local<Value> values[2] = { Integer::New(isolate, state) };
+  Local<Value> values[2] = {Integer::New(isolate, state)};
   size_t number_of_values = 1;
   if (state != Promise::PromiseState::kPending)
     values[number_of_values++] = promise->Result();
@@ -116,19 +113,15 @@ static void GetPromiseDetails(const FunctionCallbackInfo<Value>& args) {
 
 static void GetProxyDetails(const FunctionCallbackInfo<Value>& args) {
   // Return undefined if it's not a proxy.
-  if (!args[0]->IsProxy())
-    return;
+  if (!args[0]->IsProxy()) return;
 
   Local<Proxy> proxy = args[0].As<Proxy>();
 
   // TODO(BridgeAR): Remove the length check as soon as we prohibit access to
   // the util binding layer. It's accessed in the wild and `esm` would break in
   // case the check is removed.
   if (args.Length() == 1 || args[1]->IsTrue()) {
-    Local<Value> ret[] = {
-      proxy->GetTarget(),
-      proxy->GetHandler()
-    };
+    Local<Value> ret[] = {proxy->GetTarget(), proxy->GetHandler()};
 
     args.GetReturnValue().Set(
         Array::New(args.GetIsolate(), ret, arraysize(ret)));
@@ -164,22 +157,17 @@ static void GetCallerLocation(const FunctionCallbackInfo<Value>& args) {
 }
 
 static void PreviewEntries(const FunctionCallbackInfo<Value>& args) {
-  if (!args[0]->IsObject())
-    return;
+  if (!args[0]->IsObject()) return;
 
   Environment* env = Environment::GetCurrent(args);
   bool is_key_value;
   Local<Array> entries;
   if (!args[0].As<Object>()->PreviewEntries(&is_key_value).ToLocal(&entries))
     return;
   // Fast path for WeakMap and WeakSet.
-  if (args.Length() == 1)
-    return args.GetReturnValue().Set(entries);
+  if (args.Length() == 1) return args.GetReturnValue().Set(entries);
 
-  Local<Value> ret[] = {
-    entries,
-    Boolean::New(env->isolate(), is_key_value)
-  };
+  Local<Value> ret[] = {entries, Boolean::New(env->isolate(), is_key_value)};
   return args.GetReturnValue().Set(
       Array::New(env->isolate(), ret, arraysize(ret)));
 }
@@ -216,15 +204,25 @@ static uint32_t GetUVHandleTypeCode(const uv_handle_type type) {
     case UV_UNKNOWN_HANDLE:
       return 5;
     default:
-      ABORT();
+      // For an unhandled handle type, we want to return `UNKNOWN` instead of
+      // `INVALID` since the type is "known" by UV, just not exposed further to
+      // JS land
+      return 5;
   }
 }
 
 static void GuessHandleType(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
+
   int fd;
   if (!args[0]->Int32Value(env->context()).To(&fd)) return;
-  CHECK_GE(fd, 0);
+
+  // If the provided file descriptor is not valid, we return `-1`, which in JS
+  // land will be marked as "INVALID"
+  if (fd < 0) [[unlikely]] {
+    args.GetReturnValue().Set(-1);
+    return;
+  }
 
   uv_handle_type t = uv_guess_handle(fd);
   args.GetReturnValue().Set(GetUVHandleTypeCode(t));