Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions doc/api/zlib.md
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,16 @@ deallocation, this may lead to significant memory fragmentation.
It is strongly recommended that the results of compression
operations be cached to avoid duplication of effort.

Because the asynchronous `zlib` APIs run on the internal threadpool, the
input and output buffers are accessed by a worker thread through raw pointers
for the duration of the operation. The underlying `ArrayBuffer` of a buffer
passed to (or produced by) an asynchronous compress/decompress operation must
not be detached (for example with `ArrayBuffer.prototype.transfer()`),
transferred via a structured clone or `postMessage()`, or resized (with
`ResizableArrayBuffer.prototype.resize()`) until the operation has completed.
Doing so invalidates the memory the worker thread is reading or writing and
causes the operation to fail with an error.

## Compressing HTTP requests and responses

The `node:zlib` module can be used to implement support for the `gzip`, `deflate`,
Expand Down
47 changes: 33 additions & 14 deletions lib/zlib.js
Original file line number Diff line number Diff line change
Expand Up @@ -687,7 +687,18 @@ function processCallback() {
const have = handle.availOutBefore - availOutAfter;
let streamBufferIsFull = false;
if (have > 0) {
const out = self._outBuffer.slice(self._outOffset, self._outOffset + have);
let out;
try {
out = self._outBuffer.slice(self._outOffset, self._outOffset + have);
} catch (err) {
// The output buffer was detached/resized while the operation ran, so the
// compressed data cannot be read back. Surface it as a stream error
// rather than an uncaught exception.
this.buffer = null;
self.destroy(err);
this.cb(err);
return;
}
self._outOffset += have;
if (self[kBufferResult] === true)
zlibBufferAddChunk(self, out);
Expand Down Expand Up @@ -719,26 +730,34 @@ function processCallback() {
handle.inOff += inDelta;
handle.availInBefore = availInAfter;


if (!streamBufferIsFull) {
this.write(handle.flushFlag,
this.buffer, // in
handle.inOff, // in_off
handle.availInBefore, // in_len
self._outBuffer, // out
self._outOffset, // out_off
self._chunkSize); // out_len
} else {
const oldRead = self._read;
self._read = (n) => {
self._read = oldRead;
// If the input/output buffer was detached or resized while the operation
// was in flight, the native bindings throw ERR_OUT_OF_RANGE. That must be
// surfaced as a stream error rather than an uncaught exception.
const reprocess = () => {
try {
this.write(handle.flushFlag,
this.buffer, // in
handle.inOff, // in_off
handle.availInBefore, // in_len
self._outBuffer, // out
self._outOffset, // out_off
self._chunkSize); // out_len
} catch (err) {
// The buffer backing store was invalidated while the worker ran; the
// stream cannot make further progress on it.
this.buffer = null;
self.destroy(err);
this.cb(err);
}
};

if (!streamBufferIsFull) {
reprocess();
} else {
const oldRead = self._read;
self._read = (n) => {
self._read = oldRead;
reprocess();
self._read(n);
};
}
Expand Down
116 changes: 114 additions & 2 deletions src/node_zlib.cc
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@
#include <cerrno>
#include <cstdlib>
#include <cstring>
#include <memory>
#include <optional>
#include <utility>
#include <vector>
Expand Down Expand Up @@ -547,6 +548,7 @@ class CompressionStream : public AsyncWrap,
uint32_t in_off, in_len, out_off, out_len, flush;
const char* in;
char* out;
Local<Object> in_buf;

CHECK_EQ(false, args[0]->IsUndefined() && "must provide flush value");
if (!args[0]->Uint32Value(context).To(&flush)) return;
Expand All @@ -567,7 +569,7 @@ class CompressionStream : public AsyncWrap,
in_off = 0;
} else {
CHECK(Buffer::HasInstance(args[1]));
Local<Object> in_buf = args[1].As<Object>();
in_buf = args[1].As<Object>();
if (!args[2]->Uint32Value(context).To(&in_off)) return;
if (!args[3]->Uint32Value(context).To(&in_len)) return;

Expand All @@ -589,6 +591,11 @@ class CompressionStream : public AsyncWrap,
CompressionStream* ctx;
ASSIGN_OR_RETURN_UNWRAP(&ctx, args.This());

if constexpr (async) {
ctx->SetAsyncWriteBuffers(
in_buf, in_off, in_len, out_buf, out_off, out_len, &in, &out);
}

ctx->Write<async>(flush, in, in_len, out, out_len);
}

Expand Down Expand Up @@ -625,6 +632,89 @@ class CompressionStream : public AsyncWrap,
ScheduleWork();
}

// The thread-pool worker operates on raw pointers into the JavaScript-owned
// backing stores of the input/output buffers. For an asynchronous write, pin
// those backing stores so that detaching or garbage-collecting the
// ArrayBuffers cannot free the memory while the work is in flight. A
// resizable ArrayBuffer can still have its pages decommitted by resize(), so
// such buffers are copied into memory owned by this object instead, and the
// output is copied back once the work completes. On entry, `in` and `out`
// point into the JS buffers (or `nullptr` for a pure flush); for resizable
// buffers they are redirected to the engine-owned copies.
void SetAsyncWriteBuffers(Local<Object> in_buf,
uint32_t in_off,
uint32_t in_len,
Local<Object> out_buf,
uint32_t out_off,
uint32_t out_len,
const char** in,
char** out) {
ClearWriteState();

if (!in_buf.IsEmpty()) {
Local<v8::ArrayBufferView> in_view = in_buf.As<v8::ArrayBufferView>();
std::shared_ptr<v8::BackingStore> in_store =
in_view->Buffer()->GetBackingStore();
if (in_store->IsResizableByUserJavaScript()) {
input_copy_ = std::make_unique<char[]>(in_len);
memcpy(input_copy_.get(), Buffer::Data(in_buf) + in_off, in_len);
*in = input_copy_.get();
} else {
input_store_ = std::move(in_store);
}
}

Local<v8::ArrayBufferView> out_view = out_buf.As<v8::ArrayBufferView>();
std::shared_ptr<v8::BackingStore> out_store =
out_view->Buffer()->GetBackingStore();
if (out_store->IsResizableByUserJavaScript()) {
output_copy_ = std::make_unique<char[]>(out_len);
output_copy_len_ = out_len;
output_copy_out_off_ = out_off;
output_copy_view_.Reset(AsyncWrap::env()->isolate(), out_view);
*out = output_copy_.get();
} else {
output_store_ = std::move(out_store);
}
}

// Copy staged output (used for resizable output buffers) back into the
// JavaScript buffer. Only bytes that still fit are copied so that we never
// write to pages that have been decommitted by a resize() while the work was
// in flight.
void CopyBackOutput() {
if (output_copy_ == nullptr || output_copy_view_.IsEmpty()) return;

Local<v8::ArrayBufferView> out_view =
output_copy_view_.Get(AsyncWrap::env()->isolate());
Local<Object> out_obj = out_view.As<Object>();
const size_t length = Buffer::Length(out_obj);
if (output_copy_out_off_ >= length) return;

// `write_result_[0]` holds the remaining output space of the staged buffer;
// it can never exceed what we provided, but guard against any unexpected
// value to avoid a size_t underflow.
if (write_result_[0] >= output_copy_len_) return;

const size_t written = output_copy_len_ - write_result_[0];
const size_t to_copy = written < length - output_copy_out_off_
? written
: length - output_copy_out_off_;
memcpy(Buffer::Data(out_obj) + output_copy_out_off_,
output_copy_.get(),
to_copy);
}

void ClearWriteState() {
input_store_.reset();
output_store_.reset();
input_copy_.reset();
output_copy_.reset();
output_copy_len_ = 0;
output_copy_out_off_ = 0;
output_copy_view_.Reset();
}

void UpdateWriteResult() {
ctx_.GetAfterWriteOffsets(&write_result_[1], &write_result_[0]);
}
Expand Down Expand Up @@ -655,6 +745,7 @@ class CompressionStream : public AsyncWrap,
write_in_progress_ = false;

if (status == UV_ECANCELED) {
ClearWriteState();
Close();
return;
}
Expand All @@ -665,11 +756,19 @@ class CompressionStream : public AsyncWrap,
HandleScope handle_scope(env->isolate());
Context::Scope context_scope(env->context());

if (!CheckError())
if (!CheckError()) {
ClearWriteState();
return;
}

UpdateWriteResult();

// Copy any staged output (resizable output buffers) back into the JS
// buffer, and release the backing-store pins, before running the callback
// (which may reschedule the next chunk of the same write).
CopyBackOutput();
ClearWriteState();

// call the write() cb
Local<Value> cb =
object()->GetInternalField(kWriteJSCallback).template As<Value>();
Expand Down Expand Up @@ -779,6 +878,19 @@ class CompressionStream : public AsyncWrap,
unsigned int refs_ = 0;
uint32_t* write_result_ = nullptr;

// Backing-store pins and engine-owned copies for the input/output buffers of
// an asynchronous write. See SetAsyncWriteBuffers(). Holding a
// std::shared_ptr<v8::BackingStore> keeps the underlying memory alive even if
// the JS ArrayBuffer is detached or garbage-collected while the thread-pool
// worker reads/writes through a raw pointer.
std::shared_ptr<v8::BackingStore> input_store_;
std::shared_ptr<v8::BackingStore> output_store_;
std::unique_ptr<char[]> input_copy_;
std::unique_ptr<char[]> output_copy_;
size_t output_copy_len_ = 0;
uint32_t output_copy_out_off_ = 0;
v8::Global<v8::ArrayBufferView> output_copy_view_;

CompressionContext ctx_;
};

Expand Down
Loading
Loading