valkey-rb 0.3.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 569490790efc0901b11b6cd5d4c75d9a162b495601e602ed0b6a9f5307c20884
+  data.tar.gz: a731a0406f728eb47f2e65e2a7d8fca6c7719eabbe5a2c7acff184ba2b5ae3f9
+SHA512:
+  metadata.gz: 61c6127c71d7d3bbe22de3cc0a0eb7eddc34b6b6a7c439bb26ea1b0f1e95a5ce5b0e4fd497a2c8b0b6527cc5a5420b5c3ebce3bcaeb460c0efc17fd95ec92124
+  data.tar.gz: 5f304a28f904a99fd0a8fc46b59930ba20c5dbaebe25116c9801e37bd134cc77065715baabd7b945b256b58063789f05c7369394b71e5a459a910a88399a8eed

data/.rubocop.yml

@@ -0,0 +1,43 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 2.6
+  Exclude:
+    - 'vendor/**/*'
+    - 'lib/valkey/protobuf/**/*.rb'
+
+Style/StringLiterals:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+Naming/MethodParameterName:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 20
+  Exclude:
+    - 'lib/valkey.rb'
+    - 'test/**/*.rb'
+
+Metrics/ModuleLength:
+  Exclude:
+    - 'lib/valkey/request_type.rb'
+    - 'lib/valkey/utils.rb'
+    - 'lib/valkey/commands/*.rb'
+    - 'test/**/*.rb'

data/.rubocop_todo.yml

@@ -0,0 +1,22 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2025-07-15 13:27:05 UTC using RuboCop version 1.78.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 35
+  Exclude:
+    - 'lib/valkey.rb'
+
+# Offense count: 1
+# Configuration parameters: CountComments, CountAsOne.
+Metrics/ClassLength:
+  Max: 111
+  Exclude:
+    - 'lib/valkey.rb'

data/README.md

@@ -0,0 +1,34 @@
+# Valkey
+
+A Ruby client library for [Valkey][valkey-home] built with [Valkey Glide Core][valkey-glide-home] that tries to provide a drop in replacement for redis-rb.
+
+## Getting started
+
+Install with:
+
+```
+$ gem install valkey
+```
+
+You can connect to Valkey by instantiating the `Valkey` class:
+
+```ruby
+require "valkey"
+
+valkey = Valkey.new
+
+valkey.set("mykey", "hello world")
+# => "OK"
+
+valkey.get("mykey")
+# => "hello world"
+```
+
+
+Checkout [the implementation status of the Valkey commands][commands-implementation-progress].
+
+
+[valkey-home]: https://valkey.io
+[valkey-glide-home]: https://github.com/valkey-io/valkey-glide
+[commands-implementation-progress]: https://github.com/valkey-io/valkey-glide-ruby/wiki/The-implementation-status-of-the-Valkey-commands
+

data/Rakefile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+namespace :test do
+  groups = %i[valkey cluster]
+  groups.each do |group|
+    Rake::TestTask.new(group) do |t|
+      t.libs << "test"
+      t.libs << "lib"
+      t.test_files = FileList["test/#{group}/**/*_test.rb"]
+      t.options = '-v' if ENV['CI'] || ENV['VERBOSE']
+    end
+  end
+
+  lost_tests = Dir["test/**/*_test.rb"] - groups.map { |g| Dir["test/#{g}/**/*_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 default: :test

data/lib/valkey/bindings.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+class Valkey
+  module Bindings
+    extend FFI::Library
+
+    # Detect platform and load appropriate library
+    lib_name = case RbConfig::CONFIG['host_os']
+               when /darwin|mac os/
+                 'libglide_ffi.dylib'
+               when /linux/
+                 'libglide_ffi.so'
+               else
+                 raise "Unsupported platform: #{RbConfig::CONFIG['host_os']}"
+               end
+
+    ffi_lib File.expand_path("./#{lib_name}", __dir__)
+
+    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
+      )
+    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
+      )
+    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 :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     # returns *mut CommandResult
+
+    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 # returns *mut CommandResult
+
+    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)
+    ], :pointer # returns *mut CommandResult
+  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