valkey-glide-rb 0.9.0 → 0.9.2

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/route.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+class Valkey
+  # Represents a cluster routing directive. Passed as `route:` to commands
+  # that support explicit cluster routing (no-key commands like DBSIZE, INFO,
+  # PING, FLUSHALL, FUNCTION_*, etc.).
+  #
+  # When `route:` is provided the command response type depends on the route:
+  # single-node routes return the value directly, multi-node routes return a
+  # Hash of `"host:port" => value`.
+  #
+  # @example
+  #   client.dbsize(route: Valkey::Route.all_primaries)
+  #   client.ping(route: Valkey::Route.random)
+  #   client.info(route: Valkey::Route.all_nodes)
+  #
+  # @see https://valkey.io/topics/cluster-spec
+  class Route
+    class << self
+      # Route to all nodes (primaries + replicas).
+      # @note Don't use with write commands — they could be routed to replicas and fail.
+      # @return [Route]
+      def all_nodes
+        new(:all_nodes)
+      end
+
+      # Route to all primary nodes.
+      # @return [Route]
+      def all_primaries
+        new(:all_primaries)
+      end
+
+      # Route to a random node.
+      # @note Don't use with write commands — they could be randomly routed to a replica and fail.
+      # @return [Route]
+      def random
+        new(:random)
+      end
+
+      # Route to a specific slot by ID.
+      # @param slot_id [Integer] slot number (0–16383)
+      # @param slot_type [Symbol] :primary or :replica
+      # @return [Route]
+      def slot_id(slot_id, slot_type = :primary)
+        new(:slot_id, slot_id: slot_id.to_i, slot_type: slot_type)
+      end
+
+      # Route to the node owning a specific key's slot.
+      # @param key [String] the key whose slot determines routing
+      # @param slot_type [Symbol] :primary or :replica
+      # @return [Route]
+      def slot_key(key, slot_type = :primary)
+        new(:slot_key, slot_key: key.to_s, slot_type: slot_type)
+      end
+
+      # Route to a specific node by address.
+      # @param host [String] hostname or IP
+      # @param port [Integer] port number
+      # @return [Route]
+      def by_address(host, port)
+        new(:by_address, hostname: host.to_s, port: port.to_i)
+      end
+    end
+
+    # Build the FFI RouteInfo struct for passing to command_with_route_info.
+    #
+    # Returns both the struct and any pinned memory buffers that must remain
+    # alive until the FFI call completes.
+    #
+    # @return [Array(Bindings::RouteInfo, Array)] the struct and pinned buffers
+    def to_ffi
+      info = Bindings::RouteInfo.new
+      info[:route_type] = @route_type
+      info[:slot_id] = @slot_id || 0
+      info[:slot_type] = @slot_type || :primary
+      info[:port] = @port || 0
+
+      pinned = [] # prevent GC of string buffers during FFI call
+      info[:slot_key] = pin_string(@slot_key, pinned)
+      info[:hostname] = pin_string(@hostname, pinned)
+
+      [info, pinned]
+    end
+
+    private
+
+    # Pin a string into an FFI pointer (or NULL if nil), appending the buffer
+    # to +pinned+ so it is not garbage-collected before the FFI call completes.
+    def pin_string(str, pinned)
+      return FFI::Pointer::NULL unless str
+
+      buf = FFI::MemoryPointer.from_string(str)
+      pinned << buf
+      buf
+    end
+
+    def initialize(route_type, slot_id: nil, slot_key: nil, slot_type: :primary, hostname: nil, port: nil)
+      @route_type = route_type
+      @slot_id = slot_id
+      @slot_key = slot_key
+      @slot_type = slot_type
+      @hostname = hostname
+      @port = port
+    end
+  end
+end

data/lib/valkey/utils.rb

@@ -102,6 +102,11 @@ class Valkey
     HashifyStreamEntries = lambda { |reply|
       return [] if reply.nil?
 
+      # In cluster mode, MAP responses come as Hash: {id => [fields], ...}
+      if reply.is_a?(Hash)
+        return reply.map { |entry_id, values| [entry_id, values.is_a?(Array) ? values.flatten : []] }
+      end
+
       return [] if !reply.is_a?(Array) || reply.empty?
 
       # Reply format: [[entry_id, [field1, value1, field2, value2, ...]], ...]

data/lib/valkey/version.rb

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