solid-redis 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4bfba5a15f75c77fa0c5a9d2a85a0d5d8b50ebada6fbd5e1895e56e47b5813a
-  data.tar.gz: 842b205f8ba0b9298451f24bec08c0d76542e6b46026b27539853d35c06fce54
+  metadata.gz: b8d43f81f25072d1e69cf2eb753ce70869745c2b60e5b7130681b77cce431907
+  data.tar.gz: 8829253e57de67c1b5ce46932849e0dd105ca49e0bf433aa88d4e3361e0c2f75
 SHA512:
-  metadata.gz: 8a6afa66bb51a4723939441be103372efd6260c670dd8e68ca81d788cc2430bc732221c2b7b930a35365d207b1e095a654ecbd88bac715c08bc8b6f86028872d
-  data.tar.gz: c010108671dfc8c343b213fde778afc1e9c3e2750051629ae585d2857037d8da1dd455ff2dba974b78098f014a7c25c495f30d4b1fc88b2b9ab2bf236bd0bca6
+  metadata.gz: 41e44bbd248002414a12a726376e9cbf2acad0825b163bab1633db89cc5ae4c1903776ec24c51cd0c59a26335999a0f5510a4dfc8052af6686495554cb135315
+  data.tar.gz: '01281e6eaf973aaff81ffeddeb346a4edf296461532b6f6207319dba8dcd2af3c6cd5e1581e1d73452892c128189c1695cde79348420b87ad4bf54c8bdb8598b'

data/README.md

@@ -2,6 +2,7 @@
 
 [![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)
+[![Downloads](https://img.shields.io/gem/dt/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
@@ -242,6 +243,187 @@ 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.
 
+## Examples
+
+### Parallel job workers, one Ractor each
+
+Every worker receives the same shareable Sentinel specification and builds
+its own pool. Nothing but the specification and plain data crosses the
+Ractor boundary.
+
+```ruby
+SENTINEL = SolidRedis.sentinel(
+  name: "mymaster",
+  sentinels: ["redis://sentinel-1:26379", "redis://sentinel-2:26379"],
+  password: ENV.fetch("REDIS_PASSWORD"),
+  timeout: 1.0
+)
+
+workers = 4.times.map do |index|
+  Ractor.new(SENTINEL, index) do |sentinel, worker_id|
+    pool = sentinel.new_pool(size: 2)
+    processed = 0
+
+    while (job = pool.call("RPOP", "jobs"))
+      pool.call("HINCRBY", "stats", "worker:#{worker_id}", 1)
+      processed += 1
+    end
+
+    processed
+  ensure
+    pool&.close
+  end
+end
+
+workers.sum(&:value) # total processed jobs (use &:take on Ruby 3.x)
+```
+
+### Threads sharing a pool inside one Ractor
+
+Threads within a Ractor may share a pool. On CRuby < 4.0 keep all threads in
+a single Ractor (see the limitation below).
+
+```ruby
+pool = SolidRedis.config(url: "redis://localhost:6379").new_pool(size: 8)
+
+threads = 20.times.map do |i|
+  Thread.new { pool.call("SET", "key:#{i}", i) }
+end
+threads.each(&:join)
+
+pool.call("DBSIZE") # => 20
+pool.close
+```
+
+### Pipelines and error handling
+
+`call` raises `SolidRedis::CommandError` on a Redis error reply. A pipeline
+sends all commands in one round trip and reads every reply. By default it
+then raises the first `CommandError` if any; pass `exception: false` to get
+errors back in place and keep the other results.
+
+```ruby
+client = SolidRedis.config(url: "redis://localhost:6379").new_client
+
+begin
+  client.call("INCR", "not-a-number")
+rescue SolidRedis::CommandError => error
+  error.message # => "ERR value is not an integer or out of range"
+end
+
+client.pipelined do |pipeline|
+  pipeline.call("SET", "counter", 1)
+  pipeline.call("INCR", "counter")
+  pipeline.call("GET", "counter")
+end
+# => ["OK", 2, "2"]
+
+begin
+  client.pipelined do |pipeline|
+    pipeline.call("SET", "counter", "abc")
+    pipeline.call("INCR", "counter") # fails; the SET was still applied
+  end
+rescue SolidRedis::CommandError => error
+  error.message # => "ERR value is not an integer or out of range"
+end
+
+results = client.pipelined(exception: false) do |pipeline|
+  pipeline.call("SET", "counter", "abc")
+  pipeline.call("INCR", "counter")
+  pipeline.call("GET", "counter")
+end
+# => ["OK", #<SolidRedis::CommandError: ERR value is not an integer...>, "abc"]
+
+results.each { |result| raise result if result.is_a?(SolidRedis::CommandError) }
+```
+
+### Building commands dynamically
+
+`call_v` accepts an array, which is convenient for variadic commands.
+
+```ruby
+fields = { "name" => "Ada", "language" => "Ruby" }
+client.call_v(["HSET", "user:1", *fields.flatten])
+client.call("HGETALL", "user:1")
+# => { "name" => "Ada", "language" => "Ruby" } with RESP3
+# => ["name", "Ada", "language", "Ruby"]     with RESP2
+```
+
+### Reading from replicas
+
+Use `role: :replica` for read-only traffic and keep a separate `:master`
+specification for writes. Both are shareable and resolve independently.
+
+```ruby
+WRITER = SolidRedis.sentinel(name: "mymaster", sentinels: SENTINELS, role: :master)
+READER = SolidRedis.sentinel(name: "mymaster", sentinels: SENTINELS, role: :replica)
+
+Ractor.new(WRITER, READER) do |writer, reader|
+  writer.new_client.call("SET", "greeting", "hello")
+  reader.new_client.call("GET", "greeting") # after replication
+end
+```
+
+### Observing failover
+
+After a connection error the Ractor's cached target is dropped and the next
+attempt asks Sentinel again. Register a callback to trace it.
+
+```ruby
+module FailoverLog
+  def self.connection_error(type, message) = warn("[redis] #{type}: #{message}")
+  def self.resolved(name, url)             = warn("[redis] #{name} -> #{url}")
+end
+
+callbacks = CallbackCollection.new do |collection|
+  collection.register(:connection_error, FailoverLog)
+  collection.register(:resolved, FailoverLog)
+end
+
+sentinel = SolidRedis.sentinel(
+  name: "mymaster",
+  sentinels: SENTINELS,
+  reconnect_attempts: 2,
+  callbacks: callbacks
+)
+
+client = sentinel.new_client
+client.call("PING")            # [redis] mymaster -> redis://10.0.0.15:6379
+# ... master goes down, Sentinel promotes a replica ...
+client.call("PING")            # [redis] ConnectionError: Connection reset by peer
+                               # [redis] mymaster -> redis://10.0.0.16:6379
+```
+
+### Strict at-most-once delivery
+
+Retries after a connection error may replay a command. Disable them for
+non-idempotent operations and handle the error yourself.
+
+```ruby
+config = SolidRedis.config(url: "redis://localhost:6379", reconnect_attempts: 0)
+client = config.new_client
+
+begin
+  client.call("LPUSH", "payments", payment_id)
+rescue SolidRedis::ConnectionError
+  # Nothing was retried; decide whether to re-enqueue.
+end
+```
+
+### Unix socket and TLS
+
+```ruby
+SolidRedis.config(url: "unix:///var/run/redis/redis.sock", db: 2)
+
+SolidRedis.config(
+  url: "rediss://redis.example:6380",
+  ssl_params: {
+    verify_mode: OpenSSL::SSL::VERIFY_PEER,
+    ca_file: "/etc/ssl/certs/redis-ca.pem"
+  }
+)
+```
+
 ## Semantics and current scope
 
 - Clients, pools, sockets, mutexes, and Sentinel runtime state are never

data/lib/solid_redis/client.rb

@@ -26,7 +26,7 @@ module SolidRedis
       end
     end
 
-    def pipelined
+    def pipelined(exception: true)
       pipeline = Pipeline.new
       yield pipeline
       return [] if pipeline.commands.empty?
@@ -34,7 +34,9 @@ module SolidRedis
       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)
+        if exception && (error = results.find { |result| result.is_a?(CommandError) })
+          raise error
+        end
 
         results
       end

data/lib/solid_redis/pool.rb

@@ -37,8 +37,8 @@ module SolidRedis
       with { |client| client.call_v(command) }
     end
 
-    def pipelined(&block)
-      with { |client| client.pipelined(&block) }
+    def pipelined(exception: true, &block)
+      with { |client| client.pipelined(exception: exception, &block) }
     end
 
     def close

data/lib/solid_redis/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid-redis
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Nicolas Vandenbogaerde
@@ -95,7 +95,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-  documentation_uri: https://www.rubydoc.info/gems/solid-redis/0.1.0
+  documentation_uri: https://www.rubydoc.info/gems/solid-redis/0.2.0
   source_code_uri: https://github.com/nicolasva/solid-redis
 rdoc_options: []
 require_paths: