cloudsearchable 0.0.1

data/.rspec

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

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# gem's dependencies in cloudsearchable.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Lane LaRue
+
+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,119 @@
+# Cloudsearchable
+An ActiveRecord-style ORM query interface for AWS Cloud Search.
+
+## Installation
+Add to your Gemfile: gem 'cloudsearchable'. Run bundle or: gem install cloudsearchable.
+
+## Usage
+### 1. Mix Cloudsearchable into your class
+```ruby
+class Customer
+  include Cloudsearchable
+
+  attr_accessor :id, :customer, :name, :lock_version
+  
+  # This is the default index. You probably only need one.
+  index_in_cloudsearch do |idx|
+    literal :id,          :searchable => true
+  end
+
+  # A named index.
+  index_in_cloudsearch :test_index do |idx|
+  
+    # Fetch the customer_id field from customer
+    literal :customer_id, :returnable => true,  :searchable => true, :source => Proc.new { customer }
+
+    # Map the 'name' Ruby attribute to a field called 'test_name'
+    text    :test_name,   :returnable => false, :searchable => true, :source => :name
+
+    # uint fields can be used in result ranking functions
+    uint    :helpfulness, :returnable => true,  :searchable => false do; 1234 end
+  end
+end
+```
+### 2. Index some objects
+```ruby
+c = Customer.new
+c.add_to_indexes
+c.update_indexes
+c.remove_from_indexes
+```
+### 3. Start querying
+```ruby
+Customer.search.where(customer_id: 12345)
+Customer.search.where(customer_id: 12345).order('-helpfulness')  # ordering
+Customer.search.where(customer_id: 12345).limit(10)              # limit, default 100000
+Customer.search.where(customer_id: 12345).offset(100)            # offset
+Customer.search.where(customer_id: 12345).found_count            # count
+
+Customer.search.where(customer_id: 12345).where(helpfulness: 42) # query chain
+Customer.search.where(customer_id: 12345, helpfulness: 42)       # query chain from hash
+Customer.search.where(:category, :any, ["big", "small"])         # multiple values
+Customer.search.where(:customer_id, :!=, 1234)                   # "not equal to" operator
+Customer.search.text('test')                                     # text search
+Customer.search.text('test').where(:featured, :==, 'f')          # text search with other fields
+
+Customer.search.where(:helpfulness, :within_range, 0..123)       # uint range query, string range works too
+Customer.search.where(:helpfulness, :>, 123)                     # uint greather than
+Customer.search.where(:helpfulness, :>=, 123)                    # uint greather than or equal to
+Customer.search.where(:helpfulness, :<, 123)                     # uint less than
+Customer.search.where(:helpfulness, :<=, 123)                    # uint less than or equal to
+```
+These queries return a Cloudsearchable::Query, calling .to_a or .found_count will fetch the results
+```ruby
+Customer.search.where(customer_id: 12345).each |customer|
+  p "#{customer.class}: #{customer.name}"
+end
+# Customer: foo
+# Customer: bar
+```
+### Configuration
+```ruby
+# config\initializers\cloudsearchable_config.rb
+
+require 'cloudsearchable'
+
+Cloudsearchable.configure do |config|
+  config.domain_prefix = "dev-lane-"
+end
+```
+Supported Options
+* domain_prefix - A name prefix string for your domains in CloudSearch. Defaults to Rails.env, or "" if Rails is undefined.
+* config.fatal_warnings - raises WarningInQueryResult exception on warning. Defaults to false.
+* config.logger - a custom logger, defaults to Rails if defined.
+
+### Other Features
+
+Cloudsearchable provides access the underlying AWS client objects, such as '''CloudSearch.client''' and '''class.cloudsearch_domains'''. For example here is how to drop domains associated with Customer class:
+
+```ruby
+  client = CloudSearch.client
+  Customer.cloudsearch_domains.each do |key, domain|
+    domain_name = domain.name
+    puts "...dropping #{domain_name}"
+    client.delete_domain(:domain_name => domain_name)
+  end
+```
+
+See spec tests and source code for more information.
+
+## TODO:
+- use ActiveSupport instrumentation: http://edgeguides.rubyonrails.org/active_support_instrumentation.html#creating-custom-events
+
+## Credits
+
+* [Logan Bowers](https://github.com/loganb)
+* [Peter Abrahamsen](https://github.com/rainhead)
+* [Lane LaRue](https://github.com/luxx)
+* [Philip White](https://github.com/philipmw)
+
+MIT License
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Run the tests (`rake spec`)
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new('spec')
+
+# make spec test the default task
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', "README", "LICENSE"]   # optional
+  t.options = ['-m', 'markdown'] # optional
+end

data/cloudsearchable.gemspec

@@ -0,0 +1,50 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cloudsearchable/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "cloudsearchable"
+  spec.version       = Cloudsearchable::VERSION
+  spec.authors       = ["Lane LaRue"]
+  spec.email         = ["llarue@amazon.com"]
+  spec.description   = %q{ActiveRecord-like query interface for AWS Cloud Search}
+  spec.summary       = %q{ActiveRecord-like query interface for AWS Cloud Search}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  # generated with `git ls-files`.split($/)
+  spec.files = [
+      ".rspec",
+      "Gemfile",
+      "LICENSE.txt",
+      "README.md",
+      "Rakefile",
+      "cloudsearchable.gemspec",
+      "lib/cloudsearchable.rb",
+      "lib/cloudsearchable/cloud_search.rb",
+      "lib/cloudsearchable/domain.rb",
+      "lib/cloudsearchable/field.rb",
+      "lib/cloudsearchable/query_chain.rb",
+      "lib/cloudsearchable/version.rb",
+      "spec/cloudsearchable/cloud_search_spec.rb",
+      "spec/cloudsearchable/cloudsearchable_spec.rb",
+      "spec/cloudsearchable/domain_spec.rb",
+      "spec/cloudsearchable/field_spec.rb",
+      "spec/cloudsearchable/query_chain_spec.rb",
+      "spec/spec_helper.rb",
+      "spec/test_classes/cloud_searchable_test_class.rb"
+  ]
+
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_dependency 'aws-sdk'
+
+  # testing dependencies
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "activemodel"
+end

data/lib/cloudsearchable.rb

@@ -0,0 +1,206 @@
+require 'cloudsearchable/version'
+
+require 'cloudsearchable/domain'
+require 'cloudsearchable/field'
+require 'cloudsearchable/query_chain'
+require 'cloudsearchable/cloud_search'
+require 'cloudsearchable/config'
+
+require 'active_support/inflector'
+require 'active_support/core_ext/string'
+
+module Cloudsearchable
+  def self.configure
+    block_given? ? yield(Cloudsearchable::Config) : Cloudsearchable::Config
+  end
+
+  def self.config
+    configure
+  end
+
+  def self.logger
+    Cloudsearchable::Config.logger
+  end
+
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  def cloudsearch_domains= *args
+    self.class.cloudsearch_domains = args
+  end
+
+  def cloudsearch_domains
+    self.class.cloudsearch_domains
+  end
+
+  def update_indexes
+    if destroyed?
+      remove_from_indexes
+    else
+      add_to_indexes
+    end
+  end
+
+  def add_to_indexes
+    cloudsearch_domains.map do |name, domain|
+      domain.post_record(self, id, lock_version)
+    end
+  end
+
+  def remove_from_indexes
+    cloudsearch_domains.map do |name, domain|
+      domain.delete_record(id, lock_version)
+    end
+  end
+
+  protected
+
+  class DSL
+    attr_reader :domain, :base
+
+    def initialize domain, base
+      @domain = domain
+      @base = base
+    end
+
+    def uint name, options = {}, &block
+      field name, :uint, options, &block
+    end
+
+    def text name, options = {}, &block
+      field name, :text, options, &block
+    end
+
+    def literal name, options = {}, &block
+      field name, :literal, options, &block
+    end
+
+    def field name, type, options = {}, &block
+      # This block is executed in the context of the record
+      if block_given?
+        options[:source] = block.to_proc
+      end
+      domain.add_field name, type, options
+    end
+  end
+
+  module ClassMethods
+    def cloudsearch_domains= domains
+      @cloudsearch_domains = domains
+    end
+
+    def cloudsearch_domains
+      @cloudsearch_domains || {}
+    end
+
+    #
+    # Declares a Cloudsearchable index that returns a list of object of this class.
+    #
+    # @param name (optional) optional name for the index. If not specified, a default (unnamed) index for the class will be created
+    # @param options (optional) Hash defining an index
+    #
+    # @option options [String] :name Name of the index
+    #
+    #
+    def index_in_cloudsearch(name = nil, &block)
+      locator_field = :"#{cloudsearch_prefix.singularize}_id"
+      # Fetches the existing search domain, or generates a new one
+      unless domain = cloudsearch_domains[name]
+        domain = new_cloudsearch_index(name).tap do |d|
+          # This id field is used to reify search results
+          d.add_field(locator_field, :literal,
+            :result_enabled => true, :search_enabled => true,
+            :source => :id)
+        end
+        self.cloudsearch_domains = self.cloudsearch_domains.merge({name => domain})
+      end
+
+      if block_given?
+        dsl = DSL.new(domain, self)
+        dsl.instance_exec &block
+      end
+
+      # Define the search method
+      search_method_name = "search#{name && ('_' + name.to_s)}".to_sym
+      define_singleton_method search_method_name do
+        Query.new(self, cloudsearch_index(name), locator_field)
+      end
+    end
+
+    def cloudsearch_index name = nil
+      cloudsearch_domains[name]
+    end
+
+    #
+    # Prefix name used for indexes, defaults to class name underscored
+    #
+    def cloudsearch_prefix
+      name.pluralize.underscore.gsub('/', '_')
+    end
+
+    def new_cloudsearch_index name
+      name = [cloudsearch_prefix, name].compact.join('-').gsub('_','-')
+      Cloudsearchable::Domain.new name
+    end
+
+    # By default use 'find' to materialize items
+    def materialize_method method_name = nil
+      @materialize_method = method_name unless method_name.nil?
+      @materialize_method.nil? ? :find : @materialize_method
+    end
+  end
+
+  #
+  # Wraps a Cloudsearchable::QueryChain, provides methods to execute and reify
+  # a query into search result objects
+  #
+  class Query
+    include Enumerable
+
+    attr_reader :query, :class
+
+    #
+    # @param clazz [ActiveRecord::Model] The class of the Model object that
+    #        is being searched. The result set will be objects of this type.
+    # @param domain [Domain] Cloudsearchable Domain to search
+    # @param identity_field [Symbol] name of the field that contains the id of
+    #                                the clazz (e.g. :collection_id)
+    #
+    def initialize(clazz, domain, identity_field)
+      @query = Cloudsearchable::QueryChain.new(domain, fatal_warnings: Cloudsearchable.config.fatal_warnings)
+      @class = clazz
+      @query.returning(identity_field)
+      @identity_field = identity_field
+    end
+
+    [:where, :text, :order, :limit, :offset, :returning].each do |method_name|
+      # Passthrough methods, see CloudSearch::Domain for docs
+      define_method method_name do |*args|
+        @query.send(method_name, *args)
+        self
+      end
+    end
+
+    # Pass through to Cloudsearchable::Domain#materialize!, then retrieve objects from database
+    # TODO: this does NOT preserve order!
+    def materialize!(*args)
+      @results ||= begin
+        record_ids = @query.map{|result_hit| result_hit['data'][@identity_field.to_s].first}.reject{|r| r.nil?}
+        @class.send(@class.materialize_method, record_ids)
+      end
+    end
+
+    def each &block
+      # Returns an enumerator
+      return enum_for(__method__) unless block_given?
+      materialize!
+      @results.respond_to?(:each) ? @results.each { |o| yield o } : [@results].send(:each, &block)
+    end
+
+    def found_count
+      query.found_count
+    end
+
+  end
+end

data/lib/cloudsearchable/cloud_search.rb

@@ -0,0 +1,41 @@
+require 'aws-sdk'
+require 'json'
+
+module CloudSearch
+  API_VERSION = "2011-02-01"
+
+  def self.client
+    @client ||= AWS::CloudSearch::Client.new
+  end
+
+  def self.client=(client)
+    @client = client
+  end
+
+  #
+  # Send an SDF document to CloudSearch via http post request.
+  # Returns parsed JSON response, or raises an exception
+  #
+  def self.post_sdf endpoint, sdf
+    self.post_sdf_list endpoint, [sdf]
+  end
+
+  def self.post_sdf_list endpoint, sdf_list
+    uri = URI.parse("http://#{endpoint}/#{API_VERSION}/documents/batch")
+
+    req = Net::HTTP::Post.new(uri.path)
+    req.body = JSON.generate sdf_list
+    req["Content-Type"] = "application/json"
+
+    http = Net::HTTP.new uri.host,uri.port
+    response = http.start{|http| http.request(req)}
+
+    if response.is_a? Net::HTTPSuccess
+      JSON.parse response.body
+    else
+      # Raise an exception based on the response see http://ruby-doc.org/stdlib-1.9.2/libdoc/net/http/rdoc/Net/HTTP.html
+      response.error!
+    end
+
+  end
+end