universalid 0.0.1 → 0.1.1

data/Rakefile

@@ -6,9 +6,5 @@ require "minitest/test_task"
 task default: :test
 
 Minitest::TestTask.create(:test) do |t|
-  t.test_globs = if ARGV.size > 1
-    ARGV[1..]
-  else
-    ["test/**/*_test.rb"]
-  end
+  t.test_globs = ENV["GLOBS"] ? ENV["GLOBS"].split(",") : ["test/**/*_test.rb"]
 end

data/config/default.yml

@@ -0,0 +1,12 @@
+---
+prepack:
+  exclude: []
+  include: []
+  include_blank: true
+
+  database:
+    include_keys: true
+    include_timestamps: true
+    include_unsaved_changes: false
+    include_descendants: false
+    descendant_depth: 0

data/config/example.yml

@@ -0,0 +1,45 @@
+---
+##############################################################################################################
+# Prepack options applied before packing with MessagePack
+##############################################################################################################
+prepack:
+  # ..........................................................................................................
+  # A list of attributes to exclude (for objects like Hash, OpenStruct, Struct, etc.)
+  # Takes prescedence over the`include` list
+  exclude: []
+
+  # ..........................................................................................................
+  # A list of attributes to include (for objects like Hash, OpenStruct, Struct, etc.)
+  include: []
+
+  # ..........................................................................................................
+  # Whether or not to omit blank values when packing (nil, {}, [], "", etc.)
+  include_blank: true
+
+  # ==========================================================================================================
+  # Database records
+  database:
+    # ......................................................................................................
+    # Whether or not to include primary/foreign keys
+    # Setting this to `false` can be used to make a copy of an existing record
+    include_keys: true
+
+    # ......................................................................................................
+    # Whether or not to include date/time timestamps (created_at, updated_at, etc.)
+    # Setting this to `false` can be used to make a copy of an existing record
+    include_timestamps: true
+
+    # ......................................................................................................
+    # Whether or not to include unsaved changes
+    # Assign to `true` when packing new records
+    include_unsaved_changes: false
+
+    # ......................................................................................................
+    # Whether or not to include loaded in-memory descendants (i.e. child associations)
+    include_descendants: false
+
+    # ......................................................................................................
+    # The max depth (number) of loaded in-memory descendants to include when `include_descendants == true`
+    # For example, a value of (2) would include the following:
+    #   Parent > Child > Grandchild
+    descendant_depth: 0

data/lib/universal_id/contrib/active_record/base_message_pack_type.rb

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

data/lib/universal_id/contrib/active_record/base_packer.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+class UniversalID::Contrib::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
+    return record.attributes.slice(record.class.primary_key) if id_only?(prepack_database_options)
+
+    hash = record.attributes
+    reject_keys! hash if prepack_database_options.exclude_keys?
+    reject_timestamps! hash if prepack_database_options.exclude_timestamps?
+    reject_unsaved_changes! hash if prepack_database_options.exclude_unsaved_changes?
+    add_descendants! hash if include_descendants?
+
+    hash.prepack prepack_options
+  end
+
+  # helpers ..................................................................................................
+  def id_only?(prepack_database_options)
+    return false if record.new_record?
+    return false if prepack_database_options.include_descendants?
+    prepack_database_options.exclude_unsaved_changes?
+  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
+    foreign_key_column_names.each { |key| hash.delete key }
+  end
+
+  def reject_timestamps!(hash)
+    timestamp_column_names.each { |key| hash.delete key }
+  end
+
+  def reject_unsaved_changes!(hash)
+    record.changes_to_save.each do |key, (original_value, _)|
+      hash[key] = original_value
+    end
+  end
+
+  def add_descendants!(hash)
+    hash[DESCENDANTS_KEY] ||= {}
+
+    loaded_has_many_relations_by_name.each do |name, relation|
+      descendants = relation.map do |descendant|
+        descendant.instance_variable_set(:@_uid_depth, prepack_database_options.current_depth + 1)
+        UniversalID::Encoder.encode descendant, prepack_options
+      ensure
+        prepack_database_options.decrement_current_depth!
+        descendant.remove_instance_variable :@_uid_depth
+      end
+      hash[DESCENDANTS_KEY][name] = 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
+
+  def loaded_has_many_relations_by_name
+    has_many_associations.each_with_object({}) do |association, memo|
+      relation = record.public_send(association.name)
+      next unless relation.loaded?
+      memo[association.name] = relation
+    end
+  end
+end

data/lib/universal_id/contrib/active_record/base_unpacker.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+class UniversalID::Contrib::ActiveRecordBaseUnpacker
+  using UniversalID::Refinements::KernelRefinement
+
+  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 = const_find(class_name)
+      return nil unless klass
+
+      record = if attributes[klass.primary_key]
+        klass.find_by(klass.primary_key => attributes[klass.primary_key])
+      else
+        klass.new
+      end
+
+      assign_attributes record, attributes
+      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::Contrib::ActiveRecordBasePacker::DESCENDANTS_KEY] || {}
+      descendants.each do |name, list|
+        next unless record.respond_to?(name) && record.respond_to?("#{name}=")
+
+        models = list.map { |encoded| UniversalID::Encoder.decode encoded }
+        models.compact!
+        next unless models.any?
+
+        # NOTE: ActiveRecord is smart enough to not re-create or re-add
+        #       existing records for has_many associations
+        record.public_send "#{name}=", models
+      end
+    end
+  end
+end

data/lib/universal_id/contrib/active_record/relation_message_pack_type.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# 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 }
+)

data/lib/universal_id/contrib/active_record.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "active_record/base_message_pack_type"
+require_relative "active_record/relation_message_pack_type"

data/lib/universal_id/contrib/active_support/time_with_zone_message_pack_type.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+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
+)

data/lib/universal_id/contrib/active_support.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "active_support/time_with_zone_message_pack_type"

data/lib/universal_id/contrib/global_id/global_id_model.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class UniversalID::Contrib::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))
+      end
+    end
+
+    @id = @uid&.payload
+  end
+end

data/lib/universal_id/contrib/global_id/global_id_uid_extension.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module UniversalID::Contrib::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::Contrib::GlobalIDModel instance
+  # which implements the GlobalID::Identification interface/protocol
+  def to_global_id_model
+    UniversalID::Contrib::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

data/lib/universal_id/contrib/global_id/message_pack_type.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module UniversalID::Contrib::GlobalID; end
+
+require_relative "global_id_model"
+require_relative "global_id_uid_extension"
+
+URI::UID.include UniversalID::Contrib::GlobalIDUIDExtension
+
+UniversalID::MessagePackFactory.register(
+  type: GlobalID,
+  recreate_pool: false,
+  packer: ->(obj, packer) { packer.write obj.to_param },
+  unpacker: ->(unpacker) { GlobalID.parse unpacker.read }
+)

data/lib/universal_id/contrib/global_id.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "global_id/message_pack_type"

data/lib/universal_id/contrib/rails.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "active_record" if defined? ActiveRecord
+require_relative "active_support" if defined? ActiveSupport
+require_relative "global_id" if defined? GlobalID
+require_relative "signed_global_id" if defined? SignedGlobalID

data/lib/universal_id/contrib/signed_global_id/message_pack_type.rb

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

data/lib/universal_id/contrib/signed_global_id.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "signed_global_id/message_pack_type"

data/lib/universal_id/encoder.rb

@@ -0,0 +1,27 @@
+# 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 = {})
+      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
+      packed = UniversalID::MessagePackFactory.msgpack_pool.dump(object)
+      deflated = Brotli.deflate(packed)
+      Base64.urlsafe_encode64 deflated, padding: false
+    end
+
+    def decode(string)
+      decoded = Base64.urlsafe_decode64(string)
+      inflated = Brotli.inflate(decoded)
+      # 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 inflated
+    end
+  end
+end

data/lib/universal_id/message_pack_factory.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "etc"
+require "msgpack"
+
+UniversalID::MessagePackFactory = MessagePack::Factory.new.tap do |factory|
+  class << factory
+    attr_reader :msgpack_pool
+
+    def create_msgpack_pool
+      @msgpack_pool = UniversalID::MessagePackFactory.pool([Etc.nprocessors.to_i, 1].max)
+    end
+
+    def register_scalar(type:, recreate_pool: true, **options)
+      register id: next_type_id(order: :asc), type: type, **options
+    end
+
+    def register(type:, id: nil, recreate_pool: true, **options)
+      options[:recursive] = true unless options.key?(:recursive)
+      register_type(id || next_type_id(order: :desc), type, options)
+      create_msgpack_pool if recreate_pool
+    end
+
+    def next_type_id(order:)
+      range = 0..127
+
+      case order
+      when :asc
+        id = range.first
+        id += 1 while type_registered?(id)
+      when :desc
+        id = range.last
+        id -= 1 while type_registered?(id)
+      end
+
+      id = nil unless range.cover?(id)
+      id
+    end
+  end
+end
+
+# Register MessagePack built-in types
+UniversalID::MessagePackFactory.register_type MessagePack::Timestamp::TYPE, ::Time,
+  packer: MessagePack::Time::Packer,
+  unpacker: MessagePack::Time::Unpacker
+
+# Register MessagePack built-in extensions
+UniversalID::MessagePackFactory.register_type 0x00, ::Symbol
+
+# Register UniversalID types/extensions
+require_relative "message_pack_types"

data/lib/universal_id/message_pack_types/ruby/composites/open_struct.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+UniversalID::MessagePackFactory.register(
+  type: OpenStruct,
+  recreate_pool: false,
+  packer: ->(obj, packer) { packer.write obj.to_h },
+  unpacker: ->(unpacker) { OpenStruct.new unpacker.read }
+)

data/lib/universal_id/message_pack_types/ruby/composites/set.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+UniversalID::MessagePackFactory.register(
+  type: Set,
+  recusive: true,
+  recreate_pool: false,
+  packer: ->(obj, packer) { packer.write obj.to_a },
+  unpacker: ->(unpacker) { Set.new unpacker.read }
+)

data/lib/universal_id/message_pack_types/ruby/composites/struct.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+using UniversalID::Refinements::KernelRefinement
+
+UniversalID::MessagePackFactory.register(
+  type: Struct,
+  recreate_pool: false,
+  packer: ->(obj, packer) do
+    packer.write obj.class.name
+    packer.write obj.to_h
+  end,
+
+  unpacker: ->(unpacker) do
+    class_name = unpacker.read
+    hash = unpacker.read
+    klass = const_find(class_name)
+
+    # shenanigans to support ::Ruby 3.0.X and 3.1.X
+    RUBY_VERSION.start_with?("3.0", "3.1") ?
+      klass.new.tap { |struct| hash.each { |key, val| struct[key] = hash[key] } } :
+      klass.new(**hash)
+  end
+)

data/lib/universal_id/message_pack_types/ruby/scalars/complex.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+UniversalID::MessagePackFactory.register_scalar(
+  type: Complex,
+  recreate_pool: false,
+  packer: ->(obj, packer) { packer.write obj.to_s },
+  unpacker: ->(unpacker) { Kernel.Complex unpacker.read }
+)

data/lib/universal_id/message_pack_types/ruby/scalars/date.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+UniversalID::MessagePackFactory.register_scalar(
+  type: Date,
+  recreate_pool: false,
+  packer: ->(obj, packer) { packer.write obj.iso8601 },
+  unpacker: ->(unpacker) { Date.parse unpacker.read }
+)

data/lib/universal_id/message_pack_types/ruby/scalars/date_time.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+UniversalID::MessagePackFactory.register_scalar(
+  type: DateTime,
+  recreate_pool: false,
+  packer: ->(obj, packer) { packer.write obj.iso8601(9) },
+  unpacker: ->(unpacker) { DateTime.parse unpacker.read }
+)

data/lib/universal_id/message_pack_types/ruby/scalars/range.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+UniversalID::MessagePackFactory.register_scalar(
+  type: Range,
+  recreate_pool: false,
+  packer: ->(obj, packer) do
+    packer.write obj.first
+    packer.write obj.to_s.scan(/\.{2,3}/).first
+    packer.write obj.last
+  end,
+  unpacker: ->(unpacker) do
+    first = unpacker.read
+    operator = unpacker.read
+    last = unpacker.read
+    case operator
+    when ".." then first..last
+    when "..." then first...last
+    end
+  end
+)

data/lib/universal_id/message_pack_types/ruby/scalars/rational.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+UniversalID::MessagePackFactory.register_scalar(
+  type: Rational,
+  recreate_pool: false,
+  packer: ->(obj, packer) { packer.write obj.to_s },
+  unpacker: ->(unpacker) { Kernel.Rational unpacker.read }
+)

data/lib/universal_id/message_pack_types/ruby/scalars/regexp.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+UniversalID::MessagePackFactory.register_scalar(
+  type: Regexp,
+  recreate_pool: false,
+  packer: ->(obj, packer) do
+    packer.write obj.source
+    packer.write obj.options
+  end,
+  unpacker: ->(unpacker) do
+    source = unpacker.read
+    options = unpacker.read
+    Regexp.new source, options
+  end
+)

data/lib/universal_id/message_pack_types/uri/uid/type.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+UniversalID::MessagePackFactory.register(
+  type: URI::UID,
+  recreate_pool: false,
+  packer: ->(obj, packer) { packer.write obj.to_s },
+  unpacker: ->(unpacker) { URI::UID.parse unpacker.read }
+)

data/lib/universal_id/message_pack_types.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# NOTE: MessagePack scans registered type in linear order and first match wins
+
+# scalars
+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"
+require_relative "message_pack_types/ruby/scalars/date"
+require_relative "message_pack_types/ruby/scalars/range"
+require_relative "message_pack_types/ruby/scalars/regexp"
+
+# composites
+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
+
+UniversalID::MessagePackFactory.create_msgpack_pool