/ 
Net-BitTorrent-v2.0.0
River stage zero No dependents
⭐ Starred 13 GitHub stars
/ Net::BitTorrent::Protocol::BEP55

NAME

Net::BitTorrent::Protocol::BEP55 - Holepunching Extension (NAT Traversal)

SYNOPSIS

# Inherits from Net::BitTorrent::Protocol::BEP11
use Net::BitTorrent::Protocol::BEP55;

my $p = Net::BitTorrent::Protocol::BEP55->new(...);

# Ask a mutual peer to introduce us to a target
$p->send_hp_rendezvous($target_peer_id);

# Handle incoming connection requests
$p->on(hp_connect => sub ( $emitter, $ip, $port ) {
    say "Attempting holepunch connect to $ip:$port";
});

DESCRIPTION

Net::BitTorrent::Protocol::BEP55 implements the Holepunching Extension (BEP 55). This extension allows two peers who are both behind NAT (Network Address Translation) to coordinate a simultaneous UDP connection (uTP) using a third, mutually connected peer as a signaling relay.

It runs as a sub-protocol of the Extension Protocol (BEP 10) under the name ut_holepunch.

METHODS

send_hp_rendezvous( $target_id )

Requests a rendezvous with a target peer.

$p->send_hp_rendezvous( $target_peer_id );

This method asks the peer to act as a mediator to coordinate a holepunch with another peer.

Expected parameters:

$target_id

The 20-byte binary peer ID of the target.

send_hp_connect( $ip, $port )

Instructs a peer to connect to a specific address.

$p->send_hp_connect( '1.2.3.4', 6881 );

This method is sent by the mediator to the target peer, instructing it to initiate a uTP connection.

Expected parameters:

$ip

The IP address.

$port

The port number.

send_hp_error( $err_code )

Sends a holepunch error.

$p->send_hp_error( 0x01 );

This method informs the requester that the holepunch operation failed.

Expected parameters:

$err_code

The error code (e.g., 0x01 for peer not found).

hp_rendezvous event

Emitted when a rendezvous request is received.

$p->on( hp_rendezvous => sub ( $self, $id ) { ... } );

Expected parameters:

$id

The target peer ID.

hp_connect event

Emitted when a connect instruction is received.

$p->on( hp_connect => sub ( $self, $ip, $port ) { ... } );

Expected parameters:

$ip

The IP to connect to.

$port

The port to connect to.

hp_error event

Emitted when a holepunch error is received.

$p->on( hp_error => sub ( $self, $err ) { ... } );

Expected parameters:

$err

The error code.

Specifications

  • BEP 55: Holepunching

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.