valkey-glide-rb 0.9.0 → 0.9.1

data/lib/valkey.rb

@@ -7,6 +7,7 @@ require "cgi"
 require "valkey/version"
 require "valkey/request_type"
 require "valkey/response_type"
+require "valkey/read_from"
 require "valkey/request_error_type"
 require "valkey/bindings"
 require "valkey/utils"
@@ -31,420 +32,154 @@ class Valkey
     send_batch_commands(pipeline.commands, exception: exception)
   end
 
-  def send_batch_commands(commands, exception: true)
-    # WORKAROUND: The underlying Glide FFI backend has stability issues when
-    # batching transactional commands like MULTI / EXEC / DISCARD. To avoid
-    # native crashes we fall back to issuing those commands sequentially
-    # instead of via `Bindings.batch`.
-    tx_types = [RequestType::MULTI, RequestType::EXEC, RequestType::DISCARD]
+  def initialize(options = {})
+    # Parse URL if provided
+    if options[:url]
+      url_options = Utils.parse_redis_url(options[:url])
+      # Merge URL options, but explicit options take precedence
+      options = url_options.merge(options.reject { |k, _v| k == :url })
+    end
 
-    if commands.any? { |(command_type, _args, _block)| tx_types.include?(command_type) }
-      results = []
+    # Extract connection parameters
+    host = options[:host] || "127.0.0.1"
+    port = options[:port] || 6379
+    database_id = options[:db] || 0
 
-      commands.each do |command_type, command_args, block|
-        res = send_command(command_type, command_args)
-        res = block.call(res) if block
-        results << res
-      end
+    # Validate database ID
+    raise ArgumentError, "Database ID must be non-negative, got: #{database_id}" if database_id.negative?
 
-      return results
-    end
+    nodes = options[:nodes] || [{ host: host, port: port }]
 
-    cmds = []
-    blocks = []
-    buffers = [] # Keep references to prevent GC
+    # Validate nodes array
+    raise ArgumentError, "Nodes array cannot be empty" if nodes.empty?
 
-    commands.each do |command_type, command_args, block|
-      arg_ptrs, arg_lens, arg_bufs = build_command_args(command_args)
+    # Build URI string
+    # Use the first node for standalone mode, or first node for cluster discovery
+    first_node = nodes.first
+    raise ArgumentError, "First node cannot be nil" if first_node.nil?
 
-      cmd = Bindings::CmdInfo.new
-      cmd[:request_type] = command_type
-      cmd[:args] = arg_ptrs
-      cmd[:arg_count] = command_args.size
-      cmd[:args_len] = arg_lens
+    uri_host = first_node[:host]
+    uri_port = first_node[:port]
 
-      cmds << cmd
-      blocks << block
-      buffers << [arg_ptrs, arg_lens, arg_bufs] # Prevent GC
-    end
+    # Validate host and port
+    raise ArgumentError, "Host cannot be nil" if uri_host.nil?
+    raise ArgumentError, "Port cannot be nil" if uri_port.nil?
+    raise ArgumentError, "Port must be a number" unless uri_port.is_a?(Integer)
 
-    # Create array of pointers to CmdInfo structs
-    cmd_ptrs = FFI::MemoryPointer.new(:pointer, cmds.size)
-    cmds.each_with_index do |cmd, i|
-      cmd_ptrs[i].put_pointer(0, cmd.to_ptr)
+    # Determine scheme based on TLS/SSL
+    scheme = [true, "true"].include?(options[:ssl]) ? "rediss" : "redis"
+
+    # Build URI with authentication if provided
+    uri_parts = [scheme, "://"]
+
+    # Add authentication to URI
+    if options[:username] && options[:password]
+      uri_parts << CGI.escape(options[:username])
+      uri_parts << ":"
+      uri_parts << CGI.escape(options[:password])
+      uri_parts << "@"
+    elsif options[:password]
+      uri_parts << ":"
+      uri_parts << CGI.escape(options[:password])
+      uri_parts << "@"
     end
 
-    batch_info = Bindings::BatchInfo.new
-    batch_info[:cmd_count] = cmds.size
-    batch_info[:cmds] = cmd_ptrs
-    batch_info[:is_atomic] = false
+    uri_parts << uri_host
+    uri_parts << ":"
+    uri_parts << uri_port.to_s
 
-    batch_options = Bindings::BatchOptionsInfo.new
-    batch_options[:retry_server_error] = true
-    batch_options[:retry_connection_error] = true
-    batch_options[:has_timeout] = false
-    batch_options[:timeout] = 0 # No timeout
-    batch_options[:route_info] = FFI::Pointer::NULL
+    # Add database ID to URI if specified
+    uri_parts << "/" << database_id.to_s if database_id.positive?
 
-    # Create OpenTelemetry span for batch operation if sampling is enabled
-    # TODO: add parent span propagation via create_batch_otel_span_with_parent
-    # to support distributed tracing context (see Go client base_client.go for reference)
-    span_ptr = 0
-    if OpenTelemetry.should_sample?
-      begin
-        span_ptr = Bindings.create_batch_otel_span
-      rescue StandardError => e
-        warn "Failed to create OpenTelemetry batch span: #{e.message}"
-        span_ptr = 0
-      end
-    end
+    uri_str = uri_parts.join
 
-    begin
-      res = Bindings.batch(
-        @connection,
-        0,
-        batch_info,
-        exception,
-        batch_options.to_ptr,
-        span_ptr
-      )
+    # Build JSON options for additional configuration
+    json_options = {}
 
-      results = convert_response(res)
-    ensure
-      # Always drop the span if one was created
-      if span_ptr != 0
-        begin
-          Bindings.drop_otel_span(span_ptr)
-        rescue StandardError => e
-          warn "Failed to drop OpenTelemetry batch span: #{e.message}"
-        end
-      end
-    end
+    # Cluster mode
+    json_options["cluster_mode_enabled"] = true if options[:cluster_mode]
 
-    blocks.each_with_index do |block, i|
-      results[i] = block.call(results[i]) if block
-    end
+    # Protocol
+    json_options["protocol"] = case options[:protocol]
+                               when :resp3, "resp3", 3
+                                 "RESP3"
+                               else
+                                 "RESP2"
+                               end
 
-    results
-  end
+    # Timeouts
+    request_timeout = options[:timeout] || 5.0
 
-  def build_command_args(command_args)
-    # For empty arrays, pass NULL pointers as per Rust FFI contract
-    # This matches Go's approach which successfully uses nil pointers
-    return [FFI::Pointer::NULL, FFI::Pointer::NULL, []] if command_args.empty?
+    # Validate timeout types
+    raise ArgumentError, "Timeout must be a number, got: #{request_timeout.class}" unless request_timeout.is_a?(Numeric)
+    raise ArgumentError, "Timeout must be positive, got: #{request_timeout}" if request_timeout <= 0
 
-    arg_ptrs = FFI::MemoryPointer.new(:pointer, command_args.size)
-    arg_lens = FFI::MemoryPointer.new(:ulong, command_args.size)
-    buffers = []
+    json_options["request_timeout"] = (request_timeout * 1000).to_i
 
-    command_args.each_with_index do |arg, i|
-      arg = arg.to_s # Ensure we convert to string
+    if options[:connect_timeout]
+      connect_timeout = options[:connect_timeout]
+      unless connect_timeout.is_a?(Numeric)
+        raise ArgumentError, "Connect timeout must be a number, got: #{connect_timeout.class}"
+      end
+      raise ArgumentError, "Connect timeout must be positive, got: #{connect_timeout}" if connect_timeout <= 0
 
-      buf = FFI::MemoryPointer.from_string(arg.to_s)
-      buffers << buf # prevent garbage collection
-      arg_ptrs.put_pointer(i * FFI::Pointer.size, buf)
-      arg_lens.put_ulong(i * 8, arg.bytesize)
+      json_options["connection_timeout"] = (connect_timeout * 1000).to_i
     end
 
-    [arg_ptrs, arg_lens, buffers]
-  end
+    # Client name (user-configurable)
+    json_options["client_name"] = options[:client_name] if options[:client_name]
 
-  def convert_response(res, &block)
-    result = Bindings::CommandResult.new(res)
+    # read_from parsing.
+    json_options["read_from"] = options[:read_from] if options[:read_from]
 
-    if result[:response].null?
-      error = result[:command_error]
+    # client_az
+    json_options["client_az"] = options[:client_az] if options[:client_az]
 
-      case error[:command_error_type]
-      when RequestErrorType::EXECABORT, RequestErrorType::UNSPECIFIED
-        raise CommandError, error[:command_error_message]
-      when RequestErrorType::TIMEOUT
-        raise TimeoutError, error[:command_error_message]
-      when RequestErrorType::DISCONNECT
-        raise ConnectionError, error[:command_error_message]
-      else
-        raise "Unknown error type: #{error[:command_error_type]}"
+    unless json_options["client_az"]
+      case json_options["read_from"]
+      when ReadFrom::AZ_AFFINITY
+        raise ArgumentError, "client_az must be set when read_from is AZAffinity"
+      when ReadFrom::AZ_AFFINITY_REPLICAS_AND_PRIMARY
+        raise ArgumentError, "client_az must be set when read_from is AZAffinityReplicasAndPrimary"
       end
     end
 
-    result = result[:response]
-
-    convert_response = lambda { |response_item|
-      # TODO: handle all types of responses
-      case response_item[:response_type]
-      when ResponseType::STRING
-        response_item[:string_value].read_string(response_item[:string_value_len])
-      when ResponseType::INT
-        response_item[:int_value]
-      when ResponseType::FLOAT
-        response_item[:float_value]
-      when ResponseType::BOOL
-        response_item[:bool_value]
-      when ResponseType::ARRAY
-        ptr = response_item[:array_value]
-        count = response_item[:array_value_len].to_i
-        return [] if count.zero? || ptr.null?
-
-        count.times.map do |i|
-          item = Bindings::CommandResponse.new(ptr + (i * Bindings::CommandResponse.size))
-          convert_response.call(item)
-        end
-      when ResponseType::MAP
-        return nil if response_item[:array_value].null?
+    if options.key?(:inflight_requests_limit)
+      json_options["inflight_requests_limit"] = options[:inflight_requests_limit]
+    end
 
-        ptr = response_item[:array_value]
-        count = response_item[:array_value_len].to_i
-        map = {}
+    json_options["lazy_connect"] = options[:lazy_connect] if options.key?(:lazy_connect)
 
-        Array.new(count) do |i|
-          item = Bindings::CommandResponse.new(ptr + (i * Bindings::CommandResponse.size))
+    json_options["periodic_checks"] = build_periodic_checks(options[:periodic_checks]) if options.key?(:periodic_checks)
 
-          map_key = convert_response.call(Bindings::CommandResponse.new(item[:map_key]))
-          map_value = convert_response.call(Bindings::CommandResponse.new(item[:map_value]))
+    # TLS/SSL certificates
+    root_certs = []
+    if options[:ssl_params].is_a?(Hash)
+      # ca_file - read CA certificate file (PEM or DER format)
+      if options[:ssl_params][:ca_file]
+        ca_file = options[:ssl_params][:ca_file]
+        raise ArgumentError, "CA file does not exist: #{ca_file}" unless File.exist?(ca_file)
+        raise ArgumentError, "CA file is not readable: #{ca_file}" unless File.readable?(ca_file)
 
-          map[map_key] = map_value
-        end
+        root_certs << File.binread(ca_file)
+      end
 
-        # technically it has to return a Hash, but as of now we return just one pair
-        map.to_a.flatten(1) # Flatten to get pairs
-      when ResponseType::SETS
-        ptr = response_item[:sets_value]
-        count = response_item[:sets_value_len].to_i
+      # cert - client certificate (file path or OpenSSL::X509::Certificate)
+      if options[:ssl_params][:cert]
+        cert_data = if options[:ssl_params][:cert].is_a?(String)
+                      cert_file = options[:ssl_params][:cert]
+                      raise ArgumentError, "Cert file does not exist: #{cert_file}" unless File.exist?(cert_file)
+                      raise ArgumentError, "Cert file is not readable: #{cert_file}" unless File.readable?(cert_file)
 
-        Array.new(count) do |i|
-          item = Bindings::CommandResponse.new(ptr + (i * Bindings::CommandResponse.size))
-          convert_response.call(item)
-        end
-      when ResponseType::NULL
-        nil
-      when ResponseType::OK
-        "OK"
-      when ResponseType::ERROR
-        # For errors in arrays (like EXEC responses), return an error object
-        # instead of raising. The error message is typically in string_value.
-        error_msg = if response_item[:string_value].null?
-                      "Unknown error"
+                      File.binread(cert_file)
+                    elsif options[:ssl_params][:cert].respond_to?(:to_pem)
+                      options[:ssl_params][:cert].to_pem
+                    elsif options[:ssl_params][:cert].respond_to?(:to_der)
+                      options[:ssl_params][:cert].to_der
                     else
-                      response_item[:string_value].read_string(response_item[:string_value_len])
+                      options[:ssl_params][:cert].to_s
                     end
-        CommandError.new(error_msg)
-      else
-        raise "Unsupported response type: #{response_item[:response_type]}"
-      end
-    }
-
-    response = convert_response.call(result)
-
-    if block_given?
-      block.call(response)
-    else
-      response
-    end
-  end
-
-  def send_command(command_type, command_args = [], &block)
-    # Validate connection
-    if @connection.nil?
-      raise "Connection is nil"
-    elsif @connection.null?
-      raise "Connection pointer is null"
-    elsif @connection.address.zero?
-      raise "Connection address is 0"
-    end
-
-    channel = 0
-    route = ""
-
-    route_buf = FFI::MemoryPointer.from_string(route)
-
-    # Handle empty command_args case
-    if command_args.empty?
-      arg_ptrs = FFI::MemoryPointer.new(:pointer, 1)
-      arg_lens = FFI::MemoryPointer.new(:ulong, 1)
-      arg_ptrs.put_pointer(0, FFI::MemoryPointer.new(1))
-      arg_lens.put_ulong(0, 0)
-      _buffers = [] # nothing to keep alive
-    else
-      arg_ptrs, arg_lens, _buffers = build_command_args(command_args)
-    end
-
-    # Create OpenTelemetry span if sampling is enabled
-    # TODO: add parent span propagation via create_otel_span_with_parent
-    # to support distributed tracing context (see Go client base_client.go for reference)
-    span_ptr = 0
-    if OpenTelemetry.should_sample?
-      begin
-        span_ptr = Bindings.create_otel_span(command_type)
-      rescue StandardError => e
-        # Log error but continue execution - tracing is non-critical
-        warn "Failed to create OpenTelemetry span: #{e.message}"
-        span_ptr = 0
-      end
-    end
-
-    begin
-      res = Bindings.command(
-        @connection,
-        channel,
-        command_type,
-        command_args.size,
-        arg_ptrs,
-        arg_lens,
-        route_buf,
-        route.bytesize,
-        span_ptr
-      )
-
-      result = convert_response(res, &block)
-    ensure
-      # Always drop the span if one was created, even if command fails
-      if span_ptr != 0
-        begin
-          Bindings.drop_otel_span(span_ptr)
-        rescue StandardError => e
-          # Log but don't raise - span cleanup errors shouldn't break command execution
-          warn "Failed to drop OpenTelemetry span: #{e.message}"
-        end
-      end
-    end
-
-    # Track queued commands during MULTI (except for MULTI, EXEC, DISCARD, WATCH, UNWATCH)
-    if @in_multi && !@queued_commands.nil?
-      tx_commands = [
-        RequestType::MULTI, RequestType::EXEC, RequestType::DISCARD,
-        RequestType::WATCH, RequestType::UNWATCH
-      ]
-      @queued_commands << [command_type, command_args.dup] if !tx_commands.include?(command_type) && result == "QUEUED"
-    end
-
-    result
-  end
-
-  def initialize(options = {})
-    # Parse URL if provided
-    if options[:url]
-      url_options = Utils.parse_redis_url(options[:url])
-      # Merge URL options, but explicit options take precedence
-      options = url_options.merge(options.reject { |k, _v| k == :url })
-    end
-
-    # Extract connection parameters
-    host = options[:host] || "127.0.0.1"
-    port = options[:port] || 6379
-    database_id = options[:db] || 0
-
-    # Validate database ID
-    raise ArgumentError, "Database ID must be non-negative, got: #{database_id}" if database_id.negative?
-
-    nodes = options[:nodes] || [{ host: host, port: port }]
-
-    # Validate nodes array
-    raise ArgumentError, "Nodes array cannot be empty" if nodes.empty?
-
-    # Build URI string
-    # Use the first node for standalone mode, or first node for cluster discovery
-    first_node = nodes.first
-    raise ArgumentError, "First node cannot be nil" if first_node.nil?
-
-    uri_host = first_node[:host]
-    uri_port = first_node[:port]
-
-    # Validate host and port
-    raise ArgumentError, "Host cannot be nil" if uri_host.nil?
-    raise ArgumentError, "Port cannot be nil" if uri_port.nil?
-    raise ArgumentError, "Port must be a number" unless uri_port.is_a?(Integer)
-
-    # Determine scheme based on TLS/SSL
-    scheme = [true, "true"].include?(options[:ssl]) ? "rediss" : "redis"
-
-    # Build URI with authentication if provided
-    uri_parts = [scheme, "://"]
-
-    # Add authentication to URI
-    if options[:username] && options[:password]
-      uri_parts << CGI.escape(options[:username])
-      uri_parts << ":"
-      uri_parts << CGI.escape(options[:password])
-      uri_parts << "@"
-    elsif options[:password]
-      uri_parts << ":"
-      uri_parts << CGI.escape(options[:password])
-      uri_parts << "@"
-    end
-
-    uri_parts << uri_host
-    uri_parts << ":"
-    uri_parts << uri_port.to_s
-
-    # Add database ID to URI if specified
-    uri_parts << "/" << database_id.to_s if database_id.positive?
-
-    uri_str = uri_parts.join
-
-    # Build JSON options for additional configuration
-    json_options = {}
-
-    # Cluster mode
-    json_options["cluster_mode_enabled"] = true if options[:cluster_mode]
-
-    # Protocol
-    json_options["protocol"] = case options[:protocol]
-                               when :resp3, "resp3", 3
-                                 "RESP3"
-                               else
-                                 "RESP2"
-                               end
-
-    # Timeouts
-    request_timeout = options[:timeout] || 5.0
-
-    # Validate timeout types
-    raise ArgumentError, "Timeout must be a number, got: #{request_timeout.class}" unless request_timeout.is_a?(Numeric)
-    raise ArgumentError, "Timeout must be positive, got: #{request_timeout}" if request_timeout <= 0
-
-    json_options["request_timeout"] = (request_timeout * 1000).to_i
-
-    if options[:connect_timeout]
-      connect_timeout = options[:connect_timeout]
-      unless connect_timeout.is_a?(Numeric)
-        raise ArgumentError, "Connect timeout must be a number, got: #{connect_timeout.class}"
-      end
-      raise ArgumentError, "Connect timeout must be positive, got: #{connect_timeout}" if connect_timeout <= 0
-
-      json_options["connection_timeout"] = (connect_timeout * 1000).to_i
-    end
-
-    # Client name
-    json_options["client_name"] = options[:client_name] if options[:client_name]
-
-    # TLS/SSL certificates
-    root_certs = []
-    if options[:ssl_params].is_a?(Hash)
-      # ca_file - read CA certificate file (PEM or DER format)
-      if options[:ssl_params][:ca_file]
-        ca_file = options[:ssl_params][:ca_file]
-        raise ArgumentError, "CA file does not exist: #{ca_file}" unless File.exist?(ca_file)
-        raise ArgumentError, "CA file is not readable: #{ca_file}" unless File.readable?(ca_file)
-
-        root_certs << File.binread(ca_file)
-      end
-
-      # cert - client certificate (file path or OpenSSL::X509::Certificate)
-      if options[:ssl_params][:cert]
-        cert_data = if options[:ssl_params][:cert].is_a?(String)
-                      cert_file = options[:ssl_params][:cert]
-                      raise ArgumentError, "Cert file does not exist: #{cert_file}" unless File.exist?(cert_file)
-                      raise ArgumentError, "Cert file is not readable: #{cert_file}" unless File.readable?(cert_file)
-
-                      File.binread(cert_file)
-                    elsif options[:ssl_params][:cert].respond_to?(:to_pem)
-                      options[:ssl_params][:cert].to_pem
-                    elsif options[:ssl_params][:cert].respond_to?(:to_der)
-                      options[:ssl_params][:cert].to_der
-                    else
-                      options[:ssl_params][:cert].to_s
-                    end
-        root_certs << cert_data
+        root_certs << cert_data
       end
 
       # key - client key (file path or OpenSSL::PKey)
@@ -614,4 +349,334 @@ class Valkey
   end
 
   alias get_statistics statistics
+
+  # Sends a single low-level command to the server, converting the response to
+  # a Ruby value. This is the primitive every command method in
+  # `lib/valkey/commands/*.rb` is built on. Public (rather than private) because
+  # some test helpers (e.g. `test/lint/vector_search_commands.rb`,
+  # `test/valkey/connection_lifecycle_test.rb`) call it directly with an
+  # explicit receiver to issue commands with no dedicated wrapper method yet
+  # (e.g. `DEBUG SLEEP`, raw `HSET` in vector search fixtures).
+  def send_command(command_type, command_args = [], &block)
+    # Validate connection. A nil/null pointer means the client was closed (or
+    # never established a usable connection); surface it as a typed error with
+    # the same "the client is closed" wording the sibling GLIDE clients use
+    # (Go ClosingError, Node/Java ClosingException).
+    raise ConnectionError, "the client is closed" if @connection.nil? || @connection.null? || @connection.address.zero?
+
+    channel = 0
+    route = ""
+
+    route_buf = FFI::MemoryPointer.from_string(route)
+
+    # Handle empty command_args case
+    if command_args.empty?
+      arg_ptrs = FFI::MemoryPointer.new(:pointer, 1)
+      arg_lens = FFI::MemoryPointer.new(:ulong, 1)
+      arg_ptrs.put_pointer(0, FFI::MemoryPointer.new(1))
+      arg_lens.put_ulong(0, 0)
+      _buffers = [] # nothing to keep alive
+    else
+      arg_ptrs, arg_lens, _buffers = build_command_args(command_args)
+    end
+
+    # Create OpenTelemetry span if sampling is enabled, as a child of the app's current
+    # span context when a parent_span_context_provider is registered (see Valkey::OpenTelemetry).
+    span_ptr = 0
+    if OpenTelemetry.should_sample?
+      begin
+        parent_ctx = OpenTelemetry.parent_span_context
+        span_ptr = if parent_ctx
+                     Bindings.create_otel_span_with_trace_context(
+                       command_type, parent_ctx[:trace_id], parent_ctx[:span_id],
+                       parent_ctx[:trace_flags], parent_ctx[:tracestate]
+                     )
+                   else
+                     Bindings.create_otel_span(command_type)
+                   end
+      rescue StandardError => e
+        # Log error but continue execution - tracing is non-critical
+        warn "Failed to create OpenTelemetry span: #{e.message}"
+        span_ptr = 0
+      end
+    end
+
+    begin
+      res = Bindings.command(
+        @connection,
+        channel,
+        command_type,
+        command_args.size,
+        arg_ptrs,
+        arg_lens,
+        route_buf,
+        route.bytesize,
+        span_ptr
+      )
+
+      result = convert_response(res, &block)
+    ensure
+      # Always drop the span if one was created, even if command fails
+      if span_ptr != 0
+        begin
+          Bindings.drop_otel_span(span_ptr)
+        rescue StandardError => e
+          # Log but don't raise - span cleanup errors shouldn't break command execution
+          warn "Failed to drop OpenTelemetry span: #{e.message}"
+        end
+      end
+    end
+
+    # Track queued commands during MULTI (except for MULTI, EXEC, DISCARD, WATCH, UNWATCH)
+    if @in_multi && !@queued_commands.nil?
+      tx_commands = [
+        RequestType::MULTI, RequestType::EXEC, RequestType::DISCARD,
+        RequestType::WATCH, RequestType::UNWATCH
+      ]
+      @queued_commands << [command_type, command_args.dup] if !tx_commands.include?(command_type) && result == "QUEUED"
+    end
+
+    result
+  end
+
+  private
+
+  def send_batch_commands(commands, exception: true)
+    # WORKAROUND: The underlying Glide FFI backend has stability issues when
+    # batching transactional commands like MULTI / EXEC / DISCARD. To avoid
+    # native crashes we fall back to issuing those commands sequentially
+    # instead of via `Bindings.batch`.
+    tx_types = [RequestType::MULTI, RequestType::EXEC, RequestType::DISCARD]
+
+    if commands.any? { |(command_type, _args, _block)| tx_types.include?(command_type) }
+      results = []
+
+      commands.each do |command_type, command_args, block|
+        res = send_command(command_type, command_args)
+        res = block.call(res) if block
+        results << res
+      end
+
+      return results
+    end
+
+    cmds = []
+    blocks = []
+    buffers = [] # Keep references to prevent GC
+
+    commands.each do |command_type, command_args, block|
+      arg_ptrs, arg_lens, arg_bufs = build_command_args(command_args)
+
+      cmd = Bindings::CmdInfo.new
+      cmd[:request_type] = command_type
+      cmd[:args] = arg_ptrs
+      cmd[:arg_count] = command_args.size
+      cmd[:args_len] = arg_lens
+
+      cmds << cmd
+      blocks << block
+      buffers << [arg_ptrs, arg_lens, arg_bufs] # Prevent GC
+    end
+
+    # Create array of pointers to CmdInfo structs
+    cmd_ptrs = FFI::MemoryPointer.new(:pointer, cmds.size)
+    cmds.each_with_index do |cmd, i|
+      cmd_ptrs[i].put_pointer(0, cmd.to_ptr)
+    end
+
+    batch_info = Bindings::BatchInfo.new
+    batch_info[:cmd_count] = cmds.size
+    batch_info[:cmds] = cmd_ptrs
+    batch_info[:is_atomic] = false
+
+    batch_options = Bindings::BatchOptionsInfo.new
+    batch_options[:retry_server_error] = true
+    batch_options[:retry_connection_error] = true
+    batch_options[:has_timeout] = false
+    batch_options[:timeout] = 0 # No timeout
+    batch_options[:route_info] = FFI::Pointer::NULL
+
+    # Create OpenTelemetry span for batch operation if sampling is enabled, as a child of
+    # the app's current span context when a parent_span_context_provider is registered.
+    span_ptr = 0
+    if OpenTelemetry.should_sample?
+      begin
+        parent_ctx = OpenTelemetry.parent_span_context
+        span_ptr = if parent_ctx
+                     Bindings.create_batch_otel_span_with_trace_context(
+                       parent_ctx[:trace_id], parent_ctx[:span_id], parent_ctx[:trace_flags], parent_ctx[:tracestate]
+                     )
+                   else
+                     Bindings.create_batch_otel_span
+                   end
+      rescue StandardError => e
+        warn "Failed to create OpenTelemetry batch span: #{e.message}"
+        span_ptr = 0
+      end
+    end
+
+    begin
+      res = Bindings.batch(
+        @connection,
+        0,
+        batch_info,
+        exception,
+        batch_options.to_ptr,
+        span_ptr
+      )
+
+      results = convert_response(res)
+    ensure
+      # Always drop the span if one was created
+      if span_ptr != 0
+        begin
+          Bindings.drop_otel_span(span_ptr)
+        rescue StandardError => e
+          warn "Failed to drop OpenTelemetry batch span: #{e.message}"
+        end
+      end
+    end
+
+    blocks.each_with_index do |block, i|
+      results[i] = block.call(results[i]) if block
+    end
+
+    results
+  end
+
+  # Builds the `periodic_checks` extra_options_json value. Accepts
+  # `{ manual_interval: { duration_in_sec: N } }` or `{ disabled: true/false }`
+  # (symbol or string keys). Only checks shape (Hash present, manual_interval
+  # is a Hash) to avoid a NoMethodError -- the core validates values.
+  def build_periodic_checks(periodic_checks)
+    unless periodic_checks.is_a?(Hash)
+      raise ArgumentError, "periodic_checks must be a Hash, got: #{periodic_checks.class}"
+    end
+
+    if periodic_checks.key?(:disabled) || periodic_checks.key?("disabled")
+      disabled = periodic_checks.key?(:disabled) ? periodic_checks[:disabled] : periodic_checks["disabled"]
+      return { "disabled" => disabled }
+    end
+
+    manual_interval = periodic_checks[:manual_interval] || periodic_checks["manual_interval"]
+    raise ArgumentError, "periodic_checks must contain :manual_interval or :disabled" unless manual_interval.is_a?(Hash)
+
+    duration_in_sec = manual_interval[:duration_in_sec] || manual_interval["duration_in_sec"]
+
+    { "manual_interval" => { "duration_in_sec" => duration_in_sec } }
+  end
+
+  def build_command_args(command_args)
+    # For empty arrays, pass NULL pointers as per Rust FFI contract
+    # This matches Go's approach which successfully uses nil pointers
+    return [FFI::Pointer::NULL, FFI::Pointer::NULL, []] if command_args.empty?
+
+    arg_ptrs = FFI::MemoryPointer.new(:pointer, command_args.size)
+    arg_lens = FFI::MemoryPointer.new(:ulong, command_args.size)
+    buffers = []
+
+    command_args.each_with_index do |arg, i|
+      arg = arg.to_s # Ensure we convert to string
+
+      buf = FFI::MemoryPointer.from_string(arg.to_s)
+      buffers << buf # prevent garbage collection
+      arg_ptrs.put_pointer(i * FFI::Pointer.size, buf)
+      arg_lens.put_ulong(i * 8, arg.bytesize)
+    end
+
+    [arg_ptrs, arg_lens, buffers]
+  end
+
+  def convert_response(res, &block)
+    result = Bindings::CommandResult.new(res)
+
+    if result[:response].null?
+      error = result[:command_error]
+
+      case error[:command_error_type]
+      when RequestErrorType::EXECABORT, RequestErrorType::UNSPECIFIED
+        raise CommandError, error[:command_error_message]
+      when RequestErrorType::TIMEOUT
+        raise TimeoutError, error[:command_error_message]
+      when RequestErrorType::DISCONNECT
+        raise ConnectionError, error[:command_error_message]
+      else
+        raise "Unknown error type: #{error[:command_error_type]}"
+      end
+    end
+
+    result = result[:response]
+
+    convert_response = lambda { |response_item|
+      # TODO: handle all types of responses
+      case response_item[:response_type]
+      when ResponseType::STRING
+        response_item[:string_value].read_string(response_item[:string_value_len])
+      when ResponseType::INT
+        response_item[:int_value]
+      when ResponseType::FLOAT
+        response_item[:float_value]
+      when ResponseType::BOOL
+        response_item[:bool_value]
+      when ResponseType::ARRAY
+        ptr = response_item[:array_value]
+        count = response_item[:array_value_len].to_i
+        return [] if count.zero? || ptr.null?
+
+        count.times.map do |i|
+          item = Bindings::CommandResponse.new(ptr + (i * Bindings::CommandResponse.size))
+          convert_response.call(item)
+        end
+      when ResponseType::MAP
+        return nil if response_item[:array_value].null?
+
+        ptr = response_item[:array_value]
+        count = response_item[:array_value_len].to_i
+        map = {}
+
+        Array.new(count) do |i|
+          item = Bindings::CommandResponse.new(ptr + (i * Bindings::CommandResponse.size))
+
+          map_key = convert_response.call(Bindings::CommandResponse.new(item[:map_key]))
+          map_value = convert_response.call(Bindings::CommandResponse.new(item[:map_value]))
+
+          map[map_key] = map_value
+        end
+
+        # technically it has to return a Hash, but as of now we return just one pair
+        map.to_a.flatten(1) # Flatten to get pairs
+      when ResponseType::SETS
+        ptr = response_item[:sets_value]
+        count = response_item[:sets_value_len].to_i
+
+        Array.new(count) do |i|
+          item = Bindings::CommandResponse.new(ptr + (i * Bindings::CommandResponse.size))
+          convert_response.call(item)
+        end
+      when ResponseType::NULL
+        nil
+      when ResponseType::OK
+        "OK"
+      when ResponseType::ERROR
+        # For errors in arrays (like EXEC responses), return an error object
+        # instead of raising. The error message is typically in string_value.
+        error_msg = if response_item[:string_value].null?
+                      "Unknown error"
+                    else
+                      response_item[:string_value].read_string(response_item[:string_value_len])
+                    end
+        CommandError.new(error_msg)
+      else
+        raise "Unsupported response type: #{response_item[:response_type]}"
+      end
+    }
+
+    response = convert_response.call(result)
+
+    if block_given?
+      block.call(response)
+    else
+      response
+    end
+  end
 end