rlp 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 32e4d13b19619a0c3f381595d5942f9e915ee837
-  data.tar.gz: 3968b3f4dd481c15a878465214e1db635d42b616
+  metadata.gz: 3195187f64cf0bc3c2d9499028b45d66a19591f2
+  data.tar.gz: 1d20e7ef25821a865001a5e59237418749e87aa1
 SHA512:
-  metadata.gz: e0c09429505321937097e3dc71bbb1c4d3029ddffd9b9dfdbfaf1bdbdf9133b929b44141558ba435d720ae4f318e15615b5f41de41ebbea9963370fe2a9f9111
-  data.tar.gz: 9be9e4d4bb3d9f246f32440e1eb97f4a5d12c0de700007f21c6f0e41ab9546f54237e7aa756ee96e435de54f8892f10599a34d3059c4c74b0e9e21c762292781
+  metadata.gz: 1c1a5fcb71deda8629cdc4806499cdc050b4900af1ae65e67179e8245ce263db67f89bbf8e3fcc29bdb39c8168b688490a77591a7429d7851ae921e6f3398ce3
+  data.tar.gz: 7bf8bc70835a72adbc41f012c21bed66fee6afdaae78a81fd95a65591b6f6615ba720612fec287e6980b053aa793f33c8c2d6a564b2c23e506aa84230210487e

data/lib/rlp/data.rb

@@ -1,6 +1,6 @@
 ##
 # A wrapper to represent already RLP encoded data
-
+#
 module RLP
   class Data < String
   end

data/lib/rlp/encode.rb

@@ -4,6 +4,40 @@ module RLP
     include Error
     include Utils
 
+    ##
+    # Encode a Ruby object in RLP format.
+    #
+    # By default, the object is serialized in a suitable way first (using
+    # {RLP::Sedes.infer}) and then encoded. Serialization can be explicitly
+    # suppressed by setting {RLP::Sedes.infer} to `false` and not passing an
+    # alternative as `sedes`.
+    #
+    # If `obj` has an attribute `_cached_rlp` (as, notably,
+    # {RLP::Serializable}) and its value is not `nil`, this value is returned
+    # bypassing serialization and encoding, unless `sedes` is given (as the
+    # cache is assumed to refer to the standard serialization which can be
+    # replaced by specifying `sedes`).
+    #
+    # If `obj` is a {RLP::Serializable} and `cache` is true, the result of the
+    # encoding will be stored in `_cached_rlp` if it is empty and
+    # {RLP::Serializable.make_immutable} will be invoked on `obj`.
+    #
+    # @param obj [Object] object to encode
+    # @param sedes [#serialize(obj)] an object implementing a function
+    #   `serialize(obj)` which will be used to serialize `obj` before
+    #   encoding, or `nil` to use the infered one (if any)
+    # @param infer_serializer [Boolean] if `true` an appropriate serializer
+    #   will be selected using {RLP::Sedes.infer} to serialize `obj` before
+    #   encoding
+    # @param cache [Boolean] cache the return value in `obj._cached_rlp` if
+    #   possible and make `obj` immutable (default `false`)
+    #
+    # @return [String] the RLP encoded item
+    #
+    # @raise [RLP::EncodingError] in the rather unlikely case that the item
+    #   is too big to encode (will not happen)
+    # @raise [RLP::SerializationError] if the serialization fails
+    #
     def encode(obj, sedes: nil, infer_serializer: true, cache: false)
       # TODO: cache flow
 

data/lib/rlp/error.rb

@@ -4,6 +4,8 @@ module RLP
     class RLPException < Exception; end
 
     class EncodingError < RLPException
+      attr :obj
+
       def initialize(message, obj)
         super(message)
 
@@ -12,6 +14,8 @@ module RLP
     end
 
     class DecodingError < RLPException
+      attr :rlp
+
       def initialize(message, rlp)
         super(message)
 
@@ -20,6 +24,8 @@ module RLP
     end
 
     class SerializationError < RLPException
+      attr :obj
+
       def initialize(message, obj)
         super(message)
 
@@ -28,6 +34,8 @@ module RLP
     end
 
     class DeserializationError < RLPException
+      attr :serial
+
       def initialize(message, serial)
         super(message)
 
@@ -36,6 +44,8 @@ module RLP
     end
 
     class ListSerializationError < SerializationError
+      attr :index, :element_exception
+
       def initialize(message: nil, obj: nil, element_exception: nil, index: nil)
         if message.nil?
           raise ArgumentError, "index and element_exception must be present" if index.nil? || element_exception.nil?
@@ -50,6 +60,8 @@ module RLP
     end
 
     class ListDeserializationError < DeserializationError
+      attr :index, :element_exception
+
       def initialize(message: nil, serial: nil, element_exception: nil, index: nil)
         if message.nil?
           raise ArgumentError, "index and element_exception must be present" if index.nil? || element_exception.nil?
@@ -63,5 +75,74 @@ module RLP
       end
     end
 
+    ##
+    # Exception raised if serialization of a {RLP::Sedes::Serializable} object
+    # fails.
+    #
+    class ObjectSerializationError < SerializationError
+      attr :field, :list_exception
+
+      ##
+      # @param sedes [RLP::Sedes::Serializable] the sedes that failed
+      # @param list_exception [RLP::Error::ListSerializationError] exception raised by the underlying
+      #   list sedes, or `nil` if no exception has been raised
+      #
+      def initialize(message: nil, obj: nil, sedes: nil, list_exception: nil)
+        if message.nil?
+          raise ArgumentError, "list_exception and sedes must be present" if list_exception.nil? || sedes.nil?
+
+          if list_exception.element_exception
+            field = sedes.serializable_fields.keys[list_exception.index]
+            message = "Serialization failed because of field #{field} ('#{list_exception.element_exception}')"
+          else
+            field = nil
+            message = "Serialization failed because of underlying list ('#{list_exception}')"
+          end
+        else
+          field = nil
+        end
+
+        super(message, obj)
+
+        @field = field
+        @list_exception = list_exception
+      end
+    end
+
+    ##
+    # Exception raised if deserialization by a {RLP::Sedes::Serializable} fails.
+    #
+    class ObjectDeserializationError < DeserializationError
+      attr :sedes, :field, :list_exception
+
+      ##
+      # @param sedes [RLP::Sedes::Serializable] the sedes that failed
+      # @param list_exception [RLP::ListDeserializationError] exception raised
+      #   by the underlying list sedes, or `nil` if no such exception has been
+      #   raised
+      #
+      def initialize(message: nil, serial: nil, sedes: nil, list_exception: nil)
+        if message.nil?
+          raise ArgumentError, "list_exception must be present" if list_exception.nil?
+
+          if list_exception.element_exception
+            raise ArgumentError, "sedes must be present" if sedes.nil?
+
+            field = sedes.serializable_fields.keys[list_exception.index]
+            message = "Deserialization failed because of field #{field} ('#{list_exception.element_exception}')"
+          else
+            field = nil
+            message = "Deserialization failed because of underlying list ('#{list_exception}')"
+          end
+        end
+
+        super(message, serial)
+
+        @sedes = sedes
+        @field = field
+        @list_exception = list_exception
+      end
+    end
+
   end
 end

data/lib/rlp/sedes.rb

@@ -3,13 +3,25 @@ require_relative 'sedes/binary'
 require_relative 'sedes/list'
 require_relative 'sedes/countable_list'
 require_relative 'sedes/raw'
+require_relative 'sedes/serializable'
 
 module RLP
   module Sedes
 
     class <<self
+      ##
+      # Try to find a sedes objects suitable for a given Ruby object.
+      #
+      # The sedes objects considered are `obj`'s class, `big_endian_int` and
+      # `binary`. If `obj` is a list, a `RLP::Sedes::List` will be constructed
+      # recursively.
+      #
+      # @param obj [Object] the Ruby object for which to find a sedes object
+      #
+      # @raise [TypeError] if no appropriate sedes could be found
+      #
       def infer(obj)
-        return obj if sedes?(obj)
+        return obj.class if sedes?(obj.class)
         return big_endian_int if obj.is_a?(Integer) && obj >= 0
         return binary if Binary.valid_type?(obj)
         return List.new(elements: obj.map {|item| infer(item) }) if RLP.list?(obj)

data/lib/rlp/sedes/serializable.rb

@@ -0,0 +1,127 @@
+module RLP
+  module Sedes
+    ##
+    # Mixin for objects which can be serialized into RLP lists.
+    #
+    # `fields` defines which attributes are serialized and how this is done. It
+    # is expected to be a hash in the form of `name => sedes`. Here, `name` is
+    # the name of an attribute and `sedes` is the sedes object that will be used
+    # to serialize the corresponding attribute. The object as a whole is then
+    # serialized as a list of those fields.
+    #
+    module Serializable
+
+      module ClassMethods
+        include Error
+
+        def set_serializable_fields(fields)
+          raise "Cannot override serializable fields!" if @serializable_fields
+
+          @serializable_fields = fields
+
+          fields.keys.each do |field|
+            class_eval <<-ATTR
+              def #{field}
+                @#{field}
+              end
+
+              def #{field}=(v)
+                _set_field(:#{field}, v)
+              end
+            ATTR
+          end
+        end
+
+        def serializable_fields
+          @serializable_fields
+        end
+
+        def serializable_sedes
+          @serializable_sedes ||= Sedes::List.new(elements: serializable_fields.values)
+        end
+
+        def serialize(obj)
+          begin
+            field_values = serializable_fields.keys.map {|k| obj.send k }
+          rescue NoMethodError => e
+            raise ObjectSerializationError.new(message: "Cannot serialize this object (missing attribute)", obj: obj)
+          end
+
+          begin
+            serializable_sedes.serialize(field_values)
+          rescue ListSerializationError => e
+            raise ObjectSerializationError.new(obj: obj, sedes: self, list_exception: e)
+          end
+        end
+
+        def deserialize(serial, exclude: nil, extra: {})
+          begin
+            values = serializable_sedes.deserialize(serial)
+          rescue ListDeserializationError => e
+            raise ObjectDeserializationError.new(serial: serial, sedes: self, list_exception: e)
+          end
+
+          params = Hash[*serializable_fields.keys.zip(values).flatten(1)]
+          params.delete_if {|field, value| exclude.include?(field) } if exclude
+
+          obj = self.new params.merge(extra)
+          obj.instance_variable_set :@_mutable, false
+          obj
+        end
+      end
+
+      class <<self
+        def included(base)
+          base.extend ClassMethods
+        end
+      end
+
+      def initialize(*args)
+        serializable_initialize(*args)
+      end
+
+      def serializable_initialize(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+
+        field_set = self.class.serializable_fields.keys
+
+        self.class.serializable_fields.keys.zip(args).each do |(field, arg)|
+          break unless arg
+          _set_field field, arg
+          field_set.delete field
+        end
+
+        options.each do |field, value|
+          if field_set.include?(field)
+            _set_field field, value
+            field_set.delete field
+          end
+        end
+
+        raise TypeError, "Not all fields initialized" unless field_set.size == 0
+      end
+
+      def ==(other)
+        return false unless other.class.respond_to?(:serialize)
+        self.class.serialize(self) == other.class.serialize(other)
+      end
+
+      def _set_field(field, value)
+        unless instance_variable_defined?(:@_mutable)
+          @_mutable = true
+        end
+
+        if _mutable? || !self.class.serializable_fields.has_key?(field)
+          instance_variable_set :"@#{field}", value
+        else
+          raise ArgumentError, "Tried to mutate immutable object"
+        end
+      end
+
+      def _mutable?
+        @_mutable
+      end
+
+    end
+  end
+end

data/lib/rlp/version.rb

@@ -1,3 +1,3 @@
 module RLP
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rlp
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jan Xie
@@ -38,6 +38,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 5.8.3
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.8.7.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.8.7.6
 description: A Ruby implementation of Ethereum's Recursive Length Prefix encoding
   (RLP).
 email:
@@ -60,6 +74,7 @@ files:
 - lib/rlp/sedes/countable_list.rb
 - lib/rlp/sedes/list.rb
 - lib/rlp/sedes/raw.rb
+- lib/rlp/sedes/serializable.rb
 - lib/rlp/utils.rb
 - lib/rlp/version.rb
 homepage: https://github.com/janx/ruby-rlp