meshnode

Documentation

Overview

Package meshnode contains the mesh node and related interfaces.

Index

• Constants
• Variables
• type BootstrapOptions
• type Config
• type ConnectOptions
• type Node
  • func New(opts Config) Node
  • func NewTestNode(ctx context.Context) (Node, error)
  • func NewWithLogger(log *slog.Logger, opts Config) Node

Constants

const DefaultBootstrapListenAddress = "[::]:9001"

DefaultBootstrapListenAddress is the default listen address for the bootstrap transport.

const DefaultBootstrapPort = 9001

DefaultBootstrapPort is the default port for the bootstrap transport.

const DefaultIPv4Network = "172.16.0.0/12"

DefaultIPv4Network is the default IPv4 network for the mesh.

const DefaultMeshAdmin = "admin"

DefaultMeshAdmin is the default mesh admin node ID.

const DefaultMeshDomain = "webmesh.internal"

DefaultMeshDomain is the default domain for the mesh network.

const DefaultNetworkPolicy = "accept"

DefaultNetworkPolicy is the default network policy for the mesh.

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.

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
}

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
	// 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[string]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.

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() string
	// 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() (string, 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 NewTestNode

func NewTestNode(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 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.