comic_vine 0.1.4 → 1.0.0

data/lib/comic_vine.rb

@@ -1,102 +1,307 @@
+# frozen_string_literal: true
+
 require "comic_vine/version"
 require "net/http"
-require "multi_json"
+require "openssl"
+require "json"
 require "cgi"
 
+# A simple Ruby interface to the ComicVine API
+# (https://comicvine.gamespot.com/api/).
+#
+# Set {ComicVine::API.key} and call resource methods on {ComicVine::API}:
+#
+#     ComicVine::API.key = "your-api-key"
+#     ComicVine::API.volume 766
+#     ComicVine::API.characters(limit: 5)
+#     ComicVine::API.search "volume", "batman"
 module ComicVine
-  
+  # Base class for all errors raised by this gem.
   class CVError < StandardError
   end
-  
+
+  # Raised when the ComicVine API answers with a non-success status_code
+  # (e.g. invalid API key, object not found).
+  class CVAPIError < CVError
+  end
+
+  # Raised when the connection fails or times out after all retries.
+  class CVConnectionError < CVError
+  end
+
+  # Raised when the server answers with a non-2xx HTTP status.
+  class CVHTTPError < CVError
+    # @return [Integer, nil] the HTTP status code, if known
+    attr_reader :status
+
+    # @param message [String] the error message
+    # @param status [Integer, nil] the HTTP status code
+    def initialize(message, status = nil)
+      @status = status
+      super(message)
+    end
+  end
+
+  # Raised on HTTP 420/429 once retries are exhausted. ComicVine rate-limits
+  # to roughly 200 requests per resource per hour.
+  class CVRateLimitError < CVHTTPError
+  end
+
+  # Raised when the response body is not valid JSON (e.g. an HTML error page).
+  class CVParseError < CVError
+  end
+
+  # Class-level entry point for all ComicVine API calls.
+  #
+  # Resource methods are resolved dynamically against the API's `/types/`
+  # list: plural resources (`characters`, `volumes`, ...) return a
+  # {CVObjectList}, singular resources (`character`, `volume`, ...) take an id
+  # and return a {CVObject}.
   class API
-    @@key = nil
-    
-    @@types = nil
-    @@last_type_check = nil
-    
-    @@API_BASE_URL = "http://comicvine.gamespot.com/api/"
+    API_BASE_URL = "https://comicvine.gamespot.com/api/"
+    TYPES_CACHE_TTL = 4 * 60 * 60
+    RETRYABLE_STATUS_CODES = [420, 429, 500, 502, 503, 504].freeze
+    RETRYABLE_EXCEPTIONS = [
+      Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED,
+      Errno::ETIMEDOUT, SocketError, EOFError, OpenSSL::SSL::SSLError
+    ].freeze
+
+    @key = nil
+    @types = nil
+    @last_type_check = nil
+    @types_mutex = Mutex.new
+
+    @open_timeout = 10
+    @read_timeout = 30
+    @max_retries = 3
+    @retry_base_delay = 1.0
 
     class << self
-      def search res, query, opts={}
-        opts[:resources] = res.gsub " ", ""
-        opts[:query] = CGI::escape query
-        resp = hit_api(build_base_url("search"), build_query(opts))
-        ComicVine::CVSearchList.new(resp, res, query)
+      # @!attribute key
+      #   @return [String, nil] your ComicVine API key (required)
+      attr_accessor :key
+
+      # @!attribute open_timeout
+      #   @return [Numeric] seconds to wait for the connection to open (default 10)
+      # @!attribute read_timeout
+      #   @return [Numeric] seconds to wait for a response (default 30)
+      attr_accessor :open_timeout, :read_timeout
+
+      # @!attribute max_retries
+      #   @return [Integer] retries on 420/429/5xx and connection errors (default 3)
+      # @!attribute retry_base_delay
+      #   @return [Numeric] base for exponential backoff, in seconds (default 1.0)
+      attr_accessor :max_retries, :retry_base_delay
+
+      attr_writer :user_agent
+
+      # The User-Agent header sent with every request.
+      #
+      # @return [String] defaults to `comic_vine gem/x.y.z (Ruby/x.y.z)`
+      def user_agent
+        @user_agent ||= "comic_vine gem/#{ComicVine::VERSION} (Ruby/#{RUBY_VERSION})"
       end
-    
+
+      # Searches ComicVine.
+      #
+      # @param res [String] resource type or types, comma-separated (e.g. `"volume,issue"`)
+      # @param query [String] the search string
+      # @param opts [Hash] extra query options (`:limit`, `:field_list`, ...)
+      # @return [CVSearchList]
+      # @raise [CVError]
+      def search res, query, opts = {}
+        query_opts = opts.merge(:resources => res.gsub(" ", ""), :query => query)
+        resp = hit_api(build_base_url("search"), build_query(query_opts))
+        ComicVine::CVSearchList.new(resp, res, query, opts)
+      end
+
+      # Looks up a plural (list) resource in the `/types/` list.
+      #
+      # @param type [String] e.g. `"characters"`
+      # @return [Hash, nil]
       def find_list type
         types.find { |t| t['list_resource_name'] == type }
       end
-    
+
+      # Looks up a singular (detail) resource in the `/types/` list.
+      #
+      # @param type [String] e.g. `"character"`
+      # @return [Hash, nil]
       def find_detail type
         types.find { |t| t['detail_resource_name'] == type }
       end
-    
-      def method_missing(method_sym, *arguments, &block)
+
+      # Resolves resource methods (`ComicVine::API.characters`,
+      # `ComicVine::API.volume 766`, ...) against the `/types/` list.
+      def method_missing(method_sym, *arguments, &)
         if find_list(method_sym.to_s)
           get_list method_sym.to_s, arguments.first
         elsif find_detail(method_sym.to_s)
           get_details method_sym.to_s, *arguments
-        elsif
+        else
           super
         end
       end
-    
-      def key
-        @@key
-      end
-    
-      def key= key
-        @@key = key
+
+      def respond_to_missing?(method_sym, include_private = false)
+        name = method_sym.to_s
+        return true if find_list(name) || find_detail(name)
+
+        super
+      rescue CVError
+        super
       end
-    
+
+      # The cached `/types/` list, fetched on first use and refreshed every
+      # {TYPES_CACHE_TTL} seconds.
+      #
+      # @return [Array<Hash>]
+      # @raise [CVError] if the `/types/` list cannot be fetched
       def types
-        if @@types.nil? || (@@last_type_check + (4 *60 *60)) < Time.now
-          @@last_type_check = Time.now
-          @@types = hit_api(build_base_url('types'))['results']
+        @types_mutex.synchronize do
+          if @types.nil? || (@last_type_check + TYPES_CACHE_TTL) < Time.now
+            begin
+              @types = hit_api(build_base_url('types'))['results']
+              @last_type_check = Time.now
+            rescue CVHTTPError => e
+              raise e.class.new("Could not load the ComicVine /types/ list (needed to resolve API methods): #{e.message}", e.status)
+            rescue CVError => e
+              raise e.class, "Could not load the ComicVine /types/ list (needed to resolve API methods): #{e.message}"
+            end
+          end
+          @types
+        end
+      end
+
+      # Clears the cached `/types/` list (mainly useful in tests).
+      #
+      # @return [void]
+      def reset_types_cache!
+        @types_mutex.synchronize do
+          @types = nil
+          @last_type_check = nil
         end
-        @@types
       end
 
-      def get_list list_type, opts=nil
+      # Fetches a list resource.
+      #
+      # @param list_type [String] plural resource name (e.g. `"characters"`)
+      # @param opts [Hash, nil] query options (`:limit`, `:offset`, `:filter`,
+      #   `:sort`, `:field_list`, ...)
+      # @return [CVObjectList]
+      # @raise [CVError]
+      def get_list list_type, opts = nil
         resp = hit_api(build_base_url(list_type), build_query(opts))
-        ComicVine::CVObjectList.new(resp, list_type)
+        ComicVine::CVObjectList.new(resp, list_type, opts || {})
       end
-  
-      def get_details item_type, id, opts=nil
-        resp = hit_api(build_base_url("#{item_type}/#{find_detail(item_type)['id']}-#{id}"), build_query(opts))
+
+      # Fetches a single resource by id.
+      #
+      # @param item_type [String] singular resource name (e.g. `"volume"`)
+      # @param id [Integer, String] the resource id
+      # @param opts [Hash, nil] query options (`:field_list`, ...)
+      # @return [CVObject]
+      # @raise [CVError] if the type is unknown or the request fails
+      def get_details item_type, id, opts = nil
+        detail = find_detail(item_type)
+        raise CVError, "Unknown ComicVine resource type: #{item_type}" if detail.nil?
+
+        resp = hit_api(build_base_url("#{item_type}/#{detail['id']}-#{id}"), build_query(opts))
         ComicVine::CVObject.new(resp['results'])
       end
-      
+
+      # Fetches a resource from its `api_detail_url`.
+      #
+      # @param url [String]
+      # @return [CVObject]
+      # @raise [CVError]
       def get_details_by_url url
         resp = hit_api(url)
         ComicVine::CVObject.new(resp['results'])
       end
-    
+
       private
-        def hit_api base_url, query=""
-          url = base_url+"?format=json&api_key=#{@@key}"+query
-          uri = URI.parse(url)
-          resp = Net::HTTP.get(uri)
-          presp = MultiJson.load(resp)
-          raise CVError, presp['error'] unless presp['status_code'] == 1
-          presp
-        end
-      
-        def build_base_url action
-          @@API_BASE_URL+action+"/"
-        end
-        
-        def build_query opts=nil
-          query = ''
-          if !opts.nil? && !opts.empty?
-            opts.each do |k,v|
-              query << "&#{k.to_s}=#{v}"
+
+      def hit_api base_url, query = ""
+        uri = URI.parse("#{base_url}?format=json&api_key=#{@key}#{query}")
+        response = fetch_with_retries(uri)
+        parse_body(response.body)
+      end
+
+      def fetch_with_retries uri
+        attempt = 0
+        loop do
+          attempt += 1
+          begin
+            response = perform_request(uri)
+          rescue *RETRYABLE_EXCEPTIONS => e
+            if attempt <= max_retries
+              sleep retry_delay(attempt)
+              next
             end
+            raise CVConnectionError, "Connection to #{uri.host} failed after #{attempt} attempts: #{e.class}: #{e.message}"
+          end
+
+          code = response.code.to_i
+          return response if (200..299).cover?(code)
+
+          if RETRYABLE_STATUS_CODES.include?(code) && attempt <= max_retries
+            sleep retry_delay(attempt, response)
+            next
+          end
+
+          if [420, 429].include?(code)
+            raise CVRateLimitError.new(
+              "ComicVine rate limit hit (HTTP #{code}) and still throttled after #{attempt} attempts" \
+              "The API allows roughly 200 requests per resource per hour.", code
+            )
           end
-          query
+
+          raise CVHTTPError.new("ComicVine API returned HTTP #{code} #{response.message}".strip, code)
+        end
+      end
+
+      def perform_request uri
+        Net::HTTP.start(uri.host, uri.port,
+                        :use_ssl => uri.scheme == "https",
+                        :open_timeout => open_timeout,
+                        :read_timeout => read_timeout) do |http|
+          request = Net::HTTP::Get.new(uri)
+          request["User-Agent"] = user_agent
+          request["Accept"] = "application/json"
+          http.request(request)
+        end
+      end
+
+      def retry_delay attempt, response = nil
+        if response && response["Retry-After"].to_s =~ /\A\d+\z/
+          response["Retry-After"].to_i
+        else
+          retry_base_delay * (2**(attempt - 1))
+        end
+      end
+
+      def parse_body body
+        presp = begin
+          JSON.parse(body)
+        rescue JSON::ParserError => e
+          raise CVParseError, "ComicVine returned a response that is not valid JSON: #{e.message}"
         end
+        raise CVParseError, "ComicVine returned unexpected JSON (expected an object, got #{presp.class})" unless presp.is_a?(Hash)
+        raise CVAPIError, presp['error'] unless presp['status_code'] == 1
+
+        presp
+      end
 
+      def build_base_url action
+        "#{API_BASE_URL}#{action}/"
+      end
+
+      def build_query opts = nil
+        return '' if opts.nil? || opts.empty?
+
+        opts.map { |k, v| "&#{k}=#{CGI.escape(v.to_s)}" }.join
+      end
     end
   end
 end

metadata

@@ -1,132 +1,52 @@
 --- !ruby/object:Gem::Specification
 name: comic_vine
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 1.0.0
 platform: ruby
 authors:
 - Patrick Sharp
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-12 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: multi_json
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: 2.0.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: 2.0.0
-- !ruby/object:Gem::Dependency
-  name: webmock
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-description: Simple api interface to Comic Vine.  Allows for searches and returning
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Simple API interface to Comic Vine. Allows for searches and returning
   specific information on resources.
-email: jakanapes@gmail.com
+email:
+- jakanapes@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .travis.yml
-- Gemfile
+- CHANGELOG.md
 - LICENSE
 - README.md
-- Rakefile
-- changelog
-- comic_vine.gemspec
 - lib/comic_vine.rb
 - lib/comic_vine/cv_list.rb
 - lib/comic_vine/cv_object.rb
 - lib/comic_vine/version.rb
-- spec/comic_vine_spec.rb
-- spec/spec_helper.rb
 homepage: https://github.com/Jakanapes/ComicVine
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  source_code_uri: https://github.com/Jakanapes/ComicVine
+  changelog_uri: https://github.com/Jakanapes/ComicVine/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Jakanapes/ComicVine/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.2
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Interface to ComicVine API
-test_files:
-- spec/comic_vine_spec.rb
-- spec/spec_helper.rb
-has_rdoc: 
+summary: Interface to the ComicVine API
+test_files: []

data/.gitignore

@@ -1,19 +0,0 @@
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
-coverage
-.DS_Store

data/.rspec

@@ -1,2 +0,0 @@
---color
---format progress

data/.travis.yml

@@ -1,4 +0,0 @@
-language: ruby
-rvm:
-  - 1.9.2
-  - 1.9.3

data/Gemfile

@@ -1,7 +0,0 @@
-source 'https://rubygems.org'
-
-# Specify your gem's dependencies in comic_vine.gemspec
-gemspec
-
-gem 'gson', platform: :jruby
-gem 'oj', platform: :ruby

data/Rakefile

@@ -1,8 +0,0 @@
-#!/usr/bin/env rake
-require "bundler/gem_tasks"
-
-require 'rspec/core/rake_task'
-
-RSpec::Core::RakeTask.new('spec')
-
-task :default => :spec

data/changelog

@@ -1,21 +0,0 @@
-0.1.4 - Update comicvine api url
-
-0.1.1 - Escape query on search, remove spaces from resources
-
-0.1.0 - Fix small bug with types cache, full coverage with rspec
-
-0.0.8 - Fix bug exposing api-key
-
-0.0.7 - Fix bug with search
-
-0.0.6 - Expose the helper methods, add get_details_by_url, allow get_* for ANY of the resource items returned in the body
-
-0.0.5 - Behind the scenes cleanup.  Change gem to work as a pure ruby implementation.  API.key is now manually set as opposed to reading from a config file.  Removed generator and railties.
-
-0.0.4 - Add CVObjectList to carry count vars from result.  Add simple pagination.  Include enumerable in the list classes
-
-0.0.3 - Add simple associations, remove initializer and do that work in the railtie class, error check on CV response, allow options
-
-0.0.2 - Create CVObjects from resource returns
-
-0.0.1 - First check-in

data/comic_vine.gemspec

@@ -1,24 +0,0 @@
-# -*- encoding: utf-8 -*-
-require File.expand_path('../lib/comic_vine/version', __FILE__)
-
-Gem::Specification.new do |gem|
-  gem.authors       = "Patrick Sharp"
-  gem.email         = "jakanapes@gmail.com"
-  gem.description   = %q{Simple api interface to Comic Vine.  Allows for searches and returning specific information on resources.}
-  gem.summary       = %q{Interface to ComicVine API}
-  gem.homepage      = "https://github.com/Jakanapes/ComicVine"
-
-  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  gem.files         = `git ls-files`.split("\n")
-  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  gem.name          = "comic_vine"
-  gem.require_paths = ["lib"]
-  gem.version       = ComicVine::VERSION
-  gem.license       = 'MIT'
-  
-  gem.add_dependency 'multi_json'
-  gem.add_development_dependency "rspec", ">= 2.0.0"
-  gem.add_development_dependency "webmock"
-  gem.add_development_dependency "simplecov"
-  gem.add_development_dependency "rake"
-end