redis-namespace 1.5.2 → 1.8.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 781a6361b78e31842c9fe934161b83e1acf9d1c1ef50cd015694b78582b461ac
+  data.tar.gz: a0856e98fb69b1063c460ef1479dd57a4659741612b398d3fac2d4bb3727e1b0
+SHA512:
+  metadata.gz: caf163b05d1f4c5f08a29d4d1f977d666f1a627b582af762f50d883df64f0f2139fe132918edbc6c59d9259f386f7ed7a094da3493579072f25d9c957da7e7eb
+  data.tar.gz: 951f20c3aaedd77400f34b161fb642d39ff0a4e8a619506441288f6671043a3bfd3e1f18e13a62fc8e014f79d989246fcb51b351f4d3f1b6f3a2a6ce8f17bd41

data/LICENSE

@@ -1,20 +1,21 @@
+MIT License
+
 Copyright (c) 2009 Chris Wanstrath
 
-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:
+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 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.
+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

@@ -1,38 +1,103 @@
 redis-namespace
----------------
+===============
+
+Redis::Namespace provides an interface to a namespaced subset of your [redis][] keyspace (e.g., keys with a common beginning), and requires the [redis-rb][] gem.
+
+```ruby
+require 'redis-namespace'
+# => true
+
+redis_connection = Redis.new
+# => #<Redis client v3.1.0 for redis://127.0.0.1:6379/0>
+namespaced_redis = Redis::Namespace.new(:ns, redis: redis_connection)
+# => #<Redis::Namespace v1.5.0 with client v3.1.0 for redis://127.0.0.1:6379/0/ns>
+
+namespaced_redis.set('foo', 'bar') # redis_connection.set('ns:foo', 'bar')
+# => "OK"
+
+# Redis::Namespace automatically prepended our namespace to the key
+# before sending it to our redis client.
+
+namespaced_redis.get('foo')
+# => "bar"
+redis_connection.get('foo')
+# => nil
+redis_connection.get('ns:foo')
+# => "bar"
+
+namespaced_redis.del('foo')
+# => 1
+namespaced_redis.get('foo')
+# => nil
+redis_connection.get('ns:foo')
+# => nil
+```
 
-Requires the redis gem.
+Installation
+============
 
-Namespaces all Redis calls.
+Redis::Namespace is packaged as the redis-namespace gem, and hosted on rubygems.org.
 
-``` ruby
-r = Redis::Namespace.new(:ns, :redis => @r)
-r['foo'] = 1000
+From the command line:
+
+    $ gem install redis-namespace
+
+Or in your Gemfile:
+
+```ruby
+gem 'redis-namespace'
 ```
 
-This will perform the equivalent of:
+Caveats
+=======
 
-    redis-cli set ns:foo 1000
+`Redis::Namespace` provides a namespaced interface to `Redis` by keeping an internal registry of the method signatures in `Redis` provided by the [redis-rb][] gem; we keep track of which arguments need the namespace added, and which return values need the namespace removed.
 
-Useful when you have multiple systems using Redis differently in your app.
+Blind Passthrough
+-----------------
+If your version of this gem doesn't know about a particular command, it can't namespace it. Historically, this has meant that Redis::Namespace blindly passes unknown commands on to the underlying redis connection without modification which can lead to surprising effects.
 
+As of v1.5.0, blind passthrough has been deprecated, and the functionality will be removed entirely in 2.0.
 
-Installation
-============
+If you come across a command that is not yet supported, please open an issue on the [issue tracker][] or submit a pull-request.
 
-    $ gem install redis-namespace
+Administrative Commands
+-----------------------
+The effects of some redis commands cannot be limited to a particular namespace (e.g., `FLUSHALL`, which literally truncates all databases in your redis server, regardless of keyspace). Historically, this has meant that Redis::Namespace intentionally passes administrative commands on to the underlying redis connection without modification, which can lead to surprising effects.
 
+As of v1.6.0, the direct use of administrative commands has been deprecated, and the functionality will be removed entirely in 2.0; while such commands are often useful for testing or administration, their meaning is inherently hidden when placed behind an interface that implies it will namespace everything.
 
+The prefered way to send an administrative command is on the redis connection itself, which is publicly exposed as `Redis::Namespace#redis`:
 
-Testing
-=======
+```ruby
+namespaced.redis.flushall()
+# => "OK"
+```
+
+2.x Planned Breaking Changes
+============================
 
-    $ bundle install
-    $ rake
+As mentioned above, 2.0 will remove blind passthrough and the administrative command passthrough.
+By default in 1.5+, deprecation warnings are present and enabled;
+they can be silenced by initializing `Redis::Namespace` with `warnings: false` or by setting the `REDIS_NAMESPACE_QUIET` environment variable.
+
+Early opt-in
+------------
+
+To enable testing against the 2.x interface before its release, in addition to deprecation warnings, early opt-in to these changes can be enabled by initializing `Redis::Namespace` with `deprecations: true` or by setting the `REDIS_NAMESPACE_DEPRECATIONS` environment variable.
+This should only be done once all warnings have been addressed.
+
+Authors
+=======
 
+While there are many authors who have contributed to this project, the following have done so on an ongoing basis with at least 5 commits:
 
-Author
-=====
+ - Chris Wanstrath (@defunkt)
+ - Ryan Biesemeyer (@yaauie)
+ - Steve Klabnik (@steveklabnik)
+ - Terence Lee (@hone)
+ - Eoin Coffey (@ecoffey)
 
-Chris Wanstrath :: chris@ozmm.org
-Terence Lee :: hone02@gmail.com
+[redis]: http://redis.io
+[redis-rb]: https://github.com/redis/redis-rb
+[issue tracker]: https://github.com/resque/redis-namespace/issues

data/lib/redis/namespace.rb

@@ -3,7 +3,7 @@ require 'redis/namespace/version'
 
 class Redis
   class Namespace
-    # The following table defines how input parameters and result
+    # The following tables define how input parameters and result
     # values should be modified for the namespace.
     #
     # COMMANDS is a hash. Each key is the name of a command and each
@@ -53,34 +53,27 @@ class Redis
     #   :all
     #     Add the namespace to all elements returned, e.g.
     #       key1 key2 => namespace:key1 namespace:key2
-    COMMANDS = {
-      "append"           => [:first],
-      "auth"             => [],
-      "bgrewriteaof"     => [],
-      "bgsave"           => [],
+    NAMESPACED_COMMANDS = {
+      "append"           => [ :first ],
       "bitcount"         => [ :first ],
       "bitop"            => [ :exclude_first ],
+      "bitpos"           => [ :first ],
       "blpop"            => [ :exclude_last, :first ],
       "brpop"            => [ :exclude_last, :first ],
       "brpoplpush"       => [ :exclude_last ],
-      "config"           => [],
-      "dbsize"           => [],
+      "bzpopmin"         => [ :first ],
+      "bzpopmax"         => [ :first ],
       "debug"            => [ :exclude_first ],
       "decr"             => [ :first ],
       "decrby"           => [ :first ],
       "del"              => [ :all   ],
-      "discard"          => [],
-      "disconnect!"      => [],
       "dump"             => [ :first ],
-      "echo"             => [],
-      "exists"           => [ :first ],
+      "exists"           => [ :all ],
+      "exists?"          => [ :all ],
       "expire"           => [ :first ],
       "expireat"         => [ :first ],
       "eval"             => [ :eval_style ],
       "evalsha"          => [ :eval_style ],
-      "exec"             => [],
-      "flushall"         => [],
-      "flushdb"          => [],
       "get"              => [ :first ],
       "getbit"           => [ :first ],
       "getrange"         => [ :first ],
@@ -103,9 +96,7 @@ class Redis
       "incr"             => [ :first ],
       "incrby"           => [ :first ],
       "incrbyfloat"      => [ :first ],
-      "info"             => [],
       "keys"             => [ :first, :all ],
-      "lastsave"         => [],
       "lindex"           => [ :first ],
       "linsert"          => [ :first ],
       "llen"             => [ :first ],
@@ -124,7 +115,6 @@ class Redis
       "mget"             => [ :all ],
       "monitor"          => [ :monitor ],
       "move"             => [ :first ],
-      "multi"            => [],
       "mset"             => [ :alternate ],
       "msetnx"           => [ :alternate ],
       "object"           => [ :exclude_first ],
@@ -134,14 +124,11 @@ class Redis
       "pfadd"            => [ :first ],
       "pfcount"          => [ :all ],
       "pfmerge"          => [ :all ],
-      "ping"             => [],
       "psetex"           => [ :first ],
       "psubscribe"       => [ :all ],
       "pttl"             => [ :first ],
       "publish"          => [ :first ],
       "punsubscribe"     => [ :all ],
-      "quit"             => [],
-      "randomkey"        => [],
       "rename"           => [ :all ],
       "renamenx"         => [ :all ],
       "restore"          => [ :first ],
@@ -150,24 +137,19 @@ class Redis
       "rpush"            => [ :first ],
       "rpushx"           => [ :first ],
       "sadd"             => [ :first ],
-      "save"             => [],
       "scard"            => [ :first ],
       "scan"             => [ :scan_style, :second ],
       "scan_each"        => [ :scan_style, :all ],
-      "script"           => [],
       "sdiff"            => [ :all ],
       "sdiffstore"       => [ :all ],
-      "select"           => [],
       "set"              => [ :first ],
       "setbit"           => [ :first ],
       "setex"            => [ :first ],
       "setnx"            => [ :first ],
       "setrange"         => [ :first ],
-      "shutdown"         => [],
       "sinter"           => [ :all ],
       "sinterstore"      => [ :all ],
       "sismember"        => [ :first ],
-      "slaveof"          => [],
       "smembers"         => [ :first ],
       "smove"            => [ :exclude_last ],
       "sort"             => [ :sort  ],
@@ -182,31 +164,75 @@ class Redis
       "sunionstore"      => [ :all ],
       "ttl"              => [ :first ],
       "type"             => [ :first ],
+      "unlink"           => [ :all   ],
       "unsubscribe"      => [ :all ],
-      "unwatch"          => [ :all ],
-      "watch"            => [ :all ],
       "zadd"             => [ :first ],
       "zcard"            => [ :first ],
       "zcount"           => [ :first ],
       "zincrby"          => [ :first ],
       "zinterstore"      => [ :exclude_options ],
+      "zpopmin"          => [ :first ],
+      "zpopmax"          => [ :first ],
       "zrange"           => [ :first ],
       "zrangebyscore"    => [ :first ],
+      "zrangebylex"      => [ :first ],
       "zrank"            => [ :first ],
       "zrem"             => [ :first ],
       "zremrangebyrank"  => [ :first ],
       "zremrangebyscore" => [ :first ],
+      "zremrangebylex"   => [ :first ],
       "zrevrange"        => [ :first ],
       "zrevrangebyscore" => [ :first ],
+      "zrevrangebylex"   => [ :first ],
       "zrevrank"         => [ :first ],
       "zscan"            => [ :first ],
       "zscan_each"       => [ :first ],
       "zscore"           => [ :first ],
-      "zunionstore"      => [ :exclude_options ],
-      "[]"               => [ :first ],
-      "[]="              => [ :first ]
+      "zunionstore"      => [ :exclude_options ]
+    }
+    TRANSACTION_COMMANDS = {
+      "discard"          => [],
+      "exec"             => [],
+      "multi"            => [],
+      "unwatch"          => [ :all ],
+      "watch"            => [ :all ],
+    }
+    HELPER_COMMANDS = {
+      "auth"             => [],
+      "disconnect!"      => [],
+      "echo"             => [],
+      "ping"             => [],
+      "time"             => [],
+    }
+    ADMINISTRATIVE_COMMANDS = {
+      "bgrewriteaof"     => [],
+      "bgsave"           => [],
+      "config"           => [],
+      "dbsize"           => [],
+      "flushall"         => [],
+      "flushdb"          => [],
+      "info"             => [],
+      "lastsave"         => [],
+      "quit"             => [],
+      "randomkey"        => [],
+      "save"             => [],
+      "script"           => [],
+      "select"           => [],
+      "shutdown"         => [],
+      "slaveof"          => [],
     }
 
+    DEPRECATED_COMMANDS = [
+      ADMINISTRATIVE_COMMANDS
+    ].compact.reduce(:merge)
+
+    COMMANDS = [
+      NAMESPACED_COMMANDS,
+      TRANSACTION_COMMANDS,
+      HELPER_COMMANDS,
+      ADMINISTRATIVE_COMMANDS,
+    ].compact.reduce(:merge)
+
     # Support 1.8.7 by providing a namespaced reference to Enumerable::Enumerator
     Enumerator = Enumerable::Enumerator unless defined?(::Enumerator)
 
@@ -223,6 +249,7 @@ class Redis
       @deprecations = !!options.fetch(:deprecations) do
                         ENV['REDIS_NAMESPACE_DEPRECATIONS']
                       end
+      @has_new_client_method = @redis.respond_to?(:_client)
     end
 
     def deprecations?
@@ -234,7 +261,13 @@ class Redis
     end
 
     def client
-      @redis.client
+      warn("The client method is deprecated as of redis-rb 4.0.0, please use the new _client" +
+            "method instead. Support for the old method will be removed in redis-namespace 2.0.") if @has_new_client_method && deprecations?
+      _client
+    end
+
+    def _client
+      @has_new_client_method ? @redis._client : @redis.client # for redis-4.0.0
     end
 
     # Ruby defines a now deprecated type method so we need to override it here
@@ -247,7 +280,9 @@ class Redis
 
     # emulate Ruby 1.9+ and keep respond_to_missing? logic together.
     def respond_to?(command, include_private=false)
-      super or respond_to_missing?(command, include_private)
+      return !deprecations? if DEPRECATED_COMMANDS.include?(command.to_s.downcase)
+
+      respond_to_missing?(command, include_private) or super
     end
 
     def keys(query = nil)
@@ -275,6 +310,14 @@ class Redis
       @namespace
     end
 
+    def full_namespace
+      redis.is_a?(Namespace) ? "#{redis.full_namespace}:#{namespace}" : namespace.to_s
+    end
+
+    def connection
+      @redis.connection.tap { |info| info[:namespace] = @namespace }
+    end
+
     def exec
       call_with_namespace(:exec)
     end
@@ -282,19 +325,46 @@ class Redis
     def eval(*args)
       call_with_namespace(:eval, *args)
     end
+    ruby2_keywords(:eval) if respond_to?(:ruby2_keywords, true)
+
+    ADMINISTRATIVE_COMMANDS.keys.each do |command|
+      define_method(command) do |*args, &block|
+        raise NoMethodError if deprecations?
+
+        if warning?
+          warn("Passing '#{command}' command to redis as is; " +
+               "administrative commands cannot be effectively namespaced " +
+               "and should be called on the redis connection directly; " +
+               "passthrough has been deprecated and will be removed in " +
+               "redis-namespace 2.0 (at #{call_site})"
+               )
+        end
+        call_with_namespace(command, *args, &block)
+      end
+      ruby2_keywords(command) if respond_to?(:ruby2_keywords, true)
+    end
+
+    COMMANDS.keys.each do |command|
+      next if ADMINISTRATIVE_COMMANDS.include?(command)
+      next if method_defined?(command)
+
+      define_method(command) do |*args, &block|
+        call_with_namespace(command, *args, &block)
+      end
+      ruby2_keywords(command) if respond_to?(:ruby2_keywords, true)
+    end
 
     def method_missing(command, *args, &block)
       normalized_command = command.to_s.downcase
 
       if COMMANDS.include?(normalized_command)
-        call_with_namespace(command, *args, &block)
+        send(normalized_command, *args, &block)
       elsif @redis.respond_to?(normalized_command) && !deprecations?
         # blind passthrough is deprecated and will be removed in 2.0
         # redis-namespace does not know how to handle this command.
         # Passing it to @redis as is, where redis-namespace shows
         # a warning message if @warning is set.
         if warning?
-          call_site = caller.reject { |l| l.start_with?(__FILE__) }.first
           warn("Passing '#{command}' command to redis as is; blind " +
                "passthrough has been deprecated and will be removed in " +
                "redis-namespace 2.0 (at #{call_site})")
@@ -304,16 +374,24 @@ class Redis
         super
       end
     end
+    ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
+
+    def inspect
+      "<#{self.class.name} v#{VERSION} with client v#{Redis::VERSION} "\
+      "for #{@redis.id}/#{full_namespace}>"
+    end
 
     def respond_to_missing?(command, include_all=false)
-      return true if COMMANDS.include?(command.to_s.downcase)
+      normalized_command = command.to_s.downcase
 
-      # blind passthrough is deprecated and will be removed in 2.0
-      if @redis.respond_to?(command, include_all) && !deprecations?
-        return true
+      case
+      when COMMANDS.include?(normalized_command)
+        true
+      when !deprecations? && redis.respond_to?(command, include_all)
+        true
+      else
+        defined?(super) && super
       end
-
-      defined?(super) && super
     end
 
     def call_with_namespace(command, *args, &block)
@@ -325,10 +403,14 @@ class Redis
 
       (before, after) = handling
 
+      # Modify the local *args array in-place, no need to copy it.
+      args.map! {|arg| clone_args(arg)}
+
       # Add the namespace to any parameters that are keys.
       case before
       when :first
         args[0] = add_namespace(args[0]) if args[0]
+        args[-1] = ruby2_keywords_hash(args[-1]) if args[-1].is_a?(Hash)
       when :all
         args = add_namespace(args)
       when :exclude_first
@@ -341,7 +423,7 @@ class Redis
         args.push(last) if last
       when :exclude_options
         if args.last.is_a?(Hash)
-          last = args.pop
+          last = ruby2_keywords_hash(args.pop)
           args = add_namespace(args)
           args.push(last)
         else
@@ -361,6 +443,7 @@ class Redis
           args[1][:get].each_index do |i|
             args[1][:get][i] = add_namespace(args[1][:get][i]) unless args[1][:get][i] == "#"
           end
+          args[1] = ruby2_keywords_hash(args[1])
         end
       when :eval_style
         # redis.eval() and evalsha() can either take the form:
@@ -381,7 +464,7 @@ class Redis
       when :scan_style
         options = (args.last.kind_of?(Hash) ? args.pop : {})
         options[:match] = add_namespace(options.fetch(:match, '*'))
-        args << options
+        args << ruby2_keywords_hash(options)
 
         if block
           original_block = block
@@ -407,9 +490,35 @@ class Redis
 
       result
     end
+    ruby2_keywords(:call_with_namespace) if respond_to?(:ruby2_keywords, true)
 
   private
 
+    if Hash.respond_to?(:ruby2_keywords_hash)
+      def ruby2_keywords_hash(kwargs)
+        Hash.ruby2_keywords_hash(kwargs)
+      end
+    else
+      def ruby2_keywords_hash(kwargs)
+        kwargs
+      end
+    end
+
+    # Avoid modifying the caller's (pass-by-reference) arguments.
+    def clone_args(arg)
+      if arg.is_a?(Array)
+        arg.map {|sub_arg| clone_args(sub_arg)}
+      elsif arg.is_a?(Hash)
+        Hash[arg.map {|k, v| [clone_args(k), clone_args(v)]}]
+      else
+        arg # Some objects (e.g. symbol) can't be dup'd.
+      end
+    end
+
+    def call_site
+      caller.reject { |l| l.start_with?(__FILE__) }.first
+    end
+
     def namespaced_block(command, &block)
       redis.send(command) do |r|
         begin
@@ -426,9 +535,10 @@ class Redis
 
       case key
       when Array
-        key.map {|k| add_namespace k}
+        key.map! {|k| add_namespace k}
       when Hash
-        Hash[*key.map {|k, v| [ add_namespace(k), v ]}.flatten]
+        key.keys.each {|k| key[add_namespace(k)] = key.delete(k)}
+        key
       else
         "#{@namespace}:#{key}"
       end