binding_dumper 0.1.0

data/lib/binding_dumper/dumpers/magic_dumper.rb

@@ -0,0 +1,75 @@
+module BindingDumper
+  # Class responsible for converting 'magical' objects to marshalable hash
+  #
+  # You should define which objects are 'magical'.
+  #  The difference between 'magical' and 'regular' objects is that
+  #  'magical' objects are the same for every sessions
+  #  like Rails.application.config or Rails.env
+  #
+  # To make object 'magical', use BindingDumper::MagicObjects.register(object)
+  #
+  # When you convert a 'magical' object to marshalable hash it returns 'the way how to get it',
+  #   not the object itself
+  #
+  # @example
+  #   class A
+  #     class << self
+  #       @config = :config
+  #       attr_reader :config
+  #     end
+  #   end
+  #   BindingDumper::MagicObjects.register(A)
+  #   BindingDumper::MagicObjects.pool
+  #   {
+  #     47472500 => "A",
+  #     600668 => "A.instance_variable_get(:@config)"
+  #   }
+  #   # (the mapping 'object id' => 'the way to get an object')
+  #
+  #   dump = BindingDumper::Dumpers::MagicDumper.new(A.config).convert
+  #   # => { :_magic => "A.instance_variable_get(:@config)" }
+  #   restored = BindingDumper::Dumpers::MagicDumper.new(dump).deconvert
+  #   # => :config
+  #
+  class Dumpers::MagicDumper < Dumpers::Abstract
+    alias_method :object, :abstract_object
+
+    # Returns true if MagicDumper can convert passed +abstract_object+
+    #
+    # @return [true, false]
+    #
+    def can_convert?
+      MagicObjects.magic?(object)
+    end
+
+    # Returns true if MagicDumper can deconvert passed +abstract_object+
+    #
+    # @return [true, false]
+    #
+    def can_deconvert?
+      abstract_object.is_a?(Hash) && abstract_object.has_key?(:_magic)
+    end
+
+    # Converts passed +abstract_object+ to marshalable Hash
+    #
+    # @return [Hash]
+    #
+    def convert
+      return unless should_convert?
+
+      object_magic = MagicObjects.get_magic(object)
+      {
+        _magic: object_magic
+      }
+    end
+
+    # Deconverts passed +abstract_object+ back to the original state
+    #
+    # @return [Object]
+    #
+    def deconvert
+      # release magic!
+      eval(abstract_object[:_magic])
+    end
+  end
+end

data/lib/binding_dumper/dumpers/object_dumper.rb

@@ -0,0 +1,106 @@
+module BindingDumper
+  # Class responsible for converting objects to marshalable Hash
+  #
+  # @example
+  #   o = Object.new
+  #   dump = BindingDumper::Dumpers::Array.new(o).convert
+  #   # => { marshalable: :hash }
+  #   BindingDumper::Dumpers::Array.new(dump).deconvert
+  #   # => o
+  #
+  class Dumpers::ObjectDumper < Dumpers::Abstract
+    alias_method :object, :abstract_object
+
+    # Returns true if ObjectDumper can convert passed +abstract_object+
+    #
+    # @return [true, false]
+    #
+    def can_convert?
+      true
+    end
+
+    # Returns true if ObjectDumper can deconvert passed +abstract_object+
+    #
+    # @return [true, false]
+    #
+    def can_deconvert?
+      abstract_object.is_a?(Hash) &&
+        (
+          abstract_object.has_key?(:_klass) ||
+          abstract_object.has_key?(:_object) ||
+          abstract_object.has_key?(:_old_object_id)
+        )
+    end
+
+    # Converts passed +abstract_object+ to marshalable Hash
+    #
+    # @return [Hash]
+    #
+    def convert
+      unless should_convert?
+        return { _existing_object_id: object.object_id }
+      end
+
+      if can_be_fully_dumped?(object)
+        {
+          _object: object
+        }
+      elsif undumpable?(object)
+        {
+          _klass: object.class,
+          _undumpable: true
+        }
+      else
+        dumped_ids << object.object_id
+        {
+          _klass: object.class,
+          _ivars: converted_ivars(dumped_ids),
+          _old_object_id: object.object_id
+        }
+      end
+    end
+
+    # Deconverts passed +abstract_object+ back to the original state
+    #
+    # @return [Object]
+    #
+    def deconvert
+      if object.has_key?(:_object)
+        object[:_object]
+      else
+        klass = object[:_klass]
+        result = klass.allocate
+        return result if object[:_undumpable]
+
+        yield result
+
+        object[:_ivars].each do |ivar_name, converted_ivar|
+          ivar = UniversalDumper.deconvert(converted_ivar)
+          result.instance_variable_set(ivar_name, ivar)
+        end
+
+        if result.respond_to?(:restored_from_binding)
+          result.restored_from_binding
+        end
+
+        result
+      end
+    end
+
+    private
+
+    # Returns converted mapping of instance variables like
+    #  { instance variable name => instance variable value }
+    #
+    # @return [Hash]
+    #
+    def converted_ivars(dumped_ids = [])
+      converted = object.instance_variables.map do |ivar_name|
+        ivar = object.instance_variable_get(ivar_name)
+        conveted_ivar = UniversalDumper.convert(ivar, dumped_ids)
+        [ivar_name, conveted_ivar]
+      end.reject(&:empty?)
+      Hash[converted]
+    end
+  end
+end

data/lib/binding_dumper/dumpers/primitive_dumper.rb

@@ -0,0 +1,48 @@
+module BindingDumper
+  # Class responsible for converting primitive objects to marshalable hash
+  #
+  # @see SUPPORTED_CLASSES
+  #
+  class Dumpers::PrimitiveDumper < Dumpers::Abstract
+    alias_method :primitive, :abstract_object
+
+    SUPPORTED_CLASSES = [
+      Numeric,
+      String,
+      NilClass,
+      FalseClass,
+      TrueClass,
+      Symbol
+    ]
+
+    # Returns true if PrimitiveDumper can convert passed +abstract_object+
+    #
+    # @return [true, false]
+    #
+    def can_convert?
+      SUPPORTED_CLASSES.any? do |klass|
+        abstract_object.is_a?(klass)
+      end
+    end
+
+    def can_deconvert?
+      true
+    end
+
+    # Returns +abstract_object+
+    #
+    # @return [Object]
+    #
+    def convert
+      primitive
+    end
+
+    # Returns +abstract_object+
+    #
+    # @return [Object]
+    #
+    def deconvert
+      primitive
+    end
+  end
+end

data/lib/binding_dumper/dumpers/proc_dumper.rb

@@ -0,0 +1,44 @@
+module BindingDumper
+  # Class responsible for converting procs and methods to marshalable hash
+  #
+  # It uses a gem called 'method_source' which may inspect the source of proc/method
+  #
+  class Dumpers::ProcDumper < Dumpers::Abstract
+    alias_method :_proc, :abstract_object
+
+    # Returns true if ProcDumper can convert passed +abstract_object+
+    #
+    # @return [true, false]
+    #
+    def can_convert?
+      _proc.is_a?(Proc) || _proc.is_a?(Method)
+    end
+
+    # Returns true if ProcDumper can deconvert pased +abstract_object+
+    #
+    # @return [true, false]
+    #
+    def can_deconvert?
+      abstract_object.is_a?(Hash) && abstract_object.has_key?(:_source)
+    end
+
+    # Converts passed +abstract_object+ to marshalable hash
+    #
+    # @return [Hash]
+    #
+    def convert
+      return unless should_convert?
+
+      source = (_proc.to_proc.source rescue 'proc {}').strip
+      { _source: source }
+    end
+
+    # Deconverts passed +abstract_object+ back to the original state
+    #
+    # @return [Object]
+    #
+    def deconvert
+      eval(_proc[:_source]) rescue proc {}
+    end
+  end
+end

data/lib/binding_dumper/magic_objects.rb

@@ -0,0 +1,98 @@
+# Module responsible for storing and retrieving 'magical' objects
+#  Object is 'magical' if it's the same for every Ruby process
+#
+# Examples of 'magical' objects:
+#  Rails.application
+#  Rails.env
+#  Rails.application.config
+#
+# To register an object, run:
+# @example
+#   BindingDumper::MagicObjects.register(MyClass)
+#   # or if it's method that returns always the same data
+#   BindingDumper::MagicObjects.register(:some_method, 'send(:some_method)')
+#
+# After marking an object as 'magical' it (and all embedded objects)
+#  will be added to the object pool of 'magical' objects
+#
+# @example
+#   class A
+#     class << self
+#       attr_reader :config
+#       @config = { config: :data }
+#     end
+#   end
+#
+#   BindingDumper::MagicObjects.register(A)
+#   BindingDumper::MagicObjects.pool
+#   {
+#     47472500 => "A",
+#     600668   => "A.instance_variable_get(:@config)"
+#   }
+#   BindingDumper::MagicObjects.magic?(A.config)
+#   # => true
+#   BindingDumper::MagicObjects.get_magic(A.config)
+#   # => "A.instance_variable_get(:@config)"
+#
+module BindingDumper::MagicObjects
+  # Builds a tree of objects inside of passed +object+
+  #
+  # @return [Hash]
+  #
+  def self.magic_tree_from(object, object_path, result = {})
+    return if result[object.object_id]
+
+    result[object.object_id] = object_path
+
+    object.instance_variables.each do |ivar_name|
+      path = "#{object_path}.instance_variable_get(:#{ivar_name})"
+      ivar = object.instance_variable_get(ivar_name)
+      magic_tree_from(ivar, path, result)
+    end
+
+    result
+  end
+
+  # Registers passed object as 'magical'
+  #
+  # @param object [Object]
+  # @param object_path [String]  the way how to get an object
+  #
+  def self.register(object, object_path = object.name)
+    tree = magic_tree_from(object, object_path)
+    pool.merge!(tree)
+    true
+  end
+
+  # Returns Hash containing all magical objects
+  #
+  # @return [Hash] in format { object_id => way to get an object }
+  #
+  def self.pool
+    @pool ||= {}
+  end
+
+  # Returns true if passed +object+ is 'magical'
+  #
+  # @return [true, false]
+  #
+  def self.magic?(object)
+    pool.has_key?(object.object_id)
+  end
+
+  # Returns the way to get a 'magical' object
+  #
+  # @param object [Object]
+  #
+  # @return [String]
+  #
+  def self.get_magic(object)
+    pool[object.object_id]
+  end
+
+  # Flushes existing information about 'magical' objects
+  #
+  def self.flush!
+    @pool = {}
+  end
+end

data/lib/binding_dumper/memories.rb

@@ -0,0 +1,51 @@
+# Module for storing mapping { dumped object_id => restored object }
+#  used for BindingDumper::Dumpers::ExistingObjectDumper strategy
+#
+# @see BindingDumper::UniversalDumper
+# @example
+#   BindingDumper::UniversalDumper.memories
+#   # => {}
+#   o = Object.new
+#   BindingDumper::UniversalDumper.remember!(123, o)
+#   BindingDumper::UniversalDumper.with_memories(123) == o
+#   # => true
+#
+module BindingDumper::Memories
+  # Returns hash containing all restored objects
+  #
+  # @return [Hash]
+  #
+  def memories
+    @memories ||= {}
+  end
+
+  # Flushes existing memories about restored objects
+  #
+  def flush_memories!
+    @memories = {}
+  end
+
+  # Saves passed +object+ and marks it with +object_id+
+  #
+  # @param object [Object]
+  # @param object_id [Fixnum]
+  #
+  def remember!(object, object_id)
+    memories[object_id] = object
+  end
+
+  # Returns an object from memories with +old_object_id+
+  #  or yields
+  #
+  # @param old_object_id [Fixnum]
+  #
+  # @yield
+  #
+  def with_memories(old_object_id, &block)
+    if memories.has_key?(old_object_id)
+      memories[old_object_id]
+    else
+      yield
+    end
+  end
+end

data/lib/binding_dumper/universal_dumper.rb

@@ -0,0 +1,118 @@
+module BindingDumper
+  # Module that puts together all existing dumpers and wraps their functionality
+  #
+  # This dumper can dump and load back _any_ object using system of existing dumpers.
+  #
+  # @example
+  #  dump = BindingDumper::UniversalDumper.dump(Object.new)
+  #  restored = BindingDumper::UniversalDumper.load(dump)
+  #  # => #<Object>
+  #
+  module UniversalDumper
+    DUMPERS_ON_CONVERTING = [
+      Dumpers::MagicDumper,
+      Dumpers::ProcDumper,
+      Dumpers::ClassDumper,
+      Dumpers::ArrayDumper,
+      Dumpers::HashDumper,
+      Dumpers::PrimitiveDumper,
+      Dumpers::ObjectDumper
+    ]
+
+    DUMPERS_ON_DECONVERTING = [
+      Dumpers::MagicDumper,
+      Dumpers::ExistingObjectDumper,
+      Dumpers::ProcDumper,
+      Dumpers::ArrayDumper,
+      Dumpers::ClassDumper,
+      Dumpers::ObjectDumper,
+      Dumpers::HashDumper,
+      Dumpers::PrimitiveDumper
+    ]
+
+    extend self
+    extend BindingDumper::Memories
+
+    # Returns converter that should be applied to provided +object+
+    #
+    # @param object [Object]
+    # @param dumped_ids [Array<Fixum>] list of object_ids that are already dumped
+    #
+    # @return [BindingDumper::Dumpers::Abstract]
+    #
+    def converter_for(object, dumped_ids)
+      DUMPERS_ON_CONVERTING.map { |dumper_klass|
+        dumper_klass.new(object, dumped_ids)
+      }.detect(&:can_convert?)
+    end
+
+    # Converts passed +object+ to marshalable string
+    #
+    # @param object [Object]
+    # @param dumped_ids [Array<Fixnum>] list of object_ids that are already dumped
+    #
+    # @return [Hash]
+    #
+    def convert(object, dumped_ids = [])
+      converter_for(object, dumped_ids).convert
+    end
+
+    # Dump passed +object+ to string
+    #
+    # @param object [Object]
+    #
+    # @return [String]
+    #
+    def dump(object)
+      converted = convert(object)
+      Marshal.dump(converted)
+    end
+
+    # Returns deconverter that should be applied to provided +object+
+    #
+    # @param object [Object]
+    #
+    # @return [BindingDumper::Dumpers::Abstract]
+    #
+    def deconverter_for(object)
+      DUMPERS_ON_DECONVERTING.map do |dumper_klass|
+        dumper_klass.new(object)
+      end.detect do |dumper|
+        dumper.can_deconvert?
+      end
+    end
+
+    # Deconverts passed +object+ to marshalable string
+    #
+    # @param object [Object]
+    #
+    # @return [Object]
+    #
+    def deconvert(converted_data)
+      deconverter = deconverter_for(converted_data)
+
+      if deconverter.is_a?(Dumpers::PrimitiveDumper)
+        return deconverter.deconvert
+      end
+
+      old_object_id = converted_data[:_old_object_id]
+
+      with_memories(old_object_id) do
+        deconverter.deconvert do |object|
+          remember!(object, old_object_id)
+        end
+      end
+    end
+
+    # Loads dumped object back to its original state
+    #
+    # @param object [String]
+    #
+    # @return [Object]
+    #
+    def load(object)
+      converted = Marshal.load(object)
+      deconvert(converted)
+    end
+  end
+end