KyuubiYoru
54 lines
2.5 KiB
Markdown
54 lines
2.5 KiB
Markdown
# 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.
|