mongoid-ids 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f98fcca5a53dd0256f8e74ab38719ce9bd2e001b
+  data.tar.gz: 47b8832b2ff1d6a217aac882b275770ff9c7fb24
+SHA512:
+  metadata.gz: 37852de0e84195e089881f026e322679977bfc3a576d5bfd57dcd14e97c6983110875ee5896a7b318509d5a983d6e07a22f4f08ae7edfc99808c0950cbc18579
+  data.tar.gz: cc4fa090eabec9cd29b999e04406d680e73537e2bec545d28b0f115665c2f40a0f782ed5aa016a1def94872e04953ceac65c5ca3e6bedcd780b55ecda59eb952

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.DS_Store

data/.rspec

@@ -0,0 +1,3 @@
+--tty
+--color
+--format documentation

data/.travis.yml

@@ -0,0 +1,18 @@
+language: ruby
+
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - 2.1.1
+  - 2.2.0
+
+gemfile:
+  - Gemfile
+
+services:
+  - mongodb
+
+env: CI="travis"
+
+script: "bundle exec rspec"

data/Gemfile

@@ -0,0 +1,10 @@
+source "http://rubygems.org"
+
+gemspec
+
+group :test do
+  gem 'rspec', '~> 3.1.0'
+  gem "codeclimate-test-reporter", require: nil
+  gem 'database_cleaner'
+  gem 'mongoid-rspec', '~> 2.0.0'
+end

data/Guardfile

@@ -0,0 +1,22 @@
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rsspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separetly)
+#  * 'just' rspec: 'rspec'
+
+# guard :rubocop do
+guard :rubocop, all_on_start: false, keep_failed: false, cli: ['-D'] do
+  watch(%r{.+\.rb$})
+  watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+end
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch(/^generators\/(.+)\.rb$/) { |_m| 'spec/schemaless/worker_spec' }
+
+  watch('spec/spec_helper.rb')  { 'spec' }
+end

data/MIT-LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Nicholas Bruning
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+# Mongoid::Ids - Short snappy ids/tokens for Mongoid documents
+
+[![Build Status](https://secure.travis-ci.org/nofxx/mongoid-ids.png)](http://travis-ci.org/nofxx/mongoid-ids)
+[![Code Climate](https://codeclimate.com/github/nofxx/mongoid-ids.png)](https://codeclimate.com/github/nofxx/mongoid-ids)
+
+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 ObjectIDs.
+
+Mongoid::Ids can help turn this:
+
+    http://bestappever.com/video/4dcfbb3c6a4f1d4c4a000012
+
+Into something more like this:
+
+    http://bestappever.com/video/8tmQ9p
+
+
+## Getting started
+
+In your gemfile, add:
+
+    gem 'mongoid-ids', '~> 2.0.0'
+
+Then update your bundle
+
+    $ bundle update
+
+In your Mongoid documents, just add `include Mongoid::Ids` and the
+`token` method will take care of all the setup, like so:
+
+```ruby
+class Person
+  include Mongoid::Document
+  include Mongoid::Ids
+
+  field :name
+
+  token
+end
+
+```
+
+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::Ids 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.
+
+
+## Finders
+
+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).
+
+```ruby
+Video.find("x3v98")
+Account.find("ACC-123456")
+```
+
+
+## Configuration
+
+### Idss
+
+As of `Mongoid::Ids` 2.0.0, you can now choose between two different
+systems for managing how your tokens look.
+
+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.
+
+For when you need to generate more complex tokens, you can use the
+[`pattern`](#patterns-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`)
+
+This one is easy, it's just an integer.
+
+__Example:__
+
+```ruby
+token :length => 6 # Tokens are now of length 6
+token :length => 12 # Whow, whow, whow. Slow down egghead.
+```
+
+You get the idea.
+
+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.
+
+#### Contains (`:contains`)
+
+Contains has 7 different options:
+
+* `: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
+
+__Examples:__
+```ruby
+token :contains => :alpha_upper, :length => 8
+token :contains => :fixed_numeric
+```
+
+#### Patterns (`:pattern`)
+
+New in 2.0.0, patterns allow you fine-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:__
+
+```ruby
+token :pattern => "PRE-%C%C-%d%d%d%d" # Generates something like: 'PRE-ND-3485'
+```
+
+You can also add a repetition modifier, which can help improve readability on
+more complex patterns. You simply add any integer after the letter.
+
+__Examples:__
+
+```ruby
+token :pattern => "APP-%d6" # Generates something like; "APP-638924"
+```
+
+### Field Name
+
+This allows you to change the field name used by `Mongoid::Ids`
+This is particularly handy to use multiple tokens one a single document.
+
+__Examples:__
+```ruby
+token :length => 6
+token :sharing_token, :length => 12
+token :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:__
+```ruby
+token :skip_finders => true
+```
+
+
+### Override to_param (`:override_to_param`)
+
+By default, `Mongoid::Ids` 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:__
+```ruby
+token :override_to_param => false
+```
+
+
+### Retry Count (`:retry_count`)
+
+In the event of a token collision, this gem will attempt to try three
+more times before raising a `Mongoid::Ids::CollisionRetriesExceeded`
+error. If you're wanting it to try harder, or less hard, then this
+option is for you.
+
+__Examples:__
+```ruby
+token :retry_count => 9
+token :retry_count => 0
+```
+
+# Notes
+
+If you find a problem, please [submit an issue](http://github.com/nofxx/mongoid-ids/issues) (and a failing test, if
+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.
+Many, many thanks - you guys rawk.
+
+
+## Contributors:
+
+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/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/benchmarks/benchmark.rb

@@ -0,0 +1,48 @@
+$: << File.expand_path("../../lib", __FILE__)
+
+require 'database_cleaner'
+require 'mongoid'
+require 'mongoid/ids'
+require 'benchmark'
+
+Mongoid.configure do |config|
+  config.connect_to("mongoid_ids_benchmark2")
+end
+
+DatabaseCleaner.strategy = :truncation
+
+# start benchmarks
+
+TOKEN_LENGTH = 5
+
+class Link
+  include Mongoid::Document
+  include Mongoid::Ids
+  field :url
+  token :length => TOKEN_LENGTH, :contains => :alphanumeric
+end
+
+class NoIdsLink
+  include Mongoid::Document
+  field :url
+end
+
+def create_link(token = true)
+  if token
+    Link.create(:url => "http://involved.com.au")
+  else
+    NoIdsLink.create(:url => "http://involved.com.au")
+  end
+end
+
+Link.delete_all
+Link.create_indexes
+NoIdsLink.delete_all
+num_records = [1, 50, 100, 1000, 2000, 3000, 5000, 10000, 30000, 50000]
+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 } }
+  end
+end

data/lib/mongoid/ids/collision_resolver.rb

@@ -0,0 +1,37 @@
+require 'mongoid/ids/collisions'
+
+module Mongoid
+  module Ids
+    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::Ids::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.send(: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/ids/collisions.rb

@@ -0,0 +1,33 @@
+module Mongoid
+  module Ids
+    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
+          else
+            raise e
+          end
+        end
+      end
+
+      def raise_collision_retries_exceeded_error(field_name, retry_count)
+        Rails.logger.warn "[Mongoid::Ids] Warning: Maximum token generation retries (#{retry_count}) exceeded on `#{field_name}'." if defined?(Rails)
+        raise Mongoid::Ids::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/ids/exceptions.rb

@@ -0,0 +1,16 @@
+module Mongoid
+  module Ids
+    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/ids/finders.rb

@@ -0,0 +1,15 @@
+module Mongoid
+  module Ids
+    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| BSON::ObjectId.legal?(arg)} ? send(:"find_without_#{field_name}",*args) : klass.send(:"find_by_#{field_name.to_s}", args.first)
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/ids/generator.rb

@@ -0,0 +1,76 @@
+# 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 Ids
+    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.rand_string_from_chars(chars, length = 1)
+        Array.new(length).map{ chars.sample }.join
+      end
+
+      def self.down_character(length = 1)
+        self.rand_string_from_chars ('a'..'z').to_a, length
+      end
+
+      def self.up_character(length = 1)
+        self.rand_string_from_chars ('A'..'Z').to_a, length
+      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)
+        self.rand_string_from_chars (('A'..'Z').to_a + ('a'..'z').to_a), length
+      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)
+        self.rand_string_from_chars ['.','-','_','=','+','$'], length
+      end
+    end
+  end
+end

data/lib/mongoid/ids/options.rb

@@ -0,0 +1,78 @@
+module Mongoid
+  module Ids
+    class 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 field_name=(param)
+        return if param.nil? || param.empty?
+        @options[:field_name] = param
+      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::Ids 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 => :_id,
+          :skip_finders => false,
+          :override_to_param => true,
+        }.merge(options)
+      end
+    end
+  end
+end

data/lib/mongoid/ids/version.rb

@@ -0,0 +1,5 @@
+module Mongoid
+  module Ids
+    VERSION = '0.1.1'
+  end
+end