gofer 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.*.swp
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,5 @@
+source "http://rubygems.org"
+
+gem 'rspec'
+# Specify your gem's dependencies in gofer.gemspec
+gemspec

data/README.md

@@ -0,0 +1,109 @@
+# Gofer!
+
+**Gofer** is a set of wrappers around the Net::SSH suite of tools to enable consistent access to remote systems.
+
+**Gofer** has been written to support the needs of system automation scripts. As such, **gofer** will:
+
+  * automatically raise an error if a command returns a non-zero exit status
+  * print and capture STDOUT automatically
+  * print STDERR but don't capture it
+  * override the above: return non-zero exit status instead of raising an error, capture STDERR, suppress output
+
+## Examples
+
+    # in a block
+    Gofer::Host.new('ubuntu', 'my.host.com', :identity_file => 'key.pem').within do
+      # Basic usage
+      run "sudo stop mysqld"
+
+      # Copying files
+      upload 'file' 'remote_file'
+      download 'remote_dir', 'dir'
+
+      # Filesystem inspection
+      if exists?('remote_directory')
+        run "rm -rf 'remote_directory'"
+      end
+
+      # read/ls
+      puts read('a_remote_file')
+      puts ls('a_remote_dir').join(", ")
+
+      # error handling - default to critical failure if a command fails
+      run "false" # this will fail
+      run "false", :capture_exit_status => true # this won't ...
+      puts last_exit_status # and will make the exit status available
+
+      # stderr/stdout
+      hello = run "echo hello" # will print 'hello'
+      puts hello # will print "hello\n"
+
+      goodbye = run "echo goodbye 1>&2"
+      # goodbye will be empty, as we don't capture stderr by default
+  
+      goodbye = run "echo goodbye 1>&2", :capture_stderr => true # unless you ask for it
+
+      # output suppression
+      run "echo noisy", :quiet => true  # don't output from our command
+      run "echo noisier 1>&2", :quiet_stderr => true # don't even output stderr!
+
+    end
+
+    # using the instance directly
+    h = Gofer::Host.new('ubuntu', 'my.host.com')
+    h.run('sudo mysqld stop')
+    h.upload('file', 'remote_file')
+    # etc..
+
+## Planned Features
+
+    write("a string buffer", 'a_remote_file')
+    # constant connection (no reconnect for each action)
+    h = Gofer::Host.new(..., :keep_open => true)
+    h.run( ... )
+    h.close
+
+    # overriding defaults
+    set :quiet => true
+    set :capture_exit_status => false
+
+    # Separate the command from the arguments, system() style
+    run "echo" "Some" "arguments" "with" "'quotes'" "in" "them"
+    
+    # Local system usage, too:
+    run "hostname" # > my.macbook.com
+
+## Testing
+  
+  * Ensure that your user can ssh as itself to localhost using the key in `~/.ssh/id_rsa`.
+  * Run `rspec spec` or `bundle install && rake spec`
+
+## TODO
+ 
+* ls, exists?, directory? should use sftp if available rather than shell commands
+* wrap STDOUT with host prefix for easy identification of system output
+
+## License
+
+(The MIT License)
+
+Copyright (c) 2011 Michael Pearson
+
+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/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/gofer.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "gofer/version"
+
+Gem::Specification.new do |s|
+  s.name        = "gofer"
+  s.version     = Gofer::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Michael Pearson"]
+  s.email       = ["mipearson@gmail.com"]
+  s.homepage    = "https://github.com/mipearson/gofer"
+  s.summary     = %q{run commands on remote servers using SSH}
+  s.description = %q{
+Gofer provides a flexible and reliable model for performing tasks on remote
+server using Net::SSH
+}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths = ["lib"]
+  
+  s.add_dependency('net-ssh', '>= 2.0.23')
+  s.add_dependency('net-scp', '>= 1.0.4')
+end

data/lib/gofer.rb

@@ -0,0 +1,4 @@
+require 'gofer/ssh_wrapper'
+require 'gofer/host'
+require 'gofer/version'
+

data/lib/gofer/host.rb

@@ -0,0 +1,62 @@
+module Gofer
+  class HostError < Exception
+    def initialize host, message
+      super "#{host.hostname}: #{message}"
+    end
+  end
+ 
+  class Host
+
+    attr_reader :last_exit_status, :hostname
+
+    def initialize username, _hostname, identity_file=nil
+      @hostname = _hostname
+      @ssh = SshWrapper.new(username, hostname, identity_file)
+    end
+
+    def run command, opts={}
+      @ssh.run command, opts
+      if opts[:capture_exit_status]
+        @last_exit_status = @ssh.last_exit_status
+      elsif @ssh.last_exit_status != 0
+        raise HostError.new(self, "Command #{command} failed with exit status #{@ssh.last_exit_status}")
+      end
+      @ssh.last_output
+    end
+
+    def exists? path
+      @ssh.run "sh -c '[ -e #{path} ]'"
+      @ssh.last_exit_status == 0
+    end
+
+    def read path
+      @ssh.read_file path
+    end
+
+    def directory? path
+      @ssh.run "sh -c '[ -d #{path} ]'"
+      @ssh.last_exit_status == 0
+    end
+
+    def ls path
+      @ssh.run "ls -1 #{path}", :quiet => true
+      if @ssh.last_exit_status == 0
+        @ssh.last_output.strip.split("\n")
+      else
+        raise HostError.new(self, "Could not list #{path}, exit status #{@ssh.last_exit_status}")
+      end
+    end
+
+    def upload from, to
+      @ssh.upload from, to, :recursive => File.directory?(from)
+    end
+
+    def download from, to
+      @ssh.download from, to, :recursive => directory?(from)
+    end
+
+    def within &block
+      instance_eval &block
+    end
+  end
+end

data/lib/gofer/options.rb

@@ -0,0 +1,37 @@
+# Unused, keeping for later use.
+module Gofer
+  class Options
+    VALID_OPTIONS => %w{identity_file}
+
+    def valid_options
+      VALID_OPTIONS
+    end
+  
+    def initialize
+      @options = {}
+    end
+
+    def merge_in opts={}
+      opts.each |k,v|
+        set k, v
+      end
+    end
+  
+    def set k, v
+      k = option_valid_check(k)
+      @options[k] = v
+    end
+
+    def get k
+      k = option_valid_check(k)
+      @options[k] 
+    end
+   
+    private
+
+    def option_valid_check(k) 
+      k = k.to_s
+      raise "Invalid option #{k}" unless valid_options.include?(k)
+    end
+  end
+end

data/lib/gofer/ssh_wrapper.rb

@@ -0,0 +1,91 @@
+require 'net/ssh'
+require 'net/scp'
+
+module Gofer
+  class SshWrapper
+
+    attr_reader :last_output, :last_exit_status
+
+    def initialize username, hostname, identity_file = nil
+      @username = username
+      @hostname = hostname
+      @identity_file = identity_file
+      @last_exit_status = nil
+      @last_output = nil
+    end
+
+    def run command, opts={}
+      Net::SSH.start(*net_ssh_credentials) do |ssh|
+        ssh_execute(ssh, command, opts)
+      end
+    end
+    
+    def read_file path
+      a = nil
+      with_scp do |scp|
+        a = scp.download! path
+      end
+      a
+    end
+
+    def download from, to, opts={}
+      with_scp do |scp|
+        scp.download! from, to, opts
+      end
+    end
+
+    def upload from, to, opts={}
+      with_scp do |scp|
+        scp.upload! from, to, opts
+      end
+    end
+
+    private
+  
+    def with_scp 
+      Net::SCP.start(*net_ssh_credentials) do |scp|
+        yield scp
+      end
+    end
+
+    def net_ssh_credentials
+      creds = [@hostname, @username]
+      creds << {:keys => [@identity_file] } if @identity_file
+      creds
+    end
+
+    def ssh_execute(ssh, command, opts={})
+      output = ''
+      exit_code = 0
+      ssh.open_channel do |channel|
+        channel.exec(command) do |ch, success|
+          unless success
+            raise "Couldn't execute command #{command} (ssh channel failure)"
+          end
+
+          channel.on_data do |ch, data|  # stdout
+            output += data
+            $stdout.print data unless opts[:quiet]
+          end
+
+          channel.on_extended_data do |ch, type, data|
+            next unless type == 1 # only handle stderr
+            output += data if opts[:capture_stderr]
+            $stderr.print data unless opts[:quiet_stderr]
+          end
+
+          channel.on_request("exit-status") do |ch, data|
+            exit_code = data.read_long
+            channel.close # Necessary or backgrounded processes will 'hang' the channel
+          end
+          
+        end
+      end
+
+      ssh.loop
+      
+      @last_exit_status = exit_code
+      @last_output = output
+    end
+  end
+end

data/lib/gofer/version.rb

@@ -0,0 +1,3 @@
+module Gofer
+  VERSION = "0.0.1"
+end

data/spec/gofer/integration_spec.rb

@@ -0,0 +1,165 @@
+require 'spec_helper'
+require 'tempfile'
+
+describe Gofer do
+ 
+  HOSTNAME = ENV['TEST_HOST'] || 'localhost'
+  USERNAME = ENV['TEST_USER'] || ENV['USER']
+  IDENTITY_FILE = ENV['TEST_IDENTITY_FILE'] || '~/.ssh/id_rsa'
+
+  def raw_ssh command
+    out = `ssh -o PasswordAuthentication=no -ni #{IDENTITY_FILE} #{USERNAME}@#{HOSTNAME} #{command}`
+    raise "Command #{command} failed" unless $? == 0 
+    out
+  end
+
+  def in_tmpdir path
+    File.join(@tmpdir, path)
+  end
+    
+  def with_local_tmpdir template
+    f = Tempfile.new template
+    path = f.path
+    f.unlink
+    FileUtils.mkdir path
+    begin
+      yield path
+    ensure
+      FileUtils.rm_rf path unless ENV['KEEPTMPDIR']
+    end
+  end
+    
+  before :all do
+    @host = Gofer::Host.new(USERNAME, HOSTNAME, IDENTITY_FILE)
+    @tmpdir = raw_ssh("mktemp -d /tmp/gofertest.XXXXX").chomp
+  end
+
+  after :all do
+    if ENV['KEEPTMPDIR']
+      puts "TMPDIR is #{@tmpdir}"
+    else
+      raw_ssh "rm -rf #{@tmpdir}" if @tmpdir && @tmpdir =~ %r{gofertest}
+    end
+  end
+  
+  describe :hostname do
+    it "should be the hostname of the host we're connecting to" do
+      @host.hostname.should == HOSTNAME
+    end
+  end
+
+  describe :run do
+    it "should run a command and capture its output" do
+      output = @host.run "echo hello", :quiet => true
+      output.should == "hello\n"
+    end
+
+    it "should run a command not capture its stderr by default" do
+      output = @host.run "echo hello 1>&2", :quiet_stderr => true
+      output.should == ""
+    end
+
+    it "should run a command capture its stderr if asked" do
+      output = @host.run "echo hello 1>&2", :quiet_stderr => true, :capture_stderr => true
+      output.should == "hello\n"
+    end
+  
+    it "should error if a command returns a non-zero response" do
+      lambda {@host.run "false"}.should raise_error /failed with exit status/
+    end
+
+    it "should capture a non-zero exit status if asked" do
+      @host.run "false", :capture_exit_status => true
+      @host.last_exit_status.should == 1
+    end
+  end
+
+  describe :exists? do
+    it "should return true if a path or file exists" do
+      raw_ssh "touch #{in_tmpdir 'exists'}"
+      @host.exists?(in_tmpdir 'exists').should be true
+    end
+
+    it "should return false if a path does not exist" do
+      @host.exists?(in_tmpdir 'doesnotexist').should be false
+    end
+  end
+
+  describe :directory? do
+    it "should return true if a path is a directory" do
+      @host.directory?(@tmpdir).should be true
+    end
+
+    it "should return false if a path is not a directory" do
+      raw_ssh "touch #{in_tmpdir 'a_file'}"
+      @host.directory?(in_tmpdir('a_file')).should be false
+    end
+  end
+
+  describe :read do
+    it "should read in the contents of a file" do
+      raw_ssh "echo 'hello' > #{@tmpdir}/hello.txt"
+      @host.read(@tmpdir + '/hello.txt').should == "hello\n"
+    end
+  end
+    
+  describe :ls do
+    it "should list the contents of a directory" do
+      raw_ssh "mkdir #{@tmpdir}/lstmp && touch #{@tmpdir}/lstmp/f"
+      @host.ls(@tmpdir + '/lstmp').should == ['f']
+    end
+  end
+
+  describe :upload do
+    it "should upload a file to the remote server" do
+      f = Tempfile.new('upload_tmp')
+      begin
+        f.write('uploadtmp')
+        f.close
+        @host.upload(f.path, in_tmpdir('uploaded'))
+        raw_ssh("cat #{in_tmpdir 'uploaded'}").should == 'uploadtmp'
+      ensure
+        f.unlink
+      end
+    end
+    it "should upload a directory to the remote server" do
+      f = with_local_tmpdir('upload_dir_tmp') do |path|
+        system "echo 'hey' >> #{File.join(path, 'temp')}"
+        @host.upload(path, in_tmpdir('uploaded_dir'))
+        raw_ssh("cat #{in_tmpdir 'uploaded_dir/temp'}").should == "hey\n"
+      end
+    end
+  end
+
+  describe :download do
+    it "should download a file from the remove server" do
+      f = Tempfile.new('download_dir')
+      begin
+        f.close
+        raw_ssh "echo 'download' > #{in_tmpdir 'download'}"
+        @host.download(in_tmpdir('download'), f.path)
+        File.open(f.path).read.should == "download\n"
+      ensure
+        f.unlink
+      end
+    end
+
+    it "should download a directory from the remote server" do
+      with_local_tmpdir 'download_dir' do |path|
+        download_dir = in_tmpdir 'download_dir'
+        raw_ssh "mkdir #{download_dir} && echo 'sup' > #{download_dir}/hey"
+      
+        @host.download(download_dir, path)
+        File.open(path + '/download_dir/hey').read.should == "sup\n"
+      end
+    end
+  end
+
+  describe :within do
+    it "should execute commands in the context of the host instance" do
+      @host.within do
+        run("echo sup", :quiet => true).should == "sup\n"
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require "rspec"
+require "gofer"

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification 
+name: gofer
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Michael Pearson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-03 01:00:00 +11:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: net-ssh
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 33
+        segments: 
+        - 2
+        - 0
+        - 23
+        version: 2.0.23
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: net-scp
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 31
+        segments: 
+        - 1
+        - 0
+        - 4
+        version: 1.0.4
+  type: :runtime
+  version_requirements: *id002
+description: |
+  
+  Gofer provides a flexible and reliable model for performing tasks on remote
+  server using Net::SSH
+
+email: 
+- mipearson@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- gofer.gemspec
+- lib/gofer.rb
+- lib/gofer/host.rb
+- lib/gofer/options.rb
+- lib/gofer/ssh_wrapper.rb
+- lib/gofer/version.rb
+- spec/gofer/integration_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: https://github.com/mipearson/gofer
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: run commands on remote servers using SSH
+test_files: 
+- spec/gofer/integration_spec.rb
+- spec/spec_helper.rb