activeid 0.6.1

data/examples/time_based_uuids.rb

@@ -0,0 +1,58 @@
+# Time-based UUIDs (version 1) store timestamp of their creation, and are
+# monotonically increasing in time.  This is very advantageous in some
+# use cases.
+
+ENV["DB"] ||= "sqlite3"
+
+require "bundler/setup"
+Bundler.require :development
+
+require "active_id"
+require_relative "../spec/support/0_logger"
+require_relative "../spec/support/1_db_connection"
+
+#### SCHEMA ####
+
+ActiveRecord::Schema.define do
+  create_table :authors, id: false, force: true do |t|
+    t.string :id, limit: 36, primary_key: true
+    t.string :name
+    t.timestamps
+  end
+end
+
+#### MODELS ####
+
+class Author < ActiveRecord::Base
+  include ActiveID::Model
+  attribute :id, ActiveID::Type::StringUUID.new
+  uuid_generator :time
+end
+
+#### PROOF ####
+
+SolidAssert.enable_assertions
+
+poe = Author.create! name: "Edgar Alan Poe"
+thu = Author.create! name: "Thucydides"
+fon = Author.create! name: "Jean de La Fontaine"
+kas = Author.create! name: "Jan Kasprowicz"
+
+# Version 1 means time-based UUIDs
+assert poe.id.version == 1
+
+# Timestamp can be extracted from UUID
+assert poe.id.timestamp.between? 1.minute.ago, 1.minute.from_now
+
+# Lexicographical ordering of version 1 UUIDs reflects their temporal ordering
+assert Author.all.order(id: :asc).to_a == [poe, thu, fon, kas]
+
+#### PROVE THAT ASSERTIONS WERE WORKING ####
+
+begin
+  assert 1 == 2
+rescue SolidAssert::AssertionFailedError
+  puts "All OK."
+else
+  raise "Assertions do not work!"
+end

data/examples/using_migrations.rb

@@ -0,0 +1,50 @@
+# Active UUID features a convenience #uuid method, which may be used to create
+# a binary column in database migration.  Since it involves monkey patching,
+# "active_id/all" must be loaded.
+
+ENV["DB"] ||= "sqlite3"
+
+require "bundler/setup"
+Bundler.require :development
+
+# Note "active_id/all", which registers new column definitions!
+require "active_id/all"
+
+require_relative "../spec/support/0_logger"
+require_relative "../spec/support/1_db_connection"
+
+#### SCHEMA ####
+
+ActiveRecord::Schema.define do
+  create_table :authors, id: false, force: true do |t|
+    t.uuid :id, primary_key: true
+    t.string :name
+    t.timestamps
+  end
+end
+
+#### PROOF ####
+
+SolidAssert.enable_assertions
+
+id_column = ActiveRecord::Base.connection.columns("authors")[0]
+assert id_column.name == "id"
+
+case ENV["DB"]
+when "sqlite3"
+  assert id_column.sql_type == "binary(16)"
+when "mysql"
+  assert id_column.sql_type == "varbinary(16)"
+when "postgresql"
+  assert id_column.sql_type == "uuid"
+end
+
+#### PROVE THAT ASSERTIONS WERE WORKING ####
+
+begin
+  assert 1 == 2
+rescue SolidAssert::AssertionFailedError
+  puts "All OK."
+else
+  raise "Assertions do not work!"
+end

data/gemfiles/Rails-5_0.gemfile

@@ -0,0 +1,8 @@
+source "http://rubygems.org"
+
+gemspec path: "../"
+
+gem "activerecord", "~> 5.0.0"
+
+gem "codecov", require: false, group: :test
+gem "simplecov", require: false, group: :test

data/gemfiles/Rails-5_1.gemfile

@@ -0,0 +1,8 @@
+source "http://rubygems.org"
+
+gemspec path: "../"
+
+gem "activerecord", "~> 5.1.0"
+
+gem "codecov", require: false, group: :test
+gem "simplecov", require: false, group: :test

data/gemfiles/Rails-5_2.gemfile

@@ -0,0 +1,8 @@
+source "http://rubygems.org"
+
+gemspec path: "../"
+
+gem "activerecord", "~> 5.2.0"
+
+gem "codecov", require: false, group: :test
+gem "simplecov", require: false, group: :test

data/gemfiles/Rails-head.gemfile

@@ -0,0 +1,8 @@
+source "http://rubygems.org"
+
+gemspec path: "../"
+
+gem "activerecord", github: "rails/rails"
+
+gem "codecov", require: false, group: :test
+gem "simplecov", require: false, group: :test

data/lib/active_id.rb

@@ -0,0 +1,12 @@
+require "active_id/version"
+require "active_id/utils"
+require "active_id/model"
+require "active_id/type"
+require "active_id/railtie" if defined?(Rails::Railtie)
+require "pp"
+
+module ActiveID
+  class << self
+    delegate :quote_as_binary, to: Utils
+  end
+end

data/lib/active_id/all.rb

@@ -0,0 +1,2 @@
+require_relative "../active_id"
+require_relative "connection_patches"

data/lib/active_id/connection_patches.rb

@@ -0,0 +1,65 @@
+require "active_record"
+require "active_support/concern"
+
+module ActiveID
+  module ConnectionPatches
+    module ColumnMethods
+      def uuid(*args, **options)
+        args.each { |name| column(name, :uuid, options) }
+      end
+    end
+
+    module Quoting
+      extend ActiveSupport::Concern
+
+      def self.prepended(_klass)
+        def native_database_types
+          super.merge(uuid: { name: "binary", limit: 16 })
+        end
+      end
+    end
+
+    module PostgreSQLQuoting
+      extend ActiveSupport::Concern
+
+      def self.prepended(_klass)
+        def native_database_types
+          super.merge(uuid: { name: "uuid" })
+        end
+      end
+    end
+
+    module ConnectionHandling
+      def establish_connection(*_args) # rubocop:disable Metrics/MethodLength
+        super
+
+        arca = ActiveRecord::ConnectionAdapters
+
+        arca::Table.include(ColumnMethods)
+        arca::TableDefinition.include(ColumnMethods)
+
+        if defined? arca::MysqlAdapter
+          arca::MysqlAdapter.prepend(Quoting)
+        end
+
+        if defined? arca::Mysql2Adapter
+          arca::Mysql2Adapter.prepend(Quoting)
+        end
+
+        if defined? arca::SQLite3Adapter
+          arca::SQLite3Adapter.prepend(Quoting)
+        end
+
+        if defined? arca::PostgreSQLAdapter
+          arca::PostgreSQLAdapter.prepend(PostgreSQLQuoting)
+        end
+      end
+    end
+
+    def self.apply!
+      ActiveRecord::Base.singleton_class.prepend ConnectionHandling
+    end
+  end
+end
+
+ActiveID::ConnectionPatches.apply!

data/lib/active_id/model.rb

@@ -0,0 +1,55 @@
+require "active_support"
+
+module ActiveID
+  # Include this module into all models which are meant to store UUIDs.
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_natural_key, instance_writer: false
+      class_attribute :_uuid_namespace, instance_writer: false
+      class_attribute :_uuid_generator, instance_writer: false
+      self._uuid_generator = :random
+
+      before_create :generate_uuids_if_needed
+    end
+
+    module ClassMethods
+      def natural_key(*attributes)
+        self._natural_key = attributes
+      end
+
+      def uuid_namespace(namespace)
+        namespace = Utils.cast_to_uuid(namespace)
+        self._uuid_namespace = namespace
+      end
+
+      def uuid_generator(generator_name)
+        self._uuid_generator = generator_name
+      end
+    end
+
+    def create_uuid
+      if _natural_key
+        # TODO if all the attributes return nil you might want to warn about this
+        chained = _natural_key.map { |attribute| send(attribute) }.join("-")
+        UUIDTools::UUID.sha1_create(_uuid_namespace || UUIDTools::UUID_OID_NAMESPACE, chained)
+      else
+        case _uuid_generator
+        when :random
+          UUIDTools::UUID.random_create
+        when :time
+          UUIDTools::UUID.timestamp_create
+        end
+      end
+    end
+
+    def generate_uuids_if_needed
+      primary_key = self.class.primary_key
+      primary_key_attribute_type = self.class.type_for_attribute(primary_key)
+      if ::ActiveID::Type::Base === primary_key_attribute_type
+        send("#{primary_key}=", create_uuid) unless send("#{primary_key}?")
+      end
+    end
+  end
+end

data/lib/active_id/railtie.rb

@@ -0,0 +1,12 @@
+require "active_id"
+require "rails"
+
+module ActiveID
+  class Railtie < Rails::Railtie
+    railtie_name :activeid
+
+    config.to_prepare do
+      ActiveID::ConnectionPatches.apply!
+    end
+  end
+end

data/lib/active_id/type.rb

@@ -0,0 +1,100 @@
+require "active_record"
+
+module ActiveID
+  # ActiveRecord's attribute types for serializing UUIDs.
+  #
+  # ==== Examples
+  #
+  #   class Book
+  #     attribute :id, ActiveID::Type::BinaryUUID.new
+  #   end
+  #
+  # ==== See also
+  #
+  # * docs for +::ActiveRecord::Attributes::ClassMethods#attribute+
+  # * docs for +::ActiveRecord::Type::Value+
+  module Type
+    # See subclasses.
+    #
+    # @abstract Subclasses should define at least +instantiate_storage+ method.
+    class Base < ::ActiveRecord::Type::Value
+      attr_reader :storage_type
+
+      delegate :cast_to_uuid, to: ActiveID::Utils
+      delegate :serialize, :deserialize, to: :storage_type, prefix: :s
+
+      def initialize
+        @storage_type = instantiate_storage
+      end
+
+      # Converts binary values into UUIDs.
+      def deserialize(value)
+        cast_to_uuid(s_deserialize(value))
+      end
+
+      # Converts strings into UUIDs on user input assignment, called internally
+      # from #cast.
+      def cast_value(value)
+        cast_to_uuid(value)
+      end
+    end
+
+    # ActiveRecord's attribute type which serializes UUIDs as binaries.  Useful
+    # for RDBSes which do not support UUIDs natively (i.e. MySQL, SQLite3).
+    #
+    # UUIDs serialized as binaries are more space efficient (16 bytes vs
+    # 36 characters of their text representation), which may also lead to
+    # performance boost if given column is indexed (a bigger piece of index can
+    # be kept in memory).  The downside is that this representation is less
+    # readable for humans who access serialized values outside Rails
+    # (i.e. in a database console).
+    #
+    # ==== Accessing in database console
+    #
+    # In MySQL (but not in MariaDB), there is
+    # a {+BIN_TO_UUID()+}[https://mysqlserverteam.com/mysql-8-0-uuid-support/]
+    # function which converts binaries to UUID strings.
+    # There is {a feature request}[https://jira.mariadb.org/browse/MDEV-15854]
+    # in MariaDB's issue tracker to add a similar feature.
+    #
+    # ==== Caveat
+    #
+    # Does not work with PostgreSQL adapter.  Nevertheless, there should not be
+    # any good reason to use {BinaryUUID} with PostgreSQL.  Open a feature
+    # request if you find any.
+    #
+    # In PostgreSQL, {StringUUID} attribute type is recommended as it is
+    # compatible with Postgres-specific +UUID+ data type.
+    class BinaryUUID < Base
+      def serialize(value)
+        s_serialize(cast_to_uuid(value)&.raw)
+      end
+
+      protected
+
+      def instantiate_storage
+        ::ActiveRecord::Type::Binary.new
+      end
+    end
+
+    # ActiveRecord's attribute type which serializes UUIDs as strings.
+    #
+    # UUIDs are serialized as 36 characters long strings
+    # (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).  In PostgreSQL, this
+    # representation is compatible with +UUID+ data type, which is a unique
+    # feature of this RDBS.  In other RDBSes, this attribute type can be
+    # used with textual data types (e.g. +VARCHAR(36)+), however {BinaryUUID}
+    # should be preferred when performance matters.
+    class StringUUID < Base
+      def serialize(value)
+        s_serialize(cast_to_uuid(value)&.to_s)
+      end
+
+      protected
+
+      def instantiate_storage
+        ::ActiveRecord::Type::String.new
+      end
+    end
+  end
+end

data/lib/active_id/utils.rb

@@ -0,0 +1,77 @@
+require "uuidtools"
+
+module ActiveID
+  # Variety of convenience functions.
+  module Utils
+    module_function
+
+    # Casts +value+ to +UUIDTools::UUID+.
+    #
+    # When an instance of +UUIDTools::UUID+ or +nil+ is given, then this method
+    # returns that argument.  When a +String+ is given, then it is parsed,
+    # and respective instance of UUIDTools::UUID is returned.
+    #
+    # A variety of string formats is recognized:
+    #
+    # - 36 characters long strings (hexadecimal number interpolated with dashes)
+    # - 32 characters long strings (hexadecimal number without dashes)
+    # - 16 bytes long strings (binary representation of UUID)
+    #
+    # @param value [UUIDTools::UUID, String, nil] value to be casted
+    #   to +UUIDTools::UUID+.
+    # @raise [ArgumentError] argument cannot be casted to UUIDTools::UUID.
+    # @return [UUIDTools::UUID, nil] respective UUID instance or nil.
+    def cast_to_uuid(value)
+      case value
+      when UUIDTools::UUID, nil
+        value
+      when String
+        parse_uuid_string(value)
+      else
+        m = "UUID, String, or nil required, but '#{value.inspect}' was given"
+        raise ArgumentError, m
+      end
+    end
+
+    # Casts UUID to binary and quotes it, so that it can be used in SQL query
+    # interpolation.
+    #
+    #   model.where("id = ?", ActiveID.quote_as_binary(some_uuid))
+    #
+    # This method is unable to determine the correct attribute type.
+    # It always casts UUIDs to their binary form, which may be unwanted in some
+    # contexts, i.e. in case of UUIDs which are meant to be serialized as
+    # strings or as Postgres' native +UUID+ data type.  Due to this fact,
+    # it is generally recommended to avoid SQL query interpolation if possible.
+    #
+    # @param value [UUIDTools::UUID, String, nil] UUID or its representation
+    #   to be quoted.
+    # @raise [ArgumentError] see cast_to_uuid.
+    # @return [::ActiveRecord::Type::Binary::Data, nil] a binary value which
+    #   can be used in SQL queries.
+    def quote_as_binary(value)
+      uuid = cast_to_uuid(value)
+      uuid && ::ActiveRecord::Type::Binary::Data.new(uuid.raw)
+    end
+
+    # :nodoc:
+    # Unfortunately, UUIDTools is missing some validations, hence we have to do
+    # them here.
+    #
+    # TODO More validations, see specs.
+    def self.parse_uuid_string(str)
+      case str.size
+      when 16 then uuid = UUIDTools::UUID.parse_raw(str)
+      when 32 then uuid = UUIDTools::UUID.parse_hexdigest(str)
+      when 36 then uuid = UUIDTools::UUID.parse(str)
+      end
+    ensure
+      unless uuid # Guard for both exceptions and nil return values
+        raise ArgumentError, "Expected string which is 16, 32, or 36 " +
+          "characters long, and represents UUID, but #{str.inspect} was given"
+      end
+    end
+
+    private_class_method :parse_uuid_string
+  end
+end