Hold an inbound port

You can hold a port that peers on the internet can reach, and know its number, or know that you have none. This page covers reserving that port on UDP and TCP together from a worker, reading a refusal, getting the port back after the relay session drops, and reporting the result to the page as a state rather than an exception.

The port lives on the relay, the server that holds the real socket at the far end of net and dgram. The end state is an app that either knows the port peers can reach it on, or says plainly that it has none. What the recipe costs:

• Uses createServer, listen, address and close from @fkn/lib/net; createSocket, bind and address from @fkn/lib/dgram; BrokerUnreachableError from @fkn/lib/api
• Needs nothing installed
• Proven by four integrations

Every step but the last carries the [Worker] badge, defined on recipes. The engine runs in a worker, a realm (one JavaScript execution context) of its own, that the page has relayed with await relayWorker(worker, { unregisterSignal }) so its socket calls reach the broker, the connection the page holds into FKN. run sockets in a worker builds that worker. The same calls run on the page for an engine without a worker, as the optional step shows.

[Worker] Reserve UDP first

Ask for port 0 and let the relay report the number it granted. The datagram socket goes first because peers record its number from the datagrams themselves, so the TCP listener has to match it rather than the other way round:

engine.ts

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

const udp = dgram.createSocket('udp4')
udp.on('error', (error: Error) => error.message) // a refusal lands here, and listening never fires
udp.bind(0, '0.0.0.0', () => {
  udp.address().port // the number the relay gave
})

bind runs the callback and emits listening once the relay has answered, and address() answers the granted port from then on. Before that it throws EBADF, so read it inside the callback. The socket holds the busy token udp socket, one of the reasons its realm reports itself busy, from bind until close, as TCP and UDP sockets explains.

[Worker] Bind TCP exactly or fail

Name the number the datagram socket holds, and pass '0.0.0.0' as the host. A listen() with no host binds '::' first and falls back to '0.0.0.0', which pays the broker deadline twice when there is no broker:

engine.ts

const server = net.createServer()
server.on('error', (error: Error) => error.message) // the relay refused the number, and listening never fires
server.listen(port, '0.0.0.0', () => {
  const address = server.address()
  const held = typeof address === 'object' && address !== null && address.port === port
  held // the two numbers match, or the attempt fails
  if (!held) server.close() // another number is not the reservation, so let it go and keep the datagram socket
})

The listener is your reservation only when the granted port is the one you named. Another number would make your announcement wrong, so treat it as a refusal: close the server and keep the datagram socket, since a port held on UDP alone is still a port peers can reach.

Note

TCP and UDP are separate port spaces, so the match usually lands on the first try.

Never name a port you do not already hold. This number is the one exception, because your own datagram socket holds it. Everywhere else ask for 0, and name a port only to reclaim one this app held a moment ago, as the reopen loop below does. The relay may refuse a port, and the error names the reason.

[Worker] Read a refusal

A refused bind emits error and nothing else: no listening, no callback and no close. A successful bind emits listening, and an error after that is the relay session going away. The same two events tell a refusal from a drop only with a flag that records which came first:

engine.ts

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

type Holder = {
  once(event: 'listening', listener: () => void): unknown
  on(event: 'error', listener: (error: Error) => void): unknown
}

// true on listening, false on a refusal, and the error listener stays for the holder's whole life
const bindOnce = (holder: Holder, start: () => void) => new Promise<boolean>(resolve => {
  let settled = false
  holder.once('listening', () => {
    settled = true
    resolve(true)
  })
  holder.on('error', () => {
    if (settled) return // a later drop belongs to the reopen loop
    settled = true
    resolve(false) // 'error' fired and 'listening' never will
  })
  start()
})

const udp = dgram.createSocket('udp4')
const bound = await bindOnce(udp, () => udp.bind(0, '0.0.0.0')) // false on a refusal, and the socket holds nothing
if (!bound) udp.close(() => {}) // the callback never runs: there is no listener to close

The contract is asymmetric in a way no signature shows. A refused bind holds nothing open: the busy token is released at once, and close() finds no listener to close, so it returns early, runs no callback and emits no close. A promise wrapped around that close() never settles. A net.Server behaves the same way, as listening describes.

The error listener stays attached for the holder’s whole life. An emitter with no error listener throws on emit, and a session drop arrives on that event later, so removing the listener turns a harmless drop into an uncaught throw in the worker.

[Worker] Reclaim by name first

Your sockets share one relay session, and a lost session closes every socket on it. Nothing reconnects on its own: the next listen dials again, as the transports underneath explains. When the session drops from under a listener, error fires with WebVPN session closed if you listen for it, then close. When the relay releases the binding from its side, close fires alone.

So close after listening is the trigger. Peers already know the old number, so the loop asks for it by name on its first tries and takes whatever is free after that, waiting longer between attempts each time:

engine.ts

export type Reachable = { type: 'reachable', port: number | null }
const report = (port: number | null) => self.postMessage({ type: 'reachable', port } satisfies Reachable)

const delays = [1_000, 5_000, 30_000] // your own ladder, the library has none
let held = 6881 // the number peers already know
let attempts = 0
let current: net.Server | undefined
let stopping = false

const reopen = async (): Promise<void> => {
  const server = net.createServer()
  current = server
  server.on('close', () => {
    if (server !== current || stopping) return // a discarded server never touches its replacement
    report(null) // no inbound port on the page until this heals
    setTimeout(reopen, delays[Math.min(attempts, delays.length - 1)])
  })
  const want = attempts < 2 ? held : 0 // reclaim the same number first, then take whatever is free
  attempts += 1
  if (!await bindOnce(server, () => server.listen(want, '0.0.0.0'))) { // refused, so nothing is open to close
    setTimeout(reopen, delays[Math.min(attempts, delays.length - 1)])
    return
  }
  const address = server.address()
  if (address && typeof address === 'object') held = address.port // the number peers can reach now
  attempts = 0 // a healed listener starts the ladder over
  report(held)
}

Every attempt makes a new server, and the identity check keeps a discarded server’s close from touching its replacement. The delays are yours: the library has no backoff of its own, and a bind that reaches the broker settles as listening or error. The datagram socket gets the same loop with bind, and its close arrives with an error first only when you listen for one.

[Page] Report a named state

The engine posts what it holds, and the page turns that into a state. The port is held in the worker’s realm, so the page never sees the sockets, only the message:

app.ts

const engine = new Worker(new URL('./engine.ts', import.meta.url), { type: 'module' })
const stop = new AbortController()
await relayWorker(engine, { unregisterSignal: stop.signal }) // the engine's binds reach the broker from here on

type Inbound = { state: 'starting' } | { state: 'held', port: number } | { state: 'none' }
let inbound: Inbound = { state: 'starting' } // on screen until the engine answers
engine.addEventListener('message', (event: MessageEvent<Reachable>) => {
  if (event.data.type !== 'reachable') return
  inbound = event.data.port === null ? { state: 'none' } : { state: 'held', port: event.data.port }
  status.textContent = inbound.state === 'held' ? `reachable on port ${inbound.port}` : 'no inbound port' // the UI says "no inbound port" rather than throwing
})

A refused port is an answer, not a failure. The engine’s outbound connections still work, and the page says what changed. Show none in words rather than colour alone, and keep starting on screen until the engine answers, since a bind waits up to 8,000 ms for the broker before it fails.

Check it worked

server.address() answers an object while the listener is bound, and its port equals the number the datagram socket holds. When a peer dials that port, the server emits connection with a socket whose remoteAddress and remotePort are readable at once. The page shows the number, and it shows no inbound port after the relay session drops, until the loop heals it.

When it does not:

1. error fires and listening never does. That is a refusal, not a timeout, and the message names the reason: webvpn: socket capacity reached, webvpn: socket control queue saturated, webvpn: account session capacity reached, webvpn: token not accepted, or webvpn: egress to a non-public address refused for a bind address that is not public. WebVPN setup timeout: <what> took over <ms>ms and FKN WebVPN: no relay reachable are worth a retry after a delay.
2. The error is a BrokerUnreachableError. No broker answered within 8,000 ms, or 1,000 ms once any call in the realm has missed that deadline. In a worker that means nobody relayed it, see run sockets in a worker.
3. Neither event has fired. The bind is still inside the broker deadline, and listen() with no host waits twice, so pass '0.0.0.0'.
4. listening fired, and address().port is not the number you named. The relay granted another port, so the TCP half of the reservation is not held. Close the server and keep the datagram socket.
5. close fired after listening. The relay released the binding or the session dropped, and the loop above reopens. An error comes first only on a holder with an error listener.

Optional: Tell the deadline from a refusal

An engine on the page reserves the port with the same calls and no relayWorker. There the deadline error means the broker frame, the hidden fkn.app iframe the library mounts, never connected. In a worker it means nobody relayed the worker. BrokerUnreachableError is created in the realm that opened the socket, so instanceof tells it from a relay refusal in both places:

app.ts

import * as dgram from '@fkn/lib/dgram'
import { BrokerUnreachableError } from '@fkn/lib/api'

const udp = dgram.createSocket('udp4')
udp.on('error', (error: Error) => {
  error instanceof BrokerUnreachableError // true when no broker answered within 8000 ms, and false for a relay refusal
  error.message // '@fkn/lib: no broker connection within 8000ms, so a udp socket could not be requested'
})
udp.on('listening', () => udp.address().port) // the number the relay gave
udp.bind(0, '0.0.0.0')

The class survives because it never crosses a realm. Every relay refusal arrives as a plain Error whose message is the only signal, as handling errors explains.

See also

• TCP and UDP sockets
• run sockets in a worker
• give a WebAssembly engine sockets
• every error
• limits and timeouts