backticks 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 156e6dd6cd59ca1201a48b9679e1f6151caf6b43
-  data.tar.gz: 225c905201c500af8cde4a7561490befaf797caa
+  metadata.gz: 8199c03291828b81d31df59a9e3341d20b13b27a
+  data.tar.gz: 5a4058b1ada73100e623660cf0c201f1aba3accb
 SHA512:
-  metadata.gz: b7230c03f69e71a6aeadb1cd0f3d43f0a12ad166231d0aecaea8c9c41bf8373e3cb5e3fbdfaf8ddb08be35c4e0632404edafb4b9de36e55213e6166f19134a1d
-  data.tar.gz: bb4bfa7199f80179fba4147379667b9e4e80ad2b8d3208e4d072953aaffbc2d42e4c1c8f52ce46059bec9c0b978600c3661b0650c23f2b7330da1fac7d9ddd8f
+  metadata.gz: 943ceaf445259b9c4fc67e94652fa5be8d613496abf198578842b81a97d5bb782d371bc5ac1b519c8143850fce1290a7f8e1245989c1a3cc71c76c4da237c279
+  data.tar.gz: 2c6ac11905c9a76836acb555d8819f74947fbf90fa42a0104bdb8823b2b3dff36d44bda9df56206cd9676ced6d5df65a24b201d1aa2d23295968e8d62b8f9c43

data/README.md

@@ -111,6 +111,18 @@ include Backticks::Ext
 
 If you do this, I will hunt you down and scoff at you. You have been warned!
 
+## Security
+
+Backticks avoids using your OS shell, which helps prevent security bugs.
+This also means that you can't pass strings such as "$HOME" to commands;
+Backticks does not perform shell substitution. Pass ENV['HOME'] instead.
+
+Be careful about the commands you pass to Backticks! Never run commands that
+you read from an untrusted source, e.g. the network.
+
+In the future, Backticks may integrate with Ruby's $SAFE level to provide smart
+escaping and shell safety.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/backticks/command.rb

@@ -21,7 +21,10 @@ module Backticks
     attr_reader :pid
 
     # @return [String] all data captured (so far) from child's stdin/stdout/stderr
-    attr_reader :captured_input, :captured_output, :captured_error, :status
+    attr_reader :captured_input, :captured_output, :captured_error
+
+    # @return [nil,Process::Status] result of command if it has ended; nil if still running
+    attr_reader :status
 
     # Watch a running command.
     def initialize(pid, stdin, stdout, stderr)
@@ -93,12 +96,12 @@ module Backticks
       # proxy STDIN to child's stdin
       if ready && ready.include?(STDIN)
         input = STDIN.readpartial(CHUNK) rescue nil
-        @captured_input << input
         if input
+          @captured_input << input
           @stdin.write(input)
         else
           # our own STDIN got closed; proxy this fact to the child
-          @stdin.close
+          @stdin.close unless @stdin.closed?
         end
       end
 

data/lib/backticks/runner.rb

@@ -1,12 +1,16 @@
 require 'pty'
+require 'open3'
 
 module Backticks
   # An easy-to-use interface for invoking commands and capturing their output.
   # Instances of Runner can be interactive, which prints the command's output
   # to the terminal and also allows the user to interact with the command.
-  # They can also be unbuffered, which uses a pseudo-tty to capture the
-  # command's output with no delay or
+  # By default commands are unbuffered, using a pseudoterminal to capture
+  # the output with no delay.
   class Runner
+    # Default streams to buffer if someone calls bufferered= with Boolean.
+    BUFFERED = [:stdin, :stdout, :stderr].freeze
+
     # If true, commands will have their stdio streams tied to the parent
     # process so the user can view their output and send input to them.
     # Commands' output is still captured normally when they are interactive.
@@ -21,18 +25,25 @@ module Backticks
     # @return [Boolean]
     attr_accessor :interactive
 
-    # If true, commands will be invoked with a pseudo-TTY for stdout in order
-    # to capture output as it is generated instead of waiting for pipe buffers
-    # to fill.
+    # List of I/O streams that should be captured using a pipe instead of
+    # a pseudoterminal.
     #
-    # @return [Boolean]
-    attr_accessor :buffered
+    # This may be a Boolean, or it may be an Array of stream names from the
+    # set [:stdin, stdout, stderr].
+    #
+    # @return [Array] list of symbolic stream names
+    attr_reader :buffered
 
     # @return [#parameters] the CLI-translation object used by this runner
     attr_reader :cli
 
     # Create an instance of Runner.
-    # @param [#parameters] cli object used to convert Ruby method parameters into command-line parameters
+    # @option [#include?,Boolean] buffered list of names; true/false for all/none
+    # @option [#parameters] cli command-line parameter translator
+    # @option [Boolean] interactive true to tie parent stdout/stdin to child
+    #
+    # @example buffer stdout
+    #   Runner.new(buffered:[:stdout])
     def initialize(options={})
       options = {
         :buffered => false,
@@ -40,9 +51,19 @@ module Backticks
         :interactive => false,
       }.merge(options)
 
-      @buffered = options[:buffered]
       @cli = options[:cli]
-      @interactive = options[:interactive]
+      self.buffered = options[:buffered]
+      self.interactive = options[:interactive]
+    end
+
+    # @param [Array,Boolean] buffered list of symbolic stream names; true/false for all/none
+    def buffered=(b)
+      @buffered = case b
+      when true then BUFFERED
+      when false, nil then []
+      else
+        b
+      end
     end
 
     # @deprecated
@@ -79,50 +100,32 @@ module Backticks
     #   remaining elements are parameters and flags
     # @return [Command] the running command
     def run_without_sugar(argv)
-      if self.buffered
-        run_buffered(argv)
+      stdin_r, stdin = if buffered.include?(:stdin) && !interactive
+        IO.pipe
       else
-        run_unbuffered(argv)
+        PTY.open
+      end
+      stdout, stdout_w = if buffered.include?(:stdout) && !interactive
+        IO.pipe
+      else
+        PTY.open
+      end
+      stderr, stderr_w = if buffered.include?(:stderr)
+        IO.pipe
+      else
+        PTY.open
       end
-    end
 
-    # Run a command. Use a pty to capture the unbuffered output.
-    #
-    # @param [Array] argv command to run; argv[0] is program name and the
-    #   remaining elements are parameters and flags
-    # @return [Command] the running command
-    private
-    def run_unbuffered(argv)
-      stdout, stdout_w = PTY.open
-      stdin_r, stdin = PTY.open
-      stderr, stderr_w = PTY.open
       pid = spawn(*argv, in: stdin_r, out: stdout_w, err: stderr_w)
       stdin_r.close
       stdout_w.close
       stderr_w.close
-      unless @interactive
+      unless interactive
         stdin.close
         stdin = nil
       end
 
       Command.new(pid, stdin, stdout, stderr)
     end
-
-    # Run a command. Perform no translation or substitution. Use a pipe
-    # to read the output, which may be buffered by the OS. Return the program's
-    # exit status and stdout.
-    #
-    # @param [Array] argv command to run; argv[0] is program name and the
-    #   remaining elements are command-line arguments.
-    # @return [Command] the running command
-    def run_buffered(argv)
-      stdin, stdout, stderr, thr = Open3.popen3(*argv)
-      unless @interactive
-        stdin.close
-        stdin = nil
-      end
-
-      Command.new(thr.pid, stdin, stdout, stderr)
-    end
   end
 end

data/lib/backticks/version.rb

@@ -1,3 +1,3 @@
 module Backticks
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: backticks
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Tony Spataro
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-27 00:00:00.000000000 Z
+date: 2016-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler