suggester 0.1.0

data/Gemfile

@@ -0,0 +1,18 @@
+source :rubygems
+gem "sinatra"
+gem "json"
+gem "vegas"
+
+group :development do
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.1"
+  gem "rcov", ">= 0"
+end
+
+group :test do
+  gem "shoulda", ">= 0"
+  gem "mocha", ">= 0"
+  gem "activerecord", "=2.3.9"
+  gem "rack-test"
+  gem "mysql"
+end

data/Gemfile.lock

@@ -0,0 +1,43 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activerecord (2.3.9)
+      activesupport (= 2.3.9)
+    activesupport (2.3.9)
+    git (1.2.5)
+    jeweler (1.5.1)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    json (1.4.6)
+    mocha (0.9.8)
+      rake
+    mysql (2.8.1)
+    rack (1.2.1)
+    rack-test (0.5.6)
+      rack (>= 1.0)
+    rake (0.8.7)
+    rcov (0.9.9)
+    shoulda (2.11.3)
+    sinatra (1.1.0)
+      rack (~> 1.1)
+      tilt (~> 1.1)
+    tilt (1.1)
+    vegas (0.1.8)
+      rack (>= 1.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (= 2.3.9)
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.1)
+  json
+  mocha
+  mysql
+  rack-test
+  rcov
+  shoulda
+  sinatra
+  vegas

data/README.md

@@ -0,0 +1,127 @@
+Suggester
+=========
+
+Suggester is an extensible, cache-based auto-suggest server and client for ruby. 
+Suggester also supports replication and scheduled refreshing.
+
+To use, you provide a configuration ruby file which registers "handlers".  Handlers
+can be any Ruby object that responds to `find`, `match`, and `refresh`.  We've included
+3 basic handlers which are easily extensible:
+
+1. Suggester::Handlers::ActiveRecord - pulls all records using an ActiveRecord class
+2. Suggester::Handlers::Marshal - deserializes a Marshaled blob from a file or url
+3. Suggester::Handlers::Yaml - deserializes YAML from a file or url 
+
+All 3 of these supplied handlers stores in a sorted array of data.  We do a binary 
+search to find results.
+
+Documentation & Requirements
+----------------------------
+
+Suggester requires the following gems:
+
+* Sinatra
+* Vegas
+* JSON
+
+Server
+------
+
+### Examples
+
+Basic usage:
+
+    suggest_server <config_file.rb>
+
+Config file example (config_file.rb):
+
+    # assuming that Book is an ActiveRecord class
+    Suggester::Server.add_handler("books", Suggester::Handlers::ActiveRecord.new(:class => Book))
+
+    # using the Marshal handler
+    Suggester::Server.add_handler("cars", Suggester::Handlers::Marshal(:file => "/path/to/file.marshal")
+
+    # using the Yaml handler
+    Suggester::Server.add_handler("dogs", Suggester::Handlers::Yaml(:file => "/path/to/file.yml")
+
+### Web Interface
+
+### Creating Custom Handlers
+
+All Handler classes must respond to 2 public instance methods:
+
+    1. find(name, options = {})
+    2. match(name, options = {})
+
+These methods should return an array of data that matches the supplied name (search term).
+
+### Refreshing Handlers
+
+Upon server start, we spawn a thread that refreshes handler caches.  We do this to prevent blocking
+the webserver which a cache reloads.  Since suggester server should never modify its data source,
+we shouldn't have to worry much about concurrency.  Note that results returned may represent an older
+state of the cache, but never an in-between cache state.
+
+There are 2 ways to refresh a handler.
+
+The first way is to make a GET request to `/<handler_name>/refresh`.  This call forces the server
+to reload the specified cache as soon as possible.
+
+The second way is to schedule recurring refreshes.  When using any handler that inherits from
+Suggester::Handlers::Base, you may supply a `:refresh_interval` option (in minutes).  The
+server will automatically refresh that cache every `:refresh_interval` minutes.
+
+### Replication
+
+An easy way to set up replication is through configuration and the Marshal or Yaml handlers are
+best for the job.  Because the Marshal and Yaml handlers can load from a local file or a url,
+you can point the replicant handler to a master server's dump output.
+
+Example Master Configuration:
+
+    Suggester::Server.add_handler("books", Suggester::Handler::ActiveRecord.new(:class => Book))
+    Suggester::Server.add_handler("authors", Suggester::Handler::ActiveRecord.new(:class => Book, :name_field => :author))
+
+Replicant Configuration:
+
+    Suggester::Server.add_handler("books", Suggester::Handler::Marshal(:file => "http://<master:port>/books/dump.marshal"))
+    Suggester::Server.add_handler("authors", Suggester::Handler::Yaml(:file => "http://<master:port>/books/dump.yml"))
+
+Note that this method of replication uses the pull model -- the replicant must determine when to 
+pull from the master.
+
+Client
+------
+
+### Examples
+
+Basic usage:
+
+    require 'rubygems'
+    require 'suggester'
+    require 'suggester/client'
+
+    # create an instance of the client pointing to a server at localhost:5050
+    client = Suggester::Client.new(:host => 'localhost', :port => 5050)
+
+    # find begins-with matches
+    client.find("books", "A Tale of Two")
+    => [{:id => 1, :display_name => "A Tale of Two Cities"}]
+    client.find("books", "The ")
+    => [{:id => 4, :display_name => "The Origin of Species"},
+        {:id => 5, :display_name => "The Catcher in the Rye"},
+        {:id => 6, :display_name => "The Lord of the Rings"}]
+    client.find("books", "Non-existent")
+    => []
+
+    # find exact matches
+    client.match("books", "a tale of two cities")
+    => [{:id => 1, :display_name => "A Tale of Two Cities"}]
+    client.match("books", "A Tale of Two")
+    => []
+    client.match("books", "The")
+    => []
+
+    # tell the server to refresh its handler
+    client.refresh("books")
+    => true

data/Rakefile

@@ -0,0 +1,70 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "suggester"
+  gem.homepage = "http://github.com/chingor13/suggester"
+  gem.license = "MIT"
+  gem.summary = %Q{Extensible, cache-based auto-suggest server for ruby.}
+  gem.description = %Q{Extensible, cache-based auto-suggest server for ruby. Includes refresh and replication support out of the box.}
+  gem.email = "ching.jeff@gmail.com"
+  gem.authors = ["Jeff Ching"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "suggester #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+namespace :db do 
+  desc 'setup test activerecord databases'
+  task :prepare do
+    load File.join(File.dirname(__FILE__), 'test', 'test_helper.rb')
+    if RUN_AR_TESTS
+      fixture_sql = File.join(File.dirname(__FILE__), 'test', 'fixtures', 'books.sql')
+      statements = open(fixture_sql).read.split(";")
+      statements.compact!
+      statements.each do |sql|
+        sql.strip!
+        ActiveRecord::Base.connection.execute(sql) unless sql.nil? || sql.empty?
+      end
+    end
+  end
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/bin/suggester_server

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+begin
+  require 'vegas'
+rescue LoadError
+  require 'rubygems'
+  require 'vegas'
+end
+require 'suggester'
+require 'suggester/server'
+
+Vegas::Runner.new(Suggester::Server, 'suggester_server', {
+  :before_run => lambda {|v|
+    path = (ENV['Suggester_CONFIG'] || v.args.first)
+    load path.to_s.strip if path
+  }
+})

data/config/database.yml.example

@@ -0,0 +1,6 @@
+test:
+  adapter: <adapter (mysql)>
+  username: <your username>
+  password: <your password>
+  host: <server host>
+  database: suggester_test

data/lib/array_bsearch.rb

@@ -0,0 +1,82 @@
+class Array
+  # 
+  # The binary search algorithm is extracted from Jon Bentley's
+  # Programming Pearls 2nd ed. p.93
+  #
+
+  #
+  # Return the lower boundary. (inside)
+  #
+  def bsearch_lower_boundary (range = 0 ... self.length, &block)
+    lower  = range.first() -1
+    upper = if range.exclude_end? then range.last else range.last + 1 end
+    while lower + 1 != upper
+      mid = ((lower + upper) / 2).to_i # for working with mathn.rb (Rational)
+      if yield(self[mid]) < 0
+	      lower = mid
+      else 
+      	upper = mid
+      end
+    end
+    return upper
+  end
+
+  #
+  # This method searches the FIRST occurrence which satisfies a
+  # condition given by a block in binary fashion and return the 
+  # index of the first occurrence. Return nil if not found.
+  #
+  def bsearch_first (range = 0 ... self.length, &block)
+    boundary = bsearch_lower_boundary(range, &block)
+    if boundary >= self.length || yield(self[boundary]) != 0
+      return nil
+    else 
+      return boundary
+    end
+  end
+
+  alias bsearch bsearch_first
+
+  #
+  # Return the upper boundary. (outside)
+  #
+  def bsearch_upper_boundary (range = 0 ... self.length, &block)
+    lower  = range.first() -1
+    upper = if range.exclude_end? then range.last else range.last + 1 end
+    while lower + 1 != upper
+      mid = ((lower + upper) / 2).to_i # for working with mathn.rb (Rational)
+      if yield(self[mid]) <= 0
+        lower = mid
+      else
+        upper = mid
+      end
+    end
+    return lower + 1 # outside of the matching range.
+  end
+
+  #
+  # This method searches the LAST occurrence which satisfies a
+  # condition given by a block in binary fashion and return the 
+  # index of the last occurrence. Return nil if not found.
+  #
+  def bsearch_last (range = 0 ... self.length, &block)
+    # `- 1' for canceling `lower + 1' in bsearch_upper_boundary.
+    boundary = bsearch_upper_boundary(range, &block) - 1
+
+    if (boundary <= -1 || yield(self[boundary]) != 0)
+      return nil
+    else
+      return boundary
+    end
+  end
+
+  #
+  # Return the search result as a Range object.
+  #
+  def bsearch_range (range = 0 ... self.length, &block)
+    lower = bsearch_lower_boundary(range, &block)
+    upper = bsearch_upper_boundary(range, &block)
+    return lower ... upper
+  end
+end
+

data/lib/suggester.rb

@@ -0,0 +1,3 @@
+# define the namespace
+module Suggester
+end

data/lib/suggester/client.rb

@@ -0,0 +1,109 @@
+# This is a simple client to access a Suggester::Server instance.
+#
+# Author::    Jeff Ching
+# Copyright:: Copyright (c) 2010
+# License::   Distributes under the same terms as Ruby
+require 'open-uri'
+require 'cgi'
+require 'json'
+require 'timeout'
+
+module Suggester
+  # Simple client to access a Suggester::Server instance
+  class Client
+    attr_accessor :host, :port
+    attr_accessor :logger
+
+    # server uses sinatra with default port 17500
+    DEFAULT_HOST = "localhost"
+    DEFAULT_PORT = 17500
+
+    # Create an instance of the client
+    def initialize(options = {})
+      @host = options[:host] || DEFAULT_HOST
+      @port = options[:port] || DEFAULT_PORT
+      @logger = options[:logger]
+    end
+
+    # Match returns an array of data returned that is an exact match for the query
+    # string provided
+    #
+    # ==== Parameters
+    #
+    # * <tt>type</tt> - The name of the handler like "book"
+    # * <tt>query</tt> - The search term you are matching on
+    # * <tt>options</tt> - Hash of optionally parameters which are passed as query
+    #   parameters.  Includes the <tt>:limit</tt> option.
+    #
+    # ==== Examples
+    #
+    #   # find exact matches
+    #   client = Suggester::Client.new
+    #   client.match("book", "A Tale of Two Cities")                # returns all books that match "A Tale of Two Cities"
+    #   client.match("book", "A Tale of Two Cities", :limit => 1)   # return the first match for "A Tale of Two Cities"
+    def match(type, query, options = {})
+      fetch_response(build_url(type, "match", query, options))
+    end
+
+    # Find returns an array of data returned for records that start with query
+    # string provided
+    #
+    # ==== Parameters
+    #
+    # * <tt>type</tt> - The name of the handler like "book"
+    # * <tt>query</tt> - The search term you are searching on
+    # * <tt>options</tt> - Hash of optionally parameters which are passed as query
+    #   parameters.  Includes the <tt>:limit</tt> option.
+    #
+    # ==== Examples
+    #
+    #   # find exact matches
+    #   client = Suggester::Client.new
+    #   client.match("book", "A Tale")                # returns all books that match "A Tale of Two Cities"
+    #   client.match("book", "A Tale", :limit => 1)   # return the first match for "A Tale of Two Cities"
+    def find(type, query, options = {})
+      fetch_response(build_url(type, "find", query, options))
+    end
+
+    # Refresh tells the server to force a reload of its cached data
+    #
+    # ==== Parameters
+    #
+    # * <tt>type</tt> - The name of the handler to refresh
+    def refresh(type)
+      url = "http://#{@host}:#{@port}/#{type}/refresh"
+      response = fetch_response(url)
+      return response.is_a?(String) && response == "OK"
+    end
+
+  private
+
+    def fetch_response(url) #:nodoc:
+      response = []
+      begin
+        Timeout::timeout(0.5) do
+          open(url) do |content|
+            response = JSON.parse(content.read)
+          end
+        end
+      rescue Timeout::Error => e
+        @logger.error("Timeout: #{e}\n#{url}") if @logger
+      rescue => e
+        @logger.error("Error: #{e}\nURL: #{url}\nStack Trace:\n#{e.backtrace}") if @logger
+      end
+      response
+    end
+
+    def build_url(type, method, query, options) #:nodoc:
+      url = "http://#{@host}:#{@port}/#{type}/#{method}/#{CGI::escape(query)}.json"
+      unless options.empty?
+        s = []
+        options.each do |k,v|
+          s << "#{CGI::escape(k.to_s)}=#{CGI::escape(v.to_s)}"
+        end
+        url = url + "?" + s.join("&")
+      end
+      url
+    end
+  end
+end