NAME
Net::BitTorrent::Protocol::PeerHandler - High-level Peer Protocol Orchestrator
SYNOPSIS
# Inherits from BEP 06, which inherits from BEP 52, then BEP 11, etc.
use Net::BitTorrent::Protocol::PeerHandler;
my $handler = Net::BitTorrent::Protocol::PeerHandler->new(
infohash => $ih,
peer_id => $id,
features => { bep06 => 1, bep10 => 1 }
);
# Link to the high-level Peer object
$handler->set_peer( $peer );
# Feed raw data from the transport
$handler->receive_data( $raw_bytes );DESCRIPTION
Net::BitTorrent::Protocol::PeerHandler is the "brain" of the Peer Wire Protocol implementation. It utilizes multiple inheritance (via the class feature) to consolidate all supported BitTorrent extensions into a single, unified interface.
It works closely with Net::BitTorrent::Peer to manage the lifecycle of a connection:
- 1. Handshake: Negotiates protocol version (v1 vs v2) and reserved bits.
- 2. Extensions: If BEP 10 is negotiated, it exchanges extended handshakes to discover support for PEX, Metadata, etc.
- 3. Steady State: Dispatches standard messages (Piece, Request) and extensions (PEX, Merkle hashes) to the high-level Peer object.
Supported Extensions:
BEP 03: Standard Handshake and Core Messages (Choke, Have, Request, etc.)
BEP 06 (Fast): Reduced latency messages (Allowed Fast, Suggest Piece, Reject)
BEP 09 (Metadata): UT_METADATA exchange for Magnet links.
BEP 10 (Extension): Capability negotiation.
BEP 11 (PEX): Peer Exchange.
BEP 52 (v2): Merkle Tree synchronization (HASHES, HASH_REQUEST).
BEP 55 (Holepunch): NAT traversal support.
METHODS
set_peer( $peer )
Associates the handler with a Peer object.
$handler->set_peer( $peer_obj );Expected parameters:
$peer-
The Net::BitTorrent::Peer object.
handshake event
Emitted when a PWP handshake is completed.
$proto->on( handshake => sub ( $self, $infohash, $peer_id ) { ... } );Expected parameters:
ext_handshake event
Emitted when an extended handshake is received.
$proto->on( ext_handshake => sub ( $self, $data ) { ... } );Expected parameters:
metadata_request event
Emitted when a metadata request is received.
$proto->on( metadata_request => sub ( $self, $piece ) { ... } );Expected parameters:
metadata_data event
Emitted when metadata data is received.
$proto->on( metadata_data => sub ( $self, $piece, $total_size, $data ) { ... } );Expected parameters:
metadata_reject event
Emitted when a metadata request is rejected.
$proto->on( metadata_reject => sub ( $self, $piece ) { ... } );Expected parameters:
hash_request event
Emitted when a Merkle tree hash request is received (BEP 52).
$proto->on( hash_request => sub ( $self, $root, $proof_layer, $base_layer, $index, $length ) { ... } );Expected parameters:
$root-
The 32-byte Merkle root.
$proof_layer-
The proof layer index.
$base_layer-
The base layer index.
$index-
The starting index.
$length-
The number of hashes.
hashes event
Emitted when Merkle tree hashes are received.
$proto->on( hashes => sub ( $self, $root, $proof_layer, $base_layer, $index, $length, $hashes ) { ... } );Expected parameters:
$root-
The 32-byte Merkle root.
$proof_layer-
The proof layer.
$base_layer-
The base layer.
$index-
The starting index.
$length-
The number of hashes.
$hashes-
The binary hashes.
hash_reject event
Emitted when a hash request is rejected.
$proto->on( hash_reject => sub ( $self, $root, $proof_layer, $base_layer, $index, $length ) { ... } );Expected parameters:
$root-
The 32-byte Merkle root.
$proof_layer-
The proof layer.
$base_layer-
The base layer.
$index-
The starting index.
$length-
The number of hashes.
pex event
Emitted when PEX data is received.
$proto->on( pex => sub ( $self, $added, $dropped, $added6, $dropped6 ) { ... } );Expected parameters:
$added-
Added IPv4 peers.
$dropped-
Dropped IPv4 peers.
$added6-
Added IPv6 peers.
$dropped6-
Dropped IPv6 peers.
hp_rendezvous event
Emitted when a holepunch rendezvous is requested.
$proto->on( hp_rendezvous => sub ( $self, $id ) { ... } );Expected parameters:
hp_connect event
Emitted when a holepunch connect instruction is received.
$proto->on( hp_connect => sub ( $self, $ip, $port ) { ... } );Expected parameters:
hp_error event
Emitted when a holepunch error is received.
$proto->on( hp_error => sub ( $self, $err ) { ... } );Expected parameters:
peer( )
Returns the associated Peer object.
my $p = $handler->peer();AUTHOR
Sanko Robinson <sanko@cpan.org>
COPYRIGHT
Copyright (C) 2008-2026 by Sanko Robinson.
This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.