=pod

=encoding utf-8

=head1 NAME

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

=head1 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";
    });

=head1 DESCRIPTION

C<Net::BitTorrent::Protocol::BEP55> implements the B<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 C<ut_holepunch>.

=head1 METHODS

=head2 C<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:

=over

=item C<$target_id>

The 20-byte binary peer ID of the target.

=back

=head2 C<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:

=over

=item C<$ip>

The IP address.

=item C<$port>

The port number.

=back

=head2 C<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:

=over

=item C<$err_code>

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

=back

=head2 C<hp_rendezvous> event

Emitted when a rendezvous request is received.

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

Expected parameters:

=over

=item C<$id>

The target peer ID.

=back

=head2 C<hp_connect> event

Emitted when a connect instruction is received.

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

Expected parameters:

=over

=item C<$ip>

The IP to connect to.

=item C<$port>

The port to connect to.

=back

=head2 C<hp_error> event

Emitted when a holepunch error is received.

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

Expected parameters:

=over

=item C<$err>

The error code.

=back

=head1 Specifications

=over

=item * B<BEP 55>: Holepunching

=back

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=head1 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.

=cut
