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 ¶
- func Discover(ctx context.Context, cfg Config) (netip.Prefix, netip.Addr, error)
- func DiscoverCIDR(ctx context.Context, cfg Config) (netip.Prefix, error)
- func LocalDialer(address func() (netip.Addr, bool)) func(context.Context, string, uint16, netip.Addr) (net.Conn, error)
- func Probe(ctx context.Context, address string) error
- type Agent
- func (a *Agent) IP() netip.Addr
- func (a *Agent) Outbound(ctx context.Context, proto string, dst netip.AddrPort) (net.Conn, error)
- func (a *Agent) Range() netip.Prefix
- func (a *Agent) Ready() <-chan netip.Addr
- func (a *Agent) Run(ctx context.Context) error
- func (a *Agent) SetDirectPeers(ids []string) error
- func (a *Agent) SetRelayOnly(ids []string) error
- type Config
- type DirectOptions
- type Router
- func (r *Router) Owns(address netip.Addr) bool
- func (r *Router) SetDirectPeers(ids []string) error
- func (r *Router) SetRelayOnly(ids []string) error
- func (r *Router) Start(ctx context.Context, config Config, onReady func(netip.Addr) (undo func())) (stop func())
- func (r *Router) TCP(ctx context.Context, local net.Conn, destination M.Socksaddr) error
- func (r *Router) UDP(ctx context.Context, local N.PacketConn, destination M.Socksaddr) error
- type SyncWriter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Discover ¶
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 ¶
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.
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 (*Agent) IP ¶
IP returns this account's overlay address, or the zero Addr before the first registration.
func (*Agent) Outbound ¶
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 ¶
Range is the hub's address space, or the zero prefix before the hub has assigned one.
func (*Agent) Ready ¶
Ready delivers the overlay address once at the first successful registration and is then closed. Receive once; afterwards use IP.
func (*Agent) Run ¶
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 ¶
SetDirectPeers replaces explicit device approvals, closing revoked direct flows and negotiations immediately. Relay remains available for every peer.
func (*Agent) SetRelayOnly ¶
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) SetDirectPeers ¶
SetDirectPeers replaces the running agent's explicit direct approvals.
func (*Router) SetRelayOnly ¶
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.
type SyncWriter ¶
type SyncWriter struct {
// contains filtered or unexported fields
}
SyncWriter serializes whole writes from several goroutines onto one pipe.