eden_cloud_search 0.1.10

data/.gitignore

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

data/.rspec

@@ -0,0 +1 @@
+--color --format documentation

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in cloud_search.gemspec
+gemspec
+
+group :test do
+  gem "growl"
+  gem "guard"
+  gem "guard-rspec"
+  gem "rb-fsevent"
+  gem "debugger"
+end
+

data/Guardfile

@@ -0,0 +1,10 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+end
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Willian Fernandes
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,142 @@
+[![Build Status](https://secure.travis-ci.org/willian/cloud_search.png)](http://travis-ci.org/willian/cloud_search)
+
+# CloudSearch
+
+This is a simple Ruby wrapper around the Amazon's CloudSearch API. It has support for searching (with both simple and boolean queries), pagination
+and documents indexing.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem "cloud_search"
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install cloud_search
+
+## Usage
+
+The example bellow uses the Amazon's example database called `imdb-movies`:
+
+### Use your AWS CloudSearch configuration
+``` ruby
+CloudSearch.configure do |config|
+  config.domain_id   = "pl6u4t3elu7dhsbwaqbsy3y6be"
+  config.domain_name = "imdb-movies"
+end
+```
+
+### Search for 'star wars' on 'imdb-movies'
+``` ruby
+searcher = CloudSearch::Searcher.new
+resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)
+         .with_query("star wars")
+         .search
+```
+
+### Or you can search using part of the name
+``` ruby
+searcher = CloudSearch::Searcher.new
+resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)
+         .with_query("matri*")
+         .search
+```
+
+### You can also search using boolean queries
+``` ruby
+searcher = CloudSearch::Searcher.new
+resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)
+         .as_boolean_query
+         .with_query("year:2000")
+         .search
+```
+
+### You can use weighted fields in your search
+``` ruby
+searcher = CloudSearch::Searcher.new
+resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)
+         .with_weights(:title => 3, :actor => 2, :default_weight => 1)
+         .as_boolean_query
+         .with_query("year:2000")
+         .search
+```
+
+### You can sort the result using a rank expression (previously created on your CloudSearch domain)
+``` ruby
+searcher = CloudSearch::Searcher.new
+resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)
+           .with_query("matrix")
+           .ranked_with("my_rank_expression")
+```
+
+If you want to rank using descending order, just prepend the expression name with a '-' sign:
+
+``` ruby
+resp = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)
+       .with_query("matrix")
+       .ranked_with("-my_rank_expression")
+```
+
+## Results
+``` ruby
+resp.results.each do |result|
+  movie = result["data"]
+
+  # List of actors on the movie
+  movie["actor"]
+
+  # Movie's name
+  movie["title"]
+
+  # A rank number used to sort the results
+  # The `text_relevance` key is added by AMS CloudSearch
+  movie["text_relevance"]
+end
+```
+
+## Pagination
+
+The results you get back are (currently) API-compatible with will\_paginate:
+
+``` ruby
+searcher = CloudSearch::Searcher.new
+resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)
+         .with_query("star wars")
+         .with_items_per_page(30)
+         .at_page(10)
+         .search
+
+resp.total_entries #=> 5000
+resp.total_pages   #=> 167
+resp.current_page  #=> 10
+resp.offset        #=> 300
+resp.page_size     #=> 30
+```
+
+## Indexing documents
+
+``` ruby
+document = CloudSearch::Document.new :type    => "add", # or "delete"
+                                     :version => 123,
+                                     :id      => 680,
+                                     :lang    => :en,
+                                     :fields  => {:title => "Lord of the Rings"}
+
+indexer = CloudSearch::Indexer.new
+indexer << document # add as many documents as you want (CloudSearch currently sets a limit of 5MB per documents batch)
+indexer.index
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test    => :spec
+

data/eden_cloud_search.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'eden_cloud_search/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "eden_cloud_search"
+  gem.version       = CloudSearch::VERSION
+  gem.platform      = Gem::Platform::RUBY
+  gem.authors       = ["Willian Fernandes"]
+  gem.email         = ["willian@willianfernandes.com.br"]
+  gem.homepage      = "http://rubygems.org/gems/eden_cloud_search"
+  gem.summary       = "A wraper to Amazon CloudSearch's API"
+  gem.description   = gem.summary
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_development_dependency "pry"
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "rspec"     , "~> 2.11"
+  gem.add_development_dependency "simplecov" , "~> 0.6"
+  gem.add_development_dependency "vcr"       , "~> 2.2"
+  gem.add_development_dependency "webmock"
+
+  gem.add_dependency "rest-client", "~> 1.6.7"
+end
+

data/lib/eden_cloud_search/config.rb

@@ -0,0 +1,62 @@
+require "singleton"
+
+module CloudSearch
+  class MissingConfigurationError < StandardError
+    def initialize(parameter_name)
+      super "Missing '#{parameter_name}' configuration parameter"
+    end
+  end
+
+  module ConfigurationChecking
+    private
+
+    def check_configuration_parameters
+      %w(domain_id domain_name).each do |config|
+        raise MissingConfigurationError.new(config) if CloudSearch.config[config].nil?
+      end
+    end
+  end
+
+  class Config
+    include Singleton
+
+    attr_accessor :api_version
+    attr_accessor :configuration_url
+    attr_accessor :domain_id
+    attr_accessor :domain_name
+    attr_accessor :document_url
+    attr_accessor :region
+    attr_accessor :search_url
+
+    def [](config)
+      self.__send__(config)
+    end
+
+    def api_version
+      @api_version ||= "2011-02-01"
+    end
+
+    def configuration_url
+      @configuration_url ||= "https://cloudsearch.#{self.region}.amazonaws.com"
+    end
+
+    def document_url
+      @document_url ||= "http://doc-#{base_path}"
+    end
+
+    def region
+      @region ||= "us-east-1"
+    end
+
+    def search_url
+      @search_url ||= "http://search-#{base_path}"
+    end
+
+    private
+
+    def base_path
+      "#{self.domain_name}-#{self.domain_id}.#{self.region}.cloudsearch.amazonaws.com/#{self.api_version}"
+    end
+  end
+end
+

data/lib/eden_cloud_search/document.rb

@@ -0,0 +1,95 @@
+module CloudSearch
+  class Document
+    MAX_VERSION = 4294967295
+
+    attr_accessor :type, :lang, :fields
+    attr_reader :errors, :id, :version
+
+    def initialize(attributes = {})
+      attributes.each_pair { |key, value| self.__send__("#{key}=", value) }
+    end
+
+    def id=(_id)
+      @id = _id.to_s
+    end
+
+    def version=(_version)
+      begin
+        @version = Integer(_version)
+      rescue ArgumentError, TypeError
+        @version = _version
+      end
+    end
+
+    def valid?
+      @errors = {}
+      run_id_validations
+      run_version_validations
+      run_type_validations
+      if type == "add"
+        run_lang_validations
+        run_fields_validations
+      end
+      errors.empty?
+    end
+
+    def as_json
+      {:type => type, :id => id, :version => version}.tap do |hash|
+        hash.merge!(:lang => lang, :fields => fields) if type == "add"
+      end
+    end
+
+    def to_json
+      JSON.unparse as_json
+    end
+
+    private
+
+    def run_id_validations
+      validate :id do |messages|
+        messages << "can't be blank" if blank?(:id)
+        messages << "is invalid" unless blank?(:id) or id =~ /\A[^_][a-z0-9_]+\z/
+      end
+    end
+
+    def run_version_validations
+      validate :version do |messages|
+        messages << "can't be blank" if blank?(:version)
+        messages << "is invalid" unless blank?(:version) or version.to_s =~ /\A[0-9]+\z/
+        messages << "must be less than #{MAX_VERSION + 1}" if messages.empty? and version > MAX_VERSION
+      end
+    end
+
+    def run_type_validations
+      validate :type do |messages|
+        messages << "can't be blank" if blank?(:type)
+        messages << "is invalid" if !blank?(:type) and !%w(add delete).include?(type)
+      end
+    end
+
+    def run_lang_validations
+      validate :lang do |messages|
+        messages << "can't be blank" if blank?(:lang)
+        messages << "is invalid" unless blank?(:lang) or lang =~ /\A[a-z]{2}\z/
+      end
+    end
+
+    def run_fields_validations
+      validate :fields do |messages|
+        messages << "can't be empty" if fields.nil?
+        messages << "must be an instance of Hash" if !fields.nil? and !fields.instance_of?(Hash)
+      end
+    end
+
+    def blank?(attr)
+      self.__send__(attr).to_s.strip.length.zero?
+    end
+
+    def validate(attr, &block)
+      messages = []
+      yield messages
+      errors[attr] = messages unless messages.empty?
+    end
+  end
+end
+

data/lib/eden_cloud_search/exceptions.rb

@@ -0,0 +1,3 @@
+module CloudSearch
+  class InsufficientParametersException < StandardError; end
+end

data/lib/eden_cloud_search/indexer.rb

@@ -0,0 +1,44 @@
+module CloudSearch
+  class Indexer
+    include ::CloudSearch::ConfigurationChecking
+
+    def initialize
+      @documents = []
+    end
+
+    def <<(document)
+      raise InvalidDocument.new(document) unless document.valid?
+      @documents << document
+    end
+
+    alias :add :<<
+
+    def documents
+      @documents.freeze
+    end
+
+    def index
+      cloud_search_response = RestClient.post url, documents_json, headers
+      message               = "#{cloud_search_response.code} - #{cloud_search_response.length} bytes\n#{url}\n"
+      response              = JSON.parse cloud_search_response.body
+
+      [response, message]
+    end
+
+    private
+
+    def headers
+      {"Content-Type" => "application/json", "Accept" => "application/json" }
+    end
+
+    def documents_json
+      JSON.unparse(@documents.map(&:as_json))
+    end
+
+    def url
+      check_configuration_parameters
+
+      "#{CloudSearch.config.document_url}/documents/batch"
+    end
+  end
+end

data/lib/eden_cloud_search/invalid_document.rb

@@ -0,0 +1,11 @@
+module CloudSearch
+  class InvalidDocument < StandardError
+    def initialize(document)
+      document.valid?
+      error_message = document.errors.map do
+        |attribute, errors| errors.empty? ? nil : "#{attribute}: #{errors.join(", ")}"
+      end.join("; ")
+      super error_message
+    end
+  end
+end

data/lib/eden_cloud_search/search_response.rb

@@ -0,0 +1,73 @@
+module CloudSearch
+  class SearchResponse
+    attr_writer   :items_per_page
+    attr_reader   :current_page, :total_pages, :body, :facets
+    attr_accessor :http_code
+
+    def body=(body)
+      @body = JSON.parse(body || "{}")
+      calculate_pages
+      build_facets
+      @body
+    end
+
+    def results
+      _hits["hit"] || []
+    end
+
+    def hits
+      _hits["found"] || 0
+    end
+
+    def found?
+      hits > 0
+    end
+
+    def items_per_page
+      @items_per_page || 10
+    end
+
+    def has_pagination?
+      hits > items_per_page
+    end
+
+    def offset
+      return 0 unless found?
+      (@current_page - 1) * items_per_page
+    end
+
+    alias :page_size :items_per_page
+    alias :limit_value :items_per_page
+    alias :total_entries :hits
+    alias :any? :found?
+
+    private
+
+    def calculate_pages
+      num_full_pages = hits / items_per_page
+      @total_pages   = hits % items_per_page > 0 ? num_full_pages + 1 : num_full_pages
+      @total_pages   = 1 if @total_pages == 0
+
+      start = _hits["start"] || 0
+      @current_page = (start / items_per_page) + 1
+      @current_page = @total_pages if @current_page > @total_pages
+    end
+
+    def build_facets
+      @facets = {}
+      return unless body['facets']
+
+      body['facets'].each do |facet, result|
+        @facets[facet] = if result['constraints']
+          result['constraints'].inject({}) { |hash, item| hash[item['value']] = item['count']; hash }
+        else
+          result
+        end
+      end
+    end
+
+    def _hits
+      body["hits"] || {}
+    end
+  end
+end

data/lib/eden_cloud_search/searcher.rb

@@ -0,0 +1,118 @@
+require 'uri'
+
+module CloudSearch
+  class Searcher
+    include ::CloudSearch::ConfigurationChecking
+
+    attr_reader :weights
+
+    def initialize
+      @response = SearchResponse.new
+      @query = ''
+      @boolean_queries = {}
+      @filters = {}
+      @facets = []
+      @fields = []
+    end
+
+    def search
+      cloud_search_response = RestClient.get "#{CloudSearch.config.search_url}/search", :params => params
+      @response.http_code   = cloud_search_response.code
+      @response.body        = cloud_search_response.body
+
+      @response
+    end
+
+    def with_query(query)
+      @query = query || ''
+      self
+    end
+
+    def with_boolean_query(queries)
+      queries.each do |k, v|
+        queries[k] = [v] unless v.respond_to? :map
+      end
+
+      @boolean_queries.merge!(queries)
+      self
+    end
+
+    def with_filters(filters)
+      @filters = filters
+      self
+    end
+
+    def with_facets(*facets)
+      @facets += facets
+      self
+    end
+
+    def ranked_by(rank_expression)
+      @rank = rank_expression
+      self
+    end
+
+    def with_fields(*fields)
+      @fields += fields
+      self
+    end
+
+    def with_items_per_page(items_per_page)
+      @response.items_per_page = items_per_page
+      self
+    end
+
+    def at_page(page)
+      @page_number = (page && page < 1) ? 1 : page
+      self
+    end
+
+    def params
+      check_configuration_parameters
+      raise InsufficientParametersException.new('At least query or boolean_query must be defined.') if (@query.empty? && @boolean_queries.empty?)
+
+      params = {
+        'q' => query,
+        'bq' => boolean_query,
+        'size' => items_per_page,
+        'start' => start,
+        'return-fields' => URI.escape(@fields.join(",")),
+        'facet' => @facets.join(','),
+        'rank' => @rank
+      }
+      params.merge! @filters
+      params.delete_if { |_,v| v.nil? || v.to_s.empty? }
+
+      params
+    end
+
+    def items_per_page
+      @response.items_per_page
+    end
+
+    def page_number
+      @page_number or 1
+    end
+
+    def start
+      return 0 if page_number <= 1
+      (items_per_page * (page_number - 1))
+    end
+
+    private
+
+    def query
+      CGI::escape(@query)
+    end
+
+    def boolean_query
+      return '' if @boolean_queries.empty?
+
+      bq = @boolean_queries.map do |key, values|
+        "#{key}:'#{values.map { |e| CGI::escape(e) }.join('|')}'"
+      end.join(' ')
+      "(and #{bq})"
+    end
+  end
+end
+

data/lib/eden_cloud_search/version.rb

@@ -0,0 +1,3 @@
+module CloudSearch
+  VERSION = "0.1.10"
+end