overlayagent

package
v0.0.0-...-2f264db Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: GPL-3.0 Imports: 47 Imported by: 0

Documentation

Overview

Package overlayagent is the client side of the private overlay network. It registers a connected session with the hub as broadcasting, tracks the peer list, answers incoming flows and opens outgoing flows to peers. It is platform independent: callers supply how streams reach the hub and where incoming flows end up locally.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Discover

func Discover(ctx context.Context, cfg Config) (netip.Prefix, netip.Addr, error)

Discover is DiscoverCIDR that also returns the address the hub assigned to this identity, so a platform can install it on its tunnel interface before the session starts. The hub keeps that address for the identity.

func DiscoverCIDR

func DiscoverCIDR(ctx context.Context, cfg Config) (netip.Prefix, error)

DiscoverCIDR authenticates through the selected transport and reads the hub's assigned range before the application installs its routes. No client range is sent. The temporary control connection closes before the session starts.

func LocalDialer

func LocalDialer(address func() (netip.Addr, bool)) func(context.Context, string, uint16, netip.Addr) (net.Conn, error)

LocalDialer completes incoming flows by dialing address, which must be a local address of this device. The dialed service sees this device as its peer; services bound only to loopback are not reachable through it.

func Probe

func Probe(ctx context.Context, address string) error

Probe checks that the hub admits this source and answers frames. It sends a malformed public key, which the hub refuses before any challenge, so the probe never registers an identity or takes an overlay address.

Types

type Agent

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

Agent is one session's overlay participant. Create it with New and run it once.

func New

func New(cfg Config) *Agent

New builds an idle agent using its enrolled identity.

func (*Agent) IP

func (a *Agent) IP() netip.Addr

IP returns this account's overlay address, or the zero Addr before the first registration.

func (*Agent) Outbound

func (a *Agent) Outbound(ctx context.Context, proto string, dst netip.AddrPort) (net.Conn, error)

Outbound opens a flow to a broadcasting peer through the hub. A TCP flow is the returned stream itself; a UDP flow exposes one datagram per Read and Write. The checks here are a cheap pre-filter: the hub remains the authority.

func (*Agent) Range

func (a *Agent) Range() netip.Prefix

Range is the hub's address space, or the zero prefix before the hub has assigned one.

func (*Agent) Ready

func (a *Agent) Ready() <-chan netip.Addr

Ready delivers the overlay address once at the first successful registration and is then closed. Receive once; afterwards use IP.

func (*Agent) Run

func (a *Agent) Run(ctx context.Context) error

Run keeps the control stream registered with the hub until ctx ends. It returns ctx.Err() after every goroutine it started has stopped.

func (*Agent) SetDirectPeers

func (a *Agent) SetDirectPeers(ids []string) error

SetDirectPeers replaces explicit device approvals, closing revoked direct flows and negotiations immediately. Relay remains available for every peer.

func (*Agent) SetRelayOnly

func (a *Agent) SetRelayOnly(ids []string) error

SetRelayOnly replaces the direct-connection deny list. IDs identify device keys, not addresses. Existing direct flows to denied peers are closed; new flows use the encrypted relay. It is safe to call while Run is active.

type Config

type Config struct {
	// CIDR optionally pins a range the caller already received from the hub.
	// It is never sent to the hub. When unset, the agent adopts the range from
	// the hub's first accepted reply and reports it through OnRange.
	CIDR netip.Prefix
	// OnRange is called once, without the agent's locks held, when the hub's
	// range becomes known. The caller installs its routes for the range here.
	OnRange func(netip.Prefix)
	// Room is the password proof derived with overlay.RoomToken.
	Room string
	// RoomID names the private room; it is required with Room.
	RoomID string
	// FallbackPublic permits a public-room retry only after explicit private-room rejection.
	FallbackPublic bool
	// Name is this device's advertised name. Empty uses the hub's default.
	Name string
	// Identity is the persistent private key enrolled with the hub.
	Identity *ecdsa.PrivateKey
	// Dial opens one stream to the hub through an authenticated VPN session.
	// The caller must enforce this: the handshake does not authenticate the hub
	// or protect the stream against an active intermediary.
	Dial func(ctx context.Context) (net.Conn, error)
	// DialLocal completes an INCOMING flow locally. For UDP it returns a
	// connected net.Conn whose Read and Write each carry one datagram.
	DialLocal func(ctx context.Context, proto string, port uint16, src netip.Addr) (net.Conn, error)
	// OnState receives every state change. It must not block.
	OnState func(overlay.State)
	// Compression DEFLATEs flow bytes in chunks (see overlay.Compressed). Default
	// off. Both peers of a flow must enable it, because the hub relays bytes unchanged.
	Compression bool
	// DisableEncryption turns off end-to-end encryption. By default every flow
	// is encrypted between the two agents with TLS 1.3, and a flow whose peer
	// does not support encryption fails.
	DisableEncryption bool
	// Direct lets flows bypass the hub when both peers enable it. Nil (the
	// default) keeps every flow on the relay.
	Direct *DirectOptions
	// RelayOnly lists device IDs that must never use direct transport.
	RelayOnly []string
	// DirectPeers is the explicit direct allowlist. Empty permits relay only.
	DirectPeers []string
}

Config wires an Agent to its platform.

type DirectOptions

type DirectOptions struct {
	// STUNServers lists host:port STUN servers asked from outside the VPN to
	// learn public UDP addresses. At least one is required.
	STUNServers []string
	// ListenPacket opens an IPv4 UDP socket. Every direct method calls it for
	// each socket it needs. Return a socket that bypasses the VPN. Nil listens
	// on all addresses, any port.
	ListenPacket func(ctx context.Context) (net.PacketConn, error)
	// Timeout bounds each method's connection attempt. Zero means ten seconds.
	Timeout time.Duration
	// Methods lists the methods to try, in order: "webrtc", "ice" and "libp2p".
	// Nil tries all of them in that order.
	Methods []string
	// Net replaces the operating system network stack of the ICE based methods.
	// It exists for network simulation; nil uses ListenPacket and the host stack.
	Net transport.Net
}

DirectOptions configures direct links. Two peers that both enable it negotiate a link over the encrypted relay and, once it is up, carry new flows on it instead of the hub. The relay keeps serving every flow that opens before a link exists or after one fails. It needs encryption.

type Router

type Router struct {
	// Prefix optionally reserves a range the hub already assigned, even while
	// disconnected. Zero follows the running agent's range, which stays empty
	// until the hub assigns one.
	Prefix netip.Prefix
	// contains filtered or unexported fields
}

Router lets a session's packet-stack handler send flows addressed to the overlay network to the agent instead of the VPN server's open internet. While no agent runs, flows to the overlay address space are refused rather than forwarded, so hidden sessions never leak overlay traffic to the server.

func (*Router) Owns

func (r *Router) Owns(address netip.Addr) bool

Owns reports whether the destination belongs to the overlay address space.

func (*Router) SetDirectPeers

func (r *Router) SetDirectPeers(ids []string) error

SetDirectPeers replaces the running agent's explicit direct approvals.

func (*Router) SetRelayOnly

func (r *Router) SetRelayOnly(ids []string) error

SetRelayOnly updates direct policy on the running agent.

func (*Router) Start

func (r *Router) Start(ctx context.Context, config Config, onReady func(netip.Addr) (undo func())) (stop func())

Start runs an agent until stop is called or ctx ends. onReady is called once with the registered overlay address and returns the platform's undo function, which stop calls. Stop blocks until the agent has finished and is idempotent.

func (*Router) TCP

func (r *Router) TCP(ctx context.Context, local net.Conn, destination M.Socksaddr) error

TCP relays one stack TCP flow to a broadcasting peer.

func (*Router) UDP

func (r *Router) UDP(ctx context.Context, local N.PacketConn, destination M.Socksaddr) error

UDP relays one stack UDP flow to a broadcasting peer.

type SyncWriter

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

SyncWriter serializes whole writes from several goroutines onto one pipe.

func NewSyncWriter

func NewSyncWriter(w io.Writer) *SyncWriter

NewSyncWriter wraps w.

func (*SyncWriter) Write

func (s *SyncWriter) Write(p []byte) (int, error)

Write implements io.Writer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址