spring 0.0.1 → 0.0.3

data/.gitignore

@@ -3,6 +3,7 @@
 .bundle
 .config
 .yardoc
+.rvmrc
 Gemfile.lock
 InstalledFiles
 _yardoc

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/README.md

@@ -1,29 +1,209 @@
 # Spring
 
-TODO: Write a gem description
+Spring is a Rails application preloader. It's trying to solve the same
+problem as [spork](https://github.com/sporkrb/spork),
+[zeus](https://github.com/burke/zeus) and
+[commands](https://github.com/rails/commands).
 
-## Installation
+I made it because we are having a discussion on the rails core team
+about shipping something to solve this problem with rails. So this is my
+proposal, as working code.
 
-Add this line to your application's Gemfile:
+(At least I hope it's working code, but this is alpha software at the
+moment. Please do try it and let me know if you hit problems.)
 
-    gem 'spring'
+## Features
 
-And then execute:
+Spring is most similar to Zeus, but it's implemented in pure Ruby, and
+is more tightly integrated with Rails (it makes use of Rails' built-in
+code reloader).
 
-    $ bundle
+Spring tries to be totally automatic.
+It boots up in the background the first time you run a
+command. Then it speeds up subsequent commands. If it detects that your
+pre-loaded environment has changed (maybe `config/application.rb` has
+been edited) then it will reload your environment in the background,
+ready for the next command. When you close your terminal session, Spring
+will automatically shut down. There's no "server" to manually start and
+stop.
 
-Or install it yourself as:
+Spring operates via a command line interface. Other solutions (e.g.
+commands) take the approach of using a special console to run commands
+from. This means we will have to re-implement shell features such as
+history, completion, etc. Whilst it's not impossible to re-implement
+those features, it's unnecessary work and our re-implementation
+won't be as feature complete as a real shell. Using a real shell also
+prevents the user having to constantly jump between a terminal with a
+real shell and a terminal running the rails "commands console".
 
-    $ gem install spring
+## Compatibility
+
+At the moment only MRI 1.9.3 / Rails 3.2 is supported.
 
 ## Usage
 
-TODO: Write usage instructions here
+Add `spring` to your gemfile and do a `bundle`.
+
+You now have a `spring` command. Do a `rbenv rehash` if necessary. Note
+that on my machine I had over 700 gems installed, and activating the gem
+to run the `spring` command added over 0.5s to the runtime. Clearing out
+my gems solved the problem, but I'd like to figure out a way to speed
+this up.
+
+For this walkthrough, I'm using the test app in the Spring repository:
+
+```
+cd /path/to/spring/test/apps/rails-3-2
+```
+
+We can run a test:
+
+```
+$ time spring test test/functional/posts_controller_test.rb
+Run options:
+
+# Running tests:
+
+.......
+
+Finished tests in 0.169882s, 41.2051 tests/s, 58.8644 assertions/s.
+
+7 tests, 10 assertions, 0 failures, 0 errors, 0 skips
+
+real	0m1.858s
+user	0m0.184s
+sys	0m0.067s
+```
+
+That booted our app in the background:
+
+```
+$ ps ax | grep spring
+ 8692 pts/6    Sl     0:00 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -r bundler/setup -r spring/server -e Spring::Server.boot
+ 8698 pts/6    Sl     0:02 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -r bundler/setup -r spring/server -e Spring::Server.boot
+```
+
+We can see two processes, one is the Spring server, the other is the
+application running in the test environment. When we close the terminal,
+the processes will be killed automatically.
+
+Running the tests is faster next time:
+
+```
+$ time spring test test/functional/posts_controller_test.rb
+Run options:
+
+# Running tests:
+
+.......
+
+Finished tests in 0.162963s, 42.9546 tests/s, 61.3637 assertions/s.
+
+7 tests, 10 assertions, 0 failures, 0 errors, 0 skips
+
+real	0m0.492s
+user	0m0.179s
+sys	0m0.063s
+```
+
+If we edit any of the application files, or test files, the change will
+be picked up on the next run, without having the background process
+having to be restarted. This works even if you e.g. referenced your
+`Post` model in an initializer and then edited it.
+
+If we edit any of the preloaded files, the application needs to restart
+automatically. Note that the application process id is 8698 above. Let's
+"edit" the `config/application.rb`:
+
+```
+$ touch config/application.rb
+$ ps ax | grep spring
+ 8692 pts/6    Sl     0:00 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -r bundler/setup -r spring/server -e Spring::Server.boot
+ 8876 pts/6    Sl     0:00 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -r bundler/setup -r spring/server -e Spring::Server.boot
+```
+
+The application process detected the change and exited. The server process
+then detected that the application process exited, so it started a new application.
+All of this happens automatically in the background. Next time we run a
+command we'll be running against a fresh application.
+
+If we run a command that uses a different environment, then it gets
+booted up. For example, the `rake` command uses the `development`
+environment by default:
+
+```
+$ time spring rake routes
+    posts GET    /posts(.:format)          posts#index
+          POST   /posts(.:format)          posts#create
+ new_post GET    /posts/new(.:format)      posts#new
+edit_post GET    /posts/:id/edit(.:format) posts#edit
+     post GET    /posts/:id(.:format)      posts#show
+          PUT    /posts/:id(.:format)      posts#update
+          DELETE /posts/:id(.:format)      posts#destroy
+
+real	0m0.763s
+user	0m0.185s
+sys	0m0.063s
+```
+
+We now have 3 processes: the server, and application in test mode and
+the application in development mode.
+
+```
+$ ps ax | grep spring
+ 8692 pts/6    Sl     0:00 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -r bundler/setup -r spring/server -e Spring::Server.boot
+ 8876 pts/6    Sl     0:15 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -r bundler/setup -r spring/server -e Spring::Server.boot
+ 9088 pts/6    Sl     0:01 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -r bundler/setup -r spring/server -e Spring::Server.boot
+```
+
+Running rake is faster the second time:
+
+```
+$ time spring rake routes
+    posts GET    /posts(.:format)          posts#index
+          POST   /posts(.:format)          posts#create
+ new_post GET    /posts/new(.:format)      posts#new
+edit_post GET    /posts/:id/edit(.:format) posts#edit
+     post GET    /posts/:id(.:format)      posts#show
+          PUT    /posts/:id(.:format)      posts#update
+          DELETE /posts/:id(.:format)      posts#destroy
+
+real	0m0.341s
+user	0m0.177s
+sys	0m0.070s
+```
+
+## Commands
+
+The following commands are shipped by default.
+
+Custom commands can be specified in `config/spring.rb`. See
+[`lib/spring/commands.rb`](https://github.com/jonleighton/spring/blob/master/lib/spring/commands.rb)
+for examples.
+
+### `test`
+
+Runs a test (e.g. Test::Unit, MiniTest::Unit, etc.) Preloads the `test_helper` file.
+
+### `rspec`
+
+Runs an rspec spec, exactly the same as the `rspec` executable. Preloads
+the `spec_helper` file.
+
+### `rake`
+
+Runs a rake task.
+
+### `console`
+
+Boots into the Rails console. Currently this is usable but not perfect,
+for example you can't scroll back through command history. (That will be
+fixed.)
+
+### `generate`
+
+Runs a Rails generator.
 
-## Contributing
+### `runner`
 
-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
+The Rails runner.

data/Rakefile

@@ -1,10 +1,21 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 
-Rake::TestTask.new do |t|
-  t.libs << "test"
-  t.test_files = FileList["test/{acceptance,unit}/*_test.rb"]
-  t.verbose = true
+namespace :test do
+  Rake::TestTask.new(:unit) do |t|
+    t.libs << "test"
+    t.test_files = FileList["test/unit/*_test.rb"]
+    t.verbose = true
+  end
+
+  Rake::TestTask.new(:acceptance) do |t|
+    t.libs << "test"
+    t.test_files = FileList["test/acceptance/*_test.rb"]
+    t.verbose = true
+  end
+
+  desc 'run all tests'
+  task all: [:unit, :acceptance]
 end
 
-task default: :test
+task default: 'test:all'

data/lib/spring/application.rb

@@ -47,10 +47,16 @@ class Spring
       loop do
         watch_application
 
-        client = manager.recv_io
-        client.autoclose = false # prevent GC closing the FD
+        client = manager.recv_io(UNIXSocket)
 
-        serve UNIXSocket.for_fd(client.fileno)
+        # Confirm that we have received the client socket. This is necessary on OS X
+        # to prevent a timing error. The client needs to keep the FD that we are receiving
+        # open until it has been received here. Unlike on Linux, it's not sufficient for
+        # the FD to just be in the socket buffer, it has to actually get received at this
+        # end before it can be closed by the client.
+        manager.puts
+
+        serve client
       end
     end
 

data/lib/spring/application_manager.rb

@@ -29,20 +29,31 @@ class Spring
       @pid
     end
 
+    # The return value of this method indicates whether or not the application
+    # successfully received the client. It might not successfully receive the
+    # client if e.g. the application has an exception during initialization, causing
+    # the application process to die.
     def run(client)
       @client = client
 
       synchronize do
-        start unless alive?
-
-        begin
-          child.send_io @client
-        rescue Errno::EPIPE
-          # EPIPE indicates child has died but has not been collected by the wait thread yet
+        if alive?
+          begin
+            child.send_io @client
+          rescue Errno::EPIPE
+            # EPIPE indicates child has died but has not been collected by the wait thread yet
+            start
+            child.send_io @client
+          end
+        else
           start
           child.send_io @client
         end
+
+        child.gets
       end
+    rescue Errno::ECONNRESET, Errno::EPIPE
+      false
     ensure
       @client.close
       @client = nil

data/lib/spring/commands.rb

@@ -1,5 +1,3 @@
-# TODO: Need a way for applications to add their own commands.
-
 class Spring
   @commands = {}
 
@@ -15,6 +13,12 @@ class Spring
     commands.fetch name
   end
 
+  # Load custom commands, if any
+  begin
+    require "./config/spring"
+  rescue LoadError
+  end
+
   module Commands
     class Test
       def env

data/lib/spring/env.rb

@@ -1,5 +1,6 @@
 require "pathname"
 require "spring/sid"
+require "fileutils"
 
 class Spring
   class Env
@@ -11,7 +12,7 @@ class Spring
 
     def tmp_path
       path = root.join('tmp/spring')
-      path.mkdir unless path.exist?
+      FileUtils.mkdir_p(path) unless path.exist?
       path
     end
 

data/lib/spring/server.rb

@@ -14,6 +14,7 @@ class Spring
     def initialize(env = Env.new)
       @env          = env
       @applications = Hash.new { |h, k| h[k] = ApplicationManager.new(k) }
+      @pidfile      = env.pidfile_path.open('a')
     end
 
     def boot
@@ -25,7 +26,18 @@ class Spring
       write_pidfile
 
       server = UNIXServer.open(env.socket_name)
-      loop { @applications[server.accept.read].run server.accept }
+      loop { serve server.accept }
+    end
+
+    def serve(client)
+      app_client = client.recv_io
+      rails_env  = client.gets.chomp
+
+      if @applications[rails_env].run(app_client)
+        client.write "0"
+      else
+        client.write "1"
+      end
     end
 
     def set_exit_hook
@@ -42,12 +54,10 @@ class Spring
     end
 
     def write_pidfile
-      file = env.pidfile_path.open('a')
-
-      if file.flock(File::LOCK_EX | File::LOCK_NB)
-        file.truncate(0)
-        file.write("#{Process.pid}\n")
-        file.fsync
+      if @pidfile.flock(File::LOCK_EX | File::LOCK_NB)
+        @pidfile.truncate(0)
+        @pidfile.write("#{Process.pid}\n")
+        @pidfile.fsync
       else
         STDERR.puts "#{file.path} is locked; it looks like a server is already running"
         exit(1)
@@ -55,5 +65,3 @@ class Spring
     end
   end
 end
-
-Spring::Server.boot if __FILE__ == $0

data/lib/spring/version.rb

@@ -1,3 +1,3 @@
 class Spring
-  VERSION = "0.0.1"
+  VERSION = "0.0.3"
 end

data/lib/spring.rb

@@ -12,7 +12,8 @@ class Spring
   SERVER_COMMAND = [
     File.join(*RbConfig::CONFIG.values_at('bindir', 'RUBY_INSTALL_NAME')),
     "-r", "bundler/setup",
-    File.expand_path("../spring/server.rb", __FILE__)
+    "-r", "spring/server",
+    "-e", "Spring::Server.boot"
   ]
 
   def self.run(args)
@@ -26,44 +27,62 @@ class Spring
   end
 
   def server_running?
-    env.socket_path.exist?
+    if env.pidfile_path.exist?
+      pidfile = env.pidfile_path.open('r')
+      !pidfile.flock(File::LOCK_EX | File::LOCK_NB)
+    else
+      false
+    end
+  ensure
+    if pidfile
+      pidfile.flock(File::LOCK_UN)
+      pidfile.close
+    end
   end
 
+  # Boot the server into the process group of the current session.
+  # This will cause it to be automatically killed once the session
+  # ends (i.e. when the user closes their terminal).
   def boot_server
-    # Boot the server into the process group of the current session.
-    # This will cause it to be automatically killed once the session
-    # ends (i.e. when the user closes their terminal).
+    env.socket_path.unlink if env.socket_path.exist?
     Process.spawn(*SERVER_COMMAND, pgroup: SID.pgid)
-    sleep 0.1 until server_running?
+    sleep 0.1 until env.socket_path.exist?
   end
 
   def run(args)
     boot_server unless server_running?
 
-    socket = UNIXSocket.open(env.socket_name)
-    socket.write rails_env_for(args.first)
-    socket.close
+    application, client = UNIXSocket.pair
+
+    server = UNIXSocket.open(env.socket_name)
+    server.send_io client
+    server.puts rails_env_for(args.first)
+
+    status = server.read(1)
+
+    server.close
+    client.close
 
-    socket = UNIXSocket.open(env.socket_name)
+    return false unless status == "0"
 
-    socket.send_io STDOUT
-    socket.send_io STDERR
-    socket.send_io stdin_slave
+    application.send_io STDOUT
+    application.send_io STDERR
+    application.send_io stdin_slave
 
-    socket.puts args.length
+    application.puts args.length
 
     args.each do |arg|
-      socket.puts  arg.length
-      socket.write arg
+      application.puts  arg.length
+      application.write arg
     end
 
     # FIXME: receive exit status from server
-    socket.read
+    application.read
     true
   rescue Errno::ECONNRESET
     false
   ensure
-    socket.close
+    application.close if application
   end
 
   private

data/spring.gemspec

@@ -18,4 +18,5 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
 
   gem.add_dependency 'activesupport'
+  gem.add_development_dependency 'rake'
 end

data/test/acceptance/app_test.rb

@@ -1,5 +1,6 @@
 require 'helper'
 require 'io/wait'
+require "timeout"
 
 class AppTest < ActiveSupport::TestCase
   BINFILE = File.expand_path('../bin/spring', TEST_ROOT)
@@ -36,20 +37,28 @@ class AppTest < ActiveSupport::TestCase
       )
     end
 
-    _, status = Process.wait2
+    _, status = Timeout.timeout(opts.fetch(:timeout, 5)) { Process.wait2 }
 
-    out, err = [stdout, stderr].map(&:first).map { |s| s.ready? ? s.readpartial(10240) : "" }
+    out, err = read_streams
 
     @times << (Time.now - start_time) if opts.fetch(:timer, true)
 
-    # p status
-    # puts "---"
-    # puts out
-    # puts "***"
-    # puts err
-    # puts "---"
-
     [status, out, err]
+  rescue Timeout::Error
+    print_streams *read_streams
+    raise
+  end
+
+  def print_streams(out, err)
+    puts "---"
+    puts out
+    puts "***"
+    puts err
+    puts "---"
+  end
+
+  def read_streams
+    [stdout, stderr].map(&:first).map { |s| s.ready? ? s.readpartial(10240) : "" }
   end
 
   def await_reload
@@ -58,17 +67,17 @@ class AppTest < ActiveSupport::TestCase
 
   def assert_successful_run(*args)
     status, _, _ = app_run(*args)
-    assert status.success?
+    assert status.success?, 'The run should be successful but it was '
   end
 
   def assert_unsuccessful_run(*args)
     status, _, _ = app_run(*args)
-    assert !status.success?
+    assert !status.success?, 'The run should not be successful but it was'
   end
 
   def assert_stdout(command, expected)
     _, stdout, _ = app_run(command)
-    assert stdout.include?(expected)
+    assert stdout.include?(expected), "expected '#{expected}' to be printed to stdout. But it wasn't, the stdout is:\n#{stdout}"
   end
 
   def assert_speedup(opts = {})
@@ -92,7 +101,7 @@ class AppTest < ActiveSupport::TestCase
 
     @times = []
 
-    app_run "bundle check || bundle update", timer: false
+    app_run "bundle check || bundle update", timer: false, timeout: nil
     app_run "bundle exec rake db:migrate",   timer: false
   end
 
@@ -195,4 +204,8 @@ class AppTest < ActiveSupport::TestCase
       File.write(application, application_contents)
     end
   end
+
+  test "custom commands" do
+    assert_stdout "#{BINFILE} custom", "omg"
+  end
 end

data/test/apps/rails-3-2/config/spring.rb

@@ -0,0 +1,7 @@
+class CustomCommand
+  def call(args)
+    puts "omg"
+  end
+end
+
+Spring.register_command "custom", CustomCommand

data/test/unit/application_watcher_test.rb

@@ -1,5 +1,6 @@
 require "helper"
 require "fileutils"
+require "active_support/core_ext/numeric/time"
 require "spring/application_watcher"
 
 class ApplicationWatcherTest < Test::Unit::TestCase
@@ -12,21 +13,21 @@ class ApplicationWatcherTest < Test::Unit::TestCase
     FileUtils.rm_r(@dir)
   end
 
-  def touch(file)
-    sleep 0.01
-    File.write(file, "omg")
+  def touch(file, mtime = nil)
+    options = {}
+    options[:mtime] = mtime if mtime
+    FileUtils.touch(file, options)
   end
 
   def test_file_mtime
     file = "#{@dir}/omg"
-    touch file
+    touch file, Time.now - 2.seconds
 
     watcher = Spring::ApplicationWatcher.new
     watcher.add_files [file]
 
     assert !watcher.stale?
-
-    touch file
+    touch file, Time.now
     assert watcher.stale?
   end
 
@@ -39,16 +40,16 @@ class ApplicationWatcherTest < Test::Unit::TestCase
 
     assert !watcher.stale?
 
-    touch "#{@dir}/1/foo"
+    touch "#{@dir}/1/foo", Time.now - 1.minute
     assert !watcher.stale?
 
-    touch "#{@dir}/1/foo.rb"
+    touch "#{@dir}/1/foo.rb", 2.seconds
     assert watcher.stale?
 
     watcher.reset
     assert !watcher.stale?
 
-    touch "#{@dir}/2/foo"
+    touch "#{@dir}/2/foo", Time.now
     assert watcher.stale?
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spring
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-29 00:00:00.000000000 Z
+date: 2013-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -27,6 +27,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Rails application preloader
 email:
 - j@jonathanleighton.com
@@ -36,6 +52,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -91,6 +108,7 @@ files:
 - test/apps/rails-3-2/config/initializers/wrap_parameters.rb
 - test/apps/rails-3-2/config/locales/en.yml
 - test/apps/rails-3-2/config/routes.rb
+- test/apps/rails-3-2/config/spring.rb
 - test/apps/rails-3-2/db/migrate/20121109171227_create_posts.rb
 - test/apps/rails-3-2/db/schema.rb
 - test/apps/rails-3-2/db/seeds.rb
@@ -184,6 +202,7 @@ test_files:
 - test/apps/rails-3-2/config/initializers/wrap_parameters.rb
 - test/apps/rails-3-2/config/locales/en.yml
 - test/apps/rails-3-2/config/routes.rb
+- test/apps/rails-3-2/config/spring.rb
 - test/apps/rails-3-2/db/migrate/20121109171227_create_posts.rb
 - test/apps/rails-3-2/db/schema.rb
 - test/apps/rails-3-2/db/seeds.rb
@@ -212,4 +231,3 @@ test_files:
 - test/apps/rails-3-2/vendor/plugins/.gitkeep
 - test/helper.rb
 - test/unit/application_watcher_test.rb
-has_rdoc: