Introducing a Socket API

[jasnell]

@dom96 has been working on the implementation of a new Socket API for workerd that is a continuation of some exploratory spec work I started last year.

Our goal is to create a spec of this API with the hope that it will be implementable not only in workerd but also other runtimes such as Node.js, Deno, and Bun. This discussion will serve as the starting point for that specification.

Details

The API is modeled closely after the socket API that Deno has already implemented, however with a few key differences:

First the connect operation:

// Deno...
const socket = await connect({ address: '123.123.123.123', port: 8080' });

// Our proposal
const socket = connect('123.123.123.123:8080', { /* ... options ... */ });

// Both... readable and writable are ReadableStream and WritableStream
const { readable, writable } = socket;

• Providing the address and port as a simple string value is, we think, more ergonomic for the simplest cases. An options argument would still be provided for more complex cases.
• By returning a Socket instance directly, rather than a Promise for a Socket, allows us to optimistically begin queing up writes and reads on the socket while it is being established, reducing overall latency. Since the underlying streams implementation is also async, we can rely on those mechanisms to determine when the streams are actually ready to receive and transmit.

The abstract interface definition for a Socket is:

interface Socket {
  readonly attribute ReadableStream readable;
  readonly attribute WritableStream writable;

  // The closed promise resolves when the Socket is fully closed in both directions.
  readonly attribute Promise<void> closed;

  // Immediately renders the Socket unusable in both directions. Pending reads
  // and writes are rejected with the given error (if any). The readable and writable
  // streams are fully closed. The closed promise will be resolved after destroy is
  // called but possibly not immediately if any part of the required cleanup is async.
  void destroy(optional any error);
}

The Socket instance would support being half-closed in manner similar to Node.js' API, specifically, when the writable side is closed, the Socket will immediately send a fin after draining its pending write queue. The Socket will become half-closed, waiting for the readable side to receive a fin from the peer, which will close the readable side. Once both the writable and readable side are closed, the Socket will close.

const { readable, writable } = connect('123.123.123.123:8080');

const enc = new TextEncoder();
const writer = writable.getWriter();
await Promise.all([
  writer.write(enc.encode('hello')),
  writer.end(),
]);

// The socket is half-closed now. The writable side is closed, fin will be sent after 'hello' is sent.

// But we can still read until the peer sends fin.
for await (const chunk of readable) { console.log(chunk);

We would support an allowHalfOpen option in the same manner as Node.js. When allowHalfOpen is false, the writable side of the socket is automatically closed when the readable side receives a fin from the peer. Any writes pending in the writable side queue are permitted to drain before closing the writable side. This will be the default behavior, just as it is in Node.js. When allowHalfOpen is true, the writable side will not be automatically ended in response to receiving a fin on the readable side. Instead, user code must explicitly close the writable itself in order to send the fin.

The Socket will support an immediate destruction option using destroy(), which will terminate both the readable and writable sides immediately, canceling pending reads and writes and closing both streams. The destroy() method itself is not awaitable.

For both the graceful and immediately destroy options, user code can optionally await the closed promise to determine when the socket is fully terminated and closed.

Global connect() ?

Our current implementation adds connect() as a global as a property of specific configurable "binding" objects. We are not yet settled on whether introducing a new global method is the right thing to do.

[lemanschik]

Sounds like douplication of

• https://wicg.github.io/direct-sockets/
• https://www.w3.org/TR/activitypub/

[dom96]

Thanks for sharing! The direct-sockets proposal looks very similar to what we intended to implement, main differences are:

• Using new TCPSocket instead of connect
• Splitting the address and port into separate arguments

But other than that, from the interface-level at least, we are at parity. I'm not sure how the activity pub spec relates though.

@jasnell let's have a chat about this.

[lemanschik]

@dom96 @jasnell chat both with me on matrix then i can show you how to use it we implemented it inside chromium but it is not public exposed how we did that as that is security related but as you are both WInterCG Fellows i would share that internals with you.

[lemanschik]

Also mozilla does not want to implement that because they have a old view see: mozilla/standards-positions#431

but i superseeded them as i did it in the engine level in fact i took fully over the web via defining a new Web standard including Web Module Standard so there is no IETF anymore!
i am rolling it out via code-oss so vscode the most used editor nothing can stop the adoption.

there was always much problems with the transport of all the needed knowleg so i have chose to go execute and implement in a way that no one can block the adoption anymore. All commits every where are landed and tested since years now we simply compose and link it up.

in fact activity pub will or is in fact as implemented by my self directly in chromium and firefox and all ECMAScript hosts superseeded by my none written web-modules specification which is already fully in action deployed and i am now creating a poc and presentation of it via a small engineering change inside vscode.

Tracking issue

• PR: Incremental refactoring to web-modules microsoft/vscode#167505

When that is closed you can see vscode running full in the browser autonomous even cluster able via webrtc to form a build grid and share resources. as also replacing the electron shell with a chromium extension and a nodejs stdio stream module that directly uses our chromium devtools pipe integration.

[kael]

I for one would be interested to use the Socket API for STOMP connections in Cloudflare Pages.

Regarding prior arts, there was also:

• TCP Socket API in Thunderbird, probably Firefox too - that I've used to write a JavaScript IMAP client upon it (until they ditched it when they introduced WebExtensions - more precisely, they made it inaccessible in the context of extensions).
• https://searchfox.org/mozilla-central/source/dom/webidl/TCPSocket.webidl

I guess WebTransport could be of interest as well.

Is there some ETA for production ?

[lemanschik]

DATACHANNEL === RAW Socket wrapped via TLS can be UDP or TCP

[lemanschik]

And ya if you wonder how to do a TLS proxy you should google for TLS cert reuse nodejs and then start putting certs into a array and call it a day.

[kael]

Is there some ETA for production ?

It's alive ! 🥳 : Announcing connect() — a new API for creating TCP sockets from Cloudflare Workers.

@jasnell @dom96 Thank you ! 🙏

[kael]

@dom96 @jasnell I've been at last able to use the new cloudflare:sockets module (couldn't run the latest version of Wrangler due to cloudflare/workers-sdk#3457).

I'm able to proxy a STOMP socket to a WebSocket connection.

The TCP API lacks event listeners (onopen, onclose, ontimeout, onerror) similar to the TCP Socket and it's unclear how to handle socket connection timeout - it seems to throw an handled error.

I'm having fun anyway.

Thanks ! 👍

[kael]

The TCP API lacks event listeners (onopen, onclose, ontimeout, onerror) similar to the TCP Socket and it's unclear how to handle socket connection timeout - it seems to throw an handled error.

Here's an example of socket.jsm a module used in Mozilla code that implements a TCP Socket API. It's then used by the XMPP client module.