familia 2.0.0.pre4 → 2.0.0.pre6

data/lib/familia/{datatype → data_type}/types/hashkey.rb

@@ -1,4 +1,4 @@
-# lib/familia/datatype/types/hashkey.rb
+# lib/familia/data_type/types/hashkey.rb
 
 module Familia
   class HashKey < DataType
@@ -55,12 +55,30 @@ module Familia
     end
 
     def hgetall
-      dbclient.hgetall(dbkey).each_with_object({}) do |(k,v), ret|
+      dbclient.hgetall(dbkey).each_with_object({}) do |(k, v), ret|
         ret[k] = deserialize_value v
       end
     end
     alias all hgetall
 
+    # Sets field in the hash stored at key to value, only if field does not yet exist.
+    # If field already exists, this operation has no effect.
+    # @param field [String] The field name
+    # @param val [Object] The value to set
+    # @return [Integer] 1 if field is a new field and value was set, 0 if field already exists
+    def hsetnx(field, val)
+      ret = dbclient.hsetnx dbkey, field.to_s, serialize_value(val)
+      update_expiration if ret == 1
+      ret
+    rescue TypeError => e
+      Familia.le "[hsetnx] #{e.message}"
+      Familia.ld "[hsetnx] #{dbkey} #{field}=#{val}" if Familia.debug
+      echo :hsetnx, caller(1..1).first if Familia.debug # logs via echo to the db and back
+      klass = val.class
+      msg = "Cannot store #{field} => #{val.inspect} (#{klass}) in #{dbkey}"
+      raise e.class, msg
+    end
+
     def key?(field)
       dbclient.hexists dbkey, field.to_s
     end

data/lib/familia/{datatype → data_type}/types/list.rb

@@ -1,8 +1,7 @@
-# lib/familia/datatype/types/list.rb
+# lib/familia/data_type/types/list.rb
 
 module Familia
   class List < DataType
-
     # Returns the number of elements in the list
     # @return [Integer] number of elements
     def element_count
@@ -91,36 +90,36 @@ module Familia
       rangeraw 0, count
     end
 
-    def each(&blk)
-      range.each(&blk)
+    def each(&)
+      range.each(&)
     end
 
-    def each_with_index(&blk)
-      range.each_with_index(&blk)
+    def each_with_index(&)
+      range.each_with_index(&)
     end
 
-    def eachraw(&blk)
-      rangeraw.each(&blk)
+    def eachraw(&)
+      rangeraw.each(&)
     end
 
-    def eachraw_with_index(&blk)
-      rangeraw.each_with_index(&blk)
+    def eachraw_with_index(&)
+      rangeraw.each_with_index(&)
     end
 
-    def collect(&blk)
-      range.collect(&blk)
+    def collect(&)
+      range.collect(&)
     end
 
-    def select(&blk)
-      range.select(&blk)
+    def select(&)
+      range.select(&)
     end
 
-    def collectraw(&blk)
-      rangeraw.collect(&blk)
+    def collectraw(&)
+      rangeraw.collect(&)
     end
 
-    def selectraw(&blk)
-      rangeraw.select(&blk)
+    def selectraw(&)
+      rangeraw.select(&)
     end
 
     def at(idx)

data/lib/familia/data_type/types/lock.rb

@@ -0,0 +1,43 @@
+# lib/familia/data_type/types/lock.rb
+
+module Familia
+  class Lock < String
+    def initialize(*args)
+      super
+      @opts[:default] = nil
+    end
+
+    # Acquire a lock with optional TTL
+    # @param token [String] Unique token to identify lock holder (auto-generated if nil)
+    # @param ttl [Integer, nil] Time-to-live in seconds. nil = no expiration, <=0 rejected
+    # @return [String, false] Returns token if acquired successfully, false otherwise
+    def acquire(token = SecureRandom.uuid, ttl: 10)
+      success = setnx(token)
+      # Handle both integer (1/0) and boolean (true/false) return values
+      return false unless success == 1 || success == true
+      return del && false if ttl&.<=(0)
+      return del && false if ttl&.positive? && !expire(ttl)
+      token
+    end
+
+    def release(token)
+      # Lua script to atomically check token and delete
+      script = "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end"
+      dbclient.eval(script, [dbkey], [token]) == 1
+    end
+
+    def locked?
+      !value.nil?
+    end
+
+    def held_by?(token)
+      value == token
+    end
+
+    def force_unlock!
+      del
+    end
+  end
+end
+
+Familia::DataType.register Familia::Lock, :lock

data/lib/familia/{datatype → data_type}/types/sorted_set.rb

@@ -1,4 +1,4 @@
-# lib/familia/datatype/types/sorted_set.rb
+# lib/familia/data_type/types/sorted_set.rb
 
 module Familia
   class SortedSet < DataType
@@ -99,36 +99,36 @@ module Familia
       revrangeraw 0, count, opts
     end
 
-    def each(&blk)
-      members.each(&blk)
+    def each(&)
+      members.each(&)
     end
 
-    def each_with_index(&blk)
-      members.each_with_index(&blk)
+    def each_with_index(&)
+      members.each_with_index(&)
     end
 
-    def collect(&blk)
-      members.collect(&blk)
+    def collect(&)
+      members.collect(&)
     end
 
-    def select(&blk)
-      members.select(&blk)
+    def select(&)
+      members.select(&)
     end
 
-    def eachraw(&blk)
-      membersraw.each(&blk)
+    def eachraw(&)
+      membersraw.each(&)
     end
 
-    def eachraw_with_index(&blk)
-      membersraw.each_with_index(&blk)
+    def eachraw_with_index(&)
+      membersraw.each_with_index(&)
     end
 
-    def collectraw(&blk)
-      membersraw.collect(&blk)
+    def collectraw(&)
+      membersraw.collect(&)
     end
 
-    def selectraw(&blk)
-      membersraw.select(&blk)
+    def selectraw(&)
+      membersraw.select(&)
     end
 
     def range(sidx, eidx, opts = {})

data/lib/familia/{datatype → data_type}/types/string.rb

@@ -1,4 +1,4 @@
-# lib/familia/datatype/types/string.rb
+# lib/familia/data_type/types/string.rb
 
 module Familia
   class String < DataType
@@ -25,6 +25,7 @@ module Familia
 
     def to_s
       return super if value.to_s.empty?
+
       value.to_s
     end
 
@@ -107,12 +108,19 @@ module Familia
       ret
     end
 
+    def del
+      ret = dbclient.del dbkey
+      ret.positive?
+    end
+
     def nil?
       value.nil?
     end
 
     Familia::DataType.register self, :string
-    Familia::DataType.register self, :counter
-    Familia::DataType.register self, :lock
   end
 end
+
+# Both subclass String
+require_relative 'lock'
+require_relative 'counter'

data/lib/familia/{datatype → data_type}/types/unsorted_set.rb

@@ -1,8 +1,7 @@
-# lib/familia/datatype/types/unsorted_set.rb
+# lib/familia/data_type/types/unsorted_set.rb
 
 module Familia
   class Set < DataType
-
     # Returns the number of elements in the unsorted set
     # @return [Integer] number of elements
     def element_count
@@ -36,36 +35,36 @@ module Familia
       dbclient.smembers(dbkey)
     end
 
-    def each(&blk)
-      members.each(&blk)
+    def each(&)
+      members.each(&)
     end
 
-    def each_with_index(&blk)
-      members.each_with_index(&blk)
+    def each_with_index(&)
+      members.each_with_index(&)
     end
 
-    def collect(&blk)
-      members.collect(&blk)
+    def collect(&)
+      members.collect(&)
     end
 
-    def select(&blk)
-      members.select(&blk)
+    def select(&)
+      members.select(&)
     end
 
-    def eachraw(&blk)
-      membersraw.each(&blk)
+    def eachraw(&)
+      membersraw.each(&)
     end
 
-    def eachraw_with_index(&blk)
-      membersraw.each_with_index(&blk)
+    def eachraw_with_index(&)
+      membersraw.each_with_index(&)
     end
 
-    def collectraw(&blk)
-      membersraw.collect(&blk)
+    def collectraw(&)
+      membersraw.collect(&)
     end
 
-    def selectraw(&blk)
-      membersraw.select(&blk)
+    def selectraw(&)
+      membersraw.select(&)
     end
 
     def member?(val)

data/lib/familia/{datatype.rb → data_type.rb}

@@ -1,10 +1,9 @@
-# lib/familia/datatype.rb
+# lib/familia/data_type.rb
 
-require_relative 'datatype/commands'
-require_relative 'datatype/serialization'
+require_relative 'data_type/commands'
+require_relative 'data_type/serialization'
 
 module Familia
-
   # DataType - Base class for Database data type wrappers
   #
   # This class provides common functionality for various Database data types
@@ -33,7 +32,7 @@ module Familia
       # +methname+ is the term used for the class and instance methods
       # that are created for the given +klass+ (e.g. set, list, etc)
       def register(klass, methname)
-        Familia.ld "[#{self}] Registering #{klass} as #{methname.inspect}"
+        Familia.trace :REGISTER, nil, "[#{self}] Registering #{klass} as #{methname.inspect}", caller(1..1) if Familia.debug?
 
         @registered_types[methname] = klass
       end
@@ -54,7 +53,7 @@ module Familia
         obj.default_expiration = default_expiration # method added via Features::Expiration
         obj.uri = uri
         obj.parent = self
-        super(obj)
+        super
       end
 
       def valid_keys_only(opts)
@@ -102,7 +101,6 @@ module Familia
     # Connection precendence: uses the database connection of the parent or the
     # value of opts[:dbclient] or Familia.dbclient (in that order).
     def initialize(keystring, opts = {})
-      #Familia.ld " [initializing] #{self.class} #{opts}"
       @keystring = keystring
       @keystring = @keystring.join(Familia.delim) if @keystring.is_a?(Array)
 
@@ -117,7 +115,7 @@ module Familia
         # this point. This would result in a Familia::Problem being raised. So
         # to be on the safe-side here until we have a better understanding of
         # the issue, we'll just log the class name for each key-value pair.
-        Familia.ld " [setting] #{k} #{v.class}"
+        Familia.trace :SETTING, nil, " [setting] #{k} #{v.class}", caller(1..1) if Familia.debug?
         send(:"#{k}=", v) if respond_to? :"#{k}="
       end
 
@@ -172,7 +170,7 @@ module Familia
         parent.dbkey(keystring)
       elsif parent_class?
         # This is a class-level datatype object so the parent class' dbkey
-        # method is defined in Familia::Horreum::ClassMethods.
+        # method is defined in Familia::Horreum::DefinitionMethods.
         parent.dbkey(keystring, nil)
       else
         # This is a standalone DataType object where it's keystring
@@ -235,9 +233,9 @@ module Familia
     include Serialization
   end
 
-  require_relative 'datatype/types/list'
-  require_relative 'datatype/types/unsorted_set'
-  require_relative 'datatype/types/sorted_set'
-  require_relative 'datatype/types/hashkey'
-  require_relative 'datatype/types/string'
+  require_relative 'data_type/types/list'
+  require_relative 'data_type/types/unsorted_set'
+  require_relative 'data_type/types/sorted_set'
+  require_relative 'data_type/types/hashkey'
+  require_relative 'data_type/types/string'
 end

data/lib/familia/encryption/encrypted_data.rb

@@ -0,0 +1,137 @@
+# lib/familia/encryption/encrypted_data.rb
+
+module Familia
+  module Encryption
+    EncryptedData = Data.define(:algorithm, :nonce, :ciphertext, :auth_tag, :key_version) do
+      # Class methods for parsing and validation
+      def self.valid?(json_string)
+        return true if json_string.nil?  # Allow nil values
+        return false unless json_string.kind_of?(::String)
+
+        begin
+          parsed = JSON.parse(json_string, symbolize_names: true)
+          return false unless parsed.is_a?(Hash)
+
+          # Check for required fields
+          required_fields = [:algorithm, :nonce, :ciphertext, :auth_tag, :key_version]
+          result = required_fields.all? { |field| parsed.key?(field) }
+          Familia.ld "[valid?] result: #{result}, parsed: #{parsed}, required: #{required_fields}"
+          result
+        rescue JSON::ParserError => e
+          Familia.ld "[valid?] JSON error: #{e.message}"
+          false
+        end
+      end
+
+      def self.validate!(json_string)
+        return nil if json_string.nil?
+
+        unless json_string.kind_of?(::String)
+          raise EncryptionError, "Expected JSON string, got #{json_string.class}"
+        end
+
+        begin
+          parsed = JSON.parse(json_string, symbolize_names: true)
+        rescue JSON::ParserError => e
+          raise EncryptionError, "Invalid JSON structure: #{e.message}"
+        end
+
+        unless parsed.is_a?(Hash)
+          raise EncryptionError, "Expected JSON object, got #{parsed.class}"
+        end
+
+        required_fields = [:algorithm, :nonce, :ciphertext, :auth_tag, :key_version]
+        missing_fields = required_fields.reject { |field| parsed.key?(field) }
+
+        unless missing_fields.empty?
+          raise EncryptionError, "Missing required fields: #{missing_fields.join(', ')}"
+        end
+
+        new(**parsed)
+      end
+
+      def self.from_json(json_string)
+        validate!(json_string)
+      end
+
+      # Instance methods for decryptability validation
+      def decryptable?
+        return false unless algorithm && nonce && ciphertext && auth_tag && key_version
+
+        # Ensure Registry is set up before checking algorithms
+        Registry.setup! if Registry.providers.empty?
+
+        # Check if algorithm is supported
+        return false unless Registry.providers.key?(algorithm)
+
+        # Validate Base64 encoding of binary fields
+        begin
+          Base64.strict_decode64(nonce)
+          Base64.strict_decode64(ciphertext)
+          Base64.strict_decode64(auth_tag)
+        rescue ArgumentError
+          return false
+        end
+
+        true
+      end
+
+      def validate_decryptable!
+        unless algorithm
+          raise EncryptionError, "Missing algorithm field"
+        end
+
+        # Ensure Registry is set up before checking algorithms
+        Registry.setup! if Registry.providers.empty?
+
+        unless Registry.providers.key?(algorithm)
+          raise EncryptionError, "Unsupported algorithm: #{algorithm}"
+        end
+
+        unless nonce && ciphertext && auth_tag && key_version
+          missing = []
+          missing << 'nonce' unless nonce
+          missing << 'ciphertext' unless ciphertext
+          missing << 'auth_tag' unless auth_tag
+          missing << 'key_version' unless key_version
+          raise EncryptionError, "Missing required fields: #{missing.join(', ')}"
+        end
+
+        # Get the provider for size validation
+        provider = Registry.providers[algorithm]
+
+        # Validate Base64 encoding and sizes
+        begin
+          decoded_nonce = Base64.strict_decode64(nonce)
+          if decoded_nonce.bytesize != provider.nonce_size
+            raise EncryptionError, "Invalid nonce size: expected #{provider.nonce_size}, got #{decoded_nonce.bytesize}"
+          end
+        rescue ArgumentError
+          raise EncryptionError, "Invalid Base64 encoding in nonce field"
+        end
+
+        begin
+          Base64.strict_decode64(ciphertext)  # ciphertext can be variable size
+        rescue ArgumentError
+          raise EncryptionError, "Invalid Base64 encoding in ciphertext field"
+        end
+
+        begin
+          decoded_auth_tag = Base64.strict_decode64(auth_tag)
+          if decoded_auth_tag.bytesize != provider.auth_tag_size
+            raise EncryptionError, "Invalid auth_tag size: expected #{provider.auth_tag_size}, got #{decoded_auth_tag.bytesize}"
+          end
+        rescue ArgumentError
+          raise EncryptionError, "Invalid Base64 encoding in auth_tag field"
+        end
+
+        # Validate that the key version exists
+        unless Familia.config.encryption_keys&.key?(key_version.to_sym)
+          raise EncryptionError, "No key for version: #{key_version}"
+        end
+
+        self
+      end
+    end
+  end
+end

data/lib/familia/encryption/manager.rb

@@ -0,0 +1,119 @@
+# lib/familia/encryption/manager.rb
+
+module Familia
+  module Encryption
+    # High-level encryption manager - replaces monolithic Encryption module
+    class Manager
+      attr_reader :provider
+
+      def initialize(algorithm: nil)
+        Registry.setup! if Registry.providers.empty?
+        @provider = algorithm ? Registry.get(algorithm) : Registry.default_provider
+        raise EncryptionError, 'No encryption provider available' unless @provider
+      end
+
+      def encrypt(plaintext, context:, additional_data: nil)
+        return nil if plaintext.to_s.empty?
+
+        key = derive_key(context)
+
+        result = @provider.encrypt(plaintext, key, additional_data)
+
+        Familia::Encryption::EncryptedData.new(
+          algorithm: @provider.algorithm,
+          nonce: Base64.strict_encode64(result[:nonce]),
+          ciphertext: Base64.strict_encode64(result[:ciphertext]),
+          auth_tag: Base64.strict_encode64(result[:auth_tag]),
+          key_version: current_key_version
+        ).to_h.to_json
+      ensure
+        Familia::Encryption.secure_wipe(key) if key
+      end
+
+      def decrypt(encrypted_json, context:, additional_data: nil)
+        return nil if encrypted_json.nil? || encrypted_json.empty?
+
+        # Increment counter immediately to track all decryption attempts, even failed ones
+        Familia::Encryption.derivation_count.increment
+
+        begin
+          data = Familia::Encryption::EncryptedData.new(**JSON.parse(encrypted_json, symbolize_names: true))
+
+          # Validate algorithm support
+          provider = Registry.get(data.algorithm)
+          key = derive_key_without_increment(context, version: data.key_version, provider: provider)
+
+          # Safely decode and validate sizes
+          nonce = decode_and_validate(data.nonce, provider.nonce_size, 'nonce')
+          ciphertext = decode_and_validate_ciphertext(data.ciphertext)
+          auth_tag = decode_and_validate(data.auth_tag, provider.auth_tag_size, 'auth_tag')
+
+          provider.decrypt(ciphertext, key, nonce, auth_tag, additional_data)
+        rescue EncryptionError
+          raise
+        rescue JSON::ParserError => e
+          raise EncryptionError, "Invalid JSON structure: #{e.message}"
+        rescue StandardError => e
+          raise EncryptionError, "Decryption failed: #{e.message}"
+        end
+      ensure
+        Familia::Encryption.secure_wipe(key) if key
+      end
+
+      private
+
+      def decode_and_validate(encoded, expected_size, component)
+        decoded = Base64.strict_decode64(encoded)
+        raise EncryptionError, 'Invalid encrypted data' unless decoded.bytesize == expected_size
+        decoded
+      rescue ArgumentError => e
+        raise EncryptionError, "Invalid Base64 encoding in #{component} field"
+      end
+
+      def decode_and_validate_ciphertext(encoded)
+        Base64.strict_decode64(encoded)
+      rescue ArgumentError => e
+        raise EncryptionError, "Invalid Base64 encoding in ciphertext field"
+      end
+
+      def derive_key(context, version: nil, provider: nil)
+        # Increment counter to prove no caching is happening
+        Familia::Encryption.derivation_count.increment
+
+        derive_key_without_increment(context, version: version, provider: provider)
+      end
+
+      def derive_key_without_increment(context, version: nil, provider: nil)
+        # Use provided provider or fall back to instance provider
+        provider ||= @provider
+
+        # Require explicit provider in decrypt context
+        raise EncryptionError, 'Provider required for key derivation' unless provider
+
+        version ||= current_key_version
+        master_key = get_master_key(version)
+
+        provider.derive_key(master_key, context)
+      ensure
+        Familia::Encryption.secure_wipe(master_key) if master_key
+      end
+
+      def get_master_key(version)
+        raise EncryptionError, 'Key version cannot be nil' if version.nil?
+
+        key = encryption_keys[version] || encryption_keys[version.to_sym] || encryption_keys[version.to_s]
+        raise EncryptionError, "No key for version: #{version}" unless key
+
+        Base64.strict_decode64(key)
+      end
+
+      def encryption_keys
+        Familia.config.encryption_keys || {}
+      end
+
+      def current_key_version
+        Familia.config.current_key_version
+      end
+    end
+  end
+end

data/lib/familia/encryption/provider.rb

@@ -0,0 +1,49 @@
+# lib/familia/encryption/provider.rb
+
+module Familia
+  module Encryption
+    # Base provider class - similar to FieldType pattern
+    class Provider
+      attr_reader :algorithm, :nonce_size, :auth_tag_size
+
+      def initialize
+        @algorithm = self.class::ALGORITHM
+        @nonce_size = self.class::NONCE_SIZE
+        @auth_tag_size = self.class::AUTH_TAG_SIZE
+      end
+
+      # Public interface methods that subclasses must implement
+      def encrypt(plaintext, key, additional_data = nil)
+        raise NotImplementedError
+      end
+
+      def decrypt(ciphertext, key, nonce, auth_tag, additional_data = nil)
+        raise NotImplementedError
+      end
+
+      def generate_nonce
+        raise NotImplementedError
+      end
+
+      def derive_key(master_key, context)
+        raise NotImplementedError
+      end
+
+      # Clear key from memory (best effort, no security guarantees)
+      # Ruby provides no reliable way to securely wipe memory
+      def secure_wipe(key)
+        key&.clear if key.respond_to?(:clear)
+      end
+
+      # Check if this provider is available
+      def self.available?
+        raise NotImplementedError
+      end
+
+      # Priority for automatic selection (higher = preferred)
+      def self.priority
+        0
+      end
+    end
+  end
+end