=pod

=encoding utf-8

=head1 NAME

Net::BitTorrent::Tracker - Multi-tier Tracker Manager

=head1 SYNOPSIS

    use Net::BitTorrent::Tracker;

    my $manager = Net::BitTorrent::Tracker->new(
        tiers_raw => [
            ['udp://tracker.openbittorrent.com:80/announce'],
            ['http://tracker.example.com/announce', 'https://another.net/announce']
        ]
    );

    # Announce presence and get peers
    $manager->announce_all({
        infohash   => $bin_ih,
        peer_id    => $my_id,
        port       => 6881,
        downloaded => 0,
        uploaded   => 0,
        left       => 1024,
        event      => 'started'
    }, sub ($peers) {
        say "Found " . scalar(@$peers) . " peers!";
    });

=head1 DESCRIPTION

C<Net::BitTorrent::Tracker> manages communication with external trackers. It implements the Multi-tracker Metadata (BEP
12) specification, handling tiers, retries, and backoff logic.

=head2 Protocol Support

The manager automatically detects and handles multiple tracker protocols:

=over

=item * B<UDP (BEP 15)>: Lightweight, preferred transport.

=item * B<HTTP/HTTPS>: Standard bencoded announce protocol.

=back

=head1 METHODS

=head2 C<new( %params )>

Creates a new Tracker manager.

    my $manager = Net::BitTorrent::Tracker->new(
        tiers_raw => [ ['http://tracker.example.com/announce'] ]
    );

This method initializes the tracker manager with a list of tracker tiers.

Expected parameters:

=over

=item C<tiers_raw>

An array reference of array references, where each inner array contains tracker URLs for a single tier.

=item C<debug> - optional

Whether to enable debug logging.

=back

=head2 C<announce_all( \%params, [$callback] )>

Announces to all tracker tiers.

    $manager->announce_all({
        infohash => $ih,
        peer_id  => $id,
        port     => 6881,
        left     => 1000
    }, sub ($peers) { ... });

This method iterates through tracker tiers (BEP 12), announcing presence and gathering peers. It returns an array
reference of unique peer structures discovered.

Expected parameters:

=over

=item C<\%params>

Standard announce parameters (infohash, peer_id, port, uploaded, downloaded, left, event).

=item C<$callback> - optional

A code reference called with an arrayref of peer structures ({ip, port}) when peers are received.

=back

=head2 C<scrape_all( \@infohashes, [$callback] )>

Scrapes all trackers for swarm stats.

    $manager->scrape_all([$ih1, $ih2], sub ($stats) { ... });

This method queries all trackers for seeder/leecher counts (BEP 48). It returns a hash reference of statistics.

Expected parameters:

=over

=item C<\@infohashes>

An array reference of binary infohashes to scrape.

=item C<$callback> - optional

A code reference called with a hash reference of statistics per infohash.

=back

=head2 C<trackers( )>

Returns a list of all tracker URLs.

    my $list = $manager->trackers();

This method returns a flattened array reference of all managed tracker URLs.

=head2 C<tick( $delta )>

Performs periodic maintenance for all trackers.

    $manager->tick( 0.1 );

This method allows individual tracker objects to process timeouts and retransmissions.

Expected parameters:

=over

=item C<$delta>

The time elapsed since the last tick in seconds.

=back

=head2 C<add_tracker( $url )>

Adds a new tracker to the manager.

    $manager->add_tracker( 'udp://new.tracker.com:6969/announce' );

This method adds a new tracker URL as a new tier if it is not already present.

Expected parameters:

=over

=item C<$url>

The URL of the tracker to add.

=back

=head1 SEE ALSO

L<Net::BitTorrent::Tracker::HTTP>, L<Net::BitTorrent::Tracker::UDP>

=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
