doable 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 56e965ddda372a9869ce205446246564c6ccff61
+  data.tar.gz: 2b7a330755f47d29ab09ea8534573b5091ce277a
+SHA512:
+  metadata.gz: c0f5a9c98bf55b5f0a6e68283605df03ee2c643f43b395d5ec25f387934289fab656128bb828b13cec3c6ed0d07486187110fd40d970b6bab6daaaae542cb1ce
+  data.tar.gz: 0475b2cc4859475763911c159eec725881b9a7297e045b2657d96bb111af45e8011ef1223aa2c1ef57d2cee859799d2b069ea60bdb66e52e4fbb1274c0ec5795

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 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
+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/lib/doable/exceptions/framework_exceptions.rb

@@ -0,0 +1,34 @@
+module Doable
+  module Exceptions
+    module FrameworkExceptions
+      class GenericFrameworkError < StandardError
+      end
+
+      class InvalidInput < GenericFrameworkError
+      end
+
+      class NotApplicable < InvalidInput
+      end
+
+      class InvalidAction < GenericFrameworkError
+      end
+
+      class MissingDefinitionsDirectory < GenericFrameworkError
+      end
+
+      class MissingParameter < InvalidInput
+      end
+
+      # This exception should be used by those rare features that aren't cross-platform
+      class UnsupportedPlatformFeature < GenericFrameworkError
+      end
+
+      # !These exceptions should never be caught by anything!
+      class SkipStep < StandardError
+      end
+
+      class RolledBack < StandardError
+      end
+    end
+  end
+end

data/lib/doable/helpers/framework_helpers.rb

@@ -0,0 +1,11 @@
+module Doable
+  module Helpers
+    module FrameworkHelpers
+      # 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")
+        raise SkipStep, message
+      end
+    end
+  end
+end

data/lib/doable/helpers/logging_helpers.rb

@@ -0,0 +1,46 @@
+module Doable
+  module Helpers
+    module LoggingHelpers
+      # Create a mutex to manage logging to STDOUT
+      LOGGING_MUTEX = Mutex.new
+      LOGGING_MUTEX.freeze
+      
+      # Applies a color (with optional addition settings) to some text
+      # @return [String]
+      # @param text [String] The String to be colorized
+      # @param color [Symbol] The color to use. Must be one of [ :gray, :red, :green, :yellow, :blue, :magenta, :cyan, :white ]
+      def colorize(text, color, options = {})
+        background = options[:background] || options[:bg] || false
+        style = options[:style].to_sym if options[:style]
+        offsets = [ :gray, :red, :green, :yellow, :blue, :magenta, :cyan, :white ]
+        styles = [ :normal, :bold, :dark, :italic, :underline, :xx, :xx, :underline, :xx, :strikethrough ]
+        start = background ? 40 : 30
+        color_code = start + (offsets.index(color) || 8)
+        style_code = styles.index(style) || 0
+        "\e[#{style_code};#{color_code}m#{text}\e[0m"
+      end
+  
+      # All logging or writing to STDOUT should happen here (to be threadsafe)
+      def log(text, level = :info)
+        level = level.to_sym
+    
+        color, options = case level
+        when :info
+          [:white, {}]
+        when :warn
+          [:yellow, {}]
+        when :error
+          [:red, {:bg => true}]
+        when :success
+          [:green, {}]
+        else
+          [:gray, {}]
+        end
+    
+        LOGGING_MUTEX.synchronize { 
+          puts "[#{Time.now.strftime('%Y/%m/%d %H:%M:%S')}] #{colorize(text, color, options)}" 
+        }
+      end
+    end
+  end
+end

data/lib/doable/helpers/password_helpers.rb

@@ -0,0 +1,15 @@
+module Doable
+  module Helpers
+    module PasswordHelpers
+      # Generates a password
+      # @param length [Fixnum] Length of the password
+      # @param options [Hash] Options hash for specifying password details
+      # @return [String]
+      def generate_password(length = 8, options = {})
+        options[:characters] ||= [*(2..9), *('a'..'z'), *('A'..'Z')] - %w(i l O)
+      
+        (1..length).collect{|a| options[:characters][rand(options[:characters].size)] }.join
+      end # generate_password()
+    end
+  end
+end

data/lib/doable/job.rb

@@ -0,0 +1,224 @@
+module Doable
+  # The Job class is responsible for describing the process of running some set of steps.
+  # It utilizes a very specific DSL for defining what steps need executing, along with their order. It
+  # 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
+    attr_reader :steps, :hooks, :handlers, :threads
+    
+    def self.plan(&block)
+      self.new(&block)
+    end
+
+    def initialize
+      @hooks    = {}
+      @steps    = []
+      @handlers = {}
+      @threads  = []
+      yield self
+    end
+
+    # Registers a hook action to be performed when the hook is triggered
+    # @param hook [Symbol] Name of the hook to register the action with
+    # @param options [Hash]
+    # @param block [Proc]
+    # @return [Step]
+    def on(hook, options = {}, &block)
+      @hooks[hook] ||= []
+      @hooks[hook] << Step.new(self, options, &block)
+    end # on()
+
+    # Adds a step to the queue
+    # @param options [Hash]
+    # @param block [Proc]
+    # @return [Step]
+    def step(options = {}, &block)
+      @steps << Step.new(self, options, &block)
+    end # step()
+
+    # Registers an action to be performed before normal step execution
+    # @param options [Hash]
+    # @param block [Proc]
+    # @return [Step]
+    def before(options = {}, &block)
+      on(:before, options, &block)
+    end # before()
+
+    # Registers an action to be performed after normal execution completes
+    # @param options [Hash]
+    # @param block [Proc]
+    # @return [Boolean]
+    def after(options = {}, &block)
+      on(:after, options, &block)
+    end # after()
+
+    # Add a step to the queue, but first wrap it in a begin..rescue
+    # WARNING! Exception handlers are __not__ used with these steps, as they never actually raise exceptions
+    # @param options [Hash]
+    # @param block [Proc]
+    # @return [Boolean]
+    def attempt(options = {}, &block)
+      @steps << Step.new(self, options) do
+        begin
+          block.call
+        rescue SkipStep => e
+          raise e # We'll rescue this somewhere higher up the stack
+        rescue => e
+          log "Ignoring Exception in attempted step: #{colorize("#{e.class}: (#{e.message})", :red)}"
+        end
+      end
+      return true
+    end # attempt()
+
+    # Allow running steps in the background
+    # @param options [Hash]
+    # @param block [Proc]
+    # @return [Step]
+    def background(options = {}, &block)
+      @steps << Step.new(self, options) do
+        @threads << Thread.new { block.call }
+      end
+    end # background()
+
+    # Check if background steps are running
+    # @return [Boolean]
+    def multitasking?
+      return @threads.collect {|t| t if t.alive? }.compact.empty? ? false : true
+    end # multitasking?()
+    
+    # Trigger a rollback of the entire Job, based on calls to #rollback!() on each eligible Step
+    def rollback!
+      log "Rolling Back...", :warn
+      @hooks[:after].reverse.each {|s| s.rollback! if s.rollbackable? }
+      @steps.reverse.each {|s| s.rollback! if s.rollbackable? }
+      @hooks[:before].reverse.each {|s| s.rollback! if s.rollbackable? }
+      log "Rollback complete!", :warn
+      raise RolledBack
+    end # rollback!()
+
+    # Returns the binding context of the Job
+    # @return [Binding]
+    def context
+      binding
+    end # context()
+
+    # Register a handler for named exception
+    # @param exception [String,StandardError] Exception to register handler for
+    # @param block [Proc]
+    def handle(exception, &block)
+      @handlers[exception] = Step.new(self, &block)
+    end # handle()
+
+    # This triggers a block associated with a hook
+    # @param hook [Symbol] Hook to trigger
+    def trigger(hook)
+      @hooks[hook].each_with_index do |step, index|
+        begin
+          step.call
+        rescue SkipStep => e
+          step.skip
+          log e.message, :warn
+        rescue => e
+          if @handlers[e.message]
+            log "Handling #{e.class}: (#{e.message})", :warn
+            @handlers[e.message].call(e, step)
+            step.handled unless step.status == :skipped       # Don't mark the step as "handled" if it was skipped
+          elsif @handlers[e.class]
+            log "Handling #{e.class}: (#{e.message})", :warn
+            @handlers[e.class].call(e, step)
+            step.handled unless step.status == :skipped       # Don't mark the step as "handled" if it was skipped
+          else
+            # Check the ancestry of the exception to see if any lower level Exception classes are caught
+            e.class.ancestors[1..-4].each do |ancestor|
+              if @handlers[ancestor]
+                log "Handling #{e.class}: (#{e.message}) via handler for #{ancestor}", :warn
+                @handlers[ancestor].call(e, step)
+                step.handled unless step.status == :skipped   # Don't mark the step as "handled" if it was skipped
+              end # if @@handlers[ancestor]
+            end
+            
+            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
+                raise message
+              end
+            end # unless
+          end
+        end # begin()
+      end if @hooks[hook] # each_with_index()
+    end # trigger()
+
+    # Here we actually trigger the execution of a Job
+    def run
+      #merge_config FILE_CONFIG
+      #merge_config CLI_CONFIG
+      ## Run our defaults Proc to merge in any default configs
+      #@defaults.call(@@config)
+
+      # before hooks
+      trigger(:before)
+      
+      # Actual installer steps
+      @steps.each_with_index do |step, index|
+        begin
+          step.call
+        rescue SkipStep => e
+          step.skip
+          log e.message, :warn
+        rescue => e
+          if @handlers[e.message]
+            log "Handling #{e.class}: (#{e.message})", :warn
+            @handlers[e.message].call(e, step)
+            step.handled
+          elsif @handlers[e.class]
+            log "Handling #{e.class}: (#{e.message})", :warn
+            @handlers[e.class].call(e, step)
+            step.handled
+          else
+            # Check the ancestry of the exception to see if any lower level Exception classes are caught
+            e.class.ancestors[1..-4].each do |ancestor|
+              if @handlers[ancestor]
+                log "Handling #{e.class}: (#{e.message}) via handler for #{ancestor}", :warn
+                @handlers[ancestor].call(e, step)
+                step.handled
+              end # if @handlers[ancestor]
+            end
+            
+            unless step.successful?
+              message = "\n\nUnhandled Exception in #{colorize("steps[#{index}]", :yellow)}: #{colorize("#{e.class}: (#{e.message})", :red)}\n\n"
+              #if @config.auto_rollback
+              #  log message
+              #  rollback!
+              #else
+                raise message
+              #end
+            end # unless
+          end # if @handlers...
+        end # rescue
+      end # @steps.each_with_index
+      
+      # after hooks
+      trigger(:after)
+      
+      # bring together all background threads
+      unless @threads.empty?
+        log "Cleaning up background tasks..."
+        @threads.each do |t|
+          begin
+            t.join
+          rescue => e
+            # We don't really need to do anything here,
+            # we've already handled or died from aborted Threads
+          end
+        end
+      end
+
+      log "All Job steps completed successfully!", :success   # This should only happen if everything goes well
+    end # run()
+  end
+end

data/lib/doable/step.rb

@@ -0,0 +1,75 @@
+module Doable
+  # This class contains the actual work to be done
+  class Step
+    attr_reader :success, :status, :task, :name
+    
+    # @param options [Hash]
+    # @param block [Proc]
+    def initialize(context, options = {}, &block)
+      @context  = context
+      @success  = false
+      @status   = :unattempted
+      @task     = block
+      @name     = options.key?(:name) ? options[:key] : block.to_s
+      @rollback = nil
+    end
+
+    # Call our step, passing any arguments to the block (task) itself
+    def call(*args)
+      @status   = :failed     # first assume our attempt fails
+      @context.instance_exec(*args, &@task)       # try to execute the Step's task
+      @success  = true        # we'll only get here if no exceptions were raised
+      @status   = :completed  # if we're here, the Step is complete
+      return self
+    end # call()
+    
+    # Set the Step's status to 'handled'
+    def handled
+      @status   = :handled
+      @success  = true        # Might want to change this to false...
+    end # handled
+
+    # Boolean way of requesting success
+    # @return [Boolean]
+    def successful?
+      return @success
+    end
+    
+    # Wrapper around call used for retrying a step. Recommended approach to retrying as this may be
+    # enhanced in the future.
+    def retry(*args)
+      call(*args)
+    end
+
+    # allow skipping steps (needs to be called externally)
+    def skip
+      @status   = :skipped
+      @success  = false
+    end
+
+    # Sets up a block to call when rolling back this step
+    # @return [Boolean]
+    def rollback(&block)
+      @rollback = block
+      return true
+    end
+
+    # Query a step to see if it can be rolled back
+    # @return [Boolean]
+    def rollbackable?
+      if @rollback and [:completed, :handled, :failed].include?(@status)
+        return true
+      else
+        return false
+      end
+    end
+
+    # Actually rollback this step
+    def rollback!
+      @rollback.call
+      @status = :rolledback
+      @success = false
+    end
+
+  end # class Step
+end

data/lib/doable.rb

@@ -0,0 +1,17 @@
+# Standard Library includes
+require 'digest'
+require 'base64'
+require 'fileutils'
+require 'tempfile'
+require 'ostruct'
+require 'erb'
+require 'thread'
+require 'pathname'
+require 'yaml'
+# Framework requirements
+require 'doable/exceptions/framework_exceptions'
+include Doable::Exceptions::FrameworkExceptions
+require 'doable/helpers/logging_helpers'
+require 'doable/helpers/framework_helpers'
+require 'doable/step'
+require 'doable/job'

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: doable
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Jonathan Gnagy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-29 00:00:00.000000000 Z
+dependencies: []
+description: A framework for automating tasks with ease
+email: jonathan.gnagy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- 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/job.rb
+- lib/doable/step.rb
+homepage: 
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.0
+signing_key: 
+specification_version: 4
+summary: Ruby Doable Framework
+test_files: []
+has_rdoc: