doc/tairent.txt

   1 Tairent
   2 =======
   3
   4 Tairent is a minimalistic BitTorrent client for Linux servers. It means that
   5 it has no GUI, TUI or CLI. Instead it provides effective way for serving large
   6 files using BitTorrent protocol. Because Tairent uses Tairon library for
   7 networking (and other stuff) it can handle very large number of idling
   8 connections at the moment. Other key feature is that Tairent tries to minimize
   9 data copying in memory by using tt:[mmap] for mapping large files into the
  10 memory and then sending them directly to the peer.
  11
  12 Tairent is divided into modules (each is located in its own directory under
  13 tt:[src/]). This document is brief introduction to how Tairent internally
  14 works.
  15
  16
  17 Core
  18 ----
  19
  20 This isn't module in the sense that it could be loaded at runtime. It's built
  21 into executable program's binary and initializes all the necessary components
  22 (i.e. managers from the Tairon library). Core module also creates thread for
  23 networking (runs tt:[Tairon::Net::Loop]) and implements common data
  24 structures: BEncode and bitfield.
  25
  26
  27 Main
  28 ----
  29
  30 Main module is the heart of the application. It implements all program logic
  31 (and thus the BitTorrent client itself). The module creates managers (for
  32 different tracker methods, torrents and one for limiting bandwidth; the last
  33 one is implemented in the Tairon library) and two program threads (main that
  34 is already created and one for hash checking). When all modules are loaded this
  35 module tells torrent manager that it can start serving torrents and executes
  36 main program loop.
  37
  38
  39 Tracker manager
  40 ~~~~~~~~~~~~~~~
  41
  42 Tracker manager (tt:[Tairent::Main::TrackerManager] class) keeps list of
  43 registered protocols for trackers (official BitTorrent specification uses just
  44 HTTP) and can create clients for those protocols.
  45
  46
  47 Torrent manager
  48 ~~~~~~~~~~~~~~~
  49
  50 Torrent manager (tt:[Tairent::Main::TorrentManager] class) keeps information
  51 about served torrents. It means that it loads these informations from
  52 tt:[torrents.xml] file stored in the directory configurable by
  53 tt:[torrents-directory] option.  For each served torrent it loads its metainfo
  54 file and possible creates storage engine for this torrent if fast-resume data
  55 is present. Torrent manager also creates client for each served torrent.
  56
  57 Every minute Torrent manager asks all clients to save their state into the
  58 tt:[torrents.xml] file and thus it allows resuming of unfinished torrents.
  59 This is done by connecting tt:[save()] method to a timer with 60 seconds
  60 timeout.
  61
  62
  63 Client
  64 ~~~~~~
  65
  66 Client for one torrent is represented by tt:[Tairent::Main::TorrentClient]
  67 class. It has lists of connected peers and connections that hasn't been fully
  68 established. Client controls connection logic by receiving specific protocol's
  69 commands and relaying them to the storage engine or doing specific actions
  70 with peers (choking, closing and opening new connections, requesting new
  71 pieces etc).
  72
  73
  74 Connection
  75 ~~~~~~~~~~
  76
  77 tt:[Tairent::Main::Connection] handles BitTorrent protocol at the network
  78 level: connection initialization by sending, receiving and verifying handshake
  79 sequence and then by reading and sending messages over the connection. This
  80 class communicates with client that owns this connection and possibly with
  81 client's storage engine. Connection handles lists commands that should be sent
  82 to the peer, peer's requests and other connection's state (which side of the
  83 connection is choked/interested, list of peer's pieces, etc).
  84
  85
  86 Storage
  87 ~~~~~~~
  88
  89 This engine (implemented in tt:[Tairent::Main::Storage] class) is one of the
  90 most critical part. It loads information about torrent's file(s) from its
  91 metainfo and prepares internal structures for effective handling. Storage also
  92 chooses what piece should be requested, maintains list of requested and
  93 already received pieces and creates objects for reading and writing them.
  94
  95
  96 HTTP tracker client
  97 -------------------
  98
  99 This is one module that implements support for trackers communicating over
 100 HTTP protocol. The module implements factory
 101 (tt:[Tairent::TrackerClient::HTTPTrackerClientFactory] class) for creating
 102 clients for these trackers and the client itself represented by
 103 tt:[Tairent::TrackerClient::HTTPTrackerClient]. Client requests list of peers
 104 from the torrent's trackers and relays this list to the client.