WebTransport and Media over QUIC

const wt = new WebTransport('https://game.example.test:4433/arena', {
  congestionControl: 'low-latency',   // 'default' | 'throughput' | 'low-latency'
  allowPooling: false,                // do not share the connection with other origins
  requireUnreliable: true,            // fail instead of using a reliable-only HTTP/2 session
  protocols: ['pixel-arena.v1'],      // application-level protocol negotiation (newer browsers)
  serverCertificateHashes: []         // see "Certificates" below
})

// Client opens a reliable, ordered, bidirectional stream.
const bidi = await wt.createBidirectionalStream({ sendOrder: 10 })
const writer = bidi.writable.getWriter()
await writer.write(new TextEncoder().encode('hello'))
await writer.close()

// A one-way stream: the client only writes.
const uni = await wt.createUnidirectionalStream()

// The server can open streams too; the client reads them.
const incoming = wt.incomingBidirectionalStreams.getReader()
const { value: serverStream } = await incoming.read()
const { value: unis } = await wt.incomingUnidirectionalStreams.getReader().read()

const writer = (wt.datagrams.createWritable ? wt.datagrams.createWritable() : wt.datagrams.writable).getWriter()
const reader = wt.datagrams.readable.getReader()

await writer.write(new Uint8Array([1, 2, 3]))      // fire and forget
const { value, done } = await reader.read()        // one datagram per read
console.log(wt.datagrams.maxDatagramSize)          // about 1200 bytes in practice

npm install @fails-components/webtransport @fails-components/webtransport-transport-http3-quiche ws
sh make-cert.sh
node server.mjs

// Pixel Arena input server: WebTransport datagrams with a WebSocket fallback.
import { createServer } from 'node:http'
import { readFileSync } from 'node:fs'
import { createHash, X509Certificate, randomBytes } from 'node:crypto'
import { Http3Server } from '@fails-components/webtransport'
import { WebSocketServer } from 'ws'

const WT_PORT = 4433
const HTTP_PORT = 8080
const cert = readFileSync('cert.pem', 'utf8')
const privKey = readFileSync('key.pem', 'utf8')
const certHash = createHash('sha256').update(new X509Certificate(cert).raw).digest('hex')

let tick = 0
setInterval(() => { tick = (tick + 1) >>> 0 }, 1000 / 30)

// Input datagram, 10 bytes: version u8 | buttons u8 | seq u16 | moveX i8 | moveY i8 | clientMs u32
// Ack datagram, 14 bytes: the same bytes followed by the server tick as u32 (big endian).
function ackFor(input) {
  if (input.byteLength !== 10 || input[0] !== 1) return null
  const out = new Uint8Array(14)
  out.set(input, 0)
  new DataView(out.buffer).setUint32(10, tick)
  return out
}

// 1. HTTP: static page plus the certificate hash for serverCertificateHashes (development only).
const http = createServer((req, res) => {
  const path = new URL(req.url, 'http://localhost').pathname
  if (path === '/config.json') {
    res.setHeader('content-type', 'application/json')
    res.end(JSON.stringify({ wtUrl: `https://127.0.0.1:${WT_PORT}/arena`, wsUrl: `ws://127.0.0.1:${HTTP_PORT}/arena`, certHash }))
  } else if (path === '/') {
    res.setHeader('content-type', 'text/html')
    res.end(readFileSync('index.html'))
  } else if (path === '/client.js') {
    res.setHeader('content-type', 'text/javascript')
    res.end(readFileSync('client.js'))
  } else {
    res.statusCode = 404
    res.end()
  }
})

// 2. WebSocket fallback: the same 10/14 byte messages in binary frames.
const wss = new WebSocketServer({ server: http, path: '/arena' })
wss.on('connection', (ws) => {
  ws.on('message', (data, isBinary) => {
    if (!isBinary) return
    const ack = ackFor(new Uint8Array(data))
    if (ack) ws.send(ack)
  })
})

// 3. WebTransport over HTTP/3.
const h3 = new Http3Server({ port: WT_PORT, host: '127.0.0.1', secret: randomBytes(16).toString('hex'), cert, privKey })

async function handleSession(session) {
  await session.ready
  // Reliable control stream: the client opens it and sends one JSON line, then we answer with its player id.
  const bidi = session.incomingBidirectionalStreams.getReader()
  const { value: stream } = await bidi.read()
  const reader = stream.readable.getReader()
  const { value } = await reader.read()
  const hello = JSON.parse(new TextDecoder().decode(value))
  const writer = stream.writable.getWriter()
  await writer.write(new TextEncoder().encode(JSON.stringify({ type: 'welcome', player: hello.name, maxDatagramSize: session.datagrams.maxDatagramSize }) + '\n'))
  await writer.close()
  // Unreliable path: acknowledge each input datagram.
  const dgWriter = session.datagrams.writable.getWriter()
  const dgReader = session.datagrams.readable.getReader()
  for (;;) {
    const { value: dg, done } = await dgReader.read()
    if (done) break
    const ack = ackFor(dg)
    if (ack) dgWriter.write(ack).catch(() => {})
  }
}

h3.startServer()
await h3.ready
const reader = h3.sessionStream('/arena').getReader()
http.listen(HTTP_PORT, '127.0.0.1', () => console.log(`http+ws on ${HTTP_PORT}, webtransport on udp ${WT_PORT}, cert sha256 ${certHash}`))
for (;;) {
  const { value: session, done } = await reader.read()
  if (done) break
  handleSession(session).catch((err) => console.error('session ended:', err.message))
}

<!doctype html>
<meta charset="utf-8">
<title>Pixel Arena transport test</title>
<pre id="log"></pre>
<script type="module" src="/client.js"></script>

// Pixel Arena input channel: WebTransport datagrams, falling back to a WebSocket.
const log = (m) => { document.getElementById('log').textContent += m + '\n'; console.log(m) }

function encodeInput(seq, moveX, moveY, buttons) {
  const buf = new ArrayBuffer(10)
  const v = new DataView(buf)
  v.setUint8(0, 1)
  v.setUint8(1, buttons)
  v.setUint16(2, seq)
  v.setInt8(4, moveX)
  v.setInt8(5, moveY)
  v.setUint32(6, performance.now() >>> 0)
  return new Uint8Array(buf)
}

function decodeAck(bytes) {
  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
  return { seq: v.getUint16(2), clientMs: v.getUint32(6), serverTick: v.getUint32(10) }
}

async function openWebTransport(cfg, onAck) {
  if (!('WebTransport' in window)) throw new Error('WebTransport is not available')
  const options = {}
  if (cfg.certHash) {
    // Development only: pin a self-signed certificate (valid <= 14 days, ECDSA).
    const hash = Uint8Array.from(cfg.certHash.match(/../g).map((h) => parseInt(h, 16)))
    options.serverCertificateHashes = [{ algorithm: 'sha-256', value: hash }]
  }
  const wt = new WebTransport(cfg.wtUrl, options)
  await wt.ready
  // Reliable control stream.
  const stream = await wt.createBidirectionalStream()
  const w = stream.writable.getWriter()
  await w.write(new TextEncoder().encode(JSON.stringify({ type: 'hello', name: 'ada' })))
  await w.close()
  const r = stream.readable.getReader()
  const { value } = await r.read()
  log('control: ' + new TextDecoder().decode(value).trim())
  // Unreliable input path.
  // Safari exposes createWritable(); Chromium and Firefox still expose the older writable attribute.
  const dgOut = wt.datagrams.createWritable ? wt.datagrams.createWritable() : wt.datagrams.writable
  const dgWriter = dgOut.getWriter()
  const dgReader = wt.datagrams.readable.getReader()
  ;(async () => {
    for (;;) {
      const { value: dg, done } = await dgReader.read()
      if (done) return
      onAck(decodeAck(dg))
    }
  })()
  wt.closed.then(() => log('closed'), (e) => log('closed with error: ' + e.message))
  return { kind: 'webtransport', send: (bytes) => dgWriter.write(bytes), maxSize: wt.datagrams.maxDatagramSize, close: () => wt.close() }
}

function openWebSocket(cfg, onAck) {
  return new Promise((resolve, reject) => {
    const ws = new WebSocket(cfg.wsUrl)
    ws.binaryType = 'arraybuffer'
    ws.onerror = () => reject(new Error('WebSocket failed'))
    ws.onmessage = (e) => onAck(decodeAck(new Uint8Array(e.data)))
    ws.onopen = () => resolve({ kind: 'websocket', send: (bytes) => ws.send(bytes), maxSize: 16384, close: () => ws.close() })
  })
}

const cfg = await (await fetch('/config.json')).json()
if (new URLSearchParams(location.search).has('forceWs')) delete cfg.wtUrl
let acks = 0
const onAck = (a) => { acks++; if (acks === 1 || acks === 30) log(`ack seq=${a.seq} serverTick=${a.serverTick}`) }
let conn
try {
  if (!cfg.wtUrl) throw new Error('forced fallback')
  conn = await openWebTransport(cfg, onAck)
} catch (err) {
  log('falling back to WebSocket: ' + err.message)
  conn = await openWebSocket(cfg, onAck)
}
log('transport=' + conn.kind + ' maxDatagramSize=' + conn.maxSize)
for (let seq = 0; seq < 30; seq++) {
  await conn.send(encodeInput(seq, 1, 0, 0))
  await new Promise((r) => setTimeout(r, 33))
}
await new Promise((r) => setTimeout(r, 300))
log(`DONE transport=${conn.kind} acks=${acks}`)
document.title = 'DONE ' + conn.kind + ' ' + acks
conn.close()

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --origin-to-force-quic-on=127.0.0.1:4433 http://127.0.0.1:8080/