rhales 0.4.0 → 0.5.3

data/lib/rhales/middleware/schema_validator.rb

@@ -0,0 +1,300 @@
+# lib/rhales/middleware/schema_validator.rb
+#
+# frozen_string_literal: true
+
+require 'json_schemer'
+require_relative '../utils/json_serializer'
+
+module Rhales
+  module Middleware
+    # Rack middleware that validates hydration data against JSON Schemas
+    #
+    # This middleware extracts hydration JSON from HTML responses and validates
+    # it against the JSON Schema for the template. In development, it fails
+    # loudly on mismatches. In production, it logs warnings but continues serving.
+    #
+    # @example Basic usage with Rack
+    #   use Rhales::Middleware::SchemaValidator,
+    #     schemas_dir: './public/schemas',
+    #     fail_on_error: ENV['RACK_ENV'] == 'development'
+    #
+    # @example With Roda
+    #   use Rhales::Middleware::SchemaValidator,
+    #     schemas_dir: File.expand_path('../public/schemas', __dir__),
+    #     fail_on_error: ENV['RACK_ENV'] == 'development',
+    #     enabled: true
+    #
+    # @example Accessing statistics
+    #   validator = app.middleware.find { |m| m.is_a?(Rhales::Middleware::SchemaValidator) }
+    #   puts validator.stats
+    class SchemaValidator
+      # Raised when schema validation fails in development mode
+      class ValidationError < StandardError; end
+
+      # Initialize the middleware
+      #
+      # @param app [#call] The Rack application
+      # @param options [Hash] Configuration options
+      # @option options [String] :schemas_dir Path to JSON schemas directory
+      # @option options [Boolean] :fail_on_error Whether to raise on validation errors
+      # @option options [Boolean] :enabled Whether validation is enabled
+      # @option options [Array<String>] :skip_paths Additional paths to skip validation
+      def initialize(app, options = {})
+        @app = app
+        # Default to public/schemas in implementing project's directory
+        @schemas_dir = options.fetch(:schemas_dir, './public/schemas')
+        @fail_on_error = options.fetch(:fail_on_error, false)
+        @enabled = options.fetch(:enabled, true)
+        @skip_paths = options.fetch(:skip_paths, [])
+        @schema_cache = {}
+        @stats = {
+          total_validations: 0,
+          total_time_ms: 0,
+          failures: 0
+        }
+      end
+
+      # Process the Rack request
+      #
+      # @param env [Hash] The Rack environment
+      # @return [Array] Rack response tuple [status, headers, body]
+      def call(env)
+        return @app.call(env) unless @enabled
+        return @app.call(env) if skip_validation?(env)
+
+        status, headers, body = @app.call(env)
+
+        # Only validate HTML responses
+        content_type = headers['Content-Type']
+        return [status, headers, body] unless content_type&.include?('text/html')
+
+        # Get template name from env (set by View)
+        template_name = env['rhales.template_name']
+        return [status, headers, body] unless template_name
+
+        # Get template path if available (for better error messages)
+        template_path = env['rhales.template_path']
+
+        # Load schema for template
+        schema = load_schema_cached(template_name)
+        return [status, headers, body] unless schema
+
+        # Extract hydration data from response
+        html_body = extract_body(body)
+        hydration_data = extract_hydration_data(html_body)
+        return [status, headers, body] if hydration_data.empty?
+
+        # Validate each hydration block
+        start_time = Time.now
+        errors = validate_hydration_data(hydration_data, schema, template_name)
+        elapsed_ms = ((Time.now - start_time) * 1000).round(2)
+
+        # Update stats
+        @stats[:total_validations] += 1
+        @stats[:total_time_ms] += elapsed_ms
+        @stats[:failures] += 1 if errors.any?
+
+        # Handle errors
+        handle_errors(errors, template_name, template_path, elapsed_ms) if errors.any?
+
+        [status, headers, body]
+      end
+
+      # Get validation statistics
+      #
+      # @return [Hash] Statistics including avg_time_ms and success_rate
+      def stats
+        avg_time = @stats[:total_validations] > 0 ?
+          (@stats[:total_time_ms] / @stats[:total_validations]).round(2) : 0
+
+        @stats.merge(
+          avg_time_ms: avg_time,
+          success_rate: @stats[:total_validations] > 0 ?
+            ((@stats[:total_validations] - @stats[:failures]).to_f / @stats[:total_validations] * 100).round(2) : 0
+        )
+      end
+
+      private
+
+      # Check if validation should be skipped for this request
+      def skip_validation?(env)
+        path = env['PATH_INFO']
+
+        # Skip static assets, APIs, public files
+        return true if path.start_with?('/assets', '/api', '/public')
+
+        # Skip configured custom paths
+        return true if @skip_paths.any? { |skip_path| path.start_with?(skip_path) }
+
+        # Skip files with extensions typically not rendered by templates
+        return true if path.match?(/\.(css|js|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)\z/i)
+
+        false
+      end
+
+      # Load and cache JSON schema for template
+      def load_schema_cached(template_name)
+        @schema_cache[template_name] ||= begin
+          schema_path = File.join(@schemas_dir, "#{template_name}.json")
+
+          return nil unless File.exist?(schema_path)
+
+          schema_json = File.read(schema_path)
+          schema_hash = JSONSerializer.parse(schema_json)
+
+          # Create JSONSchemer validator
+          # Note: json_schemer handles $schema and $id properly
+          JSONSchemer.schema(schema_hash)
+        rescue JSON::ParserError => e
+          warn "Rhales::SchemaValidator: Failed to parse schema for #{template_name}: #{e.message}"
+          nil
+        rescue StandardError => e
+          warn "Rhales::SchemaValidator: Failed to load schema for #{template_name}: #{e.message}"
+          nil
+        end
+      end
+
+      # Extract response body as string
+      def extract_body(body)
+        if body.respond_to?(:each)
+          body.each.to_a.join
+        elsif body.respond_to?(:read)
+          body.read
+        else
+          body.to_s
+        end
+      end
+
+      # Extract hydration JSON blocks from HTML
+      #
+      # Looks for <script type="application/json" data-window="varName"> tags
+      def extract_hydration_data(html)
+        hydration_blocks = {}
+
+        # Match script tags with data-window attribute
+        html.scan(/<script[^>]*type=["']application\/json["'][^>]*data-window=["']([^"']+)["'][^>]*>(.*?)<\/script>/m) do |window_var, json_content|
+          begin
+            hydration_blocks[window_var] = JSONSerializer.parse(json_content.strip)
+          rescue JSON::ParserError => e
+            warn "Rhales::SchemaValidator: Failed to parse hydration JSON for window.#{window_var}: #{e.message}"
+          end
+        end
+
+        hydration_blocks
+      end
+
+      # Validate hydration data against schema
+      def validate_hydration_data(hydration_data, schema, template_name)
+        errors = []
+
+        hydration_data.each do |window_var, data|
+          # Validate data against schema using json_schemer
+          begin
+            validation_errors = schema.validate(data).to_a
+
+            if validation_errors.any?
+              errors << {
+                window: window_var,
+                template: template_name,
+                errors: format_errors(validation_errors)
+              }
+            end
+          rescue StandardError => e
+            warn "Rhales::SchemaValidator: Schema validation error for #{template_name}: #{e.message}"
+            # Don't add to errors array - this is a schema definition problem, not data problem
+          end
+        end
+
+        errors
+      end
+
+      # Format json_schemer errors for display
+      def format_errors(validation_errors)
+        validation_errors.map do |error|
+          # json_schemer provides detailed error hash
+          # Example: { "data" => value, "data_pointer" => "/user/id", "schema" => {...}, "type" => "required", "error" => "..." }
+
+          path = error['data_pointer'] || '/'
+          type = error['type']
+          schema = error['schema'] || {}
+          data = error['data']
+
+          # For type validation errors, format like json-schema did
+          # "The property '#/count' of type string did not match the following type: number"
+          if schema['type'] && data
+            expected = schema['type']
+            actual = case data
+                     when String then 'string'
+                     when Integer, Float then 'number'
+                     when TrueClass, FalseClass then 'boolean'
+                     when Array then 'array'
+                     when Hash then 'object'
+                     when NilClass then 'null'
+                     else data.class.name.downcase
+                     end
+
+            "The property '#{path}' of type #{actual} did not match the following type: #{expected}"
+          elsif type == 'required'
+            details = error['details'] || {}
+            missing = details['missing_keys']&.join(', ') || 'unknown'
+            "The property '#{path}' is missing required field(s): #{missing}"
+          elsif schema['enum']
+            expected = schema['enum'].join(', ')
+            "The property '#{path}' must be one of: #{expected}"
+          elsif schema['minimum']
+            min = schema['minimum']
+            "The property '#{path}' must be >= #{min}"
+          elsif schema['maximum']
+            max = schema['maximum']
+            "The property '#{path}' must be <= #{max}"
+          elsif type == 'additionalProperties'
+            "The property '#{path}' is not defined in the schema and the schema does not allow additional properties"
+          else
+            # Fallback: use json_schemer's built-in error message
+            error['error'] || "The property '#{path}' failed '#{type}' validation"
+          end
+        end
+      end
+
+      # Handle validation errors
+      def handle_errors(errors, template_name, template_path, elapsed_ms)
+        error_message = build_error_message(errors, template_name, template_path, elapsed_ms)
+
+        if @fail_on_error
+          # Development: Fail loudly
+          raise ValidationError, error_message
+        else
+          # Production: Log warning
+          warn error_message
+        end
+      end
+
+      # Build detailed error message
+      def build_error_message(errors, template_name, template_path, elapsed_ms)
+        msg = ["Schema validation failed for template: #{template_name}"]
+        msg << "Template path: #{template_path}" if template_path
+        msg << "Validation time: #{elapsed_ms}ms"
+        msg << ""
+
+        errors.each do |error|
+          msg << "Window variable: #{error[:window]}"
+          msg << "Errors:"
+          error[:errors].each do |err|
+            msg << "  - #{err}"
+          end
+          msg << ""
+        end
+
+        msg << "This means your backend is sending data that doesn't match the contract"
+        msg << "defined in the <schema> section of #{template_name}.rue"
+        msg << ""
+        msg << "To fix:"
+        msg << "1. Check the schema definition in #{template_name}.rue"
+        msg << "2. Verify the data passed to render('#{template_name}', ...)"
+        msg << "3. Ensure types match (string vs number, required fields, etc.)"
+
+        msg.join("\n")
+      end
+    end
+  end
+end

data/lib/rhales/middleware.rb

@@ -0,0 +1,6 @@
+# lib/rhales/middleware.rb
+#
+# frozen_string_literal: true
+
+require_relative 'middleware/json_responder'
+require_relative 'middleware/schema_validator'

data/lib/rhales/parsers/handlebars_parser.rb

@@ -1,4 +1,6 @@
 # lib/rhales/parsers/handlebars_parser.rb
+#
+# frozen_string_literal: true
 
 module Rhales
   # Hand-rolled recursive descent parser for Handlebars template syntax

data/lib/rhales/parsers/rue_format_parser.rb

@@ -1,4 +1,6 @@
 # lib/rhales/parsers/rue_format_parser.rb
+#
+# frozen_string_literal: true
 
 require 'strscan'
 require_relative 'handlebars_parser'
@@ -9,7 +11,7 @@ module Rhales
   # This parser implements .rue file parsing rules in Ruby code and produces
   # an Abstract Syntax Tree (AST) for .rue file processing. It handles:
   #
-  # - Section-based parsing: <data>, <template>, <logic>
+  # - Section-based parsing: <schema>, <template>, <logic>
   # - Attribute extraction from section tags
   # - Delegation to HandlebarsParser for template content
   # - Validation of required sections
@@ -21,7 +23,7 @@ module Rhales
   # File format structure:
   # rue_file := section+
   # section := '<' tag_name attributes? '>' content '</' tag_name '>'
-  # tag_name := 'data' | 'template' | 'logic'
+  # tag_name := 'schema' | 'template' | 'logic'
   # attributes := attribute+
   # attribute := key '=' quoted_value
   # content := (text | handlebars_expression)*
@@ -29,9 +31,9 @@ module Rhales
   class RueFormatParser
     # At least one of these sections must be present
     unless defined?(REQUIRES_ONE_OF_SECTIONS)
-      REQUIRES_ONE_OF_SECTIONS = %w[data template].freeze
+      REQUIRES_ONE_OF_SECTIONS = %w[schema template].freeze
 
-      KNOWN_SECTIONS = %w[data template logic].freeze
+      KNOWN_SECTIONS = %w[schema template logic].freeze
       ALL_SECTIONS = KNOWN_SECTIONS.freeze
 
       # Regular expression to match HTML/XML comments outside of sections
@@ -204,7 +206,7 @@ module Rhales
           handlebars_parser.parse!
           handlebars_parser.ast.children
         else
-          # For data and logic sections, keep as simple text
+          # For schema and logic sections, keep as simple text
           raw_content.empty? ? [] : [Node.new(:text, current_location, value: raw_content)]
         end
       else
@@ -380,10 +382,10 @@ module Rhales
         when scanner.scan(/<!--.*?-->/m)
           # Comment token - non-greedy match for complete comments
           { type: :comment, content: scanner.matched }
-        when scanner.scan(/<(data|template|logic)(\s[^>]*)?>/m)
+        when scanner.scan(/<(schema|template|logic)(\s[^>]*)?>/m)
           # Section start token - matches opening tags with optional attributes
           { type: :section_start, content: scanner.matched }
-        when scanner.scan(%r{</(data|template|logic)>}m)
+        when scanner.scan(%r{</(schema|template|logic)>}m)
           # Section end token - matches closing tags
           { type: :section_end, content: scanner.matched }
         when scanner.scan(/[^<]+/)

data/lib/rhales/parsers.rb

@@ -0,0 +1,9 @@
+# lib/rhales/parsers.rb
+#
+# frozen_string_literal: true
+
+# Dependencies
+require_relative 'errors'
+
+require_relative 'parsers/handlebars_parser'
+require_relative 'parsers/rue_format_parser'

data/lib/rhales/{csp.rb → security/csp.rb}

@@ -1,4 +1,6 @@
 # lib/rhales/csp.rb
+#
+# frozen_string_literal: true
 
 module Rhales
   # Content Security Policy (CSP) header generation and management
@@ -11,6 +13,8 @@ module Rhales
   #   header = csp.build_header
   #   # => "default-src 'self'; script-src 'self' 'nonce-abc123'; ..."
   class CSP
+    include Rhales::Utils::LoggingHelpers
+
     attr_reader :config, :nonce
 
     def initialize(config, nonce: nil)
@@ -23,6 +27,7 @@ module Rhales
       return nil unless @config.csp_enabled
 
       policy_directives = []
+      nonce_used = false
 
       @config.csp_policy.each do |directive, sources|
         if sources.empty?
@@ -30,18 +35,37 @@ module Rhales
           policy_directives << directive
         else
           # Process sources and interpolate nonce if present
-          processed_sources = sources.map { |source| interpolate_nonce(source) }
+          processed_sources = sources.map do |source|
+            interpolated = interpolate_nonce(source)
+            nonce_used = true if interpolated != source
+            interpolated
+          end
           directive_string = "#{directive} #{processed_sources.join(' ')}"
           policy_directives << directive_string
         end
       end
 
-      policy_directives.join('; ')
+      header = policy_directives.join('; ')
+
+      # Log CSP header generation for security audit
+      log_with_metadata(Rhales.logger, :debug, "CSP header generated",
+        nonce_used: nonce_used,
+        nonce: @nonce,
+        directive_count: policy_directives.size,
+        header_length: header.length
+      )
+
+      header
     end
 
     # Generate a new nonce value
     def self.generate_nonce
-      SecureRandom.hex(16)
+      nonce = SecureRandom.hex(16)
+
+      # Log nonce generation for security audit trail
+      Rhales.logger.debug("CSP nonce generated: nonce=#{nonce} length=#{nonce.length} entropy_bits=#{nonce.length * 4}")
+
+      nonce
     end
 
     # Validate CSP policy configuration

data/lib/rhales/utils/json_serializer.rb

@@ -0,0 +1,114 @@
+# lib/rhales/utils/json_serializer.rb
+#
+# frozen_string_literal: true
+
+module Rhales
+  # Centralized JSON serialization with optional Oj support
+  #
+  # This module provides a unified interface for JSON operations with automatic
+  # Oj optimization when available. Oj is 10-20x faster than stdlib JSON for
+  # parsing and 5-10x faster for generation.
+  #
+  # The serializer backend is determined once at load time for optimal performance.
+  # If you want to use Oj, require it before requiring Rhales:
+  #
+  # @example Ensuring Oj is used
+  #   require 'oj'
+  #   require 'rhales'
+  #
+  # @example Basic usage
+  #   Rhales::JSONSerializer.dump({ user: 'Alice' })
+  #   # => "{\"user\":\"Alice\"}"
+  #
+  #   Rhales::JSONSerializer.parse('{"user":"Alice"}')
+  #   # => {"user"=>"Alice"}
+  #
+  # @example Pretty printing
+  #   Rhales::JSONSerializer.pretty_dump({ user: 'Alice', count: 42 })
+  #   # => "{\n  \"user\": \"Alice\",\n  \"count\": 42\n}"
+  #
+  # @example Check backend
+  #   Rhales::JSONSerializer.backend
+  #   # => :oj (if available) or :json (stdlib)
+  #
+  module JSONSerializer
+    class << self
+      # Serialize Ruby object to JSON string
+      #
+      # Uses the serializer backend determined at load time (Oj or stdlib JSON).
+      #
+      # @param obj [Object] Ruby object to serialize
+      # @return [String] JSON string (compact format)
+      # @raise [TypeError] if object contains non-serializable types
+      def dump(obj)
+        @json_dumper.call(obj)
+      end
+
+      # Serialize Ruby object to pretty-printed JSON string
+      #
+      # Uses the serializer backend determined at load time (Oj or stdlib JSON).
+      # Output is formatted with indentation for readability.
+      #
+      # @param obj [Object] Ruby object to serialize
+      # @return [String] Pretty-printed JSON string with 2-space indentation
+      # @raise [TypeError] if object contains non-serializable types
+      def pretty_dump(obj)
+        @json_pretty_dumper.call(obj)
+      end
+
+      # Parse JSON string to Ruby object
+      #
+      # Uses the parser backend determined at load time (Oj or stdlib JSON).
+      # Always returns hashes with string keys (not symbols) for consistency.
+      #
+      # @param json_string [String] JSON string to parse
+      # @return [Object] parsed Ruby object (Hash with string keys)
+      # @raise [JSON::ParserError, Oj::ParseError] if JSON is malformed
+      def parse(json_string)
+        @json_loader.call(json_string)
+      end
+
+      # Returns the active JSON backend
+      #
+      # @return [Symbol] :oj or :json
+      def backend
+        @backend
+      end
+
+      # Reset backend detection (useful for testing)
+      #
+      # @api private
+      def reset!
+        detect_backend!
+      end
+
+      private
+
+      # Detect and configure JSON backend at load time
+      def detect_backend!
+        oj_available = begin
+          require 'oj'
+          true
+        rescue LoadError
+          false
+        end
+
+        if oj_available
+          @backend = :oj
+          @json_dumper = ->(obj) { Oj.dump(obj, mode: :strict) }
+          @json_pretty_dumper = ->(obj) { Oj.dump(obj, mode: :strict, indent: 2) }
+          @json_loader = ->(json_string) { Oj.load(json_string, mode: :strict, symbol_keys: false) }
+        else
+          require 'json'
+          @backend = :json
+          @json_dumper = ->(obj) { JSON.generate(obj) }
+          @json_pretty_dumper = ->(obj) { JSON.pretty_generate(obj) }
+          @json_loader = ->(json_string) { JSON.parse(json_string) }
+        end
+      end
+    end
+
+    # Initialize backend on load
+    detect_backend!
+  end
+end

data/lib/rhales/utils/logging_helpers.rb

@@ -0,0 +1,75 @@
+# lib/rhales/utils/logging_helpers.rb
+#
+# frozen_string_literal: true
+
+module Rhales
+  module Utils
+    # Helper methods for consistent logging and timing instrumentation across Rhales components
+    module LoggingHelpers
+      include Rhales::Utils
+
+      # Log with timing for an operation
+      #
+      # @param logger [Logger] The logger instance to use
+      # @param level [Symbol] The log level (:debug, :info, :warn, :error)
+      # @param message [String] The log message
+      # @param metadata [Hash] Additional metadata to include in the log
+      # @yield The block to execute and time
+      # @return The result of the block
+      #
+      # Logs the operation with timing information in microseconds.
+      def log_timed_operation(logger, level, message, **metadata)
+        start_time = now_in_μs
+        result = yield
+        duration = now_in_μs - start_time
+
+        log_with_metadata(logger, level, message, metadata.merge(duration: duration))
+
+        result
+      rescue StandardError => ex
+        duration = now_in_μs - start_time
+        log_with_metadata(logger, :error, "#{message} failed",
+          metadata.merge(
+            duration: duration,
+            error: ex.message,
+            error_class: ex.class.name,
+          )
+        )
+        raise
+      end
+
+      # Log a message with structured metadata
+      def log_with_metadata(logger, level, message, metadata = {})
+        return logger.public_send(level, message) if metadata.empty?
+
+        metadata_str = metadata.map { |k, v| "#{k}=#{format_value(v)}" }.join(' ')
+        logger.public_send(level, "#{message}: #{metadata_str}")
+      end
+
+      private
+
+      # Format individual log values
+      def format_value(value)
+        case value
+        when String
+          value.include?(' ') ? "\"#{value}\"" : value
+        when Symbol, Numeric, true, false, nil
+          value.to_s
+        when Array
+          # For arrays longer than 5 items, show count + first/last items
+          if value.size > 5
+            first_three = value.first(3).join(', ')
+            last_two = value.last(2).join(', ')
+            "[#{value.size} items: #{first_three} ... #{last_two}]"
+          elsif value.empty?
+            '[]'
+          else
+            "[#{value.join(', ')}]"
+          end
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+end