mongoid_token 0.9.1 → 1.0.0

data/.gitignore

@@ -2,3 +2,4 @@
 .bundle
 Gemfile.lock
 pkg/*
+.DS_Store

data/Gemfile

@@ -4,11 +4,12 @@ source "http://rubygems.org"
 gemspec
 
 group :test do
+  gem 'activesupport', '~> 3.0'
   gem 'database_cleaner'
-  gem 'rspec'
+  gem 'rspec', '2.5.0'
   gem 'autotest'
   gem 'autotest-growl'
-  gem 'mongoid', '~> 2.0'
+  gem 'mongoid', '2.0.0'
   gem 'bson_ext'
   gem 'mongoid-rspec'
 end

data/README.md

@@ -17,7 +17,7 @@ Into something more like this:
 
 In your gemfile, add:
 
-    gem 'mongoid_token', '~. 0.9.0'
+    gem 'mongoid_token', '~> 1.0.0'
 
 Then update your bundle
 
@@ -43,10 +43,17 @@ end
 Obviously, this will create tokens of 8 characters long - make them as
 short or as long as you require.
 
+__Note:__ Mongoid::Token leverages Mongoid's 'safe mode' by
+automatically creating a unique index on your documents using the token
+field. In order to take advantage of this feature (and ensure that your
+documents always have unique tokens) remember to create your indexes.
+
+See 'Token collision/duplicate prevention' below for more details.
+
 
 ## Options
 
-The `token` method takes two options: `length`, which determines the
+The `token` method has a couple of key options: `length`, which determines the
 length (or maximum length, in some cases) and `contains`, which tells
 Mongoid::Token which characters to use when generating the token.
 
@@ -58,6 +65,11 @@ The options for `contains` are as follows:
   `length`
 * `:fixed_numeric` - numbers only, but with the number of characters always the same as `length`
 
+You can also rename the token field, if required, using the
+`:field_name` option:
+
+* `token :contains => :numeric, :field_name => :purchase_order_number`
+
 ### Examples:
 
 * `token :length => 8, :contains => :alphanumeric` generates something like `8Sdc98dQ`
@@ -84,7 +96,34 @@ tokens to - all you need to do is save each of your models and they will
 be assigned a token, if it's missing.
 
 
+## Token collision/duplicate prevention
+
+Mongoid::Token leverages Mongoid's 'safe mode' by
+automatically creating a unique index on your documents using the token
+field. In order to take advantage of this feature (and ensure that your
+documents always have unique tokens) remember to create your indexes.
+
+You can read more about indexes in the [Mongoid docs](http://mongoid.org/docs/indexing.html).
+
+Additionally, Mongoid::Token will attempt to create a token 3 times
+before eventually giving up and raising a
+`Mongoid::Token::CollisionRetriesExceeded` exception. To take advantage
+of this, one must set `persist_in_safe_mode = true` in your Mongoid
+configuration.
+
+The number of retry attempts is adjustable in the `token` method using the
+`:retry` options. Set it to zero to turn off retrying.
+
+* `token :length => 6, :retry => 4` Will retry token generation 4
+times before bailing out
+* `token :length => 3, :retry => 0` Retrying disabled
+
+
 # Notes
 
 If you find a problem, please [submit an issue](http://github.com/thetron/mongoid_token/issues) (and a failing test, if
-you can). Pull requests and feature requests are always welcome.
+you can). Pull requests and feature requests are always welcome and
+greatly appreciated.
+
+Thanks to everyone that has contributed to this gem over the past year,
+in particular [eagleas](https://github.com/eagleas) and [jamesotron](https://github.com/jamesotron). Many, many thanks guys.

data/benchmarks/benchmark.rb

@@ -0,0 +1,50 @@
+$: << File.expand_path("../../lib", __FILE__)
+
+require 'database_cleaner'
+require 'mongoid'
+require 'mongoid-rspec'
+require 'mongoid_token'
+require 'benchmark'
+
+Mongoid.configure do |config|
+  config.master = Mongo::Connection.new.db("mongoid_token_benchmark")
+end
+
+DatabaseCleaner.strategy = :truncation
+
+# start benchmarks
+
+token_length = 2
+
+class Link
+  include Mongoid::Document
+  include Mongoid::Token
+  field :url
+  token :length => 2, :contains => :alphanumeric
+end
+
+class NoTokenLink
+  include Mongoid::Document
+  field :url
+end
+
+def create_link(token = true)
+  if token
+    Link.create(:url => "http://involved.com.au")
+  else
+    NoTokenLink.create(:url => "http://involved.com.au")
+  end
+end
+
+Link.destroy_all
+Link.create_indexes
+num_records = [1, 50, 100, 1000, 2000, 3000, 4000]
+puts "-- Alphanumeric token of length #{token_length} (#{62**token_length} possible tokens)"
+Benchmark.bm do |b|
+  num_records.each do |qty|
+    b.report("#{qty.to_s.rjust(5, " ")} records    "){ qty.times{ create_link(false) } }
+    b.report("#{qty.to_s.rjust(5, " ")} records tok"){ qty.times{ create_link } }
+    Link.destroy_all
+  end
+end
+

data/lib/mongoid/token/exceptions.rb

@@ -0,0 +1,16 @@
+module Mongoid
+  module Token
+    class Error < StandardError; end
+
+    class CollisionRetriesExceeded < Error
+      def initialize(resource = "unknown resource", attempts = "unspecified")
+        @resource = resource
+        @attempts = attempts
+      end
+
+      def to_s
+        "Failed to generate unique token for #{@resource} after #{@attempts} attempts."
+      end
+    end
+  end
+end

data/lib/mongoid_token.rb

@@ -1,3 +1,5 @@
+require 'mongoid/token/exceptions'
+
 module Mongoid
   module Token
     extend ActiveSupport::Concern
@@ -6,9 +8,13 @@ module Mongoid
       def token(*args)
         options = args.extract_options!
         options[:length] ||= 4
+        options[:retry] ||= 3
         options[:contains] ||= :alphanumeric
+        options[:field_name] ||= :token
 
-        self.field :token, :type => String
+        self.field options[:field_name].to_sym, :type => String
+        self.index options[:field_name].to_sym, :unique => true
+        # should validate token presence? Should this be enforced?
 
         set_callback(:create, :before) do |document|
           document.create_token(options[:length], options[:contains])
@@ -17,41 +23,85 @@ module Mongoid
         set_callback(:save, :before) do |document|
           document.create_token_if_nil(options[:length], options[:contains])
         end
+
+        after_initialize do # set_callback did not work with after_initialize callback
+          self.instance_variable_set :@max_collision_retries, options[:retry]
+          self.instance_variable_set :@token_field_name, options[:field_name]
+          self.instance_variable_set :@token_length, options[:length]
+          self.instance_variable_set :@token_contains, options[:contains]
+        end
+
+        if options[:retry] > 0
+          alias_method_chain :save, :safety
+          alias_method_chain :save!, :safety
+        end
+
+        self.class_variable_set :@@token_field_name, options[:field_name]
       end
 
       def find_by_token(token)
-        self.first(:conditions => {:token => token})
+        field_name = self.class_variable_get :@@token_field_name
+        self.first(:conditions => {field_name.to_sym => token})
       end
     end
 
-    module InstanceMethods
-      def to_param
-        self.token
-      end
-
-      protected
-      def create_token(length, characters)
-        self.token = self.generate_token(length, characters) while self.token.nil? || self.class.exists?(:conditions => {:token => self.token})
-      end
+    def to_param
+      self.send(@token_field_name.to_sym)
+    end
 
-      def create_token_if_nil(length, characters)
-        self.create_token(length, characters) if self.token.nil?
+    protected
+    def save_with_safety(args = {}, &block)
+      retries = @max_collision_retries
+      begin
+       # puts "Attempt: #{retries}"
+        safely.save_without_safety(args, &block)
+      rescue Mongo::OperationFailure => e
+        if (retries -= 1) > 0
+          self.create_token(@token_length, @token_contains)
+          retry
+        else
+          Rails.logger.warn "[Mongoid::Token] Warning: Maximum to generation retries (#{@max_collision_retries}) exceeded." if defined?(Rails) && Rails.env == 'development'
+          raise Mongoid::Token::CollisionRetriesExceeded.new(self, @max_collision_retries)
+        end
       end
+    end
 
-      def generate_token(length, characters)
-        case characters
-        when :alphanumeric
-          ActiveSupport::SecureRandom.hex(length)[0...length]
-        when :numeric
-          rand(10**length).to_s
-        when :fixed_numeric
-          rand(10**length).to_s.rjust(length,rand(10).to_s)
-        when :alpha
-          Array.new(length).map{['A'..'Z','a'..'z'].map{|r|r.to_a}.flatten[rand(52)]}.join
+    def save_with_safety!(args = {}, &block)
+      retries = @max_collision_retries
+      begin
+        #puts "Attempt: #{retries}"
+        safely.save_without_safety!(args, &block)
+      rescue Mongo::OperationFailure => e
+        if (retries -= 1) > 0
+          self.create_token(@token_length, @token_contains)
+          retry
         else
-          ActiveSupport::SecureRandom.hex(length)[0...length]
+          Rails.logger.warn "[Mongoid::Token] Warning: Maximum to generation retries (#{@max_collision_retries}) exceeded." if defined?(Rails) && Rails.env == 'development'
+          raise Mongoid::Token::CollisionRetriesExceeded.new(self, @max_collision_retries)
         end
       end
     end
+
+    def create_token(length, characters)
+      self.send(:"#{@token_field_name}=", self.generate_token(length, characters))
+      #puts "Set #{@token_field_name.to_s} to #{self.send(@token_field_name.to_sym)}"
+    end
+
+    def create_token_if_nil(length, characters)
+      self.create_token(length, characters) if self[@token_field_name.to_sym].nil?
+    end
+
+    def generate_token(length, characters = :alphanumeric)
+      case characters
+      when :alphanumeric
+        (1..length).collect { (i = Kernel.rand(62); i += ((i < 10) ? 48 : ((i < 36) ? 55 : 61 ))).chr }.join
+      when :numeric
+        rand(10**length).to_s
+      when :fixed_numeric
+        rand(10**length).to_s.rjust(length,rand(10).to_s)
+      when :alpha
+        Array.new(length).map{['A'..'Z','a'..'z'].map{|r|r.to_a}.flatten[rand(52)]}.join
+      end
+    end
   end
 end

data/lib/version.rb

@@ -1,3 +1,3 @@
 module MongoidToken
-  VERSION = "0.9.1"
+  VERSION = "1.0.0"
 end

data/mongoid_token.gemspec

@@ -10,10 +10,10 @@ Gem::Specification.new do |s|
   s.email       = ["nicholas@bruning.com.au"]
   s.homepage    = "http://github.com/thetron/mongoid_token"
   s.summary     = %q{A little random, unique token generator for Mongoid documents.}
-  s.description = %q{Mongoid token is a gem for creating random, unique tokens for mongoid documents, when you want shorter URLs.}
+  s.description = %q{Mongoid token is a gem for creating random, unique tokens for mongoid documents. Highly configurable and great for making URLs a little more compact.}
 
   s.rubyforge_project = "mongoid_token"
-  s.add_dependency 'activesupport', '>= 3.0.0'
+  s.add_dependency 'activesupport', '>= 3.0'
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/spec/mongoid/token_spec.rb

@@ -22,12 +22,37 @@ class Link
   token :length => 3, :contains => :alphanumeric
 end
 
+class FailLink
+  include Mongoid::Document
+  include Mongoid::Token
+  field :url
+  token :length => 3, :contains => :alphanumeric, :retry => 0
+end
+
 class Video
   include Mongoid::Document
   include Mongoid::Token
 
   field :name
-  token :length => 8, :contains => :alpha
+  token :length => 8, :contains => :alpha, :field_name => :vid
+end
+
+class Node
+  include Mongoid::Document
+  include Mongoid::Token
+
+  field :name
+  token :length => 8, :contains => :fixed_numeric
+
+  embedded_in :cluster
+end
+
+class Cluster
+  include Mongoid::Document
+
+  field :name
+
+  embeds_many :nodes
 end
 
 describe Mongoid::Token do
@@ -35,21 +60,28 @@ describe Mongoid::Token do
     @account = Account.create(:name => "Involved Pty. Ltd.")
     @link = Link.create(:url => "http://involved.com.au")
     @video = Video.create(:name => "Nyan nyan")
+
+    Account.create_indexes
+    Link.create_indexes
+    FailLink.create_indexes
+    Video.create_indexes
+    Node.create_indexes
   end
 
   it "should have a token field" do
     @account.attributes.include?('token').should == true
     @link.attributes.include?('token').should == true
-    @video.attributes.include?('token').should == true
+    @video.attributes.include?('vid').should == true
   end
 
   it "should have a token of correct length" do
     @account.token.length.should == 16
     @link.token.length.should == 3
-    @video.token.length.should == 8
+    @video.vid.length.should == 8
   end
 
   it "should only generate unique tokens" do
+    Link.create_indexes
     1000.times do
       @link = Link.create(:url => "http://involved.com.au")
       Link.count(:conditions => {:token => @link.token}).should == 1
@@ -70,9 +102,9 @@ describe Mongoid::Token do
       @link.token.gsub(/[A-Za-z0-9]/, "").length.should == 0
     end
 
-    50.times do
+    50.times do |index|
       @video = Video.create(:name => "A test video")
-      @video.token.gsub(/[A-Za-z]/, "").length.should == 0
+      @video.vid.gsub(/[A-Za-z]/, "").length.should == 0
     end
   end
 
@@ -89,16 +121,22 @@ describe Mongoid::Token do
   it "should return the token as its parameter" do
     @account.to_param.should == @account.token
     @link.to_param.should == @link.token
-    @video.to_param.should == @video.token
+    @video.to_param.should == @video.vid
   end
 
 
-  it "should be finable by token" do
+  it "should be findable by token" do
     50.times do |index|
       Account.create(:name => "A random company #{index}")
     end
     Account.find_by_token(@account.token).id.should == @account.id
     Account.find_by_token(Account.last.token).id.should == Account.last.id
+
+    10.times do |index|
+      Video.create(:name => "Lord of the Rings, Super Special Edition part #{index}")
+    end
+    Video.find_by_token(@video.vid).id.should == @video.id
+    Video.find_by_token(Video.last.vid).id.should == Video.last.id
   end
 
   it "should create a token, if the token is missing" do
@@ -106,4 +144,46 @@ describe Mongoid::Token do
     @account.save!
     @account.token.should_not be_nil
   end
+
+  it "should fail with an exception after 3 retries (by default)" do
+    Link.destroy_all
+    Link.create_indexes
+
+    @first_link = Link.create(:url => "http://involved.com.au")
+    @link = Link.new(:url => "http://fail.com")
+    def @link.create_token(l,c) # override to always generate a duplicate
+      super
+      self.token = Link.first.token
+    end
+
+    lambda{ @link.save }.should raise_error(Mongoid::Token::CollisionRetriesExceeded)
+    Link.count.should == 1
+    Link.where(:token => @first_link.token).count.should == 1
+  end
+
+  it "should not raise a custom exception if retries are set to zero" do
+    FailLink.destroy_all
+    FailLink.create_indexes
+
+    @first_link = FailLink.create(:url => "http://involved.com.au")
+    @link = FailLink.new(:url => "http://fail.com")
+    def @link.create_token(l,c) # override to always generate a duplicate
+      super
+      self.token = FailLink.first.token
+    end
+
+    lambda{ @link.save }.should_not raise_error(Mongoid::Token::CollisionRetriesExceeded)
+  end
+
+  it "should create unique indexes on embedded documents" do
+    @cluster = Cluster.new(:name => "CLUSTER_001")
+    5.times do |index|
+      @cluster.nodes.create!(:name => "NODE_#{index.to_s.rjust(3, '0')}")
+    end
+
+    @cluster.nodes.each do |node|
+      node.attributes.include?('token').should == true
+      node.token.match(/[0-9]{8}/).should_not == nil
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -4,6 +4,7 @@ require 'database_cleaner'
 require 'mongoid'
 require 'mongoid-rspec'
 require 'mongoid_token'
+require 'mongoid/token/exceptions'
 
 RSpec.configure do |config|
   config.include Mongoid::Matchers
@@ -13,10 +14,18 @@ RSpec.configure do |config|
 
   config.after(:each) do
     DatabaseCleaner.clean
+
+    # Added dropping collection to ensure indexes are removed
+    Mongoid.master.collections.select do |collection|
+      include = collection.name !~ /system/
+      include
+    end.each(&:drop)
   end
 end
 
 Mongoid.configure do |config|
   config.master = Mongo::Connection.new.db("mongoid_token_test")
+  config.autocreate_indexes = true
+  config.persist_in_safe_mode = true
 end
 

metadata

@@ -1,78 +1,72 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: mongoid_token
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 1.0.0
   prerelease: 
-  version: 0.9.1
 platform: ruby
-authors: 
+authors:
 - Nicholas Bruning
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-06-04 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-02-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: activesupport
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &2162530960 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: 3.0.0
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
   type: :runtime
-  version_requirements: *id001
-description: Mongoid token is a gem for creating random, unique tokens for mongoid documents, when you want shorter URLs.
-email: 
+  prerelease: false
+  version_requirements: *2162530960
+description: Mongoid token is a gem for creating random, unique tokens for mongoid
+  documents. Highly configurable and great for making URLs a little more compact.
+email:
 - nicholas@bruning.com.au
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .autotest
 - .gitignore
 - .rspec
 - Gemfile
 - README.md
 - Rakefile
-- lib/.DS_Store
+- benchmarks/benchmark.rb
+- lib/mongoid/token/exceptions.rb
 - lib/mongoid_token.rb
 - lib/version.rb
 - mongoid_token.gemspec
-- spec/.DS_Store
 - spec/mongoid/token_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/thetron/mongoid_token
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: mongoid_token
-rubygems_version: 1.8.3
+rubygems_version: 1.8.7
 signing_key: 
 specification_version: 3
 summary: A little random, unique token generator for Mongoid documents.
-test_files: 
+test_files:
 - spec/mongoid/token_spec.rb
 - spec/spec_helper.rb