terrapin 0.6.0.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2f5aede86af5c29288c8f251af1dbf9bd1a179b90a416dd638ea02c3e29930a3
+  data.tar.gz: 4dd46fea24d0a8a78c0c39959d5c08dcfeec5a4429a1f18acfc87323811c18bb
+SHA512:
+  metadata.gz: 28e367c3deb7c6b6064a6dd2cfd1600646261302d135805ba47e3fbba18a2ee2256dbb2b9a379378c20bc1a770bcfdfc5b95fe668e5d499d3f2eda2bf1c49677
+  data.tar.gz: 873cb7a8046310942c2533003ae09a865fde8288fe64e97484c69d588d042b818e24ffd3b2e06e38308cffee1de99dbc86490231daf24b1cd8bade289e64f1ea

data/.gitignore

@@ -0,0 +1,8 @@
+*.rbc
+.rbx
+*.gem
+Gemfile.lock
+*.swp
+*.swo
+.bundle
+bin

data/.travis.yml

@@ -0,0 +1,6 @@
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.5
+  - jruby-19mode
+  - rbx-2

data/GOALS

@@ -0,0 +1,8 @@
+Terrapin hits 1.0.0 when:
+
+[*] It can run command lines across all major unix platforms.
+[*] It can run command lines on Windows.
+[*] It handles quoting.
+[*] It takes advantage of OS-specific functionality to be thread-safe,
+    when possible.
+[ ] It has a consistent and functioning API that pleases us.

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gemspec
+
+platforms :ruby do
+  gem "posix-spawn"
+end

data/LICENSE

@@ -0,0 +1,26 @@
+
+LICENSE
+
+The MIT License
+
+Copyright (c) 2011-2014 Jon Yurek and thoughtbot, inc.
+
+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:
+
+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.
+
+

data/NEWS.md

@@ -0,0 +1,85 @@
+New for 0.5.7:
+
+* Feature: Allow collection of both STDOUT and STDERR.
+* Improvement: Convert arguments to strings when possible
+
+New for 0.5.6:
+
+* Bug Fix: Java does not need to run commands with `env`
+* Bug Fix: Found out we were rescuing the wrong error
+
+New for 0.5.5:
+
+* Bug Fix: Posix- and ProcessRunner respect paths *and* are thread safe!
+* Bug Fix: `exitstatus` should always be set, even if command doesn't run.
+* Test Fix: Do not try to test Runners if they don't run on this system.
+* Improvement: Pass the Errno::ENOENT message through to the exception.
+* Improvement: Improve documentation
+
+New for 0.5.4:
+
+* Bug Fix: PosixRunner and ProcessRunner respect supplemental paths now.
+
+New for 0.5.3:
+
+* SECURITY: Fix exploitable bug that could allow arbitrary command execution.
+  See CVE-2013-4457 for more details. Thanks to Holger Just for report and fix!
+* Bug fix: Sub-word interpolations can be confused for the longer version
+
+New for 0.5.2:
+
+* Improvement: Close all the IO objects!
+* Feature: Add an Runner that uses IO.popen, so JRuby can play
+* Improvement: Officially drop Ruby 1.8 support, add Ruby 2.0 support
+* Bug fix: Prevent a crash if no command was actually run
+* Improvement: Add security cautions to the README
+
+New for 0.5.1:
+
+* Fixed a bug preventing running on 1.8.7 for no good reason.
+
+New for 0.5.0:
+
+* Updated the copyrights to 2013
+* Added UTF encoding markers on code files to ensure they're interpreted as
+  UTF-8 instead of ASCII.
+* Swapped the ordering of the PATH and supplemental path. A binary in the
+  supplemental path will take precedence, now.
+* Errors contain the output of the erroring command, for inspection.
+* Use climate_control instead for environment management.
+
+New for 0.4.2:
+
+* Loggers that don't understand `tty?`, like `ActiveSupport::BufferedLogger`
+  will still work.
+
+New for 0.4.1:
+
+* Introduce FakeRunner for testing, so you don't really run commands.
+* Fix logging: output the actual command, not the un-interpolated pattern.
+* Prevent color codes from being output if log destination isn't a TTY.
+
+New for 0.4.0:
+
+* Moved interpolation to the `run` method, instead of interpolating on `new`.
+* Remove official support for REE.
+
+New for 0.3.2:
+
+* Fix a hang when processes wait for IO.
+
+New for 0.3.1:
+
+* Made the `Runner` manually swappable, in case `ProcessRunner` doesn't work
+  for some reason.
+* Fixed copyright years.
+
+New for 0.3.0:
+
+* Support blank arguments.
+* Add `CommandLine#unix?`.
+* Add `CommandLine#exit_status`.
+* Automatically use `POSIX::Spawn` if available.
+* Add `CommandLine#environment` as a hash of extra `ENV` data..
+* Add `CommandLine#runner` which produces an object that responds to `#call`.
+* Fix a race condition but only on Ruby 1.9.

data/README.md

@@ -0,0 +1,215 @@
+# Terrapin [![Build Status](https://secure.travis-ci.org/thoughtbot/terrapin.png?branch=master)](http://travis-ci.org/thoughtbot/terrapin)
+
+A small library for doing (command) lines.
+
+[API reference](http://rubydoc.info/gems/terrapin/)
+
+## Usage
+
+The basic, normal stuff:
+
+```ruby
+line = Terrapin::CommandLine.new("echo", "hello 'world'")
+line.command # => "echo hello 'world'"
+line.run # => "hello world\n"
+```
+
+Interpolated arguments:
+
+```ruby
+line = Terrapin::CommandLine.new("convert", ":in -scale :resolution :out")
+line.command(in: "omg.jpg",
+             resolution: "32x32",
+             out: "omg_thumb.jpg")
+# => "convert 'omg.jpg' -scale '32x32' 'omg_thumb.jpg'"
+```
+
+It prevents attempts at being bad:
+
+```ruby
+line = Terrapin::CommandLine.new("cat", ":file")
+line.command(file: "haha`rm -rf /`.txt") # => "cat 'haha`rm -rf /`.txt'"
+
+line = Terrapin::CommandLine.new("cat", ":file")
+line.command(file: "ohyeah?'`rm -rf /`.ha!") # => "cat 'ohyeah?'\\''`rm -rf /`.ha!'"
+```
+
+NOTE: It only does that for arguments interpolated via `run`, NOT arguments
+passed into `new` (see 'Security' below):
+
+```ruby
+line = Terrapin::CommandLine.new("echo", "haha`whoami`")
+line.command # => "echo haha`whoami`"
+line.run # => "hahawebserver"
+```
+
+You can ignore the result:
+
+```ruby
+line = Terrapin::CommandLine.new("noisy", "--extra-verbose", swallow_stderr: true)
+line.command # => "noisy --extra-verbose 2>/dev/null"
+
+# ... and on Windows...
+line.command # => "noisy --extra-verbose 2>NUL"
+```
+
+If your command errors, you get an exception:
+
+```ruby
+line = Terrapin::CommandLine.new("git", "commit")
+begin
+  line.run
+rescue Terrapin::ExitStatusError => e
+  e.message # => "Command 'git commit' returned 1. Expected 0"
+end
+```
+
+If your command might return something non-zero, and you expect that, it's cool:
+
+```ruby
+line = Terrapin::CommandLine.new("/usr/bin/false", "", expected_outcodes: [0, 1])
+begin
+  line.run
+rescue Terrapin::ExitStatusError => e
+  # => You never get here!
+end
+```
+
+You don't have the command? You get an exception:
+
+```ruby
+line = Terrapin::CommandLine.new("lolwut")
+begin
+  line.run
+rescue Terrapin::CommandNotFoundError => e
+  e # => the command isn't in the $PATH for this process.
+end
+```
+
+But don't fear, you can specify where to look for the command:
+
+```ruby
+Terrapin::CommandLine.path = "/opt/bin"
+line = Terrapin::CommandLine.new("lolwut")
+line.command # => "lolwut", but it looks in /opt/bin for it.
+```
+
+You can even give it a bunch of places to look:
+
+```ruby
+    FileUtils.rm("/opt/bin/lolwut")
+    File.open('/usr/local/bin/lolwut') {|f| f.write('echo Hello') }
+    Terrapin::CommandLine.path = ["/opt/bin", "/usr/local/bin"]
+    line = Terrapin::CommandLine.new("lolwut")
+    line.run # => prints 'Hello', because it searches the path
+```
+
+Or just put it in the command:
+
+```ruby
+line = Terrapin::CommandLine.new("/opt/bin/lolwut")
+line.command # => "/opt/bin/lolwut"
+```
+
+You can see what's getting run. The 'Command' part it logs is in green for visibility!
+
+```ruby
+line = Terrapin::CommandLine.new("echo", ":var", logger: Logger.new(STDOUT))
+line.run(var: "LOL!") # => Logs this with #info -> Command :: echo 'LOL!'
+```
+
+Or log every command:
+
+```ruby
+Terrapin::CommandLine.logger = Logger.new(STDOUT)
+Terrapin::CommandLine.new("date").run # => Logs this -> Command :: date
+```
+
+## Security
+
+Short version: Only pass user-generated data into the `run` method and NOT
+`new`.
+
+As shown in examples above, Terrapin will only shell-escape what is passed in as
+interpolations to the `run` method. It WILL NOT escape what is passed in to the
+second argument of `new`. Terrapin assumes that you will not be manually
+passing user-generated data to that argument and will be using it as a template
+for your command line's structure.
+
+## POSIX Spawn
+
+You can potentially increase performance by installing [the posix-spawn
+gem](https://rubygems.org/gems/posix-spawn). This gem can keep your
+application's heap from being copied when forking command line
+processes. For applications with large heaps the gain can be
+significant. To include `posix-spawn`, simply add it to your `Gemfile` or,
+if you don't use bundler, install the gem.
+
+## Runners
+
+Terrapin will attempt to choose from among 3 different ways of running commands.
+The simplest is using backticks, and is the default in 1.8. In Ruby 1.9, it
+will attempt to use `Process.spawn`. And, as mentioned above, if the
+`posix-spawn` gem is installed, it will attempt to use that. If for some reason
+one of the `.spawn` runners don't work for you, you can override them manually
+by setting a new runner, like so:
+
+```ruby
+Terrapin::CommandLine.runner = Terrapin::CommandLine::BackticksRunner.new
+```
+
+And if you really want to, you can define your own Runner, though I can't
+imagine why you would.
+
+### JRuby issues
+
+#### Caveat
+
+If you get `Error::ECHILD` errors and are using JRuby, there is a very good
+chance that the error is actually in JRuby. This was brought to our attention
+in https://github.com/thoughtbot/terrapin/issues/24 and probably fixed in
+http://jira.codehaus.org/browse/JRUBY-6162. You *will* want to use the
+`BackticksRunner` if you are unable to update JRuby.
+
+#### Spawn warning
+
+If you get `unsupported spawn option: out` warning (like in [issue 38](https://github.com/thoughtbot/terrapin/issues/38)),
+try to use `PopenRunner`:
+
+```ruby
+Terrapin::CommandLine.runner = Terrapin::CommandLine::PopenRunner.new
+```
+
+## Thread Safety
+
+Terrapin should be thread safe. As discussed [here, in this climate_control
+thread](https://github.com/thoughtbot/climate_control/pull/11), climate_control,
+which modifies the environment under which commands are run for the
+BackticksRunner and PopenRunner, is thread-safe but not reentrant. Please let us
+know if you find this is ever not the case.
+
+## Feedback
+
+*Security* concerns must be privately emailed to
+[security@thoughtbot.com](security@thoughtbot.com).
+
+Question? Idea? Problem? Bug? Comment? Concern? Like using question marks?
+
+[GitHub Issues For All!](https://github.com/thoughtbot/terrapin/issues)
+
+## Credits
+
+Thank you to all [the contributors](https://github.com/thoughtbot/terrapin/graphs/contributors)!
+
+![thoughtbot](http://thoughtbot.com/logo.png)
+
+Terrapin is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
+
+The names and logos for thoughtbot are trademarks of thoughtbot, inc.
+
+## License
+
+Copyright 2011-2014 Jon Yurek and thoughtbot, inc. This is free software, and
+may be redistributed under the terms specified in the
+[LICENSE](https://github.com/thoughtbot/terrapin/blob/master/LICENSE)
+file.

data/Rakefile

@@ -0,0 +1,13 @@
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+desc 'Default: Run specs.'
+task :default => 'spec:unit'
+
+namespace :spec do
+  desc "Run unit specs"
+  RSpec::Core::RakeTask.new('unit') do |t|
+    t.pattern = 'spec/terrapin/**/*_spec.rb'
+  end
+end

data/lib/terrapin.rb

@@ -0,0 +1,12 @@
+# coding: UTF-8
+
+require 'rbconfig'
+require 'terrapin/os_detector'
+require 'terrapin/command_line'
+require 'terrapin/command_line/output'
+require 'terrapin/command_line/multi_pipe'
+require 'terrapin/command_line/runners'
+require 'terrapin/exceptions'
+
+module Terrapin
+end

data/lib/terrapin/command_line.rb

@@ -0,0 +1,197 @@
+# coding: UTF-8
+
+module Terrapin
+  class CommandLine
+    class << self
+      attr_accessor :logger, :runner
+
+      def path
+        @supplemental_path
+      end
+
+      def path=(supplemental_path)
+        @supplemental_path = Array(supplemental_path).
+          flatten.
+          join(OS.path_separator)
+      end
+
+      def environment
+        @supplemental_environment ||= {}
+      end
+
+      def runner
+        @runner || best_runner
+      end
+
+      def runner_options
+        @default_runner_options ||= {}
+      end
+
+      def fake!
+        @runner = FakeRunner.new
+      end
+
+      def unfake!
+        @runner = nil
+      end
+
+      private
+
+      def best_runner
+        [PosixRunner, ProcessRunner, BackticksRunner].detect do |runner|
+          runner.supported?
+        end.new
+      end
+    end
+
+    @environment = {}
+
+    attr_reader :exit_status, :runner
+
+    def initialize(binary, params = "", options = {})
+      @binary            = binary.dup
+      @params            = params.dup
+      @options           = options.dup
+      @runner            = @options.delete(:runner) || self.class.runner
+      @logger            = @options.delete(:logger) || self.class.logger
+      @swallow_stderr    = @options.delete(:swallow_stderr)
+      @expected_outcodes = @options.delete(:expected_outcodes) || [0]
+      @environment       = @options.delete(:environment) || {}
+      @runner_options    = @options.delete(:runner_options) || {}
+    end
+
+    def command(interpolations = {})
+      cmd = [path_prefix, @binary, interpolate(@params, interpolations)]
+      cmd << bit_bucket if @swallow_stderr
+      cmd.join(" ").strip
+    end
+
+    def run(interpolations = {})
+      @exit_status = nil
+      begin
+        full_command = command(interpolations)
+        log("#{colored("Command")} :: #{full_command}")
+        @output = execute(full_command)
+      rescue Errno::ENOENT => e
+        raise Terrapin::CommandNotFoundError, e.message
+      ensure
+        @exit_status = $?.respond_to?(:exitstatus) ? $?.exitstatus : 0
+      end
+
+      if @exit_status == 127
+        raise Terrapin::CommandNotFoundError
+      end
+
+      unless @expected_outcodes.include?(@exit_status)
+        message = [
+          "Command '#{full_command}' returned #{@exit_status}. Expected #{@expected_outcodes.join(", ")}",
+          "Here is the command output: STDOUT:\n", command_output,
+          "\nSTDERR:\n", command_error_output
+        ].join("\n")
+        raise Terrapin::ExitStatusError, message
+      end
+      command_output
+    end
+
+    def command_output
+      output.output
+    end
+
+    def command_error_output
+      output.error_output
+    end
+
+    def output
+      @output || Output.new
+    end
+
+    private
+
+    def colored(text, ansi_color = "\e[32m")
+      if @logger && @logger.respond_to?(:tty?) && @logger.tty?
+        "#{ansi_color}#{text}\e[0m"
+      else
+        text
+      end
+    end
+
+    def log(text)
+      if @logger
+        @logger.info(text)
+      end
+    end
+
+    def path_prefix
+      if !self.class.path.nil? && !self.class.path.empty?
+        os_path_prefix
+      end
+    end
+
+    def os_path_prefix
+      if OS.unix?
+        unix_path_prefix
+      else
+        windows_path_prefix
+      end
+    end
+
+    def unix_path_prefix
+      "PATH=#{self.class.path}#{OS.path_separator}$PATH;"
+    end
+
+    def windows_path_prefix
+      "SET PATH=#{self.class.path}#{OS.path_separator}%PATH% &"
+    end
+
+    def execute(command)
+      runner.call(command, environment, runner_options)
+    end
+
+    def environment
+      self.class.environment.merge(@environment)
+    end
+
+    def runner_options
+      self.class.runner_options.merge(@runner_options)
+    end
+
+    def interpolate(pattern, interpolations)
+      interpolations = stringify_keys(interpolations)
+      pattern.gsub(/:\{?(\w+)\b\}?/) do |match|
+        key = match.tr(":{}", "")
+        if interpolations.key?(key)
+          shell_quote_all_values(interpolations[key])
+        else
+          match
+        end
+      end
+    end
+
+    def stringify_keys(hash)
+      Hash[hash.map{ |k, v| [k.to_s, v] }]
+    end
+
+    def shell_quote_all_values(values)
+      Array(values).map(&method(:shell_quote)).join(" ")
+    end
+
+    def shell_quote(string)
+      return "" if string.nil?
+      string = string.to_s if string.respond_to? :to_s
+
+      if OS.unix?
+        if string.empty?
+          "''"
+        else
+          string.split("'", -1).map{|m| "'#{m}'" }.join("\\'")
+        end
+      else
+        %{"#{string}"}
+      end
+    end
+
+    def bit_bucket
+      OS.unix? ? "2>/dev/null" : "2>NUL"
+    end
+  end
+end