Rendezvous and relay reference

Category: rendezvous · Applies to: the nodera-rendezvous binary and the Java rendezvous transport.

One binary, two jobs that must stay logically separate:

• Rendezvous — peers register a signed record into a namespace and discover each other's records. Cheap metadata; scales like a tracker.
• Relay — when no direct path can be made to work, the service bridges two legs of a circuit. This is the expensive half: every byte is received and sent again, so relay bandwidth is the only genuinely scarce resource here and everything about it is metered.

It holds no authority and cannot read what it carries. Records are self-signed and re-verified by the discovering peer; the transport handshake re-proves identity on connect; circuit payloads are end-to-end encrypted. A lying relay can refuse to forward or hide records. It cannot forge one, and it cannot read a byte of what passes through it — it sees ciphertext, framing sizes, and the fact that two identities are talking.

For installing and running one, see SELF-HOSTING.md. This page is the contract.

Namespaces

A namespace is (networkId, genesisHash) — one world is one namespace. The Java side derives networkId from the world id, so a peer registering for a world is not visible to a query for any other world. Namespacing is what keeps a discovery query bounded: without it a peer asks "who is out there" and gets an answer sized by the network rather than by the session.

Verbs

Kinds are the frozen wire kinds of ../network/REFERENCE.md.

Server-originated kinds are refused inbound. A peer that sends RendezvousPeers, RelayReservation, RelayIncoming or ObservedAddress is dropped with a reason, which keeps the state machine one-directional.

Registration admission

1. Frame size — anything above max_frame_bytes is dropped as too-large before decoding.
2. Per-IP quota — per_ip_request_quota register and reserve requests per refresh interval.
3. Signature — Ed25519 over the record's own signed byte range, as received.
4. Freshness — the record's issuedAt must be within clock_skew_seconds, both directions.
5. Identity binding — trust-on-first-use, per service, exactly as the tracker does. A graceful departure releases the binding.
6. Quotas — max_records_per_namespace, then max_namespaces.

Registrations are leases, not state. The effective expiry is the sooner of registration_ttl_seconds and the record's own self-declared expiresAt, so a peer can ask to be forgotten early while the service still caps how long one registration keeps a record alive. Crashed peers disappear on their own; there is no cleanup protocol. Peers refresh at about half the advertised refresh_interval_seconds, which tolerates one lost refresh — the failure it prevents is invisible from the peer's side, because a peer whose lease lapsed still believes it is registered while nobody can discover it.

Relay reservations and circuits

A peer that expects inbound relayed connections reserves before it advertises a relay candidate. The reservation carries an expiry and the two ceilings, plus an HMAC proof over exactly those limits, computed under a key that never leaves the process. The service re-validates the proof immediately before it bridges, in constant time, so a mismatched-limits bug cannot silently widen a ceiling and a peer cannot forge one. No reservation, no circuit — which is what closes the open-relay hole. An open relay is an open proxy however carefully its byte ceilings are set.

A bridged circuit is metered per direction against the reservation and always torn down with a stable reason:

The idle timeout is not a nicety: without it, opening many circuits and sending nothing consumes reservation slots and connection state at no cost to the attacker. "The connection dropped" is unactionable; byte-limit is a capacity decision and idle-timeout is a keepalive bug.

Hole punching

Over an established circuit the two peers exchange observed addresses and agree a shared T-minus. The service only relays that exchange and stamps one go-signal, 500 ms out, shared by both directions — the first PunchSync with an unset signal fixes the value for that pair, and every later one for the same pair is stamped identically, so A and B receive the same instant whichever asked first. The pair key is unordered, because a punch is symmetric.

The service never dials. Failure is not an error: staying relayed is a legal steady state, so nothing in this lane can break a working circuit. A synchronisation window too tight for both peers to receive the signal before dialling is the usual cause of a punch that never succeeds anywhere.

Draining

SIGTERM starts a drain rather than a cut: the service stops accepting new work, tells the peers holding its control channels, tells its trackers, and waits up to drain_grace_seconds for live circuits to finish.

• A RelayReserve during a drain is answered with accepted = false and the reason draining — a refusal with a reason, not a closed socket. A peer that can read the reason re-reserves elsewhere immediately; a silent close reads as "retry here", which is the difference between a migration and a stall.
• A RelayConnect during a drain is refused for the same reason: a new circuit through a relay that is about to stop is a connection that breaks inside the grace period.
• The grace is bounded on purpose — an unbounded wait lets one stuck circuit hang a restart forever. A drain that times out still cuts, and making that cost a re-dial instead of the whole transfer needs resumable transfers, which do not exist yet.

update_channel therefore requires tracker_endpoints, and the service refuses to start without them: a relay that updates itself has to be able to tell peers where to go while it drains, and it learns about replacement relays from its trackers.

Settings

Every setting is a key in nodera-rendezvous.toml and an environment variable: NODERA_RENDEZVOUS_ plus the key, uppercased. Precedence is defaults → config file → environment → command line. An unrecognised NODERA_RENDEZVOUS_* variable refuses the start. Three names in that prefix belong to the Java peer rather than to this service — NODERA_RENDEZVOUS_ENDPOINTS, _FANOUT, _SWEEP_SECONDS — and are ignored rather than refused, so one shell can start both.

Refused at load: a zero refresh_interval_seconds; a registration_ttl_seconds below it, which guarantees every peer expires between its own refreshes; a zero discover_page_limit, max_records_per_namespace, max_namespaces or max_frame_bytes; a max_frame_bytes above the protocol cap; a zero reservation TTL, byte ceiling, duration ceiling or idle timeout; a reservation_hmac_key_hex that is not even-length hex; a zero drain_grace_seconds, because that makes every restart the hard cut this whole lane exists to remove; and, with update_channel set, a zero check interval, a non-https:// feed, or no tracker_endpoints.

Command line

nodera-rendezvous [--config <file>] [--bind <addr>] [--healthcheck <addr>] [--print-env] [--version]

--print-env lists every environment variable this build understands. --healthcheck speaks the real protocol against a running instance rather than merely opening a socket.

Metrics

Off unless telemetry_endpoint is set. Windowed counters and coarse classes only — never an address, a node id, a namespace, or a pair identity.

The NAT class is derived from one boolean per peer: does the address it advertises match the address its packets came from? Four classes and no finer — anything more specific would begin to characterise individual networks rather than the population. The number it exists to answer is "of attempts between two hard NATs, what fraction worked", which is what decides whether the relay lane can ever be retired.

Failure modes

What this service deliberately does not do

• No relay pooling. A peer reserves against its first configured endpoint only. Several rendezvous endpoints are used for discovery, but inbound relay capacity depends on one service, so if that endpoint is the unreachable one the peer has no relay path even with healthy alternatives configured. Tracked in LIMITATIONS.md.
• No decentralised rendezvous. Endpoints are configured or learned from a tracker's service directory; there is no DHT, no peer exchange and no local multicast discovery.
• No authority over identity. NodeId is random rather than derived from the key, so no service can check the binding cryptographically. Trust-on-first-use is a directory-level protection, not authentication — the transport handshake is what proves key possession, per connection.
• No visibility into payloads, and no hiding of metadata. Payload encryption is end to end, and no amount of it changes the fact that a relay knows it is relaying between two endpoints. Relay logs are simultaneously the investigative record and the largest privacy liability the deployment holds; short retention is the only thing that resolves that tension.