duel-redis 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8945f91caaf5208b93bdaef3934320e6722dc1ba837d5c6d72d8eb2c8a97245b
+  data.tar.gz: a55066487902efb5bb189a982d3de10a8698f984d22e05f62bc538c6a7d542a3
+SHA512:
+  metadata.gz: 51a4bf4253ceb07cf1b809e3ed6c124dff48884875bb73a229f2e2fb91764c8ce2a5536f97e8b45ae510a48da3c4f89e6ca872919cf2a75090d0f236003b1c03
+  data.tar.gz: d5f2ee1dd4383dd37e8b9cb359f122d7a8459cc445cadf04581daaa7fe510153df4bcc8b051cd0c0adfec81757c9831b2226d431ef1605e0804f4fd222c3801f

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-24
+
+The first release. duel-redis is a Duel plugin, open source under the MIT
+license. It needs Ruby 3.4 or later, Duel 0.1, and `redis-server`
+(Redis 6.2 or later, or Valkey) on the `PATH`.
+
+### Added
+
+- `c.use :redis`: a Redis server for each Duel worker, on a Unix
+  socket, and the `redis_cpu`, `redis_commands` and `redis_round_trips`
+  metrics.
+- `Duel::Redis.url` and `Duel::Redis.flush`, for benchmarks: `flush`
+  opens a connection of its own, from the worker's `DUEL_REDIS_URL`.
+- `c.use :redis` returns the plugin's own connection, made in each
+  worker (`c.in_worker`) and closed as it ends (`at_stop`). Its `value`
+  fails outside a worker. The module keeps no connection.
+- `redis_commands` and `redis_round_trips` are in commands and round
+  trips (`unit:`), so reports read "1 command → 2 commands".
+- `Duel::Redis.flush` raises `Duel::Error` while a benchmark is measured
+  (`Duel.measuring?`): it's for `setup` hooks, and `once` and `untimed`
+  blocks, where its `FLUSHALL` isn't counted.
+- Its metrics are costly to read (Duel's `costly`): a benchmark with an
+  `around_iteration` hook reads the server's statistics only as each
+  sample starts and stops, not twice an iteration, and what the hook
+  sends the server (a transaction's `BEGIN` and `ROLLBACK`, say) is
+  learned in each worker and subtracted.
+- Each worker's server works in the worker's own directory (`--dir`),
+  so persistence that `args:` turn on writes its snapshots and
+  append-only files there, never in the project.
+- The plugin's connection (`Duel::Redis::Connection#call`) reads every
+  type of reply RESP2 has, whole: a nil bulk string (a missing key's),
+  an array (returned as an `Array`, nested ones and nil included, any
+  error in it a `RuntimeError`), and an integer, as an `Integer`. It
+  never sends `HELLO`, so it reads RESP2 only: a reply of another type
+  (RESP3's) closes the connection and raises `IOError`, rather than
+  read the next reply out of step.
+
+
+[Unreleased]: https://github.com/sferik/duel-ruby/compare/duel-redis-v0.1.0...HEAD
+[0.1.0]: https://github.com/sferik/duel-ruby/releases/tag/duel-redis-v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erik Berlin
+
+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,80 @@
+# duel-redis
+
+[![Duel](https://raw.githubusercontent.com/sferik/duel-ruby/main/assets/badge.svg)](https://github.com/sferik/duel-ruby)
+[![duel-redis](https://github.com/sferik/duel-ruby/actions/workflows/plugin-redis.yml/badge.svg)](https://github.com/sferik/duel-ruby/actions/workflows/plugin-redis.yml)
+[![Gem Version](https://badge.fury.io/rb/duel-redis.svg)](https://rubygems.org/gems/duel-redis)
+
+A [Duel](https://github.com/sferik/duel-ruby) plugin for code that talks
+to Redis: each Duel worker gets a Redis server of its own, and every
+benchmark is judged on what Redis did for it too.
+
+| Metric | What it is | A regression |
+|---|---|---|
+| `redis_cpu` | the time Redis spent running the benchmark's commands, in µs | judged like CPU time |
+| `redis_commands` | the commands it ran | any increase |
+| `redis_round_trips` | the replies it wrote: one per round trip | any increase |
+
+So a change that sends one more command per job, or stops pipelining,
+fails even when its CPU time on the Ruby side doesn't change.
+
+## Installation
+
+```ruby
+# Gemfile
+group :development do
+  gem "duel-redis"
+end
+```
+
+> [!NOTE]
+> It needs `redis-server` (Redis 6.2 or later, or Valkey) on the `PATH`.
+
+## Usage
+
+```ruby
+# .duel.rb
+Duel.configure { |c| c.use :redis }
+```
+
+Each worker's server listens only on a Unix socket in the worker's own
+directory, with persistence off, and works in that directory too
+(`--dir`): if your `args:` turn persistence on, its snapshots and
+append-only files go there, never in your project. Its URL is in
+`DUEL_REDIS_URL`, and in `REDIS_URL` too, so a client that reads that
+finds it and nothing reaches another Redis. Benchmarks can call
+`Duel::Redis.url` and `Duel::Redis.flush`.
+
+> [!IMPORTANT]
+> `Duel::Redis.flush` is for setting up: call it in a `setup` hook, or
+> a `once` or `untimed` block. While a benchmark is measured (`Duel.measuring?`), it
+> raises `Duel::Error` rather than have its `FLUSHALL` counted.
+
+```ruby
+# duel/cache_duel.rb
+duel "cache: a hit" do
+  once do
+    Duel::Redis.flush                           # empties the worker's server (over a connection of its own)
+    @cache = MyCache.new(url: Duel::Redis.url)  # its URL
+    @cache.write("k", "v")
+  end
+  @cache.read("k")
+end
+```
+
+Options:
+
+```ruby
+c.use :redis,
+  server: "valkey-server",        # the program (default: DUEL_REDIS_SERVER, or redis-server)
+  args: ["--maxmemory", "64mb"],  # more of its options
+  env: %w[CACHE_URL]              # variables given its URL besides DUEL_REDIS_URL (default: REDIS_URL)
+```
+
+The metrics come from the server's `INFO` (command statistics and
+`total_writes_processed`), read over a connection of the plugin's own,
+opened as each worker starts (Duel's `c.in_worker`) and closed as it
+ends. `c.use :redis` returns it, for a `.duel.rb` that reads the server
+too (`connection.value`, in a worker only). Each reading is a command and a
+reply itself, so Duel learns what readings add, and takes it away. Reports
+count them: `redis_commands 4→6`, `redis_round_trips: 1 round trip → 2
+round trips an iteration`.

data/lib/duel/redis/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Duel
+  module Redis
+    VERSION = "0.1.0"
+  end
+end

data/lib/duel/redis.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "duel"
+require "socket"
+require_relative "redis/version"
+
+module Duel
+  # A Redis server of each worker's own, and what it did for each
+  # benchmark:
+  #
+  # - redis_cpu: the time Redis spent running commands, in microseconds
+  #   (judged by ratio, as CPU time is)
+  # - redis_commands: the commands it ran (counted)
+  # - redis_round_trips: the replies it wrote, one per round trip (counted)
+  #
+  #   # .duel.rb
+  #   Duel.configure { |c| c.use :redis }
+  #
+  # Benchmarks can call Duel::Redis.url and Duel::Redis.flush.
+  #
+  # The server listens only on a Unix socket in the worker's directory,
+  # and works there too (--dir): what its options make it write, a
+  # snapshot or an append-only file, goes there, never in the project.
+  # Its URL is in DUEL_REDIS_URL, and in REDIS_URL too (unless +env+
+  # names others), so a client that reads that finds it.
+  module Redis
+    Duel.plugin(:redis, self)
+
+    URL = "DUEL_REDIS_URL"
+
+    # Every server's options: no TCP port, and nothing written to disk.
+    OPTIONS = ["--port", "0", "--save", "", "--appendonly", "no"].freeze
+
+    # Configures Duel for the plugin (c.use :redis): the server
+    # (+server+ is the program, +args+ more of its options) and its
+    # metrics. Returns the plugin's own connection to it, a worker's
+    # (see Config#in_worker, and in tests, Duel::Testing.in_worker).
+    def self.configure(config, server: ENV.fetch("DUEL_REDIS_SERVER", "redis-server"), args: [], env: %w[REDIS_URL])
+      config.prepare(:worker) do |w|
+        socket = w.path("redis.sock")
+        w.spawn(*[server, "--unixsocket", socket, "--dir", w.dir, *OPTIONS] + args)
+        w.wait_until { Connection.ping(socket) }
+        url = "unix://#{socket}"
+        ([URL] + env).to_h { |name| [name, url] }
+      end
+      connection = config.in_worker { |w| Connection.new(url).tap { |redis| w.at_stop { redis.close } } }
+      config.metric(METRICS) { stats(connection.value) }.costly
+      connection
+    end
+
+    METRICS = {
+      "redis_cpu" => {kind: :ratio, unit: "µs", floor: 300},
+      "redis_commands" => {kind: :counted, unit: %w[command commands]},
+      "redis_round_trips" => {kind: :counted, unit: ["round trip", "round trips"]}
+    }
+
+    # What the worker's server has done so far, read over +connection+:
+    # every command's time but INFO's own (the reading's, too slight to
+    # count but not steady enough to take away), and every command and
+    # reply.
+    def self.stats(connection)
+      info = connection.call("INFO", "all") #: String
+      usec = calls = 0
+      info.scan(/^cmdstat_([^:]+):calls=(\d+),usec=(\d+)/) do |command, c, u|
+        calls += Integer(c)
+        usec += Integer(u) unless command == "info"
+      end
+      {"redis_cpu" => usec, "redis_commands" => calls, "redis_round_trips" => Integer(info[/^total_writes_processed:(\d+)/, 1])}
+    end
+
+    # For benchmarks: the worker's server.
+    def self.url = ENV.fetch(URL)
+
+    # Empties it, over a connection of its own (opened and closed: a Unix
+    # socket's is cheap). For setup or untimed blocks only: while a
+    # benchmark is measured (Duel.measuring?) it fails, as its FLUSHALL
+    # would be counted.
+    def self.flush
+      Duel.unmeasured!("Duel::Redis.flush")
+
+      connection = Connection.new(url)
+      begin
+        connection.call("FLUSHALL") #: String
+      ensure
+        connection.close
+      end
+    end
+
+    # The least a connection needs to read a server's statistics: not the
+    # code's own, whose commands are what's measured.
+    class Connection
+      CLOSED = "Redis closed the connection"
+
+      # The first byte of a reply: its type, one of RESP2's.
+      STATUS, ERROR, INTEGER, BULK, ARRAY = "+-:$*".bytes
+
+      def self.ping(path)
+        socket = UNIXSocket.new(path)
+        begin
+          socket.write("PING\r\n")
+          socket.gets == "+PONG\r\n"
+        ensure
+          socket.close
+        end
+      rescue SystemCallError
+        false
+      end
+
+      def initialize(url)
+        @socket = UNIXSocket.new(url.delete_prefix("unix://"))
+      end
+
+      # Sends a command; returns its reply, read whole (every type RESP2
+      # has): a status or a bulk string as a String, an integer as an
+      # Integer, a missing one (a nil bulk string or array) as nil, and an
+      # array as an Array of replies, any error in it a RuntimeError. An
+      # error reply raises it. A reply cut short (the server gone) raises
+      # IOError.
+      #
+      # The connection never sends HELLO, so Redis answers in RESP2. A
+      # reply of a type RESP2 doesn't have (RESP3's, after a HELLO 3)
+      # closes the connection, as the rest of it can't be read, and raises
+      # IOError.
+      def call(*args)
+        @socket.write(args.map(&:to_s).reduce("*#{args.size}\r\n") { |out, arg| out << "$#{arg.bytesize}\r\n#{arg}\r\n" })
+        reply = read
+        raise reply if reply.is_a?(Exception)
+
+        reply
+      end
+
+      def close = @socket.close
+
+      private
+
+      # A reply, and every element of an array's: its first line's type
+      # (its first byte), then what follows it.
+      def read
+        line = (@socket.gets or raise IOError, CLOSED)
+        line.chomp!
+        case line.getbyte(0)
+        when STATUS then line.byteslice(1..)
+        when BULK then bulk(number(line))
+        when INTEGER then number(line)
+        when ARRAY then array(number(line))
+        when ERROR then RuntimeError.new("Redis: #{line.byteslice(1..)}")
+        else
+          close
+          raise IOError, "Redis: a reply of a type the connection doesn't read (RESP2 only): #{line}"
+        end
+      end
+
+      # A line's number, after its type: the type byte made a space rather
+      # than cut (which would copy the line), as Integer() skips one.
+      def number(line)
+        line.setbyte(0, 32)
+        Integer(line)
+      end
+
+      # A bulk string of +size+ bytes, and its CRLF (nil for size -1, a
+      # missing one).
+      def bulk(size)
+        return if size == -1
+
+        @socket.read(size + 2)&.delete_suffix!("\r\n") or raise IOError, CLOSED
+      end
+
+      # An array of +size+ replies (nil for size -1, a missing one).
+      def array(size)
+        Array.new(size) { read } unless size == -1
+      end
+    end
+  end
+end

data/sig/duel/redis.rbs

@@ -0,0 +1,68 @@
+module Duel
+  # A Redis server of each worker's own, and what it did for each
+  # benchmark (redis_cpu, redis_commands, redis_round_trips).
+  module Redis
+    VERSION: String
+
+    URL: String
+
+    # Every server's options: no TCP port, and nothing written to disk.
+    OPTIONS: Array[String]
+
+    METRICS: Hash[String, Metric::settings]
+
+    # Configures Duel for the plugin (c.use :redis): the server (+server+
+    # is the program, +args+ more of its options, +env+ the variables
+    # besides DUEL_REDIS_URL given its URL) and its metrics. Returns the
+    # plugin's own connection to it, a worker's.
+    def self.configure: (Config config, ?server: String, ?args: Array[String], ?env: Array[String]) -> InWorker[Connection]
+
+    # What the worker's server has done so far, read over +connection+.
+    def self.stats: (Connection connection) -> Hash[String, Integer]
+
+    # For benchmarks: the worker's server.
+    def self.url: () -> String
+
+    # Empties it, over a connection of its own: in setup or untimed blocks
+    # only (it fails while a benchmark is measured).
+    def self.flush: () -> String
+
+    # The least a connection needs to read a server's statistics.
+    class Connection
+      # A reply, as Connection#call returns it, or in an array (where an
+      # error is one too).
+      type reply = String | Integer | RuntimeError | Array[reply] | nil
+
+      CLOSED: String
+
+      # The first byte of a reply: its type, one of RESP2's.
+      STATUS: Integer
+      ERROR: Integer
+      INTEGER: Integer
+      BULK: Integer
+      ARRAY: Integer
+
+      @socket: UNIXSocket
+
+      def self.ping: (String path) -> bool
+
+      def initialize: (String url) -> void
+
+      # Sends a command; returns its reply (RESP2's, read whole): an error
+      # reply raises.
+      def call: (*String | Symbol | Integer args) -> (String | Integer | Array[reply] | nil)
+
+      def close: () -> void
+
+      private
+
+      def read: () -> reply
+
+      def number: (String line) -> Integer
+
+      def bulk: (Integer size) -> String?
+
+      def array: (Integer size) -> Array[reply]?
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: duel-redis
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Erik Berlin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: duel
+  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'
+description: 'A Duel plugin: each worker gets a Redis server of its own, and every
+  benchmark is judged on the Redis CPU time, commands and round trips it took too.'
+email:
+- sferik@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/duel/redis.rb
+- lib/duel/redis/version.rb
+- sig/duel/redis.rbs
+homepage: https://github.com/sferik/duel-ruby/tree/main/plugins/redis
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/sferik/duel-ruby/tree/main/plugins/redis
+  changelog_uri: https://github.com/sferik/duel-ruby/blob/main/plugins/redis/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sferik/duel-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: A Redis server for each Duel worker, and what it did for each benchmark
+test_files: []