spn2 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ec6088e94bed925212bc5aa5abf3211cae5fd0bf5402c49f316d7e4d65f051d
-  data.tar.gz: e00cad0b9921f36052ec81271e69f553979dec1e0b6cd540f1bee1c0f712f337
+  metadata.gz: 744fc63b21023c96ff40a72561d80f8e277be132b369c10b7196f273178177d8
+  data.tar.gz: 26c923d7ac606c16c0f56e98cff3497878771899a7fc23947c57d864316de4a7
 SHA512:
-  metadata.gz: e618df35304407811745df2e7c92106669a01564d4c61c1639fa06a109ffb995fb05e145e12d13efc7cf30fd4c899a959138e0640894bc68c3942efd1035e3d0
-  data.tar.gz: cc5616e4848cd9f5bfceb58e163095f9adfc86e584857d3c5c9674bfbbe8a182262d7c779c7d24a87134e7959e7f3a6fcbfc4588f039efc5184919e193d70ca2
+  metadata.gz: ca70afc978bd3766ebdc4234575ea1ca5e19202757c353bd917b6b822293764fbde204ad3e6753188eaab0c2123abf2b71ae8fee6c827df41fb836662f90f788
+  data.tar.gz: 23a245ea4c896b034da511fa7dab95d81fda3cd8cec778c1e0be27eddf4f49e46452efb7e10feeb59af0b7ad02ee95fc352f2cbc34c8e79f245c5a8efd283b52

data/CHANGELOG.md

@@ -3,3 +3,8 @@
 ## [0.1.0] - 2022-06-29
 
 - Initial release
+
+## [0.1.1] - 2022-06-30
+
+- Add error handling
+- Add ability to add opts to Spn2.save

data/README.md

@@ -21,20 +21,30 @@ For the Spn2 namespace do:
 ```rb
 require 'spn2'
 ```
-
 ### Authentication
 
 The API requires authentication, so you will need an account at [archive.org](https://archive.org). There are two methods of authentication; cookies and API key. Presently only the latter is implemented. API keys may be generated at https://archive.org/account/s3.php. Ensure your access key and secret key are set in environment variables SPN2_ACCESS_KEY and SPN2_SECRET_KEY respectively.
 
+```rb
+> Spn2.access_key
+=> <your access key>
+> Spn2.secret_key
+=> <your secret key>
+```
 ### Save a page
 
-Save a url in the Wayback Machine. This method returns the job_id in a hash.
+Save (capture) a url in the Wayback Machine. This method returns the job_id in a hash.
 ```rb
 > Spn2.save(url: 'example.com') # returns a job_id
 
-=> {job_id: 'spn2-9c17e047f58f9220a7008d4f18152fee4d111d14'}
+=> {job_id: 'spn2-9c17e047f58f9220a7008d4f18152fee4d111d14'} # json may include "url" and "message" keys too
 ```
+Various options are available, as detailed in the [specification](https://docs.google.com/document/d/1Nsv52MvSjbLb2PCpHlat0gkzw0EvtSgpKHu4mk0MnrA/edit) in the section "Capture request". These may be passed like so:
+```rb
+> Spn2.save(url: 'example.com', opts: { capture_all: 1, capture_outlinks: 1 })
 
+=> {url: 'example.com', job_id: 'spn2-9c17e047f58f9220a7008d4f18152fee4d111d14'}
+```
 ### View the status of a job
 
 Use the job_id.
@@ -53,9 +63,15 @@ Use the job_id.
 The status of Wayback Machine itself is available.
 ```rb
 > Spn2.system_status
-=> {"status"=>"ok"}
+=> {"status"=>"ok"} # if not "ok" captures may be delayed
 ```
+### Error handling
 
+To fascilitate graceful error handling, a full list of all error classes is provided by:
+```rb
+> Spn2.error_classes
+=> [Spn2::Spn2Error, Spn2::Spn2ErrorBadAuth,.. ..]
+```
 ## Development
 
 ~~After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.~~

data/lib/curlable.rb

@@ -12,7 +12,7 @@ module Curlable
   end
 
   def post(url:, headers: {}, params: {})
-    Curl::Easy.http_post("#{url}?#{Curl.postalize(params)}", params) do |http|
+    Curl::Easy.http_post("#{url}?#{Curl.postalize(params)}", Curl.postalize(params)) do |http|
       http.follow_location = true
       headers.each { |k, v| http.headers[k] = v }
     end.body_str

data/lib/spn2/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Spn2
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/lib/spn2.rb

@@ -5,57 +5,103 @@ require 'nokogiri'
 
 require_relative 'curlable'
 
-# namespace
+# Design decison to not use a class as only 'state' is in 2 env vars
 module Spn2
-  extend Curlable # for .system_status
+  extend Curlable # for system_status
   include Curlable
 
-  class Spn2Error < StandardError; end
+  ERROR_CODES = [502].freeze
 
-  FIND_JOB_ID_REGEXP = /(spn2-([a-f]|\d){40})/
+  class Spn2Error < StandardError; end
+  class Spn2ErrorBadAuth < Spn2Error; end
+  class Spn2ErrorBadAuth < Spn2Error; end
+  class Spn2ErrorBadResponse < Spn2Error; end
+  class Spn2ErrorInvalidOption < Spn2Error; end
+  class Spn2ErrorUnknownResponseCode < Spn2Error; end
+  ERROR_CODES.each { |i| Spn2.const_set("Spn2Error#{i}", Class.new(Spn2Error)) }
+
+  BAD_AUTH_MSG = 'You need to be logged in to use Save Page Now.'
+  ESSENTIAL_STATUS_KEYS = %w[job_id resources status].freeze
+  JOB_ID_REGEXP = /^(spn2-([a-f]|\d){40})$/
   WEB_ARCHIVE = 'https://web.archive.org'
 
-  def self.access_key
-    ENV.fetch('SPN2_ACCESS_KEY', nil)
-  end
+  BINARY_OPTS = %w[capture_all capture_outlinks capture_screenshot delay_wb_availabilty force_get skip_first_archive
+                   outlinks_availability email_result].freeze
+  OTHER_OPTS = %w[if_not_archived_within js_behavior_timeout capture_cookie target_username target_password].freeze
 
-  def self.secret_key
-    ENV.fetch('SPN2_SECRET_KEY', nil)
-  end
+  class << self
+    def error_classes
+      Spn2.constants.map { |e| Spn2.const_get(e) }.select { |e| e.is_a?(Class) && e < Exception }
+    end
 
-  def self.system_status
-    JSON.parse get(url: "#{WEB_ARCHIVE}/save/status/system")
-  end
+    def access_key
+      ENV.fetch('SPN2_ACCESS_KEY', nil)
+    end
 
-  def self.save(url:)
-    job_id(json(auth_post(url: "#{WEB_ARCHIVE}/save/#{url}", params: "url=#{url}")))
-  end
+    def secret_key
+      ENV.fetch('SPN2_SECRET_KEY', nil)
+    end
 
-  def self.status(job_id:)
-    json auth_get(url: "#{WEB_ARCHIVE}/save/status/#{job_id}?_t=#{Time.now.to_i}")
-  end
+    def system_status
+      json get(url: "#{WEB_ARCHIVE}/save/status/system") # no auth
+    end
 
-  def self.auth_get(url:)
-    get(url: url, headers: accept_header.merge(auth_header))
-  end
+    def save(url:, opts: {})
+      raise Spn2ErrorInvalidOption, "One or more invalid options: #{opts}" unless options_valid?(opts)
 
-  def self.auth_post(url:, params:)
-    post(url: url, headers: accept_header.merge(auth_header), params:)
-  end
+      hash = json(auth_post(url: "#{WEB_ARCHIVE}/save/#{url}", params: { url: url }.merge(opts)))
+      raise Spn2ErrorBadAuth, hash.inspect if hash['message']&.== BAD_AUTH_MSG
 
-  def self.accept_header
-    { 'Accept' => 'application/json' }
-  end
+      raise Spn2ErrorBadResponse, "Bad response: #{hash.inspect}" unless hash['job_id']
 
-  def self.auth_header
-    { 'Authorization' => "LOW #{Spn2.access_key}:#{Spn2.secret_key}" }
-  end
+      hash
+    end
+    alias capture save
 
-  def self.job_id(hash)
-    { job_id: hash['job_id'] }
-  end
+    def status(job_id:)
+      hash = json(auth_get(url: "#{WEB_ARCHIVE}/save/status/#{job_id}"))
+      raise Spn2ErrorBadAuth, hash.inspect if hash['message']&.== BAD_AUTH_MSG
+
+      raise Spn2ErrorBadResponse, "Bad response: #{hash.inspect}" unless (ESSENTIAL_STATUS_KEYS - hash.keys).empty?
+
+      hash
+    end
+
+    private
+
+    def auth_get(url:)
+      get(url: url, headers: accept_header.merge(auth_header))
+    end
+
+    def auth_post(url:, params: {})
+      post(url: url, headers: accept_header.merge(auth_header), params: params)
+    end
+
+    def accept_header
+      { Accept: 'application/json' }
+    end
+
+    def auth_header
+      { Authorization: "LOW #{Spn2.access_key}:#{Spn2.secret_key}" }
+    end
+
+    def json(html_string)
+      JSON.parse(doc = Nokogiri::HTML(html_string))
+    rescue JSON::ParserError # an html response
+      raise Spn2ErrorBadResponse, "No title in: #{html_string}" unless (title = doc.title)
+
+      parse_error_code_from_page_title(title)
+    end
+
+    def parse_error_code_from_page_title(string)
+      code = string.to_i
+      raise Spn2.const_get("Spn2Error#{code}") if ERROR_CODES.include? code
+
+      raise Spn2ErrorUnknownResponseCode, string
+    end
 
-  def self.json(json_string)
-    JSON.parse Nokogiri::HTML(json_string)
+    def options_valid?(opts)
+      opts.keys.all? { |k| (BINARY_OPTS + OTHER_OPTS).include? k.to_s }
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spn2
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - MatzFan
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-06-29 00:00:00.000000000 Z
+date: 2022-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: curb
@@ -177,7 +177,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.16
+rubygems_version: 3.3.17
 signing_key: 
 specification_version: 4
 summary: Gem for the Save Page Now API of the Wayback Machine