valkey-rb 1.0.0

data/lib/valkey/commands/vector_search_commands.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+class Valkey
+  module Commands
+    # This module contains commands related to RediSearch Vector Search.
+    #
+    # RediSearch provides secondary indexing, full-text search, and vector similarity search
+    # capabilities on top of Redis/Valkey. These commands require the RediSearch module to be loaded.
+    #
+    # @see https://redis.io/docs/stack/search/
+    #
+    module VectorSearchCommands
+      # List all available indexes.
+      #
+      # @example List all indexes
+      #   valkey.ft_list
+      #     # => ["idx1", "idx2"]
+      #
+      # @return [Array<String>] array of index names
+      #
+      # @see https://redis.io/commands/ft._list/
+      def ft_list
+        send_command(RequestType::FT_LIST)
+      end
+
+      # Run a search query with aggregations.
+      #
+      # @example Perform an aggregation query
+      #   valkey.ft_aggregate("myIndex", "*", "GROUPBY", "1", "@category", "REDUCE", "COUNT", "0", "AS", "count")
+      #     # => [[1, ["category", "electronics", "count", "5"]]]
+      #
+      # @param [String] index the index name to search
+      # @param [String] query the search query
+      # @param [Array<String>] args additional query arguments (GROUPBY, REDUCE, etc.)
+      # @return [Array] aggregation results
+      #
+      # @see https://redis.io/commands/ft.aggregate/
+      def ft_aggregate(index, query, *args)
+        command_args = [index, query] + args
+        send_command(RequestType::FT_AGGREGATE, command_args)
+      end
+
+      # Add an alias to an index.
+      #
+      # @example Add an alias to an index
+      #   valkey.ft_alias_add("myAlias", "myIndex")
+      #     # => "OK"
+      #
+      # @param [String] alias the alias name
+      # @param [String] index the index name
+      # @return [String] "OK" on success
+      #
+      # @see https://redis.io/commands/ft.aliasadd/
+      def ft_alias_add(alias_name, index)
+        send_command(RequestType::FT_ALIAS_ADD, [alias_name, index])
+      end
+
+      # Delete an alias from an index.
+      #
+      # @example Delete an alias
+      #   valkey.ft_alias_del("myAlias")
+      #     # => "OK"
+      #
+      # @param [String] alias the alias name to delete
+      # @return [String] "OK" on success
+      #
+      # @see https://redis.io/commands/ft.aliasdel/
+      def ft_alias_del(alias_name)
+        send_command(RequestType::FT_ALIAS_DEL, [alias_name])
+      end
+
+      # List all existing aliases.
+      #
+      # @example List all aliases
+      #   valkey.ft_alias_list
+      #     # => ["alias1", "alias2"]
+      #
+      # @return [Array<String>] array of alias names
+      #
+      # @see https://redis.io/commands/ft.aliaslist/
+      def ft_alias_list
+        send_command(RequestType::FT_ALIAS_LIST)
+      end
+
+      # Update an alias to point to a different index.
+      #
+      # @example Update an alias
+      #   valkey.ft_alias_update("myAlias", "newIndex")
+      #     # => "OK"
+      #
+      # @param [String] alias the alias name
+      # @param [String] index the new index name
+      # @return [String] "OK" on success
+      #
+      # @see https://redis.io/commands/ft.aliasupdate/
+      def ft_alias_update(alias_name, index)
+        send_command(RequestType::FT_ALIAS_UPDATE, [alias_name, index])
+      end
+
+      # Create a search index with the given schema.
+      #
+      # @example Create a basic index
+      #   valkey.ft_create("myIndex", "SCHEMA", "title", "TEXT", "price", "NUMERIC")
+      #     # => "OK"
+      #
+      # @example Create an index with vector field
+      #   valkey.ft_create("vecIndex", "ON", "HASH", "PREFIX", "1", "doc:",
+      #                    "SCHEMA", "embedding", "VECTOR", "HNSW", "6",
+      #                    "TYPE", "FLOAT32", "DIM", "128", "DISTANCE_METRIC", "COSINE")
+      #     # => "OK"
+      #
+      # @param [String] index the index name
+      # @param [Array<String>] args schema definition and options
+      # @return [String] "OK" on success
+      #
+      # @see https://redis.io/commands/ft.create/
+      def ft_create(index, *args)
+        command_args = [index] + args
+        send_command(RequestType::FT_CREATE, command_args)
+      end
+
+      # Drop an index and optionally delete all documents.
+      #
+      # @example Drop an index without deleting documents
+      #   valkey.ft_drop_index("myIndex")
+      #     # => "OK"
+      #
+      # @example Drop an index and delete all documents
+      #   valkey.ft_drop_index("myIndex", dd: true)
+      #     # => "OK"
+      #
+      # @param [String] index the index name
+      # @param [Boolean] dd whether to delete documents (DD flag)
+      # @return [String] "OK" on success
+      #
+      # @see https://redis.io/commands/ft.dropindex/
+      def ft_drop_index(index, dd: false)
+        args = [index]
+        args << "DD" if dd
+        send_command(RequestType::FT_DROP_INDEX, args)
+      end
+
+      # Explain how a query is parsed and executed.
+      #
+      # @example Explain a query
+      #   valkey.ft_explain("myIndex", "@title:hello @price:[0 100]")
+      #     # => "INTERSECT {\n  @title:hello\n  @price:[0 100]\n}\n"
+      #
+      # @param [String] index the index name
+      # @param [String] query the search query
+      # @param [Array<String>] args additional query arguments
+      # @return [String] query execution plan
+      #
+      # @see https://redis.io/commands/ft.explain/
+      def ft_explain(index, query, *args)
+        command_args = [index, query] + args
+        send_command(RequestType::FT_EXPLAIN, command_args)
+      end
+
+      # Explain how a query is parsed and executed (CLI-formatted output).
+      #
+      # @example Explain a query in CLI format
+      #   valkey.ft_explain_cli("myIndex", "@title:hello")
+      #     # => formatted query plan
+      #
+      # @param [String] index the index name
+      # @param [String] query the search query
+      # @param [Array<String>] args additional query arguments
+      # @return [String] formatted query execution plan
+      #
+      # @see https://redis.io/commands/ft.explaincli/
+      def ft_explain_cli(index, query, *args)
+        command_args = [index, query] + args
+        send_command(RequestType::FT_EXPLAIN_CLI, command_args)
+      end
+
+      # Get information about an index.
+      #
+      # @example Get index info
+      #   valkey.ft_info("myIndex")
+      #     # => ["index_name", "myIndex", "fields", [...], ...]
+      #
+      # @param [String] index the index name
+      # @return [Array] index information as array of key-value pairs
+      #
+      # @see https://redis.io/commands/ft.info/
+      def ft_info(index)
+        send_command(RequestType::FT_INFO, [index])
+      end
+
+      # Profile a search or aggregation query.
+      #
+      # @example Profile a search query
+      #   valkey.ft_profile("myIndex", "SEARCH", "QUERY", "@title:hello")
+      #     # => [execution time, results]
+      #
+      # @example Profile an aggregation query
+      #   valkey.ft_profile("myIndex", "AGGREGATE", "QUERY", "*", "GROUPBY", "1", "@category")
+      #     # => [execution time, results]
+      #
+      # @param [String] index the index name
+      # @param [String] query_type either "SEARCH" or "AGGREGATE"
+      # @param [Array<String>] args query arguments
+      # @return [Array] profiling results with execution time and query results
+      #
+      # @see https://redis.io/commands/ft.profile/
+      def ft_profile(index, query_type, *args)
+        command_args = [index, query_type] + args
+        send_command(RequestType::FT_PROFILE, command_args)
+      end
+
+      # Search an index with a query.
+      #
+      # @example Basic search
+      #   valkey.ft_search("myIndex", "hello world")
+      #     # => [1, "doc1", ["title", "hello world"]]
+      #
+      # @example Search with options
+      #   valkey.ft_search("myIndex", "@title:hello", "LIMIT", "0", "10", "RETURN", "2", "title", "price")
+      #     # => [total_results, doc_id, [field1, value1, field2, value2], ...]
+      #
+      # @example Vector similarity search
+      #   valkey.ft_search("vecIndex", "*=>[KNN 5 @embedding $vec]",
+      #                    "PARAMS", "2", "vec", vector_blob,
+      #                    "RETURN", "1", "__embedding_score",
+      #                    "DIALECT", "2")
+      #     # => [results_count, doc_id, ["__embedding_score", "0.95"], ...]
+      #
+      # @param [String] index the index name
+      # @param [String] query the search query
+      # @param [Array<String>] args additional query arguments (LIMIT, RETURN, SORTBY, etc.)
+      # @return [Array] search results with total count and matching documents
+      #
+      # @see https://redis.io/commands/ft.search/
+      def ft_search(index, query, *args)
+        command_args = [index, query] + args
+        send_command(RequestType::FT_SEARCH, command_args)
+      end
+
+      # Convenience method for FT.* commands.
+      #
+      # @example List indexes
+      #   valkey.ft(:list)
+      #     # => ["idx1", "idx2"]
+      #
+      # @example Create an index
+      #   valkey.ft(:create, "myIndex", "SCHEMA", "title", "TEXT")
+      #     # => "OK"
+      #
+      # @example Search an index
+      #   valkey.ft(:search, "myIndex", "hello")
+      #     # => [results]
+      #
+      # @param [String, Symbol] subcommand the subcommand (list, create, search, etc.)
+      # @param [Array] args arguments for the subcommand
+      # @param [Hash] options options for the subcommand
+      # @return [Object] depends on subcommand
+      def ft(subcommand, *args, **options)
+        subcommand = subcommand.to_s.downcase.gsub("-", "_")
+
+        if args.empty? && options.empty?
+          send("ft_#{subcommand}")
+        elsif options.empty?
+          send("ft_#{subcommand}", *args)
+        else
+          send("ft_#{subcommand}", *args, **options)
+        end
+      end
+    end
+  end
+end

data/lib/valkey/commands.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "valkey/commands/string_commands"
+require "valkey/commands/connection_commands"
+require "valkey/commands/server_commands"
+require "valkey/commands/generic_commands"
+require "valkey/commands/bitmap_commands"
+require "valkey/commands/list_commands"
+require "valkey/commands/geo_commands"
+require "valkey/commands/hyper_log_log_commands"
+require "valkey/commands/sorted_set_commands"
+require "valkey/commands/set_commands"
+require "valkey/commands/scripting_commands"
+require "valkey/commands/function_commands"
+require "valkey/commands/module_commands"
+require "valkey/commands/pubsub_commands"
+require "valkey/commands/json_commands"
+require "valkey/commands/cluster_commands"
+require "valkey/commands/transaction_commands"
+require "valkey/commands/vector_search_commands"
+require "valkey/commands/stream_commands"
+require "valkey/commands/hash_commands"
+
+class Valkey
+  # Valkey commands module
+  #
+  # This module includes various command modules that provide methods
+  # for interacting with a Valkey server. Each command module corresponds to a
+  # specific set of commands that can be executed against the Valkey server.
+  #
+  # The commands are organized into groups based on their functionality,
+  # such as string operations, connection management, server information,
+  # key management, and bitmap operations.
+  #
+  # @see https://valkey.io/commands/ Valkey Commands Documentation
+  #
+  module Commands
+    include StringCommands
+    include ConnectionCommands
+    include ServerCommands
+    include GenericCommands
+    include BitmapCommands
+    include ListCommands
+    include GeoCommands
+    include HyperLogLogCommands
+    include SortedSetCommands
+    include SetCommands
+    include ScriptingCommands
+    include FunctionCommands
+    include ModuleCommands
+    include PubSubCommands
+    include JsonCommands
+    include ClusterCommands
+    include TransactionCommands
+    include VectorSearchCommands
+    include StreamCommands
+    include HashCommands
+
+    # Commands that are not implemented by design.
+    # Raises CommandError when called.
+    #
+    %i[].each do |command|
+      define_method command do |*_args|
+        raise CommandError, "Unsupported command: #{command}"
+      end
+    end
+  end
+end

data/lib/valkey/errors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class Valkey
+  class BaseError < StandardError; end
+
+  class ProtocolError < BaseError
+    def initialize(reply_type)
+      super(<<-MESSAGE.gsub(/(?:^|\n)\s*/, " "))
+        Got '#{reply_type}' as initial reply byte.
+        If you're in a forking environment, such as Unicorn, you need to
+        connect to Valkey after forking.
+      MESSAGE
+    end
+  end
+
+  class CommandError < BaseError; end
+
+  class PermissionError < CommandError; end
+
+  class WrongTypeError < CommandError; end
+
+  class OutOfMemoryError < CommandError; end
+
+  class NoScriptError < CommandError; end
+
+  class BaseConnectionError < BaseError; end
+
+  class CannotConnectError < BaseConnectionError; end
+
+  class ConnectionError < BaseConnectionError; end
+
+  class TimeoutError < BaseConnectionError; end
+
+  class InheritedError < BaseConnectionError; end
+
+  class ReadOnlyError < BaseConnectionError; end
+
+  class InvalidClientOptionError < BaseError; end
+
+  class SubscriptionError < BaseError; end
+end

data/lib/valkey/opentelemetry.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+class Valkey
+  # OpenTelemetry integration for Valkey GLIDE Ruby client.
+  #
+  # This module provides integration with the OpenTelemetry implementation
+  # built into the Valkey GLIDE core (Rust FFI layer). Unlike typical Ruby
+  # OpenTelemetry instrumentation, this directly configures the native
+  # OpenTelemetry exporter in the Rust layer.
+  #
+  # @example Initialize with HTTP collector
+  #   Valkey::OpenTelemetry.init(
+  #     traces: {
+  #       endpoint: "http://localhost:4318/v1/traces",
+  #       sample_percentage: 10
+  #     },
+  #     metrics: {
+  #       endpoint: "http://localhost:4318/v1/metrics"
+  #     },
+  #     flush_interval_ms: 5000
+  #   )
+  #
+  # @example Initialize with gRPC collector
+  #   Valkey::OpenTelemetry.init(
+  #     traces: {
+  #       endpoint: "grpc://localhost:4317",
+  #       sample_percentage: 1
+  #     },
+  #     metrics: {
+  #       endpoint: "grpc://localhost:4317"
+  #     }
+  #   )
+  #
+  # @example Initialize with file exporter (for testing)
+  #   Valkey::OpenTelemetry.init(
+  #     traces: {
+  #       endpoint: "file:///tmp/valkey_traces.json",
+  #       sample_percentage: 100
+  #     },
+  #     metrics: {
+  #       endpoint: "file:///tmp/valkey_metrics.json"
+  #     }
+  #   )
+  module OpenTelemetry
+    class << self
+      @initialized = false
+      @config = nil
+
+      # Initialize OpenTelemetry in the Valkey GLIDE core.
+      #
+      # This method can only be called once per process. Subsequent calls will
+      # be ignored with a warning.
+      #
+      # @param traces [Hash, nil] Traces configuration
+      # @option traces [String] :endpoint The endpoint URL (required)
+      #   Supported formats:
+      #   - HTTP: http://localhost:4318/v1/traces
+      #   - gRPC: grpc://localhost:4317
+      #   - File: file:///absolute/path/to/traces.json
+      # @option traces [Integer] :sample_percentage Sample percentage 0-100 (default: 1)
+      #   Keep low (1-5%) in production for performance
+      #
+      # @param metrics [Hash, nil] Metrics configuration
+      # @option metrics [String] :endpoint The endpoint URL (required)
+      #   Same format as traces endpoint
+      #
+      # @param flush_interval_ms [Integer, nil] Flush interval in milliseconds (default: 5000)
+      #   Must be a positive integer
+      #
+      # @raise [ArgumentError] if neither traces nor metrics is provided
+      # @raise [ArgumentError] if sample_percentage is not between 0-100
+      # @raise [RuntimeError] if initialization fails
+      #
+      # @return [void]
+      def init(traces: nil, metrics: nil, flush_interval_ms: nil)
+        if @initialized
+          warn "Valkey::OpenTelemetry already initialized - ignoring new configuration"
+          return
+        end
+
+        # Validate input
+        raise ArgumentError, "At least one of traces or metrics must be provided" if traces.nil? && metrics.nil?
+
+        if traces && traces[:sample_percentage]
+          sample = traces[:sample_percentage]
+          unless sample.is_a?(Integer) && sample >= 0 && sample <= 100
+            raise ArgumentError, "sample_percentage must be an integer between 0 and 100, got: #{sample}"
+          end
+        end
+
+        if flush_interval_ms && (!flush_interval_ms.is_a?(Integer) || flush_interval_ms <= 0)
+          raise ArgumentError, "flush_interval_ms must be a positive integer, got: #{flush_interval_ms}"
+        end
+
+        # Build the configuration
+        config = build_config(traces, metrics, flush_interval_ms)
+
+        # Call the FFI function
+        error_ptr = Bindings.init_open_telemetry(config)
+
+        unless error_ptr.null?
+          error_msg = error_ptr.read_string
+          Bindings.free_c_string(error_ptr)
+          raise "Failed to initialize OpenTelemetry: #{error_msg}"
+        end
+
+        @initialized = true
+        @config = { traces: traces, metrics: metrics, flush_interval_ms: flush_interval_ms }
+
+        puts "✅ Valkey OpenTelemetry initialized successfully"
+        puts "   Traces: #{traces ? traces[:endpoint] : 'disabled'}"
+        puts "   Metrics: #{metrics ? metrics[:endpoint] : 'disabled'}"
+      end
+
+      # Check if OpenTelemetry has been initialized.
+      #
+      # @return [Boolean] true if initialized
+      def initialized?
+        @initialized
+      end
+
+      # Determine if the current request should be sampled based on the configured sample percentage.
+      #
+      # @return [Boolean] true if the request should be sampled
+      def should_sample?
+        return false unless @initialized
+        return false unless @config&.dig(:traces)
+
+        sample_percentage = @config.dig(:traces, :sample_percentage) || 1
+        rand(100) < sample_percentage
+      end
+
+      # Get the current OpenTelemetry configuration.
+      #
+      # @return [Hash, nil] the configuration hash or nil if not initialized
+      attr_reader :config
+
+      # Reset initialization state (for testing only).
+      #
+      # @api private
+      def reset!
+        @initialized = false
+        @config = nil
+      end
+
+      private
+
+      def build_config(traces, metrics, flush_interval_ms)
+        config_struct = Bindings::OpenTelemetryConfig.new
+
+        # Configure traces if provided
+        if traces
+          validate_endpoint!(traces[:endpoint], "traces")
+
+          traces_struct = Bindings::OpenTelemetryTracesConfig.new
+          traces_struct[:endpoint] = FFI::MemoryPointer.from_string(traces[:endpoint])
+
+          if traces[:sample_percentage]
+            traces_struct[:has_sample_percentage] = true
+            traces_struct[:sample_percentage] = traces[:sample_percentage]
+          else
+            traces_struct[:has_sample_percentage] = false
+            traces_struct[:sample_percentage] = 1 # Default
+          end
+
+          config_struct[:traces] = traces_struct.pointer
+        else
+          config_struct[:traces] = FFI::Pointer::NULL
+        end
+
+        # Configure metrics if provided
+        if metrics
+          validate_endpoint!(metrics[:endpoint], "metrics")
+
+          metrics_struct = Bindings::OpenTelemetryMetricsConfig.new
+          metrics_struct[:endpoint] = FFI::MemoryPointer.from_string(metrics[:endpoint])
+          config_struct[:metrics] = metrics_struct.pointer
+        else
+          config_struct[:metrics] = FFI::Pointer::NULL
+        end
+
+        # Configure flush interval
+        if flush_interval_ms
+          config_struct[:has_flush_interval_ms] = true
+          config_struct[:flush_interval_ms] = flush_interval_ms
+        else
+          config_struct[:has_flush_interval_ms] = false
+          config_struct[:flush_interval_ms] = 5000 # Default
+        end
+
+        config_struct
+      end
+
+      def validate_endpoint!(endpoint, type)
+        unless endpoint.is_a?(String) && !endpoint.empty?
+          raise ArgumentError, "#{type} endpoint must be a non-empty string"
+        end
+
+        # Validate endpoint format
+        valid_prefixes = %w[http:// https:// grpc:// file://]
+        return if valid_prefixes.any? { |prefix| endpoint.start_with?(prefix) }
+
+        raise ArgumentError, "#{type} endpoint must start with one of: #{valid_prefixes.join(', ')}"
+      end
+    end
+  end
+end

data/lib/valkey/pipeline.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class Valkey
+  class Pipeline
+    include Commands
+
+    attr_reader :commands
+
+    def initialize
+      @commands = []
+      # Keep transactional state consistent with the main client so that
+      # helpers like `multi`/`exec` can safely consult `@in_multi`.
+      @in_multi = false
+    end
+
+    def send_command(command_type, command_args = [], &block)
+      @commands << [command_type, command_args, block]
+    end
+  end
+end