clandestined 1.0.0a → 1.0.0b

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 47d9cefad2b6c0c74a35295e37f64aa81f8bca19
-  data.tar.gz: ce0099265bc7b8b3929228550a657edc1057e027
+  metadata.gz: 03d6d29e1c5fe16b7457ae7ae9d851a55ad2c03e
+  data.tar.gz: 9ce134bb758d8f00442ac45a1b592ccbe143f04c
 SHA512:
-  metadata.gz: cd241d8e5896d6608f81477ea23ec575bc9f55e71ca3917705a4217cf7d84a22e5c916271413d6d42a4bd2e81a73af34c4b1bd9ae57ae72a10346dbb84804b26
-  data.tar.gz: f343ef64e349cc3805b1f8e994fc9bc95865e150fad80e15f75840511f90ff7e3250bf66d3e01da69594e413f236097f78b63a57f31242672a43c2c5c8c8cf9d
+  metadata.gz: ccdcbbbd4d4d9524cbb61a21efa5d3389da3ad6b7b366c1d1d6273a7da265686a600ece76eb1a8d68e6955761fcb3ec82323747a8ee9c6c2ef76d2fb4d4e09f3
+  data.tar.gz: 04e1699336e8e5b08e0d75207d80308955e86986dafd79c1cd2d8b7ae3ec1b94de470e26cc6e88aea31c9bdf06606df2a06769737faa00ee6cb70383d8cc400d

data/CHANGES.md

@@ -0,0 +1,16 @@
+
+v1.0.0b (2014-07-07)
+====================
+
+  - `Cluster.remove_zone` now raises `ArgumentError` on attempt to remove a
+     non-existent zone.
+  - `Cluster.remove_node` and `RendezvousHash.remove_node` now raise
+    `ArgumentError` on attempt to remove  a non-existent node.
+  - Support for custom hash functions retracted for 1.0.0 milestone.
+  - `murmur_seed` keyword argument renamed to `seed` for `Cluster` and
+    `RendezvousHash` `initialize` methods.
+
+v1.0.0a (2014-07-06)
+====================
+
+  - Initial Release.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Ernest W. Durbin III
+
+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

@@ -36,7 +36,7 @@ Currently targetting for support:
      '9' => Hash['name' => 'node9.example.com', 'zone' => 'us-east-1c'],
      ]
 >>
->> cluster = Cluster.new(nodes)
+>> cluster = Clandestined::Cluster.new(nodes)
 >> cluster.find_nodes('mykey')
 => ["4", "8"]
 ```
@@ -64,8 +64,8 @@ set to 1
      '9' => Hash['name' => 'node9.example.com'],
      ]
 >>
->> cluster = Cluster.new(nodes, 1)
->> rendezvous = RendezvousHash.new(nodes.keys)
+>> cluster = Clandestined::Cluster.new(nodes, 1)
+>> rendezvous = Clandestined::RendezvousHash.new(nodes.keys)
 >>
 >> cluster.find_nodes('mykey')
 => ["4"]
@@ -77,47 +77,19 @@ set to 1
 
 ### murmur3 seeding
 
-if you plan to use keys based on untrusted input (not really supported, but go
-ahead), it would be best to use a custom seed for hashing. although this
-technique is by no means a way to fully mitigate a DoS attack using crafted
-keys, it may make you sleep better at night.
+if you plan to use keys based on untrusted input (supported, but go ahead),
+it would be best to use a custom seed for hashing. although this technique is
+by no means a way to fully mitigate a DoS attack using crafted keys, it may
+help you sleep better at night.
 
-```ruby
->> require 'clandestined/cluster'
->> require 'clandestined/rendezvous_hash'
->>
->> nodes = Hash[
-     '1' => Hash['name' => 'node1.example.com'],
-     '2' => Hash['name' => 'node2.example.com'],
-     '3' => Hash['name' => 'node3.example.com'],
-     '4' => Hash['name' => 'node4.example.com'],
-     '5' => Hash['name' => 'node5.example.com'],
-     '6' => Hash['name' => 'node6.example.com'],
-     '7' => Hash['name' => 'node7.example.com'],
-     '8' => Hash['name' => 'node8.example.com'],
-     '9' => Hash['name' => 'node9.example.com'],
-     ]
->>
->> cluster = Cluster.new(nodes, 1, 1337)
->> rendezvous = RendezvousHash.new(nodes.keys, 1337)
->>
->> cluster.find_nodes('mykey')
-=> ["7"]
->> rendezvous.find_node('mykey')
-=> "7"
-```
-
-### supplying your own hash function
+**DISCLAIMER**
 
-a more robust, but possibly slower solution to mitigate DoS vulnerability by
-crafted key might be to supply your own cryptograpic hash function.
+clandestined was not designed with consideration for untrusted input, please
+see LICENSE.
 
-in order for this to work, your method must be supplied to the `RendezvousHash`
-or `Cluster` object as a callable which takes a byte string `key` and returns
-an integer.
+**END DISCLAIMER**
 
 ```ruby
->> require 'digest'
 >> require 'clandestined/cluster'
 >> require 'clandestined/rendezvous_hash'
 >>
@@ -133,15 +105,11 @@ an integer.
      '9' => Hash['name' => 'node9.example.com'],
      ]
 >>
->> def my_hash_function(key)
-     Digest::SHA1.hexdigest(key).to_i(16)
-     end
->>
->> cluster = Cluster.new(nodes, 1, 0, method(:my_hash_function))
->> rendezvous = RendezvousHash.new(nodes.keys, 0, method(:my_hash_function))
+>> cluster = Clandestined::Cluster.new(nodes, 1, 1337)
+>> rendezvous = Clandestined::RendezvousHash.new(nodes.keys, 1337)
 >>
 >> cluster.find_nodes('mykey')
-=> ["1"]
+=> ["7"]
 >> rendezvous.find_node('mykey')
-=> "1"
+=> "7"
 ```

data/clandestined.gemspec

@@ -1,6 +1,7 @@
 Gem::Specification.new do |s|
   s.name = 'clandestined'
-  s.version = '1.0.0a'
+  s.version = '1.0.0b'
+  s.licenses = ['MIT']
   s.date = Time.now.strftime('%Y-%m-%d')
   s.summary = 'rendezvous hashing implementation based on murmur3 hash'
   s.author = "Ernest W. Durbin III"

data/lib/clandestined/cluster.rb

@@ -2,110 +2,101 @@
 require 'clandestined/rendezvous_hash'
 require 'murmur3'
 
-class Cluster
-
-  include Murmur3
-
-  attr_reader :hash_function
-  attr_reader :murmur_seed
-  attr_reader :replicas
-  attr_reader :nodes
-  attr_reader :zones
-  attr_reader :zone_members
-  attr_reader :rings
-
-  def initialize(cluster_config=nil, replicas=2, murmur_seed=0, hash_function=method(:murmur3_32))
-    @murmur_seed = murmur_seed
-
-    if hash_function == method(:murmur3_32)
-      @hash_function = lambda { |key| hash_function.call(key, murmur_seed) }
-    elsif murmur_seed != 0
-      raise ArgumentError, 'Cannot apply seed to custom hash function #{hash_function}'
-    else
-      @hash_function = hash_function
-    end
-
-    @replicas = replicas
-    @nodes = Hash[]
-    @zones = []
-    @zone_members = Hash[]
-    @rings = Hash[]
-
-    if cluster_config
-      cluster_config.each do |node, node_data|
-        name = node_data['name']
-        zone = node_data['zone']
-        add_zone(zone)
-        add_node(node, zone, name)
+module Clandestined
+  class Cluster
+
+    include Murmur3
+
+    attr_reader :hash_function
+    attr_reader :seed
+    attr_reader :replicas
+    attr_reader :nodes
+    attr_reader :zones
+    attr_reader :zone_members
+    attr_reader :rings
+
+    def initialize(cluster_config=nil, replicas=2, seed=0)
+      @seed = seed
+
+      @replicas = replicas
+      @nodes = Hash[]
+      @zones = []
+      @zone_members = Hash[]
+      @rings = Hash[]
+
+      if cluster_config
+        cluster_config.each do |node, node_data|
+          name = node_data['name']
+          zone = node_data['zone']
+          add_zone(zone)
+          add_node(node, zone, name)
+        end
       end
     end
-  end
 
-  def add_zone(zone)
-    @zones.push(zone) unless zones.include?(zone)
-    unless zone_members.has_key?(zone)
-      @zone_members[zone] = []
+    def add_zone(zone)
+      @zones.push(zone) unless zones.include?(zone)
+      @zone_members[zone] ||= []
+      @zones.sort!
     end
-    @zones.sort!
-  end
 
-  def remove_zone(zone)
-    if zones.include?(zone)
-      @zones.delete(zone)
-      for member in zone_members[zone]
-        @nodes.delete(member)
+    def remove_zone(zone)
+      if zones.include?(zone)
+        @zones.delete(zone)
+        for member in zone_members[zone]
+          @nodes.delete(member)
+        end
+        @zones.sort!
+        @rings.delete(zone)
+        @zone_members.delete(zone)
+      else
+        raise ArgumentError, "No such zone #{zone} to remove"
       end
-      @zones.sort!
-      @rings.delete(zone)
-      @zone_members.delete(zone)
     end
-  end
 
-  def add_node(node_id, node_zone=nil, node_name=nil)
-    if nodes.include?(node_id)
+    def add_node(node_id, node_zone=nil, node_name=nil)
+      if nodes.include?(node_id)
         raise ArgumentError, 'Node with id #{node_id} already exists'
+      end
+      add_zone(node_zone)
+      unless rings.has_key?(node_zone)
+        @rings[node_zone] = RendezvousHash.new(nil, seed)
+      end
+      @rings[node_zone].add_node(node_id)
+      @nodes[node_id] = node_name
+      (@zone_members[node_zone] ||= []) << node_id
     end
-    add_zone(node_zone)
-    unless rings.has_key?(node_zone)
-      @rings[node_zone] = RendezvousHash.new(nil, 0, self.hash_function)
-    end
-    @rings[node_zone].add_node(node_id)
-    @nodes[node_id] = node_name
-    unless zone_members.has_key?(node_zone)
-      @zone_members[node_zone] = []
-    end
-    @zone_members[node_zone].push(node_id)
-  end
 
-  def remove_node(node_id, node_zone=nil, node_name=nil)
-    @rings[node_zone].remove_node(node_id)
-    @nodes.delete(node_id)
-    @zone_members[node_zone].delete(node_id)
-    if zone_members[node_zone].length == 0
+    def remove_node(node_id, node_zone=nil, node_name=nil)
+      @rings[node_zone].remove_node(node_id)
+      @nodes.delete(node_id)
+      @zone_members[node_zone].delete(node_id)
+      if zone_members[node_zone].length == 0
         remove_zone(node_zone)
+      end
     end
-  end
 
-  def node_name(node_id)
-    nodes[node_id]
-  end
+    def node_name(node_id)
+      nodes[node_id]
+    end
 
-  def find_nodes(search_key, offset=nil)
-    nodes = []
-    unless offset
-      offset = search_key.split("").map{|char| char[0,1].unpack('c')[0]}.inject(0) {|sum, i|  sum + i }
+    def find_nodes(search_key, offset=nil)
+      nodes = []
+      unless offset
+        offset = search_key.split('').inject(0) { |s, c| s += c[0,1].unpack('c')[0] }
+      end
+      for i in (0...replicas)
+        zone = zones[(i + offset.to_i) % zones.length]
+        nodes << rings[zone].find_node(search_key)
+      end
+      nodes
     end
-    for i in (0...replicas)
-      zone = zones[(i + offset.to_i) % zones.length]
-      nodes << rings[zone].find_node(search_key)
+
+    def find_nodes_by_index(product_id, block_index)
+      offset = (product_id.to_i + block_index.to_i) % zones.length
+      search_key = "#{product_id}-#{block_index}"
+      find_nodes(search_key, offset)
     end
-    nodes
-  end
 
-  def find_nodes_by_index(product_id, block_index)
-    offset = (product_id.to_i + block_index.to_i) % zones.length
-    search_key = "#{product_id}-#{block_index}"
-    find_nodes(search_key, offset)
   end
-
 end

data/lib/clandestined/rendezvous_hash.rb

@@ -1,37 +1,37 @@
 require 'murmur3'
 
-class RendezvousHash
+module Clandestined
+  class RendezvousHash
 
-  include Murmur3
+    include Murmur3
 
-  attr_reader :nodes
-  attr_reader :murmur_seed
-  attr_reader :hash_function
+    attr_reader :nodes
+    attr_reader :seed
+    attr_reader :hash_function
 
-  def initialize(nodes=nil, murmur_seed=0, hash_function=method(:murmur3_32))
-    @nodes = nodes || []
-    @murmur_seed = murmur_seed
+    def initialize(nodes=nil, seed=0)
+      @nodes = nodes || []
+      @seed = seed
+
+      @hash_function = lambda { |key| murmur3_32(key, seed) }
 
-    if hash_function == method(:murmur3_32)
-      @hash_function = lambda { |key| hash_function.call(key, murmur_seed) }
-    elsif murmur_seed != 0
-      raise ArgumentError, "Cannot apply seed to custom hash function #{hash_function}"
-    else
-      @hash_function = hash_function
     end
 
-  end
+    def add_node(node)
+      @nodes.push(node) unless @nodes.include?(node)
+    end
 
-  def add_node(node)
-    @nodes.push(node) unless @nodes.include?(node)
-  end
+    def remove_node(node)
+      if @nodes.include?(node)
+        @nodes.delete(node)
+      else
+        raise ArgumentError, "No such node #{node} to remove"
+      end
+    end
 
-  def remove_node(node)
-    @nodes.delete(node) if @nodes.include?(node)
-  end
+    def find_node(key)
+      nodes.max {|a,b| hash_function.call("#{a}-#{key}") <=> hash_function.call("#{b}-#{key}")}
+    end
 
-  def find_node(key)
-    nodes.max {|a,b| hash_function.call("#{a}-#{key}") <=> hash_function.call("#{b}-#{key}")}
   end
-
 end

data/test/test_cluster.rb

@@ -4,15 +4,14 @@ require 'set'
 
 require 'clandestined/cluster'
 
-def my_hash_function(key)
-  Digest::MD5.hexdigest(key).to_i(16)
-end
+include Clandestined
+
 
 class ClusterTestCase < Test::Unit::TestCase
 
   def test_init_no_options
     cluster = Cluster.new()
-    assert_equal(1361238019, cluster.hash_function.call('6666'))
+    assert_equal(0, cluster.seed)
     assert_equal(2, cluster.replicas)
     assert_equal(Hash[], cluster.nodes)
     assert_equal([], cluster.zones)
@@ -22,16 +21,7 @@ class ClusterTestCase < Test::Unit::TestCase
 
   def test_murmur_seed
     cluster = Cluster.new(nil, 2, 10)
-    assert_equal(2981722772, cluster.hash_function.call('6666'))
-  end
-
-  def test_custom_hash_function
-      cluster = Cluster.new(nil, 2, 0, method(:my_hash_function))
-      assert_equal(310130709337150341200260887719094037511, cluster.hash_function.call('6666'))
-  end
-
-  def test_seeded_custom_hash_function
-    assert_raises(ArgumentError) { Cluster.new(nil, 2, 10, method(:my_hash_function)) }
+    assert_equal(10, cluster.seed)
   end
 
   def test_init_single_zone
@@ -430,6 +420,7 @@ class ClusterIntegrationTestCase < Test::Unit::TestCase
     cluster.remove_node('6', 'c', 'node6')
     cluster.remove_node('11', 'c', 'node11')
     cluster.remove_node('12', 'c', 'node12')
+    assert_raises(ArgumentError) {cluster.remove_zone('c')}
 
     new_placements = Hash[]
     for i in cluster.nodes.keys

data/test/test_rendezvous_hash.rb

@@ -4,9 +4,8 @@ require 'set'
 
 require 'clandestined/rendezvous_hash'
 
-def my_hash_function(key)
-  Digest::MD5.hexdigest(key).to_i(16)
-end
+include Clandestined
+
 
 class RendezvousHashTestCase < Test::Unit::TestCase
 
@@ -23,20 +22,12 @@ class RendezvousHashTestCase < Test::Unit::TestCase
     assert_equal(1361238019, rendezvous.hash_function.call('6666'))
   end
 
-  def test_murmur_seed
+  def test_seed
     rendezvous = RendezvousHash.new(nil, 10)
+    assert_equal(10, rendezvous.seed)
     assert_equal(2981722772, rendezvous.hash_function.call('6666'))
   end
 
-  def test_custom_hash_function
-      rendezvous = RendezvousHash.new(nil, 0, method(:my_hash_function))
-      assert_equal(310130709337150341200260887719094037511, rendezvous.hash_function.call('6666'))
-  end
-
-  def test_seeded_custom_hash_function
-    assert_raises(ArgumentError) { RendezvousHash.new(nil, 10, method(:my_hash_function)) }
-  end
-
   def test_add_node
     rendezvous = RendezvousHash.new()
     rendezvous.add_node('1')
@@ -54,7 +45,7 @@ class RendezvousHashTestCase < Test::Unit::TestCase
     rendezvous = RendezvousHash.new(nodes)
     rendezvous.remove_node('2')
     assert_equal(2, rendezvous.nodes.length)
-    rendezvous.remove_node('2')
+    assert_raises(ArgumentError) { rendezvous.remove_node(2, rendezvous.nodes.length) }
     assert_equal(2, rendezvous.nodes.length)
     rendezvous.remove_node('1')
     assert_equal(1, rendezvous.nodes.length)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clandestined
 version: !ruby/object:Gem::Version
-  version: 1.0.0a
+  version: 1.0.0b
 platform: ruby
 authors:
 - Ernest W. Durbin III
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-06 00:00:00.000000000 Z
+date: 2014-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -62,8 +62,10 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .travis.yml
+- CHANGES.md
 - Gemfile
 - Gemfile.lock
+- LICENSE
 - README.md
 - Rakefile
 - clandestined.gemspec
@@ -76,7 +78,8 @@ files:
 - test/test_cluster.rb
 - test/test_rendezvous_hash.rb
 homepage: https://github.com/ewdurbin/clandestined-ruby
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []