roverjoe 0.0.10

data/.gitignore

@@ -0,0 +1,7 @@
+.rvmrc
+.bundle
+.rspec
+tmp/*
+.DS_Store
+tags
+Session.vim

data/.rvmrc.example

@@ -0,0 +1 @@
+rvm use --create 1.9.3@roverjoe

data/Gemfile

@@ -0,0 +1,24 @@
+source :rubygems
+
+gem 'addressable'
+gem 'httparty'
+
+group :development do
+  gem 'rake'
+end
+
+group :test do
+  gem 'rspec'
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-cucumber'
+  gem 'webmock'
+end
+
+group :cucumber do
+  gem 'cucumber'
+  gem 'rspec'
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-cucumber'
+end

data/Gemfile.lock

@@ -0,0 +1,65 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.2.8)
+    builder (3.0.0)
+    crack (0.3.1)
+    cucumber (1.2.1)
+      builder (>= 2.1.2)
+      diff-lcs (>= 1.1.3)
+      gherkin (~> 2.11.0)
+      json (>= 1.4.6)
+    diff-lcs (1.1.3)
+    ffi (1.0.11)
+    gherkin (2.11.0)
+      json (>= 1.4.6)
+    guard (1.1.1)
+      listen (>= 0.4.2)
+      thor (>= 0.14.6)
+    guard-cucumber (1.1.0)
+      cucumber (>= 1.2.0)
+      guard (>= 1.1.0)
+    guard-rspec (1.1.0)
+      guard (>= 1.1)
+    httparty (0.8.3)
+      multi_json (~> 1.0)
+      multi_xml
+    json (1.7.3)
+    listen (0.4.5)
+      rb-fchange (~> 0.0.5)
+      rb-fsevent (~> 0.9.1)
+      rb-inotify (~> 0.8.8)
+    multi_json (1.3.6)
+    multi_xml (0.5.1)
+    rake (0.9.2.2)
+    rb-fchange (0.0.5)
+      ffi
+    rb-fsevent (0.9.1)
+    rb-inotify (0.8.8)
+      ffi (>= 0.5.0)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+    thor (0.15.3)
+    webmock (1.8.7)
+      addressable (>= 2.2.7)
+      crack (>= 0.1.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  addressable
+  cucumber
+  guard
+  guard-cucumber
+  guard-rspec
+  httparty
+  rake
+  rspec
+  webmock

data/Guardfile

@@ -0,0 +1,14 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2, :cli => '--color --format nested' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+
+guard 'cucumber' do
+  watch(%r{^features/.+\.feature$})
+  watch(%r{^features/support/.+$})          { 'features' }
+  watch(%r{^features/step_definitions/(.+)_steps\.rb$}) { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'features' }
+end

data/README.md

@@ -0,0 +1,102 @@
+# RoverJoe
+
+![RoverJoe](http://images.wikia.com/puppet/images/3/35/Muppetbremen6.gif)
+
+RoverJoe: A ruby gem that wraps the HostelWorld API, providing:
+
+* Recovery from network issuses like timeout and connection reset by
+  peer.
+* Recovery from quota exceeded conditions
+* Request and Response objects
+* Objects for RemoteProperty (work-in-progress) ...
+
+
+## Installation
+
+Assuming bundler, edit Gemfile to include
+
+    gem 'roverjoe', '>=0.0.7', git: 'git@github.com:lonelyplanet/roverjoe.git'
+
+## Use
+
+### Configuration by file
+
+Include in your initialization
+
+    RoverJoe.configure_from_file
+
+Then create config/hostelworld\_api.yml something like this.
+
+    params: 
+      format: 'json'
+      consumer_key: 'lonelyplanet.com'
+      consumer_signature: 'somethingverysecret'
+      Language: 'English'
+    uri: 'https://affiliate.xsapi.webresint.com/1.1/'
+
+Only consumer\_key and consumer\_signature are required, the rest have
+defaults.
+
+### Hardcoded configuration
+
+    RoverJoe.configure do |c|
+      c.consumer_key = 'lonelyplanet.com'
+      c.consumer_signature = 'asecretsignature'
+      c.logger = MyApp.logger
+    end
+
+The default logger does nothing, override if you want to see log output.
+
+### Logging quota delay stats
+
+Use the after\_delay callback to capture the stats however you want.
+
+    RoverJoe.configure do |c|
+      c.after_delay { |delay|  Stats.capture( "the delay was #{delay}" }
+    end
+
+### Calling the API - RemoteProperty
+
+    rp = RoverJoe::RemoteProperty( :id => hostel_number )
+    star_rating = rp.star_rating      # this triggers API call
+
+or
+
+    hw_property = RoverJoe::RemoteProperty( :id => hostel_number ).response 
+    lp_property.name = hw_property['PropertyName']
+
+### Calling the API - Request
+
+    req = RoverJoe::Request.new( :propertyInformation, :propertyNumber => hostel_number ) 
+    result = req.execute    
+
+Result is a hash of all the attributes of the property
+
+### Calling the API - Availability/Location search example
+
+    a = RoverJoe::Request.new( :propertylocationsearch,  
+                               :City => 'Athens',
+                               :DateStart => (Date.today+21).iso8601, 
+                               :NumNights => 7
+                             ).execute
+
+## Development
+
+    $ git clone git@github.com:lonelyplanet/roverjoe.git
+    $ cd roverjoe
+
+### RVM
+
+    $ cp .rvmrc.example .rvmrc
+    $ source .rvmrc
+    $ bundle install
+
+### Specs
+
+    $ rake                            # all tests
+    $ rspec                           # all tests
+    $ bundle exec guard               # all tests
+
+    $ rspec spec/lib                  # unit tests
+    $ rspec spec/integration          # integration tests
+

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/roverjoe.rb

@@ -0,0 +1,51 @@
+require 'fileutils'
+
+require_relative "roverjoe/remote_property"
+require_relative "roverjoe/remote_properties_page"
+require_relative "roverjoe/request"
+require_relative "roverjoe/response"
+require_relative "roverjoe/quota_handler"
+require_relative "roverjoe/retry_handler"
+require_relative "roverjoe/configuration"
+require_relative "roverjoe/null_logger"
+
+
+module RoverJoe
+
+  class PropertyInactiveError < RuntimeError ; end
+  class ExcessiveRetries < RuntimeError ; end
+
+  def self.root
+    FileUtils.pwd
+  end
+
+  def self.logger
+    configuration.logger
+  end
+
+  def self.configure_from_file( file = config_file )
+    reset_configuration
+    y = YAML.load_file( file )
+    configure do |c| 
+      c.request_params = y['params']
+      c.request_uri    = y['uri']
+    end
+  end
+
+  def self.config_file
+    File.join(RoverJoe.root, 'config', 'hostelworld_api.yml')
+  end
+
+  def self.reset_configuration
+    @configuration = nil
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield configuration
+  end
+
+end

data/lib/roverjoe/configuration.rb

@@ -0,0 +1,51 @@
+module RoverJoe
+
+  class Configuration
+
+    attr_writer :logger, :request_uri, :consumer_signature, :consumer_key
+    attr_accessor :after_delay_callback
+
+    def logger
+      @logger ||= NullLogger.new
+    end
+
+    # HACK: If XML format is required, it may involve more changes to the gem
+    # than simply overriding the request format from JSON to XML.
+    def default_request_params
+      { 
+        'consumer_signature' => consumer_signature, 
+        'consumer_key'       => consumer_key,
+        'format'             => 'json',
+        'Language'           => 'English' 
+      }
+    end
+
+    def request_params
+      default_request_params.merge(@request_params ||= {})
+    end
+
+    def request_params=( params )
+      @request_params = params
+      self.consumer_key = params['consumer_key'] if params['consumer_key']
+      self.consumer_signature = params['consumer_signature'] if params['consumer_signature']
+    end
+
+    def request_uri
+      @request_uri ||= 'https://affiliate.xsapi.webresint.com/1.1/'
+    end
+
+    def consumer_signature
+      @consumer_signature ||= 'you-forgot-to-configure-consumer-signature'
+    end
+
+    def consumer_key
+      @consumer_key ||= 'you-forgot-to-configure-consumer-key'
+    end
+
+    def after_delay( &callback )
+      self.after_delay_callback = callback if block_given?
+    end
+
+  end
+
+end

data/lib/roverjoe/null_logger.rb

@@ -0,0 +1,11 @@
+module RoverJoe
+
+  class NullLogger
+
+    def method_missing( *args )
+      self
+    end
+
+  end
+
+end

data/lib/roverjoe/quota_handler.rb

@@ -0,0 +1,64 @@
+module RoverJoe
+
+  require 'httparty'
+  require 'addressable/uri'
+
+
+  class QuotaHandler
+
+    attr_accessor :waiting_last_time, :quota_delay_start
+
+    def initialize
+      self.waiting_last_time = false
+    end
+
+    # HACK: The original intent was to limit requests to the
+    # hostelworld API, spreading them evenly over the quota window (60
+    # secs) thus being nice to other callers of the API with the same
+    # key. However, it's thought at present that there will only be
+    # one caller for any given API call, and so the actual throttling
+    # is not necessary and not implemented. Thus, all this method does
+    # is allow the calling code to hammer the API until it signals
+    # 'quota exceeded' after which it will keep retrying until the API
+    # becomes available again.
+    #
+    # If we do implement limiting or throttling it may belong in a
+    # different class.
+    def run
+      response = yield
+
+      retry_count = 0
+      while response.quota_exceeded? && retry_count < 200
+
+        log_quota_wait( true ) 
+        retry_count += 1
+        sleep 2
+        response = yield
+      
+      end
+      log_quota_wait( response.quota_exceeded? )
+      raise RuntimeError, "Hostelworld API: Excessive wait for new quota window to start" if response.quota_exceeded?
+
+      response
+    end
+
+    private
+
+    def log_quota_wait( waiting_now )
+      if waiting_now != waiting_last_time
+        if waiting_now
+          self.quota_delay_start = Time.now
+          RoverJoe.logger.warn( "Hostelworld API: Quota exceeded delay begins" )
+        else
+          delay = Time.now - quota_delay_start
+          RoverJoe.logger.warn( "Hostelworld API: Quota exceeded delay ends. Total time: #{delay}" )
+          cb = RoverJoe.configuration.after_delay_callback
+          cb.call( delay ) unless cb.nil?
+        end
+      end
+      self.waiting_last_time = waiting_now
+    end
+
+  end
+
+end

data/lib/roverjoe/remote_properties_page.rb

@@ -0,0 +1,45 @@
+module RoverJoe
+
+  class RemotePropertiesPage 
+
+    attr_accessor :api_request_class, :page_number
+
+    def initialize( params )
+      @api_request_class = params.delete( :api_request_class ) || RoverJoe::Request 
+      @page_number = params.delete( :page ) 
+      raise ArgumentError, ":page should not be blank" if @page_number.nil? or @page_number == ''
+    end
+
+    def response
+      @response ||= request.execute
+    end
+
+    def request
+      @request ||= api_request_class.new( :propertiesinformation, :PageNumber => self.page_number )
+    end
+
+    def self.all(&block)
+      page_1 = new(:page => 1)
+      block.call(page_1)
+      page_count = page_1.total_pages
+      if page_count > 1
+        (2..page_count).each do |n|
+          page = new(:page => n)
+          block.call(page)
+        end
+      end
+    end
+
+    def total_pages
+      raise RuntimeError, "'PagesCount' not found in #{response.keys} for RemotePropertiesPage #{page_number}." unless response.keys.include?( 'PagesCount' )
+      response['PagesCount']
+    end
+
+    def properties
+      raise RuntimeError, "'Properties' not found in #{response.keys} for RemotePropertiesPage #{page_number}." unless response.keys.include?( 'Properties' )
+      response['Properties']
+    end
+
+  end
+
+end