cuboid 0.0.0 → 0.0.3

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/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

data/lib/cuboid/state/options.rb

@@ -0,0 +1,27 @@
+module Cuboid
+class State
+
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class Options
+
+    def statistics
+        {}
+    end
+
+    def dump( directory )
+        FileUtils.mkdir_p( directory )
+        Cuboid::Options.save( "#{directory}/options" )
+    end
+
+    def self.load( directory )
+        Cuboid::Options.load( "#{directory}/options" )
+        new
+    end
+
+    def clear
+    end
+
+end
+
+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/support/buffer/autoflush.rb

@@ -0,0 +1,61 @@
+module Cuboid
+module Support::Buffer
+
+# A buffer implementation which flushes itself when it gets full or a number
+# of push attempts is reached between flushes.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class AutoFlush < Base
+
+    attr_reader :max_pushes
+
+    # @param    [Integer]  max_size
+    #   Maximum buffer size -- a flush will be triggered when that limit is
+    #   reached.
+    # @param    [Integer]  max_pushes
+    #   Maximum number of pushes between flushes.
+    # @param    [#<<, #|, #clear, #size, #empty?]   type
+    #   Internal storage class to use.
+    def initialize( max_size = nil, max_pushes = nil, type = Array )
+        super( max_size, type )
+
+        @max_pushes = max_pushes
+        @pushes     = 0
+    end
+
+    def <<( *args )
+        super( *args )
+    ensure
+        handle_push
+    end
+
+    def batch_push( *args )
+        super( *args )
+    ensure
+        handle_push
+    end
+
+    def flush
+        super
+    ensure
+        @pushes = 0
+    end
+
+    private
+
+    def handle_push
+        @pushes += 1
+        flush if flush?
+    end
+
+    def flush?
+        !!(full? || push_limit_reached?)
+    end
+
+    def push_limit_reached?
+        max_pushes && @pushes >= max_pushes
+    end
+
+end
+end
+end