asari 0.3.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in asari.gemspec
+gemspec

data/README.md

@@ -0,0 +1,4 @@
+asari
+=====
+
+a Ruby wrapper for AWS CloudSearch.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/asari.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "asari/version"
+
+Gem::Specification.new do |s|
+  s.name        = "asari"
+  s.version     = Asari::VERSION
+  s.authors     = ["Tommy Morgan"]
+  s.email       = ["tommy@wellbredgrapefruit.com"]
+  s.homepage    = "http://github.com/duwanis/asari"
+  s.summary     = %q{Asari is a Ruby interface for AWS CloudSearch.}
+  s.description = %q{Asari s a Ruby interface for AWS CloudSearch}
+
+  s.rubyforge_project = "asari"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  # s.add_runtime_dependency "rest-client"
+
+  s.add_runtime_dependency "httparty"
+
+  s.add_development_dependency "rspec"
+end

data/lib/asari.rb

@@ -0,0 +1,151 @@
+require "asari/version"
+
+require "asari/exceptions"
+
+require "httparty"
+
+require "json"
+require "cgi"
+
+class Asari
+  class << self
+    attr_accessor :mode
+    @mode = :sandbox
+  end
+
+  attr_writer :api_version
+  attr_writer :search_domain
+
+  def initialize(search_domain=nil)
+    @search_domain = search_domain 
+  end
+
+  # Public: returns the current search_domain, or raises a
+  # MissingSearchDomainException.
+  #
+  def search_domain
+    @search_domain || raise(MissingSearchDomainException.new)
+  end
+
+  # Public: returns the current api_version, or the sensible default of
+  # "2011-02-01" (at the time of writing, the current version of the
+  # CloudSearch API).
+  #
+  def api_version
+    @api_version || "2011-02-01"
+  end
+
+  # Public: Search for the specified term.
+  #
+  # Examples:
+  #
+  #     @asari.search("fritters") #=> ["13","28"]
+  #
+  # Returns: An Array of all document IDs in the system that match the
+  #   specified search term. If no results are found, an empty Array is
+  #   returned.
+  #
+  # Raises: SearchException if there's an issue communicating the request to
+  #   the server.
+  def search(term)
+    return [] if self.class.mode == :sandbox
+
+    url = "http://search-#{search_domain}.us-east-1.cloudsearch.amazonaws.com/#{api_version}/search?q=#{CGI.escape(term)}"
+    begin
+      response = HTTParty.get(url)
+    rescue Exception => e
+      ae = Asari::SearchException.new("#{e.class}: #{e.message}")
+      ae.set_backtrace e.backtrace
+      raise ae
+    end
+
+    unless response.response.code == "200"
+      raise Asari::SearchException.new("#{response.response.code}: #{response.response.msg}")
+    end
+
+    response.parsed_response["hits"]["hit"].map { |h| h["id"] }
+  end
+
+  # Public: Add an item to the index with the given ID.
+  #   
+  #     id - the ID to associate with this document
+  #     fields - a hash of the data to associate with this document. This
+  #       needs to match the search fields defined in your CloudSearch domain.
+  #
+  # Examples:
+  #
+  #     @asari.update_item("4", { :name => "Party Pooper", :email => ..., ... }) #=> nil
+  #
+  # Returns: nil if the request is successful.
+  #
+  # Raises: DocumentUpdateException if there's an issue communicating the
+  #   request to the server.
+  #
+  def add_item(id, fields)
+    return nil if self.class.mode == :sandbox
+    query = { "type" => "add", "id" => id, "version" => 1, "lang" => "en" }
+    query["fields"] = fields
+    doc_request(query)
+  end
+
+  # Public: Update an item in the index based on its document ID.
+  #   Note: As of right now, this is the same method call in CloudSearch
+  #   that's utilized for adding items. This method is here to provide a
+  #   consistent interface in case that changes.
+  # 
+  # Examples:
+  #     
+  #     @asari.update_item("4", { :name => "Party Pooper", :email => ..., ... }) #=> nil
+  #
+  # Returns: nil if the request is successful.
+  #
+  # Raises: DocumentUpdateException if there's an issue communicating the
+  #   request to the server.
+  #
+  def update_item(id, fields)
+    add_item(id, fields)
+  end
+
+  # Public: Remove an item from the index based on its document ID.
+  #
+  # Examples:
+  #   
+  #     @asari.search("fritters") #=> ["13","28"]
+  #     @asari.remove_item("13") #=> nil
+  #     @asari.search("fritters") #=> ["28"]
+  #     @asari.remove_item("13") #=> nil
+  #
+  # Returns: nil if the request is successful (note that asking the index to
+  #   delete an item that's not present in the index is still a successful
+  #   request).
+  # Raises: DocumentUpdateException if there's an issue communicating the
+  #   request to the server.
+  def remove_item(id)
+    return nil if self.class.mode == :sandbox
+
+    query = { "type" => "delete", "id" => id, "version" => 2 }
+    doc_request query
+  end
+
+  # Internal: helper method: common logic for queries against the doc endpoint.
+  #
+  def doc_request(query)
+    endpoint = "http://doc-#{search_domain}.us-east-1.cloudsearch.amazonaws.com/#{api_version}/documents/batch"
+
+    options = { :body => [query].to_json, :headers => { "Content-Type" => "application/json"} }
+
+    begin
+      response = HTTParty.post(endpoint, options)
+    rescue Exception => e
+      ae = Asari::DocumentUpdateException.new("#{e.class}: #{e.message}")
+      ae.set_backtrace e.backtrace
+      raise ae
+    end
+
+    unless response.response.code == "200"
+      raise Asari::DocumentUpdateException.new("#{response.response.code}: #{response.response.msg}")
+    end
+
+    nil
+  end
+end

data/lib/asari/active_record.rb

@@ -0,0 +1,114 @@
+class Asari
+  # Public: This module should be included in any class inheriting from
+  # ActiveRecord::Base that needs to be indexed. Every time this module is
+  # included, asari_index *must* be called (see below). Including this module
+  # will automatically create before_delete, after_create, and after_update AR
+  # callbacks to remove, add, and update items in the CloudSearch index
+  # (respectively).
+  #
+  module ActiveRecord
+    def self.included(base)
+      base.extend(ClassMethods)
+
+      base.before_delete :asari_remove_from_index
+      base.after_create :asari_add_to_index
+      base.after_update :asari_update_in_index
+    end
+
+    def asari_remove_from_index
+      self.class.asari_remove_item(self)
+    end
+
+    def asari_add_to_index
+      self.class.asari_add_item(self)
+    end
+
+    def asari_update_in_index
+      self.class.asari_update_item(self)
+    end
+
+    module ClassMethods
+
+      # Public: DSL method for adding this model object to the asari search
+      # index.
+      #
+      # This method *must* be called in any object that includes
+      # Asari::ActiveRecord, or your methods will be very sad.
+      #
+      #   search_domain - the CloudSearch domain to use for indexing this model.
+      #   fields - an array of Symbols representing the list of fields that
+      #     should be included in this index.
+      #
+      # Examples:
+      #     class User < ActiveRecord::Base
+      #       include Asari::ActiveRecord
+      #
+      #       asari_index("my-companies-users-asglkj4rsagkjlh34", [:name, :email])
+      #
+      def asari_index(search_domain, fields)
+        @asari = Asari.new(search_domain)
+        @fields = fields
+      end
+
+      # Internal: method for adding a newly created item to the CloudSearch
+      # index. Should probably only be called from asari_add_to_index above.
+      def asari_add_item(obj)
+        data = {}
+        @fields.each do |field|
+          data[field] = obj.send(field)
+        end
+        @asari.add_item(obj.send(:id), data)
+      rescue Asari::DocumentUpdateException => e
+        asari_on_error(e)
+      end
+
+      # Internal: method for updating a freshly edited item to the CloudSearch
+      # index. Should probably only be called from asari_update_in_index above.
+      def asari_update_item(obj)
+        data = {}
+        @fields.each do |field|
+          data[field] = obj.send(field)
+        end
+        @asari.update_item(obj.send(:id), data)
+      rescue Asari::DocumentUpdateException => e
+        asari_on_error(e)
+      end
+
+      # Internal: method for removing a soon-to-be deleted item from the CloudSearch
+      # index. Should probably only be called from asari_remove_from_index above.
+      def asari_remove_item(obj)
+        @asari.remove_item(obj.send(:id))
+      rescue Asari::DocumentUpdateException => e
+        asari_on_error(e)
+      end
+
+      # Public: method for searching the index for the specified term and
+      #   returning all model objects that match. 
+      #
+      # Returns: a list of all matching AR model objects, or an empty list if no
+      #   records are found that match.
+      #
+      # Raises: an Asari::SearchException error if there are issues
+      #   communicating with the CloudSearch server.
+      def asari_find(term)
+        ids = @asari.search(term).map { |id| id.to_i }
+        begin
+          self.find(*ids)
+        rescue ::ActiveRecord::RecordNotFound
+          []
+        end
+      end
+
+      # Public: method for handling errors from Asari document updates. By
+      # default, this method causes all such exceptions (generated by issues
+      # from updates, creates, or deletes to the index) to be raised immediately
+      # to the caller; override this method on your activerecord object to
+      # handle the errors in a custom fashion. Be sure to return true if you
+      # don't want the AR callbacks to halt execution.
+      #
+      def asari_on_error(exception)
+        raise exception
+      end
+    end
+  end
+end

data/lib/asari/exceptions.rb

@@ -0,0 +1,10 @@
+class Asari
+  class MissingSearchDomainException < StandardError
+  end
+
+  class SearchException < StandardError
+  end
+
+  class DocumentUpdateException < StandardError
+  end
+end

data/lib/asari/version.rb

@@ -0,0 +1,3 @@
+class Asari
+  VERSION = "0.3.0"
+end

data/spec/active_record_spec.rb

@@ -0,0 +1,105 @@
+require_relative '../spec_helper'
+
+describe Asari do
+  describe Asari::ActiveRecord do
+    describe "when CloudSearch is responding without error" do
+      before :each do
+        @asari = double()
+        ActiveRecordFake.instance_variable_set(:@asari, @asari)
+      end
+
+      it "correctly sets up a before_delete listener" do
+        expect(ActiveRecordFake.instance_variable_get(:@before_delete)).to eq(:asari_remove_from_index)
+      end
+
+      it "correctly sets up an after_create listener" do
+        expect(ActiveRecordFake.instance_variable_get(:@after_create)).to eq(:asari_add_to_index)
+      end
+
+      it "correctly sets up an after_update listener" do
+        expect(ActiveRecordFake.instance_variable_get(:@after_update)).to eq(:asari_update_in_index)
+      end
+
+      it "will automatically attempt to remove itself from the index" do
+        @asari.should_receive(:remove_item).with(1)
+        ActiveRecordFake.new.asari_remove_from_index
+      end
+
+      it "will automatically add itself to the index" do
+        @asari.should_receive(:add_item).with(1, {:name => "Fritters", :email => "fritters@aredelicious.com"})
+        ActiveRecordFake.new.asari_add_to_index
+      end
+
+      it "will automatically update itself in the index" do
+        @asari.should_receive(:update_item).with(1, {:name => "Fritters", :email => "fritters@aredelicious.com"})
+        ActiveRecordFake.new.asari_update_in_index
+      end
+
+      it "will allow you to search for items with the index" do
+        @asari.should_receive(:search).with("fritters").and_return(["1"])
+
+        ActiveRecordFake.asari_find("fritters")
+      end
+
+      it "will return a list of model objects when you search" do
+        @asari.should_receive(:search).with("fritters").and_return(["1"])
+
+        results = ActiveRecordFake.asari_find("fritters")
+        expect(results.class).to eq(Array)
+        expect(results[0].class).to eq(ActiveRecordFake)
+      end
+
+      it "will return an empty list when you search for a term that isn't in the index" do
+        @asari.should_receive(:search).with("veggie burgers").and_return([])
+
+        results = ActiveRecordFake.asari_find("veggie burgers")
+        expect(results.class).to eq(Array)
+        expect(results.size).to eq(0)
+      end
+    end
+
+    describe "When CloudSearch is being a problem" do
+      before :each do
+        ActiveRecordFake.instance_variable_set(:@asari, Asari.new("test-domain"))
+        stub_const("HTTParty", double())
+        HTTParty.stub(:post).and_return(fake_error_response)
+        HTTParty.stub(:get).and_return(fake_error_response)
+      end
+
+      it "will raise the Asari exception by default when adding to the index." do
+        expect { ActiveRecordFake.new.asari_add_to_index }.to raise_error(Asari::DocumentUpdateException)        
+      end
+
+      it "will raise the Asari exception by default when updating the index." do
+        expect { ActiveRecordFake.new.asari_update_in_index }.to raise_error(Asari::DocumentUpdateException)        
+      end
+
+      it "will raise the Asari exception by default when removing from index." do
+        expect { ActiveRecordFake.new.asari_remove_from_index }.to raise_error(Asari::DocumentUpdateException)        
+      end
+
+      it "will always raise the Asari exception when searching in the index." do
+        expect { ActiveRecordFake.asari_find("fritters") }.to raise_error(Asari::SearchException)
+      end
+
+      describe "when we've overridden asari_on_error" do
+        it "honors asari_on_error when adding to the index." do
+          expect(ActiveRecordFakeWithErrorOverride.new.asari_add_to_index).to eq(false)
+        end
+
+        it "honors asari_on_error when updating in the index." do
+          expect(ActiveRecordFakeWithErrorOverride.new.asari_update_in_index).to eq(false)
+        end
+
+        it "honors asari_on_error when removing from the index." do
+          expect(ActiveRecordFakeWithErrorOverride.new.asari_remove_from_index).to eq(false)
+        end
+
+        it "still raises the Asari exception when searching." do
+          expect { ActiveRecordFakeWithErrorOverride.asari_find("fritters") }.to raise_error(Asari::SearchException)
+        end
+      end
+
+    end
+  end
+end

data/spec/asari_spec.rb

@@ -0,0 +1,28 @@
+require_relative '../spec_helper'
+
+describe "Asari" do
+  before :each do
+    @asari = Asari.new
+  end
+
+  describe "configuration" do
+    it "defaults to the first CloudSearch API version." do
+      expect(@asari.api_version).to eq "2011-02-01"
+    end
+
+    it "allows you to set a specific API version." do
+      @asari.api_version = "2015-10-21" # WE'VE GOT TO GO BACK
+      expect(@asari.api_version).to eq "2015-10-21"
+    end
+
+    it "raises an exeception if no search domain is provided." do
+      expect { @asari.search_domain }.to raise_error Asari::MissingSearchDomainException
+    end
+
+    it "allows you to set a search domain." do
+      @asari.search_domain = "theroyaldomainofawesome"
+      expect(@asari.search_domain).to eq "theroyaldomainofawesome"
+    end
+  end
+
+end

data/spec/documents_spec.rb

@@ -0,0 +1,66 @@
+require_relative "../spec_helper"
+
+describe Asari do
+  describe "updating the index" do
+    before :each do
+      @asari = Asari.new("testdomain")
+      stub_const("HTTParty", double())
+      HTTParty.stub(:post).and_return(fake_post_success)
+    end
+
+    it "allows you to add an item to the index." do
+      HTTParty.should_receive(:post).with("http://doc-testdomain.us-east-1.cloudsearch.amazonaws.com/2011-02-01/documents/batch", { :body => [{ "type" => "add", "id" => "1", "version" => 1, "lang" => "en", "fields" => { :name => "fritters"}}].to_json, :headers => { "Content-Type" => "application/json"}})
+
+      expect(@asari.add_item("1", {:name => "fritters"})).to eq(nil)
+    end
+
+    it "allows you to update an item to the index." do
+      HTTParty.should_receive(:post).with("http://doc-testdomain.us-east-1.cloudsearch.amazonaws.com/2011-02-01/documents/batch", { :body => [{ "type" => "add", "id" => "1", "version" => 1, "lang" => "en", "fields" => { :name => "fritters"}}].to_json, :headers => { "Content-Type" => "application/json"}})
+
+      expect(@asari.update_item("1", {:name => "fritters"})).to eq(nil)
+    end
+
+    it "allows you to delete an item from the index." do
+      HTTParty.should_receive(:post).with("http://doc-testdomain.us-east-1.cloudsearch.amazonaws.com/2011-02-01/documents/batch", { :body => [{ "type" => "delete", "id" => "1", "version" => 2}].to_json, :headers => { "Content-Type" => "application/json"}})
+
+      expect(@asari.remove_item("1")).to eq(nil)
+    end
+
+    describe "when there are internet issues" do
+      before :each do
+        HTTParty.stub(:post).and_raise(SocketError.new)
+      end
+
+      it "raises an exception when you try to add an item to the index" do
+        expect { @asari.add_item("1", {})}.to raise_error(Asari::DocumentUpdateException)
+      end
+
+      it "raises an exception when you try to update an item in the index" do
+        expect { @asari.update_item("1", {})}.to raise_error(Asari::DocumentUpdateException)
+      end
+
+      it "raises an exception when you try to remove an item from the index" do
+        expect { @asari.remove_item("1")}.to raise_error(Asari::DocumentUpdateException)
+      end
+    end
+
+    describe "when there are CloudSearch issues" do
+      before :each do
+        HTTParty.stub(:post).and_return(fake_error_response)
+      end
+
+      it "raises an exception when you try to add an item to the index" do
+        expect { @asari.add_item("1", {})}.to raise_error(Asari::DocumentUpdateException)
+      end
+
+      it "raises an exception when you try to update an item in the index" do
+        expect { @asari.update_item("1", {})}.to raise_error(Asari::DocumentUpdateException)
+      end
+
+      it "raises an exception when you try to remove an item from the index" do
+        expect { @asari.remove_item("1")}.to raise_error(Asari::DocumentUpdateException)
+      end
+
+    end
+  end
+end

data/spec/search_spec.rb

@@ -0,0 +1,40 @@
+require_relative "../spec_helper"
+
+describe Asari do
+  describe "searching" do
+    before :each do
+      @asari = Asari.new("testdomain")
+      stub_const("HTTParty", double())
+      HTTParty.stub(:get).and_return(fake_response)
+    end
+
+    it "allows you to search." do
+      HTTParty.should_receive(:get).with("http://search-testdomain.us-east-1.cloudsearch.amazonaws.com/2011-02-01/search?q=testsearch")
+      @asari.search("testsearch")
+    end
+
+    it "escapes dangerous characters in search terms." do
+      HTTParty.should_receive(:get).with("http://search-testdomain.us-east-1.cloudsearch.amazonaws.com/2011-02-01/search?q=testsearch%21")
+      @asari.search("testsearch!")
+    end
+
+    it "returns a list of document IDs for search results." do
+      expect(@asari.search("testsearch")).to eq(["123","456"])
+    end
+
+    it "returns an empty list when no search results are found." do
+      HTTParty.stub(:get).and_return(fake_empty_response)
+      expect(@asari.search("testsearch")).to eq([])
+    end
+
+    it "raises an exception if the service errors out." do
+      HTTParty.stub(:get).and_return(fake_error_response)
+      expect { @asari.search("testsearch)") }.to raise_error Asari::SearchException
+    end
+
+    it "raises an exception if there are internet issues." do
+      HTTParty.stub(:get).and_raise(SocketError.new)
+      expect { @asari.search("testsearch)") }.to raise_error Asari::SearchException
+    end
+  end
+end

data/spec_helper.rb

@@ -0,0 +1,78 @@
+require 'asari'
+require 'asari/active_record'
+require 'ostruct'
+
+RSpec.configuration.expect_with(:rspec) { |c| c.syntax = :expect }
+
+def fake_response
+  OpenStruct.new(:parsed_response => { "hits" => {"hit" => [{"id" => "123"}, {"id" => "456"}]}},
+                 :response => OpenStruct.new(:code => "200"))
+end
+
+def fake_empty_response
+  OpenStruct.new(:parsed_response => { "hits" => {"hit" => []}},
+                 :response => OpenStruct.new(:code => "200"))
+end
+
+def fake_error_response
+  OpenStruct.new(:response => OpenStruct.new(:code => "404"))
+end
+
+def fake_post_success
+  OpenStruct.new(:response => OpenStruct.new(:code => "200"))
+end
+
+module ActiveRecord
+  class RecordNotFound < StandardError
+  end
+end
+
+class ActiveRecordFake
+  class << self
+    def before_delete(sym)
+      @before_delete = sym
+    end
+
+    def after_create(sym)
+      @after_create = sym
+    end
+
+    def after_update(sym)
+      @after_update = sym
+    end
+
+    def find(*args)
+      if args.size > 0
+        return [ActiveRecordFake.new]
+      else
+        raise ActiveRecord::RecordNotFound
+      end
+    end
+  end
+
+  include Asari::ActiveRecord
+
+  asari_index("test-domain", [:name, :email])
+
+  def id
+    1
+  end
+
+  def name
+    "Fritters"
+  end
+
+  def email
+    "fritters@aredelicious.com"
+  end
+end
+
+class ActiveRecordFakeWithErrorOverride < ActiveRecordFake
+  include Asari::ActiveRecord
+
+  asari_index("test-domain", [:name, :email])
+
+  def self.asari_on_error(exception)
+    false
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: asari
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+  prerelease: 
+platform: ruby
+authors:
+- Tommy Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-07-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: &70106563512800 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70106563512800
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70106563528480 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70106563528480
+description: Asari s a Ruby interface for AWS CloudSearch
+email:
+- tommy@wellbredgrapefruit.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- asari.gemspec
+- lib/asari.rb
+- lib/asari/active_record.rb
+- lib/asari/exceptions.rb
+- lib/asari/version.rb
+- spec/active_record_spec.rb
+- spec/asari_spec.rb
+- spec/documents_spec.rb
+- spec/search_spec.rb
+- spec_helper.rb
+homepage: http://github.com/duwanis/asari
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: asari
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Asari is a Ruby interface for AWS CloudSearch.
+test_files:
+- spec/active_record_spec.rb
+- spec/asari_spec.rb
+- spec/documents_spec.rb
+- spec/search_spec.rb
+has_rdoc: