familia 1.2.1 → 2.0.0.pre2

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
+      parsed_uri = normalize_uri(uri)
+      serverid = parsed_uri.serverid
 
-      raise ArgumentError, 'No URI specified' unless uri
-
-      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).
     #
-    # @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)
+    # Database transactions queue commands and execute them atomically as a single unit.
+    # All commands succeed together or all fail together, ensuring data consistency.
+    #
+    # @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

data/lib/familia/{redistype → datatype}/types/hashkey.rb

@@ -1,11 +1,11 @@
-# frozen_string_literal: true
+# lib/familia/datatype/types/hashkey.rb
 
 module Familia
-  class HashKey < RedisType
+  class HashKey < DataType
     # Returns the number of fields in the hash
     # @return [Integer] number of fields
     def field_count
-      redis.hlen rediskey
+      dbclient.hlen dbkey
     end
     alias size field_count
 
@@ -16,22 +16,22 @@ module Familia
     # +return+ [Integer] Returns 1 if the field is new and added, 0 if the
     #  field already existed and the value was updated.
     def []=(field, val)
-      ret = redis.hset rediskey, field.to_s, serialize_value(val)
+      ret = dbclient.hset dbkey, field.to_s, serialize_value(val)
       update_expiration
       ret
     rescue TypeError => e
       Familia.le "[hset]= #{e.message}"
-      Familia.ld "[hset]= #{rediskey} #{field}=#{val}" if Familia.debug
-      echo :hset, caller(1..1).first if Familia.debug # logs via echo to redis and back
+      Familia.ld "[hset]= #{dbkey} #{field}=#{val}" if Familia.debug
+      echo :hset, caller(1..1).first if Familia.debug # logs via echo to the db and back
       klass = val.class
-      msg = "Cannot store #{field} => #{val.inspect} (#{klass}) in #{rediskey}"
+      msg = "Cannot store #{field} => #{val.inspect} (#{klass}) in #{dbkey}"
       raise e.class, msg
     end
     alias put []=
     alias store []=
 
     def [](field)
-      deserialize_value redis.hget(rediskey, field.to_s)
+      deserialize_value dbclient.hget(dbkey, field.to_s)
     end
     alias get []
 
@@ -47,22 +47,22 @@ module Familia
     end
 
     def keys
-      redis.hkeys rediskey
+      dbclient.hkeys dbkey
     end
 
     def values
-      redis.hvals(rediskey).map { |v| deserialize_value v }
+      dbclient.hvals(dbkey).map { |v| deserialize_value v }
     end
 
     def hgetall
-      redis.hgetall(rediskey).each_with_object({}) do |(k,v), ret|
+      dbclient.hgetall(dbkey).each_with_object({}) do |(k,v), ret|
         ret[k] = deserialize_value v
       end
     end
     alias all hgetall
 
     def key?(field)
-      redis.hexists rediskey, field.to_s
+      dbclient.hexists dbkey, field.to_s
     end
     alias has_key? key?
     alias include? key?
@@ -72,12 +72,12 @@ module Familia
     # @param field [String] The field to remove
     # @return [Integer] The number of fields that were removed (0 or 1)
     def remove_field(field)
-      redis.hdel rediskey, field.to_s
+      dbclient.hdel dbkey, field.to_s
     end
     alias remove remove_field # deprecated
 
     def increment(field, by = 1)
-      redis.hincrby(rediskey, field.to_s, by).to_i
+      dbclient.hincrby(dbkey, field.to_s, by).to_i
     end
     alias incr increment
     alias incrby increment
@@ -93,7 +93,7 @@ module Familia
 
       data = hsh.inject([]) { |ret, pair| ret << [pair[0], serialize_value(pair[1])] }.flatten
 
-      ret = redis.hmset(rediskey, *data)
+      ret = dbclient.hmset(dbkey, *data)
       update_expiration
       ret
     end
@@ -101,11 +101,11 @@ module Familia
 
     def values_at *fields
       string_fields = fields.flatten.compact.map(&:to_s)
-      elements = redis.hmget(rediskey, *string_fields)
+      elements = dbclient.hmget(dbkey, *string_fields)
       deserialize_values(*elements)
     end
 
-    # The Great Redis Refresh-o-matic 3000 for HashKey!
+    # The Great Database Refresh-o-matic 3000 for HashKey!
     #
     # This method performs a complete refresh of the hash's state from Redis.
     # It's like giving your hash a memory transfusion - out with the old state,
@@ -117,7 +117,7 @@ module Familia
     # @return [void] Returns nothing, but your hash will be sparkling clean
     #   with all its fields synchronized with Redis.
     #
-    # @raise [Familia::KeyNotFoundError] If the Redis key for this hash no
+    # @raise [Familia::KeyNotFoundError] If the dbkey for this hash no
     #   longer exists. Time travelers beware!
     #
     # @example Basic usage
@@ -127,14 +127,14 @@ module Familia
     #   begin
     #     my_hash.refresh!
     #   rescue Familia::KeyNotFoundError
-    #     puts "Oops! Our hash seems to have vanished into the Redis void!"
+    #     puts "Oops! Our hash seems to have vanished into the Database void!"
     #   end
     def refresh!
-      Familia.trace :REFRESH, redis, redisuri, caller(1..1) if Familia.debug?
-      raise Familia::KeyNotFoundError, rediskey unless redis.exists(rediskey)
+      Familia.trace :REFRESH, dbclient, uri, caller(1..1) if Familia.debug?
+      raise Familia::KeyNotFoundError, dbkey unless dbclient.exists(dbkey)
 
       fields = hgetall
-      Familia.ld "[refresh!] #{self.class} #{rediskey} #{fields.keys}"
+      Familia.ld "[refresh!] #{self.class} #{dbkey} #{fields.keys}"
 
       # For HashKey, we update by merging the fresh data
       update(fields)
@@ -148,7 +148,7 @@ module Familia
     #
     # @return [self] Returns the refreshed hash, ready for more adventures!
     #
-    # @raise [Familia::KeyNotFoundError] If the Redis key does not exist.
+    # @raise [Familia::KeyNotFoundError] If the dbkey does not exist.
     #   The hash must exist in Redis-land for this to work!
     #
     # @example Refresh and chain
@@ -161,7 +161,7 @@ module Familia
       self
     end
 
-    Familia::RedisType.register self, :hash # legacy, deprecated
-    Familia::RedisType.register self, :hashkey
+    Familia::DataType.register self, :hash # legacy, deprecated
+    Familia::DataType.register self, :hashkey
   end
 end