cheetah 0.1.0 → 0.2.0

data/CHANGELOG

@@ -1,3 +1,15 @@
+0.2.0 (2012-04-05)
+------------------
+
+* Logger can be set globally.
+* Use :info and :error levels for logging instead of :debug.
+* Added API documentation.
+* Added proper README.md.
+* Updated gem description.
+* Rewrote tests into RSpec.
+* Improved performance for commands with big outputs.
+* Internal code improvements.
+
 0.1.0 (2012-03-23)
 ------------------
 

data/README.md

@@ -1,6 +1,95 @@
 Cheetah
 =======
 
-Cheetah is a simple library for executing external commands safely and conveniently. It is meant as a safe replacement of `backticks`, Kernel#system and similar methods, which are often used in unsecure way (they allow shell expansion of commands).
+Cheetah is a simple library for executing external commands safely and conveniently.
 
-Proper documentation is coming soon.
+Examples
+--------
+
+```ruby
+# Run a command and capture its output
+files = Cheetah.run("ls", "-la", :capture => :stdout)
+
+# Run a command and handle errors
+begin
+  Cheetah.run("rm", "/etc/passwd")
+rescue Cheetah::ExecutionFailed => e
+  puts e.message
+  puts "Standard output: #{e.stdout}"
+  puts "Error ouptut:    #{e.stderr}"
+end
+```
+
+Features
+--------
+
+  * Easy passing of command input
+  * Easy capturing of command output (standard, error, or both)
+  * 100% secure (shell expansion is impossible by design)
+  * Raises exceptions on errors (no more manual status code checks)
+  * Optional logging for easy debugging
+
+Non-features
+------------
+
+  * Handling of commands producing big outputs
+  * Handling of interactive commands
+
+Installation
+------------
+
+    $ gem install cheetah
+
+Usage
+-----
+
+First, require the library:
+
+```ruby
+require "cheetah"
+```
+
+You can now use the `Cheetah.run` method to run commands, pass them an input and capture their output:
+
+```ruby
+# Run a command with arguments
+Cheetah.run("tar", "xzf", "foo.tar.gz")
+
+# Pass an input
+Cheetah.run("python", :stdin => source_code)
+
+# Capture standard output
+files = Cheetah.run("ls", "-la", :capture => :stdout)
+
+# Capture both standard and error output
+results, errors = Cheetah.run("grep", "-r", "User", ".", :capture => [:stdout, :stderr))
+```
+
+If the command can't be executed for some reason or returns a non-zero exit status, the method raises an exception with detailed information about the failure:
+
+```ruby
+# Run a command and handle errors
+begin
+  Cheetah.run("rm", "/etc/passwd")
+rescue Cheetah::ExecutionFailed => e
+  puts e.message
+  puts "Standard output: #{e.stdout}"
+  puts "Error ouptut:    #{e.stderr}"
+end
+```
+
+For debugging purposes, you can also use a logger. Cheetah will log the command, its status, input and both outputs to it. The `:info` level will be used for normal messages, the `:error` level for messages about errors (non-zero exit status or non-empty error output):
+
+```ruby
+# Log the execution
+Cheetah.run("ls -l", :logger => logger)
+
+# Or, if you're tired of passing the :logger option all the time...
+Cheetah.logger = my_logger
+Cheetah.run("./configure")
+Cheetah.run("make")
+Cheetah.run("make", "install")
+Cheetah.logger = nil
+```
+
+For more information, see the [API documentation](http://rubydoc.info/github/openSUSE/cheetah/frames).

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/cheetah.rb

@@ -1,11 +1,58 @@
-# Contains methods for executing external commands safely and conveniently.
+# A simple library for executing external commands safely and conveniently.
+#
+# ## Features
+#
+#   * Easy passing of command input
+#   * Easy capturing of command output (standard, error, or both)
+#   * 100% secure (shell expansion is impossible by design)
+#   * Raises exceptions on errors (no more manual status code checks)
+#   * Optional logging for easy debugging
+#
+# ## Non-features
+#
+#   * Handling of commands producing big outputs
+#   * Handling of interactive commands
+#
+# @example Run a command and capture its output
+#   files = Cheetah.run("ls", "-la", :capture => :stdout)
+#
+# @example Run a command and handle errors
+#   begin
+#     Cheetah.run("rm", "/etc/passwd")
+#   rescue Cheetah::ExecutionFailed => e
+#     puts e.message
+#     puts "Standard output: #{e.stdout}"
+#     puts "Error ouptut:    #{e.stderr}"
+#   end
 module Cheetah
+  # Cheetah version (uses [semantic versioning](http://semver.org/)).
   VERSION = File.read(File.dirname(__FILE__) + "/../VERSION").strip
 
   # Exception raised when a command execution fails.
   class ExecutionFailed < StandardError
-    attr_reader :command, :args, :status, :stdout, :stderr
+    # @return [String] the executed command
+    attr_reader :command
 
+    # @return [Array<String>] the executed command arguments
+    attr_reader :args
+
+    # @return [Process::Status] the executed command exit status
+    attr_reader :status
+
+    # @return [String] the output the executed command wrote to stdout
+    attr_reader :stdout
+
+    # @return [String] the output the executed command wrote to stderr
+    attr_reader :stderr
+
+    # Initializes a new {ExecutionFailed} instance.
+    #
+    # @param [String] command the executed command
+    # @param [Array<String>] args the executed command arguments
+    # @param [Process::Status] status the executed command exit status
+    # @param [String] stdout the output the executed command wrote to stdout
+    # @param [String] stderr the output the executed command wrote to stderr
+    # @param [String, nil] message the exception message
     def initialize(command, args, status, stdout, stderr, message = nil)
       super(message)
       @command = command
@@ -16,142 +63,135 @@ module Cheetah
     end
   end
 
-  # Runs an external command, optionally capturing its output. Meant as a safe
-  # replacement of `backticks`, Kernel#system and similar methods, which are
-  # often used in unsecure way. (They allow shell expansion of commands, which
-  # often means their arguments need proper escaping. The problem is that people
-  # forget to do it or do it badly, causing serious security issues.)
-  #
-  # Examples:
-  #
-  #   # Run a command, grab its output and handle failures.
-  #   files = nil
-  #   begin
-  #     files = Cheetah.run("ls", "-la", :capture => :stdout)
-  #   rescue Cheetah::ExecutionFailed => e
-  #     puts "Command #{e.command} failed with status #{e.status}."
-  #   end
-  #
-  #   # Log the executed command, it's status, input and both outputs into
-  #   # user-supplied logger.
-  #   Cheetah.run("qemu-kvm", "foo.raw", :logger => my_logger)
-  #
-  # The first parameter specifies the command to run, the remaining parameters
-  # specify its arguments. It is also possible to specify both the command and
-  # arguments in the first parameter using an array. If the last parameter is a
-  # hash, it specifies options.
-  #
-  # For security reasons, the command never goes through shell expansion even if
-  # only one parameter is specified (i.e. the method does do not adhere to the
-  # convention used by other Ruby methods for launching external commands, e.g.
-  # Kernel#system).
-  #
-  # If the command execution succeeds, the returned value depends on the
-  # value of the :capture option (see below). If it fails (the command is not
-  # executed for some reason or returns a non-zero exit status), the method
-  # raises a ExecutionFailed exception with detailed information about the
-  # failure.
-  #
-  # Options:
-  #
-  #   :capture - configures which output(s) the method captures and returns, the
-  #              valid values are:
-  #
-  #                - nil                - no output is captured and returned
-  #                                       (the default)
-  #                - :stdout            - standard output is captured and
-  #                                       returned as a string
-  #                - :stderr            - error output is captured and returned
-  #                                       as a string
-  #                - [:stdout, :stderr] - both outputs are captured and returned
-  #                                       as a two-element array of strings
-  #
-  #   :stdin  - if specified, it is a string sent to command's standard input
-  #
-  #   :logger - if specified, the method will log the command, its status, input
-  #             and both outputs to passed logger at the "debug" level
-  #
-  def self.run(command, *args)
-    options = args.last.is_a?(Hash) ? args.pop : {}
-
-    capture = options[:capture]
-    stdin   = options[:stdin] || ""
-    logger  = options[:logger]
-
-    if command.is_a?(Array)
-      args    = command[1..-1]
-      command = command.first
-    end
+  class << self
+    # The global logger or `nil` if none is set (the default). This logger is
+    # used by {Cheetah.run} unless overridden by the `:logger` option.
+    #
+    # @return [Logger, nil] the global logger
+    attr_accessor :logger
 
-    pass_stdin = !stdin.empty?
-    pipe_stdin_read, pipe_stdin_write = pass_stdin ? IO.pipe : [nil, nil]
+    # Runs an external command with specified arguments, optionally passing it
+    # an input and capturing its output.
+    #
+    # If the command execution succeeds, the returned value depends on the value
+    # of the `:capture` option (see below). If the command can't be executed for
+    # some reason or returns a non-zero exit status, the method raises an
+    # {ExecutionFailed} exception with detailed information about the failure.
+    #
+    # The command and its arguments never undergo shell expansion — they are
+    # passed directly to the operating system. While this may create some
+    # inconvenience in certain cases, it eliminates a whole class of security
+    # bugs.
+    #
+    # The command execution can be logged using a logger. It can be set globally
+    # (using the {Cheetah.logger} attribute) or locally (using the `:logger`
+    # option).  The local setting overrides the global one. If a logger is set,
+    # the method will log the command, its status, input and both outputs to it.
+    # The `:info` level will be used for normal messages, the `:error` level for
+    # messages about errors (non-zero exit status or non-empty error output).
+    #
+    # @overload run(command, *args, options = {})
+    #   @param [String] command the command to execute
+    #   @param [Array<String>] args the command arguments
+    #   @param [Hash] options the options to execute the command with
+    #   @option options [String] :stdin ('') command's input
+    #   @option options [String] :capture (nil) configures which output(s) to
+    #     capture, the valid values are:
+    #
+    #       * `nil` — no output is captured and returned
+    #       * `:stdout` — standard output is captured and returned as a string
+    #       * `:stderr` — error output is captured and returned as a string
+    #       * `[:stdout, :stderr]` — both outputs are captured and returned as a
+    #         two-element array of strings
+    #   @option options [Logger, nil] :logger (nil) logger to log the command
+    #     execution; if set, overrides the global logger (set by
+    #     {Cheetah.logger})
+    #
+    # @overload run(command_and_args, options = {})
+    #   This variant is useful mainly when building the command and its
+    #   arguments programmatically.
+    #
+    #   @param [Array<String>] command_and_args the command to execute (first
+    #     element of the array) and its arguments (remaining elements)
+    #   @param [Hash] options the options to execute the command with, same as
+    #     in the first variant
+    #
+    # @raise [ExecutionFailed] when the command can't be executed for some
+    #   reason or returns a non-zero exit status
+    #
+    # @example Run a command and capture its output
+    #   files = Cheetah.run("ls", "-la", :capture => :stdout)
+    #
+    # @example Run a command and handle errors
+    #   begin
+    #     Cheetah.run("rm", "/etc/passwd")
+    #   rescue Cheetah::ExecutionFailed => e
+    #     puts e.message
+    #     puts "Standard output: #{e.stdout}"
+    #     puts "Error ouptut:    #{e.stderr}"
+    #   end
+    def run(command, *args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
 
-    capture_stdout = [:stdout, [:stdout, :stderr]].include?(capture) || logger
-    pipe_stdout_read, pipe_stdout_write = capture_stdout ? IO.pipe : [nil, nil]
+      stdin   = options[:stdin] || ""
+      logger  = options[:logger] || @logger
 
-    capture_stderr = [:stderr, [:stdout, :stderr]].include?(capture) || logger
-    pipe_stderr_read, pipe_stderr_write = capture_stderr ? IO.pipe : [nil, nil]
+      if command.is_a?(Array)
+        args    = command[1..-1]
+        command = command.first
+      end
 
-    if logger
-      logger.debug "Executing command #{command.inspect} with #{describe_args(args)}."
-      logger.debug "Standard input: " + (stdin.empty? ? "(none)" : stdin)
-    end
+      pipe_stdin_read,  pipe_stdin_write  = IO.pipe
+      pipe_stdout_read, pipe_stdout_write = IO.pipe
+      pipe_stderr_read, pipe_stderr_write = IO.pipe
 
-    pid = fork do
-      begin
-        if pass_stdin
+      if logger
+        logger.info "Executing command #{command.inspect} with #{describe_args(args)}."
+        logger.info "Standard input: " + (stdin.empty? ? "(none)" : stdin)
+      end
+
+      pid = fork do
+        begin
           pipe_stdin_write.close
           STDIN.reopen(pipe_stdin_read)
           pipe_stdin_read.close
-        else
-          STDIN.reopen("/dev/null", "r")
-        end
 
-        if capture_stdout
           pipe_stdout_read.close
           STDOUT.reopen(pipe_stdout_write)
           pipe_stdout_write.close
-        else
-          STDOUT.reopen("/dev/null", "w")
-        end
 
-        if capture_stderr
           pipe_stderr_read.close
           STDERR.reopen(pipe_stderr_write)
           pipe_stderr_write.close
-        else
-          STDERR.reopen("/dev/null", "w")
-        end
 
-        # All file descriptors from 3 above should be closed here, but since I
-        # don't know about any way how to detect the maximum file descriptor
-        # number portably in Ruby, I didn't implement it. Patches welcome.
+          # All file descriptors from 3 above should be closed here, but since I
+          # don't know about any way how to detect the maximum file descriptor
+          # number portably in Ruby, I didn't implement it. Patches welcome.
 
-        exec([command, command], *args)
-      rescue SystemCallError => e
-        exit!(127)
+          exec([command, command], *args)
+        rescue SystemCallError => e
+          exit!(127)
+        end
       end
-    end
-
-    [pipe_stdin_read, pipe_stdout_write, pipe_stderr_write].each { |p| p.close if p }
 
-    # We write the command's input and read its output using a select loop. Why?
-    # Because otherwise we could end up with a deadlock.
-    #
-    # Imagine if we first read the whole standard output and then the whole
-    # error output, but the executed command would write lot of data but only to
-    # the error output. Sooner or later it would fill the buffer and block,
-    # while we would be blocked on reading the standard output -- classic
-    # deadlock.
-    #
-    # Similar issues can happen with standard input vs. one of the outputs.
-    if pass_stdin || capture_stdout || capture_stderr
-      stdout = ""
-      stderr = ""
+      [pipe_stdin_read, pipe_stdout_write, pipe_stderr_write].each { |p| p.close }
 
+      # We write the command's input and read its output using a select loop.
+      # Why? Because otherwise we could end up with a deadlock.
+      #
+      # Imagine if we first read the whole standard output and then the whole
+      # error output, but the executed command would write lot of data but only
+      # to the error output. Sooner or later it would fill the buffer and block,
+      # while we would be blocked on reading the standard output -- classic
+      # deadlock.
+      #
+      # Similar issues can happen with standard input vs. one of the outputs.
+      outputs = { pipe_stdout_read => "", pipe_stderr_read => "" }
+      pipes_readable = [pipe_stdout_read, pipe_stderr_read]
+      pipes_writable = [pipe_stdin_write]
       loop do
-        pipes_readable = [pipe_stdout_read, pipe_stderr_read].compact.select { |p| !p.closed? }
-        pipes_writable = [pipe_stdin_write].compact.select { |p| !p.closed? }
+        pipes_readable.reject!(&:closed?)
+        pipes_writable.reject!(&:closed?)
 
         break if pipes_readable.empty? && pipes_writable.empty?
 
@@ -162,61 +202,58 @@ module Cheetah
           raise IOError, "Error when communicating with executed program."
         end
 
-        if ios_read.include?(pipe_stdout_read)
+        ios_read.each do |pipe|
           begin
-            stdout += pipe_stdout_read.readpartial(4096)
+            outputs[pipe] << pipe.readpartial(4096)
           rescue EOFError
-            pipe_stdout_read.close
+            pipe.close
           end
         end
 
-        if ios_read.include?(pipe_stderr_read)
-          begin
-            stderr += pipe_stderr_read.readpartial(4096)
-          rescue EOFError
-            pipe_stderr_read.close
-          end
-        end
-
-        if ios_write.include?(pipe_stdin_write)
-          n = pipe_stdin_write.syswrite(stdin)
+        ios_write.each do |pipe|
+          n = pipe.syswrite(stdin)
           stdin = stdin[n..-1]
-          pipe_stdin_write.close if stdin.empty?
+          pipe.close if stdin.empty?
         end
       end
-    end
 
-    pid, status = Process.wait2(pid)
-    begin
-      if !status.success?
-        raise ExecutionFailed.new(command, args, status,
-          capture_stdout ? stdout : nil,
-          capture_stderr ? stderr : nil,
-          "Execution of command #{command.inspect} " +
-          "with #{describe_args(args)} " +
-          "failed with status #{status.exitstatus}.")
+      stdout = outputs[pipe_stdout_read]
+      stderr = outputs[pipe_stderr_read]
+
+      pid, status = Process.wait2(pid)
+      begin
+        if !status.success?
+          raise ExecutionFailed.new(command, args, status, stdout, stderr,
+            "Execution of command #{command.inspect} " +
+            "with #{describe_args(args)} " +
+            "failed with status #{status.exitstatus}.")
+        end
+      ensure
+        if logger
+          logger.log status.success? ? Logger::INFO : Logger::ERROR,
+            "Status: #{status.exitstatus}"
+          logger.info "Standard output: " + (stdout.empty? ? "(none)" : stdout)
+          logger.log stderr.empty?  ? Logger::INFO : Logger::ERROR,
+            "Error output: " + (stderr.empty? ? "(none)" : stderr)
+        end
       end
-    ensure
-      if logger
-        logger.debug "Status: #{status.exitstatus}"
-        logger.debug "Standard output: " + (stdout.empty? ? "(none)" : stdout)
-        logger.debug "Error output: " + (stderr.empty? ? "(none)" : stderr)
+
+      case options[:capture]
+        when nil
+          nil
+        when :stdout
+          stdout
+        when :stderr
+          stderr
+        when [:stdout, :stderr]
+          [stdout, stderr]
       end
     end
 
-    case capture
-      when nil
-        nil
-      when :stdout
-        stdout
-      when :stderr
-        stderr
-      when [:stdout, :stderr]
-        [stdout, stderr]
-    end
-  end
+    private
 
-  def self.describe_args(args)
-    args.empty? ? "no arguments" : "arguments #{args.map(&:inspect).join(", ")}"
+    def describe_args(args)
+      args.empty? ? "no arguments" : "arguments #{args.map(&:inspect).join(", ")}"
+    end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: cheetah
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - David Majda
@@ -15,11 +15,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-03-23 00:00:00 +01:00
+date: 2012-04-05 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: shoulda-context
+  name: rspec
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
@@ -33,7 +33,7 @@ dependencies:
   type: :development
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: mocha
+  name: redcarpet
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
@@ -46,7 +46,21 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id002
-description: Cheetah is a simple library for executing external commands safely and conveniently. It is meant as a safe replacement of `backticks`, Kernel#system and similar methods, which are often used in unsecure way (they allow shell expansion of commands).
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: Cheetah is a simple library for executing external commands safely and conveniently.
 email: dmajda@suse.de
 executables: []