redis_scripts 0.0.1

data/.gitignore

@@ -0,0 +1 @@
+/Gemfile.lock

data/CHANGELOG

@@ -0,0 +1,3 @@
+== 0.0.1 2013-01-21
+
+ * Hi.

data/Gemfile

@@ -0,0 +1,6 @@
+source :rubygems
+gemspec
+
+group :test do
+  gem 'debugger'
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) George Ogata
+
+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.markdown

@@ -0,0 +1,49 @@
+## Redis Scripts
+
+Elegant redis scripting for ruby.
+
+## Show me
+
+    require 'redis_scripts'
+
+    # Grab a redis handle.
+    redis = Redis.new
+
+    # Configure the scripts location. Can also be done globally via
+    # RedisScripts.load_path.
+    redis.scripts.load_path = '/path/to/scripts'
+
+    # Run the script at /path/to/scripts/foo.lua .
+    redis.scripts.run :foo, keys, values
+
+The call to `run` intuitively translates to a call to `EVALSHA`. If the SHA is
+not in the redis script cache, it will be loaded (with `SCRIPT LOAD`), and then
+re-executed via `EVALSHA`, ensuring future calls are optimal.
+
+## Priming the cache
+
+You can load all scripts into cache ahead of time like this:
+
+    redis.scripts.load_all
+
+You could do this, for example, each time you deploy updates to your
+application.
+
+## Emptying the cache
+
+Redis does not offer a way to list or delete individual scripts. To clear out
+the script cache, you'll need to call `redis.script 'flush'` to empty the cache
+entirely. You can then call `load_all` to reload your scripts, or just let
+subsequent calls to `run` restore them as needed.
+
+## Contributing
+
+ * [Bug reports](https://github.com/oggy/redis_scripts/issues)
+ * [Source](https://github.com/oggy/redis_scripts)
+ * Patches: Fork on Github, send pull request.
+   * Include tests where practical.
+   * Leave the version alone, or bump it in a separate commit.
+
+## Copyright
+
+Copyright (c) George Ogata. See LICENSE for details.

data/Rakefile

@@ -0,0 +1 @@
+require 'ritual'

data/lib/redis_scripts/version.rb

@@ -0,0 +1,11 @@
+class RedisScripts
+  VERSION = [0, 0, 1]
+
+  class << VERSION
+    include Comparable
+
+    def to_s
+      join('.')
+    end
+  end
+end

data/lib/redis_scripts.rb

@@ -0,0 +1,165 @@
+require 'digest/sha1'
+require 'shellwords'
+require 'redis'
+
+# Adapter for elegant Redis scripting.
+#
+# This is usually accessed as +redis.scripts+, although can also be instantiated
+# as +RedisScripts.new(redis)+.
+class RedisScripts
+  autoload :VERSION, 'redis_scripts/version'
+
+  class << self
+    # Global load path for redis scripts.
+    #
+    # redis.scripts.load_path defaults to this value for all redis clients.
+    attr_accessor :load_path
+  end
+
+  # Create a RedisScripts adapter for the given +redis+ handle.
+  def initialize(redis)
+    @redis = redis
+    @load_path = RedisScripts.load_path
+  end
+
+  # The adapter's redis handle.
+  attr_reader :redis
+
+  # Paths to look for Redis scripts.
+  #
+  # These directories are searched recursively for all .lua files. Defaults to
+  # RedisScripts.load_path, which itself has no default, so one of these needs
+  # to be set.
+  #
+  # Like the ruby load path, earlier directories shadow later directories in the
+  # event two directories contain scripts with the same name.
+  attr_accessor :load_path
+
+  # Run the script named +name+ with the given +args+.
+  #
+  # +name+ is the path of the script relative to the +load_path+, minus the
+  # '.lua' extension. So if the load_path contains 'scripts', and the script is
+  # at 'scripts/foo/bar.lua', then +name+ should be 'foo/bar'. +name+ may be a
+  # string or symbol.
+  #
+  # +args+ are passed to Redis#evalsha (see documentation for the Redis gem). If
+  # the script is not yet loaded in the redis script cache, it is loaded and
+  # called again. Note that this means this should not be called inside a MULTI
+  # transaction - this is usually not a problem, since the purpose of scripting
+  # is to perform a sequence of atomic operations in a single command.
+  #
+  # Raises ArgumentError if no such script exists.
+  def run(name, *args)
+    script = script(name)
+    begin
+      redis.evalsha script.sha, *args
+    rescue Redis::CommandError => error
+      error.message.include?('NOSCRIPT') or
+        raise
+      sha, value = redis.pipelined do
+        redis.script 'load', script.content
+        redis.evalsha(script.sha, *args)
+      end
+      sha == script.sha or
+        raise SHAMismatch, "SHA mismatch for #{name}: expected #{script.sha}, got #{sha}"
+      value
+    end
+  end
+
+  # Call EVAL for the named script.
+  #
+  # Raises ArgumentError if no such script exists.
+  def eval(name, *args)
+    redis.eval script(name).content, *args
+  end
+
+  # Call SCRIPT LOAD for the named script.
+  #
+  # Raises ArgumentError if no such script exists.
+  def load(name)
+    redis.script 'load', script(name).content
+  end
+
+  # Call SCRIPT LOAD for all scripts.
+  #
+  # This effectively primes the script cache with all your scripts. It does not
+  # remove any scripts - use +redis.script('flush')+ to empty the script cache
+  # first if that is required.
+  def load_all
+    scripts.each do |name, script|
+      redis.script 'load', script.content
+    end
+  end
+
+  # Call SCRIPT EXISTS for the named script.
+  #
+  # Raises ArgumentError if no such script exists.
+  def exists(name)
+    redis.script 'exists', script(name).sha
+  end
+
+  # Call EVALSHA for the named script.
+  #
+  # Raises ArgumentError if no such script exists.
+  def evalsha(name, *args)
+    redis.evalsha script(name).sha, *args
+  end
+
+  # Return the named script, as a Script object.
+  #
+  # Raises ArgumentError if no such script exists.
+  def script(name)
+    scripts[name.to_s] or
+      raise ArgumentError, "no such script: #{name}"
+  end
+
+  # Represents a script in a lua file under the load path.
+  Script = Struct.new(:name, :path) do
+    # The SHA1 of the content of the script.
+    def sha
+      @sha ||= Digest::SHA1.file(path).to_s
+    end
+
+    # The content of the script.
+    def content
+      @content = File.read(path)
+    end
+  end
+
+  # Raised when Redis returns an unexpected SHA when loading a script into the
+  # redis script cache.
+  #
+  # Should never happen.
+  SHAMismatch = Class.new(RuntimeError)
+
+  private
+
+  def scripts
+    @scripts ||= find_scripts
+  end
+
+  def find_scripts
+    scripts = {}
+    @load_path.each do |path|
+      command = ['find', path, '-name', '*.lua'].shelljoin
+      prefix = /^#{Regexp.escape(path)}#{File::SEPARATOR}/
+      `#{command} 2> /dev/null`.lines.each do |path|
+        path.chomp!
+        name = path.sub(prefix, '').sub(/\.lua\z/, '')
+        scripts[name] ||= Script.new(name, path)
+      end
+    end
+    scripts
+  end
+
+  module Mixin
+    # Return a RedisScripts adapter for this redis handle.
+    #
+    # See RedisScripts for details.
+    def scripts
+      @scripts ||= RedisScripts.new(self)
+    end
+  end
+
+  Redis.__send__ :include, Mixin
+end

data/redis_scripts.gemspec

@@ -0,0 +1,20 @@
+$:.unshift File.expand_path('lib', File.dirname(__FILE__))
+require 'redis_scripts/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'redis_scripts'
+  gem.version       = RedisScripts::VERSION
+  gem.authors       = ['George Ogata']
+  gem.email         = ['george.ogata@gmail.com']
+  gem.description   = "Elegant redis scripting for ruby."
+  gem.summary       = "Elegant redis scripting for ruby."
+  gem.homepage      = 'https://github.com/oggy/redis_scripts'
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+
+  gem.add_runtime_dependency 'redis', '~> 3.0.0'
+  gem.add_development_dependency 'temporaries', '~> 0.3.0'
+  gem.add_development_dependency 'ritual', '~> 0.4.1'
+end

data/test/test_helper.rb

@@ -0,0 +1,15 @@
+ROOT = File.expand_path('..', File.dirname(__FILE__))
+Bundler.require(:test)
+
+$:.unshift "#{ROOT}/lib"
+require 'redis_scripts'
+require 'minitest/spec'
+require 'temporaries'
+
+require 'yaml'
+config_path = "#{ROOT}/redis.yml"
+if File.exist?(config_path)
+  REDIS_CONFIG = YAML.load_file(config_path)
+else
+  REDIS_CONFIG = {url: 'redis://localhost:6379'}
+end

data/test/test_redis_scripts.rb

@@ -0,0 +1,147 @@
+require_relative 'test_helper'
+
+describe RedisScripts do
+  use_temporary_directory "#{ROOT}/test/tmp"
+
+  let(:redis) { Redis.new(REDIS_CONFIG) }
+  let(:scripts) { redis.scripts }
+
+  before do
+    redis.flushall
+    redis.script 'flush'
+  end
+
+  after do
+    redis.quit
+  end
+
+  describe "#initialize" do
+    it "defaults the load path to the global one, if available" do
+      RedisScripts.load_path = ['global']
+      scripts.load_path.must_equal ['global']
+    end
+
+    it "finds scripts in all load path directories" do
+      write_file "#{tmp}/1/a.lua", "return 'a'"
+      write_file "#{tmp}/2/b.lua", "return 'b'"
+      scripts.load_path = ["#{tmp}/1", "#{tmp}/2"]
+      scripts.script('a').name.must_equal 'a'
+      scripts.script('b').name.must_equal 'b'
+    end
+
+    it "finds scripts in nested directories" do
+      write_file "#{tmp}/a/b.lua", "return 'a/b'"
+      scripts.load_path = [tmp]
+      scripts.script('a/b').name.must_equal 'a/b'
+    end
+
+    it "favors scripts that come earlier in the load path" do
+      write_file "#{tmp}/1/a.lua", "return 'a'"
+      write_file "#{tmp}/2/a.lua", "return 'b'"
+      scripts.load_path = ["#{tmp}/1", "#{tmp}/2"]
+      scripts.eval('a', [], []).must_equal 'a'
+    end
+  end
+
+  describe "#script" do
+    it "returns the named script if it exists" do
+      write_file "#{tmp}/a.lua", "return 'a'"
+      scripts.load_path = [tmp]
+      scripts.script('a').must_be_instance_of(RedisScripts::Script)
+    end
+
+    it "raises an ArgumentError if no such script exists" do
+      scripts.load_path = [tmp]
+      -> { scripts.script('a') }.must_raise(ArgumentError)
+    end
+
+    it "supports a Symbol argument" do
+      write_file "#{tmp}/a.lua", "return 'a'"
+      scripts.load_path = [tmp]
+      scripts.script(:a).must_be_instance_of(RedisScripts::Script)
+    end
+  end
+
+  describe "#load" do
+    it "loads the named script into the script cache" do
+      write_file "#{tmp}/a.lua", "return 'a'"
+      scripts.load_path = [tmp]
+      scripts.load 'a'
+      redis.script('exists', Digest::SHA1.hexdigest("return 'a'")).must_equal true
+    end
+
+    it "raises ArgumentError if there is no such script" do
+      scripts.load_path = [tmp]
+      -> { scripts.load('a', [], []) }.must_raise(ArgumentError)
+    end
+  end
+
+  describe "#load_all" do
+    it "loads all scripts into the script cache" do
+      write_file "#{tmp}/a.lua", "return 'a'"
+      write_file "#{tmp}/b.lua", "return 'b'"
+      scripts.load_path = [tmp]
+      scripts.load_all
+      redis.script('exists', Digest::SHA1.hexdigest("return 'a'")).must_equal true
+      redis.script('exists', Digest::SHA1.hexdigest("return 'b'")).must_equal true
+    end
+  end
+
+  describe "#exists" do
+    it "runs SCRIPT EXISTS for the named script" do
+      write_file "#{tmp}/a.lua", "return 'a'"
+      write_file "#{tmp}/b.lua", "return 'b'"
+      scripts.load_path = [tmp]
+      scripts.load 'a'
+      scripts.exists('a').must_equal true
+      scripts.exists('b').must_equal false
+    end
+
+    it "raises ArgumentError if there is no such script" do
+      scripts.load_path = [tmp]
+      -> { scripts.exists('a', [], []) }.must_raise(ArgumentError)
+    end
+  end
+
+  describe "#evalsha" do
+    it "runs EVALSHA for the named script" do
+      write_file "#{tmp}/a.lua", "return 'a'"
+      write_file "#{tmp}/b.lua", "return 'b'"
+      scripts.load_path = [tmp]
+      scripts.load 'a'
+      scripts.evalsha('a', [], []).must_equal 'a'
+      -> { scripts.evalsha('b', [], []) }.must_raise(Redis::CommandError)
+    end
+
+    it "raises ArgumentError if there is no such script" do
+      scripts.load_path = [tmp]
+      -> { scripts.evalsha('a', [], []) }.must_raise(ArgumentError)
+    end
+  end
+
+  describe "#run" do
+    it "evaluates the named script" do
+      write_file "#{tmp}/a.lua", "return 'a'"
+      scripts.load_path = [tmp]
+      scripts.run('a', [], []).must_equal 'a'
+      scripts.run('a', [], []).must_equal 'a'  # cached case
+    end
+
+    it "loads the script into cache for fast subsequent execution" do
+      write_file "#{tmp}/a.lua", "return 'a'"
+      scripts.load_path = [tmp]
+      scripts.run('a', [], [])
+      redis.script('exists', Digest::SHA1.hexdigest("return 'a'")).must_equal true
+    end
+
+    it "raises ArgumentError if there is no such script" do
+      scripts.load_path = [tmp]
+      -> { scripts.run('a', [], []) }.must_raise(ArgumentError)
+    end
+  end
+
+  def write_file(path, content)
+    FileUtils.mkdir_p File.dirname(path)
+    open(path, 'w') { |f| f.print content }
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: redis_scripts
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- George Ogata
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: temporaries
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: ritual
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+description: Elegant redis scripting for ruby.
+email:
+- george.ogata@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- CHANGELOG
+- Gemfile
+- LICENSE
+- README.markdown
+- Rakefile
+- lib/redis_scripts.rb
+- lib/redis_scripts/version.rb
+- redis_scripts.gemspec
+- test/test_helper.rb
+- test/test_redis_scripts.rb
+homepage: https://github.com/oggy/redis_scripts
+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.23
+signing_key: 
+specification_version: 3
+summary: Elegant redis scripting for ruby.
+test_files:
+- test/test_helper.rb
+- test/test_redis_scripts.rb
+has_rdoc: