objectid_columns 1.0.0

data/lib/objectid_columns/extensions.rb

@@ -0,0 +1,40 @@
+# This file adds very useful convenience methods to certain classes:
+
+# To each of the BSON classes, we add:
+#
+# * #to_binary, which returns a String containing a pure-binary (12-byte) representation of the ObjectId; and
+# * #to_bson_id, which simply returns +self+ -- this is so we can call this method on any object passed in where we're
+#   expecting an ObjectId, and, if you're already supplying an ObjectId object, it will just work.
+ObjectidColumns.available_objectid_columns_bson_classes.each do |klass|
+  klass.class_eval do
+    def to_binary
+      [ to_s ].pack("H*")
+    end
+
+    def to_bson_id
+      self
+    end
+  end
+end
+
+# To String, we add #to_bson_id. This method knows how to convert a String that is in either the hex or pure-binary
+# forms to an actual ObjectId object. Note that we use the method ObjectidColumns.construct_objectid to actually create
+# the object; this way, it will follow any preference for exactly what BSON class to use that's set there.
+#
+# If your String is in binary form, it must have its encoding set to Encoding::BINARY (which is aliased to
+# Encoding::ASCII_8BIT); if it's not in this encoding, it may well be coming from a source that doesn't support
+# transparent binary data (for example, UTF-8 doesn't -- certain byte combinations are illegal in UTF-8 and will cause
+# string manipulation to fail), which is a real problem.
+String.class_eval do
+  BSON_HEX_ID_REGEX = /^[0-9a-f]{24}$/i
+
+  def to_bson_id
+    if self =~ BSON_HEX_ID_REGEX
+      ObjectidColumns.construct_objectid(self)
+    elsif length == 12 && ((! respond_to?(:encoding)) || (encoding == Encoding::BINARY)) # :respond_to? is for Ruby 1.8.7 support
+      ObjectidColumns.construct_objectid(unpack("H*").first)
+    else
+      raise ArgumentError, "#{inspect} does not seem to be a valid BSON ID; it is in neither the valid hex (exactly 24 hex characters, any encoding) nor the valid binary (12 characters, binary/ASCII-8BIT encoding) form"
+    end
+  end
+end

data/lib/objectid_columns/has_objectid_columns.rb

@@ -0,0 +1,47 @@
+require 'active_support'
+require 'active_support/core_ext/object'
+require 'objectid_columns/objectid_columns_manager'
+
+module ObjectidColumns
+  # This module gets mixed into an ActiveRecord class when you say +has_objectid_column(s)+ or
+  # +has_objectid_primary_key+. It delegates everything it does to the ObjectidColumnsManager; we do it this way so
+  # that we can define all kinds of helper methods on the ObjectidColumnsManager without polluting the method
+  # namespace on the actual ActiveRecord class.
+  module HasObjectidColumns
+    extend ActiveSupport::Concern
+
+    # Reads the current value of the given +column_name+ (which must be an ObjectId column) as an ObjectId object.
+    def read_objectid_column(column_name)
+      self.class.objectid_columns_manager.read_objectid_column(self, column_name)
+    end
+
+    # Writes a new value to the given +column_name+ (which must be an ObjectId column), accepting a String (in either
+    # hex or binary formats) or an ObjectId object, and transforming it to whatever storage format is correct for
+    # that column.
+    def write_objectid_column(column_name, new_value)
+      self.class.objectid_columns_manager.write_objectid_column(self, column_name, new_value)
+    end
+
+    # Called as a +before_create+ hook, if (and only if) this class has declared +has_objectid_primary_key+ -- sets
+    # the primary key to a newly-generated ObjectId, unless it has one already.
+    def assign_objectid_primary_key
+      self.id ||= ObjectidColumns.new_objectid
+    end
+
+    module ClassMethods
+      # Does this class have any ObjectId columns? It does if this module has been included, since it only gets included
+      # if you declare an ObjectId column.
+      def has_objectid_columns?
+        true
+      end
+
+      # Delegate all of the interesting work to the ObjectidColumnsManager.
+      delegate :has_objectid_columns, :has_objectid_column, :has_objectid_primary_key,
+        :translate_objectid_query_pair, :to => :objectid_columns_manager
+
+      def objectid_columns_manager
+        @objectid_columns_manager ||= ::ObjectidColumns::ObjectidColumnsManager.new(self)
+      end
+    end
+  end
+end

data/lib/objectid_columns/objectid_columns_manager.rb

@@ -0,0 +1,298 @@
+require 'objectid_columns/dynamic_methods_module'
+
+module ObjectidColumns
+  # The ObjectidColumnsManager does all the real work of the ObjectidColumns gem, in many ways -- it takes care of
+  # reading ObjectId values and transforming them to objects, transforming supplied data to the right format when
+  # writing them, handling primary-key definitions and queries.
+  #
+  # This is a separate class, rather than being mixed into the actual ActiveRecord class, so that we can add methods
+  # and define constants here without polluting the namespace of the underlying class.
+  class ObjectidColumnsManager
+    # NOTE: These constants are used in a metaprogrammed fashion in #has_objectid_columns, below. If you rename them,
+    # you must change that, too.
+    BINARY_OBJECTID_LENGTH = 12
+    STRING_OBJECTID_LENGTH = 24
+
+    # Creates a new instance. There should only ever be a single instance for a given ActiveRecord class, accessible
+    # via ObjectidColumns::HasObjectidColumns.objectid_columns_manager.
+    def initialize(active_record_class)
+      raise ArgumentError, "You must supply a Class, not: #{active_record_class.inspect}" unless active_record_class.kind_of?(Class)
+      raise ArgumentError, "You must supply a Class that's a descendant of ActiveRecord::Base, not: #{active_record_class.inspect}" unless superclasses(active_record_class).include?(::ActiveRecord::Base)
+
+      @active_record_class = active_record_class
+      @oid_columns = { }
+
+      # We use a DynamicMethodsModule to add our magic to the target ActiveRecord class, rather than just defining
+      # methods directly on the class, for a number of very good reasons -- see the class comment on
+      # DynamicMethodsModule for more information.
+      @dynamic_methods_module = ObjectidColumns::DynamicMethodsModule.new(active_record_class, :ObjectidColumnsDynamicMethods)
+    end
+
+    # Declares that this class is using an ObjectId as its primary key. Ordinarily, this requires no arguments;
+    # however, if your primary key is not named +id+ and you have not yet told ActiveRecord this (using
+    # <tt>self.primary_key = :foo</tt>), then you must pass the name of the primary-key column.
+    #
+    # Note that, unlike normal database-generated primary keys, this will cause us to auto-generate an ObjectId
+    # primary key value for a new record just before saving it to the database (ActiveRecord's +before_create hook).
+    # ObjectIds are safe to generate client-side, and very difficult to properly generate server-side in a relational
+    # database. However, we will respect (and not overwrite) any primary key already assigned to the record before it's
+    # saved, so if you want to assign your own ObjectId primary keys, you can.
+    def has_objectid_primary_key(primary_key_name = nil)
+      # The Symbol-vs.-String distinction is critical when dealing with old versions of ActiveRecord; for example, if
+      # you say <tt>self.primary_key = :foo</tt> (instead of <tt>self.primary_key = 'foo'</tt>) to older versions of
+      # ActiveRecord, you can end up with some seriously weird errors later (like models trying to save themselves with
+      # _both_ a +:foo+ and a +'foo'+ attribute -- ick!). Boo, AR.
+      primary_key_name = primary_key_name.to_s if primary_key_name
+      pk = active_record_class.primary_key
+
+      # Make sure we know what the primary key is!
+      if (! pk) && (! primary_key_name)
+        raise ArgumentError, "Class #{active_record_class.name} has no primary key set, and you haven't supplied one to .has_objectid_primary_key. Either set one before this call (using self.primary_key = :foo), or supply one to this call (has_objectid_primary_key :foo) and we'll set it for you."
+      end
+
+      pk = pk.to_s if pk
+
+      # Initially, this was a simple +||=+ statement. However, older versions of ActiveRecord will return the string or
+      # symbol +id+ for the primary key if you haven't set an explicit primary key, even if there is no such column on
+      # the underlying table. Again, ick.
+      if (! pk) || (primary_key_name && pk.to_s != primary_key_name.to_s)
+        active_record_class.primary_key = pk = primary_key_name
+      end
+
+      # In case someone is using composite_primary_keys (http://compositekeys.rubyforge.org/).
+      raise "You can't have an ObjectId primary key that's not a String or Symbol: #{pk.inspect}" unless pk.kind_of?(String) || pk.kind_of?(Symbol)
+
+      # Declare our primary-key column as an ObjectId column.
+      has_objectid_column pk
+
+      # If it's not called just "id", we need to explicitly define an "id" method that correctly reads from and writes
+      # to the table.
+      unless pk.to_s == 'id'
+        p = pk
+        dynamic_methods_module.define_method("id") { read_objectid_column(p) }
+        dynamic_methods_module.define_method("id=") { |new_value| write_objectid_column(p, new_value) }
+      end
+
+      # Allow us to autogenerate the primary key, if needed, on save.
+      active_record_class.send(:before_create, :assign_objectid_primary_key)
+
+      # Override a couple of methods that, if you're using an ObjectId column as your primary key, need overriding. ;)
+      [ :find, :find_by_id ].each do |class_method_name|
+        @dynamic_methods_module.define_class_method(class_method_name) do |*args, &block|
+          if args.length == 1 && args[0].kind_of?(String) || ObjectidColumns.is_valid_bson_object?(args[0]) || args[0].kind_of?(Array)
+            args[0] = if args[0].kind_of?(Array)
+              args[0].map { |x| objectid_columns_manager.to_valid_value_for_column(primary_key, x) if x }
+            else
+              objectid_columns_manager.to_valid_value_for_column(primary_key, args[0]) if args[0]
+            end
+
+            super(args[0], &block)
+          else
+            super(*args, &block)
+          end
+        end
+      end
+    end
+
+    # Declares one or more columns as containing ObjectId values. After this call, they can be written using a String
+    # in hex or binary formats, or an ObjectId object; they will return ObjectId objects for values, and can be queried
+    # using any of the above (as long as you use the <tt>where(:foo_oid => ...)</tt> Hash-style syntax).
+    #
+    # If you don't pass in any column names, this will look for columns that end in +_oid+ and assume those are
+    # ObjectId columns.
+    def has_objectid_columns(*columns)
+      return unless active_record_class.table_exists?
+
+      # Autodetect columns ending in +_oid+ if needed
+      columns = autodetect_columns if columns.length == 0
+
+      columns = columns.map { |c| c.to_s.strip.downcase.to_sym }
+      columns.each do |column_name|
+        # Go fetch the column object from the ActiveRecord class, and make sure it's present and of the right type.
+        column_object = active_record_class.columns.detect { |c| c.name.to_s == column_name.to_s }
+
+        unless column_object
+          raise ArgumentError, "#{active_record_class.name} doesn't seem to have a column named #{column_name.inspect} that we could make an ObjectId column; did you misspell it? It has columns: #{active_record_class.columns.map(&:name).inspect}"
+        end
+
+        unless [ :string, :binary ].include?(column_object.type)
+          raise ArgumentError, "#{active_record_class.name} has a column named #{column_name.inspect}, but it is of type #{column_object.type.inspect}; we can only make ObjectId columns out of :string or :binary columns"
+        end
+
+        # Is the column long enough to contain the data we'll need to put in it?
+        required_length = self.class.const_get("#{column_object.type.to_s.upcase}_OBJECTID_LENGTH")
+        # The ||= is in case there's no limit on the column at all -- for example, PostgreSQL +bytea+ columns
+        # behave this way.
+        unless (column_object.limit || required_length + 1) >= required_length
+          raise ArgumentError, "#{active_record_class.name} has a column named #{column_name.inspect} of type #{column_object.type.inspect}, but it is of length #{column_object.limit}, which is too short to contain an ObjectId of this format; it must be of length at least #{required_length}"
+        end
+
+        # Define reader and writer methods that just call through to ObjectidColumns::HasObjectidColumns (which, in
+        # turn, just delegates the call back to this object -- the #read_objectid_column method below; the one on
+        # HasObjectidColumns just passes through the model object itself).
+        cn = column_name
+        dynamic_methods_module.define_method(column_name) do
+          read_objectid_column(cn)
+        end
+
+        dynamic_methods_module.define_method("#{column_name}=") do |x|
+          write_objectid_column(cn, x)
+        end
+
+        # Store away the fact that we've done this.
+        @oid_columns[column_name] = column_object.type
+      end
+    end
+
+    # Called from ObjectidColumns::HasObjectidColumns#read_objectid_column -- given a model and a column name (which
+    # must be an ObjectId column), returns the data in it, as an ObjectId.
+    def read_objectid_column(model, column_name)
+      column_name = column_name.to_s
+      value = model[column_name]
+      return value unless value # in case it's nil
+
+      # If it's not nil, the database should always be giving us back a String...
+      unless value.kind_of?(String)
+        raise "When trying to read the ObjectId column #{column_name.inspect} on #{inspect},  we got the following data from the database; we expected a String: #{value.inspect}"
+      end
+
+      # ugh...ActiveRecord 3.1.x can return this in certain circumstances
+      return nil if value.length == 0
+
+      # In many databases, if you have a column that is, _e.g._, BINARY(16), and you only store twelve bytes in it,
+      # you get back all 16 anyway, with 0x00 bytes at the end. Converting this to an ObjectId will fail, so we make
+      # sure we chop those bytes off. (Note that while String#strip will, in fact, remove these bytes too, it is not
+      # safe: if the ObjectId itself ends in one or more 0x00 bytes, then these will get incorrectly removed.)
+      case objectid_column_type(column_name)
+      when :binary then value = value[0..(BINARY_OBJECTID_LENGTH - 1)]
+      when :string then value = value[0..(STRING_OBJECTID_LENGTH - 1)]
+      else unknown_type(type)
+      end
+
+      # +lib/objectid_columns/extensions.rb+ adds this method to String.
+      value.to_bson_id
+    end
+
+    # Called from ObjectidColumns::HasObjectidColumns#write_objectid_column -- given a model, a column name (which must
+    # be an ObjectId column) and a new value, stores that value in the column.
+    def write_objectid_column(model, column_name, new_value)
+      column_name = column_name.to_s
+      if (! new_value)
+        model[column_name] = new_value
+      elsif new_value.respond_to?(:to_bson_id)
+        model[column_name] = to_valid_value_for_column(column_name, new_value)
+      else
+        raise ArgumentError, "When trying to write the ObjectId column #{column_name.inspect} on #{inspect}, we were passed the following value, which doesn't seem to be a valid BSON ID in any format: #{new_value.inspect}"
+      end
+    end
+
+    alias_method :has_objectid_column, :has_objectid_columns
+
+    # Given a value for an ObjectId column -- could be a String in either hex or binary formats, or an
+    # ObjectId object -- returns a String of the correct type for the given column (_i.e._, either the binary or hex
+    # String representation of an ObjectId, depending on the type of the underlying column).
+    def to_valid_value_for_column(column_name, value)
+      out = value.to_bson_id
+      unless ObjectidColumns.is_valid_bson_object?(out)
+        raise "We called #to_bson_id on #{value.inspect}, but it returned this, which is not a BSON ID object: #{out.inspect}"
+      end
+
+      case objectid_column_type(column_name)
+      when :binary then out = out.to_binary
+      when :string then out = out.to_s
+      else unknown_type(type)
+      end
+
+      out
+    end
+
+    # Given a key in a Hash supplied to +where+ for the given ActiveRecord class, returns a two-element Array
+    # consisting of the key and the proper value we should actually use to query on that column. If the key does not
+    # represent an ObjectID column, then this will just be exactly the data passed in; however, if it does represent
+    # an ObjectId column, then the value will be translated to whichever String format (binary or hex) that column is
+    # using.
+    #
+    # We use this in ObjectidColumns:;ActiveRecord::Relation#where to make the following work properly:
+    #
+    #     MyModel.where(:foo_oid => BSON::ObjectId('52ec126d78161f56d8000001'))
+    #
+    # This method is used to translate this to:
+    #
+    #     MyModel.where(:foo_oid => "52ec126d78161f56d8000001")
+    def translate_objectid_query_pair(query_key, query_value)
+      if (type = oid_columns[query_key.to_sym])
+
+        # Handle nil, false
+        if (! query_value)
+          [ query_key, query_value ]
+
+        # +lib/objectid_columns/extensions.rb+ adds String#to_bson_id
+        elsif query_value.respond_to?(:to_bson_id)
+          v = query_value.to_bson_id
+          v = case type
+          when :binary then v.to_binary
+          when :string then v.to_s
+          else unknown_type(type)
+          end
+          [ query_key, v ]
+
+        # Handle arrays of values
+        elsif query_value.kind_of?(Array)
+          array = query_value.map do |v|
+            translate_objectid_query_pair(query_key, v)[1]
+          end
+          [ query_key, array ]
+
+        # Um...what did you pass?
+        else
+          raise ArgumentError, "You're trying to constrain #{active_record_class.name} on column #{query_key.inspect}, which is an ObjectId column, but the value you passed, #{query_value.inspect}, is not a valid format for an ObjectId."
+        end
+      else
+        [ query_key, query_value ]
+      end
+    end
+
+    private
+    attr_reader :active_record_class, :dynamic_methods_module, :oid_columns
+
+    # Given the name of a column -- which must be an ObjectId column -- returns its type, either +:binary+ or
+    # +:string+.
+    def objectid_column_type(column_name)
+      out = oid_columns[column_name.to_sym]
+      raise "Something is horribly wrong; #{column_name.inspect} is not an ObjectId column -- we have: #{oid_columns.keys.inspect}" unless out
+      out
+    end
+
+    # Raises an exception -- used for +case+ statements where we switch on the type of the column. Useful so that if,
+    # in the future, we support a new column type, we won't forget to add a case for it in various places.
+    def unknown_type(type)
+      raise "Bug in ObjectidColumns in this method -- type #{type.inspect} does not have a case here."
+    end
+
+    # What's the entire superclass chain of the given class? Used in the constructor to make sure something is
+    # actually a descendant of ActiveRecord::Base.
+    def superclasses(klass)
+      out = [ ]
+      while (sc = klass.superclass)
+        out << sc
+        klass = sc
+      end
+      out
+    end
+
+    # If someone called +has_objectid_columns+ but didn't pass an argument, this method detects which columns we should
+    # automatically turn into ObjectId columns -- which means any columns ending in +_oid+, except for the primary key.
+    def autodetect_columns
+      out = active_record_class.columns.select { |c| c.name =~ /_oid$/i }.map(&:name).map(&:to_s)
+
+      # Make sure we never, ever automatically make the primary-key column an ObjectId column.
+      out -= [ active_record_class.primary_key ].compact.map(&:to_s)
+
+      unless out.length > 0
+        raise ArgumentError, "You didn't pass in the names of any ObjectId columns, and we couldn't find any columns ending in _oid to pick up automatically (primary key is always excluded). Either name some columns explicitly, or remove the has_objectid_columns call."
+      end
+
+      out
+    end
+  end
+end

data/lib/objectid_columns/version.rb

@@ -0,0 +1,4 @@
+# What's the current version of this gem?
+module ObjectidColumns
+  VERSION = "1.0.0"
+end

data/lib/objectid_columns.rb

@@ -0,0 +1,121 @@
+require "objectid_columns/version"
+require "objectid_columns/active_record/base"
+require "objectid_columns/active_record/relation"
+require "active_record"
+
+# This is the root module for ObjectidColumns. It contains largely just configuration and integration information;
+# all the real work is done in ObjectidColumns::ObjectidColumnsManager. ObjectidColumns gets its start through the
+# module ObjectidColumns::ActiveRecord::Base, which gets mixed into ::ActiveRecord::Base (below) and is where methods
+# like +has_objectid_columns+ are declared.
+module ObjectidColumns
+  class << self
+    # This is the set of classes we support for representing ObjectIds, as objects, themselves. BSON::ObjectId comes
+    # from the +bson+ gem, and Moped::BSON::ObjectId comes from the +moped+ gem.
+    #
+    # Note that this gem does not declare a dependency on either one of these gems, because we want you to be able to
+    # use either, and there's currently no way of expressing that explicitly. Instead,
+    # .available_objectid_columns_bson_classes, below, takes care of figuring out which ones are availble and loading
+    # them.
+    #
+    # Order is important here: when creating new ObjectId objects (such as when reading from an ObjectId column), we
+    # will prefer the earliest one of these classes that is actually defined. You can change this using
+    # .preferred_bson_class=, below.
+    #
+    #
+    # Any class added here has to obey the following constraints:
+    #
+    # * You can create a new instance from a hex string using .from_string(hex_string)
+    # * Calling #to_s on it returns a hexadecimal String of exactly 24 characters
+    #
+    # Both these objects currently do. If they change, or you want to introduce a new ObjectId representation class,
+    # a small amount of refactoring will be necessary.
+    SUPPORTED_OBJECTID_BSON_CLASS_NAMES = %w{BSON::ObjectId Moped::BSON::ObjectId}
+
+    # When we create a new ObjectId object (such as when reading from a column), what class should it be? If you have
+    # multiple classes loaded and you don't like this one, you can call .preferred_bson_class=, below.
+    def preferred_bson_class
+      @preferred_bson_class ||= available_objectid_columns_bson_classes.first
+    end
+
+    # Sets the preferred BSON class to the given class.
+    def preferred_bson_class=(bson_class)
+      unless SUPPORTED_OBJECTID_BSON_CLASS_NAMES.include?(bson_class.name)
+        raise ArgumentError, "ObjectidColumns does not support BSON class #{bson_class.name}; it supports: #{SUPPORTED_OBJECTID_BSON_CLASS_NAMES.inspect}"
+      end
+
+      @preferred_bson_class = bson_class
+    end
+
+    # Returns an array of Class objects -- of length at least 1, but potentially more than 1 -- of the various
+    # ObjectId classes we have available to use. Again, because we don't explicitly depend on the BSON gems
+    # (see above), this needs to take care of trying to load and require the gems in question, and fail gracefully
+    # if they're not present.
+    def available_objectid_columns_bson_classes
+      @available_objectid_columns_bson_classes ||= begin
+        # Try to load both gems, but don't fail if there are errors
+        %w{moped bson}.each do |require_name|
+          begin
+            gem require_name
+          rescue Gem::LoadError => le
+          end
+
+          begin
+            require require_name
+          rescue LoadError => le
+          end
+        end
+
+        # See which classes we have managed to load
+        defined_classes = SUPPORTED_OBJECTID_BSON_CLASS_NAMES.map do |name|
+          eval("if defined?(#{name}) then #{name} end")
+        end.compact
+
+        # Raise an error if we haven't loaded either
+        if defined_classes.length == 0
+          raise %{ObjectidColumns requires a library that implements an ObjectId class to be loaded; we support
+the following ObjectId classes: #{SUPPORTED_OBJECTID_BSON_CLASS_NAMES.join(", ")}.
+(These are from the 'bson' or 'moped' gems.) You seem to have neither one installed.
+
+Please add one of these gems to your project and try again. Usually, this just means
+adding this to your Gemfile:
+
+gem 'bson'
+
+(ObjectidColumns does not explicitly depend on either of these, because we want you
+to be able to choose whichever one you prefer.)}
+        end
+
+        defined_classes
+      end
+    end
+
+    # Is the given object a valid BSON ObjectId? This doesn't count Strings in any format -- only objects.
+    def is_valid_bson_object?(x)
+      available_objectid_columns_bson_classes.detect { |k| x.kind_of?(k) }
+    end
+
+    # Creates a new BSON ObjectId from the given String, which must be in the hexadecimal format.
+    def construct_objectid(hex_string)
+      preferred_bson_class.send(:from_string, hex_string)
+    end
+
+    # Creates a new BSON ObjectId, from scratch; this must return an ObjectId with a value, suitable for assigning
+    # to a newly-created row. We use this only if you've declared that your primary key column is an ObjectId, and
+    # then only if you're about to save a new row and it has no ID yet.
+    def new_objectid
+      preferred_bson_class.new
+    end
+  end
+end
+
+# Include the modules that add the initial methods to ActiveRecord::Base, like +has_objectid_columns+.
+::ActiveRecord::Base.class_eval do
+  include ::ObjectidColumns::ActiveRecord::Base
+end
+
+# This adds our patch to +#where+, so that queries will work properly (assuming you use Hash-style syntax).
+::ActiveRecord::Relation.class_eval do
+  include ::ObjectidColumns::ActiveRecord::Relation
+end
+
+require "objectid_columns/extensions"