NAME

Net::BitTorrent::Notes - Annotated Guide to the Ins and Outs of Net::BitTorrent

Description

Net::BitTorrent is a mess.

But it doesn't have to be! This document is a first draft attempt at defining a roadmap for future Net::BitTorrent development and a behavioral reference for third-party client developers. There are bits in here that may eventually make it into a recipe book for users too.

Note: Net::BitTorrent::Notes and the ideas behind it are a work in progress.

Net::BitTorrent's Way-too-Obvious Class Hierarchy

                 Net::BitTorrent
                       |
             Net::BitTorrent::Session
            /      /   |      \
N::B::S::Tracker  /    | N::B::S::Piece
                 /     |       /
         N::B::S::File | N::B::S::P::Block
                       |
                  N::B::S::Peer
                        \
                 N::B::S::P::Request

See Also: Class Pseudo-structures

Installation

This distribution uses Module::Build for installation, so use the following procedure:

perl Build.PL
./Build
./Build test
./Build install

If you would like to contribute automated test reports (and I hope you do), first install CPAN::Reporter from the CPAN shell and then install Net::BitTorrent:

$ 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, please see the CPAN::Reporter documentation, http://cpantesters.perl.org/, and the CPAN Testers Wiki (http://cpantest.grango.org/)

Prerequisites

Net::BitTorrent requires version and Digest::SHA. On Win32, we require Win32API::File and Encode when handling .torrents holding files with 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.

Portability Hacks

Net::BitTorrent aims to be portable between the big three OS (Win32, Linux [*buntu], MacOS X); 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 (and, eventually, OS-based subclassing) is needed. Here is a list of both stable and experimental workarounds by OS:

MSWin32

Extended charset filename support

[TODO]

How Do I...

Parts that aren't handled internally are described here with sample code to get you started. In the future, this will probably be in a separate recipe book.

Pause and Resume a .torrent Session

[TODO]

Stop and Resume a .torrent Session

[TODO]

Quick Resume a .torrent Session Between Client Sessions

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. Add to that some sort of verification scheme to be sure you're loading information that hasn't been tampered with or corrupted. Then, when you load the torrent, set the skip_hashcheck parameter to a true value and reload the torrent with your stored data.

[TODO]

Set File Priorities

See "priority( [NEWVAL] )" in Net::BitTorrent::Session::File.

Implement My Own Event Loop

[TODO]

Class Pseudo-structures

Net::BitTorrent

Net::BitTorrent = {
   peer_id                   => string
   socket                    => GLOB
   maximum_peers_per_client  => integer
   maximum_peers_per_session => integer
   maximum_peers_half_open   => integer
   maximum_buffer_size       => integer
   maximum_requests_size     => integer
   maximum_requests_per_peer => integer
   timeout                   => integer
   debug_level               => integer
   connections               => array, # N::B and N::B::Session objects
   callbacks                 => hash,  # key:value::(str)type:coderef
   sessions                  => array, # N::B::Session objects
   fileno                    => integer
   kBps_up                   => integer
   kBps_down                 => integer
   k_up                      => integer
   k_down                    => integer
}

Net::BitTorrent::Session

Net::BitTorrent::Session = { [TODO] }

Net::BitTorrent::Session::Tracker

Net::BitTorrent::Session::Tracker = { [TODO] }

Net::BitTorrent::Session::Peer

Net::BitTorrent::Session::Peer = { [TODO] }

Net::BitTorrent::Session::Peer::Request

Net::BitTorrent::Session::Peer::Request = { [TODO] }

Net::BitTorrent::Session::File

Net::BitTorrent::Session::File = { [TODO] }

Net::BitTorrent::Session::Piece

Net::BitTorrent::Session::Piece = { [TODO] }

Net::BitTorrent::Session::Piece::Block

Net::BitTorrent::Session::Piece::Block = { [TODO] }

Net::BitTorrent Internals

This section describes all the behind the scenes stuff that makes Net::BitTorrent work. Or not work. It depends.

Peer ID Generation

This section describes and provides examples of the Peer ID format used by the current release of the Net::BitTorrent module.

Format

This non-standard format was developed to be URL-safe, unique to the implementation, and "human parsable."

There are three distinct sections to the Peer IDs generated: the header, the mid-section, and the signature. Consider this example:

NB004S-rogzGB1v--SVN

Here, NB004S is the header, -rogzGB1v is the mid-section, and --SVN is the trailing signature.

Header

Two uppercase characters ('NB') followed by three digits representing the SVN revision number with leading zeros, a single character potentially indicating stability and how the release was obtained, and a single hyphen (-).

If the client is a CPAN build, the sixth byte is the capital letter 'C'. If the client is running a version checked out from public SVN (considered unstable), the sixth byte is the capital letter 'S'. Any other characters in the sixth byte are unsupported and may indicate a bad client.

Mid-section

Following that are eight random characters in the following range:

ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~

That is, all uppercase and lowercase letters, decimal digits, as well as the hyphen, period, underscore, and tilde (66 total). These are all characters allowed in a URL without encoded (referred to as "Unreserved Characters in [rfc://3986]) to reduce weight on the tracker during announce. On a popular tracker, every bit (and byte) helps.

This section is inspired by the pseudo-base64 set used by SHADOW's BitTornado client.

Signature

The final five characters may be random or static and should not be used in identifying the version of the client software. Some early versions even have my name in this spot. .:shrugs:.

CPAN Version Numbers

Stable CPAN releases will have the sixth byte set to 'C' (capital letter 'c').

Unstable releases (referred to as DEVELOPER releases on PAUSE) on CPAN will have this bit set as if the user checked the source out from SVN, that is, the sixth byte will be 'S' (capital letter 's'). These will be released on CPAN with version numbers matching m[\d\.\d+_\d]. See the PAUSE FAQ section entitled "Developer Releases" (http://www.cpan.org/modules/04pause.html).

Version numbers will be some value less than one with the revision number in the three significant decimal places. Eventually, I would like to make a v1.0 release of Net::BitTorrent on CPAN. The information in this document and the means of generating the module's version number will need to reflect that.

Examples

NB393C-04.9EraQ--SVN

This would be the stable CPAN release v0.393. The --SVN signature should be ignored.

NB003X-9E-ayR6b-BT<3

Improper Peer ID; the sixth bit is neither 'C' nor 'S'. Possibly fake.

NB065S--09Egae69sy8W

Completely legal Peer ID generated by SVN/Dev r65.

Handling of Errors and Bad Data

[TODO]

.torrent Metadata

[TODO]

Incoming Protocol Data

[TODO]

Disk Access Errors

[TODO]

Piece Selection

[TODO]

Outgoing Requests

[TODO]

Queuing

[TODO]

Slow Blocks

[TODO]

Endgame

[TODO]

Incoming Requests

[TODO]

Queuing

[TODO]

Rejections (Fast Ext)

[TODO]

Trackers

[TODO]

Multi-tracker .torrents

[TODO]

UDP Trackers

[TODO]

Fast Set Advertising

[TODO]

IPv6-Related Information

When will IO::Socket::INET6 or Socket6 be CORE?

Implemented Extensions

[TODO]

Do Your Part

Automated Testing

[TODO]

Bug Reporting

Right now, the best way to contribute would be through bug reports and patch submissions.

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 regardless of its content.

• 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.

• If the bug is related to one .torrent in particular, please attach it to your report.

• 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.

Co-Development and Patch Submission

Net::BitTorrent is too large for just one person to hack on. If you're Perl proficient and would like to help, you can start by fixing problems reported in the Issue Tracker and bugs you find on your own. When I decide to start looking for co-devs, you'll already have 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.

See Also

Support and Information Links for Net::BitTorrent

The Project's Website

Until I create something better on my own site, for wiki and subversion repository access, please visit the project's home: http://net-bittorrent.googlecode.com/.

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::BitTorrent mailing 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.

Stalk Me While I Tinker

Follow Net::BitTorrent's development on Twitter: http://twitter.com/Net_BitTorrent.

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"

(http://www.cpan.org/modules/04pause.html)

Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

CPAN ID: SANKO

Disclaimer and Legal

Copyright 2008 by Sanko Robinson <sanko@cpan.org>

This document and the specifications behind it are subject to change.

This original documentation is covered by the Creative Commons Attribution-Noncommercial-Share Alike 3.0 License (United States jurisdiction).

Neither this module nor the Author is affiliated with BitTorrent, Inc.

cpanm Net::BitTorrent

perl -MCPAN -e shell
install Net::BitTorrent