valkey-glide-rb 0.9.0.pre.rc1 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d4051f6e0adf4e55cc77297e535a6ef123bcbcdf0752d45e177a24b2517d586
-  data.tar.gz: 75ef28d6321af7dc452850e439a507e3dc5664650a590ae9a8a8502cabc2b401
+  metadata.gz: a8824baa9eb08b0496a2428dd1a0c4997d9716810ba75d607bbadd0c40a99dde
+  data.tar.gz: 23704fe50125575ad927860cabf0cae7f7ed9d915f651d049b608ca809fda2e9
 SHA512:
-  metadata.gz: b176821fa6b906029845a4464dab43e190fddbb6fdbd1beb3308f942f9ea74aac3faa2dd95c29f182c878608a1ac189f394fcc9a47b32aef3e60cb993df2f6de
-  data.tar.gz: 5a54e58651d9192cf5c53d570482d5bcd5b03039f252ee64f6c91e041f7848804241e0d3fcd6850c8f5b20fed4f2fd1d9add8cbce47367195a37a6d4f0a9ef33
+  metadata.gz: 62a9bd00a4bc4f1cde9da036e86703a504f7a7ef355ffce8f254c5cf46ebb103c88242e20255a14d7adee3fbf3089db584c8703c5a5f89f9a7c0e04863254abb
+  data.tar.gz: 7a7b9672f5cd499878aef940198b3f48e58fff82d9a8468eb12ab3abc57446dd905326c44aa33145926fd1c28af226817937ac9cb3b69717b7f1d07b08e3fc0f

data/.rubocop.yml

@@ -66,4 +66,5 @@ Metrics/ModuleLength:
     - 'lib/valkey/utils.rb'
     - 'lib/valkey/commands/*.rb'
     - 'lib/valkey/bindings.rb'
+    - 'lib/valkey/opentelemetry.rb'
     - 'test/**/*.rb'

data/AGENTS.md

@@ -35,8 +35,8 @@ This is the **Ruby client** for Valkey GLIDE, published as the `valkey-rb` gem.
 **Supported Platforms:**
 
 - Linux: Ubuntu 20+, Amazon Linux 2/2023 (x86_64, aarch64)
+- Alpine Linux 3.18+ (x86_64, aarch64) — musl libc
 - macOS: 13.7+ (x86_64), 14.7+ (aarch64)
-- **Note:** Alpine Linux / MUSL is **not** supported
 
 **Ruby Versions:** 2.6, 2.7, 3.0, 3.1, 3.2, 3.3, 3.4, JRuby (CI matrix)
 
@@ -54,12 +54,12 @@ bin/setup                              # bundle install
 bundle exec rubocop
 
 # Testing
-bundle exec rake test                  # standalone (default)
-bundle exec rake test:valkey           # standalone explicitly
-bundle exec rake test:cluster          # cluster (needs nodes 7000-7005)
+bundle exec rake test                  # standalone + cluster
+bundle exec rake test:standalone       # standalone only
+bundle exec rake test:cluster          # cluster only (needs nodes 7000-7005)
 
 # Verbose / CI mode
-CI=1 bundle exec rake test:valkey
+CI=1 bundle exec rake test:standalone
 
 # Console
 bundle exec bin/console
@@ -72,7 +72,7 @@ bundle exec bin/console
 bundle exec ruby test/valkey/string_commands_test.rb
 
 # Run with custom port
-VALKEY_PORT=6379 TIMEOUT=10 bundle exec rake test:valkey
+VALKEY_PORT=6379 TIMEOUT=10 bundle exec rake test:standalone
 
 # Load gem from lib/ without install
 RUBYOPT="-I$(pwd)/lib" ruby -r valkey -e 'p Valkey.new.ping'
@@ -82,7 +82,7 @@ RUBYOPT="-I$(pwd)/lib" ruby -r valkey -e 'p Valkey.new.ping'
 
 | Suite | Server requirement |
 |-------|-------------------|
-| `test:valkey` | Standalone Valkey/Redis on `localhost:6379` (DB 15) |
+| `test:standalone` | Standalone Valkey/Redis on `localhost:6379` (DB 15) |
 | `test:cluster` | 6-node cluster on `127.0.0.1:7000`–`7005` |
 | SSL tests | TLS Valkey on port `6380` + certs in `test/fixtures/ssl/` |
 | Module tests | JSON, Bloom, Search modules loaded (see CI workflow) |
@@ -191,7 +191,7 @@ valkey-glide-ruby/
 ## Quality Gates (Agent Checklist)
 
 - [ ] `bundle exec rubocop` passes
-- [ ] `bundle exec rake test:valkey` passes (with Valkey running)
+- [ ] `bundle exec rake test:standalone` passes (with Valkey running)
 - [ ] `bundle exec rake test:cluster` passes (if cluster commands touched)
 - [ ] New commands have tests in `test/valkey/` and lint coverage where applicable
 - [ ] `RequestType` matches glide-core enum

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## Pending
+
+### Changes
+
+* Ruby: Add Alpine Linux (musl libc) support for x86_64 and aarch64 — runtime detection of musl libc, CI/CD pipeline for native builds, and prebuilt `libglide_ffi.so` for musl targets ([#143](https://github.com/valkey-io/valkey-glide-ruby/pull/143))
+* Ruby: Add distributed tracing support — `Valkey::OpenTelemetry.set_parent_span_context_provider` (and `init(parent_span_context_provider:)`) let an app propagate its current W3C trace context into command/pipeline spans, so they become children of the app's trace instead of independent root spans, matching the Node.js client's `parentSpanContextProvider` behavior.

data/CLAUDE.md

@@ -27,14 +27,14 @@ Valkey GLIDE Ruby (`valkey-rb`) is the official Ruby binding for Valkey and Redi
 
 ### Before Task Completion
 
-- Tests cover the change and pass (`bundle exec rake test:valkey` at minimum)
+- Tests cover the change and pass (`bundle exec rake test:standalone` at minimum)
 - `bundle exec rubocop` passes for changed Ruby files
 - If FFI binary updated, smoke-test: `Valkey.new.ping` on target OS
 
 ### Before Push
 
 - `git pull --rebase` on your base branch; resolve conflicts
-- Run tests for relevant scope (`test:valkey` and/or `test:cluster`)
+- Run tests for relevant scope (`test:standalone` and/or `test:cluster`)
 
 ### Before PR Creation/Update
 
@@ -108,7 +108,7 @@ When working on a feature, read these paths first:
 ```bash
 bin/setup
 bundle exec rubocop
-bundle exec rake test:valkey      # needs localhost:6379
+bundle exec rake test:standalone  # needs localhost:6379
 bundle exec rake test:cluster     # needs cluster 7000-7005
 ```
 

data/CONTRIBUTING.md

@@ -30,7 +30,7 @@ For issues that affect the shared Rust core or other language clients, consider
 3. Run local checks (see [DEVELOPER.md](./DEVELOPER.md)):
    ```bash
    bundle exec rubocop
-   bundle exec rake test:valkey    # standalone — requires Valkey on :6379
+   bundle exec rake test:standalone    # standalone — requires Valkey on :6379
    bundle exec rake test:cluster   # if cluster-related — requires nodes :7000–:7005
    ```
 4. Commit with **DCO sign-off** and **conventional commits**:
@@ -102,7 +102,7 @@ This project follows the [Amazon Open Source Code of Conduct](https://aws.github
 
 ## Security
 
-Report security vulnerabilities via [valkey-glide SECURITY.md](https://github.com/valkey-io/valkey-glide/blob/main/SECURITY.md).
+See [SECURITY.md](https://github.com/valkey-io/.github/blob/main/SECURITY.md).
 
 ## Licensing
 

data/DEVELOPER.md

@@ -47,7 +47,7 @@ valkey-glide-ruby/
 │   └── cd.yml                    # Build and publish gem
 ├── valkey.gemspec
 ├── Gemfile
-└── Rakefile                      # test:valkey, test:cluster, native:build
+└── Rakefile                      # test:standalone, test:cluster, native:build
 ```
 
 ## Prerequisites
@@ -58,7 +58,7 @@ valkey-glide-ruby/
 - **Bundler**
 - **git**
 - **Valkey** or Redis OSS (for integration tests)
-- **Docker** (optional; matches CI setup)
+- **Docker** (optional; only needed for module tests with `valkey-bundle` image)
 
 To **build** the native FFI library from source:
 
@@ -188,21 +188,25 @@ Default test configuration (see `test/test_helper.rb`):
 |----------|---------|---------|
 | `VALKEY_PORT` | `6379` | Plain TCP |
 | `VALKEY_SSL_PORT` | `6380` | TLS (optional) |
+| `TLS_CERT_DIR` | `valkey-glide/utils/tls_crts` | Path to TLS certs (set by CI) |
 | `TIMEOUT` | `5.0` | Client timeout |
 | DB | `15` | Test database |
 
 ```bash
-# Example: Docker standalone (matches CI)
-docker run -d --name valkey-test -p 6379:6379 valkey/valkey:8 \
-  valkey-server --enable-module-command yes
+# Preferred: use cluster_manager.py (same as CI and all other GLIDE clients)
+python3 valkey-glide/utils/cluster_manager.py start -r 0 -p 6379 --prefix standalone
+
+# Alternative: Docker standalone
+docker run -d --name valkey-test -p 6379:6379 valkey/valkey:8 valkey-server
 ```
 
 ### Start Valkey Cluster
 
-Cluster tests expect six nodes on `127.0.0.1:7000`–`7005`. CI uses `grokzen/redis-cluster:7.0.15`.
+Cluster tests auto-start via `cluster_manager.py` (the `TestCluster` class handles lifecycle).
+You can also start manually:
 
 ```bash
-docker run -d --name redis-cluster -p 7000-7005:7000-7005 grokzen/redis-cluster:7.0.15
+python3 valkey-glide/utils/cluster_manager.py start --cluster-mode --prefix cluster
 ```
 
 ### Run Tests
@@ -211,39 +215,51 @@ docker run -d --name redis-cluster -p 7000-7005:7000-7005 grokzen/redis-cluster:
 # All default (standalone) tests
 bundle exec rake test
 # or
-bundle exec rake test:valkey
+bundle exec rake test:standalone
 
 # Cluster tests only
 bundle exec rake test:cluster
 
 # Verbose output (also enabled when CI=1)
-CI=1 bundle exec rake test:valkey
+CI=1 bundle exec rake test:standalone
 ```
 
 ### SSL Tests
 
-Generate test certificates:
+The preferred approach (matching CI and all other GLIDE clients) uses `cluster_manager.py`:
 
 ```bash
-ruby test/fixtures/ssl/generate_certs.rb
+# Start a TLS-only server on port 6380 (generates certs in valkey-glide/utils/tls_crts/)
+python3 valkey-glide/utils/cluster_manager.py --tls start -r 0 -p 6380 --prefix tls-standalone
+
+# Point tests at the generated certs
+export TLS_CERT_DIR=$(pwd)/valkey-glide/utils/tls_crts
+
+# Run tests
+bundle exec rake test:standalone
+
+# Stop the TLS server
+python3 valkey-glide/utils/cluster_manager.py --tls stop --prefix tls-standalone
 ```
 
-Start TLS Valkey on port 6380 (see `.github/workflows/CI.yml` for a full Docker example).
+Alternatively, for local development without Python, generate certs and start manually:
 
-### Module Tests (JSON, Bloom, Search)
+```bash
+ruby test/fixtures/ssl/generate_certs.rb
+# Then start a TLS Valkey server on port 6380 using those certs
+```
 
-CI copies prebuilt modules into `test/fixtures/`:
+### Module Tests (JSON, Bloom, Search)
 
-- `redisjson.so` — JSON commands
-- `redisbloom.so` — Bloom filters
-- `redisearch.so` — Vector / FT commands
+CI uses the shared `start-valkey-docker` action with `valkey/valkey-bundle:9.1` (modules pre-loaded).
+Tests connect via `STANDALONE_ENDPOINTS` env var.
 
 Load modules when starting Valkey if you run module-specific tests locally.
 
 ### Environment Overrides
 
 ```bash
-VALKEY_PORT=6379 TIMEOUT=10 bundle exec rake test:valkey
+VALKEY_PORT=6379 TIMEOUT=10 bundle exec rake test:standalone
 ```
 
 ## Linters
@@ -427,7 +443,7 @@ ruby -e "require 'valkey'; c = Valkey.new; puts c.ping; c.close"
 | `LoadError` / FFI library not found | Confirm `lib/valkey/libglide_ffi.{so,dylib}` exists and matches your OS/arch. |
 | Wrong architecture after FFI rebuild | Rebuild `glide-ffi` on the target platform; do not copy Linux `.so` to macOS. |
 | Cluster tests flaky | Wait for `cluster_state:ok`; increase `TIMEOUT` env var. |
-| SSL test failures | Regenerate certs: `ruby test/fixtures/ssl/generate_certs.rb`. |
+| SSL test failures | Use `cluster_manager.py --tls` (see SSL Tests above), or regenerate local certs: `ruby test/fixtures/ssl/generate_certs.rb`. |
 | Pipeline / MULTI crashes | Transaction commands in `pipelined` use sequential fallback by design. |
 
 ## Recommended Editor Extensions

data/README.md

@@ -36,8 +36,7 @@ The release of Valkey GLIDE Ruby was tested on the following platforms:
 
 - 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.
+- Alpine Linux 3.18+ (x86_64 and arm64/aarch64) — musl libc
 
 **macOS:**
 
@@ -137,6 +136,45 @@ end
 
 > **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.
 
+### Generic Command Dispatch (`call` / `call_v`)
+
+Not every command has a dedicated method yet. `call`/`call_v` are the escape hatch — send any
+command as plain arguments and get the raw reply back, matching `redis-client`'s `#call`/`#call_v`:
+
+```ruby
+client.call("SET", "mykey", "value")
+# => "OK"
+
+client.call_v(["MGET"] + keys)
+```
+
+`call`/`call_v` apply the same argument coercion as `redis-client`:
+
+```ruby
+# Integers/Floats auto-stringify
+client.call("SET", "mykey", 42)
+# equivalent to call("SET", "mykey", "42")
+
+# Arrays flatten (including nested arrays)
+client.call("LPUSH", "list", [1, 2, 3])
+# equivalent to call("LPUSH", "list", "1", "2", "3")
+
+# Hashes flatten to alternating key/value
+client.call("HMSET", "hash", { "foo" => "1" })
+# equivalent to call("HMSET", "hash", "foo", "1")
+
+# Keyword args become trailing command flags (call only, not call_v):
+# a truthy value emits the upcased flag name; a non-boolean value also emits
+# the stringified value. Falsy/nil values are dropped entirely, not stringified.
+client.call("SET", "k", "v", nx: true, ex: 60)
+# equivalent to call("SET", "k", "v", "NX", "EX", "60")
+client.call("SET", "k", "v", nx: false, ex: nil)
+# equivalent to call("SET", "k", "v")
+```
+
+`call_v` takes the whole command as a single Array (no keyword flags) — useful when the command is
+built dynamically. Both return the raw reply with no type-casting based on the command name.
+
 ### Connection Options (redis-rb compatible)
 
 | Option | Description |
@@ -153,6 +191,11 @@ end
 | `protocol` | `:resp2` (default) or `:resp3` |
 | `client_name` | `CLIENT SETNAME` value |
 | `reconnect_attempts`, `reconnect_delay`, `reconnect_delay_max` | Connection retry strategy |
+| `read_from` *(GLIDE-native)* | Read routing: `:primary`, `:prefer_replica`, `:az_affinity`, `:az_affinity_replicas_and_primary` symbols, the exact-match GLIDE strings (e.g. `"PreferReplica"`), or the `Valkey::ReadFrom::*` constants (e.g. `Valkey::ReadFrom::PREFER_REPLICA`). `:az_affinity`/`:az_affinity_replicas_and_primary` require `client_az` to also be set. `LowestLatency` is a valid GLIDE value but not yet usable via the vendored native library. |
+| `client_az` *(GLIDE-native)* | Availability-zone identifier for `:az_affinity` / `:az_affinity_replicas_and_primary` routing (e.g. `"us-west-2a"`) |
+| `inflight_requests_limit` *(GLIDE-native)* | Maximum concurrent in-flight requests (non-negative integer) |
+| `lazy_connect` *(GLIDE-native)* | Delay the actual connection until the first command is sent |
+| `periodic_checks` *(GLIDE-native)* | Cluster topology health checks: `{ manual_interval: { duration_in_sec: N } }` or `{ disabled: true }`. Accepted (as a no-op) on standalone connections. |
 
 ```ruby
 client = Valkey.new(
@@ -195,6 +238,50 @@ client.set("key", "value")  # traced when sampling applies
 
 OpenTelemetry can only be initialized **once per process**. Spans are created in the FFI layer when sampling is enabled.
 
+### Distributed tracing (parent context propagation)
+
+By default, every command span is an independent root span — it doesn't nest under your
+application's request trace. To fix that, register a `parent_span_context_provider`: a
+callable invoked before every command that returns the current W3C trace context (or `nil`
+when there isn't one). When it returns a valid context, the command/pipeline span is created
+as a **child** of it instead of an independent span.
+
+```ruby
+require "valkey"
+require "opentelemetry/sdk" # if your app uses the real opentelemetry-ruby gem
+
+Valkey::OpenTelemetry.init(
+  traces: { endpoint: "http://localhost:4318/v1/traces", sample_percentage: 10 }
+)
+
+Valkey::OpenTelemetry.set_parent_span_context_provider do
+  span = ::OpenTelemetry::Trace.current_span
+  next nil unless span.context.valid?
+
+  {
+    trace_id: span.context.hex_trace_id,
+    span_id: span.context.hex_span_id,
+    trace_flags: span.context.trace_flags.sampled? ? 1 : 0,
+    tracestate: span.context.tracestate.to_s
+  }
+end
+```
+
+The provider must return either `nil` or a Hash with `:trace_id` (32-char lowercase hex),
+`:span_id` (16-char lowercase hex), `:trace_flags` (Integer 0-255), and `:tracestate`
+(String or `nil`). Anything else is rejected with a warning and treated as `nil` — a broken
+provider degrades to independent root spans, it never raises into your command path.
+
+You can also pass `parent_span_context_provider:` directly to `init(...)` instead of calling
+`set_parent_span_context_provider` separately.
+
+**Note on the `OpenTelemetry` constant name:** `Valkey::OpenTelemetry` (this gem's module) and
+the real `opentelemetry-ruby` gem's top-level `::OpenTelemetry` module are unrelated constants
+and don't collide. But if you write a provider block from code that's lexically nested inside
+`Valkey` (uncommon for typical app-level code), a bare `OpenTelemetry::Trace` reference would
+resolve to `Valkey::OpenTelemetry::Trace` (undefined) instead of the real gem — always use the
+leading-`::` form, `::OpenTelemetry::Trace`, as in the example above.
+
 ## Examples
 
 Runnable examples are in [examples/](./examples/):

data/Rakefile

@@ -29,7 +29,10 @@ namespace :native do
   task build: :submodule do
     puts "Building native FFI library..."
     Dir.chdir("valkey-glide/ffi") do
-      sh "cargo build --release"
+      # Set GLIDE_NAME to identify this as the Ruby client in CLIENT SETINFO
+      # GLIDE_VERSION is set from lib/valkey/version.rb
+      version = File.read("../../lib/valkey/version.rb")[/VERSION = "([^"]+)"/, 1] || "unknown"
+      sh({ "GLIDE_NAME" => "GlideRuby", "GLIDE_VERSION" => version }, "cargo build --release")
     end
     puts "Native library built successfully!"
     puts "Location: valkey-glide/ffi/target/release/libglide_ffi.#{native_lib_ext}"
@@ -39,7 +42,9 @@ namespace :native do
   task build_debug: :submodule do
     puts "Building native FFI library (debug)..."
     Dir.chdir("valkey-glide/ffi") do
-      sh "cargo build"
+      # Set GLIDE_NAME to identify this as the Ruby client in CLIENT SETINFO
+      version = File.read("../../lib/valkey/version.rb")[/VERSION = "([^"]+)"/, 1] || "unknown"
+      sh({ "GLIDE_NAME" => "GlideRuby", "GLIDE_VERSION" => version }, "cargo build")
     end
     puts "Native library built successfully!"
     puts "Location: valkey-glide/ffi/target/debug/libglide_ffi.#{native_lib_ext}"
@@ -106,7 +111,7 @@ task native: "native:build"
 # =============================================================================
 
 namespace :test do
-  groups = %i[valkey cluster]
+  groups = %i[standalone cluster]
   groups.each do |group|
     Rake::TestTask.new(group) do |t|
       t.libs << "test"
@@ -117,10 +122,15 @@ namespace :test do
     end
   end
 
-  lost_tests = Dir["test/**/*_test.rb"] - groups.map { |g| Dir["test/#{g}/**/*_test.rb"] }.flatten
+  # Exclude module directories (valkey/, lint/) from lost_tests check
+  # These contain reusable test modules, not standalone test files
+  module_dirs = %w[valkey lint]
+  lost_tests = Dir["test/**/*_test.rb"] -
+               groups.map { |g| Dir["test/#{g}/**/*_test.rb"] }.flatten -
+               module_dirs.map { |d| Dir["test/#{d}/**/*_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 test: ["test:standalone", "test:cluster"]
 
 task default: :test