peerplane

Documentation

Overview

Package peerplane is the outpost side of the dhnt p2p resource fabric's peer data plane. cloudbox is the sole rendezvous (no third-party discovery); this package announces the host's interface candidates to cloudbox, runs a probe responder, and measures RTT to peers to classify each link into a sharding tier — the "measure, don't guess" locality signal that finds the dedicated- LAN/hub path the egress-IP heuristic and single-interface mDNS miss.

See docs/p2p-resource-fabric-design.md (umbrella).

Index

• func LocalCandidates(port int) []string
• func ProbeAll(cands []string, k int, fn func(string, int) Result) (results []Result, best *Result)
• type Client
  • func (c *Client) Announce(ctx context.Context, host, peerID string, candidates, services []string) error
  • func (c *Client) Connect(ctx context.Context, fromHost, toHost string) (*PeerTarget, error)
  • func (c *Client) Inbox(ctx context.Context, host string) ([]Rendezvous, error)
  • func (c *Client) Relays(ctx context.Context) ([]string, error)
  • func (c *Client) Resolve(ctx context.Context, service string) ([]MeshPeer, error)
• type Config
• type EchoResponder
  • func NewEchoResponder(port int) (*EchoResponder, error)
  • func (r *EchoResponder) Close() error
  • func (r *EchoResponder) Port() int
  • func (r *EchoResponder) Run(ctx context.Context)
• type MeshPeer
• type PeerTarget
• type PeerTier
• type Rendezvous
• type Result
  • func ProbeCandidate(addr string, k int) Result
  • func ProbeTCP(addr string, k int) Result
• type Service
  • func New(cfg Config) *Service
  • func (s *Service) Run(ctx context.Context) error
  • func (s *Service) SelfTier() Tier
  • func (s *Service) Snapshot() []PeerTier
• type Tier
  • func BestTier(snap []PeerTier) Tier
  • func Classify(rttMS float64) Tier

Functions

func LocalCandidates

func LocalCandidates(port int) []string

LocalCandidates returns this host's non-loopback IPv4 addresses as "ip:port" — EVERY interface (wifi, ethernet hub, link-local). Announcing all of them is the point: a peer can then find the best path (e.g. a direct hub link-local) that no single-interface view would surface.

func ProbeAll

func ProbeAll(cands []string, k int, fn func(string, int) Result) (results []Result, best *Result)

ProbeAll measures every candidate concurrently with fn and returns the results plus the best (lowest-RTT reachable) one (nil if none reachable).

Types

type Client

type Client struct {
	BaseURL string
	Token   string
	HC      *http.Client
}

Client speaks cloudbox's peer-plane signaling API (/api/v1/peer/*), the SOLE rendezvous for the fabric. Bearer-authed with the outpost access token (peer:signal scope).

func (*Client) Announce

func (c *Client) Announce(ctx context.Context, host, peerID string, candidates, services []string) error

Announce publishes this host's reachability candidates. services is the mesh wrap-harness service list: nil omits the field (cloudbox preserves the stored value — what the RTT prober passes), non-nil (even empty) sets it (the mesh announcer passes its current exposed-service names).

func (*Client) Connect

func (c *Client) Connect(ctx context.Context, fromHost, toHost string) (*PeerTarget, error)

Connect requests a rendezvous from fromHost to toHost. Returns the peer's candidates and enqueues a notice for the peer to reciprocate.

func (*Client) Inbox

func (c *Client) Inbox(ctx context.Context, host string) ([]Rendezvous, error)

Inbox returns + drains the pending rendezvous notices addressed to host.

func (*Client) Relays

func (c *Client) Relays(ctx context.Context) ([]string, error)

Relays fetches cloudbox's circuit-relay advertised multiaddrs (for AutoRelay / strict-NAT DCUtR). Empty when the relay isn't configured cloudbox-side.

func (*Client) Resolve

func (c *Client) Resolve(ctx context.Context, service string) ([]MeshPeer, error)

Resolve returns the caller's peers exposing the named mesh service (the service registry — "who runs <service>"). Empty service ⇒ all announced peers.

type Config

type Config struct {
	AgentName   string // this host's name (self)
	CloudboxURL string
	AccessToken string
	HTTPClient  *http.Client
	Interval    time.Duration // probe cadence; 0 → default 60s
	Logger      *slog.Logger
}

Config wires the peer-plane service to cloudbox.

type EchoResponder

type EchoResponder struct {
	// contains filtered or unexported fields
}

EchoResponder is a UDP server that replies "pong" to any "ping" datagram, so peers can measure RTT to this host on whatever interface they can reach. It binds 0.0.0.0:port (port 0 ⇒ ephemeral); Port() returns the chosen port, which is what the host announces in its candidates.

func NewEchoResponder

func NewEchoResponder(port int) (*EchoResponder, error)

NewEchoResponder binds the responder. port 0 picks an ephemeral port.

func (*EchoResponder) Close

func (r *EchoResponder) Close() error

Close stops the responder.

func (*EchoResponder) Port

func (r *EchoResponder) Port() int

Port is the bound UDP port — announce candidates with this port.

func (*EchoResponder) Run

func (r *EchoResponder) Run(ctx context.Context)

Run serves until ctx is cancelled (or the socket closes).

type MeshPeer

type MeshPeer struct {
	Host     string   `json:"host"`
	PeerID   string   `json:"peer_id"`
	Services []string `json:"services"`
}

MeshPeer is one peer exposing a mesh service (from the service registry).

type PeerTarget

type PeerTarget struct {
	Peer struct {
		Host       string   `json:"host"`
		Owner      string   `json:"owner"`
		PeerID     string   `json:"peer_id"`
		Candidates []string `json:"candidates"`
		ExternalIP string   `json:"external_ip"`
	} `json:"peer"`
	SameLAN bool `json:"same_lan"`
}

PeerTarget is the Connect response: the peer's candidates + observed external IP, plus the egress-IP same_lan hint (a guess; the probe is ground truth).

type PeerTier

type PeerTier struct {
	Host        string    `json:"host"`
	Tier        Tier      `json:"tier"`
	RTT         float64   `json:"rtt_ms"`
	Addr        string    `json:"addr"`
	SameLANHint bool      `json:"egress_same_lan_hint"`
	At          time.Time `json:"at"`
}

PeerTier is the latest measured locality of a peer link. Tier is GROUND TRUTH (measured RTT); SameLANHint is cloudbox's egress-IP guess, kept only so operators can see where the heuristic disagrees with the measurement.

type Rendezvous

type Rendezvous struct {
	FromHost       string   `json:"from_host"`
	FromOwner      string   `json:"from_owner"`
	FromPeerID     string   `json:"from_peer_id"`
	FromCandidates []string `json:"from_candidates"`
}

Rendezvous is one pending inbound connect notice.

type Result

type Result struct {
	Addr      string  `json:"addr"`
	RTT       float64 `json:"rtt_ms"` // valid only when Reachable
	Reachable bool    `json:"reachable"`
	Tier      Tier    `json:"tier"`
}

Result is one candidate's measurement.

func ProbeCandidate

func ProbeCandidate(addr string, k int) Result

ProbeCandidate measures the min RTT (ms) to a candidate by k UDP ping/pong round-trips against a peer's EchoResponder. Direct-dials its own socket, so it's independent of any receive loop. Unreachable (no reply within the per-ping deadline) ⇒ Reachable=false — the relay/WAN case for a NAT'd peer.

func ProbeTCP

func ProbeTCP(addr string, k int) Result

ProbeTCP measures RTT to addr by timing a TCP connect (k attempts, min RTT). Needs NO peer cooperation — it works against any host with an open port (e.g. ssh :22), so it can tier the fleet against existing services.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service announces this host's candidates to cloudbox, runs a probe responder, and periodically measures + tiers every reachable peer.

func New

func New(cfg Config) *Service

New builds the service.

func (*Service) Run

func (s *Service) Run(ctx context.Context) error

Run starts the responder + the announce/probe loop until ctx is done. No-op (returns nil) when unpaired.

func (*Service) SelfTier

func (s *Service) SelfTier() Tier

SelfTier returns the host's effective locality tier from the latest measured snapshot — a convenience wrapper over BestTier(s.Snapshot()). Use this to stamp the host's own Node with its measured (not guessed) locality. Returns TierUnreached until the first probe cycle records a reachable peer.

func (*Service) Snapshot

func (s *Service) Snapshot() []PeerTier

Snapshot returns the latest measured tiers, host-sorted. Surfaced via status / MCP so operators see ground-truth locality vs. the egress hint.

type Tier

type Tier string

Tier is the measured locality class of a peer link.

const (
	TierTP        Tier = "tp"        // tensor-parallel eligible (sub-2ms, dedicated/wired)
	TierLAN       Tier = "lan"       // pipeline-parallel (LAN/wifi)
	TierWAN       Tier = "wan"       // pipeline / relay only
	TierUnreached Tier = "unreached" // no direct path — relay required
)

func BestTier

func BestTier(snap []PeerTier) Tier

BestTier reduces a measured peer snapshot to this host's effective locality tier: the lowest-latency class observed to ANY reachable peer. The rationale is "best-link wins" — a host with at least one sub-2ms (tp) peer link is itself tensor-parallel eligible; one whose peers are all LAN is lan; and so on. An empty snapshot (single machine, or no probe cycle has completed yet) returns TierUnreached, and the caller decides whether to render or omit a "no peers" tier.

func Classify

func Classify(rttMS float64) Tier

Classify maps a measured RTT (ms) to a sharding tier.