redis_support 0.0.1

data/README.md

@@ -0,0 +1,58 @@
+Redis Support
+=============
+
+redis_support is a small library which provides simple support for
+common actions for the Redis key-value store. It is not an
+object-relational mapper, does not attempt to comprehensively solve
+all of your storage problems, and does not make julienne fries.
+
+Key Support
+-----------
+
+Redis provides a global keyspace. Most projects specify their keys
+using namespaces delimited by colons (:), with variables mixed in at
+particular points. For example:
+
+    users:1:email
+
+`redis_support`, when used as a mixin, will provide a simple method to
+declare that namespace and access it later.
+
+    class User
+      include RedisSupport
+      redis_key :email, "users:USER_ID:email"
+
+      attr_accessor :id
+
+      def email
+        redis.get Keys.email( self.id )
+      end
+    end
+
+Helpful exceptions are raised if you try to declare the same namespace
+twice - RedisSupport keeps track of all the key definitions your app
+wants to use.
+
+Locking Support
+---------------
+
+There is also a simple locking mechanism based on SETNX. Locking is
+usually unnecessary since Redis operations are atomic and Redis'
+MULTI/EXEC/DISCARD gives you the ability to make multiple operations
+atomic. But sometimes it's useful - a contrived example -
+major_operation will block for up to 30 seconds if another process
+attempts to run it at the same time:
+
+    class User
+      include RedisSupport
+      redis_key :email, "users:USER_ID:email"
+
+      attr_accessor :id
+
+      def major_operation
+        redis_lock Keys.email( self.id ) do
+          # do my expensive stuff
+        end
+      end
+    end
+

data/lib/redis_support/class_extensions.rb

@@ -0,0 +1,56 @@
+module RedisSupport
+  class RedisKeyError < StandardError ; end
+  class DuplicateRedisKeyDefinitionError < RedisKeyError ; end
+  class InvalidRedisKeyDefinitionError < RedisKeyError ; end
+
+  VAR_PATTERN = /^[A-Z]+(_[A-Z]+)*$/
+  STR_PATTERN = /^[a-z_]+$/
+  module ClassMethods
+    # Goal is to allow a class to declare a redis key/property 
+    # The key is a colon delimited string where variables
+    # are listed are upper case (underscores inbetween) and
+    # non variables are completely lower case (underscores inbetween or appending/prepending)
+    #
+    # variables cannot be repeated and must start with a letter
+    # the key must also start with a nonvariable
+    #
+    # Examples
+    #
+    #   redis_key :workpools, "job:JOB_ID:workpools"
+    #
+    # Returns the redis key.
+    def redis_key( name, keystruct )
+      if Keys.methods.include? name.to_s
+        raise DuplicateRedisKeyDefinitionError
+      end
+      
+      key = keystruct.split(":")
+      
+      unless (first = key.shift) =~ STR_PATTERN
+        raise InvalidRedisKeyDefinitionError.new "keys must begin with lowercase letters"
+      end
+
+      vars, strs = key.inject([[],[]]) do |(vs, ss), token|
+        case token
+        when VAR_PATTERN
+          var = token.downcase
+          ss << "\#{#{var}}"
+          vs << var
+        when STR_PATTERN
+          ss << token
+        else
+          raise InvalidRedisKeyDefinitionError.new "Internal error parsing #{keystruct} : last token : #{token}"
+        end
+        [vs, ss]
+      end
+
+      strs.unshift(first)
+
+      RedisSupport::Keys.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.#{name.to_s}( #{vars.map {|x| x.to_s }.join(', ')} )
+          "#{strs.join(":")}"
+        end
+      RUBY
+    end
+  end
+end

data/lib/redis_support/locks.rb

@@ -0,0 +1,98 @@
+# Locking support
+#
+module RedisSupport
+
+  # Lock a block of code so it can only be accessed by one thread in
+  # our system at a time.
+  #
+  # See 'acquire_redis_lock' for details on parameters.
+  #
+  # Returns nothing.
+  def redis_lock( key_to_lock, expiration = 30, interval = 1 )
+    acquire_redis_lock( key_to_lock, expiration, interval )
+    yield
+  ensure
+    release_redis_lock( key_to_lock )
+  end
+
+  # Acquire a lock on a key in our Redis database. This is a blocking
+  # call. It sleeps until the lock has been successfully acquired.
+  #
+  # Basic usage:
+  #
+  #   acquire_redis_lock( key.my_key )
+  #   # do some stuff on my_key
+  #   release_redis_lock( key.my_key )
+  #
+  # Described in detail here:
+  #
+  #   http://code.google.com/p/redis/wiki/SetnxCommand
+  #
+  # key_to_lock - the key to lock. the actual key for the lock in redis will
+  #               be this value with 'lock.' prepended, which lets this whole
+  #               acquire_lock business act like a standard ruby object or
+  #               synchronize lock. Also it ensures that all locks in the database
+  #               can be easily viewed using redis.keys("lock.*")
+  #
+  # expiration  - the expiration for the lock, expressed as an Integer. default is
+  #               30 seconds from when the lock is acquired. Note that this is the
+  #               amount of time others will wait for you, not the amount of time
+  #               you will wait to acquire the lock.
+  #
+  # interval    - sleep interval for checking the lock's status.
+  #   
+  # Returns nothing.
+  def acquire_redis_lock( key_to_lock, expiration = 30, interval = 1 )
+    key = lock_key( key_to_lock )
+    until redis.setnx key, timeout_i( expiration )
+      if redis.get( key ).to_i < Time.now.to_i
+        old_timeout = redis.getset( key, timeout_i( expiration ) ).to_i
+        if old_timeout < Time.now.to_i
+          return # got it!
+        end
+      else
+        sleep interval
+      end
+    end
+  end
+
+  # Acquire a redis lock only if it can be acquired
+  # is a nonblocking action
+  #
+  # Returns true on success and false on failure
+  def acquire_redis_lock_nonblock( key_to_lock, expiration = 30 ) 
+    key = lock_key( key_to_lock ) 
+    redis.setnx key, timeout_i( expiration )
+  end
+  
+  # See docs for acquire_redis_lock above
+  #
+  # Returns nothing.
+  def release_redis_lock( locked_key )
+    redis.del lock_key( locked_key )
+  end
+
+  def has_redis_lock?( locked_key )
+    redis.exists lock_key(locked_key) 
+  end
+
+  private
+
+  def lock_key( key_to_lock )
+    "lock.#{key_to_lock}"
+  end
+
+  # Converts an Integer number of seconds into a future timestamp that
+  # can be used with Redis.
+  #
+  # Examples
+  # 
+  #   timeout_i(expiration)
+  #   # => 1274955869
+  #
+  # Returns the timestamp.
+  def timeout_i( timeout )
+    timeout.seconds.from_now.to_i
+  end
+
+end

data/lib/redis_support.rb

@@ -0,0 +1,41 @@
+require 'redis'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "/"))
+require 'redis_support/class_extensions'
+require 'redis_support/locks'
+
+module RedisSupport
+
+  # Inspired/take from the redis= in Resque
+  #
+  # Accepts:
+  #   1. A 'hostname:port' string
+  #   2. A 'hostname:port:db' string (to select the Redis db)
+  #   3. An instance of `Redis`, `Redis::Client`
+  def redis=(connection)
+    if connection.respond_to? :split
+      host, port, db = connection.split(':')
+      @@redis = Redis.new(:host => host,:port => port,:thread_safe => true,:db => db)
+    else
+      @@redis = connection
+    end
+  end
+
+  def redis
+    return @@redis if @@redis
+    self.redis = @@redis || 'localhost:6379'
+    self.redis
+  end
+
+  def keys
+    Keys
+  end
+
+  module Keys ; end
+
+  def self.included(model)
+    model.extend ClassMethods
+    model.extend RedisSupport
+  end
+
+end

data/test/helper.rb

@@ -0,0 +1,70 @@
+require 'rubygems'
+require 'test/unit'
+
+dir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(File.join(dir, '..', 'lib'))
+$LOAD_PATH.unshift(dir)
+require 'redis_support'
+
+##
+# much of this was taken directly from the resque test suite
+#
+#
+if !system("which redis-server")
+  puts '', "** can't find `redis-server` in your path"
+  puts "** try running `sudo rake install`"
+  abort ''
+end
+
+#
+# start our own redis when the tests start,
+# kill it when they end
+#
+at_exit do
+  next if $!
+
+  if defined?(MiniTest)
+    exit_code = MiniTest::Unit.new.run(ARGV)
+  else
+    exit_code = Test::Unit::AutoRunner.run
+  end
+
+  pid = `ps -A -o pid,command | grep [r]edis-test`.split(" ")[0]
+  puts "Killing test redis server..."
+  `rm -f #{dir}/dump.rdb`
+  Process.kill("KILL", pid.to_i)
+  exit exit_code
+end
+
+puts "Starting redis for testing at localhost:9736..."
+`redis-server #{dir}/redis-test.conf`
+
+class TestClass
+  include RedisSupport
+  
+  redis_key :test_novar, "test:redis"
+  redis_key :test_var, "test:redis:VAR"
+  redis_key :test_vars, "test:redis:VAR_ONE:VAR_TWO:append"
+end
+
+TestClass.redis = "localhost:9736"
+
+##
+# test/spec/mini 3
+# http://gist.github.com/25455
+# chris@ozmm.org
+#
+def context(*args, &block)
+  return super unless (name = args.first) && block
+  require 'test/unit'
+  klass = Class.new(defined?(ActiveSupport::TestCase) ? ActiveSupport::TestCase : Test::Unit::TestCase) do
+    def self.test(name, &block)
+      define_method("test_#{name.gsub(/\W/,'_')}", &block) if block
+    end
+    def self.xtest(*args) end
+    def self.setup(&block) define_method(:setup, &block) end
+    def self.teardown(&block) define_method(:teardown, &block) end
+  end
+  (class << klass; self end).send(:define_method, :name) { name.gsub(/\W/,'_') }
+  klass.class_eval &block
+end

data/test/test_redis_support.rb

@@ -0,0 +1,54 @@
+require File.dirname(__FILE__) + '/helper'
+
+context "Redis Support" do
+  setup do
+    TestClass.redis.flushall
+    @test_class = TestClass.new
+  end
+
+  test "redis connection works as expected" do
+    assert_equal @test_class.redis, TestClass.redis
+    assert_equal "OK", @test_class.redis.set("superman", 1)
+    assert_equal "1", @test_class.redis.get("superman")
+  end
+
+  test "redis connections changes as expected" do
+    TestClass.redis = "localhost:6379"
+    assert_equal @test_class.redis, TestClass.redis
+    @test_class.redis = "localhost:9736"
+    assert_equal @test_class.redis, TestClass.redis
+  end
+
+  test "redis keys are created correctly in normal conditions" do
+    assert_equal "test:redis", TestClass::Keys.test_novar
+    assert_equal "test:redis:variable", TestClass::Keys.test_var("variable")
+    assert_equal "test:redis:variable:id:append", TestClass::Keys.test_vars("variable", "id")
+  end
+
+  test "redis key should be able to create key" do
+    assert_nothing_raised do
+      TestClass.redis_key :whatever, "this_should_work"
+    end
+  end
+
+  test "redis keys are not created if the keyname was previously used" do
+    assert_raise(RedisSupport::DuplicateRedisKeyDefinitionError) do
+      TestClass.redis_key :test_var, "this:should:fail"
+    end
+  end
+
+  test "redis key should fail when given incorrect syntax" do
+    failure_keys = %w{oh:WE_should:fail oh:WE_:fail oh:_WE:fail oh:WE_903:fail FAILPART:oh:no}
+    failure_keys.each do |failure_key|
+      assert_raise(RedisSupport::InvalidRedisKeyDefinitionError) do
+        TestClass.redis_key :failure, failure_key
+      end
+    end    
+  end
+
+  test "redis keys fails gracefully, syntax error, when key space is fucked" do
+    assert_raise(SyntaxError) do
+      TestClass.redis_key :failure, "test:redis:VAR:VAR:oops"
+    end
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification 
+name: redis_support
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- dolores
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-06-18 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: redis
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 31
+        segments: 
+        - 1
+        - 0
+        - 4
+        version: 1.0.4
+  type: :runtime
+  version_requirements: *id001
+description: "Module for adding redis functionality to classes: simple key namespacing and locking and connections"
+email: dolores@doloreslabs.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- lib/redis_support.rb
+- lib/redis_support/class_extensions.rb
+- lib/redis_support/locks.rb
+- README.md
+- test/helper.rb
+- test/test_redis_support.rb
+has_rdoc: true
+homepage: http://github.com/dolores/redis_support
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+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.3.7
+signing_key: 
+specification_version: 3
+summary: A Redis Support module
+test_files: 
+- test/helper.rb
+- test/test_redis_support.rb