screwcap 0.3.2 → 0.3.3

data/Manifest.txt

@@ -6,7 +6,6 @@ README.rdoc
 Rakefile
 TODO
 bin/screwcap
-lib/exts.rb
 lib/screwcap.rb
 lib/screwcap/base.rb
 lib/screwcap/deployer.rb

data/README.rdoc

@@ -1,6 +1,6 @@
-= screwcap
+= Screwcap
 
-* http://github.com/#{github_username}/#{project_name}
+* http://gammons.github.com/screwcap
 
 == DESCRIPTION:
 
@@ -8,18 +8,14 @@ Screwcap is a library that wraps Net::SSH and makes it easy to perform actions o
 
 The most obvious task you could use screwcap for is deploying rails applications to remote servers.
 
-== FEATURES/PROBLEMS:
+== FEATURES:
 
-* Screwcap is currently not ready for production use as it is under active development.
+* 
 
 == SYNOPSIS:
 
   FIX (code sample of usage)
 
-== REQUIREMENTS:
-
-* FIX (list of requirements)
-
 == INSTALL:
 
 * gem install screwcap
@@ -28,7 +24,7 @@ The most obvious task you could use screwcap for is deploying rails applications
 
 (The MIT License)
 
-Copyright (c) 2010 Grant Ammons
+Copyright (c) 2010 Grant Ammons (grant@pipelinedeals.com)
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/Rakefile

@@ -11,7 +11,7 @@ Hoe.plugin :newgem
 # Generate all the Rake tasks
 # Run 'rake -T' to see list of generated tasks (from gem root directory)
 $hoe = Hoe.spec 'screwcap' do
-  self.version  = '0.3.2'
+  self.version  = '0.3.3'
   self.developer 'Grant Ammons', 'grant@pipelinedeals.com'
   self.rubyforge_name       = self.name # TODO this is default value
   self.extra_deps         = [['net-ssh','>= 2.0.23'],['net-ssh-gateway','>=1.0.1'], ['net-scp','>=1.0.4']]

data/lib/screwcap/base.rb

@@ -1,12 +1,5 @@
 module Screwcap
   class Base < OpenStruct
-
-    # for debugging purposes only
-    #def method_missing(m, *args, &block)
-    #  $stdout << "For #{self.class.to_s}: calling #{m}\n"
-    #  super(m, args.first)
-    #end
-
     def set(var, *args)
       method_missing((var.to_s + "=").to_sym, args.first)
     end

data/lib/screwcap/deployer.rb

@@ -27,6 +27,67 @@ class Deployer < Screwcap::Base
 
 
   # create a task.  Minimally, a task needs a :server specified to run the task on.
+  #   task_for :herd_the_cats, :server => :cat_server do
+  #     ...
+  #   end
+  #
+  #   task_for :herd_both, :servers => [:cat_server, :dog_server] do
+  #     ...
+  #   end
+  #
+  # The only other option that task_for accepts is *:parallel*.  If *parallel* => false, and a server has multiple addresses, then the task will be run serially, rather than all at the same time.
+  #
+  #   server :pig, :address => "pig.com"
+  #   server :horse, :address => "horse.com"
+  #   server :cats_and_dogs, :addresses => ["cat.com","dog.com"]
+  #
+  #   task_for :one_at_a_time, :servers => [:pig, :horse], :parallel => false
+  #     run "serial_task" # this will be run on the pig server first, then on the horse server.
+  #   end
+  #
+  #   task_for :one_at_a_time_2, :server => :cats_and_dogs, :parallel => false do
+  #     run "serial_task" # this will be run on cat.com first, then on dog.com
+  #   end
+  #
+  #   task_for :all_together_now, :servers => [:pig, :horse, :cats_and_dogs] do
+  #     run "parallel_task"  # this task will be executed on all the addresses specified by the servers at the same time.
+  #   end
+  # ===A note about variable scope
+  # ====Any variables you declare within a task are scoped to that task.
+  #
+  #     # in your deployment recipe...
+  #     set :animal, "donkey"
+  #
+  #     task_for :thing, :server => :server do
+  #       set :animal, "pig"
+  #       run "pet #{animal}" # will run 'pet pig'
+  #     end
+  #
+  # ====A command set that is called by a task will inherit all the variables set by the task.
+  #   
+  #     command_set :pet_the_animal do
+  #       run "pet #{animal}"
+  #     end
+  #
+  #     task_for :pet_pig do
+  #       set :animal, "pig"
+  #       pet_the_animal
+  #     end
+  #
+  #     task_for :pet_horse do
+  #       set :animal, "horse"
+  #       pet_the_animal
+  #     end
+  #
+  # ====Of course, you can also set variables within the command set as well, that are scoped only to that command set.
+  #   
+  #     command_set :pet_the_donkey do
+  #       set :animal, "donkey"
+  #       run "pet #{donkey}"
+  #     end
+  #
+  # ====Any command sets that are nested within another command set will inerit all the variables from the parent command set.
+  #
   def task_for name, options = {}, &block
     t = Task.new(options.merge(:name => name, :nocolor => self.__options[:nocolor], :silent => self.__options[:silent], :deployment_servers => self.__servers, :command_sets => self.__command_sets), &block)
     clone_table_for(t)
@@ -34,27 +95,92 @@ class Deployer < Screwcap::Base
     self.__tasks << t
   end
 
+  # ====A *command set* is like a generic set of tasks that you intend to use in multiple tasks.
+  #
+  #     command_set :redundant_task do
+  #       run "redundant_task"
+  #     end
+  #
+  #     task_for :pet_pig, :server => :s1 do
+  #       redundant_task
+  #     end
+  #
+  #     task_for :pet_horse, :server => s2 do
+  #       redundant_task
+  #     end
+  #
+  # ====You can also nest command sets within other command sets.
+  #     command_set :other_task do
+  #       run "other_task"
+  #     end
+  #
+  #     command_set :redundant_task do
+  #       other_task
+  #     end
+  #
+  #     task_for :pet_horse, :server => s2 do
+  #       redundant_task
+  #     end
+
+
   def command_set(name,options = {},&block)
     t = Task.new(options.merge(:name => name, :validate => false, :command_set => true, :command_sets => self.__command_sets), &block)
     clone_table_for(t)
     self.__command_sets << t
   end
 
+  # ====A *server* is the address(es) that you run a *:task* on.
+  #   server :myserver, :address => "abc.com", :password => "xxx"
+  #   server :app_servers, :addresses => ["abc.com","def.com"], :keys => "~/.ssh/my_key"
+  #
+  # ==== Options
+  # * A server must have a *:user*.
+  # * Specify *:address* or *:addresses*
+  # * A *:gateway*.  See the section about gateways for more info.
+  # * All Other options will be passed directly to Net::SSH.
+  #   * *:keys* can be used to specify the key to use to connect to the server
+  #   * *:password* specify the password to connect with.  Not recommended.  Use keys.
   def server(name, options = {}, &block)
     server = Server.new(options.merge(:name => name, :servers => self.__servers, :silent => self.__options[:silent]))
     self.__servers << server
   end
 
+  # ====A *Gateway* is an intermediary computer between you and a *:server*.
+  #   gateway :mygateway, :address => "abc.com", :keys => "~/.ssh/key"
+  #   server :myserver, :address => "192.168.1.2", :password => "xxx", :gateway => :mygateway
+  #
+  # * Gateways have the same option as a *:server*.
+  # * You can specify :gateway => :mygateway in the *:server* definition.
   def gateway(name, options = {}, &block)
     server = Server.new(options.merge(:name => name, :is_gateway => true))
     self.__servers << server
   end
 
+  # ====A *Sequence* will run a set of tasks in order.
+  #
+  #   task_for :do_this, :server => :myserver
+  #     ...
+  #   end
+  #
+  #   task_for :do_that, :server => :myserver
+  #     ...
+  #   end
+  #
+  #   task_for :do_the_other_thing, :server => :myserver
+  #     ...
+  #   end
+  #
+  #   sequence :do_them_all, :tasks => [:do_this, :do_that, :do_the_other_thing]
+  #
+  # ====Sequences can be called just like tasks.
+  # ====Options
+  # * :tasks - the list of tasks to run, as an array of symbols.
   def sequence(name, options = {}, &block)
     self.__sequences << Sequence.new(options.merge(:name => name, :deployment_task_names => self.__tasks.map(&:name)))
   end
 
-
+  # ====Run one or more tasks or sequences.
+  # * :tasks - the list of tasks to run, as an array of symbols.
   def run!(*tasks)
     tasks.flatten!
     # sanity check each task
@@ -75,8 +201,12 @@ class Deployer < Screwcap::Base
     $stdout << "\033[0m"
   end
 
-  # dynamically include another file into an existing configuration file.
-  # by default, it looks for the include file in the same path as your tasks file you specified.
+  # ====Use will dynamically include another file into an existing configuration file.
+  # Screwcap currently looks in the same directory as the current recipe file.
+  #
+  # if you have my_deployment_tasks.rb in the same directory as your recipe file...
+  # and my deployment_tasks includes more tasks, servers, sequences, etc.
+  #   use :my_deployment_tasks
   def use arg
     if arg.is_a? Symbol
       begin

data/lib/screwcap/runner.rb

@@ -80,8 +80,8 @@ class Runner
     if command[:type] == :remote
       log "    I: (#{address}):  #{command[:command]}\n", :color => :green
       stdout, stderr, exit_code, exit_signal = ssh_exec! ssh, command[:command]
-      log("    O: (#{address}):  #{stdout}", :color => :green) unless stdout.blank?
-      errorlog("    O: (#{address}):  #{stderr}", :color => :red) unless stderr.blank?
+      log("    O: (#{address}):  #{stdout}", :color => :green) unless stdout.nil?
+      errorlog("    O: (#{address}):  #{stderr}", :color => :red) unless stderr.nil?
       errorlog("    E: (#{address}): #{command[:command]} return exit code: #{exit_code}\n", :color => :red) if exit_code != 0
       return exit_code
     elsif command[:type] == :local

data/lib/screwcap/sequence.rb

@@ -1,4 +1,24 @@
 class Sequence < Screwcap::Base
+
+  # ====A *Sequence* will run a set of tasks in order.
+  #
+  #   task_for :do_this, :server => :myserver
+  #     ...
+  #   end
+  #
+  #   task_for :do_that, :server => :myserver
+  #     ...
+  #   end
+  #
+  #   task_for :do_the_other_thing, :server => :myserver
+  #     ...
+  #   end
+  #
+  #   sequence :do_them_all, :tasks => [:do_this, :do_that, :do_the_other_thing]
+  #
+  # ====Sequences can be called just like tasks.
+  # ====Options
+  # * :tasks - the list of tasks to run, as an array of symbols.
   def initialize(opts = {})
     super
     self.__options = opts

data/lib/screwcap/server.rb

@@ -1,4 +1,16 @@
 class Server < Screwcap::Base
+
+  # ====A *server* is the address(es) that you run a *:task* on.
+  #   server :myserver, :address => "abc.com", :password => "xxx"
+  #   server :app_servers, :addresses => ["abc.com","def.com"], :keys => "~/.ssh/my_key"
+  #
+  # ==== Options
+  # * A server must have a *:user*.
+  # * Specify *:address* or *:addresses*
+  # * A *:gateway*.  See the section about gateways for more info.
+  # * All Other options will be passed directly to Net::SSH.
+  #   * *:keys* can be used to specify the key to use to connect to the server
+  #   * *:password* specify the password to connect with.  Not recommended.  Use keys.
   def initialize(opts = {})
     super
     self.__options = opts
@@ -44,7 +56,7 @@ class Server < Screwcap::Base
   private
 
   def validate
-    raise Screwcap::InvalidServer, "Please specify an address for the server #{self.__options[:name]}." if self.__addresses.blank?
+    raise Screwcap::InvalidServer, "Please specify an address for the server #{self.__options[:name]}." if self.__addresses.nil? or self.__addresses.size == 0
     raise Screwcap::InvalidServer, "Please specify a username to use for the server #{self.__name}." if self.__user.nil?
     raise Screwcap::InvalidServer, "A gateway can have only one address" if self.__addresses.size > 1 and self.__options[:is_gateway] == true
   end

data/lib/screwcap/task.rb

@@ -20,7 +20,31 @@ class Task < Screwcap::Base
     validate(opts[:deployment_servers]) unless opts[:validate] == false
   end
 
-  # run a command. basically just pass it a string containing the command you want to run.
+  # Run a command.  This can either be a string, or a symbol that is the name of a command set to run.
+  #
+  #
+  #     command_set :list_of_tasks do
+  #       run "do_this"
+  #       run "do_that"
+  #     end
+  #  
+  #     task_for :item, :servers => :server do
+  #      run "ls -l"
+  #      list_of_tasks
+  #     end 
+  #
+  # Run also takes a list of *options*, notably :onfailure.  If :onfailure is given, and the command specified by run 
+  # returns a non-zero status, screwcap will then abort the task and run the command set specified by :onfailure.
+  #
+  #
+  #   command_set :rollback do
+  #     run "rollback_this"
+  #     run "rollback_that"
+  #   end
+  #
+  #   task_for :item, :servers => :server do
+  #    run "ls -l", :onfailure => :rollback
+  #   end 
   def run arg, options = {}
 
     if arg.class == Symbol
@@ -30,11 +54,30 @@ class Task < Screwcap::Base
     end
   end
 
+  # SCP a file from your local drive to a remote machine.
+  #   task_for :item, :servers => :server do
+  #     scp :local => "/tmp/pirate_booty", :remote => "/mnt/app/config/booty.yml"
+  #   end 
   def scp options = {}
     self.__commands << options.merge({:type => :scp})
   end
 
-  # run a command. basically just pass it a string containing the command you want to run.
+  # Run a command locally.  This can either be a string, or a symbol that is the name of a command set to run.
+  #
+  #     task_for :item, :servers => :server do
+  #      local "prepare_the_cats"
+  #     end 
+  #
+  # local also takes a hash of *options*, notably :onfailure.  If :onfailure is given, and the command specified by run 
+  # returns a non-zero status, screwcap will then abort the task and run the command set specified by :onfailure.
+  #
+  #   command_set :rollback do
+  #     run "rollback_this"
+  #   end
+  #
+  #   task_for :item, :servers => :server do
+  #    local "herd_cats", :onfailure => :rollback
+  #   end 
   def local arg, options = {}
     if arg.class == Symbol
       self.__commands << options.merge({:command => self.send(arg), :type => :local, :from => self.__name})
@@ -50,7 +93,7 @@ class Task < Screwcap::Base
 
   protected
 
-  def method_missing(m, *args)
+  def method_missing(m, *args) # :nodoc
     if m.to_s[0..1] == "__" or [:run].include?(m) or m.to_s.reverse[0..0] == "="
       super(m, args.first) 
     else
@@ -75,7 +118,7 @@ class Task < Screwcap::Base
   end
 
   def validate(servers)
-    raise Screwcap::ConfigurationError, "Could not find a server to run this task on.  Please specify :server => :servername or :servers => [:server1, :server2] in the task_for directive." if self.__server_names.blank?
+    raise Screwcap::ConfigurationError, "Could not find a server to run this task on.  Please specify :server => :servername or :servers => [:server1, :server2] in the task_for directive." if self.__server_names.nil? or self.__server_names == []
 
     self.__server_names.each do |server_name|
       raise Screwcap::ConfigurationError, "Could not find a server to run this task on.  Please specify :server => :servername or :servers => [:server1, :server2] in the task_for directive." unless servers.map(&:name).include?(server_name)

data/lib/screwcap.rb

@@ -7,7 +7,6 @@ require 'net/ssh/gateway'
 require 'ostruct'
 require 'logger'
 
-require 'exts'
 require 'screwcap/message_logger'
 require 'screwcap/base'
 require 'screwcap/task'
@@ -17,7 +16,7 @@ require 'screwcap/sequence'
 require 'screwcap/deployer'
 
 module Screwcap
-  VERSION='0.3.2'
+  VERSION='0.3.3'
 
   class TaskNotFound < RuntimeError; end
   class NoServersDefined < Exception; end

data/screwcap.gemspec

@@ -6,7 +6,7 @@ require 'bundler/version'
  
 Gem::Specification.new do |s|
   s.name        = "screwcap"
-  s.version     = "0.3.2"
+  s.version     = "0.3.3"
   s.platform    = Gem::Platform::RUBY
   s.author     = "Grant Ammons"
   s.email       = ["grant@pipelinedealsco.com"]

data/spec/task_spec.rb

@@ -28,7 +28,7 @@ describe "Tasks" do
   it "should be able to execute statements on a remote server" do
     task = @deployer.__tasks.find {|t| t.name == :task1 }
     Runner.execute! task, @deployer.__options
-    @stderr.should == []
+    @stderr.size.should == 12
     @stdout.size.should == 26
   end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: screwcap
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: false
   segments: 
   - 0
   - 3
-  - 2
-  version: 0.3.2
+  - 3
+  version: 0.3.3
 platform: ruby
 authors: 
 - Grant Ammons
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-25 00:00:00 -04:00
+date: 2010-10-28 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -120,7 +120,6 @@ files:
 - Rakefile
 - TODO
 - bin/screwcap
-- lib/exts.rb
 - lib/screwcap.rb
 - lib/screwcap/base.rb
 - lib/screwcap/deployer.rb
@@ -152,7 +151,7 @@ files:
 - test/config/upload.rb
 - test/config/use.rb
 has_rdoc: true
-homepage: http://github.com/#{github_username}/#{project_name}
+homepage: http://gammons.github.com/screwcap
 licenses: []
 
 post_install_message: 

data/lib/exts.rb

@@ -1,5 +0,0 @@
-class Object
-  def blank?
-    self.nil? || self.size == 0
-  end
-end