Future of the net module (net.next)

[jasnell]

/cc @mcollina

After I complete the delivery of the initial QUIC implementation, I want to explore implementation of a new, modern, Promise and Web Platform API compatible implementation of the net subsystem that would exist in parallel with the existing net module. The intent would be to replace the existing net module marking it Legacy and not removing it.

I want to start a discussion about what that new API would look like:

const socket = new Socket(options);  // Used for both plain TCP and TCP+TLS
socket.readable  // Web Stream API ReadableStream
socket.writable // Web Stream API WritableStream
socket.ready // Promise fulfilled when the socket is ready to use. If TLS is used, fulfills after handshake completes
socket.closed // Promise fulfilled when the socket is closed.
socket.stats // Object that provides collected statistics
socket.close([reason]) // Abruptly closes the socket
socket.info // Object that provides information about the socket

There are a couple of important differences here:

1. Use of TLS would be largely transparent. That is, there's no distinction between Socket and TLSSocket
2. The socket is not an EventEmitter or a Duplex. The socket uses promises to delimit lifecycle stages. Web streams API are used to read/write.

Server-side is fairly simple..

const server = new SocketServer(options);
// Adding the event triggers listening implicitly
server.addEventListener('connect', (connectEvent) => {
  const { socket } = connectEvent;
  // exact same Socket object as above
};
server.close([reason]);  // Gracefully closes the server if reason is undefined, abruptly otherwise

I do plan on also revisiting the http1 and http2 implementations separately.

[mcollina]

I would prefer we had a way to read/write that would not be Web Streams. I have significant concerns about the performance of any stream implementation at this point and I would prefer we had a lower level primitive that could be fast.

[jasnell]

For that we could go with the approach I'm taking with the QUIC implementation.

Specifically, when opening a new QUIC stream, the user specifies a source for the payload:

const stream = session.openStream({ body: ... })

The body can be any of: string, ArrayBuffer, ArrayBufferView (TypedArray, DataView, Buffer), Blob, stream.Readble, ReadableStream, FileHandle, sync or async iterable, a function returning any of these, or a Promise resolving any of these.

For the All-at-once sources (string, ArrayBuffer, ArrayBufferView, and Blob), the data is passed down to the native layer all at once and consumed without needing to interface with the slower async streams APIs.

For FileHandle, since we know that is backed by a StreamBase at the native layer, we skip using the streams APIs and do all of the async i/o at the native layer. We can also apply the same optimization to any stream.Readable or ReadableStream that is backed by a StreamBase but I'm not doing so yet.

For stream.Readable, ReadableStream, iterable, and async iterable, we do take the slower path using the stream APIs to feed in the data, but with a number of optimizations by not using StreamBase under the covers (allows us to avoid necessary copying).

When receiving a stream, the respondwith({ body: ...}) acts the same way.

There are three options for consuming the data on a QUIC stream: ReadableStream, stream.Readable, or by attaching your own custom "Consumer" function... which essentially is just a callback that receives arrays of 1 or more ArrayBuffer chunks as they are received.

These options allow us to do the i/o extremely fast since, in the most optimal cases, we're completely bypassing the existing streams machinery when it's not needed, and we can easily follow the same pattern in Socket.