=pod

=encoding utf-8

=head1 NAME

Net::BitTorrent::Peer - Individual Peer Connection & State Tracking

=head1 SYNOPSIS

    use Net::BitTorrent::Types qw[:encryption];

    # Usually managed automatically by Net::BitTorrent::Torrent
    my $peer = Net::BitTorrent::Peer->new(
        protocol   => $handler,
        torrent    => $torrent,
        transport  => $tcp_transport,
        ip         => '1.2.3.4',
        port       => 6881,
        encryption => ENCRYPTION_REQUIRED
    );

    # Access transport layer
    my $transport = $peer->transport;

    # Manual choking control
    $peer->unchoke( );

    # Check peer state
    say 'Peer is interested' if $peer->peer_interested;
    say 'Download rate: ' . ($peer->rate_down / 1024) . ' KB/s';

=head1 DESCRIPTION

C<Net::BitTorrent::Peer> represents a single connection to a remote BitTorrent client. It maintains the
choking/interested state machine and handles all message routing for a specific neighbor.

=head2 Reputation & Security

This class implements peer reputation tracking to protect the swarm from malicious or buggy clients:

=over

=item * Peers start with a reputation of 100.

=item * Providing a verified piece increases reputation by 1.

=item * Providing a corrupt piece (failed hash) decreases reputation by 20.

=item * If reputation falls to B<50 or below>, the peer is automatically disconnected and blacklisted for the session.

=item * The score is capped only by the number of successful transfers (can exceed 100).

=back

=head1 METHODS

=head2 C<new( %params )>

Parameters;

=over

=item * C<encryption>: (default C<ENCRYPTION_PREFERRED>) Connection security policy (C<ENCRYPTION_NONE>, C<ENCRYPTION_PREFERRED>, C<ENCRYPTION_REQUIRED>). Supports both constants and strings ('none', 'preferred', 'required').

=item * C<transport>: An instance of L<Net::BitTorrent::Transport::TCP> or L<Net::uTP::Connection>.

=item * C<protocol>: An instance of L<Net::BitTorrent::Protocol::PeerHandler>.

=back

=head2 C<unchoke( )> / C<choke( )>

Sends a C<CHOKE> or C<UNCHOKE> message to the peer. This controls whether the remote peer is allowed to request blocks
from us.

=head2 C<send_suggest( $index )> / C<send_allowed_fast( $index )>

Sends B<BEP 06> Fast Extension hints to the peer.

=head2 C<rate_down( )> / C<rate_up( )>

Returns the current transfer rates in B<bytes per second>, calculated via a 20% moving average decay.

=head2 C<reputation( )>

Returns the current reputation score.

=head2 C<am_choking( )> / C<peer_choking( )>

Returns the current choking status for both sides of the connection.

=head2 C<am_interested( )> / C<peer_interested( )>

Returns the current interest status.

=head2 C<adjust_reputation( $delta )>

Manually adjust the peer's reputation score. Triggers an automatic disconnect if the score drops below 50.

=head1 Specifications

=over

=item * B<BEP 03>: Core Peer Wire Protocol

=item * B<BEP 06>: Fast Extension (HAVE_ALL, HAVE_NONE, SUGGEST, ALLOWED_FAST)

=item * B<BEP 10>: Extension Protocol support

=item * B<BEP 11>: PEX (Peer Exchange) data handling

=item * B<BEP 16>: Super-seeding support

=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
