rarbg 0.1.4 → 1.0.0

data/lib/rarbg/api.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday_middleware'
+
+# Main namespace for RARBG
+module RARBG
+  # Default error class for the module.
+  class APIError < StandardError; end
+
+  # Base class for RARBG API.
+  class API
+    # RARBG API endpoint.
+    API_ENDPOINT = 'https://torrentapi.org/pubapi_v2.php'
+
+    # App name identifier.
+    APP_ID = 'rarbg-rubygem'
+
+    # Default token expiration time.
+    TOKEN_EXPIRATION = 800
+
+    # @return [Faraday::Connection] the Faraday connection object.
+    attr_reader :conn
+
+    # @return [String] the token used for authentication.
+    attr_reader :token
+
+    # @return [Integer] the monotonic timestamp of the token request.
+    attr_reader :token_time
+
+    # @return [Integer] the monotonic timestamp of the last request performed.
+    attr_reader :last_request
+
+    # Initialize a new istance of `RARBG::API`.
+    #
+    # @example
+    #   rarbg = RARBG::API.new
+    def initialize
+      @conn = Faraday.new(url: API_ENDPOINT) do |conn|
+        conn.request  :json
+        conn.response :json
+        conn.adapter  Faraday.default_adapter
+
+        conn.options.timeout = 90
+        conn.options.open_timeout = 10
+
+        conn.params[:app_id] = APP_ID
+      end
+    end
+
+    # List torrents.
+    #
+    # @param params [Hash] A customizable set of parameters.
+    #
+    # @option params [Array<Integer>] :category Filter results by category.
+    # @option params [Symbol] :format Format results.
+    #   Valid values: `:json`, `:json_extended`. Default: `:json`.
+    # @option params [Integer] :limit Limit results number.
+    #   Valid values: `25`, `50`, `100`. Default: `25`.
+    # @option params [Integer] :min_seeders Filter results by minimum seeders.
+    # @option params [Integer] :min_leechers Filter results by minimum leechers.
+    # @option params [Boolean] :ranked Include/exclude unranked results.
+    # @option params [Symbol] :sort Sort results.
+    #   Valid values: `:last`, `:seeders`, `:leechers`. Default: `:last`.
+    #
+    # @return [Array<Hash>] Return torrents that match the specified parameters.
+    #
+    # @raise [ArgumentError] Exception raised if `params` is not an `Hash`.
+    #
+    # @raise [RARBG::APIError] Exception raised when request fails or endpoint
+    #   responds with an error.
+    #
+    # @example List last 100 ranked torrents in `Movies/x264/1080`
+    #   rarbg = RARBG::API.new
+    #   rarbg.list(limit: 100, ranked: true, category: [44])
+    #
+    # @example List all torrent with minimum 50 seeders
+    #   rarbg = RARBG::API.new
+    #   rarbg.list(min_seeders: 50)
+    def list(params = {})
+      raise ArgumentError, 'Expected params hash' unless params.is_a?(Hash)
+
+      params.update(
+        mode:   'list',
+        token:  token?
+      )
+      call(params)
+    end
+
+    # Search torrents.
+    #
+    # @param params [Hash] A customizable set of parameters.
+    #
+    # @option params [String] :string Search results by string.
+    # @option params [String] :imdb Search results by IMDb id.
+    # @option params [String] :tvdb Search results by TVDB id.
+    # @option params [String] :themoviedb Search results by The Movie DB id.
+    # @option params [Array<Integer>] :category Filter results by category.
+    # @option params [Symbol] :format Format results.
+    #   Valid values: `:json`, `:json_extended`. Default: `:json`
+    # @option params [Integer] :limit Limit results number.
+    #   Valid values: `25`, `50`, `100`. Default: `25`.
+    # @option params [Integer] :min_seeders Filter results by minimum seeders.
+    # @option params [Integer] :min_leechers Filter results by minimum leechers.
+    # @option params [Boolean] :ranked Include/exclude unranked results.
+    # @option params [Symbol] :sort Sort results.
+    #   Valid values: `:last`, `:seeders`, `:leechers`. Default: `:last`.
+    #
+    # @return [Array<Hash>] Return torrents that match the specified parameters.
+    #
+    # @raise [ArgumentError] Exception raised if `params` is not an `Hash`.
+    #
+    # @raise [ArgumentError] Exception raised if no search type param is passed
+    #   (among `string`, `imdb`, `tvdb`, `themoviedb`).
+    #
+    # @raise [RARBG::APIError] Exception raised when request fails or endpoint
+    #   responds with an error.
+    #
+    # @example Search by IMDb ID, sorted by leechers and in extended format.
+    #   rarbg = RARBG::API.new
+    #   rarbg.search(imdb: 'tt012831', sort: :leechers, format: :json_extended)
+    #
+    # @example Search unranked torrents by string, with at least 2 seeders.
+    #   rarbg = RARBG::API.new
+    #   rarbg.search(string: 'Star Wars', ranked: false, min_seeders: 2)
+    def search(params = {})
+      raise ArgumentError, 'Expected params hash' unless params.is_a?(Hash)
+
+      params.update(
+        mode:   'search',
+        token:  token?
+      )
+      call(params)
+    end
+
+    private
+
+    # Wrap request for error handling.
+    def call(params)
+      response = request(validate(params))
+
+      return [] if response['error'] == 'No results found'
+      raise APIError, response['error'] if response.key?('error')
+      response.fetch('torrent_results', [])
+    end
+
+    # Validate parameters.
+    def validate(params)
+      params = stringify(params)
+      params = validate_search!(params) if params['mode'] == 'search'
+
+      normalize.each_pair do |key, proc|
+        params[key] = proc.call(params[key]) if params.key?(key)
+      end
+      params
+    end
+
+    # Convert symbol keys to string and remove nil values.
+    def stringify(params)
+      Hash[params.reject { |_k, v| v.nil? }.map { |k, v| [k.to_s, v] }]
+    end
+
+    # Validate search type parameter.
+    def validate_search!(params)
+      search_keys = %w[string imdb tvdb themoviedb]
+
+      raise(
+        ArgumentError,
+        "At least one parameter required among #{search_keys.join(', ')} " \
+        'for search mode.'
+      ) if (params.keys & search_keys).none?
+
+      search_keys.each do |k|
+        params["search_#{k}"] = params.delete(k) if params.key?(k)
+      end
+      params
+    end
+
+    # Convert ruby sugar to expected value style.
+    def normalize
+      {
+        'category' => (->(v) { v.join(';') }),
+        'imdb'     => (->(v) { v.to_s[/^tt/] ? v.to_s : "tt#{v}" }),
+        'ranked'   => (->(v) { v == false ? 0 : 1 })
+      }
+    end
+
+    # Return or renew auth token.
+    def token?
+      if @token.nil? || time >= (@token_time + TOKEN_EXPIRATION)
+        response = request(get_token: 'get_token')
+        @token = response.fetch('token')
+        @token_time = time
+      end
+      @token
+    end
+
+    # Perform API request.
+    def request(params)
+      rate_limit!(2.1)
+
+      response = @conn.get(nil, params)
+      @last_request = time
+
+      return response.body if response.success?
+      raise APIError, "#{response.reason_phrase} (#{response.status})"
+    end
+
+    # Rate-limit requests to comply with endpoint limits.
+    def rate_limit!(seconds)
+      sleep(0.3) until time >= ((@last_request || 0) + seconds)
+    end
+
+    # Monotonic clock for elapsed time calculations.
+    def time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/rarbg/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module RARBG
+  # Gem version
+  VERSION = '1.0.0'
+end

data/rarbg.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rarbg/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'rarbg'
+  spec.version       = RARBG::VERSION
+  spec.author        = 'Tommaso Barbato'
+  spec.email         = 'epistrephein@gmail.com'
+
+  spec.summary       = 'RARBG Ruby client.'
+  spec.description   = 'Ruby wrapper for RARBG Torrent API.'
+  spec.homepage      = 'https://github.com/epistrephein/rarbg'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  spec.require_path  = 'lib'
+
+  spec.metadata = {
+    'bug_tracker_uri'   => 'https://github.com/epistrephein/rarbg/issues',
+    'changelog_uri'     => 'https://github.com/epistrephein/rarbg/blob/master/CHANGELOG.md',
+    'documentation_uri' => 'http://www.rubydoc.info/gems/rarbg',
+    'homepage_uri'      => 'https://github.com/epistrephein/rarbg',
+    'source_code_uri'   => 'https://github.com/epistrephein/rarbg'
+  }
+
+  spec.required_ruby_version = '>= 2.0'
+
+  spec.add_runtime_dependency 'faraday', '~> 0.10'
+  spec.add_runtime_dependency 'faraday_middleware', '~> 0.10'
+
+  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'pry', '~> 0'
+  spec.add_development_dependency 'rake', '~> 12.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'simplecov', '~> 0'
+  spec.add_development_dependency 'webmock', '~> 3.3'
+  spec.add_development_dependency 'yard', '~> 0.9'
+end

data/spec/rarbg/list_spec.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+RSpec.describe RARBG::API do
+  before(:all) do
+    @rarbg = RARBG::API.new
+    @token = SecureRandom.hex(5)
+  end
+
+  before(:each) do
+    stub_token(@token)
+  end
+
+  context 'when list request succeeds' do
+    before(:example) do
+      stub_list(
+        @token, {},
+        { torrent_results: [
+          {
+            filename: 'first stubbed name',
+            category: 'first stubbed category',
+            download: 'first stubbed magnet link'
+          },
+          {
+            filename: 'second stubbed name',
+            category: 'second stubbed category',
+            download: 'second stubbed magnet link'
+          }
+        ] }
+      )
+    end
+
+    it 'returns and array of hashes' do
+      expect(@rarbg.list).to all(be_an(Hash))
+    end
+
+    it 'returns hashes with filename and download link' do
+      expect(@rarbg.list).to all(include('filename').and include('download'))
+    end
+  end
+
+  context 'when list request returns no result' do
+    before(:example) do
+      stub_list(
+        @token, {},
+        { error: 'No results found' }
+      )
+    end
+
+    it 'returns an empty array' do
+      expect(@rarbg.list).to eq([])
+    end
+  end
+
+  context 'when list request parameters is not an hash' do
+    before(:example) do
+      stub_list(
+        @token
+      )
+    end
+
+    it 'raises an ArgumentError exception' do
+      expect { @rarbg.list('string') }.to raise_error(
+        ArgumentError, 'Expected params hash'
+      )
+    end
+  end
+
+  context 'when list request has invalid parameters' do
+    before(:example) do
+      stub_list(
+        @token,
+        { min_seeders: 'string' },
+        { error: 'Invalid value for min_seeders' }
+      )
+    end
+
+    it 'raises a RARBG::APIError exception' do
+      expect { @rarbg.list(min_seeders: 'string') }.to raise_error(
+        RARBG::APIError, 'Invalid value for min_seeders'
+      )
+    end
+  end
+
+  context 'when list request fails' do
+    before(:example) do
+      stub_error(500, 'Internal Server Error')
+    end
+
+    it 'raises a RARBG::APIError exception' do
+      expect { @rarbg.list }.to raise_error(
+        RARBG::APIError, 'Internal Server Error (500)'
+      )
+    end
+  end
+end

data/spec/rarbg/rarbg_spec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+RSpec.describe RARBG::API do
+  it 'has a version number' do
+    expect(RARBG::VERSION).not_to be nil
+  end
+
+  it 'has an app id' do
+    expect(RARBG::API::APP_ID).not_to be nil
+  end
+
+  it 'has the correct API endpoint' do
+    expect(RARBG::API::API_ENDPOINT).to eq('https://torrentapi.org/pubapi_v2.php')
+  end
+
+  it 'has a token expiration' do
+    expect(RARBG::API::TOKEN_EXPIRATION).to be_kind_of(Numeric)
+  end
+end

data/spec/rarbg/search_spec.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+RSpec.describe RARBG::API do
+  before(:all) do
+    @rarbg = RARBG::API.new
+    @token = SecureRandom.hex(5)
+  end
+
+  before(:each) do
+    stub_token(@token)
+  end
+
+  context 'when search request succeeds' do
+    before(:example) do
+      stub_search(
+        @token, {},
+        { torrent_results: [
+          {
+            filename: 'first stubbed name',
+            category: 'first stubbed category',
+            download: 'first stubbed magnet link'
+          },
+          {
+            filename: 'second stubbed name',
+            category: 'second stubbed category',
+            download: 'second stubbed magnet link'
+          }
+        ] }
+      )
+    end
+
+    it 'returns and array of hashes' do
+      expect(@rarbg.search(string: 'a search string')).to all(be_an(Hash))
+    end
+
+    it 'returns hashes with filename and download link' do
+      expect(@rarbg.search(imdb: 'tt0000000'))
+        .to all(include('filename').and include('download'))
+    end
+  end
+
+  context 'when search request returns no result' do
+    before(:example) do
+      stub_search(
+        @token, {},
+        { error: 'No results found' }
+      )
+    end
+
+    it 'returns an empty array' do
+      expect(@rarbg.search(string: 'awrongquery')).to eq([])
+    end
+  end
+
+  context 'when search request parameters is not an hash' do
+    before(:example) do
+      stub_search(
+        @token
+      )
+    end
+
+    it 'raises an ArgumentError exception' do
+      expect { @rarbg.search('string') }.to raise_error(
+        ArgumentError, 'Expected params hash'
+      )
+    end
+  end
+
+  context 'when search request is missing search type' do
+    before(:example) do
+      stub_search(
+        @token
+      )
+    end
+
+    it 'raises an ArgumentError exception' do
+      expect { @rarbg.search(category: [45, 46], sort: :last) }
+        .to raise_error(ArgumentError)
+    end
+  end
+
+  context 'when search request has invalid parameters' do
+    before(:example) do
+      stub_search(
+        @token, {},
+        { error: 'Invalid sort' }
+      )
+    end
+
+    it 'raises a RARBG::APIError exception' do
+      expect { @rarbg.search(string: 'string', sort: 'wrongsort') }
+        .to raise_error(RARBG::APIError, 'Invalid sort')
+    end
+  end
+
+  context 'when search request fails' do
+    before(:example) do
+      stub_error(503, 'Service unavailable')
+    end
+
+    it 'raises a RARBG::APIError exception' do
+      expect { @rarbg.search(string: 'string') }.to raise_error(
+        RARBG::APIError, 'Service unavailable (503)'
+      )
+    end
+  end
+end