/ 
Net-BitTorrent-v2.0.0-20260209033804-TRIAL
/ Net::BitTorrent::Protocol::PeerHandler

NAME

Net::BitTorrent::Protocol::PeerHandler - Integrated Protocol Extension 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_object )

Associates the low-level protocol handler with a high-level Net::BitTorrent::Peer object. The handler will dispatch parsed events (like on_pex or on_metadata_data) to the peer.

_handle_message( $id, $payload )

Internal dispatcher that validates message IDs against enabled features. For example, if BEP 06 is disabled, Fast Extension message IDs are ignored.

CALLBACKS (EVENT DISPATCH)

This class implements various on_* methods defined by the individual BEP modules. It acts as the implementation layer that connects wire-format data to application logic:

  • on_pex: Forwards discovered peers to the swarm manager.

  • on_hash_request: Initiates Merkle tree lookups in the storage layer.

  • on_metadata_request: Serves info dictionary pieces from local memory.

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.