oop_rails_server 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
---- 
-SHA1: 
-  metadata.gz: 84afb8fd45ac3c486c2a4ac5437cf49053f210e7
-  data.tar.gz: dc945d5c3630894bf4577d74cae750af674bdf3f
-SHA512: 
-  metadata.gz: 513409b059ea373c7f83b9c3749b7b5205287c2c869019e434f3565ce8f68b435259e3d2515a464a6032cf480309182abb24bb3a7b366744e2fbbcfae9cfc223
-  data.tar.gz: d3433fb5c40f94877cfb20a8aca1ee0011b50c2d9c2885b540d3db322a4e12d9e276261b07fa49a19f05c862492c5b596d4fd26abf71c60e6ed0129b53a15cdc
+---
+SHA1:
+  metadata.gz: 26ef5c7bd3dcc6dc6bf29ad377c4397b510193d6
+  data.tar.gz: 230c9d20af081ce7885dc1300d6056ccbff7fba2
+SHA512:
+  metadata.gz: 05c44883c4416fed68f128d239059d28e05b2ccc596ab3b1364a6220144cbe1c62af9f4c5754b565baddabb6a52fba75a0297ce2a1ef6b15624b4d68c37c8577
+  data.tar.gz: 178c4199b58ea6e0eebb41f850be0716ecfea1df09e212785bd7adbc1650bd1c904155bd4b8c7ae13187666a0af6d1d5a2957a3dab81145eb47a4018dbf4dd77

data/CHANGES.md

@@ -1,5 +1,16 @@
 # `oop_rails_server` Releases
 
+## 0.0.8, 3 April 2015
+
+* Much better error reporting if the server fails to start up.
+* Add `OopRailsServer::RailsServer#setup!`, which configures everything properly but does not actually start
+  the out-of-process Rails server yet.
+* Allow passing paths or full URIs into `OopRailsServer::RailsServer#get`, as well as passing a separate Hash
+  of query values.
+* Move question of which templates to use out of `OopRailsServer::Helpers` and into `OopRailsServer::RailsServer`.
+* Save away the actual exact versions of Rails and Ruby being used, as well as the `RUBY_ENGINE`, and allow callers
+  to access them easily.
+
 ## 0.0.7, 21 January 2015
 
 * Further fixes for the `i18n` gem version `0.7.0`.

data/README.md

@@ -1,6 +1,28 @@
 # OopRailsServer
 
-TODO: Write a gem description
+Rails makes it easy enough to write test code or RSpec that runs _within_ Rails. However, what’s much, much harder
+is testing code (like a RubyGem) that augments Rails itself, particularly if you want that code to be compatible
+with multiple versions of Rails. Often people will simply check in a full Rails tree (_i.e._, that which is generated
+by `rails new`), but that fixes you to an exact version of Rails and is difficult to upgrade or manipulate.
+
+`OopRailsServer` provides a completely different, much cleaner solution: it provides an object,
+`OopRailsServer::RailsServer`. This object knows how to:
+
+* Install any version of Rails from scratch, completely cleanly (_i.e._, the equivalent of `gem install rails -v=4.2.0`);
+* Use that version of Rails to create a new Rails installation (_i.e._, `rails _4.2.0_ new`);
+* Add any lines you want to the resulting Rails Gemfile, and run `bundle install` (so that any gems you want —
+  for example, the gem you’re testing — are available to that Rails installation);
+* Populate that installation by using one or more "template directories" that you provide — each template directory
+  is laid out exactly like a standard Rails tree (but need contain only files you actually want to provide), and will
+  overwrite the corresponding files in the Rails tree
+* Spin up a new Rails server, running on a randomly-assigned port, in that Rails installation;
+* Fetch arbitrary URLs from that Rails server on your command;
+* When it’s all done, safely (and reliably) terminate that server.
+
+As of this writing, this gem is not fully productized: while it works reliably, there is insufficient documentation
+to easily use it yourself. It is, however, very reliable: it is used as the backbone of the test suites for
+[`fortitude`](https://github.com/ageweke/fortitude), [`parcels`](https://github.com/ageweke/parcels), and the
+backbone of the real work in [`rails_view_benchmarks`](https://github.com/ageweke/rails_view_benchmarks).
 
 ## Installation
 

data/lib/oop_rails_server/helpers.rb

@@ -152,12 +152,6 @@ it should return the fully-qualified path to the root of your project (gem, appl
       end
     end
 
-    def oop_rails_server_base_templates
-      [
-        File.expand_path(File.join(File.dirname(__FILE__), '../../templates/oop_rails_server_base'))
-      ]
-    end
-
     def rails_server_implicit_template_paths
       [ ]
     end
@@ -185,7 +179,6 @@ it should return the fully-qualified path to the root of your project (gem, appl
       server = rails_servers[name]
       server ||= begin
         templates =
-          oop_rails_server_base_templates +
           rails_server_implicit_template_paths +
           templates
 

data/lib/oop_rails_server/rails_server.rb

@@ -2,21 +2,24 @@ require 'fileutils'
 require 'find'
 require 'net/http'
 require 'uri'
+require 'file/tail'
 
 module OopRailsServer
   class RailsServer
-    attr_reader :rails_root, :rails_version, :name
+    attr_reader :rails_root, :rails_version, :name, :actual_rails_version, :actual_ruby_version, :actual_ruby_engine
 
     def initialize(options)
       options.assert_valid_keys(
         :name, :template_paths, :runtime_base_directory,
-        :rails_version, :rails_env, :additional_gemfile_lines
+        :rails_version, :rails_env, :additional_gemfile_lines,
+        :log, :verbose
       )
 
       @name = options[:name] || raise(ArgumentError, "You must specify a name for the Rails server")
 
       @template_paths = options[:template_paths] || raise(ArgumentError, "You must specify one or more template paths")
       @template_paths = Array(@template_paths).map { |t| File.expand_path(t) }
+      @template_paths = base_template_directories + @template_paths
 
       @runtime_base_directory = options[:runtime_base_directory] || raise(ArgumentError, "You must specify a runtime_base_directory")
       @runtime_base_directory = File.expand_path(@runtime_base_directory)
@@ -24,6 +27,9 @@ module OopRailsServer
       @rails_version = options[:rails_version] || :default
       @rails_env = (options[:rails_env] || 'production').to_s
 
+      @log = options[:log] || $stderr
+      @verbose = options.fetch(:verbose, true)
+
       @additional_gemfile_lines = Array(options[:additional_gemfile_lines] || [ ])
 
 
@@ -36,22 +42,61 @@ module OopRailsServer
       do_start! unless server_pid
     end
 
+    def setup!
+      @set_up ||= begin
+        Bundler.with_clean_env do
+          with_rails_env do
+            setup_directories!
+
+            in_rails_root_parent do
+              splat_bootstrap_gemfile!
+              rails_new!
+              update_gemfile!
+            end
+
+            in_rails_root do
+              run_bundle_install!(:primary)
+              splat_template_files!
+            end
+          end
+        end
+
+        true
+      end
+    end
+
     def stop!
       stop_server! if server_pid
     end
 
-    def get(path, options = { })
-      out = get_response(path, options)
+    def get(path_or_uri, options = { })
+      out = get_response(path_or_uri, options)
       out.body.strip if out
     end
 
-    def uri_for(path)
-      uri_string = "http://localhost:#{@port}/#{path}"
-      URI.parse(uri_string)
+    def uri_for(path_or_uri, query_values = nil)
+      query_values ||= { }
+
+      if path_or_uri.kind_of?(::URI)
+        path_or_uri
+      else
+        uri_string = "http://#{localhost_name}:#{@port}/#{path_or_uri}"
+        if query_values.length > 0
+          uri_string += ("?" + query_values.map { |k,v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" }.join("&"))
+        end
+        URI.parse(uri_string)
+      end
+    end
+
+    def localhost_name
+      "127.0.0.1"
     end
 
-    def get_response(path, options = { })
-      uri = uri_for(path)
+    def get_response(path_or_uri, options = { })
+      options.assert_valid_keys(:ignore_status_code, :nil_on_not_found, :query, :no_layout)
+
+      uri = uri_for(path_or_uri, options[:query])
+      # say "[fetch '#{uri}']"
       data = Net::HTTP.get_response(uri)
 
       if (data.code.to_s != '200')
@@ -79,22 +124,20 @@ module OopRailsServer
     private
     attr_reader :template_paths, :runtime_base_directory, :rails_env, :additional_gemfile_lines, :port, :server_pid
 
+    def base_template_directories
+      [
+        File.expand_path(File.join(File.dirname(__FILE__), '../../templates/oop_rails_server_base'))
+      ]
+    end
+
     def do_start!
+      setup!
+
       Bundler.with_clean_env do
         with_rails_env do
-          setup_directories!
-
-          in_rails_root_parent do
-            splat_bootstrap_gemfile!
-            rails_new!
-            update_gemfile!
-          end
-
           in_rails_root do
-            run_bundle_install!(:primary)
-            splat_template_files!
             start_server!
-            verify_server!
+            verify_server_and_shut_down_if_fails!
           end
         end
       end
@@ -174,6 +217,7 @@ EOS
       gemfile_contents << "\ngem 'execjs', '~> 2.0.0'\n" if RUBY_VERSION =~ /^1\.8\./
 
       gemfile_contents << additional_gemfile_lines.join("\n")
+      gemfile_contents << "\n"
 
       File.open(gemfile, 'w') { |f| f << gemfile_contents }
     end
@@ -218,8 +262,12 @@ EOS
       end
     end
 
+    def server_output_file
+      @server_output_file ||= File.join(rails_root, 'log', 'rails-server.out')
+    end
+
     def start_server!
-      output = File.join(rails_root, 'log', 'rails-server.out')
+      output = server_output_file
       cmd = "rails server -p #{port} > '#{output}' 2>&1"
       safe_system(cmd, "starting 'rails server' on port #{port}", :background => true)
 
@@ -238,8 +286,58 @@ EOS
       end
     end
 
+    def verify_server_and_shut_down_if_fails!
+      begin
+        verify_server!
+      rescue Exception => e
+        begin
+          stop_server!
+        rescue Exception => e
+          say "WARNING: Verification of server failed, so we tried to stop it, but we couldn't do that. Proceeding, but you may have a Rails server left around anyway..."
+        end
+
+        raise
+      end
+    end
+
+    class FailedStartupError < StandardError
+      attr_reader :timeout, :verify_exception, :server_logfile, :last_lines
+
+      def initialize(timeout, verify_exception, server_logfile, last_lines)
+        message = %{The out-of-process Rails server failed to start up properly and start responding to requests,
+even after #{timeout.round} seconds. This typically means you've added code that prevents it from
+even starting up -- most likely, a syntax error in a class or other error that stops it
+dead in its tracks. (oop_rails_server starts up Rails servers in the production environment
+by default, and, in production, Rails eagerly loads all classes at startup time.)}
+
+        if server_logfile
+          message << %{
+
+Any errors will be located in the stdout/stderr of the Rails process, which is at:
+  '#{server_logfile}'}
+        end
+
+        if last_lines
+          message << %{
+
+The last #{last_lines.length} lines of this log are:
+
+#{last_lines.join("\n")}}
+        end
+
+        super(message)
+
+        @timeout = timeout
+        @verify_exception = verify_exception
+        @server_logfile = server_logfile
+        @last_lines = last_lines
+      end
+    end
+
+    SERVER_VERIFY_TIMEOUT = 5
+
     def verify_server!
-      server_verify_url = "http://localhost:#{port}/working/rails_is_working"
+      server_verify_url = "http://#{localhost_name}:#{port}/working/rails_is_working"
       uri = URI.parse(server_verify_url)
 
       data = nil
@@ -247,8 +345,24 @@ EOS
       while (! data)
         begin
           data = Net::HTTP.get_response(uri)
-        rescue Errno::ECONNREFUSED, EOFError
-          raise if Time.now > (start_time + 20)
+        rescue Errno::ECONNREFUSED, EOFError => e
+          if Time.now > (start_time + SERVER_VERIFY_TIMEOUT)
+            last_lines = server_logfile = nil
+            if File.exist?(server_output_file) && File.readable?(server_output_file)
+              server_logfile = server_output_file
+              File::Tail::Logfile.open(server_output_file, :break_if_eof => true) do |f|
+                f.extend(File::Tail)
+                last_lines ||= [ ]
+                begin
+                  f.tail(100) { |l| last_lines << l }
+                rescue File::Tail::BreakException
+                  # ok
+                end
+              end
+            end
+
+            raise FailedStartupError.new(Time.now - start_time, e, server_logfile, last_lines)
+          end
           # keep waiting
           sleep 0.1
         end
@@ -259,17 +373,22 @@ EOS
       end
       result = data.body.strip
 
-      unless result =~ /^Rails\s+version\s*:\s*(\d+\.\d+\.\d+)\n+Ruby\s+version\s*:\s*(\d+\..*?)\s*$/
+      unless result =~ /^Rails\s+version\s*:\s*(\d+\.\d+\.\d+)\s*\n+\s*Ruby\s+version\s*:\s*(\d+\..*?)\s*\n+\s*Ruby\s+engine:\s*(.*?)\s*\n?$/mi
         raise "'#{server_verify_url}' returned: #{result.inspect}"
       end
       actual_version = $1
       ruby_version = $2
+      ruby_engine = $3
 
       if rails_version != :default && (actual_version != rails_version)
         raise "We seem to have spawned the wrong version of Rails; wanted: #{rails_version.inspect} but got: #{actual_version.inspect}"
       end
 
-      say "Successfully spawned a server running Rails #{actual_version} (Ruby #{ruby_version}) on port #{port}."
+      @actual_rails_version = actual_version
+      @actual_ruby_version = ruby_version
+      @actual_ruby_engine = ruby_engine
+
+      say "Successfully spawned a server running Rails #{actual_version} (Ruby #{ruby_version}, engine #{ruby_engine.inspect}) on port #{port}."
     end
 
     def is_alive?(pid)
@@ -379,12 +498,14 @@ and output:
     end
 
     def say(s, newline = true)
-      if newline
-        $stdout.puts s
-      else
-        $stdout << s
+      if @verbose
+        if newline
+          @log.puts s
+        else
+          @log << s
+        end
+        @log.flush
       end
-      $stdout.flush
     end
 
     def safe_system(cmd, notice = nil, options = { })

data/lib/oop_rails_server/version.rb

@@ -1,3 +1,3 @@
 module OopRailsServer
-  VERSION = "0.0.7"
+  VERSION = "0.0.8"
 end

data/oop_rails_server.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency 'json'
+  spec.add_dependency 'file-tail'
 
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake", "~> 10.0"

data/templates/oop_rails_server_base/app/controllers/working_controller.rb

@@ -1,5 +1,5 @@
 class WorkingController < ApplicationController
   def rails_is_working
-    render :text => "Rails version: #{Rails.version}\nRuby version: #{RUBY_VERSION}"
+    render :text => "Rails version: #{Rails.version}\nRuby version: #{RUBY_VERSION}\nRuby engine: #{RUBY_ENGINE}\n"
   end
 end

metadata

@@ -1,58 +1,79 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: oop_rails_server
-version: !ruby/object:Gem::Version 
-  version: 0.0.7
+version: !ruby/object:Gem::Version
+  version: 0.0.8
 platform: ruby
-authors: 
+authors:
 - Andrew Geweke
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2015-01-22 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2015-04-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
   prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    requirements: 
-    - &id004 
-      - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: file-tail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: bundler
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        version: "1.6"
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
   type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rake
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        version: "10.0"
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
   type: :development
-  version_requirements: *id003
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
 description: 
-email: 
+email:
 - andrew@geweke.org
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
-- .gitignore
+files:
+- ".gitignore"
 - CHANGES.md
 - Gemfile
 - LICENSE.txt
@@ -69,27 +90,28 @@ files:
 - templates/oop_rails_server_base/config/routes.rb
 - templates/oop_rails_server_base/config/secrets.yml
 homepage: https://github.com/ageweke/oop_rails_server
-licenses: 
+licenses:
 - MIT
 metadata: {}
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - *id004
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - *id004
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
 rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
-summary: Reliably runs a Rails server in a separate process, for use in tests, utilities, etc.
+summary: Reliably runs a Rails server in a separate process, for use in tests, utilities,
+  etc.
 test_files: []
-