demux

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ConnEntry

type ConnEntry struct {
	PeerIndex      uint32
	SenderSocket   Socket
	ReceiverSocket Socket
	LastSeen       time.Time
	// contains filtered or unexported fields
}

type ConnTrack

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

func NewConnTrack

func NewConnTrack() *ConnTrack

func NewConnTrackWithLimits

func NewConnTrackWithLimits(l Limits) *ConnTrack

func (*ConnTrack) AddPartial

func (c *ConnTrack) AddPartial(ci uint32, clientSocket, serverSocket Socket, groups ...string) bool

AddPartial creates the Ci entry after type 1 forward (Si unknown yet). Returns false (and changes nothing) when the index is already taken by a different live session (spec §4: the handshake is dropped so upstream WireGuard retries with a new index, instead of overwriting a peer), or when the table is full.

func (*ConnTrack) Cleanup

func (c *ConnTrack) Cleanup() int

Cleanup removes the stale entries now and says how many it removed.

func (*ConnTrack) Complete

func (c *ConnTrack) Complete(si, ci uint32, clientSocket, serverSocket Socket) bool

Complete fills in Si after type 2 response, creating mirror entry. Returns false when Si collides with a live session that is not the matching peer, or the table is full: the response is dropped and the handshake fails; upstream WG retries.

func (*ConnTrack) Expected

func (c *ConnTrack) Expected(index uint32) (Socket, bool)

Expected is the source the session of an index expects its packets from.

func (*ConnTrack) Len

func (c *ConnTrack) Len() int

Len is the number of entries.

func (*ConnTrack) Lookup

func (c *ConnTrack) Lookup(receiverIndex uint32) (dst Socket, found bool)

Lookup finds the entry, updates LastSeen, and returns ReceiverSocket. Used for type-4 userspace fallback: receiverIndex → forward to ReceiverSocket.

func (*ConnTrack) LookupForward

func (c *ConnTrack) LookupForward(receiverIndex uint32, src Socket) (dst Socket, found bool)

LookupForward returns the forwarding destination for a type-4 transport packet. receiver_index identifies the session:

  • entries[Si].SenderSocket = serverSocket → forward client→server traffic
  • entries[Ci].SenderSocket = clientSocket → forward server→client traffic

ReceiverSocket is the expected source of packets carrying this index. A packet from another source is the session roaming, which is allowed, but at most once per RoamInterval for a session: a packet from a third address within the interval is not forwarded and moves nothing (so a spoofed packet cannot keep dragging the session around).

func (*ConnTrack) LookupPartial

func (c *ConnTrack) LookupPartial(index uint32) (client, backend Socket, found bool)

LookupPartial returns the sockets of a handshake in progress: the client that sent the init (SenderSocket) and the backend it was forwarded to (ReceiverSocket, the only address its type-2 answer may come from).

func (*ConnTrack) LookupSender

func (c *ConnTrack) LookupSender(index uint32) (Socket, bool)

LookupSender returns SenderSocket for the given index without updating LastSeen.

func (*ConnTrack) LookupStrict

func (c *ConnTrack) LookupStrict(receiverIndex uint32, src Socket) (dst Socket, found bool)

LookupStrict is LookupForward without roaming: the packet is forwarded only from the exact source the session expects (cookie replies).

func (*ConnTrack) RemoveGroup added in v1.1.0

func (c *ConnTrack) RemoveGroup(group string)

RemoveGroup retires only sessions belonging to the changed/deleted group.

func (*ConnTrack) RunTTLCleanup

func (c *ConnTrack) RunTTLCleanup(stop <-chan struct{})

RunTTLCleanup removes stale entries in a background goroutine.

func (*ConnTrack) UpdateRoaming

func (c *ConnTrack) UpdateRoaming(receiverIndex uint32, newSender Socket)

UpdateRoaming updates sender socket when client IP changes.

type Demux

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

Demux handles incoming WireGuard UDP packets on the one public port every team shares.

type 1 (handshake init)   forwarded to the group's VPN pod found by mac1; rate-limited (all sources together)
type 2 (handshake answer) accepted only from the backend the init was forwarded to
type 3 (cookie reply)     forwarded like a transport packet, but only from the exact expected source
type 4 (transport data)   forwarded by receiver index; roaming allowed at most once per interval

Nothing here is authenticated (the demux does not hold the keys: the VPN pods do, and WireGuard's own handshake is the boundary), so everything a stranger can make it hold or spend is capped (see Limits) and nothing is logged per packet.

func New

func New(listenAddr string, table *Table, ct *ConnTrack) (*Demux, error)

func NewWithLimits

func NewWithLimits(listenAddr string, table *Table, ct *ConnTrack, l Limits) (*Demux, error)

func (*Demux) Close

func (d *Demux) Close()

func (*Demux) LocalAddr

func (d *Demux) LocalAddr() net.Addr

LocalAddr is the address the demux listens on.

func (*Demux) Run

func (d *Demux) Run(stop <-chan struct{})

Run processes incoming WireGuard packets until stop is closed. Several goroutines read the socket (a UDP socket is safe to read from many), so the cost of one packet does not hold the others up.

type LabGroupWatcher

type LabGroupWatcher struct {
	client.Client
	Table          *Table
	VPNServicePort int
	// contains filtered or unexported fields
}

LabGroupWatcher is a controller-runtime reconciler keeping Table in sync with LabGroups.

func (*LabGroupWatcher) Reconcile

func (w *LabGroupWatcher) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)

func (*LabGroupWatcher) SetupWithManager

func (w *LabGroupWatcher) SetupWithManager(mgr ctrl.Manager) error

func (*LabGroupWatcher) Synced

func (w *LabGroupWatcher) Synced(ctx context.Context) bool

Synced says whether every LabGroup the cache holds has been reconciled into the table at least once: only then does the demux know the groups' keys, and a handshake of a group that is not in the table is dropped. It is the readiness of the wg-demux container.

type Limits

type Limits struct {
	// MaxEntries is the most conntrack entries (two per session) in the whole table. A handshake that would pass it is
	// dropped (the client retries).
	MaxEntries int
	// PartialTTL is how long a handshake in progress (the init was forwarded, no answer yet) keeps its entry. It is short:
	// the entry is made before anything is authenticated, so a flood of inits must not be able to fill the table for the
	// full conntrack lifetime. A completed session keeps its entry for conntrackTTL after its last packet.
	PartialTTL time.Duration
	// GlobalHandshakeRate and GlobalHandshakeBurst limit handshake initiations of all sources together: each costs a scan of every
	// group's key, so the sources cannot add up to more than the demux can pay.
	GlobalHandshakeRate  float64
	GlobalHandshakeBurst int
	// MissRate and MissBurst limit, for all sources together, the packets that match no session or come from an unexpected
	// address (a guess of the 32-bit index, a spoof, a roam): guessing an index costs one of them, so guessing is rate-limited.
	MissRate  float64
	MissBurst int
	// RoamInterval is the least time between two address changes of one session.
	RoamInterval time.Duration
	// SessionRate and SessionBurst limit the transport packets of one session per second: the demux is shared by everyone,
	// and one participant with a valid session must not be able to use its CPU up. 0 = unlimited.
	SessionRate  float64
	SessionBurst int
	// Readers is how many goroutines read the socket (1 when zero).
	Readers int
}

Limits bound what an unauthenticated sender can make the demux hold or do. The demux is shared by every team and reads a public UDP port, so every table and every cost it spends on a packet from a stranger has a cap.

There is no limit per source address: one NAT (a venue, a campus) hides a whole event behind one address, and behind a load balancer in SNAT mode every client has a node's address. What is capped is the whole table, the handshakes and the unmatched packets of all sources together, and the packets of one session.

func DefaultLimits

func DefaultLimits() Limits

DefaultLimits mirror the chart (proxy.wg.limits).

type Mac1Key

type Mac1Key [32]byte

Mac1Key is the 32-byte key used to compute and verify mac1 in WireGuard handshake init.

type Socket

type Socket struct {
	IP   net.IP
	Port uint16
}

type Table

type Table struct {
	OnChange func(string) // invoked under table lock; callback must not enter Table
	// contains filtered or unexported fields
}

Table is an in-memory mac1_key→UID/backend mapping, rebuilt from LabGroup watches. Brute-force scan is O(n) but handshake init is rare (~once per 2 min per peer).

func NewTable

func NewTable() *Table

func (*Table) Delete

func (t *Table) Delete(uid string)

Delete removes the entry for uid.

func (*Table) FindByMac1

func (t *Table) FindByMac1(packet []byte) (uid string, backend *net.UDPAddr, found bool)

FindByMac1 brute-forces mac1 verification. packet is the raw WireGuard type-1 packet (UDP payload). mac1 occupies bytes [len-32 : len-16]; the message body for MAC is packet[:len-32]. Returns the matched group UID and its VPN Service backend (host:port).

func (*Table) RunResolver

func (t *Table) RunResolver(stop <-chan struct{}, every time.Duration)

RunResolver keeps the resolved address of every backend fresh, off the read loop, until stop is closed. A backend that cannot be resolved keeps its last good address.

func (*Table) RunResolverContext added in v1.1.0

func (t *Table) RunResolverContext(ctx context.Context, every time.Duration)

func (*Table) Update

func (t *Table) Update(uid, pubKey, backend string) error

type TableEntry

type TableEntry struct {
	UID       string
	PublicKey string
	Mac1Key   Mac1Key
	// Backend is the in-cluster Service address (host:port) for the VPN server of this group; Resolved is it resolved, kept up to
	// date by Table.RunResolver (the read loop never does a DNS lookup).
	Backend  string
	Resolved *net.UDPAddr
}

Jump to

Keyboard shortcuts

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