hashids 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hashids.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Peter Hellberg
+
+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,202 @@
+# Hashids
+
+A small Ruby gem to generate YouTube-like hashes from one or many numbers.
+Use hashids when you do not want to expose your database ids to the user.
+
+[http://www.hashids.org/ruby/](http://www.hashids.org/ruby/)
+
+## What is it?
+
+hashids (Hash ID's) creates short, unique, decryptable hashes from unsigned integers.
+
+It was designed for websites to use in URL shortening, tracking stuff, or 
+making pages private (or at least unguessable).
+
+This algorithm tries to satisfy the following requirements:
+
+1. Hashes must be unique and decryptable.
+2. They should be able to contain more than one integer (so you can use them in complex or clustered systems).
+3. You should be able to specify minimum hash length.
+4. Hashes should not contain basic English curse words (since they are meant to appear in public places - like the URL).
+
+Instead of showing items as `1`, `2`, or `3`, you could show them as `U6dc`, `u87U`, and `HMou`.
+You don't have to store these hashes in the database, but can encrypt + decrypt on the fly.
+
+All integers need to be greater than or equal to zero.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'hashids'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hashids
+
+## Usage
+
+#### Encrypting one number
+
+You can pass a unique salt value so your hashes differ from everyone else's. I use "**this is my salt**" as an example.
+
+```ruby
+hashids = Hashids.new("this is my salt")
+hash = hashids.encrypt(12345)
+```
+
+`hash` is now going to be:
+
+    ryBo
+
+#### Decrypting
+
+Notice during decryption, same salt value is used:
+
+```ruby
+hashids = Hashids.new("this is my salt")
+numbers = hashids.decrypt("ryBo")
+```
+
+`numbers` is now going to be:
+
+    [ 12345 ]
+
+#### Decrypting with different salt
+
+Decryption will not work if salt is changed:
+
+```ruby
+hashids = Hashids.new("this is my pepper")
+numbers = hashids.decrypt("ryBo")
+```
+
+`numbers` is now going to be:
+
+    []
+
+#### Encrypting several numbers
+
+```ruby
+hashids = Hashids.new("this is my salt")
+hash = hashids.encrypt(683, 94108, 123, 5)
+```
+
+`hash` is now going to be:
+
+    zBphL54nuMyu5
+  
+#### Decrypting is done the same way
+
+```ruby
+hashids = Hashids.new("this is my salt")
+numbers = hashids.decrypt("zBphL54nuMyu5")
+```
+
+`numbers` is now going to be:
+
+    [ 683, 94108, 123, 5 ]
+
+#### Encrypting and specifying minimum hash length
+
+Here we encrypt integer 1, and set the minimum hash length to **8** (by default it's **0** -- meaning hashes will be the shortest possible length).
+
+```ruby
+hashids = Hashids.new("this is my salt", 8)
+hash = hashids.encrypt(1)
+```
+
+`hash` is now going to be:
+
+    b9iLXiAa
+
+#### Decrypting
+
+```ruby
+hashids = Hashids.new("this is my salt", 8)
+numbers = hashids.decrypt("b9iLXiAa")
+```
+
+`numbers` is now going to be:
+
+    [ 1 ]
+
+#### Specifying custom hash alphabet
+
+Here we set the alphabet to consist of only four letters: "abcd"
+
+```ruby
+hashids = Hashids.new("this is my salt", 0, "abcd")
+hash = hashids.encrypt(1, 2, 3, 4, 5)
+```
+
+`hash` is now going to be:
+
+    adcdacddcdaacdad
+
+## Randomness
+
+The primary purpose of hashids is to obfuscate ids. It's not meant or tested to be used for security purposes or compression.
+Having said that, this algorithm does try to make these hashes unguessable and unpredictable:
+
+#### Repeating numbers
+
+```ruby
+hashids = Hashids.new("this is my salt")
+hash = hashids.encrypt(5, 5, 5, 5)
+```
+
+You don't see any repeating patterns that might show there's 4 identical numbers in the hash:
+
+    GLh5SMs9
+
+Same with incremented numbers:
+
+```ruby
+hashids = Hashids.new("this is my salt")
+hash = hashids.encrypt(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+```
+
+`hash` will be :
+
+    zEUzfySGIpuyhpF6HaC7
+
+### Incrementing number hashes:
+
+```ruby
+hashids = Hashids.new("this is my salt")
+
+hashids.encrypt 1 #=> LX
+hashids.encrypt 2 #=> ed
+hashids.encrypt 3 #=> o9
+hashids.encrypt 4 #=> 4n
+hashids.encrypt 5 #=> a5
+```
+
+## Changelog
+
+**0.0.1**
+  
+- First commit (Heavily based on the [CoffeeScript version](https://github.com/ivanakimov/hashids.coffee))
+
+## Contact
+
+Follow me [@peterhellberg](http://twitter.com/peterhellberg)
+
+Or [http://c7.se/](http://c7.se/)
+
+## License
+
+MIT License. See the `LICENSE.txt` file.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,8 @@
+require "rake/testtask"
+require "bundler/gem_tasks"
+
+task :default => :spec
+
+Rake::TestTask.new(:spec) do |t|
+  t.test_files = FileList['spec/**/*_spec.rb']
+end

data/hashids.gemspec

@@ -0,0 +1,18 @@
+# encoding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hashids'
+
+Gem::Specification.new do |gem|
+  gem.name          = "hashids"
+  gem.version       = Hashids::VERSION
+  gem.authors       = ["Peter Hellberg"]
+  gem.email         = ["peter@c7.se"]
+  gem.summary       = %q{Generate YouTube-like hashes from one or many numbers.}
+  gem.description   = %q{Use hashids when you do not want to expose your database ids to the user.}
+  gem.homepage      = "https://github.com/peterhellberg/hashids.rb"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.test_files    = gem.files.grep(%r{^(spec)/})
+  gem.require_paths = ["lib"]
+end

data/lib/hashids.rb

@@ -0,0 +1,264 @@
+# encoding: utf-8
+
+class Hashids
+  VERSION          = "0.0.1"
+  DEFAULT_ALPHABET = "xcS4F6h89aUbideAI7tkynuopqrXCgTE5GBKHLMjfRsz"
+  PRIMES           = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43]
+
+  class SaltError      < ArgumentError; end
+  class MinLengthError < ArgumentError; end
+  class AlphabetError  < ArgumentError; end
+
+  def initialize(salt = "", min_length = 0, alphabet = DEFAULT_ALPHABET)
+    @salt       = salt
+    @min_length = min_length
+    @alphabet   = alphabet
+
+    validate_attributes
+    setup_alphabet
+  end
+
+  def encrypt(*numbers)
+    return "" unless numbers.any?
+
+    numbers.each do |number|
+      return "" if !number.kind_of?(Fixnum) || number < 0
+    end
+
+    encode(numbers, @alphabet, @salt, @min_length)
+  end
+
+  def decrypt(hash)
+    hash.empty? ? [] : decode(hash)
+  end
+
+  private
+
+  def validate_attributes
+    unless @salt.kind_of?(String)
+      raise Hashids::SaltError, "The salt must be a String"
+    end
+
+    unless @min_length.kind_of?(Fixnum)
+      raise Hashids::MinLengthError, "The min length must be a Fixnum"
+    end
+
+    unless @alphabet.kind_of?(String)
+      raise Hashids::AlphabetError, "The alphabet must be a String"
+    end
+  end
+
+  def setup_alphabet
+    @seps   = []
+    @guards = []
+
+    @alphabet = @alphabet.split('').uniq.join
+
+    if @alphabet.length < 4
+      raise AlphabetError, "Alphabet must contain at least 4 unique characters."
+    end
+
+    PRIMES.each do |prime|
+      char = @alphabet[prime - 1]
+
+      break if char.nil?
+
+      @seps.push char
+      @alphabet.gsub!(char, ' ')
+    end
+
+    [0, 4, 8, 12].each do |index|
+      separator = @seps[index]
+
+      unless separator.nil?
+        @guards.push(separator)
+        @seps.delete_at(index)
+      end
+    end
+
+    @alphabet.gsub!(' ', '')
+    @alphabet = consistent_shuffle(@alphabet, @salt)
+  end
+
+  def encode(numbers, alphabet, salt, min_length = 0)
+    ret = ""
+
+    seps = consistent_shuffle(@seps, numbers).split("")
+    lottery_char = ""
+
+    numbers.each_with_index do |number, i|
+      if i == 0
+        lottery_salt = numbers.join('-')
+        numbers.each { |n| lottery_salt += "-" + ((n.to_i + 1) * 2).to_s }
+
+        lottery = consistent_shuffle(alphabet, lottery_salt)
+
+        ret += lottery_char = lottery[0]
+
+        alphabet = lottery_char + alphabet.gsub(lottery_char, '')
+      end
+
+      alphabet = consistent_shuffle(alphabet, "#{lottery_char.ord & 12345}#{salt}")
+      ret += hash(number, alphabet)
+
+      if (i + 1) < numbers.length
+        seps_index = (number + i) % seps.length
+        ret += seps[seps_index]
+      end
+    end
+
+    if ret.length < min_length
+      first_index = 0
+      numbers.each_with_index do |number, i|
+        first_index += (i + 1) * number
+      end
+
+      guard_index = first_index % @guards.length
+      guard = @guards[guard_index]
+
+      ret = guard + ret
+
+      if ret.length < min_length
+        guard_index = (guard_index + ret.length) % @guards.length
+        guard = @guards[guard_index]
+
+        ret += guard
+      end
+    end
+
+    while ret.length < min_length
+      pad_array = [alphabet[1].ord, alphabet[0].ord]
+      pad_left = encode(pad_array, alphabet, salt)
+      pad_right = encode(pad_array, alphabet, pad_array.join(''))
+
+      ret = pad_left + ret + pad_right
+      excess = ret.length - min_length
+
+      ret = ret[(excess/2), min_length] if excess > 0
+      alphabet = consistent_shuffle(alphabet, salt + ret)
+    end
+
+    ret
+  end
+
+  def decode(hash)
+    ret = []
+
+    if hash.length > 0
+      original_hash = hash
+      alphabet = ""
+      lottery_char = ""
+
+      @guards.each do |guard|
+        hash = hash.gsub(guard, ' ')
+      end
+
+      hash_split = hash.split(' ')
+
+      hash = hash_split[[3,2].include?(hash_split.length) ? 1 : 0]
+
+      @seps.each do |sep|
+        hash = hash.gsub(sep, ' ')
+      end
+
+      hash_array = hash.split(' ')
+
+      hash_array.each_with_index do |sub_hash, i|
+        if sub_hash.length > 0
+          if i == 0
+            lottery_char = hash[0]
+            sub_hash = sub_hash[1..-1]
+            alphabet = lottery_char + @alphabet.gsub(lottery_char, "")
+          end
+
+          if alphabet.length > 0 && lottery_char.length > 0
+            alphabet = consistent_shuffle(alphabet, (lottery_char.ord & 12345).to_s + "" + @salt)
+            ret.push unhash(sub_hash, alphabet)
+          end
+        end
+      end
+
+      ret = [] if encrypt(*ret) != original_hash
+    end
+
+    ret
+  end
+
+  def consistent_shuffle(alphabet, salt)
+    ret = ""
+
+    alphabet = alphabet.join "" if alphabet.respond_to? :join
+    salt = salt.join "" if salt.respond_to? :join
+
+    alphabet_array = alphabet.split('')
+    salt_array = salt.split('')
+    sorting_array = []
+
+    salt_array.push "" unless salt_array.any?
+
+    salt_array.each do |salt_char|
+      sorting_array.push salt_char.ord || 0
+    end
+
+    sorting_array.each_with_index do |int,i|
+      add = true
+      k   = i
+
+      while k != (sorting_array.length + i - 1)
+        next_index = (k + 1) % sorting_array.length
+
+        if add
+          sorting_array[i] += sorting_array[next_index] + (k * i)
+        else
+          sorting_array[i] -= sorting_array[next_index]
+        end
+
+        add = !add
+        k += 1
+      end
+
+      sorting_array[i] = sorting_array[i].abs
+    end
+
+    i = 0
+
+    while alphabet_array.length > 0
+      alphabet_size = alphabet_array.length
+      pos = sorting_array[i]
+      pos %= alphabet_size if pos >= alphabet_size
+      ret += alphabet_array[pos]
+
+      alphabet_array.delete_at(pos)
+      i = (i+1) % sorting_array.length
+    end
+
+    ret
+  end
+
+  def hash(number, alphabet)
+    hash = ""
+    alphabet_length = alphabet.length
+
+    while number > 0
+      hash   = alphabet[number % alphabet_length] + hash
+      number = number / alphabet_length
+    end
+
+    hash
+  end
+
+  def unhash(hash, alphabet)
+    number = 0
+
+    hash.split('').each_with_index { |char, i|
+      pos = alphabet.index char
+
+      return if pos.nil?
+
+      number += pos * alphabet.length ** (hash.length - i - 1)
+    }
+
+    number
+  end
+
+end

data/spec/hashids_spec.rb

@@ -0,0 +1,164 @@
+# encoding: utf-8
+
+require "minitest/spec"
+require "minitest/pride"
+require "minitest/autorun"
+
+require_relative "../lib/hashids"
+
+describe Hashids do
+  let(:salt)              { 'this is my salt' }
+  let(:hashids)           { Hashids.new(salt) }
+  let(:alphabet)          { "xgzXjp48RaoeLdB6yrAMK9b5n7qEkG" }
+  let(:shuffled_alphabet) { "xMGAE6gXkpBR785zLraqnj49doyKeb" }
+  let(:default_alphabet)  { "xcS4F6h89aUbideAI7tkynuopqrXCgTE5GBKHLMjfRsz" }
+  let(:seps) { ["S", "F", "h", "U", "I", "t", "u", "C", "H", "f", "s"] }
+  let(:examples) {
+    {
+      'aa' => 155, 'ba' => 185, 'j9' => 814,
+      'ky' => 342, 'Xg' => 559, 'GB' => 683,
+      'B4' => 691, '9Xg' => 4159, 'jAz' => 24599
+    }
+  }
+
+  describe "setup" do
+    it "has a default alphabet" do
+      Hashids::DEFAULT_ALPHABET.must_equal default_alphabet
+    end
+
+    it "has the correct salt" do
+      hashids.instance_variable_get(:@salt).must_equal salt
+    end
+
+    it "defaults to a min_length of 0" do
+      hashids.instance_variable_get(:@min_length).must_equal 0
+    end
+
+    it "generates the correct @seps" do
+      hashids.instance_variable_get(:@seps).must_equal seps
+    end
+
+    it "generates the correct @guards" do
+      hashids.instance_variable_get(:@guards).must_equal ["c", "i", "T"]
+    end
+
+    it "generates the correct alphabet" do
+      hashids.instance_variable_get(:@alphabet).must_equal alphabet
+    end
+  end
+
+  describe "encrypt" do
+    it "encrypts a single number" do
+      hashids.encrypt(12345).must_equal 'ryBo'
+
+      hashids.tap { |h|
+        h.encrypt(-1).must_equal   ''
+        h.encrypt(1).must_equal    'LX'
+        h.encrypt(22).must_equal   '5B'
+        h.encrypt(333).must_equal  'o49'
+        h.encrypt(9999).must_equal 'GKnB'
+      }
+    end
+
+    it "can encrypt a list of numbers" do
+      hashids.encrypt(683, 94108, 123, 5).must_equal 'zBphL54nuMyu5'
+
+      hashids.tap { |h|
+        h.encrypt(1,2,3).must_equal 'eGtrS8'
+        h.encrypt(2,4,6).must_equal '9Kh7fz'
+        h.encrypt(99,25).must_equal 'dAECX'
+      }
+    end
+
+    it "returns an empty string if no numbers" do
+      hashids.encrypt.must_equal ""
+    end
+
+    it "returns an empty string if any of the numbers are negative" do
+      hashids.encrypt(-1).must_equal ""
+      hashids.encrypt(10,-10).must_equal ""
+    end
+
+    it "can encrypt to a minumum length" do
+      h = Hashids.new(salt, 8)
+      h.encrypt(1).must_equal "b9iLXiAa"
+    end
+
+    it "can encrypt with a custom alphabet" do
+      h = Hashids.new(salt, 0, "abcd")
+      h.encrypt(1,2,3,4,5).must_equal 'adcdacddcdaacdad'
+    end
+
+    it "doesn’t produce repeating patterns for identical numbers" do
+      hashids.encrypt(5,5,5,5).must_equal 'GLh5SMs9'
+    end
+
+    it "doesn’t produce repeating patterns for incremented numbers" do
+      hashids.encrypt(*(1..10).to_a).must_equal 'zEUzfySGIpuyhpF6HaC7'
+    end
+
+    it "doesn’t produce similarities between incrementing number hashes" do
+      hashids.encrypt(1).must_equal 'LX'
+      hashids.encrypt(2).must_equal 'ed'
+      hashids.encrypt(3).must_equal 'o9'
+      hashids.encrypt(4).must_equal '4n'
+      hashids.encrypt(5).must_equal 'a5'
+    end
+  end
+
+  describe "decrypt" do
+    it "decrypts an encrypted number" do
+      hashids.decrypt("ryBo").must_equal [12345]
+
+      hashids.tap { |h|
+        h.decrypt('qkpA').must_equal [1337]
+        h.decrypt('6aX').must_equal [808]
+        h.decrypt('gz9').must_equal [303]
+      }
+    end
+
+    it "decrypts a list of encrypted numbers" do
+      hashids.decrypt('zBphL54nuMyu5').must_equal [683, 94108, 123, 5]
+
+      hashids.tap { |h|
+        h.decrypt('kEFy').must_equal [1, 2]
+        h.decrypt('Aztn').must_equal [6, 5]
+      }
+    end
+
+    it "doesn’t decrypt with a different salt" do
+      peppers = Hashids.new('this is my pepper')
+      hashids.decrypt('ryBo').must_equal [12345]
+      peppers.decrypt('ryBo').must_equal []
+    end
+
+    it "can decrypt from a hash with a minimum length" do
+      h = Hashids.new(salt, 8)
+      h.decrypt("b9iLXiAa").must_equal [1]
+    end
+  end
+
+  describe "setup" do
+    it "raises an exception if the alphabet has less than 4 unique chars" do
+      -> { Hashids.new('salt', 0, 'abc') }.
+        must_raise Hashids::AlphabetError
+    end
+  end
+
+  describe "validation of attributes" do
+    it "raises an ArgumentError unless the salt is a String" do
+      -> { Hashids.new(:not_a_string) }.
+        must_raise Hashids::SaltError
+    end
+
+    it "raises an ArgumentError unless the min_length is a Fixnum" do
+      -> { Hashids.new('salt', :not_a_fixnum)}.
+        must_raise Hashids::MinLengthError
+    end
+
+    it "raises an ArgumentError unless the alphabet is a String" do
+      -> { Hashids.new('salt', 2, :not_a_string) }.
+        must_raise Hashids::AlphabetError
+    end
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: hashids
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Peter Hellberg
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-14 00:00:00.000000000 Z
+dependencies: []
+description: Use hashids when you do not want to expose your database ids to the user.
+email:
+- peter@c7.se
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- hashids.gemspec
+- lib/hashids.rb
+- spec/hashids_spec.rb
+homepage: https://github.com/peterhellberg/hashids.rb
+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: Generate YouTube-like hashes from one or many numbers.
+test_files:
+- spec/hashids_spec.rb
+has_rdoc: