doable 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f3b42f3e5a03262223ec145feb55b84a0c0d4d1a
-  data.tar.gz: efe266d164608fa68728e7198b76aaae55f61c7f
+  metadata.gz: 8049e12988f84644e8ad77af4aa81c69586cd584
+  data.tar.gz: cdde8ea4ff303b1cdd1407ce2a45f4155fad67f4
 SHA512:
-  metadata.gz: a8209389c4938a5ae05c0550d65301e7e9e194087933d2d8e07025ec54bad97d02f9335ebabee8096d28e06e7089591032a4f4f5ab6f2327a3442d361d96e817
-  data.tar.gz: 665e86ed5616a54061eb333aef7e89260e9a11f4b657e2c5bc592aa0433a8396746616acaa15423f8da54208c1407eee5fd01a0f79d433b723ef7c3f7a73e792
+  metadata.gz: 8e5e57273ae3eb3a16aafa7992a2513bc7eefada445a1feac54d53e55a4633001eeed83b7a7967a3dbced96d7868a7fb041db469c5ed968763c4023a2a2f8af4
+  data.tar.gz: e13885ee5299ae731b16a9d1c83ec4868994a66cd2ed57e5bd0a8372b7758a3645e12c95e5ad4d0eab946e84d42c71af7da200b6d41caef7ccf20bebc9f56074

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Jonathan Gnagy <jonathan.gnagy@gmail.com>
+Copyright (c) 2015 Jonathan Gnagy <jonathan.gnagy@gmail.com>
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/README.md

@@ -0,0 +1,88 @@
+Ruby Doable Framework
+=====================
+
+About
+-----
+This is a gem largely targeted and making the lives of DevOps / SysAdmin types easier. Whether it is installing complicated sets of software, writing maintenance scripts, or automating administrative tasks, `Doable` aims to simplify these common tasks, as well as make them more reliable and robust.
+
+The core set of values for this framework are:
+
+* Extensibility
+* Modularity
+* Simplicity
+* Concurrency
+* Flexibility
+* Reliability
+* Remaining lightweight
+  
+These goals are largely achieved through a small set of core features, with nearly all functionality broken out into plugins that can be enabled as required.
+
+Building
+-----
+
+The eventual goal is for this gem to simply be available via a normal rubygems search, but until then, you must build and install the gem yourself. This can be done like so:
+
+    #!bash
+    # need Mercurial to clone the repo... or download it from https://bitbucket.org/jgnagy/doable/get/tip.zip
+    hg clone https://bitbucket.org/jgnagy/doable
+    cd doable
+    # highly recommend using RVM here, and Ruby 2.x or above
+    gem build doable.gemspec
+    # install what you just built
+    gem install ./doable-*.gem
+
+Sometimes you might get lucky and there's a semi-recent version of the pre-built gem available on bitbucket [here](https://bitbucket.org/jgnagy/doable/downloads).
+
+Usage
+-----
+
+Require the right gem(s):
+
+    #!ruby
+    require 'doable'
+
+To create a simple job, define a plan:
+
+    #!ruby
+    job = Doable::Job.plan do |j|
+      j.before  { log "Starting my awesome job" }
+      j.step    { # do some stuff here }
+      j.attempt { # try to do some other stuff here }
+      j.after   { log "Looks like we're all set" }
+    end
+    
+    job.run # executes our job
+
+This job is obviously pretty boring, but it shows some of the basics. Now let's continue and include some additional helpers in a new, more complex job:
+
+    #!ruby
+    require 'doable/helpers/password'
+    
+    class JobWithPasswords < Doable::Job
+      include Doable::Helpers::Password
+    end
+    
+    job2 = JobWithPasswords.plan do |j|
+      j.before  { log "Here's a password for you..." }
+      j.step    { puts "Password: " + generate_password(16) }
+    end
+
+    job2.run
+
+After this job runs, you should see output that looks something like:
+
+    [2015/01/29 00:10:36] Here's a password for you...
+    Password: ZwyIVH8LjHGYYzDX
+    [2015/01/29 00:10:36] All Job steps completed successfully!
+
+Hopefully this demonstrates how to get access to additional helper methods.
+
+License
+-------
+
+Doable is distributed under the MIT License.
+
+Contributing
+------------
+
+I welcome pull-requests. I may or may not use your code, but I encourage the growth of others too. If this project inspires you to contribute, feel free to fork my code and submit a pull request. In most cases, I'll probably recommend you package additions in an extension gem rather than including new files, etc, directly into the core codebase.

data/lib/doable/exceptions/{framework_exceptions.rb → framework.rb}

@@ -1,6 +1,6 @@
 module Doable
   module Exceptions
-    module FrameworkExceptions
+    module Framework
       class GenericFrameworkError < StandardError
       end
 

data/lib/doable/exceptions/os.rb

@@ -0,0 +1,23 @@
+module Doable
+  module Exceptions
+    module OS
+      class OSException < GenericFrameworkError
+      end
+
+      class WrongUser < OSException
+      end
+
+      class MissingDirectory < OSException
+      end
+
+      class DirectoryExists < OSException
+      end
+
+      class InvalidHostname < OSException
+      end
+
+      class MissingFile < OSException
+      end
+    end
+  end
+end

data/lib/doable/helpers/{framework_helpers.rb → framework.rb}

@@ -1,6 +1,6 @@
 module Doable
   module Helpers
-    module FrameworkHelpers
+    module Framework
       # raises a special skip exception and __must__ only be run in job steps
       # @raise [SkipStep] Do __not__ handle this exception!
       def skip(message = "Skipping Step")

data/lib/doable/helpers/{logging_helpers.rb → logging.rb}

@@ -1,10 +1,9 @@
 module Doable
+  # Create a mutex to manage logging to STDOUT
+  LOGGING_MUTEX = Mutex.new
+  LOGGING_MUTEX.freeze
   module Helpers
-    module LoggingHelpers
-      # Create a mutex to manage logging to STDOUT
-      LOGGING_MUTEX = Mutex.new
-      LOGGING_MUTEX.freeze
-      
+    module Logging
       # Applies a color (with optional addition settings) to some text
       # @return [String]
       # @param text [String] The String to be colorized

data/lib/doable/helpers/os.rb

@@ -0,0 +1,129 @@
+require 'doable/exceptions/os'
+
+module Doable
+  module Helpers
+    module OS
+      include Doable::Exceptions::OS
+      # Confirms the current script is running as a certain user
+      # @raise [WrongUser]
+      # @param user [String] User to confirm we're using
+      def must_run_as(user)
+        raise WrongUser, user unless user == Etc.getpwuid.name
+        log "Running as correct user"
+      end
+
+      # Ensure a directory exists
+      # @param directory [String] Directory to create or verify
+      # @return [String]
+      def find_or_create_directory(directory)
+        full_path = File.expand_path(directory)
+        FileUtils.mkdir_p(full_path) unless File.directory?(full_path)
+        return full_path
+      end
+
+      # Die if a directory doesn't exist
+      # @raise [MissingDirectory]
+      # @param directory [String] Directory to verify
+      # @return [String]
+      def find_directory(directory)
+        full_path = File.expand_path(directory)
+        raise MissingDirectory, directory unless File.directory?(full_path)
+        return full_path
+      end
+
+      # Die if a directory __does__ exist.
+      # Useful for ensuring software wasn't previously installed, etc.
+      # @raise [DirectoryExists]
+      # @param directory [String] Directory to verify does not exist
+      # @return [Boolean]
+      def die_if_dir_exists(directory)
+        full_path = File.expand_path(directory)
+        if File.directory?(full_path)
+          raise DirectoryExists, directory
+        else
+          return true
+        end
+      end
+
+      # Remove a file or directory
+      # @param file_or_directory [String] File or directory path to remove
+      def remove(file_or_directory)
+        FileUtils.rm_rf(File.expand_path(file_or_directory))
+      end
+
+      # Check that the OS can resolve a hostname
+      # @raise [InvalidHostname]
+      # @param hostname [String] Hostname to validate is resolveable
+      def validate_host(hostname)
+        raise InvalidHostname, hostname unless Resolv.getaddress(hostname)
+      end
+
+      # Ruby in-memory equivalent of `tee`
+      # Note that this command is dangerous for very long command output. Need to consider setting a buffer max size for this.
+      # @param command [String] Command to run
+      # @return [Fixnum, String] Returns the exit code of the command, along with any output
+      def tee(command)
+        command_output = ""
+        IO.popen(command) do |io|
+          while line = io.gets
+            command_output << line
+            LOGGING_MUTEX.synchronize { puts line } 
+          end
+        end
+        return [$?.exitstatus, command_output]
+      end
+
+      # Used like Unix touch
+      # @param file_list [Array<String>,String] List of files to create or verify
+      def touch(file_list, options = {})
+        FileUtils.touch(file_list, options)
+      end
+
+      # Used for backwards compatibility (just a wrapper for touch)
+      # @param file [String] File to create or verify
+      def find_or_create_file(file)
+        unless File.exists?(File.expand_path(file))
+          log "File '#{file}' does not seem to exist... creating it...", :warn
+          touch File.expand_path(file)
+        end
+        return File.expand_path(file)
+      end
+
+      # Throws an exception if a file doesn't exist
+      # @raise [MissingFile]
+      # @param file [String] File or directory to verify
+      # @param message [String] Option message to log if file does not exist
+      # @return [String]
+      def find_file(file, message = "")
+        unless File.exists?(File.expand_path(file))
+          message.empty? ? log("Filename #{file} is invalid", :error) : log(message, :error)
+          raise MissingFile, file
+        end
+
+        return File.expand_path(file)
+      end
+
+      # A simple replacement for `sed`. This is far from a complete implementation and should be used sparingly. A much
+      # better approach is to use ERB files.
+      # @raise [InvalidInput]
+      # @param substitutions [Hash] Hash of Strings indexing Strings. Keys are replaced with their value.
+      # @param input_file [IO,String] IO object or String to use as the source
+      # @param output_file [IO,String] IO object or String to use as the destination
+      def sed(substitutions, input_file, output_file)
+        input_file  = input_file.kind_of?(IO) ? input_file : File.open(input_file, "r")
+        output_file = output_file.kind_of?(IO) ? output_file : File.open(output_file, "w")
+        raise InvalidInput unless substitutions.kind_of?(Hash)
+
+        # Very fancy way to replace things in a file and write to a new file
+        output_file.puts(
+          input_file.read.gsub(Regexp.union(substitutions.keys)) do |match|
+            # Hideous way to work with regular expressions *and* string substitutions in a single pass over a large file
+            substitutions[substitutions.keys.keep_if {|s| substitutions[s].to_s if match == s or s.match(match) }.first].to_s
+          end
+        )
+        output_file.close
+      end
+
+    end
+  end
+end

data/lib/doable/helpers/{password_helpers.rb → password.rb}

@@ -1,6 +1,6 @@
 module Doable
   module Helpers
-    module PasswordHelpers
+    module Password
       # Generates a password
       # @param length [Fixnum] Length of the password
       # @param options [Hash] Options hash for specifying password details

data/lib/doable/job.rb

@@ -4,8 +4,8 @@ module Doable
   # can also describe how to recover when things break and provides hooks and triggers to make more flexible
   # scripts for varying environments.
   class Job
-    include Helpers::FrameworkHelpers
-    include Helpers::LoggingHelpers
+    include Helpers::Framework
+    include Helpers::Logging
     attr_reader :steps, :hooks, :handlers, :threads
     
     def self.plan(&block)
@@ -141,12 +141,12 @@ module Doable
             
             unless step.successful?
               message = "\n\nUnhandled Exception in #{colorize("hooks##{hook}[#{index}]", :yellow)}: #{colorize("#{e.class}: (#{e.message})", :red)}\n\n"
-              if @config.auto_rollback
-                log message
-                rollback!
-              else
+              #if @config.auto_rollback
+              #  log message
+              #  rollback!
+              #else
                 raise message
-              end
+              #end
             end # unless
           end
         end # begin()

data/lib/doable.rb

@@ -8,10 +8,12 @@ require 'erb'
 require 'thread'
 require 'pathname'
 require 'yaml'
+require 'etc'
+require 'resolv'
 # Framework requirements
-require 'doable/exceptions/framework_exceptions'
-include Doable::Exceptions::FrameworkExceptions
-require 'doable/helpers/logging_helpers'
-require 'doable/helpers/framework_helpers'
+require 'doable/exceptions/framework'
+include Doable::Exceptions::Framework
+require 'doable/helpers/logging'
+require 'doable/helpers/framework'
 require 'doable/step'
 require 'doable/job'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: doable
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Jonathan Gnagy
@@ -17,11 +17,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
+- README.md
 - lib/doable.rb
-- lib/doable/exceptions/framework_exceptions.rb
-- lib/doable/helpers/framework_helpers.rb
-- lib/doable/helpers/logging_helpers.rb
-- lib/doable/helpers/password_helpers.rb
+- lib/doable/exceptions/framework.rb
+- lib/doable/exceptions/os.rb
+- lib/doable/helpers/framework.rb
+- lib/doable/helpers/logging.rb
+- lib/doable/helpers/os.rb
+- lib/doable/helpers/password.rb
 - lib/doable/job.rb
 - lib/doable/step.rb
 homepage: https://rubygems.org/gems/doable