snapsearch-client-ruby 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f2959c7bd59e817f2eef37602a4abdc8ae1f1be8
-  data.tar.gz: 3ddaec20074f02943df30adf39de5e0ad60b0ccd
+  metadata.gz: 716cbd63128f5927b2cecd2f741b163b41260647
+  data.tar.gz: bc1f48f201d33d57c4218889710470c4bd61f2a0
 SHA512:
-  metadata.gz: 1482fc4b66a72119cb2e26637429d3c48b9561e65ebcb4029fd1b173a60d0b5491aeb23719e7f0666298491e338708c3110ecdee1b0fbbe053b6ff529b520ad6
-  data.tar.gz: 1b847ec7a8e27533a0cde5f39bf0445ac923b3232dd55f85a1676814a73b8ba9dcb2637c48aed327c4cc84474b2b815274572de2ef81f56d5e2b1b9ab64a6387
+  metadata.gz: 4644c7538ebd5eaa147979d05facf00dfa819aed178965d73c55752a323dc4be362f13d2d75a20749ece4b0a1c915d63ea13f8bc2252c8cc69be8ab360c1bc07
+  data.tar.gz: 52a72306554f6ed8548b0b6b6dd27b60ea5f22d96cb9d30b5fdf0f0fe25f9e15894af7afae62e2b6291b097e2d86654ce540e8a7b314c5a02e2bcb672710a9bd

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    snapsearch-client-ruby (0.1.0)
+    snapsearch-client-ruby (1.0.0)
       addressable (~> 2.0.0)
       httpi (~> 2.1.0)
       rack (~> 1.5.0)

data/README.md

@@ -1,109 +1,214 @@
-SnapSearch-Client-Ruby
-======================
-
-[![Build Status](https://travis-ci.org/SnapSearch/SnapSearch-Client-Ruby.png?branch=master)](https://travis-ci.org/SnapSearch/SnapSearch-Client-Ruby)
-
-Snapsearch Client Ruby is Ruby based framework agnostic HTTP client library for SnapSearch (https://snapsearch.io/).
-
-SnapSearch provides similar libraries in other languages: https://github.com/SnapSearch/Snapsearch-Clients
-
-Installation
-------------
-
-Usage
------
-
-Development
----------
-
-Get the bundler dependency management tool.
-
-```
-gem install bundler
-```
-
-Install/update all dependencies:
-
-```
-bundle install
-```
-
-See all build tasks:
-
-```
-bundle exec rake -T
-```
-
-Make your changes. Release a new version tag with (see the other `rake version:bump:... etc` tasks):
-
-```
-bundle exec rake version:bump
-```
-
-Synchronise and push the tag to Github:
-
-```
-git push
-git push --tags
-```
-
-Create the gem package:
-
-```
-bundle exec rake gem
-```
-
-Push the gem to Ruby Gems:
-
-```
-gem push pkg/snapsearch-client-ruby-MAJOR.MINOR.PATCH.gem
-```
-
-Setting Up the Detector
------------------------
-
-The `Detector` class detects if the incoming request is coming from a robot or not.
-
-Detects if the request came from a search engine robot. It will intercept in cascading order:
-
-1. on a GET request
-2. on an HTTP or HTTPS protocol
-3. not on any ignored robot user agents
-4. not on any route not matching the whitelist
-5. not on any route matching the blacklist
-6. not on any static files that is not a PHP file if it is detected
-7. on requests with _escaped_fragment_ query parameter
-8. on any matched robot user agents
-
-You can customize a few aspects of this process:
-
-#### User Agents
-
-Most robots send a unique `user-agent` HTTP header that we match against to confirm if it indeed a request from a robot.  
-We also ignore certain user agents, such as the SnapSearch robot.
-
-The list of user agents to match and ignore is contained in `resources/robots.json`. You can customize this list through the Detector instance
-you are working with:
-
-```
-# Retrieve the list of user agents to match and ignore:
-detector.robots # => { 'match' => ['SomeRobot', 'AnotherRobot'], 'ignore' => ['SnapSearch'] }
-
-# Add a user agent to match against:
-detector.robots['match'] << 'NewRobot'
-
-# Add a user agent to ignore:
-detector.robots['ignore'] << 'MyRobot'
-
-# Set a new list of user agents to match and ignore:
-detector.robots = { 'match' => ['WebScraper', 'SillyBot'], 'ignore' => ['MyBotToIgnore'] }
-
-# Load from a custom JSON file:
-detector.robots_json = './my_robots.json'
-detector.robots # => { 'match' => ['MyCustomBot', 'AnotherRobot'], 'ignore' => ['MyLoadedBotFromJSON'] }
-```
-
-Tests
-----
-
+SnapSearch-Client-Ruby
+======================
+
+[![Build Status](https://travis-ci.org/SnapSearch/SnapSearch-Client-Ruby.png?branch=master)](https://travis-ci.org/SnapSearch/SnapSearch-Client-Ruby)
+
+Snapsearch Client Ruby is Ruby based framework agnostic HTTP client library for SnapSearch (https://snapsearch.io/).
+
+SnapSearch provides similar libraries in other languages: https://github.com/SnapSearch/Snapsearch-Clients
+
+Installation
+------------
+
+SnapSearch-Client-Ruby is available through Rubygems and can be installed via:
+
+```
+gem install snapsearch-client-ruby
+```
+
+or add it to your Gemfile like this:
+
+```
+gem "snapsearch-client-ruby", "~> 0.1.0"
+```
+
+For all supported Ruby versions check out the `.travis.yml` file.
+
+Usage
+-----
+
+SnapSearch Client Ruby is a rack based middleware for SnapSearch. It works with all rack based frameworks including Rails and Sinatra. You should place the SnapSearch middleware on top of other middleware so it gets called relatively early in the request response cycle. The middleware is also available as individual objects, which can be called independently. In non-rack based frameworks, it is best to start SnapSearch at the entry point of your application.
+
+**The examples folder in this repository contains a rack and sinatra example showing the context of using the SnapSearch middleware in your application. The below instructions is an abridged version of the examples.**
+
+For full documentation on the API and API request parameters see: https://snapsearch.io/documentation
+
+### Basic Usage
+
+In your `config.ru` file, import the `rack/snap_search`, then setup the configuration:
+
+```ruby
+require 'rack/snap_search'
+
+use Rack::SnapSearch do |config|
+    
+    config.email = 'user@example.com'
+    
+    config.key = 'API_KEY_HERE'
+    
+end
+```
+
+This will handle everything from the detection of the robot to outputting the cached snapshot. If it detects the robot, it will skip execution of the application and output the snapshot response. The default configuration is to output only the status, location headers and body content. This is because some headers may cause encoding errors.
+
+Here is an example of the response hash from SnapSearch: 
+
+```ruby
+response = {
+    "cache"             => true/false,
+    "callbackResult"    => "",
+    "date"              => 1390382314,
+    "headers"           => [
+        {
+            "name"  => "Content-Type",
+            "value" => "text/html"
+        }
+    ],
+    "html"              => "<html></html>",
+    "message"           => "Success/Failed/Validation Errors",
+    "pageErrors"        => [
+        {
+            "error"   => "Error: document.querySelector(...) is null",
+            "trace"   => [
+                {
+                    "file"      => "filename",
+                    "function"  => "anonymous",
+                    "line"      => "41",
+                    "sourceURL" => "urltofile"
+                }
+            ]
+        }
+    ],
+    "screensot"         => "BASE64 ENCODED IMAGE CONTENT",
+    "status"            => 200
+}
+```
+
+### Advanced Usage
+
+The rack based middleware has many options and if you use the objects independently they are even more flexible. These options can be seen in context in the examples folder:
+
+```ruby
+use Rack::SnapSearch do |config|
+    
+    config.email = 'user@example.com'
+    
+    config.key = 'API_KEY_HERE'
+
+    # Optional: The API URL to send requests to.
+    config.api_url = 'https://snapsearch.io/api/v1/robot' # Default
+    
+    # Optional: The CA Cert file to use when sending HTTPS requests to the API.
+    config.ca_cert_file = SnapSearch.root.join('resources', 'cacert.pem') # Default
+    
+    # Optional: Check X-Forwarded-Proto if you use a load balancer that proxies https to http connections
+    config.x_forwarded_proto = true # Default
+    
+    # Optional: Extra API parameters that is sent to SnapSearch
+    config.parameters = {} # Default
+    
+    # Optional: Whitelisted routes. Should be an Array of Regexp instances.
+    config.matched_routes = [] # Default
+    
+    # Optional: Blacklisted routes. Should be an Array of Regexp instances.
+    config.ignored_routes = [] # Default
+    
+    # Optional: A path of the JSON file containing the user agent whitelist & blacklist.
+    config.robots_json = SnapSearch.root.join('resources', 'robots.json') # Default
+    
+    # Optional: A path to the JSON file containing a single Hash with the keys `ignore` and `match`. These keys contain Arrays of Strings (user agents)
+    config.extensions_json = SnapSearch.root.join('resources', 'extensions.json') # Default
+    
+    # Optional: Set to `true` to check file extensions in the URL, this will check if the URL contains invalid file extensions.
+    #If there is no file extension, then there's no problem. But if there is, it could be a request to a static file. In which case it is not HTML that we want to intercept.
+    #It is typically easier to simply whitelist or blacklist file based routes.
+    #You do not need this unless your application server (not your HTTP server) is serving up static files. Like binary content, images and non-HTML text files.
+    config.check_file_extensions = false # Default
+    
+    # Optional: A block to run when an exception occurs when making requests to the API.
+    config.on_exception do |exception|
+        p exception
+    end
+    
+    # Optional: A block to run before the interception of a bot. You can use this to do client side caching.
+    config.before_intercept do |url|
+        #Get a client side cached snapshot
+    end
+    
+    # Optional: A block to run after the interception of a bot. You can use this to do client side caching.
+    config.after_intercept do |url, response|
+        #Save the client side cached snapshot (the cached time should be less then the cached time you passed to SnapSearch, we recommend half the SnapSearch cachetime)
+    end
+    
+    # Optional: A block to manipulate the response from the SnapSearch API if a bit is intercepted. The headers in this case represent [{name: "HEADERKEY", value: "HEADERVALUE"}, ...]
+    config.response_callback do |status, headers, body|        
+        [ status, headers, body ]
+    end
+
+end
+```
+
+Check out the resources folder containing the `robots.json` and `extensions.json`. The `robots.json` contains all the Search Engine and Social App robot user agents we're currently checking for. The `extensions.json` contains all the valid file extensions that a web application might use for HTML resources. Feel free to edit them and use your own JSON files for the middleware. Always make sure to ignore the "SnapSearch" robot, otherwise you could get into an infinite interception loop.
+
+The Detector instance's robot and extensions hash are publicly accessible and can be modified during runtime.
+
+```
+# Add a user agent to match against:
+detector.robots['match'] << 'NewRobot'
+
+# Add a user agent to ignore:
+detector.robots['ignore'] << 'MyRobot'
+
+detector.extensions['ruby'] << 'myvalidrubyfileextensionforhtmlresources'
+```
+
+Development
+---------
+
+Get the bundler dependency management tool.
+
+```
+gem install bundler
+```
+
+Install/update all dependencies:
+
+```
+bundle install
+```
+
+See all build tasks:
+
+```
+bundle exec rake -T
+```
+
+Make your changes. Release a new version tag with (see the other `rake version:bump:... etc` tasks):
+
+```
+bundle exec rake version:bump
+```
+
+Synchronise and push the tag to Github:
+
+```
+git push
+git push --tags
+```
+
+Create the gem package:
+
+```
+bundle exec rake gem
+```
+
+Push the gem to Ruby Gems:
+
+```
+gem push pkg/snapsearch-client-ruby-MAJOR.MINOR.PATCH.gem
+```
+
+Tests
+----
+
 Tests are written with RSpec. Run tests with `bundle exec rspec spec/`

data/VERSION

@@ -1 +1 @@
-0.1.0
+1.0.0

data/examples/rack/config.ru

@@ -1,11 +1,11 @@
 # Notes to run:
-#     gem install bundler
-#     bundle install
-#     rackup
+#   gem install bundler
+#   bundle install
+#   rackup
 # 
 # Testing:
-#    Visit http://localhost:9292/
-#    Visit http://localhost:9292/?_escaped_fragment_
+#   Visit http://localhost:9292/
+#   Visit http://localhost:9292/?_escaped_fragment_
 
 require 'bundler/setup'
 require 'rack/snap_search'
@@ -44,8 +44,8 @@ use Rack::SnapSearch do |config|
     # Optional: A path to the JSON file containing a single Hash with the keys `ignore` and `match`. These keys contain Arrays of Strings (user agents)
     config.extensions_json = SnapSearch.root.join('resources', 'extensions.json') # Default
     
-    # Optional: Set to `true` to ignore direct requests to files.
-    config.check_static_files = false # Default
+    # Optional: Set to `true` to ignore requests that have invalid file extensions
+    config.check_file_extensions = false # Default
     
     # Optional: A block to run when an exception occurs when making requests to the API.
     config.on_exception do |exception|

data/examples/sinatra/config.ru

@@ -1,15 +1,15 @@
-# Notes to run:
-#     gem install bundler
-#     bundle install
-#     rackup
-# 
-# Testing:
-#    Visit http://localhost:9292/
-#    Visit http://localhost:9292/?_escaped_fragment_
-
-require 'bundler/setup'
-require 'pathname'
-$:.unshift( Pathname.new(__FILE__).join('..', 'lib').expand_path.to_s )
-require 'sinatra_snap_search'
-
-run SinatraSnapSearch
+# Notes to run:
+#   gem install bundler
+#   bundle install
+#   rackup
+# 
+# Testing:
+#   Visit http://localhost:9292/
+#   Visit http://localhost:9292/?_escaped_fragment_
+
+require 'bundler/setup'
+require 'pathname'
+$:.unshift( Pathname.new(__FILE__).join('..', 'lib').expand_path.to_s )
+require 'sinatra_snap_search'
+
+run SinatraSnapSearch

data/examples/sinatra/lib/sinatra_snap_search.rb

@@ -9,7 +9,65 @@ class SinatraSnapSearch < Sinatra::Base
     set :root, SnapSearch.root.join('examples', 'sinatra')
     enable :sessions, :logging, :method_override, :static
     
-    use Rack::SnapSearch, email: 'email', key: 'key'
+    use Rack::SnapSearch do |config|
+      
+        # Required: The email to authenticate with.
+        config.email = 'user@example.com'
+        
+        # Required: The key to authenticate with.
+        config.key = 'API_KEY_HERE'
+        
+        # Optional: The API URL to send requests to.
+        config.api_url = 'https://snapsearch.io/api/v1/robot' # Default
+        
+        # Optional: The CA Cert file to use when sending HTTPS requests to the API.
+        config.ca_cert_file = SnapSearch.root.join('resources', 'cacert.pem') # Default
+        
+        # Optional: Check X-Forwarded-Proto because Heroku SSL Support terminates at the load balancer.
+        config.x_forwarded_proto = true # Default
+        
+        # Optional: Extra parameters to send to the API.
+        config.parameters = {} # Default
+        
+        # Optional: Whitelisted routes. Should be an Array of Regexp instances.
+        config.matched_routes = [] # Default
+        
+        # Optional: Blacklisted routes. Should be an Array of Regexp instances.
+        config.ignored_routes = [] # Default
+        
+        # Optional: A path of the JSON file containing the user agent whitelist & blacklist.
+        config.robots_json = SnapSearch.root.join('resources', 'robots.json') # Default
+        
+        # Optional: A path to the JSON file containing a single Hash with the keys `ignore` and `match`. These keys contain Arrays of Strings (user agents)
+        config.extensions_json = SnapSearch.root.join('resources', 'extensions.json') # Default
+        
+        # Optional: Set to `true` to ignore direct requests to files.
+        config.check_file_extensions = false # Default
+        
+        # Optional: A block to run when an exception occurs when making requests to the API.
+        config.on_exception do |exception|
+            p exception
+        end
+        
+        # Optional: A block to run before the interception of a bot.
+        config.before_intercept do |url|
+            puts "Before interception\n  URL: #{url}"
+        end
+        
+        # Optional: A block to run after the interception of a bot.
+        config.after_intercept do |url, response|
+            puts "After interception\n  URL: #{url}\n  Response: #{response}"
+        end
+        
+        # Optional: A block to manipulate the response from the SnapSearch API if a bit is intercepted.
+        config.response_callback do |status, headers, body|
+            puts "Response callback\n  Status: #{status}\n  Headers: #{headers}\n  Body: #{body}"
+            
+            [ status, headers, body ]
+        end
+        
+    end
+    
   end
   
   get '/' do

data/lib/rack/snap_search.rb

@@ -41,12 +41,20 @@ module Rack
             setup_api_response_from_environment(environment) # Will set @api_response if one is given from the API
             
             if @api_response
-              setup_attributes_from_api_response
+              unless @config.response_callback.nil?
+                @callback_response = @config.response_callback.call(*@api_response)
+                
+                setup_attributes_from_callback_response
+              else
+                setup_attributes_from_api_response
+              end
+              
+              rack_response
             else
               setup_attributes_from_app(environment)
             end
             
-            @config.response_callback.nil? ? rack_response : @config.response_callback.call(*rack_response)
+            
         end
         
         protected
@@ -78,7 +86,7 @@ module Rack
                 ignored_routes:     @config.ignored_routes,
                 robots_json:        @config.robots_json,
                 extensions_json:    @config.extensions_json,
-                check_static_files: @config.check_static_files
+                check_file_extensions: @config.check_file_extensions
             )
         end
         
@@ -106,7 +114,7 @@ module Rack
             begin
                 request = Rack::Request.new(environment.to_h)
                 @api_response = @interceptor.intercept(request: request)
-            rescue SnapSearch::Exception => exception
+            rescue ::SnapSearch::Error => exception
                 @config.on_exception.nil? ? raise(exception) : @config.on_exception.call(exception)
             end
         end
@@ -134,6 +142,13 @@ module Rack
           @status, @headers, @body = @app.call(environment)
         end
         
+        def setup_attributes_from_callback_response
+          @status, @headers, @body = @callback_response
+          
+          # Convert the Array of Hashes into a single Hash:
+          @headers = @headers.each_with_object({}) { |hash, memo| memo[ hash.first[0] ] = hash.first[1] }
+        end
+        
         def rack_response
           [ @status, @headers, @body ]
         end

data/lib/rack/snap_search/config.rb

@@ -7,7 +7,7 @@ module Rack
             
             ATTRIBUTES = [
                 :email, :key, :api_url, :ca_cert_file, :x_forwarded_proto, :parameters,               # Client options
-                :matched_routes, :ignored_routes, :robots_json, :extensions_json, :check_static_files # Detector options
+                :matched_routes, :ignored_routes, :robots_json, :extensions_json, :check_file_extensions # Detector options
             ]
             
             attr_accessor *ATTRIBUTES # Setup reader & writer instance methods for each attribute
@@ -25,7 +25,7 @@ module Rack
             # @option options [String] :ignored_routes Blacklisted routes. Should be an Array of Regexp instances.
             # @option options [String] :robots_json A path of the JSON file containing the user agent whitelist & blacklist.
             # @option options [String] :extensions_json A path to the JSON file containing a single Hash with the keys `ignore` and `match`. These keys contain Arrays of Strings (user agents)
-            # @option options [String] :check_static_files Set to `true` to ignore direct requests to files.
+            # @option options [String] :check_file_extensions Set to `true` to ignore direct requests to files.
             # @option options [Proc, #call] :on_exception The block to run when an exception within SnapSearch occurs.
             # @option options [Proc, #call] :before_intercept A block to run before the interception of a bot.
             # @option options [Proc, #call] :after_intercept A block to run after the interception of a bot.

data/lib/snap_search.rb

@@ -11,4 +11,5 @@ end
 require 'snap_search/client'
 require 'snap_search/detector'
 require 'snap_search/interceptor'
+require 'snap_search/error'
 require 'rack/snap_search'

data/lib/snap_search/client.rb

@@ -1,7 +1,7 @@
 require 'json'
 require 'httpi'
-require 'snap_search/connection_exception'
-require 'snap_search/validation_exception'
+require 'snap_search/connection_error'
+require 'snap_search/validation_error'
 
 module SnapSearch
     
@@ -126,7 +126,7 @@ module SnapSearch
             
             HTTPI.post(request)
         rescue
-            raise ConnectionException
+            raise ConnectionError
         end
         
         # Retrieve the `content` or raise an error based on the `code` field in the JSON response.
@@ -137,7 +137,7 @@ module SnapSearch
             
             case body['code']
             when 'success' then body['content']
-            when 'validation_error' then raise( ValidationException, body['content'] )
+            when 'validation_error' then raise( ValidationError, body['content'] )
             else; false # System error on SnapSearch; Nothing we can do # TODO: Raise exception?
             end
         end

data/lib/snap_search/{connection_exception.rb → connection_error.rb}

@@ -1,15 +1,15 @@
-require 'snap_search/exception'
-
-module SnapSearch
-    
-    # Raised when the Client could not connect to the client's `api_url`.
-    class ConnectionException < Exception
-        
-        # Create a new ConnectionException.
-        def initialize
-            super('Could not establish a connection to SnapSearch.')
-        end
-        
-    end
-    
-end
+require 'snap_search/error'
+
+module SnapSearch
+    
+    # Raised when the Client could not connect to the client's `api_url`.
+    class ConnectionError < Error
+        
+        # Create a new ConnectionError.
+        def initialize
+            super('Could not establish a connection to SnapSearch.')
+        end
+        
+    end
+    
+end

data/lib/snap_search/detector.rb

@@ -8,7 +8,7 @@ module SnapSearch
     class Detector
         
         attr_reader :matched_routes, :ignored_routes
-        attr_reader :check_static_files
+        attr_reader :check_file_extensions
         attr_reader :robots_json, :robots
         attr_reader :extensions_json, :extensions
         
@@ -18,7 +18,7 @@ module SnapSearch
         # @option options [Array<Regexp>] :matched_routes The whitelisted routes.
         # @option options [Array<Regexp>] :ignored_routes The blacklisted routes.
         # @option options [String, #to_s] :robots_json The path of the JSON file containing the user agent whitelist & blacklist.
-        # @option options [true, false] :check_static_files Set to `true` to ignore direct requests to files.
+        # @option options [true, false] :check_file_extensions Set to `true` to ignore direct requests to files.
         # @option options [Rack::Request] :request The Rack request that is to be checked/detected.
         def initialize(options={})
             raise TypeError, 'options must be a Hash or respond to #to_h or #to_hash' unless options.is_a?(Hash) || options.respond_to?(:to_h) || options.respond_to?(:to_hash)
@@ -29,10 +29,10 @@ module SnapSearch
                 ignored_routes: [],
                 robots_json: SnapSearch.root.join('resources', 'robots.json'),
                 extensions_json: SnapSearch.root.join('resources', 'extensions.json'),
-                check_static_files: false
+                check_file_extensions: false
             }.merge(options) # Reverse merge: The hash `merge` is called on is used as the default and the options argument is merged into it
             
-            @matched_routes, @ignored_routes, @check_static_files = options.values_at(:matched_routes, :ignored_routes, :check_static_files)
+            @matched_routes, @ignored_routes, @check_file_extensions = options.values_at(:matched_routes, :ignored_routes, :check_file_extensions)
             
             self.robots_json = @options[:robots_json] # Use the setter method which sets the @robots_json instance variable to the path, then sets @robots to the parsed JSON of the path's contents.
             self.extensions_json = @options[:extensions_json] # Use the setter method which sets the @extensions_json instance variable to the path, then sets @extensions to the parsed JSON of the path's contents.

data/lib/snap_search/{exception.rb → error.rb}

@@ -1,8 +1,8 @@
-module SnapSearch
-    
-    # The superclass for all SnapSearch based exceptions.
-    class Exception < StandardError
-        
-    end
-    
-end
+module SnapSearch
+    
+    # The superclass for all SnapSearch based exceptions.
+    class Error < StandardError
+        
+    end
+    
+end

data/lib/snap_search/interceptor.rb

@@ -18,18 +18,25 @@ module SnapSearch
         def intercept(options={})
             encoded_url = @detector.get_encoded_url( options[:request].params, Addressable::URI.parse(options[:request].url) )
             
-            # all the before interceptor and return an Hash response if it has one
-            unless @before_intercept.nil?
-                result = @before_intercept.call(encoded_url)
-                
-                return result.to_hash if !result.nil? && (result.respond_to?(:to_h) || result.respond_to?(:to_hash))
-            end
-            response = @detector.detect(options) ? @client.request(encoded_url) : false
-            
-            # call the after response interceptor, and pass in the response Hash (which is always going to be a Hash)
-            @after_intercept.call(encoded_url, response) unless @after_intercept.nil?
+            detected = @detector.detect(options)
             
-            response
+            if detected
+              # all the before interceptor and return an Hash response if it has one
+              unless @before_intercept.nil?
+                  result = @before_intercept.call(encoded_url)
+                  
+                  return result.to_hash if !result.nil? && (result.respond_to?(:to_h) || result.respond_to?(:to_hash))
+              end
+              
+              response = @client.request(encoded_url)
+              
+              # call the after response interceptor, and pass in the response Hash (which is always going to be a Hash)
+              @after_intercept.call(encoded_url, response) unless @after_intercept.nil?
+              
+              response
+            else
+              false
+            end
         end
         
         # Before intercept callback.

data/lib/snap_search/{validation_exception.rb → validation_error.rb}

@@ -1,17 +1,17 @@
-require 'snap_search/exception'
-
-module SnapSearch
-    
-    # Raised when the parameters of a request from the Client are not valid.
-    class ValidationException < Exception
-        
-        # Raise a new ValidationException
-        def initialize(response_content)
-            error_messages = response_content.values.collect { |message| "    #{message}" }.join("\n")
-            
-            super("Validation error from SnapSearch. Check your request parameters:\n#{ error_messages }")
-        end
-        
-    end
-    
-end
+require 'snap_search/error'
+
+module SnapSearch
+    
+    # Raised when the parameters of a request from the Client are not valid.
+    class ValidationError < Error
+        
+        # Raise a new ValidationError
+        def initialize(response_content)
+            error_messages = response_content.values.collect { |message| "    #{message}" }.join("\n")
+            
+            super("Validation error from SnapSearch. Check your request parameters:\n#{ error_messages }")
+        end
+        
+    end
+    
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: snapsearch-client-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Ryan Scott Lewis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-11 00:00:00.000000000 Z
+date: 2014-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: version
@@ -153,11 +153,11 @@ files:
 - lib/rack/snap_search/config.rb
 - lib/rack/snap_search.rb
 - lib/snap_search/client.rb
-- lib/snap_search/connection_exception.rb
+- lib/snap_search/connection_error.rb
 - lib/snap_search/detector.rb
-- lib/snap_search/exception.rb
+- lib/snap_search/error.rb
 - lib/snap_search/interceptor.rb
-- lib/snap_search/validation_exception.rb
+- lib/snap_search/validation_error.rb
 - lib/snap_search.rb
 - examples/rack/config.ru
 - examples/rack/Gemfile