Module hello 

Hello envelope — Layer 5 identity handshake (RFC 017 §8).

When two truffle nodes establish a WebSocket link, each side sends a HelloEnvelope as the very first message over the socket and expects one back before any application traffic flows. The envelope advertises the sender’s app_id, stable device_id, human-readable device_name, operating system, and (as an escape hatch) its Tailscale stable ID.

Version

HelloEnvelope::version starts at 2. Version 1 is implicit in pre-RFC-017 code and is explicitly rejected — RFC 017 is a clean break and older peers cannot talk to newer ones.

Deviation from RFC §8

RFC 017 §8 lists four fields inside the identity block: app_id, device_id, device_name, os. This implementation adds a fifth field, tailscale_id, because the session layer still routes WebSocket connections by Tailscale stable ID (the primary key of the session’s peer map). Carrying the remote’s Tailscale ID in the hello lets the session correlate the freshly-accepted WS link with the Layer 3 peer entry that already exists. A future phase can remove this field once the session layer re-keys its connection map by device_id.

Structs

HelloEnvelope

Identity block sent once in each direction when a WebSocket link comes up (RFC 017 §8). Version 2 is the first with a structured identity field; version 1 is implicit in pre-RFC-017 code.

PeerIdentity

Peer identity metadata advertised by a truffle node in its hello envelope.

Enums

HelloKind

Tag identifying a HelloEnvelope on the wire.

Constants

CLOSE_APP_MISMATCH

Remote peer’s app_id did not match ours. The link is closed immediately with this code so the remote sees a specific reason.

CLOSE_HELLO_PROTOCOL

Remote peer sent a malformed hello envelope, or no hello at all within the timeout.

CLOSE_IDENTITY_MISMATCH

The hello envelope claimed a tailscale_id that does not match the Tailscale-authenticated identity (WhoIs) of the underlying connection.

HELLO_TIMEOUT

Timeout applied to the first hello envelope read.