fs: add windowsHandle option to file streams

Fixes: #57288
Signed-off-by: PickBas <sayed.kirill@gmail.com>
PR-URL: #63851
Reviewed-By: Stefan Stojanovic <stefan.stojanovic@janeasystems.com>

Author: PickBas

doc/api/fs.md

@@ -2933,6 +2933,9 @@ behavior is similar to `cp dir1/ dir2/`.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v16.10.0
  pr-url: https://github.com/nodejs/node/pull/40013
  description: The `fs` option does not need `open` method if an `fd` was provided.
@@ -2989,6 +2992,8 @@ changes:
  * `highWaterMark` {integer} **Default:** `64 * 1024`
  * `fs` {Object|null} **Default:** `null`
  * `signal` {AbortSignal|null} **Default:** `null`
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to read from, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.ReadStream}
 
 `options` can include `start` and `end` values to read a range of bytes from
@@ -3009,6 +3014,12 @@ If `fd` points to a character device that only supports blocking reads
 available. This can prevent the process from exiting and the stream from
 closing naturally.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 
@@ -3059,6 +3070,9 @@ If `options` is a string, then it specifies the encoding.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v22.0.0
  pr-url: https://github.com/nodejs/node/pull/52037
  description: bump default highWaterMark.
@@ -3123,6 +3137,8 @@ changes:
  [`stream.getDefaultHighWaterMark()`][].
  * `flush` {boolean} If `true`, the underlying file descriptor is flushed
  prior to closing it. **Default:** `false`.
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to write to, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.WriteStream}
 
 `options` may also include a `start` option to allow writing data at some
@@ -3137,6 +3153,12 @@ then the file descriptor won't be closed, even if there's an error.
 It is the application's responsibility to close it and make sure there's no
 file descriptor leak.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 

lib/internal/fs/streams.js

@@ -13,13 +13,17 @@ const {
 }=primordials;
 
 const{
+ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
+ERR_INCOMPATIBLE_OPTION_PAIR,
 ERR_INVALID_ARG_TYPE,
 ERR_METHOD_NOT_IMPLEMENTED,
+ERR_MISSING_OPTION,
 ERR_OUT_OF_RANGE,
 ERR_STREAM_DESTROYED,
 ERR_SYSTEM_ERROR,
 }=require('internal/errors').codes;
 const{
+ isWindows,
  kEmptyObject,
 }=require('internal/util');
 const{
@@ -40,6 +44,8 @@ const {
 }=require('internal/fs/utils');
 const{ Readable, Writable, finished }=require('stream');
 const{ toPathIfFileURL }=require('internal/url');
+constbinding=internalBinding('fs');
+const{O_RDONLY,O_WRONLY}=internalBinding('constants').fs;
 constkIoDone=Symbol('kIoDone');
 constkIsPerformingIO=Symbol('kIsPerformingIO');
 
@@ -160,6 +166,26 @@ function importFd(stream, options) {
 ['number','FileHandle'],options.fd);
 }
 
+functionimportWindowsHandle(stream,options,flags){
+if(options.windowsHandle==null){
+thrownewERR_MISSING_OPTION('options.windowsHandle');
+}
+if(!isWindows){
+thrownewERR_FEATURE_UNAVAILABLE_ON_PLATFORM('windowsHandle');
+}
+if(options.fs){
+// The HANDLE is wrapped using the real filesystem, so a custom fs
+// implementation cannot be combined with it.
+thrownewERR_METHOD_NOT_IMPLEMENTED('windowsHandle with fs');
+}
+if(typeofoptions.windowsHandle!=='bigint'){
+thrownewERR_INVALID_ARG_TYPE('options.windowsHandle','bigint',
+options.windowsHandle);
+}
+stream[kFs]=fs;
+returnbinding.handleToFd(options.windowsHandle,flags);
+}
+
 functionReadStream(path,options){
 if(!(thisinstanceofReadStream))
 returnnewReadStream(path,options);
@@ -173,7 +199,11 @@ function ReadStream(path, options) {
 options.autoDestroy=false;
 }
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_RDONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');
@@ -325,7 +355,11 @@ function WriteStream(path, options) {
 // Only buffers are supported.
 options.decodeStrings=true;
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_WRONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');

src/node_file.cc

@@ -4150,6 +4150,33 @@ InternalFieldInfoBase* BindingData::Serialize(int index) {
 return info;
 }
 
+#ifdef _WIN32
+staticvoidHandleToFd(const FunctionCallbackInfo<Value>& args) {
+ Environment* env = Environment::GetCurrent(args);
+CHECK_GE(args.Length(), 1);
+CHECK(args[0]->IsBigInt());
+
+int flags = 0;
+if (args[1]->IsNumber()) {
+ flags = args[1].As<Int32>()->Value();
+ }
+
+bool lossless;
+int64_t handle = args[0].As<BigInt>()->Int64Value(&lossless);
+if (!lossless) {
+returnTHROW_ERR_OUT_OF_RANGE(env,
+"windowsHandle does not fit into 64 bits");
+ }
+intptr_t value = static_cast<intptr_t>(handle);
+
+int fd = _open_osfhandle(value, flags);
+if (fd == -1) {
+return env->ThrowErrnoException(errno, "_open_osfhandle");
+ }
+ args.GetReturnValue().Set(fd);
+}
+#endif// _WIN32
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
@@ -4216,6 +4243,10 @@ static void CreatePerIsolateProperties(IsolateData* isolate_data,
 
 SetMethod(isolate, target, "mkdtemp", Mkdtemp);
 
+#ifdef _WIN32
+SetMethod(isolate, target, "handleToFd", HandleToFd);
+#endif
+
 SetMethod(isolate, target, "cpSyncCheckPaths", CpSyncCheckPaths);
 SetMethod(isolate, target, "cpSyncOverrideFile", CpSyncOverrideFile);
 SetMethod(isolate, target, "cpSyncCopyDir", CpSyncCopyDir);
@@ -4343,6 +4374,9 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
  registry->Register(LUTimes);
 
  registry->Register(Mkdtemp);
+#ifdef _WIN32
+ registry->Register(HandleToFd);
+#endif
  registry->Register(NewFSReqCallback);
 
  registry->Register(FileHandle::New);

test/addons/fs-windows-handle/binding.cc

@@ -0,0 +1,62 @@
+#include<node.h>
+#include<v8.h>
+
+#ifdef _WIN32
+#include<windows.h>
+#endif
+
+namespace {
+
+using v8::BigInt;
+using v8::Context;
+using v8::FunctionCallbackInfo;
+using v8::Isolate;
+using v8::Local;
+using v8::Object;
+using v8::String;
+using v8::Value;
+
+// Creates an anonymous pipe and returns its raw Win32 read/write HANDLE values
+// as JS bigints. These are NOT CRT file descriptors, so passing them as the
+// `windowsHandle` stream option exercises the HANDLE -> fd conversion path on
+// Windows. Returns undefined on other platforms.
+voidCreatePipeHandles(const FunctionCallbackInfo<Value>& args) {
+ Isolate* isolate = args.GetIsolate();
+#ifdef _WIN32
+ Local<Context> context = isolate->GetCurrentContext();
+
+HANDLE read_handle = nullptr;
+HANDLE write_handle = nullptr;
+if (!CreatePipe(&read_handle, &write_handle, nullptr, 0)) {
+ isolate->ThrowException(v8::Exception::Error(
+String::NewFromUtf8(isolate, "CreatePipe failed").ToLocalChecked()));
+return;
+ }
+
+ Local<Object> result = Object::New(isolate);
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "readHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(read_handle))))
+ .Check();
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "writeHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(write_handle))))
+ .Check();
+ args.GetReturnValue().Set(result);
+#else
+ args.GetReturnValue().SetUndefined();
+#endif
+}
+
+} // anonymous namespace
+
+extern"C"NODE_MODULE_EXPORTvoidNODE_MODULE_INITIALIZER(
+ Local<Object> exports, Local<Value> module, Local<Context> context) {
+NODE_SET_METHOD(exports, "createPipeHandles", CreatePipeHandles);
+}

test/addons/fs-windows-handle/binding.gyp

@@ -0,0 +1,9 @@
+{
+'targets': [
+ {
+'target_name': 'binding',
+'sources': [ 'binding.cc' ],
+'includes': ['../common.gypi'],
+ },
+ ]
+}

test/addons/fs-windows-handle/test.js

@@ -0,0 +1,35 @@
+'use strict';
+// Verifies that fs.createReadStream()/createWriteStream() accept a raw Win32
+// HANDLE through the `windowsHandle` option, as happens when a parent process
+// passes an inherited anonymous pipe handle. The addon produces such handles
+// via CreatePipe(); Node must wrap them in CRT file descriptors instead of
+// failing with EBADF.
+
+constcommon=require('../../common');
+
+if(!common.isWindows){
+common.skip('windowsHandle is Windows-only');
+}
+
+constassert=require('assert');
+constfs=require('fs');
+
+constbinding=require(`./build/${common.buildType}/binding`);
+
+const{ readHandle, writeHandle }=binding.createPipeHandles();
+assert.strictEqual(typeofreadHandle,'bigint');
+assert.strictEqual(typeofwriteHandle,'bigint');
+
+constpayload='payload';
+
+constchunks=[];
+constrs=fs.createReadStream(null,{windowsHandle: readHandle});
+rs.on('error',(err)=>assert.fail(err));
+rs.on('data',(chunk)=>chunks.push(chunk));
+rs.on('end',common.mustCall(()=>{
+assert.strictEqual(Buffer.concat(chunks).toString(),payload);
+}));
+
+constws=fs.createWriteStream(null,{windowsHandle: writeHandle});
+ws.on('error',(err)=>assert.fail(err));
+ws.end(payload);

test/parallel/test-fs-stream-windows-handle.js

@@ -0,0 +1,47 @@
+'use strict';
+
+// Tests option validation for the `windowsHandle` option of
+// fs.createReadStream()/createWriteStream(). The functional round-trip on
+// Windows (where a real Win32 HANDLE is wrapped in a file descriptor) is
+// covered by test/addons/fs-windows-handle.
+
+constcommon=require('../common');
+constassert=require('assert');
+constfs=require('fs');
+
+consthandle=1n;
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle,fd: 2}),{
+code: 'ERR_INCOMPATIBLE_OPTION_PAIR',
+});
+}
+
+if(!common.isWindows){
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle}),{
+code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
+});
+}
+return;
+}
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+// Cannot be combined with a custom `fs` implementation.
+assert.throws(()=>create(null,{windowsHandle: handle,fs: {}}),{
+code: 'ERR_METHOD_NOT_IMPLEMENTED',
+});
+
+// Must be a bigint.
+assert.throws(()=>create(null,{windowsHandle: 'nope'}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+assert.throws(()=>create(null,{windowsHandle: 1}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+
+// Must fit into 64 bits.
+assert.throws(()=>create(null,{windowsHandle: 2n**64n}),{
+code: 'ERR_OUT_OF_RANGE',
+});
+}

doc/api/fs.md

@@ -2933,6 +2933,9 @@ behavior is similar to `cp dir1/ dir2/`.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v16.10.0
  pr-url: https://github.com/nodejs/node/pull/40013
  description: The `fs` option does not need `open` method if an `fd` was provided.
@@ -2989,6 +2992,8 @@ changes:
  * `highWaterMark` {integer} **Default:** `64 * 1024`
  * `fs` {Object|null} **Default:** `null`
  * `signal` {AbortSignal|null} **Default:** `null`
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to read from, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.ReadStream}
 
 `options` can include `start` and `end` values to read a range of bytes from
@@ -3009,6 +3014,12 @@ If `fd` points to a character device that only supports blocking reads
 available. This can prevent the process from exiting and the stream from
 closing naturally.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 
@@ -3059,6 +3070,9 @@ If `options` is a string, then it specifies the encoding.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v22.0.0
  pr-url: https://github.com/nodejs/node/pull/52037
  description: bump default highWaterMark.
@@ -3123,6 +3137,8 @@ changes:
  [`stream.getDefaultHighWaterMark()`][].
  * `flush` {boolean} If `true`, the underlying file descriptor is flushed
  prior to closing it. **Default:** `false`.
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to write to, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.WriteStream}
 
 `options` may also include a `start` option to allow writing data at some
@@ -3137,6 +3153,12 @@ then the file descriptor won't be closed, even if there's an error.
 It is the application's responsibility to close it and make sure there's no
 file descriptor leak.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 

lib/internal/fs/streams.js

@@ -13,13 +13,17 @@ const {
 }=primordials;
 
 const{
+ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
+ERR_INCOMPATIBLE_OPTION_PAIR,
 ERR_INVALID_ARG_TYPE,
 ERR_METHOD_NOT_IMPLEMENTED,
+ERR_MISSING_OPTION,
 ERR_OUT_OF_RANGE,
 ERR_STREAM_DESTROYED,
 ERR_SYSTEM_ERROR,
 }=require('internal/errors').codes;
 const{
+ isWindows,
  kEmptyObject,
 }=require('internal/util');
 const{
@@ -40,6 +44,8 @@ const {
 }=require('internal/fs/utils');
 const{ Readable, Writable, finished }=require('stream');
 const{ toPathIfFileURL }=require('internal/url');
+constbinding=internalBinding('fs');
+const{O_RDONLY,O_WRONLY}=internalBinding('constants').fs;
 constkIoDone=Symbol('kIoDone');
 constkIsPerformingIO=Symbol('kIsPerformingIO');
 
@@ -160,6 +166,26 @@ function importFd(stream, options) {
 ['number','FileHandle'],options.fd);
 }
 
+functionimportWindowsHandle(stream,options,flags){
+if(options.windowsHandle==null){
+thrownewERR_MISSING_OPTION('options.windowsHandle');
+}
+if(!isWindows){
+thrownewERR_FEATURE_UNAVAILABLE_ON_PLATFORM('windowsHandle');
+}
+if(options.fs){
+// The HANDLE is wrapped using the real filesystem, so a custom fs
+// implementation cannot be combined with it.
+thrownewERR_METHOD_NOT_IMPLEMENTED('windowsHandle with fs');
+}
+if(typeofoptions.windowsHandle!=='bigint'){
+thrownewERR_INVALID_ARG_TYPE('options.windowsHandle','bigint',
+options.windowsHandle);
+}
+stream[kFs]=fs;
+returnbinding.handleToFd(options.windowsHandle,flags);
+}
+
 functionReadStream(path,options){
 if(!(thisinstanceofReadStream))
 returnnewReadStream(path,options);
@@ -173,7 +199,11 @@ function ReadStream(path, options) {
 options.autoDestroy=false;
 }
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_RDONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');
@@ -325,7 +355,11 @@ function WriteStream(path, options) {
 // Only buffers are supported.
 options.decodeStrings=true;
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_WRONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');

src/node_file.cc

@@ -4150,6 +4150,33 @@ InternalFieldInfoBase* BindingData::Serialize(int index) {
 return info;
 }
 
+#ifdef _WIN32
+staticvoidHandleToFd(const FunctionCallbackInfo<Value>& args) {
+ Environment* env = Environment::GetCurrent(args);
+CHECK_GE(args.Length(), 1);
+CHECK(args[0]->IsBigInt());
+
+int flags = 0;
+if (args[1]->IsNumber()) {
+ flags = args[1].As<Int32>()->Value();
+ }
+
+bool lossless;
+int64_t handle = args[0].As<BigInt>()->Int64Value(&lossless);
+if (!lossless) {
+returnTHROW_ERR_OUT_OF_RANGE(env,
+"windowsHandle does not fit into 64 bits");
+ }
+intptr_t value = static_cast<intptr_t>(handle);
+
+int fd = _open_osfhandle(value, flags);
+if (fd == -1) {
+return env->ThrowErrnoException(errno, "_open_osfhandle");
+ }
+ args.GetReturnValue().Set(fd);
+}
+#endif// _WIN32
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
@@ -4216,6 +4243,10 @@ static void CreatePerIsolateProperties(IsolateData* isolate_data,
 
 SetMethod(isolate, target, "mkdtemp", Mkdtemp);
 
+#ifdef _WIN32
+SetMethod(isolate, target, "handleToFd", HandleToFd);
+#endif
+
 SetMethod(isolate, target, "cpSyncCheckPaths", CpSyncCheckPaths);
 SetMethod(isolate, target, "cpSyncOverrideFile", CpSyncOverrideFile);
 SetMethod(isolate, target, "cpSyncCopyDir", CpSyncCopyDir);
@@ -4343,6 +4374,9 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
  registry->Register(LUTimes);
 
  registry->Register(Mkdtemp);
+#ifdef _WIN32
+ registry->Register(HandleToFd);
+#endif
  registry->Register(NewFSReqCallback);
 
  registry->Register(FileHandle::New);

test/addons/fs-windows-handle/binding.cc

@@ -0,0 +1,62 @@
+#include<node.h>
+#include<v8.h>
+
+#ifdef _WIN32
+#include<windows.h>
+#endif
+
+namespace {
+
+using v8::BigInt;
+using v8::Context;
+using v8::FunctionCallbackInfo;
+using v8::Isolate;
+using v8::Local;
+using v8::Object;
+using v8::String;
+using v8::Value;
+
+// Creates an anonymous pipe and returns its raw Win32 read/write HANDLE values
+// as JS bigints. These are NOT CRT file descriptors, so passing them as the
+// `windowsHandle` stream option exercises the HANDLE -> fd conversion path on
+// Windows. Returns undefined on other platforms.
+voidCreatePipeHandles(const FunctionCallbackInfo<Value>& args) {
+ Isolate* isolate = args.GetIsolate();
+#ifdef _WIN32
+ Local<Context> context = isolate->GetCurrentContext();
+
+HANDLE read_handle = nullptr;
+HANDLE write_handle = nullptr;
+if (!CreatePipe(&read_handle, &write_handle, nullptr, 0)) {
+ isolate->ThrowException(v8::Exception::Error(
+String::NewFromUtf8(isolate, "CreatePipe failed").ToLocalChecked()));
+return;
+ }
+
+ Local<Object> result = Object::New(isolate);
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "readHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(read_handle))))
+ .Check();
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "writeHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(write_handle))))
+ .Check();
+ args.GetReturnValue().Set(result);
+#else
+ args.GetReturnValue().SetUndefined();
+#endif
+}
+
+} // anonymous namespace
+
+extern"C"NODE_MODULE_EXPORTvoidNODE_MODULE_INITIALIZER(
+ Local<Object> exports, Local<Value> module, Local<Context> context) {
+NODE_SET_METHOD(exports, "createPipeHandles", CreatePipeHandles);
+}

test/addons/fs-windows-handle/binding.gyp

@@ -0,0 +1,9 @@
+{
+'targets': [
+ {
+'target_name': 'binding',
+'sources': [ 'binding.cc' ],
+'includes': ['../common.gypi'],
+ },
+ ]
+}

test/addons/fs-windows-handle/test.js

@@ -0,0 +1,35 @@
+'use strict';
+// Verifies that fs.createReadStream()/createWriteStream() accept a raw Win32
+// HANDLE through the `windowsHandle` option, as happens when a parent process
+// passes an inherited anonymous pipe handle. The addon produces such handles
+// via CreatePipe(); Node must wrap them in CRT file descriptors instead of
+// failing with EBADF.
+
+constcommon=require('../../common');
+
+if(!common.isWindows){
+common.skip('windowsHandle is Windows-only');
+}
+
+constassert=require('assert');
+constfs=require('fs');
+
+constbinding=require(`./build/${common.buildType}/binding`);
+
+const{ readHandle, writeHandle }=binding.createPipeHandles();
+assert.strictEqual(typeofreadHandle,'bigint');
+assert.strictEqual(typeofwriteHandle,'bigint');
+
+constpayload='payload';
+
+constchunks=[];
+constrs=fs.createReadStream(null,{windowsHandle: readHandle});
+rs.on('error',(err)=>assert.fail(err));
+rs.on('data',(chunk)=>chunks.push(chunk));
+rs.on('end',common.mustCall(()=>{
+assert.strictEqual(Buffer.concat(chunks).toString(),payload);
+}));
+
+constws=fs.createWriteStream(null,{windowsHandle: writeHandle});
+ws.on('error',(err)=>assert.fail(err));
+ws.end(payload);

test/parallel/test-fs-stream-windows-handle.js

@@ -0,0 +1,47 @@
+'use strict';
+
+// Tests option validation for the `windowsHandle` option of
+// fs.createReadStream()/createWriteStream(). The functional round-trip on
+// Windows (where a real Win32 HANDLE is wrapped in a file descriptor) is
+// covered by test/addons/fs-windows-handle.
+
+constcommon=require('../common');
+constassert=require('assert');
+constfs=require('fs');
+
+consthandle=1n;
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle,fd: 2}),{
+code: 'ERR_INCOMPATIBLE_OPTION_PAIR',
+});
+}
+
+if(!common.isWindows){
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle}),{
+code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
+});
+}
+return;
+}
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+// Cannot be combined with a custom `fs` implementation.
+assert.throws(()=>create(null,{windowsHandle: handle,fs: {}}),{
+code: 'ERR_METHOD_NOT_IMPLEMENTED',
+});
+
+// Must be a bigint.
+assert.throws(()=>create(null,{windowsHandle: 'nope'}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+assert.throws(()=>create(null,{windowsHandle: 1}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+
+// Must fit into 64 bits.
+assert.throws(()=>create(null,{windowsHandle: 2n**64n}),{
+code: 'ERR_OUT_OF_RANGE',
+});
+}

doc/api/fs.md

@@ -2933,6 +2933,9 @@ behavior is similar to `cp dir1/ dir2/`.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v16.10.0
  pr-url: https://github.com/nodejs/node/pull/40013
  description: The `fs` option does not need `open` method if an `fd` was provided.
@@ -2989,6 +2992,8 @@ changes:
  * `highWaterMark` {integer} **Default:** `64 * 1024`
  * `fs` {Object|null} **Default:** `null`
  * `signal` {AbortSignal|null} **Default:** `null`
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to read from, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.ReadStream}
 
 `options` can include `start` and `end` values to read a range of bytes from
@@ -3009,6 +3014,12 @@ If `fd` points to a character device that only supports blocking reads
 available. This can prevent the process from exiting and the stream from
 closing naturally.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 
@@ -3059,6 +3070,9 @@ If `options` is a string, then it specifies the encoding.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v22.0.0
  pr-url: https://github.com/nodejs/node/pull/52037
  description: bump default highWaterMark.
@@ -3123,6 +3137,8 @@ changes:
  [`stream.getDefaultHighWaterMark()`][].
  * `flush` {boolean} If `true`, the underlying file descriptor is flushed
  prior to closing it. **Default:** `false`.
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to write to, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.WriteStream}
 
 `options` may also include a `start` option to allow writing data at some
@@ -3137,6 +3153,12 @@ then the file descriptor won't be closed, even if there's an error.
 It is the application's responsibility to close it and make sure there's no
 file descriptor leak.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 

lib/internal/fs/streams.js

@@ -13,13 +13,17 @@ const {
 }=primordials;
 
 const{
+ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
+ERR_INCOMPATIBLE_OPTION_PAIR,
 ERR_INVALID_ARG_TYPE,
 ERR_METHOD_NOT_IMPLEMENTED,
+ERR_MISSING_OPTION,
 ERR_OUT_OF_RANGE,
 ERR_STREAM_DESTROYED,
 ERR_SYSTEM_ERROR,
 }=require('internal/errors').codes;
 const{
+ isWindows,
  kEmptyObject,
 }=require('internal/util');
 const{
@@ -40,6 +44,8 @@ const {
 }=require('internal/fs/utils');
 const{ Readable, Writable, finished }=require('stream');
 const{ toPathIfFileURL }=require('internal/url');
+constbinding=internalBinding('fs');
+const{O_RDONLY,O_WRONLY}=internalBinding('constants').fs;
 constkIoDone=Symbol('kIoDone');
 constkIsPerformingIO=Symbol('kIsPerformingIO');
 
@@ -160,6 +166,26 @@ function importFd(stream, options) {
 ['number','FileHandle'],options.fd);
 }
 
+functionimportWindowsHandle(stream,options,flags){
+if(options.windowsHandle==null){
+thrownewERR_MISSING_OPTION('options.windowsHandle');
+}
+if(!isWindows){
+thrownewERR_FEATURE_UNAVAILABLE_ON_PLATFORM('windowsHandle');
+}
+if(options.fs){
+// The HANDLE is wrapped using the real filesystem, so a custom fs
+// implementation cannot be combined with it.
+thrownewERR_METHOD_NOT_IMPLEMENTED('windowsHandle with fs');
+}
+if(typeofoptions.windowsHandle!=='bigint'){
+thrownewERR_INVALID_ARG_TYPE('options.windowsHandle','bigint',
+options.windowsHandle);
+}
+stream[kFs]=fs;
+returnbinding.handleToFd(options.windowsHandle,flags);
+}
+
 functionReadStream(path,options){
 if(!(thisinstanceofReadStream))
 returnnewReadStream(path,options);
@@ -173,7 +199,11 @@ function ReadStream(path, options) {
 options.autoDestroy=false;
 }
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_RDONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');
@@ -325,7 +355,11 @@ function WriteStream(path, options) {
 // Only buffers are supported.
 options.decodeStrings=true;
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_WRONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');

src/node_file.cc

@@ -4150,6 +4150,33 @@ InternalFieldInfoBase* BindingData::Serialize(int index) {
 return info;
 }
 
+#ifdef _WIN32
+staticvoidHandleToFd(const FunctionCallbackInfo<Value>& args) {
+ Environment* env = Environment::GetCurrent(args);
+CHECK_GE(args.Length(), 1);
+CHECK(args[0]->IsBigInt());
+
+int flags = 0;
+if (args[1]->IsNumber()) {
+ flags = args[1].As<Int32>()->Value();
+ }
+
+bool lossless;
+int64_t handle = args[0].As<BigInt>()->Int64Value(&lossless);
+if (!lossless) {
+returnTHROW_ERR_OUT_OF_RANGE(env,
+"windowsHandle does not fit into 64 bits");
+ }
+intptr_t value = static_cast<intptr_t>(handle);
+
+int fd = _open_osfhandle(value, flags);
+if (fd == -1) {
+return env->ThrowErrnoException(errno, "_open_osfhandle");
+ }
+ args.GetReturnValue().Set(fd);
+}
+#endif// _WIN32
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
@@ -4216,6 +4243,10 @@ static void CreatePerIsolateProperties(IsolateData* isolate_data,
 
 SetMethod(isolate, target, "mkdtemp", Mkdtemp);
 
+#ifdef _WIN32
+SetMethod(isolate, target, "handleToFd", HandleToFd);
+#endif
+
 SetMethod(isolate, target, "cpSyncCheckPaths", CpSyncCheckPaths);
 SetMethod(isolate, target, "cpSyncOverrideFile", CpSyncOverrideFile);
 SetMethod(isolate, target, "cpSyncCopyDir", CpSyncCopyDir);
@@ -4343,6 +4374,9 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
  registry->Register(LUTimes);
 
  registry->Register(Mkdtemp);
+#ifdef _WIN32
+ registry->Register(HandleToFd);
+#endif
  registry->Register(NewFSReqCallback);
 
  registry->Register(FileHandle::New);

test/addons/fs-windows-handle/binding.cc

@@ -0,0 +1,62 @@
+#include<node.h>
+#include<v8.h>
+
+#ifdef _WIN32
+#include<windows.h>
+#endif
+
+namespace {
+
+using v8::BigInt;
+using v8::Context;
+using v8::FunctionCallbackInfo;
+using v8::Isolate;
+using v8::Local;
+using v8::Object;
+using v8::String;
+using v8::Value;
+
+// Creates an anonymous pipe and returns its raw Win32 read/write HANDLE values
+// as JS bigints. These are NOT CRT file descriptors, so passing them as the
+// `windowsHandle` stream option exercises the HANDLE -> fd conversion path on
+// Windows. Returns undefined on other platforms.
+voidCreatePipeHandles(const FunctionCallbackInfo<Value>& args) {
+ Isolate* isolate = args.GetIsolate();
+#ifdef _WIN32
+ Local<Context> context = isolate->GetCurrentContext();
+
+HANDLE read_handle = nullptr;
+HANDLE write_handle = nullptr;
+if (!CreatePipe(&read_handle, &write_handle, nullptr, 0)) {
+ isolate->ThrowException(v8::Exception::Error(
+String::NewFromUtf8(isolate, "CreatePipe failed").ToLocalChecked()));
+return;
+ }
+
+ Local<Object> result = Object::New(isolate);
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "readHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(read_handle))))
+ .Check();
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "writeHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(write_handle))))
+ .Check();
+ args.GetReturnValue().Set(result);
+#else
+ args.GetReturnValue().SetUndefined();
+#endif
+}
+
+} // anonymous namespace
+
+extern"C"NODE_MODULE_EXPORTvoidNODE_MODULE_INITIALIZER(
+ Local<Object> exports, Local<Value> module, Local<Context> context) {
+NODE_SET_METHOD(exports, "createPipeHandles", CreatePipeHandles);
+}

test/addons/fs-windows-handle/binding.gyp

@@ -0,0 +1,9 @@
+{
+'targets': [
+ {
+'target_name': 'binding',
+'sources': [ 'binding.cc' ],
+'includes': ['../common.gypi'],
+ },
+ ]
+}

test/addons/fs-windows-handle/test.js

@@ -0,0 +1,35 @@
+'use strict';
+// Verifies that fs.createReadStream()/createWriteStream() accept a raw Win32
+// HANDLE through the `windowsHandle` option, as happens when a parent process
+// passes an inherited anonymous pipe handle. The addon produces such handles
+// via CreatePipe(); Node must wrap them in CRT file descriptors instead of
+// failing with EBADF.
+
+constcommon=require('../../common');
+
+if(!common.isWindows){
+common.skip('windowsHandle is Windows-only');
+}
+
+constassert=require('assert');
+constfs=require('fs');
+
+constbinding=require(`./build/${common.buildType}/binding`);
+
+const{ readHandle, writeHandle }=binding.createPipeHandles();
+assert.strictEqual(typeofreadHandle,'bigint');
+assert.strictEqual(typeofwriteHandle,'bigint');
+
+constpayload='payload';
+
+constchunks=[];
+constrs=fs.createReadStream(null,{windowsHandle: readHandle});
+rs.on('error',(err)=>assert.fail(err));
+rs.on('data',(chunk)=>chunks.push(chunk));
+rs.on('end',common.mustCall(()=>{
+assert.strictEqual(Buffer.concat(chunks).toString(),payload);
+}));
+
+constws=fs.createWriteStream(null,{windowsHandle: writeHandle});
+ws.on('error',(err)=>assert.fail(err));
+ws.end(payload);

test/parallel/test-fs-stream-windows-handle.js

@@ -0,0 +1,47 @@
+'use strict';
+
+// Tests option validation for the `windowsHandle` option of
+// fs.createReadStream()/createWriteStream(). The functional round-trip on
+// Windows (where a real Win32 HANDLE is wrapped in a file descriptor) is
+// covered by test/addons/fs-windows-handle.
+
+constcommon=require('../common');
+constassert=require('assert');
+constfs=require('fs');
+
+consthandle=1n;
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle,fd: 2}),{
+code: 'ERR_INCOMPATIBLE_OPTION_PAIR',
+});
+}
+
+if(!common.isWindows){
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle}),{
+code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
+});
+}
+return;
+}
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+// Cannot be combined with a custom `fs` implementation.
+assert.throws(()=>create(null,{windowsHandle: handle,fs: {}}),{
+code: 'ERR_METHOD_NOT_IMPLEMENTED',
+});
+
+// Must be a bigint.
+assert.throws(()=>create(null,{windowsHandle: 'nope'}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+assert.throws(()=>create(null,{windowsHandle: 1}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+
+// Must fit into 64 bits.
+assert.throws(()=>create(null,{windowsHandle: 2n**64n}),{
+code: 'ERR_OUT_OF_RANGE',
+});
+}

doc/api/fs.md

@@ -2933,6 +2933,9 @@ behavior is similar to `cp dir1/ dir2/`.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v16.10.0
  pr-url: https://github.com/nodejs/node/pull/40013
  description: The `fs` option does not need `open` method if an `fd` was provided.
@@ -2989,6 +2992,8 @@ changes:
  * `highWaterMark` {integer} **Default:** `64 * 1024`
  * `fs` {Object|null} **Default:** `null`
  * `signal` {AbortSignal|null} **Default:** `null`
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to read from, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.ReadStream}
 
 `options` can include `start` and `end` values to read a range of bytes from
@@ -3009,6 +3014,12 @@ If `fd` points to a character device that only supports blocking reads
 available. This can prevent the process from exiting and the stream from
 closing naturally.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 
@@ -3059,6 +3070,9 @@ If `options` is a string, then it specifies the encoding.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v22.0.0
  pr-url: https://github.com/nodejs/node/pull/52037
  description: bump default highWaterMark.
@@ -3123,6 +3137,8 @@ changes:
  [`stream.getDefaultHighWaterMark()`][].
  * `flush` {boolean} If `true`, the underlying file descriptor is flushed
  prior to closing it. **Default:** `false`.
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to write to, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.WriteStream}
 
 `options` may also include a `start` option to allow writing data at some
@@ -3137,6 +3153,12 @@ then the file descriptor won't be closed, even if there's an error.
 It is the application's responsibility to close it and make sure there's no
 file descriptor leak.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 

lib/internal/fs/streams.js

@@ -13,13 +13,17 @@ const {
 }=primordials;
 
 const{
+ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
+ERR_INCOMPATIBLE_OPTION_PAIR,
 ERR_INVALID_ARG_TYPE,
 ERR_METHOD_NOT_IMPLEMENTED,
+ERR_MISSING_OPTION,
 ERR_OUT_OF_RANGE,
 ERR_STREAM_DESTROYED,
 ERR_SYSTEM_ERROR,
 }=require('internal/errors').codes;
 const{
+ isWindows,
  kEmptyObject,
 }=require('internal/util');
 const{
@@ -40,6 +44,8 @@ const {
 }=require('internal/fs/utils');
 const{ Readable, Writable, finished }=require('stream');
 const{ toPathIfFileURL }=require('internal/url');
+constbinding=internalBinding('fs');
+const{O_RDONLY,O_WRONLY}=internalBinding('constants').fs;
 constkIoDone=Symbol('kIoDone');
 constkIsPerformingIO=Symbol('kIsPerformingIO');
 
@@ -160,6 +166,26 @@ function importFd(stream, options) {
 ['number','FileHandle'],options.fd);
 }
 
+functionimportWindowsHandle(stream,options,flags){
+if(options.windowsHandle==null){
+thrownewERR_MISSING_OPTION('options.windowsHandle');
+}
+if(!isWindows){
+thrownewERR_FEATURE_UNAVAILABLE_ON_PLATFORM('windowsHandle');
+}
+if(options.fs){
+// The HANDLE is wrapped using the real filesystem, so a custom fs
+// implementation cannot be combined with it.
+thrownewERR_METHOD_NOT_IMPLEMENTED('windowsHandle with fs');
+}
+if(typeofoptions.windowsHandle!=='bigint'){
+thrownewERR_INVALID_ARG_TYPE('options.windowsHandle','bigint',
+options.windowsHandle);
+}
+stream[kFs]=fs;
+returnbinding.handleToFd(options.windowsHandle,flags);
+}
+
 functionReadStream(path,options){
 if(!(thisinstanceofReadStream))
 returnnewReadStream(path,options);
@@ -173,7 +199,11 @@ function ReadStream(path, options) {
 options.autoDestroy=false;
 }
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_RDONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');
@@ -325,7 +355,11 @@ function WriteStream(path, options) {
 // Only buffers are supported.
 options.decodeStrings=true;
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_WRONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');

src/node_file.cc

@@ -4150,6 +4150,33 @@ InternalFieldInfoBase* BindingData::Serialize(int index) {
 return info;
 }
 
+#ifdef _WIN32
+staticvoidHandleToFd(const FunctionCallbackInfo<Value>& args) {
+ Environment* env = Environment::GetCurrent(args);
+CHECK_GE(args.Length(), 1);
+CHECK(args[0]->IsBigInt());
+
+int flags = 0;
+if (args[1]->IsNumber()) {
+ flags = args[1].As<Int32>()->Value();
+ }
+
+bool lossless;
+int64_t handle = args[0].As<BigInt>()->Int64Value(&lossless);
+if (!lossless) {
+returnTHROW_ERR_OUT_OF_RANGE(env,
+"windowsHandle does not fit into 64 bits");
+ }
+intptr_t value = static_cast<intptr_t>(handle);
+
+int fd = _open_osfhandle(value, flags);
+if (fd == -1) {
+return env->ThrowErrnoException(errno, "_open_osfhandle");
+ }
+ args.GetReturnValue().Set(fd);
+}
+#endif// _WIN32
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
@@ -4216,6 +4243,10 @@ static void CreatePerIsolateProperties(IsolateData* isolate_data,
 
 SetMethod(isolate, target, "mkdtemp", Mkdtemp);
 
+#ifdef _WIN32
+SetMethod(isolate, target, "handleToFd", HandleToFd);
+#endif
+
 SetMethod(isolate, target, "cpSyncCheckPaths", CpSyncCheckPaths);
 SetMethod(isolate, target, "cpSyncOverrideFile", CpSyncOverrideFile);
 SetMethod(isolate, target, "cpSyncCopyDir", CpSyncCopyDir);
@@ -4343,6 +4374,9 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
  registry->Register(LUTimes);
 
  registry->Register(Mkdtemp);
+#ifdef _WIN32
+ registry->Register(HandleToFd);
+#endif
  registry->Register(NewFSReqCallback);
 
  registry->Register(FileHandle::New);

test/addons/fs-windows-handle/binding.cc

@@ -0,0 +1,62 @@
+#include<node.h>
+#include<v8.h>
+
+#ifdef _WIN32
+#include<windows.h>
+#endif
+
+namespace {
+
+using v8::BigInt;
+using v8::Context;
+using v8::FunctionCallbackInfo;
+using v8::Isolate;
+using v8::Local;
+using v8::Object;
+using v8::String;
+using v8::Value;
+
+// Creates an anonymous pipe and returns its raw Win32 read/write HANDLE values
+// as JS bigints. These are NOT CRT file descriptors, so passing them as the
+// `windowsHandle` stream option exercises the HANDLE -> fd conversion path on
+// Windows. Returns undefined on other platforms.
+voidCreatePipeHandles(const FunctionCallbackInfo<Value>& args) {
+ Isolate* isolate = args.GetIsolate();
+#ifdef _WIN32
+ Local<Context> context = isolate->GetCurrentContext();
+
+HANDLE read_handle = nullptr;
+HANDLE write_handle = nullptr;
+if (!CreatePipe(&read_handle, &write_handle, nullptr, 0)) {
+ isolate->ThrowException(v8::Exception::Error(
+String::NewFromUtf8(isolate, "CreatePipe failed").ToLocalChecked()));
+return;
+ }
+
+ Local<Object> result = Object::New(isolate);
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "readHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(read_handle))))
+ .Check();
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "writeHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(write_handle))))
+ .Check();
+ args.GetReturnValue().Set(result);
+#else
+ args.GetReturnValue().SetUndefined();
+#endif
+}
+
+} // anonymous namespace
+
+extern"C"NODE_MODULE_EXPORTvoidNODE_MODULE_INITIALIZER(
+ Local<Object> exports, Local<Value> module, Local<Context> context) {
+NODE_SET_METHOD(exports, "createPipeHandles", CreatePipeHandles);
+}

test/addons/fs-windows-handle/binding.gyp

@@ -0,0 +1,9 @@
+{
+'targets': [
+ {
+'target_name': 'binding',
+'sources': [ 'binding.cc' ],
+'includes': ['../common.gypi'],
+ },
+ ]
+}

test/addons/fs-windows-handle/test.js

@@ -0,0 +1,35 @@
+'use strict';
+// Verifies that fs.createReadStream()/createWriteStream() accept a raw Win32
+// HANDLE through the `windowsHandle` option, as happens when a parent process
+// passes an inherited anonymous pipe handle. The addon produces such handles
+// via CreatePipe(); Node must wrap them in CRT file descriptors instead of
+// failing with EBADF.
+
+constcommon=require('../../common');
+
+if(!common.isWindows){
+common.skip('windowsHandle is Windows-only');
+}
+
+constassert=require('assert');
+constfs=require('fs');
+
+constbinding=require(`./build/${common.buildType}/binding`);
+
+const{ readHandle, writeHandle }=binding.createPipeHandles();
+assert.strictEqual(typeofreadHandle,'bigint');
+assert.strictEqual(typeofwriteHandle,'bigint');
+
+constpayload='payload';
+
+constchunks=[];
+constrs=fs.createReadStream(null,{windowsHandle: readHandle});
+rs.on('error',(err)=>assert.fail(err));
+rs.on('data',(chunk)=>chunks.push(chunk));
+rs.on('end',common.mustCall(()=>{
+assert.strictEqual(Buffer.concat(chunks).toString(),payload);
+}));
+
+constws=fs.createWriteStream(null,{windowsHandle: writeHandle});
+ws.on('error',(err)=>assert.fail(err));
+ws.end(payload);

test/parallel/test-fs-stream-windows-handle.js

@@ -0,0 +1,47 @@
+'use strict';
+
+// Tests option validation for the `windowsHandle` option of
+// fs.createReadStream()/createWriteStream(). The functional round-trip on
+// Windows (where a real Win32 HANDLE is wrapped in a file descriptor) is
+// covered by test/addons/fs-windows-handle.
+
+constcommon=require('../common');
+constassert=require('assert');
+constfs=require('fs');
+
+consthandle=1n;
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle,fd: 2}),{
+code: 'ERR_INCOMPATIBLE_OPTION_PAIR',
+});
+}
+
+if(!common.isWindows){
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle}),{
+code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
+});
+}
+return;
+}
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+// Cannot be combined with a custom `fs` implementation.
+assert.throws(()=>create(null,{windowsHandle: handle,fs: {}}),{
+code: 'ERR_METHOD_NOT_IMPLEMENTED',
+});
+
+// Must be a bigint.
+assert.throws(()=>create(null,{windowsHandle: 'nope'}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+assert.throws(()=>create(null,{windowsHandle: 1}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+
+// Must fit into 64 bits.
+assert.throws(()=>create(null,{windowsHandle: 2n**64n}),{
+code: 'ERR_OUT_OF_RANGE',
+});
+}

doc/api/fs.md

@@ -2933,6 +2933,9 @@ behavior is similar to `cp dir1/ dir2/`.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v16.10.0
  pr-url: https://github.com/nodejs/node/pull/40013
  description: The `fs` option does not need `open` method if an `fd` was provided.
@@ -2989,6 +2992,8 @@ changes:
  * `highWaterMark` {integer} **Default:** `64 * 1024`
  * `fs` {Object|null} **Default:** `null`
  * `signal` {AbortSignal|null} **Default:** `null`
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to read from, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.ReadStream}
 
 `options` can include `start` and `end` values to read a range of bytes from
@@ -3009,6 +3014,12 @@ If `fd` points to a character device that only supports blocking reads
 available. This can prevent the process from exiting and the stream from
 closing naturally.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 
@@ -3059,6 +3070,9 @@ If `options` is a string, then it specifies the encoding.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v22.0.0
  pr-url: https://github.com/nodejs/node/pull/52037
  description: bump default highWaterMark.
@@ -3123,6 +3137,8 @@ changes:
  [`stream.getDefaultHighWaterMark()`][].
  * `flush` {boolean} If `true`, the underlying file descriptor is flushed
  prior to closing it. **Default:** `false`.
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to write to, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.WriteStream}
 
 `options` may also include a `start` option to allow writing data at some
@@ -3137,6 +3153,12 @@ then the file descriptor won't be closed, even if there's an error.
 It is the application's responsibility to close it and make sure there's no
 file descriptor leak.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 

lib/internal/fs/streams.js

@@ -13,13 +13,17 @@ const {
 }=primordials;
 
 const{
+ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
+ERR_INCOMPATIBLE_OPTION_PAIR,
 ERR_INVALID_ARG_TYPE,
 ERR_METHOD_NOT_IMPLEMENTED,
+ERR_MISSING_OPTION,
 ERR_OUT_OF_RANGE,
 ERR_STREAM_DESTROYED,
 ERR_SYSTEM_ERROR,
 }=require('internal/errors').codes;
 const{
+ isWindows,
  kEmptyObject,
 }=require('internal/util');
 const{
@@ -40,6 +44,8 @@ const {
 }=require('internal/fs/utils');
 const{ Readable, Writable, finished }=require('stream');
 const{ toPathIfFileURL }=require('internal/url');
+constbinding=internalBinding('fs');
+const{O_RDONLY,O_WRONLY}=internalBinding('constants').fs;
 constkIoDone=Symbol('kIoDone');
 constkIsPerformingIO=Symbol('kIsPerformingIO');
 
@@ -160,6 +166,26 @@ function importFd(stream, options) {
 ['number','FileHandle'],options.fd);
 }
 
+functionimportWindowsHandle(stream,options,flags){
+if(options.windowsHandle==null){
+thrownewERR_MISSING_OPTION('options.windowsHandle');
+}
+if(!isWindows){
+thrownewERR_FEATURE_UNAVAILABLE_ON_PLATFORM('windowsHandle');
+}
+if(options.fs){
+// The HANDLE is wrapped using the real filesystem, so a custom fs
+// implementation cannot be combined with it.
+thrownewERR_METHOD_NOT_IMPLEMENTED('windowsHandle with fs');
+}
+if(typeofoptions.windowsHandle!=='bigint'){
+thrownewERR_INVALID_ARG_TYPE('options.windowsHandle','bigint',
+options.windowsHandle);
+}
+stream[kFs]=fs;
+returnbinding.handleToFd(options.windowsHandle,flags);
+}
+
 functionReadStream(path,options){
 if(!(thisinstanceofReadStream))
 returnnewReadStream(path,options);
@@ -173,7 +199,11 @@ function ReadStream(path, options) {
 options.autoDestroy=false;
 }
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_RDONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');
@@ -325,7 +355,11 @@ function WriteStream(path, options) {
 // Only buffers are supported.
 options.decodeStrings=true;
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_WRONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');

src/node_file.cc

@@ -4150,6 +4150,33 @@ InternalFieldInfoBase* BindingData::Serialize(int index) {
 return info;
 }
 
+#ifdef _WIN32
+staticvoidHandleToFd(const FunctionCallbackInfo<Value>& args) {
+ Environment* env = Environment::GetCurrent(args);
+CHECK_GE(args.Length(), 1);
+CHECK(args[0]->IsBigInt());
+
+int flags = 0;
+if (args[1]->IsNumber()) {
+ flags = args[1].As<Int32>()->Value();
+ }
+
+bool lossless;
+int64_t handle = args[0].As<BigInt>()->Int64Value(&lossless);
+if (!lossless) {
+returnTHROW_ERR_OUT_OF_RANGE(env,
+"windowsHandle does not fit into 64 bits");
+ }
+intptr_t value = static_cast<intptr_t>(handle);
+
+int fd = _open_osfhandle(value, flags);
+if (fd == -1) {
+return env->ThrowErrnoException(errno, "_open_osfhandle");
+ }
+ args.GetReturnValue().Set(fd);
+}
+#endif// _WIN32
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
@@ -4216,6 +4243,10 @@ static void CreatePerIsolateProperties(IsolateData* isolate_data,
 
 SetMethod(isolate, target, "mkdtemp", Mkdtemp);
 
+#ifdef _WIN32
+SetMethod(isolate, target, "handleToFd", HandleToFd);
+#endif
+
 SetMethod(isolate, target, "cpSyncCheckPaths", CpSyncCheckPaths);
 SetMethod(isolate, target, "cpSyncOverrideFile", CpSyncOverrideFile);
 SetMethod(isolate, target, "cpSyncCopyDir", CpSyncCopyDir);
@@ -4343,6 +4374,9 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
  registry->Register(LUTimes);
 
  registry->Register(Mkdtemp);
+#ifdef _WIN32
+ registry->Register(HandleToFd);
+#endif
  registry->Register(NewFSReqCallback);
 
  registry->Register(FileHandle::New);

test/addons/fs-windows-handle/binding.cc

@@ -0,0 +1,62 @@
+#include<node.h>
+#include<v8.h>
+
+#ifdef _WIN32
+#include<windows.h>
+#endif
+
+namespace {
+
+using v8::BigInt;
+using v8::Context;
+using v8::FunctionCallbackInfo;
+using v8::Isolate;
+using v8::Local;
+using v8::Object;
+using v8::String;
+using v8::Value;
+
+// Creates an anonymous pipe and returns its raw Win32 read/write HANDLE values
+// as JS bigints. These are NOT CRT file descriptors, so passing them as the
+// `windowsHandle` stream option exercises the HANDLE -> fd conversion path on
+// Windows. Returns undefined on other platforms.
+voidCreatePipeHandles(const FunctionCallbackInfo<Value>& args) {
+ Isolate* isolate = args.GetIsolate();
+#ifdef _WIN32
+ Local<Context> context = isolate->GetCurrentContext();
+
+HANDLE read_handle = nullptr;
+HANDLE write_handle = nullptr;
+if (!CreatePipe(&read_handle, &write_handle, nullptr, 0)) {
+ isolate->ThrowException(v8::Exception::Error(
+String::NewFromUtf8(isolate, "CreatePipe failed").ToLocalChecked()));
+return;
+ }
+
+ Local<Object> result = Object::New(isolate);
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "readHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(read_handle))))
+ .Check();
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "writeHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(write_handle))))
+ .Check();
+ args.GetReturnValue().Set(result);
+#else
+ args.GetReturnValue().SetUndefined();
+#endif
+}
+
+} // anonymous namespace
+
+extern"C"NODE_MODULE_EXPORTvoidNODE_MODULE_INITIALIZER(
+ Local<Object> exports, Local<Value> module, Local<Context> context) {
+NODE_SET_METHOD(exports, "createPipeHandles", CreatePipeHandles);
+}

test/addons/fs-windows-handle/binding.gyp

@@ -0,0 +1,9 @@
+{
+'targets': [
+ {
+'target_name': 'binding',
+'sources': [ 'binding.cc' ],
+'includes': ['../common.gypi'],
+ },
+ ]
+}

test/addons/fs-windows-handle/test.js

@@ -0,0 +1,35 @@
+'use strict';
+// Verifies that fs.createReadStream()/createWriteStream() accept a raw Win32
+// HANDLE through the `windowsHandle` option, as happens when a parent process
+// passes an inherited anonymous pipe handle. The addon produces such handles
+// via CreatePipe(); Node must wrap them in CRT file descriptors instead of
+// failing with EBADF.
+
+constcommon=require('../../common');
+
+if(!common.isWindows){
+common.skip('windowsHandle is Windows-only');
+}
+
+constassert=require('assert');
+constfs=require('fs');
+
+constbinding=require(`./build/${common.buildType}/binding`);
+
+const{ readHandle, writeHandle }=binding.createPipeHandles();
+assert.strictEqual(typeofreadHandle,'bigint');
+assert.strictEqual(typeofwriteHandle,'bigint');
+
+constpayload='payload';
+
+constchunks=[];
+constrs=fs.createReadStream(null,{windowsHandle: readHandle});
+rs.on('error',(err)=>assert.fail(err));
+rs.on('data',(chunk)=>chunks.push(chunk));
+rs.on('end',common.mustCall(()=>{
+assert.strictEqual(Buffer.concat(chunks).toString(),payload);
+}));
+
+constws=fs.createWriteStream(null,{windowsHandle: writeHandle});
+ws.on('error',(err)=>assert.fail(err));
+ws.end(payload);

test/parallel/test-fs-stream-windows-handle.js

@@ -0,0 +1,47 @@
+'use strict';
+
+// Tests option validation for the `windowsHandle` option of
+// fs.createReadStream()/createWriteStream(). The functional round-trip on
+// Windows (where a real Win32 HANDLE is wrapped in a file descriptor) is
+// covered by test/addons/fs-windows-handle.
+
+constcommon=require('../common');
+constassert=require('assert');
+constfs=require('fs');
+
+consthandle=1n;
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle,fd: 2}),{
+code: 'ERR_INCOMPATIBLE_OPTION_PAIR',
+});
+}
+
+if(!common.isWindows){
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle}),{
+code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
+});
+}
+return;
+}
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+// Cannot be combined with a custom `fs` implementation.
+assert.throws(()=>create(null,{windowsHandle: handle,fs: {}}),{
+code: 'ERR_METHOD_NOT_IMPLEMENTED',
+});
+
+// Must be a bigint.
+assert.throws(()=>create(null,{windowsHandle: 'nope'}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+assert.throws(()=>create(null,{windowsHandle: 1}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+
+// Must fit into 64 bits.
+assert.throws(()=>create(null,{windowsHandle: 2n**64n}),{
+code: 'ERR_OUT_OF_RANGE',
+});
+}

doc/api/fs.md

@@ -2933,6 +2933,9 @@ behavior is similar to `cp dir1/ dir2/`.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v16.10.0
  pr-url: https://github.com/nodejs/node/pull/40013
  description: The `fs` option does not need `open` method if an `fd` was provided.
@@ -2989,6 +2992,8 @@ changes:
  * `highWaterMark` {integer} **Default:** `64 * 1024`
  * `fs` {Object|null} **Default:** `null`
  * `signal` {AbortSignal|null} **Default:** `null`
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to read from, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.ReadStream}
 
 `options` can include `start` and `end` values to read a range of bytes from
@@ -3009,6 +3014,12 @@ If `fd` points to a character device that only supports blocking reads
 available. This can prevent the process from exiting and the stream from
 closing naturally.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 
@@ -3059,6 +3070,9 @@ If `options` is a string, then it specifies the encoding.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v22.0.0
  pr-url: https://github.com/nodejs/node/pull/52037
  description: bump default highWaterMark.
@@ -3123,6 +3137,8 @@ changes:
  [`stream.getDefaultHighWaterMark()`][].
  * `flush` {boolean} If `true`, the underlying file descriptor is flushed
  prior to closing it. **Default:** `false`.
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to write to, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.WriteStream}
 
 `options` may also include a `start` option to allow writing data at some
@@ -3137,6 +3153,12 @@ then the file descriptor won't be closed, even if there's an error.
 It is the application's responsibility to close it and make sure there's no
 file descriptor leak.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 

lib/internal/fs/streams.js

@@ -13,13 +13,17 @@ const {
 }=primordials;
 
 const{
+ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
+ERR_INCOMPATIBLE_OPTION_PAIR,
 ERR_INVALID_ARG_TYPE,
 ERR_METHOD_NOT_IMPLEMENTED,
+ERR_MISSING_OPTION,
 ERR_OUT_OF_RANGE,
 ERR_STREAM_DESTROYED,
 ERR_SYSTEM_ERROR,
 }=require('internal/errors').codes;
 const{
+ isWindows,
  kEmptyObject,
 }=require('internal/util');
 const{
@@ -40,6 +44,8 @@ const {
 }=require('internal/fs/utils');
 const{ Readable, Writable, finished }=require('stream');
 const{ toPathIfFileURL }=require('internal/url');
+constbinding=internalBinding('fs');
+const{O_RDONLY,O_WRONLY}=internalBinding('constants').fs;
 constkIoDone=Symbol('kIoDone');
 constkIsPerformingIO=Symbol('kIsPerformingIO');
 
@@ -160,6 +166,26 @@ function importFd(stream, options) {
 ['number','FileHandle'],options.fd);
 }
 
+functionimportWindowsHandle(stream,options,flags){
+if(options.windowsHandle==null){
+thrownewERR_MISSING_OPTION('options.windowsHandle');
+}
+if(!isWindows){
+thrownewERR_FEATURE_UNAVAILABLE_ON_PLATFORM('windowsHandle');
+}
+if(options.fs){
+// The HANDLE is wrapped using the real filesystem, so a custom fs
+// implementation cannot be combined with it.
+thrownewERR_METHOD_NOT_IMPLEMENTED('windowsHandle with fs');
+}
+if(typeofoptions.windowsHandle!=='bigint'){
+thrownewERR_INVALID_ARG_TYPE('options.windowsHandle','bigint',
+options.windowsHandle);
+}
+stream[kFs]=fs;
+returnbinding.handleToFd(options.windowsHandle,flags);
+}
+
 functionReadStream(path,options){
 if(!(thisinstanceofReadStream))
 returnnewReadStream(path,options);
@@ -173,7 +199,11 @@ function ReadStream(path, options) {
 options.autoDestroy=false;
 }
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_RDONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');
@@ -325,7 +355,11 @@ function WriteStream(path, options) {
 // Only buffers are supported.
 options.decodeStrings=true;
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_WRONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');

src/node_file.cc

@@ -4150,6 +4150,33 @@ InternalFieldInfoBase* BindingData::Serialize(int index) {
 return info;
 }
 
+#ifdef _WIN32
+staticvoidHandleToFd(const FunctionCallbackInfo<Value>& args) {
+ Environment* env = Environment::GetCurrent(args);
+CHECK_GE(args.Length(), 1);
+CHECK(args[0]->IsBigInt());
+
+int flags = 0;
+if (args[1]->IsNumber()) {
+ flags = args[1].As<Int32>()->Value();
+ }
+
+bool lossless;
+int64_t handle = args[0].As<BigInt>()->Int64Value(&lossless);
+if (!lossless) {
+returnTHROW_ERR_OUT_OF_RANGE(env,
+"windowsHandle does not fit into 64 bits");
+ }
+intptr_t value = static_cast<intptr_t>(handle);
+
+int fd = _open_osfhandle(value, flags);
+if (fd == -1) {
+return env->ThrowErrnoException(errno, "_open_osfhandle");
+ }
+ args.GetReturnValue().Set(fd);
+}
+#endif// _WIN32
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
@@ -4216,6 +4243,10 @@ static void CreatePerIsolateProperties(IsolateData* isolate_data,
 
 SetMethod(isolate, target, "mkdtemp", Mkdtemp);
 
+#ifdef _WIN32
+SetMethod(isolate, target, "handleToFd", HandleToFd);
+#endif
+
 SetMethod(isolate, target, "cpSyncCheckPaths", CpSyncCheckPaths);
 SetMethod(isolate, target, "cpSyncOverrideFile", CpSyncOverrideFile);
 SetMethod(isolate, target, "cpSyncCopyDir", CpSyncCopyDir);
@@ -4343,6 +4374,9 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
  registry->Register(LUTimes);
 
  registry->Register(Mkdtemp);
+#ifdef _WIN32
+ registry->Register(HandleToFd);
+#endif
  registry->Register(NewFSReqCallback);
 
  registry->Register(FileHandle::New);

test/addons/fs-windows-handle/binding.cc

@@ -0,0 +1,62 @@
+#include<node.h>
+#include<v8.h>
+
+#ifdef _WIN32
+#include<windows.h>
+#endif
+
+namespace {
+
+using v8::BigInt;
+using v8::Context;
+using v8::FunctionCallbackInfo;
+using v8::Isolate;
+using v8::Local;
+using v8::Object;
+using v8::String;
+using v8::Value;
+
+// Creates an anonymous pipe and returns its raw Win32 read/write HANDLE values
+// as JS bigints. These are NOT CRT file descriptors, so passing them as the
+// `windowsHandle` stream option exercises the HANDLE -> fd conversion path on
+// Windows. Returns undefined on other platforms.
+voidCreatePipeHandles(const FunctionCallbackInfo<Value>& args) {
+ Isolate* isolate = args.GetIsolate();
+#ifdef _WIN32
+ Local<Context> context = isolate->GetCurrentContext();
+
+HANDLE read_handle = nullptr;
+HANDLE write_handle = nullptr;
+if (!CreatePipe(&read_handle, &write_handle, nullptr, 0)) {
+ isolate->ThrowException(v8::Exception::Error(
+String::NewFromUtf8(isolate, "CreatePipe failed").ToLocalChecked()));
+return;
+ }
+
+ Local<Object> result = Object::New(isolate);
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "readHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(read_handle))))
+ .Check();
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "writeHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(write_handle))))
+ .Check();
+ args.GetReturnValue().Set(result);
+#else
+ args.GetReturnValue().SetUndefined();
+#endif
+}
+
+} // anonymous namespace
+
+extern"C"NODE_MODULE_EXPORTvoidNODE_MODULE_INITIALIZER(
+ Local<Object> exports, Local<Value> module, Local<Context> context) {
+NODE_SET_METHOD(exports, "createPipeHandles", CreatePipeHandles);
+}

test/addons/fs-windows-handle/binding.gyp

@@ -0,0 +1,9 @@
+{
+'targets': [
+ {
+'target_name': 'binding',
+'sources': [ 'binding.cc' ],
+'includes': ['../common.gypi'],
+ },
+ ]
+}

test/addons/fs-windows-handle/test.js

@@ -0,0 +1,35 @@
+'use strict';
+// Verifies that fs.createReadStream()/createWriteStream() accept a raw Win32
+// HANDLE through the `windowsHandle` option, as happens when a parent process
+// passes an inherited anonymous pipe handle. The addon produces such handles
+// via CreatePipe(); Node must wrap them in CRT file descriptors instead of
+// failing with EBADF.
+
+constcommon=require('../../common');
+
+if(!common.isWindows){
+common.skip('windowsHandle is Windows-only');
+}
+
+constassert=require('assert');
+constfs=require('fs');
+
+constbinding=require(`./build/${common.buildType}/binding`);
+
+const{ readHandle, writeHandle }=binding.createPipeHandles();
+assert.strictEqual(typeofreadHandle,'bigint');
+assert.strictEqual(typeofwriteHandle,'bigint');
+
+constpayload='payload';
+
+constchunks=[];
+constrs=fs.createReadStream(null,{windowsHandle: readHandle});
+rs.on('error',(err)=>assert.fail(err));
+rs.on('data',(chunk)=>chunks.push(chunk));
+rs.on('end',common.mustCall(()=>{
+assert.strictEqual(Buffer.concat(chunks).toString(),payload);
+}));
+
+constws=fs.createWriteStream(null,{windowsHandle: writeHandle});
+ws.on('error',(err)=>assert.fail(err));
+ws.end(payload);

test/parallel/test-fs-stream-windows-handle.js

@@ -0,0 +1,47 @@
+'use strict';
+
+// Tests option validation for the `windowsHandle` option of
+// fs.createReadStream()/createWriteStream(). The functional round-trip on
+// Windows (where a real Win32 HANDLE is wrapped in a file descriptor) is
+// covered by test/addons/fs-windows-handle.
+
+constcommon=require('../common');
+constassert=require('assert');
+constfs=require('fs');
+
+consthandle=1n;
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle,fd: 2}),{
+code: 'ERR_INCOMPATIBLE_OPTION_PAIR',
+});
+}
+
+if(!common.isWindows){
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle}),{
+code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
+});
+}
+return;
+}
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+// Cannot be combined with a custom `fs` implementation.
+assert.throws(()=>create(null,{windowsHandle: handle,fs: {}}),{
+code: 'ERR_METHOD_NOT_IMPLEMENTED',
+});
+
+// Must be a bigint.
+assert.throws(()=>create(null,{windowsHandle: 'nope'}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+assert.throws(()=>create(null,{windowsHandle: 1}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+
+// Must fit into 64 bits.
+assert.throws(()=>create(null,{windowsHandle: 2n**64n}),{
+code: 'ERR_OUT_OF_RANGE',
+});
+}

doc/api/fs.md

@@ -2933,6 +2933,9 @@ behavior is similar to `cp dir1/ dir2/`.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v16.10.0
  pr-url: https://github.com/nodejs/node/pull/40013
  description: The `fs` option does not need `open` method if an `fd` was provided.
@@ -2989,6 +2992,8 @@ changes:
  * `highWaterMark` {integer} **Default:** `64 * 1024`
  * `fs` {Object|null} **Default:** `null`
  * `signal` {AbortSignal|null} **Default:** `null`
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to read from, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.ReadStream}
 
 `options` can include `start` and `end` values to read a range of bytes from
@@ -3009,6 +3014,12 @@ If `fd` points to a character device that only supports blocking reads
 available. This can prevent the process from exiting and the stream from
 closing naturally.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 
@@ -3059,6 +3070,9 @@ If `options` is a string, then it specifies the encoding.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v22.0.0
  pr-url: https://github.com/nodejs/node/pull/52037
  description: bump default highWaterMark.
@@ -3123,6 +3137,8 @@ changes:
  [`stream.getDefaultHighWaterMark()`][].
  * `flush` {boolean} If `true`, the underlying file descriptor is flushed
  prior to closing it. **Default:** `false`.
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to write to, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.WriteStream}
 
 `options` may also include a `start` option to allow writing data at some
@@ -3137,6 +3153,12 @@ then the file descriptor won't be closed, even if there's an error.
 It is the application's responsibility to close it and make sure there's no
 file descriptor leak.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 

lib/internal/fs/streams.js

@@ -13,13 +13,17 @@ const {
 }=primordials;
 
 const{
+ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
+ERR_INCOMPATIBLE_OPTION_PAIR,
 ERR_INVALID_ARG_TYPE,
 ERR_METHOD_NOT_IMPLEMENTED,
+ERR_MISSING_OPTION,
 ERR_OUT_OF_RANGE,
 ERR_STREAM_DESTROYED,
 ERR_SYSTEM_ERROR,
 }=require('internal/errors').codes;
 const{
+ isWindows,
  kEmptyObject,
 }=require('internal/util');
 const{
@@ -40,6 +44,8 @@ const {
 }=require('internal/fs/utils');
 const{ Readable, Writable, finished }=require('stream');
 const{ toPathIfFileURL }=require('internal/url');
+constbinding=internalBinding('fs');
+const{O_RDONLY,O_WRONLY}=internalBinding('constants').fs;
 constkIoDone=Symbol('kIoDone');
 constkIsPerformingIO=Symbol('kIsPerformingIO');
 
@@ -160,6 +166,26 @@ function importFd(stream, options) {
 ['number','FileHandle'],options.fd);
 }
 
+functionimportWindowsHandle(stream,options,flags){
+if(options.windowsHandle==null){
+thrownewERR_MISSING_OPTION('options.windowsHandle');
+}
+if(!isWindows){
+thrownewERR_FEATURE_UNAVAILABLE_ON_PLATFORM('windowsHandle');
+}
+if(options.fs){
+// The HANDLE is wrapped using the real filesystem, so a custom fs
+// implementation cannot be combined with it.
+thrownewERR_METHOD_NOT_IMPLEMENTED('windowsHandle with fs');
+}
+if(typeofoptions.windowsHandle!=='bigint'){
+thrownewERR_INVALID_ARG_TYPE('options.windowsHandle','bigint',
+options.windowsHandle);
+}
+stream[kFs]=fs;
+returnbinding.handleToFd(options.windowsHandle,flags);
+}
+
 functionReadStream(path,options){
 if(!(thisinstanceofReadStream))
 returnnewReadStream(path,options);
@@ -173,7 +199,11 @@ function ReadStream(path, options) {
 options.autoDestroy=false;
 }
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_RDONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');
@@ -325,7 +355,11 @@ function WriteStream(path, options) {
 // Only buffers are supported.
 options.decodeStrings=true;
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_WRONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');

src/node_file.cc

@@ -4150,6 +4150,33 @@ InternalFieldInfoBase* BindingData::Serialize(int index) {
 return info;
 }
 
+#ifdef _WIN32
+staticvoidHandleToFd(const FunctionCallbackInfo<Value>& args) {
+ Environment* env = Environment::GetCurrent(args);
+CHECK_GE(args.Length(), 1);
+CHECK(args[0]->IsBigInt());
+
+int flags = 0;
+if (args[1]->IsNumber()) {
+ flags = args[1].As<Int32>()->Value();
+ }
+
+bool lossless;
+int64_t handle = args[0].As<BigInt>()->Int64Value(&lossless);
+if (!lossless) {
+returnTHROW_ERR_OUT_OF_RANGE(env,
+"windowsHandle does not fit into 64 bits");
+ }
+intptr_t value = static_cast<intptr_t>(handle);
+
+int fd = _open_osfhandle(value, flags);
+if (fd == -1) {
+return env->ThrowErrnoException(errno, "_open_osfhandle");
+ }
+ args.GetReturnValue().Set(fd);
+}
+#endif// _WIN32
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
@@ -4216,6 +4243,10 @@ static void CreatePerIsolateProperties(IsolateData* isolate_data,
 
 SetMethod(isolate, target, "mkdtemp", Mkdtemp);
 
+#ifdef _WIN32
+SetMethod(isolate, target, "handleToFd", HandleToFd);
+#endif
+
 SetMethod(isolate, target, "cpSyncCheckPaths", CpSyncCheckPaths);
 SetMethod(isolate, target, "cpSyncOverrideFile", CpSyncOverrideFile);
 SetMethod(isolate, target, "cpSyncCopyDir", CpSyncCopyDir);
@@ -4343,6 +4374,9 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
  registry->Register(LUTimes);
 
  registry->Register(Mkdtemp);
+#ifdef _WIN32
+ registry->Register(HandleToFd);
+#endif
  registry->Register(NewFSReqCallback);
 
  registry->Register(FileHandle::New);

test/addons/fs-windows-handle/binding.cc

@@ -0,0 +1,62 @@
+#include<node.h>
+#include<v8.h>
+
+#ifdef _WIN32
+#include<windows.h>
+#endif
+
+namespace {
+
+using v8::BigInt;
+using v8::Context;
+using v8::FunctionCallbackInfo;
+using v8::Isolate;
+using v8::Local;
+using v8::Object;
+using v8::String;
+using v8::Value;
+
+// Creates an anonymous pipe and returns its raw Win32 read/write HANDLE values
+// as JS bigints. These are NOT CRT file descriptors, so passing them as the
+// `windowsHandle` stream option exercises the HANDLE -> fd conversion path on
+// Windows. Returns undefined on other platforms.
+voidCreatePipeHandles(const FunctionCallbackInfo<Value>& args) {
+ Isolate* isolate = args.GetIsolate();
+#ifdef _WIN32
+ Local<Context> context = isolate->GetCurrentContext();
+
+HANDLE read_handle = nullptr;
+HANDLE write_handle = nullptr;
+if (!CreatePipe(&read_handle, &write_handle, nullptr, 0)) {
+ isolate->ThrowException(v8::Exception::Error(
+String::NewFromUtf8(isolate, "CreatePipe failed").ToLocalChecked()));
+return;
+ }
+
+ Local<Object> result = Object::New(isolate);
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "readHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(read_handle))))
+ .Check();
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "writeHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(write_handle))))
+ .Check();
+ args.GetReturnValue().Set(result);
+#else
+ args.GetReturnValue().SetUndefined();
+#endif
+}
+
+} // anonymous namespace
+
+extern"C"NODE_MODULE_EXPORTvoidNODE_MODULE_INITIALIZER(
+ Local<Object> exports, Local<Value> module, Local<Context> context) {
+NODE_SET_METHOD(exports, "createPipeHandles", CreatePipeHandles);
+}

test/addons/fs-windows-handle/binding.gyp

@@ -0,0 +1,9 @@
+{
+'targets': [
+ {
+'target_name': 'binding',
+'sources': [ 'binding.cc' ],
+'includes': ['../common.gypi'],
+ },
+ ]
+}

test/addons/fs-windows-handle/test.js

@@ -0,0 +1,35 @@
+'use strict';
+// Verifies that fs.createReadStream()/createWriteStream() accept a raw Win32
+// HANDLE through the `windowsHandle` option, as happens when a parent process
+// passes an inherited anonymous pipe handle. The addon produces such handles
+// via CreatePipe(); Node must wrap them in CRT file descriptors instead of
+// failing with EBADF.
+
+constcommon=require('../../common');
+
+if(!common.isWindows){
+common.skip('windowsHandle is Windows-only');
+}
+
+constassert=require('assert');
+constfs=require('fs');
+
+constbinding=require(`./build/${common.buildType}/binding`);
+
+const{ readHandle, writeHandle }=binding.createPipeHandles();
+assert.strictEqual(typeofreadHandle,'bigint');
+assert.strictEqual(typeofwriteHandle,'bigint');
+
+constpayload='payload';
+
+constchunks=[];
+constrs=fs.createReadStream(null,{windowsHandle: readHandle});
+rs.on('error',(err)=>assert.fail(err));
+rs.on('data',(chunk)=>chunks.push(chunk));
+rs.on('end',common.mustCall(()=>{
+assert.strictEqual(Buffer.concat(chunks).toString(),payload);
+}));
+
+constws=fs.createWriteStream(null,{windowsHandle: writeHandle});
+ws.on('error',(err)=>assert.fail(err));
+ws.end(payload);

test/parallel/test-fs-stream-windows-handle.js

@@ -0,0 +1,47 @@
+'use strict';
+
+// Tests option validation for the `windowsHandle` option of
+// fs.createReadStream()/createWriteStream(). The functional round-trip on
+// Windows (where a real Win32 HANDLE is wrapped in a file descriptor) is
+// covered by test/addons/fs-windows-handle.
+
+constcommon=require('../common');
+constassert=require('assert');
+constfs=require('fs');
+
+consthandle=1n;
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle,fd: 2}),{
+code: 'ERR_INCOMPATIBLE_OPTION_PAIR',
+});
+}
+
+if(!common.isWindows){
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle}),{
+code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
+});
+}
+return;
+}
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+// Cannot be combined with a custom `fs` implementation.
+assert.throws(()=>create(null,{windowsHandle: handle,fs: {}}),{
+code: 'ERR_METHOD_NOT_IMPLEMENTED',
+});
+
+// Must be a bigint.
+assert.throws(()=>create(null,{windowsHandle: 'nope'}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+assert.throws(()=>create(null,{windowsHandle: 1}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+
+// Must fit into 64 bits.
+assert.throws(()=>create(null,{windowsHandle: 2n**64n}),{
+code: 'ERR_OUT_OF_RANGE',
+});
+}

doc/api/fs.md

@@ -2933,6 +2933,9 @@ behavior is similar to `cp dir1/ dir2/`.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v16.10.0
  pr-url: https://github.com/nodejs/node/pull/40013
  description: The `fs` option does not need `open` method if an `fd` was provided.
@@ -2989,6 +2992,8 @@ changes:
  * `highWaterMark` {integer} **Default:** `64 * 1024`
  * `fs` {Object|null} **Default:** `null`
  * `signal` {AbortSignal|null} **Default:** `null`
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to read from, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.ReadStream}
 
 `options` can include `start` and `end` values to read a range of bytes from
@@ -3009,6 +3014,12 @@ If `fd` points to a character device that only supports blocking reads
 available. This can prevent the process from exiting and the stream from
 closing naturally.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 
@@ -3059,6 +3070,9 @@ If `options` is a string, then it specifies the encoding.
 <!-- YAML
 added: v0.1.31
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/63851
+ description: Add the `windowsHandle` option.
  - version: v22.0.0
  pr-url: https://github.com/nodejs/node/pull/52037
  description: bump default highWaterMark.
@@ -3123,6 +3137,8 @@ changes:
  [`stream.getDefaultHighWaterMark()`][].
  * `flush` {boolean} If `true`, the underlying file descriptor is flushed
  prior to closing it. **Default:** `false`.
+ * `windowsHandle` {bigint} A raw Win32 `HANDLE` value to write to, in place
+ of `fd`. Windows only. **Default:** `null`
 * Returns: {fs.WriteStream}
 
 `options` may also include a `start` option to allow writing data at some
@@ -3137,6 +3153,12 @@ then the file descriptor won't be closed, even if there's an error.
 It is the application's responsibility to close it and make sure there's no
 file descriptor leak.
 
+On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
+use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
+obtained from another process, pass it as `windowsHandle`. The handle is wrapped
+in a file descriptor that the stream owns and closes. The `windowsHandle` option
+throws on non-Windows platforms and cannot be combined with the `fs` option.
+
 By default, the stream will emit a `'close'` event after it has been
 destroyed. Set the `emitClose` option to `false` to change this behavior.
 

lib/internal/fs/streams.js

@@ -13,13 +13,17 @@ const {
 }=primordials;
 
 const{
+ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
+ERR_INCOMPATIBLE_OPTION_PAIR,
 ERR_INVALID_ARG_TYPE,
 ERR_METHOD_NOT_IMPLEMENTED,
+ERR_MISSING_OPTION,
 ERR_OUT_OF_RANGE,
 ERR_STREAM_DESTROYED,
 ERR_SYSTEM_ERROR,
 }=require('internal/errors').codes;
 const{
+ isWindows,
  kEmptyObject,
 }=require('internal/util');
 const{
@@ -40,6 +44,8 @@ const {
 }=require('internal/fs/utils');
 const{ Readable, Writable, finished }=require('stream');
 const{ toPathIfFileURL }=require('internal/url');
+constbinding=internalBinding('fs');
+const{O_RDONLY,O_WRONLY}=internalBinding('constants').fs;
 constkIoDone=Symbol('kIoDone');
 constkIsPerformingIO=Symbol('kIsPerformingIO');
 
@@ -160,6 +166,26 @@ function importFd(stream, options) {
 ['number','FileHandle'],options.fd);
 }
 
+functionimportWindowsHandle(stream,options,flags){
+if(options.windowsHandle==null){
+thrownewERR_MISSING_OPTION('options.windowsHandle');
+}
+if(!isWindows){
+thrownewERR_FEATURE_UNAVAILABLE_ON_PLATFORM('windowsHandle');
+}
+if(options.fs){
+// The HANDLE is wrapped using the real filesystem, so a custom fs
+// implementation cannot be combined with it.
+thrownewERR_METHOD_NOT_IMPLEMENTED('windowsHandle with fs');
+}
+if(typeofoptions.windowsHandle!=='bigint'){
+thrownewERR_INVALID_ARG_TYPE('options.windowsHandle','bigint',
+options.windowsHandle);
+}
+stream[kFs]=fs;
+returnbinding.handleToFd(options.windowsHandle,flags);
+}
+
 functionReadStream(path,options){
 if(!(thisinstanceofReadStream))
 returnnewReadStream(path,options);
@@ -173,7 +199,11 @@ function ReadStream(path, options) {
 options.autoDestroy=false;
 }
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_RDONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');
@@ -325,7 +355,11 @@ function WriteStream(path, options) {
 // Only buffers are supported.
 options.decodeStrings=true;
 
-if(options.fd==null){
+if(options.fd!=null&&options.windowsHandle!=null){
+thrownewERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle','fd');
+}elseif(options.windowsHandle!=null){
+this.fd=getValidatedFd(importWindowsHandle(this,options,O_WRONLY));
+}elseif(options.fd==null){
 this.fd=null;
 this[kFs]=options.fs||fs;
 validateFunction(this[kFs].open,'options.fs.open');

src/node_file.cc

@@ -4150,6 +4150,33 @@ InternalFieldInfoBase* BindingData::Serialize(int index) {
 return info;
 }
 
+#ifdef _WIN32
+staticvoidHandleToFd(const FunctionCallbackInfo<Value>& args) {
+ Environment* env = Environment::GetCurrent(args);
+CHECK_GE(args.Length(), 1);
+CHECK(args[0]->IsBigInt());
+
+int flags = 0;
+if (args[1]->IsNumber()) {
+ flags = args[1].As<Int32>()->Value();
+ }
+
+bool lossless;
+int64_t handle = args[0].As<BigInt>()->Int64Value(&lossless);
+if (!lossless) {
+returnTHROW_ERR_OUT_OF_RANGE(env,
+"windowsHandle does not fit into 64 bits");
+ }
+intptr_t value = static_cast<intptr_t>(handle);
+
+int fd = _open_osfhandle(value, flags);
+if (fd == -1) {
+return env->ThrowErrnoException(errno, "_open_osfhandle");
+ }
+ args.GetReturnValue().Set(fd);
+}
+#endif// _WIN32
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
@@ -4216,6 +4243,10 @@ static void CreatePerIsolateProperties(IsolateData* isolate_data,
 
 SetMethod(isolate, target, "mkdtemp", Mkdtemp);
 
+#ifdef _WIN32
+SetMethod(isolate, target, "handleToFd", HandleToFd);
+#endif
+
 SetMethod(isolate, target, "cpSyncCheckPaths", CpSyncCheckPaths);
 SetMethod(isolate, target, "cpSyncOverrideFile", CpSyncOverrideFile);
 SetMethod(isolate, target, "cpSyncCopyDir", CpSyncCopyDir);
@@ -4343,6 +4374,9 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
  registry->Register(LUTimes);
 
  registry->Register(Mkdtemp);
+#ifdef _WIN32
+ registry->Register(HandleToFd);
+#endif
  registry->Register(NewFSReqCallback);
 
  registry->Register(FileHandle::New);

test/addons/fs-windows-handle/binding.cc

@@ -0,0 +1,62 @@
+#include<node.h>
+#include<v8.h>
+
+#ifdef _WIN32
+#include<windows.h>
+#endif
+
+namespace {
+
+using v8::BigInt;
+using v8::Context;
+using v8::FunctionCallbackInfo;
+using v8::Isolate;
+using v8::Local;
+using v8::Object;
+using v8::String;
+using v8::Value;
+
+// Creates an anonymous pipe and returns its raw Win32 read/write HANDLE values
+// as JS bigints. These are NOT CRT file descriptors, so passing them as the
+// `windowsHandle` stream option exercises the HANDLE -> fd conversion path on
+// Windows. Returns undefined on other platforms.
+voidCreatePipeHandles(const FunctionCallbackInfo<Value>& args) {
+ Isolate* isolate = args.GetIsolate();
+#ifdef _WIN32
+ Local<Context> context = isolate->GetCurrentContext();
+
+HANDLE read_handle = nullptr;
+HANDLE write_handle = nullptr;
+if (!CreatePipe(&read_handle, &write_handle, nullptr, 0)) {
+ isolate->ThrowException(v8::Exception::Error(
+String::NewFromUtf8(isolate, "CreatePipe failed").ToLocalChecked()));
+return;
+ }
+
+ Local<Object> result = Object::New(isolate);
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "readHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(read_handle))))
+ .Check();
+ result
+ ->Set(context,
+String::NewFromUtf8(isolate, "writeHandle").ToLocalChecked(),
+BigInt::New(
+ isolate,
+static_cast<int64_t>(reinterpret_cast<intptr_t>(write_handle))))
+ .Check();
+ args.GetReturnValue().Set(result);
+#else
+ args.GetReturnValue().SetUndefined();
+#endif
+}
+
+} // anonymous namespace
+
+extern"C"NODE_MODULE_EXPORTvoidNODE_MODULE_INITIALIZER(
+ Local<Object> exports, Local<Value> module, Local<Context> context) {
+NODE_SET_METHOD(exports, "createPipeHandles", CreatePipeHandles);
+}

test/addons/fs-windows-handle/binding.gyp

@@ -0,0 +1,9 @@
+{
+'targets': [
+ {
+'target_name': 'binding',
+'sources': [ 'binding.cc' ],
+'includes': ['../common.gypi'],
+ },
+ ]
+}

test/addons/fs-windows-handle/test.js

@@ -0,0 +1,35 @@
+'use strict';
+// Verifies that fs.createReadStream()/createWriteStream() accept a raw Win32
+// HANDLE through the `windowsHandle` option, as happens when a parent process
+// passes an inherited anonymous pipe handle. The addon produces such handles
+// via CreatePipe(); Node must wrap them in CRT file descriptors instead of
+// failing with EBADF.
+
+constcommon=require('../../common');
+
+if(!common.isWindows){
+common.skip('windowsHandle is Windows-only');
+}
+
+constassert=require('assert');
+constfs=require('fs');
+
+constbinding=require(`./build/${common.buildType}/binding`);
+
+const{ readHandle, writeHandle }=binding.createPipeHandles();
+assert.strictEqual(typeofreadHandle,'bigint');
+assert.strictEqual(typeofwriteHandle,'bigint');
+
+constpayload='payload';
+
+constchunks=[];
+constrs=fs.createReadStream(null,{windowsHandle: readHandle});
+rs.on('error',(err)=>assert.fail(err));
+rs.on('data',(chunk)=>chunks.push(chunk));
+rs.on('end',common.mustCall(()=>{
+assert.strictEqual(Buffer.concat(chunks).toString(),payload);
+}));
+
+constws=fs.createWriteStream(null,{windowsHandle: writeHandle});
+ws.on('error',(err)=>assert.fail(err));
+ws.end(payload);

test/parallel/test-fs-stream-windows-handle.js

@@ -0,0 +1,47 @@
+'use strict';
+
+// Tests option validation for the `windowsHandle` option of
+// fs.createReadStream()/createWriteStream(). The functional round-trip on
+// Windows (where a real Win32 HANDLE is wrapped in a file descriptor) is
+// covered by test/addons/fs-windows-handle.
+
+constcommon=require('../common');
+constassert=require('assert');
+constfs=require('fs');
+
+consthandle=1n;
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle,fd: 2}),{
+code: 'ERR_INCOMPATIBLE_OPTION_PAIR',
+});
+}
+
+if(!common.isWindows){
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+assert.throws(()=>create(null,{windowsHandle: handle}),{
+code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
+});
+}
+return;
+}
+
+for(constcreateof[fs.createReadStream,fs.createWriteStream]){
+// Cannot be combined with a custom `fs` implementation.
+assert.throws(()=>create(null,{windowsHandle: handle,fs: {}}),{
+code: 'ERR_METHOD_NOT_IMPLEMENTED',
+});
+
+// Must be a bigint.
+assert.throws(()=>create(null,{windowsHandle: 'nope'}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+assert.throws(()=>create(null,{windowsHandle: 1}),{
+code: 'ERR_INVALID_ARG_TYPE',
+});
+
+// Must fit into 64 bits.
+assert.throws(()=>create(null,{windowsHandle: 2n**64n}),{
+code: 'ERR_OUT_OF_RANGE',
+});
+}