familia 2.0.0.pre4 → 2.0.0.pre6

data/lib/familia/features/transient_fields.rb

@@ -0,0 +1,47 @@
+# lib/familia/features/transient_fields.rb
+
+require_relative 'transient_fields/redacted_string'
+
+module Familia
+  module Features
+    # Familia::Features::TransientFields
+    #
+    # Provides secure transient fields that wrap sensitive values in RedactedString
+    # objects. These fields are excluded from serialization operations and provide
+    # automatic memory wiping for security.
+    #
+    module TransientFields
+      def self.included(base)
+        Familia.trace :included, base, self, caller(1..1) if Familia.debug?
+        base.extend ClassMethods
+      end
+
+      # ClassMethods
+      #
+      module ClassMethods
+        # Define a transient field that automatically wraps values in RedactedString
+        #
+        # @param name [Symbol] The field name
+        # @param as [Symbol] The method name (defaults to field name)
+        # @param kwargs [Hash] Additional field options
+        #
+        # @example Define a transient API key field
+        #   class Service < Familia::Horreum
+        #     feature :transient_fields
+        #     transient_field :api_key
+        #   end
+        #
+        def transient_field(name, as: name, **kwargs)
+          # Use the field type system - much cleaner than alias_method approach!
+          # We can now remove the transient_field method from this feature entirely
+          # since it's built into DefinitionMethods using TransientFieldType
+          require_relative 'transient_fields/transient_field_type'
+          field_type = TransientFieldType.new(name, as: as, **kwargs.merge(fast_method: false))
+          register_field_type(field_type)
+        end
+      end
+
+      Familia::Base.add_feature self, :transient_fields, depends_on: nil
+    end
+  end
+end

data/lib/familia/features.rb

@@ -2,45 +2,61 @@
 
 module Familia
 
+  FeatureDefinition = Data.define(:name, :depends_on)
+
+  # Familia::Features
+  #
   module Features
 
     @features_enabled = nil
     attr_reader :features_enabled
 
-    def feature(val = nil)
+    def feature(feature_name = nil)
       @features_enabled ||= []
 
-      # If there's a value provied check that it's a valid feature
-      if val
-        val = val.to_sym
-        raise Familia::Problem, "Unsupported feature: #{val}" unless Familia::Base.features.key?(val)
+      return features_enabled if feature_name.nil?
 
-        # If the feature is already enabled, do nothing but log about it
-        if @features_enabled.member?(val)
-          Familia.warn "[Familia::Settings] feature already enabled: #{val}"
-          return
-        end
+      # If there's a value provied check that it's a valid feature
+      feature_name = feature_name.to_sym
+      unless Familia::Base.features_available.key?(feature_name)
+        raise Familia::Problem, "Unsupported feature: #{feature_name}"
+      end
 
-        Familia.trace :FEATURE, nil, "#{self} includes #{val.inspect}", caller(1..1) if Familia.debug?
+      # If the feature is already available, do nothing but log about it
+      if features_enabled.member?(feature_name)
+        Familia.warn "[#{self.class}] feature already available: #{feature_name}"
+        return
+      end
 
-        klass = Familia::Base.features[val]
+      if Familia.debug?
+        Familia.trace :FEATURE, nil, "#{self} includes #{feature_name.inspect}", caller(1..1)
+      end
 
-        # Extend the Familia::Base subclass (e.g. Customer) with the feature module
-        include klass
+      # Add it to the list available features_enabled for Familia::Base classes.
+      features_enabled << feature_name
 
-        # NOTE: We may also want to extend Familia::DataType here so that we can
-        # call safe_dump on relations fields (e.g. list, set, zset, hashkey). Or
-        # maybe that only makes sense for hashk/object relations.
-        #
-        # We'd need to avoid it getting included multiple times (i.e. once for each
-        # Familia::Horreum subclass that includes the feature).
+      klass = Familia::Base.features_available[feature_name]
 
-        # Now that the feature is loaded successfully, add it to the list
-        # enabled features for Familia::Base classes.
-        @features_enabled << val
+      # Validate dependencies
+      feature_def = Familia::Base.feature_definitions[feature_name]
+      if feature_def&.depends_on&.any?
+        missing = feature_def.depends_on - features_enabled
+        raise Familia::Problem, "#{feature_name} requires: #{missing.join(', ')}" if missing.any?
       end
 
-      features_enabled
+      # Extend the Familia::Base subclass (e.g. Customer) with the feature module
+      include klass
+
+      # NOTE: Do we want to extend Familia::DataType here? That would make it
+      # possible to call safe_dump on relations fields (e.g. list, zset, hashkey).
+      #
+      # The challenge is that DataType classes (List, Set, etc.) are shared across
+      # all Horreum models. If Customer extends DataType with safe_dump, then
+      # Session's lists would also have it. Not ideal. If that's all we wanted
+      # then we can do that by looping through every DataType class here.
+      #
+      # We'd need to extend the DataType instances for each Horreum subclass. That
+      # avoids it getting included multiple times per DataType
     end
 
   end

data/lib/familia/field_type.rb

@@ -0,0 +1,273 @@
+# lib/familia/field_type.rb
+
+module Familia
+  # Base class for all field types in Familia
+  #
+  # Field types encapsulate the behavior for different kinds of fields,
+  # including how their getter/setter methods are defined and how values
+  # are serialized/deserialized.
+  #
+  # @example Creating a custom field type
+  #   class TimestampFieldType < Familia::FieldType
+  #     def define_setter(klass)
+  #       field_name = @name
+  #       klass.define_method :"#{@method_name}=" do |value|
+  #         timestamp = value.is_a?(Time) ? value.to_i : value
+  #         instance_variable_set(:"@#{field_name}", timestamp)
+  #       end
+  #     end
+  #
+  #     def define_getter(klass)
+  #       field_name = @name
+  #       klass.define_method @method_name do
+  #         timestamp = instance_variable_get(:"@#{field_name}")
+  #         timestamp ? Time.at(timestamp) : nil
+  #       end
+  #     end
+  #   end
+  #
+  class FieldType
+    attr_reader :name, :options, :method_name, :fast_method_name, :on_conflict, :loggable
+
+    # Initialize a new field type
+    #
+    # @param name [Symbol] The field name
+    # @param as [Symbol, String, false] The method name (defaults to field name)
+    #   If false, no accessor methods are created
+    # @param fast_method [Symbol, String, false] The fast method name
+    #   (defaults to "#{name}!"). If false, no fast method is created
+    # @param on_conflict [Symbol] Conflict resolution strategy when method
+    #   already exists (:raise, :skip, :warn, :overwrite)
+    # @param loggable [Boolean] Whether this field should be included in
+    #   serialization and logging operations (default: true)
+    # @param options [Hash] Additional options for the field type
+    #
+    def initialize(name, as: name, fast_method: :"#{name}!", on_conflict: :raise, loggable: true, **options)
+      @name = name.to_sym
+      @method_name = as == false ? nil : as.to_sym
+      @fast_method_name = fast_method == false ? nil : fast_method&.to_sym
+
+      # Validate fast method name format
+      if @fast_method_name && !@fast_method_name.to_s.end_with?('!')
+        raise ArgumentError, "Fast method name must end with '!' (got: #{@fast_method_name})"
+      end
+
+      @on_conflict = on_conflict
+      @loggable = loggable
+      @options = options
+    end
+
+    # Install this field type on a class
+    #
+    # This method defines all necessary methods on the target class
+    # and registers the field type for later reference.
+    #
+    # @param klass [Class] The class to install this field type on
+    #
+    def install(klass)
+      if @method_name
+        # For skip strategy, check for any method conflicts first
+        if @on_conflict == :skip
+          has_getter_conflict = klass.method_defined?(@method_name) || klass.private_method_defined?(@method_name)
+          has_setter_conflict = klass.method_defined?(:"#{@method_name}=") || klass.private_method_defined?(:"#{@method_name}=")
+
+          # If either getter or setter conflicts, skip the whole field
+          return if has_getter_conflict || has_setter_conflict
+        end
+
+        define_getter(klass)
+        define_setter(klass)
+      end
+
+      define_fast_writer(klass) if @fast_method_name
+    end
+
+    # Define the getter method on the target class
+    #
+    # Subclasses can override this to customize getter behavior.
+    # The default implementation creates a simple attr_reader equivalent.
+    #
+    # @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
+          instance_variable_get(:"@#{field_name}")
+        end
+      end
+    end
+
+    # Define the setter method on the target class
+    #
+    # Subclasses can override this to customize setter behavior.
+    # The default implementation creates a simple attr_writer equivalent.
+    #
+    # @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|
+          instance_variable_set(:"@#{field_name}", value)
+        end
+      end
+    end
+
+    # Define the fast writer method on the target class
+    #
+    # Fast methods provide direct database access for immediate persistence.
+    # Subclasses can override this to customize fast method behavior.
+    #
+    # @param klass [Class] The class to define the method on
+    #
+    def define_fast_writer(klass)
+      return unless @fast_method_name&.to_s&.end_with?('!')
+
+      field_name = @name
+      method_name = @method_name
+      fast_method_name = @fast_method_name
+
+      handle_method_conflict(klass, fast_method_name) do
+        klass.define_method fast_method_name do |*args|
+          raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0 or 1)" if args.size > 1
+
+          val = args.first
+
+          # If no value provided, return current stored value
+          return hget(field_name) if val.nil?
+
+          begin
+            # Trace the operation if debugging is enabled
+            Familia.trace :FAST_WRITER, dbclient, "#{field_name}: #{val.inspect}", caller(1..1) if Familia.debug?
+
+            # Convert value for database storage
+            prepared = serialize_value(val)
+            Familia.ld "[FieldType#define_fast_writer] #{fast_method_name} val: #{val.class} prepared: #{prepared.class}"
+
+            # Use the setter method to update instance variable
+            send(:"#{method_name}=", val) if method_name
+
+            # Persist to database immediately
+            ret = hset(field_name, prepared)
+            ret.zero? || ret.positive?
+          rescue Familia::Problem => e
+            raise "#{fast_method_name} method failed: #{e.message}", e.backtrace
+          end
+        end
+      end
+    end
+
+    # Whether this field should be persisted to the database
+    #
+    # @return [Boolean] true if field should be persisted
+    #
+    def persistent?
+      true
+    end
+
+    def transient?
+      !persistent?
+    end
+
+    # The category for this field type (used for filtering)
+    #
+    # @return [Symbol] the field category
+    #
+    def category
+      :field
+    end
+
+    # Serialize a value for database storage
+    #
+    # Subclasses can override this to customize serialization.
+    # The default implementation passes values through unchanged.
+    #
+    # @param value [Object] The value to serialize
+    # @param record [Object] The record instance (for context)
+    # @return [Object] The serialized value
+    #
+    def serialize(value, _record = nil)
+      value
+    end
+
+    # Deserialize a value from database storage
+    #
+    # Subclasses can override this to customize deserialization.
+    # The default implementation passes values through unchanged.
+    #
+    # @param value [Object] The value to deserialize
+    # @param record [Object] The record instance (for context)
+    # @return [Object] The deserialized value
+    #
+    def deserialize(value, _record = nil)
+      value
+    end
+
+    # Returns all method names generated for this field (used for conflict detection)
+    #
+    # @return [Array<Symbol>] Array of method names this field type generates
+    #
+    def generated_methods
+      [@method_name, @fast_method_name].compact
+    end
+
+    # Enhanced inspection output for debugging
+    #
+    # @return [String] Human-readable representation
+    #
+    def inspect
+      attributes = [
+        "name=#{@name}",
+        "method_name=#{@method_name}",
+        "fast_method_name=#{@fast_method_name}",
+        "on_conflict=#{@on_conflict}",
+        "category=#{category}"
+      ]
+      "#<#{self.class.name} #{attributes.join(' ')}>"
+    end
+    alias to_s inspect
+
+    private
+
+    # Handle method name conflicts during definition
+    #
+    # @param klass [Class] The target class
+    # @param method_name [Symbol] The method name to define
+    # @yield Block that defines the method
+    #
+    def handle_method_conflict(klass, method_name)
+      case @on_conflict
+      when :skip
+        return if klass.method_defined?(method_name) || klass.private_method_defined?(method_name)
+      when :warn
+        if klass.method_defined?(method_name) || klass.private_method_defined?(method_name)
+          warn <<~WARNING
+
+            WARNING: Method >>> #{method_name} <<< already exists on #{klass}.
+            Field functionality may be broken. Consider using a different name
+            with field(:#{@name}, as: :other_name)
+
+            Called from:
+            #{Familia.pretty_stack(limit: 3)}
+
+          WARNING
+        end
+      when :raise
+        if klass.method_defined?(method_name) || klass.private_method_defined?(method_name)
+          raise ArgumentError, "Method >>> #{method_name} <<< already defined for #{klass}"
+        end
+      when :overwrite
+        # Proceed silently - allow overwrite
+      else
+        raise ArgumentError, "Unknown conflict resolution strategy: #{@on_conflict}"
+      end
+
+      yield
+    end
+  end
+end

data/lib/familia/horreum/{connection.rb → core/connection.rb}

@@ -2,9 +2,8 @@
 
 module Familia
   class Horreum
-
-    # Familia::Horreum::Connection
-    #
+    # Connection: Valkey connection management for Horreum instances
+    # Provides both instance and class-level connection methods
     module Connection
       attr_reader :uri
 
@@ -47,36 +46,28 @@ module Familia
       #
       # @note This method works with the global Familia.transaction context when available
       #
-      def transaction
+      def transaction(&)
         # If we're already in a Familia.transaction context, just yield the multi connection
         if Fiber[:familia_transaction]
           yield(Fiber[:familia_transaction])
         else
           # Otherwise, create a local transaction
-          block_result = dbclient.multi do |conn|
-            yield(conn)
-          end
+          block_result = dbclient.multi(&)
         end
         block_result
       end
       alias multi transaction
 
-      def pipeline
+      def pipeline(&)
         # If we're already in a Familia.pipeline context, just yield the pipeline connection
         if Fiber[:familia_pipeline]
           yield(Fiber[:familia_pipeline])
         else
           # Otherwise, create a local transaction
-          block_result = dbclient.pipeline do |conn|
-            yield(conn)
-          end
+          block_result = dbclient.pipeline(&)
         end
         block_result
       end
-
     end
-
-    # Include Connection module for instance methods after it's loaded
-    include Familia::Horreum::Connection
   end
 end

data/lib/familia/horreum/{commands.rb → core/database_commands.rb}

@@ -1,4 +1,4 @@
-# lib/familia/horreum/commands.rb
+# lib/familia/horreum/database_commands.rb
 
 module Familia
   # InstanceMethods - Module containing instance-level methods for Familia
@@ -7,7 +7,6 @@ module Familia
   # instance-level functionality for Database operations and object management.
   #
   class Horreum
-
     # Methods that call Database commands (InstanceMethods)
     #
     # NOTE: There is no hgetall for Horreum. This is because Horreum
@@ -16,8 +15,7 @@ module Familia
     # emphasize this, instead of "refreshing" the object with hgetall,
     # just load the object again.
     #
-    module Commands
-
+    module DatabaseCommands
       def move(logical_database)
         dbclient.move dbkey, logical_database
       end
@@ -39,8 +37,9 @@ module Familia
       # @note The default behavior maintains backward compatibility by treating empty hashes
       #   as non-existent. Use `check_size: false` for pure key existence checking.
       def exists?(check_size: true)
-        key_exists = self.class.dbclient.exists?(dbkey)
+        key_exists = self.class.exists?(identifier)
         return key_exists unless check_size
+
         key_exists && !size.zero?
       end
 
@@ -83,21 +82,11 @@ module Familia
       end
       alias remove remove_field # deprecated
 
-      def datatype
+      def data_type
         Familia.trace :DATATYPE, dbclient, uri, caller(1..1) if Familia.debug?
         dbclient.type dbkey(suffix)
       end
 
-
-      # Retrieves the prefix for the current instance by delegating to its class.
-      #
-      # @return [String] The prefix associated with the class of the current instance.
-      # @example
-      #   instance.prefix
-      def prefix
-        self.class.prefix
-      end
-
       # For parity with DataType#hgetall
       def hgetall
         Familia.trace :HGETALL, dbclient, uri, caller(1..1) if Familia.debug?
@@ -117,8 +106,21 @@ module Familia
         dbclient.hset dbkey, field, value
       end
 
-      def hmset(hsh={})
-        hsh ||= self.to_h
+      # Sets field in the hash stored at key to value, only if field does not yet exist.
+      # If key does not exist, a new key holding a hash is created. If field already exists,
+      # this operation has no effect.
+      #
+      # @param field [String] The field to set in the hash
+      # @param value [String] The value to set for the field
+      # @return [Integer] 1 if the field is a new field in the hash and the value was set,
+      #   0 if the field already exists in the hash and no operation was performed
+      def hsetnx(field, value)
+        Familia.trace :HSETNX, dbclient, field, caller(1..1) if Familia.debug?
+        dbclient.hsetnx dbkey, field, value
+      end
+
+      def hmset(hsh = {})
+        hsh ||= to_h
         Familia.trace :HMSET, dbclient, hsh, caller(1..1) if Familia.debug?
         dbclient.hmset dbkey(suffix), hsh
       end
@@ -175,9 +177,6 @@ module Familia
         ret.positive?
       end
       alias clear delete!
-
     end
-
-    include Commands # these become Familia::Horreum instance methods
   end
 end