meshnode

Documentation

Overview

Package meshnode contains the mesh node and related interfaces.

Index

• Variables
• type BootstrapOptions
  • func (b BootstrapOptions) MarshalJSON() ([]byte, error)
• type Config
• type ConnectOptions
  • func (c ConnectOptions) MarshalJSON() ([]byte, error)
• type MockAnnouncer
  • func (m *MockAnnouncer) AnnounceToDHT(ctx context.Context, opts libp2p.AnnounceOptions) error
  • func (m *MockAnnouncer) LeaveDHT(ctx context.Context, rendezvous string) error
• type Node
  • func New(opts Config) Node
  • func NewSingleNodeTestMesh(ctx context.Context) (Node, error)
  • func NewTestNode(opts Config) Node
  • func NewTestNodeWithLogger(log *slog.Logger, opts Config) Node
  • func NewWithLogger(log *slog.Logger, opts Config) Node
• type TestNode
  • func (t *TestNode) Close(ctx context.Context) error
  • func (t *TestNode) Connect(ctx context.Context, opts ConnectOptions) error
  • func (t *TestNode) Credentials() []grpc.DialOption
  • func (t *TestNode) Dial(ctx context.Context, network, address string) (net.Conn, error)
  • func (t *TestNode) Discovery() libp2p.Announcer
  • func (t *TestNode) Domain() string
  • func (t *TestNode) ID() types.NodeID
  • func (t *TestNode) Key() crypto.PrivateKey
  • func (t *TestNode) LeaderID() (types.NodeID, error)
  • func (t *TestNode) Network() meshnet.Manager
  • func (t *TestNode) Plugins() plugins.Manager
  • func (t *TestNode) Ready() <-chan struct{}
  • func (t *TestNode) Started() bool
  • func (t *TestNode) Storage() storage.Provider

Variables

var (
	// ErrNotOpen is returned when attempting to close a store that is not open.
	ErrNotOpen = fmt.Errorf("not open")
	// ErrOpen is returned when a store is already open.
	ErrOpen = fmt.Errorf("already open")
	// ErrNoLeader is returned when there is no Raft leader.
	ErrNoLeader = fmt.Errorf("no leader")
)

Types

type BootstrapOptions

type BootstrapOptions struct {
	// Transport is the transport to use for bootstrapping the mesh.
	Transport transport.BootstrapTransport
	// IPv4Network is the IPv4 Network to use for the mesh. Defaults to
	// DefaultIPv4Network.
	IPv4Network string
	// MeshDomain is the domain of the mesh network. Defaults to
	// DefaultMeshDomain.
	MeshDomain string
	// Admin is the ID of the administrator node. Defaults to "admin".
	Admin string
	// Servers are other node IDs that were bootstrapped with the same
	// transport.
	Servers []string
	// Voters are additional node IDs to assign voter permissions to.
	Voters []string
	// DisableRBAC disables RBAC for the mesh.
	DisableRBAC bool
	// DefaultNetworkPolicy is the default network policy for the mesh.
	// If empty, DefaultNetworkPolicy will be used.
	DefaultNetworkPolicy string
	// Force is true if the node should force bootstrap.
	Force bool
}

BootstrapOptions are options for bootstrapping the mesh when connecting for the first time.

func (BootstrapOptions) MarshalJSON

func (b BootstrapOptions) MarshalJSON() ([]byte, error)

type Config

type Config struct {
	// NodeID is the node ID to use. If empty, the one from the raft
	// instance will be used.
	NodeID string
	// Credentials are gRPC credentials to use when dialing other nodes
	// in the mesh.
	Credentials []grpc.DialOption
	// Key is the private key to use for WireGuard and libp2p connections.
	// This can be nil, in which case one will be generated when Connect
	// is called.
	Key crypto.PrivateKey
	// HeartbeatPurgeThreshold is the number of failed heartbeats before
	// assuming a peer is offline. This is only applicable when currently
	// the leader of the raft group.
	HeartbeatPurgeThreshold int
	// ZoneAwarenessID is an to use with zone-awareness to determine
	// peers in the same LAN segment.
	ZoneAwarenessID string
	// UseMeshDNS will attempt to set the system DNS to any discovered
	// DNS servers. This is only applicable when not serving MeshDNS
	// ourselves.
	UseMeshDNS bool
	// LocalMeshDNSAddr is the address MeshDNS is listening on locally.
	LocalMeshDNSAddr string
	// DisableIPv4 is true if IPv4 should be disabled.
	DisableIPv4 bool
	// DisableIPv6 is true if IPv6 should be disabled.
	DisableIPv6 bool
	// DisableDefaultIPAM disables the default IPAM plugin.
	DisableDefaultIPAM bool
	// DefaultIPAMStaticIPv4 is a map of node names to IPv4 addresses.
	DefaultIPAMStaticIPv4 map[string]string
}

Config contains the configurations for a new mesh connection.

type ConnectOptions

type ConnectOptions struct {
	// StorageProvider is the underlying storage provider to use.
	StorageProvider storage.Provider
	// Features are the features to broadcast to others in the mesh.
	Features []*v1.FeaturePort
	// Plugins is a map of plugins to use.
	Plugins map[string]plugins.Plugin
	// JoinRoundTripper is the round tripper to use for joining the mesh.
	JoinRoundTripper transport.JoinRoundTripper
	// LeaveRoundTripper is the round tripper to use for leaving the mesh.
	LeaveRoundTripper transport.LeaveRoundTripper
	// NetworkOptions are options for the network manager
	NetworkOptions meshnet.Options
	// Discovery are options for broadcasting to others to join the mesh
	// via this node. It can be turned on later if needed.
	Discovery *libp2p.AnnounceOptions
	// MaxJoinRetries is the maximum number of join retries.
	MaxJoinRetries int
	// GRPCAdvertisePort is the port to advertise for gRPC connections.
	GRPCAdvertisePort int
	// MeshDNSAdvertisePort is the port to advertise for MeshDNS connections.
	MeshDNSAdvertisePort int
	// PrimaryEndpoint is a publicly accessible address to broadcast as the
	// primary endpoint for this node. This is used for discovery and
	// connection into the mesh. If left unset, the node will be assumed to be
	// behind a NAT.
	PrimaryEndpoint netip.Addr
	// WireGuardEndpoints are endpoints to advertise for WireGuard connections.
	WireGuardEndpoints []netip.AddrPort
	// RequestVote requests a vote in Raft elections.
	RequestVote bool
	// RequestObserver requests to be an observer in Raft elections.
	RequestObserver bool
	// Routes are additional routes to broadcast to the mesh.
	Routes []netip.Prefix
	// DirectPeers are a map of peers to connect to directly. The values
	// are the prefered transport to use.
	DirectPeers map[types.NodeID]v1.ConnectProtocol
	// Bootstrap are options for bootstrapping the mesh when connecting for
	// the first time.
	Bootstrap *BootstrapOptions
	// PreferIPv6 is true if IPv6 should be preferred over IPv4.
	PreferIPv6 bool
	// Multiaddrs are the multiaddrs to advertise for this node.
	Multiaddrs []multiaddr.Multiaddr
}

ConnectOptions are options for opening the connection to the mesh.

func (ConnectOptions) MarshalJSON

func (c ConnectOptions) MarshalJSON() ([]byte, error)

type MockAnnouncer

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

MockAnnouncer is a mock announcer that tracks state internally but does not perform any actual announcements.

func (*MockAnnouncer) AnnounceToDHT

func (m *MockAnnouncer) AnnounceToDHT(ctx context.Context, opts libp2p.AnnounceOptions) error

AnnounceToDHT should announce the join protocol to the DHT, such that it can be used by a libp2p transport.JoinRoundTripper.

func (*MockAnnouncer) LeaveDHT

func (m *MockAnnouncer) LeaveDHT(ctx context.Context, rendezvous string) error

LeaveDHT should remove the join protocol from the DHT for the given rendezvous string.

type Node

type Node interface {
	// Dialer is the dialer for all connections.
	transport.Dialer
	// NodeDialer is the dialer for node RPC connections.
	transport.NodeDialer
	// LeaderDialer is the dialer for leader RPC connections.
	transport.LeaderDialer

	// ID returns the node ID.
	ID() types.NodeID
	// Started returns true if the mesh is started.
	Started() bool
	// Domain returns the domain of the mesh network.
	Domain() string
	// Key returns the private key used for WireGuard and libp2p connections.
	Key() crypto.PrivateKey
	// Connect opens the connection to the mesh. This must be called before
	// other methods can be used.
	Connect(ctx context.Context, opts ConnectOptions) error
	// Ready returns a channel that will be closed when the mesh is ready.
	// Ready is defined as having a leader and knowing its address.
	Ready() <-chan struct{}
	// Close closes the connection to the mesh and shuts down the storage.
	Close(ctx context.Context) error
	// Credentials returns the gRPC credentials to use for dialing the mesh.
	Credentials() []grpc.DialOption
	// LeaderID returns the current Raft leader ID.
	LeaderID() (types.NodeID, error)
	// Storage returns the underlying storage provider.
	Storage() storage.Provider
	// Network returns the Network manager.
	Network() meshnet.Manager
	// Plugins returns the Plugin manager.
	Plugins() plugins.Manager
	// Discovery returns the interface libp2p.Announcer for announcing
	// the mesh to the discovery service.
	Discovery() libp2p.Announcer
}

Node is the connection to the Webmesh. It controls raft consensus, plugins, data storage, and WireGuard connections.

func New

func New(opts Config) Node

New creates a new Mesh. You must call Open() on the returned mesh before it can be used.

func NewSingleNodeTestMesh

func NewSingleNodeTestMesh(ctx context.Context) (Node, error)

NewTestNode creates a new test mesh and waits for it to be ready. The context is used to enforce startup timeouts.

func NewTestNode

func NewTestNode(opts Config) Node

NewTestNode creates a new test mesh node. It is not started and proper methods will return errors. A proper join round tripper must be supllied to the connect method.

func NewTestNodeWithLogger

func NewTestNodeWithLogger(log *slog.Logger, opts Config) Node

NewTestNodeWithLogger creates a new test mesh node with a logger. It is not started and proper methods will return errors.

func NewWithLogger

func NewWithLogger(log *slog.Logger, opts Config) Node

NewWithLogger creates a new Mesh with the given logger. You must call Open() on the returned mesh before it can be used.

type TestNode

type TestNode struct {
	transport.NodeDialer
	transport.LeaderDialer
	// contains filtered or unexported fields
}

TestNode is a mesh node for testing.

func (*TestNode) Close

func (t *TestNode) Close(ctx context.Context) error

Close closes the connection to the mesh and shuts down the storage.

func (*TestNode) Connect

func (t *TestNode) Connect(ctx context.Context, opts ConnectOptions) error

Connect opens the connection to the mesh. This must be called before other methods can be used.

func (*TestNode) Credentials

func (t *TestNode) Credentials() []grpc.DialOption

Credentials returns the gRPC credentials to use for dialing the mesh.

func (*TestNode) Dial

func (t *TestNode) Dial(ctx context.Context, network, address string) (net.Conn, error)

Dial dials a given address.

func (*TestNode) Discovery

func (t *TestNode) Discovery() libp2p.Announcer

Discovery returns the interface libp2p.Announcer for announcing the mesh to the discovery service.

func (*TestNode) Domain

func (t *TestNode) Domain() string

Domain returns the domain of the mesh network.

func (*TestNode) ID

func (t *TestNode) ID() types.NodeID

ID returns the node ID.

func (*TestNode) Key

func (t *TestNode) Key() crypto.PrivateKey

Key returns the private key used for WireGuard and libp2p connections.

func (*TestNode) LeaderID

func (t *TestNode) LeaderID() (types.NodeID, error)

LeaderID returns the current Raft leader ID.

func (*TestNode) Network

func (t *TestNode) Network() meshnet.Manager

Network returns the Network manager.

func (*TestNode) Plugins

func (t *TestNode) Plugins() plugins.Manager

Plugins returns the Plugin manager.

func (*TestNode) Ready

func (t *TestNode) Ready() <-chan struct{}

Ready returns a channel that will be closed when the mesh is ready. Ready is defined as having a leader and knowing its address.

func (*TestNode) Started

func (t *TestNode) Started() bool

Started returns true if the mesh is started.

func (*TestNode) Storage

func (t *TestNode) Storage() storage.Provider

Storage returns the underlying storage provider.