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
- type Host
- 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) Run(ctx context.Context) error
- func (m *Host) Status() Status
- type Rendezvous
- 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.
Variables ¶
This section is empty.
Functions ¶
func LoadOrCreateKey ¶
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
}
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 ¶
CloseListen closes the forward listener bound at addr.
func (*Forwarder) Expose ¶
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 ¶
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.
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 (*Host) Connected ¶
Connected reports whether there is any connection (direct or relayed) to peer.
func (*Host) 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 ¶
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 ¶
LibP2PHost exposes the underlying libp2p host for protocol handlers added by later sprint-#8 items.
func (*Host) PeerLinkClass ¶ added in v0.12.3
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 wired link (TP-Link hub) "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.
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 ¶ added in v0.12.21
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, or "" when the host's peer id isn't known yet (no rendezvous tick has resolved it) or there's no direct link. The class is computed live from the current connection state — the host→peer-id map is only the lookup key. This is the accurate same-LAN signal peer-status overlays on cloudbox's egress-IP heuristic.
Source Files