familia 2.0.0.pre18 → 2.0.0.pre19

data/lib/familia/connection/behavior.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+# lib/familia/connection/behavior.rb
+
+module Familia
+  module Connection
+    # Shared connection behavior for both Horreum and DataType classes
+    #
+    # This module extracts common connection management functionality that was
+    # previously duplicated between Horreum::Connection and DataType::Connection.
+    # It provides:
+    #
+    # * URI normalization with logical_database support
+    # * Connection creation methods
+    # * Transaction and pipeline execution methods
+    # * Consistent connection API across object types
+    #
+    # Classes including this module must implement:
+    # * `dbclient(uri = nil)` - Connection resolution method
+    # * `build_connection_chain` (private) - Chain of Responsibility setup
+    #
+    # @example Basic usage in a class
+    #   class MyDataStore
+    #     include Familia::Connection::Behavior
+    #
+    #     def dbclient(uri = nil)
+    #       @connection_chain ||= build_connection_chain
+    #       @connection_chain.handle(uri)
+    #     end
+    #
+    #     private
+    #
+    #     def build_connection_chain
+    #       # ... handler setup ...
+    #     end
+    #   end
+    #
+    module Behavior
+      def self.included(base)
+        base.class_eval do
+          attr_writer :dbclient
+          attr_reader :uri
+        end
+      end
+
+      # Normalizes various URI formats to a consistent URI object
+      #
+      # Handles multiple input types and considers the logical_database setting
+      # when uri is nil or Integer. This method is public so connection handlers
+      # can use it for consistent URI processing.
+      #
+      # @param uri [Integer, String, URI, nil] The URI to normalize
+      # @return [URI] Normalized URI object
+      # @raise [ArgumentError] If URI type is invalid
+      #
+      # @example Integer database number
+      #   normalize_uri(2)  # => URI with db=2 on default server
+      #
+      # @example String URI
+      #   normalize_uri('redis://localhost:6379/1')
+      #
+      # @example nil with logical_database
+      #   class MyModel
+      #     include Familia::Connection::Behavior
+      #     attr_accessor :logical_database
+      #   end
+      #   model = MyModel.new
+      #   model.logical_database = 3
+      #   model.normalize_uri(nil)  # => URI with db=3
+      #
+      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
+          # Use logical_database if available, otherwise fall back to Familia.uri
+          if respond_to?(:logical_database) && logical_database
+            new_uri = Familia.uri.dup
+            new_uri.db = logical_database
+            new_uri
+          else
+            Familia.uri
+          end
+        else
+          raise ArgumentError, "Invalid URI type: #{uri.class.name}"
+        end
+      end
+
+      # Creates a new Database connection instance
+      #
+      # This method always creates a fresh connection and does not use caching.
+      # Each call returns a new Redis client instance that you are responsible
+      # for managing and closing when done.
+      #
+      # @param uri [String, URI, Integer, nil] The URI of the Database server
+      # @return [Redis] A new Database client connection
+      #
+      # @example Creating a new connection
+      #   client = create_dbclient('redis://localhost:6379/1')
+      #   client.ping
+      #   client.close
+      #
+      def create_dbclient(uri = nil)
+        parsed_uri = normalize_uri(uri)
+        Familia.create_dbclient(parsed_uri)
+      end
+
+      # Alias for create_dbclient (backward compatibility)
+      def connect(*)
+        create_dbclient(*)
+      end
+
+      # Sets the URI for this object's database connection
+      #
+      # @param uri [String, URI, Integer] The new URI
+      # @return [URI] The normalized URI
+      #
+      def uri=(uri)
+        @uri = normalize_uri(uri)
+      end
+
+      # Alias for uri (backward compatibility)
+      def url
+        uri
+      end
+
+      # Alias for uri= (backward compatibility)
+      def url=(uri)
+        self.uri = uri
+      end
+
+      # Executes a Redis transaction (MULTI/EXEC) using this object's connection context
+      #
+      # Provides atomic execution of multiple Redis commands with automatic connection
+      # management and operation mode enforcement. Uses the object's database and
+      # connection settings. Returns a MultiResult object for consistency.
+      #
+      # @yield [Redis] conn The Redis connection configured for transaction mode
+      # @return [MultiResult] Result object with success status and command results
+      #
+      # @raise [Familia::OperationModeError] When called with incompatible connection handlers
+      #
+      # @example Basic transaction
+      #   obj.transaction do |conn|
+      #     conn.set('key1', 'value1')
+      #     conn.set('key2', 'value2')
+      #     conn.get('key1')
+      #   end
+      #
+      # @example Reentrant behavior
+      #   obj.transaction do |conn|
+      #     conn.set('outer', 'value')
+      #
+      #     # Nested transaction reuses same connection
+      #     obj.transaction do |inner_conn|
+      #       inner_conn.set('inner', 'value')
+      #     end
+      #   end
+      #
+      # @note Connection Inheritance:
+      #   - Uses object's logical_database setting if configured
+      #   - Inherits class-level database settings
+      #   - Falls back to instance-level dbclient if set
+      #   - Uses global connection chain as final fallback
+      #
+      # @note Transaction Context:
+      #   - When called outside global transaction: Creates local MultiResult
+      #   - When called inside global transaction: Yields to existing transaction
+      #   - Maintains proper Fiber-local state for nested calls
+      #
+      # @see Familia.transaction For global transaction method
+      # @see MultiResult For details on the return value structure
+      #
+      def transaction(&)
+        ensure_relatives_initialized! if respond_to?(:ensure_relatives_initialized!, true)
+        Familia::Connection::TransactionCore.execute_transaction(-> { dbclient }, &)
+      end
+
+      # Alias for transaction (alternate naming)
+      def multi(&)
+        transaction(&)
+      end
+
+      # Executes Redis commands in a pipeline using this object's connection context
+      #
+      # Batches multiple Redis commands together and sends them in a single network
+      # round-trip for improved performance. Uses the object's database and connection
+      # settings. Returns a MultiResult object for consistency.
+      #
+      # @yield [Redis] conn The Redis connection configured for pipelined mode
+      # @return [MultiResult] Result object with success status and command results
+      #
+      # @raise [Familia::OperationModeError] When called with incompatible connection handlers
+      #
+      # @example Basic pipeline
+      #   obj.pipelined do |conn|
+      #     conn.set('key1', 'value1')
+      #     conn.incr('counter')
+      #     conn.get('key1')
+      #   end
+      #
+      # @example Performance optimization
+      #   # Instead of multiple round-trips:
+      #   obj.save            # Round-trip 1
+      #   obj.increment_count # Round-trip 2
+      #   obj.update_timestamp # Round-trip 3
+      #
+      #   # Use pipeline for single round-trip:
+      #   obj.pipelined do |conn|
+      #     conn.hmset(obj.dbkey, obj.to_h)
+      #     conn.hincrby(obj.dbkey, 'count', 1)
+      #     conn.hset(obj.dbkey, 'updated_at', Time.now.to_i)
+      #   end
+      #
+      # @note Connection Inheritance:
+      #   - Uses object's logical_database setting if configured
+      #   - Inherits class-level database settings
+      #   - Falls back to instance-level dbclient if set
+      #   - Uses global connection chain as final fallback
+      #
+      # @note Pipeline Context:
+      #   - When called outside global pipeline: Creates local MultiResult
+      #   - When called inside global pipeline: Yields to existing pipeline
+      #   - Maintains proper Fiber-local state for nested calls
+      #
+      # @note Performance Considerations:
+      #   - Best for multiple independent operations
+      #   - Reduces network latency by batching commands
+      #   - Commands execute independently (some may succeed, others fail)
+      #
+      # @see Familia.pipelined For global pipeline method
+      # @see MultiResult For details on the return value structure
+      # @see #transaction For atomic command execution
+      #
+      def pipelined(&block)
+        ensure_relatives_initialized! if respond_to?(:ensure_relatives_initialized!, true)
+        Familia::Connection::PipelineCore.execute_pipeline(-> { dbclient }, &block)
+      end
+
+      # Alias for pipelined (alternate naming)
+      def pipeline(&block)
+        pipelined(&block)
+      end
+    end
+  end
+end

data/lib/familia/connection/handlers.rb

@@ -219,5 +219,100 @@ module Familia
         dbclient
       end
     end
+
+    # Handler for delegating connection resolution to parent object
+    #
+    # Used by DataType objects that are attached to a parent (Horreum instance or class).
+    # Delegates the connection resolution to the parent's dbclient method, which allows
+    # DataType objects to inherit connection settings, logical_database, and transaction
+    # context from their parent.
+    #
+    # This preserves the existing architectural pattern where DataType objects owned by
+    # Horreum models use the parent's connection chain. This is the primary behavior
+    # for DataType objects in typical usage.
+    #
+    # @example Instance-level DataType with parent
+    #   user = User.new(userid: 'user_123')
+    #   user.tags  # DataType that delegates to user.dbclient
+    #
+    # @example Class-level DataType with parent
+    #   User.global_users  # DataType that delegates to User.dbclient
+    #
+    class ParentDelegationHandler < BaseConnectionHandler
+      @allows_transaction = true
+      @allows_pipelined = true
+
+      def initialize(data_type)
+        @data_type = data_type
+      end
+
+      def handle(uri)
+        return nil unless @data_type.parent
+
+        # Delegate to parent's connection chain
+        # Parent can be either a Horreum class or instance
+        parent_connection = @data_type.parent.dbclient(uri)
+
+        if parent_connection
+          Familia.trace :DBCLIENT_PARENT_DELEGATION, @data_type.dbkey,
+                       "Using parent connection from #{@data_type.parent.class}"
+        end
+
+        parent_connection
+      end
+    end
+
+    # Handler for standalone DataType objects without a parent
+    #
+    # Provides connection resolution for DataType objects that are created independently
+    # rather than being attached to a Horreum model. Checks for instance-level @dbclient
+    # first, then falls back to creating a connection based on logical_database option
+    # or global Familia connection.
+    #
+    # This enables standalone DataType usage patterns like Rack::Session implementations
+    # where DataType objects need independent connection management and transaction support.
+    #
+    # @example Standalone DataType with custom connection
+    #   leaderboard = Familia::SortedSet.new('game:leaderboard')
+    #   leaderboard.dbclient = ConnectionPool.new { Redis.new }
+    #
+    # @example Standalone DataType with logical_database option
+    #   cache = Familia::HashKey.new('app:cache', logical_database: 2)
+    #
+    class StandaloneConnectionHandler < BaseConnectionHandler
+      @allows_transaction = true
+      @allows_pipelined = true
+
+      def initialize(data_type)
+        @data_type = data_type
+      end
+
+      def handle(uri)
+        # If a specific URI is provided, always use it to get a connection.
+        if uri
+          connection = Familia.dbclient(uri)
+          Familia.trace :DBCLIENT_STANDALONE_DATATYPE, @data_type.dbkey,
+                       "Created standalone connection for specific URI: #{uri}"
+          return connection
+        end
+
+        # Use instance @dbclient if explicitly set and no URI was passed
+        instance_dbclient = @data_type.instance_variable_get(:@dbclient)
+        if instance_dbclient
+          Familia.trace :DBCLIENT_DATATYPE_INSTANCE, @data_type.dbkey,
+                       'Using DataType instance @dbclient'
+          return instance_dbclient
+        end
+
+        # Fall back to creating connection based on opts or global
+        target_uri = @data_type.opts[:logical_database]
+        connection = Familia.dbclient(target_uri)
+
+        Familia.trace :DBCLIENT_STANDALONE_DATATYPE, @data_type.dbkey,
+                     "Created standalone connection for #{target_uri || 'default'}"
+
+        connection
+      end
+    end
   end
 end

data/lib/familia/connection/operation_core.rb

@@ -45,7 +45,7 @@ module Familia
         when :transaction
           Familia.transaction_mode
         when :pipeline
-          Familia.pipeline_mode
+          Familia.pipelined_mode
         else
           :strict
         end

data/lib/familia/connection/{pipeline_core.rb → pipelined_core.rb}

@@ -16,7 +16,7 @@ module Familia
       #
       # Handles pipeline execution based on connection handler capabilities.
       # When handler doesn't support pipelines, fallback behavior is controlled
-      # by Familia.pipeline_mode setting.
+      # by Familia.pipelined_mode setting.
       #
       # @param dbclient_proc [Proc] Lambda that returns the Redis connection
       # @param block [Proc] Block containing Redis commands to execute
@@ -32,7 +32,7 @@ module Familia
       #   result.results     # => ["OK", 1]
       #
       # @example With fallback modes
-      #   Familia.configure { |c| c.pipeline_mode = :permissive }
+      #   Familia.configure { |c| c.pipelined_mode = :permissive }
       #   result = PipelineCore.execute_pipeline(-> { cached_conn }) do |conn|
       #     conn.set('key', 'value')  # Executes individually, no error
       #   end

data/lib/familia/connection/transaction_core.rb

@@ -34,27 +34,25 @@ module Familia
       #   result.successful?  # => true/false
       #   result.results     # => ["OK", 1]
       #
-      def self.execute_transaction(dbclient_proc, &block)
+      def self.execute_transaction(dbclient_proc, &)
         # First, get the connection to populate the handler class
-        connection = dbclient_proc.call
+        dbclient_proc.call
         handler_class = Fiber[:familia_connection_handler_class]
 
         # Check transaction capability
         transaction_capability = handler_class&.allows_transaction
 
         if transaction_capability == false
-          handle_transaction_fallback(dbclient_proc, handler_class, &block)
+          handle_transaction_fallback(dbclient_proc, handler_class, &)
         elsif transaction_capability == :reentrant
           # Already in transaction, just yield the connection
           yield(Fiber[:familia_transaction])
         else
           # Normal transaction flow (includes nil, true, and other values)
-          execute_normal_transaction(dbclient_proc, &block)
+          execute_normal_transaction(dbclient_proc, &)
         end
       end
 
-      private
-
       # Handles transaction fallback based on configured transaction mode
       #
       # Delegates to OperationCore.handle_fallback for consistent behavior
@@ -65,8 +63,8 @@ module Familia
       # @param block [Proc] Block containing Redis commands to execute
       # @return [MultiResult] Result from individual command execution or raises error
       #
-      def self.handle_transaction_fallback(dbclient_proc, handler_class, &block)
-        OperationCore.handle_fallback(:transaction, dbclient_proc, handler_class, &block)
+      def self.handle_transaction_fallback(dbclient_proc, handler_class, &)
+        OperationCore.handle_fallback(:transaction, dbclient_proc, handler_class, &)
       end
 
       # Executes a normal Redis transaction using MULTI/EXEC
@@ -78,7 +76,7 @@ module Familia
       # @param block [Proc] Block containing Redis commands to execute
       # @return [MultiResult] Result object with transaction command results
       #
-      def self.execute_normal_transaction(dbclient_proc, &block)
+      def self.execute_normal_transaction(dbclient_proc)
         # Check for existing transaction context
         return yield(Fiber[:familia_transaction]) if Fiber[:familia_transaction]
 

data/lib/familia/connection.rb

@@ -1,12 +1,13 @@
 # lib/familia/connection.rb
 
+require_relative 'connection/behavior'
 require_relative 'connection/handlers'
 require_relative 'connection/middleware'
 require_relative 'connection/operations'
 require_relative 'connection/individual_command_proxy'
 require_relative 'connection/operation_core'
 require_relative 'connection/transaction_core'
-require_relative 'connection/pipeline_core'
+require_relative 'connection/pipelined_core'
 
 # Familia
 #
@@ -42,7 +43,7 @@ module Familia
       @connection_chain = nil # Force rebuild of chain
     end
 
-# Sets the default URI for Database connections.
+    # 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.

data/lib/familia/data_type/connection.rb

@@ -5,21 +5,104 @@ module Familia
     # Connection - Instance-level connection and key generation methods
     #
     # This module provides instance methods for database connection resolution
-    # and Redis key generation for DataType objects.
+    # and Redis key generation for DataType objects. It includes shared connection
+    # behavior from Familia::Connection::Behavior, enabling transaction and pipeline
+    # support for both parent-owned and standalone DataType objects.
     #
     # Key features:
     # * Database connection resolution with Chain of Responsibility pattern
     # * Redis key generation based on parent context
     # * Direct database access for advanced operations
+    # * Transaction support (MULTI/EXEC) for atomic operations
+    # * Pipeline support for batched command execution
+    # * Parent delegation for owned DataType objects
+    # * Standalone connection management for independent DataType objects
+    #
+    # Connection Chain Priority:
+    # 1. FiberTransactionHandler - Active transaction context
+    # 2. FiberConnectionHandler - Fiber-local connections
+    # 3. ProviderConnectionHandler - User-defined connection provider
+    # 4. ParentDelegationHandler - Delegate to parent object (primary for owned DataTypes)
+    # 5. StandaloneConnectionHandler - Independent DataType connection
+    #
+    # @example Parent-owned DataType (automatic delegation)
+    #   class User < Familia::Horreum
+    #     logical_database 2
+    #     zset :scores
+    #   end
+    #
+    #   user = User.new(userid: 'user_123')
+    #   user.scores.transaction do |conn|
+    #     conn.zadd(user.scores.dbkey, 100, 'level1')
+    #     conn.zadd(user.scores.dbkey, 200, 'level2')
+    #   end
+    #
+    # @example Standalone DataType with transaction
+    #   leaderboard = Familia::SortedSet.new('game:leaderboard')
+    #   leaderboard.transaction do |conn|
+    #     conn.zadd(leaderboard.dbkey, 500, 'player1')
+    #     conn.zadd(leaderboard.dbkey, 600, 'player2')
+    #   end
     #
     module Connection
-      # TODO: Replace with Chain of Responsibility pattern
-      def dbclient
+      include Familia::Connection::Behavior
+
+      # Returns the effective URI this DataType will use for connections
+      #
+      # For parent-owned DataTypes, delegates to parent's URI.
+      # For standalone DataTypes with logical_database option, constructs URI with that database.
+      # For standalone DataTypes without options, returns global Familia.uri.
+      # Explicit @uri assignment (via uri=) takes precedence.
+      #
+      # @return [URI, nil] The URI for database connections
+      #
+      def uri
+        return @uri if defined?(@uri) && @uri
+        return parent.uri if parent && parent.respond_to?(:uri)
+
+        # Check opts[:logical_database] first, then parent's logical_database
+        db_num = opts[:logical_database]
+        db_num ||= parent.logical_database if parent && parent.respond_to?(:logical_database)
+
+        if db_num
+          # Create a new URI with the database number but without custom port
+          # This ensures consistent URI representation (e.g., redis://host/db not redis://host:port/db)
+          base_uri = Familia.uri
+          URI.parse("redis://#{base_uri.host}/#{db_num}")
+        else
+          Familia.uri
+        end
+      end
+
+      # Retrieves a Database connection using the Chain of Responsibility pattern
+      #
+      # Implements connection resolution optimized for DataType usage patterns:
+      # - Fast path check for active transaction context
+      # - Full connection chain for comprehensive resolution
+      # - Parent delegation as primary behavior for owned DataTypes
+      # - Standalone connection handling for independent DataTypes
+      #
+      # Note: We don't cache the connection chain in an instance variable because
+      # DataType objects are frozen for thread safety. Building the chain is cheap
+      # (just creating handler objects), and the actual connection resolution work
+      # is done by the handlers themselves.
+      #
+      # @param uri [String, URI, Integer, nil] Optional URI for database selection
+      # @return [Redis] The Database client for the specified URI
+      #
+      # @example Getting connection from parent-owned DataType
+      #   user.tags.dbclient  # Delegates to user.dbclient
+      #
+      # @example Getting connection from standalone DataType
+      #   cache = Familia::HashKey.new('app:cache', logical_database: 2)
+      #   cache.dbclient  # Uses standalone handler with db 2
+      #
+      def dbclient(uri = nil)
+        # Fast path for transaction context (highest priority)
         return Fiber[:familia_transaction] if Fiber[:familia_transaction]
-        return @dbclient if @dbclient
 
-        # Delegate to parent if present, otherwise fall back to Familia
-        parent ? parent.dbclient : Familia.dbclient(opts[:logical_database])
+        # Build connection chain (not cached due to frozen objects)
+        build_connection_chain.handle(uri)
       end
 
       # Produces the full dbkey for this object.
@@ -75,8 +158,69 @@ module Familia
       # Provides a structured way to "gear down" to run db commands that are
       # not implemented in our DataType classes since we intentionally don't
       # have a method_missing method.
+      #
+      # Enhanced to work seamlessly with transactions and pipelines. When called
+      # within a transaction or pipeline context, uses that connection automatically.
+      #
+      # @yield [Redis, String] Yields the connection and dbkey to the block
+      # @return The return value of the block
+      #
+      # @example Basic usage
+      #   datatype.direct_access do |conn, key|
+      #     conn.zadd(key, 100, 'member')
+      #   end
+      #
+      # @example Within transaction (automatic context detection)
+      #   datatype.transaction do |trans_conn|
+      #     datatype.direct_access do |conn, key|
+      #       # conn is the same as trans_conn
+      #       conn.zadd(key, 200, 'member')
+      #     end
+      #   end
+      #
       def direct_access
-        yield(dbclient, dbkey)
+        if Fiber[:familia_transaction]
+          # Already in transaction, use that connection
+          yield(Fiber[:familia_transaction], dbkey)
+        elsif Fiber[:familia_pipeline]
+          # Already in pipeline, use that connection
+          yield(Fiber[:familia_pipeline], dbkey)
+        else
+          yield(dbclient, dbkey)
+        end
+      end
+
+      private
+
+      # Builds the connection chain with handlers in priority order
+      #
+      # Creates the Chain of Responsibility for connection resolution with
+      # DataType-specific handlers. Handlers are checked in order:
+      #
+      # 1. FiberTransactionHandler - Return active transaction connection
+      # 2. FiberConnectionHandler - Use fiber-local connection
+      # 3. ProviderConnectionHandler - Delegate to connection provider
+      # 4. ParentDelegationHandler - Delegate to parent's connection (primary for owned DataTypes)
+      # 5. StandaloneConnectionHandler - Handle standalone DataTypes
+      #
+      # @return [ResponsibilityChain] Configured connection chain
+      #
+      def build_connection_chain
+        # Create fresh handler instances each time since DataType objects are frozen
+        # The chain itself is cached in @connection_chain, so this only runs once
+        fiber_connection_handler = Familia::Connection::FiberConnectionHandler.new
+        provider_connection_handler = Familia::Connection::ProviderConnectionHandler.new
+
+        # DataType-specific handlers for parent delegation and standalone usage
+        parent_delegation_handler = Familia::Connection::ParentDelegationHandler.new(self)
+        standalone_connection_handler = Familia::Connection::StandaloneConnectionHandler.new(self)
+
+        Familia::Connection::ResponsibilityChain.new
+          .add_handler(Familia::Connection::FiberTransactionHandler.instance)
+          .add_handler(fiber_connection_handler)
+          .add_handler(provider_connection_handler)
+          .add_handler(parent_delegation_handler)
+          .add_handler(standalone_connection_handler)
       end
     end
   end

data/lib/familia/data_type/database_commands.rb

@@ -22,11 +22,14 @@ module Familia
       end
 
       # Deletes the entire dbkey
-      # @return [Boolean] true if the key was deleted, false otherwise
+      #
+      # We return the dbclient.del command's return value instead of a friendly
+      # boolean b/c that logic doesn't work inside of a transaction. The return
+      # value in that case is a Redis::Future which based on the name indicates
+      # that the commend hasn't even run yet.
       def delete!
-        Familia.trace :DELETE!, nil, uri if Familia.debug?
-        ret = dbclient.del dbkey
-        ret.positive?
+        Familia.trace :DELETE!, nil, self.class.uri if Familia.debug?
+         dbclient.del dbkey
       end
       alias clear delete!
 

data/lib/familia/data_type/serialization.rb

@@ -117,7 +117,11 @@ module Familia
       # for serialization since everything becomes a string in Valkey.
       #
       def deserialize_value(val)
+        # Handle Redis::Future objects during transactions first
+        return val if val.is_a?(Redis::Future)
+
         return @opts[:default] if val.nil?
+
         return val unless @opts[:class]
 
         ret = deserialize_values val

data/lib/familia/data_type/types/hashkey.rb

@@ -152,7 +152,7 @@ module Familia
     #     puts "Oops! Our hash seems to have vanished into the Database void!"
     #   end
     def refresh!
-      Familia.trace :REFRESH, nil, uri if Familia.debug?
+      Familia.trace :REFRESH, nil, self.class.uri if Familia.debug?
       raise Familia::KeyNotFoundError, dbkey unless dbclient.exists(dbkey)
 
       fields = hgetall