asari 0.5.4 → 0.6.0

data/README.md

@@ -1,4 +1,118 @@
-asari
-=====
+# Asari
 
-a Ruby wrapper for AWS CloudSearch.
+## Description
+
+Asari is a Ruby wrapper for AWS CloudSearch, with optional ActiveRecord support
+for easy integration with your Rails apps.
+
+#### Why Asari?
+
+"Asari" is Japanese for "rummaging search." Seemed appropriate.
+
+## Usage
+
+#### Basic Usage
+
+    asari = Asari.new("my-search-domain-asdfkljwe4") # CloudSearch search domain
+    asari.add_item("1", { :name => "Tommy Morgan", :email => "tommy@wellbredgrapefruit.com"})
+    asari.search("tommy") #=> ["1"] - a list of document IDs
+    
+#### Pagination
+
+Asari defaults to a page size of 10 (because that's CloudSearch's default), but
+it allows you to specify pagination parameters with any search:
+
+    asari.search("tommy", :page_size => 30, :page => 10)
+
+The results you get back from Asari#search aren't actually Array objects,
+either: they're Asari::Collection objects, which are (currently) API-compatible
+with will\_paginate:
+  
+    results = asari.search("tommy", :page_size => 30, :page => 10)
+    results.total_entries #=> 5000
+    results.total_pages   #=> 167
+    results.current_page  #=> 10
+    results.offset        #=> 300
+    results.page_size     #=> 30
+
+#### ActiveRecord
+
+If you require 'asari/active\_record' in your project, you have access to the
+ActiveRecord module for Asari. You can take advantage of that module like so:
+
+    class User < ActiveRecord::Base
+      include Asari::ActiveRecord
+
+      #... other stuff...
+
+      asari_index("search-domain-for-users", [:name, :email, :twitter_handle, :favorite_sweater])
+    end
+
+This will automatically set up before\_destroy, after\_create, and after\_update
+hooks for your AR model to keep the data in sync with your CloudSearch index -
+the second argument to asari\_index is the list of fields to maintain in the
+index, and can represent any function on your AR object. You can then interact
+with your AR objects as follows:
+
+    # Klass.asari_find returns a list of model objects in an
+    # Asari::Collection... 
+    User.asari_find("tommy") #=> [<User:...>, <User:...>, <User:...>]
+    
+    # or with a specific instance, if you need to manually do some index
+    # management...
+    @user.asari_add_to_index
+    @user.asari_update_in_index
+    @user.asari_remove_from_index
+
+Because index updates are done as part of the AR lifecycle by default, you also
+might want to have control over how Asari handles index update errors - it's
+kind of problematic, if, say, users can't sign up on your site because
+CloudSearch isn't available at the moment. By default Asari just raises these
+exceptions when they occur, but you can define a special handler if you want
+using the asari\_on\_error method:
+
+    class User < ActiveRecord::Base
+      include Asari::ActiveRecord
+
+      asari_index(... )
+
+      def self.asari_on_error(exception)
+        Airbrake.notify(...)
+        true
+      end
+    end
+
+In the above example we decide that, instead of raising exceptions every time,
+we're going to log exception data to Airbrake so that we can review it later and
+then return true so that the AR lifecycle continues normally.
+
+## Get it
+
+It's a gem named asari. Install it and make it available however you prefer.
+
+Asari is developed on ruby 1.9.3, and the ActiveRecord portion has been tested
+with Rails 3.2. I don't know off-hand of any reasons that it shouldn't work in
+other environments, but be aware that it hasn't (yet) been tested.
+
+## Contributions
+
+If Asari interests you and you think you might want to contribute, hit me up on
+Github. You can also just fork it and make some changes, but there's a better
+chance that your work won't be duplicated or rendered obsolete if you check in
+on the current development status first.
+
+Gem requirements/etc. should be handled by Bundler.
+
+## License
+Copyright (C) 2012 by Tommy Morgan
+
+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.

data/lib/asari.rb

@@ -5,6 +5,7 @@ require "asari/exceptions"
 
 require "httparty"
 
+require "ostruct"
 require "json"
 require "cgi"
 
@@ -45,14 +46,14 @@ class Asari
   #
   #     @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
+  # Returns: An Asari::Collection containing all document IDs in the system that match the
+  #   specified search term. If no results are found, an empty Asari::Collection is
   #   returned.
   #
   # Raises: SearchException if there's an issue communicating the request to
   #   the server.
   def search(term, options = {})
-    return [] if self.class.mode == :sandbox
+    return Asari::Collection.sandbox_fake if self.class.mode == :sandbox
 
     page_size = options[:page_size].nil? ? 10 : options[:page_size].to_i
 

data/lib/asari/collection.rb

@@ -1,10 +1,25 @@
 class Asari
+  # Public: The Asari::Collection object represents a page of data returned from
+  # CloudSearch. It very closely delegates to an array containing the intended
+  # results, but provides a few extra methods containing metadata about the
+  # current pagination state: current_page, page_size, total_entries, offset, and
+  # total_pages.
+  #
+  # Asari::Collection is compatible with will_paginate collections, and the two
+  # can be used interchangeably for the purposes of pagination.
+  #
   class Collection < BasicObject
     attr_reader :current_page
     attr_reader :page_size
     attr_reader :total_entries
     attr_reader :total_pages
 
+    # Internal: method for returning a sandbox-friendly empty search result.
+    #
+    def self.sandbox_fake
+      Collection.new(::OpenStruct.new(:parsed_response => {"hits" => { "found" => 0, "start" => 0, "hit" => []}}), 10)
+    end
+
     # Internal: This object should really only ever be instantiated from within
     # Asari code. The Asari Collection knows how to build itself from an
     # HTTParty::Response object representing a search query result from
@@ -18,7 +33,11 @@ class Asari
       resp = httparty_response.parsed_response
       @total_entries = resp["hits"]["found"]
       @page_size = page_size
-      @total_pages = (@total_entries / @page_size) + 1
+
+      complete_pages = (@total_entries / @page_size)
+      @total_pages = (@total_entries % @page_size > 0) ? complete_pages + 1 : complete_pages
+      # There's always one page, even for no results
+      @total_pages = 1 if @total_pages == 0
 
       start = resp["hits"]["start"]
       @current_page = (start / page_size) + 1
@@ -30,12 +49,26 @@ class Asari
       (@current_page - 1) * @page_size
     end
 
+    # Public: replace the current data collection with a new data collection,
+    # without losing pagination information. Useful for mapping results, etc.
+    #
+    # Examples:
+    #
+    #   results = @asari.find("test") #=> ["1", "3", "10", "28"]
+    #   results.replace(results.map { |id| User.find(id)}) #=> [<User...>,<User...>,<User...>]
+    #
+    # Returns: self. #replace is a chainable method.
+    #
     def replace(array)
       @data = array
 
       self
     end
 
+    def class
+      Asari::Collection
+    end
+
     def method_missing(method, *args, &block)
       @data.send(method, *args, &block)
     end

data/lib/asari/version.rb

@@ -1,3 +1,3 @@
 class Asari
-  VERSION = "0.5.4"
+  VERSION = "0.6.0"
 end

data/spec/active_record_spec.rb

@@ -36,13 +36,13 @@ describe Asari do
       end
 
       it "will allow you to search for items with the index" do
-        @asari.should_receive(:search).with("fritters").and_return(["1"])
+        @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"])
+        @asari.should_receive(:search).with("fritters", {}).and_return(["1"])
 
         results = ActiveRecordFake.asari_find("fritters")
         expect(results.class).to eq(Array)
@@ -50,7 +50,7 @@ describe Asari do
       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([])
+        @asari.should_receive(:search).with("veggie burgers", {}).and_return([])
 
         results = ActiveRecordFake.asari_find("veggie burgers")
         expect(results.class).to eq(Array)

data/spec/collection_spec.rb

@@ -0,0 +1,30 @@
+require_relative '../spec_helper'
+
+describe Asari do
+  describe Asari::Collection do
+    before :each do  
+      response = OpenStruct.new(:parsed_response => { "hits" => { "found" => 10, "start" => 0, "hit" => ["1","2"]}})
+      @collection = Asari::Collection.new(response, 2)
+    end
+
+    it "calculates the page_size correctly" do
+      expect(@collection.page_size).to eq(2)
+    end
+
+    it "calculates the total_entries correctly" do
+      expect(@collection.total_entries).to eq(10)
+    end
+
+    it "calculates the total_pages correctly" do
+      expect(@collection.total_pages).to eq(5)
+    end
+
+    it "calculates the current_page correctly" do
+      expect(@collection.current_page).to eq(1)
+    end
+
+    it "calculates the offset correctly" do
+      expect(@collection.offset).to eq(0)
+    end
+  end
+end

data/spec/search_spec.rb

@@ -9,12 +9,12 @@ describe Asari do
     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")
+      HTTParty.should_receive(:get).with("http://search-testdomain.us-east-1.cloudsearch.amazonaws.com/2011-02-01/search?q=testsearch&size=10")
       @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")
+      HTTParty.should_receive(:get).with("http://search-testdomain.us-east-1.cloudsearch.amazonaws.com/2011-02-01/search?q=testsearch%21&size=10")
       @asari.search("testsearch!")
     end
 
@@ -24,17 +24,29 @@ describe Asari do
     end
 
     it "honors the page option" do
-      HTTParty.should_receive(:get).with("http://search-testdomain.us-east-1.cloudsearch.amazonaws.com/2011-02-01/search?q=testsearch&size=20&start=41")
+      HTTParty.should_receive(:get).with("http://search-testdomain.us-east-1.cloudsearch.amazonaws.com/2011-02-01/search?q=testsearch&size=20&start=40")
       @asari.search("testsearch", :page_size => 20, :page => 3)
     end
 
     it "returns a list of document IDs for search results." do
-      expect(@asari.search("testsearch")).to eq(["123","456"])
+      result = @asari.search("testsearch")
+
+      expect(result.size).to eq(2)
+      expect(result[0]).to eq("123")
+      expect(result[1]).to eq("456")
+      expect(result.total_pages).to eq(1)
+      expect(result.current_page).to eq(1)
+      expect(result.page_size).to eq(10)
+      expect(result.total_entries).to eq(2)
     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([])
+      result = @asari.search("testsearch")
+      expect(result.size).to eq(0)
+      expect(result.total_pages).to eq(1)
+      expect(result.current_page).to eq(1)
+      expect(result.total_entries).to eq(0)
     end
 
     it "raises an exception if the service errors out." do

data/spec_helper.rb

@@ -8,12 +8,15 @@ Asari.mode = :production
 RSpec.configuration.expect_with(:rspec) { |c| c.syntax = :expect }
 
 def fake_response
-  OpenStruct.new(:parsed_response => { "hits" => {"hit" => [{"id" => "123"}, {"id" => "456"}]}},
+  OpenStruct.new(:parsed_response => { "hits" => {
+                      "found" => 2,
+                      "start" => 0,
+                      "hit" => [{"id" => "123"}, {"id" => "456"}]}},
                  :response => OpenStruct.new(:code => "200"))
 end
 
 def fake_empty_response
-  OpenStruct.new(:parsed_response => { "hits" => {"hit" => []}},
+  OpenStruct.new(:parsed_response => { "hits" => { "found" => 0, "start" => 0, "hit" => []}},
                  :response => OpenStruct.new(:code => "200"))
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asari
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.6.0
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
-  requirement: &70352597799280 !ruby/object:Gem::Requirement
+  requirement: &70109076129460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70352597799280
+  version_requirements: *70109076129460
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70352597819640 !ruby/object:Gem::Requirement
+  requirement: &70109076128860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70352597819640
+  version_requirements: *70109076128860
 description: Asari s a Ruby interface for AWS CloudSearch
 email:
 - tommy@wellbredgrapefruit.com
@@ -52,6 +52,7 @@ files:
 - lib/asari/version.rb
 - spec/active_record_spec.rb
 - spec/asari_spec.rb
+- spec/collection_spec.rb
 - spec/documents_spec.rb
 - spec/search_spec.rb
 - spec_helper.rb
@@ -82,6 +83,7 @@ summary: Asari is a Ruby interface for AWS CloudSearch.
 test_files:
 - spec/active_record_spec.rb
 - spec/asari_spec.rb
+- spec/collection_spec.rb
 - spec/documents_spec.rb
 - spec/search_spec.rb
 has_rdoc: