pex

package

v0.0.2 Latest Latest Go to latest Published: Mar 8, 2026 License: MIT Imports: 6 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/cbluth/bittorrent

Links

Open Source Insights

Documentation ¶

Overview ¶

Package pex implements Peer Exchange (PEX) as specified in BEP 11. https://www.bittorrent.org/beps/bep_0011.html

PEX is a BEP 10 extension negotiated via the key "ut_pex" in the extension handshake. Once negotiated, peers periodically send each other lists of peers they know about for the same torrent, giving the client a third peer source (alongside trackers and DHT).

Wire format ¶

Each ut_pex message payload is a bencoded dict with up to six byte-string fields:

d
  6:added    <n*6  bytes>  compact IPv4: 4-byte BE IP + 2-byte BE port
  7:added.f  <n    bytes>  flags, one byte per IPv4 peer in "added"
  6:added6   <n*18 bytes>  compact IPv6: 16-byte IP + 2-byte BE port
  8:added6.f <n    bytes>  flags, one byte per IPv6 peer in "added6"
  7:dropped  <m*6  bytes>  compact IPv4 peers no longer seen
  8:dropped6 <m*18 bytes>  compact IPv6 peers no longer seen
e

Keys absent means no peers of that type. "dropped" peers have no flags.

Peer flags (1 byte per peer in "added[6].f") ¶

0x01  prefers encrypted connections (MSE/BEP 8)
0x02  seeder (has all pieces)
0x04  supports uTP (BEP 29)
0x08  supports holepunch (BEP 55)
0x10  outgoing connection (we dialled them)

Message cadence ¶

The first message sent to a new peer is a full snapshot of all currently connected peers. Subsequent messages are diffs: only newly-connected peers appear in "added", only disconnected peers appear in "dropped". Clients MUST NOT send a PEX message more than once per 60 seconds.

Index ¶

Constants
func Encode(msg *Message) ([]byte, error)
type Message
- func Decode(data []byte) (*Message, error)
type PeerInfo
type State
- func NewState() *State
- func (s *State) BuildMessage(current []PeerInfo) (*Message, error)

Constants ¶

View Source

const (
	FlagEncryption byte = 0x01 // Peer prefers encrypted connections (MSE)
	FlagSeed       byte = 0x02 // Peer is a seeder
	FlagUTP        byte = 0x04 // Peer supports uTP (BEP 29)
	FlagHolepunch  byte = 0x08 // Peer supports holepunch (BEP 55)
	FlagOutgoing   byte = 0x10 // We initiated the connection to this peer
)

View Source

const (
	// MinInterval is the minimum time between PEX messages per peer connection.
	MinInterval = 60 * time.Second

	// MaxPeersPerMessage is the maximum number of peers in a single PEX message.
	// Split evenly between IPv4 and IPv6 when both are present.
	MaxPeersPerMessage = 50
)

Variables ¶

This section is empty.

Functions ¶

func Encode ¶

func Encode(msg *Message) ([]byte, error)

Encode serialises a Message into the bencoded wire format expected for a ut_pex extension message payload.

Types ¶

type Message ¶

type Message struct {
	Added   []PeerInfo // peers seen since last message (or full snapshot on first send)
	Dropped []PeerInfo // peers no longer seen (empty in snapshot)
}

Message is a decoded ut_pex payload.

func Decode ¶

func Decode(data []byte) (*Message, error)

Decode parses a bencoded ut_pex payload into a Message. Unknown fields and malformed compact entries are silently skipped.

type PeerInfo ¶

type PeerInfo struct {
	Addr  *net.TCPAddr
	Flags byte
}

PeerInfo is a single peer entry as carried by PEX.

type State ¶

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

State tracks what we have already advertised to one specific peer connection so we can compute correct diffs for subsequent PEX messages.

One State should be created per peer connection and discarded when the connection closes. It is safe for concurrent use.

func NewState ¶

func NewState() *State

NewState creates a fresh PEX State for a new peer connection.

func (*State) BuildMessage ¶

func (s *State) BuildMessage(current []PeerInfo) (*Message, error)

BuildMessage computes the next PEX Message to send to the remote peer, given the caller's current view of all connected peers (current).

The first call returns a full snapshot (all current peers in Added, nothing in Dropped). Subsequent calls return diffs relative to what was last announced.

Returns (nil, nil) if the MinInterval has not elapsed since the last send. The caller should encode the returned Message with Encode and send it as a BEP 10 extension message with the negotiated ut_pex extension ID.

Source Files ¶

View all Source files

pex.go

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