quartz_torrent 0.0.1 → 0.0.2

data/.yardopts

@@ -0,0 +1 @@
+--readme README.md

data/README.md

@@ -0,0 +1,111 @@
+QuartzTorrent -- A Ruby Bittorrent Library 
+==========================================
+
+Like the title says, a bittorrent library implemented in pure ruby. Currently 
+the library works, but is still alpha.
+
+Features:
+---------
+
+  - BEP 9:  Extension for Peers to Send Metadata Files 
+  - BEP 10: Extension Protocol 
+  - BEP 15: UDP Tracker support
+  - BEP 23: Tracker Returns Compact Peer Lists
+  - Upload and download rate limiting
+  - Upload ratio enforcement
+
+Requirements
+------------
+
+This library has been tested with ruby1.9.1. The required gems are listed in the gemspec.
+
+Running the curses client requires rbcurse-core (0.0.14).
+
+Getting Started
+---------------
+
+How to use the library is best illustrated with an example. The sample program below touches on all the
+major ideas.
+
+    require 'quartz_torrent'
+    include QuartzTorrent
+    
+    # Direct logging to stdout at info level
+    LogManager.setup do
+      setLogfile "stdout"
+      setDefaultLevel :info
+    end
+    
+    # When CTRL-C is pressed, shut down
+    running = true
+    Signal.trap('SIGINT') do
+      puts "Got SIGINT. Shutting down."
+      running = false
+    end
+    
+    # Create MagnetURI from first argument
+    magnet = MagnetURI.new(ARGV[0])
+    
+    # Create a PeerClient that downloads to the current directory. 
+    # This is the main API, and implements the Bittorrent peer protocol. 
+    peerclient = PeerClient.new(".")
+    peerclient.port = 5555
+    peerclient.addTorrentByMagnetURI magnet
+    
+    # Start the peerclient in another thread.
+    peerclient.start
+    
+    while running do
+      peerclient.torrentData.each do |infohash, torrent|
+        name = torrent.recommendedName
+        pct = 0
+        if torrent.info
+          pct = (torrent.completedBytes.to_f / torrent.info.dataLength.to_f * 100.0).round(2)
+        end
+        puts "#{name}: #{pct}%"
+      end
+      sleep 2
+    end
+    
+    peerclient.stop
+
+Logging is configured using QuartzTorrent::LogManager. Logs can be sent to stdout, stderr, or file. Individual loggers can be set to different levels. 
+
+The QuartzTorrent::PeerClient class is the main interface for downloading and uploading torrents. The PeerClient constructor takes the path to the 
+directory into which torrents should be downloaded. Torrents may be  added to the PeerClient as Magnet links, or .torrent file contents before or after 
+the PeerClient is stared. When started, the PeerClient runs asynchronously in a separate thread. Information regarding the running torrents is retrieved
+with the PeerClient::torrentData method.
+
+More elaborate examples can be found in `bin/quartztorrent_download` and `bin/quartztorrent_download_curses`. 
+
+Running Tests
+-------------
+
+Run the tests as:
+
+    rake test
+
+You can run a specific test using, i.e.:
+
+    rake test TEST=tests/test_reactor.rb
+
+And a specific test case in a test using:
+
+    ruby1.9.1 -Ilib tests/test_reactor.rb -n test_client
+
+
+To-Do
+-----
+  - Start a peerclient with the full torrent. Connect with another peerclient and start downloading, then pause.
+    Finally unpause. The "server" peerclient will refuse the connections to re-establish because it believes the
+    peer is already connected.
+  - Improve CPU usage. 
+  - Implement endgame strategy and support Cancel messages.
+  - Refactor Metadata.Info into it's own independent class.
+  - Improve Documentation
+  - In peerclient, prefix log messages with torrent infohash, or (truncated) torrent name
+  - Implement uTP
+    - <http://www.bittorrent.org/beps/bep_0029.html#packet-sizes>
+    - <https://forum.utorrent.com/viewtopic.php?id=76640>
+    - <https://github.com/bittorrent/libutp>
+  

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quartz_torrent
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -163,6 +163,8 @@ files:
 - lib/quartz_torrent/filemanager.rb
 - lib/quartz_torrent/magnet.rb
 - lib/quartz_torrent/udptrackerclient.rb
+- README.md
+- .yardopts
 - bin/quartztorrent_download
 - bin/quartztorrent_download_curses
 - bin/quartztorrent_magnet_from_torrent