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

NAME

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

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

DESCRIPTION

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

Protocol Support

The manager automatically detects and handles multiple tracker protocols:

  • UDP (BEP 15): Lightweight, preferred transport.

  • HTTP/HTTPS: Standard bencoded announce protocol.

METHODS

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:

tiers_raw

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

debug - optional

Whether to enable debug logging.

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:

\%params

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

$callback - optional

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

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:

\@infohashes

An array reference of binary infohashes to scrape.

$callback - optional

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

trackers( )

Returns a list of all tracker URLs.

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

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

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:

$delta

The time elapsed since the last tick in seconds.

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:

$url

The URL of the tracker to add.

SEE ALSO

Net::BitTorrent::Tracker::HTTP, Net::BitTorrent::Tracker::UDP

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.