cuid 1.0.0

data/lib/cuid.rb

@@ -0,0 +1,175 @@
+require "socket"
+require 'cuid/version'
+begin
+  require "securerandom"
+rescue LoadError
+end
+
+##
+# Cuid is a library for generating unique collision-resistant IDs optimized for horizontal scaling and performance
+#
+# @example Generate a hash
+#   hash = Cuid::generate #=> "ch8qypsnz0000a4welw8anyr"
+#
+# @example Generate 2 hashes
+#   hashes = Cuid::generate(2) #=> ["ch8qyq35f0002a4wekjcwmh30", "ch8qyq35f0003a4weewy22izq"]
+#
+# @see http://github.com/dilvie/cuid Original author's detailed explanation of the cuid spec
+
+module Cuid
+  ##
+  # @private
+  @count = 0
+  
+  ##
+  # length of each segment of the hash
+  BLOCK_SIZE = 4
+
+  ##
+  # size of the alphabet (e.g. base36 is [a-z0-9])
+  BASE = 36
+
+  ##
+  # @private
+  # maximum number that can be stored in a block of the specified size using the specified alphabet
+  DISCRETE_VALUES = (BASE ** BLOCK_SIZE) - 1
+
+  ##
+  # size of the random segment of the block
+  RAND_SIZE = BLOCK_SIZE * 2
+
+  ##
+  # @private
+  # maximum number that can be stored in the random block
+  RAND_MAX = (BASE ** RAND_SIZE) - 1
+
+  ##
+  # @private
+  # minimum number that can be stored in the random block (otherwise it will be too short)
+  RAND_MIN = BASE ** (RAND_SIZE - 1)
+
+  ##
+  # @private
+  # first letter of the hash
+  LETTER = "c"
+
+  class << self
+
+    ##
+    # Returns one or more hashes based on the parameter supplied
+    # 
+    # @overload generate()
+    #   Returns one hash when called with no parameters or a parameter of 1
+    # 
+    #   @param [optional, Integer] quantity determines number of hashes returned (must be nil, 0 or 1)
+    #   @return [String]
+    #
+    # @overload generate(quantity)
+    #   Returns an array of hashes when called with a parameter greater than 1
+    #   
+    #   @param [Integer] quantity determines number of hashes returned (must be greater than 1)
+    #   @return [Array<String>]
+    #
+    # @overload generate(quantity,secure_random)
+    #   Returns an array of hashes when called with a parameter greater than 1
+    #
+    #   @param [Integer] quantity determines number of hashes returned (must be greater than 1)
+    #   @param [Boolean] secure_random attempts to use SecureRandom if set to True (Ruby 1.9.2 and up; reverts to Kernel#rand if SecureRandom is not supported)
+    def generate(quantity=1,secure_random=false)
+      @use_secure_random = secure_random
+      @fingerprint = get_fingerprint # only need to get the fingerprint once because it is constant per-run
+      return api unless quantity > 1
+
+      values = Array(1.upto(quantity)) # create an array of the correct size
+      return values.collect { api } # fill array with hashes
+    end
+
+    ##
+    # Validates (minimally) the supplied string is in the correct format to be a hash
+    #
+    # Validation checks that the first letter is correct and that the rest of the
+    # string is the correct length and consists of lower case letters and numbers.
+    # 
+    # @param [String] str string to check
+    # @return [Boolean] returns true if the format is correct
+    def validate(str)
+      blen = BLOCK_SIZE * 6
+      !!str.match(/#{LETTER}[a-z0-9]{#{blen}}/)
+    end
+   
+    private
+
+    ##
+    # Collects and asssembles the pieces into the actual hash string.
+    #
+    # @private
+    def api
+      timestamp = (Time.now.to_f * 1000).truncate.to_s(BASE)
+
+      random = get_random_block
+
+      @count = @count % DISCRETE_VALUES
+      counter = pad(@count.to_s(BASE))
+
+      @count += 1
+      
+      return (LETTER + timestamp + counter + @fingerprint + random)
+    end
+    
+    ##
+    # Returns a string which has been converted to the correct size alphabet as defined in
+    # the BASE constant (e.g. base36) and then padded or trimmed to the correct length.
+    #
+    # @private
+    def format(text,size=BLOCK_SIZE)
+      base36_text = text.to_s(BASE)
+      return (base36_text.length > size) ? trim(base36_text,size) : pad(base36_text,size)
+    end
+
+    ##
+    # Returns a string trimmed to the length supplied or BLOCK_SIZE if no length is supplied.
+    #
+    # @private
+    def trim(text,max=BLOCK_SIZE)
+      original_length = text.length
+      return text[original_length-max,max]
+    end
+
+    ##
+    # Returns a string right-justified and padded with zeroes up to the length supplied or
+    # BLOCK_SIZE if no length is supplied.
+    #
+    # @private
+    def pad(text,size=BLOCK_SIZE)
+      return text.rjust(size,"0")
+    end
+
+    ##
+    # Generates a random string.
+    #
+    # @private
+    def get_random_block
+      @secure_random = defined?(SecureRandom) if @secure_random.nil?
+      if @secure_random && @use_secure_random then
+        number = SecureRandom.random_number(RAND_MAX - RAND_MIN) + RAND_MIN
+      else
+        number = ((rand * (RAND_MAX - RAND_MIN)) + RAND_MIN)
+      end
+      return number.truncate.to_s(BASE)
+    end
+
+    ##
+    # Assembles the host fingerprint based on the hostname and the PID.
+    #
+    # @private
+    def get_fingerprint
+      padding = 2
+      hostname = Socket.gethostname
+      hostid = hostname.split('').inject(hostname.length+BASE) do |a,i|
+        a += (i.respond_to? "ord") ? i.ord : i[0]
+      end
+      return format($$, padding) + format(hostid, padding)
+    end
+
+  end
+end

data/lib/cuid/version.rb

@@ -0,0 +1,3 @@
+module Cuid
+  VERSION = "1.0.0"
+end

data/test/test_cuid.rb

@@ -0,0 +1,58 @@
+require 'cuid'
+require 'test/unit'
+
+class CuidTest < Test::Unit::TestCase
+  def test_generate_string
+    c = Cuid::generate
+    assert c.is_a? String
+  end
+
+  def test_generate_array
+    c = Cuid::generate(3)
+    assert c.is_a? Array
+    assert_equal 3, c.size
+  end
+
+  def test_generate_format
+    c = Cuid::generate
+    assert_equal 25, c.length
+    assert c.start_with? "c"
+  end
+
+  def test_validate_true
+    c = Cuid::generate
+    assert Cuid::validate(c)
+  end
+
+  def test_valiate_false
+    c = "d00000000000000000000"
+    assert !Cuid::validate(c)
+  end
+
+  def test_collision
+    results = {}
+    collision = false
+    c = Cuid::generate(600000)
+    c.each do |e|
+      collision = true if results[e]
+      results[e] = true
+    end
+    assert !collision
+  end
+
+  def test_secure_random
+    results = {}
+    collision = false
+    c = Cuid::generate(1000,true)
+    c.each do |e|
+      collision = true if results[e]
+      results[e] = true
+    end
+    assert !collision
+  end
+
+  def test_version
+    assert_nothing_raised { Cuid::VERSION }
+  end
+end
+

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: cuid
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Ian Shannon
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-12-15 00:00:00.000000000 Z
+dependencies: []
+description: Ruby implementation of Eric Elliot's javascript cuid
+email:
+- iyshannon@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rbenv-version
+- .travis.yml
+- .yardopts
+- Gemfile
+- README.md
+- Rakefile
+- cuid.gemspec
+- doc/index.html
+- lib/cuid.rb
+- lib/cuid/version.rb
+- test/test_cuid.rb
+homepage: http://github.com/iyshannon/cuid
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Collision-resistant ids optimized for horizontal scaling and performance
+test_files: []
+has_rdoc: