rhales 0.3.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,19 +23,22 @@ 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)*
   # handlebars_expression := '{{' expression '}}'
   class RueFormatParser
     # At least one of these sections must be present
-    REQUIRES_ONE_OF_SECTIONS = %w[data template].freeze
-    KNOWN_SECTIONS = %w[data template logic].freeze
-    ALL_SECTIONS = KNOWN_SECTIONS.freeze
+    unless defined?(REQUIRES_ONE_OF_SECTIONS)
+      REQUIRES_ONE_OF_SECTIONS = %w[schema template].freeze
 
-    # Regular expression to match HTML/XML comments outside of sections
-    COMMENT_REGEX = /<!--.*?-->/m
+      KNOWN_SECTIONS = %w[schema template logic].freeze
+      ALL_SECTIONS = KNOWN_SECTIONS.freeze
+
+      # Regular expression to match HTML/XML comments outside of sections
+      COMMENT_REGEX = /<!--.*?-->/m
+    end
 
     class ParseError < ::Rhales::ParseError
       def initialize(message, line: nil, column: nil, offset: nil)
@@ -145,7 +150,7 @@ module Rhales
     def parse_tag_name
       start_pos = @position
 
-      advance while !at_end? && current_char.match?(/[a-zA-Z]/)
+      advance while !at_end? && current_char.match?(/[a-zA-Z0-9_]/)
 
       if start_pos == @position
         parse_error('Expected tag name')
@@ -178,30 +183,42 @@ module Rhales
       attributes
     end
 
+    # Uses StringScanner to parse "content" in <section>content</section>
     def parse_section_content(tag_name)
-      start_pos     = @position
       content_start = @position
+      closing_tag = "</#{tag_name}>"
 
-      # Extract the raw content between section tags
-      raw_content = ''
-      while !at_end? && !peek_closing_tag?(tag_name)
-        raw_content << current_char
-        advance
-      end
+      # Create scanner from remaining content
+      scanner = StringScanner.new(@content[content_start..])
 
-      # For template sections, use HandlebarsParser to parse the content
-      if tag_name == 'template'
-        handlebars_parser = HandlebarsParser.new(raw_content)
-        handlebars_parser.parse!
-        handlebars_parser.ast.children
-      else
-        # For data and logic sections, keep as simple text
-        return [Node.new(:text, current_location, value: raw_content)] unless raw_content.empty?
+      # Find the closing tag position
+      if scanner.scan_until(/(?=#{Regexp.escape(closing_tag)})/)
+        # Calculate content length (scanner.charpos gives us position right before closing tag)
+        content_length = scanner.charpos
+        raw_content = @content[content_start, content_length]
 
-        []
+        # Advance position tracking to end of content
+        advance_to_position(content_start + content_length)
+
+        # Process content based on tag type
+        if tag_name == 'template'
+          handlebars_parser = HandlebarsParser.new(raw_content)
+          handlebars_parser.parse!
+          handlebars_parser.ast.children
+        else
+          # For schema and logic sections, keep as simple text
+          raw_content.empty? ? [] : [Node.new(:text, current_location, value: raw_content)]
+        end
+      else
+        parse_error("Expected '#{closing_tag}' to close section")
       end
     end
 
+    # Add this helper method to advance position tracking to a specific offset
+    def advance_to_position(target_position)
+      advance while @position < target_position && !at_end?
+    end
+
     def parse_quoted_string
       quote_char = current_char
       unless ['"', "'"].include?(quote_char)
@@ -209,7 +226,7 @@ module Rhales
       end
 
       advance # Skip opening quote
-      value = ''
+      value = []
 
       while !at_end? && current_char != quote_char
         value << current_char
@@ -217,7 +234,11 @@ module Rhales
       end
 
       consume(quote_char) || parse_error('Unterminated quoted string')
-      value
+
+      # NOTE: Character-by-character parsing is acceptable here since attribute values
+      # in section tags (e.g., <tag attribute="value">) are typically short strings.
+      # Using StringScanner would be overkill for this use case.
+      value.join
     end
 
     def parse_identifier
@@ -350,8 +371,6 @@ module Rhales
       result_parts.join
     end
 
-    private
-
     # Tokenize content into structured tokens for pattern matching
     # Uses StringScanner for better performance and cleaner code
     def tokenize_content(content)
@@ -359,23 +378,23 @@ module Rhales
       tokens = []
 
       until scanner.eos?
-        case
+        tokens << case
         when scanner.scan(/<!--.*?-->/m)
           # Comment token - non-greedy match for complete comments
-          tokens << { type: :comment, content: scanner.matched }
-        when scanner.scan(/<(data|template|logic)(\s[^>]*)?>/m)
+          { type: :comment, content: scanner.matched }
+        when scanner.scan(/<(schema|template|logic)(\s[^>]*)?>/m)
           # Section start token - matches opening tags with optional attributes
-          tokens << { type: :section_start, content: scanner.matched }
-        when scanner.scan(/<\/(data|template|logic)>/m)
+          { type: :section_start, content: scanner.matched }
+        when scanner.scan(%r{</(schema|template|logic)>}m)
           # Section end token - matches closing tags
-          tokens << { type: :section_end, content: scanner.matched }
+          { type: :section_end, content: scanner.matched }
         when scanner.scan(/[^<]+/)
           # Text token - consolidates runs of non-< characters for efficiency
-          tokens << { type: :text, content: scanner.matched }
+          { type: :text, content: scanner.matched }
         else
           # Fallback for single characters (< that don't match patterns)
           # This maintains compatibility with the original character-by-character behavior
-          tokens << { type: :text, content: scanner.getch }
+          { type: :text, content: scanner.getch }
         end
       end
 

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