wolverine 0.2.2 → 0.2.3

data/.gitignore

@@ -2,3 +2,5 @@
 .bundle
 Gemfile.lock
 pkg/*
+doc
+.yardoc/*

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode
+

data/README.md

@@ -1,12 +1,10 @@
-# Wolverine
+# Wolverine [![Build Status](https://secure.travis-ci.org/burke/wolverine.png)](http://travis-ci.org/burke/wolverine) [![Dependency Status](https://gemnasium.com/Shopify/wolverine.png)](https://gemnasium.com/Shopify/wolverine)
 
 Wolverine is a simple library to allow you to manage and run redis server-side lua scripts from a rails app, or other ruby code.
 
-## What are you talking about?
+Redis versions 2.6 and up allow lua scripts to be run on the server that execute atomically and very quickly.
 
-Redis versions 2.6 and up allow lua scripts to be run on the server that execute atomically and very, very quickly.
-
-This is really, really cool.
+This is *extremely* useful.
 
 Wolverine is a wrapper around that functionality, to package it up in a format more familiar to a Rails codebase.
 
@@ -53,8 +51,9 @@ Available configuration options:
 
 * `Wolverine.config.redis` (default `Redis.new`)
 * `Wolverine.config.script_path` (default `Rails.root + 'app/wolverine'`)
+* `Wolverine.config.instrumentation` (default none)
 
-If you want to override one or both of these, doing so in an initializer is recommended but not required.
+If you want to override one or more of these, doing so in an initializer is recommended but not required. See the [full documentation](http://shopify.github.com/wolverine/Wolverine/Configuration.html) for more details.
 
 ## More information
 
@@ -62,7 +61,7 @@ For more information on scripting redis with lua, refer to redis' excellent docu
 
 ## License
 
-Copyright (C) 2012 Shopify
+Copyright (C) 2012 [Shopify](http://shopify.com) by [Burke Libbey](http://burkelibbey.org)
 
 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:
 

data/Rakefile

@@ -5,4 +5,18 @@ Rake::TestTask.new do |t|
   t.pattern = "test/**/*_test.rb"
 end
 
-task default: :test
+require 'yard'
+require 'yard/rake/yardoc_task'
+YARD::Rake::YardocTask.new do |yardoc|
+  yardoc.options = ['--verbose']
+  # yardoc.files = [
+  #   'lib/**/*.rb', 'README.md', 'CHANGELOG.md', 'LICENSE'
+  # ]
+end
+
+task :docs do
+  Rake::Task['yard'].invoke
+  system("cd doc && git add . && git commit -am 'Regenerated docs' && git push origin gh-pages")
+end
+
+task :default => :test

data/TODO

@@ -1,5 +1,2 @@
-- be smarter about trimming and rearranging the backtrace
-- cache methods on Wolverine, rather than using mm all the time
-- clean up error handling method
-- Re-evaluate what actually needs to be exposed as public
-- Think of more TODO items
+- cache methods on Wolverine, rather than using method_missing all the time
+- better tests around error handling and stacktrace trimming

data/lib/wolverine.rb

@@ -8,26 +8,46 @@ require 'wolverine/path_component'
 require 'wolverine/lua_error'
 
 module Wolverine
+  # Returns the configuration object for reading and writing
+  # configuration values.
+  #
+  # @return [Wolverine::Configuration] the configuration object
   def self.config
     @config ||= Configuration.new
   end
 
+  # Provides access to the redis connection currently in use by Wolverine.
+  #
+  # @return [Redis] the redis connection used by Wolverine
   def self.redis
     config.redis
   end
 
+  # Resets all the scripts cached by Wolverine. Scripts are lazy-loaded and
+  # cached in-memory, so if a file changes on disk, it will be necessary to
+  # manually reset the cache using +reset!+.
+  #
+  # @return [void]
   def self.reset!
     @root_directory = nil
   end
 
-  def self.root_directory
-    @root_directory ||= PathComponent.new(config.script_path)
-  end
-
+  # Used to handle dynamic accesses to scripts. Successful lookups will be
+  # cached on the {PathComponent} object. See {PathComponent#method_missing}
+  # for more detail on how this works.
+  #
+  # @return [PathComponent, Object] a PathComponent if the method maps to a
+  #   directory, or an execution result if the the method maps to a lua file.
   def self.method_missing sym, *args
-    root_directory.send(sym, *args) 
+    root_directory.send(sym, *args)
   rescue PathComponent::MissingTemplate
-    super 
+    super
+  end
+
+  private
+
+  def self.root_directory
+    @root_directory ||= PathComponent.new(config.script_path)
   end
 
 end

data/lib/wolverine/configuration.rb

@@ -1,9 +1,30 @@
 module Wolverine
-  class Configuration < Struct.new(:redis, :script_path)
+  class Configuration < Struct.new(:redis, :script_path, :instrumentation)
+
+    # @return [Redis] the redis connection actively in use by Wolverine
     def redis
       super || @redis ||= Redis.new
     end
 
+    # Wolverine.config.instrumentation can be used to specify a callback to
+    # fire with the runtime of each script. This can be useful for analyzing
+    # scripts to make sure they aren't running for an unreasonable amount of
+    # time.
+    # 
+    # The proc will receive three parameters: 
+    # 
+    # * +script_name+: A unique identifier for the script, based on its
+    #   location in the file system
+    # * +runtime+: A float, the total execution time of the script
+    # * +eval_type+: Either +eval+ or +evalsha+, the method used to run
+    #   the script
+    # @return [#call] the proc or other callable to be triggered on completion
+    #   of a script.
+    def instrumentation
+      super || @instrumentation ||= proc { |script_name, runtime, eval_type| nil }
+    end
+
+    # @return [Pathname] the path wolverine will check for scripts
     def script_path
       super || @script_path ||= Rails.root + 'app/wolverine'
     end

data/lib/wolverine/lua_error.rb

@@ -1,29 +1,43 @@
 module Wolverine
+  # Reformats errors raised by redis representing failures while executing
+  # a lua script. The default errors have confusing messages and backtraces,
+  # and a type of +RuntimeError+. This class improves the message and
+  # modifies the backtrace to include the lua script itself in a reasonable
+  # way.
   class LuaError < StandardError
     PATTERN = /ERR Error (compiling|running) script \(.*?\): \[.*?\]:(\d+): (.*)/
     WOLVERINE_LIB_PATH = File.expand_path('../../', __FILE__)
 
-    def self.intercepts?(e)
-      e.message =~ PATTERN
+    # Is this error one that should be reformatted?
+    #
+    # @param error [StandardError] the original error raised by redis
+    # @return [Boolean] is this an error that should be reformatted?
+    def self.intercepts? error
+      error.message =~ PATTERN
     end
 
-    attr_reader :error, :file
-    def initialize(error, file)
+    # Initialize a new {LuaError} from an existing redis error, adjusting
+    # the message and backtrace in the process.
+    #
+    # @param error [StandardError] the original error raised by redis
+    # @param file [Pathname] full path to the lua file the error ocurred in
+    def initialize error, file
       @error = error
       @file = file
 
-      error.message =~ PATTERN
+      @error.message =~ PATTERN
       stage, line_number, message = $1, $2, $3
 
-
-      super(message)
-      set_backtrace generate_backtrace(file, line_number)
+      super message
+      set_backtrace generate_backtrace file, line_number
     end
 
+    private
+
     def generate_backtrace(file, line_number)
-      pre_wolverine = backtrace_before_entering_wolverine(error.backtrace)
-      index_of_first_wolverine_line = (error.backtrace.size - pre_wolverine.size - 1)
-      pre_wolverine.unshift(error.backtrace[index_of_first_wolverine_line])
+      pre_wolverine = backtrace_before_entering_wolverine(@error.backtrace)
+      index_of_first_wolverine_line = (@error.backtrace.size - pre_wolverine.size - 1)
+      pre_wolverine.unshift(@error.backtrace[index_of_first_wolverine_line])
       pre_wolverine.unshift("#{file}:#{line_number}")
       pre_wolverine
     end
@@ -38,4 +52,4 @@ module Wolverine
 
   end
 
-end
+end

data/lib/wolverine/path_component.rb

@@ -1,11 +1,28 @@
 module Wolverine
+  # A {PathComponent} represents either the +Wolverine.config.script_path+
+  # directory, or a subdirectory of it. Calling (nearly) any method on it will
+  # cause it to look in the filesystem at the location it refers to for a file
+  # or directory matching the method name. These results are cached.
+  #
+  # Calling a method that maps to a directory will return a new {PathComponent}
+  # with a +path+ referring to that directory.
+  #
+  # Calling a method that maps to a file (with +'.lua'+ automatically appended
+  # to the name) will load the file via {Script} and call it with the
+  # arugments passed, returning the result ({method_missing}).
   class PathComponent
     class MissingTemplate < StandardError ; end
 
+    # @param path [Pathname] full path to the current file or directory
     def initialize path
       @path = path
     end
 
+    # @param sym [Symbol] the file or directory to look up and execute
+    # @param args [*Objects] arguments to pass to the {Script}, if +sym+ resolves to a lua file
+    # @return [PathComponent, Object] A new, nested {PathComponent} if +sym+ resolves to
+    #   a directory, or an execution result if it resolves to a file.
+    # @raise [MissingTemplate] if +sym+ maps to neither a directory or a file
     def method_missing sym, *args
       create_method sym, *args
       send sym, *args
@@ -50,4 +67,4 @@ module Wolverine
 
   end
 
-end
+end

data/lib/wolverine/script.rb

@@ -1,15 +1,33 @@
+require 'pathname'
+require 'benchmark'
 require 'digest/sha1'
 
 module Wolverine
-
+  # {Script} represents a lua script in the filesystem. It loads the script
+  # from disk and handles talking to redis to execute it. Error handling
+  # is handled by {LuaError}.
   class Script
-    attr_reader :content, :digest, :file
+
+    # Loads the script file from disk and calculates its +SHA1+ sum.
+    #
+    # @param file [Pathname] the full path to the indicated file
     def initialize file
-      @file = file
+      @file = Pathname.new(file)
       @content = load_lua file
       @digest = Digest::SHA1.hexdigest @content
     end
 
+    # Passes the script and supplied arguments to redis for evaulation.
+    # It first attempts to use a script redis has already cached by using
+    # the +EVALSHA+ command, but falls back to providing the full script
+    # text via +EVAL+ if redis has not seen this script before. Future
+    # invocations will then use +EVALSHA+ without erroring.
+    #
+    # @param redis [Redis] the redis connection to run against
+    # @param args [*Objects] the arguments to the script
+    # @return [Object] the value passed back by redis after script execution
+    # @raise [LuaError] if the script failed to compile of encountered a
+    #   runtime error
     def call redis, *args
       begin
         run_evalsha redis, *args
@@ -17,8 +35,8 @@ module Wolverine
         e.message =~ /NOSCRIPT/ ? run_eval(redis, *args) : raise
       end
     rescue => e
-      if LuaError.intercepts?(e) 
-        raise LuaError.new(e, file)
+      if LuaError.intercepts?(e)
+        raise LuaError.new(e, @file)
       else
         raise
       end
@@ -27,11 +45,26 @@ module Wolverine
     private
 
     def run_evalsha redis, *args
-      redis.evalsha digest, args.size, *args
+      instrument :evalsha do
+        redis.evalsha @digest, args.size, *args
+      end
     end
 
     def run_eval redis, *args
-      redis.eval content, args.size, *args
+      instrument :eval do
+        redis.eval @content, args.size, *args
+      end
+    end
+
+    def instrument eval_type
+      ret = nil
+      runtime = Benchmark.realtime { ret = yield }
+      Wolverine.config.instrumentation.call relative_path.to_s, runtime, eval_type
+      ret
+    end
+
+    def relative_path
+      path = @file.relative_path_from(Wolverine.config.script_path)
     end
 
     def load_lua file

data/lib/wolverine/version.rb

@@ -1,3 +1,3 @@
 module Wolverine
-  VERSION = "0.2.2"
+  VERSION = "0.2.3"
 end

data/test/integration/wolverine_integration_test.rb

@@ -1,4 +1,4 @@
-require_relative '../test_helper'
+require File.join(File.expand_path('../../test_helper', __FILE__))
 
 class WolverineIntegrationTest < MiniTest::Unit::TestCase
 

data/test/wolverine/configuration_test.rb

@@ -1,4 +1,4 @@
-require_relative '../test_helper'
+require File.join(File.expand_path('../../test_helper', __FILE__))
 require 'pathname'
 
 module Rails
@@ -19,6 +19,11 @@ module Wolverine
       assert_equal Pathname.new('foo/app/wolverine'), actual
     end
 
+    def test_default_instrumentation
+      config = Wolverine::Configuration.new
+      assert_equal nil, config.instrumentation.call(1, 2, 3)
+    end
+
     def test_setting_redis
       config = Wolverine::Configuration.new
       config.redis = :foo
@@ -31,5 +36,11 @@ module Wolverine
       assert_equal :foo, config.script_path
     end
 
+    def test_setting_instrumentation
+      config = Wolverine::Configuration.new
+      config.instrumentation = proc { |a, b, c| :omg }
+      assert_equal :omg, config.instrumentation.call(1,2,3)
+    end
+
   end
 end

data/test/wolverine/path_component_test.rb

@@ -1,4 +1,4 @@
-require_relative '../test_helper'
+require File.join(File.expand_path('../../test_helper', __FILE__))
 
 module Wolverine
   class PathComponentTest < MiniTest::Unit::TestCase
@@ -27,4 +27,4 @@ module Wolverine
     end
 
   end
-end
+end

data/test/wolverine/script_test.rb

@@ -1,4 +1,4 @@
-require_relative '../test_helper'
+require File.join(File.expand_path('../../test_helper', __FILE__))
 require 'digest/sha1'
 
 module Wolverine
@@ -7,49 +7,47 @@ module Wolverine
     DIGEST = Digest::SHA1.hexdigest(CONTENT)
 
     def setup
-      Wolverine::Script.any_instance.stubs(load_lua: CONTENT)
+      base = Pathname.new('/a/b/c/d')
+      Wolverine.config.script_path = base
+      Wolverine::Script.any_instance.stubs(:load_lua => CONTENT)
     end
 
-    def script
-      @script ||= Wolverine::Script.new('file1')
+    def teardown
+      Wolverine.config.instrumentation = proc{}
     end
 
-    def test_compilation_error
-      base = Pathname.new('/a/b/c/d')
-      file = Pathname.new('/a/b/c/d/e/file1.lua')
-      Wolverine.config.script_path = base
-      begin
-        script = Wolverine::Script.new(file)
-        script.instance_variable_set("@content", "asdfasdfasdf+31f")
-        script.instance_variable_set("@digest", "79437f5edda13f9c1669b978dd7a9066dd2059f1")
-        script.call(Redis.new)
-      rescue Wolverine::LuaError => e
-        assert_equal "'=' expected near '+'", e.message
-        assert_equal "/a/b/c/d/e/file1.lua:1", e.backtrace.first
-        assert_match /script.rb/, e.backtrace[1]
-      end
+    def script
+      @script ||= Wolverine::Script.new('/a/b/c/d/e/file1.lua')
     end
 
-    def test_runtime_error
-      base = Pathname.new('/a/b/c/d')
-      file = Pathname.new('/a/b/c/d/e/file1.lua')
-      Wolverine.config.script_path = base
+    def test_error
+      redis = stub
+      redis.expects(:evalsha).raises(%q{ERR Error running script (call to f_178d75adaa46af3d8237cfd067c9fdff7b9d504f): [string "func definition"]:1: attempt to compare nil with number})
       begin
-        script = Wolverine::Script.new(file)
-        script.instance_variable_set("@content", "return nil > 3")
-        script.instance_variable_set("@digest", "39437f5edda13f9c1669b978dd7a9066dd2059f1")
-        script.call(Redis.new)
+        script.call(redis)
       rescue Wolverine::LuaError => e
-        assert_equal "attempt to compare number with nil", e.message
+        assert_equal "attempt to compare nil with number", e.message
         assert_equal "/a/b/c/d/e/file1.lua:1", e.backtrace.first
         assert_match /script.rb/, e.backtrace[1]
       end
     end
 
-    def test_digest_and_content
-      content = "return 1" 
-      assert_equal CONTENT, script.content
-      assert_equal DIGEST, script.digest
+    def test_instrumentation
+      callback = Object.new
+      tc = self
+      meta = class << callback ; self ; end
+      meta.send(:define_method, :call) { |a, b, c|
+        tc.assert_equal "e/file1.lua", a
+        tc.assert_operator b, :<, 1
+        tc.assert_equal :evalsha, c
+      }
+      Wolverine.config.instrumentation = callback
+      redis = Class.new do
+        define_method(:evalsha) do |digest, size, *args|
+          nil
+        end
+      end
+      script.call(redis.new, :a, :b)
     end
 
     def test_call_with_cache_hit

data/test/wolverine_test.rb

@@ -1,4 +1,4 @@
-require_relative 'test_helper'
+require File.join(File.expand_path('../test_helper', __FILE__))
 
 class WolverineTest < MiniTest::Unit::TestCase
 

data/wolverine.gemspec

@@ -18,7 +18,9 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_runtime_dependency 'redis'
-  s.add_development_dependency 'mocha'
-  s.add_development_dependency 'minitest'
+  s.add_runtime_dependency     'redis',    '~> 2.2.2'
+  s.add_development_dependency 'mocha',    '~> 0.10.5'
+  s.add_development_dependency 'minitest', '~> 2.11.3'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'yard'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wolverine
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,22 +9,44 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-03 00:00:00.000000000 Z
+date: 2012-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
-  requirement: &70197029666560 !ruby/object:Gem::Requirement
+  requirement: &70155163744540 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.2.2
   type: :runtime
   prerelease: false
-  version_requirements: *70197029666560
+  version_requirements: *70155163744540
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &70197029690560 !ruby/object:Gem::Requirement
+  requirement: &70155163743720 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.10.5
+  type: :development
+  prerelease: false
+  version_requirements: *70155163743720
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &70155163743080 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.11.3
+  type: :development
+  prerelease: false
+  version_requirements: *70155163743080
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70155163742680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70197029690560
+  version_requirements: *70155163742680
 - !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: &70197029689640 !ruby/object:Gem::Requirement
+  name: yard
+  requirement: &70155163742180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +65,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70197029689640
+  version_requirements: *70155163742180
 description: Wolverine provides a simple way to run server-side redis scripts from
   a rails app
 email:
@@ -53,6 +75,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE
 - README.md
@@ -109,3 +132,4 @@ test_files:
 - test/wolverine/path_component_test.rb
 - test/wolverine/script_test.rb
 - test/wolverine_test.rb
+has_rdoc: