spring 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ab103d29ee132ac8637c7ddca8d5c41fc567c31e
-  data.tar.gz: 88e600c6e1d59b4150625769f20f6d543958087c
+  metadata.gz: a2357648d0fc0f884098f352ab693e66556de6df
+  data.tar.gz: df070385ccdf9fbbb6d48770f21886dbab93516e
 SHA512:
-  metadata.gz: 7b4d762562b8d4c1832bcec43819b6bcc6d9168473095fac089a743c0c421d4450f77e7c0a3cf31902256ed42a3d0fa57e7767cd4a0cf9d0bd55dc24c758f460
-  data.tar.gz: 9c929b2636980dc30486f475caeacb1f3de296420c22e9f0a52c67ce732a8953e28f1b090258a18456d210ce217610e8e4df8ffeb7a1a8ebd0e2b546554235ec
+  metadata.gz: cc65ad0c92b3a134505805c9b8ed999029b49030ab0ca8e46473c47c18a6ff17804de47897a7493e28765dc3fa6dc18df2de5beb4be7b8f6bdf04bd979d2a7da
+  data.tar.gz: 1b408b559590cf9a1b13da2d390d191964809107edc00c4b67e6c54384d05df1a5f9673fcc796318e1962c1f3c4e9fd49141596a3692c80b831d9cc933dd67c5

data/.travis.yml

@@ -2,6 +2,8 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0.0
+  - 2.1.0
 env:
   - RAILS_VERSION="~> 3.2.0"
   - RAILS_VERSION="~> 4.0.0"
+  - RAILS_VERSION="~> 4.1.0.beta1"

data/CHANGELOG.md

@@ -1,3 +1,30 @@
+## 1.1.0
+
+* A `bin/spring` binstub is now generated. This allows us to load spring
+  correctly if you have it installed locally with a `BUNDLE_PATH`, so
+  it's no longer necessary to install spring system-wide. We also
+  activate the correct version from your Gemfile.lock. Note that you
+  still can't have spring in your Gemfile as a git repository or local
+  path; it must be a proper gem.
+* Various changes to how springified binstubs are implemented. Existing
+  binstubs will continue to work, but it's recommended to run `spring binstub`
+  again to upgrade them to the new format.
+* `spring binstub --remove` option added for removing spring from
+  binstubs. This won't work unless you have upgraded your binstubs to
+  the new format.
+* `config/database.yml` is watched
+* Better application restarts - if you introduce an error, for example
+  by editing `config/application.rb`, spring will now continue to watch
+  your files and will immediately try to restart the application when
+  you edit `config/application.rb` again (hopefully to correct the error).
+  This means that by the time you come to run a command the application
+  may well already be running.
+* Gemfile changes are now gracefully handled. Previously they would
+  cause spring to simply quit, meaning that you'd incur the full startup
+  penalty on the next run. Now spring doesn't quit, and will try to load
+  up your new bundle in the background.
+* Fix support for using spring with Rails engines/plugins
+
 ## 1.0.0
 
 * Enterprise ready secret sauce added

data/README.md

@@ -1,6 +1,7 @@
 # Spring
 
-[![Build Status](https://travis-ci.org/jonleighton/spring.png?branch=master)](https://travis-ci.org/jonleighton/spring)
+[![Build Status](https://travis-ci.org/rails/spring.png?branch=master)](https://travis-ci.org/rails/spring)
+[![Gem Version](https://badge.fury.io/rb/spring.png)](http://badge.fury.io/rb/spring)
 
 Spring is a Rails application preloader. It speeds up development by
 keeping your application running in the background so you don't need to
@@ -15,24 +16,50 @@ boot it every time you run a test, rake task or migration.
 
 ## Compatibility
 
-* Ruby versions: MRI 1.9.3, MRI 2.0.0
+* Ruby versions: MRI 1.9.3, MRI 2.0, MRI 2.1
 * Rails versions: 3.2, 4.0
 
-Spring makes extensive use of `Process#fork`, so won't be able to
+Spring makes extensive use of `Process.fork`, so won't be able to
 provide a speed up on platforms which don't support forking (Windows, JRuby).
 
 ## Walkthrough
 
-Either `gem install spring` or add it to your Gemfile:
+### Setup
+
+Add spring to your Gemfile:
 
 ``` ruby
-group :development do
-  gem "spring"
+gem "spring", group: :development
+```
+
+It's recommended to 'springify' the executables in your `bin/`
+directory:
+
+```
+$ bundle install
+$ bundle exec spring binstub --all
+```
+
+This generates a `bin/spring` executable, and inserts a small snippet of
+code into relevant existing executables. The snippet looks like this:
+
+``` ruby
+begin
+  load File.expand_path("../spring", __FILE__)
+rescue LoadError
 end
 ```
 
-Spring is designed to be used *without* bundle exec, so use `spring
-[command]` rather than `bundle exec spring [command]`.
+On platforms where spring is installed and supported, this snippet
+hooks spring into the execution of commands. In other cases, the snippet
+will just be silently ignored and the lines after it will be executed as
+normal.
+
+If you don't want to prefix every command you type with `bin/`, you
+can [use direnv](https://github.com/zimbatm/direnv) to automatically add
+`./bin` to your `PATH` when you `cd` into your application.
+
+### Usage
 
 For this walkthrough I've generated a new Rails application, and run
 `rails generate scaffold posts name:string`.
@@ -40,7 +67,7 @@ For this walkthrough I've generated a new Rails application, and run
 Let's run a test:
 
 ```
-$ time spring rake test test/functional/posts_controller_test.rb
+$ time bin/rake test test/functional/posts_controller_test.rb
 Run options:
 
 # Running tests:
@@ -60,7 +87,7 @@ That wasn't particularly fast because it was the first run, so spring
 had to boot the application. It's now running:
 
 ```
-$ spring status
+$ bin/spring status
 Spring is running:
 
 26150 spring server | spring-demo-app | started 3 secs ago
@@ -70,7 +97,7 @@ Spring is running:
 The next run is faster:
 
 ```
-$ time spring rake test test/functional/posts_controller_test.rb
+$ time bin/rake test test/functional/posts_controller_test.rb
 Run options:
 
 # Running tests:
@@ -86,20 +113,6 @@ user    0m0.276s
 sys     0m0.059s
 ```
 
-Writing `spring` before every command gets a bit tedious. Spring binstubs solve this:
-
-```
-$ spring binstub rake rails
-```
-
-This will generate `bin/rake` and `bin/rails`. They
-replace any binstubs that you might already have in your `bin/`
-directory. Check them in to source control.
-
-If you don't want to prefix every command you type with `bin/`, you
-can [use direnv](https://github.com/zimbatm/direnv) to automatically add
-`./bin` to your `PATH` when you `cd` into your application.
-
 If we edit any of the application files, or test files, the changes will
 be picked up on the next run without the background process having to
 restart. This works in exactly the same way as the code reloading
@@ -114,7 +127,7 @@ Let's "edit" `config/application.rb`:
 
 ```
 $ touch config/application.rb
-$ spring status
+$ bin/spring status
 Spring is running:
 
 26150 spring server | spring-demo-app | started 36 secs ago
@@ -137,7 +150,7 @@ edit_post GET    /posts/:id/edit(.:format) posts#edit
           PUT    /posts/:id(.:format)      posts#update
           DELETE /posts/:id(.:format)      posts#destroy
 
-$ spring status
+$ bin/spring status
 Spring is running:
 
 26150 spring server | spring-demo-app | started 1 min ago
@@ -150,25 +163,18 @@ when you close your terminal. However if you do want to do a manual shut
 down, use the `stop` command:
 
 ```
-$ spring stop
+$ bin/spring stop
 Spring stopped.
 ```
 
-## Commands
-
-The following commands are shipped by default.
+### Removal
 
-Custom commands can be specified in the Spring config file. See
-[`lib/spring/commands/`](https://github.com/jonleighton/spring/blob/master/lib/spring/commands/)
-for examples.
+To remove spring:
 
-You can add the following gems to your Gemfile for additional commands:
+* 'Unspring' your bin/ executables: `bin/spring binstub --remove --all`
+* Remove spring from your Gemfile
 
-* [spring-commands-rspec](https://github.com/jonleighton/spring-commands-rspec)
-* [spring-commands-cucumber](https://github.com/jonleighton/spring-commands-cucumber)
-* [spring-commands-testunit](https://github.com/jonleighton/spring-commands-testunit) - useful for
-  running `Test::Unit` tests on Rails 3, since only Rails 4 allows you
-  to use `rake test path/to/test` to run a particular test/directory.
+## Commands
 
 ### `rake`
 
@@ -194,6 +200,74 @@ a different sub command (e.g. `rails server`) then spring will automatically
 pass it through to the underlying `rails` executable (without the
 speed-up).
 
+### Additional commands
+
+You can add these to your Gemfile for additional commands (run `spring stop` afterwards
+to pick up the changes):
+
+* [spring-commands-rspec](https://github.com/jonleighton/spring-commands-rspec)
+* [spring-commands-cucumber](https://github.com/jonleighton/spring-commands-cucumber)
+* [spring-commands-testunit](https://github.com/jonleighton/spring-commands-testunit) - useful for
+  running `Test::Unit` tests on Rails 3, since only Rails 4 allows you
+  to use `rake test path/to/test` to run a particular test/directory.
+
+## Use without adding to bundle
+
+If you don't want spring-related code checked into your source
+repository, it's possible to use spring without adding to your Gemfile.
+However, using spring binstubs without adding spring to the Gemfile is not
+supported.
+
+To use spring like this, do a `gem install spring` and then prefix
+commands with `spring`. For example, rather than running `bin/rake -T`,
+you'd run `spring rake -T`.
+
+## Temporarily disabling Spring
+
+If you're using Spring binstubs, but temporarily don't want commands to
+run through Spring, set the `DISABLE_SPRING` environment variable.
+
+## Class reloading
+
+Spring uses Rails' class reloading mechanism
+(`ActiveSupport::Dependencies`) to keep your code up to date between
+test runs. This is the same mechanism which allows you to see changes
+during development when you refresh the page. However, you may never
+have used this mechanism with your `test` environment before, and this
+can cause problems.
+
+It's important to realise that code reloading means that the constants
+in your application are *different objects* after files have changed:
+
+```
+$ bin/rails runner 'puts User.object_id'
+70127987886040
+$ touch app/models/user.rb
+$ bin/rails runner 'puts User.object_id'
+70127976764620
+```
+
+Suppose you have an initializer `config/initializers/save_user_class.rb`
+like so:
+
+``` ruby
+USER_CLASS = User
+```
+
+This saves off the *first* version of the `User` class, which will not
+be the same object as `User` after the code has been reloaded:
+
+```
+$ bin/rails runner 'puts User == USER_CLASS'
+true
+$ touch app/models/user.rb
+$ bin/rails runner 'puts User == USER_CLASS'
+false
+```
+
+So to avoid this problem, don't save off references to application
+constants in your initialization code.
+
 ## Configuration
 
 Spring will read `~/.spring.rb` and `config/spring.rb` for custom
@@ -222,11 +296,6 @@ which get run when your application initializers, such as
 `config/application.rb`, `config/environments/*.rb` or
 `config/initializers/*.rb`.
 
-For example, if loading your test helper is slow, you might like to
-preload it to speed up your test runs. To do this you could put a
-`require Rails.root.join("test/helper")` in
-`config/environments/test.rb`.
-
 ### Running code after forking
 
 You might want to run code after Spring forked off the process but

data/bin/spring

@@ -21,6 +21,7 @@ if defined?(Gem)
 
     if unstubbed.any?
       warn "Warning: Running `gem pristine --all` to regenerate your installed gemspecs " \
+           "(and deleting then reinstalling your bundle if you use bundle --path) " \
            "will improve the startup performance of Spring."
     end
   end

data/lib/spring/application/boot.rb

@@ -0,0 +1,16 @@
+require "spring/application"
+
+app = Spring::Application.new(
+  UNIXSocket.for_fd(3),
+  Spring::JSON.load(ENV.delete("SPRING_ORIGINAL_ENV").dup)
+)
+
+Signal.trap("TERM") { app.terminate }
+Signal.trap("TTOU", "IGNORE")
+
+Spring::ProcessTitleUpdater.run { |distance|
+  "spring app    | #{app.app_name} | started #{distance} ago | #{app.app_env} mode"
+}
+
+app.preload if ENV.delete("SPRING_PRELOAD") == "1"
+app.run

data/lib/spring/application.rb

@@ -1,41 +1,83 @@
+require "spring/boot"
 require "set"
-require "spring/watcher"
-require "thread"
 
 module Spring
   class Application
-    attr_reader :manager, :watcher, :spring_env
+    attr_reader :manager, :watcher, :spring_env, :original_env
+
+    def initialize(manager, original_env)
+      @manager      = manager
+      @original_env = original_env
+      @spring_env   = Env.new
+      @mutex        = Mutex.new
+      @waiting      = 0
+      @preloaded    = false
+      @state        = :initialized
+      @interrupt    = IO.pipe
+    end
+
+    def state(val)
+      return if exiting?
+      log "#{@state} -> #{val}"
+      @state = val
+    end
 
-    def initialize(manager, watcher = Spring.watcher)
-      @manager    = manager
-      @watcher    = watcher
-      @setup      = Set.new
-      @spring_env = Env.new
-      @preloaded  = false
-      @mutex      = Mutex.new
-      @waiting    = 0
-      @exiting    = false
+    def state!(val)
+      state val
+      @interrupt.last.write "."
+    end
+
+    def app_env
+      ENV['RAILS_ENV']
+    end
 
-      # Workaround for GC bug in Ruby 2 which causes segfaults if watcher.to_io
-      # instances get dereffed.
-      @fds = [manager, watcher.to_io]
+    def app_name
+      spring_env.app_name
     end
 
     def log(message)
-      spring_env.log "[application:#{ENV['RAILS_ENV']}] #{message}"
+      spring_env.log "[application:#{app_env}] #{message}"
     end
 
     def preloaded?
       @preloaded
     end
 
+    def preload_failed?
+      @preloaded == :failure
+    end
+
     def exiting?
-      @exiting
+      @state == :exiting
+    end
+
+    def terminating?
+      @state == :terminating
+    end
+
+    def watcher_stale?
+      @state == :watcher_stale
+    end
+
+    def initialized?
+      @state == :initialized
+    end
+
+    def start_watcher
+      @watcher = Spring.watcher
+      @watcher.on_stale { state! :watcher_stale }
+      @watcher.start
     end
 
     def preload
       log "preloading app"
 
+      begin
+        require "spring/commands"
+      ensure
+        start_watcher
+      end
+
       require Spring.application_root_path.join("config", "application")
 
       # config/environments/test.rb will have config.cache_classes = true. However
@@ -51,44 +93,42 @@ module Spring
       Rails.application.config.cache_classes = false
       disconnect_database
 
+      @preloaded = :success
+    rescue Exception => e
+      @preloaded = :failure
+      watcher.add e.backtrace.map { |line| line.match(/^(.*)\:\d+\:in /)[1] }
+      raise e unless initialized?
+    ensure
       watcher.add loaded_application_features
       watcher.add Spring.gemfile, "#{Spring.gemfile}.lock"
-      watcher.add Rails.application.paths["config/initializers"]
 
-      @preloaded = true
+      if defined?(Rails)
+        watcher.add Rails.application.paths["config/initializers"]
+        watcher.add Rails.application.paths["config/database"]
+      end
     end
 
     def run
-      log "running"
-      watcher.start
+      state :running
+      manager.puts
 
       loop do
-        IO.select(@fds)
-
-        if watcher.stale?
-          log "watcher stale; exiting"
-          manager.close
-          @exiting = true
-          try_exit
-          sleep
+        IO.select [manager, @interrupt.first]
+
+        if terminating? || watcher_stale? || preload_failed?
+          exit
         else
           serve manager.recv_io(UNIXSocket)
         end
       end
     end
 
-    def try_exit
-      @mutex.synchronize {
-        exit if exiting? && @waiting == 0
-      }
-    end
-
     def serve(client)
       log "got client"
       manager.puts
 
-      streams = 3.times.map { client.recv_io }
-      [STDOUT, STDERR].zip(streams).each { |a, b| a.reopen(b) }
+      stdout, stderr, stdin = streams = 3.times.map { client.recv_io }
+      [STDOUT, STDERR].zip([stdout, stderr]).each { |a, b| a.reopen(b) }
 
       preload unless preloaded?
 
@@ -105,33 +145,30 @@ module Spring
 
       pid = fork {
         Process.setsid
-        STDIN.reopen(streams.last)
+        STDIN.reopen(stdin)
         IGNORE_SIGNALS.each { |sig| trap(sig, "DEFAULT") }
+        trap("TERM", "DEFAULT")
 
         ARGV.replace(args)
+        $0 = command.process_title
 
         # Delete all env vars which are unchanged from before spring started
-        Spring.original_env.each { |k, v| ENV.delete k if ENV[k] == v }
+        original_env.each { |k, v| ENV.delete k if ENV[k] == v }
 
         # Load in the current env vars, except those which *were* changed when spring started
         env.each { |k, v| ENV[k] ||= v }
 
+        # requiring is faster, and we don't need constant reloading in this process
+        ActiveSupport::Dependencies.mechanism = :require
+        Rails.application.config.cache_classes = true
+
         connect_database
         srand
 
         invoke_after_fork_callbacks
         shush_backtraces
 
-        if command.respond_to?(:call)
-          command.call
-        else
-          exec_name = command.exec_name
-          gem_name  = command.gem_name if command.respond_to?(:gem_name)
-
-          exec = Gem.bin_path(gem_name || exec_name, exec_name)
-          $0 = exec
-          load exec
-        end
+        command.call
       }
 
       disconnect_database
@@ -152,26 +189,44 @@ module Spring
         client.close
 
         @mutex.synchronize { @waiting -= 1 }
-        try_exit
+        exit_if_finished
       }
 
-    rescue => e
+    rescue Exception => e
       log "exception: #{e}"
-      streams.each(&:close) if streams
-      client.puts(1)
+      manager.puts unless pid
+
+      if streams && !e.is_a?(SystemExit)
+        print_exception(stderr, e)
+        streams.each(&:close)
+      end
+
+      client.puts(1) if pid
       client.close
-      raise
+    end
+
+    def terminate
+      state! :terminating
+    end
+
+    def exit
+      state :exiting
+      manager.shutdown(:RDWR)
+      exit_if_finished
+      sleep
+    end
+
+    def exit_if_finished
+      @mutex.synchronize {
+        Kernel.exit if exiting? && @waiting == 0
+      }
     end
 
     # The command might need to require some files in the
     # main process so that they are cached. For example a test command wants to
     # load the helper file once and have it cached.
     def setup(command)
-      return if @setup.include?(command.class)
-      @setup << command.class
-
-      if command.respond_to?(:setup)
-        command.setup
+      if command.setup
         watcher.add loaded_application_features # loaded features may have changed
       end
     end
@@ -183,7 +238,8 @@ module Spring
     end
 
     def loaded_application_features
-      $LOADED_FEATURES.select { |f| f.start_with?(File.realpath(Rails.root)) }
+      root = Spring.application_root_path.to_s
+      $LOADED_FEATURES.select { |f| f.start_with?(root) }
     end
 
     def disconnect_database
@@ -211,5 +267,11 @@ module Spring
         end
       end
     end
+
+    def print_exception(stream, error)
+      first, rest = error.backtrace.first, error.backtrace.drop(1)
+      stream.puts("#{first}: #{error} (#{error.class})")
+      rest.each { |line| stream.puts("\tfrom #{line}") }
+    end
   end
 end