/ 
Net-BitTorrent-v2.0.1
River stage zero No dependents
⭐ Starred 13 GitHub stars
/ README.md

NAME

Net::BitTorrent - Complete, Modern BitTorrent Client Library

SYNOPSIS

use v5.40;
use Net::BitTorrent;
use Net::BitTorrent::Types qw[:encryption];

# Initialize the client
my $client = Net::BitTorrent->new(
    upnp_enabled => 1,
    encryption   => ENCRYPTION_REQUIRED # or 'required'
);

# Unified add() handles magnets, .torrents, or v1/v2 infohashes
# Supports 20/32-byte binary or 40/64-character hex strings
my $torrent = $client->add("magnet:?xt=urn:btih:...", "./downloads");

# Simple event handling
$client->on(torrent_added => sub ($nb, $t) {
    say "New swarm added: " . $t->name;
    $t->start();
});

# Advanced: Manual event loop integration
# while (1) {
#     $client->tick(0.1);
#     select(undef, undef, undef, 0.1);
# }

# Wait for all downloads to finish
$client->wait();

# Graceful shutdown
$client->shutdown();

DESCRIPTION

Net::BitTorrent is a comprehensive, high-performance BitTorrent client library rewritten from the ground up for Modern Perl (v5.40+) using the native class feature.

The library is designed around three core principles:

How Everything Fits Together

Net::BitTorrent uses a hierarchical architecture to manage the complexities of the protocol:

1. The Client (Net::BitTorrent)

The entry point. It manages multiple swarms, global rate limits, decentralized discovery (DHT/LPD), and unified UDP packet routing. It also provides a centralized "hashing queue" to prevent block verification from starving your CPU.

2. Torrents (Net::BitTorrent::Torrent)

Orchestrates a single swarm. It manages its own list of discovered peers, the Piece Picker (rarest-first logic), and communicates with the Trackers. It acts as the bridge between the network (Peers) and the local disk (Storage).

3. Peers (Net::BitTorrent::Peer)

Tracks the state of a single connection (choking, interested, transfer rates). It uses a Protocol Handler to speak the wire protocol and a Net::BitTorrent::Transport (TCP or uTP) to move bytes.

4. Storage (Net::BitTorrent::Storage)

Manages files on disk. It uses Merkle trees for per-block verification (v2) and handles the "virtual contiguous file" mapping required for v1 compatibility. It includes an asynchronous disk cache to keep the main loop fast.

METHODS

new( %params )

Creates a new client instance.

my $client = Net::BitTorrent->new(
    port         => 6881,
    encryption   => 'required', # 'none', 'preferred', or 'required'
    upnp_enabled => 1
);

This method initializes the BitTorrent engine with custom configuration.

Expected parameters:

on( $event, $callback )

Registers a global callback for client-level events.

$client->on(torrent_added => sub ($nb, $torrent) {
    warn "Added: " . $torrent->name;
});

This method allows you to react to system-wide changes or automate actions for newly added swarms.

Expected parameters:

add( $thing, $base_path, [%args] )

The recommended, unified method for adding a swarm.

# Add a .torrent file
$client->add("ubuntu.torrent", "./iso");

# Add a magnet link
$client->add("magnet:?xt=urn:btih:...", "./data");

This method automatically detects the type of the first parameter and adds the corresponding swarm. It returns a Net::BitTorrent::Torrent object on success.

Expected parameters:

add_torrent( $path, $base_path, [%args] )

Adds a torrent from a local .torrent file.

my $t = $client->add_torrent("linux.torrent", "/downloads");

This method is for adding a swarm specifically from a metadata file. It returns a Net::BitTorrent::Torrent object.

Expected parameters:

add_infohash( $ih, $base_path, [%args] )

Adds a torrent by its info hash.

my $t = $client->add_infohash(pack('H*', '...'), './data');

This method is useful for bootstrapping a swarm when only the hash is known. It returns a Net::BitTorrent::Torrent object.

Expected parameters:

add_magnet( $uri, $base_path, [%args] )

Adds a torrent from a Magnet URI.

my $t = $client->add_magnet("magnet:?xt=urn:btmh:...", "./data");

This method allows adding resources from web links. It returns a Net::BitTorrent::Torrent object.

Expected parameters:

torrents( )

Returns a list of all active torrents.

my $list = $client->torrents( );

This method returns an array reference containing all currently managed Net::BitTorrent::Torrent objects.

finished( )

Returns a list of completed torrents.

my $done = $client->finished();

This method returns an array reference of all managed torrents that have completed their download.

wait( [$condition], [$timeout] )

Blocks execution until a condition is met.

$client->wait();

This method runs the internal event loop until the provided condition returns true or a timeout is reached. It returns a boolean indicating if the condition was met.

Expected parameters:

tick( [$timeout] )

The "heartbeat" of the library.

$client->tick(0.1);

This method performs discovery, updates swarm logic, and handles network I/O.

Expected parameters:

save_state( $path )

Persists session state to a file.

$client->save_state('session.json');

This method saves the current client state to a JSON file.

Expected parameters:

load_state( $path )

Restores session state from a file.

$client->load_state('session.json');

This method loads client state from a JSON file.

Expected parameters:

dht_get( $target, $callback )

Retrieves data from the DHT.

$client->dht_get($target_hash, sub ($value, $node) { ... });

This method initiates a DHT lookup for the specified target hash.

Expected parameters:

dht_put( $value, [$callback] )

Stores data in the DHT.

$client->dht_put('My Shared Note');

This method stores immutable data in the DHT.

Expected parameters:

dht_scrape( $infohash, $callback )

Performs a decentralized scrape.

$client->dht_scrape($infohash, sub ($stats) { ... });

This method queries the DHT for seeder and leecher counts.

Expected parameters:

shutdown( )

Gracefully stops the client.

$client->shutdown();

This method stops all swarms, unmaps ports, and releases resources.

features( )

Returns the enabled features.

my $f = $client->features();

This method returns a hash reference containing the status of various BEPs.

set_limit_down( $val )

Sets the global download rate limit.

$client->set_limit_down( 1024 * 1024 ); # 1MiB/s

This method sets the maximum download rate in bytes per second.

Expected parameters:

hashing_queue_size( )

Returns the number of pieces waiting for verification.

my $size = $client->hashing_queue_size();

This method returns the current size of the background hashing queue.

queue_verification( $torrent, $index, $data )

Queues a piece for background verification.

$client->queue_verification( $torrent, $index, $data );

This method adds a piece to the throttled background hashing queue.

Expected parameters:

SUPPORTED BEPS

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.