Give a WebAssembly engine sockets

You can run an engine compiled to WebAssembly, written in C, C++, Go or Rust against Node’s net and dgram, unchanged on FKN sockets. This page covers taking the two modules as options, wiring the socket calls the compiled code makes back into JavaScript, copying every buffer you read, and reading a socket’s addresses once the relay has answered.

The relay is the server that holds the real socket at the far end of net and dgram. At the end, every socket call the engine makes reaches the relay, every read is a copy the engine owns, and every connection it accepts carries usable addresses. What the recipe costs:

• Uses connect and createServer from @fkn/lib/net, createSocket from @fkn/lib/dgram
• Needs nothing installed
• Proven by four integrations

The first step carries the [Build] badge and the rest carry [Page], both defined on recipes. engine.ts is the engine’s host file, the JavaScript that loads the compiled module and answers its socket calls, and app.ts is the app that hands it the modules. The engine usually runs in a worker, and the optional step says what that adds.

[Build] Take the modules as options

An engine that imports @fkn/lib/net itself ties every host to the library, and to one copy of it. Take net and dgram as options instead. The app passes the library’s modules, a test passes Node’s, and the engine’s package declares @fkn/lib as an optional peer dependency, optional: true under peerDependenciesMeta, and imports nothing from it. The host file names the calls it makes and the members it reads on what they return:

engine.ts

export type Socket = {
  readonly remoteAddress?: string
  readonly remotePort?: number
  readonly localAddress?: string
  readonly localPort?: number
  write: (chunk: Uint8Array) => boolean
  end: () => unknown
  destroy: () => unknown
  on: (event: string, listener: (...args: any[]) => void) => unknown
}

export type Datagram = {
  bind: (port: number, address: string, listener?: () => void) => unknown
  send: (chunk: Uint8Array, port: number, address: string, callback?: (error: Error | null, bytes: number) => void) => void
  address: () => { address: string, port: number }
  close: (callback?: () => void) => unknown
  on: (event: string, listener: (...args: any[]) => void) => unknown
}

export type Modules = {
  net: { connect: (options: { host: string, port: number }, listener?: () => void) => Socket }
  dgram: { createSocket: (type: 'udp4' | 'udp6') => Datagram }
}

export const createEngine = ({ net, dgram }: Modules) => {
  const sockets = new Map<number, Socket>() // the number the compiled code holds on one side, the socket on the other
  let next = 1
  return {
    connect: (host: string, port: number) => {
      const handle = next++
      sockets.set(handle, net.connect({ host, port })) // the same call on node:net and on @fkn/lib/net
      return handle
    },
    open: (type: 'udp4' | 'udp6') => dgram.createSocket(type),
  }
}

Modules names one call on each module and the members the engine reads on what they return, by the names Node declares, so node:net and node:dgram satisfy it and the same file runs in a plain Node test with no broker, as testing shows. Add createServer the same way when the engine accepts peers. The app is the one file that imports the library:

app.ts

import * as net from '@fkn/lib/net'
import * as dgram from '@fkn/lib/dgram'
import { createEngine } from './engine'

const engine = createEngine({ net, dgram }) // the library's modules, and the compiled code never learns which
engine.connect('67.215.246.10', 6881) // 1, and the socket behind it is dialing through the relay

The engine never learns which module it holds. With the library’s, the bytes travel through the broker, the connection your page holds into FKN, to the relay. The bundle has to shim stream, events and buffer for the library’s module bodies to run, see install and bundle an app that uses sockets.

[Page] Wire the socket calls

The compiled code holds a number for each socket and passes it back on every later call, so the host keeps a table from number to socket, and each call becomes one call on the module. On the page, against @fkn/lib/net directly, the three calls an engine makes most read like this:

app.ts

import * as net from '@fkn/lib/net'

const sockets = new Map<number, net.Socket>() // the number the compiled code holds on one side, the socket on the other
let next = 1

const connect = (host: string, port: number) => {
  const handle = next++
  const socket = net.connect({ host, port })
  socket.on('error', (error: Error) => error.message) // a refused dial lands here, and nothing else fires
  sockets.set(handle, socket)
  return handle
}
const write = (handle: number, bytes: Uint8Array) => sockets.get(handle)?.write(bytes) ?? false
const close = (handle: number) => {
  sockets.get(handle)?.destroy() // tears the socket down
  sockets.delete(handle)
}

const handle = connect('67.215.246.10', 6881) // 1
sockets.get(handle) instanceof net.Socket // true, a live socket before the relay has answered
write(handle, new Uint8Array([19, 66, 105, 116])) // true, and the bytes go out once the relay has answered

connect hands back the Socket at once and dials through the relay in the background, so the number maps to a live socket before the relay has answered, and a write in that window is queued rather than refused. The error listener goes on the line after connect. A refused dial emits error and nothing else, no close and no listener call, and an error with no listener throws. What arrives there is a message: getaddrinfo ENOTFOUND <hostname> when the name has no answer, tcp connect to <address>:<port> timed out after 12000ms when the relay does not acknowledge within 12,000 ms, and the operating system’s own text when the peer refused.

None of those carries an errno, so an engine that maps error.errno to its own table is mapping its own fallback, as testing explains.

An engine written for Node may hand connect a path or a file descriptor, and the library throws FKN WebVPN does not support IPC connections for the path and FKN WebVPN does not support file descriptors for the descriptor at the call, so pass { host, port } and nothing else. The whole surface is on TCP and UDP sockets.

[Page] Copy every buffer you read

The compiled code reads from its own linear memory, so every byte a socket delivers is copied into that memory at some point, and the question is only when. A data chunk arrives as a Buffer, a view over memory the library allocated, and an engine keeps it in a queue until its next tick drains it. Copy it in the listener, before the listener returns, so the queue holds memory the engine owns:

app.ts

import * as net from '@fkn/lib/net'

const inbox: Uint8Array[] = [] // what the compiled code's read drains, in arrival order
const socket = net.connect({ host: '67.215.246.10', port: 6881 })
socket.on('error', (error: Error) => error.message)
socket.on('data', (chunk: Buffer) => {
  const copy = new Uint8Array(chunk) // the bytes, in memory of their own
  copy.byteLength === chunk.byteLength // true
  copy.buffer === chunk.buffer // false, so the next data event cannot reach it
  inbox.push(copy)
})

new Uint8Array(chunk) copies. chunk.slice() does not: on a Buffer, slice is an alias of subarray and returns a view over the same memory, and so does Buffer.from(chunk.buffer). Neither the library nor the shape above promises what happens to the memory behind a chunk once your listener returns, and the failure when it changes reads as a peer’s fault rather than the socket’s: a piece that hashes wrong, then a peer dropped for data that arrived intact. One integration traced exactly that failure to chunks it had kept rather than copied.

The same rule holds for a datagram. message hands you a Buffer and an rinfo with the sender’s address and port, and the engine’s receive queue takes a copy of the bytes and the two fields it answers with:

app.ts

import * as dgram from '@fkn/lib/dgram'

const inbox: { bytes: Uint8Array, address: string, port: number }[] = [] // what the compiled code's recvfrom drains
const socket = dgram.createSocket('udp4')
socket.on('error', (error: Error) => error.message) // a refused bind lands here, and listening never fires
socket.on('message', (message: Buffer, rinfo) => {
  inbox.push({ bytes: new Uint8Array(message), address: rinfo.address, port: rinfo.port }) // a copy of the bytes, and the two fields recvfrom answers with
})
socket.bind(0, '0.0.0.0', () => {
  socket.address().port // the port the relay granted
  socket.send(new Uint8Array([0, 0, 4, 23]), 6881, '67.215.246.10', (error, bytes) => bytes) // 4, handed to the transport
})

rinfo.size equals message.length, and rinfo.family is 'IPv4' or 'IPv6'. The send callback reports bytes handed to the transport, not delivered. The rest of the datagram surface is on UDP.

[Page] Read addresses once they land

The compiled code asks for a socket’s addresses whenever it likes, often before the relay has answered. Node answers undefined for an address it does not have yet. The library throws Socket is not connected from each of remoteAddress, remotePort, localAddress and localPort until the relay has answered, and answers from the connect event on. A socket the server accepted can name its peer inside the connection handler, because the library publishes its addresses before it emits. Read each getter inside a guard of its own, and answer the engine’s not-connected code on a throw:

app.ts

import * as net from '@fkn/lib/net'

// what the compiled code's getpeername reads, one property at a time, with a throw answered as not connected yet
const peerOf = (socket: net.Socket) => {
  const read = <T>(get: () => T) => { try { return get() } catch { return undefined } }
  const address = read(() => socket.remoteAddress)
  const port = read(() => socket.remotePort)
  return address === undefined || port === undefined ? null : { address, port }
}

const socket = net.connect({ host: '67.215.246.10', port: 6881 })
socket.on('error', (error: Error) => error.message)
peerOf(socket) // null, each getter threw Socket is not connected
socket.on('connect', () => {
  peerOf(socket) // { address: '67.215.246.10', port: 6881 }
})

const server = net.createServer((peer) => {
  peerOf(peer) // the peer's address and port, readable inside the handler
})
server.on('error', (error: Error) => error.message) // a refused bind lands here, and listening never fires
server.listen(0, '0.0.0.0')

peerOf answers null until the relay has answered and the addresses from then on, so the engine’s own lookup returns its not-connected code instead of an exception inside the compiled code. An accepted socket answers at once. Hand a socket to the engine only once it can name its peer, since an engine that cannot name a peer it accepted may drop it without a report. The listener itself is on hold an inbound port.

Check it worked

Send the engine two chunks on one TCP connection, or two datagrams, and read them back through the engine’s own read call. Each read matches what the peer sent, byte for byte, and the first still matches after the second has arrived. A dial to a public address runs the engine’s connect callback with the peer’s address on the socket, and an accepted peer reaches the accept path with one too. When that is not what you see:

1. Data that is right on the first read and wrong on the second. A chunk was kept as a view rather than a copy, in the listener or in the engine’s own memory. Copy in the data and message listeners, and copy again into linear memory when the compiled code reads.
2. The engine throws on a fresh connection. An address getter was read before the relay had answered and threw Socket is not connected: on a socket the engine dialed that is any read before connect fires, while an accepted socket can name its peer inside the connection handler.
3. A write fails with Socket not connected, on the write callback and then on error. The engine wrote on a socket whose connect() was never called, so its number was handed out before the socket was dialed.
4. Nothing arrives and nothing fails, then after 8,000 ms error carries a BrokerUnreachableError. The engine runs in a worker nobody relayed, see run sockets in a worker.

Every other message a socket can end on has its row on every error.

Optional: Run the engine in a worker

Most integrations this recipe is drawn from run the engine on a worker thread, relayed from the page with await relayWorker(worker, { unregisterSignal }) so its socket calls reach the broker, and the host file above runs there unchanged, see run sockets in a worker.

Optional: Hold an inbound port

An engine that accepts peers reserves its port on UDP and TCP together before it starts, keeps it across a relay session that drops, and reports a refusal as a state rather than an exception, see hold an inbound port.

See also

• TCP and UDP sockets
• hold an inbound port
• bundle an app that uses sockets
• testing
• every error