solid-redis 1.0.3 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1a92b96853d5d381ae812b7440c9b50a718f9b67fc678e0cbee1d0c8014fc16
-  data.tar.gz: 679a2723c695c95b68f95432006fe93e111c2318106b0384e7a409eca475b480
+  metadata.gz: b6c2088305fc897e081c9f3b7d2a5913441ab4816851a9da52158d05ea84d863
+  data.tar.gz: 15d0a731a92ac785fd837ca99be1d6521a728446be45087adbf997f338f6456d
 SHA512:
-  metadata.gz: 2ea6594459de7d81b8e8fbe1f0f323a397a6c99ff145489ecba44e0ff6ecb8c2409236283a0d21add112033377ceaab4ce787e7021afbfd6c79d18ffc1991f92
-  data.tar.gz: 4ddc0772aeb012163fced9a0bdca65c8da9d21019e82f25b36254fe2c0c3b32312052de47e707b1bcdf64fc35663363db4775155dcc4143ba9c44db93cdc6d48
+  metadata.gz: a20d9fcccf65d69d08045d196ca54478e65c689941c6a07b302acea78e3f2218b6b96b3039904e5f710fff54fc013ef951ef98b267c24d3c9cbf961066ad8442
+  data.tar.gz: 373aac9ed547db8482549be91af26821fba8ed48b4098fae5049ffd9496de97960c7f3176e6ebdbf46e6230196c90058842efce10803d5e5251d321afe623ca8

data/CHANGELOG.md

@@ -4,8 +4,30 @@ All notable changes to this project are documented in this file. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.0.4] - 2026-09-27
+
+### Changed
+
+- Cache the immutable server key instead of allocating it on every Cluster
+  lookup.
+- Encode one-level nested command arguments without creating an intermediate
+  flattened array.
+- Parse RESP data with a buffer cursor and compact only when another socket
+  read is required, reducing response-parser allocations.
+- Attempt non-blocking socket reads and writes before waiting with `IO.select`,
+  while preserving read/write deadlines when the socket would block.
+
 ## [1.0.3] - 2026-09-27
 
+### Added
+
+- Deterministic fault-injection and bounded thread/Ractor stress tests in the
+  standard CI suite.
+- A dependency-free local throughput benchmark run by the default Rake task.
+- A reproducible real-Redis comparison with `redis-client` across 1/2/4/8
+  Ractors, pipelines, isolated pools, Cluster, and forced Sentinel failover,
+  including latency percentiles, CPU, RSS, allocations, and errors.
+
 ### Fixed
 
 - Consume complete RESP arrays, maps, sets, pushes, and attributes before
@@ -91,6 +113,7 @@ project adheres to [Semantic Versioning](https://semver.org/).
   TLS, reconnection), `Pool` owned by a single Ractor, pipelines, and
   lifecycle callbacks via `callback-collection`.
 
+[1.0.4]: https://github.com/nicolasva/solid-redis/compare/v1.0.3...v1.0.4
 [1.0.3]: https://github.com/nicolasva/solid-redis/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/nicolasva/solid-redis/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/nicolasva/solid-redis/compare/v1.0.0...v1.0.1

data/README.md

@@ -583,6 +583,108 @@ futures. It cannot transparently replace a block-based synchronous pool
 without defining backpressure, cancellation, transaction, Pub/Sub, and
 exception protocols.
 
+## Benchmark
+
+<!-- benchmark-results:start -->
+This is a local-loopback microbenchmark, not a prediction of application
+performance. It excludes Redis server CPU/RAM and network latency.
+Cluster rows compare `solid-redis` with `redis-cluster-client`, the
+Cluster implementation built on `redis-client`. Unsupported combinations
+are reported rather than replaced with a different concurrency model.
+
+**Environment:** Ruby 3.4.4 (arm64-darwin24); solid-redis 1.0.3; Redis server v=8.10.0 sha=00000000:1 malloc=libc bits=64 build=80fd3081013fc32b; redis-client 0.30.1; redis-cluster-client 0.17.1; Apple M2 Max, 12 logical CPUs, 96 GiB RAM, macOS 26.6.2.
+
+Each row is measured in a fresh Ruby process. Both clients use RESP2,
+identical commands and the same local Redis topology. Client order is
+alternated between runs; values are medians of 5 runs.
+Regular workloads warm for 2 seconds and measure
+for 10 seconds. Pipeline latency is amortized
+per command (batch size 50). The isolated-pool scenario creates a
+five-connection pool inside each Ractor, warms it with
+1,000 PINGs, then measures 100,000
+PINGs per Ractor.
+CPU is client-process CPU divided by wall time and may exceed 100% with
+multiple Ractors. Peak RSS excludes Redis server processes. Sentinel
+rows kill the master process 0.5 seconds after measurement starts and
+verify that every Ractor resumes on the promoted replica. Recovery is
+measured from the kill to each Ractor's first successful response.
+Throughput counts successful commands; errors are failed commands
+observed during the measured interval. Allocation and RSS measurements
+include the identical latency-recording harness used for both clients, so
+they are comparative rather than intrinsic library-only costs.
+
+Reproduce the full run (requires `redis-server` and `redis-cli`):
+
+```sh
+BENCHMARK_README=README.md bundle exec rake benchmark:comparison
+```
+
+### GET / SET
+
+| Ractors | Client | Throughput (ops/s) | p50 (ms) | p95 (ms) | p99 (ms) | CPU | Peak RSS | Allocations/op | Errors/run |
+|---:|---|---:|---:|---:|---:|---:|---:|---:|---:|
+| 1 | `redis-client` | 35,636 | 0.027 | 0.033 | 0.045 | 58.3% | 50.6 MiB | 17.4 | 0 |
+| 1 | `solid-redis` | 33,891 | 0.028 | 0.034 | 0.051 | 52.4% | 49.0 MiB | 28.9 | 0 |
+| 2 | `redis-client` | 53,941 | 0.035 | 0.049 | 0.069 | 114.6% | 58.6 MiB | 17.3 | 0 |
+| 2 | `solid-redis` | 56,594 | 0.033 | 0.045 | 0.090 | 104.7% | 57.9 MiB | 28.7 | 0 |
+| 4 | `redis-client` | 67,608 | 0.055 | 0.092 | 0.131 | 238.3% | 63.7 MiB | 17.3 | 0 |
+| 4 | `solid-redis` | 75,539 | 0.049 | 0.082 | 0.141 | 204.1% | 63.8 MiB | 28.5 | 0 |
+| 8 | `redis-client` | 48,828 | 0.078 | 0.171 | 0.236 | 268.5% | 75.4 MiB | 17.3 | 0 |
+| 8 | `solid-redis` | 80,691 | 0.087 | 0.172 | 0.267 | 431.4% | 69.5 MiB | 28.2 | 0 |
+
+### Pipelines
+
+| Ractors | Client | Throughput (ops/s) | p50 (ms) | p95 (ms) | p99 (ms) | CPU | Peak RSS | Allocations/op | Errors/run |
+|---:|---|---:|---:|---:|---:|---:|---:|---:|---:|
+| 1 | `redis-client` | 262,482 | 0.004 | 0.005 | 0.007 | 81.5% | 39.5 MiB | 12.6 | 0 |
+| 1 | `solid-redis` | 317,150 | 0.003 | 0.004 | 0.006 | 77.9% | 41.0 MiB | 16.2 | 0 |
+| 2 | `redis-client` | 270,197 | 0.007 | 0.010 | 0.013 | 149.9% | 39.9 MiB | 12.5 | 0 |
+| 2 | `solid-redis` | 459,445 | 0.004 | 0.007 | 0.009 | 147.5% | 42.5 MiB | 15.9 | 0 |
+| 4 | `redis-client` | 222,813 | 0.017 | 0.025 | 0.031 | 282.8% | 40.0 MiB | 12.5 | 0 |
+| 4 | `solid-redis` | 464,640 | 0.008 | 0.014 | 0.017 | 251.9% | 43.2 MiB | 15.6 | 0 |
+| 8 | `redis-client` | 204,898 | 0.004 | 0.055 | 0.063 | 314.2% | 41.9 MiB | 12.5 | 0 |
+| 8 | `solid-redis` | 341,323 | 0.021 | 0.042 | 0.047 | 550.7% | 43.4 MiB | 15.5 | 0 |
+
+### Isolated pool per Ractor
+
+| Ractors | Client | Throughput (ops/s) | p50 (ms) | p95 (ms) | p99 (ms) | CPU | Peak RSS | Allocations/op | Errors/run |
+|---:|---|---:|---:|---:|---:|---:|---:|---:|---:|
+| 1 | `redis-client` | unsupported: Ractor::IsolationError (`connection_pool` uses non-shareable global state) | — | — | — | — | — | — | — |
+| 1 | `solid-redis` | 34,528 | 0.028 | 0.033 | 0.043 | 53.3% | 39.0 MiB | 25.0 | 0 |
+| 2 | `redis-client` | unsupported: Ractor::IsolationError (`connection_pool` uses non-shareable global state) | — | — | — | — | — | — | — |
+| 2 | `solid-redis` | 57,408 | 0.032 | 0.046 | 0.086 | 106.3% | 44.4 MiB | 24.8 | 0 |
+| 4 | `redis-client` | unsupported: Ractor::IsolationError (`connection_pool` uses non-shareable global state) | — | — | — | — | — | — | — |
+| 4 | `solid-redis` | 78,461 | 0.047 | 0.078 | 0.129 | 205.4% | 54.1 MiB | 24.6 | 0 |
+| 8 | `redis-client` | unsupported: Ractor::IsolationError (`connection_pool` uses non-shareable global state) | — | — | — | — | — | — | — |
+| 8 | `solid-redis` | 72,809 | 0.071 | 0.129 | 0.202 | 297.3% | 68.9 MiB | 24.4 | 0 |
+
+### Cluster
+
+| Ractors | Client | Throughput (ops/s) | p50 (ms) | p95 (ms) | p99 (ms) | CPU | Peak RSS | Allocations/op | Errors/run |
+|---:|---|---:|---:|---:|---:|---:|---:|---:|---:|
+| 1 | `redis-client` | 29,071 | 0.033 | 0.040 | 0.051 | 64.8% | 48.8 MiB | 19.4 | 0 |
+| 1 | `solid-redis` | 29,213 | 0.033 | 0.038 | 0.056 | 57.1% | 47.6 MiB | 34.9 | 0 |
+| 2 | `redis-client` | 50,333 | 0.037 | 0.051 | 0.078 | 124.7% | 57.8 MiB | 19.3 | 0 |
+| 2 | `solid-redis` | 51,805 | 0.036 | 0.050 | 0.097 | 117.2% | 57.0 MiB | 34.7 | 0 |
+| 4 | `redis-client` | 60,752 | 0.062 | 0.099 | 0.139 | 252.6% | 62.5 MiB | 19.3 | 0 |
+| 4 | `solid-redis` | 66,626 | 0.055 | 0.089 | 0.152 | 225.9% | 61.2 MiB | 34.4 | 0 |
+| 8 | `redis-client` | 43,258 | 0.089 | 0.186 | 0.253 | 278.1% | 75.4 MiB | 19.3 | 0 |
+| 8 | `solid-redis` | 48,644 | 0.079 | 0.154 | 0.248 | 241.4% | 74.7 MiB | 34.3 | 0 |
+
+### Sentinel master crash
+
+| Ractors | Client | Throughput (ops/s) | p50 (ms) | p95 (ms) | p99 (ms) | Recovery p50 (ms) | Recovery max (ms) | CPU | Peak RSS | Allocations/op | Errors/run |
+|---:|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| 1 | `redis-client` | 29,378 | 0.028 | 0.035 | 0.046 | 1333.8 | 1333.8 | 61.9% | 52.3 MiB | 20.1 | 2050 |
+| 1 | `solid-redis` | 28,794 | 0.029 | 0.035 | 0.050 | 1319.1 | 1319.1 | 55.5% | 48.3 MiB | 33.3 | 2090 |
+| 2 | `redis-client` | 30,829 | 0.036 | 0.049 | 0.070 | 4242.9 | 4243.0 | 87.8% | 53.4 MiB | 20.4 | 3080 |
+| 2 | `solid-redis` | 31,074 | 0.033 | 0.045 | 0.093 | 4440.4 | 4451.4 | 77.3% | 50.3 MiB | 33.1 | 2202 |
+| 4 | `redis-client` | 36,404 | 0.054 | 0.093 | 0.131 | 4302.8 | 4870.8 | 157.2% | 58.0 MiB | 20.5 | 3113 |
+| 4 | `solid-redis` | 41,080 | 0.048 | 0.081 | 0.136 | 4802.3 | 4962.6 | 132.6% | 56.0 MiB | 32.0 | 2251 |
+| 8 | `redis-client` | 48,133 | 0.117 | 0.219 | 0.297 | 2278.4 | 2741.5 | 434.1% | 61.5 MiB | 19.7 | 3114 |
+| 8 | `solid-redis` | 63,627 | 0.087 | 0.171 | 0.277 | 2073.7 | 2085.0 | 374.0% | 64.4 MiB | 30.6 | 2268 |
+<!-- benchmark-results:end -->
+
 ## Development
 
 ```sh
@@ -590,8 +692,15 @@ bundle install
 bundle exec rake
 ```
 
-The default task runs the Minitest suite and builds the gem in `pkg/`.
-CI runs the suite on Ruby 3.1 through 4.0.
+The default task runs the Minitest suite, a deterministic local throughput
+benchmark, and builds the gem in `pkg/`. CI runs all three on Ruby 3.1 through
+4.0. The test suite includes bounded thread/Ractor stress and fault injection
+for truncated responses, timeouts, reconnects, Sentinel, and Cluster errors.
+Run only the benchmark with:
+
+```sh
+bundle exec rake benchmark
+```
 
 The suite needs no running Redis: it uses an in-process fake server
 (`test/support/fake_redis_server.rb`) that speaks RESP2/RESP3, Sentinel,

data/lib/solid_redis/client.rb

@@ -202,14 +202,19 @@ module SolidRedis
 
     def write(payload)
       offset = 0
+      deadline = nil
       while offset < payload.bytesize
-        unless IO.select(nil, [@socket], nil, @target.write_timeout)
-          raise TimeoutError, "Redis write timed out after #{@target.write_timeout}s"
+        chunk = offset.zero? ? payload : payload.byteslice(offset..)
+        written = @socket.write_nonblock(chunk, exception: false)
+        if written == :wait_writable
+          deadline ||= monotonic_time + @target.write_timeout
+          remaining = deadline - monotonic_time
+          if remaining <= 0 || !IO.select(nil, [@socket], nil, remaining)
+            raise TimeoutError, "Redis write timed out after #{@target.write_timeout}s"
+          end
+          next
         end
 
-        written = @socket.write_nonblock(payload.byteslice(offset..), exception: false)
-        next if written == :wait_writable
-
         offset += written
       end
     rescue IOError, SystemCallError => error

data/lib/solid_redis/config.rb

@@ -56,6 +56,7 @@ module SolidRedis
       @ssl = !!ssl
       @ssl_params = Shareable.copy(ssl_params, label: "ssl_params") if ssl_params
       @callbacks = Shareable.copy(callbacks, label: "callbacks") if callbacks
+      @server_key = [@path, @host, @port].freeze
       Ractor.make_shareable(self)
     end
 
@@ -72,7 +73,7 @@ module SolidRedis
     end
 
     def server_key
-      [path, host, port].freeze
+      @server_key
     end
 
     def server_url

data/lib/solid_redis/resp.rb

@@ -7,15 +7,23 @@ module SolidRedis
     module_function
 
     def encode(command)
-      command = command.flatten(1)
-      raise ArgumentError, "Redis command cannot be empty" if command.empty?
+      length = command.sum { |argument| argument.is_a?(Array) ? argument.length : 1 }
+      raise ArgumentError, "Redis command cannot be empty" if length.zero?
 
-      command.each_with_object(+"*#{command.length}#{CRLF}") do |argument, buffer|
-        value = encode_argument(argument)
-        buffer << "$#{value.bytesize}#{CRLF}#{value}#{CRLF}"
+      command.each_with_object(+"*#{length}#{CRLF}") do |argument, buffer|
+        if argument.is_a?(Array)
+          argument.each { |value| append_argument(buffer, value) }
+        else
+          append_argument(buffer, argument)
+        end
       end
     end
 
+    def append_argument(buffer, argument)
+      value = encode_argument(argument)
+      buffer << "$#{value.bytesize}#{CRLF}#{value}#{CRLF}"
+    end
+
     def encode_argument(value)
       case value
       when String then value
@@ -32,6 +40,7 @@ module SolidRedis
         @io = io
         @read_timeout = read_timeout
         @buffer = +""
+        @offset = 0
       end
 
       # Temporarily overrides the read timeout. +nil+ waits forever, which is
@@ -49,7 +58,7 @@ module SolidRedis
       # leaves a partially consumed frame behind, so it is the safe way to
       # poll for the next Pub/Sub message.
       def wait_readable(timeout)
-        return true unless @buffer.empty?
+        return true if available_bytes.positive?
         return true unless @io.respond_to?(:to_io)
 
         !IO.select([@io], nil, nil, timeout).nil?
@@ -155,28 +164,30 @@ module SolidRedis
 
       def read_line
         loop do
-          if (index = @buffer.index(CRLF))
-            return @buffer.slice!(0, index + 2).byteslice(0, index)
+          if (index = @buffer.index(CRLF, @offset))
+            value = @buffer.byteslice(@offset, index - @offset)
+            @offset = index + 2
+            clear_consumed_buffer
+            return value
           end
           fill_buffer
         end
       end
 
       def read_bytes(length)
-        fill_buffer while @buffer.bytesize < length
-        @buffer.slice!(0, length)
+        fill_buffer while available_bytes < length
+        value = @buffer.byteslice(@offset, length)
+        @offset += length
+        clear_consumed_buffer
+        value
       end
 
       def fill_buffer
+        compact_buffer
         wait_for = :readable
+        deadline = nil
         loop do
           if @io.respond_to?(:to_io)
-            readers = wait_for == :readable ? [@io] : nil
-            writers = wait_for == :writable ? [@io] : nil
-            unless IO.select(readers, writers, nil, @read_timeout)
-              raise TimeoutError, "Redis read timed out after #{@read_timeout}s"
-            end
-
             chunk = @io.read_nonblock(16_384, exception: false)
           else
             chunk = @io.read(16_384)
@@ -184,6 +195,17 @@ module SolidRedis
 
           if chunk == :wait_readable || chunk == :wait_writable
             wait_for = chunk == :wait_readable ? :readable : :writable
+            deadline ||= monotonic_time + @read_timeout if @read_timeout
+            remaining = deadline && deadline - monotonic_time
+            if remaining && remaining <= 0
+              raise TimeoutError, "Redis read timed out after #{@read_timeout}s"
+            end
+
+            readers = wait_for == :readable ? [@io] : nil
+            writers = wait_for == :writable ? [@io] : nil
+            unless IO.select(readers, writers, nil, remaining)
+              raise TimeoutError, "Redis read timed out after #{@read_timeout}s"
+            end
             next
           end
           raise EOFError if chunk.nil?
@@ -195,6 +217,28 @@ module SolidRedis
         raise ConnectionError, error.message, cause: error
       end
 
+      def available_bytes
+        @buffer.bytesize - @offset
+      end
+
+      def clear_consumed_buffer
+        return unless @offset == @buffer.bytesize
+
+        @buffer.clear
+        @offset = 0
+      end
+
+      def compact_buffer
+        return if @offset.zero?
+
+        @buffer = @buffer.byteslice(@offset..) || +""
+        @offset = 0
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
       def error_response(message, exception)
         error = if message.start_with?("NOAUTH", "WRONGPASS")
           AuthenticationError.new(message)

data/lib/solid_redis/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidRedis
-  VERSION = "1.0.3"
+  VERSION = "1.0.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid-redis
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.4
 platform: ruby
 authors:
 - Nicolas Vandenbogaerde
@@ -71,6 +71,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: redis-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.30.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.30.1
+- !ruby/object:Gem::Dependency
+  name: redis-cluster-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
 description: Immutable, shareable Redis, Sentinel and Cluster configuration with isolated
   runtime state, pools, and sockets per Ractor. Supports pipelines, blocking commands,
   and Pub/Sub.
@@ -104,7 +132,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-  documentation_uri: https://www.rubydoc.info/gems/solid-redis/1.0.3
+  documentation_uri: https://www.rubydoc.info/gems/solid-redis/1.0.4
   source_code_uri: https://github.com/nicolasva/solid-redis
   changelog_uri: https://github.com/nicolasva/solid-redis/blob/main/CHANGELOG.md
 rdoc_options: []