awesome_spawn 1.1.1 → 1.2.0

data/lib/awesome_spawn.rb

@@ -1,9 +1,10 @@
 require "awesome_spawn/version"
+require "awesome_spawn/command_line_builder"
 require "awesome_spawn/command_result"
 require "awesome_spawn/command_result_error"
 require "awesome_spawn/no_such_file_error"
 
-require "shellwords"
+require "open3"
 
 module AwesomeSpawn
   extend self
@@ -61,18 +62,14 @@ module AwesomeSpawn
     params  = options.delete(:params)
     in_data = options.delete(:in_data)
 
-    output        = ""
-    error         = ""
-    status        = nil
-    command_line  = build_command_line(command, params)
+    output, error, status = "", "", nil
+    command_line = build_command_line(command, params)
 
     begin
-      output, error = launch(command_line, in_data, options)
-      status = exitstatus
+      output, error, status = launch(command_line, in_data, options)
     ensure
       output ||= ""
       error  ||= ""
-      self.exitstatus = nil
     end
   rescue Errno::ENOENT => err
     raise NoSuchFileError.new(err.message) if NoSuchFileError.detected?(err.message)
@@ -103,109 +100,17 @@ module AwesomeSpawn
     command_result
   end
 
-  # Build the full command line.
-  #
-  # @param [String] command The command to run
-  # @param [Hash,Array] params Optional command line parameters. They can
-  #   be passed as a Hash or associative Array. The values are sanitized to
-  #   prevent command line injection.  Keys as symbols are prefixed with `--`,
-  #   and `_` is replaced with `-`.
-  #
-  #   - `{:key => "value"}`            generates `--key value`
-  #   - `{"--key" => "value"}`         generates `--key value`
-  #   - `{:key= => "value"}`           generates `--key=value`
-  #   - `{"--key=" => "value"}`        generates `--key=value`
-  #   - `{:key_name => "value"}`       generates `--key-name value`
-  #   - `{:key => nil}`                generates `--key`
-  #   - `{"-f" => ["file1", "file2"]}` generates `-f file1 file2`
-  #   - `{nil => ["file1", "file2"]}`  generates `file1 file2`
-  #
-  # @return [String] The full command line
+  # (see CommandLineBuilder#build)
   def build_command_line(command, params = nil)
-    return command.to_s if params.nil? || params.empty?
-    "#{command} #{assemble_params(sanitize(params))}"
+    CommandLineBuilder.new.build(command, params)
   end
 
   private
 
-  def sanitize(params)
-    return [] if params.nil? || params.empty?
-    params.collect do |k, v|
-      [sanitize_key(k), sanitize_value(v)]
-    end
-  end
-
-  def sanitize_key(key)
-    case key
-    when Symbol then "--#{key.to_s.tr("_", "-")}"
-    else             key
-    end
-  end
-
-  def sanitize_value(value)
-    case value
-    when Array    then value.collect { |i| i.to_s.shellescape }
-    when NilClass then value
-    else               value.to_s.shellescape
-    end
-  end
-
-  def assemble_params(sanitized_params)
-    sanitized_params.collect do |pair|
-      pair_joiner = pair.first.to_s.end_with?("=") ? "" : " "
-      pair.flatten.compact.join(pair_joiner)
-    end.join(" ")
-  end
-
-  # IO pipes have a maximum size of 64k before blocking,
-  # so we need to read and write synchronously.
-  # http://stackoverflow.com/questions/13829830/ruby-process-spawn-stdout-pipe-buffer-size-limit/13846146#13846146
-  THREAD_SYNC_KEY = "#{self.name}-exitstatus"
-
   def launch(command, in_data, spawn_options = {})
-    out_r, out_w = IO.pipe
-    err_r, err_w = IO.pipe
-    in_r,  in_w  = IO.pipe if in_data
-
-    spawn_options[:out] = out_w
-    spawn_options[:err] = err_w
-    spawn_options[:in]  = in_r if in_data
-
-    pid = Kernel.spawn(command, spawn_options)
-
-    write_to_input(in_w, in_data) if in_data
-    wait_for_process(pid, out_w, err_w, in_r)
-    wait_for_pipes(out_r, err_r)
-  end
-
-  def write_to_input(in_w, in_data)
-    in_w.write(in_data)
-    in_w.close
-  end
-
-  def wait_for_process(pid, out_w, err_w, in_r)
-    self.exitstatus = :not_done
-    Thread.new(Thread.current) do |parent_thread|
-      _, status = Process.wait2(pid)
-      out_w.close
-      err_w.close
-      in_r.close if in_r
-      parent_thread[THREAD_SYNC_KEY] = status.exitstatus
-    end
-  end
-
-  def wait_for_pipes(out_r, err_r)
-    out = out_r.read
-    err = err_r.read
-    sleep(0.1) while exitstatus == :not_done
-    return out, err
-  end
-
-  def exitstatus
-    Thread.current[THREAD_SYNC_KEY]
-  end
-
-  def exitstatus=(value)
-    Thread.current[THREAD_SYNC_KEY] = value
+    spawn_options = spawn_options.merge(:stdin_data => in_data) if in_data
+    output, error, status = Open3.capture3(command, spawn_options)
+    status &&= status.exitstatus
+    return output, error, status
   end
 end

data/lib/awesome_spawn/command_line_builder.rb

@@ -0,0 +1,107 @@
+require "shellwords"
+
+module AwesomeSpawn
+  class CommandLineBuilder
+    # Build the full command line.
+    #
+    # @param [String] command The command to run
+    # @param [Hash,Array] params Optional command line parameters. They can
+    #   be passed as a Hash or associative Array. The values are sanitized to
+    #   prevent command line injection.  Keys as Symbols are prefixed with `--`,
+    #   and `_` is replaced with `-`.
+    #
+    #   - `{:key => "value"}`            generates `--key value`
+    #   - `[[:key, "value"]]`            generates `--key value`
+    #   - `{:key= => "value"}`           generates `--key=value`
+    #   - `[[:key=, "value"]]`           generates `--key=value` <br /><br />
+    #
+    #   - `{"--key" => "value"}`         generates `--key value`
+    #   - `[["--key", "value"]]`         generates `--key value`
+    #   - `{"--key=" => "value"}`        generates `--key=value`
+    #   - `[["--key=", "value"]]`        generates `--key=value` <br /><br />
+    #
+    #   - `{:key_name => "value"}`       generates `--key-name value`
+    #   - `[[:key_name, "value"]]`       generates `--key-name value`
+    #   - `{:key_name= => "value"}`       generates `--key-name=value`
+    #   - `[[:key_name=, "value"]]`       generates `--key-name=value` <br /><br />
+    #
+    #   - `{"-f" => ["file1", "file2"]}` generates `-f file1 file2`
+    #   - `[["-f", "file1", "file2"]]`   generates `-f file1 file2` <br /><br />
+    #
+    #   - `{:key => nil}`                generates `--key`
+    #   - `[[:key, nil]]`                generates `--key`
+    #   - `[[:key]]`                     generates `--key` <br /><br />
+    #
+    #   - `{nil => ["file1", "file2"]}`  generates `file1 file2`
+    #   - `[[nil, ["file1", "file2"]]]`  generates `file1 file2`
+    #   - `[[nil, "file1", "file2"]]`    generates `file1 file2`
+    #   - `[["file1", "file2"]]`         generates `file1 file2`
+    #
+    # @return [String] The full command line
+    def build(command, params = nil)
+      params = assemble_params(sanitize(params))
+      params.empty? ? command.to_s : "#{command} #{params}"
+    end
+
+    private
+
+    def assemble_params(sanitized_params)
+      sanitized_params.collect do |group|
+        joiner = group.first.to_s.end_with?("=") ? "" : " "
+        group.compact.join(joiner)
+      end.join(" ")
+    end
+
+    def sanitize(params)
+      return [] if params.nil? || params.empty?
+      sanitize_associative_array(params.to_a)
+    end
+
+    def sanitize_associative_array(array)
+      array.collect { |a| sanitize_item(a) }
+    end
+
+    def sanitize_item(item)
+      case item
+      when Array then sanitize_key_values(item[0], item[1..-1])
+      when Hash  then sanitize_associative_array(item.to_a)
+      else            sanitize_item([item])
+      end
+    end
+
+    def sanitize_key_values(key, values)
+      [sanitize_key(key), *sanitize_value(values)]
+    end
+
+    KEY_REGEX = /^((?:--?)?)(.+?)(=?)$/
+
+    def sanitize_key(key)
+      return key if key.nil?
+      key = convert_symbol_key(key) if key.kind_of?(Symbol)
+
+      case key
+      when String
+        return key if key.empty?
+        prefix, key, suffix = KEY_REGEX.match(key)[1..3]
+        "#{prefix}#{sanitize_value(key)}#{suffix}"
+      else
+        sanitize_value(key)
+      end
+    end
+
+    def convert_symbol_key(key)
+      "--#{key.to_s.tr("_", "-")}"
+    end
+
+    def sanitize_value(value)
+      case value
+      when Enumerable
+        value.to_a.collect { |i| sanitize_value(i) }.compact
+      when NilClass
+        value
+      else
+        value.to_s.shellescape
+      end
+    end
+  end
+end

data/lib/awesome_spawn/command_result.rb

@@ -9,6 +9,14 @@ module AwesomeSpawn
       @exit_status  = exit_status
     end
 
+    def success?
+      exit_status == 0
+    end
+
+    def failure?
+      exit_status != 0
+    end
+
     def inspect
       "#{to_s.chop} @exit_status=#{@exit_status}>"
     end

data/lib/awesome_spawn/version.rb

@@ -1,3 +1,3 @@
 module AwesomeSpawn
-  VERSION = "1.1.1"
+  VERSION = "1.2.0"
 end

data/spec/awesome_spawn_spec.rb

@@ -4,31 +4,12 @@ require 'pathname' # For Pathname specific specs
 describe AwesomeSpawn do
   subject { described_class }
 
-  let(:params) do
-    {
-      "--user"     => "bob",
-      "--pass"     => "P@$sw0^& |<>/-+*d%",
-      "--db"       => nil,
-      "--desc="    => "Some Description",
-      :symkey      => nil,
-      :symkey_dash => nil,
-      nil          => ["pkg1", "some pkg"]
-    }
-  end
-
-  let (:modified_params) do
-    params.to_a + [123, 456].collect {|pool| ["--pool", pool]}
-  end
-
   shared_examples_for "run" do
     context "options" do
-      before do
-        subject.stub(:exitstatus => 0)
-      end
-
       it ":params won't be modified" do
+        params      = {:user => "bob"}
         orig_params = params.dup
-        subject.stub(:launch)
+        subject.stub(:launch => ["", "", 0])
         subject.send(run_method, "true", :params => params)
         expect(orig_params).to eq(params)
       end
@@ -49,7 +30,7 @@ describe AwesomeSpawn do
     context "with real execution" do
       before do
         # Re-enable actual spawning just for these specs.
-        Kernel.stub(:spawn).and_call_original
+        enable_spawning
       end
 
       it "command ok exit ok" do
@@ -132,71 +113,4 @@ describe AwesomeSpawn do
       let(:run_method) {"run!"}
     end
   end
-
-  context ".build_command_line" do
-    it "sanitizes crazy params" do
-      cl = subject.build_command_line("true", modified_params)
-      expect(cl).to eq "true --user bob --pass P@\\$sw0\\^\\&\\ \\|\\<\\>/-\\+\\*d\\% --db --desc=Some\\ Description --symkey --symkey-dash pkg1 some\\ pkg --pool 123 --pool 456"
-    end
-
-    it "handles Symbol keys" do
-      cl = subject.build_command_line("true", :abc => "def")
-      expect(cl).to eq "true --abc def"
-    end
-
-    it "handles Symbol keys with tailing '='" do
-      cl = subject.build_command_line("true", :abc= => "def")
-      expect(cl).to eq "true --abc=def"
-    end
-
-    it "handles Symbol keys with underscore" do
-      cl = subject.build_command_line("true", :abc_def => "ghi")
-      expect(cl).to eq "true --abc-def ghi"
-    end
-
-    it "handles Symbol keys with underscore and tailing '='" do
-      cl = subject.build_command_line("true", :abc_def= => "ghi")
-      expect(cl).to eq "true --abc-def=ghi"
-    end
-
-    it "sanitizes Fixnum array param value" do
-      cl = subject.build_command_line("true", nil => [1])
-      expect(cl).to eq "true 1"
-    end
-
-    it "sanitizes Pathname param value" do
-      cl = subject.build_command_line("true", nil => [Pathname.new("/usr/bin/ruby")])
-      expect(cl).to eq "true /usr/bin/ruby"
-    end
-
-    it "sanitizes Pathname param key" do
-      cl = subject.build_command_line("true", Pathname.new("/usr/bin/ruby") => nil)
-      expect(cl).to eq "true /usr/bin/ruby"
-    end
-
-    it "with params as empty Hash" do
-      cl = subject.build_command_line("true", {})
-      expect(cl).to eq "true"
-    end
-
-    it "with params as nil" do
-      cl = subject.build_command_line("true", nil)
-      expect(cl).to eq "true"
-    end
-
-    it "without params" do
-      cl = subject.build_command_line("true")
-      expect(cl).to eq "true"
-    end
-
-    it "with Pathname command" do
-      cl = subject.build_command_line(Pathname.new("/usr/bin/ruby"))
-      expect(cl).to eq "/usr/bin/ruby"
-    end
-
-    it "with Pathname command and params" do
-      cl = subject.build_command_line(Pathname.new("/usr/bin/ruby"), "-v" => nil)
-      expect(cl).to eq "/usr/bin/ruby -v"
-    end
-  end
 end

data/spec/command_line_builder_spec.rb

@@ -0,0 +1,255 @@
+require 'spec_helper'
+
+describe AwesomeSpawn::CommandLineBuilder do
+  subject { described_class.new }
+
+  context "#build" do
+    def assert_params(params, expected_params)
+      expect(subject.build("true", params)).to eq "true #{expected_params}".strip
+    end
+
+    it "without params" do
+      expect(subject.build("true")).to eq "true"
+    end
+
+    it "with nil" do
+      expect(subject.build("true", nil)).to eq "true"
+    end
+
+    it "with Pathname command" do
+      actual = subject.build(Pathname.new("/usr/bin/ruby"))
+      expect(actual).to eq "/usr/bin/ruby"
+    end
+
+    it "with Pathname command and params" do
+      actual = subject.build(Pathname.new("/usr/bin/ruby"), "-v" => nil)
+      expect(actual).to eq "/usr/bin/ruby -v"
+    end
+
+    context "with Hash" do
+      it "that is empty" do
+        assert_params({}, "")
+      end
+
+      it "with normal params" do
+        assert_params({"--user" => "bob"}, "--user bob")
+      end
+
+      it "with key with tailing '='" do
+        assert_params({"--user=" => "bob"}, "--user=bob")
+      end
+
+      it "with value requiring sanitization" do
+        assert_params({"--pass" => "P@$s w0rd%"}, "--pass P@\\$s\\ w0rd\\%")
+      end
+
+      it "with key requiring sanitization" do
+        assert_params({"--h&x0r=" => "xxx"}, "--h\\&x0r=xxx")
+      end
+
+      it "with key as Symbol" do
+        assert_params({:abc => "def"}, "--abc def")
+      end
+
+      it "with key as Symbol with tailing '='" do
+        assert_params({:abc= => "def"}, "--abc=def")
+      end
+
+      it "with key as Symbol with underscore" do
+        assert_params({:abc_def => "ghi"}, "--abc-def ghi")
+      end
+
+      it "with key as Symbol with underscore and tailing '='" do
+        assert_params({:abc_def= => "ghi"}, "--abc-def=ghi")
+      end
+
+      it "with key as nil" do
+        assert_params({nil => "def"}, "def")
+      end
+
+      it "with value as nil" do
+        assert_params({"--abc" => nil}, "--abc")
+      end
+
+      it "with key and value nil" do
+        assert_params({nil => nil}, "")
+      end
+
+      it "with key of '--'" do
+        assert_params({"--" => nil}, "--")
+      end
+
+      it "with value as Symbol" do
+        assert_params({"--abc" => :def}, "--abc def")
+      end
+
+      it "with value as Array" do
+        assert_params({"--abc" => ["def", "ghi"]}, "--abc def ghi")
+      end
+
+      it "with value as Fixnum" do
+        assert_params({"--abc" => 1}, "--abc 1")
+      end
+
+      it "with value as Fixnum Array" do
+        assert_params({"--abc" => [1, 2]}, "--abc 1 2")
+      end
+
+      it "with value as Range" do
+        assert_params({"--abc" => (1..4)}, "--abc 1 2 3 4")
+      end
+
+      it "with value as Pathname" do
+        assert_params({"--abc" => Pathname.new("/usr/bin/ruby")}, "--abc /usr/bin/ruby")
+      end
+    end
+
+    context "with associative Array" do
+      it "that is empty" do
+        assert_params([], "")
+      end
+
+      it "that is nested empty" do
+        assert_params([[]], "")
+      end
+
+      it "with normal params" do
+        assert_params([["--user", "bob"]], "--user bob")
+      end
+
+      it "with key with tailing '='" do
+        assert_params([["--user=", "bob"]], "--user=bob")
+      end
+
+      it "with value requiring sanitization" do
+        assert_params([["--pass", "P@$s w0rd%"]], "--pass P@\\$s\\ w0rd\\%")
+      end
+
+      it "with key requiring sanitization" do
+        assert_params([["--h&x0r=", "xxx"]], "--h\\&x0r=xxx")
+      end
+
+      it "with key as Symbol" do
+        assert_params([[:abc, "def"]], "--abc def")
+      end
+
+      it "with key as Symbol with tailing '='" do
+        assert_params([[:abc=, "def"]], "--abc=def")
+      end
+
+      it "with key as Symbol with underscore" do
+        assert_params([[:abc_def, "ghi"]], "--abc-def ghi")
+      end
+
+      it "with key as Symbol with underscore and tailing '='" do
+        assert_params([[:abc_def=, "ghi"]], "--abc-def=ghi")
+      end
+
+      it "with key as nil" do
+        assert_params([[nil, "def"]], "def")
+      end
+
+      it "with value as nil" do
+        assert_params([["--abc", nil]], "--abc")
+      end
+
+      it "with key and value nil" do
+        assert_params([[nil, nil]], "")
+      end
+
+      it "with key as nil and multiple values" do
+        assert_params([[nil, "def", "ghi"]], "def ghi")
+      end
+
+      it "with key of '--'" do
+        assert_params([["--", nil]], "--")
+      end
+
+      it "key alone" do
+        assert_params([["--abc"]], "--abc")
+      end
+
+      it "key as Symbol alone" do
+        assert_params([[:abc]], "--abc")
+      end
+
+      it "key as a bareword" do
+        assert_params(["--abc"], "--abc")
+      end
+
+      it "key as bareword Symbol" do
+        assert_params([:abc], "--abc")
+      end
+
+      it "value as a bareword" do
+        assert_params(["abc"], "abc")
+      end
+
+      it "with value as Symbol" do
+        assert_params([["--abc" => :def]], "--abc def")
+      end
+
+      it "with value as Array" do
+        assert_params([["--abc", ["def", "ghi"]]], "--abc def ghi")
+      end
+
+      it "with value as flattened Array" do
+        assert_params([["--abc", "def", "ghi"]], "--abc def ghi")
+      end
+
+      it "with value as Fixnum" do
+        assert_params([["--abc", 1]], "--abc 1")
+      end
+
+      it "with value as Fixnum Array" do
+        assert_params([["--abc", [1, 2]]], "--abc 1 2")
+      end
+
+      it "with value as Range" do
+        assert_params([["--abc", (1..4)]], "--abc 1 2 3 4")
+      end
+
+      it "with value as Pathname" do
+        assert_params([["--abc", Pathname.new("/usr/bin/ruby")]], "--abc /usr/bin/ruby")
+      end
+
+      it "with duplicate keys" do
+        assert_params([["--abc", 1], ["--abc", 2]], "--abc 1 --abc 2")
+      end
+    end
+
+    context "with multiple params" do # real-world cases
+      let(:expected) { "log feature -E --oneline --grep abc" }
+
+      it "as full Hash" do
+        params = {"log" => nil, "feature" => nil, "-E" => nil, :oneline => nil, "--grep" => "abc"}
+        assert_params(params, expected)
+      end
+
+      it "as grouped Hash" do
+        params = {nil => ["log", "feature"], "-E" => nil, :oneline => nil, :grep => "abc"}
+        assert_params(params, expected)
+      end
+
+      it "as associative Array" do
+        params = [[nil, "log", "feature"], ["-E", nil], [:oneline, nil], [:grep, "abc"]]
+        assert_params(params, expected)
+      end
+
+      it "as associative Array without nil values" do
+        params = [["log", "feature"], ["-E"], [:oneline], [:grep, "abc"]]
+        assert_params(params, expected)
+      end
+
+      it "as mixed Array with barewords" do
+        params = ["log", "feature", "-E", :oneline, [:grep, "abc"]]
+        assert_params(params, expected)
+      end
+
+      it "as mixed Array with nested Hashes" do
+        params = ["log", "feature", "-E", :oneline, {:grep => "abc"}]
+        assert_params(params, expected)
+      end
+    end
+  end
+end

data/spec/command_result_spec.rb

@@ -5,9 +5,19 @@ describe AwesomeSpawn::CommandResult do
     it "will not display sensitive information" do
       str = described_class.new("aaa", "bbb", "ccc", 0).inspect
 
-      expect(str.include?("aaa")).to be_false
-      expect(str.include?("bbb")).to be_false
-      expect(str.include?("ccc")).to be_false
+      expect(str).to_not include("aaa")
+      expect(str).to_not include("bbb")
+      expect(str).to_not include("ccc")
+    end
+
+    it "will know if a command succeeded" do
+      expect(described_class.new("c", "o", "e", 0)).to be_a_success
+      expect(described_class.new("c", "o", "e", 0)).not_to be_a_failure
+    end
+
+    it "will know if a command failed" do
+      expect(described_class.new("c", "o", "e", 1)).to be_a_failure
+      expect(described_class.new("c", "o", "e", 1)).not_to be_a_success
     end
   end
 end

data/spec/spec_helper.rb

@@ -15,9 +15,15 @@ RSpec.configure do |config|
   #     --seed 1234
   config.order = 'random'
 
-  config.before do
-    Kernel.stub(:spawn).and_raise("Spawning is not permitted in specs.  Please change your spec to use expectations/stubs.")
-  end
+  config.before { disable_spawning }
+end
+
+def disable_spawning
+  Open3.stub(:capture3).and_raise("Spawning is not permitted in specs.  Please change your spec to use expectations/stubs.")
+end
+
+def enable_spawning
+  Open3.stub(:capture3).and_call_original
 end
 
 begin

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: awesome_spawn
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -12,7 +12,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-03 00:00:00.000000000 Z
+date: 2014-07-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -90,6 +90,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/awesome_spawn.rb
+- lib/awesome_spawn/command_line_builder.rb
 - lib/awesome_spawn/command_result.rb
 - lib/awesome_spawn/command_result_error.rb
 - lib/awesome_spawn/no_such_file_error.rb
@@ -98,6 +99,7 @@ files:
 - README.md
 - LICENSE.txt
 - spec/awesome_spawn_spec.rb
+- spec/command_line_builder_spec.rb
 - spec/command_result_spec.rb
 - spec/spec_helper.rb
 - .rspec
@@ -128,6 +130,7 @@ specification_version: 3
 summary: AwesomeSpawn is a module that provides some useful features over Ruby's Kernel.spawn.
 test_files:
 - spec/awesome_spawn_spec.rb
+- spec/command_line_builder_spec.rb
 - spec/command_result_spec.rb
 - spec/spec_helper.rb
 - .rspec