Skip to content

Commit 0067917

Browse files
committed
fs: add windowsHandle option to file streams
Fixes: nodejs#57288 Signed-off-by: PickBas <[email protected]>
1 parent 19c46ab commit 0067917

7 files changed

Lines changed: 234 additions & 2 deletions

File tree

‎doc/api/fs.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2849,6 +2849,9 @@ behavior is similar to `cp dir1/ dir2/`.
28492849
<!-- YAML
28502850
added: v0.1.31
28512851
changes:
2852+
- version: REPLACEME
2853+
pr-url: https://github.com/nodejs/node/pull/63851
2854+
description: Add the `windowsHandle` option.
28522855
- version: v16.10.0
28532856
pr-url: https://github.com/nodejs/node/pull/40013
28542857
description: The `fs` option does not need `open` method if an `fd` was provided.
@@ -2905,6 +2908,8 @@ changes:
29052908
* `highWaterMark` {integer} **Default:** `64 * 1024`
29062909
* `fs` {Object|null} **Default:** `null`
29072910
* `signal` {AbortSignal|null} **Default:** `null`
2911+
* `windowsHandle` {integer} A raw Win32 `HANDLE` value to read from, in place
2912+
of `fd`. Windows only. **Default:** `null`
29082913
* Returns: {fs.ReadStream}
29092914
29102915
`options` can include `start` and `end` values to read a range of bytes from
@@ -2925,6 +2930,12 @@ If `fd` points to a character device that only supports blocking reads
29252930
available. This can prevent the process from exiting and the stream from
29262931
closing naturally.
29272932
2933+
On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
2934+
use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
2935+
obtained from another process, pass it as `windowsHandle`. The handle is wrapped
2936+
in a file descriptor that the stream owns and closes. The `windowsHandle` option
2937+
throws on non-Windows platforms and cannot be combined with the `fs` option.
2938+
29282939
By default, the stream will emit a `'close'` event after it has been
29292940
destroyed. Set the `emitClose` option to `false` to change this behavior.
29302941
@@ -2975,6 +2986,9 @@ If `options` is a string, then it specifies the encoding.
29752986
<!-- YAML
29762987
added: v0.1.31
29772988
changes:
2989+
- version: REPLACEME
2990+
pr-url: https://github.com/nodejs/node/pull/63851
2991+
description: Add the `windowsHandle` option.
29782992
- version:
29792993
- v21.0.0
29802994
- v20.10.0
@@ -3035,6 +3049,8 @@ changes:
30353049
* `highWaterMark` {number} **Default:** `16384`
30363050
* `flush` {boolean} If `true`, the underlying file descriptor is flushed
30373051
prior to closing it. **Default:** `false`.
3052+
* `windowsHandle` {integer} A raw Win32 `HANDLE` value to write to, in place
3053+
of `fd`. Windows only. **Default:** `null`
30383054
* Returns: {fs.WriteStream}
30393055
30403056
`options` may also include a `start` option to allow writing data at some
@@ -3049,6 +3065,12 @@ then the file descriptor won't be closed, even if there's an error.
30493065
It is the application's responsibility to close it and make sure there's no
30503066
file descriptor leak.
30513067
3068+
On Windows, a value passed in `fd` is interpreted as a CRT file descriptor. To
3069+
use a raw Win32 `HANDLE` instead, such as an inherited anonymous pipe handle
3070+
obtained from another process, pass it as `windowsHandle`. The handle is wrapped
3071+
in a file descriptor that the stream owns and closes. The `windowsHandle` option
3072+
throws on non-Windows platforms and cannot be combined with the `fs` option.
3073+
30523074
By default, the stream will emit a `'close'` event after it has been
30533075
destroyed. Set the `emitClose` option to `false` to change this behavior.
30543076

‎lib/internal/fs/streams.js‎

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,11 @@ const {
1313
} = primordials;
1414

1515
const {
16+
ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
17+
ERR_INCOMPATIBLE_OPTION_PAIR,
1618
ERR_INVALID_ARG_TYPE,
1719
ERR_METHOD_NOT_IMPLEMENTED,
20+
ERR_MISSING_OPTION,
1821
ERR_OUT_OF_RANGE,
1922
ERR_STREAM_DESTROYED,
2023
ERR_SYSTEM_ERROR,
@@ -40,6 +43,9 @@ const {
4043
} = require('internal/fs/utils');
4144
const { Readable, Writable, finished } = require('stream');
4245
const { toPathIfFileURL } = require('internal/url');
46+
const { isWindows } = require('internal/util');
47+
const binding = internalBinding('fs');
48+
const { O_RDONLY, O_WRONLY } = internalBinding('constants').fs;
4349
const kIoDone = Symbol('kIoDone');
4450
const kIsPerformingIO = Symbol('kIsPerformingIO');
4551

@@ -160,6 +166,23 @@ function importFd(stream, options) {
160166
['number', 'FileHandle'], options.fd);
161167
}
162168

169+
function importWindowsHandle(stream, options, flags) {
170+
if (options.windowsHandle == null) {
171+
throw new ERR_MISSING_OPTION('options.windowsHandle');
172+
}
173+
if (!isWindows) {
174+
throw new ERR_FEATURE_UNAVAILABLE_ON_PLATFORM('windowsHandle');
175+
}
176+
if (options.fs) {
177+
// The HANDLE is wrapped using the real filesystem, so a custom fs
178+
// implementation cannot be combined with it.
179+
throw new ERR_METHOD_NOT_IMPLEMENTED('windowsHandle with fs');
180+
}
181+
validateInteger(options.windowsHandle, 'options.windowsHandle');
182+
stream[kFs] = fs;
183+
return binding.handleToFd(options.windowsHandle, flags);
184+
}
185+
163186
function ReadStream(path, options) {
164187
if (!(this instanceof ReadStream))
165188
return new ReadStream(path, options);
@@ -173,7 +196,11 @@ function ReadStream(path, options) {
173196
options.autoDestroy = false;
174197
}
175198

176-
if (options.fd == null) {
199+
if (options.fd != null && options.windowsHandle != null) {
200+
throw new ERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle', 'fd');
201+
} else if (options.windowsHandle != null) {
202+
this.fd = getValidatedFd(importWindowsHandle(this, options, O_RDONLY));
203+
} else if (options.fd == null) {
177204
this.fd = null;
178205
this[kFs] = options.fs || fs;
179206
validateFunction(this[kFs].open, 'options.fs.open');
@@ -325,7 +352,11 @@ function WriteStream(path, options) {
325352
// Only buffers are supported.
326353
options.decodeStrings = true;
327354

328-
if (options.fd == null) {
355+
if (options.fd != null && options.windowsHandle != null) {
356+
throw new ERR_INCOMPATIBLE_OPTION_PAIR('windowsHandle', 'fd');
357+
} else if (options.windowsHandle != null) {
358+
this.fd = getValidatedFd(importWindowsHandle(this, options, O_WRONLY));
359+
} else if (options.fd == null) {
329360
this.fd = null;
330361
this[kFs] = options.fs || fs;
331362
validateFunction(this[kFs].open, 'options.fs.open');

‎src/node_file.cc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4132,6 +4132,28 @@ InternalFieldInfoBase* BindingData::Serialize(int index) {
41324132
return info;
41334133
}
41344134

4135+
#ifdef _WIN32
4136+
static void HandleToFd(const FunctionCallbackInfo<Value>& args) {
4137+
Environment* env = Environment::GetCurrent(args);
4138+
CHECK_GE(args.Length(), 1);
4139+
CHECK(args[0]->IsNumber());
4140+
4141+
int flags = 0;
4142+
if (args[1]->IsNumber()) {
4143+
flags = args[1].As<Int32>()->Value();
4144+
}
4145+
4146+
intptr_t value =
4147+
static_cast<intptr_t>(args[0].As<Number>()->Value());
4148+
4149+
int fd = _open_osfhandle(value, flags);
4150+
if (fd == -1) {
4151+
return env->ThrowErrnoException(errno, "_open_osfhandle");
4152+
}
4153+
args.GetReturnValue().Set(fd);
4154+
}
4155+
#endif // _WIN32
4156+
41354157
void BindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
41364158
Local<ObjectTemplate> target) {
41374159
Isolate* isolate = isolate_data->isolate();
@@ -4198,6 +4220,10 @@ static void CreatePerIsolateProperties(IsolateData* isolate_data,
41984220

41994221
SetMethod(isolate, target, "mkdtemp", Mkdtemp);
42004222

4223+
#ifdef _WIN32
4224+
SetMethod(isolate, target, "handleToFd", HandleToFd);
4225+
#endif
4226+
42014227
SetMethod(isolate, target, "cpSyncCheckPaths", CpSyncCheckPaths);
42024228
SetMethod(isolate, target, "cpSyncOverrideFile", CpSyncOverrideFile);
42034229
SetMethod(isolate, target, "cpSyncCopyDir", CpSyncCopyDir);
@@ -4325,6 +4351,9 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
43254351
registry->Register(LUTimes);
43264352

43274353
registry->Register(Mkdtemp);
4354+
#ifdef _WIN32
4355+
registry->Register(HandleToFd);
4356+
#endif
43284357
registry->Register(NewFSReqCallback);
43294358

43304359
registry->Register(FileHandle::New);
Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
#include <node.h>
2+
#include <v8.h>
3+
4+
#ifdef _WIN32
5+
#include <windows.h>
6+
#endif
7+
8+
namespace {
9+
10+
using v8::Context;
11+
using v8::FunctionCallbackInfo;
12+
using v8::Isolate;
13+
using v8::Local;
14+
using v8::Number;
15+
using v8::Object;
16+
using v8::String;
17+
using v8::Value;
18+
19+
// Creates an anonymous pipe and returns its raw Win32 read/write HANDLE values
20+
// as JS numbers. These are NOT CRT file descriptors, so passing them as the
21+
// `windowsHandle` stream option exercises the HANDLE -> fd conversion path on
22+
// Windows. Returns undefined on other platforms.
23+
void CreatePipeHandles(const FunctionCallbackInfo<Value>& args) {
24+
Isolate* isolate = args.GetIsolate();
25+
#ifdef _WIN32
26+
Local<Context> context = isolate->GetCurrentContext();
27+
28+
HANDLE read_handle = nullptr;
29+
HANDLE write_handle = nullptr;
30+
if (!CreatePipe(&read_handle, &write_handle, nullptr, 0)) {
31+
isolate->ThrowException(v8::Exception::Error(
32+
String::NewFromUtf8(isolate, "CreatePipe failed").ToLocalChecked()));
33+
return;
34+
}
35+
36+
Local<Object> result = Object::New(isolate);
37+
result
38+
->Set(context,
39+
String::NewFromUtf8(isolate, "readHandle").ToLocalChecked(),
40+
Number::New(isolate,
41+
static_cast<double>(
42+
reinterpret_cast<intptr_t>(read_handle))))
43+
.Check();
44+
result
45+
->Set(context,
46+
String::NewFromUtf8(isolate, "writeHandle").ToLocalChecked(),
47+
Number::New(isolate,
48+
static_cast<double>(
49+
reinterpret_cast<intptr_t>(write_handle))))
50+
.Check();
51+
args.GetReturnValue().Set(result);
52+
#else
53+
args.GetReturnValue().SetUndefined();
54+
#endif
55+
}
56+
57+
} // anonymous namespace
58+
59+
extern "C" NODE_MODULE_EXPORT void
60+
NODE_MODULE_INITIALIZER(Local<Object> exports,
61+
Local<Value> module,
62+
Local<Context> context) {
63+
NODE_SET_METHOD(exports, "createPipeHandles", CreatePipeHandles);
64+
}
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
'targets': [
3+
{
4+
'target_name': 'binding',
5+
'sources': [ 'binding.cc' ],
6+
'includes': ['../common.gypi'],
7+
},
8+
]
9+
}
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
'use strict';
2+
// Verifies that fs.createReadStream()/createWriteStream() accept a raw Win32
3+
// HANDLE through the `windowsHandle` option, as happens when a parent process
4+
// passes an inherited anonymous pipe handle. The addon produces such handles
5+
// via CreatePipe(); Node must wrap them in CRT file descriptors instead of
6+
// failing with EBADF.
7+
8+
const common = require('../../common');
9+
10+
if (!common.isWindows) {
11+
common.skip('windowsHandle is Windows-only');
12+
}
13+
14+
const assert = require('assert');
15+
const fs = require('fs');
16+
17+
const binding = require(`./build/${common.buildType}/binding`);
18+
19+
const { readHandle, writeHandle } = binding.createPipeHandles();
20+
assert.strictEqual(typeof readHandle, 'number');
21+
assert.strictEqual(typeof writeHandle, 'number');
22+
23+
const payload = 'payload';
24+
25+
const chunks = [];
26+
const rs = fs.createReadStream(null, { windowsHandle: readHandle });
27+
rs.on('error', (err) => assert.fail(err));
28+
rs.on('data', (chunk) => chunks.push(chunk));
29+
rs.on('end', common.mustCall(() => {
30+
assert.strictEqual(Buffer.concat(chunks).toString(), payload);
31+
}));
32+
33+
const ws = fs.createWriteStream(null, { windowsHandle: writeHandle });
34+
ws.on('error', (err) => assert.fail(err));
35+
ws.end(payload);
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
'use strict';
2+
3+
// Tests option validation for the `windowsHandle` option of
4+
// fs.createReadStream()/createWriteStream(). The functional round-trip on
5+
// Windows (where a real Win32 HANDLE is wrapped in a file descriptor) is
6+
// covered by test/addons/fs-windows-handle.
7+
8+
const common = require('../common');
9+
const assert = require('assert');
10+
const fs = require('fs');
11+
12+
const handle = 1;
13+
14+
for (const create of [fs.createReadStream, fs.createWriteStream]) {
15+
assert.throws(() => create(null, { windowsHandle: handle, fd: 2 }), {
16+
code: 'ERR_INCOMPATIBLE_OPTION_PAIR',
17+
});
18+
}
19+
20+
if (!common.isWindows) {
21+
for (const create of [fs.createReadStream, fs.createWriteStream]) {
22+
assert.throws(() => create(null, { windowsHandle: handle }), {
23+
code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
24+
});
25+
}
26+
return;
27+
}
28+
29+
for (const create of [fs.createReadStream, fs.createWriteStream]) {
30+
// Cannot be combined with a custom `fs` implementation.
31+
assert.throws(() => create(null, { windowsHandle: handle, fs: {} }), {
32+
code: 'ERR_METHOD_NOT_IMPLEMENTED',
33+
});
34+
35+
// Must be an integer.
36+
assert.throws(() => create(null, { windowsHandle: 'nope' }), {
37+
code: 'ERR_INVALID_ARG_TYPE',
38+
});
39+
assert.throws(() => create(null, { windowsHandle: 1.5 }), {
40+
code: 'ERR_OUT_OF_RANGE',
41+
});
42+
}

0 commit comments

Comments
 (0)