@encharm/cws 4.10.0 → 4.11.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## Released 4.11.0
+* Prepared messages for fan-out: `new PreparedMessage(bytes)` copies a payload into native memory once; `ws.send(prepared, { prefix })` sends `prefix + payload` as one frame without copying or compressing the payload per socket. Uncompressed, the payload goes out as a second gather buffer. Compressed (shared compressor mode), the prefix is emitted as a DEFLATE stored block ahead of the payload's deflate blocks, which are built once on the first compressed send and cached on the handle; standard inflaters accept the result unchanged. Sockets with context takeover and client sockets take the regular copying path. Measured with 300 subscribers and a 3 KB payload: 0.9 -> 0.2 µs of JS-thread time per socket, and no per-socket compression at all.
+* `send()` accepts any `ArrayBufferView` (typed arrays are sent from their own offset, no `Buffer.from` copy needed).
+
 ## Released 4.10.0
 * microdeflate: a built-in ~150-line raw-DEFLATE encoder (fixed Huffman, greedy LZ77, no stream state, no per-message hash reset) now compresses independent messages, i.e. the shared-compressor mode. Measured on a real BSON RPC stream: same ratio as zlib-ng level 1 (2.84 vs 2.85) at ~1.7x its speed; a compressed 2 KB message costs 4.6 µs of worker CPU instead of 6.0. Output is standard DEFLATE (round-trip tested against zlib's inflater). `CWS_MICRO_DEFLATE=0` falls back to zlib-ng; `zlibBackend` reports `+ microdeflate` when active. Dedicated windows (context takeover) and inflate stay on zlib-ng.
 * Compression moved to the send worker: `send()` of a compressed message queues the raw payload and the worker deflates + frames it. Main-thread cost of a compressed 2 KB RPC message drops from ~6 µs to ~0.7 µs (Linux, per-thread measurement); wire output is byte-identical. Main-thread write paths (same-tick terminate, full worker queue, drain loop after a short write) deflate pending messages themselves first.

package/CLAUDE.md

@@ -76,6 +76,10 @@ The client side never touches Node sockets: `native.connect(clientGroup, url, ws
 
 `SendWorker` (`src/SendWorker.cpp`) starts one `std::thread` at addon load when corking is enabled. `Socket::uncork` moves up to 512 queued frames into a `Socket::SendOp` (ownership moves with them) and hands it over through `deps/readerwriterqueue` (blocking SPSC main→worker, plain SPSC worker→main plus a `uv_async`). The worker only calls `sendmsg`/`WSASend` and fills `result`/`error`; `Socket::sendComplete` on the main thread pops what was sent, requeues the rest at the head, resubmits if more queued, arms `UV_WRITABLE` for the classic drain loop on a short write, runs send callbacks, and calls `endCb` (= `STATE::onEnd`, set in `setState`) on a hard error. While an op is in flight `write()` appends to the queue and the drain loop stays out. `closeSocket` orphans an in-flight op (`socket = nullptr`, `closeFd = true`) and lets the completion close the fd, so a reused fd number can never receive the old socket's bytes. SSL sockets never use the worker. `CWS_SEND_THREAD=0` disables. Compressed sends: `WebSocket::send` queues the raw payload as a `compressPending` message (`enqueueCompressPending`); `performSend` deflates + frames it on the worker with the socket's window (`op->deflateWindow`) or the worker's own shared compressor, then builds the iovecs. Any main-thread write path calls `materializePending()` first (`WebSocket::materialize` via `materializeCb`, using the hub's compressor). A socket closed mid-flight hands its window to the op (`destroyWindow`, `workerOwnsWindow`) so `onEnd` does not free it under the worker.
 
+### Prepared (shared) messages
+
+`cWS::SharedPayload` (`src/WebSocket.h`) holds one payload for many recipients: the raw bytes plus, after the first compressed send, their deflate blocks (`Hub::deflate` with no window, i.e. the shared compressor; sync-flush tail stripped like every compressed message). `WebSocket::sendShared(prefix, payload, ...)` queues one frame as two `Queue::Message`s: an owned one with the frame header and the prefix, and a borrowed one (`ownsData = false`) pointing into the payload whose completion callback (`sharedSent`) drops the payload reference and then runs the user's callback. Compressed, the prefix becomes DEFLATE stored blocks (`00 LEN NLEN`, BFINAL=0) ahead of the cached blocks; that is only valid without context takeover, so a socket with a `slidingDeflateWindow`, the client role (masking) and an empty payload fall back to a contiguous `send()`. JS: `PreparedMessage` (`lib/prepared.ts`, native handle released through a `FinalizationRegistry`) and `WebSocket.send` routes a `PreparedMessage` (with the optional `prefix` option) to `native.sendShared`.
+
 ### 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.

package/README.md

@@ -294,6 +294,21 @@ With permessage-deflate enabled, compression of outgoing messages also runs on t
 
 Set `CWS_SEND_THREAD=0` to disable it (sends and compression then happen on the main thread at the end of the tick). The `sendThread` export reports `'active'` or the reason it is not. TLS sockets always send on the main thread.
 
+### Prepared messages (fan-out)
+
+When one payload goes to many sockets with only a small per-socket prefix in front of it (an RPC header, a subscription id), prepare it once:
+
+```js
+const { PreparedMessage } = require('@encharm/cws');
+
+const prepared = new PreparedMessage(payloadBytes);          // copied into native memory once
+for (const ws of subscribers) {
+  ws.send(prepared, { prefix: headerFor(ws) });               // one frame: header + payload
+}
+```
+
+`send` accepts a `PreparedMessage` wherever it accepts a buffer, plus a `prefix` option (a per-socket header, string or bytes) spliced in front of the payload inside the same frame. `binary` defaults to `true` for prepared messages; `compress` defaults to the server's `threshold` applied to the total length. The payload is never copied or compressed per socket: without deflate it is a second gather buffer in the end-of-tick write; with the shared compressor it is deflated once, on the first compressed send, and the prefix is spliced in front as a DEFLATE stored block. Sockets negotiated with context takeover (`serverNoContextTakeover: false`) and client sockets fall back to the regular path. Handles are released when garbage collected; sends in flight keep their own reference.
+
 ### Secure WebSocket
 You can use `wss://` with `cws` by providing `https` server to `cws` and setting `secureProtocol` on https options:
 

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="node" />
 import { WebSocketServer } from './server';
 import { SocketAddress, ServerConfigs } from './index';
+import { PreparedMessage } from './prepared';
 export declare class WebSocket {
     url: string;
     private options;
@@ -28,9 +29,10 @@ export declare class WebSocket {
     on(event: 'error', listener: (err: Error) => void): void;
     on(event: 'message', listener: (message: string | any) => void): void;
     on(event: 'close', listener: (code?: number, reason?: string) => void): void;
-    send(message: string | Buffer, options?: {
+    send(message: string | Buffer | ArrayBufferView | PreparedMessage, options?: {
         binary?: boolean;
         compress?: boolean;
+        prefix?: string | Buffer | ArrayBufferView;
     }, cb?: (err?: Error) => void): void;
     ping(message?: string | Buffer): void;
     close(code?: number, reason?: string): void;

package/dist/client.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebSocket = void 0;
 const server_1 = require("./server");
 const shared_1 = require("./shared");
+const prepared_1 = require("./prepared");
 const clientGroup = shared_1.native.client.group.create(0, shared_1.DEFAULT_PAYLOAD_LIMIT);
 function messageByteLength(message) {
     if (typeof message === 'string') {
@@ -78,6 +79,7 @@ class WebSocket {
     }
     send(message, options, cb) {
         if (this.external) {
+            const prepared = message instanceof prepared_1.PreparedMessage;
             let opCode = typeof message === 'string' ? shared_1.OPCODE_TEXT : shared_1.OPCODE_BINARY;
             if (options && options.binary === false) {
                 opCode = shared_1.OPCODE_TEXT;
@@ -90,9 +92,15 @@ class WebSocket {
                 compress = !!options.compress;
             }
             else if (this.compressThreshold !== undefined) {
-                compress = messageByteLength(message) >= this.compressThreshold;
+                compress = messageByteLength(message) + (options && options.prefix ? messageByteLength(options.prefix) : 0) >= this.compressThreshold;
+            }
+            const callback = cb ? () => process.nextTick(cb) : null;
+            if (prepared) {
+                this.nativeApi.sendShared(this.external, options && options.prefix, message.external, opCode, callback, compress);
+            }
+            else {
+                this.nativeApi.send(this.external, message, opCode, callback, compress);
             }
-            this.nativeApi.send(this.external, message, opCode, cb ? () => process.nextTick(cb) : null, compress);
         }
         else if (cb) {
             cb(new Error('Socket not connected'));

package/dist/index.d.ts

@@ -30,6 +30,7 @@ export declare type ServerConfigs = {
     verifyClient?: (info: ConnectionInfo, next: VerifyClientNext) => void;
 };
 export { WebSocket } from './client';
+export { PreparedMessage } from './prepared';
 export { WebSocketServer } from './server';
 export declare const secureProtocol: string;
 export { zlibBackend, sendThread } from './shared';

package/dist/index.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.secureProtocol = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "WebSocket", { enumerable: true, get: function () { return client_1.WebSocket; } });
+var prepared_1 = require("./prepared");
+Object.defineProperty(exports, "PreparedMessage", { enumerable: true, get: function () { return prepared_1.PreparedMessage; } });
 var server_1 = require("./server");
 Object.defineProperty(exports, "WebSocketServer", { enumerable: true, get: function () { return server_1.WebSocketServer; } });
 exports.secureProtocol = 'TLSv1_2_method';

package/dist/prepared.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="node" />
+export declare class PreparedMessage {
+    readonly byteLength: number;
+    readonly external: any;
+    constructor(data: Buffer | ArrayBufferView | ArrayBuffer);
+}

package/dist/prepared.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreparedMessage = void 0;
+const shared_1 = require("./shared");
+const preparedRegistry = typeof global.FinalizationRegistry === 'function'
+    ? new global.FinalizationRegistry((external) => shared_1.native.server.releaseShared(external))
+    : undefined;
+class PreparedMessage {
+    constructor(data) {
+        this.byteLength = data.byteLength;
+        this.external = shared_1.native.server.prepareShared(data);
+        if (preparedRegistry) {
+            preparedRegistry.register(this, this.external);
+        }
+    }
+}
+exports.PreparedMessage = PreparedMessage;

package/package.json

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

package/src/Addon.h

@@ -644,6 +644,44 @@ void sendPrepared(const FunctionCallbackInfo<Value> &args) {
               ->Value());
 }
 
+template <bool isServer>
+void prepareShared(const FunctionCallbackInfo<Value> &args) {
+  NativeString nativeString(args.GetIsolate(), args[0]);
+  args.GetReturnValue().Set(External::New(
+      args.GetIsolate(),
+      cWS::WebSocket<isServer>::prepareShared(nativeString.getData(),
+                                              nativeString.getLength())));
+}
+
+template <bool isServer>
+void releaseShared(const FunctionCallbackInfo<Value> &args) {
+  cWS::SharedPayload::unref(
+      (cWS::SharedPayload *)args[0].As<External>()->Value());
+}
+
+// (socket, prefix, payload, opCode, callback, compress)
+template <bool isServer>
+void sendShared(const FunctionCallbackInfo<Value> &args) {
+  NativeString prefix(args.GetIsolate(), args[1]);
+  cWS::SharedPayload *payload =
+      (cWS::SharedPayload *)args[2].As<External>()->Value();
+  cWS::OpCode opCode = (cWS::OpCode)args[3].As<Integer>()->Value();
+
+  SendCallbackData *sc = nullptr;
+  void (*callback)(cWS::WebSocket<isServer> *, void *, bool, void *) = nullptr;
+  if (args[4]->IsFunction()) {
+    callback = sendCallback;
+    sc = new SendCallbackData;
+    sc->jsCallback.Reset(args.GetIsolate(), Local<Function>::Cast(args[4]));
+    sc->isolate = args.GetIsolate();
+  }
+  bool compress = args[5].As<Boolean>()->Value();
+
+  unwrapSocket<isServer>(args[0].As<External>())
+      ->sendShared(prefix.getData(), prefix.getLength(), payload, opCode,
+                   compress, callback, sc);
+}
+
 template <bool isServer>
 void finalizeMessage(const FunctionCallbackInfo<Value> &args) {
   cWS::WebSocket<isServer>::finalizeMessage(
@@ -723,6 +761,9 @@ struct Namespace {
     NODE_SET_METHOD(object, "prepareMessage", prepareMessage<isServer>);
     NODE_SET_METHOD(object, "sendPrepared", sendPrepared<isServer>);
     NODE_SET_METHOD(object, "finalizeMessage", finalizeMessage<isServer>);
+    NODE_SET_METHOD(object, "prepareShared", prepareShared<isServer>);
+    NODE_SET_METHOD(object, "sendShared", sendShared<isServer>);
+    NODE_SET_METHOD(object, "releaseShared", releaseShared<isServer>);
 
     Local<Object> group = Object::New(isolate);
     NODE_SET_METHOD(group, "onConnection", onConnection<isServer>);

package/src/WebSocket.cpp

@@ -82,6 +82,155 @@ void WebSocket<isServer>::materialize(cS::Socket *s, cS::Socket::Queue::Message
     cS::Socket::materializeOnMain(s, m, stream, !webSocket->slidingDeflateWindow, hub->zlibBuffer, Hub::LARGE_BUFFER_SIZE, hub->dynamicZlibBuffer);
 }
 
+template <bool isServer>
+SharedPayload *WebSocket<isServer>::prepareShared(const char *data, size_t length) {
+    SharedPayload *payload = new SharedPayload;
+    payload->raw.assign(data, length);
+    return payload;
+}
+
+namespace {
+struct SharedCallback {
+    void (*callback)(void *socket, void *data, bool cancelled, void *reserved);
+    void *data;
+};
+
+// Completion of the shared part of a sendShared() frame: drops the payload reference,
+// then runs the caller's callback. `socket` is null when the send was orphaned by a close.
+void sharedSent(void *socket, void *data, bool cancelled, void *reserved) {
+    SharedPayload::unref((SharedPayload *) data);
+    if (reserved) {
+        SharedCallback *c = (SharedCallback *) reserved;
+        c->callback(socket, c->data, cancelled, nullptr);
+        delete c;
+    }
+}
+}
+
+/*
+ * Sends prefix + payload as one frame. The frame is queued as two messages: an owned
+ * one with the header and the prefix, and a borrowed one pointing into the payload, so
+ * nothing is copied or compressed per recipient.
+ *
+ * Compressed: the prefix goes out as DEFLATE stored blocks in front of the payload's
+ * pre-built blocks. That is valid because those blocks were produced from the payload
+ * alone, so no match reaches back before their start. It needs a socket without context
+ * takeover (no sliding window): with takeover the per-socket window would not contain
+ * these bytes, so that case, like the client role (masking rewrites every byte), takes
+ * the regular copying path.
+ */
+template <bool isServer>
+void WebSocket<isServer>::sendShared(const char *prefix, size_t prefixLength, SharedPayload *payload, OpCode opCode, bool compress,
+                                     void(*callback)(WebSocket<isServer> *webSocket, void *data, bool cancelled, void *reserved), void *callbackData) {
+    bool deflate = compress && compressionStatus == WebSocket<isServer>::CompressionStatus::ENABLED && opCode < 3;
+    if (!isServer || (deflate && slidingDeflateWindow) || payload->raw.empty()) {
+        std::string whole;
+        whole.reserve(prefixLength + payload->raw.size());
+        whole.append(prefix, prefixLength).append(payload->raw);
+        send(whole.data(), whole.size(), opCode, callback, callbackData, compress);
+        return;
+    }
+    if (isClosed()) {
+        if (callback) {
+            callback(this, callbackData, true, nullptr);
+        }
+        return;
+    }
+
+    const char *body;
+    size_t bodyLength;
+    if (deflate) {
+        if (!payload->deflatedReady) {
+            size_t length = payload->raw.size();
+            char *out = Group<isServer>::from(this)->hub->deflate((char *) payload->raw.data(), length, nullptr);
+            payload->deflated.assign(out, length);
+            payload->deflatedReady = true;
+        }
+        body = payload->deflated.data();
+        bodyLength = payload->deflated.size();
+    } else {
+        body = payload->raw.data();
+        bodyLength = payload->raw.size();
+    }
+
+    // a stored block carries at most 65535 bytes: 1 byte header, LEN, NLEN
+    const size_t STORED_MAX = 65535;
+    size_t storedBlocks = deflate ? (prefixLength + STORED_MAX - 1) / STORED_MAX : 0;
+    size_t prefixPart = prefixLength + storedBlocks * 5;
+    const size_t MAX_HEADER = 14;
+
+    Queue::Message *first = allocMessage(MAX_HEADER + prefixPart);
+    char *dst = (char *) first->data;
+    char *p = dst + WebSocketProtocol<isServer, WebSocket<isServer>>::formatMessage(dst, dst, 0, opCode, prefixPart + bodyLength, deflate);
+    if (deflate) {
+        const char *src = prefix;
+        for (size_t remaining = prefixLength; remaining; ) {
+            size_t n = remaining > STORED_MAX ? STORED_MAX : remaining;
+            *p++ = 0; // BFINAL=0, BTYPE=00, already byte aligned
+            *p++ = (char) (n & 0xff);
+            *p++ = (char) (n >> 8);
+            *p++ = (char) (~n & 0xff);
+            *p++ = (char) ((~n >> 8) & 0xff);
+            memcpy(p, src, n);
+            p += n;
+            src += n;
+            remaining -= n;
+        }
+    } else {
+        memcpy(p, prefix, prefixLength);
+        p += prefixLength;
+    }
+    first->length = p - dst;
+
+    int memoryIndex = nodeData->getMemoryBlockIndex(sizeof(Queue::Message));
+    Queue::Message *second = (Queue::Message *) nodeData->getSmallMemoryBlock(memoryIndex);
+    second->data = body;
+    second->length = bodyLength;
+    second->nextMessage = nullptr;
+    second->poolIndex = memoryIndex;
+    second->ownsData = false;
+    second->compressPending = false;
+    second->opCode = 0;
+    second->callback = sharedSent;
+    second->callbackData = payload;
+    second->reserved = callback ? new SharedCallback{(void(*)(void *, void *, bool, void *)) callback, callbackData} : nullptr;
+    payload->references++;
+
+    if (corkActive()) {
+        enqueue(first);
+        enqueue(second);
+        if (!corkPending) {
+            corkPending = true;
+            nodeData->corkState->pending.push_back(this);
+        }
+        return;
+    }
+
+    // no write corking (CWS_CORK=0, TLS): write now, queue what does not fit, keep order
+    bool wasTransferred;
+    if (!write(first, wasTransferred)) {
+        freeMessage(first);
+        void *reserved = second->reserved;
+        nodeData->freeSmallMemoryBlock((char *) second, memoryIndex);
+        sharedSent(this, payload, true, reserved);
+        return;
+    }
+    if (!wasTransferred) {
+        freeMessage(first);
+    }
+    if (!write(second, wasTransferred)) {
+        void *reserved = second->reserved;
+        nodeData->freeSmallMemoryBlock((char *) second, memoryIndex);
+        sharedSent(this, payload, true, reserved);
+        return;
+    }
+    if (!wasTransferred) {
+        void *reserved = second->reserved;
+        nodeData->freeSmallMemoryBlock((char *) second, memoryIndex);
+        sharedSent(this, payload, false, reserved);
+    }
+}
+
 /*
  * Prepares a single message for use with sendPrepared.
  *

package/src/WebSocket.h

@@ -12,6 +12,23 @@ struct Group;
 template <bool isServer>
 struct HttpSocket;
 
+// A payload prepared once and sent to many sockets with sendShared() (fan-out). Holds the
+// raw bytes and, after the first compressed send, their DEFLATE blocks: the same bytes a
+// regular compressed send would carry (sync-flush tail stripped). Reference counted: the
+// creator holds one reference, every queued message holds one until it completes.
+struct SharedPayload {
+    std::string raw;
+    std::string deflated;
+    bool deflatedReady = false;
+    int references = 1;
+
+    static void unref(SharedPayload *payload) {
+        if (!--payload->references) {
+            delete payload;
+        }
+    }
+};
+
 template <const bool isServer>
 struct WIN32_EXPORT WebSocket : cS::Socket, WebSocketState<isServer> {
 protected:
@@ -74,6 +91,10 @@ public:
     void ping(const char *message) {send(message, OpCode::PING);}
     void send(const char *message, OpCode opCode = OpCode::TEXT) {send(message, strlen(message), opCode);}
     void send(const char *message, size_t length, OpCode opCode, void(*callback)(WebSocket<isServer> *webSocket, void *data, bool cancelled, void *reserved) = nullptr, void *callbackData = nullptr, bool compress = false);
+    static SharedPayload *prepareShared(const char *data, size_t length);
+    // One frame carrying prefix + payload without copying or re-compressing the payload. Not thread safe.
+    void sendShared(const char *prefix, size_t prefixLength, SharedPayload *payload, OpCode opCode, bool compress,
+                    void(*callback)(WebSocket<isServer> *webSocket, void *data, bool cancelled, void *reserved) = nullptr, void *callbackData = nullptr);
     static PreparedMessage *prepareMessage(char *data, size_t length, OpCode opCode, bool compressed, void(*callback)(WebSocket<isServer> *webSocket, void *data, bool cancelled, void *reserved) = nullptr);
     static PreparedMessage *prepareMessageBatch(std::vector<std::string> &messages, std::vector<int> &excludedMessages,
                                                 OpCode opCode, bool compressed, void(*callback)(WebSocket<isServer> *webSocket, void *data, bool cancelled, void *reserved) = nullptr);