valkey-glide-rb 0.9.0 → 0.9.1

data/examples/opentelemetry.rb

@@ -41,10 +41,29 @@ end
 client.del("otel_key", "otel_pipe_1")
 client.close
 
+# Distributed tracing: register a parent_span_context_provider so command spans
+# become children of the app's current trace instead of independent root spans.
+# Here we hand-roll a fake W3C trace context (no dependency on the real
+# opentelemetry-ruby gem); in a real app this would read from
+# ::OpenTelemetry::Trace.current_span.context (see README).
+fake_trace_id = "4bf92f3577b34da6a3ce929d0e0e4736"
+fake_span_id = "00f067aa0ba902b7"
+
+Valkey::OpenTelemetry.set_parent_span_context_provider do
+  { trace_id: fake_trace_id, span_id: fake_span_id, trace_flags: 1, tracestate: nil }
+end
+
+client = Valkey.new(host: host, port: port)
+client.set("otel_traced_key", "value") # span will be a child of fake_trace_id/fake_span_id
+client.close
+
+Valkey::OpenTelemetry.set_parent_span_context_provider(nil)
+
 # 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."
+puts "Done. Inspect #{TRACES_FILE} - the SET span for otel_traced_key should have " \
+     "trace_id=#{fake_trace_id} and parent_span_id=#{fake_span_id}."

data/lib/valkey/bindings.rb

@@ -4,6 +4,23 @@ class Valkey
   module Bindings
     extend FFI::Library
 
+    # Detect whether the current Linux system uses musl libc (e.g., Alpine Linux).
+    # Uses a three-check cascade — any single match is sufficient.
+    def self.musl_libc?
+      return false unless FFI::Platform::OS == "linux"
+
+      # Check 1: RUBY_PLATFORM contains 'musl' (e.g., Alpine-built Ruby)
+      return true if RUBY_PLATFORM.include?("musl")
+
+      # Check 2: /etc/alpine-release exists (Alpine Linux indicator)
+      return true if File.exist?("/etc/alpine-release")
+
+      # Check 3: RbConfig target_os contains 'musl'
+      return true if RbConfig::CONFIG["target_os"].to_s.include?("musl")
+
+      false
+    end
+
     # Determine platform-specific library extension and directory name
     def self.platform_info
       os = if FFI::Platform.mac?
@@ -40,7 +57,7 @@ class Valkey
                      when "darwin"
                        "#{arch}-apple-darwin"
                      when "linux"
-                       "#{arch}-unknown-linux-gnu"
+                       musl_libc? ? "#{arch}-unknown-linux-musl" : "#{arch}-unknown-linux-gnu"
                      when "windows"
                        "#{arch}-pc-windows-msvc"
                      end
@@ -309,6 +326,21 @@ class Valkey
 
     attach_function :create_batch_otel_span, [], :uint64 # returns span pointer (u64) or 0 on failure
 
+    attach_function :create_otel_span_with_trace_context, [
+      :int,    # request_type (RequestType enum value)
+      :string, # trace_id (32-char lowercase hex, or nil for an independent span)
+      :string, # span_id (16-char lowercase hex, or nil for an independent span)
+      :uint8,  # trace_flags
+      :string  # trace_state (W3C tracestate header, or nil)
+    ], :uint64 # returns span pointer (u64); falls back to an independent span on invalid context
+
+    attach_function :create_batch_otel_span_with_trace_context, [
+      :string, # trace_id (32-char lowercase hex, or nil for an independent span)
+      :string, # span_id (16-char lowercase hex, or nil for an independent span)
+      :uint8,  # trace_flags
+      :string  # trace_state (W3C tracestate header, or nil)
+    ], :uint64 # returns span pointer (u64); falls back to an independent batch span on invalid context
+
     attach_function :drop_otel_span, [
       :uint64 # span_ptr to close
     ], :void

data/lib/valkey/commands/cluster_commands.rb

@@ -71,13 +71,30 @@ class Valkey
         send_command(RequestType::CLUSTER_DEL_SLOTS_RANGE, [start_slot, end_slot])
       end
 
+      # Valid modes for CLUSTER FAILOVER: FORCE, TAKEOVER.
+      CLUSTER_FAILOVER_MODES = %i[force takeover].freeze
+
       # Force a failover of the cluster.
       #
-      # @param [String] force force the failover
+      # Must be sent to a replica node. Without a mode, performs a coordinated
+      # failover (the primary is asked to pause clients and hand over). +:force+
+      # promotes the replica without coordinating with the primary (useful when
+      # the primary is unreachable); +:takeover+ promotes it without any cluster
+      # consensus (most aggressive — risks data loss / split brain).
+      #
+      # @param [Symbol, nil] mode optional failover mode: +:force+ or +:takeover+
       # @return [String] `"OK"`
-      def cluster_failover(force = nil)
+      # @raise [ArgumentError] if +mode+ is not nil, +:force+, or +:takeover+
+      # @see https://valkey.io/commands/cluster-failover/
+      def cluster_failover(mode = nil)
         args = []
-        args << "FORCE" if force
+        unless mode.nil?
+          unless CLUSTER_FAILOVER_MODES.include?(mode)
+            raise ArgumentError, "invalid CLUSTER FAILOVER mode #{mode.inspect}: expected :force or :takeover"
+          end
+
+          args << mode.to_s.upcase
+        end
         send_command(RequestType::CLUSTER_FAILOVER, args)
       end
 

data/lib/valkey/commands/connection_commands.rb

@@ -94,7 +94,7 @@ class Valkey
       #   client(:set_name, "my_app")  # => "OK"
       #   client(:list)                # => [{"id" => "1", ...}, ...]
       def client(subcommand, *args)
-        send("client_#{subcommand.to_s.downcase}", *args)
+        public_send("client_#{subcommand.to_s.downcase}", *args)
       end
 
       # Get the current client's ID.
@@ -136,8 +136,10 @@ class Valkey
 
         send_command(RequestType::CLIENT_LIST, args) do |reply|
           reply.lines.map do |line|
-            entries = line.chomp.split(/[ =]/)
-            entries.each_slice(2).to_a.to_h
+            line.chomp.split.each_with_object({}) do |pair, hash|
+              key, value = pair.split("=", 2)
+              hash[key] = value || ""
+            end
           end
         end
       end
@@ -290,6 +292,12 @@ class Valkey
         send_command(RequestType::CLIENT_NO_TOUCH, [mode.to_s.upcase])
       end
 
+      # Client-side caching commands are intentionally private.
+      #
+      # GLIDE's managed client-side caching is not yet implemented in the Ruby client
+      # These commands are not meant to be called directly and will be kept private.
+      private :client_tracking, :client_caching, :client_tracking_info, :client_getredir
+
       private
 
       def build_client_tracking_args(options)
@@ -299,8 +307,9 @@ class Valkey
           when :redirect
             args << "REDIRECT" << value.to_s
           when :prefix
-            args << "PREFIX"
-            Array(value).each { |prefix| args << prefix }
+            # Valkey requires the PREFIX keyword before each prefix value,
+            # e.g. PREFIX foo PREFIX bar.
+            Array(value).each { |prefix| args << "PREFIX" << prefix }
           when :bcast
             args << "BCAST" if value
           when :optin

data/lib/valkey/commands/generic_commands.rb

@@ -9,6 +9,11 @@ class Valkey
     module GenericCommands
       # Scan the keyspace
       #
+      # @note Standalone mode only. glide-core has no defined default route for
+      #   SCAN in cluster mode, so each call may land on a different node with
+      #   no cursor continuity between them — results are undefined (missed or
+      #   duplicated keys) rather than merely partial.
+      #
       # @example Retrieve the first batch of keys
       #   valkey.scan(0)
       #     # => ["4", ["key:21", "key:47", "key:42"]]
@@ -33,6 +38,9 @@ class Valkey
 
       # Scan the keyspace
       #
+      # @note Standalone mode only. Built on {#scan}, which has undefined
+      #   routing behavior in cluster mode (see its note).
+      #
       # @example Retrieve all of the keys (with possible duplicates)
       #   valkey.scan_each.to_a
       #     # => ["key:21", "key:47", "key:42"]
@@ -52,16 +60,16 @@ class Valkey
       #
       # @return [Enumerator] an enumerator for all found keys
       #
-      # def scan_each(**options, &block)
-      #   return to_enum(:scan_each, **options) unless block_given?
-      #
-      #   cursor = 0
-      #   loop do
-      #     cursor, keys = scan(cursor, **options)
-      #     keys.each(&block)
-      #     break if cursor == "0"
-      #   end
-      # end
+      def scan_each(**options, &block)
+        return to_enum(:scan_each, **options) unless block_given?
+
+        cursor = 0
+        loop do
+          cursor, keys = scan(cursor, **options)
+          keys.each(&block)
+          break if cursor == "0"
+        end
+      end
 
       # Remove the expiration from a key.
       #
@@ -520,6 +528,98 @@ class Valkey
 
         send_command(command, args, &block)
       end
+
+      # Send any command as plain arguments and get the raw reply back, with no
+      # per-command method needed. Escape hatch for commands without a dedicated
+      # method yet, matching `redis-client`'s `#call`.
+      #
+      # @example Basic dispatch
+      #   valkey.call("SET", "mykey", "value")
+      #     # => "OK"
+      # @example Integers/Floats auto-stringify
+      #   valkey.call("SET", "mykey", 42)
+      #     # equivalent to call("SET", "mykey", "42")
+      # @example Arrays flatten
+      #   valkey.call("LPUSH", "list", [1, 2, 3])
+      #     # equivalent to call("LPUSH", "list", "1", "2", "3")
+      # @example Hashes flatten to alternating key/value
+      #   valkey.call("HMSET", "hash", { "foo" => "1" })
+      #     # equivalent to call("HMSET", "hash", "foo", "1")
+      # @example Keyword args become command flags; falsy/nil flags are dropped
+      #   valkey.call("SET", "k", "v", nx: true, ex: 60)
+      #     # equivalent to call("SET", "k", "v", "NX", "EX", "60")
+      #
+      # @param [Array<String, Integer, Float, Array, Hash>] argv command name and its arguments
+      # @param [Hash] kwargs trailing command flags; truthy values emit the upcased flag name,
+      #   non-boolean values also emit the stringified value; falsy/nil values are dropped
+      # @return [Object] the raw reply, with no type-casting based on the command name
+      #
+      # @see https://valkey.io/commands/
+      def call(*argv, **kwargs)
+        send_command(RequestType::CUSTOM_COMMAND, flatten_call_args(argv).concat(call_flags(kwargs)))
+      end
+
+      # Send any command as a single Array of arguments and get the raw reply back.
+      # Same as {#call} but takes the whole command as one Array instead of splatted
+      # args, useful when the command is built dynamically. Matches `redis-client`'s
+      # `#call_v` — no keyword flags.
+      #
+      # @example
+      #   valkey.call_v(["MGET"] + keys)
+      #
+      # @param [Array<String, Integer, Float, Array, Hash>] argv command name and its arguments
+      # @return [Object] the raw reply, with no type-casting based on the command name
+      #
+      # @see https://valkey.io/commands/
+      def call_v(argv)
+        send_command(RequestType::CUSTOM_COMMAND, flatten_call_args(argv))
+      end
+
+      private
+
+      # Flattens Arrays and Hashes (to alternating key/value) and stringifies
+      # Integers/Floats, matching `redis-client`'s documented `#call`/`#call_v` behavior.
+      #
+      # @example
+      #   flatten_call_args(["CMD", [1, [2, 3]], { "a" => 1, "b" => [2, 3] }])
+      #   # => ["CMD", "1", "2", "3", "a", "1", "b", "2", "3"]
+      def flatten_call_args(args)
+        acc = []
+        # Ruby doesn't have a built in queue, so we use a reversed stack instead
+        # Insertions into the stack needs to be reversed to maintain the Queue LIFO
+        # ordering
+        stack = args.reverse
+
+        until stack.empty?
+          arg = stack.pop
+          case arg
+          when Array
+            stack.concat(arg.reverse)
+          when Hash
+            arg.to_a.reverse_each { |pair| stack.concat(pair.reverse) }
+          else
+            acc << arg.to_s
+          end
+        end
+
+        acc
+      end
+
+      # Converts `call`'s **kwargs into trailing command flags: a truthy value emits
+      # the upcased flag name, and a non-boolean truthy value also emits the
+      # stringified value. Falsy/nil values are dropped entirely, not stringified.
+      #
+      # @example
+      #   call_flags(nx: true, ex: 60, cond: false, ttl: nil)
+      #   # => ["NX", "EX", "60"]
+      def call_flags(kwargs)
+        kwargs.each_with_object([]) do |(name, value), flags|
+          next unless value
+
+          flags << name.to_s.upcase
+          flags << value.to_s unless value == true
+        end
+      end
     end
   end
 end

data/lib/valkey/commands/server_commands.rb

@@ -499,13 +499,19 @@ class Valkey
       # @see https://valkey.io/commands/failover/
       def failover(to: nil, force: false, abort: false, timeout: nil)
         args = []
-        if to
-          host, port = to.split
-          args << "TO" << host << port
+        if abort
+          # ABORT is mutually exclusive: cancels an ongoing failover and
+          # ignores any other arguments (matches the core GLIDE clients).
+          args << "ABORT"
+        else
+          if to
+            host, port = to.split
+            args << "TO" << host << port
+            # FORCE is only valid in combination with TO.
+            args << "FORCE" if force
+          end
+          args << "TIMEOUT" << timeout.to_s if timeout
         end
-        args << "FORCE" if force
-        args << "ABORT" if abort
-        args << "TIMEOUT" << timeout.to_s if timeout
         send_command(RequestType::FAIL_OVER, args)
       end
 

data/lib/valkey/opentelemetry.rb

@@ -44,6 +44,7 @@ class Valkey
   module OpenTelemetry
     @initialized = false
     @config = nil
+    @parent_span_context_provider = nil
 
     class << self
       # Initialize OpenTelemetry in the Valkey GLIDE core.
@@ -67,12 +68,16 @@ class Valkey
       # @param flush_interval_ms [Integer, nil] Flush interval in milliseconds (default: 5000)
       #   Must be a positive integer
       #
+      # @param parent_span_context_provider [Proc, nil] Optional callable returning a Hash describing
+      #   the current application span context (see {set_parent_span_context_provider}). Equivalent to
+      #   calling {set_parent_span_context_provider} separately; provided here for convenience.
+      #
       # @raise [ArgumentError] if neither traces nor metrics is provided
       # @raise [ArgumentError] if sample_percentage is not between 0-100
       # @raise [RuntimeError] if initialization fails
       #
       # @return [void]
-      def init(traces: nil, metrics: nil, flush_interval_ms: nil)
+      def init(traces: nil, metrics: nil, flush_interval_ms: nil, parent_span_context_provider: nil)
         if @initialized
           warn "Valkey::OpenTelemetry already initialized - ignoring new configuration"
           return
@@ -106,6 +111,7 @@ class Valkey
 
         @initialized = true
         @config = { traces: traces, metrics: metrics, flush_interval_ms: flush_interval_ms }
+        set_parent_span_context_provider(parent_span_context_provider) if parent_span_context_provider
 
         puts "✅ Valkey OpenTelemetry initialized successfully"
         puts "   Traces: #{traces ? traces[:endpoint] : 'disabled'}"
@@ -135,16 +141,88 @@ class Valkey
       # @return [Hash, nil] the configuration hash or nil if not initialized
       attr_reader :config
 
+      # Register a callable that returns the current application span context, so that
+      # spans created for Valkey commands become children of it instead of independent
+      # root spans. This is how distributed tracing context (e.g. from the Rails request
+      # span) is propagated into the native OpenTelemetry spans created for each command.
+      #
+      # @param callable [Proc, nil] Called with no arguments before each command. Must return
+      #   either nil (no active context - the command gets an independent span) or a Hash with:
+      #   - :trace_id [String] 32-character lowercase hex trace ID
+      #   - :span_id [String] 16-character lowercase hex span ID
+      #   - :trace_flags [Integer] 0-255
+      #   - :tracestate [String, nil] W3C tracestate header, optional
+      #   Pass nil (and no block) to clear a previously registered provider.
+      #
+      # @example
+      #   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
+      #
+      # @return [void]
+      def set_parent_span_context_provider(callable = nil, &block)
+        @parent_span_context_provider = block || callable
+      end
+
+      # Invoke the registered parent-span-context provider (if any) and return a validated
+      # context Hash, or nil if no provider is registered, the provider returned nil, the
+      # provider raised, or the returned context failed validation.
+      #
+      # @return [Hash, nil]
+      def parent_span_context
+        return nil unless @parent_span_context_provider
+
+        ctx = @parent_span_context_provider.call
+        return nil if ctx.nil?
+
+        validate_parent_span_context!(ctx)
+        ctx
+      rescue StandardError => e
+        warn "Valkey::OpenTelemetry parent_span_context_provider failed: #{e.message}"
+        nil
+      end
+
       # Reset initialization state (for testing only).
       #
       # @api private
       def reset!
         @initialized = false
         @config = nil
+        @parent_span_context_provider = nil
       end
 
       private
 
+      def validate_parent_span_context!(ctx)
+        raise ArgumentError, "parent span context must be a Hash, got: #{ctx.class}" unless ctx.is_a?(Hash)
+
+        unless ctx[:trace_id].is_a?(String) && ctx[:trace_id].match?(/\A[0-9a-f]{32}\z/)
+          raise ArgumentError, "trace_id must be a 32-character lowercase hex string, got: #{ctx[:trace_id].inspect}"
+        end
+
+        unless ctx[:span_id].is_a?(String) && ctx[:span_id].match?(/\A[0-9a-f]{16}\z/)
+          raise ArgumentError, "span_id must be a 16-character lowercase hex string, got: #{ctx[:span_id].inspect}"
+        end
+
+        trace_flags = ctx[:trace_flags]
+        unless trace_flags.is_a?(Integer) && trace_flags >= 0 && trace_flags <= 255
+          raise ArgumentError, "trace_flags must be an integer between 0 and 255, got: #{trace_flags.inspect}"
+        end
+
+        tracestate = ctx[:tracestate]
+        return if tracestate.nil? || tracestate.is_a?(String)
+
+        raise ArgumentError, "tracestate must be a String or nil, got: #{tracestate.class}"
+      end
+
       def build_config(traces, metrics, flush_interval_ms)
         config_struct = Bindings::OpenTelemetryConfig.new
 

data/lib/valkey/read_from.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Valkey
+  #
+  # this module defines constants for the `read_from:` connection option.
+  # Each constant is the canonical GLIDE string for that read-routing strategy,
+  # matching the RequestType/ResponseType constant modules' convention in this
+  # gem. Ruby symbols (`:prefer_replica`) and the exact-match strings
+  # (`"PreferReplica"`) are still accepted directly by `Valkey.new` -- these
+  # constants are purely an additional, IDE-completion-friendly way to write
+  # the same values, not a new validation mechanism.
+  #
+  module ReadFrom
+    PRIMARY = "Primary"
+    PREFER_REPLICA = "PreferReplica"
+    AZ_AFFINITY = "AZAffinity"
+    AZ_AFFINITY_REPLICAS_AND_PRIMARY = "AZAffinityReplicasAndPrimary"
+
+    # "LowestLatency" is a valid GLIDE value but not yet usable via the vendored
+    # native library (panics in ConnectionRequest::from, see types.rs) -- not
+    # defined as a constant here since it can't work today, though passing the
+    # raw string through directly is still forwarded to the core unchanged.
+  end
+end

data/lib/valkey/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Valkey
-  VERSION = "0.9.0"
+  VERSION = "0.9.1"
 end