valkey-glide-rb 0.9.2 → 1.0.0.pre.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17396d39342cbcc8a293f5e8b252e1689841b436664c630e330d06b0a1cff9c9
-  data.tar.gz: 7fa260b6afbb060a1c79a8dcb264aae5b211a24e69b042c720e242d39b7b3ab9
+  metadata.gz: 3637e780cfd586be7915d5a1bcd9993ce5772ca69afdee93e5ec1166f6f1fda6
+  data.tar.gz: 45c92cf3741eb914fadf412ae9cb26223133aebdce833045a935219fb4c79f7b
 SHA512:
-  metadata.gz: e96a09b0077bd54a30722201d03ccd8bb8baf7a47c0005d5c3d87441bfeb015479181548dce68bd1e882ee9e266be4658e68b2562e32dca6c48c101ca4e0e2cc
-  data.tar.gz: dbee972964d0a2e54dbf7f4916c2bab6427525ace1d97a679845409b9d55390419631c8407df7502ca9b3561bd51ea0bba1ebecd8bbef680cdaa45b5ba28f405
+  metadata.gz: 730a56e57f83549ea454af827d121461961858ca629a03dbdb723808845e718afe27db1ffc901564d393e070d496b2ecd16736c22a3d37461388e26430350d2c
+  data.tar.gz: aef8450541af162b9c38149589a6eccb45ece28005c2f1af26a5bd93e1639e3a2126c208276d72f72c7e9bd6b1fb1b81288ddb11d40ae38a17d612b9a9c24e3a

data/AGENTS.md

@@ -83,10 +83,26 @@ RUBYOPT="-I$(pwd)/lib" ruby -r valkey -e 'p Valkey.new.ping'
 | Suite | Server requirement |
 |-------|-------------------|
 | `test:standalone` | Standalone Valkey/Redis on `localhost:6379` (DB 15) |
-| `test:cluster` | 6-node cluster on `127.0.0.1:7000`–`7005` |
-| SSL tests | TLS Valkey on port `6380` + certs in `test/fixtures/ssl/` |
+| `test:cluster` | 6-node cluster on `127.0.0.1:7000`–`7005` (auto-started by the suite) |
+| SSL tests | TLS Valkey on port `6380` + `export TLS_CERT_DIR=...` (or `SKIP_TLS_TESTS=true`) |
 | Module tests | JSON, Bloom, Search modules loaded (see CI workflow) |
 
+Start test servers with `cluster_manager.py` (matching CI). The cluster is
+auto-started by the suite; standalone and TLS are started manually:
+
+```bash
+# Standalone on :6379
+python3 valkey-glide/utils/cluster_manager.py start -r 0 -p 6379 --prefix standalone
+
+# TLS on :6380 (generates certs in valkey-glide/utils/tls_crts/)
+python3 valkey-glide/utils/cluster_manager.py --tls start -r 0 -p 6380 --prefix tls-standalone
+export TLS_CERT_DIR=$(pwd)/valkey-glide/utils/tls_crts   # required for TLS tests
+
+# Stop when done
+python3 valkey-glide/utils/cluster_manager.py stop --prefix standalone
+python3 valkey-glide/utils/cluster_manager.py --tls stop --prefix tls-standalone
+```
+
 ### Rebuild Native FFI (when changing glide-core)
 
 ```bash
@@ -141,7 +157,7 @@ cargo fmt --manifest-path ./Cargo.toml --all
 - `*.gem` — built gem packages
 - `coverage/` — coverage reports
 - `tmp/`, `test/tmp/` — temporary test artifacts
-- Regenerated SSL certs unless intentionally updated (`test/fixtures/ssl/*.pem` may be committed for CI)
+- SSL certs — never commit them; TLS tests read certs from `TLS_CERT_DIR` (generated by `cluster_manager.py --tls`)
 - Wrong-platform `libglide_ffi` binaries (build per OS/arch)
 
 ### Ruby-Specific Rules
@@ -185,7 +201,7 @@ valkey-glide-ruby/
 ├── test/lint/            # shared lint
 ├── valkey.gemspec
 ├── Rakefile
-└── .github/workflows/CI.yml
+└── .github/workflows/ci.yml
 ```
 
 ## Quality Gates (Agent Checklist)

data/CONTRIBUTING.md

@@ -39,7 +39,7 @@ For issues that affect the shared Rust core or other language clients, consider
    ```
    Configure automatic signoff: `git config --global format.signOff true`
 
-5. Open a PR and respond to CI feedback (RuboCop + test matrix in `.github/workflows/CI.yml`).
+5. Open a PR and respond to CI feedback (RuboCop + test matrix in `.github/workflows/ci.yml`).
 
 GitHub guides: [fork a repo](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo), [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
 

data/DEVELOPER.md

@@ -43,7 +43,7 @@ valkey-glide-ruby/
 │   ├── setup                     # bundle install
 │   └── console                   # IRB with gem loaded
 ├── .github/workflows/
-│   ├── CI.yml                    # RuboCop + test matrix
+│   ├── ci.yml                    # RuboCop + test matrix
 │   └── cd.yml                    # Build and publish gem
 ├── valkey.gemspec
 ├── Gemfile
@@ -226,13 +226,14 @@ CI=1 bundle exec rake test:standalone
 
 ### SSL Tests
 
-The preferred approach (matching CI and all other GLIDE clients) uses `cluster_manager.py`:
+TLS tests require a TLS server plus `TLS_CERT_DIR` pointing at its certs. Use
+`cluster_manager.py --tls` which will prepare a self-sign certs for use:
 
 ```bash
 # Start a TLS-only server on port 6380 (generates certs in valkey-glide/utils/tls_crts/)
 python3 valkey-glide/utils/cluster_manager.py --tls start -r 0 -p 6380 --prefix tls-standalone
 
-# Point tests at the generated certs
+# Point tests at the generated certs (required — the TLS tests raise if unset)
 export TLS_CERT_DIR=$(pwd)/valkey-glide/utils/tls_crts
 
 # Run tests
@@ -242,12 +243,8 @@ bundle exec rake test:standalone
 python3 valkey-glide/utils/cluster_manager.py --tls stop --prefix tls-standalone
 ```
 
-Alternatively, for local development without Python, generate certs and start manually:
-
-```bash
-ruby test/fixtures/ssl/generate_certs.rb
-# Then start a TLS Valkey server on port 6380 using those certs
-```
+If you don't want to run the TLS tests, set `SKIP_TLS_TESTS=true` and they are
+skipped gracefully (this is what macOS CI does).
 
 ### Module Tests (JSON, Bloom, Search)
 
@@ -270,7 +267,7 @@ VALKEY_PORT=6379 TIMEOUT=10 bundle exec rake test:standalone
 bundle exec rubocop
 ```
 
-CI runs RuboCop on every push and pull request (see `.github/workflows/CI.yml`).
+CI runs RuboCop on every push and pull request (see `.github/workflows/ci.yml`).
 
 Auto-correct safe offenses:
 
@@ -350,7 +347,7 @@ bundle exec ruby test/valkey/test_opentelemetry.rb
 
 ## CI Overview
 
-GitHub Actions (`.github/workflows/CI.yml`):
+GitHub Actions (`.github/workflows/ci.yml`):
 
 | Job | Matrix |
 |-----|--------|
@@ -443,7 +440,7 @@ ruby -e "require 'valkey'; c = Valkey.new; puts c.ping; c.close"
 | `LoadError` / FFI library not found | Confirm `lib/valkey/libglide_ffi.{so,dylib}` exists and matches your OS/arch. |
 | Wrong architecture after FFI rebuild | Rebuild `glide-ffi` on the target platform; do not copy Linux `.so` to macOS. |
 | Cluster tests flaky | Wait for `cluster_state:ok`; increase `TIMEOUT` env var. |
-| SSL test failures | Use `cluster_manager.py --tls` (see SSL Tests above), or regenerate local certs: `ruby test/fixtures/ssl/generate_certs.rb`. |
+| SSL test failures / `TLS_CERT_DIR is not set` | Start a TLS server via `cluster_manager.py --tls` and `export TLS_CERT_DIR=...` (see SSL Tests above), or set `SKIP_TLS_TESTS=true`. |
 | Pipeline / MULTI crashes | Transaction commands in `pipelined` use sequential fallback by design. |
 
 ## Recommended Editor Extensions

data/lib/valkey/commands/connection_commands.rb

@@ -70,7 +70,7 @@ class Valkey
       #
       # @param [Integer] protover Protocol version (2 or 3)
       # @param [Hash] options Optional parameters like AUTH, SETNAME
-      # @return [Array] Server information as flat array (TODO: should be Hash for RESP3)
+      # @return [Hash] Server information (server, version, proto, id, mode, role, modules)
       def hello(protover = 3, **options)
         args = [protover]
 

data/lib/valkey/commands/list_commands.rb

@@ -209,7 +209,7 @@ class Valkey
       #  - when `"RIGHT"` - the elements popped are those from the right of the list
       # @params count [Integer] a number of elements to pop
       #
-      # @return [Array<String, Array<String, Float>>] list of popped elements or nil
+      # @return [Hash, nil] hash mapping key to popped elements, or nil on timeout
       def blmpop(timeout, *keys, modifier: "LEFT", count: nil)
         raise ArgumentError, "Pick either LEFT or RIGHT" unless %w[LEFT RIGHT].include?(modifier)
 
@@ -235,7 +235,7 @@ class Valkey
       #  - when `"RIGHT"` - the elements popped are those from the right of the list
       # @params count [Integer] a number of elements to pop
       #
-      # @return [Array<String, Array<String, Float>>] list of popped elements or nil
+      # @return [Hash, nil] hash mapping key to popped elements, or nil if no elements
       def lmpop(*keys, modifier: "LEFT", count: nil)
         raise ArgumentError, "Pick either LEFT or RIGHT" unless %w[LEFT RIGHT].include?(modifier)
 

data/lib/valkey/commands/pubsub_commands.rb

@@ -168,7 +168,7 @@ class Valkey
       #     # => ["channel1", 5, "channel2", 3]
       #
       # @param [Array<String>] channels the channels to check
-      # @return [Array] channel names and subscriber counts
+      # @return [Hash] channel names mapped to subscriber counts
       #
       # @see https://valkey.io/commands/pubsub-numsub/
       def pubsub_numsub(*channels)
@@ -200,7 +200,7 @@ class Valkey
       #     # => ["shard1", 2, "shard2", 1]
       #
       # @param [Array<String>] channels the shard channels to check
-      # @return [Array] shard channel names and subscriber counts
+      # @return [Hash] shard channel names mapped to subscriber counts
       #
       # @see https://valkey.io/commands/pubsub-shardnumsub/
       def pubsub_shardnumsub(*channels)

data/lib/valkey/commands/scripting_commands.rb

@@ -137,22 +137,13 @@ class Valkey
       # @example Execute script that returns different data types
       #   valkey.eval("return {1, 'hello', true, nil}")
       #     # => [1, "hello", true, nil]
-      # @example Positional form, matching redis-rb's eval(script, keys, argv)
-      #   valkey.eval("return KEYS[1] .. ARGV[1]", ["mykey"], ["myarg"])
-      #     # => "mykeynyarg"
       # Since the eval is not available in the rust backend
       # using the load and invoke script
-      def eval(script, *rest, keys: nil, args: nil)
+      def eval(script, keys: [], args: [])
         # Validate script parameter
         raise ArgumentError, "script must be a string" unless script.is_a?(String)
         raise ArgumentError, "script cannot be empty" if script.empty?
 
-        # Accept redis-rb's flexible positional form - eval(script, keys, argv)
-        # - in addition to the keyword form, mirroring the same treatment
-        # applied to evalsha (see that method for the full rationale).
-        keys ||= rest[0] || []
-        args ||= rest[1] || []
-
         # Validate and convert keys and args to strings
         begin
           keys = Array(keys).map(&:to_s)
@@ -190,22 +181,13 @@ class Valkey
       #   rescue Valkey::CommandError => e
       #     puts "Script not found: #{e.message}"
       #   end
-      # @example Positional form, matching redis-rb's evalsha(sha, keys, argv)
-      #   valkey.evalsha(sha, ["user"], ["123"])
-      #     # => "user:123"
       # Since evalsha is not available in rust backend
       # using invoke script
-      def evalsha(sha, *rest, keys: nil, args: nil)
+      def evalsha(sha, keys: [], args: [])
         # Validate SHA1 hash parameter
         raise ArgumentError, "sha1 hash must be a string" unless sha.is_a?(String)
         raise ArgumentError, "sha1 hash must be a 40-character hexadecimal string" unless valid_sha1?(sha)
 
-        # Accept redis-rb's flexible positional form - evalsha(sha, keys, argv)
-        # - in addition to the keyword form, so code written against redis-rb's
-        # API (e.g. redis_display_id) doesn't need to special-case this client.
-        keys ||= rest[0] || []
-        args ||= rest[1] || []
-
         # Validate and convert keys and args to strings
         begin
           keys = Array(keys).map(&:to_s)
@@ -271,8 +253,8 @@ class Valkey
       end
 
       def invoke_script(script, args: [], keys: [])
-        arg_ptrs, arg_lens = build_command_args(args)
-        keys_ptrs, keys_lens = build_command_args(keys)
+        arg_ptrs, arg_lens, _arg_bufs = build_command_args(args)
+        keys_ptrs, keys_lens, _keys_bufs = build_command_args(keys)
 
         route = ""
         route_buf = FFI::MemoryPointer.from_string(route)

data/lib/valkey/commands/stream_commands.rb

@@ -565,7 +565,7 @@ class Valkey
       # @param [Hash] options optional parameters
       #   - `:full => true`: return full information including entries
       #   - `:count => Integer`: limit number of entries (requires :full)
-      # @return [Array] stream information as flat array of key-value pairs
+      # @return [Hash] stream information as a hash of key-value pairs
       #
       # @example Get basic stream info
       #   valkey.xinfo_stream("mystream")

data/lib/valkey/commands/string_commands.rb

@@ -129,14 +129,7 @@ class Valkey
       # @param [String] value
       # @return [Boolean] whether the key was set or not
       def setnx(key, value)
-        # &Utils::Boolify (not glide-core's generic Boolean-coercion table) is
-        # deliberately used here: glide-core's per-command coercion is keyed by
-        # command name alone, so it can't distinguish this dedicated SETNX
-        # RequestType from a raw `customCommand(["SETNX", ...])` call, which
-        # other GLIDE bindings' existing contracts expect to keep returning a
-        # plain 0/1 integer. Doing the conversion here keeps it scoped to this
-        # one Ruby-level method - see hexists/hsetnx for the same pattern.
-        send_command(RequestType::SET_NX, [key, value], &Utils::Boolify)
+        send_command(RequestType::SET_NX, [key, value])
       end
 
       # Set one or more values.
@@ -327,7 +320,7 @@ class Valkey
       #   - `:idx => true`: Return the positions of the LCS
       #   - `:min_match_len => Integer`: Minimum match length
       #   - `:with_match_len => true`: Include match length in results
-      # @return [String, Integer, Array] the LCS result based on options
+      # @return [String, Integer, Hash] the LCS result based on options (Hash when idx: true)
       def lcs(key1, key2, len: nil, idx: nil, min_match_len: nil, with_match_len: nil)
         args = [key1, key2]
         args << "LEN" if len

data/lib/valkey/commands/transaction_commands.rb

@@ -16,12 +16,8 @@ class Valkey
       #   end # => ["OK", 6]
       #
       # @yield [multi] the commands that are called inside this block are cached
-      #   locally (no server round-trip per command) and sent to the server as a
-      #   single atomic batch once the block returns - GLIDE wraps them in a real
-      #   MULTI/EXEC transaction internally. If the block raises, nothing has been
-      #   sent to the server yet, so the exception simply propagates - there is no
-      #   transaction to discard.
-      # @yieldparam [Valkey::Pipeline] multi collects the block's commands
+      #   and written to the server upon returning from it
+      # @yieldparam [Valkey] multi `self`
       #
       # @return [Array<...>]
       #   - an array with replies
@@ -30,12 +26,17 @@ class Valkey
       # @see #unwatch
       def multi
         if block_given?
-          pipeline = Pipeline.new
-          yield pipeline
-
-          return [] if pipeline.commands.empty?
-
-          send_batch_commands(pipeline.commands, exception: true, is_atomic: true)
+          begin
+            @in_multi_block = true
+            start_multi
+            yield(self)
+            exec
+          rescue StandardError
+            discard
+            raise
+          ensure
+            @in_multi_block = false
+          end
         else
           start_multi
           self
@@ -113,12 +114,11 @@ class Valkey
       # @see #discard
       def exec
         if @in_multi
-          queued_commands = @queued_commands
           begin
             begin
               result = send_command(RequestType::EXEC)
               # If EXEC returns an error object (from array), it's already handled
-              result.is_a?(Array) ? reconvert_queued_replies(result, queued_commands) : result
+              result
             rescue CommandError => e
               # If EXEC itself raises an error (like when transaction is aborted),
               # return an array with the error to match expected behavior in tests
@@ -157,59 +157,8 @@ class Valkey
         @queued_commands = []
       end
 
-      # Commands whose reply is boolean when run standalone (via native return-type
-      # coercion server-side), but arrives as a raw 0/1 integer inside an EXEC array,
-      # since that coercion is keyed by the single command actually being run - which,
-      # for a queued command, is EXEC itself, not the original command.
-      #
-      # This list mirrors glide-core's own Boolean-coercion table in
-      # `value_conversion.rs::expected_type_for_cmd` (HEXISTS, HSETNX, EXPIRE, EXPIREAT,
-      # PEXPIRE, PEXPIREAT, SISMEMBER, PERSIST, SMOVE, PFADD, RENAMENX, MOVE, COPY,
-      # MSETNX, XGROUP DESTROY, XGROUP CREATECONSUMER) MINUS the commands whose Ruby
-      # method already passes its own explicit conversion block (`hexists`/`hsetnx`
-      # use `&Utils::Boolify`; `xgroup_destroy`/`xgroup_createconsumer` use a custom
-      # bool->int block). Those are already handled correctly by the `if block`
-      # branch below, before this list is even consulted - listing them here too
-      # would be redundant, not wrong. Every RequestType below calls `send_command`
-      # with NO block at all, so this static list is the only place their boolean-ness
-      # is recorded.
-      #
-      # NOTE: SETNX is deliberately NOT in glide-core's coercion table (and so isn't
-      # here as a "no block" entry either) - it's `redis-rb`-style boolean-ness only,
-      # not something the server/`glide-core` treats as boolean, since coercion there
-      # is keyed by command name alone and can't distinguish this dedicated RequestType
-      # from a raw `customCommand(["SETNX", ...])` call, which other bindings' existing
-      # contracts expect to keep returning a plain integer. `setnx`'s own Ruby method
-      # passes `&Utils::Boolify` directly instead - see string_commands.rb - so it's
-      # already covered by the `if block` branch, same as hexists/hsetnx.
-      BOOLEAN_REQUEST_TYPES = [
-        RequestType::EXPIRE, RequestType::EXPIRE_AT, RequestType::PEXPIRE, RequestType::PEXPIRE_AT,
-        RequestType::PERSIST, RequestType::SISMEMBER, RequestType::S_MOVE, RequestType::PFADD,
-        RequestType::RENAME_NX, RequestType::MOVE, RequestType::COPY, RequestType::MSET_NX
-      ].freeze
-
       private
 
-      # Re-applies each queued command's own reply conversion (e.g. `&Utils::Boolify`)
-      # to EXEC's raw array, since redis-rb's Future-based design does the equivalent
-      # (a Future remembers its conversion and re-applies it once EXEC resolves), but
-      # queued commands here go through the plain single-command path with no such
-      # memory - see BOOLEAN_REQUEST_TYPES above for the case with no explicit block.
-      def reconvert_queued_replies(result, queued_commands)
-        return result unless result.size == queued_commands.size
-
-        result.each_with_index.map do |value, i|
-          command_type, _args, block = queued_commands[i]
-          if block
-            block.call(value)
-          elsif BOOLEAN_REQUEST_TYPES.include?(command_type)
-            Utils::Boolify.call(value)
-          else
-            value
-          end
-        end
-      end
-
       # Start a MULTI block if one isn't already active.
       #
       # This mirrors the behaviour of popular Valkey/Redis clients where

data/lib/valkey/commands/vector_search_commands.rb

@@ -181,7 +181,7 @@ class Valkey
       #     # => ["index_name", "myIndex", "fields", [...], ...]
       #
       # @param [String] index the index name
-      # @return [Array] index information as array of key-value pairs
+      # @return [Hash] index information as a hash of key-value pairs
       #
       # @see https://redis.io/commands/ft.info/
       def ft_info(index)

data/lib/valkey/route.rb

@@ -67,6 +67,8 @@ class Valkey
     # Returns both the struct and any pinned memory buffers that must remain
     # alive until the FFI call completes.
     #
+    # TODO: Refactor to return a struct (https://github.com/valkey-io/valkey-glide-ruby/issues/179)
+    #
     # @return [Array(Bindings::RouteInfo, Array)] the struct and pinned buffers
     def to_ffi
       info = Bindings::RouteInfo.new

data/lib/valkey/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Valkey
-  VERSION = "0.9.2"
+  VERSION = "1.0.0-rc2"
 end

data/lib/valkey.rb

@@ -156,50 +156,8 @@ class Valkey
     # TLS/SSL certificates
     root_certs = []
     if options[:ssl_params].is_a?(Hash)
-      # ca_file - read CA certificate file (PEM or DER format)
-      if options[:ssl_params][:ca_file]
-        ca_file = options[:ssl_params][:ca_file]
-        raise ArgumentError, "CA file does not exist: #{ca_file}" unless File.exist?(ca_file)
-        raise ArgumentError, "CA file is not readable: #{ca_file}" unless File.readable?(ca_file)
-
-        root_certs << File.binread(ca_file)
-      end
-
-      # cert - client certificate (file path or OpenSSL::X509::Certificate)
-      if options[:ssl_params][:cert]
-        cert_data = if options[:ssl_params][:cert].is_a?(String)
-                      cert_file = options[:ssl_params][:cert]
-                      raise ArgumentError, "Cert file does not exist: #{cert_file}" unless File.exist?(cert_file)
-                      raise ArgumentError, "Cert file is not readable: #{cert_file}" unless File.readable?(cert_file)
-
-                      File.binread(cert_file)
-                    elsif options[:ssl_params][:cert].respond_to?(:to_pem)
-                      options[:ssl_params][:cert].to_pem
-                    elsif options[:ssl_params][:cert].respond_to?(:to_der)
-                      options[:ssl_params][:cert].to_der
-                    else
-                      options[:ssl_params][:cert].to_s
-                    end
-        root_certs << cert_data
-      end
-
-      # key - client key (file path or OpenSSL::PKey)
-      if options[:ssl_params][:key]
-        key_data = if options[:ssl_params][:key].is_a?(String)
-                     key_file = options[:ssl_params][:key]
-                     raise ArgumentError, "Key file does not exist: #{key_file}" unless File.exist?(key_file)
-                     raise ArgumentError, "Key file is not readable: #{key_file}" unless File.readable?(key_file)
-
-                     File.binread(key_file)
-                   elsif options[:ssl_params][:key].respond_to?(:to_pem)
-                     options[:ssl_params][:key].to_pem
-                   elsif options[:ssl_params][:key].respond_to?(:to_der)
-                     options[:ssl_params][:key].to_der
-                   else
-                     options[:ssl_params][:key].to_s
-                   end
-        root_certs << key_data
-      end
+      # ca_file - CA certificate file path
+      root_certs << read_ssl_value(options[:ssl_params][:ca_file], "CA") if options[:ssl_params][:ca_file]
 
       # Additional root certificates from ca_path
       if options[:ssl_params][:ca_path]
@@ -214,6 +172,12 @@ class Valkey
         end
       end
 
+      # cert - file path or OpenSSL::X509::Certificate
+      json_options["client_cert"] = read_ssl_value(options[:ssl_params][:cert], "Cert") if options[:ssl_params][:cert]
+
+      # key - file path or OpenSSL::PKey
+      json_options["client_key"] = read_ssl_value(options[:ssl_params][:key], "Key") if options[:ssl_params][:key]
+
       # Direct root_certs array support
       root_certs.concat(options[:ssl_params][:root_certs]) if options[:ssl_params][:root_certs].is_a?(Array)
     end
@@ -291,6 +255,11 @@ class Valkey
     # Store cluster mode flag for response handling (MAP returns Hash in cluster, Array in standalone)
     @cluster_mode = options[:cluster_mode] ? true : false
 
+    # Returns GLIDE Core map as a flattened-map array
+    # Ex: { "key1" => "value1", "key2" => "value2" } becomes ["key1", "value1", "key2", "value2"]
+    # Compatibility for redis-rb 4.x
+    @flatten_map = options[:flatten_map] ? true : false
+
     # Track transactional state for `MULTI` / `EXEC` / `DISCARD` helpers.
     # This avoids Ruby warnings about uninitialised instance variables and
     # gives us a single source of truth for whether we're inside a TX.
@@ -435,7 +404,7 @@ class Valkey
         )
       end
 
-      result = convert_response(res, return_map_as_hash: @cluster_mode, &block)
+      result = convert_response(res, &block)
     ensure
       # Free the native CommandResult (arena + response + error) to prevent memory leak
       Bindings.free_command_result(res) if res && !res.null?
@@ -457,9 +426,7 @@ class Valkey
         RequestType::MULTI, RequestType::EXEC, RequestType::DISCARD,
         RequestType::WATCH, RequestType::UNWATCH
       ]
-      if !tx_commands.include?(command_type) && result == "QUEUED"
-        @queued_commands << [command_type, command_args.dup, block]
-      end
+      @queued_commands << [command_type, command_args.dup] if !tx_commands.include?(command_type) && result == "QUEUED"
     end
 
     result
@@ -467,29 +434,41 @@ class Valkey
 
   private
 
-  def send_batch_commands(commands, exception: true, is_atomic: false)
-    # WORKAROUND: The underlying Glide FFI backend has stability issues when
-    # batching LITERAL MULTI / EXEC / DISCARD commands (e.g. a `pipelined` block
-    # that manually calls `pipeline.multi`/`pipeline.exec`). To avoid native
-    # crashes we fall back to issuing those commands sequentially instead of via
-    # `Bindings.batch`. This never applies to a real `is_atomic: true` batch
-    # (see `multi`'s block form) - that path never contains literal MULTI/EXEC
-    # commands, since the server-side transaction wrapping is handled by GLIDE
-    # itself based on the `is_atomic` flag, not by commands in the list.
-    unless is_atomic
-      tx_types = [RequestType::MULTI, RequestType::EXEC, RequestType::DISCARD]
-
-      if commands.any? { |(command_type, _args, _block)| tx_types.include?(command_type) }
-        results = []
-
-        commands.each do |command_type, command_args, block|
-          res = send_command(command_type, command_args)
-          res = block.call(res) if block
-          results << res
-        end
+  # Read an SSL value
+  # Accepts a file path (String), an OpenSSL object (#to_pem / #to_der), or a fallback #to_s.
+  def read_ssl_value(value, label)
+    if value.is_a?(String)
+      raise ArgumentError, "#{label} file does not exist: #{value}" unless File.exist?(value)
+      raise ArgumentError, "#{label} file is not readable: #{value}" unless File.readable?(value)
+
+      File.binread(value)
+    # Duck-typing check
+    elsif value.respond_to?(:to_pem)
+      value.to_pem
+    elsif value.respond_to?(:to_der)
+      value.to_der
+    else
+      value.to_s
+    end
+  end
 
-        return results
+  def send_batch_commands(commands, exception: true)
+    # WORKAROUND: The underlying Glide FFI backend has stability issues when
+    # batching transactional commands like MULTI / EXEC / DISCARD. To avoid
+    # native crashes we fall back to issuing those commands sequentially
+    # instead of via `Bindings.batch`.
+    tx_types = [RequestType::MULTI, RequestType::EXEC, RequestType::DISCARD]
+
+    if commands.any? { |(command_type, _args, _block)| tx_types.include?(command_type) }
+      results = []
+
+      commands.each do |command_type, command_args, block|
+        res = send_command(command_type, command_args)
+        res = block.call(res) if block
+        results << res
       end
+
+      return results
     end
 
     cmds = []
@@ -519,7 +498,7 @@ class Valkey
     batch_info = Bindings::BatchInfo.new
     batch_info[:cmd_count] = cmds.size
     batch_info[:cmds] = cmd_ptrs
-    batch_info[:is_atomic] = is_atomic
+    batch_info[:is_atomic] = false
 
     batch_options = Bindings::BatchOptionsInfo.new
     batch_options[:retry_server_error] = true
@@ -601,6 +580,9 @@ class Valkey
     { "manual_interval" => { "duration_in_sec" => duration_in_sec } }
   end
 
+  # Returns [ptrs, lens, buffers]. Callers must retain buffers until the FFI call returns.
+  # Otherwise, GC may free the buffers making the ptrs invalid.
+  # TODO: Refactor to return a struct (https://github.com/valkey-io/valkey-glide-ruby/issues/179)
   def build_command_args(command_args)
     # For empty arrays, pass NULL pointers as per Rust FFI contract
     # This matches Go's approach which successfully uses nil pointers
@@ -622,7 +604,7 @@ class Valkey
     [arg_ptrs, arg_lens, buffers]
   end
 
-  def convert_response(res, return_map_as_hash: false, &block)
+  def convert_response(res, &block)
     result = Bindings::CommandResult.new(res)
 
     if result[:response].null?
@@ -678,8 +660,7 @@ class Valkey
           map[map_key] = map_value
         end
 
-        # Return as Hash in cluster mode, flatten to pairs in standalone mode.
-        return_map_as_hash ? map : map.to_a.flatten(1)
+        @flatten_map ? map.to_a.flatten(1) : map
       when ResponseType::SETS
         ptr = response_item[:sets_value]
         count = response_item[:sets_value_len].to_i
@@ -708,10 +689,7 @@ class Valkey
 
     response = convert_response.call(result)
 
-    # Don't run the caller's converter (e.g. Utils::Boolify) over the MULTI-queued
-    # "QUEUED" sentinel - send_command's own `result == "QUEUED"` check (used to
-    # track queued commands) needs to see the literal string, not e.g. `true`.
-    if block_given? && response != "QUEUED"
+    if block_given?
       block.call(response)
     else
       response

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: valkey-glide-rb
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 1.0.0.pre.rc2
 platform: ruby
 authors:
 - Valkey GLIDE Maintainers
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-22 00:00:00.000000000 Z
+date: 2026-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi