cuboid 0.0.0 → 0.0.1alpha

data/lib/cuboid/ruby.rb

@@ -0,0 +1,4 @@
+lib = Cuboid::Options.paths.lib
+require lib + 'ruby/object'
+require lib + 'ruby/hash'
+require lib + 'ruby/array'

data/lib/cuboid/ruby/array.rb

@@ -0,0 +1,17 @@
+class Array
+
+    # @param    [#to_s, Array<#to_s>]  tags
+    #
+    # @return [Bool]
+    #   `true` if `self` contains any of the `tags` when objects of both `self`
+    #   and `tags` are converted to `String`.
+    def includes_tags?( tags )
+        return false if !tags
+
+        tags = [tags].flatten.compact.map( &:to_s )
+        return false if tags.empty?
+
+        (self.flatten.compact.map( &:to_s ) & tags).any?
+    end
+
+end

data/lib/cuboid/ruby/hash.rb

@@ -0,0 +1,41 @@
+class Hash
+
+    if !method_defined?( :to_h )
+        alias :to_h :to_hash
+    end
+
+    # Converts the hash keys to strings.
+    #
+    # @param    [Boolean]    recursively
+    #   Go through the Hash recursively?
+    #
+    # @return [Hash]
+    #   Hash with +self+'s keys recursively converted to strings.
+    def my_stringify_keys( recursively = true )
+        stringified = {}
+        each do |k, v|
+            stringified[k.to_s] = (recursively && v.is_a?( Hash ) ?
+                v.my_stringify_keys : v)
+        end
+        stringified
+    end
+
+    # Converts the hash keys to symbols.
+    #
+    # @param    [Boolean]    recursively
+    #   Go through the Hash recursively?
+    #
+    # @return [Hash]
+    #   Hash with +self+'s keys recursively converted to symbols.
+    def my_symbolize_keys( recursively = true )
+        symbolize = {}
+        each do |k, v|
+            k = k.respond_to?(:to_sym) ? k.to_sym : k
+
+            symbolize[k] = (recursively && v.is_a?( Hash ) ?
+                v.my_symbolize_keys : v)
+        end
+        symbolize
+    end
+
+end

data/lib/cuboid/ruby/object.rb

@@ -0,0 +1,32 @@
+# Overloads the {Object} class providing a {#deep_clone} method.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class Object
+
+    # Deep-clones self using a Marshal dump-load.
+    #
+    # @return   [Object]
+    #   Duplicate of self.
+    def deep_clone
+        Marshal.load( Marshal.dump( self ) )
+    end
+
+    def rpc_clone
+        if self.class.respond_to?( :from_rpc_data )
+            self.class.from_rpc_data(
+                Cuboid::RPC::Serializer.serializer.load(
+                    Cuboid::RPC::Serializer.serializer.dump( to_rpc_data )
+                )
+            )
+        else
+            Cuboid::RPC::Serializer.serializer.load(
+                Cuboid::RPC::Serializer.serializer.dump( self )
+            )
+        end
+    end
+
+    def to_rpc_data_or_self
+        respond_to?( :to_rpc_data ) ? to_rpc_data : self
+    end
+
+end

data/lib/cuboid/snapshot.rb

@@ -0,0 +1,186 @@
+require 'zip'
+require 'fileutils'
+
+require_relative 'data'
+require_relative 'state'
+
+module Cuboid
+
+# Stores and provides access to the state of the system.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class Snapshot
+
+    # {Snapshot} error namespace.
+    #
+    # All {Snapshot} errors inherit from and live under it.
+    #
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class Error < Cuboid::Error
+
+        # Raised when trying to read an invalid snapshot file.
+        #
+        # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+        class InvalidFile < Error
+        end
+    end
+
+    EXTENSION = 'csf'
+
+class <<self
+
+    # @return   [Hash]
+    #   Metadata associated with the {.load loaded} snapshot.
+    attr_accessor :metadata
+
+    # @return   [String]
+    #   Location of the {.load loaded} snapshot.
+    attr_accessor :location
+
+    def reset
+        @metadata = nil
+        @location = nil
+    end
+
+    # @return   [Bool]
+    #   `true` if this is a restored snapshot, `false` otherwise.
+    def restored?
+        !!location
+    end
+
+    # @return   [Hash]
+    #   Snapshot summary information.
+    def summary
+        {
+            data:  Data.statistics,
+            state: State.statistics
+        }
+    end
+
+    # @param    [String]    location
+    #   Location of the snapshot.
+    #
+    # @return   [String]
+    #   Location of the snapshot.
+    def dump( location )
+        FileUtils.rm_rf( location )
+
+        directory = get_temporary_directory
+
+        FileUtils.rm_rf( directory )
+        FileUtils.mkdir_p( directory )
+
+        begin
+            Data.dump( "#{directory}/data/" )
+            State.dump( "#{directory}/state/" )
+
+            compress directory, location
+
+            # Append metadata to the end of the file.
+            metadata = Marshal.dump( prepare_metadata )
+            File.open( location, 'ab' ) do |f|
+                f.write [metadata, metadata.size].pack( 'a*N' )
+            end
+
+            location
+        ensure
+            FileUtils.rm_rf( directory )
+        end
+    end
+
+    # @param    [String]    snapshot
+    #   Location of the snapshot to load.
+    #
+    # @return   [Snapshot]
+    #   `self`
+    #
+    # @raise    [Error::InvalidFile]
+    #   When trying to read an invalid file.
+    def load( snapshot )
+        directory = get_temporary_directory
+
+        @location = snapshot
+        @metadata = read_metadata( snapshot )
+
+        extract( snapshot, directory )
+
+        Data.load( "#{directory}/data/" )
+        State.load( "#{directory}/state/" )
+
+        self
+    ensure
+
+        # Don't delete the directory immediately because there are disk DBs that
+        # use those files.
+        Kernel.at_exit do
+            FileUtils.rm_rf( directory )
+        end
+    end
+
+    # @param    [String]    snapshot
+    #   Location of the snapshot.
+    #
+    # @return   [Hash]
+    #   Metadata associated with the given snapshot.
+    #
+    # @raise    [Error::InvalidFile]
+    #   When trying to read an invalid file.
+    def read_metadata( snapshot )
+        File.open( snapshot, 'rb' ) do |f|
+            f.seek -4, IO::SEEK_END
+            metadata_size = f.read( 4 ).unpack( 'N' ).first
+
+            f.seek -metadata_size-4, IO::SEEK_END
+            Marshal.load( f.read( metadata_size ) )
+        end
+    rescue => e
+        ne = Error::InvalidFile.new( "Invalid snapshot: #{snapshot} (#{e})" )
+        ne.set_backtrace e.backtrace
+        raise ne
+    end
+
+    private
+
+    def prepare_metadata
+        {
+            timestamp: Time.now,
+            version:   Cuboid::VERSION,
+            summary:   summary
+        }
+    end
+
+    def get_temporary_directory
+        "#{Options.paths.tmpdir}/Cuboid_Snapshot_#{Utilities.generate_token}/"
+    end
+
+    def extract( archive, directory )
+        Zip::File.open( archive ) do |zip_file|
+            zip_file.each do |f|
+                f_path = File.join( directory, f.name )
+                FileUtils.mkdir_p( File.dirname( f_path ) )
+                zip_file.extract( f, f_path ) unless File.exist?( f_path )
+            end
+        end
+
+        directory
+    end
+
+    def compress( directory, archive )
+        # Globs on Windows don't accept \ as a separator since it's an escape character.
+        directory = directory.gsub( '\\', '/' ) + '/'
+        directory.gsub!( /\/+/, '/' )
+
+        Zip::File.open( archive, Zip::File::CREATE ) do |zipfile|
+            Dir[directory + '**/**'].each do |file|
+                zipfile.add( file.sub( directory, '' ), file )
+            end
+        end
+
+        archive
+    end
+
+end
+
+reset
+end
+end

data/lib/cuboid/state.rb

@@ -0,0 +1,94 @@
+module Cuboid
+
+# Stores and provides access to the state of the system.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class State
+
+    # {State} error namespace.
+    #
+    # All {State} errors inherit from and live under it.
+    #
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class Error < Cuboid::Error
+    end
+
+    require_relative 'state/options'
+    require_relative 'state/application'
+
+class <<self
+
+    # @return     [Options]
+    attr_accessor :options
+
+    # @return     [Framework]
+    attr_accessor :application
+
+    def reset
+        @options        = Options.new
+        @application    = Application.new
+    end
+
+    def statistics
+        stats = {}
+        each do |attribute|
+            stats[attribute] = send(attribute).statistics
+        end
+        stats
+    end
+
+    # @param    [String]    directory
+    #   Location of the dump directory.
+    #
+    # @return   [String]
+    #   Location of the directory.
+    def dump( directory )
+        FileUtils.mkdir_p( directory )
+
+        each do |name, state|
+            state.dump( "#{directory}/#{name}/" )
+        end
+
+        directory
+    end
+
+    # @param    [String]    directory
+    #   Location of the dump directory.
+    #
+    # @return   [State]
+    #   `self`
+    def load( directory )
+        each do |name, state|
+            send( "#{name}=", state.class.load( "#{directory}/#{name}/" ) )
+        end
+
+        self
+    end
+
+    # Clears all states.
+    def clear
+        each { |_, state| state.clear }
+        self
+    end
+
+    private
+
+    def each( &block )
+        accessors.each do |attr|
+            block.call attr, send( attr )
+        end
+    end
+
+    def accessors
+        instance_variables.map do |ivar|
+            attribute = "#{ivar.to_s.gsub('@','')}"
+            next if !methods.include?( :"#{attribute}=" )
+            attribute
+        end.compact.map(&:to_sym)
+    end
+
+end
+
+reset
+end
+end

data/lib/cuboid/state/application.rb

@@ -0,0 +1,309 @@
+module Cuboid
+class State
+
+# State information for {Cuboid::Framework}.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class Application
+
+    # {Framework} error namespace.
+    #
+    # All {Framework} errors inherit from and live under it.
+    #
+    # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+    class Error < State::Error
+        # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+        class StateNotSuspendable < Error
+        end
+
+        # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+        class StateNotAbortable < Error
+        end
+
+        # @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+        class InvalidStatusMessage < Error
+        end
+    end
+
+    # @return     [Symbol]
+    attr_accessor :status
+
+    # @return     [Bool]
+    attr_accessor :running
+
+    # @return     [Array<String>]
+    attr_reader    :status_messages
+
+    attr_accessor  :runtime
+
+    def initialize
+        @running = false
+        @pre_pause_status = nil
+
+        @pause_signals = Set.new
+
+        @status_messages = []
+    end
+
+    def statistics
+        {
+          runtime: !!@runtime
+        }
+    end
+
+    # @return   [Hash{Symbol=>String}]
+    #   All possible {#status_messages} by type.
+    def available_status_messages
+        {
+            suspending:        'Will suspend as soon as the current page is audited.',
+            saving_snapshot:   'Saving snapshot at: %s',
+            snapshot_location: 'Snapshot location: %s',
+            aborting:          'Aborting the scan.',
+            timed_out:         'Scan timed out.'
+        }
+    end
+
+    # Sets a message as {#status_messages}.
+    #
+    # @param    (see #add_status_message)
+    # @return   (see #add_status_message)
+    def set_status_message( *args )
+        clear_status_messages
+        add_status_message( *args )
+    end
+
+    # Pushes a message to {#status_messages}.
+    #
+    # @param    [String, Symbol]    message
+    #   Status message. If `Symbol`, it will be grabbed from
+    #   {#available_status_messages}.
+    # @param    [String, Numeric]    sprintf
+    #   `sprintf` arguments.
+    def add_status_message( message, *sprintf )
+        if message.is_a? Symbol
+            if !available_status_messages.include?( message )
+                fail Error::InvalidStatusMessage,
+                     "Could not find status message for: '#{message}'"
+            end
+
+            message = available_status_messages[message] % sprintf
+        end
+
+        @status_messages << message.to_s
+    end
+
+    # Clears {#status_messages}.
+    def clear_status_messages
+        @status_messages.clear
+    end
+
+    def running?
+        !!@running
+    end
+
+    def timed_out
+        @status = :timed_out
+        nil
+    end
+
+    def timed_out?
+        @status == :timed_out
+    end
+
+    # @param    [Bool]  block
+    #   `true` if the method should block until an abortion has completed,
+    #   `false` otherwise.
+    #
+    # @return   [Bool]
+    #   `true` if the abort request was successful, `false` if the system is
+    #   already {#suspended?} or is {#suspending?}.
+    #
+    # @raise    [StateNotAbortable]
+    #   When not {#running?}.
+    def abort
+        return false if aborting? || aborted?
+
+        if !running?
+            fail Error::StateNotAbortable, "Cannot abort idle state: #{status}"
+        end
+
+        set_status_message :aborting
+        @status = :aborting
+        @abort = true
+
+        true
+    end
+
+    # @return   [Bool]
+    #   `true` if a {#abort} signal is in place , `false` otherwise.
+    def abort?
+        !!@abort
+    end
+
+    # Signals a completed abort operation.
+    def aborted
+        @abort = false
+        @status = :aborted
+        nil
+    end
+
+    # @return   [Bool]
+    #   `true` if the system has been aborted, `false` otherwise.
+    def aborted?
+        @status == :aborted
+    end
+
+    # @return   [Bool]
+    #   `true` if the system is being aborted, `false` otherwise.
+    def aborting?
+        @status == :aborting
+    end
+
+    # @return   [Bool]
+    #   `true` if the system has completed successfully, `false` otherwise.
+    def done?
+        @status == :done
+    end
+
+    # @param    [Bool]  block
+    #   `true` if the method should block until a suspend has completed,
+    #   `false` otherwise.
+    #
+    # @return   [Bool]
+    #   `true` if the suspend request was successful, `false` if the system is
+    #   already {#suspended?} or is {#suspending?}.
+    #
+    # @raise    [StateNotSuspendable]
+    #   When {#paused?} or {#pausing?}.
+    def suspend
+        return false if suspending? || suspended?
+
+        if paused? || pausing?
+            fail Error::StateNotSuspendable, 'Cannot suspend a paused state.'
+        end
+
+        if !running?
+            fail Error::StateNotSuspendable, "Cannot suspend idle state: #{status}"
+        end
+
+        set_status_message :suspending
+        @status = :suspending
+        @suspend = true
+
+        true
+    end
+
+    # @return   [Bool]
+    #   `true` if an {#abort} signal is in place , `false` otherwise.
+    def suspend?
+        !!@suspend
+    end
+
+    # Signals a completed suspension.
+    def suspended
+        @suspend = false
+        @status = :suspended
+        nil
+    end
+
+    # @return   [Bool]
+    #   `true` if the system has been suspended, `false` otherwise.
+    def suspended?
+        @status == :suspended
+    end
+
+    # @return   [Bool]
+    #   `true` if the system is being suspended, `false` otherwise.
+    def suspending?
+        @status == :suspending
+    end
+
+    # @param    [Bool]  block
+    #   `true` if the method should block until the pause has completed,
+    #   `false` otherwise.
+    #
+    # @return   [TrueClass]
+    #   Pauses the framework on a best effort basis, might take a while to take
+    #   effect.
+    def pause
+        @pre_pause_status ||= @status if !paused? && !pausing?
+
+        if !paused?
+            @status = :pausing
+        end
+
+        @pause_signals << :nil
+
+        paused if !running?
+        true
+    end
+
+    # Signals that the system has been paused..
+    def paused
+        clear_status_messages
+        @status = :paused
+    end
+
+    # @return   [Bool]
+    #   `true` if the framework is paused.
+    def paused?
+        @status == :paused
+    end
+
+    # @return   [Bool]
+    #   `true` if the system is being paused, `false` otherwise.
+    def pausing?
+        @status == :pausing
+    end
+
+    # @return   [Bool]
+    #   `true` if the framework should pause, `false` otherwise.
+    def pause?
+        @pause_signals.any?
+    end
+
+    # Resumes a paused system
+    #
+    # @return   [Bool]
+    #   `true` if the system is resumed, `false` if there are more {#pause}
+    #   signals pending.
+    def resume
+        @status = :resuming
+        @pause_signals.clear
+
+        true
+    end
+
+    def resumed
+        @status = @pre_pause_status
+        @pre_pause_status = nil
+
+        true
+    end
+
+    def dump( directory )
+        FileUtils.mkdir_p( directory )
+
+        d = Cuboid::Application.serializer.dump( @runtime )
+        IO.binwrite( "#{directory}/runtime", d )
+    end
+
+    def self.load( directory )
+        application = new
+        application.runtime = Cuboid::Application.serializer.load( IO.binread( "#{directory}/runtime" ) )
+        application
+    end
+
+    def clear
+        @pause_signals.clear
+
+        @running = false
+        @pre_pause_status = nil
+
+        @runtime = nil
+    end
+
+end
+
+end
+end