stupa 0.1.0

data/.document

@@ -0,0 +1,2 @@
+README.markdown
+LICENSE

data/.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+
+*~
+\#*
+.\#*
+
+coverage
+rdoc
+pkg
+*.gem
+.yardopts
+.yardoc
+.bundle
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,7 @@
+source :rubygems
+
+gemspec
+
+group :test do
+  gem 'shoulda-context'
+end

data/LICENSE

@@ -0,0 +1,19 @@
+
+The Stupa Ruby client library is covered by the following license :
+
+/*
+ * Copyright (c) 2011
+ * Frank Denis <j at pureftpd dot org>
+ *
+ * Permission to use, copy, modify, and distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */

data/README.markdown

@@ -0,0 +1,54 @@
+Stupa client library for Ruby
+=============================
+
+A Ruby client for [Stupa](http://code.google.com/p/stupa/).
+
+"Stupa is an associative search engine.
+You can search related documents with high performance and high precision.
+Since document data and inverted indexes are kept in memory,
+Stupa reflects updates of documents in search results in real time."
+
+The current SVN code of Stupa contains a fast HTTP API built on libevent.
+This is what this library connects to.
+
+Usage
+=====
+
+    require 'stupa'
+
+    client = Stupa::Client.new(host: "localhost", port: 22122)
+
+    # delete all entries
+    client.clear
+
+    # get the number of entries in the database
+    size = client.size
+
+    # record a couple key/features tuples
+    client.add('key1' => 'feat1')
+    client.add('key2' => 'feat2', 'key3' => 'feat3')
+    client.add('key4' => ['feat4', 'feat5', 'feat6'])
+
+    # delete keys
+    client.delete('key3')
+    client.delete(['key1', 'key2'])
+
+    # dump the database
+    client.save('/var/db/stupa.db')
+
+    # load from a dump
+    client.load('/var/db/stupa.db')
+
+    # look for entries similar to key1
+    results = client.dsearch(query: 'key1')
+    results = client.dsearch(query: 'key1', max: 50)
+
+    # look for keys with matching features
+    results = client.fsearch(query: 'feat1')
+    results = client.fsearch(query: ['feat2', 'feat3'])
+    results = client.fsearch(query: ['feat2', 'feat3'], max: 50)
+
+Copyright
+=========
+
+See LICENSE for details.

data/Rakefile

@@ -0,0 +1,14 @@
+require 'rake'
+require 'shoulda/tasks'
+require 'rake/testtask'
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+task :default => :test
+
+Rake::TestTask.new(:test) do |test|
+  test.ruby_opts = ["-rubygems"] if defined?(Gem)
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+end

data/lib/stupa.rb

@@ -0,0 +1,12 @@
+
+module Stupa
+  def self.configure
+    yield self
+    true
+  end  
+end
+
+require 'stupa/errors'  
+require 'stupa/client'
+
+    

data/lib/stupa/client.rb

@@ -0,0 +1,111 @@
+
+require 'faraday'
+require 'stupa/tsv'
+
+module Stupa
+  class Client
+    SEARCH_DEFAULT_MAX_RESULTS = 20
+    DEFAULT_HOST = 'localhost'
+    DEFAULT_PORT = 22122
+    
+    attr_accessor :host, :port, :adapter
+    
+    def base_url
+      "http://#{@host}:#{@port}"
+    end
+    
+    def initialize(params = { })
+      @host = params[:host] || DEFAULT_HOST
+      @port = params[:port] || DEFAULT_PORT
+      @adapter = params[:adapter] || :net_http      
+    end
+    
+    def close; end
+      
+    def load(file)
+      resp = _conn.post '/load' do |req|
+        req.body = { file: file }
+      end
+      _raise_errors(resp)
+    end
+
+    def save(file)
+      resp = _conn.post '/save' do |req|
+        req.body = { file: file }
+      end
+      _raise_errors(resp)
+    end
+
+    def clear
+      resp = _conn.post '/clear'
+      _raise_errors(resp)
+    end
+    
+    def size
+      resp = _conn.get '/size'
+      _raise_errors(resp)
+      resp.body.to_i
+    end
+    
+    def add(params)
+      conn = _conn
+      params.each_pair do |_key, features|
+        key = _key.to_s
+        features = [ features ] unless features.kind_of?(Array)
+        features = features.collect { |feature| feature.to_s }
+        resp = conn.post '/add' do |req|
+          req.body = { id: _key, feature: TSV.join(features) }
+        end
+        _raise_errors(resp)        
+      end
+    end
+    
+    def delete(params)      
+      params = [ params ] unless params.respond_to?('each')
+      conn = _conn
+      params.each do |_key|
+        key = _key.to_s
+        resp = conn.post '/delete' do |req|
+          req.body = { id: key }
+        end
+        _raise_errors(resp)
+      end
+    end
+    
+    def fsearch(params)
+      _search('/fsearch', params)
+    end
+    
+    def dsearch(params)
+      _search('/dsearch', params)
+    end        
+    
+    private
+    
+    def _conn(&block)
+      Faraday.new(url: base_url) do |builder|
+        builder.adapter @adapter
+        yield builder if block
+      end
+    end
+    
+    def _raise_errors(resp)
+      status = resp.status
+      raise StupaServerError, "(#{status})" if status >= 500
+      raise StupaClientError, "(#{status})" if status >= 400
+    end
+    
+    def _search(url_part, params)
+      max = params[:max] || SEARCH_DEFAULT_MAX_RESULTS
+      query = params[:query]
+      query = [ query ] unless query.kind_of?(Array)
+      query = query.collect { |part| part.to_s }
+      
+      resp = _conn.post url_part do |req|
+        req.body = { query: TSV.join(query), max: max }
+      end
+      _raise_errors(resp)
+      TSV.parse_rows_key_and_score(resp.body)      
+    end
+  end
+end

data/lib/stupa/errors.rb

@@ -0,0 +1,14 @@
+
+module Stupa
+  class StupaError < StandardError
+    attr_reader :data
+    
+    def initialize(data)
+      @data = data
+      super
+    end
+  end
+  
+  class StupaServerError < StupaError; end
+  class StupaClientError < StupaError; end
+end

data/lib/stupa/tsv.rb

@@ -0,0 +1,42 @@
+
+module TSV
+  class << self
+    def parse_rows(str)
+      str.split("\n").collect { |row| row.split("\t") }
+    end
+    
+    def parse_rows_key_and_score(str)
+      rows = parse_rows(str)
+      h = rows.collect do |row|
+        [ row.first, row.last.to_f ]
+      end
+      Hash[*h.flatten]
+    end
+    
+    def parse_rows_key_and_values(str)
+      rows = parse_rows(str)    
+      h = rows.collect do |row|
+        [ row.first, row[1..-1] ]
+      end
+      Hash[*h.flatten(1)]
+    end
+    
+    def join(values)
+      raise TSVError, values unless joinable?(values) && ! values.empty?
+      if values.respond_to?('join')
+        values.join("\t")
+      else
+        values
+      end
+    end
+    
+    def joinable?(values)
+      values = [ values ] unless values.kind_of?(Array)
+      ! values.detect do |value|
+        value.include?("\t") || value.include?("\n")
+      end
+    end
+  end
+  
+  class TSVError < StandardError; end
+end

data/lib/stupa/version.rb

@@ -0,0 +1,10 @@
+
+module Stupa
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+    
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/stupa.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/stupa/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name = %q{stupa}
+  s.version  = Stupa::VERSION::STRING
+  s.platform = Gem::Platform::RUBY
+
+  s.authors = ['Frank Denis']
+  s.email   = ['j at pureftpd dot org']
+
+  s.homepage    = %q{http://github.com/jedisct1/stupa-rb}
+  s.summary     = %q{Ruby client library for Stupa}
+  s.description = %q{Ruby client library for Stupa}
+
+  s.extra_rdoc_files = ['README.markdown']
+
+  s.add_runtime_dependency 'faraday', '~> 0.5.3'
+  
+  s.add_development_dependency 'bundler', '~> 1.0'
+  s.add_development_dependency 'rake', '~> 0.8'
+  s.add_development_dependency 'shoulda', '~> 2.11'
+  s.add_development_dependency 'test-unit', '~> 2.1'
+  
+  s.required_rubygems_version = Gem::Requirement.new('>= 1.3.6') \
+      if s.respond_to? :required_rubygems_version=
+    
+  s.platform = Gem::Platform::RUBY
+  s.require_paths = ['lib']      
+    
+  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) }
+end

data/test/client_test.rb

@@ -0,0 +1,51 @@
+
+require 'helper'
+
+class ClientTest < Test::Unit::TestCase
+  context "a Stupa client" do
+    setup do
+      @client = Stupa::Client.new
+      @client.clear
+    end
+    
+    should "build base_url" do
+      assert_equal(@client.base_url, 'http://localhost:22122')
+    end
+    
+    should "empty the initial database" do
+      assert_equal(@client.size, 0)
+    end
+    
+    should "add a single item" do
+      @client.add('key1' => 'feat1')
+      assert_equal(@client.size, 1)
+    end
+    
+    should "add a couple more items" do
+      @client.add('key2' => 'feat2', 'key3' => 'feat3')
+      assert_equal(@client.size, 2)      
+    end
+    
+    should "add multiple features to a single item" do
+      @client.add('key4' => ['feat4', 'feat5'])
+      assert_equal(@client.size, 1)
+    end    
+
+    should "add multiple features to a multiple item" do
+      @client.add('key5' => ['feat6', 'feat7'], 'key6' => ['feat8', 'feat9'])
+      assert_equal(@client.size, 2)
+    end
+
+    should "add two items and delete one" do
+      @client.add('key5' => ['feat6', 'feat7'], 'key6' => ['feat8', 'feat9'])
+      @client.delete('key5')
+      assert_equal(@client.size, 1)
+    end  
+
+    should "add two items and delete two" do
+      @client.add('key5' => ['feat6', 'feat7'], 'key6' => ['feat8', 'feat9'])
+      @client.delete(['key5', 'key6'])
+      assert_equal(@client.size, 0)
+    end  
+  end
+end

data/test/helper.rb

@@ -0,0 +1,11 @@
+
+require 'test/unit'
+require 'shoulda'
+
+begin require 'redgreen'; rescue LoadError; end
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'stupa'
+

data/test/persistence_test.rb

@@ -0,0 +1,23 @@
+
+require 'helper'
+require 'tempfile'
+
+class PersistenceTest < Test::Unit::TestCase
+  context "a Stupa client with some data on the server" do
+    setup do
+      @client = Stupa::Client.new
+      @client.clear
+      @client.add('key1' => ['feature1', 'feature2', 'feature3'],
+                  'key2' => ['feature2', 'feature3', 'feature4'])
+    end
+    
+    should "backup and reload the database" do
+      tmpfile = Tempfile.new('stupa-test')
+      @client.save(tmpfile)
+      @client.clear
+      assert_equal(@client.size, 0)
+      @client.load(tmpfile)
+      assert_equal(@client.size, 2)      
+    end
+  end
+end

data/test/search_test.rb

@@ -0,0 +1,59 @@
+
+require 'helper'
+
+class SearchTest < Test::Unit::TestCase
+  context "a Stupa client with some data on the server" do
+    setup do
+      @client = Stupa::Client.new
+      @client.clear
+      @client.add('key1' => ['feature1', 'feature2', 'feature3'],
+                  'key2' => ['feature2', 'feature3', 'feature4'])
+    end
+    
+    should "look for similar documents" do
+      result = @client.dsearch(query: 'key1')
+      assert_not_nil(result)
+      assert_nil(result[:key1])
+      assert_not_nil(result['key1'])
+      assert_equal(result['key1'], 1.0)
+      assert_not_nil(result['key2'])
+      assert(result['key2'] < 1.0)
+      assert(result['key2'] > 0.0)
+    end
+    
+    should "lookup a nonexistent document" do
+      result = @client.dsearch(query: 'nonexistent_key')
+      assert_not_nil(result)
+      assert(result.empty?)
+    end
+    
+    should "search for a feature" do
+      result = @client.fsearch(query: 'feature1')
+      assert_not_nil(result['key1'])
+      assert(result['key1'] < 1.0)
+      assert(result['key1'] > 0.0)
+      assert_nil(result['key2'])
+    end
+
+    should "search for features" do
+      result = @client.fsearch(query: ['feature3', 'feature4'])
+      assert_not_nil(result['key1'])
+      assert(result['key1'] < 1.0)
+      assert(result['key1'] > 0.0)      
+      assert_not_nil(result['key2'])
+      assert(result['key2'] < 1.0)
+      assert(result['key2'] > 0.0)
+    end
+    
+    should "search for nonexistent features" do
+      result = @client.fsearch(query: 'nonexistent_feature')
+      assert_not_nil(result)
+      assert(result.empty?)      
+    end
+    
+    should "check for partial results" do
+      result = @client.fsearch(query: 'feature3', max: 1)
+      assert(result.size == 1)
+    end
+  end
+end

metadata

@@ -0,0 +1,155 @@
+--- !ruby/object:Gem::Specification 
+name: stupa
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Frank Denis
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-06 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: faraday
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 5
+        - 3
+        version: 0.5.3
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        version: "1.0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 8
+        version: "0.8"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 11
+        version: "2.11"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: test-unit
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 1
+        version: "2.1"
+  type: :development
+  version_requirements: *id005
+description: Ruby client library for Stupa
+email: 
+- j at pureftpd dot org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.markdown
+files: 
+- .document
+- .gitignore
+- Gemfile
+- LICENSE
+- README.markdown
+- Rakefile
+- lib/stupa.rb
+- lib/stupa/client.rb
+- lib/stupa/errors.rb
+- lib/stupa/tsv.rb
+- lib/stupa/version.rb
+- stupa.gemspec
+- test/client_test.rb
+- test/helper.rb
+- test/persistence_test.rb
+- test/search_test.rb
+has_rdoc: true
+homepage: http://github.com/jedisct1/stupa-rb
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Ruby client library for Stupa
+test_files: 
+- test/client_test.rb
+- test/helper.rb
+- test/persistence_test.rb
+- test/search_test.rb