gatuna/PROTOCOL.md

gatuna wire protocol

All frames ride Ethernet with ethertype 0x6969. The ethertype is the sole discriminator; there is no magic number inside the payload.

Frame layout

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---------------+---------------+-------------------------------+
| version       | type          | session_id                    |
+---------------+---------------+-------------------------------+
| payload_len (big-endian)      | payload ...                   |
+-------------------------------+                               +
|                                                               |
+---------------------------------------------------------------+

• version (u8): protocol version. Currently 1.
• type (u8): frame type, see table below.
• session_id (u32, big-endian): 0 for non-session frames; the server-assigned ID for session-scoped frames.
• payload_len (u16, big-endian): number of payload bytes that follow. The receiver reads exactly this many bytes and ignores any trailing Ethernet padding (frames under 60 bytes are zero-padded by the NIC to meet the minimum Ethernet frame size).
• payload (payload_len bytes): type-dependent.

No CRC, no retransmit, no ordering at this layer. TCP reliability is handled by the endpoints' TCP stacks; UDP (reserved) will rely on application-level mechanisms.

Maximum payload: 1500 (Ethernet MTU) − 8 (our header) = 1492 bytes. In practice we cap at 1480 to stay conservative. Larger payloads are not emitted in v1.

Frame types

Type	Name	Direction	session_id	Payload
0x01	DISCOVER	C → broadcast	0	empty
0x02	MANIFEST	S → C	0	id:1, proto:1, port:2 × N
0x03	OPEN	C → S	0	upstream_id:1
0x04	OPEN_ACK	S → C	assigned	upstream_id:1
0x05	OPEN_NAK	S → C	0	upstream_id:1, reason:1
0x06	DATA	both	session	raw bytes (≤1480)
0x07	CLOSE	both	session	optional reason:1
0x0B	PING	C → S	0	nonce:8
0x0C	PONG	S → C	0	nonce:8 (echoed)

Reserved (unimplemented in v1; parse returns Err, encode unimplemented):

Type	Name
0x08	UDP_OPEN
0x09	UDP_DATA
0x0A	UDP_CLOSE

Payload field encodings

MANIFEST payload

A hostname prefix followed by variable-length entries, parsed sequentially until the payload is consumed.

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---------------+-----------------------------------------------+
| hostname_len  | hostname (UTF-8, hostname_len bytes) ...       |
+---------------+-----------------------------------------------+
| id            | proto         | port (big-endian)             |
+---------------+---------------+-------------------------------+
| label_len     | label (UTF-8, label_len bytes) ...           |
+---------------+-----------------------------------------------+
| ... repeated ...                                             |
+---------------------------------------------------------------+

• hostname_len (u8): length in bytes of the server's hostname. 0 is valid (unknown hostname).
• hostname (hostname_len bytes, UTF-8): the server's hostname, read via gethostname(2) at startup. Maximum 255 bytes.
• id (u8): upstream identifier (1-based positional index from gatunad cmdline).
• proto (u8): 1 = TCP, 2 = UDP (reserved; not emitted in v1).
• port (u16, big-endian): the real port on the server's 127.0.0.1.
• label_len (u8): length in bytes of the label that follows. 0 means no label.
• label (label_len bytes, UTF-8): human-readable name for the upstream, taken from the PORT[:label] cmdline argument. Maximum 255 bytes.

To parse: read hostname_len, then hostname_len bytes of hostname, then read 5-byte fixed entry prefixes + label_len bytes of label each, repeating until the payload is exhausted. The number of entries is not carried explicitly.

OPEN payload

+---------------+
| upstream_id   |
+---------------+

• upstream_id (u8): which MANIFEST entry to open.

OPEN_ACK payload

+---------------+
| upstream_id   |
+---------------+

• upstream_id (u8): echoes the requested upstream. The session is identified by the session_id field in the header, not the payload.

OPEN_NAK payload

+---------------+---------------+
| upstream_id   | reason        |
+---------------+---------------+

• upstream_id (u8): echoes the requested upstream.
• reason (u8): see reason codes.

DATA payload

Raw application bytes. Up to 1480 bytes per frame. The session_id header field identifies which session the bytes belong to.

CLOSE payload

+---------------+
| reason?       |
+---------------+

• reason (u8, optional): present iff payload length ≥ 1. See reason codes.

PING / PONG payload

+                                                               +
| nonce (big-endian, 8 bytes)                                   |
+                                                               +

• nonce (u64, big-endian): arbitrary value chosen by the client. The server echoes it verbatim in the PONG reply. Used to correlate RTT measurements.

Reason codes

Value	Meaning
0	unspecified
1	unknown_upstream
2	connect_failed
3	oversize
4	unknown_session

Discovery flow

client                            server
  |                                 |
  | DISCOVER (dst = broadcast)      |
  |-------------------------------->|
  |                                 |
  |        MANIFEST (unicast)       |
  |<--------------------------------|
  |                                 |

The server learns the client's MAC from the DISCOVER frame's source address and unicasts the MANIFEST back. The server never speaks unsolicited.

TCP session lifecycle

client                            server
  |                                 |
  | OPEN { upstream_id }            |
  |-------------------------------->|
  |                                 | TcpStream::connect(127.0.0.1:port)
  |                                 |
  |   OPEN_ACK { session_id }       |
  |<--------------------------------|   (on success)
  |        OR                       |
  |   OPEN_NAK { reason }           |
  |<--------------------------------|   (on failure)
  |                                 |
  | DATA { session_id, bytes }      |
  |<------------------------------->| DATA { session_id, bytes }
  |                                 |
  | CLOSE { session_id, reason? }   |
  |<------------------------------->|   (on EOF, RST, or error)
  |                                 |

• session_id is allocated by the server as a monotonically increasing u32 (starting at 1) from an atomic counter. Collision by wraparound is ignored.
• Either side may send CLOSE. The side receiving CLOSE tears down its half and stops emitting frames for that session.
• The server's socket→tunnel pump reads TcpStream in 1480-byte chunks and emits one DATA frame per chunk. On read returning 0 (FIN) or an error, it emits CLOSE and exits.
• The server's tunnel→socket path writes DATA payloads to the TcpStream with write_all. On error it emits CLOSE and drops the session.