N6: Joining games: direct connect, LAN and server list

- LAN discovery: a listening server answers QUERY packets on its game port
  plus one (ServerBeacon, off with --no-lan). ServerBrowser scans eight game
  ports from 24650 by broadcast.
- A self-hostable list server: --list-server [--port=N] (ListServer,
  default UDP 24660). Game servers register with --list=HOST[:PORT] and
  --name=NAME; they are listed under their source address only after
  echoing a CHALLENGE token. Entries expire after 45 s, 8 per address,
  256 in all; every source is rate-limited (SourceLimiter).
- NetDiscovery messages: every QUERY is padded to 512 bytes and no answer
  is bigger, so neither service amplifies spoofed requests.
- tidewall --browse [--list=...] [--lan-target=IP] [--lan-port=N] prints
  the servers found as JSON until menus (A10) show them.
- People who connect mid-match or during results watch a living player
  (Match.watch) and take places ahead of bots in the next lobby, instead
  of being told the server is full. Bots fill only the places left when
  the match starts.
- Tests: codec round trips, size limits and a 40,000-message fuzz; list
  server with fake servers (challenge, stolen and wrong tokens, renewal,
  expiry, caps, flood); LAN scan over loopback; watchers over UDP; lobby
  backfill. make discovery-check runs it all as real processes.

Closes #37

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-12 17:33:32 -05:00
co-authored by Claude Opus 5.5
parent 53e81bebe1
commit f795ee3fa5
31 changed files with 1524 additions and 17 deletions
+231
View File
@@ -0,0 +1,231 @@
## Finding games: the small UDP messages for LAN discovery and the list server, kept
## apart from the game protocol (NetProtocol), which runs over ENet on the game port.
##
## Everything is little-endian and starts with u8 type and the 4 bytes "TDWD":
##
## QUERY client -> game server or list server. u16 protocol version, u8 page,
## zero padding up to QUERY_BYTES.
## INFO game server -> client. u16 protocol version, u16 game port,
## u8 people, u8 max players, u8 phase, u8 name length, name.
## REGISTER game server -> list server. u32 token, then the same fields as INFO.
## CHALLENGE list server -> game server. u32 token.
## LIST list server -> client. u8 page, u8 pages, u8 count, then per server:
## u8 address length, address (ASCII), and the same fields as INFO.
##
## No answer is ever bigger than the QUERY that asked for it, so neither kind of
## server can be used to flood a third party with more bytes than it was sent. A
## REGISTER is answered with a CHALLENGE that is smaller still, and a server is only
## listed once it echoes the token, which proves it receives at the address it
## claims to send from. Decoders return an empty Dictionary for anything malformed
## and never raise an error.
class_name NetDiscovery
extends RefCounted
const MAGIC: String = "TDWD"
const MSG_QUERY: int = 1
const MSG_INFO: int = 2
const MSG_REGISTER: int = 3
const MSG_CHALLENGE: int = 4
const MSG_LIST: int = 5
## Every QUERY is padded to this size; every answer fits in it.
const QUERY_BYTES: int = 512
## A game server answers LAN queries on its game port plus this.
const DISCOVERY_PORT_OFFSET: int = 1
## A LAN scan asks the discovery ports of this many game ports, from the default up in
## steps of two, so a few servers on one machine are all found.
const LAN_SCAN_SERVERS: int = 8
const DEFAULT_LIST_PORT: int = 24660
const SERVER_NAME_MAX_CHARS: int = 32
const SERVER_NAME_MAX_BYTES: int = 48
const DEFAULT_SERVER_NAME: String = "Tidewall server"
## Longest address text: a full IPv6 address.
const ADDRESS_MAX_BYTES: int = 45
const ENTRIES_PER_PAGE: int = 4
const MAX_PAGES: int = 64
const _HEADER: int = 5
## u16 version, u16 port, u8 people, u8 max, u8 phase, u8 name length.
const _INFO_FIXED: int = 8
## A server's description: {"version", "port", "players", "max_players", "phase",
## "name"}. Everything is clamped to what fits on the wire, and people to places.
static func info(port: int, players: int, max_players: int, phase: int, server_name: String, version: int = NetProtocol.VERSION) -> Dictionary:
return {
"version": clampi(version, 0, 0xFFFF), "port": clampi(port, 0, 0xFFFF),
"players": clampi(players, 0, clampi(max_players, 0, 255)), "max_players": clampi(max_players, 0, 255),
"phase": clampi(phase, 0, 255), "name": clean_server_name(server_name),
}
## A server name fit to show, cleaned like a player name but longer.
static func clean_server_name(raw: String) -> String:
return NetProtocol.clean_name(raw, SERVER_NAME_MAX_CHARS, SERVER_NAME_MAX_BYTES, DEFAULT_SERVER_NAME)
static func encode_query(page: int = 0, version: int = NetProtocol.VERSION) -> PackedByteArray:
var out: StreamPeerBuffer = _writer(MSG_QUERY)
out.put_u16(version)
out.put_u8(clampi(page, 0, 255))
var bytes: PackedByteArray = out.data_array
bytes.resize(QUERY_BYTES)
return bytes
## {"version", "page"} or empty. Short queries are refused: the padding is what keeps
## answers from being bigger than questions.
static func decode_query(bytes: PackedByteArray) -> Dictionary:
if bytes.size() != QUERY_BYTES or not _is(bytes, MSG_QUERY):
return {}
return {"version": bytes.decode_u16(5), "page": bytes[7]}
static func encode_info(server: Dictionary) -> PackedByteArray:
var out: StreamPeerBuffer = _writer(MSG_INFO)
_put_info(out, server)
return out.data_array
static func decode_info(bytes: PackedByteArray) -> Dictionary:
if not _is(bytes, MSG_INFO):
return {}
var result: Dictionary = _read_info(bytes, _HEADER)
if result.is_empty() or int(result["end"]) != bytes.size():
return {}
result.erase("end")
return result
static func encode_register(token: int, server: Dictionary) -> PackedByteArray:
var out: StreamPeerBuffer = _writer(MSG_REGISTER)
out.put_u32(token & 0xFFFFFFFF)
_put_info(out, server)
return out.data_array
## {"token", and the INFO fields} or empty.
static func decode_register(bytes: PackedByteArray) -> Dictionary:
if bytes.size() < _HEADER + 4 or not _is(bytes, MSG_REGISTER):
return {}
var result: Dictionary = _read_info(bytes, _HEADER + 4)
if result.is_empty() or int(result["end"]) != bytes.size():
return {}
result.erase("end")
result["token"] = bytes.decode_u32(_HEADER)
return result
static func encode_challenge(token: int) -> PackedByteArray:
var out: StreamPeerBuffer = _writer(MSG_CHALLENGE)
out.put_u32(token & 0xFFFFFFFF)
return out.data_array
static func decode_challenge(bytes: PackedByteArray) -> Dictionary:
if bytes.size() != _HEADER + 4 or not _is(bytes, MSG_CHALLENGE):
return {}
return {"token": bytes.decode_u32(_HEADER)}
## One page of the list. Each entry is an INFO Dictionary with "address" added.
static func encode_list(page: int, pages: int, entries: Array[Dictionary]) -> PackedByteArray:
var out: StreamPeerBuffer = _writer(MSG_LIST)
var count: int = mini(entries.size(), ENTRIES_PER_PAGE)
out.put_u8(clampi(page, 0, 255))
out.put_u8(clampi(pages, 0, 255))
out.put_u8(count)
for index: int in count:
var entry: Dictionary = entries[index]
var address: PackedByteArray = String(entry.get("address", "")).to_ascii_buffer()
if address.size() > ADDRESS_MAX_BYTES:
address = PackedByteArray()
out.put_u8(address.size())
out.put_data(address)
_put_info(out, entry)
return out.data_array
## {"page", "pages", "servers": Array[Dictionary]} or empty.
static func decode_list(bytes: PackedByteArray) -> Dictionary:
if bytes.size() < _HEADER + 3 or bytes.size() > QUERY_BYTES or not _is(bytes, MSG_LIST):
return {}
var count: int = bytes[_HEADER + 2]
if count > ENTRIES_PER_PAGE:
return {}
var servers: Array[Dictionary] = []
var at: int = _HEADER + 3
for _index: int in count:
if at >= bytes.size():
return {}
var size: int = bytes[at]
if size == 0 or size > ADDRESS_MAX_BYTES or at + 1 + size > bytes.size():
return {}
var address: String = _address(bytes.slice(at + 1, at + 1 + size))
if address.is_empty():
return {}
var entry: Dictionary = _read_info(bytes, at + 1 + size)
if entry.is_empty():
return {}
at = int(entry["end"])
entry.erase("end")
entry["address"] = address
servers.append(entry)
if at != bytes.size():
return {}
return {"page": bytes[_HEADER], "pages": bytes[_HEADER + 1], "servers": servers}
static func _put_info(out: StreamPeerBuffer, server: Dictionary) -> void:
var name_bytes: PackedByteArray = clean_server_name(String(server.get("name", ""))).to_utf8_buffer()
out.put_u16(clampi(int(server.get("version", 0)), 0, 0xFFFF))
out.put_u16(clampi(int(server.get("port", 0)), 0, 0xFFFF))
out.put_u8(clampi(int(server.get("players", 0)), 0, 255))
out.put_u8(clampi(int(server.get("max_players", 0)), 0, 255))
out.put_u8(clampi(int(server.get("phase", 0)), 0, 255))
out.put_u8(name_bytes.size())
out.put_data(name_bytes)
## The INFO fields starting at `at`, with "end" the index after them, or empty.
static func _read_info(bytes: PackedByteArray, at: int) -> Dictionary:
if at + _INFO_FIXED > bytes.size():
return {}
var name_size: int = bytes[at + 7]
if name_size > SERVER_NAME_MAX_BYTES or at + _INFO_FIXED + name_size > bytes.size():
return {}
var port: int = bytes.decode_u16(at + 2)
var players: int = bytes[at + 4]
var max_players: int = bytes[at + 5]
if port == 0 or max_players == 0 or players > max_players:
return {}
var raw: String = NetProtocol._utf8(bytes.slice(at + _INFO_FIXED, at + _INFO_FIXED + name_size))
if name_size > 0 and raw.is_empty():
return {}
return {
"version": bytes.decode_u16(at), "port": port, "players": players, "max_players": max_players,
"phase": bytes[at + 6], "name": clean_server_name(raw), "end": at + _INFO_FIXED + name_size,
}
## Address text made only of the characters an IP address uses, or empty.
static func _address(bytes: PackedByteArray) -> String:
for byte: int in bytes:
var digit: bool = byte >= 0x30 and byte <= 0x39
var hex: bool = (byte >= 0x61 and byte <= 0x66) or (byte >= 0x41 and byte <= 0x46)
if not (digit or hex or byte == 0x2E or byte == 0x3A):
return ""
var text: String = bytes.get_string_from_ascii()
return text if text.is_valid_ip_address() else ""
static func _is(bytes: PackedByteArray, kind: int) -> bool:
return bytes.size() >= _HEADER and bytes[0] == kind and bytes.slice(1, 5) == MAGIC.to_ascii_buffer()
static func _writer(kind: int) -> StreamPeerBuffer:
var out: StreamPeerBuffer = StreamPeerBuffer.new()
out.big_endian = false
out.put_u8(kind)
out.put_data(MAGIC.to_ascii_buffer())
return out
+1
View File
@@ -0,0 +1 @@
uid://cvyxcnh6fypyq
+5 -5
View File
@@ -48,8 +48,8 @@ const MAX_HANDSHAKE_BYTES: int = 96
## A name fit to show: no control or formatting characters, single spaces, at most
## NAME_MAX_CHARS characters, and never empty.
static func clean_name(raw: String) -> String:
## NAME_MAX_CHARS characters, and never empty. Server names use longer limits.
static func clean_name(raw: String, max_chars: int = NAME_MAX_CHARS, max_bytes: int = NAME_MAX_BYTES, fallback: String = DEFAULT_NAME) -> String:
var kept: String = ""
var spaced: bool = true
for index: int in raw.length():
@@ -67,12 +67,12 @@ static func clean_name(raw: String) -> String:
elif not hidden:
kept += String.chr(code)
spaced = false
if kept.length() >= NAME_MAX_CHARS:
if kept.length() >= max_chars:
break
kept = kept.strip_edges()
while kept.to_utf8_buffer().size() > NAME_MAX_BYTES:
while kept.to_utf8_buffer().size() > max_bytes:
kept = kept.substr(0, kept.length() - 1)
return kept if not kept.is_empty() else DEFAULT_NAME
return kept if not kept.is_empty() else fallback
static func encode_hello(player_name: String, version: int = VERSION) -> PackedByteArray:
+114
View File
@@ -0,0 +1,114 @@
## The client's side of finding games: asks the LAN and any list servers which
## Tidewall servers there are, and gathers the answers. Menus (A10) show `servers`;
## until then `tidewall --browse` prints them.
##
## Each found server is an INFO Dictionary (see NetDiscovery) with "address", "port"
## being the game port to connect to, "source" ("lan" or "list") and "compatible"
## (same protocol version as this game).
class_name ServerBrowser
extends RefCounted
## Found servers by "address:port".
var servers: Dictionary = {}
## Answers that couldn't be read, so far.
var bad_packets: int = 0
var _socket: PacketPeerUDP = null
## List servers asked: "ip:port" -> pages still to ask for.
var _lists: Dictionary = {}
func open() -> Error:
close()
var socket: PacketPeerUDP = PacketPeerUDP.new()
var error: Error = socket.bind(0, "*")
if error != OK:
return error
socket.set_broadcast_enabled(true)
_socket = socket
return OK
func close() -> void:
if _socket != null:
_socket.close()
_socket = null
## Asks every server on the LAN. `targets` are the addresses to send to: the broadcast
## address by default, or particular hosts. `first_port` is the first game port asked
## about; the scan covers NetDiscovery.LAN_SCAN_SERVERS of them, two apart.
func scan_lan(targets: Array[String] = ["255.255.255.255"], first_port: int = ServerConfig.DEFAULT_PORT) -> void:
if _socket == null and open() != OK:
return
var query: PackedByteArray = NetDiscovery.encode_query()
for target: String in targets:
for index: int in NetDiscovery.LAN_SCAN_SERVERS:
var port: int = first_port + index * 2 + NetDiscovery.DISCOVERY_PORT_OFFSET
if port > 65535:
break
_socket.set_dest_address(target, port)
_socket.put_packet(query)
## Asks a list server for its first page; the rest are asked for as answers arrive.
## `host` must be an IP address.
func ask_list(host: String, port: int = NetDiscovery.DEFAULT_LIST_PORT) -> void:
if _socket == null and open() != OK:
return
_lists["%s:%d" % [host, port]] = true
_socket.set_dest_address(host, port)
_socket.put_packet(NetDiscovery.encode_query(0))
## Reads the answers that have arrived.
func poll() -> void:
if _socket == null:
return
for _index: int in 256:
if _socket.get_available_packet_count() <= 0:
break
var bytes: PackedByteArray = _socket.get_packet()
var from_ip: String = _socket.get_packet_ip()
var from_port: int = _socket.get_packet_port()
var info: Dictionary = NetDiscovery.decode_info(bytes)
if not info.is_empty():
info["address"] = from_ip
_found(info, "lan")
continue
var page: Dictionary = NetDiscovery.decode_list(bytes)
var key: String = "%s:%d" % [from_ip, from_port]
if page.is_empty() or not _lists.has(key):
bad_packets += 1
continue
for server: Dictionary in page["servers"]:
_found(server, "list")
# Pages are asked for one at a time, each only after the one before it came.
var next: int = int(page["page"]) + 1
if next < int(page["pages"]) and next < NetDiscovery.MAX_PAGES:
_socket.set_dest_address(from_ip, from_port)
_socket.put_packet(NetDiscovery.encode_query(next))
## The servers found, sorted: compatible first, then most people, then by name.
func sorted() -> Array[Dictionary]:
var result: Array[Dictionary] = []
for key: String in servers:
result.append(servers[key])
result.sort_custom(func(a: Dictionary, b: Dictionary) -> bool:
if a["compatible"] != b["compatible"]:
return bool(a["compatible"])
if a["players"] != b["players"]:
return int(a["players"]) > int(b["players"])
return String(a["name"]) < String(b["name"]))
return result
func _found(server: Dictionary, source: String) -> void:
var key: String = "%s:%d" % [server["address"], server["port"]]
# A LAN answer comes straight from the server, so it wins over a list's copy.
if servers.has(key) and servers[key]["source"] == "lan" and source == "list":
return
server["source"] = source
server["compatible"] = int(server["version"]) == NetProtocol.VERSION
servers[key] = server
+1
View File
@@ -0,0 +1 @@
uid://bkig85oib5la1
+44
View File
@@ -0,0 +1,44 @@
## Counts packets per sending address over fixed windows and says when one has sent
## too many. Used by everything that answers unauthenticated UDP (the LAN beacon and
## the list server) so a flood from one address is mostly ignored. Memory is bounded:
## once `max_sources` addresses have been seen in a window, new ones are refused
## until the next window.
class_name SourceLimiter
extends RefCounted
var per_window: int = 20
var window_msec: int = 1000
var max_sources: int = 4096
## Packets refused so far.
var refused: int = 0
var _window_start: int = -1
var _counts: Dictionary = {}
func _init(packets_per_window: int = 20, window: int = 1000, sources: int = 4096) -> void:
per_window = packets_per_window
window_msec = window
max_sources = sources
## True if a packet from `address` may be handled now. `now_msec` is for tests.
func allow(address: String, now_msec: int = -1) -> bool:
var now: int = now_msec if now_msec >= 0 else Time.get_ticks_msec()
if _window_start < 0 or now - _window_start >= window_msec:
_window_start = now
_counts.clear()
var count: int = int(_counts.get(address, 0))
if count == 0 and _counts.size() >= max_sources:
refused += 1
return false
if count >= per_window:
refused += 1
return false
_counts[address] = count + 1
return true
## Addresses being counted in the current window.
func tracked() -> int:
return _counts.size()
+1
View File
@@ -0,0 +1 @@
uid://c14fge33247u4