familia 2.0.0.pre18 → 2.0.0.pre21

data/lib/familia/horreum/persistence.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/persistence.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # Familia::Horreum
@@ -35,128 +37,187 @@ module Familia
     # Handles conversion between Ruby objects and Valkey hash storage
     #
     module Persistence
-      # Persists the object to Valkey storage with automatic timestamping.
+      # Persists object state to storage with timestamps, validation, and indexing.
       #
-      # Saves the current object state to Valkey storage, automatically setting
-      # created and updated timestamps if the object supports them. The method
-      # commits all persistent fields and optionally updates the key's expiration.
+      # Performs a complete save operation in an atomic transaction:
+      # - Sets created/updated timestamps
+      # - Validates unique index constraints
+      # - Persists all fields
+      # - Updates expiration (optional)
+      # - Updates class-level indexes
+      # - Adds to instances collection
       #
-      # @param update_expiration [Boolean] Whether to update the key's expiration
-      #   time after saving. Defaults to true.
+      # ## Transaction Safety
+      #
+      # This method CANNOT be called within a transaction context. The save process
+      # requires reading current state to validate unique constraints, which would
+      # return uninspectable Redis::Future objects inside transactions.
+      #
+      # ### Correct Pattern:
+      #     customer = Customer.new(email: 'test@example.com')
+      #     customer.save  # Validates unique constraints here
       #
-      # @return [Boolean] true if the save operation was successful, false otherwise.
+      #     customer.transaction do
+      #       # Perform other atomic operations
+      #       customer.increment(:login_count)
+      #       customer.hset(:last_login, Time.now.to_i)
+      #     end
       #
-      # @example Save an object to Valkey
-      #   user = User.new(name: "John", email: "john@example.com")
-      #   user.save
-      #   # => true
+      # ### Incorrect Pattern:
+      #     Customer.transaction do
+      #       customer = Customer.new(email: 'test@example.com')
+      #       customer.save  # Raises Familia::OperationModeError
+      #     end
       #
-      # @example Save without updating expiration
-      #   user.save(update_expiration: false)
-      #   # => true
+      # @param update_expiration [Boolean] Whether to refresh key expiration (default: true)
+      # @return [Boolean] true on success
       #
-      # @note When Familia.debug? is enabled, this method will trace the save
-      #   operation for debugging purposes.
+      # @raise [Familia::OperationModeError] If called within a transaction
+      # @raise [Familia::RecordExistsError] If unique index constraint violated
       #
-      # @see #commit_fields The underlying method that performs the field persistence
+      # @example Basic usage
+      #   user = User.new(email: "john@example.com")
+      #   user.save  # => true
+      #
+      # @see #save_if_not_exists! For conditional saves
+      # @see #transaction For atomic operations after save
       #
       def save(update_expiration: true)
-        Familia.trace :SAVE, nil, uri if Familia.debug?
-
-        # No longer need to sync computed identifier with a cache field
-        self.created ||= Familia.now.to_i if respond_to?(:created)
-        self.updated = Familia.now.to_i if respond_to?(:updated)
-
-        # Commit our tale to the Database chronicles
-        # Wrap in transaction for atomicity between save and indexing
-        ret = commit_fields(update_expiration: update_expiration)
-
-        # Auto-index for class-level indexes after successful save
-        # Use transaction to ensure atomicity with the save operation
-        if ret
-          transaction do |conn|
-            auto_update_class_indexes
-            # Add to class-level instances collection after successful save
-            self.class.instances.add(identifier, Familia.now) if self.class.respond_to?(:instances)
-          end
+        start_time = Familia.now_in_μs if Familia.debug?
+
+        # Prevent save within transaction - unique index guards require read operations
+        # which are not available in Redis MULTI/EXEC blocks
+        if Fiber[:familia_transaction]
+          raise Familia::OperationModeError, <<~ERROR_MESSAGE
+            Cannot call save within a transaction. Save operations must be called outside transactions to ensure unique constraints can be validated.
+          ERROR_MESSAGE
         end
 
-        Familia.ld "[save] #{self.class} #{dbkey} #{ret} (update_expiration: #{update_expiration})"
+        Familia.trace :SAVE, nil, self.class.uri if Familia.debug?
 
-        # Did Database accept our offering?
-        !ret.nil?
+        # Prepare object for persistence (timestamps, validation)
+        prepare_for_save
+
+        # Everything in ONE transaction for complete atomicity
+        result = transaction do |_conn|
+          persist_to_storage(update_expiration)
+        end
+
+        # Structured lifecycle logging and instrumentation
+        if Familia.debug? && start_time
+          duration = Familia.now_in_μs - start_time
+
+          begin
+            fields_count = to_h_for_storage.size
+          rescue => e
+            Familia.error "Failed to serialize fields for logging",
+              error: e.message,
+              class: self.class.name,
+              identifier: (identifier rescue nil)
+            fields_count = 0
+          end
+
+          Familia.debug "Horreum saved",
+            class: self.class.name,
+            identifier: identifier,
+            duration: duration,
+            fields_count: fields_count,
+            update_expiration: update_expiration
+
+          Familia::Instrumentation.notify_lifecycle(:save, self,
+            duration: duration,
+            update_expiration: update_expiration,
+            fields_count: fields_count
+          )
+        end
+
+        # Return boolean indicating success
+        !result.nil?
       end
 
-      # Saves the object to Valkey storage only if it doesn't already exist.
-      #
-      # Conditionally persists the object to Valkey storage by first checking if the
-      # identifier field already exists. If the object already exists in storage,
-      # raises an error. Otherwise, proceeds with a normal save operation including
-      # automatic timestamping.
-      #
-      # This method provides atomic conditional creation to prevent duplicate objects
-      # from being saved when uniqueness is required based on the identifier field.
-      #
-      # @param update_expiration [Boolean] Whether to update the key's expiration
-      #   time after saving. Defaults to true.
-      #
-      # @return [Boolean] true if the save operation was successful
+      # Conditionally persists object only if it doesn't already exist in storage.
       #
-      # @raise [Familia::RecordExistsError] If an object with the same identifier
-      #   already exists in Valkey storage
+      # Uses optimistic locking (WATCH) to atomically check existence and save.
+      # If the object doesn't exist, performs identical operations as save.
+      # If it exists, raises an error with retry logic for optimistic lock failures.
       #
-      # @example Save a new user only if it doesn't exist
-      #   user = User.new(id: 123, name: "John")
-      #   user.save_if_not_exists
-      #   # => true (saved successfully)
-      #
-      # @example Attempting to save an existing object
-      #   existing_user = User.new(id: 123, name: "Jane")
-      #   existing_user.save_if_not_exists
-      #   # => raises Familia::RecordExistsError
-      #
-      # @example Save without updating expiration
-      #   user.save_if_not_exists(update_expiration: false)
-      #   # => true
-      #
-      # @note This method uses HSETNX to atomically check and set the identifier
-      #   field, ensuring race-condition-free conditional creation.
+      # `save_if_not_exists` doesn't call save because of the gap between checking
+      # existence and persisting the data. We can't check for existence inside the
+      # transaction because commands are queued and not executed until EXEC
+      # is called (if you try you get a Redis::Future object). So here we use a
+      # WATCH + MULTI/EXEC pattern to fail the transaction if the key is created
+      # (or modified in any way) to avoid silent data corruption♀︎.
+
+      # ♀︎ Additional note about WATCH + MULTI/EXEC in Valkey/Redis or any two
+      # step existence check in any database: although it is more cautious,
+      # it is not atomic. The only way to do that is if the database process
+      # can determine itself whether the record already exists or not. For
+      # Valkey/Redis, that means writing the lua to do that.
       #
-      # @see #save The underlying save method called when the object doesn't exist
+      # @param update_expiration [Boolean] Whether to refresh key expiration (default: true)
+      # @return [Boolean] true on successful save
       #
-      # Check if save_if_not_exists is implemented correctly. It should:
+      # @raise [Familia::RecordExistsError] If object already exists
+      # @raise [Familia::OptimisticLockError] If retries exhausted (max 3 attempts)
+      # @raise [Familia::OperationModeError] If called within a transaction
       #
-      # Check if record exists
-      # If exists, raise Familia::RecordExistsError
-      # If not exists, save
-      def save_if_not_exists(update_expiration: true)
+      # @example
+      #   user = User.new(id: 123)
+      #   user.save_if_not_exists!  # => true or raises
+      def save_if_not_exists!(update_expiration: true)
+        # Prevent save_if_not_exists! within transaction - needs to read existence state
+        if Fiber[:familia_transaction]
+          raise Familia::OperationModeError, <<~ERROR_MESSAGE
+            Cannot call save_if_not_exists! within a transaction. This method
+            must be called outside transactions to properly check existence.
+          ERROR_MESSAGE
+        end
+
         identifier_field = self.class.identifier_field
 
-        Familia.ld "[save_if_not_exists]: #{self.class} #{identifier_field}=#{identifier}"
-        Familia.trace :SAVE_IF_NOT_EXISTS, nil, uri if Familia.debug?
+        Familia.debug "[save_if_not_exists]: #{self.class} #{identifier_field}=#{identifier}"
+        Familia.trace :SAVE_IF_NOT_EXISTS, nil, self.class.uri if Familia.debug?
 
-        success = dbclient.watch(dbkey) do
-          if dbclient.exists(dbkey).positive?
-            dbclient.unwatch
-            raise Familia::RecordExistsError, dbkey
-          end
+        # Prepare object for persistence (timestamps, validation)
+        prepare_for_save
 
-          result = dbclient.multi do |multi|
-            multi.hmset(dbkey, to_h_for_storage)
-          end
+        attempts = 0
+        begin
+          attempts += 1
 
-          result.is_a?(Array) # transaction succeeded
-        end
+          result = watch do
+            raise Familia::RecordExistsError, dbkey if exists?
 
-        # Auto-index for class-level indexes after successful save
-        # Use transaction to ensure atomicity with the save operation
-        if success
-          transaction do |conn|
-            auto_update_class_indexes
+            txn_result = transaction do |_multi|
+              persist_to_storage(update_expiration)
+            end
+
+            Familia.debug "[save_if_not_exists]: txn_result=#{txn_result.inspect}"
+
+            txn_result
           end
+
+          Familia.debug "[save_if_not_exists]: result=#{result.inspect}"
+
+          # Return boolean indicating success (consistent with save method)
+          !result.nil?
+        rescue OptimisticLockError => e
+          Familia.debug "[save_if_not_exists]: OptimisticLockError (#{attempts}): #{e.message}"
+          raise if attempts >= 3
+
+          sleep(0.001 * (2**attempts))
+          retry
         end
+      end
 
-        success
+      # Non-raising variant of save_if_not_exists!
+      #
+      # @return [Boolean] true on success, false if object exists
+      # @raise [Familia::OptimisticLockError] If concurrency conflict persists after retries
+      def save_if_not_exists(...)
+        save_if_not_exists!(...)
+      rescue RecordExistsError
+        false
       end
 
       # Commits object fields to the DB storage.
@@ -186,16 +247,17 @@ module Familia
       #
       def commit_fields(update_expiration: true)
         prepared_value = to_h_for_storage
-        Familia.ld "[commit_fields] Begin #{self.class} #{dbkey} #{prepared_value} (exp: #{update_expiration})"
+        Familia.debug "[commit_fields] Begin #{self.class} #{dbkey} #{prepared_value} (exp: #{update_expiration})"
 
-        result = hmset(prepared_value)
+        transaction do |_conn|
+          # Set all fields atomically
+          result = hmset(prepared_value)
 
-        # Only classes that have the expiration ferature enabled will
-        # actually set an expiration time on their keys. Otherwise
-        # this will be a no-op that simply logs the attempt.
-        update_expiration(default_expiration: nil) if update_expiration
+          # Update expiration in same transaction to ensure atomicity
+          self.update_expiration if result && update_expiration
 
-        result
+          result
+        end
       end
 
       # Updates multiple fields atomically in a Database transaction.
@@ -216,20 +278,57 @@ module Familia
 
         Familia.trace :BATCH_UPDATE, nil, fields.keys if Familia.debug?
 
-        transaction_result = transaction do |conn|
+        transaction do |_conn|
+          # 1. Update all fields atomically
           fields.each do |field, value|
             prepared_value = serialize_value(value)
-            conn.hset dbkey, field, prepared_value
+            hset field, prepared_value
             # Update instance variable to keep object in sync
             send("#{field}=", value) if respond_to?("#{field}=")
           end
+
+          # 2. Update expiration in same transaction
+          self.update_expiration if update_expiration
         end
+      end
+
+      # Persists only the specified fields to Redis.
+      #
+      # Saves the current in-memory values of specified fields to Redis without
+      # modifying them first. Fields must already be set on the instance.
+      #
+      # @param field_names [Array<Symbol, String>] Names of fields to persist
+      # @param update_expiration [Boolean] Whether to refresh key expiration
+      # @return [self] Returns self for method chaining
+      #
+      # @example Persist only passphrase fields after updating them
+      #   customer.update_passphrase('secret').save_fields(:passphrase, :passphrase_encryption)
+      #
+      def save_fields(*field_names, update_expiration: true)
+        raise ArgumentError, 'No fields specified' if field_names.empty?
 
-        # Update expiration if requested and supported
-        self.update_expiration(default_expiration: nil) if update_expiration && respond_to?(:update_expiration)
+        Familia.trace :SAVE_FIELDS, nil, field_names if Familia.debug?
 
-        # Return the MultiResult directly (transaction already returns MultiResult)
-        transaction_result
+        transaction do |_conn|
+          # Build hash of field names to serialized values
+          fields_hash = {}
+          field_names.each do |field|
+            field_sym = field.to_sym
+            raise ArgumentError, "Unknown field: #{field}" unless respond_to?(field_sym)
+
+            value = send(field_sym)
+            prepared_value = serialize_value(value)
+            fields_hash[field] = prepared_value
+          end
+
+          # Set all fields at once using hmset
+          hmset(fields_hash)
+
+          # Update expiration in same transaction
+          self.update_expiration if update_expiration
+        end
+
+        self
       end
 
       # Updates the object by applying multiple field values.
@@ -279,25 +378,35 @@ module Familia
       # @see #delete! The underlying method that performs the key deletion
       #
       def destroy!
-        Familia.trace :DESTROY, dbkey, uri
+        Familia.trace :DESTROY!, dbkey, self.class.uri
 
         # Execute all deletion operations within a transaction
-        transaction do |conn|
+        result = transaction do |_conn|
           # Delete the main object key
-          conn.del(dbkey)
+          delete!
 
           # Delete all related fields if present
           if self.class.relations?
             Familia.trace :DELETE_RELATED_FIELDS!, nil,
                           "#{self.class} has relations: #{self.class.related_fields.keys}"
 
-            self.class.related_fields.each do |name, _definition|
+            self.class.related_fields.each_key do |name|
               obj = send(name)
               Familia.trace :DELETE_RELATED_FIELD, name, "Deleting related field #{name} (#{obj.dbkey})"
-              conn.del(obj.dbkey)
+              obj.delete!
             end
           end
         end
+
+        # Structured lifecycle logging and instrumentation
+        Familia.debug "Horreum destroyed",
+          class: self.class.name,
+          identifier: identifier,
+          key: dbkey
+
+        Familia::Instrumentation.notify_lifecycle(:destroy, self, key: dbkey)
+
+        result
       end
 
       # Clears all fields by setting them to nil.
@@ -318,6 +427,7 @@ module Familia
       #   after clear_fields! if you want to persist the cleared state.
       #
       def clear_fields!
+        Familia.trace :CLEAR_FIELDS!, dbkey, self.class.uri
         self.class.field_method_map.each_value { |method_name| send("#{method_name}=", nil) }
       end
 
@@ -343,11 +453,11 @@ module Familia
       #   no authoritative source in Valkey storage.
       #
       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:#{fields.keys}"
+        Familia.debug "[refresh!] #{self.class} #{dbkey} fields:#{fields.keys}"
 
         # Reset transient fields to nil for semantic clarity and ORM consistency
         # Transient fields have no authoritative source, so they should return to
@@ -378,6 +488,11 @@ module Familia
         self
       end
 
+      # Convenience methods that forward to the class method of the same name
+      def transaction(...) = self.class.transaction(...)
+      def pipelined(...) = self.class.pipelined(...)
+      def dbclient(...) = self.class.dbclient(...)
+
       private
 
       # Reset all transient fields to nil
@@ -398,16 +513,50 @@ module Familia
 
           # UnsortedSet the transient field back to nil
           send("#{field_type.method_name}=", nil)
-          Familia.ld "[reset_transient_fields!] Reset #{field_name} to nil"
+          Familia.debug "[reset_transient_fields!] Reset #{field_name} to nil"
+        end
+      end
+
+      # Validates that unique index constraints are satisfied before saving
+      # This must be called OUTSIDE of transactions to allow reading current values
+      #
+      # @raise [Familia::RecordExistsError] If a unique index constraint is violated
+      #   for any class-level unique_index relationships
+      #
+      # @note Only validates class-level unique indexes (without within: parameter).
+      #   Instance-scoped indexes (with within:) are validated automatically when
+      #   calling add_to_*_index methods:
+      #
+      # @example Instance-scoped indexes need to be called explicitly but when
+      # called they will perform the validation automatically:
+      #   employee.add_to_company_badge_index(company) # raises on duplicate
+      #
+      # @return [void]
+      #
+      def guard_unique_indexes!
+        return unless self.class.respond_to?(:indexing_relationships)
+
+        self.class.indexing_relationships.each do |rel|
+          # Only validate unique indexes (not multi_index)
+          next unless rel.cardinality == :unique
+
+          # Only validate class-level indexes (skip instance-scoped)
+          next if rel.within
+
+          # Call the validation method if it exists
+          validate_method = :"guard_unique_#{rel.index_name}!"
+          send(validate_method) if respond_to?(validate_method)
         end
+
+        nil # Explicit nil return as documented
       end
 
       # Automatically update class-level indexes after save
       #
       # Iterates through class-level indexing relationships and calls their
       # corresponding add_to_class_* methods to populate indexes. Only processes
-      # class-level indexes (where target_class == self.class), skipping
-      # instance-scoped indexes which require parent context.
+      # class-level indexes (where within is nil), skipping instance-scoped
+      # indexes which require scope context.
       #
       # Uses idempotent Redis commands (HSET for unique_index) so repeated calls
       # are safe and have negligible performance overhead. Note that multi_index
@@ -434,12 +583,12 @@ module Familia
         return unless self.class.respond_to?(:indexing_relationships)
 
         self.class.indexing_relationships.each do |rel|
-          # Skip instance-scoped indexes (require parent context)
+          # Skip instance-scoped indexes (require scope context)
           # Instance-scoped indexes must be manually populated because they need
-          # the parent object reference (e.g., employee.add_to_company_badge_index(company))
-          unless rel.target_class == self.class
-            Familia.ld <<~LOG_MESSAGE
-              [auto_update_class_indexes] Skipping #{rel.index_name} (requires parent context)
+          # the scope instance reference (e.g., employee.add_to_company_badge_index(company))
+          if rel.within
+            Familia.debug <<~LOG_MESSAGE
+              [auto_update_class_indexes] Skipping #{rel.index_name} (requires scope context)
             LOG_MESSAGE
             next
           end
@@ -450,6 +599,49 @@ module Familia
         end
       end
 
+      # Prepares the object for persistence by setting timestamps and validating constraints
+      #
+      # This method is called by both save and save_if_not_exists to ensure consistent
+      # preparation logic. It updates created/updated timestamps and validates unique
+      # indexes before the transaction begins.
+      #
+      # @return [void]
+      #
+      def prepare_for_save
+        # Update timestamp fields before saving
+        self.created ||= Familia.now if respond_to?(:created)
+        self.updated = Familia.now if respond_to?(:updated)
+
+        # Validate unique indexes BEFORE the transaction
+        guard_unique_indexes!
+      end
+      private :prepare_for_save
+
+      # Persists the object's data to storage within a transaction
+      #
+      # This method contains the core persistence logic shared by both save and
+      # save_if_not_exists. It must be called within a transaction block.
+      #
+      # @param update_expiration [Boolean] Whether to update the key's expiration
+      # @return [Object] The result of the hmset operation
+      #
+      def persist_to_storage(update_expiration)
+        # 1. Save all fields to hashkey at once
+        prepared_h = to_h_for_storage
+        hmset_result = hmset(prepared_h)
+
+        # 2. Set expiration in same transaction
+        self.update_expiration if update_expiration
+
+        # 3. Update class-level indexes
+        auto_update_class_indexes
+
+        # 4. Add to instances collection if available
+        self.class.instances.add(identifier, Familia.now) if self.class.respond_to?(:instances)
+
+        hmset_result
+      end
+      private :persist_to_storage
     end
   end
 end

data/lib/familia/horreum/related_fields.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/related_fields.rb
+#
+# frozen_string_literal: true
 
 module Familia
 

data/lib/familia/horreum/serialization.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/serialization.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class Horreum
@@ -30,7 +32,7 @@ module Familia
           next unless field_type.loggable
 
           val = send(field_type.method_name)
-          Familia.ld " [to_h] field: #{field} val: #{val.class}"
+          Familia.debug " [to_h] field: #{field} val: #{val.class}"
 
           # Use string key for external API compatibility
           # Return Ruby values, not JSON-encoded strings
@@ -63,7 +65,7 @@ module Familia
           prepared = serialize_value(val)
 
           if Familia.debug?
-            Familia.ld " [to_h_for_storage] field: #{field} val: #{val.class} prepared: #{prepared&.class || '[nil]'}"
+            Familia.debug " [to_h_for_storage] field: #{field} val: #{val.class} prepared: #{prepared&.class || '[nil]'}"
           end
 
           # Use string key for database compatibility
@@ -96,7 +98,7 @@ module Familia
 
           method_name = field_type.method_name
           val = send(method_name)
-          Familia.ld " [to_a] field: #{field} method: #{method_name} val: #{val.class}"
+          Familia.debug " [to_a] field: #{field} method: #{method_name} val: #{val.class}"
 
           # Return actual Ruby values, including nil to maintain array positions
           val
@@ -159,6 +161,9 @@ module Familia
       def deserialize_value(val, symbolize: false, field_name: nil)
         return nil if val.nil? || val == ''
 
+        # Handle Redis::Future objects during transactions
+        return val if val.is_a?(Redis::Future)
+
         begin
           Familia::JsonSerializer.parse(val, symbolize_names: symbolize)
         rescue Familia::SerializerError
@@ -179,7 +184,24 @@ module Familia
           "Legacy plain string in #{context}: #{val.inspect} (#{dbkey_info})"
         end
 
-        Familia.le(msg)
+        # Structured error logging with instrumentation
+        error_type = looks_like_json?(val) ? :corrupted_json : :legacy_string
+        Familia.error msg,
+          error_type: error_type,
+          field: field_name,
+          value_preview: val.to_s[0...50],
+          object_class: self.class.name,
+          identifier: (identifier rescue nil),
+          key: dbkey_info
+
+        # Notify instrumentation hooks
+        Familia::Instrumentation.notify_error(
+          StandardError.new(msg),
+          operation: :deserialization,
+          error_type: error_type,
+          field: field_name,
+          object_class: self.class.name
+        )
       end
 
       def looks_like_json?(val)

data/lib/familia/horreum/settings.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/settings.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # InstanceMethods - Module containing instance-level methods for Familia