proxy_fetcher 0.6.2 → 0.6.3

data/lib/proxy_fetcher/providers/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ProxyFetcher
   module Providers
     # Base class for all the ProxyFetcher providers.
@@ -8,18 +10,26 @@ module ProxyFetcher
         load_proxy_list(filters).map { |html| to_proxy(html) }
       end
 
-      class << self
-        # Just synthetic sugar to make it easier to call #fetch_proxies! method.
-        def fetch_proxies!(*args)
-          new.fetch_proxies!(*args)
-        end
+      # Just synthetic sugar to make it easier to call #fetch_proxies! method.
+      def self.fetch_proxies!(*args)
+        new.fetch_proxies!(*args)
       end
 
       protected
 
       # Loads HTML document with Nokogiri by the URL combined with custom filters
+      #
+      # @param url [String]
+      #   URL to fetch
+      #
+      # @param filters [Hash]
+      #   filters for proxy provider
+      #
+      # @return [ProxyFetcher::Document]
+      #   ProxyFetcher document object
+      #
       def load_document(url, filters = {})
-        raise ArgumentError, 'filters must be a Hash' unless filters.is_a?(Hash)
+        raise ArgumentError, 'filters must be a Hash' if filters && !filters.is_a?(Hash)
 
         uri = URI.parse(url)
         uri.query = URI.encode_www_form(filters) if filters && filters.any?
@@ -32,13 +42,22 @@ module ProxyFetcher
       # parses the document (built as abstract <code>ProxyFetcher::Document</code>)
       # to return all the proxy entries (HTML nodes).
       #
-      # Abstract method.
+      # Abstract method. Must be implemented in a descendant class
+      #
+      # @return [Array<Document::Node>]
+      #   list of proxy elements from the providers HTML content
       #
       def load_proxy_list(*)
         raise NotImplementedError, "#{__method__} must be implemented in a descendant class!"
       end
 
-      # Convert HTML element with proxy info to ProxyFetcher::Proxy instance
+      # Convert HTML element with proxy info to ProxyFetcher::Proxy instance.
+      #
+      # Abstract method. Must be implemented in a descendant class
+      #
+      # @return [Proxy]
+      #   new proxy object from the HTML node
+      #
       def to_proxy(*)
         raise NotImplementedError, "#{__method__} must be implemented in a descendant class!"
       end

data/lib/proxy_fetcher/providers/free_proxy_list.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ProxyFetcher
   module Providers
     # FreeProxyList provider class.

data/lib/proxy_fetcher/providers/free_proxy_list_ssl.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ProxyFetcher
   module Providers
     # FreeProxyListSSL provider class.

data/lib/proxy_fetcher/providers/gather_proxy.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'json'
 
 module ProxyFetcher

data/lib/proxy_fetcher/providers/http_tunnel.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ProxyFetcher
   module Providers
     # HTTPTunnel provider class.

data/lib/proxy_fetcher/providers/proxy_docker.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ProxyFetcher
   module Providers
     # ProxyDocker provider class.

data/lib/proxy_fetcher/providers/proxy_list.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'base64'
 
 module ProxyFetcher

data/lib/proxy_fetcher/providers/xroxy.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ProxyFetcher
   module Providers
     # XRoxy provider class.

data/lib/proxy_fetcher/proxy.rb

@@ -1,9 +1,33 @@
+# frozen_string_literal: true
+
 module ProxyFetcher
   # Proxy object
   class Proxy
-    attr_accessor :addr, :port, :type, :country, :response_time, :anonymity
+    # @!attribute [rw] addr
+    #   @return [String] address (IP or domain)
+    attr_accessor :addr
+
+    # @!attribute [rw] port
+    #   @return [Integer] port
+    attr_accessor :port
+
+    # @!attribute [rw] type
+    #   @return [String] type (SOCKS, HTTP(S))
+    attr_accessor :type
+
+    # @!attribute [rw] country
+    #   @return [String] country or country code
+    attr_accessor :country
+
+    # @!attribute [rw] response_time
+    #   @return [Integer] response time (value and measurements depends on the provider)
+    attr_accessor :response_time
 
-    # Proxy type
+    # @!attribute [rw] anonymity
+    #   @return [String] anonymity level (high, elite, transparent, etc)
+    attr_accessor :anonymity
+
+    # Proxy types
     TYPES = [
       HTTP = 'HTTP'.freeze,
       HTTPS = 'HTTPS'.freeze,
@@ -31,14 +55,21 @@ module ProxyFetcher
       https? || socks4? || socks5?
     end
 
+    # Initialize new Proxy
+    #
+    # @param attributes [Hash]
+    #   proxy attributes
+    #
+    # @return [Proxy]
+    #
     def initialize(attributes = {})
       attributes.each do |attr, value|
         public_send("#{attr}=", value)
       end
     end
 
-    # Checks if proxy object is connectable? (can be used as a proxy for
-    # network requests).
+    # Checks if proxy object is connectable (can be used as a proxy for
+    # HTTP requests).
     #
     # @return [Boolean]
     #   true if proxy connectable, otherwise false.
@@ -58,7 +89,7 @@ module ProxyFetcher
       URI::Generic.build(host: addr, port: port)
     end
 
-    # Returns <code>String</object> object with <i>addr:port<i> values of the proxy.
+    # Returns <code>String</code> object with <i>addr:port</i> values of the proxy.
     #
     # @return [String]
     #   true if proxy connectable, otherwise false.

data/lib/proxy_fetcher/utils/http_client.rb

@@ -1,10 +1,22 @@
+# frozen_string_literal: true
+
 module ProxyFetcher
   # Default ProxyFetcher HTTP client used to fetch proxy lists from
   # the different providers. Uses ProxyFetcher configuration options
   # for sending HTTP requests to providers URLs.
   class HTTPClient
-    attr_reader :uri, :http
+    # @!attribute [r] uri
+    #   @return [URI] URI
+    attr_reader :uri
+
+    # @!attribute [r] http
+    #   @return [Net::HTTP] HTTP client
+    attr_reader :http
 
+    # Initialize HTTP client instance
+    #
+    # @return [HTTPClient]
+    #
     def initialize(url)
       @uri = URI.parse(url)
       @http = Net::HTTP.new(@uri.host, @uri.port)
@@ -14,6 +26,11 @@ module ProxyFetcher
       @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
     end
 
+    # Fetches resource content by sending HTTP request to it.
+    #
+    # @return [String]
+    #   response body
+    #
     def fetch
       request = Net::HTTP::Get.new(@uri.to_s)
       request['Connection'] = 'keep-alive'
@@ -22,14 +39,25 @@ module ProxyFetcher
       response.body
     end
 
-    def https?
-      @uri.is_a?(URI::HTTPS)
+    # Fetches resource content by sending HTTP request to it.
+    # Synthetic sugar to simplify URIes fetching.
+    #
+    # @param url [String] URL
+    #
+    # @return [String]
+    #   resource content
+    #
+    def self.fetch(url)
+      new(url).fetch
     end
 
-    class << self
-      def fetch(url)
-        new(url).fetch
-      end
+    # Checks if URI requires secure connection (HTTPS)
+    #
+    # @return [Boolean]
+    #   true if URI is HTTPS, false otherwise
+    #
+    def https?
+      @uri.is_a?(URI::HTTPS)
     end
   end
 end

data/lib/proxy_fetcher/utils/proxy_validator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ProxyFetcher
   # Default ProxyFetcher proxy validator that checks either proxy
   # connectable or not. It tries to send HEAD request to default
@@ -6,6 +8,13 @@ module ProxyFetcher
     # Default URL that will be used to check if proxy can be used.
     URL_TO_CHECK = 'https://google.com'.freeze
 
+    # Initialize new ProxyValidator instance
+    #
+    # @param proxy_addr [String] proxy address or IP
+    # @param proxy_port [String, Integer] proxy port
+    #
+    # @return [ProxyValidator]
+    #
     def initialize(proxy_addr, proxy_port)
       uri = URI.parse(URL_TO_CHECK)
       @http = Net::HTTP.new(uri.host, uri.port, proxy_addr, proxy_port.to_i)
@@ -16,6 +25,12 @@ module ProxyFetcher
       @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
     end
 
+    # Checks if proxy is connectable (can be used to connect
+    # resources via proxy server).
+    #
+    # @return [Boolean]
+    #   true if connection to the server using proxy established, otherwise false
+    #
     def connectable?
       @http.open_timeout = ProxyFetcher.config.timeout
       @http.read_timeout = ProxyFetcher.config.timeout
@@ -27,10 +42,16 @@ module ProxyFetcher
       false
     end
 
-    class << self
-      def connectable?(proxy_addr, proxy_port)
-        new(proxy_addr, proxy_port).connectable?
-      end
+    # Short variant to validate proxy.
+    #
+    # @param proxy_addr [String] proxy address or IP
+    # @param proxy_port [String, Integer] proxy port
+    #
+    # @return [Boolean]
+    #   true if connection to the server using proxy established, otherwise false
+    #
+    def self.connectable?(proxy_addr, proxy_port)
+      new(proxy_addr, proxy_port).connectable?
     end
   end
 end

data/lib/proxy_fetcher/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ProxyFetcher
   ##
   # ProxyFetcher gem version.
@@ -13,7 +15,7 @@ module ProxyFetcher
     # Minor version number
     MINOR = 6
     # Smallest version number
-    TINY  = 2
+    TINY  = 3
 
     # Full version number
     STRING = [MAJOR, MINOR, TINY].compact.join('.')

data/proxy_fetcher.gemspec

@@ -5,7 +5,7 @@ require 'proxy_fetcher/version'
 Gem::Specification.new do |gem|
   gem.name = 'proxy_fetcher'
   gem.version = ProxyFetcher.gem_version
-  gem.date = '2017-12-27'
+  gem.date = '2018-02-13'
   gem.summary = 'Ruby gem for dealing with proxy lists from different providers'
   gem.description = 'This gem can help your Ruby application to make HTTP(S) requests ' \
                     'using proxies by fetching and validating proxy lists from the different providers.'

data/spec/proxy_fetcher/{client_spec.rb → client/client_spec.rb}

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 require 'json'
 
@@ -40,6 +42,14 @@ describe ProxyFetcher::Client do
       expect(content).not_to be_nil
       expect(content).not_to be_empty
     end
+
+    it 'successfully returns page content using custom proxy' do
+      manager = ProxyFetcher::Manager.new
+      content = ProxyFetcher::Client.get('http://httpbin.org', options: { proxy: manager.get! })
+
+      expect(content).not_to be_nil
+      expect(content).not_to be_empty
+    end
   end
 
   context 'POST request with the valid proxy' do

data/spec/proxy_fetcher/configuration_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe ProxyFetcher::Configuration do

data/spec/proxy_fetcher/document/adapters_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe ProxyFetcher::Document::Adapters do

data/spec/proxy_fetcher/document/node_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe ProxyFetcher::Document::Node do

data/spec/proxy_fetcher/providers/base_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe ProxyFetcher::Providers::Base do

data/spec/proxy_fetcher/providers/free_proxy_list_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe ProxyFetcher::Providers::FreeProxyList do

data/spec/proxy_fetcher/providers/free_proxy_list_ssl_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe ProxyFetcher::Providers::FreeProxyListSSL do

data/spec/proxy_fetcher/providers/gather_proxy_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe ProxyFetcher::Providers::GatherProxy do

data/spec/proxy_fetcher/providers/http_tunnel_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe ProxyFetcher::Providers::HTTPTunnel do

data/spec/proxy_fetcher/providers/multiple_providers_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe 'Multiple proxy providers' do

data/spec/proxy_fetcher/providers/proxy_docker_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe ProxyFetcher::Providers::ProxyDocker do

data/spec/proxy_fetcher/providers/proxy_list_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe ProxyFetcher::Providers::ProxyList do

data/spec/proxy_fetcher/providers/xroxy_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe ProxyFetcher::Providers::XRoxy do

data/spec/proxy_fetcher/proxy_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe ProxyFetcher::Proxy do

data/spec/proxy_fetcher/version_spec.rb

@@ -0,0 +1,3 @@
+RSpec.describe ProxyFetcher::VERSION do
+  it { expect(ProxyFetcher::VERSION::STRING).to eq '0.6.3' }
+end