familia 2.0.0.pre5 → 2.0.0.pre7

data/lib/familia/features/transient_fields.rb

@@ -4,23 +4,120 @@ require_relative 'transient_fields/redacted_string'
 
 module Familia
   module Features
-    # Familia::Features::TransientFields
+    # TransientFields is a feature that provides secure handling of sensitive runtime data
+    # that should never be persisted to Redis/Valkey. Unlike encrypted fields, transient
+    # fields exist only in memory and are automatically wrapped in RedactedString objects
+    # for security.
     #
-    # 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.
+    # Transient fields are ideal for:
+    # - API keys and tokens that change frequently
+    # - Temporary passwords or passphrases
+    # - Session-specific secrets
+    # - Any sensitive data that should never touch persistent storage
+    # - Debug or development secrets that need secure handling
+    #
+    # All transient field values are automatically wrapped in RedactedString instances
+    # which provide:
+    # - Automatic redaction in logs and string representations
+    # - Secure memory management with explicit cleanup
+    # - Safe access patterns through expose blocks
+    # - Protection against accidental value exposure
+    #
+    # Example:
+    #
+    #   class ApiClient < Familia::Horreum
+    #     feature :transient_fields
+    #
+    #     field :endpoint          # Regular persistent field
+    #     transient_field :token   # Transient field (not persisted)
+    #     transient_field :secret, as: :api_secret  # Custom accessor name
+    #   end
+    #
+    #   client = ApiClient.new(
+    #     endpoint: 'https://api.example.com',
+    #     token: ENV['API_TOKEN'],
+    #     secret: ENV['API_SECRET']
+    #   )
+    #
+    #   # Regular field persists
+    #   client.save
+    #   client.endpoint  # => "https://api.example.com"
+    #
+    #   # Transient fields are RedactedString instances
+    #   puts client.token  # => "[REDACTED]"
+    #
+    #   # Access the actual value safely
+    #   client.token.expose do |token|
+    #     response = HTTP.post(client.endpoint,
+    #       headers: { 'Authorization' => "Bearer #{token}" }
+    #     )
+    #     # Token value is only available within this block
+    #   end
+    #
+    #   # Explicit cleanup when done
+    #   client.token.clear!
+    #
+    # Security Features:
+    #
+    # RedactedString automatically protects sensitive values:
+    # - String representation shows "[REDACTED]" instead of actual value
+    # - Inspect output shows "[REDACTED]" instead of actual value
+    # - Hash values are constant to prevent value inference
+    # - Equality checks work only on object identity
+    #
+    # Safe Access Patterns:
+    #
+    #   # ✅ Recommended: Use .expose block
+    #   client.token.expose do |token|
+    #     # Use token directly without creating copies
+    #     HTTP.auth("Bearer #{token}")  # Safe
+    #   end
+    #
+    #   # ✅ Direct access (use carefully)
+    #   raw_token = client.token.value
+    #   # Remember to clear original source if needed
+    #
+    #   # ❌ Avoid: These create uncontrolled copies
+    #   token_copy = client.token.value.dup      # Creates copy in memory
+    #   interpolated = "Bearer #{client.token}"  # Creates copy via to_s
+    #
+    # Memory Management:
+    #
+    #   # Clear individual fields
+    #   client.token.clear!
+    #
+    #   # Check if cleared
+    #   client.token.cleared?  # => true
+    #
+    #   # Accessing cleared values raises error
+    #   client.token.value  # => SecurityError: Value already cleared
+    #
+    # ⚠️ Important Security Limitations:
+    #
+    # Ruby provides NO memory safety guarantees for cryptographic secrets:
+    # - No secure wiping: .clear! is best-effort only
+    # - GC copying: Garbage collector may duplicate secrets
+    # - String operations: Every manipulation creates copies
+    # - Memory persistence: Secrets may remain in memory indefinitely
+    #
+    # For highly sensitive applications, consider external secrets management
+    # (HashiCorp Vault, AWS Secrets Manager) or languages with secure memory handling.
     #
     module TransientFields
       def self.included(base)
-        Familia.ld "[#{base}] Loaded #{self}"
+        Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
         base.extend ClassMethods
+
+        # Initialize transient fields tracking
+        base.instance_variable_set(:@transient_fields, []) unless base.instance_variable_defined?(:@transient_fields)
       end
 
-      # ClassMethods
-      #
       module ClassMethods
         # Define a transient field that automatically wraps values in RedactedString
         #
+        # Transient fields are not persisted to Redis/Valkey and exist only in memory.
+        # All values are automatically wrapped in RedactedString for security.
+        #
         # @param name [Symbol] The field name
         # @param as [Symbol] The method name (defaults to field name)
         # @param kwargs [Hash] Additional field options
@@ -31,14 +128,99 @@ module Familia
         #     transient_field :api_key
         #   end
         #
+        # @example Define a transient field with custom accessor name
+        #   class Service < Familia::Horreum
+        #     feature :transient_fields
+        #     transient_field :secret_key, as: :api_secret
+        #   end
+        #
+        #   service = Service.new(secret_key: 'secret123')
+        #   service.api_secret.expose { |key| use_api_key(key) }
+        #
         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
+          @transient_fields ||= []
+          @transient_fields << name unless @transient_fields.include?(name)
+
+          # Use the field type system for proper integration
           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
+
+        # Returns list of transient field names defined on this class
+        #
+        # @return [Array<Symbol>] Array of transient field names
+        #
+        def transient_fields
+          @transient_fields || []
+        end
+
+        # Check if a field is transient
+        #
+        # @param field_name [Symbol] The field name to check
+        # @return [Boolean] true if field is transient, false otherwise
+        #
+        def transient_field?(field_name)
+          transient_fields.include?(field_name.to_sym)
+        end
+      end
+
+      # Clear all transient fields for this instance
+      #
+      # This method iterates through all defined transient fields and calls
+      # clear! on each RedactedString instance. Use this for cleanup when
+      # the object is no longer needed.
+      #
+      # @return [void]
+      #
+      # @example Clear all secrets when done
+      #   client = ApiClient.new(token: 'secret', api_key: 'key123')
+      #   # ... use client ...
+      #   client.clear_transient_fields!
+      #   client.token.cleared?  # => true
+      #
+      def clear_transient_fields!
+        self.class.transient_fields.each do |field_name|
+          field_value = instance_variable_get("@#{field_name}")
+          if field_value.respond_to?(:clear!)
+            field_value.clear!
+          end
+        end
+      end
+
+      # Check if all transient fields have been cleared
+      #
+      # @return [Boolean] true if all transient fields are cleared, false otherwise
+      #
+      def transient_fields_cleared?
+        self.class.transient_fields.all? do |field_name|
+          field_value = instance_variable_get("@#{field_name}")
+          field_value.nil? || (field_value.respond_to?(:cleared?) && field_value.cleared?)
+        end
+      end
+
+      # Returns a hash of transient field names and their redacted representations
+      #
+      # This method is useful for debugging and logging as it shows which transient
+      # fields are defined without exposing their actual values.
+      #
+      # @return [Hash] Hash with field names as keys and "[REDACTED]" as values
+      #
+      # @example Check transient field status
+      #   client.transient_fields_summary
+      #   # => { token: "[REDACTED]", api_key: "[REDACTED]" }
+      #
+      def transient_fields_summary
+        self.class.transient_fields.each_with_object({}) do |field_name, summary|
+          field_value = instance_variable_get("@#{field_name}")
+          if field_value.nil?
+            summary[field_name] = nil
+          elsif field_value.respond_to?(:cleared?) && field_value.cleared?
+            summary[field_name] = "[CLEARED]"
+          else
+            summary[field_name] = "[REDACTED]"
+          end
+        end
       end
 
       Familia::Base.add_feature self, :transient_fields, depends_on: nil

data/lib/familia/features.rb

@@ -60,13 +60,14 @@ module Familia
     end
 
   end
-
 end
 
 # Load all feature files from the features directory
 features_dir = File.join(__dir__, 'features')
+Familia.ld "[DEBUG] Loading features from #{features_dir}"
 if Dir.exist?(features_dir)
   Dir.glob(File.join(features_dir, '*.rb')).each do |feature_file|
+    Familia.ld "[DEBUG] Loading feature #{feature_file}"
     require_relative feature_file
   end
 end

data/lib/familia/field_type.rb

@@ -27,7 +27,7 @@ module Familia
   #   end
   #
   class FieldType
-    attr_reader :name, :options, :method_name, :fast_method_name, :on_conflict
+    attr_reader :name, :options, :method_name, :fast_method_name, :on_conflict, :loggable
 
     # Initialize a new field type
     #
@@ -38,9 +38,11 @@ module Familia
     #   (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, **options)
+    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
@@ -51,6 +53,7 @@ module Familia
       end
 
       @on_conflict = on_conflict
+      @loggable = loggable
       @options = options
     end
 

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

@@ -2,8 +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
 
@@ -69,11 +69,5 @@ module Familia
         block_result
       end
     end
-
-    # include for instance methods after it's loaded. Note that Horreum::Utils
-    # are also included and at one time also has a uri method. This connection
-    # module is also extended for the class level methods. It will require some
-    # disambiguation at some point.
-    include Familia::Horreum::Connection
   end
 end

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

@@ -37,7 +37,7 @@ 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?
@@ -106,6 +106,19 @@ module Familia
         dbclient.hset dbkey, field, value
       end
 
+      # 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?
@@ -165,7 +178,5 @@ module Familia
       end
       alias clear delete!
     end
-
-    include DatabaseCommands # these become Familia::Horreum instance methods
   end
 end