mongoid_token 1.1.1 → 2.0.0

data/.autotest

@@ -1 +0,0 @@
-require 'autotest/growl'

data/README.md

@@ -4,30 +4,22 @@
 
 This library is a quick and simple way to generate unique, random tokens
 for your mongoid documents, in the cases where you can't, or don't want
-to use slugs, or the default MongoDB IDs.
+to use slugs, or the default MongoDB ObjectIDs.
 
 Mongoid::Token can help turn this:
 
-    http://myawesomewebapp.com/video/4dcfbb3c6a4f1d4c4a000012/edit
+    http://bestappever.com/video/4dcfbb3c6a4f1d4c4a000012
 
 Into something more like this:
 
-    http://myawesomewebapp.com/video/83xQ3r/edit
-
-
-## Mongoid 3.x Support
-
-As of version 1.1.0, Mongoid::Token now supports Mongoid 3.x.
-
-> If you still require __Mongoid 2.x__ support, please install
-> Mongoid::Token 1.0.0.
+    http://bestappever.com/video/8tmQ9p
 
 
 ## Getting started
 
 In your gemfile, add:
 
-    gem 'mongoid_token', '~> 1.1.0'
+    gem 'mongoid_token', '~> 2.0.0'
 
 Then update your bundle
 
@@ -39,102 +31,178 @@ In your Mongoid documents, just add `include Mongoid::Token` and the
 ````
 class Person
   include Mongoid::Document
-  include Mongoid::Timestamps
   include Mongoid::Token
 
-  field :first_name
-  field :last_name
+  field :name
 
-  token :length => 8
+  token
 end
 
 ````
 
-Obviously, this will create tokens of 8 characters long - make them as
-short or as long as you require.
+And that's it! There's lots of configuration options too - which are all
+listed [below](#configuration). By default, the `token` method will
+create tokens 4 characters long, containing random alphanumeric characters.
 
 __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.
 
+## Finders
 
-## Options
+By default, the gem will override the existing `find` method in Mongoid,
+in order to search for documents based on their token first (although
+the default behaviour of ObjectIDs is also there). You can disable these
+with the [`skip_finders` configuration option](#skip-finders-skip_finders).
 
-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.
+````
+Video.find("x3v98")
+Account.find("ACC-123456")
+````
 
-The options for `contains` are as follows:
 
-* `:alphanumeric` - letters (upper and lowercase) and numbers
-* `:alpha` - letters (upper and lowercase) only
-* `:alpha_lower` - letters (lowercase) only
-* `:alpha_upper` - letters (uppercase) only
-* `:numeric` - numbers only, anything from 1 character long, up to and
-  `length`
-* `:fixed_numeric` - numbers only, but with the number of characters always the same as `length`
-* `:fixed_numeric_no_leading_zeros` - as above, but will never start with
-zeros
+## Configuration
 
-You can also rename the token field, if required, using the
-`:field_name` option:
+### Tokens
 
-* `token :contains => :numeric, :field_name => :purchase_order_number`
+As of `Mongoid::Token` 2.0.0, you can now choose between two different
+systems for managing how your tokens look. 
 
-### Examples:
+For simple setup, you can use
+combination of the [`length`](#length-length) and [`contains`](#contains-contains), which modify the length and
+types of characters to use.
 
-* `token :length => 8, :contains => :alphanumeric` generates something like `8Sdc98dQ`
-* `token :length => 5, :contains => :alpha` gereates something like
-  `ASlkj`
-* token :length 
-* `token :length => 4, :contains => :numeric` could generate anything
-  from `0` upto `9999` - but in a random order
-* `token :length => 4, :contains => :fixed_numeric` will generate
-  anything from `0000` to `9999` in a random order
-* `token :length => 4, :contains => :fixed_numeric_no_leading_zeros` will
-generate anything from `1000` to `9999` in a random order
+For when you need to generate more complex tokens, you can use the
+[`pattern`](#pattern-pattern) option, which allows for very low-level control of the precise
+structure of your tokens, as well as allowing for static strings, like
+prefixes, infixes or suffixes.
 
+#### Length (`:length`)
 
-## Finders
+This one is easy, it's just an integer. 
 
-The library also contains a finder method for looking up your documents
-called `find_by_token`, e.g:
+__Example:__
 
-    Person.find_by_token('7dDn8q')
+````
+token :length => 6 # Tokens are now of length 6
+token :length => 12 # Whow, whow, whow. Slow down egghead.
+````
 
+You get the idea.
 
-## Adding tokens to existing documents
+The only caveat here is that if used in combination with the 
+`:contains => :numeric` option, tokens may vary in length _up to_ the
+specified length.
 
-If you've got an app with existing data that you would like to add
-tokens to - all you need to do is save each of your models and they will
-be assigned a token, if it's missing.
+#### Contains (`:contains`)
 
+Contains has 7 different options:
 
-## Token collision/duplicate prevention
+* `:alphanumeric` - contains uppercase & lowercase characters, as well
+as numbers
+* `:alpha` - contains only uppercase & lowercase characters
+* `:alpha_upper` - contains only uppercase letters
+* `:alpha_lower` - contains only lowercase letters
+* `:numeric` - integer, length may be shorter than `:length`
+* `:fixed_numeric` - integer, but will always be of length `:length`
+* `:fixed_numeric_no_leading_zeros` - same as `:fixed_numeric`, but will
+never start with zeros
 
-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.
+__Examples:__
+````
+token :contains => :alpha_upper, :length => 8
+token :contains => :fixed_numeric
+````
+
+#### Patterns (`:pattern`)
+
+New in 2.0.0, patterns allow you find-grained control over how your
+tokens look. It's great for generating random data that has a
+requirements to also have some basic structure. If you use the
+`:pattern` option, it will override both the `:length` and `:contains`
+options.
+
+This was designed to operate in a similar way to something like `strftime`,
+if the syntax offends you - please open an issue, I'd love to get some
+feedback here and better refine how these are generated.
+
+Any characters in the string are treated as static, except those that are
+proceeded by a `%`. Those special characters represent a single, randomly
+generated character, and are as follows:
+
+* `%s` - any uppercase, lowercase, or numeric character
+* `%w` - any uppercase, or lowercase character
+* `%c` - any lowercase character
+* `%C` - any uppercase character
+* `%d` - any digit
+* `%D` - any non-zero digit
+
+__Example:__
+
+````
+token :pattern => "PRE-%C%C-%d%d%d%d" # Generates something like: 'PRE-ND-3485'
+````
 
-You can read more about indexes in the [Mongoid docs](http://mongoid.org/docs/indexing.html).
+You can also add a repetition modifier, which can help improve readability on
+more complex patterns. You simply add any integer after the letter.
 
-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.
+__Examples:__
 
-The number of retry attempts is adjustable in the `token` method using the
-`:retry` options. Set it to zero to turn off retrying.
+````
+token :sku => "APP-%d6" # Generates something like; "APP-638924"
+````
+
+### Field Name (`:field_name`)
+
+This allows you to change the field name used by `Mongoid::Token`
+(default is `:token`). This is particularly handy when you're wanting to
+use multiple tokens one a single document.
+
+__Examples:__
+````
+token :length => 6
+token :field_name => :sharing_token, :length => 12
+token :field_name => :yet_another
+````
+
+
+### Skip Finders (`:skip_finders`)
+
+This will prevent the gem from creating the customised finders and
+overrides for the default `find` behaviour used by Mongoid.
+
+__Example:__
+````
+token :skip_finders => true
+````
+
+
+### Override to_param (`:override_to_param`)
+
+By default, `Mongoid::Token` will override to_param, to make it an easy
+drop-in replacement for the default ObjectIDs. If needed, you can turn
+this behaviour off:
+
+__Example:__
+````
+token :override_to_param => false
+````
+
+
+### Retry Count (`:retry_count`)
 
-* `token :length => 6, :retry => 4` Will retry token generation 4
-times before bailing out
-* `token :length => 3, :retry => 0` Retrying disabled
+In the event of a token collision, this gem will attempt to try three
+more times before raising a `Mongoid::Token::CollisionRetriesExceeded`
+error. If you're wanting it to try harder, or less hard, then this
+option is for you.
 
+__Examples:__
+````
+token :retry_count => 9
+token :retry_count => 0
+````
 
 # Notes
 
@@ -145,11 +213,13 @@ greatly appreciated.
 Thanks to everyone that has contributed to this gem over the past year.
 Many, many thanks - you guys rawk.
 
+
 ## Contributors:
 
-* [olliem](https://github.com/olliem)
-* [msolli](https://github.com/msolli)
-* [siong1987](https://github.com/siong1987)
-* [stephan778](https://github.com/stephan778) 
-* [eagleas](https://github.com/eagleas) 
-* [jamesotron](https://github.com/jamesotron).
+Thanks to everyone who has provided support for this gem over the years.
+In particular: [olliem](https://github.com/olliem),
+[msolli](https://github.com/msolli),
+[siong1987](https://github.com/siong1987),
+[stephan778](https://github.com/stephan778),
+[eagleas](https://github.com/eagleas), and
+[jamesotron](https://github.com/jamesotron).

data/lib/mongoid/token/collision_resolver.rb

@@ -0,0 +1,37 @@
+require 'mongoid/token/collisions'
+
+module Mongoid
+  module Token
+    class CollisionResolver
+      attr_accessor :create_new_token
+      attr_reader :klass
+      attr_reader :field_name
+      attr_reader :retry_count
+
+      def initialize(klass, field_name, retry_count)
+        @create_new_token = Proc.new {|doc|}
+        @klass = klass
+        @field_name = field_name
+        @retry_count = retry_count
+        klass.send(:include, Mongoid::Token::Collisions)
+        alias_method_with_collision_resolution(:insert)
+        alias_method_with_collision_resolution(:upsert)
+      end
+
+      def create_new_token_for(document)
+        @create_new_token.call(document)
+      end
+
+      private
+      def alias_method_with_collision_resolution(method)
+        handler = self
+        klass.define_method(:"#{method.to_s}_with_#{handler.field_name}_safety") do |method_options = {}|
+          self.resolve_token_collisions handler do
+            with(:safe => true).send(:"#{method.to_s}_without_#{handler.field_name}_safety", method_options)
+          end
+        end
+        klass.alias_method_chain method.to_sym, :"#{handler.field_name}_safety"
+      end
+    end
+  end
+end

data/lib/mongoid/token/collisions.rb

@@ -0,0 +1,31 @@
+module Mongoid
+  module Token
+    module Collisions
+      def resolve_token_collisions(resolver)
+        retries = resolver.retry_count
+        begin
+          yield
+        rescue Moped::Errors::OperationFailure => e
+          if is_duplicate_token_error?(e, self, resolver.field_name)
+            if (retries -= 1) >= 0
+              resolver.create_new_token_for(self)
+              retry
+            end
+            raise_collision_retries_exceeded_error resolver.field_name, resolver.retry_count
+          end
+        end
+      end
+
+      def raise_collision_retries_exceeded_error(field_name, retry_count)
+        Rails.logger.warn "[Mongoid::Token] Warning: Maximum token generation retries (#{retry_count}) exceeded on `#{field_name}'." if defined?(Rails)
+        raise Mongoid::Token::CollisionRetriesExceeded.new(self, retry_count)
+      end
+
+      def is_duplicate_token_error?(err, document, field_name)
+        [11000, 11001].include?(err.details['code']) &&
+          err.details['err'] =~ /dup key/ &&
+          err.details['err'] =~ /"#{document.send(field_name)}"/
+      end
+    end
+  end
+end

data/lib/mongoid/token/finders.rb

@@ -0,0 +1,19 @@
+module Mongoid
+  module Token
+    module Finders
+      def self.define_custom_token_finder_for(klass, field_name = :token)
+        klass.define_singleton_method(:"find_by_#{field_name.to_s}") do |token|
+          self.find_by(field_name.to_sym => token)
+        end
+
+        klass.define_singleton_method :"find_with_#{field_name}" do |*args| # this is going to be painful if tokens happen to look like legal object ids
+          args.all?{|arg| Moped::BSON::ObjectId.legal?(arg)} ? send(:"find_without_#{field_name}",*args) : klass.send(:"find_by_#{field_name.to_s}", args.first)
+        end
+
+        # this craziness taken from, and then compacted into a string class_eval
+        # http://geoffgarside.co.uk/2007/02/19/activesupport-alias-method-chain-modules-and-class-methods/
+        klass.class_eval("class << self; alias_method_chain :find, :#{field_name} if self.method_defined?(:find); end")
+      end
+    end
+  end
+end

data/lib/mongoid/token/generator.rb

@@ -0,0 +1,72 @@
+# proposed pattern options
+# %c - lowercase character
+# %C - uppercase character
+# %d - digit
+# %D - non-zero digit / no-leading zero digit if longer than 1
+# %s - alphanumeric character
+# %w - upper and lower alpha character
+# %p - URL-safe punctuation
+#
+# Any pattern can be followed by a number, representing how many of that type to generate
+
+module Mongoid
+  module Token
+    module Generator
+      REPLACE_PATTERN = /%((?<character>[cCdDpsw]{1})(?<length>\d+(,\d+)?)?)/
+
+      def self.generate(pattern)
+        pattern.gsub REPLACE_PATTERN do |match|
+          match_data = $~
+          type = match_data[:character]
+          length = [match_data[:length].to_i, 1].max
+
+          case type
+          when 'c'
+            down_character(length)
+          when 'C'
+            up_character(length)
+          when 'd'
+            digits(length)
+          when 'D'
+            integer(length)
+          when 's'
+            alphanumeric(length)
+          when 'w'
+            alpha(length)
+          when 'p'
+            "-"
+          end
+        end
+      end
+
+      private
+      def self.down_character(length = 1)
+        Array.new(length).map{['a'..'z'].map{|r|r.to_a}.flatten[rand(26)]}.join
+      end
+
+      def self.up_character(length = 1)
+        Array.new(length).map{['A'..'Z'].map{|r|r.to_a}.flatten[rand(26)]}.join
+      end
+
+      def self.integer(length = 1)
+        (rand(10**length - 10**(length-1)) + 10**(length-1)).to_s
+      end
+
+      def self.digits(length = 1)
+        rand(10**length).to_s.rjust(length, "0")
+      end
+
+      def self.alpha(length = 1)
+        Array.new(length).map{['A'..'Z','a'..'z'].map{|r|r.to_a}.flatten[rand(52)]}.join
+      end
+
+      def self.alphanumeric(length = 1)
+        (1..length).collect { (i = Kernel.rand(62); i += ((i < 10) ? 48 : ((i < 36) ? 55 : 61 ))).chr }.join
+      end
+
+      def self.punctuation(length = 1)
+        Array.new(length).map{['.','-','_','=','+','$'].map{|r|r.to_a}.flatten[rand(52)]}.join
+      end
+    end
+  end
+end

data/lib/mongoid/token/options.rb

@@ -0,0 +1,68 @@
+class Mongoid::Token::Options
+  def initialize(options = {})
+    @options = merge_defaults validate_options(options)
+  end
+
+  def length
+    @options[:length]
+  end
+
+  def retry_count
+    @options[:retry_count]
+  end
+
+  def contains
+    @options[:contains]
+  end
+
+  def field_name
+    @options[:field_name]
+  end
+
+  def skip_finders?
+    @options[:skip_finders]
+  end
+
+  def override_to_param?
+    @options[:override_to_param]
+  end
+
+  def pattern
+    @options[:pattern] ||= case @options[:contains].to_sym
+    when :alphanumeric
+      "%s#{@options[:length]}"
+    when :alpha
+      "%w#{@options[:length]}"
+    when :alpha_upper
+      "%C#{@options[:length]}"
+    when :alpha_lower
+      "%c#{@options[:length]}"
+    when :numeric
+      "%d1,#{@options[:length]}"
+    when :fixed_numeric
+      "%d#{@options[:length]}"
+    when :fixed_numeric_no_leading_zeros
+      "%D#{@options[:length]}"
+    end
+  end
+
+  private
+  def validate_options(options)
+    if options.has_key?(:retry)
+      STDERR.puts "Mongoid::Token Deprecation Warning: option `retry` has been renamed to `retry_count`. `:retry` will be removed in v2.1"
+      options[:retry_count] = options[:retry]
+    end
+    options
+  end
+
+  def merge_defaults(options)
+    {
+      :length => 4,
+      :retry_count => 3,
+      :contains => :alphanumeric,
+      :field_name => :token,
+      :skip_finders => false,
+      :override_to_param => true,
+    }.merge(options)
+  end
+end

data/lib/mongoid/token.rb

@@ -0,0 +1,63 @@
+require 'mongoid/token/exceptions'
+require 'mongoid/token/options'
+require 'mongoid/token/generator'
+require 'mongoid/token/finders'
+require 'mongoid/token/collision_resolver'
+
+module Mongoid
+  module Token
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def initialize_copy(source)
+        super
+        self.token = nil
+      end
+
+      def token(*args)
+        options = Mongoid::Token::Options.new(args.extract_options!)
+
+        self.field options.field_name, :type => String, :default => nil
+        self.index({ options.field_name => 1 }, { :unique => true })
+
+        resolver = Mongoid::Token::CollisionResolver.new(self, options.field_name, options.retry_count)
+        resolver.create_new_token = Proc.new do |document|
+          document.send(:create_token, options.field_name, options.pattern)
+        end
+
+        if options.skip_finders? == false
+          Finders.define_custom_token_finder_for(self, options.field_name)
+        end
+
+        set_callback(:create, :before) do |document|
+          document.create_token options.field_name, options.pattern
+        end
+
+        set_callback(:save, :before) do |document|
+          document.create_token_if_nil options.field_name, options.pattern
+        end
+
+        if options.override_to_param?
+          self.define_method :to_param do
+            self.send(options.field_name) || super
+          end
+        end
+      end
+    end
+
+    protected
+    def create_token(field_name, pattern)
+      self.send :"#{field_name.to_s}=", self.generate_token(pattern)
+    end
+
+    def create_token_if_nil(field_name, pattern)
+      if self[field_name.to_sym].blank?
+        self.create_token field_name, pattern
+      end
+    end
+
+    def generate_token(pattern)
+      Mongoid::Token::Generator.generate pattern
+    end
+  end
+end