familia 2.0.0.pre26 → 2.1.0

data/lib/familia/schema_registry.rb

@@ -0,0 +1,173 @@
+# lib/familia/schema_registry.rb
+#
+# frozen_string_literal: true
+
+require 'json'
+
+module Familia
+  # Registry for loading and caching external JSON schema files.
+  # Schemas are loaded at boot time based on configuration.
+  #
+  # @example Convention-based loading
+  #   Familia.schema_path = 'schemas/models'
+  #   SchemaRegistry.load!
+  #   SchemaRegistry.schema_for('Customer')  # loads schemas/models/customer.json
+  #
+  # @example Explicit mapping
+  #   Familia.schemas = { 'Customer' => 'schemas/customer.json' }
+  #   SchemaRegistry.load!
+  #
+  class SchemaRegistry
+    class << self
+      # Load schemas based on current configuration.
+      # Safe to call multiple times - only loads once.
+      def load!
+        return if @loaded
+
+        @schemas ||= {}
+        load_from_path if Familia.schema_path
+        load_from_hash if Familia.schemas&.any?
+        @loaded = true
+      end
+
+      # Check if schemas have been loaded
+      def loaded?
+        @loaded == true
+      end
+
+      # Get schema for a class by name or class reference
+      # @param klass_or_name [Class, String] the class or class name
+      # @return [Hash, nil] the parsed JSON schema or nil
+      def schema_for(klass_or_name)
+        load! unless loaded?
+        name = klass_or_name.is_a?(Class) ? klass_or_name.name : klass_or_name.to_s
+        @schemas[name]
+      end
+
+      # Check if a schema is defined for the given class
+      def schema_defined?(klass_or_name)
+        !schema_for(klass_or_name).nil?
+      end
+
+      # All registered schemas
+      def schemas
+        load! unless loaded?
+        @schemas.dup
+      end
+
+      # Validate data against a schema
+      # @param klass_or_name [Class, String] the class whose schema to use
+      # @param data [Hash] the data to validate
+      # @return [Hash] { valid: Boolean, errors: Array }
+      def validate(klass_or_name, data)
+        schema = schema_for(klass_or_name)
+        return { valid: true, errors: [] } unless schema
+
+        errors = validator.validate(schema, data).to_a
+        { valid: errors.empty?, errors: errors }
+      end
+
+      # Validate data or raise SchemaValidationError
+      # @raise [SchemaValidationError] if validation fails
+      def validate!(klass_or_name, data)
+        result = validate(klass_or_name, data)
+        raise SchemaValidationError.new(result[:errors]) unless result[:valid]
+
+        true
+      end
+
+      # Reset registry (primarily for testing)
+      def reset!
+        @schemas = {}
+        @loaded = false
+        @validator = nil
+      end
+
+      private
+
+      def load_from_path
+        path = Familia.schema_path
+        return unless path && File.directory?(path)
+
+        Dir.glob(File.join(path, '*.json')).each do |file|
+          # Convert filename to class name: customer.json -> Customer
+          # user_session.json -> UserSession
+          basename = File.basename(file, '.json')
+          class_name = basename.split('_').map(&:capitalize).join
+          @schemas[class_name] = load_schema_file(file)
+        end
+      end
+
+      def load_from_hash
+        Familia.schemas.each do |class_name, file_path|
+          @schemas[class_name.to_s] = load_schema_file(file_path)
+        end
+      end
+
+      def load_schema_file(path)
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        raise ArgumentError, "Failed to parse schema file #{path}: #{e.message}"
+      rescue Errno::ENOENT
+        raise ArgumentError, "Schema file not found: #{path}"
+      end
+
+      def validator
+        @validator ||= build_validator
+      end
+
+      def build_validator
+        case Familia.schema_validator
+        when :json_schemer
+          begin
+            require 'json_schemer'
+            JsonSchemerValidator.new
+          rescue LoadError
+            warn '[Familia] json_schemer gem not installed. Schema validation disabled.'
+            warn "[Familia] Add `gem 'json_schemer'` to your Gemfile to enable."
+            NullValidator.new
+          end
+        when :none, nil
+          NullValidator.new
+        else
+          # Custom validator instance provided
+          Familia.schema_validator
+        end
+      end
+    end
+  end
+
+  # Validator adapter for json_schemer gem
+  class JsonSchemerValidator
+    def validate(schema, data)
+      schemer = JSONSchemer.schema(schema)
+      schemer.validate(data)
+    end
+  end
+
+  # Null validator that always passes (for when validation is disabled)
+  class NullValidator
+    def validate(_schema, _data)
+      []
+    end
+  end
+
+  # Error raised when schema validation fails
+  class SchemaValidationError < HorreumError
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors
+      messages = errors.map { |e| format_error(e) }.first(3)
+      super("Schema validation failed: #{messages.join('; ')}")
+    end
+
+    private
+
+    def format_error(error)
+      path = error['data_pointer'] || error['schema_pointer'] || '/'
+      type = error['type'] || 'validation'
+      "#{type} at #{path}"
+    end
+  end
+end

data/lib/familia/settings.rb

@@ -15,11 +15,17 @@ module Familia
   @encryption_personalization = 'FamilialMatters'.freeze
   @pipelined_mode = :warn
 
+  # Schema validation configuration
+  @schema_path = nil      # Directory containing schema files (String or Pathname)
+  @schemas = {}           # Hash mapping class names to schema file paths
+  @schema_validator = :json_schemer # Validator type (:json_schemer, :none, or custom)
+
   # Familia::Settings
   #
   module Settings
     attr_writer :delim, :suffix, :default_expiration, :logical_database, :prefix, :encryption_keys,
-                :current_key_version, :encryption_personalization, :transaction_mode
+                :current_key_version, :encryption_personalization, :transaction_mode,
+                :schema_path, :schemas, :schema_validator
 
     def delim(val = nil)
       @delim = val if val
@@ -140,6 +146,62 @@ module Familia
       @pipelined_mode = val
     end
 
+    # Directory containing schema files for JSON Schema validation.
+    # When set, schema files are discovered by convention using the
+    # underscored class name (e.g., Customer -> customer.json).
+    #
+    # @param val [String, Pathname, nil] The schema directory path, or nil to get current value
+    # @return [String, Pathname, nil] Current schema path
+    #
+    # @example Convention-based schema discovery
+    #   Familia.configure do |config|
+    #     config.schema_path = 'schemas/models'
+    #   end
+    #
+    def schema_path(val = nil)
+      @schema_path = val if val
+      @schema_path
+    end
+
+    # Hash mapping class names to their schema file paths.
+    # Takes precedence over convention-based discovery via schema_path.
+    #
+    # @param val [Hash, nil] A hash of class name => schema path mappings, or nil to get current
+    # @return [Hash] Current schema mappings
+    #
+    # @example Explicit schema mapping
+    #   Familia.configure do |config|
+    #     config.schemas = {
+    #       'Customer' => 'schemas/customer.json',
+    #       'Session'  => 'schemas/session.json'
+    #     }
+    #   end
+    #
+    def schemas(val = nil)
+      @schemas = val if val
+      @schemas || {}
+    end
+
+    # Validator type for JSON Schema validation.
+    #
+    # @param val [Symbol, Object, nil] The validator type or instance, or nil to get current
+    # @return [Symbol, Object] Current validator setting
+    #
+    # Available options:
+    # - :json_schemer (default): Use the json_schemer gem for validation
+    # - :none: Disable schema validation entirely
+    # - Custom instance: Any object responding to #validate
+    #
+    # @example Disable validation
+    #   Familia.configure do |config|
+    #     config.schema_validator = :none
+    #   end
+    #
+    def schema_validator(val = nil)
+      @schema_validator = val if val
+      @schema_validator || :json_schemer
+    end
+
     # Configure Familia settings
     #
     # @yield [Settings] self for block-based configuration

data/lib/familia/version.rb

@@ -4,5 +4,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.0.0.pre26' unless defined?(Familia::VERSION)
+  VERSION = '2.1.0' unless defined?(Familia::VERSION)
 end

data/lib/familia.rb

@@ -181,3 +181,4 @@ require_relative 'familia/features'
 require_relative 'familia/data_type'
 require_relative 'familia/horreum'
 require_relative 'familia/encryption'
+require_relative 'familia/schema_registry'

data/try/features/schema_registry_try.rb

@@ -0,0 +1,193 @@
+# try/features/schema_registry_try.rb
+#
+# frozen_string_literal: true
+
+require_relative '../support/helpers/test_helpers'
+require 'json'
+require 'tmpdir'
+require 'fileutils'
+
+Familia.debug = false
+
+# Setup - create temp schema directory
+@schema_dir = Dir.mktmpdir('familia_schemas')
+
+# Create test schema files
+File.write(File.join(@schema_dir, 'customer.json'), JSON.generate({
+  type: 'object',
+  properties: {
+    email: { type: 'string', format: 'email' },
+    age: { type: 'integer', minimum: 0 }
+  },
+  required: ['email']
+}))
+
+File.write(File.join(@schema_dir, 'user_session.json'), JSON.generate({
+  type: 'object',
+  properties: {
+    token: { type: 'string', minLength: 32 }
+  }
+}))
+
+# Store original settings
+@original_schema_path = Familia.schema_path
+@original_schemas = Familia.schemas
+@original_validator = Familia.schema_validator
+
+# Ensure json_schemer is used for validation
+Familia.schema_validator = :json_schemer
+
+## SchemaRegistry class exists
+Familia::SchemaRegistry.is_a?(Class)
+#=> true
+
+## SchemaRegistry starts unloaded after reset
+Familia::SchemaRegistry.reset!
+Familia::SchemaRegistry.loaded?
+#=> false
+
+## schema_for returns nil before loading when no config
+Familia::SchemaRegistry.reset!
+Familia.schema_path = nil
+Familia.schemas = {}
+result = Familia::SchemaRegistry.schema_for('Customer')
+result.nil?
+#=> true
+
+## load! loads schemas from schema_path
+Familia.schema_path = @schema_dir
+Familia::SchemaRegistry.reset!
+Familia::SchemaRegistry.load!
+Familia::SchemaRegistry.loaded?
+#=> true
+
+## schema_for returns parsed schema after loading
+Familia.schema_path = @schema_dir
+Familia::SchemaRegistry.reset!
+Familia::SchemaRegistry.load!
+schema = Familia::SchemaRegistry.schema_for('Customer')
+schema['type']
+#=> 'object'
+
+## schema_defined? returns true for loaded schemas
+Familia.schema_path = @schema_dir
+Familia::SchemaRegistry.reset!
+Familia::SchemaRegistry.load!
+Familia::SchemaRegistry.schema_defined?('Customer')
+#=> true
+
+## schema_defined? returns false for unknown schemas
+Familia::SchemaRegistry.schema_defined?('NonExistent')
+#=> false
+
+## Underscore filenames convert to CamelCase class names
+Familia.schema_path = @schema_dir
+Familia::SchemaRegistry.reset!
+Familia::SchemaRegistry.load!
+Familia::SchemaRegistry.schema_defined?('UserSession')
+#=> true
+
+## validate returns valid for conforming data
+Familia.schema_path = @schema_dir
+Familia::SchemaRegistry.reset!
+Familia::SchemaRegistry.load!
+result = Familia::SchemaRegistry.validate('Customer', { 'email' => 'test@example.com', 'age' => 25 })
+result[:valid]
+#=> true
+
+## validate returns errors for missing required field
+result = Familia::SchemaRegistry.validate('Customer', { 'age' => 25 })
+result[:valid]
+#=> false
+
+## validate errors array is non-empty for invalid data
+result = Familia::SchemaRegistry.validate('Customer', { 'age' => 25 })
+result[:errors].size > 0
+#=> true
+
+## validate returns valid for undefined schemas (no-op)
+result = Familia::SchemaRegistry.validate('NonExistent', { 'anything' => 'goes' })
+result[:valid]
+#=> true
+
+## validate! raises SchemaValidationError for invalid data
+begin
+  Familia::SchemaRegistry.validate!('Customer', { 'age' => 'not a number' })
+  false
+rescue Familia::SchemaValidationError => e
+  e.errors.size > 0
+end
+#=> true
+
+## validate! returns true for valid data
+result = Familia::SchemaRegistry.validate!('Customer', { 'email' => 'valid@example.com' })
+result
+#=> true
+
+## Explicit schemas hash loads correctly
+Familia.schema_path = nil
+Familia.schemas = { 'ExplicitModel' => File.join(@schema_dir, 'customer.json') }
+Familia::SchemaRegistry.reset!
+Familia::SchemaRegistry.load!
+Familia::SchemaRegistry.schema_defined?('ExplicitModel')
+#=> true
+
+## schemas returns copy of all loaded schemas
+Familia.schema_path = @schema_dir
+Familia.schemas = {}
+Familia::SchemaRegistry.reset!
+Familia::SchemaRegistry.load!
+schemas = Familia::SchemaRegistry.schemas
+schemas.keys.sort
+#=> ['Customer', 'UserSession']
+
+## reset! clears loaded state
+Familia::SchemaRegistry.reset!
+Familia::SchemaRegistry.loaded?
+#=> false
+
+## SchemaValidationError has errors accessor
+begin
+  Familia.schema_path = @schema_dir
+  Familia::SchemaRegistry.reset!
+  Familia::SchemaRegistry.load!
+  Familia::SchemaRegistry.validate!('Customer', {})
+rescue Familia::SchemaValidationError => e
+  e.respond_to?(:errors) && e.errors.is_a?(Array)
+end
+#=> true
+
+## load! is idempotent - calling multiple times does not reload
+Familia.schema_path = @schema_dir
+Familia::SchemaRegistry.reset!
+Familia::SchemaRegistry.load!
+first_schema = Familia::SchemaRegistry.schema_for('Customer')
+Familia::SchemaRegistry.load!
+second_schema = Familia::SchemaRegistry.schema_for('Customer')
+first_schema.equal?(second_schema)
+#=> true
+
+## schema_for auto-loads when not yet loaded
+Familia.schema_path = @schema_dir
+Familia.schemas = {}
+Familia::SchemaRegistry.reset!
+schema = Familia::SchemaRegistry.schema_for('Customer')
+schema['type']
+#=> 'object'
+
+## NullValidator always returns valid when validation disabled
+Familia.schema_path = @schema_dir
+Familia.schema_validator = :none
+Familia::SchemaRegistry.reset!
+Familia::SchemaRegistry.load!
+result = Familia::SchemaRegistry.validate('Customer', {})
+Familia.schema_validator = :json_schemer
+result[:valid]
+#=> true
+
+# Teardown
+FileUtils.rm_rf(@schema_dir)
+Familia.schema_path = @original_schema_path
+Familia.schemas = @original_schemas || {}
+Familia.schema_validator = @original_validator || :json_schemer
+Familia::SchemaRegistry.reset!

data/try/features/schema_validation_feature_try.rb

@@ -0,0 +1,218 @@
+# try/features/schema_validation_feature_try.rb
+#
+# frozen_string_literal: true
+
+require_relative '../support/helpers/test_helpers'
+require 'json'
+require 'tmpdir'
+require 'fileutils'
+
+Familia.debug = false
+
+# Store original config for teardown
+@original_schema_path = Familia.schema_path
+@original_schemas = Familia.schemas
+@original_validator = Familia.schema_validator
+
+# Setup - create temp schema directory and configure before defining classes
+@schema_dir = Dir.mktmpdir('familia_schema_feature')
+@prefix = "familia:test:schemafeature:#{Process.pid}"
+
+# Create test schema for SchemaValidatedModel class
+# Note: snake_case filename converts to CamelCase class name
+# Using type arrays to allow null for optional fields (age is not required)
+File.write(File.join(@schema_dir, 'schema_validated_model.json'), JSON.generate({
+  'type' => 'object',
+  'properties' => {
+    'email' => { 'type' => 'string', 'format' => 'email' },
+    'name' => { 'type' => 'string', 'minLength' => 1 },
+    'age' => { 'type' => ['integer', 'null'], 'minimum' => 0, 'maximum' => 150 }
+  },
+  'required' => ['email', 'name']
+}))
+
+Familia.schema_path = @schema_dir
+Familia.schema_validator = :json_schemer
+Familia::SchemaRegistry.reset!
+Familia::SchemaRegistry.load!
+
+# Define test model with schema validation feature dynamically
+# Uses Object.const_set to define at runtime after schema is loaded
+Object.const_set(:SchemaValidatedModel, Class.new(Familia::Horreum) do
+  feature :schema_validation
+
+  identifier_field :modelid
+  field :modelid
+  field :email
+  field :name
+  field :age
+end)
+
+# Define model without schema validation feature for comparison
+Object.const_set(:NoSchemaFeatureModel, Class.new(Familia::Horreum) do
+  identifier_field :id
+  field :id
+  field :data
+end) unless defined?(NoSchemaFeatureModel)
+
+# Define model with feature but no schema file
+Object.const_set(:UnschemaedFeatureModel, Class.new(Familia::Horreum) do
+  feature :schema_validation
+
+  identifier_field :uid
+  field :uid
+  field :stuff
+end)
+
+## Model class has schema class method
+SchemaValidatedModel.respond_to?(:schema)
+#=> true
+
+## Model class schema returns Hash
+SchemaValidatedModel.schema.is_a?(Hash)
+#=> true
+
+## Model class has schema_defined? method
+SchemaValidatedModel.respond_to?(:schema_defined?)
+#=> true
+
+## Model class schema_defined? returns true when schema exists
+SchemaValidatedModel.schema_defined?
+#=> true
+
+## Instance can access schema via instance method
+instance = SchemaValidatedModel.new(modelid: 't1', email: 'test@example.com', name: 'Test')
+instance.respond_to?(:schema)
+#=> true
+
+## Instance schema returns same Hash as class schema
+instance = SchemaValidatedModel.new(modelid: 't1', email: 'test@example.com', name: 'Test')
+instance.schema == SchemaValidatedModel.schema
+#=> true
+
+## valid_against_schema? returns true for valid data
+instance = SchemaValidatedModel.new(modelid: 't2', email: 'test@example.com', name: 'Test', age: 25)
+instance.valid_against_schema?
+#=> true
+
+## valid_against_schema? returns false for invalid email format
+instance = SchemaValidatedModel.new(modelid: 't3', email: 'not-an-email', name: 'Test')
+instance.valid_against_schema?
+#=> false
+
+## valid_against_schema? returns false for missing required name field
+instance = SchemaValidatedModel.new(modelid: 't4', email: 'test@example.com')
+instance.valid_against_schema?
+#=> false
+
+## valid_against_schema? returns false for age out of range
+instance = SchemaValidatedModel.new(modelid: 't5', email: 'test@example.com', name: 'Test', age: 200)
+instance.valid_against_schema?
+#=> false
+
+## schema_validation_errors returns empty array for valid data
+instance = SchemaValidatedModel.new(modelid: 't6', email: 'test@example.com', name: 'Valid')
+instance.schema_validation_errors.empty?
+#=> true
+
+## schema_validation_errors returns non-empty array for invalid data
+instance = SchemaValidatedModel.new(modelid: 't7', email: 'not-valid', name: 'Test')
+instance.schema_validation_errors.size > 0
+#=> true
+
+## schema_validation_errors returns array type
+instance = SchemaValidatedModel.new(modelid: 't8', email: 'test@example.com', name: '')
+errors = instance.schema_validation_errors
+errors.is_a?(Array)
+#=> true
+
+## validate_against_schema! returns true for valid data
+instance = SchemaValidatedModel.new(modelid: 't9', email: 'valid@example.com', name: 'Valid')
+instance.validate_against_schema!
+#=> true
+
+## validate_against_schema! raises SchemaValidationError for invalid email
+instance = SchemaValidatedModel.new(modelid: 't10', email: 'bad-email', name: 'Test')
+begin
+  instance.validate_against_schema!
+  false
+rescue Familia::SchemaValidationError
+  true
+end
+#=> true
+
+## validate_against_schema! raises SchemaValidationError for missing required field
+instance = SchemaValidatedModel.new(modelid: 't11', email: 'test@example.com')
+begin
+  instance.validate_against_schema!
+  false
+rescue Familia::SchemaValidationError
+  true
+end
+#=> true
+
+## SchemaValidationError includes errors accessor
+instance = SchemaValidatedModel.new(modelid: 't12', email: 'bad')
+begin
+  instance.validate_against_schema!
+  nil
+rescue Familia::SchemaValidationError => e
+  e.respond_to?(:errors) && e.errors.is_a?(Array) && e.errors.size > 0
+end
+#=> true
+
+## Model without feature does not have valid_against_schema? method
+instance = NoSchemaFeatureModel.new(id: 'x', data: 'anything')
+instance.respond_to?(:valid_against_schema?)
+#=> false
+
+## Model without feature does not have validate_against_schema! method
+instance = NoSchemaFeatureModel.new(id: 'x', data: 'anything')
+instance.respond_to?(:validate_against_schema!)
+#=> false
+
+## Model without feature does not have schema_validation_errors method
+instance = NoSchemaFeatureModel.new(id: 'x', data: 'anything')
+instance.respond_to?(:schema_validation_errors)
+#=> false
+
+## Model with feature but no schema file still works - valid_against_schema returns true
+instance = UnschemaedFeatureModel.new(uid: 'u1', stuff: 'whatever')
+instance.valid_against_schema?
+#=> true
+
+## Model with feature but no schema file - schema_validation_errors returns empty array
+instance = UnschemaedFeatureModel.new(uid: 'u2', stuff: 123)
+instance.schema_validation_errors
+#=> []
+
+## Model with feature but no schema file - validate_against_schema! returns true
+instance = UnschemaedFeatureModel.new(uid: 'u3', stuff: nil)
+instance.validate_against_schema!
+#=> true
+
+## Model with feature but no schema - schema_defined? returns false
+UnschemaedFeatureModel.schema_defined?
+#=> false
+
+## Model with feature but no schema - schema returns nil
+UnschemaedFeatureModel.schema.nil?
+#=> true
+
+## Feature is properly registered in enabled features
+SchemaValidatedModel.features_enabled.include?(:schema_validation)
+#=> true
+
+## schema_validation feature is available in Familia
+Familia::Base.features_available.key?(:schema_validation)
+#=> true
+
+# Teardown
+FileUtils.rm_rf(@schema_dir)
+Familia.schema_path = @original_schema_path
+Familia.schemas = @original_schemas || {}
+Familia.schema_validator = @original_validator || :json_schemer
+Familia::SchemaRegistry.reset!
+Object.send(:remove_const, :SchemaValidatedModel) if defined?(SchemaValidatedModel)
+Object.send(:remove_const, :NoSchemaFeatureModel) if defined?(NoSchemaFeatureModel)
+Object.send(:remove_const, :UnschemaedFeatureModel) if defined?(UnschemaedFeatureModel)