familia 2.0.0.pre4 → 2.0.0.pre6

data/try/features/transient_fields_integration_try.rb

@@ -0,0 +1,260 @@
+# try/features/transient_fields_integration_try.rb
+
+require_relative '../helpers/test_helpers'
+
+class SecretService < Familia::Horreum
+  feature :transient_fields
+  identifier_field :service_id
+
+  field :service_id
+  field :name
+  field :endpoint_url
+  transient_field :api_key
+  transient_field :password
+  transient_field :secret_token, as: :token
+end
+
+@service = SecretService.new
+@service.service_id = 'test_service_1'
+@service.name = 'Test API Service'
+@service.endpoint_url = 'https://api.example.com'
+@service.api_key = 'sk-1234567890abcdef'
+@service.password = 'super_secret_password'
+@service.token = 'token-xyz789'
+
+
+
+## Class includes transient_fields feature
+SecretService.feature(:transient_fields)
+defined?(SecretService.feature)
+#=> "method"
+
+## Class has correct field definitions
+SecretService.fields.sort
+#=> [:api_key, :endpoint_url, :name, :password, :secret_token, :service_id]
+
+## Persistent fields exclude transient ones
+SecretService.persistent_fields.sort
+#=> [:endpoint_url, :name, :service_id]
+
+## Transient field definitions have correct category
+SecretService.field_types[:api_key].category
+#=> :transient
+
+## Password field definition has correct category
+SecretService.field_types[:password].category
+#=> :transient
+
+## Secret token field definition has correct category
+SecretService.field_types[:secret_token].category
+#=> :transient
+
+## Regular field definition has correct category
+SecretService.field_types[:name].category
+#=> :field
+
+## Transient field stores RedactedString object for api_key
+@service.api_key.class
+#=> RedactedString
+
+## Transient field stores RedactedString object for password
+@service.password.class
+#=> RedactedString
+
+## Transient field stores RedactedString object for token alias
+@service.token.class
+#=> RedactedString
+
+## Regular field stores normal string value for name
+@service.name.class
+#=> String
+
+## Regular field stores normal string value for endpoint_url
+@service.endpoint_url.class
+#=> String
+
+## Transient field value is redacted in string representation
+@service.api_key.to_s
+#=> "[REDACTED]"
+
+## Transient field value is redacted in inspect output
+@service.password.inspect
+#=> "[REDACTED]"
+
+## Transient field can expose value securely through block
+result = nil
+@service.api_key.expose { |val| result = val.dup }
+result
+#=> "sk-1234567890abcdef"
+
+## Transient field with custom method name exposes value correctly
+result = nil
+@service.token.expose { |val| result = val.dup }
+result
+#=> "token-xyz789"
+
+## Setting transient field with existing RedactedString works
+already_redacted = RedactedString.new("already_wrapped")
+@service.password = already_redacted
+@service.password.class
+#=> RedactedString
+
+## Serialization to_h only includes persistent fields
+hash_result = @service.to_h
+hash_result.keys.sort
+#=> ["endpoint_url", "name", "service_id"]
+
+## Serialization to_h excludes api_key transient field
+hash_result = @service.to_h
+hash_result.key?("api_key")
+#=> false
+
+## Serialization to_h excludes password transient field
+hash_result = @service.to_h
+hash_result.key?("password")
+#=> false
+
+## Serialization to_h excludes secret_token transient field
+hash_result = @service.to_h
+hash_result.key?("secret_token")
+#=> false
+
+## Serialization to_a only includes persistent field values
+array_result = @service.to_a
+array_result.length
+#=> 3
+
+## Array contains values in persistent field order
+array_result = @service.to_a
+persistent_fields_values = SecretService.persistent_fields.map { |f| @service.send(SecretService.field_types[f].method_name) }
+array_result == persistent_fields_values
+#=> true
+
+## Database persistence only stores persistent fields
+@service.save
+raw_data = @service.hgetall
+raw_data.keys.sort
+#=> ["endpoint_url", "name", "service_id"]
+
+## Raw Database data excludes api_key transient field
+raw_data = @service.hgetall
+raw_data.key?("api_key")
+#=> false
+
+## Raw Database data excludes password transient field
+raw_data = @service.hgetall
+raw_data.key?("password")
+#=> false
+
+## Raw Database data excludes secret_token transient field
+raw_data = @service.hgetall
+raw_data.key?("secret_token")
+#=> false
+
+## Database refresh only loads persistent fields name
+fresh_service = SecretService.new
+fresh_service.service_id = 'test_service_1'
+fresh_service.refresh!
+fresh_service.name
+#=> "Test API Service"
+
+## Database refresh only loads persistent fields endpoint_url
+fresh_service = SecretService.new
+fresh_service.service_id = 'test_service_1'
+fresh_service.refresh!
+fresh_service.endpoint_url
+#=> "https://api.example.com"
+
+## Database refresh leaves transient api_key as nil
+fresh_service = SecretService.new
+fresh_service.service_id = 'test_service_1'
+fresh_service.refresh!
+fresh_service.api_key
+#=> nil
+
+## Database refresh leaves transient password as nil
+fresh_service = SecretService.new
+fresh_service.service_id = 'test_service_1'
+fresh_service.refresh!
+fresh_service.password
+#=> nil
+
+## Database refresh leaves transient token as nil
+fresh_service = SecretService.new
+fresh_service.service_id = 'test_service_1'
+fresh_service.refresh!
+fresh_service.token
+#=> nil
+
+## String interpolation with transient field shows redacted value
+log_message = "Connecting to #{@service.name} with key: #{@service.api_key}"
+log_message.include?("[REDACTED]")
+#=> true
+
+## String interpolation with transient field hides actual value
+log_message = "Connecting to #{@service.name} with key: #{@service.api_key}"
+log_message.include?("sk-1234567890abcdef")
+#=> false
+
+## Hash containing transient field shows redacted in string output
+config_hash = {
+  service: @service.name,
+  key: @service.api_key,
+  url: @service.endpoint_url
+}
+config_hash.to_s.include?("[REDACTED]")
+#=> true
+
+## Hash containing transient field hides actual value in string output
+config_hash = {
+  service: @service.name,
+  key: @service.api_key,
+  url: @service.endpoint_url
+}
+config_hash.to_s.include?("sk-1234567890abcdef")
+#=> false
+
+## Exception messages with transient fields are safe
+begin
+  raise StandardError, "Failed to authenticate with key: #{@service.api_key}"
+rescue => e
+  e.message.include?("[REDACTED]")
+end
+#=> true
+
+## Multiple transient field assignment creates RedactedString instances
+new_service = SecretService.new
+new_service.service_id = 'test_service_2'
+new_service.name = 'Another Service'
+new_service.api_key = 'new-api-key-123'
+new_service.password = 'new-password-456'
+new_service.token = 'new-token-789'
+[new_service.api_key, new_service.password, new_service.token].all? { |f| f.is_a?(RedactedString) }
+#=> true
+
+## Transient field can be set to nil value
+new_service = SecretService.new
+new_service.api_key = nil
+new_service.api_key
+#=> nil
+
+## Persistent field definitions are correctly identified
+SecretService.field_types.values.select(&:persistent?).map(&:name).sort
+#=> [:endpoint_url, :name, :service_id]
+
+## Transient field definitions are correctly identified
+transient_fields = SecretService.field_types.values.reject(&:persistent?).map(&:name).sort
+transient_fields
+#=> [:api_key, :password, :secret_token]
+
+
+# TEARDOWN
+
+# Clean up Database
+@service.destroy! if @service.exists?
+
+# Clean up any test objects
+@service = nil
+
+# Force garbage collection to trigger any finalizers
+GC.start

data/try/helpers/test_helpers.rb

@@ -5,6 +5,7 @@
 # e.g. FAMILIA_TRACE=1 FAMILIA_DEBUG=1 bundle exec try
 
 require 'digest'
+
 require_relative '../../lib/familia'
 
 Familia.enable_database_logging = true
@@ -19,6 +20,8 @@ class Bone < Familia::Horreum
   zset      :metrics
   hashkey   :props
   string    :value, default: 'GREAT!'
+  counter   :counter, default: 0
+  lock      :lock
 end
 
 class Blone < Familia::Horreum
@@ -162,3 +165,67 @@ class Limiter < Familia::Horreum
     @name
   end
 end
+
+# # In test:
+# using RedactedStringTestHelper
+
+# secret = RedactedString.new("test-key")
+# expect(secret.raw).to eq("test-key")
+#
+# Or with rack
+#
+# post '/vault' do
+#   passphrase = RedactedString.new(request.params['passphrase'])
+#   passphrase.expose do |plain|
+#     vault.unlock(plain)
+#   end
+#   # passphrase wiped
+# end
+#
+# NOTE: This will do nothing unless RedactedString is already requried
+unless defined?(RedactedString)
+  require_relative '../../lib/familia/features/transient_fields/redacted_string'
+end
+module RedactedStringTestHelper
+  refine RedactedString do
+    def raw
+      # Only available when refinement is used
+      @value
+    end
+  end
+end
+
+unless defined?(SingleUseRedactedString)
+  require_relative '../../lib/familia/features/transient_fields/single_use_redacted_string'
+end
+module SingleUseRedactedStringTestHelper
+  refine SingleUseRedactedString do
+    def raw
+      # Only available when refinement is used
+      @value
+    end
+  end
+end
+
+# ConcealedString test helper for accessing encrypted values in tests
+unless defined?(ConcealedString)
+  require_relative '../../lib/familia/features/encrypted_fields/concealed_string'
+end
+module ConcealedStringTestHelper
+  refine ConcealedString do
+    # TEST-ONLY: Direct access to decrypted value
+    #
+    # This method bypasses the reveal block pattern and directly returns
+    # the decrypted plaintext. It should ONLY be used in test environments
+    # through refinements to keep this dangerous method out of production.
+    #
+    # @return [String] The decrypted plaintext value
+    #
+    def reveal_for_testing
+      raise SecurityError, 'Encrypted data already cleared' if cleared?
+      raise SecurityError, 'No encrypted data to reveal' if @encrypted_data.nil?
+
+      @field_type.decrypt_value(@record, @encrypted_data)
+    end
+  end
+end

data/try/horreum/base_try.rb

@@ -1,11 +1,10 @@
 # try/horreum/base_try.rb
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 Familia.debug = false
 
-@identifier = 'tryouts-27@onetimesecret.com'
+@identifier = 'tryouts-27@onetimesecret.dev'
 @customer = Customer.new @identifier
 @hashkey = Familia::HashKey.new 'tryouts-27'
 
@@ -55,7 +54,7 @@ Familia.debug = false
 ## Horreum object fields have a fast attribute method (1 of 2)
 Familia.trace :LOAD, @customer.dbclient, @customer.uri, caller if Familia.debug?
 @customer.name! 'Jane Doe'
-#=> 0
+#=> true
 
 ## Horreum object fields have a fast attribute method (2 of 2)
 @customer.refresh!
@@ -116,3 +115,158 @@ class ArrayIdentifierTest < Familia::Horreum
   field :name
 end
 #=!> Familia::Problem
+
+## Redefining a field method after it can give a warning
+class FieldRedefine < Familia::Horreum
+  identifier_field :email
+  field :name
+  field :uniquefieldname, on_conflict: :warn
+
+  def uniquefieldname
+    true
+  end
+end
+#=2> /WARNING/
+#=2> /uniquefieldname/
+
+## Defining a field with the same name as an existing method can give a warning
+class ::FieldRedefine2 < Familia::Horreum
+  identifier_field :email
+  field :name
+
+  def uniquefieldname
+    true
+  end
+
+  field :uniquefieldname, on_conflict: :warn
+end
+#=2> /WARNING/
+#=2> /uniquefieldname/
+
+## Redefining a field method after it can raise an error
+class FieldRedefine3 < Familia::Horreum
+  identifier_field :email
+  field :name
+  field :uniquefieldname, on_conflict: :raise
+
+  def uniquefieldname
+    true
+  end
+end
+#=!> ArgumentError
+
+## Defining a field with the same name as an existing method can raise an error
+class FieldRedefine4 < Familia::Horreum
+  identifier_field :email
+  field :name
+
+  def uniquefieldname
+    true
+  end
+
+  field :uniquefieldname, on_conflict: :raise
+end
+#=!> ArgumentError
+
+## Field aliasing works with 'as' parameter
+class AliasedFieldTest < Familia::Horreum
+  identifier_field :email
+  field :email
+  field :display_size, as: :width
+end
+@aliased = AliasedFieldTest.new email: 'test@example.com'
+@aliased.width = 42
+@aliased.width
+#=> 42
+
+## Aliased field getter method uses alias name
+@aliased.respond_to?(:width)
+#=> true
+
+## Aliased field setter method uses alias name
+@aliased.respond_to?(:width=)
+#=> true
+
+## Original field name is not accessible as method
+@aliased.respond_to?(:display_size)
+#=> false
+
+## Aliased field fast method works correctly
+@aliased.save
+@aliased.display_size! 100
+#=> true
+
+## Aliased field refresh works correctly
+@aliased.width = 50  # unsaved change
+@aliased.refresh!
+@aliased.width
+#=> "100"
+
+## Fast method with custom name
+class CustomFastMethodTest < Familia::Horreum
+  identifier_field :email
+  field :score, fast_method: :score_now!
+  field :email
+end
+@custom_fast = CustomFastMethodTest.new email: 'fast@example.com'
+@custom_fast.respond_to?(:score_now!)
+#=> true
+
+## Custom fast method works
+@custom_fast.save
+@custom_fast.score_now! 75
+#=> true
+
+## Field with :warn conflict handling allows redefinition with warning
+class WarnConflictTest < Familia::Horreum
+  identifier_field :email
+  field :email
+  field :test_method, on_conflict: :warn
+
+  def test_method
+    "original"
+  end
+
+end
+@warn_test = WarnConflictTest.new email: 'warn@example.com'
+@warn_test.test_method
+#=> "original"
+
+## Field with :skip conflict handling skips redefinition silently
+class SkipConflictTest < Familia::Horreum
+  identifier_field :email
+  field :email
+
+  def skip_method
+    "original"
+  end
+
+  field :skip_method, on_conflict: :skip
+end
+@skip_test = SkipConflictTest.new email: 'skip@example.com'
+@skip_test.skip_method
+#=> "original"
+
+## Combined aliasing and custom fast method
+class CombinedTest < Familia::Horreum
+  identifier_field :email
+  field :internal_count, as: :count, fast_method: :count_immediately!
+  field :email
+end
+@combined = CombinedTest.new email: 'combined1@example.com'
+@combined.count = 10
+@combined.count
+#=> 10
+
+## Combined test fast method works
+@combined.save
+@combined.count_immediately! 20
+@combined.count
+#=> 20
+
+## Combined test refresh works
+combined = CombinedTest.new email: 'combined2@example.com'
+combined.count = 5  # unsaved change
+combined.refresh!
+combined.count
+#=> 5

data/try/horreum/enhanced_conflict_handling_try.rb

@@ -0,0 +1,176 @@
+# try/horreum/enhanced_conflict_handling_try.rb
+
+require_relative '../helpers/test_helpers'
+
+Familia.debug = false
+
+## Valid strategies are defined correctly
+Familia::VALID_STRATEGIES.include?(:raise)
+#=> true
+
+## Valid strategies include all expected options
+Familia::VALID_STRATEGIES
+#=> [:raise, :skip, :ignore, :warn, :overwrite]
+
+## Overwrite strategy removes existing method and defines new one
+class OverwriteStrategyTest < Familia::Horreum
+  identifier_field :id
+  field :id
+
+  def conflicting_method
+    "original_method"
+  end
+
+  field :conflicting_method, on_conflict: :overwrite
+end
+@overwrite_test = OverwriteStrategyTest.new(id: 'overwrite1')
+@overwrite_test.conflicting_method = "new_value"
+@overwrite_test.conflicting_method
+#=> "new_value"
+
+## Overwrite strategy works with fast methods too
+@overwrite_test.save
+@overwrite_test.conflicting_method! "fast_value"
+#=> true
+
+## Invalid conflict strategy raises error during field definition
+class InvalidStrategyTest < Familia::Horreum
+  identifier_field :id
+  field :id
+  field :test_field, on_conflict: :invalid_strategy
+end
+#=!> ArgumentError
+
+## Method conflict detection works with instance methods
+class ConflictDetectionTest < Familia::Horreum
+  identifier_field :id
+  field :id
+
+  def existing_method
+    "exists"
+  end
+
+  field :existing_method, on_conflict: :raise
+end
+#=!> ArgumentError
+
+## Conflict detection provides helpful error message
+begin
+  class ConflictMessageTest < Familia::Horreum
+    identifier_field :id
+    field :id
+
+    def another_method
+      "exists"
+    end
+
+    field :another_method, on_conflict: :raise
+  end
+rescue ArgumentError => e
+  e.message.include?("another_method")
+end
+#=> true
+
+## Method location information in error message when possible
+
+class LocationInfoTest < Familia::Horreum
+  identifier_field :id
+  field :id
+
+  def location_test_method
+    "exists"
+  end
+
+  field :location_test_method, on_conflict: :raise
+end
+#=!> ArgumentError
+#==> error.message.include?("already defined")
+
+## Skip strategy silently ignores conflicts
+class SkipStrategyTest < Familia::Horreum
+  identifier_field :id
+  field :id
+
+  def skip_method
+    "original"
+  end
+
+  field :skip_method, on_conflict: :skip
+end
+@skip_test = SkipStrategyTest.new(id: 'skip1')
+@skip_test.skip_method
+#=> "original"
+
+## Skip strategy doesn't create accessor methods when method exists
+@skip_test.respond_to?(:skip_method=)
+#=> false
+
+## Warn strategy shows warning but continues with definition
+class WarnStrategyTest < Familia::Horreum
+  identifier_field :id
+  field :id
+
+  def warn_method
+    "original"
+  end
+
+  field :warn_method, on_conflict: :warn
+end
+#=2> /WARNING/
+@warn_test = WarnStrategyTest.new(id: 'warn1')
+@warn_test.warn_method = "new_value"
+@warn_test.warn_method
+#=> "new_value"
+
+## Fast method names must end with exclamation mark
+class InvalidFastMethodTest < Familia::Horreum
+  identifier_field :id
+  field :id
+  field :test_field, fast_method: :invalid_name
+end
+#=!> ArgumentError
+
+## Fast method validation works with custom names
+class ValidFastMethodTest < Familia::Horreum
+  identifier_field :id
+  field :id
+  field :score, fast_method: :update_score_now!
+end
+@valid_fast = ValidFastMethodTest.new(id: 'valid1')
+@valid_fast.respond_to?(:update_score_now!)
+#=> true
+
+## Method added hook detects conflicts after field definition
+class MethodAddedHookTest < Familia::Horreum
+  identifier_field :id
+  field :id
+  field :hook_test, on_conflict: :warn
+
+  def hook_test
+    "redefined_after"
+  end
+end
+#=2> /WARNING/
+#=2> /hook_test/
+#=2> /redefined after field definition/
+
+## Method added hook works with raise strategy too
+class MethodAddedRaiseTest < Familia::Horreum
+  identifier_field :id
+  field :id
+  field :raise_hook_test, on_conflict: :raise
+
+  def raise_hook_test
+    "redefined"
+  end
+end
+#=!> ArgumentError
+
+@overwrite_test.destroy! rescue nil
+@skip_test.destroy! rescue nil
+@warn_test.destroy! rescue nil
+@valid_fast.destroy! rescue nil
+@overwrite_test = nil
+@skip_test = nil
+@warn_test = nil
+@valid_fast = nil