tls: native pipe / splice between TLS and another native stream or fd

[mykola-mokhnach]

What is the problem this feature will solve?

net.Socket supports efficient kernel-level forwarding patterns (socket.pipe(), socket.pause()/resume() with native backpressure). There is no TLS equivalent — forwarding cleartext through TLSSocket always goes through the streams layer:

TCP (encrypted) → TLSWrap::ClearOut → JS Readable → user pump → JS Writable → sink
For full-duplex bridges (TLS ↔ TUN fd, TLS ↔ pipe, TLS ↔ another TCP socket), userland must:

1. Implement two pumps (encrypt direction + decrypt direction) in JavaScript or duplicate logic in a native addon
2. Manually coordinate backpressure (pause/resume, 'drain', TUN poll pause) across heterogeneous endpoints
3. Absorb per-chunk copies and event-loop latency from TLSWrap (see related issues on SetImmediate deferral and read copies)

net has splice-style optimizations between fds; TLSWrap sits in the middle with no supported way to wire cleartext directly to a native sink/source while keeping session setup in Node.

This forces ecosystem projects (VPN helpers, transparent proxies, iOS tunnel tooling) to ship custom OpenSSL forwarders instead of composing built-in APIs.

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

Add native TLS pipe/splice primitives that pump cleartext between an established TLSSocket (or tls.connect session) and another native I/O endpoint without per-chunk JavaScript involvement.

Proposed API (sketch):

import tls from 'node:tls';
import net from 'node:net';
const tcp = await net.connect({ port });
const tlsSocket = await tls.connect({ socket: tcp, ... });
// Duplex: TLS cleartext ↔ numeric fd (TUN, pipe, etc.)
const handle = tlsSocket.spliceTo({
  fd: tunFd,
  direction: 'duplex',   // 'in' | 'out' | 'duplex'
});
handle.start();
await handle.stop();     // idempotent cleanup
// Or one-shot helper:
await tlsSocket.pipeToNative(tunFd, { direction: 'duplex' });

Implementation outline (on TLSWrap):

1. Decrypt path (TLS → sink): SSL_read loop → write cleartext to sink fd; on EAGAIN/EWOULDBLOCK, pause uv_read_start on the underlying TCP stream until sink is writable (native backpressure, not socket.pause() in JS).
2. Encrypt path (source → TLS): read cleartext from source fd → SSL_write → EncOut → TCP; stall source read when SSL_write or TCP send buffer is full.
3. Reuse existing TLSWrap session, handshake, cert/PSK options — only the payload pump is native.
4. Clear ownership semantics for fds (caller retains TUN; bridge does not close unless autoClose: true).

Relation to other proposals:

• Lighter-weight than full tls.createBridge() when one side is already a TLSSocket and the other is an fd.
• Complements zero-copy onread for users who still want one direction in JS.

Success criteria:

• Bidirectional MTU-sized forwarding without socket.on('data') handlers.
• Backpressure propagates correctly (no unbounded buffering in pending_cleartext_input_ / userland).
• Benchmark shows lower CPU and event-loop utilization vs. an equivalent JS pump.

What alternatives have you considered?

1. socket.pipe(otherSocket) through TLSSocket — Still routes every byte through JS streams; does not splice to raw fds; no TLS-aware backpressure.
2. duplex streams + pipeline() — Same V8-boundary and allocation costs; popular but not a performance solution.
3. tls.createBridge() (separate proposal) — Higher-level API that may subsume this for fd targets; spliceTo is a narrower addition for users who already have a TLSSocket and want fd bridging only.
4. Custom N-API OpenSSL forwarder — Proven in production (e.g. iOS tunnel addons) but duplicates TLSWrap and OpenSSL linkage in every consumer.
5. node:child_process + socat/openssl s_client — Operational hack, not embeddable in Node apps.
6. Document manual pump patterns only — Insufficient; the gap is missing native wiring in TLSWrap, not developer skill.