familia 2.0.0.pre6 → 2.0.0.pre8

data/lib/familia/features/expiration.rb

@@ -2,48 +2,222 @@
 
 module Familia
   module Features
-    # Famnilia::Features::Expiration
+    # Expiration is a feature that provides Time To Live (TTL) management for Familia
+    # objects and their associated Redis/Valkey data structures. It enables automatic
+    # data cleanup and supports cascading expiration across related objects.
+    #
+    # This feature allows you to:
+    # - Set default expiration times at the class level
+    # - Update expiration times for individual objects
+    # - Cascade expiration settings to related data structures
+    # - Query remaining TTL for objects
+    # - Handle expiration inheritance in class hierarchies
+    #
+    # Example:
+    #
+    #   class Session < Familia::Horreum
+    #     feature :expiration
+    #     default_expiration 1.hour
+    #
+    #     field :user_id, :data, :created_at
+    #     list :activity_log
+    #   end
+    #
+    #   session = Session.new(user_id: 123, data: { role: 'admin' })
+    #   session.save
+    #
+    #   # Automatically expires in 1 hour (default_expiration)
+    #   session.ttl  # => 3599 (seconds remaining)
+    #
+    #   # Update expiration to 30 minutes
+    #   session.update_expiration(30.minutes)
+    #   session.ttl  # => 1799
+    #
+    #   # Set custom expiration for new objects
+    #   session.update_expiration(default_expiration: 2.hours)
+    #
+    # Class-Level Configuration:
+    #
+    # Default expiration can be set at the class level and will be inherited
+    # by subclasses unless overridden:
+    #
+    #   class BaseModel < Familia::Horreum
+    #     feature :expiration
+    #     default_expiration 1.day
+    #   end
+    #
+    #   class ShortLivedModel < BaseModel
+    #     default_expiration 5.minutes  # Overrides parent
+    #   end
+    #
+    #   class InheritedModel < BaseModel
+    #     # Inherits 1.day from BaseModel
+    #   end
+    #
+    # Cascading Expiration:
+    #
+    # When an object has related data structures (lists, sets, etc.), the
+    # expiration feature automatically applies TTL to all related structures:
+    #
+    #   class User < Familia::Horreum
+    #     feature :expiration
+    #     default_expiration 30.days
+    #
+    #     field :email, :name
+    #     list :sessions        # Will also expire in 30 days
+    #     set :permissions      # Will also expire in 30 days
+    #     hashkey :preferences  # Will also expire in 30 days
+    #   end
+    #
+    # Fine-Grained Control:
+    #
+    # Related structures can have their own expiration settings:
+    #
+    #   class Analytics < Familia::Horreum
+    #     feature :expiration
+    #     default_expiration 1.year
+    #
+    #     field :metric_name
+    #     list :hourly_data, default_expiration: 1.week    # Shorter TTL
+    #     list :daily_data, default_expiration: 1.month    # Medium TTL
+    #     list :monthly_data  # Uses class default (1.year)
+    #   end
+    #
+    # Zero Expiration:
+    #
+    # Setting expiration to 0 (zero) disables TTL, making data persist indefinitely:
+    #
+    #   session.update_expiration(default_expiration: 0)  # No expiration
+    #
+    # TTL Querying:
+    #
+    # Check remaining time before expiration:
+    #
+    #   session.ttl           # => 3599 (seconds remaining)
+    #   session.ttl.zero?     # => false (still has time)
+    #   expired_session.ttl   # => -1 (already expired or no TTL set)
+    #
+    # Integration Patterns:
+    #
+    #   # Conditional expiration based on user type
+    #   class UserSession < Familia::Horreum
+    #     feature :expiration
+    #
+    #     field :user_id, :user_type
+    #
+    #     def save
+    #       super
+    #       case user_type
+    #       when 'premium'
+    #         update_expiration(7.days)
+    #       when 'free'
+    #         update_expiration(1.hour)
+    #       else
+    #         update_expiration(default_expiration)
+    #       end
+    #     end
+    #   end
+    #
+    #   # Background job cleanup
+    #   class DataCleanupJob
+    #     def perform
+    #       # Extend expiration for active users
+    #       active_sessions = Session.where(active: true)
+    #       active_sessions.each do |session|
+    #         session.update_expiration(session.default_expiration)
+    #       end
+    #     end
+    #   end
+    #
+    # Error Handling:
+    #
+    # The feature validates expiration values and raises descriptive errors:
+    #
+    #   session.update_expiration(default_expiration: "invalid")
+    #   # => Familia::Problem: Default expiration must be a number
+    #
+    #   session.update_expiration(default_expiration: -1)
+    #   # => Familia::Problem: Default expiration must be non-negative
+    #
+    # Performance Considerations:
+    #
+    # - TTL operations are performed on Redis/Valkey side with minimal overhead
+    # - Cascading expiration uses pipelining for efficiency when possible
+    # - Zero expiration values skip Redis EXPIRE calls entirely
+    # - TTL queries are direct Redis operations (very fast)
     #
     module Expiration
       @default_expiration = nil
 
       def self.included(base)
-        Familia.trace :LOADED!, nil, self, caller(1..1) if Familia.debug?
+        Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
         base.extend ClassMethods
 
-        # Optionally define default_expiration in the class to make
-        # sure we always have an array to work with.
+        # Initialize default_expiration instance variable if not already defined
+        # This ensures the class has a place to store its default expiration setting
         return if base.instance_variable_defined?(:@default_expiration)
 
-        base.instance_variable_set(:@default_expiration, @default_expiration) # set above
+        base.instance_variable_set(:@default_expiration, @default_expiration)
       end
 
-      # ClassMethods
-      #
       module ClassMethods
+        # Set the default expiration time for instances of this class
+        #
+        # @param expiration [Numeric] Time in seconds (can be fractional)
+        #
         attr_writer :default_expiration
 
+        # Get or set the default expiration time for this class
+        #
+        # When called with an argument, sets the default expiration.
+        # When called without arguments, returns the current default expiration,
+        # checking parent classes and falling back to Familia.default_expiration.
+        #
+        # @param num [Numeric, nil] Expiration time in seconds
+        # @return [Float] The default expiration in seconds
+        #
+        # @example Set default expiration
+        #   class MyModel < Familia::Horreum
+        #     feature :expiration
+        #     default_expiration 1.hour
+        #   end
+        #
+        # @example Get default expiration
+        #   MyModel.default_expiration  # => 3600.0
+        #
         def default_expiration(num = nil)
           @default_expiration = num.to_f unless num.nil?
           @default_expiration || parent&.default_expiration || Familia.default_expiration
         end
       end
 
+      # Set the default expiration time for this instance
+      #
+      # @param num [Numeric] Expiration time in seconds
+      #
       def default_expiration=(num)
         @default_expiration = num.to_f
       end
 
+      # Get the default expiration time for this instance
+      #
+      # Returns the instance-specific default expiration, falling back to
+      # class default expiration if not set.
+      #
+      # @return [Float] The default expiration in seconds
+      #
       def default_expiration
         @default_expiration || self.class.default_expiration
       end
 
-      # Sets an expiration time for the Database data associated with this object.
+      # Sets an expiration time for the Redis/Valkey data associated with this object
       #
       # This method allows setting a Time To Live (TTL) for the data in Redis,
-      # after which it will be automatically removed.
+      # after which it will be automatically removed. The method also handles
+      # cascading expiration to related data structures when applicable.
       #
-      # @param default_expiration [Integer, nil] The Time To Live in seconds. If nil, the default
-      #   TTL will be used.
+      # @param default_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.
@@ -51,18 +225,26 @@ module Familia
       # @example Setting an expiration of one day
       #   object.update_expiration(default_expiration: 86400)
       #
-      # @note If Default expiration is set to zero, the expiration will be removed, making the
-      #   data persist indefinitely.
+      # @example Using default expiration
+      #   object.update_expiration  # Uses class default_expiration
+      #
+      # @example Removing expiration (persist indefinitely)
+      #   object.update_expiration(default_expiration: 0)
+      #
+      # @note If default expiration is set to zero, the expiration will be removed,
+      #   making the data persist indefinitely.
       #
-      # @raise [Familia::Problem] Raises an error if the default expiration is not a non-negative
-      #   integer.
+      # @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
 
-        if self.class.has_relations?
+        # Handle cascading expiration to related data structures
+        if self.class.relations?
           Familia.ld "[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)
@@ -71,30 +253,103 @@ module Familia
           end
         end
 
+        # Validate expiration value
         # 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).
-        #
-        # For the same reason, we don't want to default to 0 bc there's not a
-        # good reason for the default_expiration to not be set in the first place. If the
-        # class doesn't have a default_expiration, the default comes from
-        # Familia.default_expiration (which is 0, aka no-op/skip/do nothing).
         unless default_expiration.is_a?(Numeric)
-          raise Familia::Problem, "Default expiration must be a number (#{default_expiration.class} in #{self.class})"
+          raise Familia::Problem, "Default expiration must be a number (#{default_expiration.class} given for #{self.class})"
         end
 
-        # If zero, simply skips setting an expiry for this key. If we were to set
-        # 0 the database would drop the key immediately.
-        return Familia.ld "[update_expiration] No expiration for #{self.class} (#{dbkey})" if default_expiration.zero?
+        unless default_expiration >= 0
+          raise Familia::Problem, "Default expiration must be non-negative (#{default_expiration} given for #{self.class})"
+        end
+
+        # If zero, simply skip setting an expiry for this key. If we were to set
+        # 0, Redis would drop the key immediately.
+        if default_expiration.zero?
+          Familia.ld "[update_expiration] No expiration for #{self.class} (#{dbkey})"
+          return true
+        end
 
         Familia.ld "[update_expiration] Expires #{dbkey} in #{default_expiration} seconds"
 
         # 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 here, it's
-        # a bool.
+        # not exist or the timeout could not be set. Via redis-rb, it's a boolean.
         expire(default_expiration)
       end
 
+      # Get the remaining time to live for this object's data
+      #
+      # @return [Integer] Seconds remaining before expiration, or -1 if no TTL is set
+      #
+      # @example Check remaining TTL
+      #   session.ttl  # => 3599 (expires in ~1 hour)
+      #   session.ttl.zero?  # => false
+      #
+      # @example Check if expired or no TTL
+      #   expired_session.ttl  # => -1
+      #
+      def ttl
+        redis.ttl(dbkey)
+      end
+
+      # Check if this object's data will expire
+      #
+      # @return [Boolean] true if TTL is set, false if data persists indefinitely
+      #
+      def expires?
+        ttl > 0
+      end
+
+      # Check if this object's data has expired or will expire soon
+      #
+      # @param threshold [Numeric] Consider expired if TTL is below this threshold (default: 0)
+      # @return [Boolean] true if expired or expiring soon
+      #
+      # @example Check if expired
+      #   session.expired?  # => true if TTL <= 0
+      #
+      # @example Check if expiring within 5 minutes
+      #   session.expired?(5.minutes)  # => true if TTL <= 300
+      #
+      def expired?(threshold = 0)
+        current_ttl = ttl
+        return false if current_ttl == -1 # no expiration set
+        return true  if current_ttl == -2 # key does not exist
+        current_ttl <= threshold
+      end
+
+      # Extend the expiration time by the specified duration
+      #
+      # This adds the given duration to the current TTL, effectively extending
+      # the object's lifetime without changing the default expiration setting.
+      #
+      # @param duration [Numeric] Additional time in seconds
+      # @return [Boolean] Success of the operation
+      #
+      # @example Extend session by 1 hour
+      #   session.extend_expiration(1.hour)
+      #
+      def extend_expiration(duration)
+        current_ttl = ttl
+        return false if current_ttl < 0  # No current expiration set
+
+        new_ttl = current_ttl + duration.to_f
+        expire(new_ttl)
+      end
+
+      # Remove expiration, making the object persist indefinitely
+      #
+      # @return [Boolean] Success of the operation
+      #
+      # @example Make session persistent
+      #   session.persist!
+      #
+      def persist!
+        redis.persist(dbkey)
+      end
+
       Familia::Base.add_feature self, :expiration
     end
   end
@@ -109,22 +364,53 @@ module Familia
     # Base implementation of update_expiration that maintains API compatibility
     # with the :expiration feature's implementation.
     #
-    # This is a no-op implementation that gets overridden by features like
-    # :expiration. It accepts an optional default_expiration parameter to maintain interface
-    # compatibility with the overriding implementations.
+    # 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.
     #
-    # @param default_expiration [Integer, nil] Time To Live in seconds
-    # @return [nil] Always returns nil
+    # @param default_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
+    #
     def update_expiration(default_expiration: nil)
       Familia.ld <<~LOG
-        [update_expiration] Feature not enabled for #{self.class}.
+        [update_expiration] Expiration feature not enabled for #{self.class}.
         Key: #{dbkey} Arg: #{default_expiration} (caller: #{caller(1..1)})
       LOG
       nil
     end
+
+    # Base implementation of ttl that returns -1 (no expiration set)
+    #
+    # @return [Integer] Always returns -1 for the base implementation
+    #
+    def ttl
+      -1
+    end
+
+    # Base implementation of expires? that returns false
+    #
+    # @return [Boolean] Always returns false for the base implementation
+    #
+    def expires?
+      false
+    end
+
+    # Base implementation of expired? that returns false
+    #
+    # @param threshold [Numeric] Ignored in base implementation
+    # @return [Boolean] Always returns false for the base implementation
+    #
+    def expired?(_threshold = 0)
+      false
+    end
   end
 end

data/lib/familia/features/external_identifiers/external_identifier_field_type.rb

@@ -0,0 +1,120 @@
+# lib/familia/features/external_identifiers/external_identifier_field_type.rb
+
+require 'familia/field_type'
+
+module Familia
+  module Features
+    module ExternalIdentifiers
+      # ExternalIdentifierFieldType - Fields that generate deterministic external identifiers
+      #
+      # External identifier fields generate shorter, public-facing identifiers that are
+      # deterministically derived from object identifiers. These IDs are safe for use
+      # in URLs, APIs, and other external contexts where shorter IDs are preferred.
+      #
+      # Key characteristics:
+      # - Deterministic generation from objid ensures consistency
+      # - Shorter than objid (128-bit vs 256-bit) for external use
+      # - Base-36 encoding for URL-safe identifiers
+      # - 'ext_' prefix for clear identification as external IDs
+      # - Lazy generation preserves values from initialization
+      #
+      # @example Using external identifier fields
+      #   class User < Familia::Horreum
+      #     feature :object_identifiers
+      #     feature :external_identifiers
+      #     field :email
+      #   end
+      #
+      #   user = User.new(email: 'user@example.com')
+      #   user.objid  # => "01234567-89ab-7def-8000-123456789abc"
+      #   user.extid  # => "ext_abc123def456ghi789" (deterministic from objid)
+      #
+      #   # Same objid always produces same extid
+      #   user2 = User.new(objid: user.objid, email: 'user@example.com')
+      #   user2.extid  # => "ext_abc123def456ghi789" (identical to user.extid)
+      #
+      class ExternalIdentifierFieldType < FieldType
+        # Override getter to provide lazy generation from objid
+        #
+        # Generates the external identifier deterministically from the object's
+        # objid. This ensures consistency - the same objid will always produce
+        # the same extid. Only generates when objid is available.
+        #
+        # @param klass [Class] The class to define the method on
+        #
+        def define_getter(klass)
+          field_name = @name
+          method_name = @method_name
+
+          handle_method_conflict(klass, method_name) do
+            klass.define_method method_name do
+              # Check if we already have a value (from initialization or previous generation)
+              existing_value = instance_variable_get(:"@#{field_name}")
+              return existing_value unless existing_value.nil?
+
+              # Generate external identifier from objid if available
+              generated_extid = generate_external_identifier
+              return unless generated_extid
+
+              instance_variable_set(:"@#{field_name}", generated_extid)
+
+              # Update mapping if we have an identifier
+              if respond_to?(:identifier) && identifier
+                self.class.extid_lookup[generated_extid] = identifier
+              end
+
+              generated_extid
+            end
+          end
+        end
+
+        # Override setter to preserve values during initialization
+        #
+        # This ensures that values passed during object initialization
+        # (e.g., when loading from Redis) are preserved and not overwritten
+        # by the lazy generation logic.
+        #
+        # @param klass [Class] The class to define the method on
+        #
+        def define_setter(klass)
+          field_name = @name
+          method_name = @method_name
+
+          handle_method_conflict(klass, :"#{method_name}=") do
+            klass.define_method :"#{method_name}=" do |value|
+              # Remove old mapping if extid is changing
+              old_value = instance_variable_get(:"@#{field_name}")
+              if old_value && old_value != value && respond_to?(:identifier)
+                self.class.extid_lookup.del(old_value)
+              end
+
+              # Set the new value
+              instance_variable_set(:"@#{field_name}", value)
+
+              # Update mapping if we have both extid and identifier
+              if value && respond_to?(:identifier) && identifier
+                self.class.extid_lookup[value] = identifier
+              end
+            end
+          end
+        end
+
+        # External identifier fields are persisted to database
+        #
+        # @return [Boolean] true - external identifiers are always persisted
+        #
+        def persistent?
+          true
+        end
+
+        # Category for external identifier fields
+        #
+        # @return [Symbol] :external_identifier
+        #
+        def category
+          :external_identifier
+        end
+      end
+    end
+  end
+end

data/lib/familia/features/external_identifiers.rb

@@ -0,0 +1,111 @@
+# lib/familia/features/external_identifiers.rb
+
+require_relative 'external_identifiers/external_identifier_field_type'
+
+module Familia
+  module Features
+
+    # Familia::Features::ExternalIdentifiers
+    #
+    module ExternalIdentifiers
+      def self.included(base)
+        Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
+        base.extend ClassMethods
+
+        # Ensure default prefix is set in feature options
+        base.add_feature_options(:external_identifiers, prefix: 'ext')
+
+        # Add class-level mapping for extid -> id lookups
+        base.class_hashkey :extid_lookup
+
+        # Register the extid field using our custom field type
+        base.register_field_type(
+          ExternalIdentifiers::ExternalIdentifierFieldType.new(:extid, as: :extid, fast_method: false)
+        )
+      end
+
+      # ExternalIdentifiers::ClassMethods
+      #
+      module ClassMethods
+        def generate_extid(objid = nil)
+          unless features_enabled.include?(:object_identifiers)
+            raise Familia::Problem,
+                  'ExternalIdentifiers requires ObjectIdentifiers feature'
+          end
+          return nil if objid.to_s.empty?
+
+          objid_hex = objid.to_s.delete('-')
+          external_part = Familia.shorten_to_external_id(objid_hex, base: 36)
+          prefix = feature_options(:external_identifiers)[:prefix] || 'ext'
+          "#{prefix}_#{external_part}"
+        end
+
+        # Find an object by its external identifier
+        #
+        # @param extid [String] The external identifier to search for
+        # @return [Object, nil] The object if found, nil otherwise
+        #
+        def find_by_extid(extid)
+          return nil if extid.to_s.empty?
+
+          if Familia.debug?
+            reference = caller(1..1).first
+            Familia.trace :FIND_BY_EXTID, Familia.dbclient, extid, reference
+          end
+
+          # Look up the primary ID from the external ID mapping
+          primary_id = extid_lookup[extid]
+          return nil if primary_id.nil?
+
+          # Find the object by its primary ID
+          find_by_id(primary_id)
+        rescue Familia::NotFound
+          # If the object was deleted but mapping wasn't cleaned up
+          extid_lookup.del(extid)
+          nil
+        end
+      end
+
+      # Generate external identifier deterministically from objid
+      def generate_external_identifier
+        return nil unless respond_to?(:objid)
+
+        current_objid = objid
+        return nil if current_objid.nil? || current_objid.to_s.empty?
+
+        # Convert objid to hex string for processing
+        objid_hex = current_objid.delete('-') # Remove UUID hyphens if present
+
+        # Generate deterministic external ID using SecureIdentifier
+        external_part = Familia.shorten_to_external_id(objid_hex, base: 36)
+
+        # Get prefix from feature options, default to "ext"
+        options = self.class.feature_options(:external_identifiers)
+        prefix = options[:prefix] || 'ext'
+
+        "#{prefix}_#{external_part}"
+      end
+
+      def external_identifier
+        extid
+      end
+
+      def init
+        super if defined?(super)
+        # External IDs are generated from objid, so no additional setup needed
+      end
+
+      def destroy!
+        # Clean up extid mapping when object is destroyed
+        current_extid = instance_variable_get(:@extid)
+        if current_extid
+          self.class.extid_lookup.del(current_extid)
+        end
+
+        super if defined?(super)
+      end
+
+      Familia::Base.add_feature self, :external_identifiers, depends_on: [:object_identifiers]
+    end
+  end
+end