redis_directory 1.0.4

data/README

@@ -0,0 +1,24 @@
+= Redis::Directory
+
+Redis::Directory assumes a Redis installation running on a default
+port and database 0 that will contain connection information for various
+other Redis databases. For example, if you were using a Redis database to
+store the content of cached pages, and this was running on a cluster of
+two Redis instances, with multiple applications connecting partitioned by
+database, then your connection might look like this:
+
+  require "redis"
+  require "redis/distributed"
+
+  # The ACME Corp database is #27
+  cache = Redis::Distributed.new %w( redis://redis.example:4400/27 redis://redis.example:4401/27 )
+
+Redis::Directory uses a centralized Redis database to store the
+connection information so you don't have to remember "magic numbers" for
+each client/database mapping, and can easily update port-numbers, hostnames
+and cluster-members as necessary. The same connection with
+Redis::Directory would look like this:
+
+  require "redis_directory"
+  
+  cache = Redis::Directory.new("redis.example").get("cache", "acme")

data/Rakefile

@@ -0,0 +1,26 @@
+require "rake"
+require "rake/clean"
+require "rake/testtask"
+require "rake/rdoctask"
+
+task :default => :test
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+CLEAN.include ["*.gem", "rdoc"]
+RDOC_OPTS = [ "--quiet", "--inline-source", "--line-numbers", "--title", "Redis Directory: A database connection manager for Redis", "--main", "README" ]
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.options += RDOC_OPTS
+  rdoc.rdoc_files.add %w"README MIT-LICENSE lib/redis_directory.rb"
+end
+
+desc "Package redis_directory"
+task :package do
+  sh %{gem build redis_directory.gemspec}
+end

data/lib/redis_directory.rb

@@ -0,0 +1,90 @@
+require "redis"
+require "redis/distributed"
+require "json"
+
+class Redis::Directory
+  
+  SERVICES_KEY = "services"
+  DATABASES_KEY = "databases"
+  
+  # Hard-coded, because I don't know how to get this from the Redis connection at runtime.
+  MAXIMUM_DATABASE_COUNT = 65535
+  
+  # This error is thrown when you request a service that is not defined in the directory's "services" key.
+  class UndefinedServiceError < StandardError
+    def initialize(directory, service_name)
+      super "#{service_name} is not an available service! (#{directory.services.keys.sort})"
+    end
+  end
+  
+  # If you are unable to reserve a database during a connection attempt, this error is raised.
+  class ReservationError < StandardError
+    def initialize(directory, service_name, connection_name)
+      super "Unable to reserve a database for #{service_name}:#{connection_name}!\nCurrent databases for service: #{directory.redis.hgetall("#{service_name}-service")}"
+    end
+  end
+  
+  # You must provide the +connection_options+ to the directory server.
+  def initialize(connection_options)
+    @redis = Redis.connect(connection_options)
+  end
+  
+  def services
+    if redis.exists(SERVICES_KEY)
+      redis.hgetall(SERVICES_KEY).inject({}) do |h,(k,v)|
+        h[k] = JSON.parse(v); h
+      end
+    else
+      {}
+    end
+  end
+  
+  # This locates the next available database for a given service, starting at an index of 1.
+  # The 0 database is reserved in case you have a default connection, or local redis server
+  # (in which case 0 should be the directory database to avoid conflicts).
+  def next_db(service_name)
+    raise UndefinedServiceError.new(self, service_name) unless services.keys.include?(service_name)
+    databases = redis.hvals("#{service_name}-service").map { |i| i.to_i }.sort
+    (1..MAXIMUM_DATABASE_COUNT).select { |i| break i unless databases.include? i }
+  end
+  
+  def reserve(service_name, connection_name)
+    new_db = nil
+    # redis.multi do
+      if redis.hexists("#{service_name}-service", connection_name)
+        new_db = redis.hget("#{service_name}-service", connection_name)
+      else
+        new_db = next_db(service_name)
+        redis.hset("#{service_name}-service", connection_name, new_db)
+      end
+    # end
+    new_db
+  end
+  
+  def get(service_name, connection_name)
+    db = reserve(service_name, connection_name)
+    raise ReservationError.new(self, service_name, connection_name) if db.nil?
+    
+    connection_list = services[service_name].map do |server|
+      if server =~ /^redis\:\/\//
+        "#{server}/#{db}"
+      else
+        "redis://#{server}/#{db}"
+      end
+    end
+    connection = nil
+    
+    if connection_list.size == 1
+      connection = Redis.connect(:url => connection_list.first)
+    else
+      connection = Redis::Distributed.new(connection_list)
+    end
+    
+    connection.set("connection-name", connection_name)
+    connection
+  end
+  
+  def redis
+    @redis
+  end
+end

data/redis_directory.gemspec

@@ -0,0 +1,47 @@
+Gem::Specification.new do |s|
+  s.name            = "redis_directory"
+  s.version         = "1.0.4"
+  s.platform        = Gem::Platform::RUBY
+  s.summary         = "Redis Directory for retriving/storing redis connections in a central database."
+
+  s.description = <<-EOF
+Redis::Directory assumes a Redis installation running on a default
+port and database 0 that will contain connection information for various
+other Redis databases. For example, if you were using a Redis database to
+store the content of cached pages, and this was running on a cluster of
+two Redis instances, with multiple applications connecting partitioned by
+database, then your connection might look like this:
+
+  require "redis"
+  require "redis/distributed"
+
+  # The ACME Corp database is #27
+  cache = Redis::Distributed.new "redis://redis.example:4400/27", "redis://redis.example:4401/27"
+
+Redis::Directory uses a centralized Redis database to store the
+connection information so you don't have to remember "magic numbers" for
+each client/database mapping, and can easily update port-numbers/hostnames,
+cluster-members as necessary. The same connection with
+Redis::Directory would look like this:
+
+  require "redis_directory"
+  
+  cache = Redis::Directory.new("redis.example").connect("cache", "acme")
+EOF
+
+  s.files           = Dir[ "README", "lib/**/*", "test/**/*", "redis_directory.gemspec", "Rakefile" ]
+  s.require_path    = "lib"
+  s.test_files      = Dir["test/**/*_test.rb"]
+
+  s.author          = "Sam Smoot"
+  s.email           = "ssmoot@gmail.com"
+  s.homepage        = "https://github.com/wiecklabs/redis_directory"
+  s.license         = "MIT"
+  
+  s.has_rdoc = true
+  s.rdoc_options = [ "--inline-source", "--line-numbers", "--title", "Redis Directory: A database connection manager for Redis", "README", "MIT-LICENSE", "lib" ]
+
+  s.add_dependency "redis"
+  s.add_dependency "minitest" if RUBY_VERSION =~ /1\.8/
+  s.add_dependency "json"
+end

data/test/connection_test.rb

@@ -0,0 +1,129 @@
+require File.dirname(__FILE__) + "/helper"
+
+class ConnectionTest < MiniTest::Unit::TestCase
+
+  def setup
+    @directory = Redis::Directory.new(:url => (ENV["REDIS_DIRECTORY"] || "redis://localhost"))
+    
+    @redis = @directory.redis
+    @redis.hset Redis::Directory::SERVICES_KEY, "cache", [ "redis://localhost" ].to_json
+    @redis.hset Redis::Directory::SERVICES_KEY, "sessions", [ "redis://localhost" ].to_json
+    @redis.hset Redis::Directory::SERVICES_KEY, "queue", [ "redis://localhost" ].to_json
+  end
+  
+  def teardown
+    @redis.flushall
+    @redis.quit
+  end
+  
+  # Our first test verifies that the "services" key (populated here in #setup) is not empty.
+  # Since we can't know the hostname(s) and ports for the Redis members you've setup, you
+  # must pre-populate this.
+  # This can be as easy as using the redis-cli on the command-line to populate your directory:
+  #
+  #   redis-cli -h redis.example.com -p 8440 hset services cache '["redis.example.com:9100", "redis.example.com:9101"]'
+  #   redis-cli -h redis.example.com -p 8440 hset services sessions '["redis.example.com:9200", "redis.example.com:9201"]'
+  #   redis-cli -h redis.example.com -p 8440 hset services queue '["redis.example.com:9300"]'
+  #
+  # Then +@directory.services+ would be equal to:
+  #
+  #   {
+  #     "cache"     => ["redis.example.com:9100", "redis.example.com:9101"],
+  #     "sessions"  => ["redis.example.com:9200", "redis.example.com:9201"],
+  #     "queue"     => ["redis.example.com:9300"]
+  #   }
+  # 
+  # These are the definitions for your cluster(s) of services.
+  # It's recommended that you dedicate individual use-cases to individual clusters.
+  # This helps you balance your loads more evenly across multi-core machines
+  # (since Redis is single-threaded) as well as allowing you to tune memory limits,
+  # flush-to-disk intervals, etc on a per-cluster basis.
+  def test_services_are_staticly_assigned
+    refute_empty @directory.services
+  end
+  
+  def test_services_is_a_hash_of_connection_strings
+    assert_kind_of Hash, @directory.services
+  end
+  
+  # Because we use a Redis::Distributed connection, you should consistently
+  # use Arrays for your cluster connections even if there is only one item
+  # in the cluster.
+  def test_service_value_is_an_array
+    assert_kind_of Array, @directory.services["queue"]
+  end
+  
+  # Here we're just confirming that when we ask for it, the next availble
+  # database number for a given service is retrieved.
+  def test_database_number_is_retrieved
+    assert_kind_of Fixnum, @directory.next_db("sessions")
+  end
+  
+  # If the service/cluster is undefined, then we should raise a
+  # UndefinedServiceError when requesting it's next database number.
+  def test_database_number_errors_for_service_not_exist
+    assert_raises(Redis::Directory::UndefinedServiceError) do
+      @directory.next_db("quack")
+    end
+  end
+  
+  # Once we've made a connection (+Redis::Directory#get+), we should be able
+  # to confirm that the database we've connected to is for this name.
+  def test_database_contains_connection_name
+    assert_equal "acme", @directory.get("cache", "acme").get("connection-name")
+  end
+  
+  # If we reserve a database, it should be tracked in a Hash describing the
+  # currently reserved services for that name. That way we can look it up later
+  # and re-use it instead of always provisioning new databases every time you
+  # make a new request.
+  def test_database_is_reserved
+    @directory.reserve("cache", "acme")
+    assert @redis.hexists("cache-service", "acme")
+    refute_nil @redis.hget("cache-service", "acme")
+  end
+  
+  # This test confirms an internal implementation detail, ensuring that we don't
+  # have collisions between multiple database names for a given service.
+  def test_additional_cache_connection_increments
+    @directory.reserve("cache", "acme")
+    @directory.reserve("cache", "trioptimum")
+    assert_equal @redis.hlen("cache-service"), @redis.hget("cache-service", "trioptimum").to_i
+  end
+  
+  # When there are "gaps" in the list of tracked databases for a service, those
+  # should be filled to keep the maximum database number as low as possible.
+  # This way as long as you clean up disused databases by removing them from the
+  # service keys, eg:
+  #
+  #   redis-cli hdel cache-service acme
+  #
+  # Then we'll re-use that database number, meaning that as long as you've set
+  # (in your redis.conf) your maximum databases equal to or great than the number
+  # you plan to use, +Redis::Directory+ should not exceed that number.
+  def test_sparse_ids_are_filled
+    @redis.hset("cache-service", "corporatron", 5)
+
+    @directory.reserve("cache", "bnl")
+    assert_equal 1, @redis.hget("cache-service", "bnl").to_i
+    
+    @directory.reserve("cache", "axiom")
+    assert_equal 2, @redis.hget("cache-service", "axiom").to_i
+  end
+  
+  # In order to use as few database numbers as possible, and again, allowing you
+  # to tune Redis configuration settings like +databases+ on a per service/cluster
+  # basis, database numbers may not be consistent across services/clusters for a
+  # given client/name. This is especially true if not all clients consume all services,
+  # as the example below demonstrates.
+  def test_database_ids_are_unbalanced
+    bnl     = @directory.reserve("cache", "bnl")
+    hacker  = @directory.reserve("cache", "trioptimum")
+    acme    = @directory.reserve("cache", "acme")
+
+    shodan  = @directory.reserve("sessions", "trioptimum")
+
+    refute_equal hacker, shodan
+  end
+  
+end

data/test/helper.rb

@@ -0,0 +1,7 @@
+ENV["ENVIRONMENT"] = "test"
+
+require "rubygems"
+require "bundler/setup"
+
+require "minitest/autorun"
+require File.dirname(__FILE__) + "/../lib/redis_directory"

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification 
+name: redis_directory
+version: !ruby/object:Gem::Version 
+  hash: 31
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 4
+  version: 1.0.4
+platform: ruby
+authors: 
+- Sam Smoot
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-03-03 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: redis
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: minitest
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id003
+description: |
+  Redis::Directory assumes a Redis installation running on a default
+  port and database 0 that will contain connection information for various
+  other Redis databases. For example, if you were using a Redis database to
+  store the content of cached pages, and this was running on a cluster of
+  two Redis instances, with multiple applications connecting partitioned by
+  database, then your connection might look like this:
+  
+    require "redis"
+    require "redis/distributed"
+  
+    # The ACME Corp database is #27
+    cache = Redis::Distributed.new "redis://redis.example:4400/27", "redis://redis.example:4401/27"
+  
+  Redis::Directory uses a centralized Redis database to store the
+  connection information so you don't have to remember "magic numbers" for
+  each client/database mapping, and can easily update port-numbers/hostnames,
+  cluster-members as necessary. The same connection with
+  Redis::Directory would look like this:
+  
+    require "redis_directory"
+    
+    cache = Redis::Directory.new("redis.example").connect("cache", "acme")
+
+email: ssmoot@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README
+- lib/redis_directory.rb
+- test/connection_test.rb
+- test/helper.rb
+- redis_directory.gemspec
+- Rakefile
+homepage: https://github.com/wiecklabs/redis_directory
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --line-numbers
+- --title
+- "Redis Directory: A database connection manager for Redis"
+- README
+- MIT-LICENSE
+- lib
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.12
+signing_key: 
+specification_version: 3
+summary: Redis Directory for retriving/storing redis connections in a central database.
+test_files: 
+- test/connection_test.rb