p2p

README

p2p

English · 简体中文

Tunnel host process for GOST's p2p plugin protocol. It lets GOST establish the network path to a chain node through a tunnel opened by this process — the traversal strategy (rendezvous, relay, hole punching) is entirely up to the plugin, and GOST only ever sees a plain byte stream (the Tunnel gRPC stream) to carry its protocol over.

Status: stub + mux + DERP relay + STUN/UDP hole punching + datagram channels. The host bridges tunnels with a local TCP forward, either directly (stub mode, loopback) or through a DERP relay (engine mode, cross-machine/NAT). In engine mode, after a relay session is up, both peers probe their NAT via STUN and punch a UDP hole; once the direct path (KCP + smux) is established, new tunnels flow over it while the relay stays up as fallback. Inner dialers tcp/tls/ws/mtcp/mtls/mws/udp are supported — the mux family reuses one tunnel as a multiplexed session, and udp asks for a datagram stream instead of a byte stream (this is what carries a tun link: GOST owns the device, this host is only the pipe).

How it works

GOST client ──OpenTunnel(peer, network)──▶ p2p host (gRPC, :8003)
GOST client ◀──{ok, id}────────────────────  p2p host
GOST client ══Tunnel stream ("id" key)════▶ p2p host ──bridge──▶ peer

• peer is opaque: its semantics are defined by the plugin (a base64 public key in DERP mode, a plain host:port in stub mode).
• OpenTunnel only authorizes the tunnel and returns a cryptographically random, single-use id. The data rides the Tunnel gRPC stream bound to that id (sent as the id metadata key) — there is no local endpoint to dial, so a firewall between GOST and this host can't block the data path. Closing the stream closes the tunnel; the stream's lifetime is the tunnel's lifetime.
• The GOST-side wiring (tunnel dialer, config) lives in go-gost/x (x/p2p/); the wire contract lives in go-gost/plugin (p2p/proto).

Positioning: a generic P2P connectivity primitive

p2p is a P2P connectivity layer, not a turnkey secure tunnel. Its contract is deliberately narrow:

Give me a peer public key, get back a TCP tunnel; NAT traversal is best-effort (STUN + UDP hole punching with a relay fallback); end-to-end reachability is this layer's job, security is the caller's.

It provides reachability, not policy — the same layering as IP/TCP:

• Encryption is out of scope by design. The relay and hole-punched transports carry plaintext (matching the relay's trust model: it can observe but never decrypt). Confidentiality belongs to the layer above — run tls/mtls/wss over the tunnel, exactly as the GOST inner dialers do. This is the standard connectivity/security layering, not a gap.
• Peer discovery is an enhancement, not a requirement. Peers are addressed by base64 curve25519 public key — a complete addressing scheme. Name→key lookup is intentionally not built in (see Roadmap).
• A relay is inherent to NAT traversal. Cross-NAT reachability without a rendezvous is impossible; derper is a deployment/infrastructure choice, not a design flaw. Symmetric-NAT peers stay on relay permanently.

What an integrator must supply: a relay (self-hosted derper or a third-party DERP), the public keys of the peers to reach, and — if confidentiality is required — its own encryption above the tunnel.

Quick start

go build -o p2p ./cmd/p2p
./p2p --addr 127.0.0.1:8003

Flag	Default	Meaning
-C	(empty)	config file (YAML); config values are defaults, explicitly-set flags override
--addr	127.0.0.1:8003	gRPC control-plane listen address
--token	(empty)	control-plane auth token; empty disables checking
--derp	(empty)	DERP relay URL (wss://host/derp); enables engine mode
--key	$XDG_CONFIG_HOME/p2p/key-v1	curve25519 private key file (hex); created if missing
--target	(empty)	inbound bridge target (repeatable; bare "host:port" feeds the tcp pool, "udp://host:port" the udp pool; DERP mode)
--forward	(empty)	static port forward "listen-addr=peer-key" (repeatable; DERP mode)
--stun	(empty)	STUN server (host:port) for the IPv4 direct path; IPv6 direct works without STUN
--direct	true	attempt a direct (hole-punched) path; false forces relay-only
--tls.secure	true	verify the relay's TLS certificate (false to trust any cert)
--tls.caFile	(empty)	PEM CA file to trust the relay's self-signed certificate
--log.level	info	log level: trace, debug, info, warn, error, fatal
--log.format	json	log format: json or text
--log.output	stderr	log output: stderr, stdout, none, or a file path (size-rotates at 100 MB)

Configuration file

Every flag can live in a YAML config file instead (gost-style -C): a config value is the default, and an explicitly-set flag overrides it. --forward flags and the config forwards list are additive.

./p2p -C p2p.yaml

addr: 127.0.0.1:8003
token: gost
derp: wss://derp.example.com/derp
key: peer.key
target: 127.0.0.1:18080
stun: stun.example.com:3478
tls:
  secure: false
  caFile: /etc/p2p/ca.pem
log:
  level: debug
  format: text
  output: /var/log/p2p.log
  rotation:
    maxSize: 50
    maxAge: 7
    maxBackups: 3
    localTime: true
    compress: true
forwards:
  - listen: 127.0.0.1:18080
    peer: <peerB-key>

Point a GOST chain node at it:

p2ps:
  - name: p2p-1
    plugin:
      type: grpc
      addr: 127.0.0.1:8003
      token: gost                       # matches the host's --token

chains:
  - name: chain-0
    hops:
      - name: hop-0
        nodes:
          - name: node-0
            addr: 192.168.1.10:8080   # the "peer" this stub bridges to
            connector:
              type: http              # connector follows the peer's protocol
            dialer:
              type: tcp
            metadata:
              p2p: p2p-1              # this node's base path goes through the plugin

DERP mode (cross-machine)

The DERP engine relays tunnels through a DERP server so peers behind NAT/firewalls can reach each other. The relay server is the official derper binary; this host speaks its WebSocket path (Upgrade: websocket + subprotocol derp), which is also what keeps it deployable behind Cloudflare and other WebSocket-capable proxies. Note: this WebSocket path is Tailscale's own browser-client transport (cmd/tsconnect/wasm, via derpserver.AddWebSocketSupport) — it is not described in the custom DERP servers docs, which only cover the native Upgrade: DERP hijack, so treat it as a de-facto rather than a documented API.

# relay server (self-hosted; auto-creates its key config on first run)
derper -c /etc/derper/derper.json -hostname derp.example.com -certmode manual -certdir /etc/derper/certs -a :443

# peer side — registers at the relay, bridges inbound tunnels to the local GOST
./p2p --derp wss://derp.example.com/derp --key peer.key --target 127.0.0.1:18080

# client side — serves the GOST control plane as usual
./p2p --derp wss://derp.example.com/derp --key client.key --addr 127.0.0.1:8003

Each host generates a curve25519 keypair on first run and prints its public key (base64) at startup. In DERP mode the GOST chain node's addr is the peer host's public key, not a host:port. Everything else on the GOST side is unchanged.

DERP wire frames

The relay link is a WebSocket carrying DERP binary frames. Two layers are worth knowing: the DERP protocol itself (shared with every Tailscale client) and the small p2p framing this host puts inside a relayed packet.

DERP frame — [type 1B][length 4B big-endian][body], from tailscale.com/derp@v1.102.3:

Type	Name	Body
0x01	ServerKey	8-byte magic (DERP + key emoji) + 32-byte server public key
0x02	ClientInfo	32-byte client pubkey + 24-byte nonce + NaCl-box(JSON {Version, CanAckPings}) to the server key
0x03	ServerInfo	24-byte nonce + NaCl-box(JSON); token-bucket hints, advisory
0x04	SendPacket	32-byte destination pubkey + packet bytes (≤ 64 KiB)
0x05	RecvPacket	v2: 32-byte source pubkey + packet bytes
0x06	KeepAlive	none — no-op
0x08	PeerGone	32-byte pubkey + 1-byte reason (informational)
0x09	PeerPresent	32-byte pubkey (informational; derper only sends it to mesh watchers)
0x12 / 0x13	Ping / Pong	8-byte payload; Recv echoes a Ping back as Pong

Handshake: the server greets with ServerKey, the client replies ClientInfo (boxed to the server key, proving possession of its private key), the server answers ServerInfo. Everything else is SendPacket/RecvPacket. Unknown frame types are skipped (the reference client's recv switch has no default case) — the same forward-compat rule applies here. The client is addressed purely by its 32-byte public key; the base64 form is that key.

p2p packet framing — the bytes inside every SendPacket/RecvPacket start with a type byte:

Byte	Meaning
0x00	control frame: [0x00][kind 1B][NaCl-boxed payload]
0x01	data frame: [0x01][smux byte stream] — one DERP packet per smux write

Control kinds: 0x02 punch candidates (sealed [count]([family][addr][port])*), 0x03 udp-tunnel dial notice (sealed, empty), 0x04 capability bitfield (sealed 1 byte; bit 0 = IPv6-aware, re-sent with each broadcast and OR'd by the receiver). All control payloads are sealed to the peer key (PrivateKey.SealTo), so the relay can route but not forge them. Control frames are consumed by the engine; data frames feed the per-peer smux session.

Hole punching

When both peers are in engine mode, the relay is only used to establish the first session and carry the control channel. In the background each peer queries the derper's built-in STUN server (default port 3478, -stun is on by default) to learn its public UDP endpoint, exchanges it with the peer over the relay, and builds a KCP session over the same UDP socket.

The punch is symmetric: both peers dial the peer's candidate with the same deterministic KCP conv (mutual simultaneous open), and a session is only used once both sides complete the echo handshake — each peer must see its own token round-trip, so a half-open path can never produce a "false direct" session. This removes the old "one side dials, the other accepts" asymmetry, which failed when only one direction could be punched (e.g. a peer inside a k3s pod whose inbound UDP needs the peer to have sent first).

On success new tunnels open streams over the direct smux session (KCP + smux); the relay session stays up so a direct-path failure silently falls back to relay and re-punches. The direct path keeps working even if the relay drops — only a new punch needs the relay back. A static --forward warms its peer's direct path at startup when --stun is set, so the first connection skips the punch latency. Direct is on by default (--direct=false forces relay-only). IPv6 is a first-class candidate family: a host with a global IPv6 egress binds and advertises that address (no STUN, no NAT), and both peers prefer IPv6 when both offer it, retrying IPv4 in the same round if the v6 path does not complete.

Timings are tunable from the config file only (not flags); unset values keep the defaults, and invalid values fail at startup:

timeouts:
  punchWait: 5s       # how long a stream waits for the direct path before relay
  punch: 10s          # whole-punch window (candidate wait + dial/seed)
  seed: 5s            # symmetric echo handshake window
  backoff: 30s        # retry interval after a failed punch
  derpKeepAlive: 30s  # DERP keepalive (keep below proxy idle timeouts)
  smux:
    interval: 10s
    timeout: 30s      # must be >= 2x interval

Symmetric NAT defeats UDP punching; those peers stay on relay permanently (periodic retry). The KCP transport is unencrypted, matching the relay's trust model — confidentiality is the inner dialer's job (mtls/tls/wss).

The derper's STUN server answers only Tailscale's binding-request dialect (SOFTWARE + FINGERPRINT attributes) and binds to the same IP as -a. Run derper with an explicit IP (-a 1.2.3.4:443) so STUN is reachable on the address family the peers will query; with a wildcard -a :443 it binds IPv6-only, and the default IPv4 --stun (derp host :3478) won't reach it — set --stun explicitly in that case.

Datagram channels (a tun link, Linux)

A chain node whose dialer is udp asks for a datagram stream (network=udp) instead of a byte stream. The Tunnel stream carries it like any other tunnel; on each side this host pairs the persistent per-peer edge (the direct-or-relay stream to the other host) with the latest gost tunnel's stream and pumps bytes between them. The GOST-side conn frames each datagram into a length-prefixed frame and the peer's GOST-side conn parses it, so packet boundaries survive the byte-stream data plane and this host never parses the data. That is what makes a tun-to-tun link possible — GOST owns the device (the tun listener creates and configures it, the tun handler bridges it), this host is only the pipe. A tun device is exclusive-open, so the device cannot be shared: GOST having its own tun stack is the whole point.

# both ends: no --target, no device flags. The peer's key goes in the GOST node addr.
./p2p --derp wss://derp.example.com/derp --key a.key --addr 127.0.0.1:8003 --stun derp.example.com:3478

# GOST side (each end; see play/p2p-tun.yaml in the gost repo)
p2ps:
  - name: p2p-1
    plugin: {type: grpc, addr: 127.0.0.1:8003}
services:
  - name: tun-0
    addr: :0                      # the tun listener binds no socket
    handler: {type: tun, chain: chain-0}      # chain without forwarder = client mode
    listener:
      type: tun
      metadata: {name: p2p0, net: 10.10.0.1/30, mtu: 1420}   # 10.10.0.2/30 on the peer
chains:
  - name: chain-0
    hops:
      - name: hop-0
        nodes:
          - name: node-0
            addr: <peerB-key>     # in p2p mode the addr IS the peer key
            dialer: {type: udp}   # datagram semantics
            connector: {type: forward}   # transparent (the default is http)
            metadata: {p2p: p2p-1}

One channel exists per peer, shared by every tunnel to it and reference-counted: GOST opens a tunnel per dial and closes it on reconnect, so the channel is torn down when the last one closes and rebuilt on the next open. Only the host with the smaller public key opens the peer edge's stream; the other side is served by its normal accept path. A re-dial takes over the local edge (last dial wins), and the peer edge reconnects with backoff across its own downtime while the local edge persists. The link prefers the direct (hole-punched) path and falls back to the relay, exactly like a tunnel. network=udp requires engine mode (--derp): a channel is addressed by peer key.

Bytes are dropped whenever one side has no live edge yet (IP tolerates loss), so a side that has nothing to send yet is still reachable. The data path is unencrypted like the rest of the data plane: there is no inner dialer here to secure it, so run it over a trusted path or add your own encryption above it.

UDP target (a global datagram outlet)

A udp:// --target is a global datagram outlet — a datagram channel's second kind of end, and unlike the per-peer channel it is not bound to any peer. Every inbound datagram stream (a stream prefixed with the P2PU tag) picks a target from the udp pool, dials it, and is bridged to it for the stream's lifetime: the stream's frames become raw IP datagrams at the outlet, and each datagram comes back framed on the stream. The outlet side keeps zero per-peer state — no prebuilt channel, no per-key socket, nothing that outlives a single stream. This is the shape a tun server behind NAT wants: many NAT'd tun clients reach one NAT'd peer that holds a single tun device.

# outlet side: p2p with a udp target pointing at the tun server — no --allow, no per-peer config
./p2p --derp wss://derp.example.com/derp --key outlet.key \
      --target udp://127.0.0.1:8421 --stun derp.example.com:3478

# outlet side: GOST tun SERVER — do NOT set tun.p2p (that flag is the single-peer mode)
#   gost -L "tun://127.0.0.1:8421?net=10.10.0.1/24&keepalive=true&ttl=10s&token=<passphrase>"
#   auther: user = each spoke's tun IP, password = the shared passphrase
#   sysctl -w net.ipv4.ip_forward=1     # to reach a network behind the outlet

The spoke is a stock tun client: net 10.10.0.<n>/24, keepalive: true, the same token, and a route for whatever lies behind the outlet; its chain node addr is the outlet host's key with dialer: udp / connector: forward, exactly like the point-to-point link.

• Two ends, one rendezvous. A datagram channel pairs two ends, and p2p special-cases neither. End (1) is a local GOST udp Tunnel stream — the per-peer channel above, the generic rendezvous a tun-to-tun link uses and a spoke dialling an outlet also uses. End (2) is a udp --target — this global outlet. Which end a host holds is a deployment shape, not a mode. The opener is decided by public-key order (the smaller key opens): the channel side opens through its own loop, while the outlet side — which has no channel — opens when the peer's in-band udp-dial notice arrives; a host that holds a channel never runs that loop too.
• Admission is the caller's, not p2p's. Who may use the outlet is decided above this layer: the tun auther's per-spoke passphrase, the relay's -verify-clients=true, or simply port binding/firewall. An unauthenticated udp:// outlet is equivalent to exposing an unauthenticated tun server on the data plane — put the tun handler's token/passphrase (or an equivalent) in front of it.
• keepalive is the tun app's job, above p2p. The outlet's source port changes whenever the peer edge is (re)established, so the tun server's route (keyed by spoke IP) is refreshed by the tun client's next keepalive — the tun application's responsibility, not a p2p contract. A tun client that never sends keepalive will, after its first reconnect, have the server's downstream pointed at a dead port. Set keepalive on the spokes (their peer is the tun server, which echoes and registers their route); the server-side keepalive/ttl also expires an absent spoke's route instead of black-holing.

--target is repeatable and feeds two pools: a bare host:port is a tcp target (inbound byte-stream tunnels), udp://host:port is a udp target (the outlet above). Multiple udp targets round-robin inbound datagram streams across outlets.

Transport stats

The host reports its direct/relay statistics over the existing gRPC Status RPC, so you can tell whether hole punching actually works for your peers:

grpcurl -plaintext 127.0.0.1:8003 proto.P2P/Status

{
  "tunnels": 4,
  "directPeers": 12, "derpPeers": 3,
  "punchAttempts": 45, "punchSuccess": 15,
  "streamsDirect": 210, "streamsDerp": 30
}

directPeers/derpPeers are gauges — where each peer's traffic goes right now; punch* and streams* are cumulative since start. A punchAttempts that climbs while punchSuccess stays flat means hole punching is being tried and failing (symmetric NAT / CGNAT) — the case IPv6 or port mapping would address. With --token set, add -H 'token: <token>'.

Security

The control channel is unauthenticated by default: any process that can reach --addr can make this host dial arbitrary addresses. Keep --addr on loopback (the default). For cross-machine deployment set --token (the GOST client sends it as gRPC metadata) and control TLS — the token alone travels over a plaintext gRPC channel today.

A DERP relay with -verify-clients=false is an open relay: it sees and can drop the bytes, but never decrypts them. Confidentiality is the inner protocol's job (use mtls/tls/wss inner dialers); the relay is transport, not trust.

A datagram channel is plaintext too: IP packets cross the relay or hole-punched path unencrypted, and unlike a tunnel dialer there is nothing above them in this host to secure them. Run it only over a trusted path, or add your own encryption above the link (GOST's tls/mtls dialers do not apply to a udp tunnel).

A udp outlet shifts admission to the caller: p2p holds none. Who may reach the outlet's tun server is decided above — the tun auther's per-spoke passphrase, the relay's -verify-clients=true, or port binding/firewall. An outlet with nothing in front of it is an unauthenticated tun server exposed on the data plane.

Roadmap

1. STUN + UDP hole-punched tunnels — shipped (KCP + smux direct path, DERP relay as fallback).
2. Rendezvous address discovery — abandoned: derper v1.102.3 only sends PeerPresent to mesh watchers, never to open-relay clients, so presence-driven name discovery is infeasible. Peers are addressed by base64 public key; a human-friendly name belongs in the GOST config, not a p2p-side registry.
3. Datagram channels (tun/tap over the tunnel) — shipped (network=udp): a per-peer byte pipe between the peer's stream and the latest gost tunnel's stream, carried inside the same Tunnel streams. The device itself is GOST's (the tun listener/handler), this host is only the pipe.
4. UDP target outlet — shipped: a udp:// target is a global datagram outlet (stream-level, no per-peer state), so many NAT'd spokes reach one NAT'd peer holding a single tun device (the server's per-IP route table is GOST's). Admission is the caller's.

License

MIT

Documentation

Overview

Package p2p implements a peer-to-peer tunnel host: it exposes gRPC tunnels to a peer and bridges each one to a local target, using a DERP relay for rendezvous and, optionally, a hole-punched direct path.

It runs in two modes. With Config.Derp set, peers are addressed by base64 curve25519 public key and the relay/hole-punch engine carries the tunnel; with it empty ("stub" mode) the peer is a plain host:port dialled directly.

The package is a library. The standalone binary lives in cmd/p2p and is only a flag/config front end over New. An embedder that wants tunnels without a separate process uses:

host, err := p2p.New(&p2p.Config{Derp: url, KeyHex: hexKey})
if err != nil {
	return err
}
defer host.Close()
if err := host.Connect(); err != nil { // engine + configured forwards
	return err
}
conn, err := host.Provider().OpenTunnelStream(ctx, "tcp", peerKey)

Provider opens tunnels in-process over an in-memory stream; the gRPC control plane (Start/Serve) is only needed by out-of-process clients. Both paths run the same data-plane code, so tunnel semantics do not depend on the carrier.

Index

• type Config
  • func LoadConfig(path string) (*Config, error)
  • func (c *Config) TargetList() []string
• type Engine
  • func (e *Engine) Close()
  • func (e *Engine) Connect() error
  • func (e *Engine) OpenStream(peerB64 string) (net.Conn, error)
  • func (e *Engine) PublicKey() string
• type ForwardConfig
• type Host
  • func New(cfg *Config, opts ...Option) (*Host, error)
  • func (h *Host) AddForward(listen, peerKey string) error
  • func (h *Host) Addr() string
  • func (h *Host) Close() error
  • func (h *Host) Connect() error
  • func (h *Host) Provider() *Provider
  • func (h *Host) PublicKey() string
  • func (h *Host) Serve(ln net.Listener) error
  • func (h *Host) Start() (string, error)
  • func (h *Host) Status(ctx context.Context) (*proto.StatusReply, error)
• type LogConfig
• type LogRotationConfig
• type Option
  • func WithLogger(log *slog.Logger) Option
• type Provider
  • func (p *Provider) Close() error
  • func (p *Provider) OpenTunnelStream(ctx context.Context, network, peer string) (net.Conn, error)
• type SmuxTimeouts
• type TLSConfig
• type TimeoutsConfig

Types

type Config

type Config struct {
	Addr     string          `yaml:"addr,omitempty"`
	Token    string          `yaml:"token,omitempty"`
	Derp     string          `yaml:"derp,omitempty"`
	Key      string          `yaml:"key,omitempty"`
	KeyHex   string          `yaml:"keyHex,omitempty"`
	Target   string          `yaml:"target,omitempty"`
	Targets  []string        `yaml:"targets,omitempty"`
	Stun     string          `yaml:"stun,omitempty"`
	Direct   *bool           `yaml:"direct,omitempty"`
	TLS      *TLSConfig      `yaml:"tls,omitempty"`
	Log      *LogConfig      `yaml:"log,omitempty"`
	Timeouts *TimeoutsConfig `yaml:"timeouts,omitempty"`
	Forwards []ForwardConfig `yaml:"forwards,omitempty"`
}

Config is the optional YAML configuration file. Every field mirrors a command-line flag (the flag name without the leading "--"); a config value supplies the default and an explicitly-set flag overrides it.

func LoadConfig

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

LoadConfig reads and parses a YAML config file.

func (*Config) TargetList

func (c *Config) TargetList() []string

TargetList merges the legacy scalar `target` with the `targets` list, scalar first, into the raw spec list the engine parses.

type Engine

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

Engine connects the host to a DERP rendezvous/relay server and turns relayed packets into one smux session per peer. The peer address is the base64 (raw URL) encoding of its 32-byte curve25519 public key — the same string GOST passes to OpenTunnel as "peer".

Data path: every OpenStream on the session is one tunnel; the local endpoint listener bridges onto it exactly like the stub bridges onto a dialed TCP conn. Both peers keep an accept loop and pipe inbound streams to the local --target, so either side can open tunnels.

Session role (smux.Client vs smux.Server) is decided by public-key ordering so both ends always agree on exactly one session per pair regardless of who dials first. smux allows either side to open streams.

func (*Engine) Close

func (e *Engine) Close()

Close shuts the engine down.

func (*Engine) Connect

func (e *Engine) Connect() error

Connect dials the relay eagerly (used at startup so inbound tunnels work immediately instead of waiting for the reconnect ticker).

func (*Engine) OpenStream

func (e *Engine) OpenStream(peerB64 string) (net.Conn, error)

OpenStream opens a tunnel stream to the peer, establishing the DERP connection and mux session on first use. An established direct (hole-punched) session is preferred; on any failure it falls back to the relay session. The returned connection is tagged with the transport it uses ("direct" or "derp") so the caller can log which path the tunnel took.

func (*Engine) PublicKey

func (e *Engine) PublicKey() string

PublicKey returns the engine's public key, base64 (raw URL) encoded — the string other hosts put in their GOST node addr.

type ForwardConfig

type ForwardConfig struct {
	Listen string `yaml:"listen,omitempty"`
	Peer   string `yaml:"peer,omitempty"`
}

ForwardConfig is a pre-configured static port forward: bind Listen and bridge accepted connections to the peer's public key.

type Host

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

Host is a p2p endpoint. It owns the DERP engine (when a relay URL is configured), the gRPC control plane, and the tunnel bookkeeping. It can run standalone as the CLI does (Start + Close) or be embedded in-process (Connect + Provider).

func New

func New(cfg *Config, opts ...Option) (*Host, error)

New builds a Host from cfg. It performs no network I/O: the DERP connection is deferred to Connect, and all listeners are bound by Connect/Start.

func (*Host) AddForward

func (h *Host) AddForward(listen, peerKey string) error

AddForward binds a static endpoint and bridges it to peer (DERP mode only). listen is the local address, peerKey a base64 public key.

func (*Host) Addr

func (h *Host) Addr() string

Addr returns the resolved gRPC listen address, or "" before Start/Serve.

func (*Host) Close

func (h *Host) Close() error

Close shuts the host down: the gRPC server and listener, the static forward listeners, the DERP engine, and the pending-tunnel GC. It is idempotent.

func (*Host) Connect

func (h *Host) Connect() error

Connect establishes the DERP engine connection and applies the configured static forwards. It is idempotent: only the first call performs work and its error is remembered.

A failed DERP connection is not fatal — the engine retries in the background and inbound tunnels stay unreachable until it connects — so Start logs it and continues. Embedding callers that need strict startup can check the error.

func (*Host) Provider

func (h *Host) Provider() *Provider

Provider returns an in-process tunnel provider backed by h.

func (*Host) PublicKey

func (h *Host) PublicKey() string

PublicKey returns the host's base64 DERP public key, or "" in stub mode.

func (*Host) Serve

func (h *Host) Serve(ln net.Listener) error

Serve connects the engine and blocks, serving the gRPC control plane on ln.

func (*Host) Start

func (h *Host) Start() (string, error)

Start connects the engine and begins serving the gRPC control plane on Config.Addr in the background. It returns the resolved listen address, which is useful with ":0".

func (*Host) Status

func (h *Host) Status(ctx context.Context) (*proto.StatusReply, error)

Status reports transport stats and the live tunnel count.

type LogConfig

type LogConfig struct {
	Level    string             `yaml:"level,omitempty"`
	Format   string             `yaml:"format,omitempty"`
	Output   string             `yaml:"output,omitempty"`
	Rotation *LogRotationConfig `yaml:"rotation,omitempty"`
}

LogConfig mirrors the --log.* flags plus file rotation.

type LogRotationConfig

type LogRotationConfig struct {
	MaxSize    int  `yaml:"maxSize,omitempty"`
	MaxAge     int  `yaml:"maxAge,omitempty"`
	MaxBackups int  `yaml:"maxBackups,omitempty"`
	LocalTime  bool `yaml:"localTime,omitempty"`
	Compress   bool `yaml:"compress,omitempty"`
}

LogRotationConfig configures lumberjack file rotation for a file output. Zero values fall back to lumberjack's defaults (100 MB, keep all, UTC, no compression).

type Option

type Option func(*Host)

Option configures a Host.

func WithLogger

func WithLogger(log *slog.Logger) Option

WithLogger sets the logger used by the host, its engine, and its server. Defaults to slog.Default().

type Provider

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

Provider exposes a Host as a tunnel provider for in-process use: it opens tunnels without a loopback gRPC control plane.

Close stops the provider from accepting new tunnels; it does not tear down the Host or any already-open tunnel. Those end with their own connections, exactly as the gRPC path's streams do.

func (*Provider) Close

func (p *Provider) Close() error

Close stops accepting new tunnels. It is safe to call more than once.

func (*Provider) OpenTunnelStream

func (p *Provider) OpenTunnelStream(ctx context.Context, network, peer string) (net.Conn, error)

OpenTunnelStream opens a tunnel to peer and returns its local end. network is normalized here (udp/udp4/udp6 -> udp), so callers may pass any dialer network. peer carries the same meaning as on the gRPC path: a base64 public key in DERP mode, a host:port in stub mode.

ctx only bounds the call itself (allocation); the tunnel outlives it. The peer dial runs in the tunnel's serve goroutine, so the returned conn — not ctx — is the cancellation handle: closing it tears the tunnel down.

type SmuxTimeouts

type SmuxTimeouts struct {
	Interval time.Duration `yaml:"interval,omitempty"`
	Timeout  time.Duration `yaml:"timeout,omitempty"`
}

SmuxTimeouts tunes the smux keepalive shared by the relay and direct sessions. Timeout must be >= 2x Interval (validated in applyTimeouts).

type TLSConfig

type TLSConfig struct {
	Secure *bool  `yaml:"secure,omitempty"`
	CAFile string `yaml:"caFile,omitempty"`
}

TLSConfig mirrors the --tls.* flags. Secure is a pointer so an omitted "secure" (default true) is distinguishable from an explicit "secure: false".

type TimeoutsConfig

type TimeoutsConfig struct {
	PunchWait     time.Duration `yaml:"punchWait,omitempty"`
	Punch         time.Duration `yaml:"punch,omitempty"`
	Seed          time.Duration `yaml:"seed,omitempty"`
	Backoff       time.Duration `yaml:"backoff,omitempty"`
	DerpKeepAlive time.Duration `yaml:"derpKeepAlive,omitempty"`
	Smux          *SmuxTimeouts `yaml:"smux,omitempty"`
}

TimeoutsConfig tunes deployment-dependent timings. Zero values keep the built-in defaults; internal mechanism timeouts stay hardcoded.