Net::BitTorrent::Notes - Annotated Guide to the Ins and Outs of Net::BitTorrent
This is a first draft attempt at defining a road map for future Net::BitTorrent development and a behavioral reference for third-party client developers.
A few bits for users might slip in too.
.---- N::B::T::T::UDP
/
.-------- N::B::T::Tracker
/ \
/ .-- N::B::T::File `--- N::B::T::T::HTTP
/ /
.---- Net::BitTorrent::Torrent
/
/ .--- Net::BitTorrent::DHT
/ /
Net::BitTorrent
\
`---- Net::BitTorrent::Peer
The following utility modules also come with the distribution and will be of great use if you decide to whip together your own BitTorrent module.
Net::BitTorrent::ProtocolCorrectly builds and parses all known BitTorrent packets.
Net::BitTorrent::UtilContains basic functions to parse and create .torrent metadata files, and compact peer lists from trackers.
To pick and choose which functions will be exported into your namespace from these modules, see their POD documentation for more information.
This distribution uses Module::Build for installation, so use the following procedure:
perl Build.PL ./Build ./Build test ./Build install
See also: Automated Test Reports
Net::BitTorrent requires version and Digest::SHA. On Win32, we try to use Win32API::File and Encode to handle extended charset filenames[1]. As of perl 5.10, all of these modules are are CORE; they come bundled with the distribution.
I have listed these modules as prerequisites in Build.PL so, unless you answer 'no' when prompted, the CPAN shell should automagically install them for you.
We also use the internal utf8() functions which didn't appear until perl 5.8.1.
Parts that aren't handled internally are described here (eventually) with sample code to get you started.
Net::BitTorrent::Torrent objects can be created directly without a parent client. While functionally limited (obvious things like an inability to serve data, etc.) basic information is available and some 'advanced' functions still work (hashchecking, for example). See Net::BitTorrent::Torrent for more.
See Net::BitTorrent::Torrent::pause( ) and Net::BitTorrent::Torrent::start( )
See See Net::BitTorrent::Torrent::stop( ) and Net::BitTorrent::Torrent::start( )
Note: This section describes resume functionality as of v0.045.
Net::BitTorrent is capable of restoring the state of single torrents between sessions. To store resume data, use the save_resume_data( )
To resume a single torrent, use a variation of the following to save the data...
my $torrent = $bt->add_torrent( { Path=> 'some.torrent', Resume = '.resume' });
# later...
$torrent->save_resume_data();
...and unless Net::BitTorrent::Torrent decides the resume data is bad, you'll start right were you left off. I would suggest storing resume data on a regular basis while the client runs and again on exit.
To view a fully functioning example, see /tatoeba/004-resume.pl.
For more on what exactly you're saving and the structure of the data, see Resume API in the <Net::BitTorrent Internals|/"Net::BitTorrent Internals"> section.
Unless you've hard coded everything, being able to restore client-wide state is a necessary feature. Besides, DHT can be very slow to boot without a good set of initial nodes and the spec states that the local nodeID should not change very often, so resume is a useful thing.
I would use a hash with the following keys:
.hashThis would be a SHA-1 hash of the bencoded data in the .t, dht, nodes, and torrents keys. On restore, I would use this to validate the data in case it was tampered with.
.tTimestamp.
.versionTo avoid problems (API changes, etc.), I would use an API version number and ignore resume data created with a newer/incompatible version. This value would not be included in the SHA-1 digest used to prevent tampering.
dhtA hash with the following keys:
idThe local node ID used in the DHT swarm. To obtain this, see node_id( ).
nodesList of nodes in the DHT routing table.
To make life easy, each node would be a hash with the following keys:
A list of nodes with this format is obtained from nodes ( ). To reload these later, use the add_node ( ) method.
settingsThese would be any client-wide settings I allow users to change.
torrentsThis would be a list of filenames, their current status, and some sort of verification that the .torrent file hasn't been replaced; the infohash would do.
I would save a bencoded version of this data in a file for later. For now, putting all of this into practice is an exercise for the reader.
Note: Reloading the data may require using otherwise private methods (specifically the private Net::BitTorrent::DHT->_set_node_id( ) method). Changes to private methods are not listed in the changelog found in this distribution but they are noted in the public git repository's log.
See Net::BitTorrent::Torrent::File.
[TODO]
This section describes all the behind the scenes stuff that makes Net::BitTorrent work. Or not work. It depends.
Please see Net::BitTorrent::Version.
Socket6 does not seem to work with Win32 so... no plans for IPv6 right now.
The BitTorrent Community Forum coordinates the development of the BitTorrent protocol suite, its reference implementation, and BitTorrent Enhancement Proposals (BEPs). For more information, see BEP 0: Index of BitTorrent Enhancement Proposals http://bittorrent.org/beps/bep_0000.html
This is the list of extensions used by this release of Net::BitTorrent sorted by their progress toward standardization.
Note: the Fast Extension is only partially implemented in Net::BitTorrent.
Net::BitTorrent::Torrent's resume data is bencoded and stored in a file. To restore this data, use the Resume parameter when calling Net::BitTorrent::Torrent->new( ) or Net::BitTorrent->add_torrent( ).
Note: The structure and data held in the resume data is subject to change in future versions.
Parsed resume data is a simple hash containing the following keys:
.formatA string describing what sort of file this is. For now, it's value is Net::BitTorrent resume.
.tTimestamp when data was gathered.
.versionAPI version used to gather data. To avoid problems (API changes, etc.), Net::BitTorrent::Torrent will not load resume data created with a higher version.
bitfieldA bitvector representing the pieces we already have.
filesA list of hashes (one for each file in the .torrent) with the following keys:
peersCompact list of peers we've found either through DHT or from a tracker.
workingList of hashes representing pieces we are currently downloading with the following keys: (Subject to change)
Block_CountNumber of blocks contained in the piece.
Block_LengthSize of blocks in piece.
Block_Length_LastSize of final block in piece.
Blocks_ReceivedBitfield representing which blocks have been received and written to disk.
EndgameBoolean value dependent on endgame state when we began working on this piece.
IndexZero-based index of the piece.
LengthTotal size of the piece in bytes.
PriorityPriority based (partially) on the piece's containing file.
SlowBoolean value dependent on how long ago we received a block contained within this piece.
Changes to documented or well established parts will be clearly listed and archived in the CHANGES file.
Net::BitTorrent is just asploding with incomplete bits of stuff so I reserve the right to change or eliminate code at any time without warning unless functionality is defined in POD documentation. If you sift through the source and find something nifty that isn't described in full in POD, don't expect your client to work with future releases.
This section lists recent major changes in API or behavior between stable releases. For older news see the Changes file included with this distribution. For detail see the commit logs.
Protocol Encryption (MSE) is now supported and enabled by default. It is still rather unstable, so outgoing connections use header-only encryption but incoming connections allow for full RC4 encrypted sessions.
Entire distribution was rewritten. Both the internals and the API have broken compatibility.
If you're interested in assisting with Net::BitTorent's development but don't know where to begin, here are a few ideas.
Net::BitTorrent is too large for just one person to hack on. If you're Perl adept and would like to help, you can start by forking the project on github: http://github.com/sanko/net-bittorrent/. When ready, send me a pull request, I'll look over your changes and get back to you. Minor patches get your name in the changelog. Major patches get your name in the Acknowledgments section and an invitation to be a trusted collaborator. Oooo. Ahhh.
THIS PROJECT IS ACTIVELY SEEKING DEVELOPERS.
If you're interested in helping clear things out of the TODO list or if you have a suggestion and are willing to see it through to completion, contact me or, better yet, go ahead and fork the project on github: http://github.com/sanko/net-bittorrent.
In general, N::B could use a second or third pair of eyes. So, if you're interested in BitTorrent, p2p, or just Perl in general, let me know.
Found bugs should be reported through Net::BitTorrent's Issue Tracker. Before creating a new report through Net::BitTorrent's Issue Tracker, please review the following list:
Becoming a CPAN Tester is an easy, automatic way to contribute to the quality of your favorite module and CPAN in general. If you would like to contribute automated test reports for Net::BitTorrent, install CPAN::Reporter from the CPAN shell first:
$ cpan cpan> install CPAN::Reporter cpan> reload cpan cpan> o conf init test_report [...follow the CPAN::Reporter setup prompts...] cpan> o conf commit cpan> install Net::BitTorrent
For more on becoming a CPAN Tester and why this is useful, see the CPAN::Reporter documentation and http://cpantesters.org/.
Net::BitTorrentThe official website is http://sankorobinson.com/net-bittorrent/ and related blog entries are posted to http://sankorobinson.com/.
If you're looking for a feed with only on-topic articles, subscribe to http://sankorobinson.com/atom/?tag=Net::BitTorrent
The official means of support for Net::BitTorrent is through #net-bittorrent on the p2p IRC network: irc://irc.p2p-network.net/net-bittorrent
These are posted to the public mailing list for which both ATOM 1.0 and RSS 2.0 feeds are available; see http://groups.google.com/group/net-bittorrent/feeds.
To subscribe to the list or view the archive, visit http://groups.google.com/group/net-bittorrent. Both ATOM 1.0 and RSS 2.0 feeds are provided; see http://groups.google.com/group/net-bittorrent/feeds for a list.
Use http://code.google.com/p/net-bittorrent/issues/list for bug tracking. Please include as much information as possible and review the list above.
I announce stable builds and occasionally complain on Twitter: http://twitter.com/net_bitTorrent
Section 2.3. "Unreserved Characters" (http://tools.ietf.org/html/rfc3986#section-2.3)
Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/
CPAN ID: SANKO
Copyright (C) 2008-2009 by Sanko Robinson <sanko@cpan.org>
This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or http://www.perlfoundation.org/artistic_license_2_0. For clarification, see http://www.perlfoundation.org/artistic_2_0_notes.
When separated from the distribution, all POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See http://creativecommons.org/licenses/by-sa/3.0/us/legalcode. For clarification, see http://creativecommons.org/licenses/by-sa/3.0/us/.
Neither this module nor the Author is affiliated with BitTorrent, Inc.