core

package
v0.0.0-...-575c348 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 1, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package core provides the main orchestration logic for an I2P-based WireGuard mesh VPN node. It coordinates identity management, peer discovery, gossip protocols, and user interfaces.

Package core logging configuration

Index

Constants

View Source 
const (
	DefaultSAMAddress        = "127.0.0.1:7656"
	DefaultTunnelLength      = 1
	DefaultTunnelSubnet      = "10.42.0.0/16"
	DefaultHeartbeatInterval = 30 * time.Second
	DefaultPeerTimeout       = 5 * time.Minute
	DefaultMaxPeers          = 50
	DefaultShutdownTimeout   = 5 * time.Second
	DefaultDrainTimeout      = 10 * time.Second
	DefaultRPCSocket         = "rpc.sock"
	DefaultWebListen         = "127.0.0.1:8080"
)

Default configuration values. Note: DefaultTunnelLength is set to 1 because this mesh VPN operates on a trusted peer model where all nodes are considered trusted members. Lower tunnel length provides faster, more reliable connectivity. Use higher values (2-3) if anonymity between mesh peers is required.

Variables

This section is empty.

Functions

func SaveConfig 

func SaveConfig(cfg *Config, path string) error

SaveConfig writes the configuration to a TOML file. It creates the parent directory if it doesn't exist.

Types

type Config 

type Config struct {
	Node NodeConfig `toml:"node"`
	I2P  I2PConfig  `toml:"i2p"`
	Mesh MeshConfig `toml:"mesh"`
	RPC  RPCConfig  `toml:"rpc"`
	Web  WebConfig  `toml:"web"`
}

Config holds all configuration for an i2plan node.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a Config with sensible defaults.

func LoadConfig 

func LoadConfig(path string) (*Config, error)

LoadConfig reads configuration from a TOML file. If the file doesn't exist, it returns the default configuration. Environment variables with the I2PLAN_ prefix override configuration values.

Environment variable mapping:

  • I2PLAN_NODE_NAME -> Node.Name
  • I2PLAN_DATA_DIR -> Node.DataDir
  • I2PLAN_SAM_ADDRESS -> I2P.SAMAddress
  • I2PLAN_TUNNEL_LENGTH -> I2P.TunnelLength
  • I2PLAN_TUNNEL_SUBNET -> Mesh.TunnelSubnet
  • I2PLAN_HEARTBEAT_INTERVAL -> Mesh.HeartbeatInterval (seconds)
  • I2PLAN_PEER_TIMEOUT -> Mesh.PeerTimeout (seconds)
  • I2PLAN_MAX_PEERS -> Mesh.MaxPeers
  • I2PLAN_SHUTDOWN_TIMEOUT -> Mesh.ShutdownTimeout (seconds)
  • I2PLAN_DRAIN_TIMEOUT -> Mesh.DrainTimeout (seconds)
  • I2PLAN_RPC_ENABLED -> RPC.Enabled (true/false)
  • I2PLAN_RPC_SOCKET -> RPC.Socket
  • I2PLAN_RPC_TCP_ADDRESS -> RPC.TCPAddress
  • I2PLAN_WEB_ENABLED -> Web.Enabled (true/false)
  • I2PLAN_WEB_LISTEN -> Web.Listen

func (*Config) DataPath 

func (c *Config) DataPath(elem ...string) string

DataPath returns an absolute path within the data directory.

func (*Config) EnsureDataDir 

func (c *Config) EnsureDataDir() error

EnsureDataDir creates the data directory if it doesn't exist.

func (*Config) Validate 

func (c *Config) Validate() error

Validate checks the configuration for errors. It validates node, I2P, and mesh configuration sections.

type I2PConfig 

type I2PConfig struct {
	// SAMAddress is the SAM bridge address (host:port)
	SAMAddress string `toml:"sam_address"`
	// TunnelLength is the number of hops for I2P tunnels (0-7).
	// Lower values are faster but provide less anonymity.
	// Default is 1 for trusted mesh networks; use 2-3 for untrusted peers.
	TunnelLength int `toml:"tunnel_length"`
}

I2PConfig contains I2P transport settings.

type MeshConfig 

type MeshConfig struct {
	// TunnelSubnet is the IP range used for mesh IPs (e.g., "10.42.0.0/16")
	TunnelSubnet string `toml:"tunnel_subnet"`
	// HeartbeatInterval is how often to announce presence to peers
	HeartbeatInterval time.Duration `toml:"heartbeat_interval"`
	// PeerTimeout is how long before a peer is considered stale
	PeerTimeout time.Duration `toml:"peer_timeout"`
	// MaxPeers is the maximum number of peers to maintain connections with
	MaxPeers int `toml:"max_peers"`
	// ShutdownTimeout is the maximum time to wait for graceful device shutdown.
	// In production environments with slow I2P sessions, you may need to increase this.
	ShutdownTimeout time.Duration `toml:"shutdown_timeout"`
	// DrainTimeout is the maximum time to wait for in-flight requests to complete
	// during shutdown. This applies to RPC and Web servers.
	DrainTimeout time.Duration `toml:"drain_timeout"`
}

MeshConfig contains mesh network settings.

type Node 

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

Node is the main orchestrator for an i2plan mesh VPN node. It coordinates identity management, I2P transport, WireGuard device, gossip protocol, and user interfaces.

func NewNode 

func NewNode(cfg *Config) (*Node, error)

NewNode creates a new Node with the given configuration. The node is not started until Start() is called.

func (*Node) AcceptInvite 

func (n *Node) AcceptInvite(ctx context.Context, inviteCode string) (*rpc.InviteAcceptResult, error)

AcceptInvite accepts an invite code and initiates connection to the inviter.

func (*Node) AddBan 

func (n *Node) AddBan(nodeID, reason, description string, duration time.Duration) error

AddBan adds a peer to the ban list.

func (*Node) Config 

func (n *Node) Config() *Config

Config returns the node's configuration.

func (*Node) ConnectPeer 

func (n *Node) ConnectPeer(ctx context.Context, inviteCode string) (*rpc.PeersConnectResult, error)

ConnectPeer connects to a peer using an invite code.

func (*Node) CreateInvite 

func (n *Node) CreateInvite(expiry time.Duration, maxUses int) (*rpc.InviteCreateResult, error)

CreateInvite creates a new invite code for others to join the mesh. If this is the first node in a new network (no NetworkID set), a new network is automatically created with a randomly generated NetworkID.

func (*Node) Device 

func (n *Node) Device() *mesh.Device

Device returns the WireGuard device.

func (*Node) Done 

func (n *Node) Done() <-chan struct{}

Done returns a channel that is closed when the node has stopped.

func (*Node) GetConfig 

func (n *Node) GetConfig(key string) (any, error)

GetConfig returns a configuration value for the given key. If key is empty, returns the entire configuration. Supported keys: node.name, node.data_dir, i2p.sam_address, i2p.tunnel_length, mesh.tunnel_subnet, mesh.heartbeat_interval, mesh.peer_timeout, mesh.max_peers, rpc.enabled, rpc.socket, rpc.tcp_address, web.enabled, web.listen

func (*Node) GetState 

func (n *Node) GetState() NodeState

GetState returns the current state of the node (typed).

func (*Node) I2PAddress 

func (n *Node) I2PAddress() string

I2PAddress returns our short I2P address (base32.b32.i2p format).

func (*Node) I2PDestination 

func (n *Node) I2PDestination() string

I2PDestination returns our I2P destination.

func (*Node) Identity 

func (n *Node) Identity() *identity.Identity

Identity returns the node's identity.

func (*Node) InviteStore 

func (n *Node) InviteStore() *identity.InviteStore

InviteStore returns the invite store.

func (*Node) ListBans 

func (n *Node) ListBans() []rpc.BanEntry

ListBans returns all active bans for RPC.

func (*Node) ListPeers 

func (n *Node) ListPeers() []rpc.PeerInfo

ListPeers returns all known peers for RPC.

func (*Node) ListRoutes 

func (n *Node) ListRoutes() []rpc.RouteInfo

ListRoutes returns all routes for RPC.

func (*Node) NodeID 

func (n *Node) NodeID() string

NodeID returns the unique node identifier.

func (*Node) NodeName 

func (n *Node) NodeName() string

NodeName returns the configured node name.

func (*Node) PeerCount 

func (n *Node) PeerCount() int

PeerCount returns the number of connected peers.

func (*Node) PeerManager 

func (n *Node) PeerManager() *mesh.PeerManager

PeerManager returns the peer manager.

func (*Node) RemoveBan 

func (n *Node) RemoveBan(nodeID string) bool

RemoveBan removes a peer from the ban list.

func (*Node) RoutingTable 

func (n *Node) RoutingTable() *mesh.RoutingTable

RoutingTable returns the routing table.

func (*Node) SetConfig 

func (n *Node) SetConfig(key string, value any) (any, error)

SetConfig sets a configuration value. Note: Most configuration changes require a restart to take effect. Returns the old value if successful.

func (*Node) SetOnError 

func (n *Node) SetOnError(callback func(err error, message string))

SetOnError sets a callback for error events. The callback is invoked when recoverable errors occur.

func (*Node) SetOnStateChange 

func (n *Node) SetOnStateChange(callback func(oldState, newState NodeState))

SetOnStateChange sets a callback for state changes. The callback is invoked synchronously during state transitions.

func (*Node) Start 

func (n *Node) Start(ctx context.Context) error

Start initializes and starts all node components. This includes:

  • Creating data directory
  • Loading or generating identity
  • Opening I2P transport
  • Starting WireGuard device
  • Starting gossip protocol
  • Starting user interfaces (RPC, Web, TUI) if enabled

Start blocks until the node is fully initialized or an error occurs.

func (*Node) StartTime 

func (n *Node) StartTime() time.Time

StartTime returns when the node started.

func (*Node) StartedAt 

func (n *Node) StartedAt() time.Time

StartedAt returns when the node was started. Returns zero time if not started.

func (*Node) State 

func (n *Node) State() string

State returns the current state as a string for RPC.

func (*Node) Stop 

func (n *Node) Stop(ctx context.Context) error

Stop gracefully shuts down the node. It blocks until all components have stopped or the context is cancelled.

func (*Node) Transport 

func (n *Node) Transport() *transport.Transport

Transport returns the I2P transport.

func (*Node) TunnelIP 

func (n *Node) TunnelIP() string

TunnelIP returns our mesh tunnel IP as a string.

func (*Node) TunnelIPAddr 

func (n *Node) TunnelIPAddr() netip.Addr

TunnelIPAddr returns the tunnel IP as netip.Addr.

func (*Node) Uptime 

func (n *Node) Uptime() time.Duration

Uptime returns how long the node has been running. Returns zero if not running.

func (*Node) Version 

func (n *Node) Version() string

Version returns the software version.

type NodeConfig 

type NodeConfig struct {
	// Name is a human-readable identifier for this node
	Name string `toml:"name"`
	// DataDir is the directory where persistent data is stored
	DataDir string `toml:"data_dir"`
}

NodeConfig contains basic node identification settings.

type NodeState 

type NodeState int

NodeState represents the current state of the node. 

const (
	// StateInitial is the initial state before Start is called.
	StateInitial NodeState = iota
	// StateStarting means the node is in the process of starting.
	StateStarting
	// StateRunning means the node is fully operational.
	StateRunning
	// StateStopping means the node is shutting down.
	StateStopping
	// StateStopped means the node has been stopped.
	StateStopped
)

func (NodeState) String 

func (s NodeState) String() string

type RPCConfig 

type RPCConfig struct {
	// Enabled controls whether the RPC server is started
	Enabled bool `toml:"enabled"`
	// Socket is the path to the Unix socket for RPC (relative to DataDir)
	Socket string `toml:"socket"`
	// TCPAddress is an optional TCP address for RPC (e.g., "127.0.0.1:9090")
	TCPAddress string `toml:"tcp_address,omitempty"`
}

RPCConfig contains RPC server settings.

type WebConfig 

type WebConfig struct {
	// Enabled controls whether the web UI is started
	Enabled bool `toml:"enabled"`
	// Listen is the address to bind the web server to
	Listen string `toml:"listen"`
}

WebConfig contains web UI settings.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.