elasticsearch-rails 0.0.0 → 0.1.0.rc1

data/LICENSE.txt

@@ -1,22 +1,13 @@
-Copyright (c) 2013 Karel Minarik
+Copyright (c) 2014 Elasticsearch
 
-MIT License
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-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:
+    http://www.apache.org/licenses/LICENSE-2.0
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -1,29 +1,71 @@
 # Elasticsearch::Rails
 
-TODO: Write a gem description
+The `elasticsearch-rails` library is a companion for the
+the [`elasticsearch-model`](https://github.com/elasticsearch/elasticsearch-rails/tree/master/elasticsearch-model)
+library, providing features suitable for Ruby on Rails applications.
+
+The library is compatible with Ruby 1.9.3 and higher.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Install the package from [Rubygems](https://rubygems.org):
 
-    gem 'elasticsearch-rails'
+    gem install elasticsearch-rails --pre
 
-And then execute:
+To use an unreleased version, either add it to your `Gemfile` for [Bundler](http://bundler.io):
 
-    $ bundle
+    gem 'elasticsearch-rails', git: 'git://github.com/elasticsearch/elasticsearch-rails.git'
 
-Or install it yourself as:
+or install it from a source code checkout:
 
-    $ gem install elasticsearch-rails
+    git clone https://github.com/elasticsearch/elasticsearch-rails.git
+    cd elasticsearch-rails/elasticsearch-rails
+    bundle install
+    rake install
 
 ## Usage
 
-TODO: Write usage instructions here
+You can generate a fully working example Ruby on Rails application, with an `Article` model and a search form,
+to play with (it even downloads _Elasticsearch_ itself, generates the application skeleton and leaves you with
+a _Git_ repository to explore the steps and the code):
+
+```bash
+rails new searchapp --skip --skip-bundle --template https://raw.github.com/elasticsearch/elasticsearch-rails/master/elasticsearch-rails/lib/rails/templates/01-basic.rb
+```
+
+Run the same command with the `02-pretty` template to add features such as a custom `Article.search` method,
+result highlighting and [_Bootstrap_](http://getbootstrap.com) integration:
+
+```bash
+rails new searchapp --skip --skip-bundle --template https://raw.github.com/elasticsearch/elasticsearch-rails/master/elasticsearch-rails/lib/rails/templates/02-pretty.rb
+```
+
+NOTE: A third, much more complex template, demonstrating other features such as faceted navigation or
+      query suggestions is being worked on.
+
+## TODO
+
+This is an initial release of the `elasticsearch-rails` library. Many more features are planned and/or
+being worked on, such as:
+
+* Rake tasks for convenient (re)indexing your models from the command line
+* Hooking into Rails' notification system to display Elasticsearch related statistics in the application log
+* Instrumentation support for NewRelic integration
+
+## License
+
+This software is licensed under the Apache 2 license, quoted below.
+
+    Copyright (c) 2014 Elasticsearch <http://www.elasticsearch.org>
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
 
-## Contributing
+       http://www.apache.org/licenses/LICENSE-2.0
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.

data/Rakefile

@@ -1 +1,53 @@
 require "bundler/gem_tasks"
+
+desc "Run unit tests"
+task :default => 'test:unit'
+task :test    => 'test:unit'
+
+# ----- Test tasks ------------------------------------------------------------
+
+require 'rake/testtask'
+namespace :test do
+  task :ci_reporter do
+    ENV['CI_REPORTS'] ||= 'tmp/reports'
+    require 'ci/reporter/rake/minitest'
+    Rake::Task['ci:setup:minitest'].invoke
+  end
+
+  Rake::TestTask.new(:unit) do |test|
+    Rake::Task['test:ci_reporter'].invoke if ENV['CI']
+    test.libs << 'lib' << 'test'
+    test.test_files = FileList["test/unit/**/*_test.rb"]
+    # test.verbose = true
+    # test.warning = true
+  end
+
+  Rake::TestTask.new(:integration) do |test|
+    Rake::Task['test:ci_reporter'].invoke if ENV['CI']
+    test.libs << 'lib' << 'test'
+    test.test_files = FileList["test/integration/**/*_test.rb"]
+  end
+
+  Rake::TestTask.new(:all) do |test|
+    Rake::Task['test:ci_reporter'].invoke if ENV['CI']
+    test.libs << 'lib' << 'test'
+    test.test_files = FileList["test/unit/**/*_test.rb", "test/integration/**/*_test.rb"]
+  end
+end
+
+# ----- Documentation tasks ---------------------------------------------------
+
+require 'yard'
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.options = %w| --embed-mixins --markup=markdown |
+end
+
+# ----- Code analysis tasks ---------------------------------------------------
+
+if defined?(RUBY_VERSION) && RUBY_VERSION > '1.9'
+  require 'cane/rake_task'
+  Cane::RakeTask.new(:quality) do |cane|
+    cane.abc_max = 15
+    cane.no_style = true
+  end
+end

data/elasticsearch-rails.gemspec

@@ -3,21 +3,39 @@ lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'elasticsearch/rails/version'
 
-Gem::Specification.new do |spec|
-  spec.name          = "elasticsearch-rails"
-  spec.version       = Elasticsearch::Rails::VERSION
-  spec.authors       = ["Karel Minarik"]
-  spec.email         = ["karel.minarik@elasticsearch.org"]
-  spec.description   = %q{Elasticsearch gem integration for Rails (WIP)}
-  spec.summary       = spec.description
-  spec.homepage      = ""
-  spec.license       = "Apache 2"
+Gem::Specification.new do |s|
+  s.name          = "elasticsearch-rails"
+  s.version       = Elasticsearch::Rails::VERSION
+  s.authors       = ["Karel Minarik"]
+  s.email         = ["karel.minarik@elasticsearch.org"]
+  s.description   = "Ruby on Rails integrations for Elasticsearch."
+  s.summary       = "Ruby on Rails integrations for Elasticsearch."
+  s.homepage      = "https://github.com/elasticsearch/elasticsearch-rails/"
+  s.license       = "Apache 2"
 
-  spec.files         = `git ls-files`.split($/)
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  s.files         = `git ls-files`.split($/)
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.3"
-  spec.add_development_dependency "rake"
+  s.extra_rdoc_files  = [ "README.md", "LICENSE.txt" ]
+  s.rdoc_options      = [ "--charset=UTF-8" ]
+
+  s.add_development_dependency "bundler", "~> 1.3"
+  s.add_development_dependency "rake"
+
+  s.add_development_dependency "shoulda-context"
+  s.add_development_dependency "mocha"
+  s.add_development_dependency "turn"
+  s.add_development_dependency "yard"
+  s.add_development_dependency "ruby-prof"
+  s.add_development_dependency "pry"
+  s.add_development_dependency "ci_reporter"
+
+  if defined?(RUBY_VERSION) && RUBY_VERSION > '1.9'
+    s.add_development_dependency "simplecov"
+    s.add_development_dependency "cane"
+    s.add_development_dependency "require-prof"
+    s.add_development_dependency "coveralls"
+  end
 end

data/lib/elasticsearch/rails/version.rb

@@ -1,5 +1,5 @@
 module Elasticsearch
   module Rails
-    VERSION = "0.0.0"
+    VERSION = "0.1.0.rc1"
   end
 end

data/lib/rails/templates/01-basic.rb

@@ -0,0 +1,318 @@
+# =====================================================================================================
+# Template for generating a no-frills Rails application with support for Elasticsearch full-text search
+# =====================================================================================================
+#
+# This file creates a basic, fully working Rails application with support for Elasticsearch full-text
+# search via the `elasticsearch-rails` gem; https://github.com/elasticsearch/elasticsearch-rails.
+#
+# Requirements:
+# -------------
+#
+# * Git
+# * Ruby  >= 1.9.3
+# * Rails >= 4
+# * Java  >= 7 (for Elasticsearch)
+#
+# Usage:
+# ------
+#
+#     $ rails new searchapp --skip --skip-bundle --template https://raw.github.com/elasticsearch/elasticsearch-rails/master/elasticsearch-rails/lib/rails/templates/01-basic.rb
+#
+# =====================================================================================================
+
+require 'elasticsearch'
+client = Elasticsearch::Client.new
+
+at_exit do
+  pid = File.read("#{destination_root}/tmp/pids/elasticsearch.pid") rescue nil
+  if pid
+    say_status  "Stop", "Elasticsearch", :yellow
+    run "kill #{pid}"
+  end
+end
+
+run "touch tmp/.gitignore"
+
+append_to_file ".gitignore", "vendor/elasticsearch-0.90.7/\n"
+
+git :init
+git add:    "."
+git commit: "-m 'Initial commit: Clean application'"
+
+# ----- Download Elasticsearch --------------------------------------------------------------------
+
+unless (client.ping rescue false)
+  COMMAND = <<-COMMAND.gsub(/^    /, '')
+    curl -# -O "http://download.elasticsearch.org/elasticsearch/elasticsearch/elasticsearch-0.90.7.tar.gz"
+    tar -zxf elasticsearch-0.90.7.tar.gz
+    rm  -f   elasticsearch-0.90.7.tar.gz
+    ./elasticsearch-0.90.7/bin/elasticsearch -p #{destination_root}/tmp/pids/elasticsearch.pid
+  COMMAND
+
+  puts        "\n"
+  say_status  "ERROR", "Elasticsearch not running!\n", :red
+  puts        '-'*80
+  say_status  '',      "It appears that Elasticsearch is not running on this machine."
+  say_status  '',      "Is it installed? Do you want me to install it for you with this command?\n\n"
+  COMMAND.each_line { |l| say_status '', "$ #{l}" }
+  puts
+  say_status  '',      "(To uninstall, just remove the generated application directory.)"
+  puts        '-'*80, ''
+
+  if yes?("Install Elasticsearch?", :bold)
+    puts
+    say_status  "Install", "Elasticsearch", :yellow
+
+    commands = COMMAND.split("\n")
+    exec     = commands.pop
+    inside("vendor") do
+      commands.each { |command| run command }
+      run "(#{exec})"  # Launch Elasticsearch in subshell
+    end
+  end
+end
+
+# ----- Add README --------------------------------------------------------------------------------
+
+puts
+say_status  "README", "Adding Readme...\n", :yellow
+puts        '-'*80, ''; sleep 0.25
+
+remove_file 'README.rdoc'
+
+create_file 'README.rdoc', <<-README
+= Ruby on Rails and Elasticsearch: Example application
+
+This application is an example of integrating the {Elasticsearch}[http://www.elasticsearch.org]
+search engine with the {Ruby On Rails}[http://rubyonrails.org] web framework.
+
+It has been generated by application templates available at
+https://github.com/elasticsearch/elasticsearch-rails/tree/master/elasticsearch-rails/lib/rails/templates.
+
+== [1] Basic
+
+The `basic` version provides a simple integration for a simple Rails model, `Article`, showing how
+to include the search engine support in your model, automatically index changes to records,
+and use a form to perform simple search require 'requests.'
+
+README
+
+
+git add:    "."
+git commit: "-m '[01] Added README for the application'"
+
+# ----- Use Thin ----------------------------------------------------------------------------------
+
+begin
+  require 'thin'
+  puts
+  say_status  "Rubygems", "Adding Thin into Gemfile...\n", :yellow
+  puts        '-'*80, '';
+
+  gem 'thin'
+rescue LoadError
+end
+
+# ----- Auxiliary gems ----------------------------------------------------------------------------
+
+gem 'turn',  group: 'test'
+gem 'mocha', group: 'test', require: 'mocha/setup'
+
+# ----- Remove CoffeeScript, Sass and "all that jazz" ---------------------------------------------
+
+comment_lines 'Gemfile', /gem 'coffee/
+comment_lines 'Gemfile', /gem 'sass/
+comment_lines 'Gemfile', /gem 'uglifier/
+
+# ----- Add gems into Gemfile ---------------------------------------------------------------------
+
+puts
+say_status  "Rubygems", "Adding Elasticsearch libraries into Gemfile...\n", :yellow
+puts        '-'*80, ''; sleep 0.75
+
+gem 'elasticsearch',       git: 'git@github.com:elasticsearch/elasticsearch-ruby.git'
+gem 'elasticsearch-model', git: 'git@github.com:elasticsearch/elasticsearch-rails.git'
+gem 'elasticsearch-rails', git: 'git@github.com:elasticsearch/elasticsearch-rails.git'
+
+# ----- Install gems ------------------------------------------------------------------------------
+
+puts
+say_status  "Rubygems", "Installing Rubygems...", :yellow
+puts        '-'*80, ''
+
+run "bundle install"
+
+git add:    "Gemfile*"
+git commit: "-m 'Added libraries into Gemfile'"
+
+# ----- Generate Article resource -----------------------------------------------------------------
+
+puts
+say_status  "Model", "Generating the Article resource...", :yellow
+puts        '-'*80, ''; sleep 0.75
+
+generate :scaffold, "Article title:string content:text published_on:date"
+route "root to: 'articles#index'"
+rake  "db:migrate"
+
+git add:    "."
+git commit: "-m 'Added the generated Article resource'"
+
+# ----- Add Elasticsearch integration into the model ----------------------------------------------
+
+puts
+say_status  "Model", "Adding search support into the Article model...", :yellow
+puts        '-'*80, ''; sleep 0.25
+
+run "rm -f app/models/article.rb"
+file 'app/models/article.rb', <<-CODE
+class Article < ActiveRecord::Base
+  include Elasticsearch::Model
+  include Elasticsearch::Model::Callbacks
+end
+CODE
+
+git commit: "-a -m 'Added Elasticsearch support into the Article model'"
+
+# ----- Add Elasticsearch integration into the interface ------------------------------------------
+
+puts
+say_status  "Controller", "Adding controller action, route, and HTML for searching...", :yellow
+puts        '-'*80, ''; sleep 0.25
+
+inject_into_file 'app/controllers/articles_controller.rb', before: %r|^\s*# GET /articles/1$| do
+  <<-CODE
+
+  # GET /articles/search
+  def search
+    @articles = Article.search(params[:q]).records
+
+    render action: "index"
+  end
+
+  CODE
+end
+
+inject_into_file 'app/views/articles/index.html.erb', after: %r{<h1>Listing articles</h1>} do
+  <<-CODE
+
+  <hr>
+
+  <%= form_tag search_articles_path, method: 'get' do %>
+    <%= label_tag :query %>
+    <%= text_field_tag :q, params[:q] %>
+    <%= submit_tag :search %>
+  <% end %>
+
+  <hr>
+
+  CODE
+end
+
+inject_into_file 'app/views/articles/index.html.erb', after: %r{<%= link_to 'New Article', new_article_path %>} do
+  <<-CODE
+  <%= link_to 'All Articles', articles_path if params[:q] %>
+  CODE
+end
+
+gsub_file 'config/routes.rb', %r{resources :articles$}, <<-CODE
+resources :articles do
+    collection { get :search }
+  end
+CODE
+
+gsub_file 'test/controllers/articles_controller_test.rb', %r{setup do.*?end}m, <<-CODE
+setup do
+    @article = articles(:one)
+
+    Article.__elasticsearch__.import
+    Article.__elasticsearch__.refresh_index!
+  end
+CODE
+
+inject_into_file 'test/controllers/articles_controller_test.rb', after: %r{test "should get index" do.*?end}m do
+  <<-CODE
+
+
+  test "should get search results" do
+    get :search, q: 'mystring'
+    assert_response :success
+    assert_not_nil assigns(:articles)
+    assert_equal 2, assigns(:articles).size
+  end
+  CODE
+end
+
+git commit: "-a -m 'Added search form and controller action'"
+
+# ----- Seed the database -------------------------------------------------------------------------
+
+puts
+say_status  "Database", "Seeding the database with data...", :yellow
+puts        '-'*80, ''; sleep 0.25
+
+remove_file "db/seeds.rb"
+create_file 'db/seeds.rb', %q{
+contents = [
+'Lorem ipsum dolor sit amet.',
+'Consectetur adipisicing elit, sed do eiusmod tempor incididunt.',
+'Labore et dolore magna aliqua.',
+'Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.',
+'Excepteur sint occaecat cupidatat non proident.'
+]
+
+puts "Deleting all articles..."
+Article.delete_all
+
+unless ENV['COUNT']
+
+  puts "Creating articles..."
+  %w[ One Two Three Four Five ].each_with_index do |title, i|
+    Article.create title: title, content: contents[i], published_on: i.days.ago.utc
+  end
+
+else
+
+  print "Generating articles..."
+  (1..ENV['COUNT'].to_i).each_with_index do |title, i|
+    Article.create title: "Title #{title}", content: 'Lorem ipsum dolor', published_on: i.days.ago.utc
+    print '.' if i % ENV['COUNT'].to_i/10 == 0
+  end
+  puts "\n"
+
+end
+}
+
+run  "rails runner 'Article.__elasticsearch__.create_index! force: true'"
+rake "db:seed"
+
+git add:    "db/seeds.rb"
+git commit: "-m 'Added the database seeding script'"
+
+# ----- Print Git log -----------------------------------------------------------------------------
+
+puts
+say_status  "Git", "Details about the application:", :yellow
+puts        '-'*80, ''
+
+git tag: "basic"
+git log: "--reverse --oneline"
+
+# ----- Start the application ---------------------------------------------------------------------
+
+require 'net/http'
+if (begin; Net::HTTP.get(URI('http://localhost:3000')); rescue Errno::ECONNREFUSED; false; rescue Exception; true; end)
+  puts        "\n"
+  say_status  "ERROR", "Some other application is running on port 3000!\n", :red
+  puts        '-'*80
+
+  port = ask("Please provide free port:", :bold)
+else
+  port = '3000'
+end
+
+puts  "", "="*80
+say_status  "DONE", "\e[1mStarting the application.\e[0m", :yellow
+puts  "="*80, ""
+
+run  "rails server --port=#{port}"