cuboid 0.0.0 → 0.0.1alpha

data/lib/cuboid/application.rb

@@ -0,0 +1,326 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'monitor'
+require 'bundler/setup'
+
+require_relative 'options'
+
+module Cuboid
+
+lib = Options.paths.lib
+require lib + 'support/mixins/spec_instances'
+require lib + 'system'
+require lib + 'version'
+require lib + 'support'
+require lib + 'ruby'
+require lib + 'error'
+require lib + 'utilities'
+require lib + 'snapshot'
+require lib + 'report'
+require lib + 'processes'
+require lib + 'application/runtime'
+
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class Application
+    include Singleton
+
+    module PrependMethods
+
+        def run
+            if !self.class.valid_options?( options )
+                fail ArgumentError, 'Invalid options!'
+            end
+
+            prepare
+            return if aborted? || suspended?
+
+            state.status = :running
+
+            super if defined? super
+
+            return if aborted? || suspended?
+
+            clean_up
+            state.status = :done
+
+            true
+        end
+
+        # Cleans up the framework; should be called after running the audit or
+        # after canceling a running scan.
+        def clean_up
+            return if @cleaned_up
+            @cleaned_up = true
+
+            state.resume
+
+            state.status = :cleanup
+
+            @finish_datetime  = Time.now
+            @start_datetime ||= Time.now
+
+            state.running = false
+
+            super if defined? super
+
+            true
+        end
+
+        private
+
+        # @note Must be called before calling any audit methods.
+        #
+        # Prepares the framework for the audit.
+        #
+        # * Sets the status to `:preparing`.
+        # * Starts the clock.
+        def prepare
+            state.status  = :preparing
+            state.running = true
+            @start_datetime = Time.now
+
+            super if defined? super
+        end
+
+    end
+
+    class <<self
+
+        def provision_cores( cores )
+            @max_cores = cores
+        end
+
+        def max_cores
+            @max_cores ||= 0
+        end
+
+        def provision_memory( ram )
+            @max_memory = ram
+        end
+
+        def max_memory
+            @max_memory ||= 0
+        end
+
+        def provision_disk( ram )
+            @max_disk = ram
+        end
+
+        def max_disk
+            @max_memory ||= 0
+        end
+
+        def instance_service_for(name, service )
+            instance_services[name] = service
+        end
+
+        def instance_services
+            @instance_services ||= {}
+        end
+
+        def rest_service_for( name, service )
+            rest_services[name] = service
+        end
+
+        def rest_services
+            @rest_services ||= {}
+        end
+
+        def dispatcher_service_for( name, service )
+            dispatcher_services[name] = service
+        end
+
+        def dispatcher_services
+            @dispatcher_services ||= {}
+        end
+
+        def handler_for( signal, handler )
+            signal_handlers[signal] = handler
+        end
+
+        def signal_handlers
+            @signal_handlers ||= {}
+        end
+
+        def serialize_with( serializer)
+            @serializer = serializer
+        end
+
+        def serializer
+            @serializer ||= nil
+            @serializer || RPC::Serializer
+        end
+
+        def validate_options_with( handler )
+            @validate_options_with = handler
+        end
+
+        def valid_options?( options )
+            @validate_options_with ||= nil
+            if @validate_options_with
+                return instance.method( @validate_options_with ).call( options )
+            end
+
+            true
+        end
+
+        def source_location
+            splits = self.to_s.split ( '::' )
+            app    = splits.pop
+
+            last_const = Object
+            splits.each do |const_name|
+                last_const = last_const.const_get( const_name.to_sym )
+            end
+
+            last_const.const_source_location( app.to_sym ).first
+        end
+
+        def spawn( type, options = {}, &block )
+            const = nil
+
+            case type
+            when :instance
+                const = :Instances
+            when :dispatcher
+                const = :Dispatchers
+            when :scheduler
+                const = :Schedulers
+            when :rest
+                return Processes::Manager.spawn(
+                    :rest_service,
+                    options.merge( options: { paths: { application: source_location } } ),
+                    &block
+                )
+            end
+
+            Processes.const_get( const ).spawn(
+              options.merge( application: source_location ),
+              &block
+            )
+        end
+
+        def connect( info )
+            info = info.my_symbolize_keys
+            Processes::Instances.connect( info[:url], info[:token] )
+        end
+
+        def inherited( application )
+            super
+
+            application.prepend PrependMethods
+            @application = application
+        end
+
+        def application
+            @application ||= nil
+        end
+
+        def method_missing( sym, *args, &block )
+            if instance.respond_to?( sym )
+                instance.send( sym, *args, &block )
+            else
+                super( sym, *args, &block )
+            end
+        end
+
+        def respond_to?( *args )
+            super || instance.respond_to?( *args )
+        end
+
+    end
+
+    include UI::Output
+    include Utilities
+
+    prepend Support::Mixins::SpecInstances
+    include Support::Mixins::Observable
+    include Support::Mixins::Parts
+
+    # {Framework} error namespace.
+    #
+    # All {Framework} errors inherit from and live under it.
+    #
+    # When I say Framework I mean the {Framework} class, not the entire Engine
+    # Framework.
+    #
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class Error < Cuboid::Error
+    end
+
+    def initialize
+        super
+
+        @runtime = Runtime.new
+    end
+
+    def runtime
+        @runtime
+    end
+
+    def options=( opts )
+        Options.application = opts
+    end
+
+    def options
+        Options.application
+    end
+
+    # @return   [Hash]
+    #
+    #   Framework statistics:
+    #
+    #   *  `:runtime`       -- Scan runtime in seconds.
+    def statistics
+        {
+            runtime: @start_datetime ? (@finish_datetime || Time.now) - @start_datetime : 0,
+        }
+    end
+
+    def inspect
+        stats = statistics
+
+        s = "#<#{self.class} (#{status}) "
+        s << "runtime=#{stats[:runtime]} "
+        s << '>'
+    end
+
+    # @return    [String]
+    #   Returns the version of the framework.
+    def version
+        Cuboid::VERSION
+    end
+
+    def self._spec_instance_cleanup( i )
+        # i.clean_up
+        i.reset
+    end
+
+    def unsafe
+        self
+    end
+
+    def application
+        Cuboid::Application.application
+    end
+
+    def serializer
+        self.class.serializer
+    end
+
+    def safe( &block )
+        raise ArgumentError, 'Missing block.' if !block_given?
+
+        begin
+            block.call self
+        ensure
+            clean_up
+            reset
+        end
+
+        nil
+    end
+end
+
+end

data/lib/cuboid/application/parts/data.rb

@@ -0,0 +1,18 @@
+module Cuboid
+class Application
+module Parts
+# Provides access to {Cuboid::Data::Framework} and helpers.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+module Data
+
+    # @return   [Data::Application]
+    def data
+        Cuboid::Data.application
+    end
+
+end
+
+end
+end
+end

data/lib/cuboid/application/parts/report.rb

@@ -0,0 +1,29 @@
+module Cuboid
+class Application
+module Parts
+
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+module Report
+
+    def report( results )
+        data.report = results
+    end
+
+    # @return    [Cuboid::Report]
+    #   Scan results.
+    def generate_report
+        Cuboid::Report.new(
+            application:     self.class,
+            status:          state.status,
+            options:         Options.application,
+            data:            data.report,
+            start_datetime:  @start_datetime,
+            finish_datetime: @finish_datetime
+        )
+    end
+
+end
+
+end
+end
+end

data/lib/cuboid/application/parts/state.rb

@@ -0,0 +1,274 @@
+module Cuboid
+class Application
+module Parts
+
+# Provides access to {Cuboid::State::Application} and helpers.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+module State
+
+    def self.included( base )
+        base.extend ClassMethods
+    end
+
+    module ClassMethods
+
+        # @param   [String]    ses
+        #   Path to an `.ses.` (Cuboid Application Snapshot) file created by
+        #   {#suspend}.
+        #
+        # @return   [Application]
+        #   Restored instance.
+        def restore!( ses, &block )
+            f = self.instance.restore!( ses )
+            block_given? ? f.safe( &block ) : f
+        end
+
+        # @note You should first reset {Cuboid::Options}.
+        #
+        # Resets everything and allows the framework environment to be re-used.
+        def reset
+            Cuboid::State.clear
+            Cuboid::Data.clear
+            Cuboid::Snapshot.reset
+
+            Cuboid::Support::Database::Base.reset
+            Cuboid::System.reset
+        end
+    end
+
+    def initialize
+        super
+
+        state.status = :ready
+    end
+
+    # @return   [String]
+    #   Provisioned {#suspend} dump file for this instance.
+    def snapshot_path
+        return @state_archive if @state_archive
+
+        default_filename =
+            "Cuboid #{Time.now.to_s.gsub( ':', '_' )} " <<
+                "#{generate_token}.#{Snapshot::EXTENSION}"
+
+        location = Cuboid::Options.snapshot.path
+
+        if !location
+            location = default_filename
+        elsif File.directory? location
+            location += "/#{default_filename}"
+        end
+
+        @state_archive ||= File.expand_path( location )
+    end
+
+    # @note Prefer this from {.reset} if you already have an instance.
+    # @note You should first reset {Cuboid::Options}.
+    #
+    # Resets everything and allows the framework to be re-used.
+    def reset
+        @state_archive   = nil
+        @cleaned_up      = false
+        @start_datetime  = nil
+        @finish_datetime = nil
+
+        # This needs to happen before resetting the other components so they
+        # will be able to put in their hooks.
+        self.class.reset
+
+        clear_observers
+    end
+
+    # @return   [State::Application]
+    def state
+        Cuboid::State.application
+    end
+
+    # @param   [String]    ses
+    #   Path to an `.ses.` (Cuboid Application Snapshot) file created by {#suspend}.
+    #
+    # @return   [Application]
+    #   Restored instance.
+    def restore!( ses )
+        if handler = self.class.signal_handlers[:restore]
+            method( handler ).call
+        end
+
+        Snapshot.load ses
+
+        state.status = :restored
+
+        self
+    end
+
+    # @return   [Array<String>]
+    #   Messages providing more information about the current {#status} of
+    #   the framework.
+    def status_messages
+        state.status_messages
+    end
+
+    # @return   [Symbol]
+    #   Status of the instance, possible values are (in order):
+    #
+    #   * `:ready` -- {#initialize Initialised} and waiting for instructions.
+    #   * `:preparing` -- Getting ready to start.
+    #   * `:pausing` -- The instance is being {#pause paused} (if applicable).
+    #   * `:paused` -- The instance has been {#pause paused} (if applicable).
+    #   * `:suspending` -- The instance is being {#suspend suspended} (if applicable).
+    #   * `:suspended` -- The instance has being {#suspend suspended} (if applicable).
+    #   * `:cleanup` -- The instance is done and cleaning up.
+    #   * `:aborted` -- The scan has been {Application::Parts::State#abort}, you can grab the
+    #       report and shutdown.
+    #   * `:done` -- The scan has completed, you can grab the report and shutdown.
+    #   * `:timed_out` -- The scan was aborted due to a time-out..
+    def status
+        state.status
+    end
+
+    # @return   [Bool]
+    #   `true` if the framework is running, `false` otherwise. This is `true`
+    #   even if the scan is {#paused?}.
+    def running?
+        state.running?
+    end
+
+    # @return   [Bool]
+    #   `true` if the framework is paused, `false` otherwise.
+    def paused?
+        state.paused?
+    end
+
+    # @return   [Bool]
+    #   `true` if the framework has been instructed to pause (i.e. is in the
+    #   process of being paused or has been paused), `false` otherwise.
+    def pause?
+        state.pause?
+    end
+
+    # @return   [Bool]
+    #   `true` if the framework is in the process of pausing, `false` otherwise.
+    def pausing?
+        state.pausing?
+    end
+
+    # @return   (see Cuboid::State::Application#done?)
+    def done?
+        state.done?
+    end
+
+    # @note Each call from a unique caller is counted as a pause request
+    #   and in order for the system to resume **all** pause callers need to
+    #   {#resume} it.
+    #
+    # Pauses the framework on a best effort basis.
+    #
+    # @return   [Integer]
+    #   ID identifying this pause request.
+    def pause!
+        state.pause
+
+        if handler = self.class.signal_handlers[:pause]
+            method( handler ).call
+        end
+
+        state.paused
+
+        nil
+    end
+
+    # @return   [Bool]
+    #   `true` if the {Application#run} has been aborted, `false` otherwise.
+    def aborted?
+        state.aborted?
+    end
+
+    # @return   [Bool]
+    #   `true` if the framework has been instructed to abort (i.e. is in the
+    #   process of being aborted or has been aborted), `false` otherwise.
+    def abort?
+        state.abort?
+    end
+
+    # @return   [Bool]
+    #   `true` if the framework is in the process of aborting, `false` otherwise.
+    def aborting?
+        state.aborting?
+    end
+
+    # Aborts the {Application#run} on a best effort basis.
+    def abort!
+        state.abort
+
+        if handler = self.class.signal_handlers[:abort]
+            method( handler ).call
+        end
+
+        state.aborted
+    end
+
+    def resume!
+        state.resume
+
+        if handler = self.class.signal_handlers[:resume]
+            method( handler ).call
+        end
+
+        state.resumed
+    end
+
+    # Writes a {Snapshot.dump} to disk and aborts the scan.
+    #
+    # @return   [String,nil]
+    #   Path to the state file `wait` is `true`, `nil` otherwise.
+    def suspend!
+        state.suspend
+
+        if handler = self.class.signal_handlers[:suspend]
+            method( handler ).call
+        end
+
+        suspend_to_disk
+        state.suspended
+
+        snapshot_path
+    end
+
+    # @return   [Bool]
+    #   `true` if the system is in the process of being suspended, `false`
+    #   otherwise.
+    def suspend?
+        state.suspend?
+    end
+
+    # @return   [Bool]
+    #   `true` if the system has been suspended, `false` otherwise.
+    def suspended?
+        state.suspended?
+    end
+
+    private
+
+    def wait_if_paused
+        state.paused if pause?
+        sleep 0.2 while pause? && !abort?
+    end
+
+    def suspend_to_disk
+        state.set_status_message :saving_snapshot, snapshot_path
+        Snapshot.dump( snapshot_path )
+        state.clear_status_messages
+
+        clean_up
+
+        state.set_status_message :snapshot_location, snapshot_path
+        print_info status_messages.first
+        state.suspended
+    end
+
+end
+
+end
+end
+end