familia 2.0.0.pre18 → 2.0.0.pre19

data/lib/familia/horreum/persistence.rb

@@ -35,17 +35,23 @@ module Familia
     # Handles conversion between Ruby objects and Valkey hash storage
     #
     module Persistence
-      # Persists the object to Valkey storage with automatic timestamping.
+      # Persists the object to Valkey storage with automatic timestamping and validation.
       #
       # 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.
+      # validates unique indexes before the transaction, commits all persistent
+      # fields, and optionally updates the key's expiration.
       #
       # @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, false otherwise.
       #
+      # @raise [Familia::OperationModeError] If called within an existing transaction.
+      #   Guards need to read current values, which is not possible inside MULTI/EXEC.
+      # @raise [Familia::RecordExistsError] If a unique index constraint is violated
+      #   for any class-level unique_index relationships.
+      #
       # @example Save an object to Valkey
       #   user = User.new(name: "John", email: "john@example.com")
       #   user.save
@@ -55,36 +61,60 @@ module Familia
       #   user.save(update_expiration: false)
       #   # => true
       #
+      # @example Handle duplicate unique index
+      #   user2 = User.new(name: "Jane", email: "john@example.com")
+      #   user2.save
+      #   # => raises Familia::RecordExistsError
+      #
+      # @note Cannot be called within a transaction. Call save first to start
+      #   the transaction, or use commit_fields/hmset for manual field updates
+      #   within transactions.
+      #
       # @note When Familia.debug? is enabled, this method will trace the save
       #   operation for debugging purposes.
       #
       # @see #commit_fields The underlying method that performs the field persistence
+      # @see #guard_unique_indexes! Automatic validation of class-level unique indexes
       #
       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
+        # 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,
+            "Cannot call save within a transaction. Save operations must be called outside transactions to ensure unique constraints can be validated."
         end
 
-        Familia.ld "[save] #{self.class} #{dbkey} #{ret} (update_expiration: #{update_expiration})"
+        Familia.trace :SAVE, nil, self.class.uri if Familia.debug?
+
+        # 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!
+
+        # Everything in ONE transaction for complete atomicity
+        result = transaction do |_conn|
+          # 1. Save all fields
+          prepared_h = to_h_for_storage
+          hmset_result = hmset(prepared_h)
 
-        # Did Database accept our offering?
-        !ret.nil?
+          # 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
+
+        Familia.ld "[save] #{self.class} #{dbkey} #{result} (update_expiration: #{update_expiration})"
+
+        # Return boolean indicating success
+        !result.nil?
       end
 
       # Saves the object to Valkey storage only if it doesn't already exist.
@@ -129,34 +159,51 @@ module Familia
       # Check if record exists
       # If exists, raise Familia::RecordExistsError
       # If not exists, save
-      def save_if_not_exists(update_expiration: true)
+      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,
+            "Cannot call save_if_not_exists! within a transaction. This method must be called outside transactions to properly check existence."
+        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.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
+        attempts = 0
+        begin
+          attempts += 1
 
-          result = dbclient.multi do |multi|
-            multi.hmset(dbkey, to_h_for_storage)
-          end
+          watch do
+            raise Familia::RecordExistsError, dbkey if exists?
 
-          result.is_a?(Array) # transaction succeeded
-        end
+            txn_result = transaction do |_multi|
+              hmset(to_h_for_storage)
+
+              self.update_expiration if update_expiration
+
+              # Auto-index for class-level indexes after successful save
+              auto_update_class_indexes
+            end
 
-        # 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
+            Familia.ld "[save_if_not_exists]: txn_result=#{txn_result.inspect}"
+
+            txn_result.successful?
           end
+        rescue OptimisticLockError => e
+          Familia.ld "[save_if_not_exists]: OptimisticLockError (#{attempts}): #{e.message}"
+          raise if attempts >= 3
+
+          sleep(0.001 * (2**attempts))
+          retry
         end
+      end
 
-        success
+      def save_if_not_exists(...)
+        save_if_not_exists!(...)
+      rescue RecordExistsError, OptimisticLockError
+        false
       end
 
       # Commits object fields to the DB storage.
@@ -188,14 +235,15 @@ module Familia
         prepared_value = to_h_for_storage
         Familia.ld "[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 +264,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?
+
+        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
 
-        # Return the MultiResult directly (transaction already returns MultiResult)
-        transaction_result
+          # 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,22 +364,22 @@ 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|
+        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
@@ -318,6 +403,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,7 +429,7 @@ 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
@@ -378,6 +464,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
@@ -402,12 +493,46 @@ module Familia
         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 +559,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
+          # the scope instance reference (e.g., employee.add_to_company_badge_index(company))
+          if rel.within
             Familia.ld <<~LOG_MESSAGE
-              [auto_update_class_indexes] Skipping #{rel.index_name} (requires parent context)
+              [auto_update_class_indexes] Skipping #{rel.index_name} (requires scope context)
             LOG_MESSAGE
             next
           end
@@ -449,7 +574,6 @@ module Familia
           send(add_method) if respond_to?(add_method)
         end
       end
-
     end
   end
 end

data/lib/familia/horreum/serialization.rb

@@ -159,6 +159,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

data/lib/familia/horreum/utils.rb

@@ -11,14 +11,6 @@ module Familia
     # Provides identifier handling, dbkey generation, and object inspection
     #
     module Utils
-      # def uri
-      #   base_uri = self.class.uri || Familia.uri
-      #   u = base_uri.dup # make a copy to modify safely
-      #   u.logical_database = logical_database if logical_database
-      #   u.key = dbkey
-      #   u
-      # end
-
       # +suffix+ is the value to be used at the end of the db key
       # (e.g. `customer:customer_id:scores` would have `scores` as the suffix
       # and `customer_id` would have been the identifier in that case).

data/lib/familia/horreum.rb

@@ -51,7 +51,6 @@ module Familia
     include Familia::Base
     include Familia::Horreum::Persistence
     include Familia::Horreum::Serialization
-    include Familia::Horreum::Connection
     include Familia::Horreum::DatabaseCommands
     include Familia::Horreum::Settings
     include Familia::Horreum::Utils
@@ -226,23 +225,43 @@ module Familia
         # Default values are intentionally NOT set here
       end
 
-      # Implementing classes can define an init method to do any
-      # additional initialization. Notice that this is called
-      # after the fields are set.
+      # Implementing classes can define an init method to do any additional
+      # initialization. Notice that this is called AFTER fields are set from
+      # kwargs, so kwargs have been consumed and are no longer available.
+      #
+      # IMPORTANT: Use ||= in init to apply defaults without overriding:
+      #   def init
+      #     @email ||= email               # Preserves value already set
+      #     @status ||= 'pending'          # Applies default if nil
+      #   end
+      #
       init
     end
 
-    # Override this method in subclasses for custom initialization logic.
-    # This is called AFTER fields are set and relatives are initialized.
+    # Initialization method called at the end of initialize
+    #
+    # Override this method to apply defaults, run validations, or setup
+    # callbacks. It's recommended to call super as other modules like
+    # features can also override init.
     #
-    # DO NOT override initialize() - use this init() hook instead.
+    # IMPORTANT: The init method receieves no arguments. By the time this runs,
+    # all arguments to initialize have already been consumed and used to set
+    # fields. Use the ||= operator to preserve values already set:
     #
-    # Example:
-    #   def init(name = nil)
-    #     @name = name || SecureRandom.hex(4)
+    #   def init(email: nil, user_id: nil, **kwargs)
+    #     @email ||= email                  # Preserves value from new()
+    #     @user_id ||= user_id              # Preserves value from new()
+    #     @created_at ||= Familia.now       # Applies default if not set
+    #
+    #     # Example of additional initialization logic
+    #     validate_email_format if @email
+    #     setup_callbacks
     #   end
-    def init(*args, **kwargs)
-      # Default no-op
+    #
+    # @return [void]
+    #
+    def init
+      # Default no-op - override in subclasses
     end
 
     # Sets up related Database objects for the instance

data/lib/familia/logging.rb

@@ -142,12 +142,9 @@ module Familia
         SEVERITY_LETTERS.fetch(severity, severity[0])
       end
 
-      utc_datetime = datetime.utc.strftime('%m-%d %H:%M:%S.%3N')
-      pid = Process.pid
-      thread_id = Thread.current.object_id
-      fiber_id = Fiber.current.object_id
+      utc_datetime = datetime.utc.strftime('%H:%M:%S.%3N')
 
-      "#{severity_letter}, #{utc_datetime} pid:#{pid} [#{thread_id}/#{fiber_id}]: #{msg}\n"
+      "#{severity_letter}, #{utc_datetime} #{msg}\n"
     end
   end
 

data/lib/familia/settings.rb

@@ -11,7 +11,7 @@ module Familia
   @encryption_keys = nil
   @current_key_version = nil
   @encryption_personalization = 'FamilialMatters'.freeze
-  @pipeline_mode = :warn
+  @pipelined_mode = :warn
 
   # Familia::Settings
   #
@@ -118,24 +118,24 @@ module Familia
     #
     # @example Setting pipeline mode
     #   Familia.configure do |config|
-    #     config.pipeline_mode = :permissive
+    #     config.pipelined_mode = :permissive
     #   end
     #
-    def pipeline_mode(val = nil)
+    def pipelined_mode(val = nil)
       if val
         unless [:strict, :warn, :permissive].include?(val)
           raise ArgumentError, 'Pipeline mode must be :strict, :warn, or :permissive'
         end
-        @pipeline_mode = val
+        @pipelined_mode = val
       end
-      @pipeline_mode || :warn  # default to warn mode
+      @pipelined_mode || :warn  # default to warn mode
     end
 
-    def pipeline_mode=(val)
+    def pipelined_mode=(val)
       unless [:strict, :warn, :permissive].include?(val)
         raise ArgumentError, 'Pipeline mode must be :strict, :warn, or :permissive'
       end
-      @pipeline_mode = val
+      @pipelined_mode = val
     end
 
     # Configure Familia settings

data/lib/familia/version.rb

@@ -2,5 +2,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.0.0.pre18'.freeze unless defined?(Familia::VERSION)
+  VERSION = '2.0.0.pre19'.freeze unless defined?(Familia::VERSION)
 end

data/lib/middleware/database_logger.rb

@@ -33,7 +33,13 @@ module DatabaseLogger
   @max_commands = 10_000
   @process_start = Time.now.to_f.freeze
 
-  CommandMessage = Data.define(:command, :μs, :timeline)
+  CommandMessage = Data.define(:command, :μs, :timeline) do
+    alias_method :to_a, :deconstruct
+    def inspect
+      cmd, duration, timeline = to_a
+      format('%.6f %4dμs > %s', timeline, duration, cmd)
+    end
+  end
 
   class << self
     # Gets/sets the logger instance used by DatabaseLogger.
@@ -78,6 +84,12 @@ module DatabaseLogger
       @commands.to_a
     end
 
+    # Gets the current count of Database commands executed.
+    # @return [Integer] The number of Database commands executed.
+    def index
+      @commands.size
+    end
+
     # Thread-safe append with bounded size
     #
     # @param message [String] The message to append.
@@ -115,16 +127,62 @@ module DatabaseLogger
     block_start = DatabaseLogger.now_in_μs
     result = yield
     block_duration = DatabaseLogger.now_in_μs - block_start
-    lifetime_duration = (Time.now.to_f - DatabaseLogger.process_start).round(6)
 
     # We intentionally use two different codepaths for getting the
     # time, although they will almost always be so similar that the
     # difference is negligible.
-    message = CommandMessage.new(command, block_duration, lifetime_duration)
-    DatabaseLogger.append_command(message)
+    lifetime_duration = (Time.now.to_f - DatabaseLogger.process_start).round(6)
+
+    msgpack = CommandMessage.new(command.join(' '), block_duration, lifetime_duration)
+    DatabaseLogger.append_command(msgpack)
 
     # Log if logger is set
-    DatabaseLogger.logger&.debug(Oj.dump(message.to_h, mode: :strict))
+    message = format('[%s] %s', DatabaseLogger.index, msgpack.inspect)
+    DatabaseLogger.logger&.trace(message)
+
+    result
+  end
+
+  # Handle pipelined commands (including MULTI/EXEC transactions)
+  #
+  # Captures MULTI/EXEC and shows you the full transaction. The WATCH
+  # and EXISTS appear separately because they're executed as individual
+  # commands before the transaction starts.
+  def call_pipelined(commands, _config)
+    block_start = DatabaseLogger.now_in_μs
+    results = yield
+    block_duration = DatabaseLogger.now_in_μs - block_start
+    lifetime_duration = (Time.now.to_f - DatabaseLogger.process_start).round(6)
+
+    # Log the entire pipeline as a single operation
+    cmd_string = commands.map { |cmd| cmd.join(' ') }.join(' | ')
+    msgpack = CommandMessage.new(cmd_string, block_duration, lifetime_duration)
+    DatabaseLogger.append_command(msgpack)
+
+    message = format('[%s] %s', DatabaseLogger.index, msgpack.inspect)
+    DatabaseLogger.logger&.trace(message)
+
+    results
+  end
+
+  # call_once is used for commands that need dedicated connection handling:
+  #
+  #   * Blocking commands (BLPOP, BRPOP, BRPOPLPUSH)
+  #   * Pub/sub operations (SUBSCRIBE, PSUBSCRIBE)
+  #   * Commands requiring connection affinity
+  #   * Explicit non-pooled command execution
+  #
+  def call_once(command, _config)
+    block_start = DatabaseLogger.now_in_μs
+    result = yield
+    block_duration = DatabaseLogger.now_in_μs - block_start
+    lifetime_duration = (Time.now.to_f - DatabaseLogger.process_start).round(6)
+
+    msgpack = CommandMessage.new(command.join(' '), block_duration, lifetime_duration)
+    DatabaseLogger.append_command(msgpack)
+
+    message = format('[%s] %s', DatabaseLogger.index, msgpack.inspect)
+    DatabaseLogger.logger&.trace(message)
 
     result
   end
@@ -221,5 +279,18 @@ module DatabaseCommandCounter
     klass.increment unless klass.skip_command?(command)
     yield
   end
+
+  def call_pipelined(commands, _config)
+    # Count all commands in the pipeline (except skipped ones)
+    commands.each do |command|
+      klass.increment unless klass.skip_command?(command)
+    end
+    yield
+  end
+
+  def call_once(command, _config)
+    klass.increment unless klass.skip_command?(command)
+    yield
+  end
 end
 # rubocop:enable ThreadSafety/ClassInstanceVariable