KyuubiYoru
2.5 KiB
UDP presence contract v1
Tracking: #4
The UDP mediator accepts a single bounded presence envelope from a host or client. It associates the authenticated mediation handle with the packet's observed public source endpoint and the sender's reported local endpoint. It does not carry gameplay packets.
All multi-byte integers use network byte order. UUID bytes use the canonical
RFC 4122 textual order (the byte pairs from the 32 hexadecimal digits), not the
mixed-endian layout returned by Guid.ToByteArray().
Datagram layout
| Offset | Size | Field |
|---|---|---|
| 0 | 2 | Magic bytes 52 56 (RV). |
| 2 | 1 | Contract version, exactly 01. |
| 3 | 1 | Message type: host presence 01, client presence 02. |
| 4 | 1 | Flags, exactly 00 in v1. |
| 5 | 16 | Non-empty mediation-handle UUID. |
| 21 | 1 | Address family: IPv4 04, IPv6 06. |
| 22 | 1 | Address length: 04 for IPv4, 10 for IPv6. |
| 23 | 4 or 16 | Raw local IP address bytes. |
| next | 2 | Local UDP port, 1–65535. |
| next | 1 | Capability length, 1–192. |
| next | variable | ASCII base64url capability, without padding. |
No trailing bytes are permitted. The whole datagram is limited to 1,200 bytes, well below common Internet path MTUs. The v1 capability limit is 192 characters, which also keeps any value passed through LiteNetLib's 256-character NAT token surface safely below that library boundary.
Validation and failure behavior
Decoders return one stable failure category: oversized, truncated, invalid magic, unsupported version, unknown message type, non-zero flags, invalid handle, invalid address family, invalid address, invalid port, invalid capability, or trailing data. Unknown versions and message types are rejected; they are never interpreted as v1.
The address-family byte, encoded address length, and parsed address must agree. The service derives the public endpoint from the UDP packet source and never trusts a client-supplied public address. Reported local endpoints are candidates only and grant no authority.
Capabilities are short-lived, single-purpose, scoped to one mediation handle, and compared without exposing them in logs. A valid-looking packet does not prove authorization until the capability is checked. Invalid packets receive no UDP response, preventing the mediator from becoming an amplification oracle. Replay, expiry, pairing, and rate-limit policy are defined by later mediator issues; the v1 envelope deliberately leaves no unbounded or reflected payload.