solid-redis 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a4bfba5a15f75c77fa0c5a9d2a85a0d5d8b50ebada6fbd5e1895e56e47b5813a
+  data.tar.gz: 842b205f8ba0b9298451f24bec08c0d76542e6b46026b27539853d35c06fce54
+SHA512:
+  metadata.gz: 8a6afa66bb51a4723939441be103372efd6260c670dd8e68ca81d788cc2430bc732221c2b7b930a35365d207b1e095a654ecbd88bac715c08bc8b6f86028872d
+  data.tar.gz: c010108671dfc8c343b213fde778afc1e9c3e2750051629ae585d2857037d8da1dd455ff2dba974b78098f014a7c25c495f30d4b1fc88b2b9ab2bf236bd0bca6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolas Vandenbogaerde
+
+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/README.md

@@ -0,0 +1,293 @@
+# Solid Redis
+
+[![Build Status](https://github.com/nicolasva/solid-redis/actions/workflows/ci.yml/badge.svg)](https://github.com/nicolasva/solid-redis/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/solid-redis.svg)](https://rubygems.org/gems/solid-redis)
+[![Documentation Status](https://img.shields.io/badge/docs-RubyDoc.info-blue.svg)](https://www.rubydoc.info/gems/solid-redis)
+
+`solid-redis` is a dependency-free Redis client designed around Ractor
+isolation. Its Redis and Sentinel specifications are immutable and shareable;
+every Ractor creates and retains its own resolution state, mutex, pool,
+clients, and sockets.
+
+It does not depend on or patch `redis-client`.
+
+The implementation intentionally composes two small gems from the same
+author:
+
+- [`base-service`](https://github.com/nicolasva/base-service) executes each
+  Sentinel resolution and returns its immutable result and endpoint errors;
+- [`callback-collection`](https://github.com/nicolasva/callback-collection)
+  provides immutable lifecycle event handlers.
+
+## Architecture
+
+```text
+                       RUBY
+                         |
+             immutable/shareable config
+                         |
+        +----------------+----------------+
+        |                |                |
+     Ractor A         Ractor B         Ractor C
+        |                |                |
+  SentinelState A  SentinelState B  SentinelState C
+        |                |                |
+     Mutex A          Mutex B          Mutex C
+        |                |                |
+      Pool A           Pool B           Pool C
+        |                |                |
+     Socket A         Socket B         Socket C
+        |                |                |
+        +----------------+----------------+
+                         |
+                   Redis/Sentinel
+```
+
+`SolidRedis::SentinelConfig` contains only declarative values. It can therefore
+cross a Ractor boundary. Its first use in each Ractor creates a
+`SolidRedis::SentinelState` in `Ractor.current` storage. The state owns:
+
+- the cached Redis target;
+- the current Sentinel ordering;
+- dynamically discovered Sentinels;
+- temporary Sentinel clients;
+- a mutex protecting threads in that Ractor.
+
+Sentinel connections are opened only while resolving a target and are then
+closed. Resolution is cached until `reset` or a connection/failover error.
+
+## Requirements
+
+Ruby **3.1 or newer** is required (tested on 3.1, 3.2, 3.3, 3.4, and 4.0).
+Ruby 2.7 and 3.0 are not supported: the `Ractor` API this gem is built on
+was introduced in 3.0, and the per-Ractor storage semantics are verified
+from 3.1 onwards. Ruby >= 4.0 is recommended for workloads that run several
+threads inside several Ractors (see the CRuby limitation below).
+
+## Installation
+
+```ruby
+gem "solid-redis"
+```
+
+```sh
+bundle install
+```
+
+## Direct Redis usage
+
+```ruby
+require "solid_redis"
+
+config = SolidRedis.config(
+  url: "redis://localhost:6379/0",
+  timeout: 1.0,
+  reconnect_attempts: 1
+)
+
+client = config.new_client
+client.call("SET", "answer", 42)
+client.call("GET", "answer") # => "42"
+client.close
+```
+
+The client supports TCP, Unix sockets, TLS, RESP2 and RESP3 response types,
+AUTH, SELECT, CLIENT SETNAME, calls, vector calls, and pipelines:
+
+```ruby
+client.pipelined do |pipeline|
+  pipeline.call("SET", "first", 1)
+  pipeline.call("GET", "first")
+end
+# => ["OK", "1"]
+```
+
+## Sentinel with Ractors
+
+Create one immutable specification and pass it to every worker:
+
+```ruby
+SENTINEL = SolidRedis.sentinel(
+  name: "mymaster",
+  sentinels: [
+    { host: "127.0.0.1", port: 26_380 },
+    { host: "127.0.0.1", port: 26_381 }
+  ],
+  role: :master,
+  timeout: 1.0
+)
+
+Ractor.shareable?(SENTINEL) # => true
+
+workers = 4.times.map do
+  Ractor.new(SENTINEL) do |sentinel|
+    pool = sentinel.new_pool(size: 5)
+    pool.call("PING")
+  ensure
+    pool&.close
+  end
+end
+
+workers.map(&:value) # => ["PONG", "PONG", "PONG", "PONG"]
+# On Ruby 3.x, use workers.map(&:take) instead.
+```
+
+Each Ractor resolves `mymaster` independently on first use. A connection error
+invalidates only that Ractor's cached target and causes its next connection
+attempt to query Sentinel again.
+
+For replicas, pass `role: :replica` (the `:slave` alias is accepted).
+Unavailable replicas marked `s_down`, `o_down`, or `disconnected` are ignored.
+
+Sentinel credentials and TLS are independent from Redis credentials and TLS:
+
+```ruby
+SolidRedis.sentinel(
+  name: "mymaster",
+  sentinels: ["rediss://sentinel-user:secret@sentinel.example:26379"],
+  username: "redis-user",
+  password: "redis-secret",
+  ssl: true,
+  ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER },
+  sentinel_ssl: true,
+  sentinel_ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER }
+)
+```
+
+## Per-Ractor pool
+
+`new_pool` creates a conventional thread-safe pool owned by the calling
+Ractor:
+
+```ruby
+pool = SENTINEL.new_pool(size: 5, timeout: 1.0)
+
+pool.with do |client|
+  client.call("INCR", "jobs")
+end
+
+pool.call("GET", "jobs")
+pool.close
+```
+
+The pool may be shared by threads in its owning Ractor. It must not be sent to
+another Ractor. Create a separate pool inside every Ractor, as in the example
+above.
+
+## Configuration
+
+Direct Redis options:
+
+| Option | Default | Description |
+|---|---:|---|
+| `url` | | `redis://`, `rediss://`, or `unix://` URL |
+| `host` | `127.0.0.1` | Redis host |
+| `port` | `6379` | Redis port |
+| `path` | | Unix socket path |
+| `username` | | ACL username |
+| `password` | | Password |
+| `db` | `0` | Database number |
+| `timeout` | `1.0` | Default connect/read/write timeout |
+| `connect_timeout` | `timeout` | Connection timeout |
+| `read_timeout` | `timeout` | Read timeout |
+| `write_timeout` | `timeout` | Write timeout |
+| `reconnect_attempts` | `1` | Retries after a connection error |
+| `ssl` | `false` | Enable TLS |
+| `ssl_params` | | Immutable `OpenSSL::SSL::SSLContext` attributes |
+
+Sentinel additionally requires `name` and `sentinels`, and accepts `role`,
+`sentinel_username`, `sentinel_password`, `sentinel_ssl`, and
+`sentinel_ssl_params`. Sentinel defaults to two reconnect attempts.
+
+All configuration is copied and deeply frozen. Proc credentials and mutable
+objects such as `OpenSSL::X509::Store` are rejected because Ruby cannot make
+them Ractor-shareable. Prefer immutable values and paths in TLS parameters.
+
+## Lifecycle callbacks
+
+Pass a shareable `CallbackCollection` through `callbacks:` to observe
+`connected`, `disconnected`, `connection_error`, and `resolved` events:
+
+```ruby
+module RedisEvents
+  def self.connected(url)
+    Logger.info("Connected to #{url}")
+  end
+
+  def self.connection_error(type, message)
+    Logger.warn("#{type}: #{message}")
+  end
+end
+
+callbacks = CallbackCollection.new do |collection|
+  collection.register(:connected, RedisEvents)
+  collection.register(:connection_error, RedisEvents)
+end
+
+config = SolidRedis.sentinel(
+  name: "mymaster",
+  sentinels: [{ host: "127.0.0.1", port: 26_379 }],
+  callbacks: callbacks
+)
+```
+
+| Callback | Arguments |
+|---|---|
+| `connected` | resolved server URL |
+| `disconnected` | resolved server URL |
+| `connection_error` | exception class name and message |
+| `resolved` | Sentinel name and resolved server URL |
+
+Method registration is required for a Ractor-shareable callback collection.
+Block callbacks retain mutable lexical context and are therefore rejected.
+Callback exceptions propagate to the caller.
+
+## Semantics and current scope
+
+- Clients, pools, sockets, mutexes, and Sentinel runtime state are never
+  shared between Ractors.
+- Multiple threads in one Ractor share one protected Sentinel resolution.
+- Redis command errors are never retried.
+- Connection errors may retry a command according to `reconnect_attempts`.
+  Applications requiring strict at-most-once semantics should set it to `0`.
+- A pool waits up to its checkout timeout and then raises
+  `SolidRedis::CheckoutTimeoutError`.
+- Pub/Sub, transactions, blocking-call helpers, cluster routing, middleware,
+  and an asynchronous actor pool are not part of version `0.1`.
+
+### Known CRuby limitation
+
+Ractor support in CRuby is still experimental. On CRuby 3.4, running
+**multiple threads inside multiple Ractors simultaneously** can hang
+intermittently in the VM scheduler. This is reproducible with plain
+`Thread` + CPU work in bare Ractors, without solid-redis, and is fixed
+by the Ractor rewrite in CRuby >= 4.0 (verified by
+`test/ractor_stress_test.rb`, which is skipped on older Rubies).
+Safe patterns on CRuby 3.x:
+
+- one thread per Ractor (the natural Ractor model), or
+- multiple threads and a pool inside a single Ractor.
+
+Both are fully supported by this gem.
+
+An asynchronous `new_ractor_pool` would be a separate API: worker Ractors
+would own connections and exchange commands/results through messages or
+futures. It cannot transparently replace a block-based synchronous pool
+without defining backpressure, cancellation, transaction, Pub/Sub, and
+exception protocols.
+
+## Development
+
+```sh
+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.
+
+## Publishing
+
+Releases use RubyGems Trusted Publishing. Configure a pending trusted
+publisher for `nicolasva/solid-redis`, workflow `release.yml`, environment
+`release`, then push a tag matching `SolidRedis::VERSION`.

data/lib/solid_redis/client.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "socket"
+
+module SolidRedis
+  class Client
+    attr_reader :config
+
+    def initialize(config, name: nil)
+      @config = config
+      @name = name&.to_s
+      @socket = nil
+      @reader = nil
+      @target = nil
+    end
+
+    def call(*command)
+      call_v(command)
+    end
+
+    def call_v(command)
+      with_reconnect do
+        write(RESP.encode(command))
+        @reader.read
+      end
+    end
+
+    def pipelined
+      pipeline = Pipeline.new
+      yield pipeline
+      return [] if pipeline.commands.empty?
+
+      with_reconnect do
+        write(pipeline.commands.map { |command| RESP.encode(command) }.join)
+        results = pipeline.commands.map { @reader.read(exception: false) }
+        raise results.find { |result| result.is_a?(CommandError) } if results.any?(CommandError)
+
+        results
+      end
+    end
+
+    def connected?
+      @socket && !@socket.closed?
+    end
+
+    def close
+      socket = @socket
+      target = @target
+      @socket = @reader = @target = nil
+      socket&.close
+      config.notify(:disconnected, target.server_url) if socket && target
+      self
+    rescue IOError
+      self
+    end
+
+    def server_url
+      config.server_url
+    end
+
+    private
+
+    def with_reconnect
+      attempts = 0
+      begin
+        connect unless connected?
+        yield
+      rescue ConnectionError, IO::WaitReadable, IO::WaitWritable, SystemCallError => error
+        close
+        config.reset if config.sentinel?
+        config.notify(:connection_error, error.class.name, error.message)
+        if attempts < config.reconnect_attempts
+          attempts += 1
+          retry
+        end
+        raise error if error.is_a?(Error)
+
+        raise ConnectionError, error.message, cause: error
+      end
+    end
+
+    def connect
+      @target = config.sentinel? ? config.resolve : config
+      @socket = open_socket(@target)
+      @reader = RESP::Reader.new(@socket, read_timeout: @target.read_timeout)
+      authenticate
+      raw_call(["SELECT", @target.db]) unless @target.db.zero?
+      raw_call(["CLIENT", "SETNAME", @name]) if @name
+      verify_role if config.sentinel?
+      config.notify(:connected, @target.server_url)
+      self
+    rescue StandardError
+      close
+      raise
+    end
+
+    def open_socket(target)
+      socket = if target.path
+        UNIXSocket.new(target.path)
+      else
+        Socket.tcp(target.host, target.port, connect_timeout: target.connect_timeout)
+      end
+      return socket unless target.ssl?
+
+      context = OpenSSL::SSL::SSLContext.new
+      apply_ssl_params(context, target.ssl_params || {})
+      ssl_socket = OpenSSL::SSL::SSLSocket.new(socket, context)
+      ssl_socket.hostname = target.host if ssl_socket.respond_to?(:hostname=)
+      ssl_socket.sync_close = true
+      ssl_connect(ssl_socket, target.connect_timeout)
+      ssl_socket
+    rescue TimeoutError
+      socket&.close
+      raise
+    rescue IOError, SystemCallError, SocketError, OpenSSL::SSL::SSLError => error
+      socket&.close
+      raise ConnectionError, error.message, cause: error
+    rescue ArgumentError
+      socket&.close
+      raise
+    end
+
+    def ssl_connect(socket, timeout)
+      deadline = monotonic_time + timeout
+      loop do
+        result = socket.connect_nonblock(exception: false)
+        return if result == socket
+
+        remaining = deadline - monotonic_time
+        raise TimeoutError, "TLS handshake timed out after #{timeout}s" unless remaining.positive?
+
+        readers = result == :wait_readable ? [socket] : nil
+        writers = result == :wait_writable ? [socket] : nil
+        IO.select(readers, writers, nil, remaining)
+      end
+    end
+
+    def apply_ssl_params(context, params)
+      params.each do |name, value|
+        writer = :"#{name}="
+        raise ArgumentError, "Unknown SSL context option: #{name.inspect}" unless context.respond_to?(writer)
+
+        context.public_send(writer, value)
+      end
+    end
+
+    def authenticate
+      return unless @target.password
+
+      command = @target.username ? ["AUTH", @target.username, @target.password] : ["AUTH", @target.password]
+      raw_call(command)
+    end
+
+    def verify_role
+      actual = raw_call(["ROLE"]).first
+      expected = config.role == :master ? "master" : "slave"
+      return if actual == expected
+
+      raise FailoverError, "Expected Redis role #{expected.inspect}, got #{actual.inspect}"
+    end
+
+    def raw_call(command)
+      write(RESP.encode(command))
+      @reader.read
+    end
+
+    def write(payload)
+      offset = 0
+      while offset < payload.bytesize
+        unless IO.select(nil, [@socket], nil, @target.write_timeout)
+          raise TimeoutError, "Redis write timed out after #{@target.write_timeout}s"
+        end
+
+        written = @socket.write_nonblock(payload.byteslice(offset..), exception: false)
+        next if written == :wait_writable
+
+        offset += written
+      end
+    rescue IOError, SystemCallError => error
+      raise ConnectionError, error.message, cause: error
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    class Pipeline
+      attr_reader :commands
+
+      def initialize
+        @commands = []
+      end
+
+      def call(*command)
+        @commands << command
+        nil
+      end
+
+      def call_v(command)
+        @commands << command
+        nil
+      end
+    end
+  end
+end

data/lib/solid_redis/config.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module SolidRedis
+  class Config
+    DEFAULT_TIMEOUT = 1.0
+    DEFAULT_PORT = 6379
+
+    attr_reader :host, :port, :path, :username, :password, :db,
+      :connect_timeout, :read_timeout, :write_timeout, :reconnect_attempts,
+      :ssl_params
+
+    def initialize(
+      url: nil,
+      host: "127.0.0.1",
+      port: DEFAULT_PORT,
+      path: nil,
+      username: nil,
+      password: nil,
+      db: 0,
+      timeout: DEFAULT_TIMEOUT,
+      connect_timeout: timeout,
+      read_timeout: timeout,
+      write_timeout: timeout,
+      reconnect_attempts: 1,
+      ssl: false,
+      ssl_params: nil,
+      callbacks: nil
+    )
+      if url
+        values = parse_url(url)
+        host = values[:host]
+        port = values[:port]
+        path = values[:path]
+        username ||= values[:username]
+        password ||= values[:password]
+        db = values[:db] unless values[:db].nil?
+        ssl ||= values[:ssl]
+      end
+
+      @host = String(host).dup.freeze unless path
+      @port = Integer(port) unless path
+      @path = String(path).dup.freeze if path
+      @username = String(username).dup.freeze if username
+      @password = String(password).dup.freeze if password
+      @db = Integer(db)
+      @connect_timeout = positive_float(connect_timeout, :connect_timeout)
+      @read_timeout = positive_float(read_timeout, :read_timeout)
+      @write_timeout = positive_float(write_timeout, :write_timeout)
+      @reconnect_attempts = Integer(reconnect_attempts)
+      raise ArgumentError, "reconnect_attempts must not be negative" if @reconnect_attempts.negative?
+
+      @ssl = !!ssl
+      @ssl_params = Shareable.copy(ssl_params, label: "ssl_params") if ssl_params
+      @callbacks = Shareable.copy(callbacks, label: "callbacks") if callbacks
+      Ractor.make_shareable(self)
+    end
+
+    def ssl?
+      @ssl
+    end
+
+    def sentinel?
+      false
+    end
+
+    def resolved?
+      true
+    end
+
+    def server_key
+      [path, host, port].freeze
+    end
+
+    def server_url
+      return "unix://#{path}?db=#{db}" if path
+
+      scheme = ssl? ? "rediss" : "redis"
+      address = host.include?(":") ? "[#{host}]" : host
+      "#{scheme}://#{address}:#{port}/#{db}"
+    end
+
+    def new_client(**options)
+      Client.new(self, **options)
+    end
+
+    def new_pool(**options)
+      Pool.new(self, **options)
+    end
+
+    def notify(event, *arguments)
+      return unless @callbacks&.respond_to?(event)
+
+      @callbacks.respond_with(event, *arguments)
+    end
+
+    def inspect
+      "#<#{self.class.name} #{server_url}>"
+    end
+
+    private
+
+    def parse_url(url)
+      uri = URI.parse(url)
+      unless %w[redis rediss unix].include?(uri.scheme)
+        raise ArgumentError, "Unsupported Redis URL scheme: #{uri.scheme.inspect}"
+      end
+
+      if uri.scheme == "unix"
+        {
+          path: uri.path,
+          username: decoded(uri.user),
+          password: decoded(uri.password),
+          db: query_db(uri),
+          ssl: false,
+        }
+      else
+        {
+          host: uri.host,
+          port: uri.port || DEFAULT_PORT,
+          username: decoded(uri.user),
+          password: decoded(uri.password),
+          db: path_db(uri) || query_db(uri),
+          ssl: uri.scheme == "rediss",
+        }
+      end
+    rescue URI::InvalidURIError => error
+      raise ArgumentError, "Invalid Redis URL: #{error.message}", cause: error
+    end
+
+    def path_db(uri)
+      return if uri.path.nil? || uri.path.empty? || uri.path == "/"
+
+      Integer(uri.path.delete_prefix("/"))
+    end
+
+    def query_db(uri)
+      return 0 unless uri.query
+
+      value = URI.decode_www_form(uri.query).to_h["db"]
+      value ? Integer(value) : 0
+    end
+
+    def decoded(value)
+      URI.decode_www_form_component(value) if value
+    end
+
+    def positive_float(value, name)
+      value = Float(value)
+      raise ArgumentError, "#{name} must be positive" unless value.positive?
+
+      value
+    end
+  end
+end

data/lib/solid_redis/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SolidRedis
+  class Error < StandardError; end
+  class ConnectionError < Error; end
+  class TimeoutError < ConnectionError; end
+  class ProtocolError < Error; end
+  class CommandError < Error; end
+  class AuthenticationError < CommandError; end
+  class FailoverError < ConnectionError; end
+  class CheckoutTimeoutError < TimeoutError; end
+  class ClosedError < Error; end
+end