Documentation
¶
Overview ¶
Package meshnet holds the process-wide libp2p Host used to reach (and be reached by) honey backends flagged mesh: true, even when they sit behind NAT/CGNAT with no port-forward. It wraps a single go-libp2p Host behind a small, testable API: a self-hosted, generic (non-honey) libp2p relay node provides Circuit Relay v2 forwarding, and go-libp2p's built-in DCUtR subsystem upgrades that relayed connection to a direct, hole-punched one (typically over QUIC, a default go-libp2p transport) whenever possible.
Modeled on internal/devmtls: package-level state behind a mutex, exported lifecycle functions rather than a struct callers instantiate.
Index ¶
Constants ¶
const ProtocolID = "/honey/federation/1.0.0"
ProtocolID is the libp2p stream protocol this package's DialPeer/Listener use to carry honeyprovider's HTTP traffic over a libp2p Stream. Exported so a later task (internal/provider/honeyprovider) doesn't need to duplicate or guess this string.
Variables ¶
This section is empty.
Functions ¶
func DialPeer ¶
DialPeer resolves peerAddr (a multiaddr string, possibly including a relay circuit path like "/p2p/<relay-id>/p2p-circuit/p2p/<target-id>"), opens a stream to it using ProtocolID, and adapts the resulting network.Stream into a net.Conn.
func Enabled ¶
func Enabled() bool
Enabled reports whether Start was (first) called with cfg.Enabled true.
func Listener ¶
Listener returns a net.Listener whose Accept blocks on this Host's registered stream handler for ProtocolID, wrapping each accepted network.Stream with the same adapter DialPeer uses.
func Start ¶
Start is idempotent: the first call (across the process) does the real work under a lock; every later call — concurrent or sequential, regardless of the cfg passed — returns the exact result (error or nil) of that first attempt without re-initializing. Call Stop to genuinely reset the singleton.
It is a no-op (nil error, no host constructed) when cfg.Enabled is false, or when cfg.Enabled is true but cfg.PrivateKey or cfg.RelayAddrs is empty: config-layer validation upstream already prevents that combination from reaching here in the real app, but Start itself must not panic or attempt a real libp2p join with insufficient config.
func Stop ¶
Stop shuts down the mesh Host (if one is running) and resets the singleton so a subsequent Start genuinely re-initializes (calls newHost again) rather than replaying a stale result.
Stop does not wait for in-flight DialPeer/Listener callers to finish: a concurrent call may observe the host mid-close and fail with an error — the same contract as closing a net.Listener while Accept is blocked, or an http.Transport mid-request. That failure is expected shutdown behavior, not corruption, and callers that need a clean drain should quiesce traffic before calling Stop.
Types ¶
type Config ¶
type Config struct {
// Enabled turns the mesh subsystem on. When false, Start is a no-op.
Enabled bool
// PrivateKey is this Host's libp2p identity key, base64-encoded
// protobuf-serialized (the "for config file" format produced by
// go-libp2p's crypto.MarshalPrivateKey + crypto.ConfigEncodeKey, and
// consumed here the same way ipfs config files do: ConfigDecodeKey then
// crypto.UnmarshalPrivateKey — confirmed via `go doc` on
// github.com/libp2p/go-libp2p/core/crypto).
PrivateKey string
// RelayAddrs are multiaddrs of self-hosted, generic libp2p relay
// node(s), e.g. "/ip4/1.2.3.4/udp/4001/quic-v1/p2p/<relay-peer-id>".
// Parsed with multiaddr.NewMultiaddr and used both as AutoRelay's
// static relay candidates (so this Host can obtain a relay reservation
// and be dialable behind NAT) and as the initial relay connections
// established during Start.
RelayAddrs []string
// ListenMesh, when true, additionally runs the Circuit Relay v2 relay
// service on this Host (EnableRelayService), so this instance also acts
// as a relay for other peers. Only relevant if this instance is itself
// publicly reachable. Off by default.
ListenMesh bool
// ForceReachability overrides go-libp2p's AutoNAT reachability detection:
// "private" appends libp2p.ForceReachabilityPrivate() (this Host always
// treats itself as behind NAT, so AutoRelay reliably reserves a relay
// slot — needed when AutoNAT would otherwise conclude the Host is public
// and skip reserving, e.g. relay and Host on the same LAN); "public"
// appends ForceReachabilityPublic(); "" (default) leaves detection
// automatic. Any other value is ignored.
ForceReachability string
}
Config configures this process's own libp2p mesh identity. It is meshnet's own plain struct — the caller (internal/provider/honeyprovider) is responsible for translating config.Get().Mesh (internal/config's MeshConfig) into one of these; this package does not import internal/config.
type MeshStatus ¶
type MeshStatus struct {
PeerID string
Connected bool // is a relay connection (or better) actually up
Relays []string // connected relay multiaddrs, if any
}
MeshStatus is a small package-local diagnostics struct — deliberately not the raw go-libp2p host.Host, to keep this package's public surface independent of the underlying library's types. Named MeshStatus rather than Status (which the brief's sketch used for both the type and the accessor function below) because Go does not allow a function and a type to share a package-level name; the accessor keeps the name "Status" since that's the one referenced by call-site shape (Status().Connected) elsewhere in this package's design.
func Status ¶
func Status() (MeshStatus, error)
Status reports this Host's own peer ID and, best-effort, whether a relay connection is currently established and which relay(s).
Source Files