valkey-glide-rb 0.9.0.pre.rc1

data/README.md

@@ -0,0 +1,268 @@
+# Valkey GLIDE for Ruby
+
+Valkey General Language Independent Driver for the Enterprise (GLIDE) is the official open-source Valkey client library, proudly part of the [Valkey](https://valkey.io) organization. The Ruby gem (`valkey-rb`) wraps [Valkey GLIDE Core](https://github.com/valkey-io/valkey-glide) (Rust) and aims to be a **drop-in replacement for [redis-rb](https://github.com/redis/redis-rb)** while delivering GLIDE performance, reliability, and enterprise features.
+
+## Why Choose Valkey GLIDE?
+
+- **Community and Open Source**: Join our vibrant community and contribute to the project.
+- **Reliability**: Built with best practices learned from over a decade of operating Redis OSS-compatible services.
+- **Performance**: Optimized for high performance and low latency via the Rust-based GLIDE core.
+- **High Availability**: Cluster-aware routing, reconnection, and fault tolerance.
+- **Cross-Language Consistency**: Same core driver as Python, Java, Node.js, and Go clients.
+- **Drop-in Replacement**: Familiar redis-rb-style API (`Valkey.new`, command methods, `pipelined`, URL parsing).
+- **Observability**: Native OpenTelemetry tracing and client statistics.
+
+## Documentation
+
+- **Command coverage**: [Implementation status wiki](https://github.com/valkey-io/valkey-glide-ruby/wiki/The-implementation-status-of-the-Valkey-commands)
+- **Valkey GLIDE overview**: [glide.valkey.io](https://glide.valkey.io/)
+- **Supported engine versions**: [valkey-glide README — Supported Engine Versions](https://github.com/valkey-io/valkey-glide/blob/main/README.md#supported-engine-versions)
+- **Local development**: [DEVELOPER.md](./DEVELOPER.md)
+
+## Supported Engine Versions
+
+| Engine Type | 6.2 | 7.0 | 7.1 | 7.2 | 8.0 | 8.1 | 9.0 |
+|-------------|-----|-----|-----|-----|-----|-----|-----|
+| Valkey      | -   | -   | -   | ✓   | ✓   | ✓   | ✓   |
+| Redis OSS   | ✓   | ✓   | ✓   | ✓   | -   | -   | -   |
+
+## Getting Started — Ruby Wrapper
+
+### System Requirements
+
+The release of Valkey GLIDE Ruby was tested on the following platforms:
+
+**Linux:**
+
+- Ubuntu 20+ (x86_64/amd64 and arm64/aarch64)
+- Amazon Linux 2 (AL2) and 2023 (AL2023) (x86_64)
+
+**Note:** Alpine Linux / MUSL is **not** currently supported.
+
+**macOS:**
+
+- macOS 14.7+ (Apple silicon / aarch64)
+- macOS 13.7+ (x86_64 / amd64)
+
+### Ruby Supported Versions
+
+| Ruby Version | MRI | JRuby |
+|--------------|-----|-------|
+| 2.6          | ✓   | -     |
+| 2.7          | ✓   | -     |
+| 3.0 – 3.4    | ✓   | ✓     |
+
+Minimum Ruby version: **2.6.0** (see `valkey.gemspec`).
+
+### Installation and Setup
+
+Install from RubyGems:
+
+```bash
+gem install valkey-rb
+```
+
+Or add to your `Gemfile`:
+
+```ruby
+gem "valkey-rb"
+```
+
+Verify installation:
+
+```bash
+ruby -e 'require "valkey"; puts Valkey::VERSION'
+```
+
+The gem ships prebuilt native libraries (`libglide_ffi.so` on Linux, `libglide_ffi.dylib` on macOS) and depends on the [`ffi`](https://github.com/ffi/ffi) gem.
+
+## Basic Examples
+
+### Standalone Mode
+
+```ruby
+require "valkey"
+
+client = Valkey.new(host: "localhost", port: 6379)
+
+client.set("mykey", "hello world")
+# => "OK"
+
+client.get("mykey")
+# => "hello world"
+
+client.close
+```
+
+### Standalone with URL (redis-rb compatible)
+
+```ruby
+client = Valkey.new(url: "redis://localhost:6379/0")
+# TLS: rediss://user:password@localhost:6380/0
+
+client.ping
+# => "PONG"
+```
+
+### Cluster Mode
+
+```ruby
+nodes = [
+  { host: "127.0.0.1", port: 7000 },
+  { host: "127.0.0.1", port: 7001 },
+  { host: "127.0.0.1", port: 7002 },
+  { host: "127.0.0.1", port: 7003 },
+  { host: "127.0.0.1", port: 7004 },
+  { host: "127.0.0.1", port: 7005 }
+]
+
+client = Valkey.new(nodes: nodes, cluster_mode: true)
+client.set("foo", "bar")
+client.get("foo")
+# => "bar"
+```
+
+### Pipelining
+
+Batch multiple commands in a single network round trip (non-atomic pipeline):
+
+```ruby
+results = client.pipelined do |pipe|
+  pipe.set("key1", "value1")
+  pipe.get("key1")
+  pipe.incr("counter")
+end
+# => ["OK", "value1", 1]
+```
+
+> **Note:** Transactional commands (`MULTI` / `EXEC` / `DISCARD`) in a pipeline are executed sequentially as a workaround for FFI batch stability. Prefer `multi` / `exec` on the main client for transactions.
+
+### Connection Options (redis-rb compatible)
+
+| Option | Description |
+|--------|-------------|
+| `host`, `port` | Server address (default `127.0.0.1:6379`) |
+| `url` | `redis://` or `rediss://` URI (merged with explicit options) |
+| `db` | Database index (standalone only) |
+| `password`, `username` | Authentication |
+| `timeout` | Request timeout in seconds (default `5.0`) |
+| `connect_timeout` | Connection timeout in seconds |
+| `ssl`, `ssl_params` | TLS (`ca_file`, `cert`, `key`, `ca_path`, `root_certs`) |
+| `cluster_mode` | Enable cluster client |
+| `nodes` | Array of `{ host:, port: }` hashes |
+| `protocol` | `:resp2` (default) or `:resp3` |
+| `client_name` | `CLIENT SETNAME` value |
+| `reconnect_attempts`, `reconnect_delay`, `reconnect_delay_max` | Connection retry strategy |
+
+```ruby
+client = Valkey.new(
+  host: "localhost",
+  port: 6379,
+  timeout: 2.0,
+  connect_timeout: 1.0,
+  client_name: "my-app",
+  protocol: :resp3
+)
+```
+
+## OpenTelemetry
+
+Valkey GLIDE Ruby configures OpenTelemetry in the **native Rust core** (not via the Ruby `opentelemetry-sdk` gem). Initialize once per process before creating clients:
+
+```ruby
+require "valkey"
+
+Valkey::OpenTelemetry.init(
+  traces: {
+    endpoint: "http://localhost:4318/v1/traces",
+    sample_percentage: 10
+  },
+  metrics: {
+    endpoint: "http://localhost:4318/v1/metrics"
+  },
+  flush_interval_ms: 5000
+)
+
+client = Valkey.new(host: "localhost", port: 6379)
+client.set("key", "value")  # traced when sampling applies
+```
+
+**Supported endpoint formats:**
+
+- HTTP/HTTPS: `http://localhost:4318/v1/traces`
+- gRPC: `grpc://localhost:4317`
+- File (testing): `file:///tmp/valkey_traces.json`
+
+OpenTelemetry can only be initialized **once per process**. Spans are created in the FFI layer when sampling is enabled.
+
+## Examples
+
+Runnable examples are in [examples/](./examples/):
+
+```bash
+bundle exec ruby examples/standalone.rb
+bundle exec ruby examples/pipelining.rb
+bundle exec ruby examples/opentelemetry.rb
+```
+
+See [examples/README.md](./examples/README.md) for cluster setup and environment variables.
+
+## Client Statistics
+
+Monitor global client metrics (shared across all clients in the process):
+
+```ruby
+stats = client.get_statistics
+# alias: client.statistics
+
+puts "Connections: #{stats[:total_connections]}"
+puts "Clients: #{stats[:total_clients]}"
+puts "Compressed values: #{stats[:total_values_compressed]}"
+```
+
+Available keys: `:total_connections`, `:total_clients`, `:total_values_compressed`, `:total_values_decompressed`, `:total_original_bytes`, `:total_bytes_compressed`, `:total_bytes_decompressed`, `:compression_skipped_count`.
+
+## Pub/Sub
+
+Pub/Sub uses a native callback registered at connection time. Configure subscriptions via command modules (`subscribe`, `psubscribe`, etc.). See [DEVELOPER.md](./DEVELOPER.md) and integration tests in `test/valkey/pubsub_commands_test.rb` for details.
+
+## Layout of Ruby Code
+
+| Path | Purpose |
+|------|---------|
+| `lib/valkey.rb` | Main client: connection, pipelining, response conversion |
+| `lib/valkey/bindings.rb` | FFI bindings to `libglide_ffi` |
+| `lib/valkey/commands/` | Command modules (strings, hashes, streams, cluster, JSON, vector search, …) |
+| `lib/valkey/opentelemetry.rb` | OpenTelemetry configuration |
+| `lib/valkey/pipeline.rb` | Pipeline command batching |
+| `test/valkey/` | Standalone integration tests |
+| `test/cluster/` | Cluster integration tests |
+| `test/lint/` | Shared lint tests (redis-rb compatibility patterns) |
+
+## redis-rb Compatibility
+
+This client mirrors redis-rb conventions where possible:
+
+- `Valkey.new` with `url`, `host`, `port`, `db`, `ssl_params`
+- Command method names and argument ordering aligned with redis-rb
+- `pipelined`, `multi` / `exec`, `disconnect!` (alias of `close`)
+
+Not every redis-rb API is implemented yet. See the [command implementation wiki](https://github.com/valkey-io/valkey-glide-ruby/wiki/The-implementation-status-of-the-Valkey-commands) for coverage.
+
+## Building and Testing
+
+Instructions for building from source, updating the FFI library, running tests, and contributing are in [DEVELOPER.md](./DEVELOPER.md).
+
+For AI-assisted development, see [AGENTS.md](./AGENTS.md) and [CLAUDE.md](./CLAUDE.md).
+
+Contributing: [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Community and Feedback
+
+We encourage you to join our community to support, share feedback, and ask questions on Valkey Slack: [Join Valkey Slack](https://join.slack.com/t/valkey-oss-developer/shared_invite/zt-2nxs51chx-EB9hu9Qdch3GMfRcztTSkQ).
+
+Report issues: [valkey-glide-ruby issues](https://github.com/valkey-io/valkey-glide-ruby/issues).
+
+## License
+
+Apache-2.0 — see [LICENSE](https://github.com/valkey-io/valkey-glide-ruby/blob/main/LICENSE) in the repository.

data/Rakefile

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# Only load bundler gem tasks when not testing installed gem
+# bundler/gem_tasks can interfere with load path when testing installed gems
+require 'bundler/gem_tasks' unless ENV["TEST_INSTALLED_GEM"]
+require 'rake/testtask'
+
+# =============================================================================
+# Native Library Build Tasks
+# =============================================================================
+
+def native_lib_ext
+  case RbConfig::CONFIG['host_os']
+  when /darwin/
+    'dylib'
+  else
+    'so'
+  end
+end
+
+namespace :native do
+  desc "Initialize the valkey-glide submodule"
+  task :submodule do
+    puts "Initializing valkey-glide submodule..."
+    sh "git submodule update --init --recursive"
+  end
+
+  desc "Build the native FFI library (release mode)"
+  task build: :submodule do
+    puts "Building native FFI library..."
+    Dir.chdir("valkey-glide/ffi") do
+      sh "cargo build --release"
+    end
+    puts "Native library built successfully!"
+    puts "Location: valkey-glide/ffi/target/release/libglide_ffi.#{native_lib_ext}"
+  end
+
+  desc "Build the native FFI library (debug mode)"
+  task build_debug: :submodule do
+    puts "Building native FFI library (debug)..."
+    Dir.chdir("valkey-glide/ffi") do
+      sh "cargo build"
+    end
+    puts "Native library built successfully!"
+    puts "Location: valkey-glide/ffi/target/debug/libglide_ffi.#{native_lib_ext}"
+  end
+
+  desc "Clean native build artifacts"
+  task :clean do
+    puts "Cleaning native build artifacts..."
+    if Dir.exist?("valkey-glide/ffi")
+      Dir.chdir("valkey-glide/ffi") do
+        sh "cargo clean"
+      end
+    end
+    puts "Clean complete!"
+  end
+
+  desc "Copy built library to lib/valkey/native/{platform}/ for gem packaging"
+  task package: :build do
+    require 'fileutils'
+    require 'rbconfig'
+
+    # Determine platform directory name (matches Rust target triple)
+    os = case RbConfig::CONFIG['host_os']
+         when /darwin/
+           'apple-darwin'
+         when /linux/
+           'unknown-linux-gnu'
+         when /mswin|mingw/
+           'pc-windows-msvc'
+         else
+           abort "Unsupported OS: #{RbConfig::CONFIG['host_os']}"
+         end
+
+    arch = case RbConfig::CONFIG['host_cpu']
+           when /x86_64|amd64/i
+             'x86_64'
+           when /aarch64|arm64/i
+             'aarch64'
+           else
+             abort "Unsupported architecture: #{RbConfig::CONFIG['host_cpu']}"
+           end
+
+    platform_dir = "#{arch}-#{os}"
+    src = "valkey-glide/ffi/target/release/libglide_ffi.#{native_lib_ext}"
+    dest_dir = "lib/valkey/native/#{platform_dir}"
+    dest = "#{dest_dir}/libglide_ffi.#{native_lib_ext}"
+
+    if File.exist?(src)
+      FileUtils.mkdir_p(dest_dir)
+      FileUtils.cp(src, dest)
+      puts "Copied #{src} to #{dest}"
+      puts "Platform: #{platform_dir}"
+    else
+      abort "Native library not found at #{src}. Run 'rake native:build' first."
+    end
+  end
+end
+
+desc "Build the native FFI library"
+task native: "native:build"
+
+# =============================================================================
+# Test Tasks
+# =============================================================================
+
+namespace :test do
+  groups = %i[valkey cluster]
+  groups.each do |group|
+    Rake::TestTask.new(group) do |t|
+      t.libs << "test"
+      # Only add local lib to load path when not testing installed gem
+      t.libs << "lib" unless ENV["TEST_INSTALLED_GEM"]
+      t.test_files = FileList["test/#{group}/**/*_test.rb"]
+      t.options = '-v' if ENV['CI'] || ENV['VERBOSE']
+    end
+  end
+
+  lost_tests = Dir["test/**/*_test.rb"] - groups.map { |g| Dir["test/#{g}/**/*_test.rb"] }.flatten
+  abort "The following test files are in no group:\n#{lost_tests.join("\n")}" unless lost_tests.empty?
+end
+
+task test: ["test:valkey"]
+
+task default: :test

data/examples/README.md

@@ -0,0 +1,55 @@
+# Examples
+
+Runnable examples for Valkey GLIDE Ruby. Requires a Valkey or Redis OSS server unless noted.
+
+## Prerequisites
+
+From the repository root:
+
+```bash
+bin/setup
+```
+
+Run examples with the gem loaded from `lib/`:
+
+```bash
+bundle exec ruby examples/standalone.rb
+```
+
+Or:
+
+```bash
+RUBYOPT="-I$(pwd)/lib" ruby examples/standalone.rb
+```
+
+## Examples
+
+| File | Description | Server |
+|------|-------------|--------|
+| [standalone.rb](./standalone.rb) | Basic connect, SET, GET | Standalone `:6379` |
+| [cluster.rb](./cluster.rb) | Cluster connect, SET, GET | Cluster `:7000`–`:7005` |
+| [pipelining.rb](./pipelining.rb) | Non-atomic pipeline | Standalone `:6379` |
+| [opentelemetry.rb](./opentelemetry.rb) | OTel file exporter + traced commands | Standalone `:6379` |
+| [statistics.rb](./statistics.rb) | Client statistics | Standalone `:6379` |
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `VALKEY_HOST` | `127.0.0.1` | Server host |
+| `VALKEY_PORT` | `6379` | Standalone port |
+| `VALKEY_CLUSTER_PORT` | `7000` | First cluster node port |
+
+## Standalone with Docker
+
+```bash
+docker run -d --name valkey -p 6379:6379 valkey/valkey:8
+bundle exec ruby examples/standalone.rb
+```
+
+## Cluster with Docker
+
+```bash
+docker run -d -p 7000-7005:7000-7005 grokzen/redis-cluster:7.0.15
+bundle exec ruby examples/cluster.rb
+```

data/examples/cluster.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Cluster mode example.
+#
+# Run: bundle exec ruby examples/cluster.rb
+# Requires a 6-node cluster on 127.0.0.1:7000-7005 (see examples/README.md).
+
+require "valkey"
+
+base_port = Integer(ENV.fetch("VALKEY_CLUSTER_PORT", 7000))
+host = ENV.fetch("VALKEY_HOST", "127.0.0.1")
+
+nodes = 6.times.map { |i| { host: host, port: base_port + i } }
+
+client = Valkey.new(nodes: nodes, cluster_mode: true)
+
+puts "PING: #{client.ping}"
+puts "SET: #{client.set('cluster_key', 'cluster_value')}"
+puts "GET: #{client.get('cluster_key')}"
+
+client.del("cluster_key")
+client.close
+
+puts "Done."

data/examples/opentelemetry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# OpenTelemetry example using file exporters (no collector required).
+#
+# Run: bundle exec ruby examples/opentelemetry.rb
+# Traces: /tmp/valkey_ruby_example_traces.json
+# Metrics: /tmp/valkey_ruby_example_metrics.json
+
+require "valkey"
+require "fileutils"
+
+TRACES_FILE = "/tmp/valkey_ruby_example_traces.json"
+METRICS_FILE = "/tmp/valkey_ruby_example_metrics.json"
+
+FileUtils.rm_f(TRACES_FILE)
+FileUtils.rm_f(METRICS_FILE)
+
+Valkey::OpenTelemetry.init(
+  traces: {
+    endpoint: "file://#{TRACES_FILE}",
+    sample_percentage: 100
+  },
+  metrics: {
+    endpoint: "file://#{METRICS_FILE}"
+  },
+  flush_interval_ms: 1000
+)
+
+host = ENV.fetch("VALKEY_HOST", "127.0.0.1")
+port = Integer(ENV.fetch("VALKEY_PORT", 6379))
+
+client = Valkey.new(host: host, port: port)
+
+client.set("otel_key", "otel_value")
+client.get("otel_key")
+client.pipelined do |pipe|
+  pipe.set("otel_pipe_1", "a")
+  pipe.get("otel_pipe_1")
+end
+
+client.del("otel_key", "otel_pipe_1")
+client.close
+
+# Allow exporter flush
+sleep 2
+
+puts "OpenTelemetry initialized: #{Valkey::OpenTelemetry.initialized?}"
+puts "Traces file: #{TRACES_FILE} (#{File.size?(TRACES_FILE) || 0} bytes)"
+puts "Metrics file: #{METRICS_FILE} (#{File.size?(METRICS_FILE) || 0} bytes)"
+puts "Done."

data/examples/pipelining.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Pipeline example — batch commands in one round trip.
+#
+# Run: bundle exec ruby examples/pipelining.rb
+
+require "valkey"
+
+host = ENV.fetch("VALKEY_HOST", "127.0.0.1")
+port = Integer(ENV.fetch("VALKEY_PORT", 6379))
+
+client = Valkey.new(host: host, port: port)
+
+client.del("pipe_counter")
+
+results = client.pipelined do |pipe|
+  pipe.set("pipe_key", "pipe_value")
+  pipe.get("pipe_key")
+  pipe.incr("pipe_counter")
+  pipe.get("pipe_counter")
+end
+
+puts "Pipeline results:"
+results.each_with_index { |r, i| puts "  [#{i}] #{r.inspect}" }
+
+client.del("pipe_key", "pipe_counter")
+client.close
+
+puts "Done."

data/examples/standalone.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Basic standalone Valkey example.
+#
+# Run: bundle exec ruby examples/standalone.rb
+# Requires Valkey/Redis on VALKEY_HOST:VALKEY_PORT (default 127.0.0.1:6379).
+
+require "valkey"
+
+host = ENV.fetch("VALKEY_HOST", "127.0.0.1")
+port = Integer(ENV.fetch("VALKEY_PORT", 6379))
+
+client = Valkey.new(host: host, port: port)
+
+puts "PING: #{client.ping}"
+puts "SET: #{client.set('hello', 'world')}"
+puts "GET: #{client.get('hello')}"
+
+client.del("hello")
+client.close
+
+puts "Done."

data/examples/statistics.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Client statistics example.
+#
+# Run: bundle exec ruby examples/statistics.rb
+
+require "valkey"
+
+host = ENV.fetch("VALKEY_HOST", "127.0.0.1")
+port = Integer(ENV.fetch("VALKEY_PORT", 6379))
+
+client = Valkey.new(host: host, port: port)
+client.set("stats_demo", "1")
+client.get("stats_demo")
+
+stats = client.get_statistics
+
+puts "Client statistics:"
+stats.each { |k, v| puts "  #{k}: #{v}" }
+
+client.del("stats_demo")
+client.close
+
+puts "Done."