consistent_hashing 0.1.0

data/spec/consistent_hashing_spec.rb

@@ -0,0 +1,143 @@
+require File.dirname(__FILE__) + '/../lib/consistent_hashing'
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "Servers list with a duplicate" do
+  it "should raise a collision error" do
+
+    server = new_mock_server("127.0.0.1:11211")
+    lambda {
+       m = ConsistentHashing::Continuum.new([server, server])
+    }.should raise_error(ConsistentHashing::CollisionError)
+  end
+end
+
+describe "A continuum (with no collisions)" do
+  before do
+    servers = [
+      "192.168.0.1:11211",
+      "192.168.0.2:11211",
+      "192.168.0.3:11211",
+      "192.168.0.4:11211",
+    ].map{|address| new_mock_server(address)}
+    @continuum = ConsistentHashing::Continuum.new(servers)
+    @first_anchor = @continuum.anchors.first
+    @last_anchor = @continuum.anchors.last
+  end
+
+  it "should use the first anchor for a search value in (last anchor value, 1]" do
+    search_values = some_values_in_segment(@last_anchor.value, 1.0)
+
+    search_values.each do |search_value|
+      responsible_anchor(@continuum, search_value).should == @first_anchor
+    end
+  end
+
+  it "should use the first anchor for a search value in (0, first anchor value]" do
+    search_values = some_values_in_segment(0.0, @first_anchor.value)
+
+    search_values.each do |search_value|
+      responsible_anchor(@continuum, search_value).should == @first_anchor
+    end
+  end
+
+  it "should find the correct server for search value in (first anchor value, last anchor value]" do
+    search_values = some_values_in_segment(@first_anchor.value, @last_anchor.value)
+
+    search_values.each do |search_value|
+      responsible_anchor = responsible_anchor(@continuum, search_value)
+
+      previous_anchor = previous_anchor(responsible_anchor, @continuum)
+
+      previous_anchor.value.should < search_value
+      search_value.should <= responsible_anchor.value
+    end
+  end
+
+  it "should have a method to return the server reponsible for a key" do
+    search_value = @continuum.hash_to_unit_circle("foo")
+    responsible_anchor = responsible_anchor(@continuum, search_value)
+
+    @continuum.find_server(search_value).should == responsible_anchor.server
+  end
+
+  it "should be able to calculate the expected load" do
+    servers = []
+    3.times do |i|
+      server = mock("server-#{i}")
+      server.stub!(:address).and_return("localhost:1121#{i}")
+      servers << server
+    end
+
+    # server[0]: [  0, 0.1], (0.4, 0.5], (0.9, 1.0] => 0.1 + 0.1 + 0.1 = 0.3
+    # server[1]: (0.1, 0.2], (0.5, 0.7]             => 0.1 + 0.2       = 0.3
+    # server[2]: (0.2, 0.4], (0.7, 0.9]             => 0.2 + 0.2       = 0.4
+    value_server_pairs = [
+      [0.1, servers[0]],
+      [0.2, servers[1]],
+      [0.4, servers[2]],
+      [0.5, servers[0]],
+      [0.7, servers[1]],
+      [0.9, servers[2]],
+    ]
+
+    anchors = value_server_pairs.map do |value, server|
+      ConsistentHashing::Anchor.new(value, server)
+    end
+
+    address_to_expected_load = {
+      servers[0].address => 0.3,
+      servers[1].address => 0.3,
+      servers[2].address => 0.4,
+    }
+
+    @continuum.stub!(:anchors).and_return(anchors)
+    expected_load = @continuum.expected_load
+
+    # all (key, value) pairs in the hash should be correct
+    expected_load.each do |address, load|
+      load.should be_close(address_to_expected_load[address], 0.0001)
+    end
+    
+    # the hash should be complete
+    expected_load.size.should == address_to_expected_load.size
+  end
+  
+  it "should have a to_s method" do
+    expected_lines = @continuum.anchors.map{|anchor| anchor.to_s}
+    @continuum.to_s.split("\n").should == expected_lines
+  end
+end
+
+describe "A Continuum::Anchor" do
+  before do
+    @value = 0.123
+    @address = "localhost:11211"
+
+    @server = mock('server')
+    @server.stub!(:address).and_return(@address)
+
+    @anchor = ConsistentHashing::Anchor.new(@value, @server)
+  end
+
+  it "should have a to_s method that displays teh value and server address" do
+    @anchor.to_s.should == "value:#{@value}, server:#{@server.address}"
+  end
+
+  it "should have an inspect method" do
+    @anchor.inspect.should == 
+      "<ConsistentHashing::Anchor | value:#{@value}, server:#{@server.address}>"
+  end
+
+  it "should implement the <=> operator by comparing the value of the anchors" do
+    # Unfortunately, I cannot do 
+    #   @anchor.value.should_receieve(:<=>).with(some_value)
+    # So I will settle for a randomized test
+    10.times do 
+      random_value = rand
+      other_anchor = mock("other_anchor")
+      other_anchor.should_receive(:value).and_return(random_value)
+
+      (@anchor <=> other_anchor).should == (@anchor.value <=> random_value)
+    end
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--colour

data/spec/spec_helper.rb

@@ -0,0 +1,40 @@
+require 'rubygems'
+require 'spec'
+
+# For the purposes of testing, I want access to the anchor, not just the server
+# so that I can easily verify that the correct anchor was returned.
+def responsible_anchor(continuum, search_value)
+  continuum.send(:closest_anchor, search_value)
+end
+
+# Get the anchor responsible for the previous segment.
+def previous_anchor(anchor, continuum)
+    index = continuum.anchors.index(anchor)
+    previous_index = index - 1
+    continuum.anchors[previous_index]
+end
+
+# NOTE: I use the word 'segment' to mean a range that excludes the lower bound
+# but includes the upper bound.  For example, (0, 10] is a segment containing
+# the numbers 1-10.
+
+# Get an array of values in the segment.  The values will include some edge
+# cases, and a few random values.
+def some_values_in_segment(exclusive_lower_bound, inclusive_upper_bound)
+  raise "invalid segment" unless exclusive_lower_bound < inclusive_upper_bound
+
+  difference = inclusive_upper_bound - exclusive_lower_bound 
+  values = [ 0.01, 0.25, 0.50, 0.75, 0.99 ].map do |r|
+             exclusive_lower_bound + r*difference
+           end
+  values << inclusive_upper_bound
+  values
+end
+
+def new_mock_server(address, weight=1)
+  server = Object.new
+  server.stub!(:address).and_return(address)
+  server.stub!(:weight).and_return(weight)
+  server
+end
+

data/test/benchmark.rb

@@ -0,0 +1,32 @@
+require 'rubygems'
+require 'benchmark'
+
+require 'memcache'
+require File.dirname(__FILE__) + '/../lib/mem_cache_with_consistent_hashing'
+
+class MemCache::Server
+  def alive?
+    true
+  end
+end
+
+servers = [*"localhost:11211".."localhost:11230"]
+
+original_client = MemCache.new(servers)
+consistent_hashing_client = MemCacheWithConsistentHashing.new(servers)
+
+num_keys = 10_000
+keys = [*0...num_keys].map{|i| rand.to_s}
+
+time_for_original, time_for_consistent_hashing = 
+  [original_client, consistent_hashing_client].map do |client|
+    Benchmark.realtime do
+      for key in keys
+        client.get_server_for_key(key)
+      end
+    end
+  end
+
+printf("%4.2f <= time_for_original\n", time_for_original)
+printf("%4.2f <= time_for_consistent_hashing\n", time_for_consistent_hashing)
+printf("%4.2f <= time_for_original/time_for_consistent_hashing\n", time_for_original/time_for_consistent_hashing)

data/test/test_mem_cache.rb

@@ -0,0 +1,586 @@
+require 'stringio'
+require 'test/unit'
+require 'rubygems'
+require 'test/zentest_assertions'
+
+$TESTING = true
+
+require File.dirname(__FILE__) + '/../lib/mem_cache_with_consistent_hashing'
+
+class MemCache
+
+  attr_reader :servers
+  attr_writer :namespace
+
+end
+
+class MemCacheWithConsistentHashing
+
+  def add_server(server)
+    @continuum.anchors = (@continuum.anchors + @continuum.send(:create_anchors_for_server, server).sort)
+    @servers << server
+  end
+
+end
+
+class FakeSocket
+
+  attr_reader :written, :data
+
+  def initialize
+    @written = StringIO.new
+    @data = StringIO.new
+  end
+
+  def write(data)
+    @written.write data
+  end
+
+  def gets
+    @data.gets
+  end
+
+  def read(arg)
+    @data.read arg
+  end
+
+end
+
+class FakeServer
+
+  attr_reader :socket
+
+  @@port = 11211
+
+  def initialize(socket = nil)
+    @port = @@port
+    @@port += 1
+    @socket = socket || FakeSocket.new
+    @closed = false
+  end
+
+  def close
+    @closed = true
+  end
+
+  def alive?
+    !@closed
+  end
+
+  def weight
+    1
+  end
+
+  def address
+    "localhost:#{@port}"
+  end
+
+end
+
+class TestMemCache < Test::Unit::TestCase
+
+  def setup
+    @cache = MemCacheWithConsistentHashing.new 'localhost:1', :namespace => 'my_namespace'
+  end
+
+  def test_cache_get
+    server = util_setup_fake_server
+
+    assert_equal "\004\b\"\0170123456789",
+                 @cache.cache_get(server, 'my_namespace:key')
+
+    assert_equal "get my_namespace:key\r\n",
+                 server.socket.written.string
+  end
+
+  def test_cache_get_bad_state
+    server = FakeServer.new
+    server.socket.data.write "bogus response\r\n"
+    server.socket.data.rewind
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    e = assert_raise MemCache::MemCacheError do
+      @cache.cache_get(server, 'my_namespace:key')
+    end
+
+    assert_equal "unexpected response \"bogus response\\r\\n\"", e.message
+
+    deny server.alive?
+
+    assert_equal "get my_namespace:key\r\n",
+                 server.socket.written.string
+  end
+
+  def test_cache_get_miss
+    socket = FakeSocket.new
+    socket.data.write "END\r\n"
+    socket.data.rewind
+    server = FakeServer.new socket
+
+    assert_equal nil, @cache.cache_get(server, 'my_namespace:key')
+
+    assert_equal "get my_namespace:key\r\n",
+                 socket.written.string
+  end
+
+  def test_cache_get_multi_bad_state
+    server = FakeServer.new
+    server.socket.data.write "bogus response\r\n"
+    server.socket.data.rewind
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    e = assert_raise MemCache::MemCacheError do
+      @cache.cache_get_multi(server, ['my_namespace:key'])
+    end
+
+    assert_equal "unexpected response \"bogus response\\r\\n\"", e.message
+
+    deny server.alive?
+
+    assert_equal "get my_namespace:key\r\n",
+                 server.socket.written.string
+  end
+
+  def test_crc32_ITU_T
+    assert_equal 0, ''.crc32_ITU_T
+    assert_equal 1260851911, 'my_namespace:key'.crc32_ITU_T
+  end
+
+  def test_initialize
+    cache = MemCacheWithConsistentHashing.new :namespace => 'my_namespace', :readonly => true
+
+    assert_equal 'my_namespace', cache.namespace
+    assert_equal true, cache.readonly?
+    assert_equal true, cache.servers.empty?
+  end
+
+  def test_initialize_compatible
+    cache = MemCacheWithConsistentHashing.new ['localhost:11211', 'localhost:11212'],
+            :namespace => 'my_namespace', :readonly => true
+
+    assert_equal 'my_namespace', cache.namespace
+    assert_equal true, cache.readonly?
+    assert_equal false, cache.servers.empty?
+  end
+
+  def test_initialize_compatible_no_hash
+    cache = MemCacheWithConsistentHashing.new ['localhost:11211', 'localhost:11212']
+
+    assert_equal nil, cache.namespace
+    assert_equal false, cache.readonly?
+    assert_equal false, cache.servers.empty?
+  end
+
+  def test_initialize_compatible_one_server
+    cache = MemCacheWithConsistentHashing.new 'localhost:11211'
+
+    assert_equal nil, cache.namespace
+    assert_equal false, cache.readonly?
+    assert_equal false, cache.servers.empty?
+  end
+
+  def test_initialize_compatible_bad_arg
+    e = assert_raise ArgumentError do
+      cache = MemCacheWithConsistentHashing.new Object.new
+    end
+
+    assert_equal 'first argument must be Array, Hash or String', e.message
+  end
+
+  def test_initialize_multiple_servers
+    cache = MemCacheWithConsistentHashing.new %w[localhost:11211 localhost:11212],
+                         :namespace => 'my_namespace', :readonly => true
+
+    assert_equal 'my_namespace', cache.namespace
+    assert_equal true, cache.readonly?
+    assert_equal false, cache.servers.empty?
+    deny_empty cache.instance_variable_get(:@buckets)
+  end
+
+  def test_initialize_too_many_args
+    assert_raises ArgumentError do
+      MemCacheWithConsistentHashing.new 1, 2, 3
+    end
+  end
+
+  def test_decr
+    server = FakeServer.new
+    server.socket.data.write "5\r\n"
+    server.socket.data.rewind
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    value = @cache.decr 'key'
+
+    assert_equal "decr my_namespace:key 1\r\n",
+                 @cache.servers.first.socket.written.string
+
+    assert_equal 5, value
+  end
+
+  def test_decr_not_found
+    server = FakeServer.new
+    server.socket.data.write "NOT_FOUND\r\n"
+    server.socket.data.rewind
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    value = @cache.decr 'key'
+
+    assert_equal "decr my_namespace:key 1\r\n",
+                 @cache.servers.first.socket.written.string
+
+    assert_equal nil, value
+  end
+
+  def test_decr_space_padding
+    server = FakeServer.new
+    server.socket.data.write "5 \r\n"
+    server.socket.data.rewind
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    value = @cache.decr 'key'
+
+    assert_equal "decr my_namespace:key 1\r\n",
+                 @cache.servers.first.socket.written.string
+
+    assert_equal 5, value
+  end
+
+  def test_get
+    util_setup_fake_server
+
+    value = @cache.get 'key'
+
+    assert_equal "get my_namespace:key\r\n",
+                 @cache.servers.first.socket.written.string
+
+    assert_equal '0123456789', value
+  end
+
+  def test_get_bad_key
+    util_setup_fake_server
+    assert_raise ArgumentError do @cache.get 'k y' end
+
+    util_setup_fake_server
+    assert_raise ArgumentError do @cache.get 'k' * 250 end
+  end
+
+  def test_get_cache_get_IOError
+    socket = Object.new
+    def socket.write(arg) raise IOError, 'some io error'; end
+    server = FakeServer.new socket
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    e = assert_raise MemCache::MemCacheError do
+      @cache.get 'my_namespace:key'
+    end
+
+    assert_equal 'some io error', e.message
+  end
+
+  def test_get_cache_get_SystemCallError
+    socket = Object.new
+    def socket.write(arg) raise SystemCallError, 'some syscall error'; end
+    server = FakeServer.new socket
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    e = assert_raise MemCache::MemCacheError do
+      @cache.get 'my_namespace:key'
+    end
+
+    assert_equal 'unknown error - some syscall error', e.message
+  end
+
+  def test_get_no_connection
+    @cache.servers = 'localhost:1'
+    e = assert_raise MemCache::MemCacheError do
+      @cache.get 'key'
+    end
+
+    assert_equal 'No connection to server', e.message
+  end
+
+  def test_get_no_servers
+    @cache.servers = []
+    e = assert_raise MemCache::MemCacheError do
+      @cache.get 'key'
+    end
+
+    assert_equal 'No active servers', e.message
+  end
+
+  def test_get_multi
+    server = FakeServer.new
+    server.socket.data.write "VALUE my_namespace:key 0 14\r\n"
+    server.socket.data.write "\004\b\"\0170123456789\r\n"
+    server.socket.data.write "VALUE my_namespace:keyb 0 14\r\n"
+    server.socket.data.write "\004\b\"\0179876543210\r\n"
+    server.socket.data.write "END\r\n"
+    server.socket.data.rewind
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    values = @cache.get_multi 'key', 'keyb'
+
+    assert_equal "get my_namespace:key my_namespace:keyb\r\n",
+                 server.socket.written.string
+
+    expected = { 'key' => '0123456789', 'keyb' => '9876543210' }
+
+    assert_equal expected.sort, values.sort
+  end
+
+  def test_get_raw
+    server = FakeServer.new
+    server.socket.data.write "VALUE my_namespace:key 0 10\r\n"
+    server.socket.data.write "0123456789\r\n"
+    server.socket.data.write "END\r\n"
+    server.socket.data.rewind
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+
+    value = @cache.get 'key', true
+
+    assert_equal "get my_namespace:key\r\n",
+                 @cache.servers.first.socket.written.string
+
+    assert_equal '0123456789', value
+  end
+
+  def test_get_server_for_key
+    server = @cache.get_server_for_key 'key'
+    assert_equal 'localhost', server.host
+    assert_equal 1, server.port
+  end
+
+  def test_get_server_for_key_multiple
+    s1 = util_setup_server @cache, 'one.example.com', ''
+    s2 = util_setup_server @cache, 'two.example.com', ''
+    @cache.instance_variable_set :@servers, [s1, s2]
+    @cache.instance_variable_set :@buckets, [s1, s2]
+
+    server = @cache.get_server_for_key 'keya'
+    assert_equal 'two.example.com', server.host
+    server = @cache.get_server_for_key 'keyb'
+    assert_equal 'two.example.com', server.host
+  end
+
+  def test_get_server_for_key_no_servers
+    @cache.servers = []
+
+    e = assert_raise MemCache::MemCacheError do
+      @cache.get_server_for_key 'key'
+    end
+
+    assert_equal 'No servers available', e.message
+  end
+
+  def test_get_server_for_key_spaces
+    e = assert_raise ArgumentError do
+      @cache.get_server_for_key 'space key'
+    end
+    assert_equal 'illegal character in key "space key"', e.message
+  end
+
+  def test_get_server_for_key_length
+    @cache.get_server_for_key 'x' * 250
+    long_key = 'x' * 251
+    e = assert_raise ArgumentError do
+      @cache.get_server_for_key long_key
+    end
+    assert_equal "key too long #{long_key.inspect}", e.message
+  end
+
+  def test_incr
+    server = FakeServer.new
+    server.socket.data.write "5\r\n"
+    server.socket.data.rewind
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    value = @cache.incr 'key'
+
+    assert_equal "incr my_namespace:key 1\r\n",
+                 @cache.servers.first.socket.written.string
+
+    assert_equal 5, value
+  end
+
+  def test_incr_not_found
+    server = FakeServer.new
+    server.socket.data.write "NOT_FOUND\r\n"
+    server.socket.data.rewind
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    value = @cache.incr 'key'
+
+    assert_equal "incr my_namespace:key 1\r\n",
+                 @cache.servers.first.socket.written.string
+
+    assert_equal nil, value
+  end
+
+  def test_incr_space_padding
+    server = FakeServer.new
+    server.socket.data.write "5 \r\n"
+    server.socket.data.rewind
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    value = @cache.incr 'key'
+
+    assert_equal "incr my_namespace:key 1\r\n",
+                 @cache.servers.first.socket.written.string
+
+    assert_equal 5, value
+  end
+
+  def test_make_cache_key
+    assert_equal 'my_namespace:key', @cache.make_cache_key('key')
+    @cache.namespace = nil
+    assert_equal 'key', @cache.make_cache_key('key')
+  end
+
+  def test_servers_equals_type_error
+    e = assert_raise TypeError do
+      @cache.servers = [Object.new]
+    end
+
+    assert_equal 'cannot convert Object into MemCache::Server', e.message
+  end
+
+  def test_set
+    server = FakeServer.new
+    server.socket.data.write "STORED\r\n"
+    server.socket.data.rewind
+    @cache.servers = []
+    @cache.add_server(server)
+
+    @cache.set 'key', 'value'
+
+    expected = "set my_namespace:key 0 0 9\r\n\004\b\"\nvalue\r\n"
+    assert_equal expected, server.socket.written.string
+  end
+
+  def test_set_expiry
+    server = FakeServer.new
+    server.socket.data.write "STORED\r\n"
+    server.socket.data.rewind
+    @cache.servers = []
+    @cache.add_server(server)
+
+    @cache.set 'key', 'value', 5
+
+    expected = "set my_namespace:key 0 5 9\r\n\004\b\"\nvalue\r\n"
+    assert_equal expected, server.socket.written.string
+  end
+
+  def test_set_raw
+    server = FakeServer.new
+    server.socket.data.write "STORED\r\n"
+    server.socket.data.rewind
+    @cache.servers = []
+    @cache.add_server(server)
+
+    @cache.set 'key', 'value', 0, true
+
+    expected = "set my_namespace:key 0 0 5\r\nvalue\r\n"
+    assert_equal expected, server.socket.written.string
+  end
+
+  def test_set_readonly
+    cache = MemCacheWithConsistentHashing.new :readonly => true
+
+    e = assert_raise MemCache::MemCacheError do
+      cache.set 'key', 'value'
+    end
+
+    assert_equal 'Update of readonly cache', e.message
+  end
+
+  def test_stats
+    socket = FakeSocket.new
+    socket.data.write "STAT pid 20188\r\nSTAT total_items 32\r\rEND\r\n"
+    socket.data.rewind
+    server = FakeServer.new socket
+    def server.host() "localhost"; end
+    def server.port() 11211; end
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    expected = {"localhost:11211"=>{"pid"=>"20188", "total_items"=>"32"}}
+    assert_equal expected, @cache.stats
+
+    assert_equal "stats\r\n", socket.written.string
+  end
+
+  def test_basic_threaded_operations_should_work
+    cache = MemCacheWithConsistentHashing.new :multithread => true,
+                         :namespace => 'my_namespace',
+                         :readonly => false
+    server = util_setup_server cache, 'example.com', "OK\r\n"
+    cache.instance_variable_set :@servers, [server]
+
+    assert_nothing_raised do
+      cache.set "test", "test value"
+    end
+  end
+
+  def test_basic_unthreaded_operations_should_work
+    cache = MemCacheWithConsistentHashing.new :multithread => false,
+                         :namespace => 'my_namespace',
+                         :readonly => false
+    server = util_setup_server cache, 'example.com', "OK\r\n"
+    cache.instance_variable_set :@servers, [server]
+
+    assert_nothing_raised do
+      cache.set "test", "test value"
+    end
+  end
+
+  def util_setup_fake_server
+    server = FakeServer.new
+    server.socket.data.write "VALUE my_namespace:key 0 14\r\n"
+    server.socket.data.write "\004\b\"\0170123456789\r\n"
+    server.socket.data.write "END\r\n"
+    server.socket.data.rewind
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    return server
+  end
+
+  def util_setup_server(memcache, host, responses)
+    server = MemCache::Server.new memcache, host
+    server.instance_variable_set :@sock, StringIO.new(responses)
+
+    @cache.servers = []
+    @cache.add_server(server)
+
+    return server
+  end
+
+end
+