valkey-glide-rb 0.9.0.pre.rc1

data/lib/valkey/bindings.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+class Valkey
+  module Bindings
+    extend FFI::Library
+
+    # Determine platform-specific library extension and directory name
+    def self.platform_info
+      os = if FFI::Platform.mac?
+             "darwin"
+           elsif FFI::Platform.windows?
+             "windows"
+           else
+             "linux"
+           end
+
+      # Detect architecture
+      arch = case RbConfig::CONFIG["host_cpu"]
+             when /x86_64|amd64/i
+               "x86_64"
+             when /aarch64|arm64/i
+               "aarch64"
+             when /i[3-6]86/i
+               "x86"
+             else
+               RbConfig::CONFIG["host_cpu"]
+             end
+
+      lib_ext = case os
+                when "darwin"
+                  "dylib"
+                when "windows"
+                  "dll"
+                else
+                  "so"
+                end
+
+      # Platform directory name matches Rust target triple convention
+      platform_dir = case os
+                     when "darwin"
+                       "#{arch}-apple-darwin"
+                     when "linux"
+                       "#{arch}-unknown-linux-gnu"
+                     when "windows"
+                       "#{arch}-pc-windows-msvc"
+                     end
+
+      { os: os, arch: arch, lib_ext: lib_ext, platform_dir: platform_dir }
+    end
+
+    platform = platform_info
+    lib_ext = platform[:lib_ext]
+    platform_dir = platform[:platform_dir]
+
+    # Look for the native library in the following locations (in order):
+    # 1. valkey-glide submodule build output (development/source builds)
+    # 2. Platform-specific bundled library in lib/valkey/native/{platform}/ (for gem distribution)
+    # 3. Legacy bundled library in lib/valkey (fallback for old gem structure)
+    lib_paths = [
+      # Submodule build output (release) - from lib/valkey/ go up 2 levels to repo root
+      File.expand_path("../../valkey-glide/ffi/target/release/libglide_ffi.#{lib_ext}", __dir__),
+      # Submodule build output (debug)
+      File.expand_path("../../valkey-glide/ffi/target/debug/libglide_ffi.#{lib_ext}", __dir__),
+      # Platform-specific bundled library (for gem distribution)
+      File.expand_path("./native/#{platform_dir}/libglide_ffi.#{lib_ext}", __dir__),
+      # Legacy bundled library (fallback)
+      File.expand_path("./libglide_ffi.#{lib_ext}", __dir__)
+    ]
+
+    lib_path = lib_paths.find { |path| File.exist?(path) }
+
+    unless lib_path
+      raise LoadError, <<~ERROR
+        Could not find libglide_ffi native library for platform: #{platform_dir}
+
+        Searched in:
+        #{lib_paths.map { |p| "  - #{p}" }.join("\n")}
+
+        To build from source:
+          1. Initialize the submodule: git submodule update --init --recursive
+          2. Build the FFI library: cd valkey-glide/ffi && cargo build --release
+
+        Detected platform: OS=#{platform[:os]}, Arch=#{platform[:arch]}
+      ERROR
+    end
+
+    ffi_lib lib_path
+
+    class ClientType < FFI::Struct
+      layout(
+        :tag, :uint # 0 = AsyncClient, 1 = SyncClient
+      )
+    end
+
+    class ConnectionResponse < FFI::Struct
+      layout(
+        :conn_ptr, :pointer, # *const c_void
+        :connection_error_message, :string # *const c_char (null-terminated C string)
+      )
+    end
+
+    class CommandError < FFI::Struct
+      layout(
+        :command_error_message, :string,
+        :command_error_type, :int # Assuming RequestErrorType is repr(C) enum
+      )
+    end
+
+    class BatchOptionsInfo < FFI::Struct
+      layout(
+        :retry_server_error, :bool,
+        :retry_connection_error, :bool,
+        :has_timeout, :bool,
+        :timeout, :uint, # Assuming u32 is represented as uint in C
+        :route_info, :pointer # *const RouteInfo
+      )
+    end
+
+    class CmdInfo < FFI::Struct
+      layout(
+        :request_type, :int,  # Assuming RequestType is repr(C) enum
+        :args, :pointer,      # *const *const u8 (pointer to array of pointers to args)
+        :arg_count, :ulong,   # usize (number of arguments)
+        :args_len, :pointer   # *const usize (pointer to array of argument lengths)
+      )
+    end
+
+    class ScriptHashBuffer < FFI::Struct
+      layout(
+        :ptr, :pointer,  # *mut u8 (pointer to the script hash)
+        :len, :ulong,    # usize (length of the script hash)
+        :capacity, :ulong # usize (capacity of the buffer)
+      )
+    end
+
+    class BatchInfo < FFI::Struct
+      layout(
+        :cmd_count, :ulong,  # usize
+        :cmds, :pointer,     # *const *const CmdInfo
+        :is_atomic, :bool    # bool
+      )
+    end
+
+    class CommandResponse < FFI::Struct
+      layout(
+        :response_type, :int,         # Assuming ResponseType is repr(C) enum
+        :int_value, :int64,
+        :float_value, :double,
+        :bool_value, :bool,
+        :string_value, :pointer,      # points to C string
+        :string_value_len, :long,
+        :array_value, :pointer,       # points to CommandResponse array
+        :array_value_len, :long,
+        :map_key, :pointer,           # CommandResponse*
+        :map_value, :pointer,         # CommandResponse*
+        :sets_value, :pointer,        # CommandResponse*
+        :sets_value_len, :long,
+        :arena_ptr, :pointer          # *mut c_void - arena allocator pointer
+      )
+    end
+
+    callback :success_callback, %i[ulong pointer], :void
+    callback :failure_callback, %i[ulong string int], :void
+
+    class AsyncClientData < FFI::Struct
+      layout(
+        :success_callback, :success_callback,
+        :failure_callback, :failure_callback
+      )
+    end
+
+    class ClientData < FFI::Union
+      layout(
+        :async_client, AsyncClientData
+      )
+    end
+
+    class CommandResult < FFI::Struct
+      layout(
+        :response, CommandResponse.by_ref,
+        :command_error, CommandError.by_ref,
+        :arena, :pointer # *mut ResponseArena
+      )
+    end
+
+    callback :pubsub_callback, [
+      :ulong, # client_ptr
+      :int,             # kind (PushKind enum)
+      :pointer, :long,  # message + length
+      :pointer, :long,  # channel + length
+      :pointer, :long   # pattern + length
+    ], :void
+
+    attach_function :create_client, [
+      :pointer,        # *const u8 (connection_request_bytes)
+      :ulong,          # usize (connection_request_len)
+      ClientType.by_ref, # *const ClientType
+      :pubsub_callback # callback
+    ], :pointer        # *const ConnectionResponse
+
+    attach_function :create_client_from_uri, [
+      :string,         # *const c_char (uri_str)
+      :string,         # *const c_char (extra_options_json)
+      ClientType.by_ref, # *const ClientType
+      :pubsub_callback # callback
+    ], :pointer        # *const ConnectionResponse
+
+    attach_function :free_connection_response, [
+      :pointer # *mut ConnectionResponse
+    ], :void
+
+    attach_function :close_client, [
+      :pointer # client_adapter_ptr
+    ], :void
+
+    attach_function :command, [
+      :pointer,     # client_adapter_ptr
+      :ulong,       # request_id
+      :int,         # command_type
+      :ulong,       # arg_count
+      :pointer,     # args (pointer to usize[])
+      :pointer,     # args_len (pointer to c_ulong[])
+      :pointer,     # route_bytes
+      :ulong,       # route_bytes_len
+      :ulong        # span_ptr (u64)
+    ], :pointer, blocking: true # returns *mut CommandResult, releases GVL during I/O
+
+    attach_function :batch, [
+      :pointer,        # client_ptr
+      :ulong,          # callback_index
+      BatchInfo.by_ref, # *const BatchInfo
+      :bool,           # raise_on_error
+      :pointer,        # *const BatchOptionsInfo
+      :ulong           # span_ptr (u64)
+    ], :pointer, blocking: true # returns *mut CommandResult, releases GVL during I/O
+
+    attach_function :store_script, [
+      :pointer, # *const u8 (script_bytes)
+      :ulong # usize (script_len)
+    ], :pointer # returns *mut ScriptHashBuffer
+
+    attach_function :invoke_script, [
+      :pointer,        # client_ptr
+      :ulong,          # request_id
+      :pointer,        # hash (pointer to C string)
+      :ulong,          # keys_count (number of keys)
+      :pointer,        # keys (pointer to usize[])
+      :pointer,        # keys_len (pointer to c_ulong[])
+      :ulong,          # args_count (number of args)
+      :pointer,        # args (pointer to usize[])
+      :pointer,        # args_len (pointer to c_ulong[])
+      :pointer,        # route_bytes (pointer to u8)
+      :ulong,          # route_bytes_len (usize)
+      :uint64          # span_ptr (OpenTelemetry span pointer)
+    ], :pointer, blocking: true # returns *mut CommandResult, releases GVL during I/O
+
+    # OpenTelemetry structures
+    class OpenTelemetryTracesConfig < FFI::Struct
+      layout(
+        :endpoint, :pointer,              # const char* (trace collector endpoint)
+        :has_sample_percentage, :bool,    # whether sample_percentage is set
+        :sample_percentage, :uint32       # sampling percentage (0-100)
+      )
+    end
+
+    class OpenTelemetryMetricsConfig < FFI::Struct
+      layout(
+        :endpoint, :pointer               # const char* (metrics collector endpoint)
+      )
+    end
+
+    class OpenTelemetryConfig < FFI::Struct
+      layout(
+        :traces, :pointer,                # OpenTelemetryTracesConfig*
+        :metrics, :pointer,               # OpenTelemetryMetricsConfig*
+        :has_flush_interval_ms, :bool,    # whether flush_interval_ms is set
+        :flush_interval_ms, :int64        # flush interval in milliseconds
+      )
+    end
+
+    # Statistics structure
+    class Statistics < FFI::Struct
+      layout(
+        :total_connections, :ulong,
+        :total_clients, :ulong,
+        :total_values_compressed, :ulong,
+        :total_values_decompressed, :ulong,
+        :total_original_bytes, :ulong,
+        :total_bytes_compressed, :ulong,
+        :total_bytes_decompressed, :ulong,
+        :compression_skipped_count, :ulong,
+        :subscription_out_of_sync_count, :ulong,
+        :subscription_last_sync_timestamp, :ulong
+      )
+    end
+
+    # OpenTelemetry functions
+    attach_function :init_open_telemetry, [
+      OpenTelemetryConfig.by_ref # OpenTelemetry configuration
+    ], :pointer # returns error string or NULL on success
+
+    attach_function :free_c_string, [
+      :pointer # C string to free
+    ], :void
+
+    attach_function :create_otel_span, [
+      :int # request_type (RequestType enum value)
+    ], :uint64 # returns span pointer (u64) or 0 on failure
+
+    attach_function :create_batch_otel_span, [], :uint64 # returns span pointer (u64) or 0 on failure
+
+    attach_function :drop_otel_span, [
+      :uint64 # span_ptr to close
+    ], :void
+
+    # Statistics function
+    attach_function :get_statistics, [], Statistics.by_value # returns statistics by value
+  end
+end

data/lib/valkey/commands/bitmap_commands.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+class Valkey
+  module Commands
+    # this module contains commands related to BITMAP data type.
+    #
+    # @see https://valkey.io/commands/#bitmap
+    #
+    module BitmapCommands
+      # Sets or clears the bit at offset in the string value stored at key.
+      #
+      # @param [String] key
+      # @param [Integer] offset bit offset
+      # @param [Integer] value bit value `0` or `1`
+      # @return [Integer] the original bit value stored at `offset`
+      def setbit(key, offset, value)
+        send_command(RequestType::SET_BIT, [key, offset, value])
+      end
+
+      # Returns the bit value at offset in the string value stored at key.
+      #
+      # @param [String] key
+      # @param [Integer] offset bit offset
+      # @return [Integer] `0` or `1`
+      def getbit(key, offset)
+        send_command(RequestType::GET_BIT, [key, offset])
+      end
+
+      # Count the number of set bits in a range of the string value stored at key.
+      #
+      # @param [String] key
+      # @param [Integer] start start index
+      # @param [Integer] stop stop index
+      # @param [String, Symbol] scale the scale of the offset range
+      #     e.g. 'BYTE' - interpreted as a range of bytes, 'BIT' - interpreted as a range of bits
+      # @return [Integer] the number of bits set to 1
+      def bitcount(key, start = 0, stop = -1, scale: nil)
+        args = [key, start, stop]
+        args << scale if scale
+        send_command(RequestType::BIT_COUNT, args)
+      end
+
+      # Perform a bitwise operation between strings and store the resulting string in a key.
+      #
+      # @param [String] operation e.g. `and`, `or`, `xor`, `not`
+      # @param [String] destkey destination key
+      # @param [String, Array<String>] keys one or more source keys to perform `operation`
+      # @return [Integer] the length of the string stored in `destkey`
+      def bitop(operation, destkey, *keys)
+        keys.flatten!(1)
+        args = [operation, destkey]
+        args.concat(keys)
+
+        send_command(RequestType::BIT_OP, args)
+      end
+
+      def bitfield(key, *args)
+        send_command(RequestType::BIT_FIELD, [key] + args.map(&:to_s))
+      end
+
+      def bitfield_ro(key, *args)
+        send_command(RequestType::BIT_FIELD_READ_ONLY, [key] + args.map(&:to_s))
+      end
+
+      # Return the position of the first bit set to 1 or 0 in a string.
+      #
+      # @param [String] key
+      # @param [Integer] bit whether to look for the first 1 or 0 bit
+      # @param [Integer] start start index
+      # @param [Integer] stop stop index
+      # @param [String, Symbol] scale the scale of the offset range
+      #     e.g. 'BYTE' - interpreted as a range of bytes, 'BIT' - interpreted as a range of bits
+      # @return [Integer] the position of the first 1/0 bit.
+      #                  -1 if looking for 1 and it is not found or start and stop are given.
+      def bitpos(key, bit, start = nil, stop = nil, scale: nil)
+        raise(ArgumentError, 'stop parameter specified without start parameter') if stop && !start
+
+        args = [key, bit]
+        args << start if start
+        args << stop if stop
+        args << scale if scale
+        send_command(RequestType::BIT_POS, args)
+      end
+    end
+  end
+end

data/lib/valkey/commands/cluster_commands.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+class Valkey
+  module Commands
+    # This module contains commands related to Redis Cluster management.
+    #
+    # @see https://valkey.io/commands/#cluster
+    #
+    module ClusterCommands
+      # Send ASKING command to the server.
+      #
+      # @return [String] `"OK"`
+      def asking
+        send_command(RequestType::ASKING)
+      end
+
+      # Add slots to the cluster.
+      #
+      # @param [Array<Integer>] slots array of slot numbers
+      # @return [String] `"OK"`
+      def cluster_addslots(*slots)
+        send_command(RequestType::CLUSTER_ADD_SLOTS, slots)
+      end
+
+      # Add a range of slots to the cluster.
+      #
+      # @param [Integer] start_slot starting slot number
+      # @param [Integer] end_slot ending slot number
+      # @return [String] `"OK"`
+      def cluster_addslotsrange(start_slot, end_slot)
+        send_command(RequestType::CLUSTER_ADD_SLOTS_RANGE, [start_slot, end_slot])
+      end
+
+      # Bump the epoch of the cluster.
+      #
+      # @return [String] `"OK"`
+      def cluster_bumpepoch
+        send_command(RequestType::CLUSTER_BUMP_EPOCH)
+      end
+
+      # Count failure reports for a node.
+      #
+      # @param [String] node_id the node ID
+      # @return [Integer] number of failure reports
+      def cluster_count_failure_reports(node_id)
+        send_command(RequestType::CLUSTER_COUNT_FAILURE_REPORTS, [node_id])
+      end
+
+      # Count keys in a specific slot.
+      #
+      # @param [Integer] slot the slot number
+      # @return [Integer] number of keys in the slot
+      def cluster_countkeysinslot(slot)
+        send_command(RequestType::CLUSTER_COUNT_KEYS_IN_SLOT, [slot])
+      end
+
+      # Delete slots from the cluster.
+      #
+      # @param [Array<Integer>] slots array of slot numbers
+      # @return [String] `"OK"`
+      def cluster_delslots(*slots)
+        send_command(RequestType::CLUSTER_DEL_SLOTS, slots)
+      end
+
+      # Delete a range of slots from the cluster.
+      #
+      # @param [Integer] start_slot starting slot number
+      # @param [Integer] end_slot ending slot number
+      # @return [String] `"OK"`
+      def cluster_delslotsrange(start_slot, end_slot)
+        send_command(RequestType::CLUSTER_DEL_SLOTS_RANGE, [start_slot, end_slot])
+      end
+
+      # Force a failover of the cluster.
+      #
+      # @param [String] force force the failover
+      # @return [String] `"OK"`
+      def cluster_failover(force = nil)
+        args = []
+        args << "FORCE" if force
+        send_command(RequestType::CLUSTER_FAILOVER, args)
+      end
+
+      # Flush all slots from the cluster.
+      #
+      # @return [String] `"OK"`
+      def cluster_flushslots
+        send_command(RequestType::CLUSTER_FLUSH_SLOTS)
+      end
+
+      # Remove a node from the cluster.
+      #
+      # @param [String] node_id the node ID to forget
+      # @return [String] `"OK"`
+      def cluster_forget(node_id)
+        send_command(RequestType::CLUSTER_FORGET, [node_id])
+      end
+
+      # Get keys in a specific slot.
+      #
+      # @param [Integer] slot the slot number
+      # @param [Integer] count maximum number of keys to return
+      # @return [Array<String>] array of keys
+      def cluster_getkeysinslot(slot, count)
+        send_command(RequestType::CLUSTER_GET_KEYS_IN_SLOT, [slot, count])
+      end
+
+      # Get information about the cluster.
+      #
+      # @return [Hash<String, String>] cluster information
+      def cluster_info
+        send_command(RequestType::CLUSTER_INFO) do |reply|
+          Utils::HashifyInfo.call(reply)
+        end
+      end
+
+      # Get the slot for a key.
+      #
+      # @param [String] key the key name
+      # @return [Integer] slot number
+      def cluster_keyslot(key)
+        send_command(RequestType::CLUSTER_KEY_SLOT, [key])
+      end
+
+      # Get information about cluster links.
+      #
+      # @return [Array<Hash>] array of link information
+      def cluster_links
+        send_command(RequestType::CLUSTER_LINKS)
+      end
+
+      # Meet another node in the cluster.
+      #
+      # @param [String] ip IP address of the node
+      # @param [Integer] port port of the node
+      # @return [String] `"OK"`
+      def cluster_meet(ip, port)
+        send_command(RequestType::CLUSTER_MEET, [ip, port])
+      end
+
+      # Get the ID of the current node.
+      #
+      # @return [String] node ID
+      def cluster_myid
+        send_command(RequestType::CLUSTER_MY_ID)
+      end
+
+      # Get the shard ID of the current node.
+      #
+      # @return [String] shard ID
+      def cluster_myshardid
+        send_command(RequestType::CLUSTER_MY_SHARD_ID)
+      end
+
+      # Get information about all nodes in the cluster.
+      #
+      # @return [Array<Hash>] array of node information
+      def cluster_nodes
+        send_command(RequestType::CLUSTER_NODES) do |reply|
+          Utils::HashifyClusterNodes.call(reply)
+        end
+      end
+
+      # Get information about replica nodes.
+      #
+      # @param [String] node_id the master node ID
+      # @return [Array<Hash>] array of replica information
+      def cluster_replicas(node_id)
+        send_command(RequestType::CLUSTER_REPLICAS, [node_id]) do |reply|
+          Utils::HashifyClusterSlaves.call(reply)
+        end
+      end
+
+      # Set a node as a replica of another node.
+      #
+      # @param [String] node_id the master node ID
+      # @return [String] `"OK"`
+      def cluster_replicate(node_id)
+        send_command(RequestType::CLUSTER_REPLICATE, [node_id])
+      end
+
+      # Reset the cluster.
+      #
+      # @param [String] hard hard reset
+      # @return [String] `"OK"`
+      def cluster_reset(hard = nil)
+        args = []
+        args << "HARD" if hard
+        send_command(RequestType::CLUSTER_RESET, args)
+      end
+
+      # Save the cluster configuration.
+      #
+      # @return [String] `"OK"`
+      def cluster_saveconfig
+        send_command(RequestType::CLUSTER_SAVE_CONFIG)
+      end
+
+      # Set the config epoch for a node.
+      #
+      # @param [Integer] epoch the config epoch
+      # @return [String] `"OK"`
+      def cluster_set_config_epoch(epoch)
+        send_command(RequestType::CLUSTER_SET_CONFIG_EPOCH, [epoch])
+      end
+
+      # Set the state of a slot.
+      #
+      # @param [Integer] slot the slot number
+      # @param [String] state the state (importing, migrating, node, stable)
+      # @param [String] node_id the node ID (optional)
+      # @return [String] `"OK"`
+      def cluster_setslot(slot, state, node_id = nil)
+        args = [slot, state]
+        args << node_id if node_id
+        send_command(RequestType::CLUSTER_SETSLOT, args)
+      end
+
+      # Get information about cluster shards.
+      #
+      # @return [Array<Hash>] array of shard information
+      def cluster_shards
+        send_command(RequestType::CLUSTER_SHARDS)
+      end
+
+      # Get information about slave nodes (deprecated, use cluster_replicas).
+      #
+      # @return [Array<Hash>] array of slave information
+      def cluster_slaves(node_id)
+        send_command(RequestType::CLUSTER_SLAVES, [node_id]) do |reply|
+          Utils::HashifyClusterSlaves.call(reply)
+        end
+      end
+
+      # Get information about cluster slots.
+      #
+      # @return [Array<Hash>] array of slot information
+      def cluster_slots
+        send_command(RequestType::CLUSTER_SLOTS) do |reply|
+          Utils::HashifyClusterSlots.call(reply)
+        end
+      end
+
+      # Set the connection to read-only mode.
+      #
+      # @return [String] "OK"
+      def readonly
+        send_command(RequestType::READ_ONLY)
+      end
+
+      # Set the connection to read-write mode.
+      #
+      # @return [String] "OK"
+      def readwrite
+        send_command(RequestType::READ_WRITE)
+      end
+    end
+  end
+end