trans-api 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4750d6488dcb9805c0bbd635509b4cc2b82f664e
-  data.tar.gz: 112eebe82c5696c795c38d311047cb6bc154d396
+  metadata.gz: 1d01cbf84b3889d9915b90cafc5d77f2616568f3
+  data.tar.gz: 82999c9a1f31862aedfb2e7f08202bb6bf916502
 SHA512:
-  metadata.gz: 2d6928aee4bdebfe1272677a7b88dbe56df591922aeaf38d175d5c109fbd8b149a7519259d8322e202223319601a61a0d82d73084becf8126019b45af12acea5
-  data.tar.gz: 6baef1393173ee402a8487bf7656702c399d39f0b490047ad306a4807546c28561ef23810ab49bd90316ffbe6bafb3132cd12eac69b787d6766ec3ade5b00a21
+  metadata.gz: f9e138a46699147e1afbf586d1fdc78a467f3e5c7ddcbbbf8421d6151b0e36bed7754a2c990ae16ec61b996dc972f2b41cdda694bff36db2d1ed501f05baef8d
+  data.tar.gz: 648590c449721d663b85003c779f83abbcdde2b1c72dc606b5875bcc02282cb3715aeb66126cdcb128349e541d17859a5b4aeea987123f89de3331af9072b849

data/.gitignore

@@ -17,4 +17,6 @@ capybara-*.html
 rerun.txt
 pickle-email-*.html
 /pkg/*
+.vagrant/machines/*
 
+.coveralls.yml

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.1.0
+  - jruby-19mode
+  - ruby-head
+  - jruby-head
+jdk:
+  - oraclejdk7
+before_install:
+  - gem update --system
+  - gem --version

data/.vagrant/bootstrap/settings.json

@@ -0,0 +1,70 @@
+{
+    "alt-speed-down": 50,
+    "alt-speed-enabled": false,
+    "alt-speed-time-begin": 540,
+    "alt-speed-time-day": 127,
+    "alt-speed-time-enabled": false,
+    "alt-speed-time-end": 1020,
+    "alt-speed-up": 50,
+    "bind-address-ipv4": "0.0.0.0",
+    "bind-address-ipv6": "::",
+    "blocklist-enabled": false,
+    "blocklist-url": "http://www.example.com/blocklist",
+    "cache-size-mb": 4,
+    "dht-enabled": true,
+    "download-dir": "/home/vagrant/downloads/",
+    "download-limit": 100,
+    "download-limit-enabled": 0,
+    "download-queue-enabled": true,
+    "download-queue-size": 5,
+    "encryption": 2,
+    "idle-seeding-limit": 30,
+    "idle-seeding-limit-enabled": false,
+    "incomplete-dir": "/root/Downloads",
+    "incomplete-dir-enabled": false,
+    "lpd-enabled": false,
+    "max-peers-global": 200,
+    "message-level": 2,
+    "peer-congestion-algorithm": "",
+    "peer-limit-global": 240,
+    "peer-limit-per-torrent": 60,
+    "peer-port": 51413,
+    "peer-port-random-high": 65535,
+    "peer-port-random-low": 49152,
+    "peer-port-random-on-start": false,
+    "peer-socket-tos": "default",
+    "pex-enabled": true,
+    "port-forwarding-enabled": false,
+    "preallocation": 1,
+    "prefetch-enabled": 1,
+    "queue-stalled-enabled": true,
+    "queue-stalled-minutes": 30,
+    "ratio-limit": 2,
+    "ratio-limit-enabled": false,
+    "rename-partial-files": true,
+    "rpc-authentication-required": true,
+    "rpc-bind-address": "0.0.0.0",
+    "rpc-enabled": true,
+    "rpc-password": "{f95980ad4f56d462b8c27311d7091373b3fdcbc8jwb6VOkY",
+    "rpc-port": 9091,
+    "rpc-url": "/transmission/",
+    "rpc-username": "admin",
+    "rpc-whitelist": "*",
+    "rpc-whitelist-enabled": true,
+    "scrape-paused-torrents-enabled": true,
+    "script-torrent-done-enabled": false,
+    "script-torrent-done-filename": "",
+    "seed-queue-enabled": false,
+    "seed-queue-size": 10,
+    "speed-limit-down": 100,
+    "speed-limit-down-enabled": false,
+    "speed-limit-up": 100,
+    "speed-limit-up-enabled": false,
+    "start-added-torrents": true,
+    "trash-original-torrent-files": false,
+    "umask": 18,
+    "upload-limit": 100,
+    "upload-limit-enabled": 0,
+    "upload-slots-per-torrent": 14,
+    "utp-enabled": true
+}

data/.vagrant/bootstrap/testing.sh

@@ -0,0 +1,34 @@
+echo "======================================================="
+echo " Updating Apt... "
+echo "======================================================="
+sudo DEBIAN_FRONTEND=noninteractive apt-get -q -y -o Dpkg::Options::="--force-confdef" update
+
+echo "======================================================="
+echo " Installing Dependencies... "
+echo "======================================================="
+sudo DEBIAN_FRONTEND=noninteractive apt-get -q -y -o Dpkg::Options::="--force-confdef" install transmission-cli transmission-common transmission-daemon
+
+echo "======================================================="
+echo " Configuring... "
+echo "======================================================="
+# ruby /vagrant/.vagrant/bootstrap/testing.rb
+
+# prepare paths
+sudo mkdir -p /home/vagrant/downloads/
+sudo chmod -R 777 /home/vagrant/downloads/
+# register daemon
+sudo update-rc.d transmission-daemon defaults
+# push config and restart
+sudo service transmission-daemon stop
+sudo cp /vagrant/.vagrant/bootstrap/settings.json /var/lib/transmission-daemon/info/settings.json
+sudo chown debian-transmission /var/lib/transmission-daemon/info/settings.json
+sudo service transmission-daemon start
+
+echo "======================================================="
+echo " VM is up and running!"
+echo " ---------------------"
+echo " Running service at: http://localhost:19091 (tunneled)"
+echo " - You can now start testing!"
+echo " $ CONFIG=\"{\\\"host\\\":\\\"localhost\\\",\\\"port\\\":\\\"19091\\\",\\\"user\\\":\\\"admin\\\",\\\"pass\\\":\\\"adm1n\\\",\\\"path\\\":\\\"/transmission/rpc\\\"}\" ruby -I test test/unit/trans_connect.rb"
+echo "======================================================="
+

data/Gemfile.lock

@@ -1,26 +1,52 @@
 PATH
   remote: .
   specs:
-    trans-api (0.0.3)
+    trans-api (0.0.4)
       json (> 1.6.1)
       nokogiri (> 1.5.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    coveralls (0.7.1)
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      term-ansicolor
+      thor
+    docile (1.1.5)
     json (1.8.1)
     json (1.8.1-java)
-    mini_portile (0.5.2)
-    nokogiri (1.6.1)
-      mini_portile (~> 0.5.0)
-    nokogiri (1.6.1-java)
-      mini_portile (~> 0.5.0)
-    test-unit (2.5.2)
+    mime-types (2.3)
+    mini_portile (0.6.0)
+    multi_json (1.10.1)
+    netrc (0.7.7)
+    nokogiri (1.6.3.1)
+      mini_portile (= 0.6.0)
+    nokogiri (1.6.3.1-java)
+    power_assert (0.1.3)
+    rake (10.3.2)
+    rest-client (1.7.2)
+      mime-types (>= 1.16, < 3.0)
+      netrc (~> 0.7)
+    simplecov (0.9.1)
+      docile (~> 1.1.0)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    term-ansicolor (1.3.0)
+      tins (~> 1.0)
+    test-unit (3.0.1)
+      power_assert
+    thor (0.19.1)
+    tins (1.3.3)
 
 PLATFORMS
   java
   ruby
 
 DEPENDENCIES
-  test-unit (> 2.0.0)
+  coveralls (> 0.7.0)
+  rake (> 10.0.0)
+  test-unit (> 3.0.0)
   trans-api!

data/README.md

@@ -3,6 +3,8 @@
 Trans::Api is an ruby implementation for Transmission RPC (bittorrent client). Based on RPC spec 13328
 https://trac.transmissionbt.com/browser/trunk/extras/rpc-spec.txt
 
+[![Build Status](https://travis-ci.org/dblommesteijn/trans-api.svg?branch=master)](https://travis-ci.org/dblommesteijn/trans-api) [![Coverage Status](https://coveralls.io/repos/dblommesteijn/trans-api/badge.png)](https://coveralls.io/r/dblommesteijn/trans-api) [![Code Climate](https://codeclimate.com/github/dblommesteijn/trans-api.png)](https://codeclimate.com/github/dblommesteijn/trans-api) [![Dependency Status](https://gemnasium.com/dblommesteijn/trans-api.svg)](https://gemnasium.com/dblommesteijn/trans-api)
+
 It required for the Transmission RPC to run the 'remote access':
 
 OSX:
@@ -14,55 +16,53 @@ OSX:
 
 This gem is (build and) tested with:
 
-  OSX Lion, Mountain Lion, Mavericks
-
-  Ruby 1.9.3, 2.1.0
-
-  Rails: 3.2.8, 3.2.9, 4.0.3
-
-  Transmission 2.73 (13589) - 2.82 (14160)
+  * OSX: Lion, Mountain Lion, Mavericks
+  * Ruby: 1.9.3, 2.1.0
+  * Rails: 3.2.8, 3.2.9, 4.0.3
+  * Transmission 2.73 (13589) - 2.82 (14160)
 
 
 ### Roadmap
 
 * Version (0.0.1)
 
-  Initial project import.
+  * Initial project import.
 
 * Version (0.0.2)
 
-  Session object include: 'blocklist', 'port-test'
-
-  Torrent object include 'torrent-start-now', 'queue-move-top/up/down/bottom'
-
-  Torrent object 'delete_all!' explicit torrent references
-
-  Torrent object 'waitfor' helper to check for lambda after/before calling it's chained cousin
+  * Session object include: 'blocklist', 'port-test'
+  * Torrent object include 'torrent-start-now', 'queue-move-top/up/down/bottom'
+  * Torrent object 'delete_all!' explicit torrent references
+  * Torrent object 'waitfor' helper to check for lambda after/before calling it's chained cousin
 
 * Version (0.0.3)
 
-  Querying name before add (duplicate detect), not hammering torrent-add (due to a transmission BUG)
-
-  Added some File internal fields (total and completed transfer)
+  * Querying name before add (duplicate detect), not hammering torrent-add (due to a transmission BUG)
+  * Added some File internal fields (total and completed transfer)
 
 * Version (0.0.4)
 
-  Added Session.alt_speed_time_day_options, returns a list of values to set `alt_speed_time_day`
+  * Added Session.alt_speed_time_day_options, returns a list of values to set `alt_speed_time_day`
+  * Added Session.reload!, that reconnects to the client (for example using alternate configs)
+  * Added Session.update_blocklist!, updating the current set blocklist
+
+* Version (0.0.5)
 
-  Added Session.reload!, that reconnects to the client (for example using alternate configs)
+  * Added Session.connected?, checks if there is a valid connection to the client
+  * Fixed Torrent.waitfor chained method arguements
+  * Added magnet support
 
-  Added Session.update_blocklist!, updating the current set blocklist
+* Version (0.0.6)
 
+  * TBA
 
-### Changelog
+
+### Changelog (call changes)
 
 * Version (0.0.3)
-  
-  Torrent.add_metainfo(base64, filename, options={}) -> requires a filename parameter
 
-* Version (0.0.4)
+  * Torrent.add_metainfo(base64, filename, options={}) -> requires a filename parameter
 
-  TBA
 
 ### Known Issues
 
@@ -70,6 +70,8 @@ The Transmission RPC call 'torrent-remove' (implemented as torrent.delete! and T
 
 Due to a Transmission bug (https://trac.transmissionbt.com/ticket/5614) duplicate torrents are accepted by the RPC call. The GUI will eventually crash the daemon, when interacting with these duplicate files (or instances). Torrent.add_file/ add_metainfo queries for duplicates to omit this bug.
 
+On rapid RPC calls the client will ignore the request, and respond with successfull. For example rapid Torrent.delete! will respond with status successfull, but it remains active. You can use a blocked call via waitfor (chained) to make sure the action was completed.
+
 
 ## Installation
 
@@ -82,7 +84,7 @@ And then execute:
     $ bundle
 
 
-## Setup
+## Configuration
 
 Define a configuration for your connection (initialize script)
 
@@ -116,10 +118,6 @@ torrent = Trans::Api::Torrent.find id
 torrent.files
 ```
 
-## Examples
-
-  Check the examples/ folder or Unit tests: test/unit/trans_ (session/torrent) _object.rb
-
 
 ## Usage
 
@@ -194,6 +192,13 @@ base64_file_contents = Base64.encode64 file.read
 Trans::Api::Torrent.add_metainfo base64_file_contents, file_name, options
 ```
 
+Add magnet URI
+
+```ruby
+magnet_link = "magnet:?xt=urn:btih:42ae58b8f59bd19fe97d6ca6fd884b2e9666a4d1&dn=debian-6.0.6-amd64-CD-2.iso&tr=http%3A%2F%2Fbttracker.debian.org%3A6969%2Fannounce"
+torrent = Trans::Api::Torrent.add_magnet(magnet_link, paused: true)
+```
+
 Get all fields
 ```ruby
 Trans::Api::Torrent.ACCESSOR_FIELDS
@@ -271,8 +276,7 @@ torrent.reannounce!
 Delete (tranmission daemon will crash on rapid call)
 
 ```ruby
-options = {delete_local_data: true}
-torrent.delete! options
+torrent.delete! {delete_local_data: true}
 ```
 
 Waitfor (automatic delayed responce after/before chained method is called)
@@ -283,9 +287,13 @@ Waitfor (automatic delayed responce after/before chained method is called)
 # waitfor status name not equals stopped after calling start!
 optional = :after
 torrent.waitfor( lambda{|t| t.status_name != :stopped}, optional ).start!
+
 # waitfor status name equals stopped after calling stop!
 torrent.waitfor( lambda{|t| t.status_name == :stopped}, optional ).stop!
 # NOTE: waitfor can be used for blocking without a chained method (optional = :before only)
+
+# via the Torrent object `reset_exception` we can verify if the torrent is probably removed
+torrent.waitfor(lambda{|t| t.last_error[:error] == "reset_exception"}).delete!(delete_local_data: true)
 ```
 
 NOTE: defined torrent accessor fields are defined as instance methods to the Torrent object
@@ -332,7 +340,7 @@ session.blocklist_url = "http://list.iblocklist.com/?list=bt_level3&fileformat=p
 session.blocklist_enable = true
 # save changes
 session.save!
-# force update 
+# force update
 begin
   session.update_blocklist!
 rescue Exception => e
@@ -350,10 +358,11 @@ Getting files from a torrent (file cannot be used standalone, it's an helper cla
 ```ruby
 id = 1
 torrent = Trans::Api::Torrent.find id
-files = torrent.files_objects
-files.each do |file|
-	# manipulate file here!
+torrent.files_objects.each do |file|
+	# manipulate or stat the file here! (unwant, want)
 end
+# save the torrent (internal changes to files_objects are saved as well)
+torrent.save!
 ```
 
 File name
@@ -380,7 +389,7 @@ File wanted? (marked for download)
 file.wanted?
 ```
 
-File stats
+File stat
 
 ```ruby
 file.stat
@@ -390,4 +399,78 @@ NOTE: changed preferences (want, unwant) set options on the linked Torrent objec
 
 
 
+## Running Tests
+
+Run the unittest embedded with the project from the commandline. Configure the CONFIG variable with an escaped json to provide configuration for your transmission client.
+
+* WARNING: torrents and files will be destroyed by these tests *
+
+
+```bash
+# example format: define CONFIG in escaped json
+$ CONFIG="{\"host\":\"localhost\",\"port\":1234,\"user\":\"youruser\",\"pass\":\"yourpass\",\"path\":\"/transmission/rpc\"}"
+```
+
+Run 'test/unit/trans_connect.rb' to test the intermediate layer between the RPC API and wrappers.
+
+```bash
+$ CONFIG="{\"host\":\"localhost\",\"port\":1234,\"user\":\"youruser\",\"pass\":\"yourpass\",\"path\":\"/transmission/rpc\"}" ruby -I test test/unit/trans_connect.rb
+```
+
+Run 'test/unit/trans_session_object.rb' to test the working of Trans::Api::Session.
+
+```bash
+# run unit test session
+$ CONFIG="{\"host\":\"localhost\",\"port\":1234,\"user\":\"youruser\",\"pass\":\"yourpass\",\"path\":\"/transmission/rpc\"}" ruby -I test test/unit/trans_session_object.rb
+```
+
+Run 'test/unit/trans_torrent_object.rb' to test the working of Trans::Api::Torrent.
+
+```bash
+# run unit test session
+$ CONFIG="{\"host\":\"localhost\",\"port\":1234,\"user\":\"youruser\",\"pass\":\"yourpass\",\"path\":\"/transmission/rpc\"}" ruby -I test test/unit/trans_torrent_object.rb
+```
+
+NOTE: test `test_torrent_rapid_delete` will fail because of an issue with rapid calling.
+
+
+### Vagrant
+
+Besides running your existing client with Transmission you can test on an isolated virtual machine via Vagrant.
+
+**Download Dependencies**
+
+Download and follow the installation instructions.
+
+* Vagrant: http://www.vagrantup.com/downloads.html
+* VirtualBox: https://www.virtualbox.org/wiki/Downloads
+
+
+##### Boot the Test VM
+
+Download and run the testing Debian Linux distribution with a test Transmission client.
+
+```bash
+$ cd /location/of/trans-api
+# download and start a testing box (will take some time)
+$ vagrant up testing
+```
+
+**Configure the CONFIG variable to target the VM**
+
+```bash
+# use this CONFIG string to connect to the testing instance
+$ CONFIG="{\"host\":\"localhost\",\"port\":19091,\"user\":\"admin\",\"pass\":\"adm1n\",\"path\":\"/transmission/rpc\"}"
+# run tests like described above
+```
+
+*NOTE: don't forget to HALT (and DESTROY) the VM when done!*
+
+```bash
+# power down VM
+$ vagrant halt testing
+# power down and destroy files
+$ vagrant destroy testing
+```
+
 

data/Rakefile

@@ -1 +1,15 @@
 require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  tfs = FileList['test/unit/*.rb']
+  t.test_files = tfs
+  t.verbose = true
+end
+
+require 'coveralls/rake/task'
+Coveralls::RakeTask.new
+
+task test_with_coveralls: ['test', 'coveralls:push']
+task default: [:build, :install]

data/Vagrantfile

@@ -0,0 +1,18 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# vagrant config
+Vagrant.configure("2") do |config|
+
+  # testing configuration
+  config.vm.define "testing" do |testing|
+    testing.vm.box = "chef/debian-7.4"
+    testing.vm.provision :shell, path: ".vagrant/bootstrap/testing.sh"
+    testing.vm.network :forwarded_port, guest: 9091, host: 19091
+    testing.vm.network :private_network, ip: "10.1.1.2"
+    testing.vm.provider :virtualbox do |vb|
+      vb.customize ["modifyvm", :id, "--memory", "256"]
+    end
+  end
+
+end

data/lib/trans-api/client.rb

@@ -2,12 +2,13 @@ module Trans
   module Api
 
     class Client
-      DEFAULT = {scheme: "http", host: "localhost", port: 9091, path: "/transmission/rpc", user: "admin", pass: "admin"}
+      DEFAULT = {scheme: "http", host: "localhost", port: 9091, path: "/transmission/rpc", user: "admin", pass: "admin", timeout: 5}
 
       # construct
 
       def initialize(options={})
-        args = @@config
+        # @@config ||= {}
+        args = @@config || {}
         args.merge!(options)
         @conn = Connect.new args
       end
@@ -19,6 +20,11 @@ module Trans
       class << self
         def config=(config = {})
           config[:port] = config[:port].to_i if config.include? :port
+          if config.include? :timeout
+            config[:timeout] = config[:timeout].to_i
+          else
+            config[:timeout] = DEFAULT[:timeout]
+          end
           @@config = config
         end
       end