mesh

Documentation

Overview

Package mesh is the outpost's libp2p peer data plane — the node that carries authenticated, encrypted, NAT-traversing peer↔peer streams.

It is the transport under shard-RPC (a loopback rpc-server forwarded over the mesh), peer-backup, and the broader resource fabric. cloudbox is the rendezvous/signaler; data goes peer-to-peer direct (hole-punched via DCUtR), with relay only as fallback. See docs/libp2p-mesh-transport.md.

Index

• Constants
• func LoadOrCreateKey() (crypto.PrivKey, error)
• type Config
• type ForwardListener
• type ForwardSnapshot
• type Forwarder
  • func (f *Forwarder) CloseListen(addr string) error
  • func (f *Forwarder) Expose(name, loopbackAddr string)
  • func (f *Forwarder) Listen(localAddr, peerID, service string) (net.Listener, error)
  • func (f *Forwarder) Snapshot() ForwardSnapshot
  • func (f *Forwarder) Unexpose(name string)
• type Host
  • func New(cfg Config) (*Host, error)
  • func (m *Host) Close() error
  • func (m *Host) Connected(peerID string) bool
  • func (m *Host) Forwarder() *Forwarder
  • func (m *Host) HasDirectConn(peerID string) bool
  • func (m *Host) LibP2PHost() host.Host
  • func (m *Host) PeerID() string
  • func (m *Host) PeerLinkClass(peerID string) string
  • func (m *Host) PeerLinkInfo(peerID string) LinkInfo
  • func (m *Host) Run(ctx context.Context) error
  • func (m *Host) Status() Status
• type LinkInfo
• type PeerConn
• type Rendezvous
  • func NewRendezvous(host *Host, agentName, cloudboxURL, accessToken string, log *slog.Logger) *Rendezvous
  • func (r *Rendezvous) LinkClassForHost(host string) string
  • func (r *Rendezvous) LinkInfoForHost(host string) LinkInfo
  • func (r *Rendezvous) PeerIDForHost(host string) string
  • func (r *Rendezvous) Run(ctx context.Context) error
• type Status

Constants

const ForwardProtocol = "/dhnt/mesh/forward/1.0.0"

ForwardProtocol is the libp2p stream protocol for the generic loopback-TCP forwarder. A client opens a stream, writes the target service name, and the remote host bridges the stream to that service's local loopback address.

Functions

func LoadOrCreateKey

func LoadOrCreateKey() (crypto.PrivKey, error)

LoadOrCreateKey returns outpost's persistent libp2p mesh identity. The first call generates an ed25519 keypair and writes the libp2p-marshalled private key to <ConfigDir>/mesh_ed25519 (mode 0600); later calls read it back.

Like the SSH host key, it lives in its own file (not agent.json) so that re-pairing — which rewrites agent.json — does NOT change the peer ID. A stable peer ID is what lets cloudbox keep routing rendezvous to this host.

Types

type Config

type Config struct {
	// AgentName is this outpost's name, surfaced in the libp2p user-agent.
	AgentName string
	// ListenPort is the TCP+QUIC listen port; 0 = an ephemeral port per
	// transport. A stable port helps NAT/hole-punch and the loopback
	// forwarder added by later sprint-#8 items.
	ListenPort int
	// PrivKey, when non-nil, is used as the host identity instead of the
	// persistent on-disk key. Tests pass an ephemeral key; production
	// leaves it nil so LoadOrCreateKey owns the stable peer ID.
	PrivKey crypto.PrivKey
	// RelayAddrs are circuit-relay v2 relay multiaddrs (cloudbox's relay,
	// each ending in /p2p/<relay-id>). When set, the host runs AutoRelay
	// against them — it reserves a slot, advertises a relayed address, and
	// DCUtR upgrades the relayed link to a direct hole-punched one. This is
	// what lets two strict-NAT peers connect when neither is directly
	// reachable (same-LAN/same-vicinity needs no relay).
	RelayAddrs []string
	Logger     *slog.Logger
	// DisableMDNS turns off local-LAN mDNS peer discovery. Production leaves it
	// false (mDNS on — same-LAN peers connect directly). Tests set it true so
	// real multicast can't discover sibling test hosts (or real outposts on the
	// LAN) and perturb exact connected-peer-count assertions.
	DisableMDNS bool
}

Config configures the mesh host.

type ForwardListener

type ForwardListener struct {
	Addr    string `json:"addr"`
	PeerID  string `json:"peer_id"`
	Service string `json:"service"`
}

ForwardListener describes one active forward listener.

type ForwardSnapshot

type ForwardSnapshot struct {
	Exposed   map[string]string `json:"exposed"`   // service → loopback addr
	Listeners []ForwardListener `json:"listeners"` // active forward listeners
}

ForwardSnapshot is the live state of this host's forwarder.

type Forwarder

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

Forwarder carries a local loopback TCP service over the mesh — the transport the rest of the fabric rides on. Two halves:

• EXPOSER (worker): registers allowlisted local services; a stream handler bridges each inbound stream to the named service's loopback address.
• DIALER (client/leader): opens a local TCP listener that bridges every accepted connection over a fresh mesh stream to a (peer, service).

This is the transport under shard-RPC (a loopback rpc-server Expose()d here, the leader's llama-server pointed at a local Listen() address) and peer-backup. Only allowlisted services are reachable — a connected peer can never dial an arbitrary local port, which is what makes exposing a loopback service over the mesh safe.

func (*Forwarder) CloseListen

func (f *Forwarder) CloseListen(addr string) error

CloseListen closes the forward listener bound at addr.

func (*Forwarder) Expose

func (f *Forwarder) Expose(name, loopbackAddr string)

Expose registers a local loopback service reachable over the mesh under name (e.g. Expose("rpc", "127.0.0.1:50052")). Only exposed services are reachable; re-exposing a name replaces its address.

func (*Forwarder) Listen

func (f *Forwarder) Listen(localAddr, peerID, service string) (net.Listener, error)

Listen opens a local TCP listener; every accepted connection is bridged over a fresh mesh stream to (peerID, service) on the remote host. Close the returned listener to stop forwarding. localAddr "" → 127.0.0.1:0 (ephemeral).

func (*Forwarder) Snapshot

func (f *Forwarder) Snapshot() ForwardSnapshot

Snapshot returns the forwarder's exposed services + active listeners.

func (*Forwarder) Unexpose

func (f *Forwarder) Unexpose(name string)

Unexpose removes a service from the allowlist.

type Host

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

Host is the outpost's libp2p peer — the data-plane node of the mesh. It is constructed with TCP+QUIC transports, Noise/TLS security, yamux, AutoNAT, and DCUtR hole-punching, so it can form direct peer↔peer links across NATs and different subnets once a rendezvous (cloudbox) supplies peer addresses.

func New

func New(cfg Config) (*Host, error)

New builds the libp2p host with the persistent (or supplied) mesh identity.

func (*Host) Close

func (m *Host) Close() error

Close shuts the host down (for callers not using Run, e.g. tests).

func (*Host) Connected

func (m *Host) Connected(peerID string) bool

Connected reports whether there is any connection (direct or relayed) to peer.

func (*Host) Forwarder

func (m *Host) Forwarder() *Forwarder

Forwarder is the loopback-TCP-over-mesh transport bound to this host (the stream handler is registered at construction). Expose local services on the worker side; Listen for a (peer, service) on the client side.

func (*Host) HasDirectConn

func (m *Host) HasDirectConn(peerID string) bool

HasDirectConn reports whether there is a DIRECT (non-relayed) connection to the peer — the mesh-native "local / same-vicinity" signal: a relayed connection (network.Limited) means the peer is reachable only over the WAN relay, i.e. remote. The mobility-aware mirror's lan_only gate uses this to mirror only while the pair is genuinely local (and pause when it falls back to relay).

func (*Host) LibP2PHost

func (m *Host) LibP2PHost() host.Host

LibP2PHost exposes the underlying libp2p host for protocol handlers added by later sprint-#8 items.

func (*Host) PeerID

func (m *Host) PeerID() string

PeerID returns this host's stable libp2p peer ID (string form).

func (*Host) PeerLinkClass

func (m *Host) PeerLinkClass(peerID string) string

PeerLinkClass classifies a DIRECT (non-relayed) connection to the peer by its remote address — the ground truth for same-locality that the peerplane's UDP probes miss (they can't dial a zone-less link-local address, and a firewalled LAN drops the echo, so genuinely-local peers come back "unreached"):

"tp"  — link-local / APIPA (169.254.x, fe80:) : a dedicated point-to-point wired link
"lan" — RFC-1918 / ULA private address          : same LAN (incl. wifi)
"wan" — public address                          : remote
""    — no direct connection (relayed or absent)

It returns the strongest class across all direct connections to the peer. Kept for back-compat; implemented via PeerLinkInfo.

func (*Host) PeerLinkInfo

func (m *Host) PeerLinkInfo(peerID string) LinkInfo

PeerLinkInfo returns the strongest direct-link class to the peer AND the LAN label of the local interface that strongest link uses. It walks every direct (non-relayed) connection, keeps the one whose REMOTE-addr class wins (tp>lan>wan), and derives LinkInfo.LAN from THAT connection's LOCAL multiaddr — because the class alone collapses all private LANs into "lan", but the local subnet/interface identifies which one (Wi-Fi vs. a wired crosslink vs. a second LAN).

func (*Host) Run

func (m *Host) Run(ctx context.Context) error

Run logs the host identity + listen addresses and blocks until ctx is cancelled, then closes the host. It is the errgroup entry point.

func (*Host) Status

func (m *Host) Status() Status

Status returns a live snapshot of the mesh host.

type LinkInfo

type LinkInfo struct {
	Class string // strongest direct-link class: tp>lan>wan; "" if relayed/none
	LAN   string // local LAN label of the winning conn (see localLANLabel); "" if none
}

LinkInfo is the per-peer direct-link summary the peer-status overlay needs: the strongest direct link Class (tp/lan/wan; "" when relayed/absent) PLUS a LAN label naming WHICH local LAN that strongest link rides over. The class collapses every private network into "lan", so a node on Wi-Fi *and* a wired crosslink can't tell its peers apart by class alone — the LAN label (derived from the winning connection's LOCAL multiaddr) is what disambiguates them.

type PeerConn

type PeerConn struct {
	ID        string   `json:"id"`         // peer id (string form)
	Direct    bool     `json:"direct"`     // at least one non-relayed connection
	LinkClass string   `json:"link_class"` // strongest of its direct conns: tp>lan>wan; "" if relayed/none
	Remote    []string `json:"remote"`     // remote multiaddr string(s)
}

PeerConn is the per-connected-peer link detail for the local mesh-status debug surface: which remote address(es) the peer is reached over and the strongest link class across its direct connections. This is a LOCAL loopback/admin view (the owner inspecting their own daemon) — raw remote addrs are fine here and deliberately NOT surfaced by the cross-account peer-status API.

type Rendezvous

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

Rendezvous wires the mesh Host to cloudbox's peer-signal surface — the SOLE rendezvous for the fabric (no third-party discovery; every outpost already holds a tunnel to cloudbox). Each tick it announces this host's peer id + dialable multiaddrs, discovers the paired-host list, and dials each peer. libp2p upgrades the link to a direct hole-punched one (DCUtR) where possible; cloudbox only brokers the introduction — the bytes then go peer-to-peer. See docs/libp2p-mesh-transport.md.

func NewRendezvous

func NewRendezvous(host *Host, agentName, cloudboxURL, accessToken string, log *slog.Logger) *Rendezvous

NewRendezvous builds the rendezvous client for a mesh host. cloudboxURL + accessToken are the paired outpost's existing cloudbox credentials (the same the peerplane + registry push use).

func (*Rendezvous) LinkClassForHost

func (r *Rendezvous) LinkClassForHost(host string) string

LinkClassForHost returns the mesh link class ("tp"/"lan"/"wan"/"") of the DIRECT connection to the named paired host. Back-compat shim over LinkInfoForHost (which also carries the LAN label).

func (*Rendezvous) LinkInfoForHost

func (r *Rendezvous) LinkInfoForHost(host string) LinkInfo

LinkInfoForHost returns the mesh link class AND the LAN label (which local LAN the direct link rides over) for the named paired host, or a zero LinkInfo when the host's peer id isn't known yet or there's no direct link. The class+label are computed live from the current connection state — the host→peer-id map is only the lookup key. This is the accurate same-LAN signal (enriched with WHICH lan) that peer-status overlays on cloudbox's egress-IP heuristic.

func (*Rendezvous) PeerIDForHost

func (r *Rendezvous) PeerIDForHost(host string) string

PeerIDForHost returns the libp2p peer id learned for host during rendezvous, or "" if none is known yet. This is the reliable host→peer-id source — the id the mesh actually connected with — independent of a per-call cloudbox peer/connect round-trip (which can momentarily return an empty id on a stale announce).

func (*Rendezvous) Run

func (r *Rendezvous) Run(ctx context.Context) error

Run announces + discovers on a timer until ctx is cancelled.

type Status

type Status struct {
	PeerID         string     `json:"peer_id"`
	ListenAddrs    []string   `json:"listen_addrs"`
	ConnectedPeers int        `json:"connected_peers"`
	Peers          []PeerConn `json:"peers,omitempty"`
}

Status is a snapshot for admincore / status surfaces.