valkey-rb 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a20f9cdffea000924afe9304a0c63bae69be3eeaae532f1ae64e7ec562403eb3
+  data.tar.gz: e451bc8429e5514e1b76115507c40a26e7698a01f6a1a5aa39c597c3da2f9170
+SHA512:
+  metadata.gz: d8300adf645ac1de3bfb33ca882016e9d943f3ed033e3f0b5d7397478af22e45a52bae7e1aa7ac3b55eb8acf4b25090d3e46cc6bf63ad97f7cb93d65e78c0a15
+  data.tar.gz: 55e5127393ca215b079cb6c9622f9640d5aa2fdf9143fe44c86acaf3dce766ecf8c6530cacdaa28983c9e46ae08c8347c4fedc623cc0dba169ff55d0b8a1f43b

data/.rubocop.yml

@@ -0,0 +1,58 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 2.6
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'lib/valkey/protobuf/**/*.rb'
+
+Style/StringLiterals:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Naming/AccessorMethodName:
+  Enabled: false
+
+Lint/DuplicateBranch:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 20
+  Exclude:
+    - 'lib/valkey.rb'
+    - 'lib/valkey/opentelemetry.rb'
+    - 'test/**/*.rb'
+
+Metrics/ClassLength:
+  Exclude:
+    - 'lib/valkey.rb'
+    - 'test/**/*.rb'
+
+Metrics/BlockNesting:
+  Exclude:
+    - 'test_app/**/*.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,95 @@
+# 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.
+
+## Features
+
+- **High Performance**: Built on Valkey GLIDE Core (Rust-based) for optimal performance
+- **OpenTelemetry Integration**: Built-in distributed tracing support
+- **Client Statistics**: Real-time monitoring of connections and commands
+- **Drop-in Replacement**: Compatible with redis-rb API
+
+## 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"
+```
+
+## OpenTelemetry and Monitoring
+
+The Valkey client includes built-in support for OpenTelemetry distributed tracing and client statistics monitoring.
+
+### OpenTelemetry Tracing
+
+Enable automatic tracing of all Valkey operations:
+
+```ruby
+require 'valkey'
+require 'opentelemetry/sdk'
+
+# Configure OpenTelemetry
+OpenTelemetry::SDK.configure do |c|
+  c.service_name = 'my-app'
+end
+
+# Create client with tracing enabled
+client = Valkey.new(
+  host: 'localhost',
+  port: 6379,
+  tracing: true
+)
+
+# All commands are automatically traced
+client.set('key', 'value')
+client.get('key')
+```
+
+### Client Statistics
+
+Monitor connection and command metrics in real-time:
+
+```ruby
+client = Valkey.new
+
+# Execute some operations
+client.set('key1', 'value1')
+client.get('key1')
+
+# Get statistics
+stats = client.get_statistics
+
+puts "Active connections: #{stats[:connection_stats][:active_connections]}"
+puts "Total commands: #{stats[:command_stats][:total_commands]}"
+puts "Success rate: #{
+  (stats[:command_stats][:successful_commands].to_f / 
+   stats[:command_stats][:total_commands] * 100).round(2)
+}%"
+```
+
+For detailed documentation, see [OPENTELEMETRY_GUIDE.md](OPENTELEMETRY_GUIDE.md) and [opentelemetry_example.rb](opentelemetry_example.rb).
+
+## Documentation
+
+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,224 @@
+# frozen_string_literal: true
+
+class Valkey
+  module Bindings
+    extend FFI::Library
+
+    lib_ext = FFI::Platform.mac? ? "dylib" : "so"
+    ffi_lib File.expand_path("./libglide_ffi.#{lib_ext}", __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
+
+    # 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 connections opened to Valkey
+        :total_clients, :ulong,            # total GLIDE clients created
+        :total_values_compressed, :ulong,  # number of values compressed
+        :total_values_decompressed, :ulong, # number of values decompressed
+        :total_original_bytes, :ulong,     # bytes before compression
+        :total_bytes_compressed, :ulong,   # bytes after compression
+        :total_bytes_decompressed, :ulong, # bytes after decompression
+        :compression_skipped_count, :ulong # times compression was skipped
+      )
+    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