wsbind

Documentation

Overview

Package wsbind implements a WireGuard conn.Bind that transports WireGuard datagrams as binary WebSocket messages, with an optional upgrade to UDP relay for better performance.

Architecture:

WireGuard device ←→ wsBind ←→ WebSocket (or UDP) ←→ Hub relay

Transport modes:

1. WebSocket (default) -- works through any HTTP proxy / Cloudflare.
2. UDP relay (upgrade) -- eliminates TCP-over-TCP. Hub relays raw UDP datagrams tagged with an 8-byte session token.

Thread safety:

• WebSocket sends serialized via writeMu.
• UDP sends are inherently goroutine-safe (single socket).
• Receives from both transports merge into RecvCh.
• Close is idempotent; bind supports Close→Open cycles.

Index

• type Bind
  • func New(ws *websocket.Conn, bufSize int) *Bind
  • func (b *Bind) AttemptDirect(peerAddrStr string) error
  • func (b *Bind) BatchSize() int
  • func (b *Bind) Close() error
  • func (b *Bind) DirectActive() bool
  • func (b *Bind) Open(port uint16) ([]conn.ReceiveFunc, uint16, error)
  • func (b *Bind) ParseEndpoint(s string) (conn.Endpoint, error)
  • func (b *Bind) STUNDiscover() (string, error)
  • func (b *Bind) Send(bufs [][]byte, ep conn.Endpoint) error
  • func (b *Bind) SendText(data []byte) error
  • func (b *Bind) SetMark(mark uint32) error
  • func (b *Bind) UDPActive() bool
  • func (b *Bind) UpgradeUDP(hubHost string, hubPort int, token []byte) error

Types

type Bind

type Bind struct {
	RecvCh chan []byte // binary WG datagrams from the reader goroutine(s)
	// contains filtered or unexported fields
}

Bind implements conn.Bind for WireGuard-over-WebSocket transport with optional UDP relay upgrade.

WireGuard calls Close() then Open() during device state transitions (e.g. Up). The bind must support this cycle -- Close/Open are re-entrant and reset the receive path each time.

func New

func New(ws *websocket.Conn, bufSize int) *Bind

New creates a Bind using the given WebSocket connection. bufSize controls the receive channel buffer depth.

func (*Bind) AttemptDirect

func (b *Bind) AttemptDirect(peerAddrStr string) error

AttemptDirect initiates UDP hole punching to the given peer address. It sends probe packets and waits for a response from the peer. On success, the bind routes WG datagrams directly to the peer. On failure, returns an error and the bind continues using UDP relay or WebSocket.

func (*Bind) BatchSize

func (b *Bind) BatchSize() int

BatchSize returns 1 (no batching).

func (*Bind) Close

func (b *Bind) Close() error

Close signals all receiveFunc goroutines to stop and closes the UDP socket if active. Safe to call multiple times.

func (*Bind) DirectActive

func (b *Bind) DirectActive() bool

DirectActive reports whether the bind is using a direct peer-to-peer path.

func (*Bind) Open

func (b *Bind) Open(port uint16) ([]conn.ReceiveFunc, uint16, error)

Open returns the receive function. WireGuard calls Open after Close during state transitions, so this resets the closed channel to allow receiveFunc to work again.

func (*Bind) ParseEndpoint

func (b *Bind) ParseEndpoint(s string) (conn.Endpoint, error)

ParseEndpoint returns a static endpoint -- there's only one peer per bind.

func (*Bind) STUNDiscover

func (b *Bind) STUNDiscover() (string, error)

STUNDiscover performs a STUN Binding Request (RFC 5389) on the existing UDP socket and returns the server-reflexive address (public IP:port). This must be called after UpgradeUDP succeeds.

func (*Bind) Send

func (b *Bind) Send(bufs [][]byte, ep conn.Endpoint) error

Send writes WireGuard datagrams. Priority: direct → UDP relay → WebSocket.

func (*Bind) SendText

func (b *Bind) SendText(data []byte) error

SendText sends a text (JSON control) message through the WebSocket, serialized with WireGuard datagram sends to avoid concurrent writes.

func (*Bind) SetMark

func (b *Bind) SetMark(mark uint32) error

SetMark is a no-op (SO_MARK is irrelevant for WebSocket/UDP relay transport).

func (*Bind) UDPActive

func (b *Bind) UDPActive() bool

UDPActive reports whether the bind is currently using UDP.

func (*Bind) UpgradeUDP

func (b *Bind) UpgradeUDP(hubHost string, hubPort int, token []byte) error

UpgradeUDP attempts to switch from WebSocket to UDP relay. hubHost is the hub's hostname, hubPort is the UDP port, and token is the 8-byte session token assigned by the hub.

Returns nil on success (UDP is now active). On failure, returns an error and the bind continues using WebSocket transparently.