rye 0.3

data/CHANGES.txt

@@ -0,0 +1,26 @@
+RYE, CHANGES
+
+#### 0.3 (2009-04-05) ###############################
+
+* ADDED: Rye::Set supports executing commands parallel 
+* ADDED: Rye::Rap now contains STDERR output from command
+* FIXED: Rye::Box wasn't properly adding keypairs to SSH Agent
+* CHANGED: Moved all SSH key stuff to Rye (used to be done per Box)
+* ADDED: Supports all options provided by Net::SSH#start. This 
+includes support for password logins and proxies. 
+* ADDED: Safe mode can now be disabled (to allow file globs
+and environment variable access).
+* ADDED: Basic sanity test
+* FIXED: Rye::Box.method_missing Symbol/String ambiguity
+* ADDED: Mucho more rdocs and examples.
+
+#### 0.2 (2009-04-04) ###############################
+
+* FIXED: ssh-agent shutdown wasn't deleting the SSH tmp directory
+* ADDED: Now with more rdocs!
+
+
+#### 0.1 (2009-04-03) ###############################
+
+Initial public release
+

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2009 Delano Mandelbaum, Solutious 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/README.rdoc

@@ -0,0 +1,176 @@
+= Rye - v0.3
+
+Run system commands via SSH locally and remotely in a Ruby way. 
+
+Rye is similar to Rush[http://rush.heroku.com] but everything happens over SSH (no HTTP daemon) and the default settings are less powerful (for safety). For example, file globs are disabled so unless otherwise specified, you can't do this: <tt>rbox.rm('-rf', '/etc/**/*')</tt>.
+
+See +bin/try+ for working examples.
+
+== Installation
+
+One of:
+
+    $ sudo gem install rye
+    $ sudo gem install delano-rye --source http://gems.github.com/
+    $ git clone git://github.com/delano/rye.git
+
+
+== EXAMPLE 1 -- Basic Usage
+    
+    rbox = Rye::Box.new('localhost')
+    
+    # Commands are run as methods on the Rye::Box object
+    puts rbox.uptime                # => 11:02  up 16:01, 3 users
+    
+    # The response value for all commands is a Rye::Rap object. The rap is a
+    # subclass of Array so you can treat it as an Array, but it can also act 
+    # like a String if there's only one element. 
+    puts rbox.ls('rye.test')           # => ""
+    puts rbox.ls('rye.test').stderr    # => ls: rye.test: No such file or directory
+    
+    puts rbox.touch('rye.test')        # => ""
+    puts rbox.rm('rye.test')           # => ""
+    
+    # You can change directories
+    puts rbox.pwd                      # => /home/rye
+    puts rbox['/usr/bin'].pwd          # => /usr/bin
+    puts rbox.pwd                      # => /usr/bin
+    puts rbox.cd('/home/rye').pwd      # => /home/rye
+    
+    # You can specify environment variables
+    rbox.add_env(:RYE, "Forty Creek")
+    rbox.env                           # => ['HOME=/home/rye', 'RYE=Forty Creek', ...]
+    
+    # The commands method returns an Array of available commands:                        
+    puts rbox.commands.join(', ')      # => pwd, touch, echo, wc, ...
+    
+    # When you're done you can disconnect explicitly. 
+    # (Although Rye does this automatically at exit.)
+    rbox.disconnect
+
+
+== EXAMPLE 2 -- Disabling Safe-Mode
+
+    rbox_safe = Rye::Box.new('localhost')
+    rbox_wild = Rye::Box.new('localhost', :safe => false)
+
+    # Safe-mode is enabled by default. In safe-mode, all command 
+    # arguments are thoroughly escaped. This prevents access to
+    # environment variables and file globs (among other things).
+    p rbox_safe.echo('$HOME')                   # => "$HOME"
+    p rbox_safe['/etc'].ls('host*')             # => 
+    p rbox_safe.ls('-l | wc -l')                # => 
+    p rbox_safe.echo('$HOME > /tmp/rye-home')   # => "$HOME > /tmp/home"
+    p rbox_safe.cat('/tmp/rye-home')            # => 
+    p rbox_safe.cat('/tmp/rye-home').stderr     # => "No such file or directory"
+
+    # Here's the same commands with safe-mode disabled:
+    p rbox_wild.echo('$HOME')                   # => "/home/rye"
+    p rbox_wild['/etc'].ls('host*')             # => ["hostconfig", "hosts"]
+    p rbox_wild.ls('-l | wc -l')                # => 110
+    p rbox_wild.echo('$HOME > /tmp/rye-home')   # => 
+    p rbox_wild.cat('/tmp/rye-home')            # => "/home/rye"
+    p rbox_wild.rm('/tmp/rye-home')             # =>
+
+
+
+== EXAMPLE 3 -- Custom Commands
+
+    rbox = Rye::Box.new('localhost')
+    rbox.add_keys('/private/key/path')   # Specify additional private keys
+    
+    # There's currently no rye900 command
+    p rbox.commands.member?('rye9000')   # => false
+    
+    # But we can add our own commands to the Rye::Cmd class. They 
+    # automatically become available to all Rye::Box objects.
+    module Rye::Cmd
+      def rye9000(*args)
+        add_command("ls", args)
+      end
+      def somescript(*args)
+        add_command("/path/to/my/script", args)
+      end
+    end
+    
+    # We can now run rye9000 (with arguments)
+    p rbox.rye9000('-a')                 # => [".", "..", ".bashrc", ...]
+    p rbox.commands.member?('rye9000')   # => true
+
+
+== EXAMPLE 4 -- Accessing Multiple Machines
+
+    rset = Rye::Set.new
+    rbox = Rye::Box.new
+    
+    rset.add_keys('/private/key/path')     # For passwordless logins 
+    rset.add_boxes(rbox, 'localhost')      # Add boxes as hostnames or objects
+    
+    # Calling methods on Rye::Set objects is very similar to calling them on
+    # Rye::Box objects. In fact, it's identical:
+    p rset.uptime        # => [[14:19:02 up 32 days, 19:35 ...], [14:19:02 up 30 days, 01:35]]
+    p rset['/etc'].ls    # => [['file1', 'file2', ...], ['life1', 'life2', ...]]
+    
+    # Like Rye::Box, the response value is a Rye::Rap object containing the
+    # responses from each box. Each response is itself a Rye::Rap object.
+    unames = rset.uname
+    p unames                               # => [["Darwin"], ["Darwin"]]
+    puts unames.class                      # => Rye::Rap
+    
+    # The Rye::Rap object also keeps a reference to the object that called the 
+    # command. In this case, it will keep a reference to Rye::Set:
+    puts unames.set.class                  # => Rye::Set
+    puts unames.set == rset                # => true
+    puts unames.size                       # => 2
+    puts unames.first                      # => Darwin
+    puts unames.first.class                # => Rye::Rap
+    puts unames.first.box.class            # => Rye::Box
+    puts unames.first.box == rbox          # => true
+    
+    # Envrionment variables can be set the same way as with Rye::Box
+    rset.add_env(:RYE, "Forty Creek")
+    p rset.env.first.select { |env| env =~ /RYE/ }  # => ["RYE=Forty Creek"]
+
+
+== About Safe-Mode
+
+In safe-mode:
+
+* You can't use file globs. This means you can't do this: <tt>rbox.ls('*.rb')</tt>. 
+* Commands arguments cannot contain environment variables. However, environment variables are available to the commands you run. This means you can't do this: <tt>rbox.echo('$HOME')</tt>.
+* Pipes and operators don't work: <tt>|, &&, >, <, ||</tt>, etc...
+* Backticks don't work either: <tt>procs=`ps aux`</tt>
+
+Why? In safe-mode, all command arguments are escaped which turns all arguments into their literal values. 
+
+Using a Ruby interface to execute shell commands is pretty awesome, particularly to run them on several machines simultaneously. That's a lot of power and it's potentially very dangerous. That's why some stuff isn't available in Rye that you would otherwise expect to be able to do (particularly the file globs). There's probably a way to do it safely but it's not obvious yet (to me). If you have any ideas, I'd love to hear them!
+
+
+== Credits
+
+* Delano Mandelbaum (delano@solutious.com)
+
+
+== Thanks
+
+* Solutious Incorporated (http://solutious.com) for all the orange juice.
+* The country of Canada for making Rye Whiskey. 
+
+
+== Kudos
+
+* http://github.com/adamwiggins/rush
+* http://github.com/jamis/capistrano/blob/master/lib/capistrano/shell.rb
+* http://www.nofluffjuststuff.com/blog/david_bock/2008/10/ruby_s_closure_cleanup_idiom_and_net_ssh.html
+* http://groups.google.com/group/ruby-talk-google/browse_thread/thread/674a6f6de15ceb49?pli=1
+* http://paste.lisp.org/display/6912
+
+
+== Credits
+
+* Delano Mandelbaum (delano@solutious.com)
+
+
+== License
+
+See: LICENSE.txt

data/Rakefile

@@ -0,0 +1,83 @@
+require 'rubygems'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'hanna/rdoctask'
+require 'fileutils'
+include FileUtils
+ 
+task :default => :package
+ 
+# CONFIG =============================================================
+
+# Change the following according to your needs
+README = "README.rdoc"
+CHANGES = "CHANGES.txt"
+LICENSE = "LICENSE.txt"
+
+# Files and directories to be deleted when you run "rake clean"
+CLEAN.include [ 'doc', 'pkg', '*.gem', '.config' ]
+
+# Virginia assumes your project and gemspec have the same name
+name = (Dir.glob('*.gemspec') || ['rye']).first.split('.').first
+load "#{name}.gemspec"
+version = @spec.version
+
+# That's it! The following defaults should allow you to get started
+# on other things. 
+
+
+# TESTS/SPECS =========================================================
+
+
+
+# INSTALL =============================================================
+
+Rake::GemPackageTask.new(@spec) do |p|
+  p.need_tar = true if RUBY_PLATFORM !~ /mswin/
+end
+
+task :release => [ :rdoc, :package ]
+task :install => [ :rdoc, :package ] do
+  sh %{sudo gem install pkg/#{name}-#{version}.gem}
+end
+task :uninstall => [ :clean ] do
+  sh %{sudo gem uninstall #{name}}
+end
+
+
+# RUBYFORGE RELEASE / PUBLISH TASKS ==================================
+
+if @spec.rubyforge_project
+  desc 'Publish website to rubyforge'
+  task 'publish:rdoc' => 'doc/index.html' do
+    sh "scp -rp doc/* rubyforge.org:/var/www/gforge-projects/#{name}/"
+  end
+
+  desc 'Public release to rubyforge'
+  task 'publish:gem' => [:package] do |t|
+    sh <<-end
+      rubyforge add_release -o Any -a #{CHANGES} -f -n #{README} #{name} #{name} #{@spec.version} pkg/#{name}-#{@spec.version}.gem &&
+      rubyforge add_file -o Any -a #{CHANGES} -f -n #{README} #{name} #{name} #{@spec.version} pkg/#{name}-#{@spec.version}.tgz 
+    end
+  end
+end
+
+
+
+# RUBY DOCS TASK ==================================
+
+Rake::RDocTask.new do |t|
+  t.rdoc_dir = 'doc'
+  t.title    = @spec.summary
+  t.options << '--line-numbers' << '-A cattr_accessor=object'
+  t.options << '--charset' << 'utf-8'
+  t.rdoc_files.include(LICENSE)
+  t.rdoc_files.include(README)
+  t.rdoc_files.include(CHANGES)
+  #t.rdoc_files.include('bin/*')
+  t.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+

data/bin/try

@@ -0,0 +1,148 @@
+#!/usr/bin/ruby
+
+# Rye -- A working example
+#
+# If your reading this via the rdocs you won't be able to see the code
+# See: http://github.com/delano/rye/blob/master/bin/try
+#
+# Usage: bin/try
+#
+
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'rubygems'
+require 'stringio'
+require 'yaml'
+require 'rye'
+
+
+puts %Q(
+# ------------------------------------------------------------------
+#   EXAMPLE 1 -- Basic Usage
+#)
+
+rbox = Rye::Box.new('localhost')
+
+# Commands are run as methods on the Rye::Box object
+puts rbox.uptime                # => 11:02  up 16:01, 3 users
+
+# The response value for all commands is a Rye::Rap object. The rap is a
+# subclass of Array so you can treat it as an Array, but it can also act 
+# like a String if there's only one element. 
+puts rbox.ls('rye.test')           # => ""
+puts rbox.ls('rye.test').stderr    # => ls: rye.test: No such file or directory
+
+puts rbox.touch('rye.test')        # => ""
+puts rbox.rm('rye.test')           # => ""
+                                 
+# You can change directories
+puts rbox.pwd                      # => /home/rye
+puts rbox['/usr/bin'].pwd          # => /usr/bin
+puts rbox.pwd                      # => /usr/bin
+puts rbox.cd('/home/rye').pwd      # => /home/rye
+
+# You can specify environment variables
+rbox.add_env(:RYE, "Forty Creek")
+rbox.env                           # => ['HOME=/home/rye', 'RYE=Forty Creek', ...]
+
+# The commands method returns an Array of available commands:                        
+puts rbox.commands.join(', ')      # => pwd, touch, echo, wc, ...
+
+# When you're done you can disconnect explicitly. 
+# (Although Rye does this automatically at exit.)
+rbox.disconnect
+
+
+puts %Q(
+# ------------------------------------------------------------------
+#   EXAMPLE 2 -- Disabling Safe-Mode
+#)
+
+rbox_safe = Rye::Box.new('localhost')
+rbox_wild = Rye::Box.new('localhost', :safe => false)
+
+# Safe-mode is enabled by default. In safe-mode, all command 
+# arguments are thoroughly escaped. This prevents access to
+# environment variables and file globs (among other things).
+p rbox_safe.echo('$HOME')                   # => "$HOME"
+p rbox_safe['/etc'].ls('host*')             # => 
+p rbox_safe.ls('-l | wc -l')                # => 
+p rbox_safe.echo('$HOME > /tmp/rye-home')   # => "$HOME > /tmp/home"
+p rbox_safe.cat('/tmp/rye-home')            # => 
+p rbox_safe.cat('/tmp/rye-home').stderr     # => "No such file or directory"
+
+# Here's the same commands with safe-mode disabled:
+p rbox_wild.echo('$HOME')                   # => "/home/rye"
+p rbox_wild['/etc'].ls('host*')             # => ["hostconfig", "hosts"]
+p rbox_wild.ls('-l | wc -l')                # => 110
+p rbox_wild.echo('$HOME > /tmp/rye-home')   # => 
+p rbox_wild.cat('/tmp/rye-home')            # => "/home/rye"
+p rbox_wild.rm('/tmp/rye-home')             # =>
+
+
+puts %Q(
+# ------------------------------------------------------------------
+#   EXAMPLE 3 -- Custom Commands
+#)
+
+rbox = Rye::Box.new('localhost')
+rbox.add_keys('/private/key/path')   # Specify additional private keys
+
+# There's currently no rye900 command
+p rbox.commands.member?('rye9000')   # => false
+
+# But we can add our own commands to the Rye::Cmd class. They 
+# automatically become available to all Rye::Box objects.
+module Rye::Cmd
+  def rye9000(*args)
+    add_command("ls", args)
+  end
+  def somescript(*args)
+    add_command("/path/to/my/script", args)
+  end
+end
+
+# We can now run rye9000 (with arguments)
+p rbox.rye9000('-a')                 # => [".", "..", ".bashrc", ...]
+p rbox.commands.member?('rye9000')   # => true
+
+
+puts %Q(
+# ------------------------------------------------------------------
+#   EXAMPLE 4 -- Accessing Multiple Machines
+#)
+
+rset = Rye::Set.new
+rbox = Rye::Box.new
+
+rset.add_keys('/private/key/path')     # For passwordless logins 
+rset.add_boxes(rbox, 'localhost')      # Add boxes as hostnames or objects
+
+# Calling methods on Rye::Set objects is very similar to calling them on
+# Rye::Box objects. In fact, it's identical:
+p rset.uptime        # => [[14:19:02 up 32 days, 19:35 ...], [14:19:02 up 30 days, 01:35]]
+p rset['/etc'].ls    # => [['file1', 'file2', ...], ['life1', 'life2', ...]]
+
+# Like Rye::Box, the response value is a Rye::Rap object containing the
+# responses from each box. Each response is itself a Rye::Rap object.
+unames = rset.uname
+p unames                               # => [["Darwin"], ["Darwin"]]
+puts unames.class                      # => Rye::Rap
+
+# The Rye::Rap object also keeps a reference to the object that called the 
+# command. In this case, it will keep a reference to Rye::Set:
+puts unames.set.class                  # => Rye::Set
+puts unames.set == rset                # => true
+puts unames.size                       # => 2
+puts unames.first                      # => Darwin
+puts unames.first.class                # => Rye::Rap
+puts unames.first.box.class            # => Rye::Box
+puts unames.first.box == rbox          # => true
+
+# Envrionment variables can be set the same way as with Rye::Box
+rset.add_env(:RYE, "Forty Creek")
+p rset.env.first.select { |env| env =~ /RYE/ }  # => ["RYE=Forty Creek"]
+
+
+
+