:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import posthog from 'posthog-js'
import { ApiError } from 'lib/api-error'
import { terminalNetplayMailboxRetrieve, terminalNetplaySignalCreate } from '~/generated/core/api'
import type { TerminalNetplayReceivedSignalApi } from '~/generated/core/api.schemas'
// Doom's network module in PostHog/terminal-assets sends SLIP frames over the guest's third serial port.
// The first byte names the peer: guest frames name the destination, and host frames name the source.
const SLIP_END = 0xc0
const SLIP_ESC = 0xdb
const SLIP_ESC_END = 0xdc
const SLIP_ESC_ESC = 0xdd
const HOST_PEER = 0
const CONTROL_PEER = 255
const MAX_FRAME = 1500
const ROOM_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'
const ICE_SERVERS: RTCIceServer[] = [{ urls: 'stun:stun.cloudflare.com:3478' }]
const HOST_POLL_MS = 1000
const JOIN_POLL_MS = 500
const JOIN_TIMEOUT_MS = 20_000
const GATHER_TIMEOUT_MS = 3000
const MAX_PENDING_PEERS = 16
interface HostLobby {
room: string
token: string
game: AbortSignal
signal: AbortSignal
peers: Map<string, number>
pending: Set<string>
}
export function encodeFrame(peer: number, payload: Uint8Array): Uint8Array {
const bytes = [SLIP_END]
for (const byte of [peer, ...payload]) {
if (byte === SLIP_END) {
bytes.push(SLIP_ESC, SLIP_ESC_END)
} else if (byte === SLIP_ESC) {
bytes.push(SLIP_ESC, SLIP_ESC_ESC)
} else {
bytes.push(byte)
}
}
bytes.push(SLIP_END)
return Uint8Array.from(bytes)
}
export class FrameDecoder {
private frame: number[] = []
private escaped = false
private overflow = false
push(byte: number): Uint8Array | null {
if (byte === SLIP_END) {
const frame = this.overflow || !this.frame.length ? null : Uint8Array.from(this.frame)
this.frame = []
this.escaped = false
this.overflow = false
return frame
}
if (this.escaped) {
byte = byte === SLIP_ESC_END ? SLIP_END : byte === SLIP_ESC_ESC ? SLIP_ESC : byte
this.escaped = false
} else if (byte === SLIP_ESC) {
this.escaped = true
return null
}
if (this.frame.length <= MAX_FRAME) {
this.frame.push(byte)
} else {
this.overflow = true
}
return null
}
}
function randomCode(alphabet: string, length: number): string {
return Array.from(
crypto.getRandomValues(new Uint8Array(length)),
(value) => alphabet[value % alphabet.length]
).join('')
}
function sleep(ms: number, signal: AbortSignal): Promise<void> {
return new Promise((resolve) => {
if (signal.aborted) {
resolve()
return
}
const timer = setTimeout(done, ms)
signal.addEventListener('abort', done, { once: true })
function done(): void {
clearTimeout(timer)
signal.removeEventListener('abort', done)
resolve()
}
})
}
// Sending complete descriptions avoids a second signaling round trip for each ICE candidate.
function gathered(connection: RTCPeerConnection, signal: AbortSignal): Promise<void> {
return new Promise((resolve) => {
const timer = setTimeout(done, GATHER_TIMEOUT_MS)
connection.addEventListener('icegatheringstatechange', check)
signal.addEventListener('abort', done, { once: true })
check()
function check(): void {
if (signal.aborted || connection.iceGatheringState === 'complete') {
done()
}
}
function done(): void {
clearTimeout(timer)
connection.removeEventListener('icegatheringstatechange', check)
signal.removeEventListener('abort', done)
resolve()
}
})
}
function opened(channel: RTCDataChannel, timeout: number, signal: AbortSignal): Promise<boolean> {
return new Promise((resolve) => {
if (signal.aborted) {
resolve(false)
return
}
if (channel.readyState === 'open') {
resolve(true)
return
}
const timer = setTimeout(() => done(false), timeout)
const open = (): void => done(true)
const close = (): void => done(false)
channel.addEventListener('open', open)
channel.addEventListener('close', close)
signal.addEventListener('abort', close, { once: true })
function done(result: boolean): void {
clearTimeout(timer)
channel.removeEventListener('open', open)
channel.removeEventListener('close', close)
signal.removeEventListener('abort', close)
resolve(result)
}
})
}
class NetplayError extends Error {}
/** Relays Doom network frames between this terminal's VM and other players' browsers over WebRTC. */
export class TerminalNetplay {
private decoder = new FrameDecoder()
private encoder = new TextEncoder()
private send?: (bytes: Uint8Array) => void
private game?: AbortController
private lobby?: AbortController
private channels = new Map<number, RTCDataChannel>()
constructor(
private projectId: string,
signal: AbortSignal
) {
signal.addEventListener('abort', () => this.endGame(), { once: true })
}
attach(send: (bytes: Uint8Array) => void): void {
this.send = send
}
receive(byte: number): void {
const frame = this.decoder.push(byte)
if (!frame) {
return
}
if (frame[0] === CONTROL_PEER) {
this.control(new TextDecoder().decode(frame.subarray(1)))
return
}
const channel = this.channels.get(frame[0])
if (channel?.readyState === 'open') {
channel.send(frame.slice(1))
}
}
private control(message: string): void {
if (message === 'host') {
void this.host(this.newGame())
} else if (message.startsWith('join ')) {
void this.join(message.slice(5).toUpperCase(), this.newGame())
} else if (message === 'launched') {
// Doom accepts no players after launch, so the room can expire.
this.lobby?.abort()
}
}
private reply(message: string): void {
this.send?.(encodeFrame(CONTROL_PEER, this.encoder.encode(message)))
}
private newGame(): AbortSignal {
this.endGame()
this.game = new AbortController()
return this.game.signal
}
private endGame(): void {
this.lobby?.abort()
this.game?.abort()
this.channels.clear()
}
private connect(
peer: number,
game: AbortSignal
): { connection: RTCPeerConnection; channel: RTCDataChannel; close: () => void } {
const connection = new RTCPeerConnection({ iceServers: ICE_SERVERS })
// Doom resends lost packets itself, so late packets are worse than lost ones.
const channel = connection.createDataChannel('doom', {
negotiated: true,
id: 0,
ordered: false,
maxRetransmits: 0,
})
channel.binaryType = 'arraybuffer'
let closed = false
channel.addEventListener('message', ({ data }: MessageEvent<ArrayBuffer>) => {
if (!closed && !game.aborted && data.byteLength <= MAX_FRAME) {
this.send?.(encodeFrame(peer, new Uint8Array(data)))
}
})
const close = (): void => {
if (closed) {
return
}
closed = true
game.removeEventListener('abort', close)
channel.removeEventListener('close', close)
connection.close()
if (this.channels.get(peer) === channel) {
this.channels.delete(peer)
}
}
game.addEventListener('abort', close, { once: true })
channel.addEventListener('close', close, { once: true })
this.channels.set(peer, channel)
return { connection, channel, close }
}
private async host(game: AbortSignal): Promise<void> {
const room = randomCode(ROOM_ALPHABET, 6)
const lobby = (this.lobby = new AbortController())
const signal = lobby.signal
const token = randomCode('0123456789abcdef', 64)
const state: HostLobby = { room, token, game, signal, peers: new Map(), pending: new Set() }
let announced = false
while (!signal.aborted) {
try {
const { signals } = await terminalNetplayMailboxRetrieve(
this.projectId,
{ room, peer: 'host' },
{ signal, headers: { 'X-Terminal-Netplay-Token': token } }
)
if (signal.aborted) {
return
}
if (!announced) {
announced = true
this.reply(`room ${room}`)
posthog.capture('terminal deathmatch hosted')
}
this.acceptOffers(state, signals)
} catch (error) {
if (signal.aborted) {
return
}
if (!announced) {
this.reply(`error ${this.describe(error, 'Could not open a deathmatch room. Try again.')}`)
return
}
}
await sleep(HOST_POLL_MS, signal)
}
}
private acceptOffers(lobby: HostLobby, signals: TerminalNetplayReceivedSignalApi[]): void {
for (const { sender, description } of signals) {
if (description.type !== 'offer' || lobby.peers.has(sender) || lobby.pending.size >= MAX_PENDING_PEERS) {
continue
}
const allocated = new Set(lobby.peers.values())
let peer = HOST_PEER + 1
while (allocated.has(peer)) {
peer++
}
if (peer < CONTROL_PEER) {
lobby.peers.set(sender, peer)
lobby.pending.add(sender)
void this.accept(lobby, sender, description.sdp, peer)
}
}
}
private async accept(lobby: HostLobby, sender: string, sdp: string, peer: number): Promise<void> {
const negotiation = new AbortController()
const signal = negotiation.signal
const abort = (): void => negotiation.abort()
const timeout = setTimeout(abort, JOIN_TIMEOUT_MS)
lobby.signal.addEventListener('abort', abort, { once: true })
let close: (() => void) | undefined
let connected = false
try {
const client = this.connect(peer, lobby.game)
close = client.close
signal.addEventListener('abort', client.close, { once: true })
const { connection, channel } = client
await connection.setRemoteDescription({ type: 'offer', sdp })
if (signal.aborted) {
return
}
await connection.setLocalDescription()
await gathered(connection, signal)
if (signal.aborted || !connection.localDescription) {
return
}
await terminalNetplaySignalCreate(
this.projectId,
{
room: lobby.room,
sender: 'host',
recipient: sender,
description: { type: 'answer', sdp: connection.localDescription.sdp },
},
{ signal, headers: { 'X-Terminal-Netplay-Token': lobby.token } }
)
connected = await opened(channel, JOIN_TIMEOUT_MS, signal)
} catch {
// The joining player reports the failure when the answer does not arrive.
} finally {
clearTimeout(timeout)
lobby.signal.removeEventListener('abort', abort)
if (close) {
signal.removeEventListener('abort', close)
}
lobby.pending.delete(sender)
if (!connected) {
close?.()
lobby.peers.delete(sender)
}
}
}
private async waitForAnswer(
room: string,
peer: string,
token: string,
deadline: number,
game: AbortSignal
): Promise<string | undefined> {
while (!game.aborted) {
if (Date.now() > deadline) {
throw new NetplayError('The host did not answer. Check the room code and try again.')
}
await sleep(JOIN_POLL_MS, game)
if (game.aborted) {
return
}
const { signals } = await terminalNetplayMailboxRetrieve(
this.projectId,
{ room, peer },
{ signal: game, headers: { 'X-Terminal-Netplay-Token': token } }
)
const answer = signals.find(({ sender, description }) => sender === 'host' && description.type === 'answer')
if (answer) {
return answer.description.sdp
}
}
}
private async join(room: string, game: AbortSignal): Promise<void> {
const id = randomCode('abcdefghijklmnopqrstuvwxyz0123456789', 16)
const token = randomCode('0123456789abcdef', 64)
const deadline = Date.now() + JOIN_TIMEOUT_MS
let close: (() => void) | undefined
let connected = false
try {
const client = this.connect(HOST_PEER, game)
close = client.close
const { connection, channel } = client
await connection.setLocalDescription()
await gathered(connection, game)
if (game.aborted || !connection.localDescription) {
return
}
await terminalNetplaySignalCreate(
this.projectId,
{
room,
sender: id,
recipient: 'host',
description: { type: 'offer', sdp: connection.localDescription.sdp },
},
{ signal: game, headers: { 'X-Terminal-Netplay-Token': token } }
)
const answer = await this.waitForAnswer(room, id, token, deadline, game)
if (game.aborted || !answer) {
return
}
await connection.setRemoteDescription({ type: 'answer', sdp: answer })
connected = await opened(channel, Math.max(deadline - Date.now(), 5000), game)
if (!connected) {
throw new NetplayError(
'Could not connect to the host. A firewall or VPN may block peer-to-peer connections.'
)
}
if (!game.aborted) {
this.reply('joined')
posthog.capture('terminal deathmatch joined', { success: true })
}
} catch (error) {
if (!game.aborted) {
this.reply(`error ${this.describe(error, 'Could not join the deathmatch. Try again.')}`)
posthog.capture('terminal deathmatch joined', { success: false })
}
} finally {
if (!connected) {
close?.()
}
}
}
private describe(error: unknown, fallback: string): string {
if (error instanceof NetplayError) {
return error.message
}
if (error instanceof ApiError && (error.status === 404 || error.status === 429) && error.detail) {
return error.detail
}
return fallback
}
}