shavaluator 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 43d2339fcfa21cdc7ab98bd19be457c4ec1675d4
+  data.tar.gz: 441c001a06b3b2fb0f642a4c8b0bfaf7804fa91f
+SHA512:
+  metadata.gz: de247f58819511ee9006857985677815fff46d39bd0ad61eac46661d0446e7a7917d5dd238eb97024dc83f8262d45cc3e37b943abdf8f97200b97ba1fecf6583
+  data.tar.gz: f0bc3bbc2477d69842301b1d69e1bbd43ef58ce58411ba030fb8a5b76759f60c77498492af69cf3ad11a664d6892699d1c9549650570ff56a1e03492066ca390

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Jeff Lee <jeffomatic@gmail.com>
+
+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

@@ -0,0 +1,104 @@
+# shavaluator
+
+This library provides a convenient wrapper for sending Lua scripts to a Redis server via `EVALSHA`.
+
+## What is EVALSHA?
+
+`EVALSHA` allows you to send Lua scripts to a Redis server by sending the SHA-1 hashes instead of actual script content. As long as the body of your script was previously sent to Redis via `EVAL` or `SCRIPT LOAD`, you can use `EVALSHA` to avoid the overhead of sending your entire Lua script over the network.
+
+A Shavaluator object wraps a Redis client for executing Lua scripts. When executing Lua scripts, a shavaluator will always attempt `EVALSHA` first, falling back on `EVAL` if the script has not yet been cached by the Redis server.
+
+## Example
+
+```ruby
+require 'redis'
+require 'shavaluator'
+
+# 1. Initialize a shavaluator with a Redis client
+redis = Redis.new(:host => '127.0.0.1', :port => 6379)
+shavaluator = Shavaluator.new(:redis => redis)
+
+# 2. Add a series of named Lua scripts to the shavaluator.
+shavaluator.add(
+  :delequal => """
+    if redis.call('GET', KEYS[1]) == ARGV[1] then
+      return redis.call('DEL', KEYS[i])
+    end
+    return 0
+   """
+)
+
+# 3. The 'delequal' script is now added to the shavaluator and bound
+#    as a method. When you call this, the shavaluator will first attempt
+#    an EVALSHA, and fall back onto EVAL.
+shavaluator.delequal :keys => ['key'], :argv => ['val']
+```
+
+## Adding scripts
+
+Before you can run Lua scripts, you should give each one a name and add them to a shavaluator.
+
+```ruby
+scripts = {
+  :delequal => """
+    if redis.call('GET', KEYS[1]) == ARGV[1] then
+      return redis.call('DEL', KEYS[i])
+    end
+    return 0
+   """,
+
+  :zmembers => """
+    local key = KEYS[1]
+    local results = {}
+    if redis.call('ZCARD', key) == 0 then
+      return {}
+    end
+    for i = 1, #ARGV, 1 do
+      local memberName = ARGV[i]
+      if redis.call('ZSCORE', key, memberName) then
+        table.insert(results, memberName)
+      end
+    end
+    return results
+   """,
+}
+
+shavaluator.add scripts
+```
+
+Adding a script does two things by default: it generates the SHA-1 of the script body, and binds the script name as a method on the shavaluator object. It **does not** perform any network operations, such as sending `SCRIPT LOAD` to the Redis server.
+
+## Executing scripts
+
+By default, adding a script to a shavaluator will bind each script as a method on the shavaluator object. These methods preserve [redis-rb](https://github.com/redis/redis-rb)'s calling convention for Lua scripts, where keys and script arguments are either passed via a hash, or as a pair of arrays.
+
+- **hash**: `shavaluator.your_script :keys => ['key1', 'key2'], :argv => ['arg1', 'arg2']`
+- **array pair**: `shavaluator.your_script ['key1', 'key2'], ['arg1', 'arg2']`
+
+If you don't like the auto-binding interface, you can use the `exec` function, which takes the name of a script.
+
+```ruby
+shavaluator.exec 'your_script', :keys => ['key1', 'key2'], :argv => ['arg1', 'arg2']
+```
+
+## Class reference
+
+### new(opts)
+
+Creates a new Shavaluator object.
+
+Options:
+
+- `:redis`: (required) an instance of a [redis-rb](https://github.com/redis/redis-rb) client that the Shavaluator will use to connect to a Redis server.
+
+### add(scripts, opts = {})
+
+Adds Lua scripts to the shavaluator. scripts is a key/value object, mapping script names to script bodies.
+
+Options:
+
+- `:bind`: (defaults to `true`) new methods will be created for each script.
+
+### exec(script_name, params...)
+
+Executes the script corresponding to the provided `script_name`. Script parameters can be passed in two different ways. See [Executing scripts](#executing-scripts) for usage examples.

data/lib/shavaluator.rb

@@ -0,0 +1,63 @@
+require 'digest/sha1'
+
+class Shavaluator
+	def initialize(opts)
+		@redis = opts[:redis]
+		@scripts = {}
+	end
+
+	def add(scripts, opts = {})
+		defaults = {:bind => true}
+		opts = {}.merge(defaults).merge(opts)
+
+		scripts.each do |name, lua|
+			name = name.to_sym
+
+			@scripts[name.to_sym] = {
+				:lua => lua,
+				:sha => Digest::SHA1.hexdigest(lua),
+			}
+
+			if opts[:bind]
+				raise "#{name} method already defined!" if respond_to?(name)
+				define_singleton_method(name) do |*args|
+					exec name, *args
+				end
+			end
+		end
+
+		nil
+	end
+
+	# This method calls a previously-added lua script. The argument syntax
+	# is the same as redis-rb's eval and evalsha methods.
+  #
+  # @example EVAL without KEYS nor ARGV
+  #   shavaluator.exec(:script)
+  #     # => 1
+  # @example EVAL with KEYS and ARGV as array arguments
+  #   shavaluator.exec(:script, ["k1", "k2"], ["a1", "a2"])
+  #     # => [["k1", "k2"], ["a1", "a2"]]
+  # @example EVAL with KEYS and ARGV in a hash argument
+  #   shavaluator.exec(:script, :keys => ["k1", "k2"], :argv => ["a1", "a2"])
+  #     # => [["k1", "k2"], ["a1", "a2"]]
+	def exec(script, *args)
+		begin
+			s = @scripts.fetch(script.to_sym)
+		rescue KeyError
+			raise "'#{script}' script has not been added yet!"
+		end
+
+		lua, sha = s.values_at(:lua, :sha)
+
+		begin
+			@redis.evalsha(s[:sha], *args)
+		rescue Redis::CommandError => e
+			if e.to_s.match /^NOSCRIPT/
+				@redis.eval(s[:lua], *args)
+			else
+				raise
+			end
+		end
+	end
+end

data/lib/shavaluator/version.rb

@@ -0,0 +1,3 @@
+class Shavaluator
+  VERSION = '0.1'
+end

data/shavaluator.gemspec

@@ -0,0 +1,20 @@
+# encoding: utf-8
+$:.unshift File.expand_path("../lib", __FILE__)
+require 'shavaluator/version'
+
+Gem::Specification.new do |s|
+  s.name = 'shavaluator'
+  s.licenses = ['MIT']
+  s.summary = "Provides a convenient wrapper for sending Lua scripts to a Redis server via EVALSHA."
+  s.version = Shavaluator::VERSION
+  s.homepage = 'https://github.com/jeffomatic/shavaluator-rb'
+
+  s.authors = ["Jeff Lee"]
+  s.email = 'jeffomatic@gmail.com'
+
+  s.files = %w( README.md LICENSE shavaluator.gemspec )
+  s.files += Dir.glob('lib/**/*')
+
+  s.add_development_dependency('rspec', '~>3.1.0')
+  s.add_development_dependency('redis', '~>3.2.0')
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: shavaluator
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Jeff Lee
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+description: 
+email: jeffomatic@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/shavaluator.rb
+- lib/shavaluator/version.rb
+- shavaluator.gemspec
+homepage: https://github.com/jeffomatic/shavaluator-rb
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.2
+signing_key: 
+specification_version: 4
+summary: Provides a convenient wrapper for sending Lua scripts to a Redis server via
+  EVALSHA.
+test_files: []