test-valkey-glide-rb 0.0.1.pre.rc1

data/Rakefile

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# Only load bundler gem tasks when not testing installed gem
+# bundler/gem_tasks can interfere with load path when testing installed gems
+require 'bundler/gem_tasks' unless ENV["TEST_INSTALLED_GEM"]
+require 'rake/testtask'
+
+# =============================================================================
+# Native Library Build Tasks
+# =============================================================================
+
+def native_lib_ext
+  case RbConfig::CONFIG['host_os']
+  when /darwin/
+    'dylib'
+  else
+    'so'
+  end
+end
+
+namespace :native do
+  desc "Initialize the valkey-glide submodule"
+  task :submodule do
+    puts "Initializing valkey-glide submodule..."
+    sh "git submodule update --init --recursive"
+  end
+
+  desc "Build the native FFI library (release mode)"
+  task build: :submodule do
+    puts "Building native FFI library..."
+    Dir.chdir("valkey-glide/ffi") do
+      sh "cargo build --release"
+    end
+    puts "Native library built successfully!"
+    puts "Location: valkey-glide/ffi/target/release/libglide_ffi.#{native_lib_ext}"
+  end
+
+  desc "Build the native FFI library (debug mode)"
+  task build_debug: :submodule do
+    puts "Building native FFI library (debug)..."
+    Dir.chdir("valkey-glide/ffi") do
+      sh "cargo build"
+    end
+    puts "Native library built successfully!"
+    puts "Location: valkey-glide/ffi/target/debug/libglide_ffi.#{native_lib_ext}"
+  end
+
+  desc "Clean native build artifacts"
+  task :clean do
+    puts "Cleaning native build artifacts..."
+    if Dir.exist?("valkey-glide/ffi")
+      Dir.chdir("valkey-glide/ffi") do
+        sh "cargo clean"
+      end
+    end
+    puts "Clean complete!"
+  end
+
+  desc "Copy built library to lib/valkey for gem packaging"
+  task package: :build do
+    require 'fileutils'
+    src = "valkey-glide/ffi/target/release/libglide_ffi.#{native_lib_ext}"
+    dest = "lib/valkey/libglide_ffi.#{native_lib_ext}"
+
+    if File.exist?(src)
+      FileUtils.cp(src, dest)
+      puts "Copied #{src} to #{dest}"
+    else
+      abort "Native library not found at #{src}. Run 'rake native:build' first."
+    end
+  end
+end
+
+desc "Build the native FFI library"
+task native: "native:build"
+
+# =============================================================================
+# Test Tasks
+# =============================================================================
+
+namespace :test do
+  groups = %i[valkey cluster]
+  groups.each do |group|
+    Rake::TestTask.new(group) do |t|
+      t.libs << "test"
+      # Only add local lib to load path when not testing installed gem
+      t.libs << "lib" unless ENV["TEST_INSTALLED_GEM"]
+      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/examples/README.md

@@ -0,0 +1,55 @@
+# Examples
+
+Runnable examples for Valkey GLIDE Ruby. Requires a Valkey or Redis OSS server unless noted.
+
+## Prerequisites
+
+From the repository root:
+
+```bash
+bin/setup
+```
+
+Run examples with the gem loaded from `lib/`:
+
+```bash
+bundle exec ruby examples/standalone.rb
+```
+
+Or:
+
+```bash
+RUBYOPT="-I$(pwd)/lib" ruby examples/standalone.rb
+```
+
+## Examples
+
+| File | Description | Server |
+|------|-------------|--------|
+| [standalone.rb](./standalone.rb) | Basic connect, SET, GET | Standalone `:6379` |
+| [cluster.rb](./cluster.rb) | Cluster connect, SET, GET | Cluster `:7000`–`:7005` |
+| [pipelining.rb](./pipelining.rb) | Non-atomic pipeline | Standalone `:6379` |
+| [opentelemetry.rb](./opentelemetry.rb) | OTel file exporter + traced commands | Standalone `:6379` |
+| [statistics.rb](./statistics.rb) | Client statistics | Standalone `:6379` |
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `VALKEY_HOST` | `127.0.0.1` | Server host |
+| `VALKEY_PORT` | `6379` | Standalone port |
+| `VALKEY_CLUSTER_PORT` | `7000` | First cluster node port |
+
+## Standalone with Docker
+
+```bash
+docker run -d --name valkey -p 6379:6379 valkey/valkey:8
+bundle exec ruby examples/standalone.rb
+```
+
+## Cluster with Docker
+
+```bash
+docker run -d -p 7000-7005:7000-7005 grokzen/redis-cluster:7.0.15
+bundle exec ruby examples/cluster.rb
+```

data/examples/cluster.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Cluster mode example.
+#
+# Run: bundle exec ruby examples/cluster.rb
+# Requires a 6-node cluster on 127.0.0.1:7000-7005 (see examples/README.md).
+
+require "valkey"
+
+base_port = Integer(ENV.fetch("VALKEY_CLUSTER_PORT", 7000))
+host = ENV.fetch("VALKEY_HOST", "127.0.0.1")
+
+nodes = 6.times.map { |i| { host: host, port: base_port + i } }
+
+client = Valkey.new(nodes: nodes, cluster_mode: true)
+
+puts "PING: #{client.ping}"
+puts "SET: #{client.set('cluster_key', 'cluster_value')}"
+puts "GET: #{client.get('cluster_key')}"
+
+client.del("cluster_key")
+client.close
+
+puts "Done."

data/examples/opentelemetry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# OpenTelemetry example using file exporters (no collector required).
+#
+# Run: bundle exec ruby examples/opentelemetry.rb
+# Traces: /tmp/valkey_ruby_example_traces.json
+# Metrics: /tmp/valkey_ruby_example_metrics.json
+
+require "valkey"
+require "fileutils"
+
+TRACES_FILE = "/tmp/valkey_ruby_example_traces.json"
+METRICS_FILE = "/tmp/valkey_ruby_example_metrics.json"
+
+FileUtils.rm_f(TRACES_FILE)
+FileUtils.rm_f(METRICS_FILE)
+
+Valkey::OpenTelemetry.init(
+  traces: {
+    endpoint: "file://#{TRACES_FILE}",
+    sample_percentage: 100
+  },
+  metrics: {
+    endpoint: "file://#{METRICS_FILE}"
+  },
+  flush_interval_ms: 1000
+)
+
+host = ENV.fetch("VALKEY_HOST", "127.0.0.1")
+port = Integer(ENV.fetch("VALKEY_PORT", 6379))
+
+client = Valkey.new(host: host, port: port)
+
+client.set("otel_key", "otel_value")
+client.get("otel_key")
+client.pipelined do |pipe|
+  pipe.set("otel_pipe_1", "a")
+  pipe.get("otel_pipe_1")
+end
+
+client.del("otel_key", "otel_pipe_1")
+client.close
+
+# Allow exporter flush
+sleep 2
+
+puts "OpenTelemetry initialized: #{Valkey::OpenTelemetry.initialized?}"
+puts "Traces file: #{TRACES_FILE} (#{File.size?(TRACES_FILE) || 0} bytes)"
+puts "Metrics file: #{METRICS_FILE} (#{File.size?(METRICS_FILE) || 0} bytes)"
+puts "Done."

data/examples/pipelining.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Pipeline example — batch commands in one round trip.
+#
+# Run: bundle exec ruby examples/pipelining.rb
+
+require "valkey"
+
+host = ENV.fetch("VALKEY_HOST", "127.0.0.1")
+port = Integer(ENV.fetch("VALKEY_PORT", 6379))
+
+client = Valkey.new(host: host, port: port)
+
+client.del("pipe_counter")
+
+results = client.pipelined do |pipe|
+  pipe.set("pipe_key", "pipe_value")
+  pipe.get("pipe_key")
+  pipe.incr("pipe_counter")
+  pipe.get("pipe_counter")
+end
+
+puts "Pipeline results:"
+results.each_with_index { |r, i| puts "  [#{i}] #{r.inspect}" }
+
+client.del("pipe_key", "pipe_counter")
+client.close
+
+puts "Done."

data/examples/standalone.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Basic standalone Valkey example.
+#
+# Run: bundle exec ruby examples/standalone.rb
+# Requires Valkey/Redis on VALKEY_HOST:VALKEY_PORT (default 127.0.0.1:6379).
+
+require "valkey"
+
+host = ENV.fetch("VALKEY_HOST", "127.0.0.1")
+port = Integer(ENV.fetch("VALKEY_PORT", 6379))
+
+client = Valkey.new(host: host, port: port)
+
+puts "PING: #{client.ping}"
+puts "SET: #{client.set('hello', 'world')}"
+puts "GET: #{client.get('hello')}"
+
+client.del("hello")
+client.close
+
+puts "Done."

data/examples/statistics.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Client statistics example.
+#
+# Run: bundle exec ruby examples/statistics.rb
+
+require "valkey"
+
+host = ENV.fetch("VALKEY_HOST", "127.0.0.1")
+port = Integer(ENV.fetch("VALKEY_PORT", 6379))
+
+client = Valkey.new(host: host, port: port)
+client.set("stats_demo", "1")
+client.get("stats_demo")
+
+stats = client.get_statistics
+
+puts "Client statistics:"
+stats.each { |k, v| puts "  #{k}: #{v}" }
+
+client.del("stats_demo")
+client.close
+
+puts "Done."

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