familia 1.2.0 → 2.0.0.pre.pre

data/lib/familia/base.rb

@@ -1,8 +1,8 @@
-# frozen_string_literal: true
+# lib/familia/base.rb
 
 #
 module Familia
-  # A common module for Familia::RedisType and Familia::Horreum to include.
+  # A common module for Familia::DataType and Familia::Horreum to include.
   #
   # This allows us to use a single comparison to check if a class is a
   # Familia class. e.g.
@@ -11,13 +11,23 @@ module Familia
   #     klass.ancestors.member?(Familia::Base) # => true
   #
   # @see Familia::Horreum
-  # @see Familia::RedisType
+  # @see Familia::DataType
   #
   module Base
     @features = nil
     @dump_method = :to_json
     @load_method = :from_json
 
+    # Returns a string representation of the object. Implementing classes
+    # are welcome to override this method to provide a more meaningful
+    # representation. Using this as a default via super is recommended.
+    #
+    # @return [String] A string representation of the object. Never nil.
+    #
+    def to_s
+      "#<#{self.class}:0x#{object_id.to_s(16)}>"
+    end
+
     class << self
       attr_reader :features
       attr_accessor :dump_method, :load_method
@@ -34,23 +44,23 @@ module Familia
     # with the :expiration feature's implementation.
     #
     # This is a no-op implementation that gets overridden by features like
-    # :expiration. It accepts an optional ttl parameter to maintain interface
+    # :expiration. It accepts an optional default_expiration parameter to maintain interface
     # compatibility with the overriding implementations.
     #
-    # @param ttl [Integer, nil] Time To Live in seconds (ignored in base implementation)
+    # @param default_expiration [Integer, nil] Time To Live in seconds (ignored in base implementation)
     # @return [nil] Always returns nil
     #
     # @note This is a no-op implementation. Classes that need expiration
     #       functionality should include the :expiration feature.
     #
-    def update_expiration(ttl: nil)
-      Familia.ld "[update_expiration] Feature not enabled for #{self.class}. Key: #{rediskey} (caller: #{caller(1..1)})"
+    def update_expiration(default_expiration: nil)
+      Familia.ld "[update_expiration] Feature not enabled for #{self.class}. Key: #{dbkey} (caller: #{caller(1..1)})"
       nil
     end
 
     def generate_id
-      @key ||= Familia.generate_id
-      @key
+      @identifier ||= Familia.generate_id
+      @identifier
     end
 
     def uuid

data/lib/familia/connection.rb

@@ -1,103 +1,270 @@
-# frozen_string_literal: true
+# lib/familia/connection.rb
 
-require_relative '../../lib/redis_middleware'
+require_relative '../../lib/middleware/database_middleware'
+require_relative 'multi_result'
 
+# Familia
+#
+# A family warehouse for your keystore data.
 #
 module Familia
-  @uri = URI.parse 'redis://127.0.0.1'
-  @redis_clients = {}
-  @redis_uri_by_class = {}
+  @uri = URI.parse 'redis://127.0.0.1:6379'
+  @database_clients = {}
 
-  # The Connection module provides Redis connection management for Familia.
-  # It allows easy setup and access to Redis clients across different URIs.
+  # The Connection module provides Database connection management for Familia.
+  # It allows easy setup and access to Database clients across different URIs
+  # with robust connection pooling for thread safety.
   module Connection
-    # @return [Hash] A hash of Redis clients, keyed by server ID
-    attr_reader :redis_clients
-
-    # @return [URI] The default URI for Redis connections
+    # @return [URI] The default URI for Database connections
     attr_reader :uri
 
-    # @return [Boolean] Whether Redis command logging is enabled
-    attr_accessor :enable_redis_logging
+    # @return [Hash] A hash of Database clients, keyed by server ID
+    attr_reader :database_clients
+
+    # @return [Boolean] Whether Database command logging is enabled
+    attr_accessor :enable_database_logging
+
+    # @return [Boolean] Whether Database command counter is enabled
+    attr_accessor :enable_database_counter
 
-    # @return [Boolean] Whether Redis command counter is enabled
-    attr_accessor :enable_redis_counter
+    # @return [Proc] A callable that provides Database connections
+    attr_accessor :connection_provider
+
+    # @return [Boolean] Whether to require external connections (no fallback)
+    attr_accessor :connection_required
+
+    # Sets the default URI for Database connections.
+    #
+    # NOTE: uri is not a property of the Settings module b/c it's not
+    # configured in class defintions like default_expiration or logical DB index.
+    #
+    # @param v [String, URI] The new default URI
+    # @example
+    #   Familia.uri = 'redis://localhost:6379'
+    def uri=(uri)
+      @uri = normalize_uri(uri)
+    end
+    alias url uri
+    alias url= uri=
 
-    # Establishes a connection to a Redis server.
+    # Establishes a connection to a Database server.
     #
-    # @param uri [String, URI, nil] The URI of the Redis server to connect to.
-    #   If nil, uses the default URI from `@redis_uri_by_class` or `Familia.uri`.
-    # @return [Redis] The connected Redis client.
+    # @param uri [String, URI, nil] The URI of the Database server to connect to.
+    #   If nil, uses the default URI from `@database_clients` or `Familia.uri`.
+    # @return [Redis] The connected Database client.
     # @raise [ArgumentError] If no URI is specified.
     # @example
     #   Familia.connect('redis://localhost:6379')
     def connect(uri = nil)
-      uri = URI.parse(uri) if uri.is_a?(String)
-      uri ||= @redis_uri_by_class[self]
-      uri ||= Familia.uri
-
-      raise ArgumentError, 'No URI specified' unless uri
+      parsed_uri = normalize_uri(uri)
+      serverid = parsed_uri.serverid
 
-      conf = uri.conf
-      @redis_uri_by_class[self] = uri.serverid
+      if Familia.enable_database_logging
+        DatabaseLogger.logger = Familia.logger
+        RedisClient.register(DatabaseLogger)
+      end
 
-      if Familia.enable_redis_logging
-        RedisLogger.logger = Familia.logger
-        RedisClient.register(RedisLogger)
+      if Familia.enable_database_counter
+        # NOTE: This middleware uses AtommicFixnum from concurrent-ruby which is
+        # less contentious than Mutex-based counters. Safe for
+        RedisClient.register(DatabaseCommandCounter)
       end
 
-      if Familia.enable_redis_counter
-        # NOTE: This middleware stays thread-safe with a mutex so it will
-        # be a bottleneck when enabled in multi-threaded environments.
-        RedisClient.register(RedisCommandCounter)
+      dbclient = Redis.new(parsed_uri.conf)
+
+      if @database_clients.key?(serverid)
+        msg = "Overriding existing connection for #{serverid}"
+        Familia.warn(msg)
       end
 
-      redis = Redis.new(conf)
+      @database_clients[serverid] = dbclient
+    end
+
+    def reconnect(uri = nil)
+      parsed_uri = normalize_uri(uri)
+      serverid = parsed_uri.serverid
 
       # Close the existing connection if it exists
-      @redis_clients[uri.serverid].close if @redis_clients[uri.serverid]
-      @redis_clients[uri.serverid] = redis
+      @database_clients[serverid].close if @database_clients.key?(serverid)
+
+      connect(parsed_uri)
     end
 
-    # Retrieves or creates a Redis client for the given URI.
+    # Retrieves a Database connection from the appropriate pool.
+    # Handles DB selection automatically based on the URI.
     #
-    # @param uri [String, URI, nil] The URI of the Redis server.
-    #   If nil, uses the default URI.
-    # @return [Redis] The Redis client for the specified URI
+    # @return [Redis] The Database client for the specified URI
     # @example
-    #   Familia.redis('redis://localhost:6379')
-    def redis(uri = nil)
-      if uri.is_a?(Integer)
-        tmp = Familia.uri
-        tmp.db = uri
-        uri = tmp
-      elsif uri.is_a?(String)
-        uri &&= URI.parse uri
+    #   Familia.dbclient('redis://localhost:6379/1')
+    #   Familia.dbclient(2)  # Use DB 2 with default server
+    def dbclient(uri = nil)
+      # First priority: Thread-local connection (middleware pattern)
+      return Thread.current[:familia_connection] if Thread.current.key?(:familia_connection)
+
+      # Second priority: Connection provider
+      if connection_provider
+        # Always pass normalized URI with database to provider
+        # Provider MUST return connection already on the correct database
+        parsed_uri = normalize_uri(uri)
+        connection = connection_provider.call(parsed_uri.to_s)
+        
+        # In debug mode, verify the provider honored the contract
+        if Familia.debug? && connection.respond_to?(:client)
+          current_db = connection.client.db
+          expected_db = parsed_uri.db || 0
+          if current_db != expected_db
+            Familia.warn "Connection provider returned connection on DB #{current_db}, expected #{expected_db}"
+          end
+        end
+        
+        return connection
+      end
+
+      # Third priority: Fallback behavior or error
+      raise Familia::NoConnectionAvailable, 'No connection available.' if connection_required
+
+      # Legacy behavior: create connection
+      parsed_uri = normalize_uri(uri)
+
+      # Only cache when no specific URI/DB is requested to avoid DB conflicts
+      if uri.nil?
+        @dbclient ||= connect(parsed_uri)
+        @dbclient.select(parsed_uri.db) if parsed_uri.db
+        @dbclient
+      else
+        # When a specific DB is requested, create a new connection
+        # to avoid conflicts with cached connections
+        connection = connect(parsed_uri)
+        connection.select(parsed_uri.db) if parsed_uri.db
+        connection
       end
-      uri ||= Familia.uri
-      connect(uri) unless @redis_clients[uri.serverid]
-      @redis_clients[uri.serverid]
     end
 
-    # Retrieves the Redis client associated with the given class.
+    # Executes Database commands atomically within a transaction (MULTI/EXEC).
+    #
+    # Database transactions queue commands and execute them atomically as a single unit.
+    # All commands succeed together or all fail together, ensuring data consistency.
     #
-    # @param klass [Class] The class for which to retrieve the Redis client.
-    # @return [Redis] The Redis client associated with the given class.
-    def redis_uri_by_class(klass)
-      uri = @redis_uri_by_class[klass]
-      connect(uri)
+    # @yield [Redis] The Database transaction connection
+    # @return [Array] Results of all commands executed in the transaction
+    #
+    # @example Basic transaction usage
+    #   Familia.transaction do |trans|
+    #     trans.set("key1", "value1")
+    #     trans.incr("counter")
+    #     trans.lpush("list", "item")
+    #   end
+    #   # Returns: ["OK", 2, 1] - results of all commands
+    #
+    # @note **Comparison of Database batch operations:**
+    #
+    #   | Feature         | Multi/Exec      | Pipeline        |
+    #   |-----------------|-----------------|-----------------|
+    #   | Atomicity       | Yes             | No              |
+    #   | Performance     | Good            | Better          |
+    #   | Error handling  | All-or-nothing  | Per-command     |
+    #   | Use case        | Data consistency| Bulk operations |
+    #
+    def transaction(&)
+      block_result = nil
+      result = dbclient.multi do |conn|
+        Fiber[:familia_transaction] = conn
+        begin
+          block_result = yield(conn) # rubocop:disable Lint/UselessAssignment
+        ensure
+          Fiber[:familia_transaction] = nil # cleanup reference
+        end
+      end
+      # Return the multi result which contains the transaction results
+      result
     end
+    alias multi transaction
 
-    # Sets the default URI for Redis connections.
+    # Executes Database commands in a pipeline for improved performance.
     #
-    # @param v [String, URI] The new default URI
-    # @example
-    #   Familia.uri = 'redis://localhost:6379'
-    def uri=(val)
-      @uri = val.is_a?(URI) ? v : URI.parse(val)
+    # Pipelines send multiple commands without waiting for individual responses,
+    # reducing network round-trips. Commands execute independently and can
+    # succeed or fail without affecting other commands in the pipeline.
+    #
+    # @yield [Redis] The Database pipeline connection
+    # @return [Array] Results of all commands executed in the pipeline
+    #
+    # @example Basic pipeline usage
+    #   Familia.pipeline do |pipe|
+    #     pipe.set("key1", "value1")
+    #     pipe.incr("counter")
+    #     pipe.lpush("list", "item")
+    #   end
+    #   # Returns: ["OK", 2, 1] - results of all commands
+    #
+    # @example Error handling - commands succeed/fail independently
+    #   results = Familia.pipeline do |conn|
+    #     conn.set("valid_key", "value")     # This will succeed
+    #     conn.incr("string_key")            # This will fail (wrong type)
+    #     conn.set("another_key", "value2")  # This will still succeed
+    #   end
+    #   # Returns: ["OK", Redis::CommandError, "OK"]
+    #   # Notice how the error doesn't prevent other commands from executing
+    #
+    # @example Contrast with transaction behavior
+    #   results = Familia.transaction do |conn|
+    #     conn.set("inventory:item1", 100)
+    #     conn.incr("invalid_key")        # Fails, rolls back everything
+    #     conn.set("inventory:item2", 200) # Won't be applied
+    #   end
+    #   # Result: neither item1 nor item2 are set due to the error
+    #
+    def pipeline(&)
+      block_result = nil
+      result = dbclient.pipelined do |conn|
+        Fiber[:familia_pipeline] = conn
+        begin
+          block_result = yield(conn) # rubocop:disable Lint/UselessAssignment
+        ensure
+          Fiber[:familia_pipeline] = nil # cleanup reference
+        end
+      end
+      # Return the pipeline result which contains the command results
+      result
     end
 
-    alias url uri
-    alias url= uri=
+    # Provides explicit access to a Database connection.
+    #
+    # This method is useful when you need direct access to a connection
+    # for operations not covered by other methods. The connection is 
+    # properly managed and returned to the pool (if using connection_provider).
+    #
+    # @yield [Redis] A Database connection
+    # @return The result of the block
+    #
+    # @example Using with_connection for custom operations
+    #   Familia.with_connection do |conn|
+    #     conn.set("custom_key", "value")
+    #     conn.expire("custom_key", 3600)
+    #   end
+    #
+    def with_connection(&block)
+      yield dbclient
+    end
+
+    private
+
+    # Normalizes various URI formats to a consistent URI object
+    def normalize_uri(uri)
+      case uri
+      when Integer
+        new_uri = Familia.uri.dup
+        new_uri.db = uri
+        new_uri
+      when ->(obj) { obj.is_a?(String) || obj.instance_of?(::String) }
+        URI.parse(uri)
+      when URI
+        uri
+      when nil
+        Familia.uri
+      else
+        raise ArgumentError, "Invalid URI type: #{uri.class.name}"
+      end
+    end
   end
 end

data/lib/familia/core_ext.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: true
+# lib/familia/core_ext.rb
 
 # Extends the String class with time-related functionality
 #

data/lib/familia/datatype/commands.rb

@@ -0,0 +1,59 @@
+# lib/familia/datatype/commands.rb
+
+class Familia::DataType
+
+  # Must be included in all DataType classes to provide Redis
+  # commands. The class must have a dbkey method.
+  module Commands
+
+    def move(logical_database)
+      dbclient.move dbkey, logical_database
+    end
+
+    def rename(newkey)
+      dbclient.rename dbkey, newkey
+    end
+
+    def renamenx(newkey)
+      dbclient.renamenx dbkey, newkey
+    end
+
+    def type
+      dbclient.type dbkey
+    end
+
+    # Deletes the entire dbkey
+    # @return [Boolean] true if the key was deleted, false otherwise
+    def delete!
+      Familia.trace :DELETE!, dbclient, uri, caller(1..1) if Familia.debug?
+      ret = dbclient.del dbkey
+      ret.positive?
+    end
+    alias clear delete!
+
+    def exists?
+      dbclient.exists(dbkey) && !size.zero?
+    end
+
+    def current_expiration
+      dbclient.ttl dbkey
+    end
+
+    def expire(sec)
+      dbclient.expire dbkey, sec.to_i
+    end
+
+    def expireat(unixtime)
+      dbclient.expireat dbkey, unixtime
+    end
+
+    def persist
+      dbclient.persist dbkey
+    end
+
+    def echo(meth, trace)
+      dbclient.echo "[#{self.class}\##{meth}] #{trace} (#{@opts[:class]}\#)"
+    end
+
+  end
+end

data/lib/familia/{redistype → datatype}/serialization.rb

@@ -1,6 +1,6 @@
-# rubocop:disable all
+# lib/familia/datatype/serialization.rb
 
-class Familia::RedisType
+class Familia::DataType
 
   module Serialization
 
@@ -29,7 +29,7 @@ class Familia::RedisType
     def serialize_value(val, strict_values: true)
       prepared = nil
 
-      Familia.trace :TOREDIS, redis, "#{val}<#{val.class}|#{opts[:class]}>", caller(1..1) if Familia.debug?
+      Familia.trace :TOREDIS, dbclient, "#{val}<#{val.class}|#{opts[:class]}>", caller(1..1) if Familia.debug?
 
       if opts[:class]
         prepared = Familia.distinguisher(opts[:class], strict_values: strict_values)
@@ -42,12 +42,11 @@ class Familia::RedisType
         Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
       end
 
-      Familia.trace :TOREDIS, redis, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>", caller(1..1) if Familia.debug?
+      Familia.trace :TOREDIS, dbclient, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>", caller(1..1) if Familia.debug?
 
       Familia.warn "[#{self.class}\#serialize_value] nil returned for #{opts[:class]}\##{name}" if prepared.nil?
       prepared
     end
-    alias to_redis serialize_value
 
     # Deserializes multiple values from Redis, removing nil values.
     #
@@ -63,7 +62,6 @@ class Familia::RedisType
       # expected value.
       deserialize_values_with_nil(*values).compact
     end
-    alias from_redis deserialize_values
 
     # Deserializes multiple values from Redis, preserving nil values.
     #
@@ -97,16 +95,15 @@ class Familia::RedisType
         val
       rescue StandardError => e
         Familia.info val
-        Familia.info "Parse error for #{rediskey} (#{load_method}): #{e.message}"
+        Familia.info "Parse error for #{dbkey} (#{load_method}): #{e.message}"
         Familia.info e.backtrace
         nil
       end
 
       values
     end
-    alias from_redis_with_nil deserialize_values_with_nil
 
-    # Deserializes a single value from Redis.
+    # Deserializes a single value from the database.
     #
     # @param val [String, nil] The value to deserialize.
     # @return [Object, nil] The deserialized object, the default value if
@@ -115,10 +112,10 @@ class Familia::RedisType
     # @note If no class option is specified, the original value is
     #   returned unchanged.
     #
-    # NOTE: Currently only the RedisType class uses this method. Horreum
+    # NOTE: Currently only the DataType class uses this method. Horreum
     # fields are a newer addition and don't support the full range of
-    # deserialization options that RedisType supports. It uses to_redis
-    # for serialization since everything becomes a string in Redis.
+    # deserialization options that DataType supports. It uses serialize_value
+    # for serialization since everything becomes a string in Valkey.
     #
     def deserialize_value(val)
       return @opts[:default] if val.nil?
@@ -127,7 +124,6 @@ class Familia::RedisType
       ret = deserialize_values val
       ret&.first # return the object or nil
     end
-    alias from_redis deserialize_value
   end
 
 end