valkey-namespace 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a385b6f2e0f44403c0fe05fecc1b03823583fc5a8ae177e1b2e0a78ac6e83d31
+  data.tar.gz: 26a7e394ad8a9e6609f2397922a6084a162305fe372045faecbfff6c2f97efb1
+SHA512:
+  metadata.gz: fb54cb5c43cbec71678dfedf72c1d42b041813bf5f038d0efb80e9f7335c84965d22f4fb99a35b2d1dd9675f754de468781ffa247e93878af4e863b5590bddb2
+  data.tar.gz: 7afd85a87386b5d52f7f1cddc2be5f49f9a39156cf75f1751083ed1998e63997a8c55c78dce0026691602cac85a6f9b9a5aee6754a33d660364074259cd91564

data/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Valkey Community
+
+This project is based on redis-namespace:
+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:
+
+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/NOTICE

@@ -0,0 +1,25 @@
+valkey-namespace
+Copyright (c) 2026 Valkey Community
+
+This project is a derivative work based on redis-namespace:
+https://github.com/resque/redis-namespace
+
+redis-namespace
+Copyright (c) 2009 Chris Wanstrath
+
+Both projects are licensed under the MIT License.
+
+The original redis-namespace implementation has been adapted to work with
+the Valkey database and the valkey-glide-ruby client library. The core
+architecture, command registry patterns, and namespacing logic are derived
+from redis-namespace.
+
+Key changes in valkey-namespace:
+- Adapted to work with Valkey instead of Redis
+- Uses valkey-glide-ruby client instead of redis-rb
+- Updated naming conventions (Redis → Valkey)
+- Updated environment variables (REDIS_NAMESPACE_* → VALKEY_NAMESPACE_*)
+- Added examples and additional documentation
+
+We are grateful to the redis-namespace project and its contributors for
+their excellent work that made this adaptation possible.

data/README.md

@@ -0,0 +1,130 @@
+valkey-namespace
+===============
+
+Valkey::Namespace provides an interface to a namespaced subset of your [Valkey][] keyspace (e.g., keys with a common beginning), and requires the [valkey-glide-ruby][] gem.
+
+```ruby
+require 'valkey-namespace'
+# => true
+
+valkey_connection = Valkey.new
+# => #<Valkey client>
+namespaced_valkey = Valkey::Namespace.new(:ns, valkey: valkey_connection)
+# => #<Valkey::Namespace v1.0.0 with client for ns>
+
+namespaced_valkey.set('foo', 'bar') # valkey_connection.set('ns:foo', 'bar')
+# => "OK"
+
+# Valkey::Namespace automatically prepended our namespace to the key
+# before sending it to our valkey client.
+
+namespaced_valkey.get('foo')
+# => "bar"
+valkey_connection.get('foo')
+# => nil
+valkey_connection.get('ns:foo')
+# => "bar"
+
+namespaced_valkey.del('foo')
+# => 1
+namespaced_valkey.get('foo')
+# => nil
+valkey_connection.get('ns:foo')
+# => nil
+```
+
+Valkey::Namespace also supports `Proc` as a namespace and will take the result string as namespace at runtime.
+
+```ruby
+valkey_connection = Valkey.new
+namespaced_valkey = Valkey::Namespace.new(Proc.new { Tenant.current_tenant }, valkey: valkey_connection)
+```
+
+Installation
+============
+
+Valkey::Namespace is packaged as the valkey-namespace gem, and hosted on rubygems.org.
+
+From the command line:
+
+    $ gem install valkey-namespace
+
+Or in your Gemfile:
+
+```ruby
+gem 'valkey-namespace'
+```
+
+Caveats
+=======
+
+`Valkey::Namespace` provides a namespaced interface to `Valkey` by keeping an internal registry of the method signatures in `Valkey` provided by the [valkey-glide-ruby][] gem; we keep track of which arguments need the namespace added, and which return values need the namespace removed.
+
+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 Valkey::Namespace blindly passes unknown commands on to the underlying valkey connection without modification which can lead to surprising effects.
+
+As of v1.0.0, blind passthrough has been deprecated, and the functionality will be removed entirely in 2.0.
+
+If you come across a command that is not yet supported, please open an issue on the [issue tracker][] or submit a pull-request.
+
+Administrative Commands
+-----------------------
+The effects of some valkey commands cannot be limited to a particular namespace (e.g., `FLUSHALL`, which literally truncates all databases in your valkey server, regardless of keyspace). Historically, this has meant that Valkey::Namespace intentionally passes administrative commands on to the underlying valkey connection without modification, which can lead to surprising effects.
+
+As of v1.0.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 preferred way to send an administrative command is on the valkey connection itself, which is publicly exposed as `Valkey::Namespace#valkey`:
+
+```ruby
+namespaced.valkey.flushall()
+# => "OK"
+```
+
+2.x Planned Breaking Changes
+============================
+
+As mentioned above, 2.0 will remove blind passthrough and the administrative command passthrough.
+By default in 1.0+, deprecation warnings are present and enabled;
+they can be silenced by initializing `Valkey::Namespace` with `warning: false` or by setting the `VALKEY_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 `Valkey::Namespace` with `deprecations: true` or by setting the `VALKEY_NAMESPACE_DEPRECATIONS` environment variable.
+This should only be done once all warnings have been addressed.
+
+Compatibility
+=============
+
+This gem is designed to work with [valkey-glide-ruby][], which provides a drop-in replacement for redis-rb. It supports all Valkey commands and is API-compatible with Redis 6.2, 7.0, 7.1, and 7.2.
+
+Authors
+=======
+
+This project is based on [redis-namespace][] and adapted for Valkey.
+
+Original redis-namespace authors who contributed significantly:
+ - Chris Wanstrath (@defunkt)
+ - Ryan Biesemeyer (@yaauie)
+ - Steve Klabnik (@steveklabnik)
+ - Terence Lee (@hone)
+ - Eoin Coffey (@ecoffey)
+
+valkey-namespace adaptation:
+ - Valkey Community
+
+## License
+
+This project is licensed under the MIT License, the same as redis-namespace.
+See the LICENSE file for details.
+
+## Acknowledgments
+
+Special thanks to the redis-namespace project and its contributors for creating
+the original implementation that this project is based on.
+
+[Valkey]: https://valkey.io
+[valkey-glide-ruby]: https://github.com/valkey-io/valkey-glide-ruby
+[redis-namespace]: https://github.com/resque/redis-namespace
+[issue tracker]: https://github.com/valkey-io/valkey-namespace/issues

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/valkey/namespace/version.rb

@@ -0,0 +1,5 @@
+class Valkey
+  class Namespace
+    VERSION = "1.0.0"
+  end
+end

data/lib/valkey/namespace.rb

@@ -0,0 +1,625 @@
+# frozen_string_literal: true
+
+# This file is based on redis-namespace (https://github.com/resque/redis-namespace)
+# Copyright (c) 2009 Chris Wanstrath
+# Adapted for Valkey by the Valkey Community
+# Licensed under the MIT License
+
+require 'valkey'
+require 'valkey/namespace/version'
+
+class Valkey
+  class Namespace
+    # 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
+    # value is a two element array.
+    #
+    # The first element in the value array describes how to modify the
+    # arguments passed. It can be one of:
+    #
+    #   nil
+    #     Do nothing.
+    #   :first
+    #     Add the namespace to the first argument passed, e.g.
+    #       GET key => GET namespace:key
+    #   :all
+    #     Add the namespace to all arguments passed, e.g.
+    #       MGET key1 key2 => MGET namespace:key1 namespace:key2
+    #   :exclude_first
+    #     Add the namespace to all arguments but the first, e.g.
+    #   :exclude_last
+    #     Add the namespace to all arguments but the last, e.g.
+    #       BLPOP key1 key2 timeout =>
+    #       BLPOP namespace:key1 namespace:key2 timeout
+    #   :exclude_options
+    #     Add the namespace to all arguments, except the last argument,
+    #     if the last argument is a hash of options.
+    #       ZUNIONSTORE key1 2 key2 key3 WEIGHTS 2 1 =>
+    #       ZUNIONSTORE namespace:key1 2 namespace:key2 namespace:key3 WEIGHTS 2 1
+    #   :alternate
+    #     Add the namespace to every other argument, e.g.
+    #       MSET key1 value1 key2 value2 =>
+    #       MSET namespace:key1 value1 namespace:key2 value2
+    #   :sort
+    #     Add namespace to first argument if it is non-nil
+    #     Add namespace to second arg's :by and :store if second arg is a Hash
+    #     Add namespace to each element in second arg's :get if second arg is
+    #       a Hash; forces second arg's :get to be an Array if present.
+    #   :eval_style
+    #     Add namespace to each element in keys argument (via options hash or multi-args)
+    #   :scan_style
+    #     Add namespace to :match option, or supplies "#{namespace}:*" if not present.
+    #
+    # The second element in the value array describes how to modify
+    # the return value of the Valkey call. It can be one of:
+    #
+    #   nil
+    #     Do nothing.
+    #   :all
+    #     Add the namespace to all elements returned, e.g.
+    #       key1 key2 => namespace:key1 namespace:key2
+    NAMESPACED_COMMANDS = {
+      "append"           => [ :first ],
+      "bitcount"         => [ :first ],
+      "bitfield"         => [ :first ],
+      "bitop"            => [ :exclude_first ],
+      "bitpos"           => [ :first ],
+      "blpop"            => [ :exclude_last, :first ],
+      "brpop"            => [ :exclude_last, :first ],
+      "brpoplpush"       => [ :exclude_last ],
+      "bzpopmin"         => [ :first ],
+      "bzpopmax"         => [ :first ],
+      "debug"            => [ :exclude_first ],
+      "decr"             => [ :first ],
+      "decrby"           => [ :first ],
+      "del"              => [ :all   ],
+      "dump"             => [ :first ],
+      "exists"           => [ :all ],
+      "exists?"          => [ :all ],
+      "expire"           => [ :first ],
+      "expireat"         => [ :first ],
+      "expiretime"       => [ :first ],
+      "eval"             => [ :eval_style ],
+      "evalsha"          => [ :eval_style ],
+      "get"              => [ :first ],
+      "getex"            => [ :first ],
+      "getbit"           => [ :first ],
+      "getrange"         => [ :first ],
+      "getset"           => [ :first ],
+      "hset"             => [ :first ],
+      "hsetnx"           => [ :first ],
+      "hget"             => [ :first ],
+      "hincrby"          => [ :first ],
+      "hincrbyfloat"     => [ :first ],
+      "hmget"            => [ :first ],
+      "hmset"            => [ :first ],
+      "hdel"             => [ :first ],
+      "hexists"          => [ :first ],
+      "hlen"             => [ :first ],
+      "hkeys"            => [ :first ],
+      "hscan"            => [ :first ],
+      "hscan_each"       => [ :first ],
+      "hvals"            => [ :first ],
+      "hgetall"          => [ :first ],
+      "incr"             => [ :first ],
+      "incrby"           => [ :first ],
+      "incrbyfloat"      => [ :first ],
+      "keys"             => [ :first, :all ],
+      "lindex"           => [ :first ],
+      "linsert"          => [ :first ],
+      "llen"             => [ :first ],
+      "lpop"             => [ :first ],
+      "lpos"             => [ :first ],
+      "lpush"            => [ :first ],
+      "lpushx"           => [ :first ],
+      "lrange"           => [ :first ],
+      "lrem"             => [ :first ],
+      "lset"             => [ :first ],
+      "ltrim"            => [ :first ],
+      "mapped_hmset"     => [ :first ],
+      "mapped_hmget"     => [ :first ],
+      "mapped_mget"      => [ :all, :all ],
+      "mapped_mset"      => [ :all ],
+      "mapped_msetnx"    => [ :all ],
+      "mget"             => [ :all ],
+      "monitor"          => [ :monitor ],
+      "move"             => [ :first ],
+      "mset"             => [ :alternate ],
+      "msetnx"           => [ :alternate ],
+      "object"           => [ :exclude_first ],
+      "persist"          => [ :first ],
+      "pexpire"          => [ :first ],
+      "pexpireat"        => [ :first ],
+      "pexpiretime"      => [ :first ],
+      "pfadd"            => [ :first ],
+      "pfcount"          => [ :all ],
+      "pfmerge"          => [ :all ],
+      "psetex"           => [ :first ],
+      "psubscribe"       => [ :all ],
+      "pttl"             => [ :first ],
+      "publish"          => [ :first ],
+      "punsubscribe"     => [ :all ],
+      "rename"           => [ :all ],
+      "renamenx"         => [ :all ],
+      "restore"          => [ :first ],
+      "rpop"             => [ :first ],
+      "rpoplpush"        => [ :all ],
+      "rpush"            => [ :first ],
+      "rpushx"           => [ :first ],
+      "sadd"             => [ :first ],
+      "sadd?"            => [ :first ],
+      "scard"            => [ :first ],
+      "scan"             => [ :scan_style, :second ],
+      "scan_each"        => [ :scan_style, :all ],
+      "sdiff"            => [ :all ],
+      "sdiffstore"       => [ :all ],
+      "set"              => [ :first ],
+      "setbit"           => [ :first ],
+      "setex"            => [ :first ],
+      "setnx"            => [ :first ],
+      "setrange"         => [ :first ],
+      "sinter"           => [ :all ],
+      "sinterstore"      => [ :all ],
+      "sismember"        => [ :first ],
+      "smembers"         => [ :first ],
+      "smismember"       => [ :first ],
+      "smove"            => [ :exclude_last ],
+      "sort"             => [ :sort  ],
+      "spop"             => [ :first ],
+      "srandmember"      => [ :first ],
+      "srem"             => [ :first ],
+      "srem?"            => [ :first ],
+      "sscan"            => [ :first ],
+      "sscan_each"       => [ :first ],
+      "strlen"           => [ :first ],
+      "subscribe"        => [ :all ],
+      "sunion"           => [ :all ],
+      "sunionstore"      => [ :all ],
+      "ttl"              => [ :first ],
+      "type"             => [ :first ],
+      "unlink"           => [ :all   ],
+      "unsubscribe"      => [ :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 ]
+    }
+    TRANSACTION_COMMANDS = {
+      "discard"          => [],
+      "exec"             => [],
+      "multi"            => [],
+      "unwatch"          => [ :all ],
+      "watch"            => [ :all ],
+    }
+    HELPER_COMMANDS = {
+      "auth"             => [],
+      "disconnect!"      => [],
+      "close"            => [],
+      "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)
+
+    attr_writer :namespace
+    attr_reader :valkey
+    attr_accessor :warning
+
+    def initialize(namespace, options = {})
+      @namespace = namespace
+      @valkey = options[:valkey] || Valkey.new
+      @warning = !!options.fetch(:warning) do
+                   !ENV['VALKEY_NAMESPACE_QUIET']
+                 end
+      @deprecations = !!options.fetch(:deprecations) do
+                        ENV['VALKEY_NAMESPACE_DEPRECATIONS']
+                      end
+    end
+
+    def deprecations?
+      @deprecations
+    end
+
+    def warning?
+      @warning
+    end
+
+    # Ruby defines a now deprecated type method so we need to override it here
+    # since it will never hit method_missing
+    def type(key)
+      call_with_namespace(:type, key)
+    end
+
+    alias_method :self_respond_to?, :respond_to?
+
+    # emulate Ruby 1.9+ and keep respond_to_missing? logic together.
+    def respond_to?(command, include_private=false)
+      return !deprecations? if DEPRECATED_COMMANDS.include?(command.to_s.downcase)
+
+      respond_to_missing?(command, include_private) or super
+    end
+
+    def keys(query = nil)
+      call_with_namespace(:keys, query || '*')
+    end
+
+    def multi(&block)
+      if block_given?
+        namespaced_block(:multi, &block)
+      else
+        call_with_namespace(:multi)
+      end
+    end
+
+    def pipelined(&block)
+      namespaced_block(:pipelined, &block)
+    end
+
+    def namespace(desired_namespace = nil)
+      if desired_namespace
+        yield Valkey::Namespace.new(desired_namespace,
+                                   :valkey => @valkey)
+      end
+
+      @namespace.respond_to?(:call) ? @namespace.call : @namespace
+    end
+
+    def full_namespace
+      valkey.is_a?(Namespace) ? "#{valkey.full_namespace}:#{namespace}" : namespace.to_s
+    end
+
+    def connection
+      @valkey.connection.tap { |info| info[:namespace] = namespace }
+    end
+
+    def exec
+      call_with_namespace(:exec)
+    end
+
+    def eval(*args)
+      call_with_namespace(:eval, *args)
+    end
+    ruby2_keywords(:eval) if respond_to?(:ruby2_keywords, true)
+
+    # This operation can run for a very long time if the namespace contains lots of keys!
+    # It should be used in tests, or when the namespace is small enough
+    # and you are sure you know what you are doing.
+    def clear
+      if warning?
+        warn("This operation can run for a very long time if the namespace contains lots of keys! " +
+             "It should be used in tests, or when the namespace is small enough " +
+             "and you are sure you know what you are doing.")
+      end
+
+      batch_size = 1000
+
+      if supports_scan?
+        cursor = "0"
+        begin
+          cursor, keys = scan(cursor, count: batch_size)
+          del(*keys) unless keys.empty?
+        end until cursor == "0"
+      else
+        all_keys = keys("*")
+        all_keys.each_slice(batch_size) do |keys|
+          del(*keys)
+        end
+      end
+    end
+
+    ADMINISTRATIVE_COMMANDS.keys.each do |command|
+      define_method(command) do |*args, &block|
+        raise NoMethodError if deprecations?
+
+        if warning?
+          warn("Passing '#{command}' command to valkey as is; " +
+               "administrative commands cannot be effectively namespaced " +
+               "and should be called on the valkey connection directly; " +
+               "passthrough has been deprecated and will be removed in " +
+               "valkey-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)
+        send(normalized_command, *args, &block)
+      elsif @valkey.respond_to?(normalized_command) && !deprecations?
+        # blind passthrough is deprecated and will be removed in 2.0
+        # valkey-namespace does not know how to handle this command.
+        # Passing it to @valkey as is, where valkey-namespace shows
+        # a warning message if @warning is set.
+        if warning?
+          warn("Passing '#{command}' command to valkey as is; blind " +
+               "passthrough has been deprecated and will be removed in " +
+               "valkey-namespace 2.0 (at #{call_site})")
+        end
+
+        wrapped_send(@valkey, command, args, &block)
+      else
+        super
+      end
+    end
+    ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
+
+    def inspect
+      "<#{self.class.name} v#{VERSION} with client "\
+      "for #{full_namespace}>"
+    end
+
+    def respond_to_missing?(command, include_all=false)
+      normalized_command = command.to_s.downcase
+
+      case
+      when COMMANDS.include?(normalized_command)
+        true
+      when !deprecations? && valkey.respond_to?(command, include_all)
+        true
+      else
+        defined?(super) && super
+      end
+    end
+
+    def call_with_namespace(command, *args, &block)
+      handling = COMMANDS[command.to_s.downcase]
+
+      if handling.nil?
+        fail("Valkey::Namespace does not know how to handle '#{command}'.")
+      end
+
+      (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
+        first = args.shift
+        args = add_namespace(args)
+        args.unshift(first) if first
+      when :exclude_last
+        last = args.pop unless args.length == 1
+        args = add_namespace(args)
+        args.push(last) if last
+      when :exclude_options
+        if args.last.is_a?(Hash)
+          last = ruby2_keywords_hash(args.pop)
+          args = add_namespace(args)
+          args.push(last)
+        else
+          args = add_namespace(args)
+        end
+      when :alternate
+        args = args.flatten
+        args.each_with_index { |a, i| args[i] = add_namespace(a) if i.even? }
+      when :sort
+        args[0] = add_namespace(args[0]) if args[0]
+        if args[1].is_a?(Hash)
+          [:by, :store].each do |key|
+            args[1][key] = add_namespace(args[1][key]) if args[1][key]
+          end
+
+          args[1][:get] = Array(args[1][:get])
+
+          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
+        # valkey.eval() and evalsha() can either take the form:
+        #
+        #   valkey.eval(script, [key1, key2], [argv1, argv2])
+        #
+        # Or:
+        #
+        #   valkey.eval(script, :keys => ['k1', 'k2'], :argv => ['arg1', 'arg2'])
+        #
+        # This is a tricky + annoying special case, where we only want the `keys`
+        # argument to be namespaced.
+        if args.last.is_a?(Hash)
+          args.last[:keys] = add_namespace(args.last[:keys])
+        else
+          args[1] = add_namespace(args[1])
+        end
+      when :scan_style
+        options = (args.last.kind_of?(Hash) ? args.pop : {})
+        options[:match] = add_namespace(options.fetch(:match, '*'))
+        args << ruby2_keywords_hash(options)
+
+        if block
+          original_block = block
+          block = proc { |key| original_block.call rem_namespace(key) }
+        end
+      end
+
+      # Dispatch the command to Valkey and store the result.
+      result = wrapped_send(@valkey, command, args, &block)
+
+      # Remove the namespace from results that are keys.
+      case after
+      when :all
+        result = rem_namespace(result)
+      when :first
+        result[0] = rem_namespace(result[0]) if result
+      when :second
+        result[1] = rem_namespace(result[1]) if result
+      end
+
+      result
+    end
+    ruby2_keywords(:call_with_namespace) if respond_to?(:ruby2_keywords, true)
+
+  protected
+
+    def valkey=(valkey)
+      @valkey = valkey
+    end
+
+  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
+
+    def wrapped_send(valkey_client, command, args = [], &block)
+      if valkey_client.class.name == "ConnectionPool"
+        valkey_client.with do |pool_connection|
+          pool_connection.send(command, *args, &block)
+        end
+      else
+        valkey_client.send(command, *args, &block)
+      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)
+      if block.arity == 0
+        wrapped_send(valkey, command, &block)
+      else
+        outer_block = proc { |r| copy = dup; copy.valkey = r; yield copy }
+        wrapped_send(valkey, command, &outer_block)
+      end
+    end
+
+    def add_namespace(key)
+      return key unless key && namespace
+
+      case key
+      when Array
+        key.map! {|k| add_namespace k}
+      when Hash
+        key.keys.each {|k| key[add_namespace(k)] = key.delete(k)}
+        key
+      else
+        "#{namespace}:#{key}"
+      end
+    end
+
+    def rem_namespace(key)
+      return key unless key && namespace
+
+      case key
+      when Array
+        key.map {|k| rem_namespace k}
+      when Hash
+        Hash[*key.map {|k, v| [ rem_namespace(k), v ]}.flatten]
+      when Enumerator
+        create_enumerator do |yielder|
+          key.each { |k| yielder.yield rem_namespace(k) }
+        end
+      else
+        key.to_s.sub(/\A#{namespace}:/, '')
+      end
+    end
+
+    def create_enumerator(&block)
+      # Enumerator in 1.8.7 *requires* a single argument, so we need to use
+      # its Generator class, which matches the block syntax of 1.9.x's
+      # Enumerator class.
+      if RUBY_VERSION.start_with?('1.8')
+        require 'generator' unless defined?(Generator)
+        Generator.new(&block).to_enum
+      else
+        Enumerator.new(&block)
+      end
+    end
+
+    def supports_scan?
+      # Valkey supports SCAN command (inherited from Redis 2.8.0+)
+      true
+    end
+  end
+end

data/lib/valkey-namespace.rb

@@ -0,0 +1 @@
+require 'valkey/namespace'

data/spec/spec_helper.rb

@@ -0,0 +1,27 @@
+require 'bundler/setup'
+require 'valkey-namespace'
+require 'rspec/its'
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.filter_run_when_matching :focus
+  config.example_status_persistence_file_path = "spec/examples.txt"
+  config.disable_monkey_patching!
+  config.warnings = true
+
+  if config.files_to_run.one?
+    config.default_formatter = "doc"
+  end
+
+  config.profile_examples = 10
+  config.order = :random
+  Kernel.srand config.seed
+end

data/spec/valkey_spec.rb

@@ -0,0 +1,122 @@
+require 'spec_helper'
+
+describe Valkey::Namespace do
+  let(:valkey) { double('valkey') }
+  let(:namespace) { 'test' }
+  let(:namespaced) { Valkey::Namespace.new(namespace, valkey: valkey) }
+
+  describe '#initialize' do
+    it 'accepts a namespace and valkey connection' do
+      expect(namespaced.namespace).to eq('test')
+      expect(namespaced.valkey).to eq(valkey)
+    end
+
+    it 'creates a new Valkey connection if none provided' do
+      allow(Valkey).to receive(:new).and_return(valkey)
+      ns = Valkey::Namespace.new('test')
+      expect(ns.valkey).to eq(valkey)
+    end
+
+    it 'accepts a Proc as namespace' do
+      proc_namespace = Proc.new { 'dynamic' }
+      ns = Valkey::Namespace.new(proc_namespace, valkey: valkey)
+      expect(ns.namespace).to eq('dynamic')
+    end
+  end
+
+  describe '#set and #get' do
+    it 'namespaces the key for set' do
+      expect(valkey).to receive(:set).with('test:foo', 'bar')
+      namespaced.set('foo', 'bar')
+    end
+
+    it 'namespaces the key for get' do
+      expect(valkey).to receive(:get).with('test:foo').and_return('bar')
+      expect(namespaced.get('foo')).to eq('bar')
+    end
+  end
+
+  describe '#keys' do
+    it 'namespaces the pattern and removes namespace from results' do
+      expect(valkey).to receive(:keys).with('test:*').and_return(['test:foo', 'test:bar'])
+      expect(namespaced.keys).to eq(['foo', 'bar'])
+    end
+
+    it 'accepts a custom pattern' do
+      expect(valkey).to receive(:keys).with('test:foo*').and_return(['test:foo1', 'test:foo2'])
+      expect(namespaced.keys('foo*')).to eq(['foo1', 'foo2'])
+    end
+  end
+
+  describe '#del' do
+    it 'namespaces all keys' do
+      expect(valkey).to receive(:del).with('test:foo', 'test:bar').and_return(2)
+      expect(namespaced.del('foo', 'bar')).to eq(2)
+    end
+  end
+
+  describe '#mget' do
+    it 'namespaces all keys' do
+      expect(valkey).to receive(:mget).with('test:foo', 'test:bar').and_return(['val1', 'val2'])
+      expect(namespaced.mget('foo', 'bar')).to eq(['val1', 'val2'])
+    end
+  end
+
+  describe '#mset' do
+    it 'namespaces alternating keys' do
+      expect(valkey).to receive(:mset).with('test:foo', 'val1', 'test:bar', 'val2')
+      namespaced.mset('foo', 'val1', 'bar', 'val2')
+    end
+  end
+
+  describe '#full_namespace' do
+    it 'returns the namespace as string' do
+      expect(namespaced.full_namespace).to eq('test')
+    end
+
+    context 'with nested namespaces' do
+      it 'combines namespaces with colons' do
+        inner_ns = Valkey::Namespace.new('inner', valkey: namespaced)
+        expect(inner_ns.full_namespace).to eq('test:inner')
+      end
+    end
+  end
+
+  describe '#inspect' do
+    it 'includes version and namespace' do
+      expect(namespaced.inspect).to include('Valkey::Namespace')
+      expect(namespaced.inspect).to include('v1.0.0')
+      expect(namespaced.inspect).to include('test')
+    end
+  end
+
+  describe 'administrative commands' do
+    it 'warns when using flushall' do
+      allow(valkey).to receive(:flushall)
+      expect { namespaced.flushall }.to output(/administrative commands/).to_stderr
+    end
+
+    it 'raises NoMethodError when deprecations enabled' do
+      ns = Valkey::Namespace.new('test', valkey: valkey, deprecations: true)
+      expect { ns.flushall }.to raise_error(NoMethodError)
+    end
+  end
+
+  describe '#warning?' do
+    it 'returns true by default' do
+      expect(namespaced.warning?).to be true
+    end
+
+    it 'can be disabled via option' do
+      ns = Valkey::Namespace.new('test', valkey: valkey, warning: false)
+      expect(ns.warning?).to be false
+    end
+
+    it 'can be disabled via environment variable' do
+      ENV['VALKEY_NAMESPACE_QUIET'] = '1'
+      ns = Valkey::Namespace.new('test', valkey: valkey)
+      expect(ns.warning?).to be false
+      ENV.delete('VALKEY_NAMESPACE_QUIET')
+    end
+  end
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: valkey-namespace
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Valkey Community
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: valkey
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  Adds a Valkey::Namespace class which can be used to namespace calls
+  to Valkey. This is useful when using a single instance of Valkey with
+  multiple, different applications.
+email:
+- maintainer@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- NOTICE
+- README.md
+- Rakefile
+- lib/valkey-namespace.rb
+- lib/valkey/namespace.rb
+- lib/valkey/namespace/version.rb
+- spec/spec_helper.rb
+- spec/valkey_spec.rb
+homepage: https://github.com/valkey-io/valkey-namespace
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/valkey-io/valkey-namespace/issues
+  changelog_uri: https://github.com/valkey-io/valkey-namespace/blob/master/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/valkey-namespace/1.0.0
+  source_code_uri: https://github.com/valkey-io/valkey-namespace
+  homepage_uri: https://github.com/valkey-io/valkey-namespace
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Namespaces Valkey commands.
+test_files: []