- Net::BitTorrent's Way-too-Obvious Class Hierarchy
- How Do I...
- Net::BitTorrent Internals
- Peer ID Specification
- Handling of Errors and Bad Data
- Piece Selection
- Outgoing Requests
- Incoming Requests
- Fast Set Advertising
- IPv6-Related Information
- Implemented Extensions
- Portability Hacks
- Giving back
- See Also
- License and Legal
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 `---- N::B::D::Node \ `---- Net::BitTorrent::Peer
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. 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. See Portability Hacks.
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.
Early versions of N::B had resume built in but it was removed for various reasons. Adding this yourself is trivial, fortunately. For each torrent, store the bitfield, nodes (compact list of peers), piece priorities, and the modified times for each file just to be safe. Oh, and a list of the current 'working' pieces and their progress. Saving the DHT node ID and routing table would be a good idea too. Add to that some sort of verification scheme to be sure you're not loading corrupt data. Then, when you reload the torrent, shove your data through all the related back alley private methods until I come up with a less insane way to do this safely.
This section describes all the behind the scenes stuff that makes
Net::BitTorrent work. Or not work. It depends.
Please see Net::BitTorrent::Version.
To have any semblance of basic functionality, a BitTorrent client must have a good piece selection strategy. The 'strict priority' based algorithm used by Net::BitTorrent seems to strike a balance between efficiency and speed while keeping the pipes full of incoming data. I'll walk you through it...
Count the number of unrequited
$free_blocksin all working pieces.
Count how many
$free_slotswe have open to us. To calculate this, we iterate through all peers who aren't choking us adding the difference between the total number of outgoing requests and the peer-defined maximum or our own internal 'safe' max.
$max_workingis set to the current number of working pieces plus the bool value of
$free_blocks < $free_slots.
%weightsbased on file priorities and our bitfield.
Take the sum of all the relative (priority) weights and call it
Take a random number between 0 and 1, and multiply it by
$total. Call the new number
$rand_valis positive, iterate through each element of
@weightsand do the following:
The language used in this section probably only makes sense to me and will require a rewrite. For the actual code, see
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.
These BEPs describe mechanisms that have been deployed in one or more BitTorrent implementations and have proven useful. They may require minor revisions. They await the blessing of the BDFL before they can be considered Final.
BEP 32: Tracker Returns Compact Peer Lists - http://bittorrent.org/beps/bep_0023.html
The following BEPs are under consideration for standardization.
BEP 5: DHT Protocol - http://bittorrent.org/beps/bep_0005.html
BEP 6: Fast Extension - http://bittorrent.org/beps/bep_0006.html
Note: the Fast Extension is only partially implemented in Net::BitTorrent.
BEP 10: Extension Protocol - http://bittorrent.org/beps/bep_0010.html
BEP 12: Multitracker Metadata Extension - http://bittorrent.org/beps/bep_0012.html
BEP 15: UDP Tracker Protocol - http://bittorrent.org/beps/bep_0015.html
BEP 27: Private Torrents - http://bittorrent.org/beps/bep_0027.html
Net::BitTorrent aims to be portable between the big three OS when possible, this should be achieved without a glut of code using easily obtained third-party modules. Core modules are considered first followed by well tested CPAN modules. Modules that prevent broad use (ie. fails to install on a majority of systems) will not be considered.
There will be times, though, that
$^O-based clutter is needed. Here is a list of both stable and experimental workarounds by OS:
If you're interested in assisting with Net::BitTorent's development but don't know where to begin, here are a few ideas.
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
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/.
Found bugs should be reported through
Net::BitTorrent's Issue Tracker. Please include as much information as possible. Before creating a new report through
Net::BitTorrent's Issue Tracker, please review the following list:
Make sure you are using the most recent release of
Net::BitTorrent. This may mean checking out the latest SVN commit. All patches should be made against the most recent revision and well tested. For a list of SVN clients, some of which make patch creation a little easier, see http://subversion.tigris.org/links.html#clients.
Make sure the bug is reproducible.
Please write in clear English.
Include as much detail as possible when describing the bug. Provide "baby steps" to describe exactly how to replicate the bug. Sample code is welcome. Net::BitTorrent's issue tracker also allows attachments so, if relevant, also include the .torrent file.
If the bug is related to one .torrent in particular, please attach it to your report.
Search the list of open and resolved issues to make sure the flaw hasn't already been reported. If it has, you can star the issue to stay up to date. You'll know what I mean by 'star' it when you get there... I can see how many people have stars on a particular issue and popular bugs get priority.
Issues are open to the public, so don't include passwords or other confidential information. Beyond that, you can never provide too much information in a bug report.
One bug is one bug report. Please do not include multiple, separate issues in one report unless they are explicitly related to each other.
It never hurts to do a little homework. If you run into a problem, find the place that's causing trouble and manage to fix it, please attach a patch (diff against the latest svn revision) or at least a very good description (with code) of what you did.
Star the issue so you can stay up to date with my progress.
Look over your report before submission to be sure you've included as much detail as possible. Seriously. Get up, have a drink of water, come back, read over it again to make sure you've included everything you intended, and then submit.
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 fixing problems reported in the Issue Tracker and bugs you find on your own. I am currently seeking co-devs and patches are a great way to get your foot in the door.
Please submit patches for review by attaching it through the
Net::BitTorrent Issue Tracker. If it's a patch to fix an existing Issue, use that thread. Otherwise, create a new Issue. Minor patches get your name in the changelog. Major (security, especially) patches get your name in the Acknowledgments section. Oooo. Ahhh.
- Support and Information Links for
- The Project's Website
For updates and links to the wiki and subversion repository access, please visit http://sankorobinson.com/net-bittorrent/.
- Receive SVN Commit and Issue Tracker Updates
The preferred way is to subscribe to one of the feeds of the announce group. Both ATOM 1.0 and RSS 2.0 feeds are provided; see http://groups.google.com/group/net-bittorrent-announce/feeds for a list.
To have each message delivered to your mailbox, subscribe to the read only announce group by visiting http://groups.google.com/group/net-bittorrent-announce.
- Public Mailinglist
Rather than contacting me directly (which you're welcome to do, it's just nice having a searchable, public archive), general questions and comments should be posted to the
Net::BitTorrentmailing list. To subscribe to the list or view the archive, visit http://groups.google.com/group/net-bittorrent-discuss.
- Issue Tracker
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.
- Stalk Me While I Tinker
Net::BitTorrent's development on Twitter: http://twitter.com/Net_BitTorrent.
It's open source social networking. ...I think. Regardless of it's use, Net::BitTorrent has an Ohloh page: http://www.ohloh.net/projects/net-bittorrent/
Wait, project cost: $65,430? Yeah, okay!
- Other Recommend Open Source BitTorrent Clients
libtorrent (http://www.rasterbar.com/products/libtorrent/) is covered by the The BSD License.
Bitflu (http://bitflu.workaround.ch/) is a full client written in (*nix oriented) Perl and available under the Perl/Artistic License.
btpeer (http://www.alhem.net/project/btpeer/) is "a collection of classes implementing the core client functionality of the BitTorrent protocol" and has been released under the GPL.
Arctic (http://dev.int64.org/arctic.html) is a minimal client based on libtorrent, written in C++ and released under the MIT License.
- RFC 3986 (URI: Generic Syntax)
Section 2.3. "Unreserved Characters" (http://tools.ietf.org/html/rfc3986#section-2.3)
- PAUSE FAQ sub-section entitled "Developer Releases"
Sanko Robinson <email@example.com> - http://sankorobinson.com/
CPAN ID: SANKO
Copyright (C) 2008 by Sanko Robinson <firstname.lastname@example.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.