simple_solr 0.0.1 → 0.4.0

data/.gitignore

@@ -2,3 +2,5 @@
 .bundle
 Gemfile.lock
 pkg/*
+.rvmrc
+spec/db/database.yml

data/.rspec

@@ -0,0 +1 @@
+--color

data/CHANGELOG.rdoc

@@ -0,0 +1,3 @@
+== 0.4.0 (Aug 16, 2011)
+
+- First release as a gem, indexing works

data/Gemfile

@@ -1,4 +1,9 @@
 source "http://rubygems.org"
 
-# Specify your gem's dependencies in simple_solr.gemspec
 gemspec
+
+gem "activerecord"
+gem "rspec",            ">= 2"
+gem "sqlite3"
+gem "httparty"
+gem "builder"

data/README.rdoc

@@ -0,0 +1,103 @@
+Extremely lightweight adapter between Rails and Solr.
+
+SimpleSolr uses the REST interface that Solr offers and makes a great number
+of assumptions. This has resulted in a very fast, very lightweight library
+almost anyone can use straight away.
+
+* only a few dozen lines of code
+* extremely simple DSL
+* only depends on httparty
+* can handle all common use cases
+* has support for master/slave configurations
+* does not come with a bundled Solr
+* does not send a bunch of magic fields
+
+And my personal favorite:
+
+* <b>does nothing for unconfigured environments</b>
+
+If you have no +development+ section in the config file (see below) then
+nothing will happen at all. Your models will not be indexed, but you are
+freed from having to run a local Solr instance as well.
+
+Naturally there are downsides as well.
+
+* assumes an +id+ field present
+* makes Solr commit after every change
+* does not come with a bundled Solr
+* no rake tasks included
+
+This gem is not really suitable for use outside Rails, as it requires both
+ActiveRecord and ActiveSupport.
+
+I owe a great deal to @outoftime's Sunspot[https://github.com/outoftime/sunspot] library. If you need a fully-packed
+solution that handles every Solr case you might have, use that instead.
+
+
+== Installation
+
+Rails 2, in config/environment.rb:
+
+  config.gem 'simple_solr'
+  
+Rails 3, in Gemfile:
+
+  gem 'simple_solr'
+  
+
+== Configuration
+
+Create a file called <tt>config/simple_solr.yml</tt>.
+
+  production:
+    solr:
+      hostname: "slave.local"
+      port: 8000
+      path: "/solr"
+    master_solr:
+      hostname: "master.local"
+      port: 8000
+      path: "/solr"
+
+If you have just one Solr server, leave out the master_solr section.
+
+=== Your models
+
+Then in your models include the following:
+
+  class Document < ActiveRecord::Base
+    simple_solr do
+      field :title
+    end
+  end
+
+Only the fields listed in the +simple_solr+ block will be sent to Solr,
+with the addition of the +id+ field which is always included. The type of
+the field is not appended; the XML sent to Solr is as bare as possible.
+
+This also means no type casting is performed on dates/times. If you need
+anything like that, use a lambda to manipulate the field to your liking.
+
+Full example:
+
+  class FullDocument < ActiveRecord::Base
+    simple_solr do
+      field :id,            lambda { |record| "full-document-#{record.id}" }
+      field :title
+      field :date_creation, :created_at
+      field :shared,        false
+      field :published,     "Megacorp LLC"
+      field :body
+    end
+  end
+  
+As you can see you have a couple options with regards to the fields:
+
+1. Do nothing - in which case the corresponding attribute is used
+2. A symbol - uses the instance method with that name as the value
+3. Static value such as a string or boolean - which is used verbatim
+4. A lambda - for your every customization need.
+
+Use the latter form if you want to add a dynamic field to Solr. The model
+instance is passed as a parameter, so you can use every method inside
+the block, or run a calculation, or whatever.

data/Rakefile

@@ -1 +1,6 @@
 require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+task :default => :spec

data/lib/simple_solr/active_record.rb

@@ -0,0 +1,83 @@
+module SimpleSolr
+  module ActiveRecord
+    def self.included(base)
+      base.extend ClassMethods
+    end
+    
+    module ClassMethods
+      def simple_solr(&block)
+        class_eval do
+          # httparty
+          include HTTParty
+          
+          # callbacks
+          after_save :add_to_solr
+          after_destroy :delete_from_solr
+        end
+        
+        # Store the simple_solr fields for this class
+        cattr_accessor :simple_solr_fields
+        self.simple_solr_fields = { id: nil }
+        block.call
+        
+        include InstanceMethods
+      end
+      
+      # gets called by every +field+ line inside the simple_solr block.
+      # It stores the given values in +simple_solr_fields+, which we later use to build the XML.
+      def field(name, value=nil)
+        simple_solr_fields[name] = value
+      end
+    end
+    
+    module InstanceMethods
+      # callback which uses httparty to send a POST to solr.
+      def add_to_solr
+        if SimpleSolr.configuration.present?
+          self.class.post(SimpleSolr.configuration.master_uri + "/update?commit=true", :body => to_solr)
+        end
+      end
+      
+      def delete_from_solr
+        if SimpleSolr.configuration.present?
+          self.class.post(SimpleSolr.configuration.master_uri + "/update?commit=true", :body => to_solr_delete)
+        end
+      end
+      
+      private
+        def to_solr_delete
+          xml = Builder::XmlMarkup.new
+          
+          xml.delete do
+            xml.id id
+          end
+        end
+        
+        # Convert this instance's attributes to an XML suitable for Solr.
+        # The fields in the XML are determined from the simple_solr block.
+        def to_solr
+          xml = Builder::XmlMarkup.new
+          
+          xml.add do
+            xml.doc do
+              self.class.simple_solr_fields.each do |name, value|
+                if value.nil?
+                  # no value given, get it from the attribute
+                  xml.field self.send(name), :name => name
+                elsif value.is_a?(Symbol)
+                  # symbol given, use it to get the attribute
+                  xml.field self.send(value), :name => name
+                elsif value.is_a?(Proc)
+                  # Procs are used to fetch information from the instance
+                  xml.field value.call(self), :name => name
+                else
+                  # value given, use it directly.
+                  xml.field value, :name => name
+                end
+              end
+            end
+          end
+        end
+    end
+  end
+end

data/lib/simple_solr/configuration.rb

@@ -0,0 +1,88 @@
+module SimpleSolr
+  # SimpleSolr is configured via the config/simple_solr.yml file, which
+  # contains properties keyed by environment name.
+  #
+  #   production:
+  #     solr:
+  #       hostname: "solr.slave.local"
+  #       port: 8983
+  #       path: "/solr"
+  #     master_solr:
+  #       hostname: "solr.master.local"
+  #       port: 8983
+  #       path: "/solr"
+  #
+  # If the <code>master_solr</code> configuration is present, SimpleSolr will use
+  # the Solr instance specified there for all write operations, and the Solr
+  # configured under <code>solr</code> for all read operations.
+  class Configuration
+    # Define methods for the <code>solr</code> key. This key is normally used to
+    # configure SimpleSolr. 
+    %w(hostname port path).each do |method|
+      define_method method do
+        configuration('solr', method) || self.send("default_#{method}")
+      end
+    end
+
+    # Define methods for the <code>master_solr</code> key. When present, this key
+    # defines the Solr used for all write operations, while all read operations
+    # take place on the Solr defined in the <code>solr</code> key.
+    %w(hostname port path).each do |method|
+      define_method "master_#{method}" do
+        configuration('master_solr', method) || self.send(method)
+      end
+    end
+    
+    def present?
+      not user_configuration.nil?
+    end
+    
+    # Full URI to use for all read operations.
+    def uri
+      "#{hostname}:#{port}#{path}"
+    end
+    
+    # Full URI to use for all write operations.
+    # Automatically falls back to the <code>uri</code> when no master defined.
+    def master_uri
+      "#{master_hostname}:#{master_port}#{master_path}"
+    end
+    
+    private
+      def configuration(*keys)
+        keys.inject(user_configuration) do |hash, key|
+          hash[key] if hash
+        end
+      end
+      
+      def user_configuration
+        @user_configuration ||=
+          begin
+            path = File.join(::Rails.root, 'config', config_file_name)
+            if File.exist?(path)
+              File.open(path) do |file|
+                YAML.load(file)[::Rails.env]
+              end
+            else
+              {}
+            end
+          end
+      end
+      
+      def default_hostname
+        'localhost'
+      end
+      
+      def default_port
+        8983
+      end
+      
+      def default_path
+        "/solr"
+      end
+      
+      def config_file_name
+        'simple_solr.yml'
+      end
+  end
+end

data/lib/simple_solr/version.rb

@@ -1,3 +1,3 @@
 module SimpleSolr
-  VERSION = "0.0.1"
+  VERSION = "0.4.0"
 end

data/lib/simple_solr.rb

@@ -1,5 +1,19 @@
+require 'active_record'
+require 'httparty'
+require 'builder'
+
+require "simple_solr/active_record"
+require "simple_solr/configuration"
 require "simple_solr/version"
 
-module SimpleSolr
-  # Your code goes here...
+if defined?(ActiveRecord::Base)
+  ActiveRecord::Base.send :include, SimpleSolr::ActiveRecord
 end
+
+module SimpleSolr
+  class << self
+    def configuration
+      @configuration ||= SimpleSolr::Configuration.new
+    end
+  end
+end

data/simple_solr.gemspec

@@ -18,7 +18,9 @@ Gem::Specification.new do |s|
   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_development_dependency "rspec", ">= 2"
+  
+  s.add_runtime_dependency "activerecord"
+  s.add_runtime_dependency "httparty"
+  s.add_runtime_dependency "builder"
 end

data/spec/config/master_slave.yml

@@ -0,0 +1,5 @@
+test:
+  solr:
+    hostname: "slave.local"
+  master_solr:
+    hostname: "master.local"

data/spec/config/simple_solr.yml

@@ -0,0 +1,3 @@
+test:
+  solr:
+    hostname: "test.local"

data/spec/db/database.yml.example

@@ -0,0 +1,3 @@
+sqlite3:
+  adapter: sqlite3
+  database: ":memory:"

data/spec/db/models.rb

@@ -0,0 +1,17 @@
+# A bunch of models with varying amounts of simple_solrism.
+
+class SimpleDocument < ActiveRecord::Base
+  simple_solr do
+    field :title
+  end
+end
+
+class FullDocument < ActiveRecord::Base
+  simple_solr do
+    field :id,            lambda { |record| "full-document-#{record.id}" }
+    field :title
+    field :date_creation, :created_at
+    field :shared,        false
+    field :body
+  end
+end

data/spec/db/schema.rb

@@ -0,0 +1,11 @@
+ActiveRecord::Schema.define(:version => 0) do
+  create_table :simple_documents, :force => true do |t|
+    t.string :title
+  end
+  
+  create_table :full_documents, :force => true do |t|
+    t.string :title
+    t.timestamps
+    t.text :body
+  end
+end

data/spec/simple_solr/active_record_spec.rb

@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+describe SimpleSolr::ActiveRecord do
+  describe SimpleDocument do
+    it "provides simple_solr class method" do
+      SimpleDocument.should respond_to(:simple_solr)
+    end
+    
+    it "stores simple_solr fields" do
+      SimpleDocument.simple_solr_fields.should eq({:id => nil, :title => nil})
+    end
+    
+    context "save" do
+      let(:document) { SimpleDocument.create! :title => 'Omg Ponies' }
+
+      it "posts to solr" do
+        SimpleDocument.should_receive(:post).with("test.local:8983/solr/update?commit=true", :body => "<add><doc><field name=\"id\">#{document.id}</field><field name=\"title\">Omg Ponies</field></doc></add>")
+      end
+    end
+    
+    context "destroy" do
+      let(:document) { SimpleDocument.create! :title => 'Omg Ponies' }
+      
+      it "posts to solr" do
+        SimpleDocument.should_receive(:post).with("test.local:8983/solr/update?commit=true", :body => "<add><doc><field name=\"id\">#{document.id}</field><field name=\"title\">Omg Ponies</field></doc></add>")
+        SimpleDocument.should_receive(:post).with("test.local:8983/solr/update?commit=true", :body => "<delete><id>#{document.id}</id></delete>")
+        document.destroy
+      end
+    end
+
+    context "when unconfigured" do
+      before do
+        SimpleSolr.stub_chain(:configuration, :present?).and_return(false)
+      end
+
+      it "does nothing" do
+        SimpleDocument.should_not_receive(:post)
+        document = SimpleDocument.new :title => 'Omg Ponies'
+        document.save
+      end
+    end    
+  end
+  
+  describe FullDocument do
+    let(:document) { FullDocument.create :title => "Rainbows" }
+    
+    it "posts to solr after save" do
+      FullDocument.should_receive(:post).with("test.local:8983/solr?commit=true", :body => "<add><doc><field name=\"id\">full-document-#{document.id}</field><field name=\"title\">Rainbows</field><field name=\"date_creation\">#{document.created_at}</field><field name=\"shared\">false</field><field name=\"body\"></field></doc></add>")
+    end
+  end
+end

data/spec/simple_solr/configuration_spec.rb

@@ -0,0 +1,55 @@
+require 'spec_helper'
+
+describe SimpleSolr::Configuration do
+  it { should be_present}
+  
+  its(:hostname)          { should eq('test.local')}
+  its(:port)              { should eq(8983)}
+  its(:path)              { should eq('/solr')}
+  its(:uri)               { should eq('test.local:8983/solr')}
+
+  its(:master_hostname)   { should eq('test.local')}
+  its(:master_port)       { should eq(8983)}
+  its(:master_path)       { should eq('/solr')}
+  its(:master_uri)        { should eq('test.local:8983/solr')}
+  
+  context "unconfigured Rails env" do
+    before do
+      ::Rails.stub(:env).and_return('staging')
+    end
+    
+    it { should_not be_present }
+  end
+
+  context "missing config file" do
+    before do
+      ::Rails.stub(:root).and_return(Pathname.new('/'))
+    end
+    
+    its(:hostname)        { should eq('localhost')}
+    its(:port)            { should eq(8983)}
+    its(:path)            { should eq('/solr')}
+    its(:uri)             { should eq('localhost:8983/solr')}
+
+    its(:master_hostname) { should eq('localhost')}
+    its(:master_port)     { should eq(8983)}
+    its(:master_path)     { should eq('/solr')}
+    its(:master_uri)      { should eq('localhost:8983/solr')}
+  end
+
+  context "master/slave configuration" do
+    before do
+      subject.stub(:config_file_name).and_return('master_slave.yml')
+    end
+    
+    its(:hostname)        { should eq('slave.local')}
+    its(:port)            { should eq(8983)}
+    its(:path)            { should eq('/solr')}
+    its(:uri)             { should eq('slave.local:8983/solr')}
+
+    its(:master_hostname) { should eq('master.local')}
+    its(:master_port)     { should eq(8983)}
+    its(:master_path)     { should eq('/solr')}
+    its(:master_uri)      { should eq('master.local:8983/solr')}
+  end
+end

data/spec/simple_solr_spec.rb

@@ -0,0 +1,4 @@
+require 'spec_helper'
+
+describe SimpleSolr do
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'simple_solr'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  # some (optional) config here
+end

data/spec/support/database.rb

@@ -0,0 +1,28 @@
+require 'yaml'
+
+ENV['DB'] ||= 'sqlite3'
+
+database_yml = File.expand_path('../../db/database.yml', __FILE__)
+if File.exists?(database_yml)
+  active_record_configuration = YAML.load_file(database_yml)[ENV['DB']]
+  
+  ActiveRecord::Base.establish_connection(active_record_configuration)
+  
+  ActiveRecord::Base.silence do
+    ActiveRecord::Migration.verbose = false
+    
+    load(File.dirname(__FILE__) + '/../db/schema.rb')
+    load(File.dirname(__FILE__) + '/../db/models.rb')
+  end  
+  
+else
+  raise "Please create #{database_yml} first to configure your database. Take a look at: #{database_yml}.example"
+end
+
+def clean_database!
+  [SimpleDocument].each do |model|
+    ActiveRecord::Base.connection.execute "DELETE FROM #{model.table_name}"
+  end
+end
+
+clean_database!

data/spec/support/rails.rb

@@ -0,0 +1,12 @@
+require 'pathname'
+
+# Fake Rails class to provide stubbed methods we use on the real one.
+class Rails
+  def self.env
+    'test'
+  end
+  
+  def self.root
+    Pathname.new File.dirname(__FILE__) + "/.."
+  end
+end

metadata

@@ -1,13 +1,8 @@
 --- !ruby/object:Gem::Specification 
 name: simple_solr
 version: !ruby/object:Gem::Version 
-  hash: 29
   prerelease: 
-  segments: 
-  - 0
-  - 0
-  - 1
-  version: 0.0.1
+  version: 0.4.0
 platform: ruby
 authors: 
 - Joost Baaij
@@ -15,10 +10,53 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-15 00:00:00 +02:00
+date: 2011-08-16 00:00:00 +02:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "2"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: builder
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id004
 description: Rails plugins which connects to a Solr search engine with as less features as possible.
 email: 
 - joost@spacebabies.nl
@@ -30,11 +68,27 @@ extra_rdoc_files: []
 
 files: 
 - .gitignore
+- .rspec
+- CHANGELOG.rdoc
 - Gemfile
+- README.rdoc
 - Rakefile
 - lib/simple_solr.rb
+- lib/simple_solr/active_record.rb
+- lib/simple_solr/configuration.rb
 - lib/simple_solr/version.rb
 - simple_solr.gemspec
+- spec/config/master_slave.yml
+- spec/config/simple_solr.yml
+- spec/db/database.yml.example
+- spec/db/models.rb
+- spec/db/schema.rb
+- spec/simple_solr/active_record_spec.rb
+- spec/simple_solr/configuration_spec.rb
+- spec/simple_solr_spec.rb
+- spec/spec_helper.rb
+- spec/support/database.rb
+- spec/support/rails.rb
 has_rdoc: true
 homepage: ""
 licenses: []
@@ -49,18 +103,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
       version: "0"
 requirements: []
 
@@ -69,5 +117,15 @@ rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: Simple Solr client
-test_files: []
-
+test_files: 
+- spec/config/master_slave.yml
+- spec/config/simple_solr.yml
+- spec/db/database.yml.example
+- spec/db/models.rb
+- spec/db/schema.rb
+- spec/simple_solr/active_record_spec.rb
+- spec/simple_solr/configuration_spec.rb
+- spec/simple_solr_spec.rb
+- spec/spec_helper.rb
+- spec/support/database.rb
+- spec/support/rails.rb