relay.v1¶

The relay daemon's API to nexus. Source: platform/nexus/proto/relay/v1/relay.proto. Served by nexus (internal/relayconnect). The relay itself lives in edge/relay.

Services¶

Service	Auth
`RelayEnrollmentService`	none; the bootstrap token in the request is the credential
`RelayService`	`Authorization: Bearer <relay api_token>` (`RelayTokenInterceptor`)

RelayEnrollmentService¶

RPC	Purpose
`Enroll`	Spend a bootstrap token (written into cloud-init by terraform and registered beforehand through `GatewayInternalService.RegisterRelayToken`) for a durable `{relay_id, api_token}`. Carries `RelayInfo`: hostname, public IPv4/IPv6, region, version, WireGuard public key and port. A spent token is refused.

RelayService¶

RPC	Purpose
`Heartbeat`	Report load (`forward_sessions`, `rendezvous_sessions`, load average, free memory), `draining`, and `tunnel_url` (empty when the relay offers no rung 3). The response carries the whole route table (`PublishedRoute`: public hostname → gateway `host:port` inside the tunnel), the whole WireGuard peer set (`TunnelPeer`: gateway id, public key, tunnel address, per-peer tunnel token) and `should_drain`. The relay reconciles against both sets and removes anything absent, so a revocation reaches the data plane on the next beat.
`ReportAttach`	A gateway's session arrived on this relay; nexus records the session and writes the gateway's DNS name. Returns that name.
`ReportDetach`	A gateway's session left. Ignored unless the gateway is still recorded on this relay.
`RequestCertificate`	CSR for the relay's own tunnel name (`tunnel.<relay-id>.<zone>`); returns the chain, the names, and `renew_after`.

relayd (edge/relay) has client methods for ReportAttach and ReportDetach but does not call them. Assignment and the gateway's DNS record are written when nexus answers the gateway's RequestRelay.

Semantics worth knowing¶

Freshness. A relay that has not heartbeated within 90 s (relay.StaleAfter) is not handed out, whatever its healthy flag says.
Draining is sticky. A heartbeat can set draining but never clear it; only PortalGatewayService.SetRelayDraining clears it. See Relay fleet.
Tunnel tokens. A relay learns only the tunnel tokens of gateways already assigned to it and verifies rung-3 connections by comparison; it holds no minting key.