RubyTorrent Documentation

Introduction
------------

RubyTorrent is a pure-Ruby BitTorrent library. You can use RubyTorrent
in your Ruby applications to download and serve files via the
BitTorrent protocol.  More information about BitTorrent can be found
at http://bittorrent.com/.

There's a lot going behind the scenes, but using this library is
pretty simple: on the surface, RubyTorrent simply lets you download a
file or set of files, given an initial .torrent filename or URL.

I recommend you take a look at rtpeer.rb for an example Ruby BitTorrent
peer that uses all this stuff.

Synopsis
--------

require "rubytorrent"

# simple
bt = RubyTorrent::BitTorrent.new(filename)
bt.on_event(self, :complete) { puts "done!" }

# more complex
mi = RubyTorrent::MetaInfo.from_location(url)
package = RubyTorrent::Package.new(mi, dest)
bt = RubyTorrent::BitTorrent.new(mi, package)
thread = Thread.new do
  until bt.complete?
    puts "#{bt.percent_completed}% done"
    sleep 5
  end
end
bt.on_event(self, :complete) { puts "done!" }
thread.join

Overview
--------

There are three top-level classes you should be familiar with in the
RubyTorrent module: BitTorrent, MetaInfo and Package. BitTorrent is
the main interface; MetaInfo and Package classes allow you more
control over the details, but they're completely options and the
BitTorrent class will do reasonable things if you don't use them.

RubyTorrent has a very event-driven interface; all methods are
non-blocking and the BitTorrent class generates notifications of all
interesting events, which you can subscribe to. See the documentation
on BitTorrent#on_event() below for how to subscribe to events.

RubyTorrent::MetaInfo
---------------------

This class represents the contents of the .torrent file or URL.

CLASS METHODS

from_location(location, http_proxy=ENV["http_proxy"])
  Creates a MetaInfo object from a filename or URL.

  Arguments:
   location: a filename or a URL of a .torrent file.
   http_proxy: is the HTTP proxy to be used in the case that
    "location" is a URL (nil for none).

  Returns:
    A MetaInfo object.

  Throws:
    RubyTorrent::MetaInfoFormatError,
    RubyTorrent::BEncodingError,
    RubyTorrent::TypedStructError
      if the contents of the file/url are not a BitTorrent metainfo file.
    IOError, SystemCallError
      if reading the contents of the file/url failed for system-level
      issues.

from_stream(stream)
  Creates a MetaInfo object from a readable IO stream.

  Arguments:
    stream: a readable IO stream, e.g. an opened File.

  Returns:
    A MetaInfo object.

  Throws:
    same as RubyTorrent::Metainfo#from_location

INSTANCE METHODS

single?
  Returns true if this .torrent contains a single file, false otherwise.

multiple?
  The opposite of single?

RubyTorrent::Package
--------------------

This class represents the target file or files on disk.

CLASS METHODS

new(info, out=nil, validity_assumption=nil, path_sep="/") # optional block
  Creates a Package.

  Arguments:
   info: a MetaInfo object.
   out: if info.single?, this should be a File object corresponding to
     the target file on disk. If info.multiple?, this should be a Dir
     object corresponding to the target directory on disk. If nil, the
     original filename (for single-file .torrents) or the current
     directory (for multi-file .torrents) will be used.
   validity_assumption: if nil, make no assumptions about the validity of
     any files on disk. If true, assume all files on disk are complete
     and valid. If false, assume all files on disk are incomplete and
     invalid.  This can be used to speed up start time by skipping all
     examination of current disk contents: if you're just starting a
     download, you can use false; if you're serving a complete file or
     set of files, you can use true.
   path_sep: how to join path-name components to make paths. "/"
     should work on both Windows and Unix worlds; I'm not sure about
     other OSs.

  Block:
    If given, yields a "Piece" object when checking the files on
    disk. This object has complete?() and valid?() methods. This is
    really only useful for updating the user on the status of the
    Package creation, which can take a long time for large files (I/O
    time and SHA1 calculations).

  Throws:
    IOError, if the file access fails.

RubyTorrent::BitTorrent
-----------------------

The main BitTorrent peer protocol interface.

CLASS METHODS

new(metainfo, package=nil, :host, :port, :dlratelim, :ulratelim, :http_proxy)
  Creates a BitTorrent peer.

  Arguments (all symbol arguments are optional hash pseudo-keyword arguments):
    metainfo: a String, IO or MetaInfo object corresponding to a .torrent file.
      In the case of a String or IO object, a MetaInfo object will be implictly
      created with default arguments.
    package: a Package, or nil. In the case on nil, a new Package will be
      implicitly created with default arguments.
    :host: the host to report to the tracker, if the source IP address of the
      HTTP request is not correct (for weird IP masquerading issues, I suppose).
    :port: the port to report to the tracker, if the port the BitTorrent peer is
      listening on is not correct (likewise).
    :dlratelim: the download rate limit in bytes/sec. This limit right now is
      applied on a per-peer basis to the average download rate. In the future
      this might change to something stricter/more useful.
    :ulratelim: likewise, for the upload rate limit.
    :http_proxy: the http_proxy used for connecting to the tracker, or nil
      or unspecified for ENV["http_proxy"].

  Throws:
    All of the exceptions thrown by MetaInfo.new and Package.new.

INSTANCE METHODS

running?
  Returns whether this client is running or not.

ip
  Returns the IP address the client is bound to, as a String (possibly "0.0.0.0")

port
  Returns the port the client is bound to.

complete?
  Returns whether the file on disk is complete or not.

bytes_completed
  Returns the number of bytes completed.

total_bytes
  Returns the total number of bytes in the target file/fileset.
  
percent_completed
  Returns the percent of bytes completed.

pieces_completed
  Returns the number of BitTorrent "pieces" completed.

num_pieces
  Returns the total number of BitTorrent pieces.

tracker
  Returns the URL of the tracker being used, or nil if no tracker can be reached.

num_possible_peers
  Returns the number of peers we've read from the tracker, or nil if no tracker
  can be reached. This is typically capped at 50.

peer_info
  Returns an array of hashes, one per current peer, with the following symbols
  as keys:
    :name: the peer name (probably "ip address/port")
    :seed: true if the peer is a seed, false if it's a leecher
    :dlamt, :ulamt: the number of bytes downloaded from /uploaded to this peer
    :dlrate, :ulrate: the bytes/sec downloaded from/uploaded to this peer
    :pending_send, :pending_recv: the number of blocks pending for send/receive
    :interested, :peer_interested: who's interested in the other's pieces
    :choking, :peer_choking: who's choking whom
    :snubbing: whether we're snubbing this peer
    :we_desire, :they_desire: number of pieces one has that the other wants
  A lot of this stuff has to do with the internals of the BitTorrent wire
  protocol, so it's mainly useful for debugging.

shutdown
  Shuts down this particular client.

shutdown_all
  Shuts down all clients.

on_event(who, *events) # mandatory block
  Registers a notification for one or more events. When one of the
  events occurs, the block will be called. The first argument to the
  block will be the source of the event (in this case a
  RubyTorrent::BitTorrent object); the other arguments are dependent
  on the block itself.

  Arguments:
    who: should be "self"
    events: one or more event symbols (see EVENTS below)

unregister_events(who, *events)
  Unregisters event notifications. All blocks added with on_event(who, ...)
  will be removed if they have an event in "events". If "events" is nil,
  all blocks registered with on_event(who, ...) will be removed.

  Arguments:
    who: the same argument as was passed to on_event()
    events: one or more event symbols.

EVENTS

:trying_peer |source, peer|
  We're trying to connect to the peer "peer" (a String: "ip addr/port").

:forgetting_peer |source, peer|
  We're couldn't connect to the peer.
 
:added_peer |source, peer|
  We successfully connected to the peer.

:removed_peer |source, peer|
  We dropped our connection to the peer.

:received_block |source, block, peer|
  We received a block "block" from peer.

:sent_block |source, block, peer|
  We sent a block "block" to peer.

:have_piece |source, piece|
  We've successfully downloaded a complete piece "piece".

:discarded_piece |source, piece|
  We had to discard piece "piece" because of checksum errors

:complete |source|
  We've downloaded the entire file! Hooray!

:tracker_connected |source, url|
  We connected to tracker "url".

:tracker_lost
  We couldn't connect to tracker "url" after previously having connected to it.

COPYRIGHT
---------

Copyright 2005 William Morgan
Permission is granted to copy, distribute and/or modify this document under the
terms of the GNU Free Documentation License, Version 1.2; with no Invariant
Sections, no Front-Cover Texts, and no Back-Covers. A copy of the license may
be found at http://www.gnu.org/licenses/fdl.html.