sbf-dm-types 1.3.0.beta

data/lib/dm-types/support/dirty_minder.rb

@@ -0,0 +1,168 @@
+# Approach
+#
+# We need to detect whether or not the underlying Hash or Array changed and
+# update the dirty-ness of the encapsulating Resource accordingly (so that it
+# will actually save).
+#
+# DM's state-tracking code only triggers dirty-ness by comparing the new value
+# against the instance's Property's current value.  WRT mutation, we have to
+# choose one of the following approaches:
+#
+#   (1) mutate a copy ("after"), then invoke the Resource assignment and State
+#       tracking
+#
+#   (2) create a copy ("before"), mutate self ("after"), then invoke the
+#       Resource assignment and State tracking
+#
+# (1) seemed simpler at first, but it required additional steps to alias the
+# original (pre-hooked) methods before overriding them (so they could be invoked
+# externally, ala self.clone.send("orig_...")), and more importantly it resulted
+# in any external references keeping their old value (instead of getting the
+# new), like so:
+#
+#   copy = instance.json
+#   copy[:some] = :value
+#   instance.json[:some] == :value
+#    => true
+#   copy[:some] == :value
+#    => false  # fk!
+#
+# In order to do (2) and still have State tracking trigger normally, we need to
+# ensure the Property has a different value other than self when the State
+# tracking does the comparison.  This equates to setting the Property directly
+# to the "before" value (a clone and thus a different object/value) before
+# invoking the Resource Property/attribute assignment.
+#
+# The cloning of any value might sound expensive, but it's identical in cost to
+# what you already had to do: assign a cloned copy in order to trigger
+# dirty-ness (e.g. ::DataMapper::Property::Json):
+#
+#     model.json = model.json.merge({:some=>:value})
+#
+# Hooking Core Classes
+#
+# We want to hook certain methods on Hash and Array to trigger dirty-ness in the
+# resource.  However, because these are core classes, they are individually
+# mapped to C primitives and thus cannot be hooked through #send/#__send__.  We
+# have to override each method, but we don't want to write a lot of code.
+#
+# Minimally Invasive
+#
+# We also want to extend behaviour of existing class instances instead of
+# impersonating/delegating from a proxy class of our own, or overriding a global
+# class behaviour.  This is the most flexible approach and least prone to error,
+# since it leaves open the option for consumers to proxy or override global
+# classes, and is less likely to interfere with method_missing/etc shenanigans.
+#
+# Nested Object Mutations
+#
+# Since we use {Array,Hash}#hash to compare before & after, and #hash accounts
+# for/traverses nested structures, no "deep" inspection logic is technically
+# necessary.  However, Resource#dirty? only queries a cache of dirtied
+# attributes, whose own population strategy is to hook assignment (instead of
+# interrogating properties on demand).  So the approach is still limited to
+# top-level mutators.
+#
+# Maybe consider optional "advisory" Property#dirty? method for Resource#dirty?
+# that custom properties could use for this purpose.
+#
+# TODO: add support for detecting mutations in nested objects, but we can't
+#       catch the assignment from here (yet?).
+# TODO: ensure we covered all indirectly-mutable classes that DM uses underneath
+#       a property type
+# TODO: figure out how to hook core class methods on RBX (which do use #send)
+
+module DataMapper
+  class Property
+    module DirtyMinder
+
+      module Hooker
+        MUTATION_METHODS = {
+          ::Array => %w(
+            []= push << shift pop insert unshift delete
+            delete_at replace fill clear
+            slice! reverse! rotate! compact! flatten! uniq!
+            collect! map! sort! sort_by! reject! delete_if!
+            select! shuffle!
+          ).select { |meth| ::Array.instance_methods.any? { |m| m.to_s == meth } },
+
+          ::Hash => %w(
+            []= store delete delete_if replace update
+            delete rehash shift clear
+            merge! reject! select!
+          ).select { |meth| ::Hash.instance_methods.any? { |m| m.to_s == meth } },
+        }.freeze
+
+        def self.extended(instance)
+          # FIXME: DirtyMinder is currently unsupported on RBX, because unlike
+          # the other supported Rubies, RBX core class (e.g. Array, Hash)
+          # methods use #send().  In other words, the other Rubies don't use
+          # #send() (they map directly to their C functions).
+          #
+          # The current methodology takes advantage of this by using #send() to
+          # forward method invocations we've hooked.  Supporting RBX will
+          # require finding another way, possibly for all Rubies.  In the
+          # meantime, something is better than nothing.
+          return if defined?(RUBY_ENGINE) and RUBY_ENGINE == 'rbx'
+
+          return unless (type = MUTATION_METHODS.keys.find { |k| instance.is_a?(k) })
+
+          instance.extend const_get("#{type}Hooks")
+        end
+
+        MUTATION_METHODS.each do |klass, methods|
+          methods.each do |meth|
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              module #{klass}Hooks
+                def #{meth}(*)
+                  before = self.clone
+                  ret    = super
+                  after  = self
+
+                  # If the hashes aren't equivalent then we know the Resource
+                  # should be dirty.  However because we mutated self, normal
+                  # State tracking will never trigger, because it will compare the
+                  # new value - self - to the Resource's existing property value -
+                  # which is also self.
+                  #
+                  # The solution is to drop 1 level beneath Resource State
+                  # tracking and set the value of the property directly to the
+                  # previous value (a different object now, because it's a clone).
+                  # Then trigger the State tracking like normal.
+                  if before.hash != after.hash
+                    @property.set(@resource, before)
+                    @resource.attribute_set(@property.name, after)
+                  end
+
+                  ret
+                end
+              end
+            RUBY
+          end
+        end
+
+        def track(resource, property)
+          @resource, @property = resource, property
+        end
+      end
+
+      # Catch any direct assignment (#set), and any Resource#reload (set!).
+      def set!(resource, value)
+        # Do not extend non observed value classes
+        if Hooker::MUTATION_METHODS.keys.detect { |klass| value.is_a?(klass) }
+          hook_value(resource, value) unless value.is_a? Hooker
+        end
+        super
+      end
+
+      private
+
+      def hook_value(resource, value)
+        return if value.is_a? Hooker
+
+        value.extend Hooker
+        value.track(resource, self)
+      end
+    end
+  end
+end

data/lib/dm-types/support/flags.rb

@@ -0,0 +1,41 @@
+module DataMapper
+  class Property
+    module Flags
+      def self.included(base)
+        base.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          extend DataMapper::Property::Flags::ClassMethods
+
+          accept_options :flags
+          attr_reader :flag_map
+
+          class << self
+            attr_accessor :generated_classes
+          end
+
+          self.generated_classes = {}
+        RUBY
+      end
+
+      def custom?
+        true
+      end
+
+      module ClassMethods
+        # TODO: document
+        # @api public
+        def [](*values)
+          if (klass = generated_classes[values.flatten])
+            klass
+          else
+            klass = ::Class.new(self)
+            klass.flags(values)
+
+            generated_classes[values.flatten] = klass
+
+            klass
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dm-types/uri.rb

@@ -0,0 +1,27 @@
+require 'addressable/uri'
+require 'dm-core'
+
+module DataMapper
+  class Property
+    class URI < String
+      load_as Addressable::URI
+
+      # Maximum length chosen based on recommendation:
+      # http://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-an-url
+      length 2083
+
+      def load(value)
+        uri = Addressable::URI.parse(value)
+        uri.normalize unless uri.nil?
+      end
+
+      def dump(value)
+        value.to_str unless value.nil?
+      end
+
+      def typecast(value)
+        load(value) unless value.nil?
+      end
+    end # class URI
+  end # class Property
+end # module DataMapper

data/lib/dm-types/uuid.rb

@@ -0,0 +1,64 @@
+require 'dm-core'
+require 'uuidtools'  # must be ~>2.0
+
+module DataMapper
+  class Property
+    # UUID Type
+    # First run at this, because I need it. A few caveats:
+    #  * Only works on postgres, using the built-in native uuid type.
+    #    To make it work in mysql, you'll have to add a typemap entry to
+    #    the mysql_adapter. I think. I don't have mysql handy, so I'm
+    #    not going to try. For SQLite, this will have to inherit from the
+    #    String primitive
+    #  * Won't accept a random default, because of the namespace clash
+    #    between this and the UUIDtools gem. Also can't set the default
+    #    type to UUID() (postgres-contrib's native generator) and
+    #    automigrate, because auto_migrate! tries to make it a string "UUID()"
+    # Feel free to enchance this, and delete these caveats when they're fixed.
+    #
+    #  -- Rando Sept 25, 08
+    #
+    # Actually, setting the primitive to "UUID" is not neccessary and causes
+    # a segfault when trying to query uuid's from the database.  The primitive
+    # should be a class which has been added to the do driver you are using.
+    # Also, it's only neccessary to add a class to the do drivers to use as a
+    # primitive when a value cannot be represented as a string.  A uuid can be
+    # represented as a string, so setting the primitive to String ensures that
+    # the value argument is a String containing the uuid in string form.
+    #
+    # <strike>It is still neccessary to add the UUID entry to the type map for
+    # each different adapter with their respective database primitive.</strike>
+    #
+    # The method that generates the SQL schema from the typemap currently
+    # ignores the size attribute from the type map if the primitive type
+    # is String.  The causes the generated SQL statement to contain a size for
+    # a UUID column (e.g. id UUID(50)), which causes a syntax error in postgres.
+    # Until this is resolved, you will have to manually change the column type
+    # to UUID in a migration, if you want to use postgres' built in UUID type.
+    #
+    #  -- benburkert Nov 15, 08
+    #
+    class UUID < String
+      load_as UUIDTools::UUID
+
+      length 36
+
+      def dump(value)
+        value.to_s unless value.nil?
+      end
+
+      def load(value)
+        if value_loaded?(value)
+          value
+        elsif !value.nil?
+          UUIDTools::UUID.parse(value)
+        end
+      end
+
+      def typecast(value)
+        return if value.nil?
+        load(value)
+      end
+    end
+  end
+end

data/lib/dm-types/version.rb

@@ -0,0 +1,5 @@
+module DataMapper
+  module Types
+    VERSION = '1.3.0.beta'
+  end
+end

data/lib/dm-types/yaml.rb

@@ -0,0 +1,39 @@
+require 'yaml'
+require 'safe_yaml'
+require 'dm-core'
+require 'dm-types/support/dirty_minder'
+
+module DataMapper
+  class Property
+    class Yaml < Text
+      load_as ::Object
+
+      def load(value)
+        if value.nil?
+          nil
+        elsif value.is_a?(::String)
+          ::YAML.safe_load(value)
+        else
+          raise ArgumentError, '+value+ of a property of YAML type must be nil or a String'
+        end
+      end
+
+      def dump(value)
+        if value.nil?
+          nil
+        elsif value.is_a?(::String) && value =~ /^---/
+          value
+        else
+          ::YAML.dump(value)
+        end
+      end
+
+      def typecast(value)
+        value
+      end
+
+      include ::DataMapper::Property::DirtyMinder
+
+    end # class Yaml
+  end # class Property
+end # module DataMapper

data/lib/dm-types.rb

@@ -0,0 +1,23 @@
+require 'dm-core'
+
+module DataMapper
+  class Property
+    autoload :CommaSeparatedList, 'dm-types/comma_separated_list'
+    autoload :Csv,                'dm-types/csv'
+    autoload :BCryptHash,         'dm-types/bcrypt_hash'
+    autoload :Enum,               'dm-types/enum'
+    autoload :EpochTime,          'dm-types/epoch_time'
+    autoload :FilePath,           'dm-types/file_path'
+    autoload :Flag,               'dm-types/flag'
+    autoload :IPAddress,          'dm-types/ip_address'
+    autoload :Json,               'dm-types/json'
+    autoload :Regexp,             'dm-types/regexp'
+    autoload :ParanoidBoolean,    'dm-types/paranoid_boolean'
+    autoload :ParanoidDateTime,   'dm-types/paranoid_datetime'
+    autoload :Slug,               'dm-types/slug'
+    autoload :UUID,               'dm-types/uuid'
+    autoload :URI,                'dm-types/uri'
+    autoload :Yaml,               'dm-types/yaml'
+    autoload :APIKey,             'dm-types/api_key'
+  end
+end

data/spec/fixtures/api_user.rb

@@ -0,0 +1,14 @@
+module DataMapper
+  module TypesFixtures
+    class APIUser
+
+      include DataMapper::Resource
+
+      property :id, Serial
+
+      property :name, String
+
+      property :api_key, APIKey
+    end
+  end
+end

data/spec/fixtures/article.rb

@@ -0,0 +1,35 @@
+module DataMapper
+  module TypesFixtures
+
+    class Article
+      #
+      # Behaviors
+      #
+
+      include ::DataMapper::Resource
+
+      #
+      # Properties
+      #
+
+      property :id,         Serial
+
+      property :title,      String, :length => 255
+      property :body,       Text
+
+      property :created_at,   DateTime
+      property :updated_at,   DateTime
+      property :published_at, DateTime
+
+      property :slug, Slug
+
+      #
+      # Hooks
+      #
+
+      before :valid? do
+        self.slug = self.title
+      end
+    end # Article
+  end
+end

data/spec/fixtures/bookmark.rb

@@ -0,0 +1,23 @@
+module DataMapper
+  module TypesFixtures
+
+    class Bookmark
+      #
+      # Behaviors
+      #
+
+      include ::DataMapper::Resource
+
+      #
+      # Properties
+      #
+
+      property :id, Serial
+
+      property :title,  String, :length => 255
+      property :shared, Boolean
+      property :uri,    URI
+      property :tags,   Yaml
+    end # Bookmark
+  end
+end

data/spec/fixtures/invention.rb

@@ -0,0 +1,7 @@
+module DataMapper
+  module TypesFixtures
+
+    Invention = Struct.new(:name)
+
+  end
+end

data/spec/fixtures/network_node.rb

@@ -0,0 +1,36 @@
+module DataMapper
+  module TypesFixtures
+
+    class NetworkNode
+      #
+      # Behaviors
+      #
+
+      include ::DataMapper::Resource
+
+      #
+      # Properties
+      #
+
+      property :id,               Serial
+      property :ip_address,       IPAddress
+      property :cidr_subnet_bits, Integer
+      property :node_uuid,        UUID
+
+      #
+      # API
+      #
+
+      alias_method :uuid,  :node_uuid
+      alias_method :uuid=, :node_uuid=
+
+      def runs_ipv6?
+        self.ip_address.ipv6?
+      end
+
+      def runs_ipv4?
+        self.ip_address.ipv4?
+      end
+    end # NetworkNode
+  end # TypesFixtures
+end # DataMapper

data/spec/fixtures/person.rb

@@ -0,0 +1,25 @@
+module DataMapper
+  module TypesFixtures
+    class Person
+      #
+      # Behaviors
+      #
+
+      include DataMapper::Resource
+
+      #
+      # Properties
+      #
+
+      property :id,         Serial
+      property :name,       String
+      property :positions,  Json
+      property :inventions, Yaml
+      property :birthday,   EpochTime
+
+      property :interests, CommaSeparatedList
+
+      property :password, BCryptHash
+    end
+  end
+end

data/spec/fixtures/software_package.rb

@@ -0,0 +1,33 @@
+module DataMapper
+  module TypesFixtures
+
+    class SoftwarePackage
+      #
+      # Behaviors
+      #
+
+      include ::DataMapper::Resource
+
+      #
+      # Properties
+      #
+
+      property :id, Serial
+      without_auto_validations do
+        property :node_number, Integer, :index => true
+
+        property :source_path,      FilePath
+        property :destination_path, FilePath
+
+        property :product,     String
+        property :version,     String
+        property :released_at, DateTime
+
+        property :security_update,  Boolean
+
+        property :installed_at,     DateTime
+        property :installed_by,     String
+      end
+    end # SoftwarePackage
+  end # TypesFixtures
+end # DataMapper

data/spec/fixtures/ticket.rb

@@ -0,0 +1,21 @@
+module DataMapper
+  module TypesFixtures
+    class Ticket
+      #
+      # Behaviors
+      #
+
+      include DataMapper::Resource
+      include DataMapper::Validations
+
+      #
+      # Properties
+      #
+
+      property :id,     Serial
+      property :title,  String, :length => 255
+      property :body,   Text
+      property :status, Enum[:unconfirmed, :confirmed, :assigned, :resolved, :not_applicable]
+    end # Ticket
+  end
+end

data/spec/fixtures/tshirt.rb

@@ -0,0 +1,24 @@
+module DataMapper
+  module TypesFixtures
+
+      class TShirt
+        #
+        # Behaviors
+        #
+
+        include ::DataMapper::Resource
+
+        #
+        # Properties
+        #
+
+        property :id,          Serial
+        property :writing,     String
+        property :has_picture, Boolean, :default => false
+        property :picture,     Enum[:octocat, :fork_you, :git_down]
+
+        property :color, Enum[:white, :black, :red, :orange, :yellow, :green, :cyan, :blue, :purple]
+        property :size,  Flag[:xs, :small, :medium, :large, :xl, :xxl], :default => [:xs]
+      end # Shirt
+    end # TypesFixtures
+end # DataMapper

data/spec/integration/api_key_spec.rb

@@ -0,0 +1,27 @@
+require_relative '../spec_helper'
+
+try_spec do
+  require_relative '../fixtures/api_user'
+
+  describe DataMapper::TypesFixtures::APIUser do
+    supported_by :all do
+      subject { described_class.new(:name => 'alice') }
+
+      let(:original_api_key) { subject.api_key }
+
+      it "has a default value" do
+        expect(original_api_key).not_to be_nil
+      end
+
+      it "preserves the default value" do
+        expect(subject.api_key).to eq original_api_key
+      end
+
+      it "generates unique API Keys for each resource" do
+        other_resource = described_class.new(:name => 'eve')
+
+        expect(other_resource.api_key).not_to eq original_api_key
+      end
+    end
+  end
+end

data/spec/integration/bcrypt_hash_spec.rb

@@ -0,0 +1,47 @@
+require_relative '../spec_helper'
+
+try_spec do
+
+  require_relative '../fixtures/person'
+
+  describe DataMapper::TypesFixtures::Person do
+    supported_by :all do
+      before :all  do
+        @resource  = DataMapper::TypesFixtures::Person.create(:password => 'DataMapper R0cks!')
+        DataMapper::TypesFixtures::Person.create(:password => 'password1')
+
+        @people = DataMapper::TypesFixtures::Person.all
+        @resource.reload
+      end
+
+      it 'persists the password on initial save' do
+        expect(@resource.password).to eq 'DataMapper R0cks!'
+        expect(@people.last.password).to eq 'password1'
+      end
+
+      it 'recalculates password hash on attribute update' do
+        @resource.attribute_set(:password, 'bcryptic obscure')
+        @resource.save
+
+        @resource.reload
+        expect(@resource.password).to eq 'bcryptic obscure'
+        expect(@resource.password).not_to eq 'DataMapper R0cks!'
+      end
+
+      it 'does not change password value on reload' do
+        resource = @people.last
+        original = resource.password.to_s
+        resource.reload
+        expect(resource.password.to_s).to eq original
+      end
+
+      it 'uses cost of BCrypt::Engine::DEFAULT_COST' do
+        expect(@resource.password.cost).to eq BCrypt::Engine::DEFAULT_COST
+      end
+
+      it 'allows Bcrypt::Password#hash to be an Integer' do
+        expect(@resource.password.hash).to be_kind_of(Integer)
+      end
+    end
+  end
+end