familia 2.0.0.pre18 → 2.0.0.pre21

data/lib/familia/data_type/database_commands.rb

@@ -1,4 +1,6 @@
 # lib/familia/data_type/database_commands.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class DataType
@@ -22,11 +24,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

@@ -1,4 +1,6 @@
 # lib/familia/data_type/serialization.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class DataType
@@ -32,13 +34,13 @@ module Familia
 
         if opts[:class]
           prepared = Familia.identifier_extractor(opts[:class])
-          Familia.ld "  from opts[class] <#{opts[:class]}>: #{prepared || '<nil>'}"
+          Familia.debug "  from opts[class] <#{opts[:class]}>: #{prepared || '<nil>'}"
         end
 
         if prepared.nil?
           # Enforce strict values when no class option is specified
           prepared = Familia.identifier_extractor(val)
-          Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
+          Familia.debug "  from <#{val.class}> => <#{prepared.class}>"
         end
 
         if Familia.debug?
@@ -77,7 +79,7 @@ module Familia
       #   replaced with nil.
       #
       def deserialize_values_with_nil(*values)
-        Familia.ld "deserialize_values: (#{@opts}) #{values}"
+        Familia.debug "deserialize_values: (#{@opts}) #{values}"
         return [] if values.empty?
         return values.flatten unless @opts[:class]
 
@@ -89,7 +91,7 @@ module Familia
           next if obj.nil?
 
           val = @opts[:class].send load_method, obj
-          Familia.ld "[#{self.class}#deserialize_values] nil returned for #{@opts[:class]}##{name}" if val.nil?
+          Familia.debug "[#{self.class}#deserialize_values] nil returned for #{@opts[:class]}##{name}" if val.nil?
 
           val
         rescue StandardError => e
@@ -117,7 +119,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/settings.rb

@@ -1,4 +1,6 @@
 # lib/familia/data_type/settings.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class DataType

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

@@ -1,4 +1,6 @@
 # lib/familia/data_type/types/counter.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class Counter < StringKey

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

@@ -1,4 +1,6 @@
 # lib/familia/data_type/types/hashkey.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class HashKey < DataType
@@ -22,8 +24,8 @@ module Familia
       update_expiration
       ret
     rescue TypeError => e
-      Familia.le "[hset]= #{e.message}"
-      Familia.ld "[hset]= #{dbkey} #{field}=#{val}" if Familia.debug
+      Familia.error "[hset]= #{e.message}"
+      Familia.debug "[hset]= #{dbkey} #{field}=#{val}"
       echo :hset, Familia.pretty_stack(limit: 1) if Familia.debug # logs via echo to the db and back
       klass = val.class
       msg = "Cannot store #{field} => #{val.inspect} (#{klass}) in #{dbkey}"
@@ -74,8 +76,8 @@ module Familia
       update_expiration if ret == 1
       ret
     rescue TypeError => e
-      Familia.le "[hsetnx] #{e.message}"
-      Familia.ld "[hsetnx] #{dbkey} #{field}=#{val}" if Familia.debug
+      Familia.error "[hsetnx] #{e.message}"
+      Familia.debug "[hsetnx] #{dbkey} #{field}=#{val}"
       echo :hsetnx, Familia.pretty_stack(limit: 1) if Familia.debug # logs via echo to the db and back
       klass = val.class
       msg = "Cannot store #{field} => #{val.inspect} (#{klass}) in #{dbkey}"
@@ -152,11 +154,11 @@ 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
-      Familia.ld "[refresh!] #{self.class} #{dbkey} #{fields.keys}"
+      Familia.debug "[refresh!] #{self.class} #{dbkey} #{fields.keys}"
 
       # For HashKey, we update by merging the fresh data
       update(fields)

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

@@ -1,4 +1,6 @@
 # lib/familia/data_type/types/listkey.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class ListKey < DataType

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

@@ -1,4 +1,6 @@
 # lib/familia/data_type/types/lock.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class Lock < StringKey

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

@@ -1,4 +1,6 @@
 # lib/familia/data_type/types/sorted_set.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class SortedSet < DataType

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

@@ -1,4 +1,6 @@
 # lib/familia/data_type/types/stringkey.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class StringKey < DataType

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

@@ -1,4 +1,6 @@
 # lib/familia/data_type/types/unsorted_set.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # Familia::UnsortedSet

data/lib/familia/data_type.rb

@@ -1,4 +1,6 @@
 # lib/familia/data_type.rb
+#
+# frozen_string_literal: true
 
 require_relative 'data_type/class_methods'
 require_relative 'data_type/settings'

data/lib/familia/encryption/encrypted_data.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/encrypted_data.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Encryption
@@ -15,10 +17,10 @@ module Familia
           # Check for required fields
           required_fields = %i[algorithm nonce ciphertext auth_tag key_version]
           result = required_fields.all? { |field| parsed.key?(field) }
-          Familia.ld "[valid?] result: #{result}, parsed: #{parsed}, required: #{required_fields}"
+          Familia.debug "[valid?] result: #{result}, parsed: #{parsed}, required: #{required_fields}"
           result
         rescue Familia::SerializerError => e
-          Familia.ld "[valid?] JSON error: #{e.message}"
+          Familia.debug "[valid?] JSON error: #{e.message}"
           false
         end
       end

data/lib/familia/encryption/manager.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/manager.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Encryption

data/lib/familia/encryption/provider.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/provider.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Encryption

data/lib/familia/encryption/providers/aes_gcm_provider.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/providers/aes_gcm_provider.rb
+#
+# frozen_string_literal: true
 
 # ⚠️  RUBY MEMORY SAFETY WARNING ⚠️
 #

data/lib/familia/encryption/providers/secure_xchacha20_poly1305_provider.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/providers/secure_xchacha20_poly1305_provider.rb
+#
+# frozen_string_literal: true
 
 # ⚠️  PROTOTYPE IMPLEMENTATION - NOT FOR PRODUCTION USE ⚠️
 #

data/lib/familia/encryption/providers/xchacha20_poly1305_provider.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/providers/xchacha20_poly1305_provider.rb
+#
+# frozen_string_literal: true
 
 # ⚠️  RUBY MEMORY SAFETY WARNING ⚠️
 #

data/lib/familia/encryption/registry.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/registry.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Encryption

data/lib/familia/encryption/request_cache.rb

@@ -1,5 +1,7 @@
 # lib/familia/encryption/request_cache.rb
 #
+# frozen_string_literal: true
+
 # Request-scoped caching for encryption keys (if needed for performance)
 # This should ONLY be enabled if performance testing shows it's necessary
 #

data/lib/familia/encryption.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption.rb
+#
+# frozen_string_literal: true
 
 require 'base64'
 require 'oj'
@@ -60,9 +62,14 @@ module Familia
     #   end
     class << self
       # Get or create a manager with specific algorithm
+      #
+      # Thread-safe lazy initialization using Concurrent::Map to ensure
+      # only a single Manager instance is created per algorithm even under
+      # concurrent encryption/decryption requests.
+      #
       def manager(algorithm: nil)
-        @managers ||= {}
-        @managers[algorithm] ||= Manager.new(algorithm: algorithm)
+        @managers ||= Concurrent::Map.new
+        @managers.fetch_or_store(algorithm) { Manager.new(algorithm: algorithm) }
       end
 
       # Quick encryption with auto-selected best provider

data/lib/familia/errors.rb

@@ -1,19 +1,54 @@
 # lib/familia/errors.rb
 #
+# frozen_string_literal: true
+
 module Familia
+  # Base exception class for all Familia errors
   class Problem < RuntimeError; end
-  class NoIdentifier < Problem; end
-  class NonUniqueKey < Problem; end
 
-  class FieldTypeError < Problem; end
-  class AutoloadError < Problem; end
+  # Base exception class for Redis/persistence-related errors
+  class PersistenceError < Problem; end
+
+  # Base exception class for Horreum models
+  class HorreumError < Problem; end
+
+  # Raised when an object creation fails (e.g. the identifier
+  # is already in use)
+  class CreationError < HorreumError; end
+
+  # Raised when an object lacks a required identifier
+  class NoIdentifier < HorreumError; end
+
+  # Raised when a key is expected to be unique but isn't
+  class NonUniqueKey < PersistenceError; end
+
+  # Raised when watch failed (e.g. key was modified), typically
+  # retry
+  class OptimisticLockError < PersistenceError; end
+
+  # Raised when a field type is invalid or unexpected
+  class FieldTypeError < HorreumError; end
+
+  # Raised when autoloading fails
+  class AutoloadError < HorreumError; end
+
+  # Raised when serialization or deserialization fails
+  class SerializerError < HorreumError; end
+
+  # Raised when attempting to start transactions or pipelines on
+  # connection types that don't support them
+  class OperationModeError < PersistenceError; end
 
-  class SerializerError < Problem; end
+  # Raised when attempting to call a major method like save when
+  # inside a transaction or pipeline
+  class NestedTransactionError < OperationModeError; end
 
-  # Raised when attempting to start transactions or pipelines on connection types that don't support them
-  class OperationModeError < Problem; end
+  # Raised when attempting to reference a field that doesn't exist
+  class UnknownFieldError < HorreumError; end
 
-  class NotDistinguishableError < Problem
+  # Raised when a value cannot be converted to a distinguishable
+  # string representation
+  class NotDistinguishableError < HorreumError
     attr_reader :value
 
     def initialize(value)
@@ -26,7 +61,8 @@ module Familia
     end
   end
 
-  class NotConnected < Problem
+  # Raised when no connection is available for a given URI
+  class NotConnected < PersistenceError
     attr_reader :uri
 
     def initialize(uri)
@@ -39,13 +75,15 @@ module Familia
     end
   end
 
-  # UnsortedSet Familia.connection_provider or use middleware to provide connections.
-  class NoConnectionAvailable < Problem; end
+  # UnsortedSet Familia.connection_provider or use middleware
+  # to provide connections.
+  class NoConnectionAvailable < PersistenceError; end
 
   # Raised when a load method fails to find the requested object
-  class NotFound < Problem; end
+  class NotFound < PersistenceError; end
 
-  # Raised when attempting to refresh an object whose key doesn't exist in the database
+  # Raised when attempting to refresh an object whose key
+  # doesn't exist in the database
   class KeyNotFoundError < NonUniqueKey
     attr_reader :key
 
@@ -59,7 +97,8 @@ module Familia
     end
   end
 
-  # Raised when attempting to create an object that already exists in the database
+  # Raised when attempting to create an object that already
+  # exists in the database
   class RecordExistsError < NonUniqueKey
     attr_reader :key
 

data/lib/familia/features/autoloader.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/autoloader.rb
+#
+# frozen_string_literal: true
 
 # rubocop:disable Style/ClassAndModuleChildren
 module Familia::Features

data/lib/familia/features/encrypted_fields/concealed_string.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/encrypted_fields/concealed_string.rb
+#
+# frozen_string_literal: true
 
 # ConcealedString
 #

data/lib/familia/features/encrypted_fields/encrypted_field_type.rb

@@ -1,3 +1,7 @@
+# lib/familia/features/encrypted_fields/encrypted_field_type.rb
+#
+# frozen_string_literal: true
+
 # lib/familia/field_types/encrypted_field_type.rb
 
 require_relative '../../field_type'

data/lib/familia/features/encrypted_fields.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/encrypted_fields.rb
+#
+# frozen_string_literal: true
 
 require_relative 'encrypted_fields/encrypted_field_type'
 
@@ -341,8 +343,6 @@ module Familia
       # Check if this instance has any encrypted fields with values
       #
       # @return [Boolean] true if any encrypted fields have values
-      #
-      # TODO: Missing test coverage
       def encrypted_data?
         self.class.encrypted_fields.any? do |field_name|
           field_value = instance_variable_get("@#{field_name}")

data/lib/familia/features/expiration/extensions.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/expiration/extensions.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # Add a default update_expiration method for all classes that include
@@ -10,25 +12,23 @@ module Familia
     # with the :expiration feature's implementation.
     #
     # This is a no-op implementation that gets overridden by the :expiration
-    # feature. It accepts an optional default_expiration parameter to maintain
-    # interface compatibility with the overriding implementations.
+    # feature when it is enabled. This allows for calling this method on any
+    # horreum model regardless of the feature status. It accepts an optional
+    # expiration parameter to maintain interface compatibility with
+    # the overriding implementations.
     #
-    # @param default_expiration [Numeric, nil] Time To Live in seconds
+    # @param expiration [Numeric, nil] Time To Live in seconds
     # @return [nil] Always returns nil for the base implementation
     #
     # @note This is a no-op implementation. Classes that need expiration
     #       functionality should include the :expiration feature.
     #
-    # @example Enable expiration feature
-    #   class MyModel < Familia::Horreum
-    #     feature :expiration
-    #     default_expiration 1.hour
-    #   end
+    # @example MyModel.new.update_expiration(expiration: 3600) # => nothing happens
     #
-    def update_expiration(default_expiration: nil)
-      Familia.ld <<~LOG
+    def update_expiration(expiration: nil)
+      Familia.debug <<~LOG
         [update_expiration] Expiration feature not enabled for #{self.class}.
-        Key: #{dbkey} Arg: #{default_expiration} (caller: #{caller(1..1)})
+        Key: #{dbkey} Arg: #{expiration} (caller: #{caller(1..1)})
       LOG
       nil
     end

data/lib/familia/features/expiration.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/expiration.rb
+#
+# frozen_string_literal: true
 
 require_relative 'expiration/extensions'
 
@@ -36,7 +38,7 @@ module Familia
     #   session.ttl  # => 1799
     #
     #   # UnsortedSet custom expiration for new objects
-    #   session.update_expiration(default_expiration: 2.hours)
+    #   session.update_expiration(expiration: 2.hours)
     #
     # Class-Level Configuration:
     #
@@ -89,7 +91,7 @@ module Familia
     #
     # Setting expiration to 0 (zero) disables TTL, making data persist indefinitely:
     #
-    #   session.update_expiration(default_expiration: 0)  # No expiration
+    #   session.update_expiration(expiration: 0)  # No expiration
     #
     # TTL Querying:
     #
@@ -115,7 +117,7 @@ module Familia
     #       when 'free'
     #         update_expiration(1.hour)
     #       else
-    #         update_expiration(default_expiration)
+    #         update_expiration(expiration)
     #       end
     #     end
     #   end
@@ -135,10 +137,10 @@ module Familia
     #
     # The feature validates expiration values and raises descriptive errors:
     #
-    #   session.update_expiration(default_expiration: "invalid")
+    #   session.update_expiration(expiration: "invalid")
     #   # => Familia::Problem: Default expiration must be a number
     #
-    #   session.update_expiration(default_expiration: -1)
+    #   session.update_expiration(expiration: -1)
     #   # => Familia::Problem: Default expiration must be non-negative
     #
     # Performance Considerations:
@@ -226,20 +228,20 @@ module Familia
       # after which it will be automatically removed. The method also handles
       # cascading expiration to related data structures when applicable.
       #
-      # @param default_expiration [Numeric, nil] The Time To Live in seconds. If nil,
+      # @param expiration [Numeric, nil] The Time To Live in seconds. If nil,
       #   the default TTL will be used.
       #
       # @return [Boolean] Returns true if the expiration was set successfully,
       #   false otherwise.
       #
       # @example Setting an expiration of one day
-      #   object.update_expiration(default_expiration: 86400)
+      #   object.update_expiration(expiration: 86400)
       #
       # @example Using default expiration
       #   object.update_expiration  # Uses class default_expiration
       #
       # @example Removing expiration (persist indefinitely)
-      #   object.update_expiration(default_expiration: 0)
+      #   object.update_expiration(expiration: 0)
       #
       # @note If default expiration is set to zero, the expiration will be removed,
       #   making the data persist indefinitely.
@@ -247,19 +249,19 @@ module Familia
       # @raise [Familia::Problem] Raises an error if the default expiration is not
       #   a non-negative number.
       #
-      def update_expiration(default_expiration: nil)
-        default_expiration ||= self.default_expiration
+      def update_expiration(expiration: nil)
+        expiration ||= default_expiration
 
         # Handle cascading expiration to related data structures
         if self.class.relations?
-          Familia.ld "[update_expiration] #{self.class} has relations: #{self.class.related_fields.keys}"
+          Familia.debug "[update_expiration] #{self.class} has relations: #{self.class.related_fields.keys}"
           self.class.related_fields.each do |name, definition|
             # Skip relations that don't have their own expiration settings
             next if definition.opts[:default_expiration].nil?
 
             obj = send(name)
-            Familia.ld "[update_expiration] Updating expiration for #{name} (#{obj.dbkey}) to #{default_expiration}"
-            obj.update_expiration(default_expiration: default_expiration)
+            Familia.debug "[update_expiration] Updating expiration for #{name} (#{obj.dbkey}) to #{expiration}"
+            obj.update_expiration(expiration: expiration)
           end
         end
 
@@ -267,29 +269,35 @@ module Familia
         # It's important to raise exceptions here and not just log warnings. We
         # don't want to silently fail at setting expirations and cause data
         # retention issues (e.g. not removed in a timely fashion).
-        unless default_expiration.is_a?(Numeric)
+        unless expiration.is_a?(Numeric)
           raise Familia::Problem,
-                "Default expiration must be a number (#{default_expiration.class} given for #{self.class})"
+                "Default expiration must be a number (#{expiration.class} given for #{self.class})"
         end
 
-        unless default_expiration >= 0
+        unless expiration >= 0
           raise Familia::Problem,
-                "Default expiration must be non-negative (#{default_expiration} given for #{self.class})"
+                "Default expiration must be non-negative (#{expiration} given for #{self.class})"
         end
 
         # If zero, simply skip setting an expiry for this key. If we were to set
         # 0, Valkey/Redis would drop the key immediately.
-        if default_expiration.zero?
-          Familia.ld "[update_expiration] No expiration for #{self.class} (#{dbkey})"
+        if expiration.zero?
+          Familia.debug "[update_expiration] No expiration for #{self.class} (#{dbkey})"
           return true
         end
 
-        Familia.ld "[update_expiration] Expires #{dbkey} in #{default_expiration} seconds"
+        # Structured TTL operation logging
+        Familia.debug "TTL updated",
+          operation: :expire,
+          key: dbkey,
+          ttl_seconds: expiration,
+          class: self.class.name,
+          identifier: (identifier rescue nil)
 
         # The Valkey/Redis' EXPIRE command returns 1 if the timeout was set, 0
         # if key does not exist or the timeout could not be set. Via redis-rb,
         # it's a boolean.
-        expire(default_expiration)
+        expire(expiration)
       end
 
       # Get the remaining time to live for this object's data