tls: zero-copy / static-buffer read path through TLSWrap (bypass Readable chunk allocation)

[mykola-mokhnach]

What is the problem this feature will solve?

Node supports onread: { buffer, callback } on TCP sockets to avoid the streams 'data' path and reuse a fixed buffer. For TLS, cleartext still goes through TLSWrap::ClearOut() which:

1. Reads with SSL_read() into a stack buffer (kClearOutChunkSize = 16384 in src/crypto/crypto_tls.h)
2. memcpy into a buffer from EmitAlloc()
3. Delivers via EmitRead() → stream listener → JS (src/crypto/crypto_tls.cc)

So TLS consumers doing pump-style I/O (forward proxies, protocol bridges, tunnel helpers) pay at least one copy per read chunk plus Buffer/stream allocation pressure, even when they pass onread to tls.connect().

For sustained bidirectional traffic at path-MTU sizes (1280–1500 bytes for many tunnels):

• Extra copies and allocations raise CPU use and GC pauses on long-lived connections
• 16 KiB chunking can split L3 frames across reads, pushing framing/reassembly into userland
• 'data' event mode is even worse (multiple Buffer objects per second under load)

The stream Readable API is the right default for applications; pump workloads need a documented fast path that stays in native code until the user callback.

What is the feature you are proposing to solve the problem?

Extend TLSWrap so that when onread is configured on a TLSSocket, cleartext can be delivered directly into the caller's buffer without an intermediate EmitAlloc copy or Readable queue.

Proposed API / behavior:

const buf = Buffer.alloc(2048);
const socket = tls.connect({
  host,
  port,
  rejectUnauthorized: false,
  onread: {
    buffer: buf,
    callback(nread, buf) {
      // nread > 0: process cleartext in-place
      // nread < 0: error/EOF handling
    },
  },
  // optional: suppress 'data' events when onread is used
  emitData: false,
});

Implementation outline:

1. In TLSWrap::ClearOut(), if an onread buffer is registered on the wrap, SSL_read() into that buffer (or a TLS-owned ring buffer with the same lifetime rules as TCP onread) and invoke the C++ → JS callback directly — mirror the TCP static-buffer path in stream_wrap / StreamBase.
2. Skip EmitRead() / Readable enqueue when onread mode is active and emitData: false.
3. Make read chunk size configurable or MTU-aware (e.g. default max(16384, suggestedSize) or tlsOptions.readSize) for tunnel-friendly framing.
4. Document lifetime rules: callback must not retain references past return if buffer is reused; same contract as TCP onread.

Success criteria:

• Benchmark: fewer allocations and copies vs. current TLSSocket + 'data' or current onread + TLS for sustained receive workload.
• Existing test/parallel/test-tls-onread-static-buffer.js extended to assert TLS cleartext lands in the static buffer without extra Buffer churn.
• No regression when onread is not set (streams path unchanged).

What alternatives have you considered?

1. Keep using 'data' events — Simple but allocates per chunk and runs through the full Readable state machine; unsuitable for high-QPS forwarding.
2. TCP onread only (TLS disabled at Node layer) — Not viable for TLS-protected protocols (lockdown, HTTPS, CDTunnel over TLS); users must use TLSSocket.
3. Native TLS bridge (tls.createBridge) — Best for kernel-adjacent forwarding where JS should never see bytes; heavier API. Zero-copy onread helps users who still orchestrate in JS but want a faster pump.
4. Larger kClearOutChunkSize alone — Reduces SSL_read loop iterations but does not remove the memcpy/alloc to JS; does not fix frame splitting for MTU-sized traffic.
5. WASM / addon OpenSSL — Works but duplicates session management; core should offer the fast path on existing TLSWrap.