universalid 0.1.2 → 0.1.4

data/Rakefile

@@ -2,9 +2,23 @@
 
 require "bundler/gem_tasks"
 require "minitest/test_task"
+require "pry-byebug"
 
 task default: :test
 
-Minitest::TestTask.create(:test) do |t|
-  t.test_globs = ENV["GLOBS"] ? ENV["GLOBS"].split(",") : ["test/**/*_test.rb"]
+# take explicit control of test initialization
+
+task test: [:load_tests, :exec_tests]
+
+task :load_tests do
+  ENV["TEST_SEED"] ||= ENV.fetch("TEST_SEED", Time.now).to_s
+  require_relative "test/test_extension"
+
+  globs = ENV["GLOBS"] ? ENV["GLOBS"].split(",") : ["test/**/*_test.rb"]
+  files = globs.map { |glob| Dir[glob] }.flatten.shuffle
+  files.each { |file| require_relative file }
+end
+
+Minitest::TestTask.create(:exec_tests) do |t|
+  t.test_globs.clear
 end

data/config/default.yml

@@ -7,6 +7,6 @@ prepack:
   database:
     include_keys: true
     include_timestamps: true
-    include_unsaved_changes: false
+    include_changes: false
     include_descendants: false
     descendant_depth: 0

data/config/example.yml

@@ -13,7 +13,7 @@ prepack:
   include: []
 
   # ..........................................................................................................
-  # Whether or not to omit blank values when packing (nil, {}, [], "", etc.)
+  # Whether or not to include blank values when packing (nil, {}, [], "", etc.)
   include_blank: true
 
   # ==========================================================================================================
@@ -32,7 +32,7 @@ prepack:
     # ......................................................................................................
     # Whether or not to include unsaved changes
     # Assign to `true` when packing new records
-    include_unsaved_changes: false
+    include_changes: false
 
     # ......................................................................................................
     # Whether or not to include loaded in-memory descendants (i.e. child associations)

data/lib/universalid/encoder.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "base64"
+require "brotli"
+
+# This module provides the ability to encode and decode objects into a compressed, URL-safe string
+module UniversalID::Encoder
+  class << self
+    def encode(object, options = {})
+      packed = UniversalID::Packer.pack(object, options)
+      deflated = Brotli.deflate(packed)
+      Base64.urlsafe_encode64 deflated, padding: false
+    end
+
+    def decode(string)
+      decoded = Base64.urlsafe_decode64(string)
+      inflated = Brotli.inflate(decoded)
+      UniversalID::Packer.unpack inflated
+    end
+  end
+end

data/lib/universalid/extensions/active_record/base_message_pack_type.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+if defined? ActiveRecord::Base
+
+  require_relative "base_packer"
+  require_relative "base_unpacker"
+
+  UniversalID::MessagePackFactory.register(
+    type: ActiveRecord::Base,
+    recreate_pool: false,
+    packer: ->(obj, packer) { UniversalID::Extensions::ActiveRecordBasePacker.new(obj).pack_with packer },
+    unpacker: ->(unpacker) { UniversalID::Extensions::ActiveRecordBaseUnpacker.unpack_with unpacker }
+  )
+
+end

data/lib/universalid/extensions/active_record/base_packer.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+if defined? ActiveRecord
+
+  class UniversalID::Extensions::ActiveRecordBasePacker
+    using UniversalID::Refinements::HashRefinement
+
+    # TODO: implement support for has_one
+    #       ActiveRecord::Reflection::HasOneReflection
+    #
+    # TODO: implement support for has_and_belongs_to_many
+    #       ActiveRecord::Reflection::HasAndBelongsToManyReflection
+    #
+    HAS_MANY_ASSOCIATIONS = [
+      ActiveRecord::Reflection::HasManyReflection
+    ]
+
+    DESCENDANTS_KEY = "uid:descendants"
+
+    attr_reader :record
+
+    def initialize(record)
+      @record = record
+    end
+
+    def pack_with(packer)
+      packer.write record.class.name
+      packer.write packable_attributes
+    end
+
+    def prepack_options
+      options = record.instance_variable_get(:@_uid_prepack_options)
+      options = UniversalID::PrepackOptions.new unless options.is_a?(UniversalID::PrepackOptions)
+      options
+    end
+
+    def prepack_database_options
+      prepack_options.database_options
+    end
+
+    private
+
+    def packable_attributes
+      hash = if id_only?
+        record.attributes.slice record.class.primary_key
+      else
+        record.attributes.select { |name, _| prepack_options.keep_key? name }.tap do |attrs|
+          reject_keys! attrs if prepack_database_options.exclude_keys?
+          reject_timestamps! attrs if prepack_database_options.exclude_timestamps?
+          reject_unsaved_changes! attrs if prepack_database_options.exclude_changes?
+        end
+      end
+
+      if include_descendants?
+        add_descendants! hash
+        hash.delete DESCENDANTS_KEY if hash[DESCENDANTS_KEY].empty?
+      end
+
+      hash["marked_for_destruction"] = true if record.marked_for_destruction?
+
+      hash.prepack prepack_options
+    end
+
+    # helpers ..................................................................................................
+    def id_only?
+      return false if record.new_record?
+
+      # explicit exclusion of primary key
+      return false if prepack_options.reject_key?(record.class.primary_key)
+
+      # explicit exclusion of all db keys and primary key is not explicitly included
+      return false if prepack_database_options.exclude_keys? && !prepack_options.keep_key?(record.class.primary_key)
+
+      # non-pk attribute names
+      attribute_names = record.attributes.keys - [record.class.primary_key]
+
+      # explicit inclusion of non-pk attributes
+      return false if prepack_options.includes.any? && attribute_names.any? { |attr| prepack_options.includes[attr] }
+
+      # record has unsaved non-pk changes and we want to keep them
+      return false if prepack_database_options.include_changes? && attribute_names.any? { |attr| record.changes[attr] }
+
+      prepack_database_options.include_keys?
+    end
+
+    def include_descendants?
+      return false unless prepack_database_options.include_descendants?
+
+      max_depth = prepack_database_options.descendant_depth.to_i
+      record_depth = record.instance_variable_get(:@_uid_depth).to_i
+      record_depth < max_depth
+    end
+
+    # attribute mutators .......................................................................................
+
+    def reject_keys!(hash)
+      hash.delete record.class.primary_key unless prepack_options.includes[record.class.primary_key]
+      foreign_key_column_names.each { |key| hash.delete(key) unless prepack_options.includes[key] }
+    end
+
+    def reject_timestamps!(hash)
+      timestamp_column_names.each { |key| hash.delete key unless prepack_options.includes[key] }
+    end
+
+    def reject_unsaved_changes!(hash)
+      record.changes_to_save.each do |key, (original_value, _)|
+        hash[key] = original_value if prepack_options.keep_key?(key)
+      end
+    end
+
+    def add_descendants!(hash)
+      hash[DESCENDANTS_KEY] ||= {}
+
+      has_many_descendant_instances_by_association_name.each do |name, relation|
+        descendants = relation.each_with_object([]) do |descendant, memo|
+          next unless descendant.persisted? || prepack_database_options.include_changes?
+
+          descendant.instance_variable_set(:@_uid_depth, prepack_database_options.current_depth + 1)
+          prepacked = UniversalID::Prepacker.prepack(descendant, prepack_options.to_h)
+          memo << UniversalID::MessagePackFactory.msgpack_pool.dump(prepacked)
+        ensure
+          prepack_database_options.decrement_current_depth!
+          descendant.remove_instance_variable :@_uid_depth
+        end
+        hash[DESCENDANTS_KEY][name.to_s] = descendants
+      end
+
+      prepack_database_options.increment_current_depth!
+    end
+
+    # active record helpers ....................................................................................
+
+    def timestamp_column_names
+      record.class.all_timestamp_attributes_in_model
+    end
+
+    def foreign_key_column_names
+      record.class.reflections
+        .each_with_object([]) do |(name, reflection), memo|
+          memo << reflection.foreign_key if reflection.macro == :belongs_to
+        end
+    end
+
+    def associations
+      record.class.reflect_on_all_associations
+    end
+
+    def has_many_associations
+      associations.select { |a| HAS_MANY_ASSOCIATIONS.include? a.class }
+    end
+
+    # Returns a has of the current in-memory `has_many` associated records keyed by name
+    def has_many_descendant_instances_by_association_name
+      has_many_associations.each_with_object({}) do |association, memo|
+        relation = record.public_send(association.name)
+
+        descendants = Set.new
+
+        # persisted records
+        relation.each { |descendant| descendants << descendant } if relation.loaded?
+
+        # new records
+        relation.target.each { |descendant| descendants << descendant } if relation.target.any?
+
+        memo[association.name] = descendants.to_a if descendants.any?
+      end
+    end
+  end
+
+end

data/lib/universalid/extensions/active_record/base_unpacker.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+if defined? ActiveRecord
+
+  class UniversalID::Extensions::ActiveRecordBaseUnpacker
+    class << self
+      def unpack_with(unpacker)
+        class_name = unpacker.read
+        attributes = unpacker.read || {}
+        create_instance class_name, attributes
+      end
+
+      private
+
+      def create_instance(class_name, attributes)
+        klass = Object.const_get(class_name) if Object.const_defined?(class_name)
+        return nil unless klass
+
+        record = if attributes[klass.primary_key]
+          klass.find_by(klass.primary_key => attributes[klass.primary_key])
+        end
+        record ||= klass.new
+
+        assign_attributes record, attributes.except("marked_for_destruction")
+        record.mark_for_destruction if attributes["marked_for_destruction"]
+        assign_descendants record, attributes
+
+        record
+      end
+
+      def assign_attributes(record, attributes)
+        attributes.each do |key, value|
+          record.public_send :"#{key}=", value if record.respond_to? :"#{key}="
+        end
+      end
+
+      def assign_descendants(record, attributes)
+        descendants = attributes[UniversalID::Extensions::ActiveRecordBasePacker::DESCENDANTS_KEY] || {}
+        descendants.each do |name, list|
+          next unless record.respond_to?(name) && record.respond_to?(:"#{name}=")
+
+          models = list.map { |packed| UniversalID::MessagePackFactory.msgpack_pool.load(packed) }
+          models.compact!
+          next unless models.any?
+
+          new_models = models.select(&:new_record?)
+          models -= new_models
+
+          # restore persisted models
+          # NOTE: ActiveRecord is smart enough to not re-create or re-add
+          #       existing records for has_many associations
+          record.public_send :"#{name}=", models if models.any?
+
+          # restore new unsaved models
+          record.public_send(name).target.concat new_models if new_models.any?
+        end
+      end
+    end
+  end
+
+end

data/lib/universalid/extensions/active_record/relation_message_pack_type.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+if defined? ActiveRecord::Relation
+
+  # TODO: Revisit ActiveRecord::Relation serialization strategy,
+  #       and attempt to optimize without falling back to Marshal.dump/load
+  UniversalID::MessagePackFactory.register(
+    type: ActiveRecord::Relation,
+    recreate_pool: false,
+    packer: ->(obj, packer) do
+      # NOTE: packing a relation will reset the loaded state and internal cache of the relation
+      #       this ensures minimal payload size
+      obj = obj.dup # clear internal cached state (loaded results, etc.)
+      obj.reset # dup should clear any internal caching, but we call reset just in case
+      packer.write Marshal.dump(obj)
+    end,
+    unpacker: ->(unpacker) { Marshal.load unpacker.read }
+  )
+
+end

data/lib/universalid/extensions/active_support/time_with_zone_message_pack_type.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+if defined? ActiveSupport::TimeWithZone
+
+  UniversalID::MessagePackFactory.register(
+    type: ActiveSupport::TimeWithZone,
+    packer: ->(obj, packer) do
+      packer.write obj.iso8601(9)
+      packer.write obj.zone
+    end,
+    unpacker: ->(unpacker) do
+      time = Time.parse(unpacker.read)
+      zone = unpacker.read
+      ActiveSupport::TimeWithZone.new time, ActiveSupport::TimeZone[zone]
+    end
+  )
+
+end

data/lib/universalid/extensions/global_id/global_id_model.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+if defined? GlobalID::Identification
+
+  class UniversalID::Extensions::GlobalIDModel
+    include GlobalID::Identification
+
+    def self.find(value)
+      new value
+    end
+
+    attr_reader :id, :uid
+
+    def initialize(universal_id)
+      @uid = case universal_id
+      when URI::UID then universal_id
+      when String
+        case universal_id
+        when /\A#{URI::UID::SCHEME}/o then URI::UID.parse(universal_id)
+        else URI::UID.parse(URI::UID.build_string(universal_id, self))
+        end
+      end
+
+      @id = @uid&.payload
+    end
+  end
+
+end

data/lib/universalid/extensions/global_id/global_id_uid_extension.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+if defined? GlobalID::Identification && defined? SignedGlobalID
+
+  require "forwardable"
+  require_relative "global_id_model"
+
+  module UniversalID::Extensions::GlobalIDUIDExtension
+    extend Forwardable
+
+    def self.included(mixer)
+      mixer.extend ClassMethods
+    end
+
+    # Adds all GlobalID::Identification methods
+    def_delegators(:to_global_id_model, *GlobalID::Identification.instance_methods(false))
+
+    # Returns a UniversalID::Extensions::GlobalIDModel instance
+    # which implements the GlobalID::Identification interface/protocol
+    def to_global_id_model
+      UniversalID::Extensions::GlobalIDModel.new self
+    end
+
+    module ClassMethods
+      def from_global_id_record(gid_record)
+        gid_record&.find&.uid
+      end
+
+      def from_global_id(gid, options = {})
+        from_global_id_record GlobalID.parse(gid, options)
+      end
+
+      alias_method :from_gid, :from_global_id
+
+      def from_signed_global_id(sgid, options = {})
+        from_global_id_record SignedGlobalID.parse(sgid, options)
+      end
+
+      alias_method :from_sgid, :from_signed_global_id
+    end
+  end
+
+end

data/lib/universalid/extensions/global_id/message_pack_type.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+if defined? GlobalID
+
+  require_relative "global_id_uid_extension"
+
+  URI::UID.include UniversalID::Extensions::GlobalIDUIDExtension
+
+  UniversalID::MessagePackFactory.register(
+    type: GlobalID,
+    recreate_pool: false,
+    packer: ->(obj, packer) { packer.write obj.to_param },
+    unpacker: ->(unpacker) { GlobalID.parse unpacker.read }
+  )
+
+end

data/lib/universalid/extensions/signed_global_id/message_pack_type.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+if defined? SignedGlobalID
+
+  UniversalID::MessagePackFactory.register(
+    type: SignedGlobalID,
+    recreate_pool: false,
+    packer: ->(obj, packer) { packer.write obj.to_param },
+    unpacker: ->(unpacker) { SignedGlobalID.parse unpacker.read }
+  )
+
+end

data/lib/{universal_id → universalid}/message_pack_types/ruby/composites/open_struct.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "ostruct"
+
 UniversalID::MessagePackFactory.register(
   type: OpenStruct,
   recreate_pool: false,

data/lib/universalid/message_pack_types/ruby/scalars/bigdecimal.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+UniversalID::MessagePackFactory.register_scalar(
+  type: BigDecimal,
+  recreate_pool: false,
+  packer: ->(obj, packer) { packer.write obj.to_s },
+  unpacker: ->(unpacker) { BigDecimal unpacker.read }
+)

data/lib/{universal_id → universalid}/message_pack_types/ruby/scalars/date.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "date"
+
 UniversalID::MessagePackFactory.register_scalar(
   type: Date,
   recreate_pool: false,

data/lib/{universal_id → universalid}/message_pack_types/ruby/scalars/date_time.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "date"
+
 UniversalID::MessagePackFactory.register_scalar(
   type: DateTime,
   recreate_pool: false,

data/lib/{universal_id → universalid}/message_pack_types.rb

@@ -3,6 +3,7 @@
 # NOTE: MessagePack scans registered type in linear order and first match wins
 
 # scalars
+require_relative "message_pack_types/ruby/scalars/bigdecimal"
 require_relative "message_pack_types/ruby/scalars/complex"
 require_relative "message_pack_types/ruby/scalars/rational"
 require_relative "message_pack_types/ruby/scalars/date_time"
@@ -16,10 +17,7 @@ require_relative "message_pack_types/ruby/composites/open_struct"
 require_relative "message_pack_types/ruby/composites/struct"
 require_relative "message_pack_types/ruby/composites/set"
 
-# uid
-require_relative "message_pack_types/uri/uid/type"
-
-# contribs
-require_relative "contrib/rails" if defined? Rails
+# extensions
+Dir["#{__dir__}/extensions/**/*.rb"].each { |f| require f }
 
 UniversalID::MessagePackFactory.create_msgpack_pool

data/lib/universalid/packer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class UniversalID::Packer
+  class << self
+    def pack(object, options = {})
+      object = UniversalID::Prepacker.prepack(object, options)
+
+      # This is basically the same call as UniversalID::MessagePackFactory.pack(object),
+      # but it uses a pool of pre-initialized packers/unpackers instead of creating a new one each time
+      UniversalID::MessagePackFactory.msgpack_pool.dump object
+    end
+
+    def unpack(string)
+      # This is basically the same call as UniversalID::MessagePackFactory.unpack(object),
+      # but it uses a pool of pre-initialized packers/unpackers instead of creating a new one each time
+      UniversalID::MessagePackFactory.msgpack_pool.load string
+    end
+  end
+end

data/lib/{universal_id → universalid}/prepack_database_options.rb

@@ -25,12 +25,12 @@ class UniversalID::PrepackDatabaseOptions
     !include_timestamps?
   end
 
-  def include_unsaved_changes?
-    !!@settings.include_unsaved_changes
+  def include_changes?
+    !!@settings.include_changes
   end
 
-  def exclude_unsaved_changes?
-    !include_unsaved_changes?
+  def exclude_changes?
+    !include_changes?
   end
 
   def descendant_depth

data/lib/{universal_id → universalid}/prepack_options.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "prepack_database_options"
-
 class UniversalID::PrepackOptions
   attr_reader :excludes, :includes, :database_options
 
@@ -37,7 +35,7 @@ class UniversalID::PrepackOptions
   end
 
   def reject_key?(key)
-    excludes[key.to_s]
+    !!excludes[key.to_s]
   end
 
   def keep_value?(value)
@@ -57,15 +55,7 @@ class UniversalID::PrepackOptions
   end
 
   def blank?(value)
-    return true if value.nil?
-    return false if !!value == value # booleans
-
-    result = false
-    result ||= value.empty? if value.respond_to?(:empty?)
-    result ||= value.blank? if value.respond_to?(:blank?)
-    result ||= value.strip.empty? if value.is_a?(String)
-    result ||= value.compact.empty? if value.is_a?(Array) || value.is_a?(Hash)
-    result
+    (value == false) ? false : value.blank?
   end
 
   def present?(value)

data/lib/{universal_id → universalid}/prepacker.rb

@@ -15,11 +15,11 @@ class UniversalID::Prepacker
   class << self
     def prepack(object, options = {})
       options = UniversalID::PrepackOptions.new(options) unless options.is_a?(UniversalID::PrepackOptions)
+      object.instance_variable_set(:@_uid_prepack_options, options) unless object.frozen?
 
-      return object.prepack(options) if object.respond_to?(:prepack)
+      return object unless object.respond_to?(:prepack)
 
-      object.instance_variable_set(:@_uid_prepack_options, options) unless object.frozen?
-      object
+      object.prepack options
     end
   end
 end

data/lib/{universal_id → universalid}/refinements/open_struct_refinement.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "ostruct"
+
 module UniversalID::Refinements::OpenStructRefinement
   refine OpenStruct do
     using UniversalID::Refinements::HashRefinement

data/lib/universalid/refinements.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+module UniversalID::Refinements; end

data/lib/{universal_id → universalid}/settings.rb

@@ -38,7 +38,8 @@ class UniversalID::Settings
       in database: database then database.each { |k, v| assign k, v, to: to }
       in include_keys: include_keys then to.prepack.database.include_keys = !!include_keys
       in include_timestamps: include_timestamps then to.prepack.database.include_timestamps = !!include_timestamps
-      in include_unsaved_changes: include_unsaved_changes then to.prepack.database.include_unsaved_changes = !!include_unsaved_changes
+      in include_changes: include_changes then to.prepack.database.include_changes = !!include_changes
+      in include_unsaved_changes: include_changes then to.prepack.database.include_changes = !!include_unsaved_changes # TODO: Remove in v1.0
       in include_descendants: include_descendants then to.prepack.database.include_descendants = !!include_descendants
       in descendant_depth: descendant_depth then to.prepack.database.descendant_depth = descendant_depth
       else # ignore key
@@ -60,7 +61,7 @@ class UniversalID::Settings
       config = self.class.build(**config) unless key == :default
       registry[key] = config
       self.class.define_method(key) { config }
-      self.class.define_method("#{key}_copy") { Marshal.load Marshal.dump(config) }
+      self.class.define_method(:"#{key}_copy") { Marshal.load Marshal.dump(config) }
       self.class.define_singleton_method(key) { instance.public_send key }
       [key, config]
     end

data/lib/{universal_id → universalid}/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module UniversalID
-  VERSION = "0.1.2"
+  VERSION = "0.1.4"
 end