@encharm/cws 4.5.3 → 4.6.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## Released 4.6.0
+* Add Node 26 support (ABI 147, V8 14.6): vendored `src/headers/26`, `MakeCallback` with explicit `async_context`, tagged internal-field reads via `BaseObject::FromJSObject`.
+* Cork writes per event-loop iteration: sends to the same socket within one tick go out in a single gathered write. Disable with `CWS_CORK=0`.
+* Binary messages are detached after the `message` handler returns. A retained `ArrayBuffer` now throws on use instead of exposing another connection's bytes (the receive buffer is shared). Copy with `slice()` if the data is needed later.
+* Fix use-after-free when a send callback closes the socket while its write queue is draining.
+* `terminate()` on an already closed socket is a no-op.
+* The `message` handler is now dispatched through `MakeCallback` like every other handler: correct AsyncLocalStorage propagation, exceptions reach `uncaughtException`, and microtasks drain after each message instead of after the whole poll phase. No measurable throughput cost.
+* Fix `send()` of a typed array that is a subarray (non-zero `byteOffset`): the bytes were read from the start of the underlying ArrayBuffer instead of the view's offset.
+
 ## Released 4.1.0
 * Add support for socket.bufferedAmount
 

package/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`@encharm/cws` is a native C++ WebSocket implementation for Node.js that aims to be a near drop-in replacement for the `ws` module. It is a fork of ClusterWS/cWS, which itself forked uWebSockets v0.14 (dual MIT + ZLIB license, see `LICENSE` and `src/LICENSE`). Prebuilt binaries for every supported platform/ABI are committed under `dist/bindings/` and published with the package; end users never compile.
+
+## Commands
+
+```sh
+npm run build-ts        # lint + tsc: lib/*.ts -> dist/*.js + *.d.ts (dist JS is committed)
+npm run lint            # tslint over lib/**/*.ts
+npm test                # nyc + mocha, runs tests/**/*.test.ts via ts-node (loads ../lib, not dist)
+npx mocha -r ts-node/register tests/server-client.test.ts -g "ping/pong" --exit   # single test
+npm run build-cpp       # node-gyp rebuild for the *current* Node ABI only; output goes to build_log.txt, never fails the install
+npm run clean           # deletes dist/bindings/* (all committed binaries!) -- don't run casually
+```
+
+Tests bind ports 3000 (ws) and 3001 (wss, certs in `tests/certs/`). The test file currently iterates only `['Non-SSL']`; the SSL loop is wired up but disabled. `tests/autobahn-*.js` are manual Autobahn testsuite harnesses, not part of `npm test`.
+
+### Building the release binaries (multi-ABI)
+
+`binding.gyp` is only used by `npm install` for a local build against the running Node. Release binaries are built by the `Makefile` (macOS/Linux) and `make.bat` (Windows), which:
+
+1. Download official Node header tarballs for one pinned version per supported major into `targets/` (`VER_115`=Node 20, `VER_127`=Node 22, `VER_137`=Node 24, `VER_147`=Node 26; the number is the Node ABI / `process.versions.modules`).
+2. Compile `src/*.cpp` once per ABI with `g++`/`cl` directly, with `-I src/headers/$V` for the matching Node major.
+3. Emit `dist/bindings/cws_<platform>_<arch>_node<ABI>.node`.
+
+```sh
+make                                  # all three ABIs for the host OS/arch (needs curl + g++/clang)
+./build-on-docker.sh linux/arm64      # Linux arm64 (native on Apple Silicon, ~1 min)
+./build-on-docker.sh linux/amd64      # Linux x64 (default; emulated on Apple Silicon, slower)
+make.bat                              # Windows x64; auto-detects VS 2022 (Build Tools or any edition)
+```
+
+All of it can be driven from the Mac. Docker builds mount the repo and write straight into `dist/bindings/`. The Windows build runs in the Parallels "Windows 11" VM through the shared folder (cmd refuses UNC batch paths, hence `pushd`):
+
+```sh
+prlctl resume "Windows 11"
+prlctl exec "Windows 11" cmd /c "pushd \\\\Mac\\code\\cWS && make.bat"   # 4 backslashes in zsh -> \\Mac
+prlctl suspend "Windows 11"
+```
+
+The VM is Windows on ARM: `vcvars64` still emits x64 code, so `make.bat` names outputs `win32_x64` explicitly, and testing them needs an x64 Node in the guest (an x64 zip from nodejs.org extracted under `C:\Temp` works; the guest's own ARM64 Node cannot load them). Docker base image is Ubuntu 22.04 = the minimum glibc baseline. Smoke-test a binding on its target Node with `node node_modules/mocha/bin/mocha -r ts-node/register 'tests/**/*.test.ts' --exit`, e.g. inside `node:22-bookworm` for Linux.
+
+Adding a new Node major means: add a `VER_xxx`/ABI line to `Makefile` and `make.bat`, vendor that Node version's private headers into `src/headers/<major>/`, and add a `#if NODE_MAJOR_VERSION==<major>` include block in `src/Addon.h`. Vendoring = copy every `src/**/*.h` from the Node source tarball, plus `deps/ncrypto/ncrypto.h` and any `deps/v8/include/*.h` missing from the official headers tarball, then make `ssl_` public in `crypto/crypto_tls.h` (`TLSWrapSSLGetter` needs it). For 26 there is a second edit: `MaybeStackBuffer::AllocateSufficientStorage` (primary and the concept-constrained `V8Type` partial specialization) and `ToPath` are defined in-class in `util.h` instead of out-of-line in `util-inl.h`, because MSVC `cl.exe` cannot match out-of-line member definitions once that constrained specialization exists (Node builds Windows with clang-cl, which the Parallels VM does not have). Both edits are marked with a `cWS:` comment. Node's gyp-only config macros (e.g. `HAVE_SQLITE`, `HAVE_AMARO` for 26) must be defined before the include. Expect V8 API churn in `Addon.h` on each major; 26 needed tagged internal-field reads (`BaseObject::FromJSObject`) and dropped `Object::GetIsolate` and the `MakeCallback` overload without `async_context`.
+
+## Architecture
+
+### Two layers, one binary
+
+- **`lib/*.ts` (thin JS facade)** compiled to `dist/`. `shared.ts` loads the native addon by filename `cws_${platform}_${arch}_node${versions.modules}` and wires native group callbacks (`onConnection`, `onMessage`, `onDisconnection`, …) to per-socket `registeredEvents`. Events are single-listener: `on()` overwrites, with a console warning. `client.ts` exports `WebSocket` (used for both client sockets and server-side peers, distinguished by `options.external`), `server.ts` exports `WebSocketServer` (aliased as `WebSocket.Server`).
+- **`src/` (C++ addon)** is the uWebSockets 0.14 core (`Hub`, `Group`, `WebSocket`, `HTTPSocket`, `Networking`, `WebSocketProtocol.h`, `Extensions` for permessage-deflate) plus the V8 binding layer in `src/Addon.h` / `Addon.cpp`. `Backend.h` picks the event backend: libuv everywhere (`-DUSE_LIBUV` is always set), the epoll backend in `Epoll.*` is legacy and not compiled in by the Makefile.
+
+### How a server connection gets into C++ (the important part)
+
+cWS does **not** run its own HTTP listener. `WebSocketServer` uses a Node `http`/`https` server (user-supplied or created internally) and hooks its `'upgrade'` event. In `upgradeConnection()`:
+
+1. It grabs the raw libuv handle from the Node socket (`socket._handle`, or `_parent._handle` for TLS).
+2. For TLS it calls `native.getSSLContext(socket.ssl)` to pull the raw `SSL*` out of Node's internal `TLSWrap`. This is why `src/headers/<major>/` vendors Node **private** headers (`crypto/crypto_tls.h`, `base_object-inl.h`, etc.) and `Addon.h` defines `NODE_WANT_INTERNALS` around them: `TLSWrapSSLGetter` subclasses `node::crypto::TLSWrap` to reach the protected `ssl_` member. This is the ABI-fragile part and the reason binaries are per-Node-major.
+3. `native.transfer(fd, ssl)` creates a `Ticket` and the Node socket is destroyed. On its `'close'` event, `native.upgrade(group, ticket, secKey, extensions, protocol)` hands the fd to the uWS `Hub`, which performs the WebSocket handshake and owns the socket from then on. On Linux with Node >= 20 the fd is `dup()`ed first as a workaround for io_uring (see comment in `Addon.h`).
+
+`noServer: true` + `handleUpgrade()` follows the same path for `ws` compatibility. `path` and `verifyClient` checks happen in JS before the transfer.
+
+### Client connections
+
+The client side never touches Node sockets: `native.connect(clientGroup, url, ws)` lets the uWS `Hub` do TCP/TLS itself using a process-wide `SSL_CTX` created in `cSNode.cpp` (TLS 1.0–1.2 only). `secureProtocol = 'TLSv1_2_method'` is exported for users to pin their https server to match.
+
+### Write corking
+
+`Socket::sendTransformed` does not write when the socket is corkable (WebSockets only, plain TCP only) and `NodeData::corkState->enabled` is set. It frames the message into the socket's `messageQueue` and registers the socket in the per-loop `corkState->pending` list. `Socket::flushCorked` drains that list with one `sendmsg`/`WSASend` gather per socket from two libuv hooks registered in `registerCheck` (`src/Addon.h`): a `uv_prepare` (before the loop blocks in poll) and the existing `uv_check` (after poll and after Node's immediates). Anything that cannot be written falls through to the normal `UV_WRITABLE` drain loop in `ioHandler`. `closeSocket`/`onEnd`/`transfer` call `flushCorkedOnClose`, which unregisters the socket and pushes what it can to the kernel without invoking callbacks. `CWS_CORK=0` disables it at addon load (`corkEnabledFromEnv`). `HttpSocket` is never corkable because `Hub::upgrade` deletes it synchronously.
+
+### Things that are easy to get wrong
+
+- `dist/*.js` and `dist/bindings/*.node` are committed. Rebuild TS with `npm run build-ts` and commit the output; binaries must be rebuilt on each platform when C++ changes.
+- Binary messages reach JS as an `ArrayBuffer` that is a zero-copy view over the per-loop receive buffer shared by every socket. `onMessage` in `Addon.h` detaches it after the handler returns, so retaining it without `slice()` throws on later use rather than exposing another connection's bytes. Text frames are copied into a V8 string. Ping/pong payloads also go through the string path.
+- Every handler, including `message`, is invoked through `node::MakeCallback`, which establishes an async-context scope and drains nextTick/microtasks after the handler returns. Because that drain happens before `onMessage` detaches the binary `ArrayBuffer`, a continuation that resolves within it still sees the bytes; anything that waits on real I/O sees a detached buffer.
+- `shared.ts` currently has a leftover `console.log('log', ...)` printing the binding path on load.
+- The addon exposes one `Group` per server plus a single shared client group; `ws.external` is the C++ `WebSocket*` and is nulled on disconnect, so every native call in `client.ts` guards on it.
+- Close code defaults to 1005 when the peer sends none (matches `ws`). App-level ping uses the single byte `'9'` (`APP_PING_CODE`) for browser clients that can't see protocol pings.

package/README.md

@@ -12,9 +12,10 @@
 
 This table is true if you run ssl directly with `cws` (`Node.js`). In case if you use proxy for example `nginx`, `cws` can be run on bigger coverage.
 
-| cWS Version | Node 24  | Node 22 | Node 20 |
-|-------------|----------|---------|----------
-| 4.5.3       |    X     |    X    |   X     |
+| cWS Version | Node 26 | Node 24  | Node 22 | Node 20 |
+|-------------|---------|----------|---------|----------
+| 4.6.0       |    X    |    X     |    X    |   X     |
+| 4.5.3       |         |    X     |    X    |   X     |
 
 ## Documentation
 
@@ -262,6 +263,12 @@ server.on('upgrade', (request, socket, head) => {
 
 **For more information check typings (`*.d.ts`) files in [dist](https://github.com/encharm/cWS/blob/master/dist) folder**
 
+### Write corking (performance)
+
+All `send()` calls made to a socket during one event-loop iteration are framed immediately but written with a single gathered write (`writev`) when the iteration ends, instead of one syscall per `send()`. This is transparent to callers and preserves ordering; `send()` followed by `close()`/`terminate()` in the same tick still delivers the message. While writes are corked they are counted in `bufferedAmount` until the flush.
+
+Set `CWS_CORK=0` in the environment to disable it and write every message immediately (previous behaviour). Corking applies to plain TCP sockets only; TLS sockets always write immediately.
+
 ### Secure WebSocket
 You can use `wss://` with `cws` by providing `https` server to `cws` and setting `secureProtocol` on https options:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@encharm/cws",
-  "version": "4.5.3",
+  "version": "4.6.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "description": "cWS - fast C++ WebSocket implementation for Node.js",

package/src/Addon.cpp

@@ -3,7 +3,7 @@
 #include "Addon.h"
 
 void Initialize(Local<Object> exports) {
-  Isolate *isolate = exports->GetIsolate();
+  Isolate *isolate = Isolate::GetCurrent();
   exports->Set(isolate->GetCurrentContext(), String::NewFromUtf8(isolate, "server").ToLocalChecked(),
               Namespace<cWS::SERVER>(isolate).object);
   exports->Set(isolate->GetCurrentContext(), String::NewFromUtf8(isolate, "client").ToLocalChecked(),
@@ -20,6 +20,7 @@ void Initialize(Local<Object> exports) {
   NODE_SET_METHOD(exports, "upgrade", upgrade);
   NODE_SET_METHOD(exports, "connect", connect);
   NODE_SET_METHOD(exports, "setNoop", setNoop);
+  hub.getNodeData()->corkState->enabled = corkEnabledFromEnv();
   registerCheck(isolate);
 }
 

package/src/Addon.h

@@ -24,6 +24,19 @@
   #include "headers/24/base_object-inl.h"
 #endif
 
+#if NODE_MAJOR_VERSION==26
+  // Build-configuration macros normally supplied by Node's own gyp build;
+  // official binaries are built with both enabled.
+  #ifndef HAVE_SQLITE
+    #define HAVE_SQLITE 1
+  #endif
+  #ifndef HAVE_AMARO
+    #define HAVE_AMARO 1
+  #endif
+  #include "headers/26/crypto/crypto_tls.h"
+  #include "headers/26/base_object-inl.h"
+#endif
+
 #include <tcp_wrap.h>
 
 using BaseObject = node::BaseObject;
@@ -64,8 +77,14 @@ using namespace v8;
 
 cWS::Hub hub(0, true);
 uv_check_t check;
+uv_prepare_t corkPrepare;
 Persistent<Function> noop;
 
+// Corked writes are flushed twice per loop iteration: in the prepare phase
+// (right before the loop blocks in poll, so sends made from timers/nextTick/
+// microtasks go out without waiting for I/O) and in the check phase (after
+// poll and after Node's setImmediate callbacks, so sends made from I/O
+// callbacks go out in the same iteration).
 void registerCheck(Isolate *isolate) {
   uv_check_init((uv_loop_t *)hub.getLoop(), &check);
   check.data = isolate;
@@ -73,9 +92,29 @@ void registerCheck(Isolate *isolate) {
     Isolate *isolate = (Isolate *)check->data;
     HandleScope hs(isolate);
     node::MakeCallback(isolate, isolate->GetCurrentContext()->Global(),
-                       Local<Function>::New(isolate, noop), 0, nullptr);
+                       Local<Function>::New(isolate, noop), 0, nullptr, node::async_context{0, 0});
+    cS::Socket::flushCorked(hub.getNodeData());
   });
   uv_unref((uv_handle_t *)&check);
+
+  uv_prepare_init((uv_loop_t *)hub.getLoop(), &corkPrepare);
+  uv_prepare_start(&corkPrepare, [](uv_prepare_t *) {
+    cS::Socket::flushCorked(hub.getNodeData());
+  });
+  uv_unref((uv_handle_t *)&corkPrepare);
+}
+
+// CWS_CORK=0 (or "false"/"off") disables write corking; anything else enables.
+bool corkEnabledFromEnv() {
+  const char *value = getenv("CWS_CORK");
+  if (!value) {
+    return true;
+  }
+  std::string v(value);
+  for (char &c : v) {
+    c = (char) tolower((unsigned char) c);
+  }
+  return !(v == "0" || v == "false" || v == "off" || v == "no");
 }
 
 class NativeString {
@@ -102,7 +141,9 @@ class NativeString {
 #if NODE_MAJOR_VERSION >= 18
       length = arrayBufferView->ByteLength();
       auto store = arrayBufferView->Buffer()->GetBackingStore();
-      data = reinterpret_cast<char*>(store->Data());
+      // A typed array may be a window into a larger ArrayBuffer (subarray);
+      // honour its offset or we would send bytes from the start of the pool.
+      data = reinterpret_cast<char*>(store->Data()) + arrayBufferView->ByteOffset();
 #else
       ArrayBuffer::Contents contents = arrayBufferView->Buffer()->GetContents();
       length = contents.ByteLength();
@@ -271,7 +312,7 @@ void sendCallback(cWS::WebSocket<isServer> *webSocket, void *data,
     HandleScope hs(sc->isolate);
     node::MakeCallback(sc->isolate, sc->isolate->GetCurrentContext()->Global(),
                        Local<Function>::New(sc->isolate, sc->jsCallback), 0,
-                       nullptr);
+                       nullptr, node::async_context{0, 0});
   }
   sc->jsCallback.Reset();
   delete sc;
@@ -358,11 +399,15 @@ void transfer(const FunctionCallbackInfo<Value> &args) {
     Isolate* isolate = args.GetIsolate();
     Local<Context> context = isolate->GetCurrentContext();
     auto arg_0 = args[0]->ToObject(context).ToLocalChecked();
+#if NODE_MAJOR_VERSION >= 26
+    // V8 14 tags internal-field pointers; Node's own reader knows the tag.
+    // The BaseObject* is the start of the TCPWrap (single inheritance chain).
+    void *handleWrap = node::BaseObject::FromJSObject(arg_0);
+#else
     auto field_to_get = arg_0->InternalFieldCount() > 3 ? 1 : 0;
-
-    uv_fileno((handle = getTcpHandle(
-                   arg_0->GetAlignedPointerFromInternalField(field_to_get))),
-              (uv_os_fd_t *)&ticket->fd);
+    void *handleWrap = arg_0->GetAlignedPointerFromInternalField(field_to_get);
+#endif
+    uv_fileno((handle = getTcpHandle(handleWrap)), (uv_os_fd_t *)&ticket->fd);
   } else {
     ticket->fd = args[0].As<Integer>()->Value();
   }
@@ -400,7 +445,7 @@ void onConnection(const FunctionCallbackInfo<Value> &args) {
         Local<Value> argv[] = {wrapSocket(webSocket, isolate)};
         node::MakeCallback(isolate, isolate->GetCurrentContext()->Global(),
                            Local<Function>::New(isolate, *connectionCallback),
-                           1, argv);
+                           1, argv, node::async_context{0, 0});
       });
 }
 
@@ -424,8 +469,19 @@ void onMessage(const FunctionCallbackInfo<Value> &args) {
       HandleScope hs(isolate);
       Local<Value> argv[] = {wrapMessage(message, length, opCode, isolate),
                             getDataV8(webSocket, isolate)};
-      Local<Function>::New(isolate, *messageCallback)
-          ->Call(isolate->GetCurrentContext(), Null(isolate), 2, argv);
+      node::MakeCallback(isolate, isolate->GetCurrentContext()->Global(),
+                         Local<Function>::New(isolate, *messageCallback), 2, argv, node::async_context{0, 0});
+      // Binary messages are zero-copy views over the shared per-loop receive
+      // buffer, which the next socket read overwrites. Detach the ArrayBuffer
+      // once the handler returns so a retained reference reads as empty and
+      // throws on use, instead of silently exposing another connection's data.
+      // Handlers that need the bytes after returning must copy them (slice()).
+      if (opCode == cWS::OpCode::BINARY) {
+        Local<ArrayBuffer> arrayBuffer = argv[0].template As<ArrayBuffer>();
+        if (arrayBuffer->IsDetachable()) {
+          arrayBuffer->Detach();
+        }
+      }
     }
   });
 }
@@ -446,7 +502,7 @@ void onPing(const FunctionCallbackInfo<Value> &args) {
         wrapMessage(message, length, cWS::OpCode::PING, isolate),
         getDataV8(webSocket, isolate)};
     node::MakeCallback(isolate, isolate->GetCurrentContext()->Global(),
-                       Local<Function>::New(isolate, *pingCallback), 2, argv);
+                       Local<Function>::New(isolate, *pingCallback), 2, argv, node::async_context{0, 0});
   });
 }
 
@@ -466,7 +522,7 @@ void onPong(const FunctionCallbackInfo<Value> &args) {
         wrapMessage(message, length, cWS::OpCode::PONG, isolate),
         getDataV8(webSocket, isolate)};
     node::MakeCallback(isolate, isolate->GetCurrentContext()->Global(),
-                       Local<Function>::New(isolate, *pongCallback), 2, argv);
+                       Local<Function>::New(isolate, *pongCallback), 2, argv, node::async_context{0, 0});
   });
 }
 
@@ -492,7 +548,7 @@ void onDisconnection(const FunctionCallbackInfo<Value> &args) {
         getDataV8(webSocket, isolate)};
     node::MakeCallback(isolate, isolate->GetCurrentContext()->Global(),
                        Local<Function>::New(isolate, *disconnectionCallback), 4,
-                       argv);
+                       argv, node::async_context{0, 0});
   });
 }
 
@@ -510,7 +566,7 @@ void onError(const FunctionCallbackInfo<Value> &args) {
     Local<Value> argv[] = {
         Local<Value>::New(isolate, *(Persistent<Value> *)user)};
     node::MakeCallback(isolate, isolate->GetCurrentContext()->Global(),
-                       Local<Function>::New(isolate, *errorCallback), 1, argv);
+                       Local<Function>::New(isolate, *errorCallback), 1, argv, node::async_context{0, 0});
 
     ((Persistent<Value> *)user)->Reset();
     delete (Persistent<Value> *)user;

package/src/Hub.h

@@ -75,6 +75,7 @@ public:
     using cS::Node::run;
     using cS::Node::poll;
     using cS::Node::getLoop;
+    using cS::Node::getNodeData;
     using Group<SERVER>::onConnection;
     using Group<CLIENT>::onConnection;
     using Group<SERVER>::onTransfer;

package/src/Networking.h

@@ -215,6 +215,17 @@ struct WIN32_EXPORT NodeData {
     std::vector<Poll *> changePollQueue;
     static void asyncCallback(Async *async);
 
+    // Write corking: every send() issued during one event-loop iteration is
+    // queued and flushed with a single gathered write per socket from the
+    // loop's prepare/check hooks (see Socket::flushCorked). One CorkState per
+    // loop, shared by pointer between every NodeData copy (Groups copy the
+    // Hub's NodeData). Disabled with the CWS_CORK=0 environment variable.
+    struct CorkState {
+        bool enabled = false;
+        std::vector<Poll *> pending;
+    };
+    CorkState *corkState = nullptr;
+
     static int getMemoryBlockIndex(size_t length) {
         return (int) ((length >> 4) + bool(length & 15));
     }

package/src/Socket.h

@@ -2,6 +2,9 @@
 #define SOCKET_CWS_H
 
 #include "Networking.h"
+#ifndef _WIN32
+#include <sys/uio.h>
+#endif
 
 namespace cS {
 
@@ -33,6 +36,12 @@ protected:
     void *user = nullptr;
     NodeData *nodeData;
 
+    // Corking (see NodeData::CorkState). Only WebSockets opt in; HttpSocket
+    // objects are deleted synchronously in Hub::upgrade so they must never
+    // sit in the pending list. Plain TCP only, SSL keeps the immediate path.
+    bool corkable = false;
+    bool corkPending = false;
+
     // this is not needed by HttpSocket!
     struct Queue {
         struct Message {
@@ -91,6 +100,7 @@ protected:
     }
 
     void transfer(NodeData *nodeData, void (*cb)(Poll *)) {
+        flushCorkedOnClose();
         // userData is invalid from now on till onTransfer
         setUserData(new TransferData({getFd(), ssl, getCb(), getPoll(), getUserData(), nodeData, cb}));
         stop(this->nodeData->loop);
@@ -160,10 +170,17 @@ protected:
                 Queue::Message *messagePtr = socket->messageQueue.front();
                 int sent = SSL_write(socket->ssl, messagePtr->data, (int) messagePtr->length);
                 if (sent == (ssize_t) messagePtr->length) {
-                    if (messagePtr->callback) {
-                        messagePtr->callback(p, messagePtr->callbackData, false, messagePtr->reserved);
-                    }
+                    // Pop before the callback: it may close/terminate this socket,
+                    // which frees the queue (use-after-free otherwise).
+                    auto callback = messagePtr->callback;
+                    void *callbackData = messagePtr->callbackData, *reserved = messagePtr->reserved;
                     socket->messageQueue.pop();
+                    if (callback) {
+                        callback(p, callbackData, false, reserved);
+                        if (socket->isClosed()) {
+                            return;
+                        }
+                    }
                     if (socket->messageQueue.empty()) {
                         if ((socket->state.poll & UV_WRITABLE) && SSL_want(socket->ssl) != SSL_WRITING) {
                             socket->change(socket->nodeData->loop, socket, socket->setPoll(UV_READABLE));
@@ -235,10 +252,17 @@ protected:
                     Queue::Message *messagePtr = socket->messageQueue.front();
                     ssize_t sent = ::send(socket->getFd(), messagePtr->data, messagePtr->length, MSG_NOSIGNAL);
                     if (sent == (ssize_t) messagePtr->length) {
-                        if (messagePtr->callback) {
-                            messagePtr->callback(p, messagePtr->callbackData, false, messagePtr->reserved);
-                        }
+                        // Pop before the callback: it may close/terminate this socket,
+                        // which frees the queue (use-after-free otherwise).
+                        auto callback = messagePtr->callback;
+                        void *callbackData = messagePtr->callbackData, *reserved = messagePtr->reserved;
                         socket->messageQueue.pop();
+                        if (callback) {
+                            callback(p, callbackData, false, reserved);
+                            if (socket->isClosed()) {
+                                return;
+                            }
+                        }
                         if (socket->messageQueue.empty()) {
                             // todo, remove bit, don't set directly
                             socket->change(socket->nodeData->loop, socket, socket->setPoll(UV_READABLE));
@@ -358,6 +382,21 @@ protected:
     void sendTransformed(const char *message, size_t length, void(*callback)(void *socket, void *data, bool cancelled, void *reserved), void *callbackData, D transformData) {
         size_t estimatedLength = T::estimate(message, length) + sizeof(Queue::Message);
 
+        if (corkActive()) {
+            // Frame now, write later: everything sent to this socket during the
+            // current loop iteration goes out in one gathered write (uncork()).
+            Queue::Message *messagePtr = allocMessage(estimatedLength - sizeof(Queue::Message));
+            messagePtr->length = T::transform(message, (char *) messagePtr->data, length, transformData);
+            messagePtr->callback = callback;
+            messagePtr->callbackData = callbackData;
+            enqueue(messagePtr);
+            if (!corkPending) {
+                corkPending = true;
+                nodeData->corkState->pending.push_back(this);
+            }
+            return;
+        }
+
         if (hasEmptyQueue()) {
             if (estimatedLength <= cS::NodeData::preAllocMaxSize) {
                 int memoryLength = (int) estimatedLength;
@@ -477,8 +516,164 @@ public:
         }
     }
 
+    // ---- Write corking ------------------------------------------------------
+
+    bool corkActive() {
+        return corkable && !ssl && nodeData->corkState && nodeData->corkState->enabled;
+    }
+
+    void setCorkable(bool enable) {
+        corkable = enable;
+    }
+
+    void unregisterCork() {
+        if (!corkPending) {
+            return;
+        }
+        corkPending = false;
+        std::vector<Poll *> &pending = nodeData->corkState->pending;
+        for (size_t i = 0; i < pending.size(); i++) {
+            if (pending[i] == this) {
+                pending[i] = pending.back();
+                pending.pop_back();
+                break;
+            }
+        }
+    }
+
+    // One gathered write of (up to MAX_IOV) messages from the queue head.
+    // Returns bytes written or -1 with errno/WSAGetLastError set. Never pops.
+    ssize_t writeQueueGathered() {
+        static const int MAX_IOV = 64;
+#ifdef _WIN32
+        WSABUF bufs[MAX_IOV];
+        DWORD n = 0;
+        for (Queue::Message *m = messageQueue.front(); m && n < MAX_IOV; m = m->nextMessage) {
+            bufs[n].buf = (CHAR *) m->data;
+            bufs[n].len = (ULONG) m->length;
+            n++;
+        }
+        DWORD sent = 0;
+        if (WSASend(getFd(), bufs, n, &sent, 0, nullptr, nullptr) == SOCKET_ERROR) {
+            return -1;
+        }
+        return (ssize_t) sent;
+#else
+        iovec iov[MAX_IOV];
+        int n = 0;
+        for (Queue::Message *m = messageQueue.front(); m && n < MAX_IOV; m = m->nextMessage) {
+            iov[n].iov_base = (void *) m->data;
+            iov[n].iov_len = m->length;
+            n++;
+        }
+        msghdr msg = {};
+        msg.msg_iov = iov;
+        msg.msg_iovlen = n;
+        return ::sendmsg(getFd(), &msg, MSG_NOSIGNAL);
+#endif
+    }
+
+    // Consumes `sent` bytes from the queue head. Fully written messages are
+    // popped (their callbacks appended to `callbacks` if given); a partially
+    // written head is advanced in place. Returns true if the write was partial.
+    struct PendingCallback {
+        void (*callback)(void *socket, void *data, bool cancelled, void *reserved);
+        void *callbackData, *reserved;
+    };
+
+    bool consumeSent(ssize_t sent, std::vector<PendingCallback> *callbacks) {
+        while (sent > 0 && !messageQueue.empty()) {
+            Queue::Message *m = messageQueue.front();
+            if ((size_t) sent >= m->length) {
+                sent -= m->length;
+                if (callbacks && m->callback) {
+                    callbacks->push_back({m->callback, m->callbackData, m->reserved});
+                }
+                messageQueue.pop();
+            } else {
+                m->length -= sent;
+                m->data += sent;
+                messageQueue.totalLength -= sent;
+                return true;
+            }
+        }
+        return false;
+    }
+
+    // Flush this socket's corked queue. Called from the loop's prepare/check
+    // hooks via flushCorked(). Whatever cannot be written now is left to the
+    // regular UV_WRITABLE drain loop, which also surfaces hard errors (onEnd).
+    void uncork() {
+        corkPending = false;
+        if (isClosed() || messageQueue.empty()) {
+            return;
+        }
+
+        std::vector<PendingCallback> callbacks;
+        bool stalled = false;
+        while (!messageQueue.empty() && !stalled) {
+            ssize_t sent = writeQueueGathered();
+            if (sent < 0) {
+                stalled = true; // would block, or hard error: drain loop reports it
+            } else {
+                stalled = consumeSent(sent, &callbacks);
+            }
+        }
+
+        if (!messageQueue.empty()) {
+            if ((getPoll() & UV_WRITABLE) == 0) {
+                setPoll(getPoll() | UV_WRITABLE);
+                changePoll(this);
+            }
+        } else if (getPoll() & UV_WRITABLE) {
+            change(nodeData->loop, this, setPoll(UV_READABLE));
+        }
+
+        for (PendingCallback &c : callbacks) {
+            c.callback(this, c.callbackData, false, c.reserved);
+            if (isClosed()) {
+                break; // callback closed us; nothing further may touch the fd
+            }
+        }
+    }
+
+    // Best effort on close/terminate/transfer: push what was corked during this
+    // iteration to the kernel so send() immediately followed by terminate()
+    // still delivers. Callbacks are not invoked; the caller drains the queue.
+    void flushCorkedOnClose() {
+        if (!corkPending) {
+            return;
+        }
+        unregisterCork();
+        if (isClosed()) {
+            return;
+        }
+        while (!messageQueue.empty()) {
+            ssize_t sent = writeQueueGathered();
+            if (sent <= 0 || consumeSent(sent, nullptr)) {
+                break;
+            }
+        }
+    }
+
+    // Loop hook: flush every socket that corked writes since the last hook.
+    static void flushCorked(NodeData *nodeData) {
+        if (!nodeData->corkState || nodeData->corkState->pending.empty()) {
+            return;
+        }
+        // Swap out the list: callbacks run during uncork() may cork new writes
+        // (picked up by the next hook) or close other sockets (their deletion
+        // is deferred to libuv's close phase, so pointers stay valid here).
+        std::vector<Poll *> batch;
+        batch.swap(nodeData->corkState->pending);
+        for (Poll *p : batch) {
+            ((Socket *) p)->uncork();
+        }
+    }
+
     template <class T>
     void closeSocket() {
+        unregisterCork();
         uv_os_sock_t fd = getFd();
         Context *netContext = nodeData->netContext;
         stop(nodeData->loop);